runtime

package
v0.6.1 Latest Latest
Warning

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

Go to latest
Published: Oct 1, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package runtime defines the abstraction the service layer uses to drive a sandbox container, regardless of which OCI runtime executes it. The first implementation is pkg/docker.Client, which talks to the local Docker daemon and can drive either runc or runsc (gVisor) depending on per-sandbox / host-default selection. Future implementations (e.g. native runsc without Docker, Firecracker, WASM) plug in behind the same interface.

Methods that are intrinsically Docker-API-shaped — exec hijacking, the /events stream — intentionally stay off this interface and on the concrete *docker.Client. Pulling them through the abstraction would only buy clutter; gVisor under Docker uses the same exec/event paths anyway.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ContainerRuntime added in v0.5.3

type ContainerRuntime interface {
	Runtime

	// PushAllowedPorts updates the in-container toolbox's allowlist of ports
	// reachable through its proxy. Best-effort; callers log on failure.
	PushAllowedPorts(ctx context.Context, containerIP, toolboxToken string, ports []int) error

	// ClearNetworkRules releases any per-IP network rules previously attached
	// to a sandbox. Used by the event-driven path when a container exits or
	// is destroyed out-of-band; Destroy() handles this during normal teardown.
	ClearNetworkRules(containerIP string) error

	// ApplyNetworkBlockAll installs the per-IP egress DROP rule for sandboxes
	// created with NetworkBlockAll=true. Idempotent — safe to call on every
	// Start and reconcile pass. Used to reapply the rule after Stop+Start
	// cycles (which clear it on the stop event) and after host-side state
	// loss (iptables flush, daemon restart that rebuilds chains).
	ApplyNetworkBlockAll(containerIP string) error

	// ApplyNetworkBlockIngress installs the per-IP ingress DROP rule. Used
	// by the network-quota enforcer when net_bytes_in_limit is crossed.
	// Idempotent at the netrules layer. Distinct from the egress block so
	// quota enforcement composes with NetworkBlockAll independently on each
	// direction.
	ApplyNetworkBlockIngress(containerIP string) error

	// ClearNetworkBlockIngress removes the per-IP ingress DROP rule. The
	// caller is responsible for not racing this against quota state — the
	// service layer only clears when limits are raised above current usage.
	ClearNetworkBlockIngress(containerIP string) error

	// ClearNetworkBlockEgress removes the per-IP egress DROP rule. Symmetric
	// to ApplyNetworkBlockAll for callers that need to walk back a quota-
	// driven block without also undoing NetworkBlockAll. Today the underlying
	// rule is shared, so the service must consult NetworkBlockAll before
	// invoking this on a quota-clear path.
	ClearNetworkBlockEgress(containerIP string) error

	// ApplyEgressPolicy installs the selective-egress CIDR policy (E2B
	// network.allowOut / denyOut). At most one of allowCIDRs / denyCIDRs is
	// non-empty. Comment-tagged so it composes with, rather than collides
	// with, the NetworkBlockAll / quota DROP. Idempotent — reapplied on Start
	// and reconcile just like ApplyNetworkBlockAll.
	ApplyEgressPolicy(containerIP string, allowCIDRs, denyCIDRs []string) error

	// ClearEgressPolicy removes the rules ApplyEgressPolicy installed for the
	// same (containerIP, allowCIDRs, denyCIDRs). Callers pass the policy from
	// the sandbox row so cleanup is exact and the blanket DROP is untouched.
	ClearEgressPolicy(containerIP string, allowCIDRs, denyCIDRs []string) error
}

ContainerRuntime extends Runtime with per-IP network rules and the in-container toolbox port allowlist. Docker and Firecracker satisfy both; WASM satisfies only Runtime and uses host-mediated sockets instead.

func AsContainerRuntime added in v0.5.3

func AsContainerRuntime(rt Runtime) (ContainerRuntime, bool)

AsContainerRuntime returns the network-rule surface when rt implements it. WASM and other host-mediated runtimes return false.

type NetworkBlockReporter added in v0.5.6

type NetworkBlockReporter interface {
	ApplyNetworkBlockAllReport(containerIP string) (inserted bool, err error)
}

