Rust API Reference

Rust API Reference v0.17.0¶

Functions¶

schema_query_only()¶

Create a simple schema configuration with only Query type.

This is a convenience function for schemas that only have queries.

Returns:

A QueryOnlyConfig with default settings

Signature:

pub fn schema_query_only() -> QueryOnlyConfig

Example:

let result = schema_query_only();

Returns: QueryOnlyConfig

schema_query_mutation()¶

Create a schema configuration with Query and Mutation types.

This is a convenience function for schemas with queries and mutations but no subscriptions.

Returns:

A QueryMutationConfig with default settings

Signature:

pub fn schema_query_mutation() -> QueryMutationConfig

Example:

let result = schema_query_mutation();

Returns: QueryMutationConfig

schema_full()¶

Create a schema configuration with all three root types.

This is a convenience function for fully-featured schemas.

Returns:

A FullSchemaConfig with default settings

Signature:

pub fn schema_full() -> FullSchemaConfig

Example:

let result = schema_full();

Returns: FullSchemaConfig

handler_result_from_response()¶

Convert a binding-side handler outcome into the framework's HandlerResult.

Binding handler bridges return Result<Response, BoxError> after invoking the host-language callable; this adapter folds the result into the axum-compatible HandlerResult shape the trait dispatch expects.

Signature:

pub fn handler_result_from_response(outcome: Response) -> HandlerResult

Example:

let result = handler_result_from_response(Response::default());

Parameters:

Name	Type	Required	Description
`outcome`	`Response`	Yes	The response

Returns: HandlerResult

