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:

• 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.
• tempfile: Save the uploaded content in the temporary file.
• dynamic-schema: Support dynamic schema.

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