mod_pubsub_post

Introduction

This module is a fairly generic WebHook receiver that lets you easily publish data to PubSub using a HTTP POST request. The payload can be Atom feeds, arbitrary XML, or arbitrary JSON. The type should be indicated via the Content-Type header.

• JSON data is wrapped in a XEP-0335 container.
• An Atom feed may have many <entry> and each one is published as its own PubSub item.
• Other XML is simply published to the item with ID current.

JSON example

curl http://localhost:5280/pubsub_post/princely_musings \
    -H "Content-Type: application/json" \
    --data-binary '{"musing":"To be, or not to be: that is the question"}'

Atom example

curl http://localhost:5280/pubsub_post/princely_musings \
    -H "Content-Type: application/xml" \
    --data-binary '<feed xmlns="http://www.w3.org/2005/Atom">
        <entry><title>Hello</title></entry></feed>'

Simple form-data

curl http://localhost:5280/pubsub_post/princely_musings \
    --data musing="To be, or not to be: that is the question"

Configuration

All settings are optional.

Actor identification

First we have to figure out who is making the request. This is configured on a per-node basis like this:

-- Per node secrets
pubsub_post_actors = {
    princely_musings = "hamlet@denmark.lit"
}
pubsub_post_default_actor = "nobody@nowhere.invalid"

pubsub_post_default_actor is used when trying to publish to a node that is not listed in pubsub_post_actors. Otherwise the IP address of the connection is used.

Authentication

WebSub Authenticated Content Distribution authentication is used.

pubsub_post_secrets = {
    princely_musings = "shared secret"
}
pubsub_post_default_secret = "default secret"

pubsub_post_default_secret is used when trying to publish to a node that is not listed in pubsub_post_secrets. Otherwise the request proceeds with the previously identified actor.

Authorization

Authorization is handled via pubsub affiliations. Publishing requires an affiliation with the publish capability, usually "publisher".

Setting up affiliations

Prosodys PubSub module supports setting affiliations via XMPP, since 0.11.0, so affiliations can be configured with a capable client.

It can however be done from another plugin:

local mod_pubsub = module:depends("pubsub");
local pubsub = mod_pubsub.service;

pubsub:create("princely_musings", true);
pubsub:set_affiliation("princely_musings", true, "127.0.0.1", "publisher");

Data mappings

The datamapper library added in 0.12.0 allows posting JSON and having it converted to XML based on a special JSON Schema.

{
   "properties" : {
      "content" : {
         "type" : "string"
      },
      "title" : {
         "type" : "string"
      }
   },
   "type" : "object",
   "xml" : {
      "name" : "musings",
      "namespace" : "urn:example:princely"
   }
}

And in the Prosody config file:

pubsub_post_mappings = {
    princely_musings = "musings.json";
}

Then, POSTing a JSON payload like

{
   "content" : "To be, or not to be: that is the question",
   "title" : "Soliloquy"
}

results in a payload like

<musings xmlns="urn:example:princely">
  <title>Soliloquy</title>
  <content>To be, or not to be: that is the question</content>
</musings>

being published to the node.

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