Mercurial > prosody-modules
view mod_pubsub_post/README.markdown @ 4094:dd00a2b9927c
mod_invites_page: New module to generate landing page for invites
author | Matthew Wild <mwild1@gmail.com> |
---|---|
date | Fri, 11 Sep 2020 13:52:32 +0100 |
parents | a6db99c1420a |
children | c87181a98f29 |
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 a randomly named item as-is. ## 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>' ``` # 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"); ```