replay

package
v0.3.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 14, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Index

Constants

View Source
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

View Source
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",
	}
)
View Source
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 ListOpts

type ListOpts struct {
	SessionID uuid.UUID
	Limit     int
	Offset    int
}

ListOpts contains options for listing checkpoints.

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

func (m *Manager) DeleteCheckpoint(ctx context.Context, id uuid.UUID) error

DeleteCheckpoint deletes a checkpoint

func (*Manager) ForkFromCheckpoint

func (m *Manager) ForkFromCheckpoint(ctx context.Context, opts ForkOpts) (*uuid.UUID, error)

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

func (m *Manager) GetCheckpoint(ctx context.Context, id uuid.UUID) (*Checkpoint, error)

GetCheckpoint retrieves a specific checkpoint

func (*Manager) ListCheckpoints

func (m *Manager) ListCheckpoints(ctx context.Context, opts ListOpts) ([]*Checkpoint, error)

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL