Configuration Reference

Configuration Reference¶

This page documents all configuration types and their defaults across all languages.

DynamicSchemaConfig¶

Configuration for building and executing a dynamic-SDL schema.

Field	Type	Default	Description
`introspection_enabled`	`bool`	—	Whether introspection queries (`__schema`, `__type`) are permitted.
`max_complexity`	`int \\| None`	`None`	Maximum query complexity (`None` = unlimited).
`max_depth`	`int \\| None`	`None`	Maximum query depth (`None` = unlimited).
`field_errors`	`list\[FieldErrorSpec\]`	`[]`	Field-level errors to inject at specific response paths.

SchemaConfig¶

Configuration for GraphQL schema building.

Encapsulates all schema-level configuration options including introspection control, complexity limits, and depth limits.

Field	Type	Default	Description
`introspection_enabled`	`bool`	`True`	Enable introspection queries
`complexity_limit`	`int \\| None`	`None`	Maximum query complexity (None = unlimited)
`depth_limit`	`int \\| None`	`None`	Maximum query depth (None = unlimited)

QueryOnlyConfig¶

Configuration for schemas with only Query type

Field	Type	Default	Description
`introspection_enabled`	`bool`	`True`	Enable introspection queries
`complexity_limit`	`int \\| None`	`None`	Maximum query complexity (None = unlimited)
`depth_limit`	`int \\| None`	`None`	Maximum query depth (None = unlimited)

QueryMutationConfig¶

Configuration for schemas with Query and Mutation types

Field	Type	Default	Description
`introspection_enabled`	`bool`	`True`	Enable introspection queries
`complexity_limit`	`int \\| None`	`None`	Maximum query complexity (None = unlimited)
`depth_limit`	`int \\| None`	`None`	Maximum query depth (None = unlimited)

FullSchemaConfig¶

Configuration for fully-featured schemas with Query, Mutation, and Subscription types

Field	Type	Default	Description
`introspection_enabled`	`bool`	`True`	Enable introspection queries
`complexity_limit`	`int \\| None`	`None`	Maximum query complexity (None = unlimited)
`depth_limit`	`int \\| None`	`None`	Maximum query depth (None = unlimited)

AsyncApiConfig¶

AsyncAPI HTTP endpoint configuration

Field	Type	Default	Description
`enabled`	`bool`	—	Enable AsyncAPI endpoints (default: false)
`spec`	`dict\[str, Any\] \\| None`	`None`	Pre-registered AsyncAPI spec to serve from GET /asyncapi.json

BackgroundTaskConfig¶

Configuration for in-process background task execution.

Field	Type	Default	Description
`enabled`	`bool`	`False`	Whether the server starts a background task executor at router-construction time. `ServerConfig.background_tasks` is a bare struct rather than an `Option`, so its mere presence cannot mean "configured" the way `Option`-shaped middleware config does — every server has one. Without this flag every router build would spawn an executor task, which also requires an ambient Tokio runtime that a synchronous `build_router_*` caller may not have. Defaults to `False` so opting in is explicit, and matches the corpus vocabulary: `fixtures/background_tasks.json` spells its per-route payloads `{"enabled": true, ...}`.
`max_queue_size`	`int`	`1024`	Maximum queue size
`max_concurrent_tasks`	`int`	`128`	Maximum concurrent tasks
`drain_timeout_secs`	`int`	`30`	Drain timeout secs

BackgroundJobMetadata¶

Field	Type	Default	Description
`name`	`str`	`"background_task"`	The name
`request_id`	`str \\| None`	`None`	Request id

CorsConfig¶

CORS configuration for a route

Field	Type	Default	Description
`allowed_origins`	`list\[str\]`	`["*"]`	Allowed origins
`allowed_methods`	`list\[str\]`	`["*"]`	Allowed methods
`allowed_headers`	`list\[str\]`	`[]`	Allowed headers
`expose_headers`	`list\[str\] \\| None`	`None`	Expose headers
`max_age`	`int \\| None`	`None`	Maximum age
`allow_credentials`	`bool \\| None`	`None`	Allow credentials

CompressionConfig¶

Compression configuration shared across runtimes

Field	Type	Default	Description
`gzip`	`bool`	`True`	Enable gzip compression
`brotli`	`bool`	`True`	Enable brotli compression
`min_size`	`int`	`1024`	Minimum response size to compress (bytes)
`quality`	`int`	`6`	Compression quality (0-11 for brotli, 0-9 for gzip)

