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

Maximum data batches per producer HTTP response (0 = unbounded). Default 1 to mirror the Python/Go servers.

pub fn token_ttl(self, ttl: Duration) -> 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.

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

Enable zstd response compression at the given level (1..=22) when the client sends Accept-Encoding: zstd. Default off.

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 build(self) -> Arc<HttpState>

Trait Implementations

impl Default for HttpStateBuilder

fn default() -> HttpStateBuilder

Returns the “default value” for a type.