mod_pubsub_subscription

Introduction

This module lets you programmatically subscribe to updates from a pubsub node, even if the pubsub service is remote.

Example

module:depends("pubsub_subscription");
module:add_item("pubsub-subscription", {
    service = "pubsub.example.com";
    node = "otter_facts";

    -- Callbacks:
    on_subscribed = function()
        module:log("info", "Otter facts incoming!");
    end;

    on_item = function(event)
        module:log("info", "Random Otter Fact: %s", event.payload:get_text());
    end;
});

Usage

Ensure the module is loaded and add your subscription via the :add_item API. The item table MUST have service and node fields and SHOULD have one or more on_<event> callbacks.

The JID of the pubsub service is given in service (could also be the JID of an user for advanced PEP usage) and the node is given in, unsurprisingly, the node field.

The various on_event callback functions, if present, gets called when new events are received. The most interesting would be on_item, which receives incoming items. Available events are:

on_subscribed

The subscription was successful, events may follow.

on_unsubscribed

Subscription was removed successfully, this happens if the subscription is removed, which you would normally never do.

on_error

If there was an error subscribing to the pubsub service. Receives a table with type, condition, text, and extra fields as argument.

on_item

An item publication, the payload itself available in the payload field in the table provided as argument. The ID of the item can be found in item.attr.id.

on_retract

When an item gets retracted (removed by the publisher). The ID of the item can be found in item.attr.id of the table argument..

on_purge

All the items were removed by the publisher.

on_delete

The entire pubsub node was removed from the pubsub service. No subscription exists after this.

event_payload = {
    -- Common prosody event entries:
    stanza = util.stanza;
    origin = util.session;

    -- PubSub service details
    service = "pubsub.example.com";
    node = "otter_facts";

    -- The pubsub event itself
    item = util.stanza; -- <item/>
    payload = util.stanza; -- actual payload, child of <item/>
}

Compatibility

Should work with Prosody >= 0.11.x

sudo prosodyctl install --server=https://modules.prosody.im/rocks/ mod_pubsub_subscription