NetworkBlockReporter is the reporting variant of ContainerRuntime.ApplyNetworkBlockAll: same install, but it also says whether the rule was actually missing. Kept as a separate optional interface rather than widening ApplyNetworkBlockAll's signature so drivers that can't answer the question (Firecracker, which doesn't implement per-IP rules at all) stay untouched.

Only reconcile needs the answer — it reapplies on every pass, so the raw call count is a constant, not a drift signal.

func AsNetworkBlockReporter added in v0.5.6

func AsNetworkBlockReporter(cr ContainerRuntime) (NetworkBlockReporter, bool)

AsNetworkBlockReporter returns the reporting surface when cr implements it. Callers must fall back to plain ApplyNetworkBlockAll when this returns false — the healing behavior is mandatory, the metric is not.

type Runtime

type Runtime interface {
	// Create provisions and starts a managed container. The caller owns the
	// sandbox ID. The runtime sets it as the container's canonical name so
	// the sandbox ID is the end-to-end identifier (the container ID is an
	// internal detail). The chosen OCI runtime is read from
	// req.Runtime; the implementation is expected to substitute its own
	// default when req.Runtime is empty.
	Create(ctx context.Context, req models.CreateSandboxRequest, sandboxID, toolboxToken string, hostMounts []mounts.ContainerBind) (*models.SandboxRuntimeState, error)

	// Start boots a previously created container and waits for the in-container
	// toolbox to become reachable.
	Start(ctx context.Context, containerRef string) (*models.SandboxRuntimeState, error)

	// Stop sends a graceful stop with a default timeout.
	Stop(ctx context.Context, containerRef string) error

	// Destroy removes the container and clears any per-IP network rules.
	// Passing nil is a no-op — convenient for cleanup paths that may not yet
	// have a sandbox record.
	Destroy(ctx context.Context, sandbox *models.Sandbox) error

	// CreateSnapshot commits a managed container into a reusable local image
	// reference and returns the resulting image ID.
	CreateSnapshot(ctx context.Context, containerRef, imageRef string) (string, error)

	// Resize updates CPU/memory caps on a running container. DiskGB is not
	// resizable on a live container; resize-up at create time is honored
	// per-runtime.
	Resize(ctx context.Context, containerRef string, req models.ResizeSandboxRequest) error

	// Inspect returns the current runtime state for a single container.
	Inspect(ctx context.Context, containerRef string) (*models.SandboxRuntimeState, error)

	// ListManaged returns the runtime state of every container managed by
	// this sandboxd, keyed by sandbox ID. Used by reconcile.
	ListManaged(ctx context.Context) (map[string]*models.SandboxRuntimeState, error)

	// Ping verifies the underlying runtime daemon is reachable.
	Ping(ctx context.Context) error

	// RemoveImage GCs an image from the runtime's local store. 404/409 are
	// treated as success — see implementation notes.
	RemoveImage(ctx context.Context, imageRef string) error
}

Runtime is the core contract the service layer requires of any sandbox runtime driver. Implementations must be safe for concurrent use; the service serializes per-sandbox operations but issues calls for different sandboxes in parallel.

Network-rule methods (per-IP iptables, in-container toolbox allowlists) live on ContainerRuntime instead — WASM satisfies only Runtime (see plans/wasm-runtime.md D17).

Directories

Path Synopsis
Package firecracker is the native Firecracker runtime driver.
Package firecracker is the native Firecracker runtime driver.
Package isolate is the V8-isolate (Workers-model) runtime driver — the fifth implementation of internal/runtime.Runtime, after pkg/docker (docker + gvisor), internal/runtime/firecracker, and internal/runtime/wasm (plans/isolate-runtime.md).
Package isolate is the V8-isolate (Workers-model) runtime driver — the fifth implementation of internal/runtime.Runtime, after pkg/docker (docker + gvisor), internal/runtime/firecracker, and internal/runtime/wasm (plans/isolate-runtime.md).
Package wasm is the WASM/WASI runtime driver — the third implementation of internal/runtime.Runtime (after pkg/docker and internal/runtime/firecracker).
Package wasm is the WASM/WASI runtime driver — the third implementation of internal/runtime.Runtime (after pkg/docker and internal/runtime/firecracker).
statekv
Package statekv implements the host KV capability for durable WASM sandboxes (plans/wasm-runtime.md §4.6).
Package statekv implements the host KV capability for durable WASM sandboxes (plans/wasm-runtime.md §4.6).
toolhost
Package toolhost implements the host-side toolbox for WASM sandboxes (plans/wasm-runtime.md §3).
Package toolhost implements the host-side toolbox for WASM sandboxes (plans/wasm-runtime.md §3).

Jump to

Keyboard shortcuts

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