annotate mod_pubsub_post/README.md @ 3148:8c7b8b2c3237

mod_slack_webhooks: Add a special webhook target for debugging
author Kim Alvefur <zash@zash.se>
date Sun, 03 Jun 2018 02:18:02 +0200
parents 0422fb55cc37
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3100
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
1 # Introduction
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
2
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
3 Lets you easily publish data to PubSub using a HTTP POST request. The
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
4 payload can be Atom feeds, arbitrary XML, or arbitrary JSON. The type
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
5 should be indicated via the `Content-Type` header.
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
7 ``` {.bash}
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
8 curl http://localhost:5280/pubsub_post/princely_musings \
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9 -H "Content-Type: application/json" \
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
10 --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
11 ```
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
12
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13 # Configuration
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
14
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
15 ## Authentication
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 Authentication can be handled in two different ways.
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
18
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
19 ### None
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
20
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
21 ``` {.lua}
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
22 pubsub_post_actor = "superuser"
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
23 ```
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
24
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
25 The module uses an internal actor that has all privileges and can always
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
26 do everything. It is strongly suggested that you do not expose this to
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
27 the Internet. *Maybe* it shouldn't be the default...
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
28
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
29 ### IP
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
30
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
31 ``` {.lua}
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
32 pubsub_post_actor = "request.ip"
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
33 ```
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
34
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
35 Uses the IP address from the HTTP request as actor, which means this
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
36 pseudo-JID must be given a 'publisher' affiliation. This should work
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
37 nicely with the `autocreate_on_publish` setting, where the first actor
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
38 to attempt to publish to a non-existant node becomes owner of it, which
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
39 includes publishing rights.
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
40
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
41 Prosodys PubSub module does not currently support [setting affiliations
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
42 via XMPP](https://xmpp.org/extensions/xep-0060.html#owner-affiliations),
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
43 but this is planned.
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
44
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
45 It can however be done from another plugin:
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
46
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
47 ``` {.lua}
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
48 local mod_pubsub = module:depends("pubsub");
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
49 local pubsub = mod_pubsub.service;
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
50
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
51 pubsub:create("princely_musings", true);
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
52 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
53 ```