prosody-modules: mod_pubsub_post/README.markdown annotate

annotate mod_pubsub_post/README.markdown @ 3866:c0df50ce96f0

mod_rest: Handle internal http request errors early and then return Skips over attempted parsing of the payload which usually failed since the body is an error string like "connection refused", so this produced useless errors.

author	Kim Alvefur <zash@zash.se>
date	Sat, 25 Jan 2020 20:22:12 +0100
parents	a6db99c1420a
children	c87181a98f29

rev	line source
3505 106b4ae4469b mod_pubsub_post/README: Mention use as a webhook receiver Kim Alvefur <zash@zash.se> parents: 3503 diff changeset	1 ---
3506 7b1eede1a840 mod_pubsub_post/README: Set stage label to stable Kim Alvefur <zash@zash.se> parents: 3505 diff changeset	2 labels:
7b1eede1a840 mod_pubsub_post/README: Set stage label to stable Kim Alvefur <zash@zash.se> parents: 3505 diff changeset	3 - 'Stage-Stable'
3505 106b4ae4469b mod_pubsub_post/README: Mention use as a webhook receiver Kim Alvefur <zash@zash.se> parents: 3503 diff changeset	4 summary: Publish to PubSub nodes from via HTTP POST/WebHooks
106b4ae4469b mod_pubsub_post/README: Mention use as a webhook receiver Kim Alvefur <zash@zash.se> parents: 3503 diff changeset	5 ---
106b4ae4469b mod_pubsub_post/README: Mention use as a webhook receiver Kim Alvefur <zash@zash.se> parents: 3503 diff changeset	6
3100 0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	7 # Introduction
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	8
3505 106b4ae4469b mod_pubsub_post/README: Mention use as a webhook receiver Kim Alvefur <zash@zash.se> parents: 3503 diff changeset	9 This module is a fairly generic WebHook receiver that lets you easily
106b4ae4469b mod_pubsub_post/README: Mention use as a webhook receiver Kim Alvefur <zash@zash.se> parents: 3503 diff changeset	10 publish data to PubSub using a HTTP POST request. The payload can be
106b4ae4469b mod_pubsub_post/README: Mention use as a webhook receiver Kim Alvefur <zash@zash.se> parents: 3503 diff changeset	11 Atom feeds, arbitrary XML, or arbitrary JSON. The type should be
106b4ae4469b mod_pubsub_post/README: Mention use as a webhook receiver Kim Alvefur <zash@zash.se> parents: 3503 diff changeset	12 indicated via the `Content-Type` header.
3100 0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	13
3719 a6db99c1420a mod_pubsub_post/README: Add an example of curl-ing Atom data Kim Alvefur <zash@zash.se> parents: 3506 diff changeset	14 - JSON data is wrapped in a [XEP-0335] container.
a6db99c1420a mod_pubsub_post/README: Add an example of curl-ing Atom data Kim Alvefur <zash@zash.se> parents: 3506 diff changeset	15 - An Atom feed may have many `<entry>` and each one is published as
a6db99c1420a mod_pubsub_post/README: Add an example of curl-ing Atom data Kim Alvefur <zash@zash.se> parents: 3506 diff changeset	16 its own PubSub item.
a6db99c1420a mod_pubsub_post/README: Add an example of curl-ing Atom data Kim Alvefur <zash@zash.se> parents: 3506 diff changeset	17 - Other XML is simply published to a randomly named item as-is.
a6db99c1420a mod_pubsub_post/README: Add an example of curl-ing Atom data Kim Alvefur <zash@zash.se> parents: 3506 diff changeset	18
a6db99c1420a mod_pubsub_post/README: Add an example of curl-ing Atom data Kim Alvefur <zash@zash.se> parents: 3506 diff changeset	19 ## JSON example
a6db99c1420a mod_pubsub_post/README: Add an example of curl-ing Atom data Kim Alvefur <zash@zash.se> parents: 3506 diff changeset	20
3100 0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	21 ``` {.bash}
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	22 curl http://localhost:5280/pubsub_post/princely_musings \
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	23 -H "Content-Type: application/json" \
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	24 --data-binary '{"musing":"To be, or not to be: that is the question"}'
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	25 ```
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	26
3719 a6db99c1420a mod_pubsub_post/README: Add an example of curl-ing Atom data Kim Alvefur <zash@zash.se> parents: 3506 diff changeset	27 ## Atom example
a6db99c1420a mod_pubsub_post/README: Add an example of curl-ing Atom data Kim Alvefur <zash@zash.se> parents: 3506 diff changeset	28
a6db99c1420a mod_pubsub_post/README: Add an example of curl-ing Atom data Kim Alvefur <zash@zash.se> parents: 3506 diff changeset	29 ``` {.bash}
a6db99c1420a mod_pubsub_post/README: Add an example of curl-ing Atom data Kim Alvefur <zash@zash.se> parents: 3506 diff changeset	30 curl http://localhost:5280/pubsub_post/princely_musings \
a6db99c1420a mod_pubsub_post/README: Add an example of curl-ing Atom data Kim Alvefur <zash@zash.se> parents: 3506 diff changeset	31 -H "Content-Type: application/xml" \
a6db99c1420a mod_pubsub_post/README: Add an example of curl-ing Atom data Kim Alvefur <zash@zash.se> parents: 3506 diff changeset	32 --data-binary '<feed xmlns="http://www.w3.org/2005/Atom">
a6db99c1420a mod_pubsub_post/README: Add an example of curl-ing Atom data Kim Alvefur <zash@zash.se> parents: 3506 diff changeset	33 <entry><title>Hello</title></entry></feed>'
a6db99c1420a mod_pubsub_post/README: Add an example of curl-ing Atom data Kim Alvefur <zash@zash.se> parents: 3506 diff changeset	34
a6db99c1420a mod_pubsub_post/README: Add an example of curl-ing Atom data Kim Alvefur <zash@zash.se> parents: 3506 diff changeset	35 ```
3153 e0de1fdbc80a mod_pubsub_post/README: Describe what happens to different data types Kim Alvefur <zash@zash.se> parents: 3152 diff changeset	36
3100 0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	37 # Configuration
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	38
3503 882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	39 All settings are optional.
3100 0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	40
3503 882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	41 ## Actor identification
3100 0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	42
3503 882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	43 First we have to figure out who is making the request.
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	44 This is configured on a per-node basis like this:
3501 1df139b157fb mod_pubsub_post: Add support for WebSub authentication Kim Alvefur <zash@zash.se> parents: 3256 diff changeset	45
1df139b157fb mod_pubsub_post: Add support for WebSub authentication Kim Alvefur <zash@zash.se> parents: 3256 diff changeset	46 ``` {.lua}
1df139b157fb mod_pubsub_post: Add support for WebSub authentication Kim Alvefur <zash@zash.se> parents: 3256 diff changeset	47 -- Per node secrets
3503 882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	48 pubsub_post_actors = {
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	49 princely_musings = "hamlet@denmark.lit"
3501 1df139b157fb mod_pubsub_post: Add support for WebSub authentication Kim Alvefur <zash@zash.se> parents: 3256 diff changeset	50 }
3503 882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	51 pubsub_post_default_actor = "nobody@nowhere.invalid"
3501 1df139b157fb mod_pubsub_post: Add support for WebSub authentication Kim Alvefur <zash@zash.se> parents: 3256 diff changeset	52 ```
1df139b157fb mod_pubsub_post: Add support for WebSub authentication Kim Alvefur <zash@zash.se> parents: 3256 diff changeset	53
3503 882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	54 `pubsub_post_default_actor` is used when trying to publish to a node
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	55 that is not listed in `pubsub_post_actors`. Otherwise the IP address
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	56 of the connection is used.
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	57
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	58 ## Authentication
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	59
3501 1df139b157fb mod_pubsub_post: Add support for WebSub authentication Kim Alvefur <zash@zash.se> parents: 3256 diff changeset	60 [WebSub](https://www.w3.org/TR/2018/REC-websub-20180123/) [Authenticated
1df139b157fb mod_pubsub_post: Add support for WebSub authentication Kim Alvefur <zash@zash.se> parents: 3256 diff changeset	61 Content
1df139b157fb mod_pubsub_post: Add support for WebSub authentication Kim Alvefur <zash@zash.se> parents: 3256 diff changeset	62 Distribution](https://www.w3.org/TR/2018/REC-websub-20180123/#authenticated-content-distribution)
3503 882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	63 authentication is used.
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	64
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	65 ``` {.lua}
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	66 pubsub_post_secrets = {
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	67 princely_musings = "shared secret"
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	68 }
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	69 pubsub_post_default_secret = "default secret"
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	70 ```
3501 1df139b157fb mod_pubsub_post: Add support for WebSub authentication Kim Alvefur <zash@zash.se> parents: 3256 diff changeset	71
3503 882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	72 `pubsub_post_default_secret` is used when trying to publish to a node
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	73 that is not listed in `pubsub_post_secrets`. Otherwise the request
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	74 proceeds with the previously identified actor.
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	75
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	76 ::: {.alert .alert-danger}
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	77 If configured without a secret and a default actor that has permission
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	78 to create nodes the service becomes wide open.
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	79 :::
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	80
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	81 ## Authorization
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	82
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	83 Authorization is handled via pubsub affiliations. Publishing requires an
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	84 affiliation with the _publish_ capability, usually `"publisher"`.
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	85
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	86 ### Setting up affiliations
3256 0992c0398783 mod_pubsub_post/README: Add a heading for affiliation related text Kim Alvefur <zash@zash.se> parents: 3153 diff changeset	87
3152 882f7d5c3ce8 mod_pubsub_post/README: Affiliation management in trunk now Kim Alvefur <zash@zash.se> parents: 3151 diff changeset	88 Prosodys PubSub module supports [setting affiliations via
882f7d5c3ce8 mod_pubsub_post/README: Affiliation management in trunk now Kim Alvefur <zash@zash.se> parents: 3151 diff changeset	89 XMPP](https://xmpp.org/extensions/xep-0060.html#owner-affiliations), in
882f7d5c3ce8 mod_pubsub_post/README: Affiliation management in trunk now Kim Alvefur <zash@zash.se> parents: 3151 diff changeset	90 trunk since [revision
3503 882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	91 384ef9732b81](https://hg.prosody.im/trunk/rev/384ef9732b81), so
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	92 affiliations can be configured with a capable client.
3100 0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	93
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	94 It can however be done from another plugin:
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	95
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	96 ``` {.lua}
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	97 local mod_pubsub = module:depends("pubsub");
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	98 local pubsub = mod_pubsub.service;
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	99
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	100 pubsub:create("princely_musings", true);
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	101 pubsub:set_affiliation("princely_musings", true, "127.0.0.1", "publisher");
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	102 ```

Mercurial > prosody-modules

annotate mod_pubsub_post/README.markdown @ 3866:c0df50ce96f0