Mercurial > prosody-modules

annotate mod_pubsub_subscription/README.markdown @ 4980:da151f9af861

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
replaced 'session' with 'origin' in push_disable session is not defined in this function, trying to access it leads to an error. The correct reference seems to be 'origin'. (This may have come about by copying from the similar code in process_stanza_queue.)
author arcseconds
date Sat, 30 Jul 2022 21:07:47 +1200
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