Rust API Reference

Rust API Reference v0.15.6-rc.3¶

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

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

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

Returns: FullSchemaConfig

Types¶

ApiKeyConfig¶

API Key authentication configuration

AsyncApiConfig¶

AsyncAPI HTTP endpoint configuration

BackgroundJobMetadata¶

Methods¶

default()¶

Signature:

pub fn default() -> BackgroundJobMetadata

BackgroundTaskConfig¶

Configuration for in-process background task execution.

Methods¶

default()¶

Signature:

pub fn default() -> BackgroundTaskConfig

CompressionConfig¶

Compression configuration shared across runtimes

Methods¶

default()¶

Signature:

pub fn default() -> CompressionConfig

ContactInfo¶

Contact information

CorsConfig¶

CORS configuration for a route

Methods¶

allowed_methods_joined()¶

Get the cached joined methods string for preflight responses

Signature:

pub fn allowed_methods_joined(&self) -> String

allowed_headers_joined()¶

Get the cached joined headers string for preflight responses

Signature:

pub fn allowed_headers_joined(&self) -> 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

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

are_headers_allowed()¶

Check if all requested headers are allowed (O(n) where n = num requested headers)

Signature:

pub fn are_headers_allowed(&self, requested: Vec<String>) -> bool

default()¶

Signature:

pub fn default() -> CorsConfig

FullSchemaConfig¶

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

Methods¶

default()¶

Signature:

pub fn default() -> FullSchemaConfig

GraphQlRouteConfig¶

Configuration for GraphQL routes

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

Methods¶

path()¶

Set the HTTP path for the GraphQL endpoint

Signature:

pub fn path(&self, path: &str) -> GraphQlRouteConfig

method()¶

Set the HTTP method for the GraphQL endpoint

Signature:

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

enable_playground()¶

Enable or disable the GraphQL Playground UI

Signature:

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

description()¶

Set a custom description for documentation

Signature:

pub fn description(&self, description: &str) -> GraphQlRouteConfig

get_path()¶

Get the configured path

Signature:

pub fn get_path(&self) -> String

get_method()¶

Get the configured method

Signature:

pub fn get_method(&self) -> String

is_playground_enabled()¶

Check if playground is enabled

Signature:

pub fn is_playground_enabled(&self) -> bool

get_description()¶

Get the description if set

Signature:

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

default()¶

Signature:

pub fn default() -> GraphQlRouteConfig

GraphQlSubscriptionSnapshot¶

Snapshot of a GraphQL subscription exchange over WebSocket.

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

Methods¶

default()¶

Signature:

pub fn default() -> GrpcConfig

JsonRpcConfig¶

JSON-RPC server configuration

Methods¶

default()¶

Signature:

pub fn default() -> 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.

JwtConfig¶

JWT authentication configuration

LicenseInfo¶

License information

OpenApiConfig¶

OpenAPI configuration

Methods¶

default()¶

Signature:

pub fn default() -> OpenApiConfig

ParseRequest¶

Request body for POST /asyncapi/parse

ParseResult¶

Full parse result returned by POST /asyncapi/parse

ParsedChannel¶

A single channel extracted from an AsyncAPI spec

ParsedMessage¶

A resolved message (name + JSON Schema)

ParsedOperation¶

A single operation extracted from an AsyncAPI spec

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": [...]
}

Methods¶

with_detail()¶

Set the detail field

Signature:

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

with_instance()¶

Set the instance field

Signature:

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

not_found()¶

Create a not found error

Signature:

pub fn not_found(detail: &str) -> ProblemDetails

method_not_allowed()¶

Create a method not allowed error

Signature:

pub fn method_not_allowed(detail: &str) -> ProblemDetails

internal_server_error()¶

Create an internal server error

Signature:

pub fn internal_server_error(detail: &str) -> ProblemDetails

bad_request()¶

Create a bad request error

Signature:

pub fn bad_request(detail: &str) -> ProblemDetails

to_json()¶

Serialize to JSON string

Errors: Returns an error if the serialization fails.

Signature:

pub fn to_json(&self) -> String

to_json_pretty()¶

Serialize to pretty JSON string

Errors: Returns an error if the serialization fails.

Signature:

pub fn to_json_pretty(&self) -> String

QueryMutationConfig¶

Configuration for schemas with Query and Mutation types

Methods¶

default()¶

Signature:

pub fn default() -> QueryMutationConfig

QueryOnlyConfig¶

Configuration for schemas with only Query type

Methods¶

default()¶

Signature:

pub fn default() -> QueryOnlyConfig

RateLimitConfig¶

Rate limiting configuration shared across runtimes

