Crate diana[−][src]
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’s greatest feature is that it provides opinionated deployment methods that just work. You can deploy Diana with Actix Web (support for alternative server libraries coming soon) or as a serverless function on any system that gives you a request body and access to HTTP headers, with prebuilt deployment support for AWS Lambda and its derivatives (like Netlify). However, serverless functions cannot run subscriptions, so Diana provides a subscriptions server system that can be run externally to the serverless function, allowing you to minimise hosting costs. The communication between the two is supported fully out-of-the-box authenticated by JWTs.
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!
Diana is built as a high-level wrapper around async_graphql, and uses it for all internal GraphQL operations.
All examples on how to use Diana and further documentation are in the book (under construction).
Installation
This crate is on crates.io and can be used by adding diana to your dependencies in your project’s
Cargo.toml like so:
[dependencies]
diana = "0.1.0"
Modules
The module for errors and results. This uses error_chain behind the scenes.
You’ll also find GQLResult and GQLError in here, which may be useful in working with your own resolvers.
The module for utility functions useful when developing your own schemas.
Macros
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 call bail! with an ErrorKind::Unauthorised
error if the user is unauthenticated, so that must be handled in your function’s return type!
Asynchronous stream
Structs
Application builder - structure that follows the builder pattern for building application instances.
Empty mutation
Empty subscription
An HTTP Server.
The Lambda function execution context. The values in this struct are populated using the Lambda environment variables and the headers returned by the poll request to the Runtime APIs.
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 OptionsBuilder 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 response from a generic serverless request invocation. This is the primitive you’ll likely process into some kind of custom response if you’re not using AWS Lambda or one of its derivatives (e.g. Netlify). If you are, use run_aws_req and ignore this!
Traits
A conversion of self into a Response<Body> for various types.
A stream of values produced asynchronously.
An extension trait for the Stream trait that provides a variety of
convenient combinator functions.
Functions
Creates a configuration handler to create a new GraphQL server for queries and mutations.
The resulting server will not support subscriptions, you should use create_subscriptions_server for that.
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).
Creates a configuration handler to create a new GraphQL server for subscriptions.
The resulting server will not support your queries and mutations, you should use create_graphql_server for that. It will however
expose a publish mutation that Publisher automatically works with.
Decodes time strings like ‘1w’ into actual times from the present moment.
Accepts strings of the form ‘xXyYzZ…’, where the lower-case letters are numbers meaning a number of the intervals X/Y/Z.
The available intervals are:
s: second,
m: minute,
h: hour,
d: day,
w: week,
M: month (30 days used here, 12M =/= 1y!),
y: year (365 days always, leap years ignored, if you want them add them as days)
Decodes time strings like ‘1w’ into actual datetimes from the present moment. If you’ve ever used Node’s jsonwebtoken module, this is
very similar (based on Vercel’s ms 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.
Runs a request for AWS Lambda or its derivatives (e.g. Netlify). This just takes the entire Lambda request and does all the processing for you, but it’s really just a wrapper around run_serverless_req. You should use this function in your Lambda handler.
Runs a GraphQL query/mutation in a serverless function. This is deliberately as general as possible so we support basically every serverless
function provider. If you’re using AWS Lambda or one of its derivatives (e.g. Netlify), you can use run_aws_req instead for greater
convenience.
There are no examples for the usage of this function because it’s a primitive. Just provide a request body (which should contain the query,
variables, etc.) and the HTTP Authorization header. You don’t need to do any further processing, this function will do the rest.
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).
Type Definitions
A very generic error type that the lambda will accept as a return type.
Context object for resolve field
Type alias for http::Requests with a fixed Body type