RateLimitConfig¶

Rate limiting configuration shared across runtimes

Field	Type	Default	Description
`per_second`	`int`	`100`	Requests per second
`burst`	`int`	`200`	Burst allowance
`ip_based`	`bool`	`True`	Use IP-based rate limiting

GrpcConfig¶

Configuration for gRPC support

Controls how the server handles gRPC requests, including compression, timeouts, and protocol settings.

Stream Limits¶

This configuration enforces message-level size limits but delegates concurrent stream limiting to the HTTP/2 transport layer:

Message Size Limits: The max_message_size field is enforced per individual message (request or response) in both unary and streaming RPCs. When a single message exceeds this limit, the request is rejected with PAYLOAD_TOO_LARGE (HTTP 413).
Concurrent Stream Limits: The max_concurrent_streams is an advisory configuration passed to the HTTP/2 layer for connection-level stream negotiation. The HTTP/2 transport automatically enforces this limit and returns GOAWAY frames when exceeded. Applications should not rely on custom enforcement of this limit.
Stream Response Size Limits: The max_stream_response_bytes field caps the total encoded bytes emitted across a server-streaming or bidi-streaming response. When the cumulative size exceeds the limit, the stream is terminated with tonic.Status.resource_exhausted. Defaults to None (unbounded).

Field	Type	Default	Description
`enabled`	`bool`	`True`	Enable gRPC support
`max_message_size`	`int`	`4194304`	Maximum message size in bytes (for both sending and receiving) This limit applies to individual messages in both unary and streaming RPCs. When a single message exceeds this size, the request is rejected with HTTP 413 (Payload Too Large). Default: 4MB (4194304 bytes) Note: This limit does NOT apply to the total response size in streaming RPCs. For multi-message streams, the total response can exceed this limit as long as each individual message stays within the limit.
`enable_compression`	`bool`	`True`	Enable gzip compression for gRPC messages
`request_timeout`	`int \\| None`	`None`	Timeout for gRPC requests in seconds (None = no timeout)
`max_concurrent_streams`	`int`	`100`	Maximum number of concurrent streams per connection (HTTP/2 advisory) This value is communicated to HTTP/2 clients as the server's flow control limit. The HTTP/2 transport layer enforces this limit automatically via SETTINGS frames and GOAWAY responses. Applications should NOT implement custom enforcement. Default: 100 streams per connection # Stream Limiting Strategy - Per Connection: This limit applies per HTTP/2 connection, not globally - Transport Enforcement: HTTP/2 handles all stream limiting; applications need not implement custom checks - Streaming Requests: In server streaming or bidi streaming, each logical RPC consumes one stream slot. Message ordering within a stream follows HTTP/2 frame ordering.
`enable_keepalive`	`bool`	`True`	Enable HTTP/2 keepalive
`keepalive_interval`	`int`	`75`	HTTP/2 keepalive interval in seconds
`keepalive_timeout`	`int`	`20`	HTTP/2 keepalive timeout in seconds
`max_stream_response_bytes`	`int \\| None`	`None`	Total byte cap across an entire streaming response. When `Some(n)`, the streaming adapter aborts the stream with `tonic.Status.resource_exhausted` once the cumulative encoded message bytes exceed `n`. The stream yields the error item and then terminates. Per-message cap remains `max_message_size`. This limit applies to server-streaming and bidirectional-streaming RPCs only; unary RPCs are governed solely by `max_message_size`. Default: `None` (unbounded total response size).

JsonRpcConfig¶

JSON-RPC server configuration

Field	Type	Default	Description
`enabled`	`bool`	`True`	Enable JSON-RPC endpoint
`endpoint_path`	`str`	`"/rpc"`	HTTP endpoint path for JSON-RPC requests (default: "/rpc")
`enable_batch`	`bool`	`True`	Enable batch request processing (default: true)
`max_batch_size`	`int`	`100`	Maximum number of requests in a batch (default: 100)

OpenApiConfig¶

OpenAPI configuration

