//! 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, }