async_graphql/lib.rs
1//! # A GraphQL server library implemented in Rust
2//!
3//! <div align="center">
4//! <!-- CI -->
5//! <img src="https://github.com/async-graphql/async-graphql/workflows/CI/badge.svg" />
6//! <!-- codecov -->
7//! <img src="https://codecov.io/gh/async-graphql/async-graphql/branch/master/graph/badge.svg" />
8//! <!-- Crates version -->
9//! <a href="https://crates.io/crates/async-graphql">
10//! <img src="https://img.shields.io/crates/v/async-graphql.svg?style=flat-square"
11//! alt="Crates.io version" />
12//! </a>
13//! <!-- Downloads -->
14//! <a href="https://crates.io/crates/async-graphql">
15//! <img src="https://img.shields.io/crates/d/async-graphql.svg?style=flat-square"
16//! alt="Download" />
17//! </a>
18//! <!-- docs.rs docs -->
19//! <a href="https://docs.rs/async-graphql">
20//! <img src="https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square"
21//! alt="docs.rs docs" />
22//! </a>
23//! <a href="https://github.com/rust-secure-code/safety-dance/">
24//! <img src="https://img.shields.io/badge/unsafe-forbidden-success.svg?style=flat-square"
25//! alt="Unsafe Rust forbidden" />
26//! </a>
27//! </div>
28//!
29//! ## Documentation
30//!
31//! * [Book](https://async-graphql.github.io/async-graphql/en/index.html)
32//! * [中文文档](https://async-graphql.github.io/async-graphql/zh-CN/index.html)
33//! * [Docs](https://docs.rs/async-graphql)
34//! * [GitHub repository](https://github.com/async-graphql/async-graphql)
35//! * [Cargo package](https://crates.io/crates/async-graphql)
36//! * Minimum supported Rust version: 1.56.1 or later
37//!
38//! ## Features
39//!
40//! * Fully supports async/await
41//! * Type safety
42//! * Rustfmt friendly (Procedural Macro)
43//! * Custom scalars
44//! * Minimal overhead
45//! * Easy integration ([poem](https://crates.io/crates/poem), actix_web, tide,
46//! warp, rocket ...)
47//! * File upload (Multipart request)
48//! * Subscriptions (WebSocket transport)
49//! * Custom extensions
50//! * Apollo Tracing extension
51//! * Limit query complexity/depth
52//! * Error Extensions
53//! * Apollo Federation(v2)
54//! * Batch Queries
55//! * Apollo Persisted Queries
56//!
57//! ## Crate features
58//!
59//! This crate offers the following features, all of which are not activated by
60//! default:
61//!
62//! | feature | enables |
63//! |:-------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
64//! | **`apollo_tracing`** | Enable the [Apollo tracing extension](https://docs.rs/async-graphql/latest/async_graphql/extensions/struct.ApolloTracing.html). |
65//! | **`apollo_persisted_queries`** | Enable the [Apollo persisted queries extension](https://docs.rs/async-graphql/latest/async_graphql/extensions/apollo_persisted_queries/struct.ApolloPersistedQueries.html). |
66//! | **`boxed-trait`** | Enables [`async-trait`](https://crates.io/crates/async-trait) for all traits. |
67//! | **`bson`** | Integrate with the [`bson` crate](https://crates.io/crates/bson). |
68//! | **`bigdecimal`** | Integrate with the [`bigdecimal` crate](https://crates.io/crates/bigdecimal). |
69//! | **`cbor`** | Support for [serde_cbor](https://crates.io/crates/serde_cbor). |
70//! | **`chrono`** | Integrate with the [`chrono` crate](https://crates.io/crates/chrono). |
71//! | **`chrono-tz`** | Integrate with the [`chrono-tz` crate](https://crates.io/crates/chrono-tz). |
72//! | **`dataloader`** | Support [DataLoader](dataloader/struct.DataLoader.html). |
73//! | **`decimal`** | Integrate with the [`rust_decimal` crate](https://crates.io/crates/rust_decimal). |
74//! | **`dynamic-schema`** | Support dynamic schema |
75//! | **`fast_chemail`** | Integrate with the [`fast_chemail` crate](https://crates.io/crates/fast_chemail). |
76//! | **`graphiql`** | Enables the [GraphiQL IDE](https://github.com/graphql/graphiql) integration |
77//! | **`hashbrown`** | Integrate with the [`hashbrown` crate](https://github.com/rust-lang/hashbrown). |
78//! | **`log`** | Enable the [Logger extension](https://docs.rs/async-graphql/latest/async_graphql/extensions/struct.Logger.html). |
79//! | **`opentelemetry`** | Enable the [OpenTelemetry extension](https://docs.rs/async-graphql/latest/async_graphql/extensions/struct.OpenTelemetry.html). |
80//! | **`playground`** | Enables the [GraphQL playground IDE](https://github.com/graphql/graphql-playground) integration |
81//! | **`rawvalue`** | Support raw values from [`serde_json`](https://crates.io/crates/serde_json) |
82//! | **`secrecy`** | Integrate with the [`secrecy` crate](https://crates.io/crates/secrecy). |
83//! | **`smol_str`** | Integrate with the [`smol_str` crate](https://crates.io/crates/smol_str). |
84//! | **`string_number`** | Enable the [StringNumber](types/struct.StringNumber.html). |
85//! | **`time`** | Integrate with the [`time` crate](https://github.com/time-rs/time). |
86//! | **`tracing`** | Enable the [Tracing extension](https://docs.rs/async-graphql/latest/async_graphql/extensions/struct.Tracing.html). |
87//! | **`tempfile`** | Save the uploaded content in the temporary file. |
88//! | **`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). |
89//! | **`unblock`** | Support [Asynchronous reader for Upload](types/struct.Upload.html) |
90//! | **`uuid`** | Integrate with the [`uuid` crate](https://crates.io/crates/uuid). |
91//! | **`url`** | Integrate with the [`url` crate](https://crates.io/crates/url). |
92//!
93//! ## Integrations
94//!
95//! * Poem [async-graphql-poem](https://crates.io/crates/async-graphql-poem)
96//! * Actix-web [async-graphql-actix-web](https://crates.io/crates/async-graphql-actix-web)
97//! * Warp [async-graphql-warp](https://crates.io/crates/async-graphql-warp)
98//! * Tide [async-graphql-tide](https://crates.io/crates/async-graphql-tide)
99//! * Rocket [async-graphql-rocket](https://github.com/async-graphql/async-graphql/tree/master/integrations/rocket)
100//! * Axum [async-graphql-axum](https://github.com/async-graphql/async-graphql/tree/master/integrations/axum)
101//!
102//! ## License
103//!
104//! Licensed under either of
105//!
106//! * Apache License, Version 2.0, (./LICENSE-APACHE or <http://www.apache.org/licenses/LICENSE-2.0>)
107//! * MIT license (./LICENSE-MIT or <http://opensource.org/licenses/MIT>) at
108//! your option.
109//!
110//! ## References
111//!
112//! * [GraphQL](https://graphql.org)
113//! * [GraphQL Multipart Request](https://github.com/jaydenseric/graphql-multipart-request-spec)
114//! * [GraphQL Cursor Connections Specification](https://facebook.github.io/relay/graphql/connections.htm)
115//! * [GraphQL over WebSocket Protocol](https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md)
116//! * [Apollo Tracing](https://github.com/apollographql/apollo-tracing)
117//! * [Apollo Federation](https://www.apollographql.com/docs/apollo-server/federation/introduction)
118//!
119//! ## Examples
120//!
121//! All examples are in the [sub-repository](https://github.com/async-graphql/examples), located in the examples directory.
122//!
123//! **Run an example:**
124//!
125//! ```shell
126//! git submodule update # update the examples repo
127//! cd examples && cargo run --bin [name]
128//! ```
129//!
130//! ## Benchmarks
131//!
132//! Ensure that there is no CPU-heavy process in background!
133//!
134//! ```shell script
135//! cd benchmark
136//! cargo bench
137//! ```
138//!
139//! Now a HTML report is available at `benchmark/target/criterion/report`.
140
141#![deny(clippy::all)]
142// #![deny(clippy::pedantic)]
143#![deny(clippy::inefficient_to_string)]
144#![deny(clippy::match_wildcard_for_single_variants)]
145#![allow(clippy::module_name_repetitions)]
146#![allow(clippy::similar_names)]
147#![allow(clippy::if_not_else)]
148#![allow(clippy::doc_markdown)]
149#![allow(clippy::must_use_candidate)]
150#![allow(clippy::missing_errors_doc)]
151#![allow(clippy::needless_pass_by_value)]
152#![deny(clippy::redundant_closure_for_method_calls)]
153#![allow(clippy::option_if_let_else)]
154#![allow(clippy::match_same_arms)]
155#![allow(clippy::default_trait_access)]
156#![allow(clippy::map_flatten)]
157#![allow(clippy::map_unwrap_or)]
158#![allow(clippy::explicit_iter_loop)]
159#![allow(clippy::too_many_lines)]
160#![allow(clippy::cast_sign_loss)]
161#![allow(clippy::unused_self)]
162#![allow(clippy::cast_lossless)]
163#![allow(clippy::cast_possible_truncation)]
164#![allow(clippy::implicit_hasher)]
165// #![deny(clippy::nursery)]
166#![allow(clippy::use_self)]
167#![allow(clippy::missing_const_for_fn)]
168#![allow(clippy::needless_borrow)]
169#![allow(clippy::future_not_send)]
170#![allow(clippy::redundant_pub_crate)]
171#![allow(clippy::cognitive_complexity)]
172#![allow(clippy::useless_let_if_seq)]
173#![allow(clippy::uninlined_format_args)]
174#![warn(missing_docs)]
175#![allow(clippy::trivially_copy_pass_by_ref)]
176#![allow(clippy::upper_case_acronyms)]
177#![recursion_limit = "256"]
178#![forbid(unsafe_code)]
179#![cfg_attr(docsrs, feature(doc_cfg))]
180
181mod base;
182mod custom_directive;
183mod error;
184mod executor;
185mod guard;
186mod look_ahead;
187mod model;
188mod request;
189mod response;
190mod schema;
191mod subscription;
192mod validation;
193
194pub mod context;
195#[cfg(feature = "dataloader")]
196#[cfg_attr(docsrs, doc(cfg(feature = "dataloader")))]
197pub mod dataloader;
198#[cfg(feature = "dynamic-schema")]
199#[cfg_attr(docsrs, doc(cfg(feature = "dynamic-schema")))]
200pub mod dynamic;
201pub mod extensions;
202pub mod http;
203pub mod resolver_utils;
204pub mod types;
205#[doc(hidden)]
206pub mod validators;
207
208#[doc(hidden)]
209pub mod registry;
210
211pub use async_graphql_parser as parser;
212pub use async_graphql_value::{
213 from_value, to_value, value, ConstValue as Value, DeserializerError, Extensions, Name, Number,
214 SerializerError, Variables,
215};
216#[doc(hidden)]
217pub use async_stream;
218#[doc(hidden)]
219pub use async_trait;
220pub use base::{
221 ComplexObject, Description, InputObjectType, InputType, InterfaceType, ObjectType,
222 OneofObjectType, OutputType, TypeName, UnionType,
223};
224#[doc(hidden)]
225pub use context::ContextSelectionSet;
226pub use context::*;
227pub use custom_directive::{CustomDirective, CustomDirectiveFactory, TypeDirective};
228pub use error::{
229 Error, ErrorExtensionValues, ErrorExtensions, InputValueError, InputValueResult,
230 ParseRequestError, PathSegment, Result, ResultExt, ServerError, ServerResult,
231};
232pub use executor::Executor;
233pub use extensions::ResolveFut;
234#[doc(hidden)]
235pub use futures_util;
236pub use guard::{Guard, GuardExt};
237#[doc(hidden)]
238pub use indexmap;
239pub use look_ahead::Lookahead;
240#[doc(no_inline)]
241pub use parser::{Pos, Positioned};
242pub use registry::{CacheControl, SDLExportOptions};
243pub use request::{BatchRequest, Request};
244#[doc(no_inline)]
245pub use resolver_utils::{ContainerType, EnumType, ScalarType};
246pub use response::{BatchResponse, Response};
247pub use schema::{IntrospectionMode, Schema, SchemaBuilder, SchemaEnv};
248#[doc(hidden)]
249pub use static_assertions_next;
250pub use subscription::SubscriptionType;
251pub use types::*;
252pub use validation::{ValidationMode, ValidationResult, VisitorContext};
253pub use validators::CustomValidator;
254
255/// An alias of [async_graphql::Error](struct.Error.html). Present for backward
256/// compatibility reasons.
257pub type FieldError = Error;
258
259/// An alias of [async_graphql::Result](type.Result.html). Present for backward
260/// compatibility reasons.
261pub type FieldResult<T> = Result<T>;
262
263#[doc = include_str!("docs/complex_object.md")]
264pub use async_graphql_derive::ComplexObject;
265#[doc = include_str!("docs/description.md")]
266pub use async_graphql_derive::Description;
267#[doc = include_str!("docs/directive.md")]
268pub use async_graphql_derive::Directive;
269#[doc = include_str!("docs/enum.md")]
270pub use async_graphql_derive::Enum;
271#[doc = include_str!("docs/input_object.md")]
272pub use async_graphql_derive::InputObject;
273#[doc = include_str!("docs/interface.md")]
274pub use async_graphql_derive::Interface;
275#[doc = include_str!("docs/merged_object.md")]
276pub use async_graphql_derive::MergedObject;
277#[doc = include_str!("docs/merged_subscription.md")]
278pub use async_graphql_derive::MergedSubscription;
279#[doc = include_str!("docs/newtype.md")]
280pub use async_graphql_derive::NewType;
281#[doc = include_str!("docs/object.md")]
282pub use async_graphql_derive::Object;
283#[doc = include_str!("docs/oneof_object.md")]
284pub use async_graphql_derive::OneofObject;
285#[doc = include_str!("docs/scalar.md")]
286pub use async_graphql_derive::Scalar;
287#[doc = include_str!("docs/simple_object.md")]
288pub use async_graphql_derive::SimpleObject;
289#[doc = include_str!("docs/subscription.md")]
290pub use async_graphql_derive::Subscription;
291pub use async_graphql_derive::TypeDirective;
292#[doc = include_str!("docs/union.md")]
293pub use async_graphql_derive::Union;