Field	Type	Default	Description
`enabled`	`bool`	`False`	Enable OpenAPI generation (default: false for zero overhead)
`title`	`str`	`"API"`	API title
`version`	`str`	`"1.0.0"`	API version
`description`	`str \\| None`	`None`	API description (supports markdown)
`swagger_ui_path`	`str`	`"/docs"`	Path to serve Swagger UI (default: "/docs")
`redoc_path`	`str`	`"/redoc"`	Path to serve Redoc (default: "/redoc")
`openapi_json_path`	`str`	`"/openapi.json"`	Path to serve OpenAPI JSON spec (default: "/openapi.json")
`contact`	`ContactInfo \\| None`	`None`	Contact information
`license`	`LicenseInfo \\| None`	`None`	License information
`servers`	`list\[ServerInfo\]`	`[]`	Server definitions
`security_schemes`	`dict\[str, SecuritySchemeInfo\]`	`{}`	Security schemes (auto-detected from middleware if not provided)

Response¶

HTTP Response with custom status code, headers, and content

Field	Type	Default	Description
`content`	`dict\[str, Any\] \\| None`	`None`	Response body content
`status_code`	`int`	`200`	HTTP status code (defaults to 200)
`headers`	`dict\[str, str\]`	`{}`	Response headers

JwtConfig¶

JWT authentication configuration

Field	Type	Default	Description
`secret`	`str`	—	Secret key for JWT verification
`algorithm`	`str`	`"HS256"`	Required algorithm (HS256, HS384, HS512, RS256, etc.)
`audience`	`list\[str\] \\| None`	`None`	Required audience claim
`issuer`	`str \\| None`	`None`	Required issuer claim
`leeway`	`int`	`/* serde(default) */`	Leeway for expiration checks (seconds)

ApiKeyConfig¶

API Key authentication configuration

Field	Type	Default	Description
`keys`	`list\[str\]`	—	Valid API keys
`header_name`	`str`	`"X-API-Key"`	Header name to check (e.g., "X-API-Key")

StaticFilesConfig¶

Static file serving configuration

Field	Type	Default	Description
`directory`	`str`	—	Directory path to serve
`route_prefix`	`str`	—	URL path prefix (e.g., "/static")
`index_file`	`bool`	`True`	Fallback to index.html for directories
`cache_control`	`str \\| None`	`None`	Cache-Control header value

ServerConfig¶

Server configuration

Field	Type	Default	Description
`host`	`str`	`"127.0.0.1"`	Host to bind to
`port`	`int`	`8000`	Port to bind to
`workers`	`int`	`1`	Number of Tokio runtime worker threads used by binding-managed server runtimes
`enable_request_id`	`bool`	`False`	Enable request ID generation and propagation
`max_body_size`	`int \\| None`	`10485760`	Maximum request body size in bytes (None = unlimited, not recommended)
`request_timeout`	`int \\| None`	`None`	Request timeout in seconds (None = no timeout)
`compression`	`CompressionConfig \\| None`	`None`	Enable compression middleware
`rate_limit`	`RateLimitConfig \\| None`	`None`	Enable rate limiting
`jwt_auth`	`JwtConfig \\| None`	`None`	JWT authentication configuration
`api_key_auth`	`ApiKeyConfig \\| None`	`None`	API Key authentication configuration
`static_files`	`list\[StaticFilesConfig\]`	`[]`	Static file serving configuration
`graceful_shutdown`	`bool`	`True`	Enable graceful shutdown on SIGTERM/SIGINT
`shutdown_timeout`	`int`	`30`	Graceful shutdown timeout (seconds)
`asyncapi`	`AsyncApiConfig \\| None`	`None`	AsyncAPI HTTP endpoint configuration
`openapi`	`OpenApiConfig \\| None`	`None`	OpenAPI documentation configuration
`jsonrpc`	`JsonRpcConfig \\| None`	`None`	JSON-RPC configuration
`grpc`	`GrpcConfig \\| None`	`None`	gRPC configuration
`background_tasks`	`BackgroundTaskConfig`	—	Background task executor configuration
`enable_http_trace`	`bool`	`False`	Enable per-request HTTP tracing (tower-http `TraceLayer`)

RequestIdConfig¶

Per-route request-id generation/propagation override.

Modeled as a struct rather than Option<bool> on RouteMetadata because the wire shape is an object, not a bare boolean: fixtures/request_id.json's request_id_middleware_can_be_disabled sends {"enabled": false}, which Option<bool> cannot deserialize at all ("invalid type: map, expected a boolean") — the very fixture whose purpose is proving the middleware can be disabled was the one that failed to parse.

Field	Type	Default	Description
`enabled`	`bool`	—	Whether request-id generation/propagation is active for this route

JwtAuthConfig¶

