Skip to content

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.

crates/nest-rs-graphql/src/config.rs
#[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,
}
FieldEnv varDefaultEffect
path<PREFIX>_GRAPHQL__PATH/graphqlMount 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__PLAYGROUNDSurface::ByProfile: open in development and testWhen open, GET <path> serves the GraphQL Playground page, which loads its scripts, styles and fonts from third-party hosts (The playground).
emit<PREFIX>_GRAPHQL__EMITSurface::ByProfile: open in developmentWhen 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_PATHschema.graphqlWhere the SDL gets written; a relative path is the app crate’s (SDL emission).
max_depth<PREFIX>_GRAPHQL__MAX_DEPTH15Bound 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_COMPLEXITY2000Bound 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_BYTES4096Bound 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__INTROSPECTIONSurface::ByProfile: open in development and testWhen open, the schema answers introspection queries (__schema, __type).
max_batch_size<PREFIX>_GRAPHQL__MAX_BATCH_SIZE10Maximum operations in a single HTTP batch request, from 1 to 1024, never off.
max_connection<PREFIX>_GRAPHQL__MAX_CONNECTION_SECS14400 (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_BYTES65536 (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_SECS3How 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_SECS20How 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_SECS20How 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_OPERATIONS100Operations 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_REPRESENTATIONS100Bound 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_MEMBERSHIPfalseWhen true, a resolver no imported module owns fails the boot instead of warning.
federation<PREFIX>_GRAPHQL__FEDERATIONfalseServe 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_SDLSurface::ClosedWhether 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.

Every module’s config follows this rule (framework-wide):

crates/features/src/posts/graphql/module.rs — env-driven
use nest_rs::core::module;
use super::resolver::PostsResolver;
use crate::posts::PostsModule;
#[module(imports = [PostsModule], providers = [PostsResolver])]
pub struct PostsGraphqlModule;
.env.production
NESTRS_GRAPHQL__MAX_COMPLEXITY=1200
apps/api/src/module.rs — pinned at the import site
use 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.

GraphqlModule mounts on HttpTransport at path:

  • POST <path> — GraphQL operations (queries + mutations): one JSON request, a JSON array of up to max_batch_size of them (a longer one is answered 413), 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, when playground is on. With the playground off, a plain GET is answered 405 with Allow: POST: a GraphQL request travels as a POST here.

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.

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.

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.

dev workflow
$ nestrs run dev api
# apps/api/schema.graphql is rewritten before the app starts serving
$ git diff apps/api/schema.graphql # see the wire change

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

Before shipping:

  • <PREFIX>_ENV=production declared, or left unset: the playground, introspection and the SDL emit stay off. A boot that opens a surface says so at warn.
  • <PREFIX>_GRAPHQL__MAX_DEPTH set (a value of 15 fits most apps).
  • <PREFIX>_GRAPHQL__MAX_COMPLEXITY set after calibrating against observed legitimate traffic. See Query limits.
  • path matches 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.
  • crates/nest-rs-graphql/src/config.rs — the GraphqlConfig struct, whose overlay #[config] derives.
  • crates/nest-rs-graphql/src/module.rs — the for_root / register glue that turns the config into route mounts.
  • GraphQL — the section landing and full schema wiring.
  • Query limits — the depth and complexity ceilings set here.
  • HTTP — the transport this endpoint mounts on.