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
• 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.
• 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.
• string_number: Enable the StringNumber.
• dataloader: Support DataLoader.
• decimal: Integrate with the rust_decimal crate.
• cbor: Support for serde_cbor.

Integrations

• Actix-web async-graphql-actix_web
• Warp async-graphql-warp
• Tide async-graphql-tide

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 resolver_utils::ContainerType;

pub use resolver_utils::EnumType;

pub use resolver_utils::ScalarType;

pub use context::*;

pub use parser::Pos;

pub use parser::Positioned;

pub use types::*;

Modules

context

Query context.

dataloaderdataloader

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

extensions

Extensions for schema

guard

Field guards

http

A helper module that supports HTTP

resolver_utils

Utilities for implementing OutputType::resolve.

types

Useful GraphQL types.

validators

Input value validators

Macros

scalar

Define a scalar

value

Construct a ConstValue.

Structs

CacheControl

Cache control values

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.

ResolverError

A wrapper around a dynamic error type for resolver.

Response

Query response

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

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

ErrorExtensions

An error which can be extended into a Error.

InputObjectType

A GraphQL input object.

InputType

Represents a GraphQL input value.

InterfaceType

A GraphQL interface.

ObjectType

A GraphQL object.

OutputType

Represents a GraphQL output value.

ResultExt

Extend a Result’s error value with ErrorExtensions.

Type

Represents a GraphQL type.

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.

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

SimpleObject

Define a GraphQL object with fields

Union

Define a GraphQL union