author | Matthew Wild <mwild1@gmail.com> |
Wed, 13 Jul 2022 11:20:09 +0100 | |
changeset 5002 | 5ab134b7e510 |
parent 4515 | 97fac0ba0469 |
permissions | -rw-r--r-- |
4515
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 |