1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
//! 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
//!
//! | 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:
//!
//! ```toml
//! suku = { version = "0.1.0", 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
//!
//! ```no_run
//! use suku::{Context, GraphQLRequest, Server};
//!
//! # async fn run(schema: gql::Schema) {
//! let server = Server::new(schema).introspection(true).max_depth(12);
//! let response = server
//! .execute(&GraphQLRequest::new("{ hello }"), Context::empty())
//! .await;
//! # let _ = response;
//! # }
//! ```
//!
//! Mounting on Axum:
//!
//! ```no_run
//! # #[cfg(feature = "axum")]
//! # fn run(schema: gql::Schema) {
//! let app = suku::axum::GraphQL::new(suku::Server::new(schema))
//! .path("/graphql")
//! .graphiql(true)
//! .into_router();
//! # let _ = app;
//! # }
//! ```
//!
//! # 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:
//!
//! ```toml
//! [dependencies]
//! suku = { version = "0.1.0", 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`.
pub use crate::;
pub use Upload;
pub use crateDEFAULT_MAX_MULTIPART_PARTS;
pub use crate;
pub use crate;
pub use crate;
pub use crateGraphQL;