Mercurial > prosody-modules
annotate mod_pubsub_post/README.markdown @ 4734:e58ec4b3cf90
mod_rest: Add an anonymous mode
Could be useful for a demo instance.
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Mon, 01 Nov 2021 15:08:21 +0100 |
parents | 6bcccc63b542 |
children | 8d4b91a703af |
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 |
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. |
4636
6bcccc63b542
mod_pubsub_post: fix incorrect claim
Jonas Schäfer <jonas@wielicki.name>
parents:
4552
diff
changeset
|
17 - Other XML is simply published to the item with ID `current`. |
3719
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 | 21 ``` {.bash} |
22 curl http://localhost:5280/pubsub_post/princely_musings \ | |
23 -H "Content-Type: application/json" \ | |
24 --data-binary '{"musing":"To be, or not to be: that is the question"}' | |
25 ``` | |
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>' |
4552
c87181a98f29
mod_pubsub_post: Add support for urlencoded form-data
Kim Alvefur <zash@zash.se>
parents:
3719
diff
changeset
|
34 ``` |
3719
a6db99c1420a
mod_pubsub_post/README: Add an example of curl-ing Atom data
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
35 |
4552
c87181a98f29
mod_pubsub_post: Add support for urlencoded form-data
Kim Alvefur <zash@zash.se>
parents:
3719
diff
changeset
|
36 ## Simple form-data |
c87181a98f29
mod_pubsub_post: Add support for urlencoded form-data
Kim Alvefur <zash@zash.se>
parents:
3719
diff
changeset
|
37 |
c87181a98f29
mod_pubsub_post: Add support for urlencoded form-data
Kim Alvefur <zash@zash.se>
parents:
3719
diff
changeset
|
38 ``` {.bash} |
c87181a98f29
mod_pubsub_post: Add support for urlencoded form-data
Kim Alvefur <zash@zash.se>
parents:
3719
diff
changeset
|
39 curl http://localhost:5280/pubsub_post/princely_musings \ |
c87181a98f29
mod_pubsub_post: Add support for urlencoded form-data
Kim Alvefur <zash@zash.se>
parents:
3719
diff
changeset
|
40 --data musing="To be, or not to be: that is the question" |
3719
a6db99c1420a
mod_pubsub_post/README: Add an example of curl-ing Atom data
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
41 ``` |
3153
e0de1fdbc80a
mod_pubsub_post/README: Describe what happens to different data types
Kim Alvefur <zash@zash.se>
parents:
3152
diff
changeset
|
42 |
3100 | 43 # Configuration |
44 | |
3503
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
45 All settings are optional. |
3100 | 46 |
3503
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
47 ## Actor identification |
3100 | 48 |
3503
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
49 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
|
50 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
|
51 |
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3256
diff
changeset
|
52 ``` {.lua} |
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3256
diff
changeset
|
53 -- Per node secrets |
3503
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
54 pubsub_post_actors = { |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
55 princely_musings = "hamlet@denmark.lit" |
3501
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3256
diff
changeset
|
56 } |
3503
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
57 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
|
58 ``` |
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_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
|
61 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
|
62 of the connection is used. |
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 ## Authentication |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
65 |
3501
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3256
diff
changeset
|
66 [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
|
67 Content |
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3256
diff
changeset
|
68 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
|
69 authentication is used. |
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 ``` {.lua} |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
72 pubsub_post_secrets = { |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
73 princely_musings = "shared secret" |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
74 } |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
75 pubsub_post_default_secret = "default secret" |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
76 ``` |
3501
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3256
diff
changeset
|
77 |
3503
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
78 `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
|
79 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
|
80 proceeds with the previously identified actor. |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
81 |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
82 ::: {.alert .alert-danger} |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
83 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
|
84 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
|
85 ::: |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
86 |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
87 ## Authorization |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
88 |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
89 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
|
90 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
|
91 |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
92 ### 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
|
93 |
3152
882f7d5c3ce8
mod_pubsub_post/README: Affiliation management in trunk now
Kim Alvefur <zash@zash.se>
parents:
3151
diff
changeset
|
94 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
|
95 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
|
96 trunk since [revision |
3503
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3502
diff
changeset
|
97 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
|
98 affiliations can be configured with a capable client. |
3100 | 99 |
100 It can however be done from another plugin: | |
101 | |
102 ``` {.lua} | |
103 local mod_pubsub = module:depends("pubsub"); | |
104 local pubsub = mod_pubsub.service; | |
105 | |
106 pubsub:create("princely_musings", true); | |
107 pubsub:set_affiliation("princely_musings", true, "127.0.0.1", "publisher"); | |
108 ``` |