Struct HttpStateBuilder 

pub struct HttpStateBuilder { /* private fields */ }

Fluent builder for HttpState.

Implementations

impl HttpStateBuilder

pub fn server(self, server: Arc<RpcServer>) -> Self

pub fn token_key(self, key: &[u8]) -> Self

AEAD master key used to seal state tokens. Must be ≥32 bytes — the XChaCha20-Poly1305 key size; the first 32 bytes are used. A shorter slice is a configuration error and panics rather than being silently zero-padded into a weak key. When not set, a random 32-byte key is generated at build() time.

pub fn token_key_hex(self, hex: &str) -> Self

Set the token key from a lowercase-hex string (64 hex chars → 32 bytes). Panics on invalid input — intended for startup config, not runtime callers.

pub fn token_key_base64(self, b64: &str) -> Self

Set the token key from a base64-encoded string (standard alphabet, padding optional). Panics on invalid input.

pub fn token_key_from_env(self, var: &str) -> Self

Read the token key from environment variable var. Accepts either base64 or lowercase-hex (auto-detected). Panics if the variable is unset, empty, or decodes to fewer than 32 bytes. Use this for production deployments where the key is supplied by a secret manager.

pub fn producer_batch_limit(self, n: usize) -> Self

Assert the protocol’s fixed producer limit of one data batch per HTTP response. Retained for source compatibility with callers that explicitly configured the former default; values other than 1 are rejected because HTTP requests are lock-step producer turns.

pub fn call_state_cache_entries(self, n: usize) -> Self

Maximum age of a state token. Continuation requests with a token older than this are rejected. Default 5 minutes. Set to Duration::ZERO to disable TTL enforcement. Size the per-process call-state cache; 0 disables it.

The cache is a pure accelerator — a miss reopens the call token the client echoed, so correctness never depends on a hit. Disabling it is the supported way to prove that: every continuation then takes the miss path, so a client that fails to echo the call token fails immediately instead of only once the cache goes cold in production.

pub fn token_ttl(self, ttl: Duration) -> Self

pub fn max_body_size(self, n: usize) -> Self

Maximum request body size (post-decompression) in bytes. Default 64 * 1024 * 1024 (64 MiB). Enforced as a hard ceiling on the raw request body by a RequestBodyLimitLayer — independent of the Content-Length header, so a chunked upload cannot bypass it.

pub fn request_timeout(self, d: Duration) -> Self

Wall-clock timeout for a single HTTP request. Default 30 s.

pub fn authenticate(self, cb: Authenticate) -> Self

Register an authenticate callback run on every request. Not set → anonymous for all callers (mirrors the Python make_wsgi_app default).

