<div align="center">
<samp>

# gqlrs

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

</samp>

[Repository](https://github.com/smartcrabai/gqlrs) • [Upstream Book](https://async-graphql.github.io/async-graphql/en/index.html) • [Upstream 中文文档](https://async-graphql.github.io/async-graphql/zh-CN/index.html) • [Upstream Docs](https://docs.rs/async-graphql) • [Upstream Cargo package](https://crates.io/crates/async-graphql)

---

[![Unsafe Rust forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg)](https://github.com/rust-secure-code/safety-dance/)

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

</div>

## About this project

`gqlrs` is a rebranded clone of the upstream [`async-graphql`](https://github.com/async-graphql/async-graphql) project.
This repository keeps an explicit reference to the original project while using the `gqlrs` name for this codebase and package metadata.

For compatibility with the existing Rust API and examples, many code snippets still import the crate under the `async_graphql` alias. When depending on the rebranded package directly, use Cargo's `package` key if you want to keep that alias:

```toml
[dependencies]
async-graphql = { package = "gqlrs", version = "0.1.0" }
```

## Static schema

```rs
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.

```rs
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](https://async-graphql.github.io/async-graphql/en/depth_and_complexity.html?highlight=complex#limiting-query-complexity) of queries in a production environment to avoid possible DDos attacks.

- [SchemaBuilder.limit_complexity](https://docs.rs/async-graphql/latest/async_graphql/struct.SchemaBuilder.html#method.limit_complexity)
- [SchemaBuilder.limit_depth](https://docs.rs/async-graphql/latest/async_graphql/struct.SchemaBuilder.html#method.limit_depth)
- [SchemaBuilder.limit_directives](https://docs.rs/async-graphql/latest/async_graphql/struct.SchemaBuilder.html#method.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](https://crates.io/crates/poem), [axum](https://crates.io/crates/axum), [actix-web](https://crates.io/crates/actix-web), [warp](https://crates.io/crates/warp), [rocket](https://crates.io/crates/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.89.0 or later

## Examples

All examples are in the [sub-repository](https://github.com/async-graphql/examples), located in the examples directory.

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

For more information, see the [sub-repository](https://github.com/async-graphql/examples) README.md.

## Integrations

Integrations are what glue `gqlrs` with your web server, here are provided ones, or you can build your own!

- Poem `gqlrs-poem`
- Actix-web `gqlrs-actix-web`
- Warp `gqlrs-warp`
- Rocket `gqlrs-rocket`
- Axum `gqlrs-axum`

## Crate features

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

| feature                        | enables                                                                                                                                                                                       |
| :----------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`apollo_tracing`**           | Enable the [Apollo tracing extension](https://docs.rs/async-graphql/latest/async_graphql/extensions/struct.ApolloTracing.html).                                                               |
| **`apollo_persisted_queries`** | Enable the [Apollo persisted queries extension](https://docs.rs/async-graphql/latest/async_graphql/extensions/apollo_persisted_queries/struct.ApolloPersistedQueries.html).                   |
| **`boxed-trait`**              | Enables [`async-trait`](https://crates.io/crates/async-trait) for all traits.                                                                                                                 |
| **`chrono`**                   | Integrate with the [`chrono` crate](https://crates.io/crates/chrono).                                                                                                                         |
| **`chrono-tz`**                | Integrate with the [`chrono-tz` crate](https://crates.io/crates/chrono-tz).                                                                                                                   |
| **`dataloader`**               | Support [DataLoader](dataloader/struct.DataLoader.html).                                                                                                                                      |
| **`decimal`**                  | Integrate with the [`rust_decimal` crate](https://crates.io/crates/rust_decimal).                                                                                                             |
| **`dynamic-schema`**           | Support dynamic schema                                                                                                                                                                        |
| **`fast-check`**               | Generate minimal derive macro stubs for faster `cargo check` and rust-analyzer feedback during development.                                                                                   |
| **`graphiql`**                 | Enables the [GraphiQL IDE](https://github.com/graphql/graphiql) integration                                                                                                                   |
| **`log`**                      | Enable the [Logger extension](https://docs.rs/async-graphql/latest/async_graphql/extensions/struct.Logger.html).                                                                              |
| **`rawvalue`**                 | Support raw values from [`serde_json`](https://crates.io/crates/serde_json)                                                                                                                   |
| **`secrecy`**                  | Integrate with the [`secrecy` crate](https://crates.io/crates/secrecy).                                                                                                                       |
| **`string_number`**            | Enable the [StringNumber](types/struct.StringNumber.html).                                                                                                                                    |
| **`time`**                     | Integrate with the [`time` crate](https://github.com/time-rs/time).                                                                                                                           |
| **`tracing`**                  | Enable the [Tracing extension](https://docs.rs/async-graphql/latest/async_graphql/extensions/struct.Tracing.html).                                                                            |
| **`tempfile`**                 | Save the uploaded content in the temporary file.                                                                                                                                              |
| **`unblock`**                  | Support [Asynchronous reader for Upload](types/struct.Upload.html)                                                                                                                            |
| **`uuid`**                     | Integrate with the [`uuid` crate](https://crates.io/crates/uuid).                                                                                                                             |
| **`url`**                      | Integrate with the [`url` crate](https://crates.io/crates/url).                                                                                                                               |

### Extra Extensions

Additional extensions are available in the [`gqlrs-extras`](./extras) crate. These extensions require additional dependencies and are maintained separately.

See the [extras crate README](./extras/README.md) for more information.

### 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`](https://github.com/async-graphql/async_graphql_apollo_studio_extension) to make this available.

## Who's using upstream `async-graphql` in production?

- [Vector](https://vector.dev/)
- [DiveDB](https://divedb.net)
- [Kairos Sports tech](https://kairostech.io/)
- [AxieInfinity](https://axieinfinity.com/)
- [Nando's](https://www.nandos.co.uk/)
- [Prima.it](https://www.prima.it/)
- [VoxJar](https://voxjar.com/)
- [Zenly](https://zen.ly/)
- [Brevz](https://brevz.io/)
- [thorndyke](https://www.thorndyke.ai/)
- [My Data My Consent](https://mydatamyconsent.com/)

## Community Showcase

- [rust-actix-graphql-sqlx-postgresql](https://github.com/camsjams/rust-actix-graphql-sqlx-postgresql)
  Using GraphQL with Rust and Apollo Federation
- [entity-rs](https://github.com/chipsenkbeil/entity-rs) A simplistic framework based on TAO, Facebook's distributed database for Social Graph.
- [vimwiki-server](https://github.com/chipsenkbeil/vimwiki-rs/tree/master/vimwiki-server) Provides graphql server to inspect and manipulate vimwiki files.
- [Diana](https://github.com/arctic-hen7/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](https://www.cindythink.com/)
- [sudograph](https://github.com/sudograph/sudograph)
- [grpc_graphql_gateway](https://github.com/Protocol-Lattice/grpc_graphql_gateway) is an open-source protoc plugin that generates GraphQL execution server code from your gRPC/Protocol Buffers definitions.

## Blog Posts

- [Async GraphQL with Rust](https://formidable.com/blog/2022/async-graphql-with-rust-1/)
- [GraphQL in Rust](https://romankudryashov.com/blog/2020/12/graphql-rust/)
- [How to implement a Rust micro-service using Rocket, GraphQL, PostgreSQL](https://lionkeng.medium.com/how-to-implement-a-rust-micro-service-using-rocket-graphql-postgresql-a3f455f2ae8b)
- [Running GraphQL on Lambda with Rust](https://dylananthony.com/posts/graphql-lambda-rust)

## References

- [GraphQL](https://graphql.org)
- [GraphQL Multipart Request](https://github.com/jaydenseric/graphql-multipart-request-spec)
- [Multipart HTTP protocol for GraphQL subscriptions](https://www.apollographql.com/docs/router/executing-operations/subscription-multipart-protocol/)
- [GraphQL Cursor Connections Specification](https://facebook.github.io/relay/graphql/connections.htm)
- [GraphQL over WebSocket Protocol](https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md)
- [Apollo Tracing](https://github.com/apollographql/apollo-tracing)
- [Apollo Federation](https://www.apollographql.com/docs/apollo-server/federation/introduction)

## License

Licensed under either of

- Apache License, Version 2.0,
  ([LICENSE-APACHE](./LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](./LICENSE-MIT) or http://opensource.org/licenses/MIT)
  at your option.
