Crate async_graphql

A GraphQL server library implemented in Rust

Documentation

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

Features

• Fully supports async/await
• Type safety
• Rustfmt friendly (Procedural Macro)
• Custom scalars
• Minimal overhead
• Easy integration (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.

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