control

type CreateSandboxRequest struct {
	Labels    map[string]string
	Template  string       // Provider-specific template/base image.
	Resources ResourceSpec // CPU, memory limits.
}

type CreateSandboxResponse struct {
	SandboxID    string
	Address      string // How to reach this sandbox ("host:port").
	Capabilities SandboxCapabilities
}

type GetProcessStatusRequest struct {
	SandboxID string
	ProcessID string
}

type GetProcessStatusResponse struct {
	Status   ProcessStatus
	ExitCode *int // Only set if Status == ProcessExited.
}

type KillProcessRequest struct {
	SandboxID string
	ProcessID string
	Signal    int // Unix signal (default SIGTERM if 0).
}

type LaunchProcessRequest struct {
	SandboxID  string
	Binary     string            // Path to binary or command name.
	Args       []string          // Command arguments.
	Env        map[string]string // Environment variables (including API keys).
	ExposePort int               // Port the process will listen on inside sandbox.
}

type LaunchProcessResponse struct {
	ProcessID string
	Address   string        // How to reach the launched process ("host:port").
	Status    ProcessStatus // Initial status.
}

type ProcessStatus string

type ResourceSpec struct {
	CPUs  float64
	MemMB int
}

type SandboxCapabilities struct {
	Snapshots           bool
	Rollback            bool
	Pause               bool
	LaunchProcess       bool
	DeepPause           bool          // ZFS-to-S3 style cold storage (future).
	ConcurrentSandboxes int           // Max concurrent sandbox instances (0 = unlimited).
	MaxSandboxDuration  time.Duration // Max sandbox lifetime (0 = unlimited).
}

type SandboxControl interface {
	// CreateSandbox provisions a new sandbox environment.
	CreateSandbox(ctx context.Context, req CreateSandboxRequest) (*CreateSandboxResponse, error)

	// DestroySandbox tears down a sandbox and releases all resources.
	DestroySandbox(ctx context.Context, sandboxID string) error

	// LaunchProcess starts a long-running process inside an existing sandbox.
	// Returns connectivity info (address, port) for the launched process.
	LaunchProcess(ctx context.Context, req LaunchProcessRequest) (*LaunchProcessResponse, error)

	// KillProcess terminates a previously launched process.
	KillProcess(ctx context.Context, req KillProcessRequest) error

	// GetProcessStatus returns the current status of a launched process.
	GetProcessStatus(ctx context.Context, req GetProcessStatusRequest) (*GetProcessStatusResponse, error)

	// PauseSandbox pauses a sandbox (provider-specific semantics).
	PauseSandbox(ctx context.Context, sandboxID string) error

	// ResumeSandbox resumes a paused sandbox.
	ResumeSandbox(ctx context.Context, sandboxID string) error

	// Capabilities returns what this provider supports.
	Capabilities() SandboxCapabilities
}