prosody-modules: mod_pubsub_subscription/README.markdown annotate

annotate mod_pubsub_subscription/README.markdown @ 4942:e7b9bc629ecc

mod_rest: Add special handling to catch MAM results from remote hosts Makes MAM queries to remote hosts works. As the comment says, MAM results from users' local archives or local MUCs are returned via origin.send() which is provided in the event and thus already worked. Results from remote hosts go via normal stanza routing and events, which need this extra handling to catch. This pattern of iq-set, message+, iq-result is generally limited to MAM. Closest similar thing might be MUC join, but to really handle that you would need the webhook callback mechanism.

author	Kim Alvefur <zash@zash.se>
date	Mon, 16 May 2022 19:47:09 +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

Mercurial > prosody-modules

annotate mod_pubsub_subscription/README.markdown @ 4942:e7b9bc629ecc