sandbox

type Backend interface {
	// Create returns a running sandbox for name, creating it if absent and
	// returning the existing one if present. It is the caller's session-affinity
	// primitive: the same name reaches the same sandbox until it is reaped.
	//
	// Options are applied only when the sandbox is created. Calling Create again
	// with different options on a live sandbox does not reconfigure it.
	Create(ctx context.Context, name string, opts ...CreateOption) (Sandbox, error)

	// Open returns an existing sandbox. It reports ErrNotFound if name has no
	// sandbox, and never creates one.
	Open(ctx context.Context, name string) (Sandbox, error)

	// List returns every sandbox this backend manages, running or stopped.
	List(ctx context.Context) ([]Info, error)

	// Destroy removes a sandbox and its writable layer. It is idempotent:
	// destroying an absent sandbox is not an error.
	Destroy(ctx context.Context, name string) error

	// Close releases the backend's own resources. It does not stop or destroy
	// running sandboxes, which outlive the process that created them.
	Close() error
}

type Command struct {
	// Argv is the program and its arguments. It is executed directly, without a
	// shell, so no quoting or escaping is applied. To use shell syntax, invoke a
	// shell explicitly: []string{"sh", "-c", script}.
	Argv []string
	// Env entries are "KEY=value", merged over the sandbox's environment.
	Env []string
	// Dir is the working directory. Empty means the image's default.
	Dir   string
	Stdin io.Reader
	// Timeout bounds this command. Zero means the backend's default. The backend
	// clamps it to a configured maximum.
	Timeout time.Duration
}

type CreateOption func(*Spec)

type EgressPolicy int

type Info struct {
	// Name is the caller-supplied identity passed to Create.
	Name string
	// ID is the runtime's identifier, for correlating with host-level tooling.
	ID    string
	Image string
	State State

	CreatedAt time.Time
}

type Lifetime struct {
	// IdleTimeout stops a sandbox with no activity for this long.
	IdleTimeout time.Duration
	// MaxAge destroys a sandbox this long after creation regardless of activity.
	// It reaps what the idle sweep misses — a sandbox kept warm by a wedged
	// background process is never idle.
	MaxAge time.Duration
}

type Preview struct {
	URL   string
	Token string
	// Port is echoed back so a caller holding several previews can match them
	// up without tracking the mapping itself.
	Port      int
	ExpiresAt time.Time
}

type Resources struct {
	CPUs        float64
	MemoryBytes int64

	// DiskBytes caps the sandbox's writable scratch space.
	//
	// The root filesystem is read-only, so all writes land on sized tmpfs mounts
	// and this is their combined ceiling. Container-layer quotas
	// (--storage-opt size) are deliberately not used: they require overlay2 on
	// xfs with pquota and hard-fail on the far more common ext4, so relying on
	// them would make the disk bound silently unavailable on most hosts.
	//
	// Because tmpfs is RAM-backed, this budget is drawn from MemoryBytes rather
	// than being independent of it: a sandbox that fills its scratch space has
	// that much less memory for processes. DiskBytes must not exceed
	// MemoryBytes.
	DiskBytes int64

	// MaxProcesses caps the process count. Without it a fork bomb inside the
	// sandbox exhausts host PIDs regardless of CPU and memory limits.
	MaxProcesses int
}

type Result struct {
	Stdout   []byte
	Stderr   []byte
	ExitCode int
}

type Sandbox interface {
	// Info returns a snapshot of the sandbox's identity and state. It does not
	// query the runtime and so cannot fail; use [Backend.Open] for fresh state.
	Info() Info

	// Exec runs a command to completion and returns its output. A non-zero exit
	// status is reported in Result.ExitCode, not as an error — err is non-nil
	// only when the command could not be run or did not finish.
	Exec(ctx context.Context, cmd Command) (Result, error)

	// WriteFile writes src to path inside the sandbox, creating parent
	// directories as needed. It streams, so it is safe for large payloads.
	WriteFile(ctx context.Context, path string, mode fs.FileMode, src io.Reader) error

	// ReadFile opens path inside the sandbox for reading. The caller must close
	// the returned reader.
	ReadFile(ctx context.Context, path string) (io.ReadCloser, error)

	// StartProcess starts cmd as a detached background process under name. It is
	// idempotent: if a process is already running under name, it is left alone
	// and no error is returned.
	StartProcess(ctx context.Context, name string, cmd Command) error

	// Expose returns a signed, expiring URL for a port inside the sandbox.
	//
	// The returned token is a bearer credential and must be sent as a request
	// header, never a query parameter — query strings leak into access logs,
	// browser history, and Referer headers.
	Expose(ctx context.Context, port int, ttl time.Duration) (Preview, error)

	// Revoke invalidates a token returned by Expose before it expires.
	Revoke(ctx context.Context, port int, token string) error

	// Stop halts the sandbox without discarding it. A stopped sandbox can be
	// reached again through [Backend.Create] with the same name.
	Stop(ctx context.Context) error
}

type Spec struct {
	Image     string
	Runtime   string
	User      string
	Resources Resources
	Lifetime  Lifetime
	Egress    EgressPolicy
	Env       []string
	Labels    map[string]string

	// DefaultTimeout applies to commands that set none.
	DefaultTimeout time.Duration
	// MaxTimeout is the ceiling a command may request.
	MaxTimeout time.Duration
}

type State string