Mercurial > prosody-modules
annotate mod_pubsub_post/README.markdown @ 3512:5fb14ae57b4c
mod_pubsub_github/README: Mark up options as code snippets
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Sun, 31 Mar 2019 16:59:08 +0200 |
parents | 7b1eede1a840 |
children | a6db99c1420a |
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 | 7 # Introduction |
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 | 13 |
14 ``` {.bash} | |
15 curl http://localhost:5280/pubsub_post/princely_musings \ | |
16 -H "Content-Type: application/json" \ | |
17 --data-binary '{"musing":"To be, or not to be: that is the question"}' | |
18 ``` | |
19 | |
3153
e0de1fdbc80a
mod_pubsub_post/README: Describe what happens to different data types
Kim Alvefur <zash@zash.se>
parents:
3152
diff
changeset
|
20 - 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
|
21 - 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
|
22 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
|
23 - 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
|
24 |
3100 | 25 # Configuration |
26 | |
3503
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
27 All settings are optional. |
3100 | 28 |
3503
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
29 ## Actor identification |
3100 | 30 |
3503
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
31 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
|
32 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
|
33 |
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3256
diff
changeset
|
34 ``` {.lua} |
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3256
diff
changeset
|
35 -- Per node secrets |
3503
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
36 pubsub_post_actors = { |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
37 princely_musings = "hamlet@denmark.lit" |
3501
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3256
diff
changeset
|
38 } |
3503
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
39 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
|
40 ``` |
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3256
diff
changeset
|
41 |
3503
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
42 `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
|
43 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
|
44 of the connection is used. |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
45 |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
46 ## Authentication |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
47 |
3501
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3256
diff
changeset
|
48 [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
|
49 Content |
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3256
diff
changeset
|
50 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
|
51 authentication is used. |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
52 |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
53 ``` {.lua} |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
54 pubsub_post_secrets = { |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
55 princely_musings = "shared secret" |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
56 } |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
57 pubsub_post_default_secret = "default secret" |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
58 ``` |
3501
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3256
diff
changeset
|
59 |
3503
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
60 `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
|
61 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
|
62 proceeds with the previously identified actor. |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
63 |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
64 ::: {.alert .alert-danger} |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
65 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
|
66 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
|
67 ::: |
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 |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
70 |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
71 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
|
72 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
|
73 |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
74 ### 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
|
75 |
3152
882f7d5c3ce8
mod_pubsub_post/README: Affiliation management in trunk now
Kim Alvefur <zash@zash.se>
parents:
3151
diff
changeset
|
76 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
|
77 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
|
78 trunk since [revision |
3503
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
79 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
|
80 affiliations can be configured with a capable client. |
3100 | 81 |
82 It can however be done from another plugin: | |
83 | |
84 ``` {.lua} | |
85 local mod_pubsub = module:depends("pubsub"); | |
86 local pubsub = mod_pubsub.service; | |
87 | |
88 pubsub:create("princely_musings", true); | |
89 pubsub:set_affiliation("princely_musings", true, "127.0.0.1", "publisher"); | |
90 ``` |