Mercurial > prosody-modules
view mod_pubsub_post/README.markdown @ 4919:347e34c3c7e2
mod_rest: Improve error handling during format mapping
Prevents e.g. a nil, error return going directly into e.g. json
encoding, resulting in "null" being returned.
Further handling improvements down the line is needed.
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Thu, 07 Apr 2022 17:49:08 +0200 |
parents | 8d4b91a703af |
children | 18774cc621d6 |
line wrap: on
line source
--- labels: - 'Stage-Stable' summary: Publish to PubSub nodes from via HTTP POST/WebHooks --- # 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 ``` {.bash} 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 ``` {.bash} 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 ``` {.bash} 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: ``` {.lua} -- 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](https://www.w3.org/TR/2018/REC-websub-20180123/) [Authenticated Content Distribution](https://www.w3.org/TR/2018/REC-websub-20180123/#authenticated-content-distribution) authentication is used. ``` {.lua} 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. ::: {.alert .alert-danger} If configured without a secret and a default actor that has permission to create nodes the service becomes wide open. ::: ## 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](https://xmpp.org/extensions/xep-0060.html#owner-affiliations), in trunk since [revision 384ef9732b81](https://hg.prosody.im/trunk/rev/384ef9732b81), so affiliations can be configured with a capable client. It can however be done from another plugin: ``` {.lua} 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 trunk allows posting JSON and having it converted to XML based on a special JSON Schema. ``` json { "properties" : { "content" : { "type" : "string" }, "title" : { "type" : "string" } }, "type" : "object", "xml" : { "name" : "musings", "namespace" : "urn:example:princely" } } ``` And in the Prosody config file: ``` lua pubsub_post_mappings = { princely_musings = "musings.json"; } ``` Then, POSTing a JSON payload like ``` json { "content" : "To be, or not to be: that is the question", "title" : "Soliloquy" } ``` results in a payload like ``` xml <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.