M3.6: integrated terminal with PTY sessions and xterm.js sub-tabs

- 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>
This commit is contained in:
danny 2026-10-18 11:25:30 +02:00
parent 5fa7f0c8b3
commit a8daf269fb
45 changed files with 3935 additions and 49 deletions

View file

@ -12,6 +12,12 @@ publish.workspace = true
layer = 3
[dependencies]
portable-pty = "0.9.0"
thiserror = "2.0.21"
[lints]
workspace = true
[dev-dependencies]
proptest.workspace = true
tempfile.workspace = true

View file

@ -1,4 +1,68 @@
//! Integrated terminal sessions for Lutra (layer L3).
//!
//! Spawns shells in pseudo-terminals and streams their output to the frontend,
//! where xterm.js renders it.
//! 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,
}

View file

@ -0,0 +1,410 @@
//! One shell in a pseudo terminal; see the crate documentation for the
//! threads, the output buffer and the drop policy.
use std::collections::VecDeque;
use std::ffi::OsString;
use std::io::{ErrorKind, Read, Write};
use std::path::PathBuf;
use std::sync::mpsc::{Receiver, SyncSender, TrySendError, sync_channel};
use std::sync::{Arc, Condvar, Mutex, MutexGuard, PoisonError};
use std::thread;
use std::time::{Duration, Instant};
use portable_pty::{ChildKiller, CommandBuilder, MasterPty, PtySize, native_pty_system};
use crate::{Shell, TerminalError, Utf8Chunker};
/// Most bytes of decoded output a session buffers before its reader stops
/// reading (backpressure).
pub const OUTPUT_CAP: usize = 1 << 20;
/// Largest piece of input queued at once; longer input is split.
pub const INPUT_CHUNK: usize = 64 * 1024;
/// Most pieces of input waiting for the writer thread.
pub const INPUT_QUEUE_CHUNKS: usize = 64;
/// Largest number of columns or rows.
pub const MAX_SIZE: u16 = 1000;
/// How long after the shell exited its output may stay open (a background
/// process holding the pty) before the exit is reported anyway.
pub const EXIT_GRACE: Duration = Duration::from_millis(500);
/// Size of one read from the pty.
const READ_BUF: usize = 16 * 1024;
/// How long a reader blocked by a full buffer sleeps before it checks
/// whether the session was closed.
const BACKPRESSURE_POLL: Duration = Duration::from_millis(100);
/// What to start.
#[derive(Debug, Clone)]
pub struct SpawnOptions {
/// The shell and its arguments.
pub shell: Shell,
/// Working directory of the shell.
pub cwd: PathBuf,
/// Columns, `1..=MAX_SIZE`.
pub cols: u16,
/// Rows, `1..=MAX_SIZE`.
pub rows: u16,
/// Extra environment variables, set after `TERM=xterm-256color`,
/// `COLORTERM=truecolor` and `TERM_PROGRAM=Lutra`.
pub env: Vec<(OsString, OsString)>,
}
/// How a session ended.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Exit {
/// The shell's exit code; `None` if it could not be read.
pub code: Option<i64>,
}
/// State the threads share with the session, behind [`Shared::output`].
#[derive(Debug, Default)]
struct Output {
/// Decoded output not taken yet, oldest first.
text: VecDeque<String>,
/// Total bytes in `text`.
bytes: usize,
/// The reader reached the end of the output.
eof: bool,
/// The session was closed; the reader stops and buffered output is
/// dropped.
closed: bool,
/// The shell exited: its code and when the waiter saw it.
exited: Option<(Option<i64>, Instant)>,
}
/// The output buffer and the condition the reader waits on while it is
/// full.
#[derive(Debug, Default)]
struct Shared {
/// The buffer.
output: Mutex<Output>,
/// Signalled when output was taken or the session closed.
room: Condvar,
}
impl Shared {
/// Locks the buffer, recovering it if a thread panicked while holding
/// it (the buffer stays consistent: every change is a single push or
/// pop).
fn lock(&self) -> MutexGuard<'_, Output> {
self.output.lock().unwrap_or_else(PoisonError::into_inner)
}
/// Appends decoded output, waiting while the buffer is full.
///
/// # Returns
/// `false` once the session is closed; the reader stops then.
fn append(&self, text: String) -> bool {
let mut out = self.lock();
while out.bytes >= OUTPUT_CAP && !out.closed {
out = self
.room
.wait_timeout(out, BACKPRESSURE_POLL)
.map(|(guard, _)| guard)
.unwrap_or_else(|e| e.into_inner().0);
}
if out.closed {
return false;
}
if !text.is_empty() {
out.bytes = out.bytes.saturating_add(text.len());
out.text.push_back(text);
}
true
}
}
/// A running shell in a pseudo terminal. Dropping it kills the shell.
pub struct Session {
/// Output buffer shared with the threads.
shared: Arc<Shared>,
/// Input queue of the writer thread; `None` after [`Session::kill`].
input: Option<SyncSender<Vec<u8>>>,
/// The pty, for resizing; the waiter takes and closes it after the shell
/// exited.
master: Arc<Mutex<Option<Box<dyn MasterPty + Send>>>>,
/// Kills the shell.
killer: Box<dyn ChildKiller + Send + Sync>,
/// Process id of the shell, if the platform reports one.
pid: Option<u32>,
}
impl std::fmt::Debug for Session {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Session")
.field("pid", &self.pid)
.field("buffered", &self.buffered_bytes())
.finish_non_exhaustive()
}
}
/// Checks a size and turns it into a [`PtySize`].
fn pty_size(cols: u16, rows: u16) -> Result<PtySize, TerminalError> {
if !(1..=MAX_SIZE).contains(&cols) || !(1..=MAX_SIZE).contains(&rows) {
return Err(TerminalError::InvalidSize { cols, rows });
}
Ok(PtySize {
rows,
cols,
pixel_width: 0,
pixel_height: 0,
})
}
/// A spawn error from any displayable cause.
fn spawn_error(e: impl std::fmt::Display) -> TerminalError {
TerminalError::Spawn(e.to_string())
}
impl Session {
/// Starts a shell in a new pseudo terminal.
///
/// # Errors
/// [`TerminalError::InvalidSize`] for a size outside `1..=MAX_SIZE`,
/// [`TerminalError::Spawn`] if the pty cannot be created, the program
/// cannot be started (missing, not executable, bad working directory)
/// or a thread cannot be spawned.
pub fn spawn(options: SpawnOptions) -> Result<Self, TerminalError> {
let size = pty_size(options.cols, options.rows)?;
if !options.cwd.is_dir() {
return Err(TerminalError::Spawn(format!(
"{} is not a directory",
options.cwd.display()
)));
}
let pair = native_pty_system().openpty(size).map_err(spawn_error)?;
let mut cmd = CommandBuilder::new(&options.shell.program);
cmd.args(&options.shell.args);
cmd.cwd(&options.cwd);
cmd.env("TERM", "xterm-256color");
cmd.env("COLORTERM", "truecolor");
cmd.env("TERM_PROGRAM", "Lutra");
for (key, value) in &options.env {
cmd.env(key, value);
}
let mut child = pair.slave.spawn_command(cmd).map_err(spawn_error)?;
drop(pair.slave);
let mut killer = child.clone_killer();
let pid = child.process_id();
let started = (|| {
let reader = pair.master.try_clone_reader().map_err(spawn_error)?;
let writer = pair.master.take_writer().map_err(spawn_error)?;
let shared = Arc::new(Shared::default());
let master = Arc::new(Mutex::new(Some(pair.master)));
let (input, queue) = sync_channel(INPUT_QUEUE_CHUNKS);
let reader_shared = Arc::clone(&shared);
thread::Builder::new()
.name("lutra-terminal-read".into())
.spawn(move || read_loop(reader, &reader_shared))
.map_err(spawn_error)?;
thread::Builder::new()
.name("lutra-terminal-write".into())
.spawn(move || write_loop(writer, &queue))
.map_err(spawn_error)?;
let waiter_shared = Arc::clone(&shared);
let waiter_master = Arc::clone(&master);
thread::Builder::new()
.name("lutra-terminal-wait".into())
.spawn(move || {
let code = child.wait().ok().map(|s| i64::from(s.exit_code()));
waiter_shared.lock().exited = Some((code, Instant::now()));
let pty = waiter_master
.lock()
.unwrap_or_else(PoisonError::into_inner)
.take();
drop(pty);
})
.map_err(spawn_error)?;
Ok::<_, TerminalError>((shared, master, input))
})();
let (shared, master, input) = match started {
Ok(parts) => parts,
Err(e) => {
let _ = killer.kill();
return Err(e);
}
};
Ok(Self {
shared,
input: Some(input),
master,
killer,
pid,
})
}
/// Queues input for the shell (keys, pasted text), as UTF-8 bytes.
/// Never blocks: a writer thread writes it.
///
/// # Errors
/// [`TerminalError::Exited`] after the session ended or was killed,
/// [`TerminalError::InputFull`] when [`INPUT_QUEUE_CHUNKS`] pieces are
/// already waiting (the shell is not reading); pieces queued before the
/// queue filled up stay queued.
pub fn write(&self, data: &[u8]) -> Result<(), TerminalError> {
if self.shared.lock().exited.is_some() {
return Err(TerminalError::Exited);
}
let Some(input) = &self.input else {
return Err(TerminalError::Exited);
};
for piece in data.chunks(INPUT_CHUNK) {
match input.try_send(piece.to_vec()) {
Ok(()) => {}
Err(TrySendError::Full(_)) => return Err(TerminalError::InputFull),
Err(TrySendError::Disconnected(_)) => return Err(TerminalError::Exited),
}
}
Ok(())
}
/// Changes the size of the pseudo terminal.
///
/// # Errors
/// [`TerminalError::InvalidSize`] outside `1..=MAX_SIZE`,
/// [`TerminalError::Exited`] after the shell exited,
/// [`TerminalError::Resize`] if the platform refuses.
pub fn resize(&self, cols: u16, rows: u16) -> Result<(), TerminalError> {
let size = pty_size(cols, rows)?;
let master = self.master.lock().unwrap_or_else(PoisonError::into_inner);
let Some(master) = master.as_ref() else {
return Err(TerminalError::Exited);
};
master
.resize(size)
.map_err(|e| TerminalError::Resize(e.to_string()))
}
/// Takes buffered output, oldest first, and wakes a reader waiting for
/// room.
///
/// # Parameters
/// - `max_bytes`: the most bytes to take. The cut falls on a character
/// boundary, so the result may be shorter; it holds at least one
/// character when output is buffered, even if that character is
/// longer than `max_bytes`.
///
/// # Returns
/// The text, empty when nothing is buffered.
pub fn take_output(&self, max_bytes: usize) -> String {
let mut out = self.shared.lock();
let mut taken = String::new();
while let Some(front) = out.text.front_mut() {
let room = max_bytes.saturating_sub(taken.len());
if front.len() <= room {
taken.push_str(front);
out.text.pop_front();
continue;
}
let mut cut = (0..=room)
.rev()
.find(|&i| front.is_char_boundary(i))
.unwrap_or(0);
if cut == 0 && taken.is_empty() {
cut = front.chars().next().map_or(front.len(), char::len_utf8);
}
if cut > 0 {
let rest = front.split_off(cut);
taken.push_str(front);
*front = rest;
}
break;
}
out.bytes = out.bytes.saturating_sub(taken.len());
drop(out);
if !taken.is_empty() {
self.shared.room.notify_all();
}
taken
}
/// Bytes of output buffered and not taken yet.
pub fn buffered_bytes(&self) -> usize {
self.shared.lock().bytes
}
/// How the session ended, once the shell exited, its output was read to
/// the end (or [`EXIT_GRACE`] passed) and every buffered byte was
/// taken. `None` while it runs or output is left.
pub fn exit(&self) -> Option<Exit> {
let out = self.shared.lock();
let (code, at) = out.exited?;
let drained = out.text.is_empty() && (out.eof || at.elapsed() >= EXIT_GRACE);
drained.then_some(Exit { code })
}
/// Process id of the shell, if the platform reports one.
pub fn pid(&self) -> Option<u32> {
self.pid
}
/// Kills the shell unless it already exited, stops the reader and drops
/// buffered output. The pty closes once the waiter sees the exit.
/// Killing is best effort: an error means the process is already gone,
/// so it is ignored.
pub fn kill(&mut self) {
let exited = {
let mut out = self.shared.lock();
out.closed = true;
out.text.clear();
out.bytes = 0;
out.exited.is_some()
};
self.shared.room.notify_all();
self.input = None;
if !exited {
let _ = self.killer.kill();
}
}
}
impl Drop for Session {
fn drop(&mut self) {
self.kill();
}
}
/// The reader thread: reads the pty until its end or an error, decodes
/// UTF-8 and appends the text, waiting while the buffer is full. A read
/// error ends the output like the end of the stream does (on Unix the pty
/// reports EIO once the shell is gone).
fn read_loop(mut reader: Box<dyn Read + Send>, shared: &Shared) {
let mut buf = vec![0u8; READ_BUF];
let mut utf8 = Utf8Chunker::new();
loop {
match reader.read(&mut buf) {
Ok(0) => break,
Ok(n) => {
let text = utf8.push(buf.get(..n).unwrap_or_default());
if !shared.append(text) {
return;
}
}
Err(e) if e.kind() == ErrorKind::Interrupted => {}
Err(_) => break,
}
}
if shared.append(utf8.finish()) {
shared.lock().eof = true;
}
}
/// The writer thread: writes queued input until the session drops its
/// queue or a write fails (the shell is gone; later input is refused by
/// [`Session::write`] once the exit is seen).
fn write_loop(mut writer: Box<dyn Write + Send>, queue: &Receiver<Vec<u8>>) {
for piece in queue {
if writer
.write_all(&piece)
.and_then(|()| writer.flush())
.is_err()
{
return;
}
}
}