Types¶

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`	`Vec<String>`	`/* 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`	`String`	`"X-API-Key"`	Header name to check (e.g., "X-API-Key")

ApiKeyConfig¶

API Key authentication configuration

Field	Type	Default	Description
`keys`	`Vec<String>`	—	Valid API keys
`header_name`	`String`	`"X-API-Key"`	Header name to check (e.g., "X-API-Key")

App¶

Spikard application builder.

Methods¶

new()¶

Create a new application with the default server configuration.

Signature:

pub fn new() -> App

Example:

let result = App::new();

Returns: App

on_request()¶

Register an on_request lifecycle hook (runs before validation and handler dispatch).

Signature:

pub fn on_request(&mut self, hook: String) -> App

Example:

let result = instance.on_request("value");

Parameters:

Name	Type	Required	Description
`hook`	`String`	Yes	The hook

Returns: App

pre_validation()¶

Register a pre_validation lifecycle hook (runs after on_request, before validation).

Signature:

pub fn pre_validation(&mut self, hook: String) -> App

Example:

let result = instance.pre_validation("value");

Parameters:

Name	Type	Required	Description
`hook`	`String`	Yes	The hook

Returns: App

pre_handler()¶

Register a pre_handler lifecycle hook (runs after validation, before the handler).

Signature:

pub fn pre_handler(&mut self, hook: String) -> App

Example:

let result = instance.pre_handler("value");

Parameters:

Name	Type	Required	Description
`hook`	`String`	Yes	The hook

Returns: App

on_response()¶

Register an on_response lifecycle hook (runs after a successful handler response).

Signature:

pub fn on_response(&mut self, hook: String) -> App

Example:

let result = instance.on_response("value");

Parameters:

Name	Type	Required	Description
`hook`	`String`	Yes	The hook

Returns: App

on_error()¶

Register an on_error lifecycle hook (runs when the handler returns an error).

Signature:

pub fn on_error(&mut self, hook: String) -> App

Example:

let result = instance.on_error("value");

Parameters:

Name	Type	Required	Description
`hook`	`String`	Yes	The hook

Returns: App

register_graphql_route()¶

Register a /graphql-style route backed by one of Spikard's built-in async-graphql test schemas.

This is a binding-friendly entry point: unlike spikard_graphql::GraphQLHandler, which is generic over the GraphQL root types and therefore cannot cross an FFI boundary, this method is monomorphic. Callers select a schema by name and the concrete GraphQLHandler<Query, Mutation, Subscription> is constructed internally and registered as an Arc<dyn Handler>.

The built-in schemas exist to exercise Spikard's GraphQL execution path end to end (see fixtures/graphql_schema.json); they are not meant to be extended with application-specific fields. Hosts that need a custom GraphQL schema should build their own GraphQLHandler in Rust and register it via App::route.

Errors:

Returns AppError::GraphQL if schema_type is not a recognized built-in schema name, and AppError::Route if route construction fails.

Signature:

pub fn register_graphql_route(&mut self, path: String, method: Method, schema_type: &str, config: &SchemaConfig) -> Result<App, AppError>

Example:

let result = instance.register_graphql_route("value", Method::default(), "value", &SchemaConfig::default())?;

Parameters:

Name	Type	Required	Description
`path`	`String`	Yes	The HTTP path to serve GraphQL requests on (e.g. `/graphql`).
`method`	`Method`	Yes	The HTTP method to accept (fixtures always use `POST`).
`schema_type`	`&str`	Yes	One of `"query_only"`, `"query_mutation"`, or `"full"`.
`config`	`&SchemaConfig`	Yes	Introspection/complexity/depth limits applied to the selected schema.

Returns: App

Errors: Returns Err(AppError).

register_graphql_sdl_route()¶

Register a /graphql-style route backed by an arbitrary SDL schema string, with field resolution driven by a static response_data JSON tree instead of hand-written Rust resolvers.

This is the dynamic-schema counterpart to App::register_graphql_route: instead of selecting one of Spikard's built-in test schemas by name, callers supply their own SDL and a JSON tree shaped like the successful data payload each query should produce. Every field resolver is generic — it navigates response_data by field name — so argument-dependent results (e.g. user(id: "user-42")) must already be baked into response_data at the correct path. See spikard_graphql::dynamic for the full resolver-data encoding and field-level-error support via config.field_errors.

Errors:

Returns AppError::GraphQL if the SDL cannot be parsed or fails dynamic-schema validation (e.g. an unsupported type kind, duplicate field names), and AppError::Route if route construction fails.

Signature:

pub fn register_graphql_sdl_route(&mut self, path: String, method: Method, sdl: &str, response_data: serde_json::Value, config: &DynamicSchemaConfig) -> Result<App, AppError>

Example:

let result = instance.register_graphql_sdl_route("value", Method::default(), "value", std::collections::HashMap::new(), &DynamicSchemaConfig::default())?;

Parameters:

Name	Type	Required	Description
`path`	`String`	Yes	The HTTP path to serve GraphQL requests on (e.g. `/graphql`).
`method`	`Method`	Yes	The HTTP method to accept (fixtures always use `POST`).
`sdl`	`&str`	Yes	The GraphQL SDL schema string (object and input-object types only).
`response_data`	`serde_json::Value`	Yes	JSON tree resolvers navigate by field name to produce query results.
`config`	`&DynamicSchemaConfig`	Yes	Introspection/complexity/depth limits and field-level error injection.

Returns: App

Errors: Returns Err(AppError).

merge_axum_router()¶

Attach an existing Axum router to this application, returning ownership.

Signature:

pub fn merge_axum_router(self, router: String) -> App

Example:

let result = instance.merge_axum_router("value");

Parameters:

Name	Type	Required	Description
`router`	`String`	Yes	The router

Returns: App

attach_axum_router()¶

Attach an Axum router using a mutable reference for incremental configuration.

Signature:

pub fn attach_axum_router(&mut self, router: String) -> App

Example:

let result = instance.attach_axum_router("value");

Parameters:

Name	Type	Required	Description
`router`	`String`	Yes	The router

Returns: App

into_router()¶

Build the underlying Axum router.

Errors:

Returns an error if server or router construction fails.

Signature:

pub fn into_router(self) -> Result<String, AppError>

Example:

let result = instance.into_router()?;

Returns: String

Errors: Returns Err(AppError).

into_router_and_config()¶

Decompose the application into its Axum router and server configuration.

This is the low-level escape hatch used by the C FFI layer to start the server on a background thread while retaining the bind address from the caller-supplied ServerConfig. Prefer App::run for normal use.

Errors:

Returns an error if router construction fails.

Signature:

pub fn into_router_and_config(self) -> Result<String, AppError>

Example:

let result = instance.into_router_and_config()?;

Returns: String

Errors: Returns Err(AppError).

default()¶

Signature:

pub fn default() -> App

Example:

let result = App::default();

Returns: App

AsyncApiConfig¶

AsyncAPI HTTP endpoint configuration

Field	Type	Default	Description
`enabled`	`bool`	—	Enable AsyncAPI endpoints (default: false)
`spec`	`Option<serde_json::Value>`	`Default::default()`	Pre-registered AsyncAPI spec to serve from GET /asyncapi.json

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`	`Vec<String>`	`vec![]`	Roles the authenticated caller must have
`required_scopes`	`Vec<String>`	`vec![]`	OAuth-style scopes the authenticated caller must have
`required_permissions`	`Vec<String>`	`vec![]`	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)

Methods¶

default()¶

Signature:

pub fn default() -> AuthorizationConfig

Example:

let result = AuthorizationConfig::default();

Returns: AuthorizationConfig

BackgroundJobMetadata¶

Field	Type	Default	Description
`name`	`String`	`"background_task"`	The name
`request_id`	`Option<String>`	`None`	Request id

Methods¶

default()¶

Signature:

pub fn default() -> BackgroundJobMetadata

Example:

let result = BackgroundJobMetadata::default();

Returns: BackgroundJobMetadata

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`	`usize`	`1024`	Maximum queue size
`max_concurrent_tasks`	`usize`	`128`	Maximum concurrent tasks
`drain_timeout_secs`	`u64`	`30`	Drain timeout secs

Methods¶

default()¶

Signature:

pub fn default() -> BackgroundTaskConfig

Example:

let result = BackgroundTaskConfig::default();

Returns: BackgroundTaskConfig

CompressionConfig¶

Compression configuration shared across runtimes

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

Methods¶

default()¶

Signature:

pub fn default() -> CompressionConfig

Example:

let result = CompressionConfig::default();

Returns: CompressionConfig

ContactInfo¶

Contact information

Field	Type	Default	Description
`name`	`Option<String>`	`None`	Name of the contact person or organisation.
`email`	`Option<String>`	`None`	Contact email address.
`url`	`Option<String>`	`None`	URL pointing to the contact information page.

CorsConfig¶

CORS configuration for a route

Field	Type	Default	Description
`allowed_origins`	`Vec<String>`	`["*"]`	Allowed origins
`allowed_methods`	`Vec<String>`	`["*"]`	Allowed methods
`allowed_headers`	`Vec<String>`	`vec![]`	Allowed headers
`expose_headers`	`Option<Vec<String>>`	`None`	Expose headers
`max_age`	`Option<u32>`	`None`	Maximum age
`allow_credentials`	`Option<bool>`	`None`	Allow credentials
`methods_joined_cache`	`OnceLock`	`OnceLock::new()`	Methods joined cache
`headers_joined_cache`	`OnceLock`	`OnceLock::new()`	Headers joined cache

Methods¶

allowed_methods_joined()¶

Get the cached joined methods string for preflight responses

Signature:

pub fn allowed_methods_joined(&self) -> String

Example:

let result = instance.allowed_methods_joined();

Returns: String

allowed_headers_joined()¶

Get the cached joined headers string for preflight responses

Signature:

pub fn allowed_headers_joined(&self) -> String

Example:

let result = instance.allowed_headers_joined();

Returns: String

is_origin_allowed()¶

Check if an origin is allowed (O(1) with wildcard, O(n) for exact match)

Signature:

pub fn is_origin_allowed(&self, origin: &str) -> bool

Example:

let result = instance.is_origin_allowed("value");

Parameters:

Name	Type	Required	Description
`origin`	`&str`	Yes	The origin

Returns: bool

is_method_allowed()¶

Check if a method is allowed (O(1) with wildcard, O(n) for exact match)

Signature:

pub fn is_method_allowed(&self, method: &str) -> bool

Example:

let result = instance.is_method_allowed("value");

Parameters:

Name	Type	Required	Description
`method`	`&str`	Yes	The method

Returns: bool

default()¶

Signature:

pub fn default() -> CorsConfig

Example:

let result = CorsConfig::default();

Returns: CorsConfig

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`	`Option<usize>`	`Default::default()`	Maximum query complexity (`None` = unlimited).
`max_depth`	`Option<usize>`	`Default::default()`	Maximum query depth (`None` = unlimited).
`field_errors`	`Vec<FieldErrorSpec>`	`vec![]`	Field-level errors to inject at specific response paths.

FieldErrorSpec¶

A field-level error to inject at a specific response path.

path is the dot-separated sequence of field names from the operation root to the field that should fail, e.g. "user" for a top-level field or "order.customer" for a nested one.

Field	Type	Default	Description
`path`	`String`	—	Dot-separated path to the field that should error.
`message`	`String`	—	The error message to surface for that field.

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`	`Option<usize>`	`None`	Maximum query complexity (None = unlimited)
`depth_limit`	`Option<usize>`	`None`	Maximum query depth (None = unlimited)

Methods¶

default()¶

Signature:

pub fn default() -> FullSchemaConfig

Example:

let result = FullSchemaConfig::default();

Returns: FullSchemaConfig

GraphQlRouteConfig¶

Configuration for GraphQL routes

Provides a builder pattern for configuring GraphQL route parameters for the Spikard HTTP server's routing system.

Methods¶

new()¶

Create a new GraphQL route configuration with defaults

Default values:

path: "/graphql"
method: "POST"
enable_playground: false

Signature:

pub fn new() -> GraphQlRouteConfig

Example:

let result = GraphQlRouteConfig::new();

Returns: GraphQlRouteConfig

path()¶

Set the HTTP path for the GraphQL endpoint

Signature:

pub fn path(self, path: String) -> GraphQlRouteConfig

Example:

let result = instance.path("value");

Parameters:

Name	Type	Required	Description
`path`	`String`	Yes	The URL path (e.g., "/graphql", "/api/graphql")

Returns: GraphQlRouteConfig

method()¶

Set the HTTP method for the GraphQL endpoint

Signature:

pub fn method(self, method: String) -> GraphQlRouteConfig

Example:

let result = instance.method("value");

Parameters:

Name	Type	Required	Description
`method`	`String`	Yes	The HTTP method (typically "POST")

Returns: GraphQlRouteConfig

enable_playground()¶

Enable or disable the GraphQL Playground UI

Signature:

pub fn enable_playground(self, enable: bool) -> GraphQlRouteConfig

Example:

let result = instance.enable_playground(true);

Parameters:

Name	Type	Required	Description
`enable`	`bool`	Yes	Whether to enable playground

Returns: GraphQlRouteConfig

description()¶

Set a custom description for documentation

Signature:

pub fn description(self, description: String) -> GraphQlRouteConfig

Example:

let result = instance.description("value");

Parameters:

Name	Type	Required	Description
`description`	`String`	Yes	Documentation string

Returns: GraphQlRouteConfig

get_path()¶

Get the configured path

Signature:

pub fn get_path(&self) -> String

Example:

let result = instance.get_path();

Returns: String

get_method()¶

Get the configured method

Signature:

pub fn get_method(&self) -> String

Example:

let result = instance.get_method();

Returns: String

is_playground_enabled()¶

Check if playground is enabled

Signature:

pub fn is_playground_enabled(&self) -> bool

Example:

let result = instance.is_playground_enabled();

Returns: bool

get_description()¶

Get the description if set

Signature:

pub fn get_description(&self) -> Option<String>

Example:

let result = instance.get_description();

Returns: Option<String>

default()¶

Signature:

pub fn default() -> GraphQlRouteConfig

Example:

let result = GraphQlRouteConfig::default();

Returns: GraphQlRouteConfig

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`	`String`	—	Operation id used for the subscription request.
`acknowledged`	`bool`	—	Whether the server acknowledged the GraphQL WebSocket connection.
`event`	`Option<serde_json::Value>`	`Default::default()`	First `next.payload` received for this subscription, if any.
`errors`	`Vec<serde_json::Value>`	`vec![]`	GraphQL protocol errors emitted by the server.
`complete_received`	`bool`	—	Whether a `complete` frame was observed for this operation.

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`	`usize`	`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`	`Option<u64>`	`None`	Timeout for gRPC requests in seconds (None = no timeout)
`max_concurrent_streams`	`u32`	`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`	`u64`	`75`	HTTP/2 keepalive interval in seconds
`keepalive_timeout`	`u64`	`20`	HTTP/2 keepalive timeout in seconds
`max_stream_response_bytes`	`Option<usize>`	`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).

Methods¶

default()¶

Signature:

pub fn default() -> GrpcConfig

Example:

let result = GrpcConfig::default();

Returns: GrpcConfig

Handler¶

Handler trait that all language bindings must implement

This trait is completely language-agnostic. Each binding (Python, Node, WASM) implements this trait to bridge their runtime to our HTTP server.

Methods¶

call()¶

Handle an HTTP request

Takes the extracted request data and returns a future that resolves to either:

Ok(Response): A successful HTTP response
Err((StatusCode, String)): An error with status code and message

Signature:

pub async fn call(&self, request: Request, request_data: RequestData) -> HandlerResult

Example:

let result = instance.call(Request::default(), RequestData::default()).await;

Parameters:

Name	Type	Required	Description
`request`	`Request`	Yes	The request
`request_data`	`RequestData`	Yes	The request data

Returns: HandlerResult

prefers_raw_json_body()¶

Whether this handler prefers consuming RequestData::raw_body over the parsed RequestData::body for JSON requests.

When true, the server may skip eager JSON parsing when there is no request-body schema validator attached to the route.

Signature:

pub fn prefers_raw_json_body(&self) -> bool

Example:

let result = instance.prefers_raw_json_body();

Returns: bool

prefers_parameter_extraction()¶

Whether this handler wants to perform its own parameter validation/extraction (path/query/header/cookie).

When true, the server will skip ParameterValidator::validate_and_extract in ValidatingHandler. This is useful for language bindings which need to transform validated parameters into language-specific values (e.g., Python kwargs) without duplicating work. When false, the server stores validated output in RequestData::validated_params.

Signature:

pub fn prefers_parameter_extraction(&self) -> bool

Example:

let result = instance.prefers_parameter_extraction();

Returns: bool

wants_headers()¶

Whether this handler needs the parsed headers map in RequestData.

When false, the server may skip building RequestData::headers for requests without a body. (Requests with bodies still typically need Content-Type decisions.)

Signature:

pub fn wants_headers(&self) -> bool

Example:

let result = instance.wants_headers();

Returns: bool

wants_cookies()¶

Whether this handler needs the parsed cookies map in RequestData.

When false, the server may skip parsing cookies for requests without a body.

Signature:

pub fn wants_cookies(&self) -> bool

Example:

let result = instance.wants_cookies();

Returns: bool

wants_request_extensions()¶

Whether this handler needs RequestData stored in request extensions.

When false, the server avoids inserting RequestData into extensions to skip cloning in hot paths.

Signature:

pub fn wants_request_extensions(&self) -> bool

Example:

let result = instance.wants_request_extensions();

Returns: bool

static_response()¶

Return a pre-built static response if this handler always produces the same output. When Some, the server bypasses the full middleware pipeline and serves the pre-built response directly.

Signature:

pub fn static_response(&self) -> Option<StaticResponse>

Example:

let result = instance.static_response();

Returns: Option<StaticResponse>

IntoHandler¶

Convert user-facing handler functions into the low-level Handler trait.

Methods¶

into_handler()¶

Convert this value into a shared request handler.

Signature:

pub fn into_handler(self) -> Handler

Example:

let result = instance.into_handler();

Returns: Handler

JsonRpcConfig¶

JSON-RPC server configuration

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

Methods¶

default()¶

Signature:

pub fn default() -> JsonRpcConfig

Example:

let result = JsonRpcConfig::default();

Returns: JsonRpcConfig

JsonRpcMethodInfo¶

JSON-RPC method metadata for routes that support JSON-RPC

This struct captures the metadata needed to expose HTTP routes as JSON-RPC methods, enabling discovery and documentation of RPC-compatible endpoints.

Field	Type	Default	Description
`method_name`	`String`	—	The JSON-RPC method name (e.g., "user.create")
`description`	`Option<String>`	`None`	Optional description of what the method does
`params_schema`	`Option<serde_json::Value>`	`None`	Optional JSON Schema for method parameters
`result_schema`	`Option<serde_json::Value>`	`None`	Optional JSON Schema for the result
`deprecated`	`bool`	`/* serde(default) */`	Whether this method is deprecated
`tags`	`Vec<String>`	`/* serde(default) */`	Tags for categorizing and grouping methods

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`	`Option<String>`	`/* serde(default) */`	Symmetric secret key for JWT verification (HS256, HS384, HS512)
`public_key`	`Option<String>`	`/* serde(default) */`	Asymmetric public key for JWT verification (RS256, ES256, etc.)
`algorithm`	`String`	`"HS256"`	Required algorithm (HS256, HS384, HS512, RS256, etc.)
`audience`	`Option<Vec<String>>`	`None`	Required audience claim
`issuer`	`Option<String>`	`None`	Required issuer claim
`leeway`	`u64`	`/* serde(default) */`	Leeway for expiration checks (seconds)

