sandbox

type BackendType string

type DirectBackend struct {
	// contains filtered or unexported fields
}

type DockerBackend struct {
	// contains filtered or unexported fields
}

type ExecuteRequest struct {
	// Code is the Python code to execute.
	Code string
	// ExecutionID identifies this execution. When empty, the backend mints one.
	// Supplying it lets the caller correlate runtime tokens, storage tagging, and logs.
	ExecutionID string
	// Env contains additional environment variables to set in the sandbox.
	Env map[string]string
	// Timeout overrides the default execution timeout. If zero, uses the config default.
	Timeout time.Duration
	// SessionID is an optional session ID to reuse a persistent container.
	// If empty, a new session is created. If provided, the existing session is reused.
	SessionID string
	// OwnerID is the GitHub user ID that owns the session.
	// Required for session creation and verification.
	OwnerID string
}

type ExecutionResult struct {
	// Stdout contains the standard output from execution.
	Stdout string
	// Stderr contains the standard error from execution.
	Stderr string
	// ExitCode is the process exit code (0 = success).
	ExitCode int
	// ExecutionID is a unique identifier for this execution.
	ExecutionID string
	// OutputFiles lists file names created in /output directory.
	OutputFiles []string
	// Metrics contains any metrics reported by the executed code.
	Metrics map[string]any
	// DurationSeconds is the wall-clock execution time.
	DurationSeconds float64

	// Session-related fields (only populated when sessions are enabled).
	// SessionID is the session identifier. Can be used to reuse this session.
	SessionID string
	// SessionFiles lists files persisted in the session's /workspace directory.
	SessionFiles []SessionFile
	// SessionTTLRemaining is the time until this session expires from inactivity.
	SessionTTLRemaining time.Duration
}

type GVisorBackend struct {
	*DockerBackend
}

type NoneBackend struct {
	// contains filtered or unexported fields
}

type SecurityConfig struct {
	// User to run the container as (e.g., "nobody").
	User string
	// ReadonlyRootfs makes the root filesystem read-only.
	ReadonlyRootfs bool
	// DropCapabilities lists Linux capabilities to drop.
	DropCapabilities []string
	// SecurityOpts are additional security options (e.g., "no-new-privileges:true").
	SecurityOpts []string
	// PidsLimit restricts the number of processes in the container.
	PidsLimit int64
	// MemoryLimit in bytes.
	MemoryLimit int64
	// CPUQuota as a percentage of one CPU (100000 = 1 CPU).
	CPUQuota int64
	// CPUPeriod is the CPU CFS scheduler period.
	CPUPeriod int64
	// TmpfsSize is the size of the /tmp tmpfs mount.
	TmpfsSize string
	// Runtime specifies the container runtime (e.g., "" for default, "runsc" for gVisor).
	Runtime string
}

type SecurityConfigFunc func(memoryLimit string, cpuLimit float64) (*SecurityConfig, error)

type Service interface {
	// Start initializes the sandbox backend (e.g., connecting to Docker).
	Start(ctx context.Context) error
	// Stop cleans up resources and any active containers.
	Stop(ctx context.Context) error
	// Execute runs Python code in an isolated container.
	Execute(ctx context.Context, req ExecuteRequest) (*ExecutionResult, error)
	// Name returns the backend name for logging/metrics.
	Name() string

	// ListSessions returns all active sessions. If ownerID is non-empty, filters by owner.
	ListSessions(ctx context.Context, ownerID string) ([]SessionInfo, error)
	// CreateSession creates a new empty session and returns its ID.
	CreateSession(ctx context.Context, ownerID string, env map[string]string) (string, error)
	// DestroySession destroys a session by ID.
	// If ownerID is non-empty, verifies ownership before destroying.
	DestroySession(ctx context.Context, sessionID, ownerID string) error
	// CanCreateSession checks if a new session can be created.
	// Returns (canCreate, currentCount, maxAllowed).
	CanCreateSession(ctx context.Context, ownerID string) (bool, int, int)
	// SessionsEnabled returns whether sessions are enabled.
	SessionsEnabled() bool
}

type Session struct {
	ID        string
	OwnerID   string // Optional owner ID for session binding.
	Handle    string
	CreatedAt time.Time
	LastUsed  time.Time
	Env       map[string]string
}

type SessionFile struct {
	Name     string    `json:"name"`
	Size     int64     `json:"size"`
	Modified time.Time `json:"modified"`
}

type SessionInfo struct {
	ID             string        `json:"session_id"`
	CreatedAt      time.Time     `json:"created_at"`
	LastUsed       time.Time     `json:"last_used"`
	TTLRemaining   time.Duration `json:"ttl_remaining"`
	WorkspaceFiles []SessionFile `json:"workspace_files"`
}

type SessionManager struct {
	// contains filtered or unexported fields
}

type SessionStore interface {
	// Get returns the session with the given ID, or (nil, nil) when it does not
	// exist. A non-nil error is a lookup failure, not a missing session.
	Get(ctx context.Context, sessionID string) (*Session, error)
	// List returns all live sessions.
	List(ctx context.Context) ([]*Session, error)
	// Remove tears down the session's backing resource (container / workspace).
	Remove(ctx context.Context, session *Session) error
}