- crates/terminal: portable-pty sessions (ConPTY on Windows) with reader, writer and waiter threads, UTF-8 chunking, a 1 MiB output buffer with backpressure, a non-blocking input queue, resize, kill and exit codes; default shell pwsh -> powershell -> cmd on Windows, $SHELL or /bin/sh. - Engine: terminal.create/input/resize/close, terminalOutput (capped per terminal and per pump, round-robin) and terminalExited through the pump; terminals close with the project and on app.quit. - UI: Terminal tab in the bottom panel (tabs next to Find), xterm.js with the fit addon, sub-tabs, copy/paste, a focus rule that leaves plain Ctrl keys to the shell, terminal.open (Mod+Shift+T), --lt-terminal-* ANSI tokens in both themes (text colours AA) and a 4.5:1 minimum contrast. - Tests: real-shell crate tests (UTF-8, backpressure), engine and TCP control tests, Vitest with a mocked xterm; live check on port 7936; docs and parity rows. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
68 lines
2.8 KiB
Rust
68 lines
2.8 KiB
Rust
//! Integrated terminal sessions for Lutra (layer L3).
|
|
//!
|
|
//! Spawns shells in pseudo-terminals (`portable-pty`: ConPTY on Windows, a
|
|
//! Unix pty elsewhere) and hands their output to the engine, which streams
|
|
//! it to the frontend, where xterm.js renders it.
|
|
//!
|
|
//! A [`Session`] owns three threads, so that no call on it blocks its
|
|
//! caller (the engine holds its lock while it calls in):
|
|
//!
|
|
//! - the **reader** reads the pty, decodes UTF-8 with [`Utf8Chunker`]
|
|
//! (a multibyte character split across two reads is joined, invalid
|
|
//! bytes become U+FFFD) and appends the text to a bounded output buffer;
|
|
//! - the **writer** writes queued input to the pty;
|
|
//! - the **waiter** waits for the shell to exit, records the exit code and
|
|
//! closes the pty, which ends the reader (ConPTY only reports end of
|
|
//! output once the pseudo console is closed).
|
|
//!
|
|
//! **Output buffer and drop policy:** each session buffers at most
|
|
//! [`OUTPUT_CAP`] bytes of decoded text. When the buffer is full the reader
|
|
//! stops reading, so the shell blocks on its next write (backpressure, as in
|
|
//! a real terminal): output is never dropped while the session runs. Output
|
|
//! still buffered when the session is closed or killed is dropped.
|
|
//! [`Session::take_output`] drains the buffer in pieces of a size the caller
|
|
//! chooses, cut on character boundaries.
|
|
//!
|
|
//! **Input:** [`Session::write`] queues input for the writer thread; at most
|
|
//! [`INPUT_QUEUE_CHUNKS`] pieces of up to [`INPUT_CHUNK`] bytes wait. A full
|
|
//! queue refuses more input ([`TerminalError::InputFull`]) instead of
|
|
//! blocking.
|
|
//!
|
|
//! **Exit:** [`Session::exit`] reports the exit code once the shell exited
|
|
//! and its output was read to the end (or [`EXIT_GRACE`] passed, for a
|
|
//! background process that keeps the pty open) and drained.
|
|
|
|
mod session;
|
|
mod shell;
|
|
mod utf8;
|
|
|
|
pub use session::{
|
|
EXIT_GRACE, Exit, INPUT_CHUNK, INPUT_QUEUE_CHUNKS, MAX_SIZE, OUTPUT_CAP, Session, SpawnOptions,
|
|
};
|
|
pub use shell::{Shell, default_shell, find_in_path};
|
|
pub use utf8::Utf8Chunker;
|
|
|
|
/// Errors of terminal sessions.
|
|
#[derive(Debug, thiserror::Error, PartialEq, Eq)]
|
|
pub enum TerminalError {
|
|
/// The pseudo terminal could not be created or the shell not started.
|
|
#[error("cannot start the terminal: {0}")]
|
|
Spawn(String),
|
|
/// Resizing the pseudo terminal failed.
|
|
#[error("cannot resize the terminal: {0}")]
|
|
Resize(String),
|
|
/// A size outside `1..=MAX_SIZE` columns or rows.
|
|
#[error("invalid terminal size {cols}x{rows}")]
|
|
InvalidSize {
|
|
/// Requested columns.
|
|
cols: u16,
|
|
/// Requested rows.
|
|
rows: u16,
|
|
},
|
|
/// The input queue is full; the shell is not reading its input.
|
|
#[error("the terminal is not reading its input")]
|
|
InputFull,
|
|
/// The session has ended; it takes no more input or resizes.
|
|
#[error("the terminal has exited")]
|
|
Exited,
|
|
}
|