Documentation
¶
Index ¶
- Constants
- Variables
- type Checkpoint
- type CreateCheckpointOpts
- type ForkOpts
- type ListOpts
- type Manager
- func (m *Manager) CreateCheckpoint(ctx context.Context, opts CreateCheckpointOpts) (*Checkpoint, error)
- func (m *Manager) DeleteCheckpoint(ctx context.Context, id uuid.UUID) error
- func (m *Manager) ForkFromCheckpoint(ctx context.Context, opts ForkOpts) (*uuid.UUID, error)
- func (m *Manager) GetCheckpoint(ctx context.Context, id uuid.UUID) (*Checkpoint, error)
- func (m *Manager) ListCheckpoints(ctx context.Context, opts ListOpts) ([]*Checkpoint, error)
- func (m *Manager) RestoreCheckpoint(ctx context.Context, opts RestoreOpts) error
- type RestoreOpts
- type WorkspaceManager
Constants ¶
const ( MaxCheckpointNameLength = 200 MaxCheckpointDescriptionLength = 2000 MaxCheckpointCommandLength = 4096 MaxCheckpointArgs = 1000 MaxCheckpointEnvVars = 500 )
Bounds on caller-supplied checkpoint metadata. Stdout and stderr are truncated rather than rejected because a caller cannot control how much a command printed, but the fields it does choose are bounded so one checkpoint cannot carry megabytes of metadata.
Variables ¶
var ( // ErrCheckpointNotFound is returned when a checkpoint doesn't exist ErrCheckpointNotFound = errors.New("checkpoint not found") // ErrCheckpointLimitExceeded is returned when session has too many checkpoints ErrCheckpointLimitExceeded = errors.New("checkpoint limit exceeded") // ErrCheckpointTooLarge is returned when workspace is too large for checkpoint ErrCheckpointTooLarge = errors.New("checkpoint size exceeds limit") // ErrOrgStorageLimitExceeded is returned when org has too much checkpoint storage ErrOrgStorageLimitExceeded = errors.New("org checkpoint storage limit exceeded") // ErrCheckpointTampered is returned when HMAC signature is invalid ErrCheckpointTampered = errors.New("checkpoint signature invalid - possible tampering") // ErrActiveCommandsRunning is returned when trying to restore with active commands ErrActiveCommandsRunning = errors.New("cannot restore: active commands running") // ErrSessionNotFound is returned when the session a checkpoint refers to // does not exist ErrSessionNotFound = errors.New("session not found") // ErrReplayDisabled is returned when a session has not opted into replay ErrReplayDisabled = errors.New("replay is not enabled for this session") // ErrInvalidCheckpoint is returned when checkpoint input fails validation ErrInvalidCheckpoint = errors.New("invalid checkpoint") // SensitivePathPatterns are excluded from checkpoints for security SensitivePathPatterns = []string{ "**/*.key", "**/*.pem", "**/.ssh/*", "**/.aws/*", "**/id_rsa", "**/id_ed25519", "**/.env", "**/credentials", "**/secrets.yaml", "**/secret.*", } // SensitiveEnvVars are substrings that mark an environment variable as // secret; a matching variable is replaced with [REDACTED] in checkpoint // snapshots. Matching is substring-based and case-insensitive, so short // generic fragments cover many concrete names: "KEY" covers // AWS_ACCESS_KEY_ID, SSH_KEY and API_KEY alike. // // Erring toward over-redaction is deliberate: a redacted non-secret is a // minor annoyance during debugging, a leaked credential is not. SensitiveEnvVars = []string{ "PASSWORD", "PASSWD", "PWD", "SECRET", "TOKEN", "KEY", "CREDENTIAL", "AUTH", "SALT", "PASSPHRASE", "CIPHER", "SESSION", "COOKIE", "CERT", "SIGNATURE", "SIGNING", "PRIVATE", "APIKEY", "DSN", "CONNECTION_STRING", } )
var ( // DefaultCheckpointLimit is the default number of checkpoints to return DefaultCheckpointLimit = 50 // MaxCheckpointsPerSession is the maximum checkpoints allowed per session MaxCheckpointsPerSession = 50 // MaxCheckpointListLimit is the largest page a list request may ask for. MaxCheckpointListLimit = 100 // MaxCheckpointSizeBytes is the maximum size of a single checkpoint MaxCheckpointSizeBytes = int64(2 * 1024 * 1024 * 1024) // 2GB // MaxTotalCheckpointStoragePerOrg is the maximum total checkpoint storage per org MaxTotalCheckpointStoragePerOrg = int64(100 * 1024 * 1024 * 1024) // 100GB )
Functions ¶
This section is empty.
Types ¶
type Checkpoint ¶
type Checkpoint struct {
ID uuid.UUID `json:"id" db:"id"`
SessionID uuid.UUID `json:"session_id" db:"session_id"`
RunID *uuid.UUID `json:"run_id,omitempty" db:"run_id"`
CheckpointNumber int `json:"checkpoint_number" db:"checkpoint_number"`
Name *string `json:"name,omitempty" db:"name"`
Description string `json:"description" db:"description"`
WorkspaceSnapshotID uuid.UUID `json:"workspace_snapshot_id" db:"workspace_snapshot_id"`
ArchivePath string `json:"-" db:"archive_path"` // Never expose to API
EnvVarsSnapshot models.JSONB `json:"env_vars_snapshot,omitempty" db:"env_vars_snapshot"`
Command string `json:"command,omitempty" db:"command"`
Args models.JSONB `json:"args,omitempty" db:"args"`
ExitCode *int `json:"exit_code,omitempty" db:"exit_code"`
DurationMs *int `json:"duration_ms,omitempty" db:"duration_ms"`
StdoutPreview string `json:"stdout_preview,omitempty" db:"stdout_preview"`
StderrPreview string `json:"stderr_preview,omitempty" db:"stderr_preview"`
Signature string `json:"signature" db:"signature"`
CreatedAt time.Time `json:"created_at" db:"created_at"`
SizeBytes int64 `json:"size_bytes" db:"size_bytes"`
}
Checkpoint represents a point-in-time snapshot of a session. Can be restored or forked to enable time-travel debugging.
type CreateCheckpointOpts ¶
type CreateCheckpointOpts struct {
SessionID uuid.UUID
RunID *uuid.UUID
Name *string
Description string
Command string
Args []string
ExitCode *int
DurationMs *int
Stdout string
Stderr string
EnvVars map[string]string
}
CreateCheckpointOpts contains options for creating a checkpoint.
type ForkOpts ¶
type ForkOpts struct {
CheckpointID uuid.UUID
Name string // Name for new session
// Actor owns the new session. It must be the caller, not the owner of the
// source session: quotas and ownership are keyed on created_by, so
// attributing a fork to someone else both misreports who started it and
// leaves the caller's own quota untouched. Empty falls back to the source
// session's owner.
Actor string
CPULimit *float64
MemoryLimitMB *int
}
ForkOpts contains options for forking a checkpoint.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager manages session replay checkpoints
func New ¶
func New(db *sqlx.DB, ws WorkspaceManager, signingKey []byte) *Manager
New creates a new replay Manager
func (*Manager) CreateCheckpoint ¶
func (m *Manager) CreateCheckpoint(ctx context.Context, opts CreateCheckpointOpts) (*Checkpoint, error)
CreateCheckpoint creates a new checkpoint for a session. This should be called after command execution with the run results.
func (*Manager) DeleteCheckpoint ¶
DeleteCheckpoint deletes a checkpoint
func (*Manager) ForkFromCheckpoint ¶
ForkFromCheckpoint creates a new session whose workspace is the checkpoint's snapshot, leaving the original session untouched.
The new session inherits the source session's image, network configuration and org, because a fork is meant to reproduce the recorded state — running it against a different image would not reproduce anything. CPU and memory may be raised or lowered by the caller; the caller is responsible for bounding those against the deployment's limits before calling.
func (*Manager) GetCheckpoint ¶
GetCheckpoint retrieves a specific checkpoint
func (*Manager) ListCheckpoints ¶
ListCheckpoints lists checkpoints for a session.
Limit and offset are clamped here rather than trusted from the caller: in Postgres a negative LIMIT means "no limit", so passing limit=-1 would return every checkpoint and a negative OFFSET is an outright query error.
func (*Manager) RestoreCheckpoint ¶
func (m *Manager) RestoreCheckpoint(ctx context.Context, opts RestoreOpts) error
RestoreCheckpoint restores a session to a previous checkpoint state
type RestoreOpts ¶
type RestoreOpts struct {
SessionID uuid.UUID
CheckpointID uuid.UUID
StopActiveCommands bool // If true, stop active commands before restoring
}
RestoreOpts contains options for restoring a checkpoint.
type WorkspaceManager ¶
type WorkspaceManager interface {
Create(sessionID uuid.UUID) (path string, err error)
Delete(sessionID uuid.UUID) error
CreateSnapshot(sessionID, snapshotID uuid.UUID) (archivePath string, sizeBytes int64, err error)
RestoreSnapshot(sessionID uuid.UUID, archivePath string) error
DeleteSnapshot(archivePath string) error
}
WorkspaceManager defines the interface for workspace operations