JwtConfig¶

JWT authentication configuration

Field	Type	Default	Description
`secret`	`String`	—	Secret key for JWT verification
`algorithm`	`String`	`"HS256"`	Required algorithm (HS256, HS384, HS512, RS256, etc.)
`audience`	`Option<Vec<String>>`	`None`	Required audience claim
`issuer`	`Option<String>`	`None`	Required issuer claim
`leeway`	`u64`	`/* serde(default) */`	Leeway for expiration checks (seconds)

LicenseInfo¶

License information

Field	Type	Default	Description
`name`	`String`	—	SPDX license identifier or display name (e.g. `"MIT"`).
`url`	`Option<String>`	`None`	URL to the full license text.

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`	`String`	—	Registered name of the hook to run, resolved against the server's `LifecycleHooks`
`handler`	`String`	—	Name of the handler function this hook invokes
`dependencies`	`Vec<String>`	`vec![]`	Dependency keys this hook requires (for DI), resolved before the hook runs
`config`	`Option<serde_json::Value>`	`Default::default()`	Optional free-form configuration passed to the hook (e.g. rate-limit thresholds)
`order`	`Option<u32>`	`Default::default()`	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`	`Vec<LifecycleHookRef>`	`vec![]`	Hooks to run in the `on_request` phase
`pre_validation`	`Vec<LifecycleHookRef>`	`vec![]`	Hooks to run in the `pre_validation` phase
`pre_handler`	`Vec<LifecycleHookRef>`	`vec![]`	Hooks to run in the `pre_handler` phase
`on_response`	`Vec<LifecycleHookRef>`	`vec![]`	Hooks to run in the `on_response` phase
`on_error`	`Vec<LifecycleHookRef>`	`vec![]`	Hooks to run in the `on_error` phase

