Document not found (404)
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +A common issue with graphql servers is how the resolvers query their datasource. -This issue results in a large number of unneccessary database queries or http requests. -Say you were wanting to list a bunch of cults people were in
-query {
- persons {
- id
- name
- cult {
- id
- name
- }
- }
-}
-What would be executed by a SQL database would be:
-SELECT id, name, cult_id FROM persons;
-SELECT id, name FROM cults WHERE id = 1;
-SELECT id, name FROM cults WHERE id = 1;
-SELECT id, name FROM cults WHERE id = 1;
-SELECT id, name FROM cults WHERE id = 1;
-SELECT id, name FROM cults WHERE id = 2;
-SELECT id, name FROM cults WHERE id = 2;
-SELECT id, name FROM cults WHERE id = 2;
-# ...
-Once the list of users has been returned, a separate query is run to find the cult of each user. -You can see how this could quickly become a problem.
-A common solution to this is to introduce a dataloader. -This can be done with Juniper using the crate cksac/dataloader-rs, which has two types of dataloaders; cached and non-cached.
-DataLoader provides a memoization cache, after .load() is called once with a given key, the resulting value is cached to eliminate redundant loads.
-DataLoader caching does not replace Redis, Memcache, or any other shared application-level cache. DataLoader is first and foremost a data loading mechanism, and its cache only serves the purpose of not repeatedly loading the same data in the context of a single request to your Application. (read more)
-!FILENAME Cargo.toml
-[dependencies]
-actix-identity = "0.4.0-beta.4"
-actix-rt = "1.0"
-actix-web = {version = "2.0", features = []}
-juniper = { git = "https://github.com/graphql-rust/juniper" }
-futures = "0.3"
-postgres = "0.15.2"
-dataloader = "0.12.0"
-async-trait = "0.1.30"
-// use dataloader::cached::Loader;
-use dataloader::non_cached::Loader;
-use dataloader::BatchFn;
-use std::collections::HashMap;
-use postgres::{Connection, TlsMode};
-use std::env;
-
-pub fn get_db_conn() -> Connection {
- let pg_connection_string = env::var("DATABASE_URI").expect("need a db uri");
- println!("Connecting to {}", pg_connection_string);
- let conn = Connection::connect(&pg_connection_string[..], TlsMode::None).unwrap();
- println!("Connection is fine");
- conn
-}
-
-#[derive(Debug, Clone)]
-pub struct Cult {
- pub id: i32,
- pub name: String,
-}
-
-pub fn get_cult_by_ids(hashmap: &mut HashMap<i32, Cult>, ids: Vec<i32>) {
- let conn = get_db_conn();
- for row in &conn
- .query("SELECT id, name FROM cults WHERE id = ANY($1)", &[&ids])
- .unwrap()
- {
- let cult = Cult {
- id: row.get(0),
- name: row.get(1),
- };
- hashmap.insert(cult.id, cult);
- }
-}
-
-pub struct CultBatcher;
-
-#[async_trait]
-impl BatchFn<i32, Cult> for CultBatcher {
-
- // A hashmap is used, as we need to return an array which maps each original key to a Cult.
- async fn load(&self, keys: &[i32]) -> HashMap<i32, Cult> {
- println!("load cult batch {:?}", keys);
- let mut cult_hashmap = HashMap::new();
- get_cult_by_ids(&mut cult_hashmap, keys.to_vec());
- cult_hashmap
- }
-}
-
-pub type CultLoader = Loader<i32, Cult, CultBatcher>;
-
-// To create a new loader
-pub fn get_loader() -> CultLoader {
- Loader::new(CultBatcher)
- // Usually a DataLoader will coalesce all individual loads which occur
- // within a single frame of execution before calling your batch function with all requested keys.
- // However sometimes this behavior is not desirable or optimal.
- // Perhaps you expect requests to be spread out over a few subsequent ticks
- // See: https://github.com/cksac/dataloader-rs/issues/12
- // More info: https://github.com/graphql/dataloader#batch-scheduling
- // A larger yield count will allow more requests to append to batch but will wait longer before actual load.
- .with_yield_count(100)
-}
-
-#[juniper::graphql_object(Context = Context)]
-impl Cult {
- // your resolvers
-
- // To call the dataloader
- pub async fn cult_by_id(ctx: &Context, id: i32) -> Cult {
- ctx.cult_loader.load(id).await
- }
-}
-
-Once created, a dataloader has the async functions .load() and .load_many().
-In the above example cult_loader.load(id: i32).await returns Cult. If we had used cult_loader.load_many(Vec<i32>).await it would have returned Vec<Cult>.
Dataloaders should be created per-request to avoid risk of bugs where one user is able to load cached/batched data from another user/ outside of its authenticated scope. -Creating dataloaders within individual resolvers will prevent batching from occurring and will nullify the benefits of the dataloader.
-For example:
-When you declare your context
-use juniper;
-
-#[derive(Clone)]
-pub struct Context {
- pub cult_loader: CultLoader,
-}
-
-impl juniper::Context for Context {}
-
-impl Context {
- pub fn new(cult_loader: CultLoader) -> Self {
- Self {
- cult_loader
- }
- }
-}
-Your handler for GraphQL (Note: instantiating context here keeps it per-request)
-pub async fn graphql(
- st: web::Data<Arc<Schema>>,
- data: web::Json<GraphQLRequest>,
-) -> Result<HttpResponse, Error> {
-
- // Context setup
- let cult_loader = get_loader();
- let ctx = Context::new(cult_loader);
-
- // Execute
- let res = data.execute(&st, &ctx).await;
- let json = serde_json::to_string(&res).map_err(error::ErrorInternalServerError)?;
-
- Ok(HttpResponse::Ok()
- .content_type("application/json")
- .body(json))
-}
-For a full example using Dataloaders and Context check out jayy-lmao/rust-graphql-docker.
- -There are two ways that a client can submit a null argument or field in a query.
-They can use a null literal:
-{
- field(arg: null)
-}
-Or they can simply omit the argument:
-{
- field
-}
-The former is an explicit null and the latter is an implicit null.
-There are some situations where it's useful to know which one the user provided.
-For example, let's say your business logic has a function that allows users to -perform a "patch" operation on themselves. Let's say your users can optionally -have favorite and least favorite numbers, and the input for that might look -like this:
--/// Updates user attributes. Fields that are `None` are left as-is. -pub struct UserPatch { - /// If `Some`, updates the user's favorite number. - pub favorite_number: Option<Option<i32>>, - - /// If `Some`, updates the user's least favorite number. - pub least_favorite_number: Option<Option<i32>>, -} - -# fn main() {} -
To set a user's favorite number to 7, you would set favorite_number to
-Some(Some(7)). In GraphQL, that might look like this:
mutation { patchUser(patch: { favoriteNumber: 7 }) }
-To unset the user's favorite number, you would set favorite_number to
-Some(None). In GraphQL, that might look like this:
mutation { patchUser(patch: { favoriteNumber: null }) }
-If you want to leave the user's favorite number alone, you would set it to
-None. In GraphQL, that might look like this:
mutation { patchUser(patch: {}) }
-The last two cases rely on being able to distinguish between explicit and implicit null.
-In Juniper, this can be done using the Nullable type:
-# extern crate juniper; -use juniper::{FieldResult, Nullable}; - -#[derive(juniper::GraphQLInputObject)] -struct UserPatchInput { - pub favorite_number: Nullable<i32>, - pub least_favorite_number: Nullable<i32>, -} - -impl Into<UserPatch> for UserPatchInput { - fn into(self) -> UserPatch { - UserPatch { - // The `explicit` function transforms the `Nullable` into an - // `Option<Option<T>>` as expected by the business logic layer. - favorite_number: self.favorite_number.explicit(), - least_favorite_number: self.least_favorite_number.explicit(), - } - } -} - -# pub struct UserPatch { -# pub favorite_number: Option<Option<i32>>, -# pub least_favorite_number: Option<Option<i32>>, -# } - -# struct Session; -# impl Session { -# fn patch_user(&self, _patch: UserPatch) -> FieldResult<()> { Ok(()) } -# } - -struct Context { - session: Session, -} -impl juniper::Context for Context {} - -struct Mutation; - -#[juniper::graphql_object(context = Context)] -impl Mutation { - fn patch_user(ctx: &Context, patch: UserPatchInput) -> FieldResult<bool> { - ctx.session.patch_user(patch.into())?; - Ok(true) - } -} -# fn main() {} -
This type functions much like Option, but has two empty variants so you can
-distinguish between implicit and explicit null.
The chapters below cover some more advanced scenarios.
- - -GraphQL defines a special built-in top-level field called __schema. Querying
-for this field allows one to introspect the schema
-at runtime to see what queries and mutations the GraphQL server supports.
Because introspection queries are just regular GraphQL queries, Juniper supports -them natively. For example, to get all the names of the types supported one -could execute the following query against Juniper:
-{
- __schema {
- types {
- name
- }
- }
-}
-Many client libraries and tools in the GraphQL ecosystem require a complete
-representation of the server schema. Often this representation is in JSON and
-referred to as schema.json. A complete representation of the schema can be
-produced by issuing a specially crafted introspection query.
Juniper provides a convenience function to introspect the entire schema. The -result can then be converted to JSON for use with tools and libraries such as -graphql-client:
-- -# #![allow(unused_variables)] -# extern crate juniper; -# extern crate serde_json; -use juniper::{ - graphql_object, EmptyMutation, EmptySubscription, FieldResult, - GraphQLObject, IntrospectionFormat, -}; - -// Define our schema. - -#[derive(GraphQLObject)] -struct Example { - id: String, -} - -struct Context; -impl juniper::Context for Context {} - -struct Query; - -#[graphql_object(context = Context)] -impl Query { - fn example(id: String) -> FieldResult<Example> { - unimplemented!() - } -} - -type Schema = juniper::RootNode< - 'static, - Query, - EmptyMutation<Context>, - EmptySubscription<Context> ->; - -fn main() { - // Create a context object. - let ctx = Context{}; - - // Run the built-in introspection query. - let (res, _errors) = juniper::introspect( - &Schema::new(Query, EmptyMutation::new(), EmptySubscription::new()), - &ctx, - IntrospectionFormat::default(), - ).unwrap(); - - // Convert introspection result to json. - let json_result = serde_json::to_string_pretty(&res); - assert!(json_result.is_ok()); -} -
The GraphQL standard generally assumes there will be one server request for each client operation you want to perform (such as a query or mutation). This is conceptually simple but has the potential to be inefficent.
-Some client libraries such as apollo-link-batch-http have added the ability to batch operations in a single HTTP request to save network round-trips and potentially increase performance. There are some tradeoffs that should be considered before batching requests.
-Juniper's server integration crates support multiple operations in a single HTTP request using JSON arrays. This makes them compatible with client libraries that support batch operations without any special configuration.
-Server integration crates maintained by others are not required to support batch requests. Batch requests aren't part of the official GraphQL specification.
-Assuming an integration supports batch requests, for the following GraphQL query:
-{
- hero {
- name
- }
-}
-The json data to POST to the server for an individual request would be:
-{
- "query": "{hero{name}}"
-}
-And the response would be of the form:
-{
- "data": {
- "hero": {
- "name": "R2-D2"
- }
- }
-}
-If you wanted to run the same query twice in a single HTTP request, the batched json data to POST to the server would be:
-[
- {
- "query": "{hero{name}}"
- },
- {
- "query": "{hero{name}}"
- }
-]
-And the response would be of the form:
-[
- {
- "data": {
- "hero": {
- "name": "R2-D2"
- }
- }
- },
- {
- "data": {
- "hero": {
- "name": "R2-D2"
- }
- }
- }
-]
-Up until now, we've only looked at mapping structs to GraphQL objects. However, -any Rust type can be mapped into a GraphQL object. In this chapter, we'll look -at enums, but traits will work too - they don't have to be mapped into GraphQL -interfaces.
-Using Result-like enums can be a useful way of reporting e.g. validation
-errors from a mutation:
-# extern crate juniper; -# use juniper::{graphql_object, GraphQLObject}; -# #[derive(juniper::GraphQLObject)] struct User { name: String } -# -#[derive(GraphQLObject)] -struct ValidationError { - field: String, - message: String, -} - -# #[allow(dead_code)] -enum SignUpResult { - Ok(User), - Error(Vec<ValidationError>), -} - -#[graphql_object] -impl SignUpResult { - fn user(&self) -> Option<&User> { - match *self { - SignUpResult::Ok(ref user) => Some(user), - SignUpResult::Error(_) => None, - } - } - - fn error(&self) -> Option<&Vec<ValidationError>> { - match *self { - SignUpResult::Ok(_) => None, - SignUpResult::Error(ref errors) => Some(errors) - } - } -} -# -# fn main() {} -
Here, we use an enum to decide whether a user's input data was valid or not, and -it could be used as the result of e.g. a sign up mutation.
-While this is an example of how you could use something other than a struct to -represent a GraphQL object, it's also an example on how you could implement -error handling for "expected" errors - errors like validation errors. There are -no hard rules on how to represent errors in GraphQL, but there are -some -comments -from one of the authors of GraphQL on how they intended "hard" field errors to -be used, and how to model expected errors.
- -Yet another point where GraphQL and Rust differs is in how generics work. In -Rust, almost any type could be generic - that is, take type parameters. In -GraphQL, there are only two generic types: lists and non-nullables.
-This poses a restriction on what you can expose in GraphQL from Rust: no generic
-structs can be exposed - all type parameters must be bound. For example, you can
-not make e.g. Result<T, E> into a GraphQL type, but you can make e.g.
-Result<User, String> into a GraphQL type.
Let's make a slightly more compact but generic implementation of the last -chapter:
--# extern crate juniper; -# #[derive(juniper::GraphQLObject)] struct User { name: String } -# #[derive(juniper::GraphQLObject)] struct ForumPost { title: String } - -#[derive(juniper::GraphQLObject)] -struct ValidationError { - field: String, - message: String, -} - -# #[allow(dead_code)] -struct MutationResult<T>(Result<T, Vec<ValidationError>>); - -#[juniper::graphql_object( - name = "UserResult", -)] -impl MutationResult<User> { - fn user(&self) -> Option<&User> { - self.0.as_ref().ok() - } - - fn error(&self) -> Option<&Vec<ValidationError>> { - self.0.as_ref().err() - } -} - -#[juniper::graphql_object( - name = "ForumPostResult", -)] -impl MutationResult<ForumPost> { - fn forum_post(&self) -> Option<&ForumPost> { - self.0.as_ref().ok() - } - - fn error(&self) -> Option<&Vec<ValidationError>> { - self.0.as_ref().err() - } -} - -# fn main() {} -
Here, we've made a wrapper around Result and exposed some concrete
-instantiations of Result<T, E> as distinct GraphQL objects. The reason we
-needed the wrapper is of Rust's rules for when you can derive a trait - in this
-case, both Result and Juniper's internal GraphQL trait are from third-party
-sources.
Because we're using generics, we also need to specify a name for our
-instantiated types. Even if Juniper could figure out the name,
-MutationResult<User> wouldn't be a valid GraphQL type name.
GraphQL subscriptions are a way to push data from the server to clients requesting real-time messages -from the server. Subscriptions are similar to queries in that they specify a set of fields to be delivered to the client, -but instead of immediately returning a single answer a result is sent every time a particular event happens on the -server.
-In order to execute subscriptions you need a coordinator (that spawns connections)
-and a GraphQL object that can be resolved into a stream--elements of which will then
-be returned to the end user. The juniper_subscriptions crate
-provides a default connection implementation. Currently subscriptions are only supported on the master branch. Add the following to your Cargo.toml:
[dependencies]
-juniper = { git = "https://github.com/graphql-rust/juniper", branch = "master" }
-juniper_subscriptions = { git = "https://github.com/graphql-rust/juniper", branch = "master" }
-The Subscription is just a GraphQL object, similar to the query root and mutations object that you defined for the
-operations in your [Schema][Schema]. For subscriptions all fields/operations should be async and should return a Stream.
This example shows a subscription operation that returns two events, the strings Hello and World!
-sequentially:
-# use juniper::{graphql_object, graphql_subscription, FieldError}; -# use futures::Stream; -# use std::pin::Pin; -# -# #[derive(Clone)] -# pub struct Database; -# impl juniper::Context for Database {} - -# pub struct Query; -# #[graphql_object(context = Database)] -# impl Query { -# fn hello_world() -> &'static str { -# "Hello World!" -# } -# } -pub struct Subscription; - -type StringStream = Pin<Box<dyn Stream<Item = Result<String, FieldError>> + Send>>; - -#[graphql_subscription(context = Database)] -impl Subscription { - async fn hello_world() -> StringStream { - let stream = futures::stream::iter(vec![ - Ok(String::from("Hello")), - Ok(String::from("World!")) - ]); - Box::pin(stream) - } -} -# -# fn main () {} -
Subscriptions require a bit more resources than regular queries and provide a great vector for DOS attacks. This can can bring down a server easily if not handled correctly. The [SubscriptionCoordinator][SubscriptionCoordinator] trait provides coordination logic to enable functionality like DOS attack mitigation and resource limits.
The [SubscriptionCoordinator][SubscriptionCoordinator] contains the schema and can keep track of opened connections, handle subscription
-start and end, and maintain a global subscription id for each subscription. Each time a connection is established,
-the [SubscriptionCoordinator][SubscriptionCoordinator] spawns a [SubscriptionConnection][SubscriptionConnection]. The [SubscriptionConnection][SubscriptionConnection] handles a single connection, providing resolver logic for a client stream as well as reconnection
-and shutdown logic.
While you can implement [SubscriptionCoordinator][SubscriptionCoordinator] yourself, Juniper contains a simple and generic implementation called [Coordinator][Coordinator]. The subscribe
-operation returns a [Future][Future] with an Item value of a Result<Connection, GraphQLError>,
-where [Connection][Connection] is a Stream of values returned by the operation and [GraphQLError][GraphQLError] is the error when the subscription fails.
-# #![allow(dead_code)] -# extern crate futures; -# extern crate juniper; -# extern crate juniper_subscriptions; -# extern crate serde_json; -# extern crate tokio; -# use juniper::{ -# http::GraphQLRequest, -# graphql_object, graphql_subscription, -# DefaultScalarValue, EmptyMutation, FieldError, -# RootNode, SubscriptionCoordinator, -# }; -# use juniper_subscriptions::Coordinator; -# use futures::{Stream, StreamExt}; -# use std::pin::Pin; -# -# #[derive(Clone)] -# pub struct Database; -# -# impl juniper::Context for Database {} -# -# impl Database { -# fn new() -> Self { -# Self {} -# } -# } -# -# pub struct Query; -# -# #[graphql_object(context = Database)] -# impl Query { -# fn hello_world() -> &'static str { -# "Hello World!" -# } -# } -# -# pub struct Subscription; -# -# type StringStream = Pin<Box<dyn Stream<Item = Result<String, FieldError>> + Send>>; -# -# #[graphql_subscription(context = Database)] -# impl Subscription { -# async fn hello_world() -> StringStream { -# let stream = -# futures::stream::iter(vec![Ok(String::from("Hello")), Ok(String::from("World!"))]); -# Box::pin(stream) -# } -# } -type Schema = RootNode<'static, Query, EmptyMutation<Database>, Subscription>; - -fn schema() -> Schema { - Schema::new(Query {}, EmptyMutation::new(), Subscription {}) -} - -async fn run_subscription() { - let schema = schema(); - let coordinator = Coordinator::new(schema); - let req: GraphQLRequest<DefaultScalarValue> = serde_json::from_str( - r#"{ - "query": "subscription { helloWorld }" - }"#, - ) - .unwrap(); - let ctx = Database::new(); - let mut conn = coordinator.subscribe(&req, &ctx).await.unwrap(); - while let Some(result) = conn.next().await { - println!("{}", serde_json::to_string(&result).unwrap()); - } -} -# -# fn main() { } -
Currently there is an example of subscriptions with [warp][warp], but it still in an alpha state. -GraphQL over [WS][WS] is not fully supported yet and is non-standard.
- - -[Coordinator]: https://docs.rs/juniper_subscriptions/0.15.0/struct.Coordinator.html -[SubscriptionCoordinator]: https://docs.rs/juniper_subscriptions/0.15.0/trait.SubscriptionCoordinator.html -[Connection]: https://docs.rs/juniper_subscriptions/0.15.0/struct.Connection.html -[SubscriptionConnection]: https://docs.rs/juniper_subscriptions/0.15.0/trait.SubscriptionConnection.html - -[Future]: https://docs.rs/futures/0.3.4/futures/future/trait.Future.html -[warp]: https://github.com/graphql-rust/juniper/tree/master/juniper_warp -[WS]: https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md -[GraphQLError]: https://docs.rs/juniper/0.14.2/juniper/enum.GraphQLError.html -[Schema]: ../schema/schemas_and_mutations.md - -