GraphQL configuration
GraphqlConfig — the mount path, the playground, introspection and SDL emission: production-safe defaults, development surfaces left to the profile.
A bare GraphqlModule import — the one every resolver brings — reads
<PREFIX>_GRAPHQL__* from the environment; GraphqlModule::for_root(config)
at the app’s root pins a base those variables still overlay, field by field. Every field is settable both ways —
pin host behaviour in code, leave secrets and per-environment toggles to env.
Default is production-safe: the mount path is /graphql, and the playground,
introspection and the SDL emit are each a
Surface left to the profile.
A declared development or test profile opens them: the playground serves and
introspection answers, and a development run writes the schema beside the app’s
manifest. A process that declares no <PREFIX>_ENV runs as production and opens
none of them.
The config struct
Section titled “The config struct”#[config(namespace = "graphql")]pub struct GraphqlConfig { /// Default `/graphql`. pub path: String, /// Serve the playground. `ByProfile` in `Default`: on in development and test. pub playground: Surface, /// (Re)write `emit_path` from the live schema once at boot. /// `ByProfile` in `Default`: on in development. A write failure is logged, never fatal. pub emit: Surface, /// Where the committed SDL lives, relative to the app crate. /// Default `schema.graphql`. pub emit_path: PathBuf, /// Reject queries nesting deeper than this. Default `Some(15)` /// (production-safe); set `None` to disable. See Query limits. pub max_depth: Option<usize>, /// Reject queries whose complexity score exceeds this. Default /// `Some(2000)` (production-safe); set `None` to disable. See Query limits. pub max_complexity: Option<usize>, /// Reject a document whose fields below a list read more than this many /// bytes of arguments, which each row reads again. Default `Some(4096)`; /// set `None` to disable. See Query limits. pub max_list_argument_bytes: Option<usize>, /// Answer introspection queries. `ByProfile` in `Default`: on in development /// and test. pub introspection: Surface, /// Maximum operations in a single HTTP batch request. Default `10`. pub max_batch_size: usize, /// Ceiling on a subscription's lifetime. Default 4 hours; `None` unlimited. pub max_connection: Option<Duration>, /// Byte cap on one graphql-ws message. Default 64 KiB. pub max_message_bytes: usize, /// The wait for `connection_init`. Default 3 seconds. pub connection_init_timeout: Duration, /// Operations one socket runs at once. Default `100`; `None` unlimited. pub max_socket_operations: Option<usize>, /// Serve as an Apollo subgraph. Default `false`. pub federation: bool, /// Boot a subgraph whose guards identify no caller, its SDL served to anyone. /// `Closed` in `Default`: such a subgraph fails the boot. pub federation_sdl: Surface, /// Bound on a federation `_entities` request. Default `100`; `None` /// unlimited. pub max_representations: Option<usize>, /// Fail the boot on an unreachable resolver. Default `false`. pub strict_resolver_membership: bool,}| Field | Env var | Default | Effect |
|---|---|---|---|
path | <PREFIX>_GRAPHQL__PATH | /graphql | Mount point for both POST (operations) and GET (playground, when enabled). One literal path: template syntax ({ }) or what the router reads as a parameter (: * <) fails the boot. |
playground | <PREFIX>_GRAPHQL__PLAYGROUND | Surface::ByProfile: open in development and test | When open, GET <path> serves the GraphQL Playground page, which loads its scripts, styles and fonts from third-party hosts (The playground). |
emit | <PREFIX>_GRAPHQL__EMIT | Surface::ByProfile: open in development | When open, the running app writes its live SDL to emit_path once at boot, said at warn outside a development or test profile. |
emit_path | <PREFIX>_GRAPHQL__EMIT_PATH | schema.graphql | Where the SDL gets written; a relative path is the app crate’s (SDL emission). |
max_depth | <PREFIX>_GRAPHQL__MAX_DEPTH | 15 | Bound on AST nesting depth, from 1 to 33, where async-graphql’s own recursion bound takes over; None disables, as 0 does from the environment. See Query limits. |
max_complexity | <PREFIX>_GRAPHQL__MAX_COMPLEXITY | 2000 | Bound on query complexity score and on what a fragment’s repeats add, from 1 to 10000000; None disables the score, as 0 does from the environment, and leaves the repeats at ten million. See Query limits. |
max_list_argument_bytes | <PREFIX>_GRAPHQL__MAX_LIST_ARGUMENT_BYTES | 4096 | Bound on what the arguments of the fields a list stands above weigh, which each of its rows reads again, from 1 to 1073741824 (a gibibyte); None disables it, as 0 does from the environment, and a pinned Some(0) fails the boot. A root field’s arguments are read once and never counted. See Query limits. |
introspection | <PREFIX>_GRAPHQL__INTROSPECTION | Surface::ByProfile: open in development and test | When open, the schema answers introspection queries (__schema, __type). |
max_batch_size | <PREFIX>_GRAPHQL__MAX_BATCH_SIZE | 10 | Maximum operations in a single HTTP batch request, from 1 to 1024, never off. |
max_connection | <PREFIX>_GRAPHQL__MAX_CONNECTION_SECS | 14400 (4 h) | Ceiling on a subscription’s lifetime. A security control: a socket authenticates once and replays those privileges for as long as it stays open. 0 disables it. |
max_message_bytes | <PREFIX>_GRAPHQL__MAX_MESSAGE_BYTES | 65536 (64 KiB) | Byte cap on one graphql-ws message, held at the protocol layer: a larger frame is never buffered, and the socket closes. From 1 to 1073741824 (a gibibyte), never off. What an operation copies on the socket is held to twice it (Query limits). |
connection_init_timeout | <PREFIX>_GRAPHQL__CONNECTION_INIT_TIMEOUT_SECS | 3 | How long an upgraded socket may wait for connection_init before it closes 4408. From 1 to 60, never off. |
ping_interval | <PREFIX>_GRAPHQL__PING_INTERVAL_SECS | 20 | How long a subscription socket’s peer may send nothing before the server sends it a Ping, which every client answers as it reads. From 1 to 3600; None sends none, as 0 does from the environment. See Subscriptions. |
ping_timeout | <PREFIX>_GRAPHQL__PING_TIMEOUT_SECS | 20 | How long that Ping waits for any frame back before the socket is dropped as its peer’s. From 1 to 3600, never off. |
max_socket_operations | <PREFIX>_GRAPHQL__MAX_SOCKET_OPERATIONS | 100 | Operations one socket runs at once, from 1 to 10000; a subscribe past it is answered an error message for its id. None disables it, as 0 does from the environment; a pinned Some(0) fails the boot. |
max_representations | <PREFIX>_GRAPHQL__MAX_REPRESENTATIONS | 100 | Bound on the representations a federation _entities call may ask for in one request, from 1 to 100000. None disables it, as 0 does from the environment; a pinned Some(0) fails the boot. |
strict_resolver_membership | <PREFIX>_GRAPHQL__STRICT_RESOLVER_MEMBERSHIP | false | When true, a resolver no imported module owns fails the boot instead of warning. |
federation | <PREFIX>_GRAPHQL__FEDERATION | false | Serve as an Apollo subgraph: declares the federation directives and exports the subgraph SDL form. An #[entity] declared while this is false fails the boot. See Federation. |
federation_sdl | <PREFIX>_GRAPHQL__FEDERATION_SDL | Surface::Closed | Whether a subgraph whose guards identify no caller boots, serving _service’s SDL to whoever reaches it: closed, it fails the boot naming the guard to add; Surface::Open, or true from the environment, is the opening for a subgraph only its router reaches, said at warn outside a development or test profile; Surface::ByProfile opens it under one of those alone. See Federation. |
The dual path
Section titled “The dual path”Every module’s config follows this rule (framework-wide):
use nest_rs::core::module;
use super::resolver::PostsResolver;use crate::posts::PostsModule;
#[module(imports = [PostsModule], providers = [PostsResolver])]pub struct PostsGraphqlModule;NESTRS_GRAPHQL__MAX_COMPLEXITY=1200use nest_rs::core::module;use nest_rs::graphql::{GraphqlConfig, GraphqlModule};
#[module(imports = [ GraphqlModule::for_root(GraphqlConfig { path: "/api/graphql".into(), ..Default::default() }),])]pub struct ApiModule;Mix both freely — pin the mount path in code (the reverse proxy
depends on it), leave the limits to the deployment’s environment. A pin takes its
whole namespace off the .env cascade: the .env.production line above lands on the
bare import only, and beside a pin the boot names it at warn and leaves it unread. A pin closes nothing it does not name:
..Default::default() keeps the profile’s surfaces under development and test,
and opens none of them in a deployment.
Mount path
Section titled “Mount path”GraphqlModule mounts on HttpTransport at path:
POST <path>— GraphQL operations (queries + mutations): one JSON request, a JSON array of up tomax_batch_sizeof them (a longer one is answered413), or a GraphQL multipart request carrying file uploads, each held to the transport’s body cap.GET <path>— the subscription socket when the request asks to upgrade; otherwise the playground HTML, whenplaygroundis on. With the playground off, a plainGETis answered405withAllow: POST: a GraphQL request travels as aPOSThere.
Any other method is answered 405, with Allow: POST, GET, HEAD.
@defer and @stream are not offered: validation refuses a document using them
as an unknown directive.
An operation’s answer is application/json, status 200 whatever its
errors hold. It carries the schema’s cache hints as Cache-Control when every
operation in it succeeded, and every header a resolver set with
ctx.insert_http_header or ctx.append_http_header.
The path is a route on the HTTP transport, which GraphqlModule imports bare,
so the surrounding HttpModule config (host, port, CORS, TLS, the body cap)
applies as usual.
HTTP configuration covers the transport itself.
The playground
Section titled “The playground”When playground is on, GET <path> serves
async_graphql::http::playground_source, the GraphQL Playground page. The
app serves only its shell: the playground’s script, stylesheet and icon load
from cdn.jsdelivr.net, and its fonts from Google Fonts
(fonts.googleapis.com, fonts.gstatic.com). The browser that opens it needs
to reach those hosts, and a Content-Security-Policy the app sets (see
Default security headers)
must admit them and the page’s inline script and styles.
The page hits the same mount path for its requests, so a
reverse proxy or a path = "/api/graphql" override needs no extra
playground setting.
In development, the playground is the fastest way to read the schema, run a query, and inspect the response with field-level docs — the profile serves it and answers its introspection, with nothing to set. In production, both stay off: rely on the committed SDL, and on introspection-aware clients reading from a development or test environment.
SDL emission
Section titled “SDL emission”A development run rewrites emit_path from the live schema once at
boot: the profile opens emit, and only that one — under test, parallel
suites would rewrite a committed file. The SDL gets sorted (types, fields,
arguments, enum values) so two builds of the same schema produce
byte-identical files — the diff in git tells you what changed.
$ nestrs run dev api# apps/api/schema.graphql is rewritten before the app starts serving$ git diff apps/api/schema.graphql # see the wire changeApps commit schema.graphql next to Cargo.toml. A relative emit_path is
resolved against the directory of the crate #[nest_rs::main] expanded in,
whatever directory the process runs from, so each app of a workspace writes
its own file; an absolute one is written as given. A schema change shows up in
a code review without a separate generator pass or a CI drift-check.
A write failure is logged at warn level (nest_rs::graphql
target), never fatal — the app still starts.
Production checklist
Section titled “Production checklist”Before shipping:
<PREFIX>_ENV=productiondeclared, or left unset: the playground, introspection and the SDL emit stay off. A boot that opens a surface says so atwarn.<PREFIX>_GRAPHQL__MAX_DEPTHset (a value of 15 fits most apps).<PREFIX>_GRAPHQL__MAX_COMPLEXITYset after calibrating against observed legitimate traffic. See Query limits.pathmatches what your gateway / ingress routes to.- The SDL committed in git is the one the production binary serves: a development run rewrites it, and the diff is committed with the change.
Reference
Section titled “Reference”crates/nest-rs-graphql/src/config.rs— theGraphqlConfigstruct, whose overlay#[config]derives.crates/nest-rs-graphql/src/module.rs— thefor_root/registerglue that turns the config into route mounts.
Going further
Section titled “Going further”- GraphQL — the section landing and full schema wiring.
- Query limits — the depth and complexity ceilings set here.
- HTTP — the transport this endpoint mounts on.