OpenApiConfig¶

OpenAPI configuration

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

Methods¶

default()¶

Signature:

pub fn default() -> OpenApiConfig

Example:

let result = OpenApiConfig::default();

Returns: OpenApiConfig

ParseRequest¶

Request body for POST /asyncapi/parse

Field	Type	Default	Description
`spec`	`serde_json::Value`	—	Spec

ParseResult¶

Full parse result returned by POST /asyncapi/parse

Field	Type	Default	Description
`spec_version`	`String`	—	Spec version
`title`	`String`	—	Title
`api_version`	`String`	—	Api version
`channels`	`Vec<ParsedChannel>`	—	Channels
`operations`	`Vec<ParsedOperation>`	—	Operations
`messages`	`Vec<ParsedMessage>`	—	Messages

ParsedChannel¶

A single channel extracted from an AsyncAPI spec

Field	Type	Default	Description
`name`	`String`	—	Channel key from the spec (e.g. "chat/messages")
`address`	`String`	—	Channel address / path
`messages`	`Vec<String>`	—	Message names declared on this channel
`bindings`	`Option<serde_json::Value>`	`None`	Bindings (ws / http / amqp / …) as raw JSON for forward-compatibility

ParsedMessage¶

A resolved message (name + JSON Schema)

Field	Type	Default	Description
`name`	`String`	—	Message name
`schema`	`Option<serde_json::Value>`	`None`	Resolved JSON Schema for the message payload, if available

ParsedOperation¶

A single operation extracted from an AsyncAPI spec

Field	Type	Default	Description
`name`	`String`	—	Operation name
`action`	`String`	—	Operation action: "send" or "receive"
`channel`	`String`	—	Channel reference (resolved to the channel name)

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`	`String`	`"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`	`String`	`""`	A short, human-readable summary of the problem type. Should not change from occurrence to occurrence of the problem.
`status`	`u16`	`500`	The HTTP status code generated by the origin server. This is advisory; the actual HTTP status code takes precedence.
`detail`	`Option<String>`	`None`	A human-readable explanation specific to this occurrence of the problem.
`instance`	`Option<String>`	`None`	A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
`extensions`	`HashMap<String, serde_json::Value>`	`HashMap::new()`	Extension members - problem-type-specific data. For validation errors, this typically contains an "errors" array.

Methods¶

default()¶

Signature:

pub fn default() -> ProblemDetails

Example:

let result = ProblemDetails::default();

Returns: ProblemDetails

with_detail()¶

Set the detail field

Signature:

pub fn with_detail(self, detail: String) -> ProblemDetails

Example:

let result = instance.with_detail("value");

Parameters:

Name	Type	Required	Description
`detail`	`String`	Yes	The detail

Returns: ProblemDetails

with_instance()¶

Set the instance field

Signature:

pub fn with_instance(self, instance: String) -> ProblemDetails

Example:

let result = instance.with_instance("value");

Parameters:

Name	Type	Required	Description
`instance`	`String`	Yes	The instance

Returns: ProblemDetails

not_found()¶

Create a not found error

Signature:

pub fn not_found(detail: String) -> ProblemDetails

Example:

let result = ProblemDetails::not_found("value");

Parameters:

Name	Type	Required	Description
`detail`	`String`	Yes	The detail

