HttpHandlerOptions

Configuration options for createHttpHandler().

Properties

_onStickyHandle?

optional _onStickyHandle?: (handle) => void;

Defined in: src/http/types.ts:195

Internal — invoked once at handler creation with a DrainHandle when sticky is enabled. Conformance fixtures use this to wire up the test-only /__test_drain__ admin endpoint without the library exposing the registry directly. Production code should hold the handle returned by a future createHttpHandlerWithDrainHandle helper.

Parameters

Parameter	Type
`handle`	`DrainHandle`

Returns

void

allowedReturnOrigins?

optional allowedReturnOrigins?: ReadonlySet<string>;

Defined in: src/http/types.ts:174

Allowed return-to origins for external frontend redirects. Default: Set([“https://cupola.query-farm.services”]).

authenticate?

optional authenticate?: AuthenticateFn;

Defined in: src/http/types.ts:81

Optional authentication callback. Called for each request before dispatch.

callStateCacheEntries?

optional callStateCacheEntries?: number;

Defined in: src/http/types.ts:134

Size of the per-process cache of resolved stream calls. The cache is a pure accelerator — a miss reopens the call token the client echoed — so 0 disables it and forces every continuation onto the miss path, which is what the cold-cache conformance group runs against. Default: 4096.

compressionLevel?

optional compressionLevel?: number | null;

Defined in: src/http/types.ts:79

zstd compression level for responses (1-22).

Defaults to 1 — response compression is on. Responses are compressed with the codec the client asked for (see the Compression guide); the level applies to zstd only, since the Web CompressionStream gzip encoder exposes no level.

Level 1 rather than 3 because on Arrow IPC bodies it is not a speed/size tradeoff — on an 8.41 MB body level 1 measured 4.7x faster and produced a smaller result. Every VGI SDK defaults to the same level.

Set to null to disable response compression entirely: no codec is advertised (VGI-Supported-Encodings goes out present-but-empty) and bodies travel uncompressed however the client asks.

corsMaxAge?

optional corsMaxAge?: number | null;

Defined in: src/http/types.ts:22

Access-Control-Max-Age value in seconds for preflight OPTIONS responses. Default: 300 (5 minutes). null omits the header.

corsOrigins?

optional corsOrigins?: string;

Defined in: src/http/types.ts:20

CORS allowed origins. If set, CORS headers are added to all responses.

dispatchHook?

optional dispatchHook?: DispatchHook;

Defined in: src/http/types.ts:138

Optional dispatch hook for observability (tracing, metrics).

enableDescribePage?

optional enableDescribePage?: boolean;

Defined in: src/http/types.ts:151

Enable HTML describe/API reference page at GET {prefix}/describe. Default: true.

enableHealthEndpoint?

optional enableHealthEndpoint?: boolean;

Defined in: src/http/types.ts:155

Enable JSON health endpoint at GET {prefix}/health. Default: true.

enableLandingPage?

optional enableLandingPage?: boolean;

Defined in: src/http/types.ts:144

Enable HTML landing page at GET {prefix}/. Default: true.

enableNotFoundPage?

optional enableNotFoundPage?: boolean;

Defined in: src/http/types.ts:153

Enable HTML 404 page for unmatched GET routes. Default: true.

enableSticky?

optional enableSticky?: boolean;

Defined in: src/http/types.ts:180

Enable opt-in sticky sessions on this HTTP handler. When enabled the server advertises VGI-Sticky-Enabled: true (capability discovery), honours VGI-Session / VGI-Session-Accept headers, and exposes a DELETE {prefix}/__session__ teardown endpoint. Default: false.

externalLocation?

optional externalLocation?: ExternalLocationConfig;

Defined in: src/http/types.ts:166

External storage config for externalizing large response batches.

extraRoutes?

optional extraRoutes?: ExtraRouteHandler;

Defined in: src/http/types.ts:149

Extra GET routes contributed by a layer above this one, consulted after authentication and the OAuth browser redirect but before the generic landing page and the 404. Return null to decline and let normal routing continue. See ExtraRouteHandler.

hostingMaxRequestBytes?

optional hostingMaxRequestBytes?: number;

Defined in: src/http/types.ts:27

Optional hosting-platform request cap. The effective advertised and enforced limit is the minimum of this and maxRequestBytes.

hostingMaxResponseBytes?

optional hostingMaxResponseBytes?: number;

Defined in: src/http/types.ts:49

Optional hosting-platform response cap. Combined with the application cap and the client’s VGI-Accept-Max-Response-Bytes value.

identityBearer?

optional identityBearer?: boolean;

Defined in: src/http/types.ts:129

Accept the hosted vgi_rpc.Identity.v1’s credentials as bearers – its sealed grants (when grant keys are configured) and tokens its resolveToken resolves – after authenticate (WIRE_PROTOCOL.md §16). Default true. false is for a deployment that composes grantAuthenticate / resolveTokenAuthenticate itself, which is required when authentication depends on proxy-injected evidence (proxyProofRequired, proxyAuthHeaders).

includeTracebacks?

optional includeTracebacks?: boolean;

Defined in: src/http/types.ts:62

Whether EXCEPTION batches carry the remote traceback. Default: the served VgiRpcServer’s includeTracebacks, else true – included on every transport (WIRE_PROTOCOL.md §8, “Tracebacks”). false omits it.

maxDecompressedRequestBytes?

optional maxDecompressedRequestBytes?: number;

Defined in: src/http/types.ts:34

Cap on the post-decompression size of a Content-Encoding: zstd request body, in bytes. Defends against zstd decompression bombs: a tiny compressed frame can declare a huge decompressed size and blow up the server before maxRequestBytes ever sees the payload. When omitted, defaults to maxRequestBytes * 16 if that is set, otherwise unbounded.

maxExternalizedResponseBytes?

optional maxExternalizedResponseBytes?: number;

Defined in: src/http/types.ts:56

Cap on bytes uploaded to external storage during one HTTP response. Always hard — externalised uploads have no escape valve. Advertised via VGI-Max-Externalized-Response-Bytes. Undefined = unbounded.

maxRequestBytes?

optional maxRequestBytes?: number;

Defined in: src/http/types.ts:24

Maximum request body size in bytes. Advertised via VGI-Max-Request-Bytes header.

maxResponseBytes?

optional maxResponseBytes?: number;

Defined in: src/http/types.ts:46

Hard HTTP response body cap for unary, exchange, and producer turns. Overshoot is replaced by an error-only response and producer cursors are discarded. Externalised payloads do not count toward this — they leave only tiny pointer batches on the wire. Advertised via VGI-Max-Response-Bytes. Undefined = unbounded.

maxStreamResponseBytes?

optional maxStreamResponseBytes?: number;

Defined in: src/http/types.ts:40

Worker-visible response-size budget for each producer invocation.

maxUploadBytes?

optional maxUploadBytes?: number;

Defined in: src/http/types.ts:170

Optional advertised maximum upload size, surfaced via VGI-Max-Upload-Bytes.

oauthPkceScope?

optional oauthPkceScope?: string;

Defined in: src/http/types.ts:172

OAuth scope for PKCE authorization requests. Default: “openid email”.

oauthResourceMetadata?

optional oauthResourceMetadata?: OAuthResourceMetadata;

Defined in: src/http/types.ts:136

Optional RFC 9728 OAuth Protected Resource Metadata. Served at well-known endpoint.

onServeStart?

optional onServeStart?: ServeStartHook;

Defined in: src/http/types.ts:142

Optional lifecycle hook fired once on the first dispatched request. Mirrors Python’s on_serve_start; lazy-firing keeps it fork-safe for pre-fork servers.

peerAuthenticationPolicy?

optional peerAuthenticationPolicy?: PeerAuthenticationPolicy;

Defined in: src/http/types.ts:85

Composition policy for application auth and resolved peer evidence.

peerIdentityProviders?

optional peerIdentityProviders?: readonly PeerIdentityProvider[];

Defined in: src/http/types.ts:83

Off-wire transport peer evidence providers.

peerProviderConcurrency?

optional peerProviderConcurrency?: number;

Defined in: src/http/types.ts:102

Maximum provider calls allowed to remain active, including calls that ignore abort after their request deadline. Must be at least the configured provider count. An exhausted provider contributes UNAVAILABLE evidence; the authentication policy decides whether that request may continue. Default: 64.

peerResolutionContext?

optional peerResolutionContext?: (request) =>
  | PeerResolutionOptions
| Promise<PeerResolutionOptions>;

Defined in: src/http/types.ts:93

Runtime adapter for immediate/destination socket facts unavailable to Fetch Request. Header-based identity providers must also supply raw, multiplicity-preserving headers here. Fetch Headers has already merged duplicates and is therefore never trusted as identity evidence. When this hook is absent, or omits headers, providers see no identity headers at all; there is deliberately no fallback to request.headers. Values must be arrays even for single-valued headers so accidental use of a lossy string-valued adapter fails closed.

Parameters

Parameter	Type
`request`	`Request`

Returns

| PeerResolutionOptions | Promise<PeerResolutionOptions>

peerResolutionTimeoutMs?

optional peerResolutionTimeoutMs?: number;

Defined in: src/http/types.ts:97

Total peer-provider deadline in milliseconds. Default: 5000.

peerServiceName?

optional peerServiceName?: string;

Defined in: src/http/types.ts:95

Operator-configured logical destination for destination-scoped evidence.

preferredResponseBytes?

optional preferredResponseBytes?: number;

Defined in: src/http/types.ts:52

Worker sizing target, clamped to the effective hard response limit and exposed off-wire on CallContext/OutputCollector.

prefix?

optional prefix?: string;

Defined in: src/http/types.ts:12

URL path prefix for all endpoints. Default: “” (root).

protocolName?

optional protocolName?: string;

Defined in: src/http/types.ts:157

Protocol name shown in HTML pages. Defaults to the Protocol’s name.

protocolVersion?

optional protocolVersion?: string;

Defined in: src/http/types.ts:162

Operator-supplied protocol-contract version label, surfaced on every access-log record so dashboards and alerts can key off contract changes. Mirrors the Python RpcServer(..., protocol_version=...) argument.

proxyAuthHeaders?

optional proxyAuthHeaders?: readonly string[];

Defined in: src/http/types.ts:121

Proxy-injected headers this service’s authentication depends on, for a custom AuthenticateFn the handler cannot introspect.

Declaring them turns on the 401 proxy note of docs/unauthorized-spec.md §5: VGI-Auth-Proxy-Required: true plus a proxy_hint explaining that a rejection here is at least as likely to be a proxy that is not forwarding the header as a bad credential — the failure mode that otherwise looks exactly like a rotated credential. A requireProxyProof gate declared through proxyProofRequired contributes its own header, so this is only needed on top of that.

proxyProofRequired?

optional proxyProofRequired?: boolean;

Defined in: src/http/types.ts:110

Advertise VGI-Proxy-Proof-Required: true on every response, so a proxy or operator can confirm this worker rejects unproofed requests.

Advertisement only — it enforces nothing. Set it alongside a requireProxyProof gate built with mode: "require"; that gate arrives as an opaque AuthenticateFn the handler cannot introspect, so the posture has to be stated. Default: false.

repositoryUrl?

optional repositoryUrl?: string;

Defined in: src/http/types.ts:164

URL to service’s source repository, shown in landing/describe pages.

serverId?

optional serverId?: string;

Defined in: src/http/types.ts:58

Server ID included in response metadata. Random if omitted.

stateSerializer?

optional stateSerializer?: StateSerializer;

Defined in: src/http/types.ts:64

Custom state serializer for stream state objects. Default: JSON with BigInt support.

stickyDefaultTtl?

optional stickyDefaultTtl?: number;

Defined in: src/http/types.ts:183

Default session TTL in seconds when ctx.openSession is called without an explicit ttl override. Default: 300.

stickyEchoHeaders?

optional stickyEchoHeaders?: Record<string, string>;

Defined in: src/http/types.ts:188

Headers the server emits as VGI-Echo-<name>: <value> on the session-opening response. A conformant client captures them and replays them on every subsequent request in the session — used for client-driven routing (e.g. fly-force-instance-id on Fly.io).

tokenKey?

optional tokenKey?: Uint8Array<ArrayBufferLike>;

Defined in: src/http/types.ts:16

XChaCha20-Poly1305 master key (32 bytes) used to seal stream state tokens. A random 32-byte key is generated if omitted (tokens won’t survive a restart or load-balance across workers).

tokenTtl?

optional tokenTtl?: number;

Defined in: src/http/types.ts:18

State token time-to-live in seconds. Default: 3600 (1 hour). 0 disables TTL checks.

uploadUrlProvider?

optional uploadUrlProvider?: UploadUrlProvider;

Defined in: src/http/types.ts:168

Provider for vending pre-signed upload URLs to clients via {prefix}/upload_url/init.