View file

@ -0,0 +1,110 @@
//! Which shell a new terminal runs.
use std::ffi::OsString;
use std::path::{Path, PathBuf};
/// A program with its arguments.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Shell {
/// The program: a path, or a name looked up in `PATH`.
pub program: PathBuf,
/// Its arguments.
pub args: Vec<OsString>,
}
impl Shell {
/// A shell without arguments.
pub fn new(program: impl Into<PathBuf>) -> Self {
Self {
program: program.into(),
args: Vec::new(),
}
}
}
/// The shell for a new terminal when the user chose none.
///
/// - **Windows:** `pwsh.exe` (PowerShell 7) from `PATH`, else
/// `powershell.exe` (Windows PowerShell), else `%COMSPEC%`, else
/// `cmd.exe`. PowerShell starts with `-NoLogo`.
/// - **Unix:** `$SHELL`, else `/bin/sh`.
pub fn default_shell() -> Shell {
if cfg!(windows) {
for name in ["pwsh.exe", "powershell.exe"] {
if let Some(path) = find_in_path(name) {
return Shell {
program: path,
args: vec![OsString::from("-NoLogo")],
};
}
}
let comspec = std::env::var_os("COMSPEC")
.map(PathBuf::from)
.filter(|p| p.is_file());
return Shell::new(comspec.unwrap_or_else(|| PathBuf::from("cmd.exe")));
}
let shell = std::env::var_os("SHELL")
.filter(|s| !s.is_empty())
.map(PathBuf::from);
Shell::new(shell.unwrap_or_else(|| PathBuf::from("/bin/sh")))
}
/// Looks a program up in `PATH`.
///
/// # Parameters
/// - `name`: a file name such as `pwsh.exe`. On Windows a name without an
/// extension is also tried with each extension in `PATHEXT`.
///
/// # Returns
/// The first matching file, or `None`. A name with a directory part is
/// returned as is if it is a file.
pub fn find_in_path(name: &str) -> Option<PathBuf> {
let candidate = Path::new(name);
if candidate.components().count() > 1 {
return candidate.is_file().then(|| candidate.to_path_buf());
}
let path = std::env::var_os("PATH")?;
let extensions: Vec<String> = if cfg!(windows) && candidate.extension().is_none() {
std::env::var("PATHEXT")
.unwrap_or_else(|_| ".COM;.EXE;.BAT;.CMD".into())
.split(';')
.filter(|e| !e.is_empty())
.map(str::to_string)
.collect()
} else {
Vec::new()
};
for dir in std::env::split_paths(&path) {
let plain = dir.join(name);
if plain.is_file() {
return Some(plain);
}
for ext in &extensions {
let with_ext = dir.join(format!("{name}{ext}"));
if with_ext.is_file() {
return Some(with_ext);
}
}
}
None
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn default_shell_exists() {
let shell = default_shell();
let found =
shell.program.is_file() || find_in_path(&shell.program.to_string_lossy()).is_some();
assert!(found, "{shell:?}");
}
#[test]
fn finds_programs_in_path() {
let name = if cfg!(windows) { "cmd" } else { "sh" };
assert!(find_in_path(name).is_some());
assert!(find_in_path("lutra-no-such-program-x").is_none());
}
}

