Worker & serving

On this page

Building a worker and putting it on a transport.

function buildVgiProtocol

source

export function buildVgiProtocol(config: ProtocolConfig): Protocol

function createLandingRoutes

source

export function createLandingRoutes(info: LandingInfo): ExtraRouteHandler

Description

Build the VGI landing surface as a route contributed to vgi-rpc’s HTTP handler.

Serves two paths, both relative to the handler’s mount prefix:

• GET {prefix}/ — the shared landing.html for browsers, or a JSON status document for health checks, ?format=json, and the page’s own identity read. Content negotiation matches vgi-python’s LandingPageResource.
• GET {prefix}/vgi-client.js — the browser build the page imports.

Anything else returns null, which lets normal routing continue.

interface LandingInfo

source

export interface LandingInfo

Description

Worker identity for the standardized VGI landing surface.

The shared landing.html reads catalog metadata by speaking the VGI protocol through the client bundle the worker serves beside it, so nothing about the catalog belongs here. What the protocol has no method for — which worker this is, what it is called, what version it runs — rides on the JSON status document at GET {prefix}/?format=json.

Fields

namestring

Worker name shown as the page heading, e.g. “ishares”.

docstringoptional

One-line description shown under the heading.

versionstringoptional

Worker version string shown in the footer.

cupolaBasestringoptional

Override the Cupola base URL the “Explore” links point at.

interface ProtocolConfig

source

export interface ProtocolConfig

Fields

registryFunctionRegistry

catalogInterfaceCatalogInterfaceoptional

catalogNamestringoptional

recoverExchangeState(opaqueData: Uint8Array) => anyoptional

Recover accumulated exchange state from FINALIZE init_opaque_data. For HTTP transport, this unpacks the state token that the C++ extension passes from the last INPUT exchange to the FINALIZE init request. Returns the deserialized VGI dispatch state object (with userState field).

signingKeyUint8Arrayoptional

AEAD signing key for sealing catalog opaque-data envelopes. Pass the same 32-byte key used for HTTP state tokens. When omitted (subprocess / unix transports) attach_opaque_data / transaction_opaque_data pass through unsealed — OS process ownership already enforces identity there.

class Worker

source

export class Worker

Methods

method run

source

run(argv: readonly string[] = process.argv.slice(2)): void

method serveStream

source

async serveStream(
  readable: ReadableStream<Uint8Array> | NodeJS.ReadableStream,
  writable?: number | import("node:net").Socket | import("@query-farm/vgi-rpc").ByteSink,
): Promise<void>

Serve this worker over a caller-provided byte-stream pair, instead of the argv-selected stdio/unix/tcp transports run() uses. Resolves when the readable ends.

This is the seam for transports that aren’t a process/socket — most notably a Web Worker: bridge the worker’s MessagePort to a Node Duplex (readable side ← port.on('message'), writable side → port.postMessage) and pass it as both arguments. The same code runs in a browser Web Worker.

interface WorkerConfig

source

export interface WorkerConfig

Fields

functionsVgiFunction[]optional

catalogCatalogDescriptoroptional

catalogInterfaceCatalogInterfaceoptional

catalogInterfaceFactory(base: ReadOnlyCatalogInterface) => CatalogInterfaceoptional

Factory that receives the built ReadOnlyCatalogInterface and returns a custom catalog.

catalogNamestringoptional

registryFunctionRegistryoptional

Registry to dispatch through. Pass the same instance used to build a pre-constructed catalogInterface — catalogs record which schema (and catalog) declares each function on the registry they are given, and schema-qualified resolution only works if that is the registry the worker dispatches on. Omit to have the worker create its own.