Crate async_graphql

A GraphQL server library implemented in Rust

Documentation

• Feature Comparison
• 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:

• apollo_tracing: Enable the Apollo tracing extension.
• apollo_persisted_queries: Enable the [Apollo persisted queries extension](extensions/apollo_persisted_queries/struct. ApolloPersistedQueries.html).
• log: Enable the logger extension.
• tracing: Enable the tracing extension.
• opentelemetry: Enable the OpenTelemetry extension.
• unblock: Support asynchronous reader for Upload
• bson: Integrate with the bson crate.
• chrono: Integrate with the chrono crate.
• chrono-tz: Integrate with the chrono-tz crate.
• url: Integrate with the url crate.
• uuid: Integrate with the uuid crate.
• uuid08: Integrate with the uuid 0.8 crate.
• string_number: Enable the StringNumber.
• dataloader: Support DataLoader.
• secrecy: Integrate with the secrecy crate.
• decimal: Integrate with the rust_decimal crate.
• bigdecimal: Integrate with the bigdecimal crate.
• cbor: Support for serde_cbor.
• smol_str: Integrate with the smol_str crate.
• hashbrown: Integrate with the hashbrown crate.
• time: Integrate with the time crate.
• tokio-sync Integrate with the tokio::sync::RwLock and tokio::sync::Mutex.
• fast_chemail: Integrate with the fast_chemail 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 async_graphql_parser as parser;

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 context::*;

pub use types::*;

Modules

context

Query context.

dataloaderdataloader

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

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.

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.

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 Definitions

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

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