Mercurial > prosody-modules
annotate mod_pubsub_subscription/README.markdown @ 5418:f2c7bb3af600
mod_http_oauth2: Add role selector to consent page
List includes all roles available to the user, if more than one.
Defaults to either the first role in the scope string or the users
primary role.
Earlier draft listed all roles, but having options that can't be
selected is bad UX and the entire list of all roles on the server could
be long, and perhaps even sensitive.
Allows e.g. picking a role with fewer permissions than what might
otherwise have been selected.
UX wise, doing this with more checkboxes or possibly radio buttons would
have been confusion and/or looked messier.
Fixes the previous situation where unselecting a role would default to
the primary role, which could be more permissions than requested.
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Fri, 05 May 2023 01:23:13 +0200 |
parents | 97fac0ba0469 |
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 |