View Source Absinthe.Subscription.Pubsub behaviour (absinthe v1.7.8)

Pubsub behaviour expected by Absinthe to power subscriptions

A subscription includes a GraphQL query document that resolves to a set of objects and fields. When the subscription is triggered, Absinthe will run the document and publish the resolved objects to subscribers through a module that implements the behaviour defined here.

Each application is free to implement the PubSub behavior in its own way.
For example, the absinthe_phoenix project implements the subscription pubsub using Phoenix.PubSub by way of the application's Endpoint. Regardless of the underlying mechanisms, the implementation should maintain the type signatures and expected behaviors of the callbacks below.

Summary

Callbacks

An Absinthe.Subscription.Pubsub system may extend across multiple nodes connected by some mechanism. Regardless of this mechanism, all nodes should have unique names.

An Absinthe.Subscription.Pubsub system may extend across multiple nodes. Processes need only subscribe to the pubsub process that is running on their own node.

After a mutation is published, and Absinthe has re-run the necessary GraphQL subscriptions to generate a new set of resolved data, it calls publish_subscription.

Subscribe the current process for messages about the given topic.

Types

Callbacks

@callback node_name() :: binary()

An Absinthe.Subscription.Pubsub system may extend across multiple nodes connected by some mechanism. Regardless of this mechanism, all nodes should have unique names.

Absinthe invokes node_name function to get current node's name. If you are running inside erlang cluster, you can use Kernel.node/0 as a node name.

Link to this callback

publish_mutation(proxy_topic, mutation_result, subscribed_fields)

View Source
@callback publish_mutation(
  proxy_topic :: binary(),
  mutation_result :: term(),
  subscribed_fields :: list()
) :: term()

An Absinthe.Subscription.Pubsub system may extend across multiple nodes. Processes need only subscribe to the pubsub process that is running on their own node.

However, mutations can happen on any node in the cluster and must to be broadcast to other nodes so that they can also reevaluate their GraphQL subscriptions and notify subscribers on that node.

When told of a mutation, Absinthe invokes the publish_mutation function on the node in which the mutation is processed first. The function should publish a message to the given proxy_topic, with the identity of node on which the mutation occurred included in the broadcast message.

The message broadcast should be a map that contains, at least

%{
    node: node_name,      # should be equal to `node_name/0`
    mutation_result: ,   # from arguments
    subscribed_fields:   # from arguments

    # other fields as needed
}
Link to this callback

publish_subscription(topic, data)

View Source
@callback publish_subscription(topic :: binary(), data :: map()) :: term()

After a mutation is published, and Absinthe has re-run the necessary GraphQL subscriptions to generate a new set of resolved data, it calls publish_subscription.

Your pubsub implementation should publish a message to the given topic, with the newly resolved data. The broadcast should be limited to the current node only.

Link to this callback

run_docset(pubsub, docs_and_topics, mutation_result)

View Source (optional)
@callback run_docset(pubsub :: t(), docs_and_topics :: list(), mutation_result :: term()) ::
  term()
@callback subscribe(topic :: binary()) :: term()

Subscribe the current process for messages about the given topic.