Mercurial > prosody-modules
annotate mod_component_http/README.markdown @ 4090:e77122025080
mod_easy_invite: Add a touch of dependency info
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Thu, 10 Sep 2020 17:54:39 +0200 |
parents | 1f06a7fe75a8 |
children |
rev | line source |
---|---|
2950
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 |
2954
1f06a7fe75a8
mod_component_http/README: Include language tag in example to enable syntax highlighting in rendered version
Kim Alvefur <zash@zash.se>
parents:
2953
diff
changeset
|
18 ``` php |
2950
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 |
2951
01ed9eb111d4
mod_component_http: Fix headings in README
Matthew Wild <mwild1@gmail.com>
parents:
2950
diff
changeset
|
35 ============= |
2950
18e6d437003f
mod_component_http: Allow implementing a component over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
36 |
2953
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2951
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:
2951
diff
changeset
|
38 |
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2951
diff
changeset
|
39 ``` |
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2951
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:
2951
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:
2951
diff
changeset
|
42 ``` |
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2951
diff
changeset
|
43 |
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2951
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:
2951
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:
2951
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:
2951
diff
changeset
|
47 |
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2951
diff
changeset
|
48 Available configuration options are: |
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2951
diff
changeset
|
49 |
0092bcceda0a
mod_component_http: Update README to include config snippet example
Matthew Wild <mwild1@gmail.com>
parents:
2951
diff
changeset
|
50 |
2950
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 |
2951
01ed9eb111d4
mod_component_http: Fix headings in README
Matthew Wild <mwild1@gmail.com>
parents:
2950
diff
changeset
|
57 ======= |
2950
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 |
2951
01ed9eb111d4
mod_component_http: Fix headings in README
Matthew Wild <mwild1@gmail.com>
parents:
2950
diff
changeset
|
60 -------- |
2950
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 |
2951
01ed9eb111d4
mod_component_http: Fix headings in README
Matthew Wild <mwild1@gmail.com>
parents:
2950
diff
changeset
|
81 --------- |
2950
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 |
2951
01ed9eb111d4
mod_component_http: Fix headings in README
Matthew Wild <mwild1@gmail.com>
parents:
2950
diff
changeset
|
97 -------- |
2950
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 |
2951
01ed9eb111d4
mod_component_http: Fix headings in README
Matthew Wild <mwild1@gmail.com>
parents:
2950
diff
changeset
|
106 ============= |
2950
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. |