pubsub.ex (2891B)
1 defmodule Absinthe.Subscription.Pubsub do 2 @moduledoc """ 3 Pubsub behaviour expected by Absinthe to power subscriptions 4 5 A subscription includes a GraphQL query document that resolves to a set of 6 objects and fields. When the subscription is triggered, Absinthe will run the 7 document and publish the resolved objects to subscribers through a module that 8 implements the behaviour defined here. 9 10 Each application is free to implement the PubSub behavior in its own way. 11 For example, the absinthe_phoenix project implements the subscription pubsub 12 using Phoenix.PubSub by way of the application's Endpoint. Regardless 13 of the underlying mechanisms, the implementation should maintain the type 14 signatures and expected behaviors of the callbacks below. 15 """ 16 17 @type t :: module() 18 19 @doc """ 20 Subscribe the current process for messages about the given topic. 21 """ 22 @callback subscribe(topic :: binary) :: term 23 24 @doc """ 25 An Absinthe.Subscription.Pubsub system may extend across multiple nodes 26 connected by some mechanism. Regardless of this mechanism, all nodes should 27 have unique names. 28 29 Absinthe invokes `node_name` function to get current node's name. If you 30 are running inside erlang cluster, you can use `Kernel.node/0` as a node 31 name. 32 """ 33 @callback node_name() :: binary 34 35 @doc """ 36 An Absinthe.Subscription.Pubsub system may extend across multiple nodes. 37 Processes need only subscribe to the pubsub process that 38 is running on their own node. 39 40 However, mutations can happen on any node in the cluster and must to be 41 broadcast to other nodes so that they can also reevaluate their GraphQL 42 subscriptions and notify subscribers on that node. 43 44 When told of a mutation, Absinthe invokes the `publish_mutation` function 45 on the node in which the mutation is processed first. The function should 46 publish a message to the given `proxy_topic`, with the identity of node 47 on which the mutation occurred included in the broadcast message. 48 49 The message broadcast should be a map that contains, at least 50 51 %{ 52 node: node_name, # should be equal to `node_name/0` 53 mutation_result: …, # from arguments 54 subscribed_fields: … # from arguments 55 56 # other fields as needed 57 } 58 59 """ 60 @callback publish_mutation( 61 proxy_topic :: binary, 62 mutation_result :: term, 63 subscribed_fields :: list 64 ) :: term 65 66 @doc """ 67 After a mutation is published, and Absinthe has re-run the necessary GraphQL 68 subscriptions to generate a new set of resolved data, it calls 69 `publish_subscription`. 70 71 Your pubsub implementation should publish a message to the given topic, with 72 the newly resolved data. The broadcast should be limited to the current node 73 only. 74 """ 75 @callback publish_subscription(topic :: binary, data :: map) :: term 76 end