worker

package
v0.7.21 Latest Latest
Warning

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

 Go to latest Published: Jul 21, 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 

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 

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 

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 

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 

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 

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.