author | Matthew Wild <mwild1@gmail.com> |
Tue, 27 Mar 2018 11:36:25 +0100 | |
changeset 2962 | 13acce68a89c |
parent 2958 | 1f06a7fe75a8 |
permissions | -rw-r--r-- |
2954
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
1 |
--- |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
2 |
summary: 'Allows implementing a component or bot over HTTP' |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
3 |
... |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
4 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
5 |
Introduction |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
6 |
============ |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
7 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
8 |
This module allows you to implement a component that speaks HTTP. Stanzas (such as messages) coming from XMPP are sent to |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
9 |
a configurable URL as a HTTP POST. If the POST returns a response, that response is returned to the sender over XMPP. |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
10 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
11 |
See also mod_post_msg. |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
12 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
13 |
Example usage |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
14 |
------------- |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
15 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
16 |
Example echo bot in PHP: |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
17 |
|
2958
1f06a7fe75a8
mod_component_http/README: Include language tag in example to enable syntax highlighting in rendered version
Kim Alvefur <zash@zash.se>
parents:
2957
diff
changeset
|
18 |
``` php |
2954
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
19 |
<?php |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
20 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
21 |
// Receive and decode message JSON |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
22 |
$post_data = file_get_contents('php://input'); |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
23 |
$received = json_decode($post_data)->body; |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
24 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
25 |
// Send response |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
26 |
header('Content-Type: application/json'); |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
27 |
echo json_encode(array( |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
28 |
'body' => "Did you say $received?" |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
29 |
)); |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
30 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
31 |
?> |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
32 |
``` |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
33 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
34 |
Configuration |
2955
01ed9eb111d4
mod_component_http: Fix headings in README
Matthew Wild <mwild1@gmail.com>
parents:
2954
diff
changeset
|
35 |
============= |
2954
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
36 |
|
2957
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2955
diff
changeset
|
37 |
The module is quite flexible, but should generally be loaded as a component like this: |
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2955
diff
changeset
|
38 |
|
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2955
diff
changeset
|
39 |
``` |
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2955
diff
changeset
|
40 |
Component "yourservice.example.com" "component_http" |
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2955
diff
changeset
|
41 |
component_post_url = "https://example.com/your-api" |
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2955
diff
changeset
|
42 |
``` |
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2955
diff
changeset
|
43 |
|
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2955
diff
changeset
|
44 |
Such a component would handle traffic for all JIDs with 'yourservice.example.com' as the hostname, such |
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2955
diff
changeset
|
45 |
as 'foobar@yourservice.example.com'. Although this example uses a subdomain, there is no requirement for |
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2955
diff
changeset
|
46 |
the component to use a subdomain. |
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2955
diff
changeset
|
47 |
|
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2955
diff
changeset
|
48 |
Available configuration options are: |
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2955
diff
changeset
|
49 |
|
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2955
diff
changeset
|
50 |
|
2954
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
51 |
Option Description |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
52 |
------------------------------------ ------------------------------------------------------------------------------------------------------------------------------------------------- |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
53 |
component\_post\_url The URL that will handle incoming stanzas |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
54 |
component\_post\_stanzas A list of stanza types to forward over HTTP. Defaults to `{ "message" }`. |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
55 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
56 |
Details |
2955
01ed9eb111d4
mod_component_http: Fix headings in README
Matthew Wild <mwild1@gmail.com>
parents:
2954
diff
changeset
|
57 |
======= |
2954
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
58 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
59 |
Requests |
2955
01ed9eb111d4
mod_component_http: Fix headings in README
Matthew Wild <mwild1@gmail.com>
parents:
2954
diff
changeset
|
60 |
-------- |
2954
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
61 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
62 |
Each received stanza is converted into a JSON object, and submitted to `component_post_url` using a HTTP POST request. |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
63 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
64 |
The JSON object always has the following properties: |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
65 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
66 |
Property Description |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
67 |
-------------------------- ------------ |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
68 |
to The JID that the stanza was sent to (e.g. foobar@your.component.domain) |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
69 |
from The sender's JID. |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
70 |
kind The kind of stanza (will always be "message", "presence" or "iq". |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
71 |
stanza The full XML of the stanza. |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
72 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
73 |
Additionally, the JSON object may contain the following properties: |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
74 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
75 |
Property Description |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
76 |
-------------------------- ------------ |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
77 |
body If the stanza is a message, and it contains a body, this is the string content of the body. |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
78 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
79 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
80 |
Responses |
2955
01ed9eb111d4
mod_component_http: Fix headings in README
Matthew Wild <mwild1@gmail.com>
parents:
2954
diff
changeset
|
81 |
--------- |
2954
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
82 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
83 |
If you wish to respond to a stanza, you may include a reply when you respond to the HTTP request. |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
84 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
85 |
Responses must have a HTTP status 200 (OK), and must set the Conent-Type header to `application/json`. |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
86 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
87 |
A response may contain any of the properties of a request. If not supplied, then defaults are chosen. |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
88 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
89 |
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. |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
90 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
91 |
If 'kind' is not set, it defaults to 'message', and if 'body' is set, this is automatically added as a message body. |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
92 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
93 |
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 |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
94 |
sent by components must have a 'to' and 'from'. |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
95 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
96 |
Presence |
2955
01ed9eb111d4
mod_component_http: Fix headings in README
Matthew Wild <mwild1@gmail.com>
parents:
2954
diff
changeset
|
97 |
-------- |
2954
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
98 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
99 |
By default the module automatically handles presence to provide an always-on component, that automatically accepts subscription requests. |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
100 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
101 |
This means that by default presence stanzas are not forwarded to the configured URL. To provide your own presence handling, you can override |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
102 |
this by adding "presence" to the component\_post\_stanzas option in your config. |
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
103 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
104 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
105 |
Compatibility |
2955
01ed9eb111d4
mod_component_http: Fix headings in README
Matthew Wild <mwild1@gmail.com>
parents:
2954
diff
changeset
|
106 |
============= |
2954
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
107 |
|
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
108 |
Should work with all versions of Prosody from 0.9 upwards. |