Files
pipelines/internal/protocol/terminal.go
T
alan 227c036aa5 Start machine terminals at the su login prompt instead of tmux
A new terminal runs su -l for the server's own account in its PTY, so the
operator types the account password before getting a shell. Opening is
refused when su is missing, the server runs as root, or su opens a shell
without asking. The Pipelines-owned tmux backing, its reattach and its
persisted session names are removed: terminals end with the server and
are listed as ended. A starting server ends leftover pipelines-term_*
sessions on tmux -L pipelines only.
2026-11-10 00:37:11 +00:00

109 lines
4.7 KiB
Go

package protocol
// Machine terminals: interactive login shells the operator opens on a
// server's machine, independent of any chat. Each starts at the machine's
// login prompt for the server's own account (`su -l <user>` in a
// pseudo-terminal): the operator types that account's password before the
// login shell starts. A terminal ends with the server process and is then
// listed as ended (run tmux inside it to keep work across restarts). Typed
// input is never logged or stored.
const (
// TerminalOpen starts a terminal at the login prompt. The body is
// TerminalRequest (cwd, cols, rows); cwd defaults to the operator's home
// and must be an existing directory inside it (the shell starts there
// after the login). The reply, sent once the password prompt shows,
// carries the new terminal; the connection is subscribed to its
// terminal_event output frames. A login that cannot ask for a password
// (no su, a root server, an account without one) is refused.
TerminalOpen = "terminal_open"
// TerminalList lists this machine's terminals (running and ended),
// oldest first, without output. The body is optional.
TerminalList = "terminal_list"
// TerminalInput writes Data (UTF-8, control characters included, at most
// ChatShellInputLimit bytes) to a running terminal. No reply body.
TerminalInput = "terminal_input"
// TerminalResize sets a running terminal's size (cols, rows); the reply
// echoes the terminal.
TerminalResize = "terminal_resize"
// TerminalOutput reads one terminal with its retained output from the
// absolute byte After on (all of it when After precedes the retained
// tail; OutputStart says where it starts). It also subscribes the
// connection to the terminal's terminal_event output frames.
TerminalOutput = "terminal_output"
// TerminalClose ends a terminal: its login or shell is killed
// and its record removed. The reply echoes the last record.
TerminalClose = "terminal_close"
// TerminalEvent is pushed: an output chunk to the connections subscribed
// to that terminal (Output, Offset, End), or a lifecycle change (Terminal
// set: opened, title, exited, closed) to every connection.
TerminalEvent = "terminal_event"
)
// Terminal status values. Running is the only live status.
const (
TerminalRunning = "running"
TerminalExited = "exited"
TerminalClosed = "closed"
)
// Terminal bounds.
const (
// TerminalOpenLimit bounds the running terminals of one machine.
TerminalOpenLimit = 8
// TerminalRetained is the output tail kept for reconnecting clients.
TerminalRetained = 1 << 20
// TerminalChunkLimit bounds one live output frame.
TerminalChunkLimit = 64 << 10
// TerminalEndedKept bounds the ended terminals still listed.
TerminalEndedKept = 16
// TerminalTitleLimit bounds a recorded title.
TerminalTitleLimit = 200
)
// TerminalRequest is the body of every terminal request.
type TerminalRequest struct {
TerminalID string `json:"terminal_id,omitempty"`
Cwd string `json:"cwd,omitempty"`
Cols int `json:"cols,omitempty"`
Rows int `json:"rows,omitempty"`
Data string `json:"data,omitempty"`
After int64 `json:"after,omitempty"`
}
// TerminalRecord is one terminal. Output and OutputStart are set only on
// terminal_output replies.
type TerminalRecord struct {
ID string `json:"id"`
// Title is the last terminal title (OSC 0/2) the shell set, or empty;
// clients show the cwd then.
Title string `json:"title,omitempty"`
Cwd string `json:"cwd"`
Shell string `json:"shell"`
CreatedAt int64 `json:"created_at"`
Status string `json:"status"`
EndedAt int64 `json:"ended_at,omitempty"`
ExitCode *int `json:"exit_code,omitempty"`
// Reason says why an ended terminal ended when it was not simply its
// shell exiting (the login failed, the server stopped or restarted).
Reason string `json:"reason,omitempty"`
Cols int `json:"cols"`
Rows int `json:"rows"`
// Stream names this server process's output stream of the terminal;
// OutputEnd is the absolute byte count read into it. A client holding
// another stream reads the terminal again from its start.
Stream string `json:"stream,omitempty"`
OutputEnd int64 `json:"output_end"`
Output string `json:"output,omitempty"`
OutputStart int64 `json:"output_start,omitempty"`
}
// TerminalEventFrame is one pushed terminal change: either Terminal (a
// lifecycle change) or one output chunk covering bytes [Offset, End).
type TerminalEventFrame struct {
TerminalID string `json:"terminal_id"`
Terminal *TerminalRecord `json:"terminal,omitempty"`
Output string `json:"output,omitempty"`
Offset int64 `json:"offset,omitempty"`
End int64 `json:"end,omitempty"`
}