Per-route JWT authentication requirement.

spikard-http defines the canonical JwtConfig used by ServerConfig.jwt_auth, but spikard-core cannot depend on spikard-http (the dependency runs the other way), so that type cannot be reused here. This mirrors its fields so a later enforcement phase in spikard-http can convert between the two without losing information.

secret and public_key are both optional because asymmetric algorithms (RS256, ES256, ...) verify against a public key rather than a shared secret; see fixtures/auth.json's jwt_config_algorithm_rs256, which carries public_key and no secret at all. Exactly one is expected to be populated for a given algorithm, but that cross-field invariant is left to a later enforcement phase rather than the type itself.

Field	Type	Default	Description
`enabled`	`bool`	`True`	Whether this per-route JWT auth requirement is active. Present on 21/21 `jwt_auth` fixture payloads in the corpus; defaults to `True` because presence of a `jwt_auth` block has always meant "enabled" up to now. Without this field a fixture setting `"enabled": false` would silently keep auth on while the fixture's parse still succeeds — a vacuous pass.
`secret`	`str \\| None`	`/* serde(default) */`	Symmetric secret key for JWT verification (HS256, HS384, HS512)
`public_key`	`str \\| None`	`/* serde(default) */`	Asymmetric public key for JWT verification (RS256, ES256, etc.)
`algorithm`	`str`	`"HS256"`	Required algorithm (HS256, HS384, HS512, RS256, etc.)
`audience`	`list\[str\] \\| None`	`None`	Required audience claim
`issuer`	`str \\| None`	`None`	Required issuer claim
`leeway`	`int`	`/* serde(default) */`	Leeway for expiration checks (seconds)

ApiKeyAuthConfig¶

Per-route API key authentication requirement.

Mirrors spikard_http.ApiKeyConfig for the same reason JwtAuthConfig mirrors spikard_http.JwtConfig: spikard-core cannot depend on spikard-http.

Field	Type	Default	Description
`enabled`	`bool`	`True`	Whether this per-route API key auth requirement is active. Present on 10/10 `api_key_auth` fixture payloads in the corpus; defaults to `True` for the same reason as `JwtAuthConfig.enabled`.
`keys`	`list\[str\]`	`/* serde(default) */`	Valid API keys. Defaults to empty (rather than being a required field) so that `fixtures/server_config.json`'s `server_jwt_and_api_key_auth_combined` payload (`{"enabled": true, "header": "X-API-Key"}`, no `keys` at all) deserializes instead of hard-failing with "missing field `keys`". An empty list is NOT "allow everyone": a later enforcement phase MUST treat an empty `keys` list as a hard misconfiguration error, never as an open gate.
`header_name`	`str`	`"X-API-Key"`	Header name to check (e.g., "X-API-Key")

AuthorizationConfig¶

Per-route roles/scopes/permissions authorization requirement.

spikard_http.auth.Claims does not yet carry roles, scopes, or permissions, so nothing can enforce this today. This type only defines the requirement shape; a later phase must extend Claims (or an equivalent claims-decoding path) to populate them before enforcement is possible.

Deserialization goes through AuthorizationConfigRepr rather than a derive so the fixture's singular {"required_role": "admin"} shape (fixtures/problem_details.json's problem_details_403_forbidden) populates required_roles instead of being silently dropped as an unrecognized field — a config that parses to "no constraint" from real authorization data is a vacuous-pass bug, not a compatibility shim. deny_unknown_fields on the repr means any other unrecognized key is a loud deserialize error instead.

Field	Type	Default	Description
`required_roles`	`list\[str\]`	`[]`	Roles the authenticated caller must have
`required_scopes`	`list\[str\]`	`[]`	OAuth-style scopes the authenticated caller must have
`required_permissions`	`list\[str\]`	`[]`	Fine-grained permissions the authenticated caller must have
`require_all`	`bool`	`True`	When true, the caller must satisfy every listed requirement (AND); when false, any single listed requirement is sufficient (OR)

LifecycleHookRef¶

A single lifecycle hook reference within a LifecycleHooksConfig phase.

Matches the fixture shape exactly (fixtures/lifecycle_hooks.json, fixtures/di.json): each entry is an object with a required name and handler, an optional list of dependency keys, and an optional free-form config blob (e.g. {"max_requests": 10, "window_seconds": 60} for a rate-limiting hook). deny_unknown_fields turns future fixture drift into a loud error.

