Mercurial > prosody-modules
annotate mod_component_http/README.markdown @ 5536:96dec7681af8
mod_firewall: Update user marks to store instantly via map store
The original approach was to keep marks in memory only, and persist them at
shutdown. That saves I/O, at the cost of potentially losing marks on an
unclean shutdown.
This change persists marks instantly, which may have some performance overhead
but should be more "correct".
It also splits the marking/unmarking into an event which may be watched or
even fired by other modules.
author | Matthew Wild <mwild1@gmail.com> |
---|---|
date | Thu, 08 Jun 2023 16:20:42 +0100 |
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. |