com.walmartlabs.lacinia.pedestal2 — com.walmartlabs/lacinia-pedestal 1.2-beta-1

Utilities for creating handlers, interceptors, routes, and service maps needed by a Pedestal service that exposes a GraphQL API and GraphiQL IDE.

async-query-executor-handler clj

Async variant of query-executor-handler which returns a channel that conveys the updated context.

body-data-interceptor clj

Converts the POSTed body from a input stream into a string, or rejects the request with a 400 response if the content type is not application/json.

default-interceptors clj

(default-interceptors compiled-schema)

(default-interceptors compiled-schema app-context)

(default-interceptors compiled-schema app-context options)

Returns the default set of GraphQL interceptors, as a seq:

• ::initialize-tracing initialize-tracing-interceptor
• ::json-response json-response-interceptor
• ::error-response error-response-interceptor
• ::body-data body-data-interceptor
• ::graphql-data graphql-data-interceptor
• ::status-conversion status-conversion-interceptor
• ::missing-query missing-query-interceptor
• ::query-parser query-parser-interceptor
• ::disallow-subscriptions disallow-subscriptions-interceptor
• ::prepare-query prepare-query-interceptor
• ::inject-app-context inject-app-context-interceptor
• ::enable-tracing enable-tracing-interceptor
• ::query-executor query-executor-handler

compiled-schema may be the actual compiled schema, or a no-arguments function that returns the compiled schema.

app-context is the application context that will be passed into all resolvers (the inject-app-context-interceptor adds a :request key to this map).

The options map may contain key :parsed-query-cache, which will be used by the ::query-parser interceptor.

default-service clj

(default-service compiled-schema options)

Returns a default Pedestal service map, with subscriptions and GraphiQL enabled.

The defaults put the GraphQL API at /api and the GraphiQL IDE at /ide (and subscriptions endpoint at /ws).

Unlike earlier versions of lacinia-pedestal, only POST is supported, and the content type must be application/json.

compiled-schema is either the compiled schema itself, or a function returning the compiled schema.

options is a map combining options needed by [[graphiql-ide-route]], default-interceptors, enable-subscriptions, and [[listener-fn-factory]].

It may also contain keys :app-context and :port (which defaults to 8888).

You can also define an explicit :host address to your application. Useful when running inside Docker.

This is useful for initial development and exploration, but applications with any more sophisticated needs should construct their service map directly.

disallow-subscriptions-interceptor clj

Handles requests for subscriptions. Subscription requests must only be sent to the subscriptions web-socket, not the general query endpoint, so any subscription request received in this pipeline is a bad request.

enable-graphiql clj

(enable-graphiql service-map)

Disables secure headers in the service map, a prerequisite for GraphiQL requests to operate.

enable-subscriptions clj

(enable-subscriptions service-map compiled-schema subscription-options)

Updates a Pedestal service map to add support for subscriptions.

As elsewhere, the compiled-schema may be a function that returns the compiled schema.

The subscription options are documented at [[listener-fn-factory]], with the addition of :subscriptions-path (defaulting to "/ws").

enable-tracing-interceptor clj

Enables tracing if the lacinia-tracing header is present.

error-response-interceptor clj

Returns an internal server error response when an exception was not handled in prior interceptors.

This must come after json-response-interceptor, as the error still needs to be converted to json.

graphiql-asset-routes clj

(graphiql-asset-routes asset-path)

Returns a set of routes for retrieving GraphiQL assets (CSS and JS).

These routes are needed for the GraphiQL IDE to operate.

graphiql-ide-handler clj

(graphiql-ide-handler options)

Returns a handler for the GraphiQL IDE.

A route can be constructed from this handler.

Options:

:api-path (default: "/api") : Path at which GraphQL requests are serviced.

:asset-path (default: "/assets/graphiql") : Path from which the JavaScript and CSS assets may be loaded.

:subscriptions-path (default: "/ws") : Path for web socket connections, to handle GraphQL subscriptions.

:ide-headers : A map from header name to header value. Keys and values may be strings, keywords, or symbols and are converted to strings using clojure.core/name. These define additional headers to be included in the requests from the IDE. Typically, the headers are used to identify and authenticate the requests.

The default for :ide-headers is `{"lacinia-tracing", "true"} to enable GraphQL tracing from inside the GraphiQL IDE>

:ide-connection-params : A value that is used with the GraphiQL IDE; this value is converted to JSON, and becomes the connectionParams passed in the initial subscription web service call; this can be used to identify and authenticate subscription requests.

graphql-data-interceptor clj

Comes after body-data-interceptor, extracts the JSON query and other data into request keys :graphql-query (the query document as a string), :graphql-vars (a map) and :graphql-operation-name (a string).

These keys are dissoc'ed on leave, or on error.

Comes after body-data-interceptor.

initialize-tracing-interceptor clj

Initializes timing information for the request; largely, this captures the earliest possible start time for the request (before any other interceptors), just in case tracing is enabled for this request (that decision is made by enable-tracing-interceptor).

inject-app-context-interceptor clj

(inject-app-context-interceptor app-context)

Adds a :lacinia-app-context key to the request, used when executing the query.

The provided app-context map is augmented with the request map, as key :request.

On leave (or error), the :lacinia-app-context key is dissoc'ed.

It is not uncommon to replace this interceptor with one that constructs the application context dynamically; for example, to extract authentication information from the request and expose that as app-context keys.

json-response-interceptor clj

An interceptor that sees if the response body is a map and, if so, converts the map to JSON and sets the response Content-Type header.

missing-query-interceptor clj

Rejects the request with a 400 response is the JSON query variable is missing or blank.

Comes after graphql-data-interceptor.

prepare-query-interceptor clj

Prepares (with query variables) and validates the query, previously parsed by query-parser-interceptor.

query-executor-handler clj

The handler at the end of interceptor chain, invokes Lacinia to execute the query and return the main response.

This comes last in the interceptor chain.

query-parser-interceptor clj

(query-parser-interceptor compiled-schema)

(query-parser-interceptor compiled-schema cache)

Given a compiled schema, returns an interceptor that parses the query.

compiled-schema may be the actual compiled schema, or a no-arguments function that returns the compiled schema.

Expected to come after missing-query-interceptor in the interceptor chain.

Adds a new request key, :parsed-lacinia-query, containing the parsed query. This key is removed on leave or on error.

cache defaults to nil, it should implement [[ParsedQueryCache]].

Before execution, prepare-query-interceptor injects query variables and performs validations.

status-conversion-interceptor clj

Checks to see if any error map in the :errors key of the response contains a :status value (under it's :extensions key). If so, the maximum status value of such errors is found and used as the status of the overall response, and the :status key is dissoc'ed from all errors.