Skip to content

A modern terminal with a built-in multiplexer: close it and your sessions keep running. Run shells and tons of AI agents across your machines, then pick them up from desktop, browser, TUI and more. Written in Rust with no UI framework: interface drawn straight on the GPU. No Electron, GPUI or webview.

feat(mux): carry plugin frames between clients and the plugin server

RoversXe8a656231fa4
diff --git a/codec/Cargo.toml b/codec/Cargo.toml
index 649bcfe6..d85223ea 100644
--- a/codec/Cargo.toml
+++ b/codec/Cargo.toml
@@ -15,6 +15,7 @@ metrics.workspace = true
rangeset.workspace = true
thinkterm-proto.workspace = true
serde = {workspace=true, features = ["rc", "derive"]}
+serde_bytes.workspace = true
futures-lite.workspace = true
termwiz.workspace = true
thiserror.workspace = true
@@ -31,7 +32,6 @@ zstd.workspace = true
ruzstd.workspace = true
[dev-dependencies]
-serde_bytes.workspace = true
base91.workspace = true
chrono.workspace = true
serde_json.workspace = true
diff --git a/codec/src/lib.rs b/codec/src/lib.rs
index 2959f495..6639d072 100644
--- a/codec/src/lib.rs
+++ b/codec/src/lib.rs
@@ -577,7 +577,10 @@ macro_rules! pdu {
/// port is minted, listed and revoked over the mux connection
/// (WebTokenMint/List/Revoke), the way TLS credentials are obtained.
/// 72: Web status and minted links carry the live TLS certificate identity.
-pub const CODEC_VERSION: usize = 72;
+/// 73: The plugin channel: a client reaches the plugin host on the server's
+/// machine through its mux connection (PluginFrame), which the server
+/// carries unread.
+pub const CODEC_VERSION: usize = 73;
// Defines the Pdu enum.
// Each struct has an explicit identifying number.
@@ -671,6 +674,7 @@ pdu! {
WebServerStatus: 93,
DefaultPalette: 94,
MoveTab: 95,
+ PluginFrame: 96,
}
impl Pdu {
@@ -1549,6 +1553,23 @@ pub struct MoveTab {
pub index: usize,
}
+/// One frame of the plugin channel (the thinkterm-plugin-channel crate), between
+/// a client and the plugin host on the server's machine. The server passes
+/// it on without reading it.
+///
+/// From a client: for the host, over a connection the server opens at the
+/// first frame and keeps for this client until it disconnects. Answered
+/// with `UnitResponse` once the frame has left, or with an error when there
+/// is no host to reach. An empty frame closes that connection.
+///
+/// From the server, unasked: a frame the host sent, or an empty one when
+/// the connection to the host closed.
+#[derive(Deserialize, Serialize, PartialEq, Debug)]
+pub struct PluginFrame {
+ #[serde(with = "serde_bytes")]
+ pub data: Vec<u8>,
+}
+
#[derive(Deserialize, Serialize, PartialEq, Debug)]
pub struct SetPaneZoomed {
pub containing_tab_id: TabId,
@@ -2560,7 +2581,7 @@ mod test {
// The exact assertion is the tripwire: whoever bumps the codec must
// come here, confirm the round-trips still cover the new version,
// and advance it deliberately.
- assert_eq!(CODEC_VERSION, 72);
+ assert_eq!(CODEC_VERSION, 73);
use thinkterm_proto::{AgentEvidence, AgentState, AgentStatus};
fn round_trip(pdu: Pdu) {
@@ -2598,6 +2619,18 @@ mod test {
}));
}
+ #[test]
+ fn plugin_frames_round_trip_as_bytes() {
+ for data in [vec![], b"{\"call\":{}}".to_vec(), vec![0u8; 70_000]] {
+ let pdu = Pdu::PluginFrame(PluginFrame { data });
+ let mut encoded = Vec::new();
+ pdu.encode(&mut encoded, 0x73).unwrap();
+ let decoded = Pdu::decode(encoded.as_slice()).unwrap();
+ assert_eq!(decoded.serial, 0x73);
+ assert_eq!(decoded.pdu, pdu);
+ }
+ }
+
#[test]
fn thinkterm_session_viewport_and_landing_protocol_round_trip() {
let size = TerminalSize {
diff --git a/wezterm-mux-server-impl/Cargo.toml b/wezterm-mux-server-impl/Cargo.toml
index 15d50e64..1d9382d1 100644
--- a/wezterm-mux-server-impl/Cargo.toml
+++ b/wezterm-mux-server-impl/Cargo.toml
@@ -45,6 +45,7 @@ wezterm-term = { workspace=true, features=["use_serde"] }
wezterm-uds.workspace = true
varbincode.workspace = true
zstd.workspace = true
+thinkterm-plugin-channel = { workspace = true, features = ["native"] }
thinkterm-proto.workspace = true
[target."cfg(unix)".dependencies]
diff --git a/wezterm-mux-server-impl/src/lib.rs b/wezterm-mux-server-impl/src/lib.rs
index 5b96c5c3..ca2a8ce6 100644
--- a/wezterm-mux-server-impl/src/lib.rs
+++ b/wezterm-mux-server-impl/src/lib.rs
@@ -11,6 +11,7 @@ pub mod dispatch;
pub mod handoff;
pub mod local;
pub mod pki;
+mod plugin_relay;
mod private_file;
mod sent_images;
pub mod sessionhandler;
diff --git a/wezterm-mux-server-impl/src/plugin_relay.rs b/wezterm-mux-server-impl/src/plugin_relay.rs
new file mode 100644
index 00000000..56becc95
--- /dev/null
+++ b/wezterm-mux-server-impl/src/plugin_relay.rs
@@ -0,0 +1,288 @@
+//! The plugin channel through the mux: a client's frames to the plugin host
+//! on this machine, and the host's frames back, carried unread.
+//!
+//! The mux runs terminals and nothing else; the plugins run in a process of
+//! their own (see thinkterm-plugin-channel). A browser can only reach the mux, so
+//! this is its way there. Each client that sends a frame gets a connection
+//! of its own to the host, opened at its first frame and closed when the
+//! client asks or goes away; to the host it is one more client.
+
+use crate::sessionhandler::PduSender;
+use anyhow::anyhow;
+use codec::{DecodedPdu, Pdu, PluginFrame, UnitResponse};
+use smol::channel::{bounded, Receiver, Sender, TrySendError};
+use smol::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
+use smol::Async;
+use std::io;
+use thinkterm_plugin_channel::client::{Connection, Host};
+use thinkterm_plugin_channel::wire::{frame_header, frame_len};
+
+/// Frames one client may have on their way to the host at once; a client
+/// with more is not waiting for its answers.
+const QUEUE: usize = 64;
+
+pub(crate) type Respond = Box<dyn FnOnce(anyhow::Result<Pdu>) + Send>;
+
+/// One client's connection to the host. Dropping it ends the connection
+/// once what the client already sent has left: a change sent just before
+/// the client closed the panel, or went away, is still made.
+pub(crate) struct Pipe {
+ frames: Sender<(Vec<u8>, Respond)>,
+ carrier: Option<smol::Task<()>>,
+}
+
+impl Drop for Pipe {
+ fn drop(&mut self) {
+ // The carrier drains the queue, finds it closed, and ends.
+ self.frames.close();
+ if let Some(carrier) = self.carrier.take() {
+ carrier.detach();
+ }
+ }
+}
+
+impl Pipe {
+ /// A connection to the host this build ships, started if need be.
+ pub(crate) fn open(to_client: PduSender) -> Self {
+ Self::open_with(to_client, || Host::for_this_build()?.connect())
+ }
+
+ fn open_with(
+ to_client: PduSender,
+ connect: impl FnOnce() -> anyhow::Result<Connection> + Send + 'static,
+ ) -> Self {
+ let (frames, queued) = bounded(QUEUE);
+ Self {
+ frames,
+ carrier: Some(crate::connections::spawn_task(carry(
+ queued, to_client, connect,
+ ))),
+ }
+ }
+
+ /// Connected, or still connecting.
+ pub(crate) fn is_open(&self) -> bool {
+ !self.frames.is_closed()
+ }
+
+ /// Sends `data` on to the host; `respond` is told once it has left.
+ pub(crate) fn send(&self, data: Vec<u8>, respond: Respond) {
+ match self.frames.try_send((data, respond)) {
+ Ok(()) => {}
+ Err(TrySendError::Full((_, respond))) => respond(Err(anyhow!(
+ "too many frames are already on their way to the plugin host"
+ ))),
+ Err(TrySendError::Closed((_, respond))) => {
+ respond(Err(anyhow!("the connection to the plugin host has closed")))
+ }
+ }
+ }
+}
+
+async fn carry(
+ queued: Receiver<(Vec<u8>, Respond)>,
+ to_client: PduSender,
+ connect: impl FnOnce() -> anyhow::Result<Connection> + Send + 'static,
+) {
+ // Off the connection threads: reaching the host may mean starting it.
+ let stream = match smol::unblock(move || -> anyhow::Result<_> {
+ Ok(Async::new(connect()?.into_stream())?)
+ })
+ .await
+ {
+ Ok(stream) => stream,
+ Err(err) => {
+ let reason = format!("{err:#}");
+ log::warn!("cannot reach the plugin host: {reason}");
+ refuse_waiting(&queued, &format!("no plugin host here: {reason}"));
+ return;
+ }
+ };
+ let (mut from_host, mut to_host) = smol::io::split(stream);
+ let outbound = async {
+ while let Ok((data, respond)) = queued.recv().await {
+ match write_frame(&mut to_host, &data).await {
+ Ok(()) => respond(Ok(Pdu::UnitResponse(UnitResponse {}))),
+ Err(err) => {
+ respond(Err(anyhow!("sending to the plugin host: {err}")));
+ return;
+ }
+ }
+ }
+ };
+ let inbound = async {
+ while let Ok(data) = read_frame(&mut from_host).await {
+ let frame = DecodedPdu {
+ serial: 0,
+ pdu: Pdu::PluginFrame(PluginFrame { data }),
+ };
+ if to_client.send(frame).is_err() {
+ return;
+ }
+ }
+ };
+ smol::future::or(outbound, inbound).await;
+ refuse_waiting(&queued, "the connection to the plugin host has closed");
+ // An empty frame: the client may open another connection when it wants.
+ let _ = to_client.send(DecodedPdu {
+ serial: 0,
+ pdu: Pdu::PluginFrame(PluginFrame { data: vec![] }),
+ });
+}
+
+/// Closes the queue, answering whatever was still in it.
+fn refuse_waiting(queued: &Receiver<(Vec<u8>, Respond)>, reason: &str) {
+ queued.close();
+ while let Ok((_, respond)) = queued.try_recv() {
+ respond(Err(anyhow!("{reason}")));
+ }
+}
+
+fn too_long() -> io::Error {
+ io::Error::new(io::ErrorKind::InvalidData, "plugin frame too long")
+}
+
+async fn write_frame(to: &mut (impl AsyncWrite + Unpin), payload: &[u8]) -> io::Result<()> {
+ let header = frame_header(payload.len()).ok_or_else(too_long)?;
+ let mut frame = Vec::with_capacity(header.len() + payload.len());
+ frame.extend_from_slice(&header);
+ frame.extend_from_slice(payload);
+ to.write_all(&frame).await?;
+ to.flush().await
+}
+
+async fn read_frame(from: &mut (impl AsyncRead + Unpin)) -> io::Result<Vec<u8>> {
+ let mut header = [0u8; 4];
+ from.read_exact(&mut header).await?;
+ let len = frame_len(header).ok_or_else(too_long)?;
+ let mut payload = vec![0u8; len];
+ from.read_exact(&mut payload).await?;
+ Ok(payload)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use std::path::Path;
+ use std::sync::mpsc;
+ use std::time::Duration;
+ use thinkterm_plugin_channel::wire::{self, FromHost, PROTOCOL};
+
+ const WAIT: Duration = Duration::from_secs(10);
+
+ fn host_at(dir: &Path) -> Host {
+ Host {
+ socket: dir.join("sock"),
+ lock: dir.join("lock"),
+ data_dir: dir.join("data"),
+ log: dir.join("log"),
+ program: dir.join("no-such-program"),
+ }
+ }
+
+ fn client() -> (PduSender, mpsc::Receiver<Pdu>) {
+ let (tx, rx) = mpsc::channel();
+ let sender = PduSender::new(move |decoded: DecodedPdu| {
+ assert_eq!(decoded.serial, 0, "pushes are unasked");
+ tx.send(decoded.pdu).map_err(|err| anyhow!("{err}"))
+ });
+ (sender, rx)
+ }
+
+ fn send(pipe: &Pipe, data: &[u8]) -> anyhow::Result<Pdu> {
+ let (tx, rx) = mpsc::channel();
+ pipe.send(
+ data.to_vec(),
+ Box::new(move |result| {
+ let _ = tx.send(result);
+ }),
+ );
+ rx.recv_timeout(WAIT).expect("an answer")
+ }
+
+ fn pushed(rx: &mpsc::Receiver<Pdu>) -> Vec<u8> {
+ match rx.recv_timeout(WAIT).expect("a push") {
+ Pdu::PluginFrame(PluginFrame { data }) => data,
+ other => panic!("expected a plugin frame, got {other:?}"),
+ }
+ }
+
+ #[test]
+ fn frames_go_both_ways_as_they_are() {
+ let dir = tempfile::tempdir().unwrap();
+ let host = host_at(dir.path());
+ // A host that answers each frame with its bytes reversed, whatever
+ // they are, and hangs up when told to.
+ let listener = wezterm_uds::UnixListener::bind(&host.socket).unwrap();
+ let fake = std::thread::spawn(move || {
+ let (mut stream, _) = listener.accept().unwrap();
+ let hello = FromHost::Hello { protocol: PROTOCOL }.encode();
+ wire::write_frame(&mut stream, &hello).unwrap();
+ loop {
+ let frame = wire::read_frame(&mut stream).unwrap();
+ if frame == b"bye" {
+ return;
+ }
+ let reversed: Vec<u8> = frame.into_iter().rev().collect();
+ wire::write_frame(&mut stream, &reversed).unwrap();
+ }
+ });
+
+ let (sender, pushes) = client();
+ let pipe = Pipe::open_with(sender, move || host.connect());
+ assert!(matches!(
+ send(&pipe, b"not json at all"),
+ Ok(Pdu::UnitResponse(_))
+ ));
+ assert_eq!(pushed(&pushes), b"lla ta nosj ton");
+ assert!(matches!(send(&pipe, b"bye"), Ok(Pdu::UnitResponse(_))));
+ fake.join().unwrap();
+ // The host hung up: the client is told with an empty frame, and the
+ // pipe is closed for good.
+ assert_eq!(pushed(&pushes), b"");
+ assert!(!pipe.is_open());
+ assert!(send(&pipe, b"more").is_err());
+ }
+
+ #[test]
+ fn what_was_sent_before_the_pipe_closed_still_arrives() {
+ let dir = tempfile::tempdir().unwrap();
+ let host = host_at(dir.path());
+ let listener = wezterm_uds::UnixListener::bind(&host.socket).unwrap();
+ let fake = std::thread::spawn(move || {
+ let (mut stream, _) = listener.accept().unwrap();
+ let hello = FromHost::Hello { protocol: PROTOCOL }.encode();
+ wire::write_frame(&mut stream, &hello).unwrap();
+ let mut got = Vec::new();
+ while let Ok(frame) = wire::read_frame(&mut stream) {
+ got.push(frame);
+ }
+ got
+ });
+ let (sender, _pushes) = client();
+ let pipe = Pipe::open_with(sender, move || host.connect());
+ for frame in [&b"one"[..], b"two", b"three"] {
+ pipe.send(frame.to_vec(), Box::new(|_| {}));
+ }
+ // Closed while the connection may still be coming up.
+ drop(pipe);
+ assert_eq!(
+ fake.join().unwrap(),
+ [b"one".to_vec(), b"two".to_vec(), b"three".to_vec()]
+ );
+ }
+
+ #[test]
+ fn a_frame_with_no_host_to_reach_is_refused() {
+ let dir = tempfile::tempdir().unwrap();
+ let host = host_at(dir.path());
+ let (sender, _pushes) = client();
+ let pipe = Pipe::open_with(sender, move || host.connect());
+ let err = send(&pipe, b"{}").unwrap_err();
+ assert!(
+ format!("{err:#}").contains("no plugin host here"),
+ "{err:#}"
+ );
+ assert!(!pipe.is_open());
+ }
+}
diff --git a/wezterm-mux-server-impl/src/sessionhandler.rs b/wezterm-mux-server-impl/src/sessionhandler.rs
index c94dd81d..26e423d0 100644
--- a/wezterm-mux-server-impl/src/sessionhandler.rs
+++ b/wezterm-mux-server-impl/src/sessionhandler.rs
@@ -1095,6 +1095,7 @@ fn web_peer_may_send(pdu: &Pdu) -> bool {
| Pdu::SetClientView(_)
| Pdu::SetFrontendAccessMode(_)
| Pdu::GetAgentStatuses(_)
+ | Pdu::PluginFrame(_)
)
}
@@ -1106,6 +1107,10 @@ pub struct SessionHandler {
client_registration: Option<ClientRegistrationId>,
palette_session_id: Option<PaletteSessionId>,
proxy_client_id: Option<ClientId>,
+ /// This client's connection to the plugin host, from its first
+ /// `PluginFrame` on; it closes when this does, or when the client
+ /// sends an empty frame.
+ plugin_pipe: Option<crate::plugin_relay::Pipe>,
}
impl Drop for SessionHandler {
@@ -1135,6 +1140,7 @@ impl SessionHandler {
client_registration: None,
palette_session_id: None,
proxy_client_id: None,
+ plugin_pipe: None,
}
}
@@ -2365,6 +2371,22 @@ impl SessionHandler {
}
}
+ // Carried to the plugin host unread; see plugin_relay.
+ Pdu::PluginFrame(PluginFrame { data }) => {
+ if data.is_empty() {
+ self.plugin_pipe = None;
+ send_response(Ok(Pdu::UnitResponse(UnitResponse {})));
+ return;
+ }
+ if !self.plugin_pipe.as_ref().is_some_and(|pipe| pipe.is_open()) {
+ self.plugin_pipe =
+ Some(crate::plugin_relay::Pipe::open(self.to_write_tx.clone()));
+ }
+ if let Some(pipe) = &self.plugin_pipe {
+ pipe.send(data, Box::new(send_response));
+ }
+ }
+
Pdu::GetServerOsRelease(_) => send_response(Ok(Pdu::GetServerOsReleaseResponse(
GetServerOsReleaseResponse {
os_release_id: local_os_release_id().clone(),