com.walmartlabs.lacinia.pedestal2 — com.walmartlabs/lacinia-pedestal 0.15.0-alpha-2

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 app-context)

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).

Often, this list of interceptors is augmented by calls to [[inject]].

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 schema or a function returning the schema.

options is a map combining options needed by [[graphiql-ide-route]] and [[listener-fn-factory]].

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

This is useful for initial development and exploration, but applications with any more 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).

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.

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)

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.

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.