gql 0.3.2

A GraphQL reference implementation for Rust.
Documentation

gql

A GraphQL reference implementation for Rust.

gql implements the GraphQL October 2021 specification:

  • lexer, parser and borrowed AST for executable documents and SDL
  • the complete type system: scalars, objects, interfaces, unions, enums, input objects, directives
  • full document validation
  • execution with variables, arguments, aliases, fragments, directives, lists, null propagation, errors and response paths
  • queries, mutations and subscriptions
  • introspection (__schema, __type, __typename)
  • query depth and complexity analysis
  • prepared (persisted) queries that skip parsing and validation on every request
  • schema printing, SDL import and backwards-compatibility diffing
  • pluggable field authorization

It is deliberately transport- and framework-agnostic. gql knows nothing about HTTP, databases, authentication or a particular high-level API. A schema is built with SchemaBuilder, or generated by a higher-level crate such as gurafi, and served by a transport such as suku.

use gql::{Field, ObjectType, Schema, TypeRef, Value};

let mut builder = Schema::builder();
builder.add_type(
    ObjectType::new("Query")
        .field(Field::new("hello", TypeRef::string().non_null()).resolve(|_| {
            Box::pin(async { Ok(Value::from("world")) })
        }))
        .into(),
);

let schema = builder.query("Query").build().expect("valid schema");
let response = futures::executor::block_on(gql::execute(
    &schema,
    gql::Request::new("{ hello }"),
    &gql::ExecutionOptions::default(),
));

assert_eq!(response.data.unwrap().as_object().unwrap().get("hello").unwrap().as_str(), Some("world"));

Prepared queries

gql::execute parses and validates every document it receives, which is what an endpoint that accepts arbitrary client documents needs. Once a document is trusted (for example, an operation loaded from a build-time manifest), prepare it once and execute it many times:

# use gql::{ExecutionOptions, Schema};
# fn run(schema: &Schema) {
let prepared = gql::prepared::PreparedQuery::new(
    schema,
    "dashboard",
    "query Dashboard { hello }",
    None,
)
.expect("valid query");

let response = futures::executor::block_on(
    prepared.execute(None, &ExecutionOptions::default()),
);
# let _ = response;
# }

A prepared query owns its source and AST safely, is Send + Sync, and applies the same variables, complexity limits, introspection policy, authorization, timeouts and null propagation as normal execution. PreparedQueryRegistry builds a named set with duplicate-id detection, and gql::execute_prepared is the free-function form of PreparedQuery::execute.

Preparation is done against one schema instance. Cloning a schema shares that instance, but two separately built schemas do not compare equal: use Schema::ptr_eq when the distinction matters. A prepared query stores its schema, so callers that dispatch prepared work next to a different schema should check the instance first (suku does this for its servers). Complexity is checked with a conservative bound computed at preparation; documents with field-level complexity estimators fall back to the exact per-request analysis, because estimator results can depend on request variables.

Features

Feature Default Description
serde yes serde::Serialize for Value, Object, GraphQLError and Response
tracing no optional spans for parsing, validation, execution, fields, subscriptions and schema construction

Observability

Enable the optional feature to instrument parsing, validation, variable coercion, field execution, subscriptions and schema construction:

[dependencies]
gql = { version = "0.3", features = ["tracing"] }

Spans are hierarchical (gql.execute → gql.execute_operation → gql.field) and record shapes, counts and timings rather than variable values, arguments or document text. Field spans are DEBUG and collection spans are TRACE; enable them while investigating an operation, and keep INFO for request summaries. See docs/plugins/tracing.md for the full catalog and the recommended tracing-subscriber setup.