async-graphql

a high-performance graphql server library that's fully specification compliant

Book • 中文文档 • Docs • GitHub repository • Cargo package

This crate uses #![forbid(unsafe_code)] to ensure everything is implemented in 100% safe Rust.

Static schema

use std::error::Error;

use async_graphql::{http::GraphiQLSource, EmptyMutation, EmptySubscription, Object, Schema};
use async_graphql_poem::*;
use poem::{listener::TcpListener, web::Html, *};

struct Query;

#[Object]
impl Query {
    async fn howdy(&self) -> &'static str {
        "partner"
    }
}

#[handler]
async fn graphiql() -> impl IntoResponse {
    Html(GraphiQLSource::build().finish())
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // create the schema
    let schema = Schema::build(Query, EmptyMutation, EmptySubscription).finish();

    // start the http server
    let app = Route::new().at("/", get(graphiql).post(GraphQL::new(schema)));
    println!("GraphiQL: http://localhost:8000");
    Server::new(TcpListener::bind("0.0.0.0:8000"))
        .run(app)
        .await?;
    Ok(())
}

Dynamic schema

Requires the dynamic-schema feature to be enabled.

use std::error::Error;

use async_graphql::{dynamic::*, http::GraphiQLSource};
use async_graphql_poem::*;
use poem::{listener::TcpListener, web::Html, *};

#[handler]
async fn graphiql() -> impl IntoResponse {
    Html(GraphiQLSource::build().finish())
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let query = Object::new("Query").field(Field::new(
        "howdy",
        TypeRef::named_nn(TypeRef::STRING),
        |_| FieldFuture::new(async { "partner" }),
    ));

    // create the schema
    let schema = Schema::build(query, None, None).register(query).finish()?;

    // start the http server
    let app = Route::new().at("/", get(graphiql).post(GraphQL::new(schema)));
    println!("GraphiQL: http://localhost:8000");
    Server::new(TcpListener::bind("0.0.0.0:8000"))
        .run(app)
        .await?;
    Ok(())
}

⚠️Security

I strongly recommend limiting the complexity and depth of queries in a production environment to avoid possible DDos attacks.

• SchemaBuilder.limit_complexity
• SchemaBuilder.limit_depth
• SchemaBuilder.limit_directives

Features

• Static and dynamic schemas are fully supported
• Fully supports async/await
• Type safety
• Rustfmt friendly (Procedural Macro)
• Custom scalars
• Minimal overhead
• Easy integration (poem, axum, actix-web, tide, warp, rocket ...)
• Upload files (Multipart request)
• Subscriptions (WebSocket transport)
• Custom extensions
• Error extensions
• Limit query complexity/depth
• Batch queries
• Apollo Persisted Queries
• Apollo Tracing extension
• Apollo Federation(v2)

Note: Minimum supported Rust version: 1.75.0 or later

Examples

All examples are in the sub-repository, located in the examples directory.

git submodule update # update the examples repo
cd examples && cargo run --bin [name]

For more information, see the sub-repository README.md.

Integrations

Integrations are what glue async-graphql with your web server, here are provided ones, or you can build your own!

• 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

Crate features

This crate offers the following features. Most are not activated by default, except the integrations of GraphiQL (graphiql) and GraphQL Playground (playground):

Observability

One of the tools used to monitor your graphql server in production is Apollo Studio. Apollo Studio is a cloud platform that helps you build, monitor, validate, and secure your organization's data graph. Add the extension crate async_graphql_apollo_studio_extension to make this avaliable.

Who's using async-graphql in production?

• Vector
• DiveDB
• Kairos Sports tech
• AxieInfinity
• Nando's
• Prima.it
• VoxJar
• Zenly
• Brevz
• thorndyke
• My Data My Consent

Community Showcase

• rust-actix-graphql-sqlx-postgresql Using GraphQL with Rust and Apollo Federation
• entity-rs A simplistic framework based on TAO, Facebook's distributed database for Social Graph.
• vimwiki-server Provides graphql server to inspect and manipulate vimwiki files.
• Diana Diana is a GraphQL system for Rust that's designed to work as simply as possible out of the box, without sacrificing configuration ability.
• cindythink
• sudograph

Blog Posts

• Async GraphQL with Rust
• GraphQL in Rust
• How to implement a Rust micro-service using Rocket, GraphQL, PostgreSQL
• Running GraphQL on Lambda with Rust

References

• GraphQL
• GraphQL Multipart Request
• Multipart HTTP protocol for GraphQL subscriptions
• GraphQL Cursor Connections Specification
• GraphQL over WebSocket Protocol
• Apollo Tracing
• Apollo Federation

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.