HttpHandlerOptions
Defined in: src/http/types.ts:10
Configuration options for createHttpHandler().
Properties
Section titled “Properties”_onStickyHandle?
Section titled “_onStickyHandle?”optional _onStickyHandle?: (handle) => void;Defined in: src/http/types.ts:180
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
Section titled “Parameters”| Parameter | Type |
|---|---|
handle |
DrainHandle |
Returns
Section titled “Returns”void
allowedReturnOrigins?
Section titled “allowedReturnOrigins?”optional allowedReturnOrigins?: ReadonlySet<string>;Defined in: src/http/types.ts:133
Allowed return-to origins for external frontend redirects. Default: Set([“https://cupola.query-farm.services”]).
authenticate?
Section titled “authenticate?”optional authenticate?: AuthenticateFn;Defined in: src/http/types.ts:68
Optional authentication callback. Called for each request before dispatch.
callStateCacheEntries?
Section titled “callStateCacheEntries?”optional callStateCacheEntries?: number;Defined in: src/http/types.ts:92
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?
Section titled “compressionLevel?”optional compressionLevel?: number | null;Defined in: src/http/types.ts:66
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?
Section titled “corsMaxAge?”optional corsMaxAge?: number | null;Defined in: src/http/types.ts:22
Access-Control-Max-Age value in seconds for preflight OPTIONS responses. Default: 7200 (2 hours). null omits the header.
corsOrigins?
Section titled “corsOrigins?”optional corsOrigins?: string;Defined in: src/http/types.ts:20
CORS allowed origins. If set, CORS headers are added to all responses.
dispatchHook?
Section titled “dispatchHook?”optional dispatchHook?: DispatchHook;Defined in: src/http/types.ts:96
Optional dispatch hook for observability (tracing, metrics).
enableDescribePage?
Section titled “enableDescribePage?”optional enableDescribePage?: boolean;Defined in: src/http/types.ts:110
Enable HTML describe/API reference page at GET {prefix}/describe. Default: true.
enableHealthEndpoint?
Section titled “enableHealthEndpoint?”optional enableHealthEndpoint?: boolean;Defined in: src/http/types.ts:114
Enable JSON health endpoint at GET {prefix}/health. Default: true.
enableLandingPage?
Section titled “enableLandingPage?”optional enableLandingPage?: boolean;Defined in: src/http/types.ts:102
Enable HTML landing page at GET {prefix}/. Default: true.
enableNotFoundPage?
Section titled “enableNotFoundPage?”optional enableNotFoundPage?: boolean;Defined in: src/http/types.ts:112
Enable HTML 404 page for unmatched GET routes. Default: true.
enableSticky?
Section titled “enableSticky?”optional enableSticky?: boolean;Defined in: src/http/types.ts:139
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?
Section titled “externalLocation?”optional externalLocation?: ExternalLocationConfig;Defined in: src/http/types.ts:125
External storage config for externalizing large response batches.
introspectPrincipals?
Section titled “introspectPrincipals?”optional introspectPrincipals?: Iterable<string, any, any>;Defined in: src/http/types.ts:166
Principals permitted to introspect. Required whenever introspectResolver is set, with no permissive default: authentication and introspection are different capabilities, and a deployment where any valid credential may introspect lets any user resolve any other user’s credential to its owner.
introspectRateLimit?
Section titled “introspectRateLimit?”optional introspectRateLimit?: number;Defined in: src/http/types.ts:173
Introspection requests allowed per caller per second (default 20). Bounds, rather than closes, the oracle an allowlisted-but-compromised caller still has.
introspectResolver?
Section titled “introspectResolver?”optional introspectResolver?: TokenResolver;Defined in: src/http/types.ts:160
Enables POST {prefix}/__introspect_token__, which resolves an opaque
bearer credential to a principal for a reverse proxy that must know the
caller’s identity before it can authorize.
Omitted (the default) leaves the endpoint disabled — it answers a
definitive 404 {"error": "not_enabled"} and holds no resolver — so no
worker grows a credential-to-identity oracle by upgrading a dependency.
The callable returns a TokenIdentity or null, and throws
AuthUnavailableError when the answer is not knowable, which a caller
must retry rather than cache. It never returns claims; see
src/http/introspect.ts for why.
introspectTtlSeconds?
Section titled “introspectTtlSeconds?”optional introspectTtlSeconds?: number;Defined in: src/http/types.ts:169
Cache window advertised as ttl_seconds when a resolved TokenIdentity
names none. Default: 300.
landingInfo?
Section titled “landingInfo?”optional landingInfo?: LandingInfo;Defined in: src/http/types.ts:108
Activates the VGI landing surface. When set, GET {prefix}/ serves the
shared vendored landing.html (plus a JSON status document carrying this
identity) and GET {prefix}/vgi-client.js serves the browser build of the
VGI client the page reads the catalog with. Replaces the generic styled
landing page for VGI workers. See LandingInfo.
maxDecompressedRequestBytes?
Section titled “maxDecompressedRequestBytes?”optional maxDecompressedRequestBytes?: number;Defined in: src/http/types.ts:31
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?
Section titled “maxExternalizedResponseBytes?”optional maxExternalizedResponseBytes?: number;Defined in: src/http/types.ts:47
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?
Section titled “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?
Section titled “maxResponseBytes?”optional maxResponseBytes?: number;Defined in: src/http/types.ts:43
HTTP body cap. Hard for unary and stream-exchange (overshoot surfaces as 200 + X-VGI-RPC-Error EXCEPTION batch). Soft for producer streams (overshoot mints a continuation token). 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?
Section titled “maxStreamResponseBytes?”optional maxStreamResponseBytes?: number;Defined in: src/http/types.ts:37
Maximum bytes before a producer stream emits a continuation token.
maxUploadBytes?
Section titled “maxUploadBytes?”optional maxUploadBytes?: number;Defined in: src/http/types.ts:129
Optional advertised maximum upload size, surfaced via VGI-Max-Upload-Bytes.
oauthPkceScope?
Section titled “oauthPkceScope?”optional oauthPkceScope?: string;Defined in: src/http/types.ts:131
OAuth scope for PKCE authorization requests. Default: “openid email”.
oauthResourceMetadata?
Section titled “oauthResourceMetadata?”optional oauthResourceMetadata?: OAuthResourceMetadata;Defined in: src/http/types.ts:94
Optional RFC 9728 OAuth Protected Resource Metadata. Served at well-known endpoint.
onServeStart?
Section titled “onServeStart?”optional onServeStart?: ServeStartHook;Defined in: src/http/types.ts:100
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.
prefix?
Section titled “prefix?”optional prefix?: string;Defined in: src/http/types.ts:12
URL path prefix for all endpoints. Default: “” (root).
protocolName?
Section titled “protocolName?”optional protocolName?: string;Defined in: src/http/types.ts:116
Protocol name shown in HTML pages. Defaults to the Protocol’s name.
protocolVersion?
Section titled “protocolVersion?”optional protocolVersion?: string;Defined in: src/http/types.ts:121
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?
Section titled “proxyAuthHeaders?”optional proxyAuthHeaders?: readonly string[];Defined in: src/http/types.ts:87
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?
Section titled “proxyProofRequired?”optional proxyProofRequired?: boolean;Defined in: src/http/types.ts:76
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?
Section titled “repositoryUrl?”optional repositoryUrl?: string;Defined in: src/http/types.ts:123
URL to service’s source repository, shown in landing/describe pages.
serverId?
Section titled “serverId?”optional serverId?: string;Defined in: src/http/types.ts:49
Server ID included in response metadata. Random if omitted.
stateSerializer?
Section titled “stateSerializer?”optional stateSerializer?: StateSerializer;Defined in: src/http/types.ts:51
Custom state serializer for stream state objects. Default: JSON with BigInt support.
stickyDefaultTtl?
Section titled “stickyDefaultTtl?”optional stickyDefaultTtl?: number;Defined in: src/http/types.ts:142
Default session TTL in seconds when ctx.openSession is called without
an explicit ttl override. Default: 300.
stickyEchoHeaders?
Section titled “stickyEchoHeaders?”optional stickyEchoHeaders?: Record<string, string>;Defined in: src/http/types.ts:147
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?
Section titled “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?
Section titled “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?
Section titled “uploadUrlProvider?”optional uploadUrlProvider?: UploadUrlProvider;Defined in: src/http/types.ts:127
Provider for vending pre-signed upload URLs to clients via {prefix}/upload_url/init.