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.
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 base::ComplexObject;
• pub use base::Description;
• pub use custom_directive::CustomDirectiveFactory;
• pub use custom_directive::TypeDirective;
• 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 schema::SchemaEnv;
• pub use validation::VisitorContext;
• 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
  Suppport 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.
• 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