Mercurial > prosody-modules
view mod_pubsub_post/README.markdown @ 5424:b45d9a81b3da
mod_http_oauth2: Revert role selector, going to try something else
Back out f2c7bb3af600
Allowing only a single role to be encoded into the grant takes away the
possibility of having multiple roles in the grant, one of which is
selected when issuing an access token. It also takes away the ability to
have zero roles granted, which could be useful e.g. when you only need
OIDC scopes.
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Sun, 07 May 2023 19:40:57 +0200 |
parents | 18774cc621d6 |
children |
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), since 0.11.0, 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 0.12.0 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.