Skip to main content

Crate suku

Crate suku 

Source
Expand description

A production GraphQL-over-HTTP server built on gql.

suku turns a gql::Schema into an HTTP endpoint. It implements the GraphQL-over-HTTP request/response protocol, including content negotiation, batches, GraphiQL, server-sent-event subscriptions, the graphql-transport-ws WebSocket protocol and GraphQL multipart requests, while keeping the execution engine (gql) free of transport concerns.

§Layers

  • Server executes queries, mutations and subscriptions. It has no HTTP types. It also owns the optional error formatter that redacts messages before a client sees them.
  • http is a transport-agnostic request handler. Any framework can call it with request parts and a body.
  • axum mounts a Server on an Axum router (enabled by the default axum feature).
  • ws drives one graphql-transport-ws connection over any text-message stream (enabled by the default ws feature, which implies axum).

§Feature flags

FeatureDefaultPurpose
axumyesThe axum router and ExtractContext integration.
wsyesgraphql-transport-ws WebSocket subscriptions. Enables axum.
multipartyesGraphQL multipart requests; uses multer.
vendored-graphiqlnoSelf-contained GraphiQL page with pinned browser assets.
tracingnoRequest spans, and gql/tracing.

To build without WebSocket support while keeping Axum:

suku = { version = "0.1.2", default-features = false, features = ["axum", "multipart"] }

A WebSocket upgrade then receives no special handling and falls through to the normal GET path. To drop file uploads, omit multipart; a multipart/form-data POST is then rejected with 415 Unsupported Media Type exactly like any other non-JSON body.

§Example

use suku::{Context, GraphQLRequest, Server};

let server = Server::new(schema).introspection(true).max_depth(12);
let response = server
    .execute(&GraphQLRequest::new("{ hello }"), Context::empty())
    .await;

Mounting on Axum:

let app = suku::axum::GraphQL::new(suku::Server::new(schema))
    .path("/graphql")
    .graphiql(true)
    .into_router();

§Transports

  • HTTP — one request or batch per GET/POST, JSON responses and GraphiQL.
  • SSE — POST + Accept: text/event-stream streams subscription events as event: next/data: frames.
  • WebSocket — graphql-transport-ws over an upgrade at the same path. It multiplexes queries, mutations and subscriptions, and supports client cancellation. Authentication runs once per connection against the upgrade request; every operation reuses that Context.
  • Multipart — the GraphQL multipart request shape, with files inserted as gql::Upload values into request variables.

See the module documentation of ws and multipart for the protocol details, and the crate README for deployment notes.

§GraphiQL assets

The GraphiQL page served for GET requests that accept HTML loads React, ReactDOM and GraphiQL from unpkg by default. Enable the vendored-graphiql feature to compile the pinned browser assets into the crate and serve one self-contained page with no CDN requests:

[dependencies]
suku = { version = "0.1.2", features = ["vendored-graphiql"] }

The inline page works with both http::handle and the Axum adapter because it needs no asset routes. Scripts and styles are inline, so an accompanying CSP should allow inline script/style while restricting connect-src to the application itself. Versions, checksums, licenses and the update procedure live in crates/suku/src/http/vendor/.

§Observability

The optional tracing feature (which also enables gql/tracing) emits a suku.request span with method, path, body size, operation, request id, batch size and status, plus children for parsing, execution, serialization and subscriptions. Transport and extractor failures are WARN events with a status and code. Request bodies, headers, tokens and variable values are never recorded. See the repository’s docs/plugins/tracing.md.

Re-exports§

pub use crate::multipart::DEFAULT_MAX_MULTIPART_PARTS;
pub use crate::prepared::PreparedOperation;
pub use crate::prepared::PreparedQueries;
pub use crate::prepared::PreparedQueriesError;
pub use crate::prepared::persisted_query_not_found;
pub use crate::prepared::persisted_query_not_found_error;
pub use crate::http::ContextRequest;
pub use crate::http::ExtractContext;
pub use crate::http::HttpConfig;
pub use crate::http::HttpError;
pub use crate::http::HttpResponse;
pub use crate::http::HttpResult;
pub use crate::http::SseResponse;
pub use crate::http::graphiql;
pub use crate::http::graphiql_html;
pub use crate::http::handle;
pub use crate::axum::GraphQL;

Modules§

axum
Axum integration (enabled by the default axum feature).
http
Transport-agnostic GraphQL-over-HTTP handling.
multipart
GraphQL multipart requests (file uploads).
prepared
Persisted-query manifests.
ws
GraphQL over WebSocket (graphql-transport-ws).

Structs§

Context
Per-request user data handed to resolvers.
ErrorContext
Context handed to an error formatter.
GraphQLRequest
A GraphQL-over-HTTP request body.
RequestError
An error that occurred before or while interpreting a request.
Server
A GraphQL server.
Upload
A file supplied by a multipart request.
UploadBinding
A file attached to a path inside a request’s variables.

Enums§

ErrorKind
Whether an error happened before execution or during it.
RequestPayload
A request body, which is either a single operation or a batch.

Constants§

DEFAULT_BATCH_CONCURRENCY
Default number of batch operations executed concurrently.
DEFAULT_MAX_BATCH_SIZE
Default maximum number of operations in a batch.
DEFAULT_MAX_BODY_BYTES
Default maximum request body size: 1 MiB.
INTERNAL_ERROR_MESSAGE
The message used by mask_internal for errors that are not safe to expose.

Traits§

ErrorFormatter
A function that rewrites errors before they are returned to a client.
ResponseExt
JSON helpers for GraphQL responses.

Functions§

error_json_bytes
A specification-shaped error response as JSON bytes.
error_response
A specification-shaped error response.
json_to_graphql
Convert a JSON value into the GraphQL value model.
mask_internal
Mask messages that are not intentionally client-facing.
to_json
Serialize a response to a JSON value.
to_json_bytes
Serialize a response to JSON bytes.

Type Aliases§

GraphQLResponse
The canonical GraphQL response type.