Go API Reference

Go API Reference v0.17.1¶

Functions¶

SchemaQueryOnly()¶

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:

func SchemaQueryOnly() *QueryOnlyConfig

Example:

result := SchemaQueryOnly()

Returns: QueryOnlyConfig

SchemaQueryMutation()¶

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:

func SchemaQueryMutation() *QueryMutationConfig

Example:

result := SchemaQueryMutation()

Returns: QueryMutationConfig

SchemaFull()¶

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:

func SchemaFull() *FullSchemaConfig

Example:

result := SchemaFull()

Returns: FullSchemaConfig

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.

ApiKeyConfig¶

API Key authentication configuration

AsyncApiConfig¶

AsyncAPI HTTP endpoint configuration

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.

BackgroundJobMetadata¶

BackgroundTaskConfig¶

Configuration for in-process background task execution.

CompressionConfig¶

Compression configuration shared across runtimes

ContactInfo¶

Contact information

CorsConfig¶

CORS configuration for a route

Methods¶

AllowedMethodsJoined()¶

Get the cached joined methods string for preflight responses

Signature:

func (o *CorsConfig) AllowedMethodsJoined() string

Example:

result := instance.AllowedMethodsJoined()

Returns: string

AllowedHeadersJoined()¶

Get the cached joined headers string for preflight responses

Signature:

func (o *CorsConfig) AllowedHeadersJoined() string

Example:

result := instance.AllowedHeadersJoined()

Returns: string

IsOriginAllowed()¶

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

Signature:

func (o *CorsConfig) IsOriginAllowed(origin string) bool

Example:

result := instance.IsOriginAllowed("value")

Parameters:

Returns: bool

IsMethodAllowed()¶

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

Signature:

func (o *CorsConfig) IsMethodAllowed(method string) bool

Example:

result := instance.IsMethodAllowed("value")

Parameters:

Returns: bool

DynamicSchemaConfig¶

Configuration for building and executing a dynamic-SDL schema.

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.

FullSchemaConfig¶

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

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:

func GraphQlRouteConfigNew() *GraphQlRouteConfig

Example:

result := GraphQlRouteConfigNew()

Returns: GraphQlRouteConfig

Path()¶

Set the HTTP path for the GraphQL endpoint

Signature:

func (o *GraphQlRouteConfig) Path(path string) *GraphQlRouteConfig

Example:

result := instance.Path("value")

Parameters:

Returns: GraphQlRouteConfig

Method()¶

Set the HTTP method for the GraphQL endpoint

Signature:

func (o *GraphQlRouteConfig) Method(method string) *GraphQlRouteConfig

Example:

result := instance.Method("value")

Parameters:

Returns: GraphQlRouteConfig

EnablePlayground()¶

Enable or disable the GraphQL Playground UI

Signature:

func (o *GraphQlRouteConfig) EnablePlayground(enable bool) *GraphQlRouteConfig

Example:

result := instance.EnablePlayground(true)

Parameters:

Returns: GraphQlRouteConfig

Description()¶

Set a custom description for documentation

Signature:

func (o *GraphQlRouteConfig) Description(description string) *GraphQlRouteConfig

Example:

result := instance.Description("value")

Parameters:

Returns: GraphQlRouteConfig

GetPath()¶

Get the configured path

Signature:

func (o *GraphQlRouteConfig) GetPath() string

Example:

result := instance.GetPath()

Returns: string

GetMethod()¶

Get the configured method

Signature:

func (o *GraphQlRouteConfig) GetMethod() string

Example:

result := instance.GetMethod()

Returns: string

IsPlaygroundEnabled()¶

Check if playground is enabled

Signature:

func (o *GraphQlRouteConfig) IsPlaygroundEnabled() bool

Example:

result := instance.IsPlaygroundEnabled()

Returns: bool

GetDescription()¶

Get the description if set

Signature:

func (o *GraphQlRouteConfig) GetDescription() *string

Example:

result := instance.GetDescription()

Returns: *string

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 nil (unbounded).

IntoHandler¶

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

Methods¶

IntoHandler()¶

Convert this value into a shared request handler.

Signature:

func (o *IntoHandler) IntoHandler() *Handler

Example:

result := instance.IntoHandler()

Returns: Handler

JsonRpcConfig¶

JSON-RPC server configuration

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.

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.

JwtConfig¶

JWT authentication configuration

LicenseInfo¶

License information

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.

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

OpenApiConfig¶

OpenAPI configuration

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¶

WithDetail()¶

Set the detail field

Signature:

func (o *ProblemDetails) WithDetail(detail string) *ProblemDetails

Example:

result := instance.WithDetail("value")

Parameters:

Returns: ProblemDetails