Methods¶

default()¶

Signature:

pub fn default() -> RateLimitConfig

Response¶

HTTP Response with custom status code, headers, and content

Methods¶

set_header()¶

Set a header

Signature:

pub fn set_header(&self, key: &str, value: &str)

set_cookie()¶

Set a cookie in the response

Signature:

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

default()¶

Signature:

pub fn default() -> Response

ResponseSnapshot¶

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

Methods¶

text()¶

Return response body as UTF-8 string.

Signature:

pub fn text(&self) -> String

header()¶

Lookup header by case-insensitive name.

Signature:

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

SchemaConfig¶

Configuration for GraphQL schema building.

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

Methods¶

default()¶

Signature:

pub fn default() -> SchemaConfig

ServerConfig¶

Server configuration

Methods¶

default()¶

Signature:

pub fn default() -> ServerConfig

ServerInfo¶

Server information

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

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: &str) -> 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

StaticFilesConfig¶

Static file serving configuration

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¶

get()¶

Make a GET request

Signature:

pub fn get(&self, path: &str, query_params: Option<Vec<Vec<String>>>, headers: Option<Vec<Vec<String>>>) -> ResponseSnapshot

post()¶

Make a POST request

Signature:

pub fn post(&self, path: &str, json: Option<serde_json::Value>, form_data: Option<Vec<Vec<String>>>, multipart: &str, query_params: Option<Vec<Vec<String>>>, headers: Option<Vec<Vec<String>>>) -> ResponseSnapshot

request_raw()¶

Make a request with a raw body payload.

Signature:

pub fn request_raw(&self, method: Method, path: &str, body: &[u8], query_params: Option<Vec<Vec<String>>>, headers: Option<Vec<Vec<String>>>) -> ResponseSnapshot

put()¶

Make a PUT request

Signature:

pub fn put(&self, path: &str, json: Option<serde_json::Value>, query_params: Option<Vec<Vec<String>>>, headers: Option<Vec<Vec<String>>>) -> ResponseSnapshot

patch()¶

Make a PATCH request

Signature:

pub fn patch(&self, path: &str, json: Option<serde_json::Value>, query_params: Option<Vec<Vec<String>>>, headers: Option<Vec<Vec<String>>>) -> ResponseSnapshot

delete()¶

Make a DELETE request

Signature:

pub fn delete(&self, path: &str, query_params: Option<Vec<Vec<String>>>, headers: Option<Vec<Vec<String>>>) -> ResponseSnapshot

options()¶

Make an OPTIONS request

Signature:

pub fn options(&self, path: &str, query_params: Option<Vec<Vec<String>>>, headers: Option<Vec<Vec<String>>>) -> ResponseSnapshot

head()¶

Make a HEAD request

Signature:

pub fn head(&self, path: &str, query_params: Option<Vec<Vec<String>>>, headers: Option<Vec<Vec<String>>>) -> ResponseSnapshot

trace()¶

Make a TRACE request

Signature:

pub fn trace(&self, path: &str, query_params: Option<Vec<Vec<String>>>, headers: Option<Vec<Vec<String>>>) -> ResponseSnapshot

graphql_at()¶

Send a GraphQL query/mutation to a custom endpoint

Signature:

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

graphql()¶

Send a GraphQL query/mutation

Signature:

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

graphql_with_status()¶

Send a GraphQL query and return HTTP status code separately

This method allows tests to distinguish between:

• HTTP-level errors (400/422 for invalid requests)
• GraphQL-level errors (200 with errors in response body)

Signature:

pub fn graphql_with_status(&self, query: &str, variables: Option<serde_json::Value>, operation_name: Option<String>) -> String

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 fn graphql_subscription_at(&self, endpoint: &str, query: &str, variables: Option<serde_json::Value>, operation_name: Option<String>) -> GraphQlSubscriptionSnapshot

graphql_subscription()¶

Send a GraphQL subscription (WebSocket).

Uses /graphql as the default subscription endpoint.

Signature:

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

TestingSseEvent¶

A single Server-Sent 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.

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>

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

content_type_or_default()¶

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

Signature:

pub fn content_type_or_default(&self) -> String

ValidateRequest¶

Request body for POST /asyncapi/validate

ValidationResponse¶

Response body for POST /asyncapi/validate

Enums¶

SnapshotError¶

Possible errors while converting an Axum response into a snapshot.

WebSocketMessage¶

A WebSocket message that can be text or binary.

Method¶

HTTP method

SecuritySchemeInfo¶

Security scheme types

Errors¶

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.

SchemaError¶

Error type for schema building operations

Edit this page on GitHub