Files
pipelines/internal/protocol/terminal.go
T

114 lines
4.9 KiB
Go

package protocol
// Machine terminals: interactive login shells the operator opens on a
// server's machine, independent of any chat. Each runs `$SHELL -l` (else
// /bin/sh) in a pseudo-terminal; where tmux is installed the shell lives in
// a Pipelines-owned tmux server (socket name "pipelines", never the
// operator's own), so it survives a Pipelines server restart and the next
// process reattaches it. Without tmux a shell ends with the server and is
// listed as ended. Typed input is never logged or stored.
const (
// TerminalOpen starts a shell. The body is TerminalRequest (cwd, cols,
// rows); cwd defaults to the operator's home and must be an existing
// directory inside it. The reply carries the new terminal; the
// connection is then subscribed to its terminal_event output frames.
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 shell (and tmux session) 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
// TerminalTmuxHistory is the tmux scrollback of one tmux-backed shell.
TerminalTmuxHistory = 10000
// 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"`
// Tmux is the tmux session name keeping the shell alive across server
// restarts; empty when the shell is a direct child of the server and
// ends with it.
Tmux string `json:"tmux,omitempty"`
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 server restarted without tmux, its tmux session
// was gone).
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 restarted server
// that reattaches starts a new stream at zero, so 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"`
}