pub fn proxy_auth_headers<I, S>(self, headers: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Advertise VGI-Proxy-Proof-Required: true so a proxy can tell it is minting proofs for a worker that actually checks them. Set it when the proof gate is installed in ProofMode::Require.

Advertisement only — it enables and enforces nothing. The gate rides in through Self::authenticate as an opaque callback the builder cannot introspect, so the operator states the posture here. Declare proxy-injected headers this service’s authentication depends on, for a custom authenticator the framework cannot introspect. The built-in proxy-proof gate registers its own header in require mode.

pub fn proxy_proof_required(self, required: bool) -> Self

pub fn oauth_resource_metadata(self, metadata: OAuthResourceMetadata) -> Self

Attach RFC 9728 Protected Resource Metadata. When set, the server exposes /.well-known/oauth-protected-resource and includes a WWW-Authenticate header on 401 responses.

pub fn cors_origins(self, origins: impl Into<String>) -> Self

Enable CORS with the given Access-Control-Allow-Origin value. Pass "*" for a permissive server or a specific origin URL.

pub fn cors_max_age(self, seconds: u32) -> Self

Override the preflight cache lifetime (seconds). Default 7200.

pub fn prefix(self, prefix: impl Into<String>) -> Self

Mount the router under a URL prefix (e.g. /v1). Default empty.

pub fn response_compression_level(self, level: i32) -> Self

Override the zstd level (1..=22) used for response compression.

Response compression is on by default at DEFAULT_RESPONSE_COMPRESSION_LEVEL; this only changes the level. It applies when the client offers zstd in X-VGI-Accept-Encoding or Accept-Encoding and the body is at least 1024 bytes (bodies below that threshold are sent uncompressed). Use HttpStateBuilder::disable_response_compression to turn it off.

pub fn disable_response_compression(self) -> Self

Turn response compression off entirely.

The server then advertises an empty VGI-Supported-Encodings — a positive statement that it speaks no compression, distinct from a legacy server that omits the header — and ships every body uncompressed however the client asks. Use this when a proxy or CDN already compresses, or when measuring the uncompressed wire.

pub fn enable_landing_page(self, enabled: bool) -> Self

Serve a friendly HTML landing page at GET /. Default on.

pub fn enable_describe_page(self, enabled: bool) -> Self

Serve an API reference HTML page at GET /describe. Default on.

pub fn enable_health(self, enabled: bool) -> Self

Serve a liveness probe at GET /health. Default on.

pub fn max_request_bytes(self, n: usize) -> Self

Maximum inline-request body size advertised via the VGI-Max-Request-Bytes capability header and enforced server-side (413 Payload Too Large for non-exempt routes). When set together with Self::upload_url_provider, clients can externalize oversize requests via __upload_url__/init + a pointer batch.

pub fn max_upload_bytes(self, n: usize) -> Self

Advertised upper bound on the size of any single client-vended upload (header VGI-Max-Upload-Bytes). Advertisement only — no server-side enforcement.

pub fn max_response_bytes(self, n: usize) -> Self

HTTP body cap (header VGI-Max-Response-Bytes). Hard for unary and stream-exchange — overshoot replaces the response with a fresh EXCEPTION-only IPC stream surfaced via 200 + X-VGI-RPC-Error: true. Externalised payloads do not count toward this cap.

pub fn max_externalized_response_bytes(self, n: usize) -> Self

Cap on bytes uploaded to external storage during one HTTP response (header VGI-Max-Externalized-Response-Bytes). Always hard — externalised uploads have no escape valve.

pub fn upload_url_provider(self, provider: Arc<dyn UploadUrlProvider>) -> Self

Install an UploadUrlProvider. When set, the server exposes POST /__upload_url__/init and advertises VGI-Upload-URL-Support: true.

pub fn enable_sticky(self, enabled: bool) -> Self

Opt in to sticky sessions (HTTP-only). When enabled the server advertises VGI-Sticky-Enabled: true, honours the VGI-Session / VGI-Session-Accept headers, and exposes DELETE {prefix}/__session__. Off by default — the non-sticky wire path is unchanged.

pub fn sticky_default_ttl(self, ttl: Duration) -> Self

Default session TTL when a method calls ctx.open_session without an explicit TTL. Default 300 s. Advertised via VGI-Sticky-Default-TTL.

pub fn sticky_echo_headers( self, headers: impl IntoIterator<Item = (String, String)>, ) -> Self

Headers the server tells the client to echo back on every subsequent request in a session (emitted as VGI-Echo-<name> on the session-opening response; advertised by name via VGI-Sticky-Echo-Headers). Used for client-driven routing (e.g. fly-force-instance-id on Fly.io).

pub fn landing_info(self, info: LandingInfo) -> Self

Supply the worker’s identity for the standardized landing surface. When set, GET {prefix}/ serves the shared landing.html plus a JSON status document carrying this identity, and GET {prefix}/vgi-client.js serves the browser client build the page reads the catalog with.

pub fn introspect_resolver(self, resolver: TokenResolver) -> Self

Enable 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.

Off by default: the route answers a fixed 404 not_enabled and holds no resolver, so no worker grows a credential-to-identity oracle by upgrading a dependency. It stays definitive rather than unrouted because a caller that classifies 401/403/404 as final and everything else as transient would retry a generic 415 forever.

Requires introspect_principals. See crate::auth::introspect for the guards and why it is deliberately not a replay through the server’s own authenticate chain.

pub fn introspect_principals<I, S>(self, principals: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Principals permitted to introspect.

Required alongside introspect_resolver, 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.

pub fn introspect_default_ttl(self, ttl: Duration) -> Self

Cache window advertised as ttl_seconds for a resolution that does not name its own. Default 300 s. Treat it as an authorization window: for any path the asker serves without re-presenting the credential, it is exactly that.

pub fn introspect_rate_limit(self, per_second: u32) -> Self

Introspection requests allowed per caller per second (default 20). Bounds, rather than closes, the oracle an allowlisted-but-compromised caller still has.

pub fn build(self) -> Arc<HttpState>

Trait Implementations

impl Default for HttpStateBuilder

fn default() -> HttpStateBuilder

Returns the “default value” for a type.