Mercurial > prosody-modules

annotate mod_component_http/README.markdown @ 4918:9d0ec61c70a1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_rest: Catch and coerce errors in echo endpoint This should ensure problems in encode() are reported back
author Kim Alvefur <zash@zash.se>
date Thu, 07 Apr 2022 17:48:08 +0200
parents 1f06a7fe75a8
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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.