38 lines
2.1 KiB
Go
38 lines
2.1 KiB
Go
// Package terminal is the live-terminal streaming feature: each WebSocket
|
|
// client that opens a pane gets its OWN attach Stream, piped over a
|
|
// ch-tagged wire protocol, alongside a session-state channel fed by the CDC
|
|
// broadcaster.
|
|
//
|
|
// The runtime is selected by runtimeselect: tmux on Darwin/Linux, conpty on
|
|
// Windows. On unix, tmux spawns an attach CLI (`tmux attach`) on a local PTY
|
|
// via ptyexec; on Windows, conpty dials the session's loopback pty-host and
|
|
// speaks its framing protocol directly (no attach CLI).
|
|
//
|
|
// Per-client attach (no shared PTY, no replay buffer): the multiplexer owns the
|
|
// session's screen state and scrollback, and answers every fresh attach with
|
|
// its full init handshake (alt screen, SGR mouse tracking, bracketed paste)
|
|
// followed by a faithful repaint. Sharing one PTY and replaying a bounded byte
|
|
// ring to late subscribers loses exactly that handshake (it is emitted once, at
|
|
// the head of the stream), which left clients without mouse reporting (wheel
|
|
// scroll dead). Spawning a fresh attach per client makes the runtime re-send
|
|
// it, every time, by construction. The cost is one client process (tmux) or one
|
|
// loopback connection (conpty) per open pane per connection.
|
|
//
|
|
// Boundaries (see docs/architecture.md):
|
|
//
|
|
// - This package owns the product workflow: per-client PTY attach, liveness
|
|
// gating, re-attach resilience, and the ch-tagged wire protocol. It is
|
|
// transport-agnostic: it speaks to a small wsConn interface, not to any
|
|
// concrete WebSocket library.
|
|
// - internal/httpd owns the HTTP/WebSocket upgrade and adapts the accepted
|
|
// socket to wsConn; it does not contain stream logic.
|
|
// - The PTY itself is reached through PTYSource (satisfied by the selected
|
|
// runtime adapter's AttachCommand/IsAlive) and spawned through an injectable
|
|
// spawnFunc, so the attach and re-attach logic test without a real process,
|
|
// runtime, or network.
|
|
//
|
|
// Raw PTY bytes never flow through the CDC change_log; only the session channel
|
|
// is fed by cdc.Broadcaster. Terminal output is high-volume ephemeral data and
|
|
// goes straight from the PTY to the socket.
|
|
package terminal
|