worker

package
v0.7.23 Latest Latest
Warning

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

 Go to latest Published: Jul 23, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package worker implements the WASM worker-subprocess pool (plans/wasm-runtime.md §2.1). Phase 1 lands length-prefixed JSON framing; CBOR encoding can replace the codec without changing the message types.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultResidentSpawner added in v0.7.10 

func DefaultResidentSpawner(ctx context.Context, socketPath string) (*exec.Cmd, error)

DefaultResidentSpawner runs the current executable as a resident-module host (--wasm-resident-host → RunCLIResident): one process compiles a module once and hosts many isolated sandbox instances. Used by the driver's resident-host supervisor when SB_WASM_RESIDENT_HOST_ENABLED is set.

func DefaultSpawner 

func DefaultSpawner(ctx context.Context, socketPath string) (*exec.Cmd, error)

DefaultSpawner runs the current executable in worker mode. Requires main to delegate --wasm-worker to worker.RunCLI (wired from cmd/sandboxd in Phase 1).

func ReadyPollSleep added in v0.5.5 

func ReadyPollSleep(ctx context.Context, attempt int)

ReadyPollSleep waits before the next worker readiness ping. attempt 0 is a no-op (first ping fires immediately); subsequent attempts use 2ms doubling to a 25ms cap (plans/wasm-create-latency.md Phase 4).

func RunCLI 

func RunCLI(args []string) error

RunCLI is the `--wasm-worker <socket>` entrypoint shared by sandboxd and tests.

func RunCLIResident added in v0.7.10 

func RunCLIResident(args []string) error

RunCLIResident is the `--wasm-resident-host <socket>` entrypoint.

func ServeSocketPath 

func ServeSocketPath(socketPath string) error

ServeSocketPath listens on a Unix domain socket and serves each connection concurrently.

func ServeSocketPathResident added in v0.7.10 

func ServeSocketPathResident(socketPath string) error

ServeSocketPathResident listens on a Unix socket and serves each connection with a shared ResidentServer (one MultiInstanceEngine per process).

Types

type Client 

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

Client talks to one worker over a Unix domain socket.

func NewClient 

func NewClient(socketPath string) *Client

NewClient dials socketPath for each request.

func (*Client) Checkpoint 

func (c *Client) Checkpoint(ctx context.Context, sandboxID, outDir string, meta wasmengine.SnapshotConfig) error

Checkpoint writes a mem.snap artifact to outDir.

func (*Client) Exec 

func (c *Client) Exec(sandboxID string, caps wasmengine.Capabilities, export string) (wasmengine.RunResult, error)

Exec re-instantiates with caps, invokes export, and returns captured IO.

func (*Client) InstanceLoaded 

func (c *Client) InstanceLoaded(ctx context.Context, sandboxID string) (bool, error)

InstanceLoaded reports whether the worker currently has an engine/module loaded.

func (*Client) Instantiate 

func (c *Client) Instantiate(sandboxID string, caps wasmengine.Capabilities) error

Instantiate creates a WASI instance with the given capabilities.

func (*Client) Invoke 

func (c *Client) Invoke(sandboxID, export string) error

Invoke calls an exported function (defaults to _start).

func (*Client) LoadModule 

func (c *Client) LoadModule(sandboxID, path string, memoryMB int) (wasmengine.LoadTimings, error)

LoadModule compiles the module at path inside the worker process and returns the sub-stage timing breakdown (best-effort; zero-valued if the worker did not report it) so the host create path can emit wasm_load Server-Timing subs.

func (*Client) NetstatsTick 

func (c *Client) NetstatsTick(sandboxID string) (bytesIn, bytesOut int64, err error)

NetstatsTick drains worker-side byte counters since the last poll (UC-43).

func (*Client) Ping 

func (c *Client) Ping(sandboxID string) error

Ping verifies the worker responds to HealthPing.

func (*Client) ProxyHTTP 

func (c *Client) ProxyHTTP(sandboxID string, guestPort int, w http.ResponseWriter, r *http.Request) error

ProxyHTTP forwards one HTTP request to the guest wasip1 listener inside the worker.

func (*Client) ResolvedListenPort 

func (c *Client) ResolvedListenPort(sandboxID string) (int, error)

ResolvedListenPort returns the host port for the active wasip1 listener (after ephemeral bind).

func (*Client) Restore 

func (c *Client) Restore(sandboxID, dir string, caps wasmengine.Capabilities) error

Restore loads a mem.snap artifact from dir into the active worker engine.

func (*Client) SetCapability 

func (c *Client) SetCapability(sandboxID string, caps wasmengine.Capabilities) error

SetCapability hot-updates memory/wall-timeout caps on a running instance.

func (*Client) SetListenPort 

func (c *Client) SetListenPort(sandboxID string, port int, host string) error

SetListenPort hot-updates the wasip1 listener port without touching memory caps.

func (*Client) SetNetworkBlocks 

func (c *Client) SetNetworkBlocks(sandboxID string, blockIngress, blockEgress bool) error

SetNetworkBlocks applies quota blocks at the worker-side socket mediator (UC-43).

func (*Client) StopInstance 

