Mercurial > prosody-modules

annotate mod_pubsub_post/README.markdown @ 3505:106b4ae4469b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_pubsub_post/README: Mention use as a webhook receiver
author Kim Alvefur <zash@zash.se>
date Sat, 30 Mar 2019 23:33:58 +0100
parents 882180b459a0
children 7b1eede1a840
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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 ---
106b4ae4469b mod_pubsub_post/README: Mention use as a webhook receiver
Kim Alvefur <zash@zash.se>
parents: 3503
diff changeset
2 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
3 ---
106b4ae4469b mod_pubsub_post/README: Mention use as a webhook receiver
Kim Alvefur <zash@zash.se>
parents: 3503
diff changeset
4
3100
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
5 # Introduction
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6
3505
106b4ae4469b mod_pubsub_post/README: Mention use as a webhook receiver
Kim Alvefur <zash@zash.se>
parents: 3503
diff changeset
7 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
8 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
9 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
10 indicated via the `Content-Type` header.
3100
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
11
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
12 ``` {.bash}
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13 curl http://localhost:5280/pubsub_post/princely_musings \
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
14 -H "Content-Type: application/json" \
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
15 --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
16 ```
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
17
3153
e0de1fdbc80a mod_pubsub_post/README: Describe what happens to different data types
Kim Alvefur <zash@zash.se>
parents: 3152
diff changeset
18 - JSON data is wrapped in a [XEP-0335] container.
e0de1fdbc80a mod_pubsub_post/README: Describe what happens to different data types
Kim Alvefur <zash@zash.se>
parents: 3152
diff changeset
19 - An Atom feed may have many `<entry>` and each one is published as
e0de1fdbc80a mod_pubsub_post/README: Describe what happens to different data types
Kim Alvefur <zash@zash.se>
parents: 3152
diff changeset
20 its own PubSub item.
e0de1fdbc80a mod_pubsub_post/README: Describe what happens to different data types
Kim Alvefur <zash@zash.se>
parents: 3152
diff changeset
21 - Other XML is simply published to a randomly named item as-is.
e0de1fdbc80a mod_pubsub_post/README: Describe what happens to different data types
Kim Alvefur <zash@zash.se>
parents: 3152
diff changeset
22
3100
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
23 # Configuration
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
24
3503
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
25 All settings are optional.
3100
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
26
3503
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
27 ## Actor identification
3100
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
28
3503
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
29 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
30 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
31
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
32 ``` {.lua}
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
33 -- Per node secrets
3503
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
34 pubsub_post_actors = {
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
35 princely_musings = "hamlet@denmark.lit"
3501
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
36 }
3503
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
37 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
38 ```
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
39
3503
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
40 `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
41 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
42 of the connection is used.
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
43
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
44 ## Authentication
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
45
3501
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
46 [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
47 Content
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
48 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
49 authentication is used.
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
50
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
51 ``` {.lua}
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
52 pubsub_post_secrets = {
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
53 princely_musings = "shared secret"
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
54 }
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
55 pubsub_post_default_secret = "default secret"
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
56 ```
3501
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
57
3503
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
58 `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
59 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
60 proceeds with the previously identified actor.
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
61
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
62 ::: {.alert .alert-danger}
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
63 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
64 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
65 :::
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
66
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
67 ## Authorization
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 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
70 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
71
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
72 ### 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
73
3152
882f7d5c3ce8 mod_pubsub_post/README: Affiliation management in trunk now
Kim Alvefur <zash@zash.se>
parents: 3151
diff changeset
74 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
75 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
76 trunk since [revision
3503
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents: 3502
diff changeset
77 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
78 affiliations can be configured with a capable client.
3100
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
79
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
80 It can however be done from another plugin:
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
81
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
82 ``` {.lua}
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
83 local mod_pubsub = module:depends("pubsub");
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
84 local pubsub = mod_pubsub.service;
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
85
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
86 pubsub:create("princely_musings", true);
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
87 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
88 ```