Returns: ProblemDetails

method_not_allowed()¶

Create a method not allowed error

Signature:

pub fn method_not_allowed(detail: String) -> ProblemDetails

Example:

let result = ProblemDetails::method_not_allowed("value");

Parameters:

Name	Type	Required	Description
`detail`	`String`	Yes	The detail

Returns: ProblemDetails

internal_server_error()¶

Create an internal server error

Signature:

pub fn internal_server_error(detail: String) -> ProblemDetails

Example:

let result = ProblemDetails::internal_server_error("value");

Parameters:

Name	Type	Required	Description
`detail`	`String`	Yes	The detail

Returns: ProblemDetails

bad_request()¶

Create a bad request error

Signature:

pub fn bad_request(detail: String) -> ProblemDetails

Example:

let result = ProblemDetails::bad_request("value");

Parameters:

Name	Type	Required	Description
`detail`	`String`	Yes	The detail

Returns: ProblemDetails

to_json()¶

Serialize to JSON string

Errors: Returns an error if the serialization fails.

Signature:

pub fn to_json(&self) -> Result<String, Error>

Example:

let result = instance.to_json()?;

Returns: String

Errors: Returns Err(Error).

to_json_pretty()¶

Serialize to pretty JSON string

Errors: Returns an error if the serialization fails.

Signature:

pub fn to_json_pretty(&self) -> Result<String, Error>

Example:

let result = instance.to_json_pretty()?;

Returns: String

Errors: Returns Err(Error).

QueryMutationConfig¶

Configuration for schemas with Query and Mutation types

Field	Type	Default	Description
`introspection_enabled`	`bool`	`true`	Enable introspection queries
`complexity_limit`	`Option<usize>`	`None`	Maximum query complexity (None = unlimited)
`depth_limit`	`Option<usize>`	`None`	Maximum query depth (None = unlimited)

Methods¶

default()¶

Signature:

pub fn default() -> QueryMutationConfig

Example:

let result = QueryMutationConfig::default();

Returns: QueryMutationConfig

QueryOnlyConfig¶

Configuration for schemas with only Query type

Field	Type	Default	Description
`introspection_enabled`	`bool`	`true`	Enable introspection queries
`complexity_limit`	`Option<usize>`	`None`	Maximum query complexity (None = unlimited)
`depth_limit`	`Option<usize>`	`None`	Maximum query depth (None = unlimited)

Methods¶

default()¶

Signature:

pub fn default() -> QueryOnlyConfig

Example:

let result = QueryOnlyConfig::default();

Returns: QueryOnlyConfig

RateLimitConfig¶

Rate limiting configuration shared across runtimes

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

Methods¶

default()¶

Signature:

pub fn default() -> RateLimitConfig

Example:

let result = RateLimitConfig::default();

Returns: RateLimitConfig

Request¶

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

Response¶

HTTP Response with custom status code, headers, and content

Field	Type	Default	Description
`content`	`Option<serde_json::Value>`	`None`	Response body content
`status_code`	`u16`	`200`	HTTP status code (defaults to 200)
`headers`	`HashMap<String, String>`	`HashMap::new()`	Response headers

Methods¶

set_header()¶

Set a header

Signature:

pub fn set_header(&mut self, key: String, value: String)

Example:

instance.set_header("value", "value");

Parameters:

Name	Type	Required	Description
`key`	`String`	Yes	The key
`value`	`String`	Yes	The value

Returns: No return value.

set_cookie()¶

Set a cookie in the response

Signature:

pub fn set_cookie(&mut self, key: String, value: String, secure: bool, http_only: bool, max_age: Option<i64>, domain: Option<String>, path: Option<String>, same_site: Option<String>)

Example:

instance.set_cookie("value", "value", true, true, 42, "value", "value", "value");

Parameters:

Name	Type	Required	Description
`key`	`String`	Yes	The key
`value`	`String`	Yes	The value
`secure`	`bool`	Yes	The secure
`http_only`	`bool`	Yes	The http only
`max_age`	`Option<i64>`	No	The max age
`domain`	`Option<String>`	No	The domain
`path`	`Option<String>`	No	Path to the file
`same_site`	`Option<String>`	No	The same site

Returns: No return value.

default()¶

Signature:

pub fn default() -> Response

Example:

let result = Response::default();

Returns: Response

ResponseSnapshot¶

Snapshot of an Axum response used by higher-level language bindings.

Field	Type	Default	Description
`status`	`u16`	—	HTTP status code.
`headers`	`HashMap<String, String>`	—	Response headers (lowercase keys for predictable lookups).
`body`	`Vec<u8>`	—	Response body bytes (decoded for supported encodings).

Methods¶

text()¶

Return response body as UTF-8 string.

Signature:

pub fn text(&self) -> Result<String, FromUtf8Error>

Example:

let result = instance.text()?;

Returns: String

Errors: Returns Err(FromUtf8Error).

Lookup header by case-insensitive name.

Signature:

pub fn header(&self, name: &str) -> Option<String>

Example:

let result = instance.header("value");

Parameters:

Name	Type	Required	Description
`name`	`&str`	Yes	The name

Returns: Option<String>

RouteBuilder¶

Builder for defining a route.

Methods¶

new()¶

Create a new builder for the provided HTTP method and path.

Signature:

pub fn new(method: Method, path: String) -> RouteBuilder

Example:

let result = RouteBuilder::new(Method::default(), "value");

Parameters:

Name	Type	Required	Description
`method`	`Method`	Yes	The method
`path`	`String`	Yes	Path to the file

Returns: RouteBuilder

handler_name()¶

Assign an explicit handler name.

Signature:

pub fn handler_name(self, name: String) -> RouteBuilder

Example:

let result = instance.handler_name("value");

Parameters:

Name	Type	Required	Description
`name`	`String`	Yes	The name

Returns: RouteBuilder

request_schema_json()¶

Provide a raw JSON schema for the request body.

Signature:

pub fn request_schema_json(self, schema: serde_json::Value) -> RouteBuilder

Example:

let result = instance.request_schema_json(std::collections::HashMap::new());

Parameters:

Name	Type	Required	Description
`schema`	`serde_json::Value`	Yes	The schema

Returns: RouteBuilder

response_schema_json()¶

Provide a raw JSON schema for the response body.

Signature:

pub fn response_schema_json(self, schema: serde_json::Value) -> RouteBuilder

Example:

let result = instance.response_schema_json(std::collections::HashMap::new());

Parameters:

Name	Type	Required	Description
`schema`	`serde_json::Value`	Yes	The schema

Returns: RouteBuilder

params_schema_json()¶

Provide a raw JSON schema for request parameters.