func (c *Client) StopInstance(sandboxID string) error

StopInstance tears down the active instance inside the worker.

func (*Client) TriggerPanic 

func (c *Client) TriggerPanic(sandboxID string) error

TriggerPanic sends the test-only panic message. The worker process is expected to exit.

type Envelope 

type Envelope struct {
	Type      MessageType `json:"type"`
	SandboxID string      `json:"sandbox_id,omitempty"`
	Payload   []byte      `json:"payload,omitempty"`
}

Envelope is the on-wire message body (after the length prefix).

type MessageType 

type MessageType string

MessageType identifies a worker control-plane message. 

const (
	MsgHealthPing       MessageType = "health_ping"
	MsgPong             MessageType = "pong"
	MsgInstanceStatus   MessageType = "instance_status"
	MsgTriggerPanic     MessageType = "trigger_panic" // test-only: verifies crash isolation (D10)
	MsgLoadModule       MessageType = "load_module"
	MsgInstantiate      MessageType = "instantiate"
	MsgInvoke           MessageType = "invoke"
	MsgExec             MessageType = "exec"
	MsgStopInstance     MessageType = "stop_instance"
	MsgOK               MessageType = "ok"
	MsgError            MessageType = "error"
	MsgInvokeResult     MessageType = "invoke_result"
	MsgCheckpoint       MessageType = "checkpoint"
	MsgRestore          MessageType = "restore"
	MsgSetCapability    MessageType = "set_capability"
	MsgNetstatsTick     MessageType = "netstats_tick"
	MsgSetNetworkBlocks MessageType = "set_network_blocks"
	MsgSetListenPort    MessageType = "set_listen_port"
	MsgListenPort       MessageType = "listen_port"
	MsgProxyHTTP        MessageType = "proxy_http"
	MsgProxyHTTPResult  MessageType = "proxy_http_result"
)

type NetMediator 

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

NetMediator is the host-mediated TCP egress surface for UC-43. Guest WASI sockets (when wired) and host-side proxies dial through here so bytes and quota blocks are observable per sandbox.

func (*NetMediator) Copy 

func (m *NetMediator) Copy(sandboxID string, dst io.Writer, src io.Reader, outbound bool) (int64, error)

Copy counts bytes moved through the mediator for tests and host proxies.

func (*NetMediator) DialContext 

func (m *NetMediator) DialContext(ctx context.Context, sandboxID, network, address string) (net.Conn, error)

DialContext dials address when egress is allowed and counts bytes in/out.

func (*NetMediator) DrainUsage 

func (m *NetMediator) DrainUsage(sandboxID string) (in, out int64)

DrainUsage returns and clears accumulated socket bytes for sandboxID.

func (*NetMediator) SetBlocks 

func (m *NetMediator) SetBlocks(sandboxID string, blockIngress, blockEgress bool)

type ResidentServer added in v0.7.10 

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

ResidentServer serves the worker protocol backed by a MultiInstanceEngine: one resident process compiles a module once and hosts many isolated sandbox instances (compile-once, instantiate-many). Spawned via `--wasm-resident-host`.

Phase 2b PR-A: per-instance egress via MultiInstanceEngine.SetNetworkHook (name-keyed hooks + conn ownership) and a shared NetMediator. Listener (expose_port/HTTP) and checkpoint/restore remain rejected — those stay on the per-sandbox cold path (migrate-on-expose is PR-B).

func (*ResidentServer) Serve added in v0.7.10 

func (s *ResidentServer) Serve(conn net.Conn) error

Serve accepts framed control messages on conn until EOF or an unrecoverable error. Multiple connections may be served concurrently; the MultiInstanceEngine is internally synchronized.

type Server 

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

Server holds one wazero engine per worker process (D11: one module per worker).

func (*Server) Serve 

func (s *Server) Serve(conn net.Conn) error

Serve accepts framed control messages on conn until EOF or an unrecoverable error.

type Slot 

type Slot struct {
	SandboxID  string
	SocketPath string
	// contains filtered or unexported fields
}

Slot tracks one sandbox worker subprocess.

type Spawner 

type Spawner func(ctx context.Context, socketPath string) (*exec.Cmd, error)

Spawner starts a worker subprocess bound to socketPath. Production wiring uses `sandboxd --wasm-worker <socket>`; tests inject a subprocess of this test binary.

type Supervisor 

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

Supervisor owns worker subprocesses for WASM sandboxes. A worker crash kills only that subprocess; the supervisor respawns the slot while sandboxd keeps running.

func NewSupervisor 

func NewSupervisor(spawn Spawner) *Supervisor

NewSupervisor constructs a supervisor. spawn must be non-nil.

func (*Supervisor) Ensure 

func (s *Supervisor) Ensure(ctx context.Context, sandboxID, socketPath string) error

Ensure starts (or restarts) the worker for sandboxID at socketPath.

func (*Supervisor) SpawnCount 

func (s *Supervisor) SpawnCount(sandboxID string) int

SpawnCount returns how many times the worker for sandboxID has been started.

func (*Supervisor) Stop 

func (s *Supervisor) Stop(sandboxID string) error

Stop terminates the worker for sandboxID.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.