prosody-modules
97fac0ba0469
mod_pubsub_subscription/README.markdown

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Comparison

mod_pubsub_subscription/README.markdown @ 4511:97fac0ba0469

mod_pubsub_subscription: New module providing an API for pubsub subscriptions This lets other modules hook events from local or remote XEP-0060 pubsub services. API allows keeping track of items added, removed or if the whole node gets cleared or even deleted. Requested by MattJ.
author Kim Alvefur <zash@zash.se>
date Mon, 15 Mar 2021 16:31:23 +0100
comparison
equal deleted inserted replaced
4510:6690586826e8 4511:97fac0ba0469
1 # Introduction
2
3 This module lets you programmatically subscribe to updates from a
4 [pubsub][xep0060] node, even if the pubsub service is remote.
5
6 ## Example
7
8 ``` {.lua}
9 module:depends("pubsub_subscription");
10 module:add_item("pubsub-subscription", {
11 service = "pubsub.example.com";
12 node = "otter_facts";
13
14 -- Callbacks:
15 on_subscribed = function()
16 module:log("info", "Otter facts incoming!");
17 end;
18
19 on_item = function(event)
20 module:log("info", "Random Otter Fact: %s", event.payload:get_text());
21 end;
22 });
23 ```
24
25 ## Usage
26
27 Ensure the module is loaded and add your subscription via the
28 `:add_item` API. The item table MUST have `service` and `node` fields
29 and SHOULD have one or more `on_<event>` callbacks.
30
31 The JID of the pubsub service is given in `service` (could also be the
32 JID of an user for advanced PEP usage) and the node is given in,
33 unsurprisingly, the `node` field.
34
35 The various `on_event` callback functions, if present, gets called when
36 new events are received. The most interesting would be `on_item`, which
37 receives incoming items. Available events are:
38
39 `on_subscribed`
40 : The subscription was successful, events may follow.
41
42 `on_unsubscribed`
43 : Subscription was removed successfully, this happens if the
44 subscription is removed, which you would normally never do.
45
46 `on_error`
47 : If there was an error subscribing to the pubsub service. Receives a
48 table with `type`, `condition`, `text`, and `extra` fields as
49 argument.
50
51 `on_item`
52 : An item publication, the payload itself available in the `payload`
53 field in the table provided as argument. The ID of the item can be
54 found in `item.attr.id`.
55
56 `on_retract`
57 : When an item gets retracted (removed by the publisher). The ID of
58 the item can be found in `item.attr.id` of the table argument..
59
60 `on_purge`
61 : All the items were removed by the publisher.
62
63 `on_delete`
64 : The entire pubsub node was removed from the pubsub service. No
65 subscription exists after this.
66
67 ``` {.lua}
68 event_payload = {
69 -- Common prosody event entries:
70 stanza = util.stanza;
71 origin = util.session;
72
73 -- PubSub service details
74 service = "pubsub.example.com";
75 node = "otter_facts";
76
77 -- The pubsub event itself
78 item = util.stanza; -- <item/>
79 payload = util.stanza; -- actual payload, child of <item/>
80 }
81 ```
82
83 # Compatibility
84
85 Should work with Prosody \>= 0.11.x