# HG changeset patch
# User Kim Alvefur <zash@zash.se>
# Date 1528027935 -7200
# Node ID 0422fb55cc373c1b7b420f1002eaeb2cb5957e40
# Parent  c88f91626e078378f22461f017784700e1d26a40
mod_pubsub_post: Add a README

diff -r c88f91626e07 -r 0422fb55cc37 mod_pubsub_post/README.md
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_pubsub_post/README.md	Sun Jun 03 14:12:15 2018 +0200
@@ -0,0 +1,53 @@
+# Introduction
+
+Lets you easily publish data to PubSub using a HTTP POST request. The
+payload can be Atom feeds, arbitrary XML, or arbitrary JSON. The type
+should be indicated via the `Content-Type` header.
+
+``` {.bash}
+curl http://localhost:5280/pubsub_post/princely_musings \
+    -H "Content-Type: application/json" \
+    --data-binary '{"musing":"To be, or not to be: that is the question"}'
+```
+
+# Configuration
+
+## Authentication
+
+Authentication can be handled in two different ways.
+
+### None
+
+``` {.lua}
+pubsub_post_actor = "superuser"
+```
+
+The module uses an internal actor that has all privileges and can always
+do everything. It is strongly suggested that you do not expose this to
+the Internet. *Maybe* it shouldn't be the default...
+
+### IP
+
+``` {.lua}
+pubsub_post_actor = "request.ip"
+```
+
+Uses the IP address from the HTTP request as actor, which means this
+pseudo-JID must be given a 'publisher' affiliation. This should work
+nicely with the `autocreate_on_publish` setting, where the first actor
+to attempt to publish to a non-existant node becomes owner of it, which
+includes publishing rights.
+
+Prosodys PubSub module does not currently support [setting affiliations
+via XMPP](https://xmpp.org/extensions/xep-0060.html#owner-affiliations),
+but this is planned.
+
+It can however be done from another plugin:
+
+``` {.lua}
+local mod_pubsub = module:depends("pubsub");
+local pubsub = mod_pubsub.service;
+
+pubsub:create("princely_musings", true);
+pubsub:set_affiliation("princely_musings", true, "127.0.0.1", "publisher");
+```