Mercurial > prosody-modules

annotate mod_pubsub_subscription/README.markdown @ 5897:896e7c7bf87f

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