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, warp,
46//! 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//! | **`chrono`** | Integrate with the [`chrono` crate](https://crates.io/crates/chrono). |
68//! | **`chrono-tz`** | Integrate with the [`chrono-tz` crate](https://crates.io/crates/chrono-tz). |
69//! | **`dataloader`** | Support [DataLoader](dataloader/struct.DataLoader.html). |
70//! | **`decimal`** | Integrate with the [`rust_decimal` crate](https://crates.io/crates/rust_decimal). |
71//! | **`dynamic-schema`** | Support dynamic schema |
72//! | **`fast_chemail`** | Integrate with the [`fast_chemail` crate](https://crates.io/crates/fast_chemail). |
73//! | **`graphiql`** | Enables the [GraphiQL IDE](https://github.com/graphql/graphiql) integration |
74//! | **`jiff`** | Integrate with the [`jiff` crate](https://crates.io/crates/jiff). |
75//! | **`log`** | Enable the [Logger extension](https://docs.rs/async-graphql/latest/async_graphql/extensions/struct.Logger.html). |
76//! | **`opentelemetry`** | Enable the [OpenTelemetry extension](https://docs.rs/async-graphql/latest/async_graphql/extensions/struct.OpenTelemetry.html). |
77//! | **`rawvalue`** | Support raw values from [`serde_json`](https://crates.io/crates/serde_json) |
78//! | **`secrecy`** | Integrate with the [`secrecy` crate](https://crates.io/crates/secrecy). |
79//! | **`string_number`** | Enable the [StringNumber](types/struct.StringNumber.html). |
80//! | **`time`** | Integrate with the [`time` crate](https://github.com/time-rs/time). |
81//! | **`tracing`** | Enable the [Tracing extension](https://docs.rs/async-graphql/latest/async_graphql/extensions/struct.Tracing.html). |
82//! | **`tempfile`** | Save the uploaded content in the temporary file. |
83//! | **`unblock`** | Support [Asynchronous reader for Upload](types/struct.Upload.html) |
84//! | **`uuid`** | Integrate with the [`uuid` crate](https://crates.io/crates/uuid). |
85//! | **`url`** | Integrate with the [`url` crate](https://crates.io/crates/url). |
86//!
87//! ## Integrations
88//!
89//! * Poem [async-graphql-poem](https://crates.io/crates/async-graphql-poem)
90//! * Actix-web [async-graphql-actix-web](https://crates.io/crates/async-graphql-actix-web)
91//! * Warp [async-graphql-warp](https://crates.io/crates/async-graphql-warp)
92//! * Rocket [async-graphql-rocket](https://github.com/async-graphql/async-graphql/tree/master/integrations/rocket)
93//! * Axum [async-graphql-axum](https://github.com/async-graphql/async-graphql/tree/master/integrations/axum)
94//!
95//! ## License
96//!
97//! Licensed under either of
98//!
99//! * Apache License, Version 2.0, (./LICENSE-APACHE or <http://www.apache.org/licenses/LICENSE-2.0>)
100//! * MIT license (./LICENSE-MIT or <http://opensource.org/licenses/MIT>) at
101//! your option.
102//!
103//! ## References
104//!
105//! * [GraphQL](https://graphql.org)
106//! * [GraphQL Multipart Request](https://github.com/jaydenseric/graphql-multipart-request-spec)
107//! * [GraphQL Cursor Connections Specification](https://facebook.github.io/relay/graphql/connections.htm)
108//! * [GraphQL over WebSocket Protocol](https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md)
109//! * [Apollo Tracing](https://github.com/apollographql/apollo-tracing)
110//! * [Apollo Federation](https://www.apollographql.com/docs/apollo-server/federation/introduction)
111//!
112//! ## Examples
113//!
114//! All examples are in the [sub-repository](https://github.com/async-graphql/examples), located in the examples directory.
115//!
116//! **Run an example:**
117//!
118//! ```shell
119//! git submodule update # update the examples repo
120//! cd examples && cargo run --bin [name]
121//! ```
122//!
123//! ## Benchmarks
124//!
125//! Ensure that there is no CPU-heavy process in background!
126//!
127//! ```shell script
128//! cd benchmark
129//! cargo bench
130//! ```
131//!
132//! Now a HTML report is available at `benchmark/target/criterion/report`.
133
134#![deny(clippy::all)]
135// #![deny(clippy::pedantic)]
136#![deny(clippy::inefficient_to_string)]
137#![deny(clippy::match_wildcard_for_single_variants)]
138#![allow(clippy::module_name_repetitions)]
139#![allow(clippy::similar_names)]
140#![allow(clippy::if_not_else)]
141#![allow(clippy::doc_markdown)]
142#![allow(clippy::must_use_candidate)]
143#![allow(clippy::missing_errors_doc)]
144#![allow(clippy::needless_pass_by_value)]
145#![deny(clippy::redundant_closure_for_method_calls)]
146#![allow(clippy::option_if_let_else)]
147#![allow(clippy::match_same_arms)]
148#![allow(clippy::default_trait_access)]
149#![allow(clippy::map_flatten)]
150#![allow(clippy::map_unwrap_or)]
151#![allow(clippy::explicit_iter_loop)]
152#![allow(clippy::too_many_lines)]
153#![allow(clippy::cast_sign_loss)]
154#![allow(clippy::unused_self)]
155#![allow(clippy::cast_lossless)]
156#![allow(clippy::cast_possible_truncation)]
157#![allow(clippy::implicit_hasher)]
158// #![deny(clippy::nursery)]
159#![allow(clippy::use_self)]
160#![allow(clippy::missing_const_for_fn)]
161#![allow(clippy::needless_borrow)]
162#![allow(clippy::future_not_send)]
163#![allow(clippy::redundant_pub_crate)]
164#![allow(clippy::cognitive_complexity)]
165#![allow(clippy::useless_let_if_seq)]
166#![allow(clippy::uninlined_format_args)]
167#![warn(missing_docs)]
168#![allow(clippy::trivially_copy_pass_by_ref)]
169#![allow(clippy::upper_case_acronyms)]
170#![recursion_limit = "256"]
171#![forbid(unsafe_code)]
172#![cfg_attr(docsrs, feature(doc_cfg))]
173
174mod base;
175mod custom_directive;
176mod error;
177mod executor;
178mod guard;
179mod look_ahead;
180mod model;
181mod request;
182mod response;
183mod schema;
184mod subscription;
185mod validation;
186
187pub mod context;
188#[cfg(feature = "dataloader")]
189#[cfg_attr(docsrs, doc(cfg(feature = "dataloader")))]
190pub mod dataloader;
191#[cfg(feature = "dynamic-schema")]
192#[cfg_attr(docsrs, doc(cfg(feature = "dynamic-schema")))]
193pub mod dynamic;
194pub mod extensions;
195pub mod http;
196pub mod resolver_utils;
197pub mod runtime;
198pub mod types;
199#[doc(hidden)]
200pub mod validators;
201
202#[doc(hidden)]
203pub mod registry;
204
205pub use async_graphql_parser as parser;
206pub use async_graphql_value::{
207 ConstValue as Value, DeserializerError, Extensions, Name, Number, SerializerError, Variables,
208 from_value, to_value, value,
209};
210#[doc(hidden)]
211pub use async_trait;
212pub use base::{
213 ComplexObject, Description, InputObjectType, InputType, InterfaceType, ObjectType,
214 OneofObjectType, OutputType, TypeName, UnionType,
215};
216#[doc(hidden)]
217pub use context::ContextSelectionSet;
218pub use context::*;
219pub use custom_directive::{CustomDirective, CustomDirectiveFactory, TypeDirective};
220pub use error::{
221 Error, ErrorExtensionValues, ErrorExtensions, InputValueError, InputValueResult,
222 ParseRequestError, PathSegment, Result, ResultExt, ServerError, ServerResult,
223};
224pub use executor::Executor;
225pub use extensions::ResolveFut;
226#[doc(hidden)]
227pub use futures_util;
228pub use guard::{Guard, GuardExt};
229#[doc(hidden)]
230pub use indexmap;
231pub use look_ahead::Lookahead;
232#[doc(no_inline)]
233pub use parser::{Pos, Positioned};
234pub use registry::{CacheControl, SDLExportOptions};
235pub use request::{BatchRequest, Request};
236#[doc(no_inline)]
237pub use resolver_utils::{ContainerType, EnumType, ScalarType};
238pub use response::{BatchResponse, Response};
239pub use schema::{IntrospectionMode, Schema, SchemaBuilder, SchemaEnv};
240#[doc(hidden)]
241pub use static_assertions_next;
242pub use subscription::SubscriptionType;
243pub use types::*;
244pub use validation::{ValidationMode, ValidationResult, VisitorContext};
245pub use validators::CustomValidator;
246
247/// An alias of [async_graphql::Error](struct.Error.html). Present for backward
248/// compatibility reasons.
249pub type FieldError = Error;
250
251/// An alias of [async_graphql::Result](type.Result.html). Present for backward
252/// compatibility reasons.
253pub type FieldResult<T> = Result<T>;
254
255#[doc = include_str!("docs/complex_object.md")]
256pub use async_graphql_derive::ComplexObject;
257#[doc = include_str!("docs/description.md")]
258pub use async_graphql_derive::Description;
259#[doc = include_str!("docs/directive.md")]
260pub use async_graphql_derive::Directive;
261#[doc = include_str!("docs/enum.md")]
262pub use async_graphql_derive::Enum;
263#[doc = include_str!("docs/input_object.md")]
264pub use async_graphql_derive::InputObject;
265#[doc = include_str!("docs/interface.md")]
266pub use async_graphql_derive::Interface;
267#[doc = include_str!("docs/merged_object.md")]
268pub use async_graphql_derive::MergedObject;
269#[doc = include_str!("docs/merged_subscription.md")]
270pub use async_graphql_derive::MergedSubscription;
271#[doc = include_str!("docs/newtype.md")]
272pub use async_graphql_derive::NewType;
273#[doc = include_str!("docs/object.md")]
274pub use async_graphql_derive::Object;
275#[doc = include_str!("docs/oneof_object.md")]
276pub use async_graphql_derive::OneofObject;
277#[doc = include_str!("docs/scalar.md")]
278pub use async_graphql_derive::Scalar;
279#[doc = include_str!("docs/simple_object.md")]
280pub use async_graphql_derive::SimpleObject;
281#[doc = include_str!("docs/subscription.md")]
282pub use async_graphql_derive::Subscription;
283pub use async_graphql_derive::TypeDirective;
284#[doc = include_str!("docs/union.md")]
285pub use async_graphql_derive::Union;