RFC: GraphQL Subscriptions

[aklish]

Overview

Elide support for GraphQL subscriptions would allow interactive websockets and also eliminate client-side polling large models for changes. The proposed subscriptions would notify clients of any changes (create, delete, update) to any Elide model in realtime.

Annotations

The elide-graphql package will support the following new model annotation:

@Target({TYPE, METHOD, FIELD})
@Retention(RUNTIME)
public @interface Subscription {

    enum Operation {
        CREATE,
        UPDATE,
        DELETE
    };

    Operation[] operations();
}

Models or their properties can be annotated. If only the model is annotated, it signifies that all fields within the model are available for subscription. If individual fields within a model are annotated, only those fields, are available for subscription. (It is important to limit the field set available for subscriptions to minimize unnecessary data published to subscription topics. )

GraphQL Schema

A Book model annotated with the Subscription annotation would produce a GraphQL schema as follows:

type Subscription {
   bookAdded(filter: String!): Book  
   bookUpdated(filter: String!): Book
   bookdeleted(filter: String!): Book
} 

The Book type returned here comes from a separate GraphQL schema for subscriptions. It only includes the attributes and relationships of Book that have been annotated as part of the subscription.

Subscription Filters

All subscriptions can be filtered by providing a RSQL filter. It is only valid to filter on fields in the subscription annotation.

API Endpiont

Elide graphql will include a new websocket servlet endpoint that exposes subscriptions and their associated schemas.

Pub/Sub Configuration

Elide will leverage JMS to communicate with a pubsub message bus to:

1. Create topics for each model and each operation that has a Subscription annotation.
2. Publish Jackson serialized JSON for each subscription whenever its corresponding Elide model is created, deleted, or updated.

Implementation Details

The following is a brief synopsis of how this feature might be implemented.

GraphQL-Java Version

An upgrade to the latest GraphQL-java version should not be required to implement this RFC.

Two Elide Instances

Subscriptions will leverage a different Elide instance backed by a new read-only DataStore that can read from JMS topics. The DataStore will manage all models that include the Subscription annotation. The new DataStore will leverage Elide's dynamic type system to create new data types for Elide models - limiting the models, attributes, and relationships to only those annotated with Subscription.

Lifecycle Hooks

The primary (non-subscription) elide instance will register life cycle hooks for create, update, and delete for any model marked with a Subscription annotation. The lifecycle hook will serialize the impacted object using a custom Jackson serializer and post the resulting JSON to the corresponding topic in JMS.

Jackson

A custom Jackson serializer will serialize objects and ignore any attribute or relationship that has not been marked with the Subscription annotation.

Custom Data Store

A new, read-only JMSDataStore will be created that:

1. Only populates the entity dictionary with models that have been annotated with Subscription.
2. Creates new dynamic types for each populated model with limited fields based on the Subscription annotation.
3. Deserializes objects from JMS topics into Elide models in the loadRecords function.
4. Delegate to the In-Memory store for model filtering.
5. Includes a custom iterator to wrap a JMS MessageListener.

Subclass ModelBuilder

A subclass of the GraphQL ModelBuilder that builds subscription types instead of mutations & queries.

Modified QueryRunner

Modify or subclass the GraphQL QueryRunner to support reactive ExecutionResults.

New Reactive DataFetcher

A new, simplified, reactive GraphQL DataFetcher for subscriptions. Given that pagination will not be supported, we can remove the concept of Nodes and Edges from the response payloads.

GraphQL Websocket Servlet

A new servlet that will use the modified QueryRunner to execute GraphQL queries and pass the Reactive result to the websocket.

[moizarafat]

👍