Crate async_graphql

A GraphQL server library implemented in Rust

Documentation

• Book
• 中文文档
• Docs
• GitHub repository
• Cargo package
• Minimum supported Rust version: 1.56.1 or later

Features

• Fully supports async/await
• Type safety
• Rustfmt friendly (Procedural Macro)
• Custom scalars
• Minimal overhead
• Easy integration (poem, actix_web, tide, warp, rocket …)
• File upload (Multipart request)
• Subscriptions (WebSocket transport)
• Custom extensions
• Apollo Tracing extension
• Limit query complexity/depth
• Error Extensions
• Apollo Federation(v2)
• Batch Queries
• Apollo Persisted Queries

Crate features

This crate offers the following features, all of which are not activated by default:

feature	enables
apollo_tracing	Enable the Apollo tracing extension.
apollo_persisted_queries	Enable the Apollo persisted queries extension.
boxed-trait	Enables async-trait for all traits.
bson	Integrate with the bson crate.
bigdecimal	Integrate with the bigdecimal crate.
cbor	Support for serde_cbor.
chrono	Integrate with the chrono crate.
chrono-tz	Integrate with the chrono-tz crate.
dataloader	Support DataLoader.
decimal	Integrate with the rust_decimal crate.
dynamic-schema	Support dynamic schema
fast_chemail	Integrate with the fast_chemail crate.
graphiql	Enables the GraphiQL IDE integration
hashbrown	Integrate with the hashbrown crate.
log	Enable the Logger extension.
opentelemetry	Enable the OpenTelemetry extension.
playground	Enables the GraphQL playground IDE integration
rawvalue	Support raw values from serde_json
secrecy	Integrate with the secrecy crate.
smol_str	Integrate with the smol_str crate.
string_number	Enable the StringNumber.
time	Integrate with the time crate.
tracing	Enable the Tracing extension.
tempfile	Save the uploaded content in the temporary file.
tokio-sync	Integrate with the tokio::sync::RwLock and tokio::sync::Mutex.
unblock	Support Asynchronous reader for Upload
uuid	Integrate with the uuid crate.
url	Integrate with the url crate.

Integrations

• Poem async-graphql-poem
• Actix-web async-graphql-actix-web
• Warp async-graphql-warp
• Tide async-graphql-tide
• Rocket async-graphql-rocket
• Axum async-graphql-axum

License

Licensed under either of

• Apache License, Version 2.0, (./LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (./LICENSE-MIT or http://opensource.org/licenses/MIT) at your option.

References

• GraphQL
• GraphQL Multipart Request
• GraphQL Cursor Connections Specification
• GraphQL over WebSocket Protocol
• Apollo Tracing
• Apollo Federation

Examples

All examples are in the sub-repository, located in the examples directory.

Run an example:

git submodule update # update the examples repo
cd examples && cargo run --bin [name]

Benchmarks

Ensure that there is no CPU-heavy process in background!

cd benchmark
cargo bench

Now a HTML report is available at benchmark/target/criterion/report.

Re-exports

pub use extensions::ResolveFut;

pub use parser::Pos;

pub use parser::Positioned;

pub use resolver_utils::ContainerType;

pub use resolver_utils::EnumType;

pub use resolver_utils::ScalarType;

pub use async_graphql_parser as parser;

pub use context::*;

pub use types::*;

Modules

context

Query context.

dataloaderdataloader

Batch loading support, used to solve N+1 problem.

dynamicdynamic-schema

Support for dynamic schema

extensions

Extensions for schema

http

A helper module that supports HTTP

resolver_utils

Utilities for implementing OutputType::resolve.

types

Useful GraphQL types.

Macros

scalar

Define a scalar

value

Construct a ConstValue.

Structs

CacheControl

Cache control value

DeserializerError

This type represents errors that can occur when deserializing.

Error

An error with a message and optional extensions.

ErrorExtensionValues

Extensions to the error.

Extensions

Extensions of a query.

InputValueError

An error parsing an input value.

Lookahead

A selection performed by a query.

Name

A GraphQL name.

Number

Represents a JSON number, whether integer or floating point.

Request

GraphQL request.

Response

Query response

SDLExportOptions

Options for SDL export

Schema

GraphQL schema.

SchemaBuilder

Schema builder

SerializerError

This type represents errors that can occur when serializing.

ServerError

An error in a GraphQL server.

ValidationResult

Validation results.

Variables

Variables of a query.

Enums

BatchRequest

Batch support for GraphQL requests, which is either a single query, or an array of queries

BatchResponse

Response for batchable queries

IntrospectionMode

Introspection mode

ParseRequestError

An error parsing the request.

PathSegment

A segment of path to a resolver.

ValidationMode

Validation mode

Value

A resolved GraphQL value, for example 1 or "Hello World!".

Traits

CustomDirective

Represents a custom directive.

CustomValidator

Represents a custom input value validator.

ErrorExtensions

An error which can be extended into a Error.

Executor

Represents a GraphQL executor

Guard

Field guard

GuardExt

An extension trait for Guard.

InputObjectType

A GraphQL input object.

InputType

Represents a GraphQL input type.

InterfaceType

A GraphQL interface.

ObjectType

A GraphQL object.

OneofObjectType

A GraphQL oneof input object.

OutputType

Represents a GraphQL output type.

ResultExt

Extend a Result’s error value with ErrorExtensions.

SubscriptionType

A GraphQL subscription object

TypeName

Used to specify the GraphQL Type name.

UnionType

A GraphQL interface.

Functions

from_value

Interpret a ConstValue as an instance of type T.

to_value

Convert a T into ConstValue which is an enum that can represent any valid GraphQL data.

Type Aliases

FieldError

An alias of async_graphql::Error. Present for backward compatibility reasons.

FieldResult

An alias of async_graphql::Result. Present for backward compatibility reasons.

InputValueResult

An error parsing a value of type T.

Result

An alias for Result<T, Error>.

ServerResult

Alias for Result<T, ServerError>.

Attribute Macros

ComplexObject

Define a complex GraphQL object for SimpleObject’s complex field resolver.

Directive

Define a directive for query.

Object

Define a GraphQL object with methods

Scalar

Define a Scalar

Subscription

Define a GraphQL subscription

TypeDirective

Derive Macros

Description

Attach a description to Object, Scalar or Subscription.

Enum

Define a GraphQL enum

InputObject

Define a GraphQL input object

Interface

Define a GraphQL interface

MergedObject

Define a merged object with multiple object types.

MergedSubscription

Define a merged subscription with multiple subscription types.

NewType

Define a NewType Scalar

OneofObject

Define a GraphQL oneof input object

SimpleObject

Define a GraphQL object with fields

Union

Define a GraphQL union