web

Documentation

Overview

Package web installs the WinterTC (minimum common Web API) vocabulary on a go-spidermonkey interpreter: console, TextEncoder/TextDecoder, atob/btoa, URL/URLSearchParams, AbortController, queueMicrotask, structuredClone, performance.now, crypto.getRandomValues/randomUUID, ReadableStream, fetch, and setTimeout/setInterval.

Registration is explicit:

js, _ := spidermonkey.New(cfg)
w, err := web.Install(js)
...
js.Eval(ctx, script)   // script may set timers, fetch, ...
w.Wait(ctx)            // run the event loop until all timers/ops settle

Network access from fetch is gated by the interpreter's Config: Resolve is consulted per hostname lookup and Dial per outbound connection. Console output goes to Config.Stdout/Stderr.

Index

• type Web
  • func Install(js *spidermonkey.JS) (*Web, error)
  • func (w *Web) Close() error
  • func (w *Web) Loop() *eventloop.Loop
  • func (w *Web) ResetKeys()
  • func (w *Web) ResetPerRequest()
  • func (w *Web) Wait(ctx context.Context) error

Types

type Web

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

Web is one installation of the web vocabulary on one interpreter.

func Install

func Install(js *spidermonkey.JS) (*Web, error)

Install defines the web globals on js and returns the handle that drives the event loop (Wait) and cleanup (Close). Install once per interpreter.

func (*Web) Close

func (w *Web) Close() error

Close releases host resources held by the installation (open fetch bodies, cached engine handles). The interpreter itself stays usable.

func (*Web) Loop

func (w *Web) Loop() *eventloop.Loop

Loop exposes the installation's event loop so sibling compat packages (compat/nodejs) can extend it — schedule immediates, replace the microtask drain. The type lives in an internal package; external callers use Wait.

func (*Web) ResetKeys

func (w *Web) ResetKeys()

ResetKeys drops the whole SubtleCrypto key table. A host that wants strict per-request key isolation on a pooled instance can call this between requests so one request's key material can't be addressed — via a forged globalThis.CryptoKey carrying its handle — by a later one. The cfworkers pool deliberately does NOT call this: real Cloudflare Workers preserve module globals (including imported CryptoKeys) across requests on a warm isolate, so the "import once, cache the key" pattern must keep working there; the random unguessable handle is the anti-forgery boundary within that single trust domain. AES/ECDH/HKDF/PBKDF2 material already survives (guest-side WeakMaps), so persisting the host table too just makes all algorithms consistent.

func (*Web) ResetPerRequest

func (w *Web) ResetPerRequest()

ResetPerRequest drops per-request host state that must not leak across pooled instance reuse (cfworkers): leftover timers/immediates and in-flight async fetches. It deliberately does NOT clear the SubtleCrypto key table — see ResetKeys for why keys persist across requests. Call alongside Loop().Reset() between requests.

func (*Web) Wait

func (w *Web) Wait(ctx context.Context) error

Wait runs the event loop until every timer has fired (or been cleared) and every in-flight op has completed, or ctx is done. A JS exception thrown by a timer callback stops the loop and is returned. Call it after evaluating code that schedules async work.