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
- func EgressDialGuard() egresspolicy.DialGuard
- func JailBasePrepared(chrootBase string) bool
- func JailRealizable() bool
- func PrepareJailBase(chrootBase, workerdPath string) error
- func RunJailShim(args []string) error
- func SetEgressDialGuard(g egresspolicy.DialGuard)
- func SetEgressUpstream(up *egresspolicy.Upstream)
- type EgressDenialObserver
- type EgressObserver
- type EgressPolicy
- type Host
- func (h *Host) ApplyCaps(cpu float64, memMB int, pidsMax int) error
- func (h *Host) Invoke(ctx context.Context, id string, r *http.Request) (*http.Response, error)
- func (h *Host) Load(id string, b *jsbundle.Bundle) error
- func (h *Host) LoadedCount() int
- func (h *Host) SetEgressDenialObserver(obs EgressDenialObserver)
- func (h *Host) SetEgressObserver(obs EgressObserver)
- func (h *Host) SetEgressPolicy(id string, raw EgressPolicy)
- func (h *Host) SetLearnObserver(obs LearnObserver)
- func (h *Host) Start(ctx context.Context) error
- func (h *Host) Stop() error
- func (h *Host) Unload(id string) int
- type HostConfig
- type JailConfig
- type LearnObserver
- type SeccompArgMask
- type SeccompArgRule
Constants ¶
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.
const ( SeccompEnforce = "enforce" SeccompAudit = "audit" SeccompOff = "off" )
Seccomp modes.
const (
// DefaultCgroupRoot is the daemon's parent cgroup for isolate groups.
DefaultCgroupRoot = "/sys/fs/cgroup/aerolvm-isolate"
)
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.
const JailShimFlag = "--isolate-jail-exec"
JailShimFlag is the daemon subcommand that runs the shim.
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
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
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
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
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 ¶
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 ¶
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 ¶
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 ¶
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.
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
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
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.