137
crates/terminal/src/utf8.rs Normal file
View file

@ -0,0 +1,137 @@
//! Incremental UTF-8 decoding of pty output.
/// Turns a stream of bytes, read in arbitrary pieces, into text.
///
/// A multibyte character split across two pieces is held back until the
/// rest arrives. Invalid sequences become U+FFFD, one per maximal invalid
/// subpart, as [`String::from_utf8_lossy`] does.
#[derive(Debug, Default)]
pub struct Utf8Chunker {
/// The start of a character whose remaining bytes have not arrived;
/// at most 3 bytes.
pending: Vec<u8>,
}
impl Utf8Chunker {
/// A chunker with nothing pending.
pub fn new() -> Self {
Self::default()
}
/// Decodes the next piece of the stream.
///
/// # Returns
/// Every complete character so far, possibly empty. An incomplete
/// character at the end of `bytes` is kept for the next call.
pub fn push(&mut self, bytes: &[u8]) -> String {
let mut input = std::mem::take(&mut self.pending);
input.extend_from_slice(bytes);
let mut out = String::with_capacity(input.len());
let mut rest: &[u8] = &input;
loop {
match std::str::from_utf8(rest) {
Ok(text) => {
out.push_str(text);
break;
}
Err(e) => {
let (valid, after) = rest.split_at(e.valid_up_to());
out.push_str(&String::from_utf8_lossy(valid));
match e.error_len() {
Some(len) => {
out.push(char::REPLACEMENT_CHARACTER);
rest = after.get(len..).unwrap_or_default();
}
None => {
self.pending = after.to_vec();
break;
}
}
}
}
}
out
}
/// Ends the stream: an incomplete character still pending becomes
/// U+FFFD.
pub fn finish(&mut self) -> String {
let pending = std::mem::take(&mut self.pending);
String::from_utf8_lossy(&pending).into_owned()
}
/// Whether bytes of an incomplete character are held back.
pub fn has_pending(&self) -> bool {
!self.pending.is_empty()
}
}
#[cfg(test)]
mod tests {
use proptest::prelude::*;
use super::Utf8Chunker;
#[test]
fn joins_a_character_split_across_reads() {
let bytes = "aä€😀".as_bytes();
for split in 0..=bytes.len() {
let mut c = Utf8Chunker::new();
let (a, b) = bytes.split_at(split);
let text = c.push(a) + &c.push(b) + &c.finish();
assert_eq!(text, "aä€😀", "split at {split}");
}
}
#[test]
fn one_byte_at_a_time() {
let mut c = Utf8Chunker::new();
let mut text = String::new();
for b in "😀x".as_bytes() {
text.push_str(&c.push(&[*b]));
}
assert_eq!(text, "😀x");
assert!(!c.has_pending());
}
#[test]
fn invalid_bytes_become_replacement_characters() {
let mut c = Utf8Chunker::new();
assert_eq!(c.push(b"a\xffb"), "a\u{fffd}b");
assert_eq!(c.push(b"\xe2\x82"), "");
assert!(c.has_pending());
assert_eq!(c.push(b"x"), "\u{fffd}x");
assert_eq!(c.push(b"\xf0\x9f"), "");
assert_eq!(c.finish(), "\u{fffd}");
}
proptest! {
#[test]
fn matches_lossy_decoding_for_any_split(
bytes in proptest::collection::vec(any::<u8>(), 0..64),
cuts in proptest::collection::vec(0usize..64, 0..6),
) {
let mut cuts: Vec<usize> = cuts.into_iter().map(|c| c.min(bytes.len())).collect();
cuts.sort_unstable();
let mut c = Utf8Chunker::new();
let mut text = String::new();
let mut start = 0;
for cut in cuts.into_iter().chain([bytes.len()]) {
text.push_str(&c.push(&bytes[start..cut]));
start = cut;
}
text.push_str(&c.finish());
prop_assert_eq!(text, String::from_utf8_lossy(&bytes).into_owned());
}
#[test]
fn valid_text_round_trips(text in "\\PC{0,40}", cut in 0usize..200) {
let bytes = text.as_bytes();
let cut = cut.min(bytes.len());
let mut c = Utf8Chunker::new();
let out = c.push(&bytes[..cut]) + &c.push(&bytes[cut..]);
prop_assert_eq!(out, text);
prop_assert!(!c.has_pending());
}
}
}

