diff --git a/README.md b/README.md index 5e0f4d03..d068eab1 100644 --- a/README.md +++ b/README.md @@ -1,102 +1,79 @@ -# A GraphQL server library implemented in Rust -
- - - - - - - Crates.io version - - - - Download - - - - docs.rs docs - - - Unsafe Rust forbidden - + + +# async-graphql + +**a high-performance graphql server library that's fully specification compliant** + + + +[Feature Comparison](feature-comparison.md) • [Book](https://async-graphql.github.io/async-graphql/en/index.html) • [中文文档](https://async-graphql.github.io/async-graphql/zh-CN/index.html) • [Docs](https://docs.rs/async-graphql) • [GitHub repository](https://github.com/async-graphql/async-graphql) • [Cargo package](https://crates.io/crates/async-graphql) + +--- + +![ci status](https://github.com/async-graphql/async-graphql/workflows/CI/badge.svg) +[![code coverage](https://codecov.io/gh/async-graphql/async-graphql/branch/master/graph/badge.svg)](https://codecov.io/gh/async-graphql/async-graphql/) +[![Unsafe Rust forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg)](https://github.com/rust-secure-code/safety-dance/) +[![Crates.io version](https://img.shields.io/crates/v/async-graphql.svg)](https://crates.io/crates/async-graphql) +[![docs.rs docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://docs.rs/async-graphql) +[![downloads](https://img.shields.io/crates/d/async-graphql.svg)](https://crates.io/crates/async-graphql) +[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/async-graphql/async-graphql/compare) + +_This crate uses `#![forbid(unsafe_code)]` to ensure everything is implemented in 100% safe Rust._ +
-`Async-graphql` is a high-performance server-side library that supports all GraphQL specifications. +```rs +struct Query; -* [Feature Comparison](feature-comparison.md) -* [Book](https://async-graphql.github.io/async-graphql/en/index.html) -* [中文文档](https://async-graphql.github.io/async-graphql/zh-CN/index.html) -* [Docs](https://docs.rs/async-graphql) -* [GitHub repository](https://github.com/async-graphql/async-graphql) -* [Cargo package](https://crates.io/crates/async-graphql) -* Minimum supported Rust version: 1.59.0 or later +#[Object] +impl Query { + fn howdy() -> &'static str { + "partner" + } +} -## Safety +async fn main() { + let schema = Schema::build(Query, EmptyMutation, EmptySubscription).finish(); -This crate uses `#![forbid(unsafe_code)]` to ensure everything is implemented in 100% Safe Rust. + 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 + .unwrap(); +} +``` ## Features -* Fully supports async/await -* Type safety -* Rustfmt friendly (Procedural Macro) -* Custom scalars -* Minimal overhead -* Easy integration ([poem](https://crates.io/crates/poem), actix_web, tide, warp, rocket ...) -* Upload files (Multipart request) -* Subscriptions (WebSocket transport) -* Custom extensions -* Apollo Tracing extension -* Limit query complexity/depth -* Error Extensions -* Apollo Federation -* Batch Queries -* Apollo Persisted Queries +- Fully supports async/await +- Type safety +- Rustfmt friendly (Procedural Macro) +- Custom scalars +- Minimal overhead +- Easy integration ([poem](https://crates.io/crates/poem), 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 -## Crate features - -This crate offers the following features, all of which are not activated by default: - -- `apollo_tracing`: Enable the [Apollo tracing extension](extensions/struct.ApolloTracing.html). -- `apollo_persisted_queries`: Enable the [Apollo persisted queries extension](extensions/apollo_persisted_queries/struct.ApolloPersistedQueries.html). -- `log`: Enable the [logger extension](extensions/struct.Logger.html). -- `tracing`: Enable the [tracing extension](extensions/struct.Tracing.html). -- `opentelemetry`: Enable the [OpenTelemetry extension](extensions/struct.OpenTelemetry.html). -- `unblock`: Support [asynchronous reader for Upload](types/struct.Upload.html) -- `bson`: Integrate with the [`bson` crate](https://crates.io/crates/bson). -- `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). -- `url`: Integrate with the [`url` crate](https://crates.io/crates/url). -- `uuid`: Integrate with the [`uuid` crate](https://crates.io/crates/uuid). -- `uuid08`: Integrate with the [`uuid 0.8` crate](https://crates.io/crates/uuid/0.8.2). -- `string_number`: Enable the [StringNumber](types/struct.StringNumber.html). -- `dataloader`: Support [DataLoader](dataloader/struct.DataLoader.html). -- `secrecy`: Integrate with the [`secrecy` crate](https://crates.io/crates/secrecy). -- `decimal`: Integrate with the [`rust_decimal` crate](https://crates.io/crates/rust_decimal). -- `bigdecimal`: Integrate with the [`bigdecimal` crate](https://crates.io/crates/bigdecimal). -- `cbor`: Support for [serde_cbor](https://crates.io/crates/serde_cbor). -- `smol_str`: Integrate with the [`smol_str` crate](https://crates.io/crates/smol_str). -- `hashbrown`: Integrate with the [`hashbrown` crate](https://github.com/rust-lang/hashbrown). -- `time`: Integrate with the [`time` crate](https://github.com/time-rs/time). -- `tokio-sync` Integrate with the [`tokio::sync::RwLock`](https://docs.rs/tokio/1.18.1/tokio/sync/struct.RwLock.html) and [`tokio::sync::Mutex`](https://docs.rs/tokio/1.18.1/tokio/sync/struct.Mutex.html). -- `fast_chemail`: Integrate with the [`fast_chemail` crate](https://crates.io/crates/fast_chemail). - -## Apollo Studio - -Apollo Studio is a cloud platform that helps you build, monitor, validate, and secure your organization's data graph. -An existing extension is available for this crate [here](https://github.com/async-graphql/async_graphql_apollo_studio_extension) +> **Note**: Minimum supported Rust version: 1.59.0 or later ## Examples All examples are in the [sub-repository](https://github.com/async-graphql/examples), located in the examples directory. -**Run an example:** - ```shell git submodule update # update the examples repo cd examples && cargo run --bin [name] @@ -104,14 +81,51 @@ cd examples && cargo run --bin [name] ## Integrations -* Poem [async-graphql-poem](https://crates.io/crates/async-graphql-poem) -* Actix-web [async-graphql-actix-web](https://crates.io/crates/async-graphql-actix-web) -* Warp [async-graphql-warp](https://crates.io/crates/async-graphql-warp) -* Tide [async-graphql-tide](https://crates.io/crates/async-graphql-tide) -* Rocket [async-graphql-rocket](https://github.com/async-graphql/async-graphql/tree/master/integrations/rocket) -* Axum [async-graphql-axum](https://github.com/async-graphql/async-graphql/tree/master/integrations/axum) +Integrations are what glue `async-graphql` with your web server, here are provided ones, or you can build your own! -## Who's using Async-graphql in production? +- Poem [async-graphql-poem](https://crates.io/crates/async-graphql-poem) +- Actix-web [async-graphql-actix-web](https://crates.io/crates/async-graphql-actix-web) +- Warp [async-graphql-warp](https://crates.io/crates/async-graphql-warp) +- Tide [async-graphql-tide](https://crates.io/crates/async-graphql-tide) +- Rocket [async-graphql-rocket](https://github.com/async-graphql/async-graphql/tree/master/integrations/rocket) +- Axum [async-graphql-axum](https://github.com/async-graphql/async-graphql/tree/master/integrations/axum) + +## 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](extensions/struct.ApolloTracing.html). | +| **`apollo_persisted_queries`** | Enable the [Apollo persisted queries extension](extensions/apollo_persisted_queries/struct.ApolloPersistedQueries.html). | +| **`log`** | Enable the [logger extension](extensions/struct.Logger.html). | +| **`tracing`** | Enable the [tracing extension](extensions/struct.Tracing.html). | +| **`opentelemetry`** | Enable the [OpenTelemetry extension](extensions/struct.OpenTelemetry.html). | +| **`unblock`** | Support [asynchronous reader for Upload](types/struct.Upload.html) | +| **`bson`** | Integrate with the [`bson` crate](https://crates.io/crates/bson). | +| **`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). | +| **`url`** | Integrate with the [`url` crate](https://crates.io/crates/url). | +| **`uuid`** | Integrate with the [`uuid` crate](https://crates.io/crates/uuid). | +| **`uuid08`** | Integrate with the [`uuid 0.8` crate](https://crates.io/crates/uuid/0.8.2). | +| **`string_number`** | Enable the [StringNumber](types/struct.StringNumber.html). | +| **`dataloader`** | Support [DataLoader](dataloader/struct.DataLoader.html). | +| **`secrecy`** | Integrate with the [`secrecy` crate](https://crates.io/crates/secrecy). | +| **`decimal`** | Integrate with the [`rust_decimal` crate](https://crates.io/crates/rust_decimal). | +| **`bigdecimal`** | Integrate with the [`bigdecimal` crate](https://crates.io/crates/bigdecimal). | +| **`cbor`** | Support for [serde_cbor](https://crates.io/crates/serde_cbor). | +| **`smol_str`** | Integrate with the [`smol_str` crate](https://crates.io/crates/smol_str). | +| **`hashbrown`** | Integrate with the [`hashbrown` crate](https://github.com/rust-lang/hashbrown). | +| **`time`** | Integrate with the [`time` crate](https://github.com/time-rs/time). | +| **`tokio-sync`** | Integrate with the [`tokio::sync::RwLock`](https://docs.rs/tokio/1.18.1/tokio/sync/struct.RwLock.html) and [`tokio::sync::Mutex`](https://docs.rs/tokio/1.18.1/tokio/sync/struct.Mutex.html). | +| **`fast_chemail`** | Integrate with the [`fast_chemail` crate](https://crates.io/crates/fast_chemail). | + +### 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 avaliable. + +## Who's using `async-graphql` in production? - [Vector](https://vector.dev/) - [DiveDB](https://divedb.net) @@ -138,31 +152,24 @@ cd examples && cargo run --bin [name] ## 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) +- [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, +- 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) +- MIT license ([LICENSE-MIT](./LICENSE-MIT) or http://opensource.org/licenses/MIT) at your option. - -## References - -* [GraphQL](https://graphql.org) -* [GraphQL Multipart Request](https://github.com/jaydenseric/graphql-multipart-request-spec) -* [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) - -## Contribute - -Welcome to contribute !