WithInstance()¶

Set the instance field

Signature:

func (o *ProblemDetails) WithInstance(instance string) *ProblemDetails

Example:

result := instance.WithInstance("value")

Parameters:

Returns: ProblemDetails

NotFound()¶

Create a not found error

Signature:

func ProblemDetailsNotFound(detail string) *ProblemDetails

Example:

result := ProblemDetailsNotFound("value")

Parameters:

Returns: ProblemDetails

MethodNotAllowed()¶

Create a method not allowed error

Signature:

func ProblemDetailsMethodNotAllowed(detail string) *ProblemDetails

Example:

result := ProblemDetailsMethodNotAllowed("value")

Parameters:

Returns: ProblemDetails

InternalServerError()¶

Create an internal server error

Signature:

func ProblemDetailsInternalServerError(detail string) *ProblemDetails

Example:

result := ProblemDetailsInternalServerError("value")

Parameters:

Returns: ProblemDetails

BadRequest()¶

Create a bad request error

Signature:

func ProblemDetailsBadRequest(detail string) *ProblemDetails

Example:

result := ProblemDetailsBadRequest("value")

Parameters:

Returns: ProblemDetails

ToJson()¶

Serialize to JSON string

Errors: Returns an error if the serialization fails.

Signature:

func (o *ProblemDetails) ToJson() (string, error)

Example:

result, err := instance.ToJson()
if err != nil {
    return err
}

Returns: string

Errors: Returns error.

ToJsonPretty()¶

Serialize to pretty JSON string

Errors: Returns an error if the serialization fails.

Signature:

func (o *ProblemDetails) ToJsonPretty() (string, error)

Example:

result, err := instance.ToJsonPretty()
if err != nil {
    return err
}

Returns: string

Errors: Returns error.

QueryMutationConfig¶

Configuration for schemas with Query and Mutation types

QueryOnlyConfig¶

Configuration for schemas with only Query type

RateLimitConfig¶

Rate limiting configuration shared across runtimes

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.

Response¶

HTTP Response with custom status code, headers, and content

Methods¶

SetHeader()¶

Set a header

Signature:

func (o *Response) SetHeader(key string, value string)

Example:

instance.SetHeader("value", "value")

Parameters:

Returns: No return value.

SetCookie()¶

Set a cookie in the response

Signature:

func (o *Response) SetCookie(key string, value string, secure bool, httpOnly bool, maxAge int64, domain string, path string, sameSite string)

Example:

instance.SetCookie("value", "value", true, true, 42, "value", "value", "value")

Parameters:

Returns: No return value.

RouteBuilder¶

Builder for defining a route.

Methods¶

New()¶

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

Signature:

func RouteBuilderNew(method Method, path string) *RouteBuilder

Example:

result := RouteBuilderNew(Method{}, "value")

Parameters:

Returns: RouteBuilder

HandlerName()¶

Assign an explicit handler name.

Signature:

func (o *RouteBuilder) HandlerName(name string) *RouteBuilder

Example:

result := instance.HandlerName("value")

Parameters:

Returns: RouteBuilder

RequestSchemaJson()¶

Provide a raw JSON schema for the request body.

Signature:

func (o *RouteBuilder) RequestSchemaJson(schema interface{}) *RouteBuilder

Example:

result := instance.RequestSchemaJson(nil)

Parameters:

Returns: RouteBuilder

ResponseSchemaJson()¶

Provide a raw JSON schema for the response body.

Signature:

func (o *RouteBuilder) ResponseSchemaJson(schema interface{}) *RouteBuilder

Example:

result := instance.ResponseSchemaJson(nil)

Parameters:

Returns: RouteBuilder

ParamsSchemaJson()¶

Provide a raw JSON schema for request parameters.

Signature:

func (o *RouteBuilder) ParamsSchemaJson(schema interface{}) *RouteBuilder

Example:

result := instance.ParamsSchemaJson(nil)

Parameters:

Returns: RouteBuilder

FileParamsJson()¶

Provide multipart file parameter configuration.

Signature:

func (o *RouteBuilder) FileParamsJson(schema interface{}) *RouteBuilder

Example:

result := instance.FileParamsJson(nil)

Parameters:

Returns: RouteBuilder

Cors()¶

Attach a CORS configuration for this route.

Signature:

func (o *RouteBuilder) Cors(cors CorsConfig) *RouteBuilder

Example:

result := instance.Cors(CorsConfig{})

Parameters:

Returns: RouteBuilder

Compression()¶

Attach a compression configuration for this route.

Signature:

func (o *RouteBuilder) Compression(compression CompressionConfig) *RouteBuilder

Example:

result := instance.Compression(CompressionConfig{})