View file

@ -0,0 +1,263 @@
//! Sessions with a real shell: `cmd.exe` on Windows, `/bin/sh` elsewhere.
//!
//! ConPTY asks for the cursor position (`ESC[6n`) when it starts and waits
//! for the answer; xterm.js gives it in the app, [`drive`] gives it here.
#![allow(
clippy::unwrap_used,
clippy::expect_used,
clippy::panic,
clippy::indexing_slicing
)]
use std::ffi::OsString;
use std::time::{Duration, Instant};
use lutra_terminal::{Exit, OUTPUT_CAP, Session, Shell, SpawnOptions, TerminalError, find_in_path};
/// The platform's plain shell.
fn plain_shell() -> std::path::PathBuf {
if cfg!(windows) {
find_in_path("cmd.exe").unwrap()
} else {
"/bin/sh".into()
}
}
/// Runs a one-line command with `cmd /c` or `sh -c`.
fn command(windows: &[&str], unix: &str) -> Shell {
let args: Vec<OsString> = if cfg!(windows) {
std::iter::once("/c")
.chain(windows.iter().copied())
.map(OsString::from)
.collect()
} else {
vec!["-c".into(), unix.into()]
};
Shell {
program: plain_shell(),
args,
}
}
/// An interactive plain shell.
fn interactive() -> Shell {
let args = if cfg!(windows) {
vec![OsString::from("/q")]
} else {
Vec::new()
};
Shell {
program: plain_shell(),
args,
}
}
fn spawn(shell: Shell, cols: u16) -> Session {
Session::spawn(SpawnOptions {
shell,
cwd: std::env::temp_dir(),
cols,
rows: 24,
env: Vec::new(),
})
.unwrap()
}
/// Takes output until `done` holds for it or the session exited (then the
/// exit is returned), answering cursor-position queries, for at most 30 s.
fn drive(session: &Session, done: impl Fn(&str) -> bool) -> (String, Option<Exit>) {
let deadline = Instant::now() + Duration::from_secs(30);
let mut all = String::new();
let mut answered = 0;
loop {
all.push_str(&session.take_output(64 * 1024));
let asked = all.matches("\x1b[6n").count();
while answered < asked {
let _ = session.write(b"\x1b[1;1R");
answered += 1;
}
if let Some(exit) = session.exit() {
return (all, Some(exit));
}
if done(&all) || Instant::now() > deadline {
return (all, None);
}
std::thread::sleep(Duration::from_millis(10));
}
}
/// Drives the session to its end.
fn finish(session: &Session) -> (String, Exit) {
let (out, exit) = drive(session, |_| false);
(out, exit.expect("the session did not exit in time"))
}
#[test]
fn echo_output_and_exit_code() {
let s = spawn(command(&["echo", "lutra-ok"], "echo lutra-ok"), 80);
assert!(s.pid().is_some());
let (out, exit) = finish(&s);
assert!(out.contains("lutra-ok"), "{out:?}");
assert_eq!(exit.code, Some(0));
assert_eq!(s.write(b"x"), Err(TerminalError::Exited));
}
#[test]
fn reports_the_exit_code() {
let s = spawn(command(&["exit", "3"], "exit 3"), 80);
assert_eq!(finish(&s).1.code, Some(3));
}
#[test]
fn input_reaches_the_shell() {
let s = spawn(interactive(), 120);
s.write(b"echo lutra-in-%OS%-$0\r").unwrap();
let (out, exit) = drive(&s, |out| out.contains("lutra-in-"));
assert!(exit.is_none());
assert!(out.contains("lutra-in-"), "{out:?}");
s.write(b"exit 5\r").unwrap();
assert_eq!(finish(&s).1.code, Some(5));
}
#[test]
fn multibyte_output_survives_read_boundaries() {
let text = "äöü€".repeat(1500);
let s = spawn(
command(&["echo", &text], &format!("printf '%s' '{text}'")),
200,
);
let (out, exit) = finish(&s);
assert_eq!(exit.code, Some(0));
assert!(!out.contains('\u{fffd}'), "replacement character in output");
assert!(out.matches('€').count() >= 1500, "characters were lost");
}
/// Padding of each line in the backpressure test, so that the output is
/// well over twice [`OUTPUT_CAP`] even if ConPTY drops a few bytes.
const PAD: &str =
"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
/// The shell prints a file of about 3 MB with `type` / `cat`, which is
/// fast, so the test depends on the buffer and not on how quickly a shell
/// loop runs on a busy machine.
#[test]
fn a_full_buffer_stops_the_shell_without_dropping_output() {
let lines = 30_000;
let dir = tempfile::tempdir().unwrap();
let file = dir.path().join("lines.txt");
let text: String = (1..=lines)
.map(|i| {
format!(
"line-{i}-{PAD}
"
)
})
.collect();
assert!(
text.len() > 2 * OUTPUT_CAP,
"the output must overfill the buffer by far"
);
std::fs::write(&file, text).unwrap();
let path = file.to_string_lossy().into_owned();
let s = spawn(command(&["type", &path], &format!("cat '{path}'")), 200);
let (mut out, exit) = drive(&s, |out| out.contains("line-1-"));
assert!(exit.is_none(), "the shell ended early: {out:?}");
let deadline = Instant::now() + Duration::from_secs(60);
while s.buffered_bytes() < OUTPUT_CAP {
assert!(Instant::now() < deadline, "the buffer never filled");
std::thread::sleep(Duration::from_millis(20));
}
std::thread::sleep(Duration::from_millis(500));
let buffered = s.buffered_bytes();
assert!(
buffered <= OUTPUT_CAP + 64 * 1024,
"buffered {buffered} bytes"
);
assert!(
s.exit().is_none(),
"the shell went on while the buffer was full"
);
let first = s.take_output(10);
assert!(first.len() <= 10 && !first.is_empty());
out.push_str(&first);
let deadline = Instant::now() + Duration::from_secs(120);
let exit = loop {
out.push_str(&s.take_output(256 * 1024));
if let Some(exit) = s.exit() {
break exit;
}
assert!(Instant::now() < deadline, "the shell did not finish");
std::thread::sleep(Duration::from_millis(5));
};
assert_eq!(exit.code, Some(0));
assert!(
out.contains(&format!("line-{lines}-")),
"the last line is missing"
);
let seen = (1..=lines)
.step_by(997)
.filter(|i| out.contains(&format!("line-{i}-")))
.count();
assert_eq!(seen, (1..=lines).step_by(997).count(), "lines were dropped");
}
#[test]
fn resizes_and_rejects_bad_sizes() {
let s = spawn(interactive(), 80);
s.resize(120, 40).unwrap();
assert!(matches!(
s.resize(0, 10),
Err(TerminalError::InvalidSize { .. })
));
assert!(matches!(
s.resize(80, 1001),
Err(TerminalError::InvalidSize { .. })
));
let _ = drive(&s, |out| !out.is_empty());
s.write(b"exit\r").unwrap();
finish(&s);
assert_eq!(s.resize(80, 24), Err(TerminalError::Exited));
}
#[test]
fn kill_ends_the_session() {
let mut s = spawn(interactive(), 80);
let _ = drive(&s, |out| !out.is_empty());
s.kill();
assert_eq!(s.write(b"x"), Err(TerminalError::Exited));
let deadline = Instant::now() + Duration::from_secs(10);
while s.exit().is_none() {
assert!(Instant::now() < deadline, "no exit after kill");
std::thread::sleep(Duration::from_millis(20));
}
assert_eq!(s.buffered_bytes(), 0);
}
#[test]
fn spawn_errors() {
let options = |shell: Shell, cwd: std::path::PathBuf, cols| SpawnOptions {
shell,
cwd,
cols,
rows: 24,
env: Vec::new(),
};
let tmp = std::env::temp_dir();
assert!(matches!(
Session::spawn(options(interactive(), tmp.join("lutra-no-such-dir"), 80)),
Err(TerminalError::Spawn(_))
));
assert!(matches!(
Session::spawn(options(
Shell::new("lutra-no-such-shell-x"),
tmp.clone(),
80
)),
Err(TerminalError::Spawn(_))
));
assert!(matches!(
Session::spawn(options(interactive(), tmp, 0)),
Err(TerminalError::InvalidSize { cols: 0, rows: 24 })
));
}