backend

package
v0.1.4 Latest Latest
Warning

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

Go to latest
Published: Jul 8, 2026 License: Apache-2.0 Imports: 36 Imported by: 0

Documentation

Overview

Package backend abstracts the sandbox runtime so callers don't care whether a sandbox is a Docker container or a Kubernetes Pod.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Export

func Export(ctx context.Context, id, destDir string) error

Export copies the workspace of sandbox id to destDir on the host. It's a point-in-time copy; later host edits never flow back into the sandbox.

Types

type Backend

type Backend interface {
	Name() string
	Create(ctx context.Context, spec Spec) (*Sandbox, error)
	Exec(ctx context.Context, id string, req ExecRequest) (*ExecResult, error)
	AttachPTY(ctx context.Context, id string, io PTYStream) error
	CopyFiles(ctx context.Context, id string, files []profile.File) error
	ExportWorkspace(ctx context.Context, id string, w io.Writer) error
	Snapshot(ctx context.Context, id, name string) (*SnapshotRef, error)
	Restore(ctx context.Context, ref SnapshotRef) (*Sandbox, error)
	Kill(ctx context.Context, id string) error
	List(ctx context.Context) ([]Sandbox, error)
}

Backend provisions and controls sandboxes for a given execution host.

func Detect

func Detect(ctx context.Context, id string) (Backend, error)

Detect returns the backend hosting sandbox id, probing Docker then Kubernetes. A backend that can't be constructed (e.g. no kubeconfig) is skipped, not an error.

func For

func For(p *profile.Profile) (Backend, error)

For returns the backend implementing the profile's execution host.

type Docker

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

Docker provisions one container per sandbox. It drives the docker CLI rather than the SDK; the CLI contract is more stable across

func NewDocker

func NewDocker() (*Docker, error)

NewDocker returns a Docker backend, verifying the CLI is present and the engine is actually reachable so misconfig fails fast with a clear message.

func NewPodman

func NewPodman() (*Docker, error)

NewPodman returns a Podman-backed container backend.

func (*Docker) AttachPTY

func (d *Docker) AttachPTY(ctx context.Context, id string, s PTYStream) error

func (*Docker) CopyFiles

func (d *Docker) CopyFiles(ctx context.Context, id string, files []profile.File) error

func (*Docker) Create

func (d *Docker) Create(ctx context.Context, spec Spec) (*Sandbox, error)

func (*Docker) Exec

func (d *Docker) Exec(ctx context.Context, id string, req ExecRequest) (*ExecResult, error)

func (*Docker) ExportWorkspace

func (d *Docker) ExportWorkspace(ctx context.Context, id string, w io.Writer) error

ExportWorkspace streams a tar of the container workdir contents to w.

func (*Docker) Kill

func (d *Docker) Kill(ctx context.Context, id string) error

func (*Docker) List

func (d *Docker) List(ctx context.Context) ([]Sandbox, error)

func (*Docker) Name

func (d *Docker) Name() string

func (*Docker) Restore

func (d *Docker) Restore(ctx context.Context, ref SnapshotRef) (*Sandbox, error)

func (*Docker) RestoreWithSpec

func (d *Docker) RestoreWithSpec(ctx context.Context, ref SnapshotRef, spec Spec) (*Sandbox, error)

func (*Docker) Snapshot

func (d *Docker) Snapshot(ctx context.Context, id, name string) (*SnapshotRef, error)

type ExecRequest

type ExecRequest struct {
	Command []string
	Workdir string
	Env     map[string]string
	Timeout time.Duration
}

ExecRequest is a one-shot command execution.

type ExecResult

type ExecResult struct {
	ExitCode int
	Stdout   string
	Stderr   string
	Duration time.Duration
}

ExecResult captures the outcome of an Exec.

type K8s

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

K8s provisions one Pod (plus a workspace PVC) per sandbox via client-go, managing Pods directly rather than through a controller.

func NewK8s

func NewK8s() (*K8s, error)

