isolate

package
v0.6.8 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

Package isolate is the workerd engine wrapper for the V8-isolate runtime (plans/isolate-runtime.md §7, the analog of pkg/wasm for WASM). It owns one workerd process per isolate group: it generates the group's capnp config and the controller worker, spawns and supervises the process, and drives per-sandbox dynamic isolate loading through the controller.

Architecture (validated by the §2.2 spike): each group process runs a CONTROLLER worker with a `workerLoader` binding. Sandbox traffic arrives at the controller keyed by the x-sb-id header (the driver sets it; clients cannot forge it because the driver's proxy owns the socket). The controller calls env.LOADER.get(id#slot, provider); on a cache miss the provider fetches the sandbox's bundle from the HOST service binding — a tiny bundle-server the Go host serves over a unix socket — so the driver never has to restart the process or push code through workerd's config. Loaded isolates are cached by id and egress slot (the warm path: ~0.3ms) and auto-evicted when idle; a re-fetch on the next request transparently reloads.

Index

Constants

View Source
const (
	DenyReasonHostNotAllowed = "host_not_allowed"
	DenyReasonIPNotAllowed   = "ip_not_allowed"
	DenyReasonBlockedIP      = "blocked_ip"
	DenyReasonBadRequest     = "bad_request"
	// DenyReasonRuleDenied: a ruled host's request matched no rule (P3-1).
	DenyReasonRuleDenied = "rule_denied"
	// DenyReasonPathNotCanonical: a ruled host's path could be read two ways.
	DenyReasonPathNotCanonical = "path_not_canonical"
	// DenyReasonSecretMissing: an inject rule's value never reached the host.
	DenyReasonSecretMissing = "secret_missing"
)

Denial reasons, shared with the gateway's vocabulary.

View Source
const (
	SeccompEnforce = "enforce"
	SeccompAudit   = "audit"
	SeccompOff     = "off"
)

Seccomp modes.

View Source
const (
	// DefaultCgroupRoot is the daemon's parent cgroup for isolate groups.
	DefaultCgroupRoot = "/sys/fs/cgroup/aerolvm-isolate"
)
View Source
const JailRunDirName = "run"

JailRunDirName is the group's writable run directory inside its chroot (sockets, generated config). The supervisor places the host-side RunDir at ChrootDir/JailRunDirName so both sides name the same inodes.

View Source
const JailShimFlag = "--isolate-jail-exec"

JailShimFlag is the daemon subcommand that runs the shim.

View Source
const JailWorkerdPath = "/workerd"

JailWorkerdPath is where the workerd binary lives inside every group chroot.

Variables

This section is empty.

Functions

func EgressDialGuard added in v0.6.6

func EgressDialGuard() egresspolicy.DialGuard

EgressDialGuard returns the guard isolate egress dials with now.

func JailBasePrepared added in v0.6.1

func JailBasePrepared(chrootBase string) bool

JailBasePrepared reports whether PrepareJailBase has produced a usable tree under chrootBase.

func JailRealizable

func JailRealizable() bool

JailRealizable is the exported platform-capability check the daemon logs at boot so operators can see whether SB_ISOLATE_USE_JAIL can actually be honored on this host (Linux) or whether isolate creates will fail closed until it is disabled or the host is Linux.

func PrepareJailBase added in v0.6.1

func PrepareJailBase(chrootBase, workerdPath string) error

PrepareJailBase builds <chrootBase>/.base for the workerd binary at workerdPath. Idempotent: an existing tree is rebuilt in place so an upgraded binary or a changed library set takes effect on the next spawn. Must run before any jailed spawn; the daemon calls it at start when SB_ISOLATE_USE_JAIL is on and fails boot on error.

func RunJailShim added in v0.6.1

func RunJailShim(args []string) error

RunJailShim is the child half of the jail: sandboxd re-exec'd as `sandboxd --isolate-jail-exec` with the spec in SB_ISOLATE_JAIL_SPEC. It runs as root inside the group's cgroup (the parent cloned it there) and, in this order, chroots, changes into the run dir, drops every privilege, forbids regaining any, installs the seccomp filter, and execs workerd. The order matters: chroot needs root; the filter must be in place before execve so the dynamic loader already runs under it; and no_new_privs must precede seccomp for an unprivileged process (we are root by then anyway, but the kernel requires it and it is what makes the filter inescapable).

Every failure is fatal and reported on stderr with a distinct exit code so the parent's "workerd exited during startup" has a cause next to it.

func SetEgressDialGuard added in v0.6.6

func SetEgressDialGuard(g egresspolicy.DialGuard)

SetEgressDialGuard installs the operator's guard for every isolate host in this process. Strict is forced on: the operator can widen isolate only through ZoneInStrict.

func SetEgressUpstream added in v0.6.6

func SetEgressUpstream(up *egresspolicy.Upstream)

SetEgressUpstream installs (nil: removes) the upstream proxy every isolate host's egress goes through for names it proxies.

Types

type EgressDenialObserver added in v0.6.6

type EgressDenialObserver func(sandboxID, destination, reason string)

EgressDenialObserver receives each refused egress request with the shared denial reason (plans/egress-domain-filtering.md H5, P1-7), so isolate denials land in the same audit log and counters as the gateway's. Called synchronously on the request path: it must not block.

type EgressObserver added in v0.6.1

type EgressObserver func(sandboxID, network, destination string)

EgressObserver is notified when a sandbox is allowed to contact a destination through the host egress proxy. Must be non-blocking. Destination is host or host:port — never credentials.

type EgressPolicy

type EgressPolicy struct {
	BlockAll bool
	Allow    []string
	Deny     []string
	// Learn selects learn mode (P2-7): open egress, each destination
	// reported to the learn observer.
	Learn bool
	// Rules are method and path rules (P3-1). The host proxies plaintext
	// requests itself, so it checks them without terminating any TLS.
	Rules []egresspolicy.RuleSpec
	// Secrets are inject rules' values by env key (P3-2), memory only.
	Secrets map[string]string
}

EgressPolicy is the per-sandbox outbound policy enforced by the host-side egress proxy (plans/isolate-runtime.md §4 Phase 3). Mirrored from the driver-level type so pkg/isolate does not import the runtime package. The lists use the shared pkg/egresspolicy grammar and its allow-wins precedence (plans/egress-domain-filtering.md D4, D15), the same as every other runtime.

type Host

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

Host owns one workerd process for an isolate group and the Go-side bundle-server the controller fetches bundles from. It is safe for concurrent use: Load/Unload/Invoke may race with each other.

func NewHost

func NewHost(cfg HostConfig) (*Host, error)

NewHost prepares (does not start) a group host.

func (*Host) ApplyCaps added in v0.6.1

func (h *Host) ApplyCaps(cpu float64, memMB int, pidsMax int) error

ApplyCaps changes the group's cgroup caps while it runs: a warm blank host starts unlimited and takes the claiming tenant's caps here. No-op when the host is not jailed (there is no cgroup to write).

func (*Host) Invoke

func (h *Host) Invoke(ctx context.Context, id string, r *http.Request) (*http.Response, error)

Invoke proxies an HTTP request to the sandbox identified by id. The caller's request is forwarded verbatim except that x-sb-id is (re)set to id so the controller routes it; the isolate never sees the control header.

func (*Host) Load

func (h *Host) Load(id string, b *jsbundle.Bundle) error

Load pins a sandbox's bundle so the controller's provider can fetch it on the next request for that id. Idempotent: re-loading the same id replaces the pin. Loading does not itself spawn an isolate — the first Invoke does, on a loader cache miss.

func (*Host) LoadedCount

func (h *Host) LoadedCount() int

LoadedCount is the number of sandboxes currently pinned on this host.

func (*Host) SetEgressDenialObserver added in v0.6.6

func (h *Host) SetEgressDenialObserver(obs EgressDenialObserver)

SetEgressDenialObserver installs (or clears) the denial audit callback.

func (*Host) SetEgressObserver added in v0.6.1

func (h *Host) SetEgressObserver(obs EgressObserver)

SetEgressObserver installs (or clears) the async egress attribution callback.

func (*Host) SetEgressPolicy

func (h *Host) SetEgressPolicy(id string, raw EgressPolicy)

SetEgressPolicy registers (or replaces) the outbound policy for a sandbox and (re)assigns its egress slot (§4). A non-block-all policy claims a free slot and lazily binds that slot's listener; block-all releases any slot so the sandbox binds EGRESS_DENY. Until a policy is set — or when the pool is exhausted — the sandbox has no slot and its egress is denied (fail-closed). Called after Load; Unload clears both policy and slot.

Creates validate the lists first (internal/service), so a policy that does not compile here is a stored row from before the shared grammar (for example a hostname in Deny, D15). It is enforced as block-all rather than guessed at: fail closed, never open.

func (*Host) SetLearnObserver added in v0.6.6

func (h *Host) SetLearnObserver(obs LearnObserver)

SetLearnObserver installs (or clears) the learn-mode recording callback.

func (*Host) Start

func (h *Host) Start(ctx context.Context) error

Start generates the group's config + controller, starts the bundle-server and the Phase-3 attributed egress server on their unix sockets, spawns workerd, and waits until the control socket answers.

func (*Host) Stop

func (h *Host) Stop() error

Stop kills the workerd process and tears down the host servers. Idempotent.

func (*Host) Unload

func (h *Host) Unload(id string) int

Unload drops a sandbox's bundle pin. A subsequent request for that id fails the provider's fetch (404) and the controller returns 502 — the sandbox is gone. Returns the number of bundles still pinned (the group's live-member count, for last-member teardown).

type HostConfig

type HostConfig struct {
	// WorkerdPath is the workerd binary.
	WorkerdPath string
	// GroupKey is the isolate-group key (§2.1); also the workerLoader cache id.
	GroupKey string
	// RunDir is the group's private run directory (sockets + generated config).
	RunDir string
	// StartTimeout bounds the spawn→ready wait. Zero → 10s.
	StartTimeout time.Duration
	// Jail is the OS confinement for the workerd process. When Jail.Require is
	// true, Start applies it before exec and FAILS CLOSED if it cannot be
	// realized on this platform — the group never runs unconfined.
	Jail JailConfig
	// EgressPoolSize is the number of per-slot egress services pre-declared in
	// the group config (§4). Caps concurrently-egressing sandboxes; zero →
	// defaultEgressPoolSize.
	EgressPoolSize int
	// Logger records egress pool-exhaustion spill (no silent caps). Nil →
	// slog.Default().
	Logger *slog.Logger
}

HostConfig configures one workerd group host.

type JailConfig

type JailConfig struct {
	Require       bool
	ChrootDir     string
	UID           int
	GID           int
	CgroupRoot    string
	CgroupName    string
	CPUQuota      float64
	MemoryLimitMB int
	// PidsMax bounds pids.max on the group cgroup. clone/clone3 are in the
	// seccomp allowlist (pthread_create needs them) and every thread takes a
	// PID, so without this one group can exhaust the host PID space and stop
	// every other tenant from creating processes. Zero = unlimited, which is
	// only for a warm blank host that has not been claimed yet.
	PidsMax int
	Jitless bool
	// SeccompMode is one of SeccompEnforce (unlisted syscalls kill the
	// process), SeccompAudit (unlisted syscalls are logged by the kernel and
	// allowed — for the first real-host run against a new workerd build) or
	// SeccompOff (no filter; only for isolating a suspected filter fault).
	SeccompMode string
	// SeccompAllow are syscall names the group process may make;
	// SeccompArgRules narrow some of them by argument. Names unknown to the
	// running architecture are skipped (they cannot be invoked there).
	SeccompAllow    []string
	SeccompArgRules []SeccompArgRule
	// ShimPath is the daemon binary re-exec'd as the jail shim.
	ShimPath string
}

JailConfig is the OS-confinement request for a group's workerd process. It is projected from the driver's JailSpec (internal/runtime/isolate/jail.go, which this package cannot import), carrying only the primitives the spawner applies.

Require=true is load-bearing for SECURITY, not a hint: when set, Start MUST either realize the confinement or refuse to spawn. It must never run workerd unconfined while Require is true — that is the false-confinement bug this gate exists to prevent (an operator sets SB_ISOLATE_USE_JAIL=true and believes untrusted tenant JS is boxed in). See applyJail / jailRealizable.

What "realized" means on Linux (host_jail_linux.go, shim_linux.go):

  • chroot into ChrootDir, a per-group directory hard-linked from the base tree PrepareJailBase built at daemon start (workerd + its shared libs + /dev nodes), with the group's run dir the only writable place;
  • cgroup v2 under CgroupRoot/CgroupName with cpu.max / memory.max from the group's caps (the tenant's blast radius);
  • privilege drop to UID/GID with no supplementary groups;
  • PR_SET_NO_NEW_PRIVS and a seccomp allowlist (SeccompAllow + SeccompArgRules) installed before workerd is exec'd, so the dynamic loader itself already runs under the filter.

The last two cannot be expressed through os/exec's SysProcAttr, so the spawner execs the daemon binary itself (ShimPath) in a tiny mode that performs them and then execs workerd — the same re-exec shape as --wasm-worker.

type LearnObserver added in v0.6.6

type LearnObserver func(sandboxID, host string, port uint16)

LearnObserver is told each destination a learn-mode sandbox reached. The driver owns the recordings, so they outlive a reaped group.

type SeccompArgMask added in v0.6.1

type SeccompArgMask struct {
	Arg  int
	Mask uint32
}

SeccompArgMask is one argument test: (args[Arg] & Mask) != 0.

type SeccompArgRule added in v0.6.1

type SeccompArgRule struct {
	Syscall   string
	DenyIfAll []SeccompArgMask
}

SeccompArgRule denies Syscall when every mask in DenyIfAll is non-zero on the call's arguments and allows it otherwise. It is how --jitless keeps mprotect (the loader's RELRO needs it) while refusing PROT_EXEC flips.

Jump to

Keyboard shortcuts

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