Signature:

pub fn params_schema_json(self, schema: serde_json::Value) -> RouteBuilder

Example:

let result = instance.params_schema_json(std::collections::HashMap::new());

Parameters:

Name	Type	Required	Description
`schema`	`serde_json::Value`	Yes	The schema

Returns: RouteBuilder

file_params_json()¶

Provide multipart file parameter configuration.

Signature:

pub fn file_params_json(self, schema: serde_json::Value) -> RouteBuilder

Example:

let result = instance.file_params_json(std::collections::HashMap::new());

Parameters:

Name	Type	Required	Description
`schema`	`serde_json::Value`	Yes	The schema

Returns: RouteBuilder

cors()¶

Attach a CORS configuration for this route.

Signature:

pub fn cors(self, cors: CorsConfig) -> RouteBuilder

Example:

let result = instance.cors(CorsConfig::default());

Parameters:

Name	Type	Required	Description
`cors`	`CorsConfig`	Yes	The cors config

Returns: RouteBuilder

compression()¶

Attach a compression configuration for this route.

Signature:

pub fn compression(self, compression: CompressionConfig) -> RouteBuilder

Example:

let result = instance.compression(CompressionConfig::default());

Parameters:

Name	Type	Required	Description
`compression`	`CompressionConfig`	Yes	The compression config

Returns: RouteBuilder

body_limit()¶

Attach a per-route maximum request body size in bytes, overriding the server-global default.

Signature:

pub fn body_limit(self, max_bytes: usize) -> RouteBuilder

Example:

let result = instance.body_limit(42);

Parameters:

Name	Type	Required	Description
`max_bytes`	`usize`	Yes	The max bytes

Returns: RouteBuilder

request_timeout()¶

Attach a per-route request timeout in seconds, overriding the server-global default.

Signature:

pub fn request_timeout(self, seconds: u64) -> RouteBuilder

Example:

let result = instance.request_timeout(42);

Parameters:

Name	Type	Required	Description
`seconds`	`u64`	Yes	The seconds

Returns: RouteBuilder

rate_limit()¶

Attach a per-route rate limiting configuration, overriding the server-global default.

Signature:

pub fn rate_limit(self, rate_limit: RateLimitConfig) -> RouteBuilder

Example:

let result = instance.rate_limit(RateLimitConfig::default());

Parameters:

Name	Type	Required	Description
`rate_limit`	`RateLimitConfig`	Yes	The rate limit config

Returns: RouteBuilder

request_id()¶

Force per-route request-id generation on or off, overriding the server-global default.

