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 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
}
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) Delete ¶
Delete removes a session record. If it's still running, signal it first. Always best-effort — does not block on the process actually exiting.
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.
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.
Source Files