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

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.

Link to this section Summary

Types

t()

Callbacks

node_name()

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

publish_mutation(proxy_topic, mutation_result, subscribed_fields)

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.

publish_subscription(topic, data)

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(topic)

Subscribe the current process for messages about the given topic.

Link to this section Types

t()

Specs

t() :: module()

Link to this section Callbacks

node_name()

Specs

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.

publish_mutation(proxy_topic, mutation_result, subscribed_fields)

Specs

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 custer 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
}

publish_subscription(topic, data)

Specs

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.