Expand description
§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, 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
- Relay 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. |
relay_persisted_queries | Enable the Relay persisted queries extension. |
boxed-trait | Enables async-trait for all traits. |
no_send | Removes Send + Sync bounds from traits and futures. Enables the crate for use in single-threaded runtimes such as Cloudflare Workers. |
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-check | Generate minimal derive macro stubs for faster cargo check and rust-analyzer feedback during development. |
fast_chemail | Integrate with the fast_chemail crate. |
graphiql | Enables the GraphiQL IDE integration |
jiff | Integrate with the jiff crate. |
log | Enable the Logger extension. |
opentelemetry | Enable the OpenTelemetry extension. |
rawvalue | Support raw values from serde_json |
secrecy | Integrate with the secrecy 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. |
unblock | Support Asynchronous reader for Upload |
uuid | Integrate with the uuid crate. |
url | Integrate with the url crate. |
wide-integer-scalars | Enable GraphQL Int scalar implementations for Rust integer types that can hold values outside the signed 32-bit GraphQL Int range. |
§Integrations
- Poem
gqlrs-poem - Actix-web
gqlrs-actix-web - Warp
gqlrs-warp - Rocket
gqlrs-rocket - Axum
gqlrs-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 benchNow a HTML report is available at benchmark/target/criterion/report.
Re-exports§
pub use base::InputObjectType;pub use base::InputType;pub use base::InterfaceType;pub use base::ObjectType;pub use base::OneofObjectType;pub use base::OutputType;pub use base::OutputTypeMarker;pub use base::TypeName;pub use base::UnionType;pub use custom_directive::CustomDirective;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::IntrospectionMode;pub use schema::Schema;pub use schema::SchemaBuilder;pub use sendable::MaybeSend;pub use sendable::MaybeSync;pub use validation::ValidationMode;pub use validation::ValidationResult;pub use async_graphql_parser as parser;pub use context::*;pub use types::*;
Modules§
- context
- Query context.
- dataloader
dataloader - Batch loading support, used to solve N+1 problem.
- dynamic
dynamic-schema - Support for dynamic schema
- extensions
- Extensions for schema
- http
- A helper module that supports HTTP
- resolver_
utils - Utilities for implementing
OutputType::resolve. - runtime
- Runtime abstraction traits
- sendable
- Conditional
Send/Syncbounds for single-threaded runtime support. - types
- Useful GraphQL types.
Macros§
Structs§
- Cache
Control - Cache control value
- Deserializer
Error - This type represents errors that can occur when deserializing.
- Error
- An error with a message and optional extensions.
- Error
Extension Values - Extensions to the error.
- Extensions
- Extensions of a query.
- Input
Value Error - 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
- SDLExport
Options - Options for SDL export
- Schema
- GraphQL schema.
- Schema
Builder - Schema builder
- Serializer
Error - This type represents errors that can occur when serializing.
- Server
Error - An error in a GraphQL server.
- Validation
Result - Validation results.
- Validator
Adapter validator - Adapter that bridges the
validator::Validatetrait to async-graphql’sCustomValidator. - Variables
- Variables of a query.
Enums§
- Batch
Request - Batch support for GraphQL requests, which is either a single query, or an array of queries
- Batch
Response - Response for batchable queries
- Introspection
Mode - Introspection mode
- Parse
Request Error - An error parsing the request.
- Path
Segment - A segment of path to a resolver.
- Validation
Mode - Validation mode
- Value
- A resolved GraphQL value, for example
1or"Hello World!".
Traits§
- Custom
Directive - Represents a custom directive.
- Custom
Validator - Represents a custom input value validator.
- Custom
Validator With Context - Represents a custom input value validator that has access to the request context.
- Error
Extensions - An error which can be extended into a
Error. - Executor
- Represents a GraphQL executor
- Guard
- Field guard
- Guard
Ext - An extension trait for
Guard. - Input
Object Type - A GraphQL input object.
- Input
Type - Represents a GraphQL input type.
- Interface
Type - A GraphQL interface.
- Into
Error - A trait for types that can be converted into a GraphQL [
Error]. - Object
Type - A GraphQL object.
- Oneof
Object Type - A GraphQL oneof input object.
- Output
Type - Represents a GraphQL output type.
- Output
Type Marker - Marker trait for GraphQL output type metadata.
- Result
Ext - Extend a
Result’s error value withErrorExtensions. - Subscription
Type - A GraphQL subscription object
- Type
Name - Used to specify the GraphQL Type name.
- Union
Type - A GraphQL interface.
- Validator
Ext validator - Extension trait for converting
validator::ValidationErrorsintoInputValueError.
Functions§
- from_
value - Interpret a
ConstValueas an instance of typeT. - to_
value - Convert a
TintoConstValuewhich is an enum that can represent any valid GraphQL data.
Type Aliases§
- Error
Formatter no_send - Field
Error - An alias of gqlrs::Error. Present for backward compatibility reasons.
- Field
Result - An alias of gqlrs::Result. Present for backward compatibility reasons.
- Input
Value Result - An error parsing a value of type
T. - Result
- An alias for
Result<T, Error>. - Server
Result - Alias for
Result<T, ServerError>.
Attribute Macros§
- Complex
Interface - Define resolvers for an interface type at the interface level.
- Complex
Object - 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
- Type
Directive
Derive Macros§
- Description
- Attach a description to
Object,ScalarorSubscription. - Enum
- Define a GraphQL enum
- Input
Object - Define a GraphQL input object
- Interface
- Define a GraphQL interface
- Merged
Object - Define a merged object with multiple object types.
- Merged
Subscription - Define a merged subscription with multiple subscription types.
- NewType
- Define a NewType Scalar
- Oneof
Object - Define a GraphQL oneof input object
- Simple
Object - Define a GraphQL object with fields
- Union
- Define a GraphQL union