com.walmartlabs.lacinia.pedestal — com.walmartlabs/lacinia-pedestal 0.8.0

Defines Pedestal interceptors and supporting code.

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.

default-interceptors clj

(default-interceptors compiled-schema options)

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

• ::json-response json-response-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
• ::inject-app-context inject-app-context-interceptor
• ::query-executor query-executor-handler or async-query-executor-handler

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

Often, this list of interceptors is augemented by calls to inject.

Options:

:async (default false) : If true, the query will execute asynchronously (return a core.async channel).

:app-context : The base application context provided to Lacinia when executing a query.

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.

extract-query clj multimethod

Based on the content type of the query, adds up to three keys to the request:

:graphql-query : The query itself, as a string (parsing the query happens later)

:graphql-vars : A map of variables used when executing the query.

:graphql-operation-name : The specific operation requested (for queries that define multiple named operations).

graphiql-ide-response clj

(graphiql-ide-response options)

Reads the graphiql.html resource, then injects new content into it, and ultimately returns a Ring response map.

This function is used when creating customized Pedestal routers that expose the GraphiQL IDE.

Options are as specified in graphql-routes.

Reads the template file, makes necessary substitutions, and returns a Ring response.

graphql-data-interceptor clj

Extracts the raw data (query and variables) from the request using extract-query.

graphql-routes clj

(graphql-routes compiled-schema options)

Creates default routes for handling GET and POST requests and (optionally) the GraphiQL IDE.

The paths for the routes are determined by the options.

Returns a set of route vectors, compatible with io.pedestal.http.route.definition.table/table-routes.

Uses default-interceptors to define the base seq of interceptors. For the POST route, body-data-interceptor is prepended.

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

Options:

:graphiql (default: false) : If true, enables routes for the GraphiQL IDE.

:path (default: "/graphql") : Path at which GraphQL requests are services (distinct from the GraphQL IDE).

:ide-path (default: "/") : Path from which the GraphiQL IDE, if enabled, can be loaded.

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

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

:interceptors : A seq of interceptors, to be passed to routes-from-interceptors.

:async (default: false) : If true, the query will execute asynchronously; the handler will return a clojure.core.async channel rather than blocking.

:app-context : The base application context provided to Lacinia when executing a query.

Asset paths use wildcard matching; you should be careful to ensure that the asset path does not overlap the paths for query request handling, the IDE, or subscriptions (or the asset handler will override the others and deliver 404 responses).

inject clj

(inject interceptors new-interceptor relative-position interceptor-name)

Locates the named interceptor in the list of interceptors and adds (or replaces) the new interceptor to the list.

relative-position may be :before, :after, or :replace.

The named interceptor must exist, or an exception is thrown.

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 when there's no GraphQL query in the request map.

This must come after graphql-data-interceptor, which is responsible for adding the query to the request map.

pedestal-service clj deprecated

(pedestal-service compiled-schema options)

This function has been deprecated in favor of service-map, but is being maintained for compatibility.

This simply invokes service-map and passes the resulting map through io.pedestal.http/create-server.

To be removed in 0.8.0.

query-executor-handler clj

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

The handler adds the Ring request map as the :request key to the provided app-context before executing the query.

This comes after query-parser-interceptor, inject-app-context-interceptor, and status-conversion-interceptor in the interceptor chain.

query-parser-interceptor clj

(query-parser-interceptor compiled-schema)

Given an 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 and prepared query.

routes-from-interceptors clj

(routes-from-interceptors route-path interceptors options)

Returns a set of route vectors from a primary seq of interceptors. This returns a two element set, one for GET (using the seq as is), and one for POST (prefixing with body-data-interceptor.

Options:

:get-enabled (default true) : If true, then a route for the GET method is included.

service-map clj

(service-map compiled-schema options)

Creates and returns a Pedestal service map. This uses a server type of :jetty.

The returned service map can be passed to the io.pedestal.http/create-server function.

The deprecated function pedestal-service invokes create-server before returning. However, in many cases, further extensions to the service map are needed before creating and starting the server.

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

Options:

:graphiql (default: false) : If given, then enables resources to support the GraphiQL IDE. This includes disabling the Content-Security-Policy headers that Pedestal 0.5.3 generates by default.

:routes (default: via graphql-routes) : Used when explicitly setting up the routes. It is significantly easier to configure the interceptors than to set up the routes explicitly, this option exists primarily for backwards compatibility.

:subscriptions (default: false) : If enabled, then support for WebSocket-based subscriptions is added. : See [[listener-fn-factory]] for further options related to subscriptions.

:path (default: "/graphql") : Path at which GraphQL requests are services (distinct from the GraphQL IDE).

:ide-path (default: "/") : Path from which the GraphiQL IDE, if enabled, can be loaded.

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

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

:interceptors : A seq of interceptors to be used in GraphQL routes; passed to routes-from-interceptors. If not provided, default-interceptors is invoked.

:async (default: false) : If true, the query will execute asynchronously; the handler will return a clojure.core.async channel rather than blocking.

:app-context : The base application context provided to Lacinia when executing a query.

:subscriptions-path (default: "/graphql-ws") : If subscriptions are enabled, the path at which to service GraphQL websocket requests. This must be a distinct path (not the same as the main path or the GraphiQL IDE path).

:port (default: 8888) : HTTP port to use.

:env (default: :dev) : Environment being started.

See further notes in graphql-routes and default-interceptors.

status-conversion-interceptor clj

Checks to see if any error map in the :errors key of the response contains a :status value. 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.