prosody-modules
fe081789f7b5
mod_pubsub_post/README.md

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Comparison

mod_pubsub_post/README.md @ 6003:fe081789f7b5

All community modules: Unify file extention of Markdown files to .md
author Menel <menel@snikket.de>
date Tue, 22 Oct 2024 10:26:01 +0200
parent 4961:mod_pubsub_post/README.markdown@18774cc621d6
comparison
equal deleted inserted replaced
6002:5a65a632d5b9 6003:fe081789f7b5
1 ---
2 labels:
3 - 'Stage-Stable'
4 summary: Publish to PubSub nodes from via HTTP POST/WebHooks
5 ---
6
7 # Introduction
8
9 This module is a fairly generic WebHook receiver that lets you easily
10 publish data to PubSub using a HTTP POST request. The payload can be
11 Atom feeds, arbitrary XML, or arbitrary JSON. The type should be
12 indicated via the `Content-Type` header.
13
14 - JSON data is wrapped in a [XEP-0335] container.
15 - An Atom feed may have many `<entry>` and each one is published as
16 its own PubSub item.
17 - Other XML is simply published to the item with ID `current`.
18
19 ## JSON example
20
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
27 ## Atom example
28
29 ``` {.bash}
30 curl http://localhost:5280/pubsub_post/princely_musings \
31 -H "Content-Type: application/xml" \
32 --data-binary '<feed xmlns="http://www.w3.org/2005/Atom">
33 <entry><title>Hello</title></entry></feed>'
34 ```
35
36 ## Simple form-data
37
38 ``` {.bash}
39 curl http://localhost:5280/pubsub_post/princely_musings \
40 --data musing="To be, or not to be: that is the question"
41 ```
42
43 # Configuration
44
45 All settings are optional.
46
47 ## Actor identification
48
49 First we have to figure out who is making the request.
50 This is configured on a per-node basis like this:
51
52 ``` {.lua}
53 -- Per node secrets
54 pubsub_post_actors = {
55 princely_musings = "hamlet@denmark.lit"
56 }
57 pubsub_post_default_actor = "nobody@nowhere.invalid"
58 ```
59
60 `pubsub_post_default_actor` is used when trying to publish to a node
61 that is not listed in `pubsub_post_actors`. Otherwise the IP address
62 of the connection is used.
63
64 ## Authentication
65
66 [WebSub](https://www.w3.org/TR/2018/REC-websub-20180123/) [Authenticated
67 Content
68 Distribution](https://www.w3.org/TR/2018/REC-websub-20180123/#authenticated-content-distribution)
69 authentication is used.
70
71 ``` {.lua}
72 pubsub_post_secrets = {
73 princely_musings = "shared secret"
74 }
75 pubsub_post_default_secret = "default secret"
76 ```
77
78 `pubsub_post_default_secret` is used when trying to publish to a node
79 that is not listed in `pubsub_post_secrets`. Otherwise the request
80 proceeds with the previously identified actor.
81
82 ::: {.alert .alert-danger}
83 If configured without a secret and a default actor that has permission
84 to create nodes the service becomes wide open.
85 :::
86
87 ## Authorization
88
89 Authorization is handled via pubsub affiliations. Publishing requires an
90 affiliation with the _publish_ capability, usually `"publisher"`.
91
92 ### Setting up affiliations
93
94 Prosodys PubSub module supports [setting affiliations via
95 XMPP](https://xmpp.org/extensions/xep-0060.html#owner-affiliations),
96 since 0.11.0, so affiliations can be configured with a capable client.
97
98 It can however be done from another plugin:
99
100 ``` {.lua}
101 local mod_pubsub = module:depends("pubsub");
102 local pubsub = mod_pubsub.service;
103
104 pubsub:create("princely_musings", true);
105 pubsub:set_affiliation("princely_musings", true, "127.0.0.1", "publisher");
106 ```
107
108 ## Data mappings
109
110 The datamapper library added in 0.12.0 allows posting JSON and having it
111 converted to XML based on a special JSON Schema.
112
113 ``` json
114 {
115 "properties" : {
116 "content" : {
117 "type" : "string"
118 },
119 "title" : {
120 "type" : "string"
121 }
122 },
123 "type" : "object",
124 "xml" : {
125 "name" : "musings",
126 "namespace" : "urn:example:princely"
127 }
128 }
129 ```
130
131 And in the Prosody config file:
132
133 ``` lua
134 pubsub_post_mappings = {
135 princely_musings = "musings.json";
136 }
137 ```
138
139 Then, POSTing a JSON payload like
140
141 ``` json
142 {
143 "content" : "To be, or not to be: that is the question",
144 "title" : "Soliloquy"
145 }
146 ```
147
148 results in a payload like
149
150 ``` xml
151 <musings xmlns="urn:example:princely">
152 <title>Soliloquy</title>
153 <content>To be, or not to be: that is the question</content>
154 </musings>
155 ```
156
157 being published to the node.