Expand description
Diana is an out-of-the-box fully-fledged GraphQL system with inbuilt support for commonly-used features like subscriptions and authentication. It was built to allow a simple but fully-featured GraphQL system to be very quickly created for systems that have complex data structures and no time for boilerplate.
Diana builds on the fantastic work of async_graphql to provide an architecture that allows you
to run queries and mutations serverlessly, with subscriptions running on serverful infrastructure. To achieve this, Diana uses an
integrations system, whereby the core DianaHandler
logic is used to create high-level wrappers for common deployment systems like
Actix Web and AWS Lambda (including its derivatives, like Netlify). The communication between the serverless and serverful systems is done
for you, exposing a simple, automatically authenticated publishing API.
In development, Diana supports setting up one server for queries/mutations and another for subscriptions. When it comes time to go serverless, you just change one file!
This documentation does not contain examples, which can be found in the GitHub repository. More detailed explanations and tutorials can be found in the book.
Re-exports§
pub use crate::diana_handler::SysSchema;
pub use async_graphql;
pub use async_stream::stream;
pub use tokio_stream::Stream;
pub use tokio_stream::StreamExt;
Modules§
- The module for errors and results. This uses error_chain behind the scenes. You’ll also find
GQLResult
andGQLError
in here, which may be useful in working with your own resolvers. - The module for utility functions for schema development.
Macros§
- if_
authed Deprecated Checks to see if the given authentication state matches the series of given claims. This must be provided with the authentication state, a series of claims to check against, and code to execute if the user is authenticated. This will callbail!
with anErrorKind::Unauthorised
error if the user is unauthenticated, so that must be handled in your function’s return type! - Checks to see if the given authentication state matches the series of given claims. This must be provided with the authentication state, a series of claims to check against. It will then return a boolean as to whether or not the user is authorized. This should be used instead of
if_authed!
.
Structs§
- An authentication token with claims.
- The claims made by a JWT, including metadata.
- The core logic primitive that underlies Diana’s systems. You should only use this if you need to support a platform other than the ones Diana has pre-built systems for (see the book). This is a struct so as to allow the caching of data that stay the same across requests, like the parsed and built schemas.
- A parsed JWT secret. This should be created once with
get_jwt_secret
and then reused as much as possible. You may want to place it in your context underOptions
. - The options for creating the normal server, subscriptions server, and serverless function. You should define your options in one file and then import them everywhere you need them. You should use
::builder()
to construct this. - A builder-style struct to create an instance of
Options
idiomatically.
Enums§
- An enum for the level of blocking imposed on a particular endpoint. Your choice on this should be carefully evaluated based on your threat model. Please choose wisely!
- The three states authentication can be in at the token level.
- This represents the decision as to whether or not a use is allowed through to an endpoint. You should only have to deal with this if you’re developing middleware for a custom integration.
- The basic response from a given request.
Functions§
- Creates a new JWT. You should use this to issue all client JWTs and create the initial JWT for communication with the subscriptions server (more information in the book).
- Decodes time strings like ‘1w’ into actual datetimes from the present moment. If you’ve ever used NodeJS’s
jsonwebtoken
module, this is very similar (based on Vercel’sms
module for JavaScript). Accepts strings of the form ‘xXyYzZ…’, where the lower-case letters are numbers meaning a number of the intervals X/Y/Z (e.g. 1m4d – one month four days). The available intervals are: - Transforms a string JWT secret into a form in which it can be used for operations.
- Validates a JWT and returns the payload. All client JWTs are automatically validated and their payloads are sent (parsed) to your resolvers, but if you have a system on top of that you’ll want to use this function (not required for normal Diana usage though).