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, 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 (the warm path: ~0.3ms) and auto-evicted when idle; a re-fetch on the next request transparently reloads.
Index ¶
- func JailRealizable() bool
- type EgressPolicy
- type Host
- 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) SetEgressPolicy(id string, p EgressPolicy)
- func (h *Host) Start(ctx context.Context) error
- func (h *Host) Stop() error
- func (h *Host) Unload(id string) int
- type HostConfig
- type JailConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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.
Types ¶
type EgressPolicy ¶
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.
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) 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) SetEgressPolicy ¶
func (h *Host) SetEgressPolicy(id string, p 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.
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
CgroupName string
MemoryLimitMB int
Jitless bool
}
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.
Source Files