sandbox

type Closer interface {
	Close() error
}

type Factory func(name string, cfg map[string]any) (Sandbox, error)

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

type Request struct {
	// Command is the program to execute. Sandboxes that spawn locally
	// (direct) treat this as a file path; sandboxes that run the command
	// somewhere else (kubectl exec, docker exec) typically pass it
	// verbatim to the remote runner.
	Command string

	// Args are positional arguments passed to Command.
	Args []string

	// Env contains additional environment entries in "KEY=value" form to
	// be merged on top of whatever the sandbox considers baseline. The
	// caller is responsible for resolving any host-side lookups (e.g.
	// os.LookupEnv) before populating this slice.
	Env []string

	// Stdin is the bytes piped to the subprocess's stdin. Typically the
	// exec-hook JSON payload. The sandbox does not retain this slice.
	Stdin []byte

	// Timeout bounds the invocation. Zero means the sandbox's own
	// default; negative is treated as zero.
	Timeout time.Duration
}

type Response struct {
	// Stdout is the bytes read from the subprocess's stdout.
	Stdout []byte
	// Stderr is the bytes read from the subprocess's stderr. Empty when
	// the sandbox cannot separately capture stderr (e.g. a remote
	// transport that conflates the streams); in that case stderr content
	// should be appended to Stdout or included in Err instead.
	Stderr []byte
	// Err is non-nil when the process exited non-zero, the timeout
	// expired, or the transport failed. Callers distinguish these cases
	// with errors.Is against standard sentinels (context.DeadlineExceeded,
	// exec.ExitError) where applicable.
	Err error
}

type Sandbox interface {
	// Name returns a stable identifier used in logs and observability
	// events. Typically matches the mode name or the registered sandbox
	// name from RuntimeConfig.
	Name() string

	// Spawn runs the given command, pipes Stdin to its stdin, collects
	// stdout and stderr, and returns when the process exits, the timeout
	// expires, or the transport fails. A non-zero exit code, a timeout,
	// or a transport error all surface as a non-nil Response.Err —
	// implementations should include enough detail for callers to
	// distinguish those cases (e.g. by wrapping a context.DeadlineExceeded).
	Spawn(ctx context.Context, req Request) (Response, error)
}