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:
parent
5fa7f0c8b3
commit
a8daf269fb
45 changed files with 3935 additions and 49 deletions
176
crates/control/tests/terminal.rs
Normal file
176
crates/control/tests/terminal.rs
Normal file
|
|
@ -0,0 +1,176 @@
|
|||
//! The integrated terminal over a real TCP control connection:
|
||||
//! `terminal.create` answers at once, `terminalOutput` and `terminalExited`
|
||||
//! arrive as event lines from the pump, `terminal.input` reaches the shell.
|
||||
//!
|
||||
//! ConPTY asks for the cursor position (`ESC[6n`) when it starts and waits
|
||||
//! for the answer; the client answers like xterm.js does.
|
||||
|
||||
#![allow(
|
||||
clippy::unwrap_used,
|
||||
clippy::expect_used,
|
||||
clippy::indexing_slicing,
|
||||
clippy::panic
|
||||
)]
|
||||
|
||||
use std::io::{BufRead, BufReader, Write};
|
||||
use std::net::TcpStream;
|
||||
use std::sync::Arc;
|
||||
use std::sync::atomic::{AtomicBool, Ordering};
|
||||
use std::time::{Duration, Instant};
|
||||
|
||||
use lutra_testkit::EngineBackend;
|
||||
use serde_json::{Value, json};
|
||||
|
||||
/// A client that answers requests and collects terminal events.
|
||||
struct Client {
|
||||
reader: BufReader<TcpStream>,
|
||||
writer: TcpStream,
|
||||
output: String,
|
||||
exit: Option<Value>,
|
||||
answered: usize,
|
||||
next: u64,
|
||||
}
|
||||
|
||||
impl Client {
|
||||
fn connect(addr: std::net::SocketAddr) -> Self {
|
||||
let stream = TcpStream::connect(addr).unwrap();
|
||||
stream
|
||||
.set_read_timeout(Some(Duration::from_secs(10)))
|
||||
.unwrap();
|
||||
Self {
|
||||
writer: stream.try_clone().unwrap(),
|
||||
reader: BufReader::new(stream),
|
||||
output: String::new(),
|
||||
exit: None,
|
||||
answered: 0,
|
||||
next: 0,
|
||||
}
|
||||
}
|
||||
|
||||
fn line(&mut self) -> Value {
|
||||
let mut line = String::new();
|
||||
self.reader.read_line(&mut line).expect("line within 10 s");
|
||||
serde_json::from_str(&line).unwrap()
|
||||
}
|
||||
|
||||
fn event(&mut self, event: &Value) {
|
||||
match event["kind"].as_str() {
|
||||
Some("terminalOutput") => self.output.push_str(event["data"].as_str().unwrap()),
|
||||
Some("terminalExited") => self.exit = Some(event.clone()),
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
|
||||
fn call(&mut self, method: &str, params: Value) -> Value {
|
||||
self.next += 1;
|
||||
let request = json!({"id": self.next, "method": method, "params": params});
|
||||
self.writer
|
||||
.write_all(format!("{request}\n").as_bytes())
|
||||
.unwrap();
|
||||
loop {
|
||||
let line = self.line();
|
||||
if let Some(event) = line.get("event") {
|
||||
let event = event.clone();
|
||||
self.event(&event);
|
||||
} else {
|
||||
return line;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn execute(&mut self, command: &str, params: Value) -> Value {
|
||||
self.call(
|
||||
"engine.execute",
|
||||
json!({"command": command, "params": params}),
|
||||
)
|
||||
}
|
||||
|
||||
/// Reads events until `done` holds or the terminal exited, answering
|
||||
/// cursor-position queries.
|
||||
fn until(&mut self, id: u64, done: impl Fn(&str) -> bool) {
|
||||
let deadline = Instant::now() + Duration::from_secs(30);
|
||||
while Instant::now() < deadline {
|
||||
while self.answered < self.output.matches("\x1b[6n").count() {
|
||||
let r = self.execute(
|
||||
"terminal.input",
|
||||
json!({"terminalId": id, "data": "\x1b[1;1R"}),
|
||||
);
|
||||
assert!(r.get("error").is_none(), "{r}");
|
||||
self.answered += 1;
|
||||
}
|
||||
if self.exit.is_some() || done(&self.output) {
|
||||
return;
|
||||
}
|
||||
let line = self.line();
|
||||
if let Some(event) = line.get("event") {
|
||||
let event = event.clone();
|
||||
self.event(&event);
|
||||
}
|
||||
}
|
||||
panic!("timed out; output so far: {:?}", self.output);
|
||||
}
|
||||
}
|
||||
|
||||
/// Pumps the backend every 20 ms, like the desktop's pump thread, until
|
||||
/// dropped.
|
||||
struct Pump(Arc<AtomicBool>);
|
||||
|
||||
impl Pump {
|
||||
fn start(backend: Arc<EngineBackend>) -> Self {
|
||||
let stop = Arc::new(AtomicBool::new(false));
|
||||
let flag = stop.clone();
|
||||
std::thread::spawn(move || {
|
||||
while !flag.load(Ordering::Relaxed) {
|
||||
backend.pump();
|
||||
std::thread::sleep(Duration::from_millis(20));
|
||||
}
|
||||
});
|
||||
Self(stop)
|
||||
}
|
||||
}
|
||||
|
||||
impl Drop for Pump {
|
||||
fn drop(&mut self) {
|
||||
self.0.store(true, Ordering::Relaxed);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn create_output_input_exit() {
|
||||
let dir = tempfile::tempdir().unwrap();
|
||||
let backend = Arc::new(EngineBackend::new());
|
||||
let server = lutra_control::start(0, backend.clone()).unwrap();
|
||||
let mut client = Client::connect(server.local_addr());
|
||||
client.call("events.subscribe", json!({}));
|
||||
let r = client.execute("project.open", json!({"path": dir.path()}));
|
||||
assert!(r["result"]["root"].is_string(), "{r}");
|
||||
let _pump = Pump::start(backend.clone());
|
||||
|
||||
let shell = if cfg!(windows) { "cmd.exe" } else { "sh" };
|
||||
let r = client.execute(
|
||||
"terminal.create",
|
||||
json!({"shell": shell, "cols": 100, "rows": 30}),
|
||||
);
|
||||
let id = r["result"]["terminalId"].as_u64().expect("terminalId");
|
||||
let r = client.execute(
|
||||
"terminal.input",
|
||||
json!({"terminalId": id, "data": "echo lutra-tcp\r"}),
|
||||
);
|
||||
assert!(r.get("error").is_none(), "{r}");
|
||||
client.until(id, |out| out.matches("lutra-tcp").count() >= 2);
|
||||
let r = client.execute(
|
||||
"terminal.resize",
|
||||
json!({"terminalId": id, "cols": 70, "rows": 20}),
|
||||
);
|
||||
assert!(r.get("error").is_none(), "{r}");
|
||||
client.execute(
|
||||
"terminal.input",
|
||||
json!({"terminalId": id, "data": "exit 4\r"}),
|
||||
);
|
||||
client.until(id, |_| false);
|
||||
let exit = client.exit.clone().unwrap();
|
||||
assert_eq!(
|
||||
exit,
|
||||
json!({"kind": "terminalExited", "terminalId": id, "code": 4})
|
||||
);
|
||||
}
|
||||
|
|
@ -16,6 +16,7 @@ lutra-index.workspace = true
|
|||
lutra-lsp.workspace = true
|
||||
lutra-search.workspace = true
|
||||
lutra-syntax.workspace = true
|
||||
lutra-terminal.workspace = true
|
||||
lutra-text.workspace = true
|
||||
lutra-vfs.workspace = true
|
||||
serde = { version = "1.0.229", features = ["derive"] }
|
||||
|
|
|
|||
|
|
@ -47,7 +47,8 @@ impl Command for Quit {
|
|||
}
|
||||
}
|
||||
|
||||
fn run(&self, _state: &mut State, _params: Value) -> Result<Outcome, EngineError> {
|
||||
fn run(&self, state: &mut State, _params: Value) -> Result<Outcome, EngineError> {
|
||||
crate::cmd::terminal::close_all(state);
|
||||
Ok(Outcome::effect(Effect::Quit))
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -10,6 +10,7 @@ mod recovery;
|
|||
pub mod search;
|
||||
mod settings;
|
||||
pub mod syntax;
|
||||
pub mod terminal;
|
||||
pub mod theme;
|
||||
pub mod toolchain;
|
||||
pub mod ui;
|
||||
|
|
@ -53,5 +54,9 @@ pub fn register_builtins(registry: &mut Registry) -> Result<(), EngineError> {
|
|||
registry.register(Box::new(toolchain::Status))?;
|
||||
registry.register(Box::new(toolchain::DownloadPhpactor))?;
|
||||
registry.register(Box::new(buffer::List))?;
|
||||
registry.register(Box::new(terminal::Create))?;
|
||||
registry.register(Box::new(terminal::Input))?;
|
||||
registry.register(Box::new(terminal::Resize))?;
|
||||
registry.register(Box::new(terminal::Close))?;
|
||||
Ok(())
|
||||
}
|
||||
|
|
|
|||
437
crates/engine/src/cmd/terminal.rs
Normal file
437
crates/engine/src/cmd/terminal.rs
Normal file
|
|
@ -0,0 +1,437 @@
|
|||
//! The integrated terminal: `terminal.create`, `terminal.input`,
|
||||
//! `terminal.resize` and `terminal.close`, and the events
|
||||
//! `terminalOutput` and `terminalExited`.
|
||||
//!
|
||||
//! Each terminal is a [`lutra_terminal::Session`]: a shell in a pseudo
|
||||
//! terminal whose reading, writing and waiting happen on threads of its own,
|
||||
//! so no command blocks the engine lock on the shell. Output waits in the
|
||||
//! session's bounded buffer (backpressure when full, see the crate) until
|
||||
//! [`crate::Engine::pump_vfs`] calls [`pump`], which emits one
|
||||
//! `terminalOutput` per terminal with at most [`MAX_OUTPUT_PER_TERMINAL`]
|
||||
//! bytes, at most [`MAX_OUTPUT_PER_PUMP`] bytes over all terminals
|
||||
//! (round-robin, so one busy terminal cannot starve the others). With the
|
||||
//! desktop's pump every 100 ms that caps the stream at about 2.5 MB/s; the
|
||||
//! shell waits when it writes faster. `terminalExited` follows the last
|
||||
//! output of a shell that ended.
|
||||
//!
|
||||
//! Terminals belong to the project open when they were created: closing the
|
||||
//! project (or opening another) closes them ([`sync_project`], run after
|
||||
//! every command and every pump), and so does `app.quit` ([`close_all`]).
|
||||
//! A terminal closed by Lutra reports `terminalExited` with `code: null`.
|
||||
|
||||
use std::collections::BTreeMap;
|
||||
use std::ops::Bound;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use lutra_terminal::{Session, Shell, SpawnOptions, TerminalError};
|
||||
use serde::{Deserialize, Serialize};
|
||||
use serde_json::{Value, json};
|
||||
|
||||
use crate::cmd::params::parse;
|
||||
use crate::{Command, CommandSpec, EngineError, Event, Outcome, State};
|
||||
|
||||
/// Most terminals open at once.
|
||||
pub const MAX_TERMINALS: usize = 16;
|
||||
|
||||
/// Most bytes of input one `terminal.input` takes.
|
||||
pub const MAX_INPUT_BYTES: usize = 1 << 20;
|
||||
|
||||
/// Most bytes of output one pump emits for one terminal.
|
||||
pub const MAX_OUTPUT_PER_TERMINAL: usize = 64 * 1024;
|
||||
|
||||
/// Most bytes of output one pump emits over all terminals.
|
||||
pub const MAX_OUTPUT_PER_PUMP: usize = 256 * 1024;
|
||||
|
||||
/// Events of the terminal, appended to [`Event`] untagged: each serialises
|
||||
/// with its own `kind`.
|
||||
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
|
||||
#[serde(
|
||||
tag = "kind",
|
||||
rename_all = "camelCase",
|
||||
rename_all_fields = "camelCase"
|
||||
)]
|
||||
pub enum TerminalEvent {
|
||||
/// Output of a terminal, as UTF-8 text with the shell's escape
|
||||
/// sequences; at most [`MAX_OUTPUT_PER_TERMINAL`] bytes.
|
||||
TerminalOutput {
|
||||
/// The terminal, as `terminal.create` returned it.
|
||||
terminal_id: u64,
|
||||
/// The text; never empty.
|
||||
data: String,
|
||||
},
|
||||
/// A terminal ended: its shell exited or Lutra closed it. No events for
|
||||
/// it follow.
|
||||
TerminalExited {
|
||||
/// The terminal.
|
||||
terminal_id: u64,
|
||||
/// The shell's exit code; `null` when Lutra closed the terminal or
|
||||
/// the code is unknown.
|
||||
code: Option<i64>,
|
||||
},
|
||||
}
|
||||
|
||||
/// The open terminals.
|
||||
#[derive(Debug, Default)]
|
||||
pub struct Terminals {
|
||||
/// The id of the last terminal created; ids are never reused.
|
||||
last_id: u64,
|
||||
/// The terminal the last pump emitted output for first; the next pump
|
||||
/// starts after it.
|
||||
cursor: u64,
|
||||
/// Open terminals by id.
|
||||
sessions: BTreeMap<u64, Running>,
|
||||
}
|
||||
|
||||
impl Terminals {
|
||||
/// Number of open terminals.
|
||||
pub fn len(&self) -> usize {
|
||||
self.sessions.len()
|
||||
}
|
||||
|
||||
/// Whether no terminal is open.
|
||||
pub fn is_empty(&self) -> bool {
|
||||
self.sessions.is_empty()
|
||||
}
|
||||
}
|
||||
|
||||
/// One open terminal.
|
||||
#[derive(Debug)]
|
||||
struct Running {
|
||||
/// The shell.
|
||||
session: Session,
|
||||
/// Root of the project it belongs to.
|
||||
root: PathBuf,
|
||||
}
|
||||
|
||||
/// Root of the open project.
|
||||
fn project_root(state: &State) -> Option<PathBuf> {
|
||||
state
|
||||
.project
|
||||
.as_ref()
|
||||
.map(|w| w.project.root().to_path_buf())
|
||||
}
|
||||
|
||||
/// An engine error for a session error of command `id`.
|
||||
fn session_error(id: &str, e: TerminalError) -> EngineError {
|
||||
match e {
|
||||
TerminalError::InvalidSize { .. } => EngineError::invalid_params(id, e.to_string()),
|
||||
_ => EngineError::Failed(e.to_string()),
|
||||
}
|
||||
}
|
||||
|
||||
/// The open terminal `terminal_id`.
|
||||
fn running<'a>(state: &'a State, id: &str, terminal_id: u64) -> Result<&'a Running, EngineError> {
|
||||
state
|
||||
.terminals
|
||||
.sessions
|
||||
.get(&terminal_id)
|
||||
.ok_or_else(|| EngineError::invalid_params(id, format!("no terminal {terminal_id}")))
|
||||
}
|
||||
|
||||
/// Params of `terminal.create`.
|
||||
#[derive(Deserialize)]
|
||||
#[serde(deny_unknown_fields, rename_all = "camelCase")]
|
||||
struct CreateParams {
|
||||
/// Working directory: project-relative or absolute.
|
||||
cwd: Option<String>,
|
||||
/// Program to run instead of the default shell.
|
||||
shell: Option<String>,
|
||||
/// Columns.
|
||||
cols: u16,
|
||||
/// Rows.
|
||||
rows: u16,
|
||||
}
|
||||
|
||||
/// `terminal.create`: starts a shell in a new terminal.
|
||||
pub struct Create;
|
||||
|
||||
impl Command for Create {
|
||||
fn spec(&self) -> &CommandSpec {
|
||||
&CommandSpec {
|
||||
id: "terminal.create",
|
||||
label: "New Terminal",
|
||||
menu_path: None,
|
||||
default_shortcut: None,
|
||||
params: "{ cwd? (project-relative or absolute directory, default the project root), shell? (program name or path; default pwsh, then powershell, then cmd on Windows, $SHELL or /bin/sh elsewhere), cols, rows (1..=1000) }; returns { terminalId }, then events terminalOutput { terminalId, data } and terminalExited { terminalId, code }; at most 16 terminals",
|
||||
}
|
||||
}
|
||||
|
||||
fn enabled(&self, state: &State) -> bool {
|
||||
state.has_project()
|
||||
}
|
||||
|
||||
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
|
||||
let id = self.spec().id;
|
||||
let p: CreateParams = parse(id, params)?;
|
||||
if state.terminals.sessions.len() >= MAX_TERMINALS {
|
||||
return Err(EngineError::Failed(format!(
|
||||
"at most {MAX_TERMINALS} terminals can be open"
|
||||
)));
|
||||
}
|
||||
let root = project_root(state).ok_or_else(|| EngineError::Disabled(id.to_string()))?;
|
||||
let cwd = match p.cwd.as_deref() {
|
||||
None | Some("") => root.clone(),
|
||||
Some(dir) => root.join(Path::new(dir)),
|
||||
};
|
||||
if !cwd.is_dir() {
|
||||
return Err(EngineError::invalid_params(
|
||||
id,
|
||||
format!("{} is not a directory", cwd.display()),
|
||||
));
|
||||
}
|
||||
let shell = match p.shell.as_deref() {
|
||||
None | Some("") => lutra_terminal::default_shell(),
|
||||
Some(program) => Shell::new(
|
||||
lutra_terminal::find_in_path(program).unwrap_or_else(|| PathBuf::from(program)),
|
||||
),
|
||||
};
|
||||
let session = Session::spawn(SpawnOptions {
|
||||
shell,
|
||||
cwd,
|
||||
cols: p.cols,
|
||||
rows: p.rows,
|
||||
env: Vec::new(),
|
||||
})
|
||||
.map_err(|e| session_error(id, e))?;
|
||||
let terminals = &mut state.terminals;
|
||||
terminals.last_id = terminals.last_id.saturating_add(1);
|
||||
let terminal_id = terminals.last_id;
|
||||
terminals
|
||||
.sessions
|
||||
.insert(terminal_id, Running { session, root });
|
||||
Ok(Outcome::value(json!({ "terminalId": terminal_id })))
|
||||
}
|
||||
}
|
||||
|
||||
/// Params of `terminal.input`.
|
||||
#[derive(Deserialize)]
|
||||
#[serde(deny_unknown_fields, rename_all = "camelCase")]
|
||||
struct InputParams {
|
||||
/// The terminal.
|
||||
terminal_id: u64,
|
||||
/// Keys or pasted text, as xterm.js sends them.
|
||||
data: String,
|
||||
}
|
||||
|
||||
/// `terminal.input`: sends input to a terminal's shell.
|
||||
pub struct Input;
|
||||
|
||||
impl Command for Input {
|
||||
fn spec(&self) -> &CommandSpec {
|
||||
&CommandSpec {
|
||||
id: "terminal.input",
|
||||
label: "Terminal Input",
|
||||
menu_path: None,
|
||||
default_shortcut: None,
|
||||
params: "{ terminalId, data (at most 1 MiB) }; returns null; failed when the shell has exited or is not reading its input",
|
||||
}
|
||||
}
|
||||
|
||||
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
|
||||
let id = self.spec().id;
|
||||
let p: InputParams = parse(id, params)?;
|
||||
if p.data.len() > MAX_INPUT_BYTES {
|
||||
return Err(EngineError::invalid_params(
|
||||
id,
|
||||
format!("at most {MAX_INPUT_BYTES} bytes of input per call"),
|
||||
));
|
||||
}
|
||||
running(state, id, p.terminal_id)?
|
||||
.session
|
||||
.write(p.data.as_bytes())
|
||||
.map_err(|e| session_error(id, e))?;
|
||||
Ok(Outcome::default())
|
||||
}
|
||||
}
|
||||
|
||||
/// Params of `terminal.resize`.
|
||||
#[derive(Deserialize)]
|
||||
#[serde(deny_unknown_fields, rename_all = "camelCase")]
|
||||
struct ResizeParams {
|
||||
/// The terminal.
|
||||
terminal_id: u64,
|
||||
/// Columns.
|
||||
cols: u16,
|
||||
/// Rows.
|
||||
rows: u16,
|
||||
}
|
||||
|
||||
/// `terminal.resize`: changes a terminal's size.
|
||||
pub struct Resize;
|
||||
|
||||
impl Command for Resize {
|
||||
fn spec(&self) -> &CommandSpec {
|
||||
&CommandSpec {
|
||||
id: "terminal.resize",
|
||||
label: "Resize Terminal",
|
||||
menu_path: None,
|
||||
default_shortcut: None,
|
||||
params: "{ terminalId, cols, rows (1..=1000) }; returns null",
|
||||
}
|
||||
}
|
||||
|
||||
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
|
||||
let id = self.spec().id;
|
||||
let p: ResizeParams = parse(id, params)?;
|
||||
running(state, id, p.terminal_id)?
|
||||
.session
|
||||
.resize(p.cols, p.rows)
|
||||
.map_err(|e| session_error(id, e))?;
|
||||
Ok(Outcome::default())
|
||||
}
|
||||
}
|
||||
|
||||
/// Params of `terminal.close`.
|
||||
#[derive(Deserialize)]
|
||||
#[serde(deny_unknown_fields, rename_all = "camelCase")]
|
||||
struct CloseParams {
|
||||
/// The terminal.
|
||||
terminal_id: u64,
|
||||
}
|
||||
|
||||
/// `terminal.close`: kills a terminal's shell.
|
||||
pub struct Close;
|
||||
|
||||
impl Command for Close {
|
||||
fn spec(&self) -> &CommandSpec {
|
||||
&CommandSpec {
|
||||
id: "terminal.close",
|
||||
label: "Close Terminal",
|
||||
menu_path: None,
|
||||
default_shortcut: None,
|
||||
params: "{ terminalId }; returns { closed }: false if the terminal already ended; a closed terminal reports terminalExited { code: null }",
|
||||
}
|
||||
}
|
||||
|
||||
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
|
||||
let p: CloseParams = parse(self.spec().id, params)?;
|
||||
let closed = close(state, p.terminal_id);
|
||||
Ok(Outcome::value(json!({ "closed": closed })))
|
||||
}
|
||||
}
|
||||
|
||||
/// Kills terminal `terminal_id`, drops its buffered output and emits
|
||||
/// `terminalExited {code: null}`.
|
||||
///
|
||||
/// # Returns
|
||||
/// Whether the terminal was open.
|
||||
fn close(state: &mut State, terminal_id: u64) -> bool {
|
||||
let Some(mut running) = state.terminals.sessions.remove(&terminal_id) else {
|
||||
return false;
|
||||
};
|
||||
running.session.kill();
|
||||
state.emit(Event::Terminal(TerminalEvent::TerminalExited {
|
||||
terminal_id,
|
||||
code: None,
|
||||
}));
|
||||
true
|
||||
}
|
||||
|
||||
/// Closes every terminal, for `app.quit`.
|
||||
pub fn close_all(state: &mut State) {
|
||||
let ids: Vec<u64> = state.terminals.sessions.keys().copied().collect();
|
||||
for terminal_id in ids {
|
||||
close(state, terminal_id);
|
||||
}
|
||||
}
|
||||
|
||||
/// Closes the terminals of a project that is no longer open.
|
||||
pub fn sync_project(state: &mut State) {
|
||||
let root = project_root(state);
|
||||
let stale: Vec<u64> = state
|
||||
.terminals
|
||||
.sessions
|
||||
.iter()
|
||||
.filter(|(_, r)| root.as_ref() != Some(&r.root))
|
||||
.map(|(&id, _)| id)
|
||||
.collect();
|
||||
for terminal_id in stale {
|
||||
close(state, terminal_id);
|
||||
}
|
||||
}
|
||||
|
||||
/// Moves buffered output into `terminalOutput` events and reports ended
|
||||
/// shells with `terminalExited`; see the module documentation for the caps.
|
||||
/// Closes the terminals of a project that is no longer open first.
|
||||
pub fn pump(state: &mut State) {
|
||||
sync_project(state);
|
||||
let terminals = &mut state.terminals;
|
||||
let cursor = terminals.cursor;
|
||||
let order: Vec<u64> = terminals
|
||||
.sessions
|
||||
.range((Bound::Excluded(cursor), Bound::Unbounded))
|
||||
.chain(terminals.sessions.range(..=cursor))
|
||||
.map(|(&id, _)| id)
|
||||
.collect();
|
||||
let mut budget = MAX_OUTPUT_PER_PUMP;
|
||||
let mut events = Vec::new();
|
||||
let mut ended = Vec::new();
|
||||
let mut first = None;
|
||||
for terminal_id in order {
|
||||
let Some(running) = terminals.sessions.get(&terminal_id) else {
|
||||
continue;
|
||||
};
|
||||
if budget > 0 {
|
||||
let data = running
|
||||
.session
|
||||
.take_output(budget.min(MAX_OUTPUT_PER_TERMINAL));
|
||||
if !data.is_empty() {
|
||||
budget = budget.saturating_sub(data.len());
|
||||
first.get_or_insert(terminal_id);
|
||||
events.push(TerminalEvent::TerminalOutput { terminal_id, data });
|
||||
}
|
||||
}
|
||||
if let Some(exit) = running.session.exit() {
|
||||
events.push(TerminalEvent::TerminalExited {
|
||||
terminal_id,
|
||||
code: exit.code,
|
||||
});
|
||||
ended.push(terminal_id);
|
||||
}
|
||||
}
|
||||
if let Some(first) = first {
|
||||
terminals.cursor = first;
|
||||
}
|
||||
for terminal_id in ended {
|
||||
terminals.sessions.remove(&terminal_id);
|
||||
}
|
||||
for event in events {
|
||||
state.emit(Event::Terminal(event));
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use serde_json::json;
|
||||
|
||||
use super::TerminalEvent;
|
||||
use crate::Event;
|
||||
|
||||
#[test]
|
||||
fn event_shapes() {
|
||||
let e = Event::Terminal(TerminalEvent::TerminalOutput {
|
||||
terminal_id: 1,
|
||||
data: "hi\r\n".into(),
|
||||
});
|
||||
assert_eq!(
|
||||
serde_json::to_value(e).unwrap(),
|
||||
json!({"kind": "terminalOutput", "terminalId": 1, "data": "hi\r\n"})
|
||||
);
|
||||
let e = Event::Terminal(TerminalEvent::TerminalExited {
|
||||
terminal_id: 1,
|
||||
code: Some(3),
|
||||
});
|
||||
assert_eq!(
|
||||
serde_json::to_value(e).unwrap(),
|
||||
json!({"kind": "terminalExited", "terminalId": 1, "code": 3})
|
||||
);
|
||||
let e = Event::Terminal(TerminalEvent::TerminalExited {
|
||||
terminal_id: 2,
|
||||
code: None,
|
||||
});
|
||||
assert_eq!(
|
||||
serde_json::to_value(e).unwrap(),
|
||||
json!({"kind": "terminalExited", "terminalId": 2, "code": null})
|
||||
);
|
||||
}
|
||||
}
|
||||
|
|
@ -119,6 +119,7 @@ impl Engine {
|
|||
}
|
||||
let outcome = command.run(state, params);
|
||||
crate::workspace::sync_buffer_dirs(state);
|
||||
cmd::terminal::sync_project(state);
|
||||
outcome
|
||||
});
|
||||
state.commands_run = state.commands_run.saturating_add(1);
|
||||
|
|
@ -134,6 +135,7 @@ impl Engine {
|
|||
/// events (see [`cmd::search`]), merges index updates (see
|
||||
/// [`cmd::goto`]), stores finished parses and starts due ones (see
|
||||
/// [`cmd::syntax`]) and returns every queued event.
|
||||
/// Terminal output and exits become events too (see [`cmd::terminal`]).
|
||||
/// Hosts call it regularly, e.g. every 100 ms from a background thread.
|
||||
///
|
||||
/// # Errors
|
||||
|
|
@ -148,6 +150,7 @@ impl Engine {
|
|||
cmd::goto::sync(state);
|
||||
cmd::syntax::pump(state, std::time::Instant::now());
|
||||
cmd::toolchain::pump(state);
|
||||
cmd::terminal::pump(state);
|
||||
Ok(())
|
||||
})?;
|
||||
Ok(state.take_events())
|
||||
|
|
@ -410,6 +413,10 @@ mod tests {
|
|||
"settings.reset",
|
||||
"settings.set",
|
||||
"syntax.outline",
|
||||
"terminal.close",
|
||||
"terminal.create",
|
||||
"terminal.input",
|
||||
"terminal.resize",
|
||||
"test.disabled",
|
||||
"theme.list",
|
||||
"theme.systemPreference",
|
||||
|
|
|
|||
|
|
@ -197,6 +197,9 @@ pub enum Event {
|
|||
/// PHP or Phpactor changed: `{php, phpactor}` as `toolchain.status`
|
||||
/// returns it.
|
||||
ToolchainChanged(crate::cmd::toolchain::ToolchainStatus),
|
||||
/// Terminal events (`terminalOutput`, `terminalExited`), see [`crate::cmd::terminal`].
|
||||
#[serde(untagged)]
|
||||
Terminal(crate::cmd::terminal::TerminalEvent),
|
||||
}
|
||||
|
||||
/// One match of [`Event::SearchResults`]. Positions are 0-based; columns
|
||||
|
|
|
|||
|
|
@ -43,6 +43,8 @@ pub struct State {
|
|||
pub syntax: crate::cmd::syntax::Syntax,
|
||||
/// PHP and Phpactor (`toolchain.status`).
|
||||
pub toolchain: crate::cmd::toolchain::Toolchain,
|
||||
/// Open integrated terminals (`terminal.*`).
|
||||
pub terminals: crate::cmd::terminal::Terminals,
|
||||
/// Number of notifications emitted, for their ids.
|
||||
notifications: u64,
|
||||
/// Events queued for the host, oldest first.
|
||||
|
|
|
|||
|
|
@ -62,6 +62,35 @@ pub const SYNTAX_TOKENS: &[&str] = &[
|
|||
"operator",
|
||||
];
|
||||
|
||||
/// Terminal token names (`--lt-terminal-<name>`) every theme defines: the
|
||||
/// terminal's background, text, cursor and selection, and the 16 ANSI
|
||||
/// colours xterm.js maps escape sequences to. Every ANSI colour that shows
|
||||
/// as text reaches 4.5:1 on `terminal-bg` (`ui/tests/theme/contrast.test.ts`);
|
||||
/// the exceptions are the colour meant to vanish into the background: ANSI
|
||||
/// black in the dark theme, white and bright white in the light one.
|
||||
pub const TERMINAL_TOKENS: &[&str] = &[
|
||||
"bg",
|
||||
"fg",
|
||||
"cursor",
|
||||
"selection-bg",
|
||||
"ansi-black",
|
||||
"ansi-red",
|
||||
"ansi-green",
|
||||
"ansi-yellow",
|
||||
"ansi-blue",
|
||||
"ansi-magenta",
|
||||
"ansi-cyan",
|
||||
"ansi-white",
|
||||
"ansi-bright-black",
|
||||
"ansi-bright-red",
|
||||
"ansi-bright-green",
|
||||
"ansi-bright-yellow",
|
||||
"ansi-bright-blue",
|
||||
"ansi-bright-magenta",
|
||||
"ansi-bright-cyan",
|
||||
"ansi-bright-white",
|
||||
];
|
||||
|
||||
/// The default dark theme.
|
||||
pub const DARK: Theme = Theme {
|
||||
id: "lutra-dark",
|
||||
|
|
@ -97,6 +126,26 @@ pub const DARK: Theme = Theme {
|
|||
("syntax-tag", "#e08b70"),
|
||||
("syntax-attribute", "#cdb87e"),
|
||||
("syntax-operator", "#b8afa6"),
|
||||
("terminal-bg", "#191817"),
|
||||
("terminal-fg", "#e6e1da"),
|
||||
("terminal-cursor", "#d39a5c"),
|
||||
("terminal-selection-bg", "#513f2c"),
|
||||
("terminal-ansi-black", "#2e2b28"),
|
||||
("terminal-ansi-red", "#ef7b6c"),
|
||||
("terminal-ansi-green", "#a9bd7e"),
|
||||
("terminal-ansi-yellow", "#e6c46f"),
|
||||
("terminal-ansi-blue", "#8fa8e0"),
|
||||
("terminal-ansi-magenta", "#c4a0d6"),
|
||||
("terminal-ansi-cyan", "#7fbac6"),
|
||||
("terminal-ansi-white", "#d0c9c1"),
|
||||
("terminal-ansi-bright-black", "#9a928a"),
|
||||
("terminal-ansi-bright-red", "#f59a8d"),
|
||||
("terminal-ansi-bright-green", "#c2d69a"),
|
||||
("terminal-ansi-bright-yellow", "#f2d88e"),
|
||||
("terminal-ansi-bright-blue", "#aebff0"),
|
||||
("terminal-ansi-bright-magenta", "#dbbde8"),
|
||||
("terminal-ansi-bright-cyan", "#a2d3dc"),
|
||||
("terminal-ansi-bright-white", "#f5f1ec"),
|
||||
],
|
||||
};
|
||||
|
||||
|
|
@ -135,6 +184,26 @@ pub const LIGHT: Theme = Theme {
|
|||
("syntax-tag", "#a5432a"),
|
||||
("syntax-attribute", "#695d1a"),
|
||||
("syntax-operator", "#5a5149"),
|
||||
("terminal-bg", "#fbfaf8"),
|
||||
("terminal-fg", "#2a2622"),
|
||||
("terminal-cursor", "#965a22"),
|
||||
("terminal-selection-bg", "#e5d7c9"),
|
||||
("terminal-ansi-black", "#2a2622"),
|
||||
("terminal-ansi-red", "#b23a29"),
|
||||
("terminal-ansi-green", "#4e6a24"),
|
||||
("terminal-ansi-yellow", "#7a5808"),
|
||||
("terminal-ansi-blue", "#2f55a4"),
|
||||
("terminal-ansi-magenta", "#73479a"),
|
||||
("terminal-ansi-cyan", "#24697a"),
|
||||
("terminal-ansi-white", "#ddd6cd"),
|
||||
("terminal-ansi-bright-black", "#6b625a"),
|
||||
("terminal-ansi-bright-red", "#8f2a1c"),
|
||||
("terminal-ansi-bright-green", "#3b5418"),
|
||||
("terminal-ansi-bright-yellow", "#5f4404"),
|
||||
("terminal-ansi-bright-blue", "#233f7f"),
|
||||
("terminal-ansi-bright-magenta", "#5a3480"),
|
||||
("terminal-ansi-bright-cyan", "#1a5260"),
|
||||
("terminal-ansi-bright-white", "#f4f1ec"),
|
||||
],
|
||||
};
|
||||
|
||||
|
|
@ -280,6 +349,20 @@ mod tests {
|
|||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn themes_define_the_terminal_tokens() {
|
||||
for theme in BUILTIN {
|
||||
let tokens = token_map(theme);
|
||||
for name in TERMINAL_TOKENS {
|
||||
assert!(
|
||||
tokens.contains_key(&format!("--lt-terminal-{name}")),
|
||||
"{} lacks terminal-{name}",
|
||||
theme.id
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn resolves_settings() {
|
||||
assert_eq!(resolve("lutra-light", Some(true)), LIGHT);
|
||||
|
|
|
|||
212
crates/engine/tests/terminal.rs
Normal file
212
crates/engine/tests/terminal.rs
Normal file
|
|
@ -0,0 +1,212 @@
|
|||
//! `terminal.*` with a real shell (`cmd.exe` on Windows, `/bin/sh`
|
||||
//! elsewhere): output and exits arrive through the pump; project close and
|
||||
//! `app.quit` close terminals.
|
||||
//!
|
||||
//! ConPTY asks for the cursor position (`ESC[6n`) when it starts and waits
|
||||
//! for the answer, which xterm.js gives in the app and [`Pumped`] gives here.
|
||||
|
||||
#![allow(
|
||||
clippy::unwrap_used,
|
||||
clippy::expect_used,
|
||||
clippy::panic,
|
||||
clippy::indexing_slicing
|
||||
)]
|
||||
|
||||
use std::time::{Duration, Instant};
|
||||
|
||||
use lutra_engine::cmd::terminal::{MAX_OUTPUT_PER_TERMINAL, TerminalEvent};
|
||||
use lutra_engine::{Engine, Event};
|
||||
use serde_json::{Value, json};
|
||||
use tempfile::TempDir;
|
||||
|
||||
fn shell() -> &'static str {
|
||||
if cfg!(windows) { "cmd.exe" } else { "sh" }
|
||||
}
|
||||
|
||||
fn open_project() -> (TempDir, Engine) {
|
||||
let dir = tempfile::tempdir().unwrap();
|
||||
let mut engine = Engine::new().unwrap();
|
||||
engine
|
||||
.execute("project.open", json!({"path": dir.path()}))
|
||||
.unwrap();
|
||||
(dir, engine)
|
||||
}
|
||||
|
||||
fn create(engine: &mut Engine) -> u64 {
|
||||
let out = engine
|
||||
.execute(
|
||||
"terminal.create",
|
||||
json!({"shell": shell(), "cols": 100, "rows": 30}),
|
||||
)
|
||||
.unwrap();
|
||||
out.value["terminalId"].as_u64().unwrap()
|
||||
}
|
||||
|
||||
/// What the pump reported for one terminal.
|
||||
#[derive(Default)]
|
||||
struct Pumped {
|
||||
output: String,
|
||||
exit: Option<Option<i64>>,
|
||||
largest: usize,
|
||||
answered: usize,
|
||||
}
|
||||
|
||||
/// Pumps until `done` holds or the terminal exited, for at most 30 s.
|
||||
fn pump_until(engine: &mut Engine, id: u64, seen: &mut Pumped, done: impl Fn(&str) -> bool) {
|
||||
let deadline = Instant::now() + Duration::from_secs(30);
|
||||
while Instant::now() < deadline {
|
||||
for event in engine.pump_vfs().unwrap() {
|
||||
match event {
|
||||
Event::Terminal(TerminalEvent::TerminalOutput { terminal_id, data })
|
||||
if terminal_id == id =>
|
||||
{
|
||||
assert!(!data.is_empty());
|
||||
seen.largest = seen.largest.max(data.len());
|
||||
seen.output.push_str(&data);
|
||||
}
|
||||
Event::Terminal(TerminalEvent::TerminalExited { terminal_id, code })
|
||||
if terminal_id == id =>
|
||||
{
|
||||
seen.exit = Some(code);
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
while seen.answered < seen.output.matches("\x1b[6n").count() {
|
||||
input(engine, id, "\x1b[1;1R").unwrap();
|
||||
seen.answered += 1;
|
||||
}
|
||||
if seen.exit.is_some() || done(&seen.output) {
|
||||
return;
|
||||
}
|
||||
std::thread::sleep(Duration::from_millis(10));
|
||||
}
|
||||
}
|
||||
|
||||
fn input(engine: &mut Engine, id: u64, data: &str) -> Result<Value, lutra_engine::EngineError> {
|
||||
engine
|
||||
.execute("terminal.input", json!({"terminalId": id, "data": data}))
|
||||
.map(|o| o.value)
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn create_output_input_exit() {
|
||||
let (_dir, mut engine) = open_project();
|
||||
let id = create(&mut engine);
|
||||
assert_eq!(engine.state().terminals.len(), 1);
|
||||
let mut seen = Pumped::default();
|
||||
input(&mut engine, id, "echo lutra-term\r").unwrap();
|
||||
pump_until(&mut engine, id, &mut seen, |out| {
|
||||
out.matches("lutra-term").count() >= 2
|
||||
});
|
||||
assert!(seen.output.contains("lutra-term"), "{:?}", seen.output);
|
||||
engine
|
||||
.execute(
|
||||
"terminal.resize",
|
||||
json!({"terminalId": id, "cols": 60, "rows": 20}),
|
||||
)
|
||||
.unwrap();
|
||||
input(&mut engine, id, "exit 7\r").unwrap();
|
||||
pump_until(&mut engine, id, &mut seen, |_| false);
|
||||
assert_eq!(seen.exit, Some(Some(7)));
|
||||
assert!(seen.largest <= MAX_OUTPUT_PER_TERMINAL);
|
||||
assert!(engine.state().terminals.is_empty());
|
||||
let err = input(&mut engine, id, "x").unwrap_err();
|
||||
assert_eq!(err.code(), "invalid_params");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn bad_params_fail() {
|
||||
let (_dir, mut engine) = open_project();
|
||||
for params in [
|
||||
json!({"cols": 0, "rows": 10}),
|
||||
json!({"cols": 80, "rows": 1001}),
|
||||
json!({"cols": 80}),
|
||||
json!({"cols": 80, "rows": 24, "cwd": "no-such-dir"}),
|
||||
json!({"cols": 80, "rows": 24, "extra": 1}),
|
||||
] {
|
||||
let err = engine
|
||||
.execute("terminal.create", params.clone())
|
||||
.unwrap_err();
|
||||
assert_eq!(err.code(), "invalid_params", "{params}");
|
||||
}
|
||||
let err = engine
|
||||
.execute(
|
||||
"terminal.create",
|
||||
json!({"cols": 80, "rows": 24, "shell": "lutra-no-such-shell-x"}),
|
||||
)
|
||||
.unwrap_err();
|
||||
assert_eq!(err.code(), "failed");
|
||||
let id = create(&mut engine);
|
||||
let big = "x".repeat(lutra_engine::cmd::terminal::MAX_INPUT_BYTES + 1);
|
||||
assert_eq!(
|
||||
input(&mut engine, id, &big).unwrap_err().code(),
|
||||
"invalid_params"
|
||||
);
|
||||
let err = engine
|
||||
.execute(
|
||||
"terminal.resize",
|
||||
json!({"terminalId": id, "cols": 0, "rows": 5}),
|
||||
)
|
||||
.unwrap_err();
|
||||
assert_eq!(err.code(), "invalid_params");
|
||||
let err = engine
|
||||
.execute(
|
||||
"terminal.resize",
|
||||
json!({"terminalId": 99, "cols": 10, "rows": 5}),
|
||||
)
|
||||
.unwrap_err();
|
||||
assert_eq!(err.code(), "invalid_params");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn close_project_close_and_quit_end_terminals() {
|
||||
let (_dir, mut engine) = open_project();
|
||||
let a = create(&mut engine);
|
||||
let out = engine
|
||||
.execute("terminal.close", json!({"terminalId": a}))
|
||||
.unwrap();
|
||||
assert_eq!(out.value["closed"], true);
|
||||
assert!(
|
||||
out.events
|
||||
.contains(&Event::Terminal(TerminalEvent::TerminalExited {
|
||||
terminal_id: a,
|
||||
code: None,
|
||||
}))
|
||||
);
|
||||
let out = engine
|
||||
.execute("terminal.close", json!({"terminalId": a}))
|
||||
.unwrap();
|
||||
assert_eq!(out.value["closed"], false);
|
||||
|
||||
let b = create(&mut engine);
|
||||
let out = engine.execute("project.close", json!({})).unwrap();
|
||||
assert!(
|
||||
out.events
|
||||
.contains(&Event::Terminal(TerminalEvent::TerminalExited {
|
||||
terminal_id: b,
|
||||
code: None,
|
||||
}))
|
||||
);
|
||||
assert!(engine.state().terminals.is_empty());
|
||||
let err = engine
|
||||
.execute("terminal.create", json!({"cols": 80, "rows": 24}))
|
||||
.unwrap_err();
|
||||
assert_eq!(err.code(), "disabled");
|
||||
|
||||
let (_dir2, mut engine) = open_project();
|
||||
let c = create(&mut engine);
|
||||
let d = create(&mut engine);
|
||||
assert!(d > c);
|
||||
let out = engine.execute("app.quit", json!({})).unwrap();
|
||||
for id in [c, d] {
|
||||
assert!(
|
||||
out.events
|
||||
.contains(&Event::Terminal(TerminalEvent::TerminalExited {
|
||||
terminal_id: id,
|
||||
code: None,
|
||||
}))
|
||||
);
|
||||
}
|
||||
assert!(engine.state().terminals.is_empty());
|
||||
}
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
}
|
||||
|
|
|
|||
410
crates/terminal/src/session.rs
Normal file
410
crates/terminal/src/session.rs
Normal 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;
|
||||
}
|
||||
}
|
||||
}
|
||||
110
crates/terminal/src/shell.rs
Normal file
110
crates/terminal/src/shell.rs
Normal 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
137
crates/terminal/src/utf8.rs
Normal 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());
|
||||
}
|
||||
}
|
||||
}
|
||||
263
crates/terminal/tests/session.rs
Normal file
263
crates/terminal/tests/session.rs
Normal 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 })
|
||||
));
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue