HttpHandlerOptions
Defined in: src/http/types.ts:9
Configuration options for createHttpHandler().
Properties
Section titled “Properties”_onStickyHandle?
Section titled “_onStickyHandle?”optional _onStickyHandle?: (handle) => void;Defined in: src/http/types.ts:110
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:90
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:55
Optional authentication callback. Called for each request before dispatch.
compressionLevel?
Section titled “compressionLevel?”optional compressionLevel?: number;Defined in: src/http/types.ts:53
zstd compression level for responses (1-22). If set, responses are compressed when the client sends Accept-Encoding: zstd.
corsMaxAge?
Section titled “corsMaxAge?”optional corsMaxAge?: number | null;Defined in: src/http/types.ts:21
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:19
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:59
Optional dispatch hook for observability (tracing, metrics).
enableDescribePage?
Section titled “enableDescribePage?”optional enableDescribePage?: boolean;Defined in: src/http/types.ts:67
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:71
Enable JSON health endpoint at GET {prefix}/health. Default: true.
enableLandingPage?
Section titled “enableLandingPage?”optional enableLandingPage?: boolean;Defined in: src/http/types.ts:65
Enable HTML landing page at GET {prefix}/. Default: true.
enableNotFoundPage?
Section titled “enableNotFoundPage?”optional enableNotFoundPage?: boolean;Defined in: src/http/types.ts:69
Enable HTML 404 page for unmatched GET routes. Default: true.
enableSticky?
Section titled “enableSticky?”optional enableSticky?: boolean;Defined in: src/http/types.ts:96
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:82
External storage config for externalizing large response batches.
maxDecompressedRequestBytes?
Section titled “maxDecompressedRequestBytes?”optional maxDecompressedRequestBytes?: number;Defined in: src/http/types.ts:30
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:46
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:23
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:42
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:36
Maximum bytes before a producer stream emits a continuation token.
maxUploadBytes?
Section titled “maxUploadBytes?”optional maxUploadBytes?: number;Defined in: src/http/types.ts:86
Optional advertised maximum upload size, surfaced via VGI-Max-Upload-Bytes.
oauthPkceScope?
Section titled “oauthPkceScope?”optional oauthPkceScope?: string;Defined in: src/http/types.ts:88
OAuth scope for PKCE authorization requests. Default: “openid email”.
oauthResourceMetadata?
Section titled “oauthResourceMetadata?”optional oauthResourceMetadata?: OAuthResourceMetadata;Defined in: src/http/types.ts:57
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:63
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:11
URL path prefix for all endpoints. Default: "" (root).
protocolName?
Section titled “protocolName?”optional protocolName?: string;Defined in: src/http/types.ts:73
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:78
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.
repositoryUrl?
Section titled “repositoryUrl?”optional repositoryUrl?: string;Defined in: src/http/types.ts:80
URL to service’s source repository, shown in landing/describe pages.
serverId?
Section titled “serverId?”optional serverId?: string;Defined in: src/http/types.ts:48
Server ID included in response metadata. Random if omitted.
stateSerializer?
Section titled “stateSerializer?”optional stateSerializer?: StateSerializer;Defined in: src/http/types.ts:50
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:99
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:104
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:15
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:17
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:84
Provider for vending pre-signed upload URLs to clients via {prefix}/upload_url/init.