view mod_pubsub_subscription/README.markdown @ 4575:5b4f43b90766

mod_measure_malloc: port to most recent trunk statistics API
author Jonas Schäfer <>
date Tue, 25 May 2021 19:01:54 +0200
parents 97fac0ba0469
line wrap: on
line source

# Introduction

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

## Example

``` {.lua}
module:add_item("pubsub-subscription", {
    service = "";
    node = "otter_facts";

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

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

## 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:

:   The subscription was successful, events may follow.

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

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

:   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 ``.

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

:   All the items were removed by the publisher.

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

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

    -- PubSub service details
    service = "";
    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