Changeset

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_component_http/README.markdown	Mon Mar 26 13:49:13 2018 +0100
@@ -0,0 +1,94 @@
+---
+summary: 'Allows implementing a component or bot over HTTP'
+...
+
+Introduction
+============
+
+This module allows you to implement a component that speaks HTTP. Stanzas (such as messages) coming from XMPP are sent to
+a configurable URL as a HTTP POST. If the POST returns a response, that response is returned to the sender over XMPP.
+
+See also mod_post_msg.
+
+Example usage
+-------------
+
+Example echo bot in PHP:
+
+```
+<?php 
+
+// Receive and decode message JSON
+$post_data = file_get_contents('php://input');
+$received = json_decode($post_data)->body;
+
+// Send response
+header('Content-Type: application/json');
+echo json_encode(array(
+        'body' => "Did you say $received?"
+));
+
+?>
+```
+
+Configuration
+-------------
+
+  Option                                 Description
+  ------------------------------------   -------------------------------------------------------------------------------------------------------------------------------------------------
+  component\_post\_url                   The URL that will handle incoming stanzas
+  component\_post\_stanzas               A list of stanza types to forward over HTTP. Defaults to `{ "message" }`.
+
+Details
+-------
+
+Requests
+========
+
+Each received stanza is converted into a JSON object, and submitted to `component_post_url` using a HTTP POST request.
+
+The JSON object always has the following properties:
+
+  Property                    Description
+  --------------------------  ------------
+  to                          The JID that the stanza was sent to (e.g. foobar@your.component.domain)
+  from                        The sender's JID.
+  kind                        The kind of stanza (will always be "message", "presence" or "iq".
+  stanza                      The full XML of the stanza.
+
+Additionally, the JSON object may contain the following properties:
+
+  Property                    Description
+  --------------------------  ------------
+  body                        If the stanza is a message, and it contains a body, this is the string content of the body.
+
+
+Responses
+=========
+
+If you wish to respond to a stanza, you may include a reply when you respond to the HTTP request.
+
+Responses must have a HTTP status 200 (OK), and must set the Conent-Type header to `application/json`.
+
+A response may contain any of the properties of a request. If not supplied, then defaults are chosen.
+
+If 'to' and 'from' are not specified in the response, they are automatically swapped so that the reply is sent to the original sender of the stanza.
+
+If 'kind' is not set, it defaults to 'message', and if 'body' is set, this is automatically added as a message body.
+
+If 'stanza' is set, it overrides all of the above, and the supplied stanza is sent as-is using Prosody's normal routing rules. Note that stanzas
+sent by components must have a 'to' and 'from'.
+
+Presence
+========
+
+By default the module automatically handles presence to provide an always-on component, that automatically accepts subscription requests.
+
+This means that by default presence stanzas are not forwarded to the configured URL. To provide your own presence handling, you can override
+this by adding "presence" to the component\_post\_stanzas option in your config.
+
+
+Compatibility
+-------------
+
+Should work with all versions of Prosody from 0.9 upwards.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_component_http/mod_component_http.lua	Mon Mar 26 13:49:13 2018 +0100
@@ -0,0 +1,102 @@
+local http = require "net.http";
+local json = require "util.json";
+local st = require "util.stanza";
+local xml = require "util.xml";
+local unpack = rawget(_G, "unpack") or table.unpack;
+
+local url = module:get_option_string("component_post_url");
+assert(url, "Missing required config option 'component_post_url'");
+
+local stanza_kinds = module:get_option_set("post_stanza_types", { "message" });
+
+local http_error_map = {
+	[0]   = { "cancel", "remote-server-timeout", "Connection failure" };
+	-- 4xx
+	[400] = { "modify", "bad-request" };
+	[401] = { "auth", "not-authorized" };
+	[402] = { "auth", "forbidden", "Payment required" };
+	[403] = { "auth", "forbidden" };
+	[404] = { "cancel", "item-not-found" };
+	[410] = { "cancel", "gone" };
+	-- 5xx
+	[500] = { "cancel", "internal-server-error" };
+	[501] = { "cancel", "feature-not-implemented" };
+	[502] = { "cancel", "remote-server-timeout", "Bad gateway" };
+	[503] = { "wait", "remote-server-timeout", "Service temporarily unavailable" };
+	[504] = { "wait", "remote-server-timeout", "Gateway timeout" };
+}
+
+local function error_reply(stanza, code)
+	local error = http_error_map[code] or { "cancel", "service-unavailable" };
+	return st.error_reply(stanza, unpack(error, 1, 3));
+end
+
+function handle_stanza(event)
+	local origin, stanza = event.origin, event.stanza;
+	local request_body = json.encode({
+		to = stanza.attr.to;
+		from = stanza.attr.from;
+		kind = stanza.name;
+		body = stanza.name == "message" and stanza:get_child_text("body") or nil;
+		stanza = tostring(stanza);
+	});
+	http.request(url, {
+		body = request_body;
+	}, function (response_text, code, req, response)
+		if stanza.attr.type == "error" then return; end -- Avoid error loops, don't reply to error stanzas		
+		if code == 200 and response_text and response.headers["content-type"] == "application/json" then
+			local response_data = json.decode(response_text);
+			if response_data.stanza then
+				local reply_stanza = xml.parse(response_data.stanza);
+				if reply_stanza then
+					reply_stanza.attr.from, reply_stanza.attr.to = stanza.attr.to, stanza.attr.from;
+					return origin.send(reply_stanza);
+				else
+					module:log("warn", "Unable to parse reply stanza");
+				end
+			else
+				local stanza_kind = response_data.kind or "message";
+				local to = response_data.to or stanza.attr.from;
+				local from = response_data.from or stanza.attr.to;
+				local reply_stanza = st.stanza(stanza_kind, {
+					to = to, from = from;
+					type = response_data.type or (stanza_kind == "message" and "chat") or nil;
+				});
+				if stanza_kind == "message" and response_data.body then
+					reply_stanza:tag("body"):text(tostring(response_data.body)):up();
+				end
+				module:log("debug", "Sending %s", tostring(reply_stanza));
+				return origin.send(reply_stanza);
+			end
+			return;
+		elseif code >= 200 and code <= 299 then
+			return true;
+		else
+			return origin.send(error_reply(stanza, code));
+		end
+	end);
+	return true;
+end
+
+for stanza_kind in stanza_kinds do
+	for _, jid_type in ipairs({ "host", "bare", "full" }) do
+		module:hook(stanza_kind.."/"..jid_type, handle_stanza);
+	end
+end
+
+-- Simple handler for an always-online JID that allows everyone to subscribe to presence
+local function default_presence_handler(event)
+	local origin, stanza = event.origin, event.stanza;
+	module:log("debug", "Handling %s", tostring(stanza));
+	if stanza.attr.type == "probe" then
+		module:send(st.presence({ to = stanza.attr.from, from = stanza.attr.to.."/default" }));
+	elseif stanza.attr.type == "subscribe" then
+		module:send(st.presence({ type = "subscribed", to = stanza.attr.from, from = stanza.attr.to.."/default" }));
+		module:send(st.presence({ to = stanza.attr.from, from = stanza.attr.to.."/default" }));
+	elseif stanza.attr.type == "unsubscribe" then
+		module:send(st.presence({ type = "unavailable", to = stanza.attr.from, from = stanza.attr.to.."/default" }));	
+	end
+	return true;
+end
+
+module:hook("presence/bare", default_presence_handler, -1);