Documentation
¶
Overview ¶
Package sessions implements long-running command sessions inside a sandbox container: PTY or pipes, in-memory replay buffer, fan-out to multiple attached clients, and asciinema recording. Designed to live in toolboxd (PID 1 of the container) and be reachable via the toolbox HTTP/WS API.
Index ¶
- Variables
- type Config
- type Frame
- type Manager
- func (m *Manager) Close()
- func (m *Manager) Create(ctx context.Context, req models.CreateSessionRequest) (*Session, error)
- func (m *Manager) Delete(id string) error
- func (m *Manager) FlushRecording(id string) error
- func (m *Manager) Get(id string) (*Session, error)
- func (m *Manager) GetByName(name string) (*Session, error)
- func (m *Manager) GetOrCreate(ctx context.Context, req models.CreateSessionRequest) (*Session, bool, error)
- func (m *Manager) List() []models.Session
- type Session
- func (s *Session) CloseStdin() error
- func (s *Session) Done() <-chan struct{}
- func (s *Session) ExitInfo() (int, string)
- func (s *Session) ID() string
- func (s *Session) IsPTY() bool
- func (s *Session) Name() string
- func (s *Session) PID() int
- func (s *Session) RecordingPath() string
- func (s *Session) Replay() []byte
- func (s *Session) Resize(cols, rows int) error
- func (s *Session) Signal(name string) error
- func (s *Session) Snapshot() models.Session
- func (s *Session) Subscribe() (<-chan Frame, func())
- func (s *Session) Write(p []byte) (int, error)
- type Stream
Constants ¶
This section is empty.
Variables ¶
var ErrNoShell = errors.New("this sandbox's image has no shell: neither bash nor sh is installed")
ErrNoShell is returned for a shell or a command string in an image with neither bash nor sh (distroless, scratch). Without it the session fails later as "fork/exec /bin/sh: no such file or directory", which reads as a toolboxd fault rather than a property of the image.
var ErrNotFound = errors.New("session not found")
ErrNotFound is returned when a session ID isn't tracked.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// SandboxID is recorded in metadata and used as a recordings subdirectory.
SandboxID string
// RecordingDir is where asciinema cast files land. Required.
RecordingDir string
// RecordingRetention prunes cast files older than this. Zero = never.
RecordingRetention time.Duration
// SweepInterval drives the retention sweeper. Default 1 h.
SweepInterval time.Duration
// BufferBytes is the per-session replay buffer size. Default 1 MiB.
BufferBytes int
// StartProcess starts a session's command (start is cmd.Start, or a PTY
// start that calls it) and returns how to wait for its exit. toolboxd is
// PID 1 and reaps orphans with wait4(-1), which can take a session's own
// exit status before cmd.Wait does; it passes its child table here so
// the status reaches the session instead of reading as exit 0. Nil means
// start, then cmd.Wait: right for a host that reaps nothing (the WASM
// tool host).
StartProcess func(cmd *exec.Cmd, start func() error) (wait func() (code int, signal string), err error)
// BaseEnv returns the environment a session starts from, before the
// request's own env is laid on top. Nil means os.Environ(). toolboxd
// sets it so sessions, terminals and envd processes see the sandbox env
// a Firecracker host pushed over vsock (cmd/toolboxd/sandboxenv), which
// is not in toolboxd's own process environment.
BaseEnv func() []string
}
Config controls Manager behavior. Defaults are sensible for an in-container daemon; everything is overridable via toolboxd env vars.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager owns every Session running in the container.
func (*Manager) Close ¶
func (m *Manager) Close()
Close kills every running session and stops the sweeper. Best-effort.
func (*Manager) FlushRecording ¶ added in v0.4.1
FlushRecording best-effort fsyncs the asciinema cast file for the given session id. Called from the in-guest vsock handler's OnPreSnapshot (Phase 3 PR-B) so a clone resumed from the snapshot observes a session recording that ends cleanly at the freeze point rather than missing the trailing few-hundred bytes. Returns nil for sessions without an attached recording (the common case for template captures), unknown IDs (caller iterates List() and a session can finish between the two calls), and recorders that have already been Close()d.
func (*Manager) GetByName ¶ added in v0.1.7
GetByName fetches a running session by its stable name. Exited sessions are not returned because the byName map is cleared when a session finishes.
func (*Manager) GetOrCreate ¶
func (m *Manager) GetOrCreate(ctx context.Context, req models.CreateSessionRequest) (*Session, bool, error)
GetOrCreate returns the running session with the given Name (creating it from req if absent). Used by SSH attach so `ssh sandbox+default@host` idempotently lands on a single shared shell. created is true for exactly one of any number of concurrent callers for the same name: the others wait for that caller's session instead of starting their own.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is one long-running process plus the fan-out hub that distributes its output to attached clients. Methods are safe for concurrent use.
func (*Session) CloseStdin ¶
CloseStdin half-closes stdin so the process sees EOF.
func (*Session) Done ¶
func (s *Session) Done() <-chan struct{}
Done returns a channel that closes when the underlying process exits.
func (*Session) ExitInfo ¶
ExitInfo returns the exit code and signal name (empty if not signaled). If the session is still running, returns -1, "".
func (*Session) PID ¶ added in v0.1.7
PID returns the OS process identifier for the session, or 0 when the session has not started successfully.
func (*Session) RecordingPath ¶
RecordingPath returns the absolute path to the session's asciinema cast file, or "" if recording is disabled.
func (*Session) Signal ¶
Signal sends a signal to the session's process group. Accepts INT, TERM, KILL, HUP, QUIT (with or without SIG prefix).
func (*Session) Subscribe ¶
Subscribe registers a new attacher. The returned channel first receives a replay frame containing the current buffer contents (merged as stdout), then live output frames in order until the session ends or the caller calls the cancel function. Channel buffer size is 64; slow consumers drop older frames.