NewK8s builds the Kubernetes backend from the ambient kubeconfig. $RUNEWARD_KUBE_CONTEXT pins the context; $RUNEWARD_K8S_NAMESPACE overrides the default "runeward" namespace.

func (*K8s) AttachPTY

func (k *K8s) AttachPTY(ctx context.Context, id string, s PTYStream) error

func (*K8s) CopyFiles

func (k *K8s) CopyFiles(ctx context.Context, id string, files []profile.File) error

func (*K8s) Create

func (k *K8s) Create(ctx context.Context, spec Spec) (*Sandbox, error)

func (*K8s) Exec

func (k *K8s) Exec(ctx context.Context, id string, req ExecRequest) (*ExecResult, error)

func (*K8s) ExportWorkspace

func (k *K8s) ExportWorkspace(ctx context.Context, id string, w io.Writer) error

ExportWorkspace streams a tar of the pod workdir contents to w.

func (*K8s) Kill

func (k *K8s) Kill(ctx context.Context, id string) error

func (*K8s) List

func (k *K8s) List(ctx context.Context) ([]Sandbox, error)

func (*K8s) Name

func (k *K8s) Name() string

func (*K8s) Restore

func (k *K8s) Restore(ctx context.Context, ref SnapshotRef) (*Sandbox, error)

func (*K8s) RestoreWithSpec

func (k *K8s) RestoreWithSpec(ctx context.Context, ref SnapshotRef, spec Spec) (*Sandbox, error)

func (*K8s) Snapshot

func (k *K8s) Snapshot(ctx context.Context, id, name string) (*SnapshotRef, error)

type PTYStream

type PTYStream struct {
	Stdin   io.Reader
	Stdout  io.Writer
	Stderr  io.Writer
	TTY     bool
	Command []string
	Resize  <-chan TermSize
}

PTYStream carries the interactive terminal I/O for AttachPTY.

type Resources

type Resources struct {
	NanoCPUs    int64
	MemoryBytes int64
}

Resources are best-effort resource caps applied to the sandbox.

type Sandbox

type Sandbox struct {
	ID        string
	Profile   string
	Backend   string
	Image     string
	Status    string
	CreatedAt time.Time
	Endpoint  string
}

Sandbox is a handle to a provisioned sandbox.

func RestoreSnapshot

func RestoreSnapshot(ctx context.Context, be Backend, ref SnapshotRef, spec Spec) (*Sandbox, error)

RestoreSnapshot restores a snapshot using the full spec path when supported.

type SnapshotRef

type SnapshotRef struct {
	ID       string    `json:"id"`
	Name     string    `json:"name"`
	Profile  string    `json:"profile"`
	Backend  string    `json:"backend"`
	Location string    `json:"location"`
	Sha256   string    `json:"sha256,omitempty"`
	Created  time.Time `json:"created"`
}

SnapshotRef identifies a captured workspace snapshot.

type Spec

type Spec struct {
	Profile      string
	Image        string
	Workdir      string
	User         string
	Env          map[string]string
	Labels       map[string]string
	Files        []profile.File
	SeedDir      string
	Network      profile.Network
	Resources    Resources
	RuntimeClass string
	// ReadOnly mounts the container root filesystem read-only.
	ReadOnly bool
	// Seccomp is a seccomp profile path (Docker: --security-opt seccomp=;
	// k8s: Localhost profile path). Empty means the backend default.
	Seccomp string
	// AppArmor is an AppArmor profile name.
	AppArmor string
}

Spec is the resolved, backend-agnostic description of a sandbox to create.

func SpecFromProfile

func SpecFromProfile(p *profile.Profile, env map[string]string) Spec

SpecFromProfile derives a backend-agnostic Spec from a resolved profile. Env values are expected to already be resolved to literals by the caller.

type TermSize

type TermSize struct {
	Rows uint16
	Cols uint16
}

TermSize is a terminal window dimension update.

Jump to

Keyboard shortcuts

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