Field	Type	Default	Description
`name`	`str`	—	Registered name of the hook to run, resolved against the server's `LifecycleHooks`
`handler`	`str`	—	Name of the handler function this hook invokes
`dependencies`	`list\[str\]`	`[]`	Dependency keys this hook requires (for DI), resolved before the hook runs
`config`	`dict\[str, Any\] \\| None`	`None`	Optional free-form configuration passed to the hook (e.g. rate-limit thresholds)
`order`	`int \\| None`	`None`	Explicit execution order within the phase, where the corpus states one (`fixtures/lifecycle_hooks.json`'s `hook_execution_order`). Array position already implies an order, so this exists to let a fixture assert ordering rather than rely on it.

LifecycleHooksConfig¶

Per-route selection of registered lifecycle hooks.

ServerConfig.lifecycle_hooks holds Arc<dyn LifecycleHook> function pointers and is marked #[serde(skip)] / #[alef(skip)] because closures cannot be serialized or cross the FFI boundary. A per-route field with that same shape would be invisible to alef, and therefore invisible to every binding — defeating the purpose of exposing it here. This descriptor carries LifecycleHookRef entries instead: each one names a registered hook (plus its declared dependencies and optional config), so a later enforcement phase can resolve those names against the server's registered LifecycleHooks and run the matches for this route. The five fields mirror the five hook phases documented in the tower-middleware-and-lifecycle project convention (onRequest, preValidation, preHandler, onResponse, onError).

Field	Type	Default	Description
`on_request`	`list\[LifecycleHookRef\]`	`[]`	Hooks to run in the `on_request` phase
`pre_validation`	`list\[LifecycleHookRef\]`	`[]`	Hooks to run in the `pre_validation` phase
`pre_handler`	`list\[LifecycleHookRef\]`	`[]`	Hooks to run in the `pre_handler` phase
`on_response`	`list\[LifecycleHookRef\]`	`[]`	Hooks to run in the `on_response` phase
`on_error`	`list\[LifecycleHookRef\]`	`[]`	Hooks to run in the `on_error` phase

ProblemDetails¶

RFC 9457 Problem Details for HTTP APIs

A machine-readable format for specifying errors in HTTP API responses. Per RFC 9457, all fields are optional. The type field defaults to "about:blank" if not specified.

Content-Type¶

Responses using this struct should set:

Content-Type: application/problem+json

{
  "type": "<https://spikard.dev/errors/validation-error>",
  "title": "Request Validation Failed",
  "status": 422,
  "detail": "2 validation errors in request body",
  "errors": [...]
}

Field	Type	Default	Description
`type_uri`	`str`	`"about:blank"`	A URI reference that identifies the problem type. Defaults to "about:blank" when absent. Should be a stable, human-readable identifier for the problem type.
`title`	`str`	`""`	A short, human-readable summary of the problem type. Should not change from occurrence to occurrence of the problem.
`status`	`int`	`500`	The HTTP status code generated by the origin server. This is advisory; the actual HTTP status code takes precedence.
`detail`	`str \\| None`	`None`	A human-readable explanation specific to this occurrence of the problem.
`instance`	`str \\| None`	`None`	A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
`extensions`	`dict\[str, dict\[str, Any\]\]`	`{}`	Extension members - problem-type-specific data. For validation errors, this typically contains an "errors" array.

GraphQLSubscriptionSnapshot¶

Snapshot of a GraphQL subscription exchange over WebSocket.

Derives Serialize so language bindings (e.g. the JNI backend) can marshal it across the FFI boundary via serde_json without a hand-written wrapper.

Field	Type	Default	Description
`operation_id`	`str`	—	Operation id used for the subscription request.
`acknowledged`	`bool`	—	Whether the server acknowledged the GraphQL WebSocket connection.
`event`	`dict\[str, Any\] \\| None`	`None`	First `next.payload` received for this subscription, if any.
`errors`	`list\[dict\[str, Any\]\]`	`[]`	GraphQL protocol errors emitted by the server.
`complete_received`	`bool`	—	Whether a `complete` frame was observed for this operation.

Enums¶

SecuritySchemeInfo¶

Security scheme types

Variant	Wire value	Description
`Http`	`http`	Http — Fields: `scheme`: `String`, `bearer_format`: `String`
`ApiKey`	`apiKey`	Api key — Fields: `location`: `String`, `name`: `String`

Edit this page on GitHub