Takes a plain bool rather than RequestIdConfig directly: the wire/metadata type had to become a struct to represent {"enabled": false} (see RequestIdConfig's docs), but this builder is the ergonomic call site (.request_id(true)), so it keeps accepting a bool and wraps it into RequestIdConfig internally in Self::into_metadata.

Signature:

pub fn request_id(self, enabled: bool) -> RouteBuilder

Example:

let result = instance.request_id(true);

Parameters:

Name	Type	Required	Description
`enabled`	`bool`	Yes	The enabled

Returns: RouteBuilder

jwt_auth()¶

Require JWT authentication for this route.

Signature:

pub fn jwt_auth(self, config: JwtAuthConfig) -> RouteBuilder

Example:

let result = instance.jwt_auth(JwtAuthConfig::default());

Parameters:

Name	Type	Required	Description
`config`	`JwtAuthConfig`	Yes	The configuration options

Returns: RouteBuilder

api_key_auth()¶

Require API key authentication for this route.

Signature:

pub fn api_key_auth(self, config: ApiKeyAuthConfig) -> RouteBuilder

Example:

let result = instance.api_key_auth(ApiKeyAuthConfig::default());

Parameters:

Name	Type	Required	Description
`config`	`ApiKeyAuthConfig`	Yes	The configuration options

Returns: RouteBuilder

authorization()¶

Attach a roles/scopes/permissions authorization requirement for this route.

Signature:

pub fn authorization(self, config: AuthorizationConfig) -> RouteBuilder

Example:

let result = instance.authorization(AuthorizationConfig::default());

Parameters:

Name	Type	Required	Description
`config`	`AuthorizationConfig`	Yes	The configuration options

Returns: RouteBuilder

lifecycle_hooks()¶

Select registered lifecycle hooks to run for this route.

Signature:

pub fn lifecycle_hooks(self, hooks: LifecycleHooksConfig) -> RouteBuilder

Example:

let result = instance.lifecycle_hooks(LifecycleHooksConfig::default());

Parameters:

Name	Type	Required	Description
`hooks`	`LifecycleHooksConfig`	Yes	The lifecycle hooks config

Returns: RouteBuilder

jsonrpc_method()¶

Expose this route as a JSON-RPC method.

Signature:

pub fn jsonrpc_method(self, info: JsonRpcMethodInfo) -> RouteBuilder

Example:

let result = instance.jsonrpc_method(JsonRpcMethodInfo::default());

Parameters:

Name	Type	Required	Description
`info`	`JsonRpcMethodInfo`	Yes	The json rpc method info

Returns: RouteBuilder

openrpc_spec()¶

Attach a literal OpenRPC method spec document for this route, overriding auto-derivation from the Self::jsonrpc_method metadata when present.

Signature:

pub fn openrpc_spec(self, spec: serde_json::Value) -> RouteBuilder

Example:

let result = instance.openrpc_spec(std::collections::HashMap::new());

Parameters:

Name	Type	Required	Description
`spec`	`serde_json::Value`	Yes	The spec

Returns: RouteBuilder

sync()¶

Mark the route as synchronous.

Signature:

pub fn sync(self) -> RouteBuilder

Example:

let result = instance.sync();

Returns: RouteBuilder

handler_dependencies()¶

Declare the dependency keys that must be resolved before this handler runs.

Signature:

pub fn handler_dependencies(self, dependencies: Vec<String>) -> RouteBuilder

Example:

let result = instance.handler_dependencies(vec![]);

Parameters:

Name	Type	Required	Description
`dependencies`	`Vec<String>`	Yes	The dependencies

Returns: RouteBuilder

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`	`Option<usize>`	`None`	Maximum query complexity (None = unlimited)
`depth_limit`	`Option<usize>`	`None`	Maximum query depth (None = unlimited)

Methods¶

default()¶

Signature:

pub fn default() -> SchemaConfig

Example:

let result = SchemaConfig::default();

Returns: SchemaConfig

ServerConfig¶

Server configuration

Field	Type	Default	Description
`host`	`String`	`"127.0.0.1"`	Host to bind to
`port`	`u16`	`8000`	Port to bind to
`workers`	`usize`	`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`	`Option<usize>`	`10485760`	Maximum request body size in bytes (None = unlimited, not recommended)
`request_timeout`	`Option<u64>`	`None`	Request timeout in seconds (None = no timeout)
`compression`	`Option<CompressionConfig>`	`None`	Enable compression middleware
`rate_limit`	`Option<RateLimitConfig>`	`None`	Enable rate limiting
`jwt_auth`	`Option<JwtConfig>`	`None`	JWT authentication configuration
`api_key_auth`	`Option<ApiKeyConfig>`	`None`	API Key authentication configuration
`static_files`	`Vec<StaticFilesConfig>`	`vec![]`	Static file serving configuration
`graceful_shutdown`	`bool`	`true`	Enable graceful shutdown on SIGTERM/SIGINT
`shutdown_timeout`	`u64`	`30`	Graceful shutdown timeout (seconds)
`asyncapi`	`Option<AsyncApiConfig>`	`None`	AsyncAPI HTTP endpoint configuration
`openapi`	`Option<OpenApiConfig>`	`None`	OpenAPI documentation configuration
`jsonrpc`	`Option<JsonRpcConfig>`	`None`	JSON-RPC configuration
`grpc`	`Option<GrpcConfig>`	`None`	gRPC configuration
`lifecycle_hooks`	`Option<LifecycleHooks>`	`None`	Lifecycle hooks for request/response processing
`background_tasks`	`BackgroundTaskConfig`	—	Background task executor configuration
`enable_http_trace`	`bool`	`false`	Enable per-request HTTP tracing (tower-http `TraceLayer`)
`di_container`	`Option<DependencyContainer>`	`None`	Dependency injection container (requires 'di' feature)

Methods¶

default()¶

Signature:

pub fn default() -> ServerConfig

Example:

let result = ServerConfig::default();

Returns: ServerConfig

ServerInfo¶

Server information

Field	Type	Default	Description
`url`	`String`	—	Base URL of the server (e.g. `"<https://api.example.com/v1>"`).
`description`	`Option<String>`	`None`	Optional human-readable description of the server environment.

SseEvent¶

An individual SSE event

Represents a single Server-Sent Event to be sent to a connected client. Events can have an optional type, ID, and retry timeout for advanced scenarios.

SSE Format¶

Events are serialized to the following text format:

event: event_type
data: {"json":"value"}
id: event-123
retry: 3000

Field	Type	Default	Description
`event_type`	`Option<String>`	`None`	Event type (optional)
`data`	`serde_json::Value`	—	Event data (JSON value)
`id`	`Option<String>`	`None`	Event ID (optional, for client-side reconnection)
`retry`	`Option<u64>`	`None`	Retry timeout in milliseconds (optional)

Methods¶

with_id()¶

Set the event ID for client-side reconnection support

Sets an ID that clients can use to resume from this point if they disconnect. The client sends this ID back in the Last-Event-ID header when reconnecting.

Signature:

pub fn with_id(self, id: String) -> SseEvent

Example:

use serde_json::json;
use spikard_http::sse::SseEvent;

let event = SseEvent::new(json!({"count": 1}))
    .with_id("event-1");

Parameters:

Name	Type	Required	Description
`id`	`String`	Yes	Unique identifier for this event

Returns: SseEvent

with_retry()¶

Set the retry timeout for client reconnection

Sets the time in milliseconds clients should wait before attempting to reconnect if the connection is lost. The client browser will automatically handle reconnection.

Signature:

pub fn with_retry(self, retry_ms: u64) -> SseEvent

Example:

use serde_json::json;
use spikard_http::sse::SseEvent;

let event = SseEvent::new(json!({"data": "value"}))
    .with_retry(5000); // Reconnect after 5 seconds

Parameters:

Name	Type	Required	Description
`retry_ms`	`u64`	Yes	Retry timeout in milliseconds

Returns: SseEvent

StaticFilesConfig¶

Static file serving configuration

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

TestClient¶

Core test client for making HTTP requests to a Spikard application.

This struct wraps axum-test's TestServer and provides a language-agnostic interface for making HTTP requests, sending WebSocket connections, and handling Server-Sent Events. Language bindings wrap this to provide native API surfaces.

Methods¶

graphql_at()¶

Send a GraphQL query/mutation to a custom endpoint

Signature:

pub async fn graphql_at(&self, endpoint: &str, query: &str, variables: Option<serde_json::Value>, operation_name: Option<&str>) -> Result<ResponseSnapshot, SnapshotError>

Example:

let result = instance.graphql_at("value", "value", std::collections::HashMap::new(), "value").await?;

Parameters:

Name	Type	Required	Description
`endpoint`	`&str`	Yes	The endpoint
`query`	`&str`	Yes	The query
`variables`	`Option<serde_json::Value>`	No	The variables
`operation_name`	`Option<&str>`	No	The operation name

Returns: ResponseSnapshot

Errors: Returns Err(SnapshotError).

graphql()¶

Send a GraphQL query/mutation

Signature:

pub async fn graphql(&self, query: &str, variables: Option<serde_json::Value>, operation_name: Option<&str>) -> Result<ResponseSnapshot, SnapshotError>

Example:

let result = instance.graphql("value", std::collections::HashMap::new(), "value").await?;

Parameters:

Name	Type	Required	Description
`query`	`&str`	Yes	The query
`variables`	`Option<serde_json::Value>`	No	The variables
`operation_name`	`Option<&str>`	No	The operation name

Returns: ResponseSnapshot

Errors: Returns Err(SnapshotError).

graphql_subscription_at()¶

Send a GraphQL subscription (WebSocket) to a custom endpoint.

Uses the graphql-transport-ws protocol and captures the first next payload. After the first payload is received, this client sends complete to unsubscribe.

Signature:

pub async fn graphql_subscription_at(&self, endpoint: &str, query: &str, variables: Option<serde_json::Value>, operation_name: Option<&str>) -> Result<GraphQlSubscriptionSnapshot, SnapshotError>

Example:

let result = instance.graphql_subscription_at("value", "value", std::collections::HashMap::new(), "value").await?;

Parameters:

Name	Type	Required	Description
`endpoint`	`&str`	Yes	The endpoint
`query`	`&str`	Yes	The query
`variables`	`Option<serde_json::Value>`	No	The variables
`operation_name`	`Option<&str>`	No	The operation name

Returns: GraphQlSubscriptionSnapshot

Errors: Returns Err(SnapshotError).

graphql_subscription()¶

Send a GraphQL subscription (WebSocket).

Uses /graphql as the default subscription endpoint.

Signature:

pub async fn graphql_subscription(&self, query: &str, variables: Option<serde_json::Value>, operation_name: Option<&str>) -> Result<GraphQlSubscriptionSnapshot, SnapshotError>

Example:

let result = instance.graphql_subscription("value", std::collections::HashMap::new(), "value").await?;

Parameters:

Name	Type	Required	Description
`query`	`&str`	Yes	The query
`variables`	`Option<serde_json::Value>`	No	The variables
`operation_name`	`Option<&str>`	No	The operation name

Returns: GraphQlSubscriptionSnapshot

Errors: Returns Err(SnapshotError).

TestingSseEvent¶

A single Server-Sent Event.

Field	Type	Default	Description
`data`	`String`	—	The data field of the event.

UploadFile¶

Represents an uploaded file from multipart/form-data requests.

This struct provides efficient access to file content with automatic base64 decoding and implements standard I/O traits for compatibility.

Field	Type	Default	Description
`filename`	`String`	—	Original filename from the client
`content_type`	`Option<String>`	`None`	MIME type of the uploaded file
`size`	`Option<usize>`	`None`	Size of the file in bytes
`content`	`Vec<u8>`	—	File content (may be base64 encoded)
`content_encoding`	`Option<String>`	`None`	Content encoding type
`cursor`	`Cursor`	—	Internal cursor for Read/Seek operations

Methods¶

as_bytes()¶

Get the raw file content as bytes.

This provides zero-copy access to the underlying buffer.

Signature:

pub fn as_bytes(&self) -> Vec<u8>

Example:

let result = instance.as_bytes();

Returns: Vec<u8>

read_to_string()¶

Read the file content as a UTF-8 string.

Errors:

Returns an error if the content is not valid UTF-8.

Signature:

pub fn read_to_string(&self) -> Result<String, Error>

Example:

let result = instance.read_to_string()?;

Returns: String

Errors: Returns Err(Error).

content_type_or_default()¶

Get the content type, defaulting to "application/octet-stream".

Signature:

pub fn content_type_or_default(&self) -> String

Example:

let result = instance.content_type_or_default();

Returns: String

ValidateRequest¶

Request body for POST /asyncapi/validate

Field	Type	Default	Description
`spec`	`serde_json::Value`	—	Spec
`channel`	`String`	—	Channel
`message`	`String`	—	Message
`payload`	`serde_json::Value`	—	Payload

ValidationResponse¶

Response body for POST /asyncapi/validate

Field	Type	Default	Description
`valid`	`bool`	—	Valid
`errors`	`Vec<String>`	—	Errors

Enums¶

Method¶

HTTP method

Value	Description
`Get`	Get
`Post`	Post
`Put`	Put
`Patch`	Patch
`Delete`	Delete
`Head`	Head
`Options`	Options
`Connect`	Connect
`Trace`	Trace

LifecycleHookPhase¶

The five lifecycle phases a hook can be registered against.

Used to resolve a per-route named hook selection (LifecycleHooksConfig in spikard-core::http) against the hooks actually registered on the server: a name is looked up within one specific phase's registered hooks, not across all five, so a hook registered for on_response can never be silently picked up by a route asking for on_request.

Value	Description
`OnRequest`	On request
`PreValidation`	Pre validation
`PreHandler`	Pre handler
`OnResponse`	On response
`OnError`	On error

SecuritySchemeInfo¶

Security scheme types

Value	Description
`Http`	Http — Fields: `scheme`: `String`, `bearer_format`: `String`
`ApiKey`	Api key — Fields: `location`: `String`, `name`: `String`

SnapshotError¶

Possible errors while converting an Axum response into a snapshot.

Value	Description
`InvalidHeader`	Response header could not be decoded to UTF-8. — Fields: `0`: `String`
`Decompression`	Body decompression failed. — Fields: `0`: `String`

WebSocketMessage¶

A WebSocket message that can be text or binary.

Value	Description
`Text`	A text message. — Fields: `0`: `String`
`Binary`	A binary message. — Fields: `0`: `Vec<u8>`
`Close`	A close message with a numeric close code (RFC 6455) and optional reason text. Common codes: 1000 Normal Closure, 1001 Going Away, 1005 No Status Received, 1006 Abnormal Closure. — Fields: `code`: `u16`, `reason`: `String`
`Ping`	A ping message. — Fields: `0`: `Vec<u8>`
`Pong`	A pong message. — Fields: `0`: `Vec<u8>`

Errors¶

AppError¶

Error type for application builder operations.

Variant	Description
`Route`	Route registration failed.
`Server`	Server/router construction failed.
`Decode`	Failed to extract DTO from the request context.
`GraphQl`	GraphQL route registration failed (e.g. an unrecognized `schema_type`).

GraphQlError¶

Errors that can occur during GraphQL operations

These errors are compatible with async-graphql error handling and can be converted to structured HTTP responses matching the project's error fixtures.

Variant	Description
`ExecutionError`	Error during schema execution Occurs when the GraphQL executor encounters a runtime error during query execution.
`SchemaBuildError`	Error during schema building Occurs when schema construction fails due to invalid definitions or conflicts.
`RequestHandlingError`	Error during request handling Occurs when the HTTP request cannot be properly handled or parsed.
`SerializationError`	Serialization error Occurs during JSON serialization/deserialization of GraphQL values.
`JsonError`	JSON parsing error Occurs when JSON input cannot be parsed.
`ValidationError`	GraphQL validation error Occurs when a GraphQL query fails schema validation.
`ParseError`	GraphQL parse error Occurs when the GraphQL query string cannot be parsed.
`AuthenticationError`	Authentication error Occurs when request authentication fails.
`AuthorizationError`	Authorization error Occurs when user lacks required permissions.
`NotFound`	Not found error Occurs when a requested resource is not found.
`RateLimitExceeded`	Rate limit error Occurs when rate limit is exceeded.
`InvalidInput`	Invalid input error with validation details Occurs during input validation with detailed error information.
`ComplexityLimitExceeded`	Query complexity limit exceeded Occurs when a GraphQL query exceeds the configured complexity limit.
`DepthLimitExceeded`	Query depth limit exceeded Occurs when a GraphQL query exceeds the configured depth limit.
`IntrospectionDisabled`	Introspection query rejected because introspection is disabled Occurs when a query selects `__schema` or `__type` while the schema was configured with introspection disabled.
`InternalError`	Internal server error Occurs when an unexpected internal error happens.

SchemaError¶

Error type for schema building operations

Variant	Description
`BuildingFailed`	Generic schema building error
`ValidationError`	Configuration validation error
`ComplexityLimitExceeded`	Complexity limit exceeded
`DepthLimitExceeded`	Depth limit exceeded

Edit this page on GitHub