com.walmartlabs.lacinia.pedestal.subscriptions — com.walmartlabs/lacinia-pedestal 0.12.0-alpha-1

Support for GraphQL subscriptions using Jetty WebSockets, following the design of the Apollo client and server.

default-subscription-interceptors clj

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

Processing of operation requests from the client is passed through interceptor pipeline. The context for the pipeline includes special keys for the necessary channels.

The :request key is the payload sent from the client, along with additional keys:

:response-data-ch : Channel to which Clojure data destined for the client should be written. : This should be closed when the subscription data is exhausted.

:shutdown-ch : This channel will be closed if the client terminates the connection. For subscriptions, this ensures that the subscription is cleaned up.

:id : The client-provided string that must be included in the response.

For mutation and query operations, a :response key is added to the context, which triggers a response to the client.

For subscription operations, it's a bit different; there's no immediate response, but a new CSP will work with the streamer defined by the subscription to send a sequence of "data" messages to the client.

• ::exception-handler -- exception-handler-interceptor
• ::send-operation-response -- send-operation-response-interceptor
• ::query-parser -- query-parser-interceptor
• ::inject-app-context -- inject-app-context-interceptor
• ::execute-operation -- execute-operation-interceptor

Returns a vector of interceptors.

exception-handler-interceptor clj

An interceptor that implements the :error callback, to send an "error" message to the client.

execute-operation-interceptor clj

Executes a mutation or query operation and sets the :response key of the context, or executes a long-lived subscription operation.

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.

It is not uncommon to replace this interceptor with one that constructs the application context dynamically.

listener-fn-factory clj

(listener-fn-factory compiled-schema options)

A factory for the function used to create a WS listener.

This function is invoked for each new client connecting to the service.

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

Once a subscription is initiated, the flow is:

streamer -> values channel -> resolver -> response channel -> send channel

The default channels are all buffered and non-lossy, which means that a very active streamer may be able to saturate the web socket used to send responses to the client. By introducing lossiness or different buffers, the behavior can be tuned.

Each new subscription from the same client will invoke a new streamer and create a corresponding values channel, but there is only one response channel per client.

Options:

:keep-alive-ms (default: 30000) : The interval at which keep alive messages are sent to the client.

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

:subscription-interceptors : A seq of interceptors for processing queries. The default is derived from default-subscription-interceptors.

:init-context : A function returning the base context for the subscription-interceptors to operate on. The function takes the following arguments:

• the minimal viable context for operation
• the ServletUpgradeRequest that initiated this connection
• the ServletUpgradeResponse to the upgrade request Defaults to returning the context unchanged.

:response-chan-fn : A function that returns a new channel. Responses to be written to client are put into this channel. The default is a non-lossy channel with a buffer size of 10.

:values-chan-fn : A function that returns a new channel. The channel conveys the values provided by the subscription's streamer. The values are executed as queries, then transformed into responses that are put into the response channel. The default is a non-lossy channel with a buffer size of 1.

:send-buffer-or-n : Used to create the channel of text responses sent to the client. The default is 10 (a non-lossy channel).

query-parser-interceptor clj

(query-parser-interceptor compiled-schema)

An interceptor that parses the query and places a prepared and validated query into the :parsed-lacinia-query key of the request.

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

send-operation-response-interceptor clj

Interceptor responsible for the :response key of the context (set when a request is either a query or mutation, but not a subscription). The :response data is packaged up as the payload of a "data" message to the client, followed by a "complete" message.