Parameters:

Returns: RouteBuilder

BodyLimit()¶

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

Signature:

func (o *RouteBuilder) BodyLimit(maxBytes uint) *RouteBuilder

Example:

result := instance.BodyLimit(42)

Parameters:

Returns: RouteBuilder

RequestTimeout()¶

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

Signature:

func (o *RouteBuilder) RequestTimeout(seconds uint64) *RouteBuilder

Example:

result := instance.RequestTimeout(42)

Parameters:

Returns: RouteBuilder

RateLimit()¶

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

Signature:

func (o *RouteBuilder) RateLimit(rateLimit RateLimitConfig) *RouteBuilder

Example:

result := instance.RateLimit(RateLimitConfig{})

Parameters:

Returns: RouteBuilder

RequestId()¶

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:

func (o *RouteBuilder) RequestId(enabled bool) *RouteBuilder

Example:

result := instance.RequestId(true)

Parameters:

Returns: RouteBuilder

JwtAuth()¶

Require JWT authentication for this route.

Signature:

func (o *RouteBuilder) JwtAuth(config JwtAuthConfig) *RouteBuilder

Example:

result := instance.JwtAuth(JwtAuthConfig{})

Parameters:

Returns: RouteBuilder

ApiKeyAuth()¶

Require API key authentication for this route.

Signature:

func (o *RouteBuilder) ApiKeyAuth(config ApiKeyAuthConfig) *RouteBuilder

Example:

result := instance.ApiKeyAuth(ApiKeyAuthConfig{})

Parameters:

Returns: RouteBuilder

Authorization()¶

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

Signature:

func (o *RouteBuilder) Authorization(config AuthorizationConfig) *RouteBuilder

Example:

result := instance.Authorization(AuthorizationConfig{})

Parameters:

Returns: RouteBuilder

LifecycleHooks()¶

Select registered lifecycle hooks to run for this route.

Signature:

func (o *RouteBuilder) LifecycleHooks(hooks LifecycleHooksConfig) *RouteBuilder

Example:

result := instance.LifecycleHooks(LifecycleHooksConfig{})

Parameters:

Returns: RouteBuilder

JsonrpcMethod()¶

Expose this route as a JSON-RPC method.

Signature:

func (o *RouteBuilder) JsonrpcMethod(info JsonRpcMethodInfo) *RouteBuilder

Example:

result := instance.JsonrpcMethod(JsonRpcMethodInfo{})

Parameters:

Returns: RouteBuilder

OpenrpcSpec()¶

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

Signature:

func (o *RouteBuilder) OpenrpcSpec(spec interface{}) *RouteBuilder

Example:

result := instance.OpenrpcSpec(nil)

Parameters:

Returns: RouteBuilder

Sync()¶

Mark the route as synchronous.

Signature:

func (o *RouteBuilder) Sync() *RouteBuilder

Example:

result := instance.Sync()

Returns: RouteBuilder

HandlerDependencies()¶

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

Signature:

func (o *RouteBuilder) HandlerDependencies(dependencies []string) *RouteBuilder

Example:

result := instance.HandlerDependencies(nil)

Parameters:

Returns: RouteBuilder

SchemaConfig¶

Configuration for GraphQL schema building.

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

ServerConfig¶

Server configuration

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¶

WithId()¶

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:

func (o *SseEvent) WithId(id string) *SseEvent

Example:

result := instance.WithId("value")

Parameters:

Returns: SseEvent

WithRetry()¶

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:

func (o *SseEvent) WithRetry(retryMs uint64) *SseEvent

Example:

result := instance.WithRetry(42)

Parameters:

Returns: SseEvent

StaticFilesConfig¶

Static file serving configuration

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¶

AsBytes()¶

Get the raw file content as bytes.

This provides zero-copy access to the underlying buffer.

Signature:

func (o *UploadFile) AsBytes() []byte

Example:

result := instance.AsBytes()

Returns: []byte

ReadToString()¶

Read the file content as a UTF-8 string.

Errors:

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

Signature:

func (o *UploadFile) ReadToString() (string, error)

Example:

result, err := instance.ReadToString()
if err != nil {
    return err
}

Returns: string

Errors: Returns error.

ContentTypeOrDefault()¶

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

Signature:

func (o *UploadFile) ContentTypeOrDefault() string

Example:

result := instance.ContentTypeOrDefault()

Returns: string

ValidateRequest¶

Request body for POST /asyncapi/validate

ValidationResponse¶

Response body for POST /asyncapi/validate

Enums¶

Method¶

HTTP method

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.

SecuritySchemeInfo¶

Security scheme types

Errors¶

AppError¶

Error type for application builder operations.

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