Mercurial > prosody-modules
annotate mod_pubsub_subscription/README.md @ 6029:cc665f343690
mod_firewall: SUBSCRIBED: Flip subscription check to match documentation
The documentation claims that this condition checks whether the recipient is
subscribed to the sender.
However, it was using the wrong method, and actually checking whether the
sender was subscribed to the recipient.
A quick poll of folk suggested that the documentation's approach is the right
one, so this should fix the code to match the documentation.
This should also fix the bundled anti-spam rules from blocking presence from
JIDs that you subscribe do (but don't have a mutual subscription with).
| author | Matthew Wild <mwild1@gmail.com> |
|---|---|
| date | Fri, 22 Nov 2024 13:50:48 +0000 |
| parents | fe081789f7b5 |
| children |
| 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 |
