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
Serverexecutes queries, mutations and subscriptions. It has no HTTP types. It also owns the optional error formatter that redacts messages before a client sees them.httpis a transport-agnostic request handler. Any framework can call it with request parts and a body.axummounts aServeron an Axum router (enabled by the defaultaxumfeature).wsdrives onegraphql-transport-wsconnection over any text-message stream (enabled by the defaultwsfeature, which impliesaxum).
§Feature flags
| Feature | Default | Purpose |
|---|---|---|
axum | yes | The axum router and ExtractContext integration. |
ws | yes | graphql-transport-ws WebSocket subscriptions. Enables axum. |
multipart | yes | GraphQL multipart requests; uses multer. |
vendored-graphiql | no | Self-contained GraphiQL page with pinned browser assets. |
tracing | no | Request 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-streamstreams subscription events asevent: next/data:frames. - WebSocket —
graphql-transport-wsover 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 thatContext. - Multipart — the GraphQL multipart request shape, with files inserted as
gql::Uploadvalues 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
axumfeature). - 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.
- Error
Context - Context handed to an error formatter.
- GraphQL
Request - A GraphQL-over-HTTP request body.
- Request
Error - An error that occurred before or while interpreting a request.
- Server
- A GraphQL server.
- Upload
- A file supplied by a multipart request.
- Upload
Binding - A file attached to a path inside a request’s variables.
Enums§
- Error
Kind - Whether an error happened before execution or during it.
- Request
Payload - 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_internalfor errors that are not safe to expose.
Traits§
- Error
Formatter - A function that rewrites errors before they are returned to a client.
- Response
Ext - 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§
- GraphQL
Response - The canonical GraphQL response type.