prosody-modules: mod_component_http/README.markdown annotate

annotate mod_component_http/README.markdown @ 4976:75b6e5df65f9

various: Improve error reporting if missing file server module on 0.12 If there is some error loading net.http.files then it would be swallowed by the pcall and then it would proceed to trying mod_http_files, which might cause unexpected behavior on 0.12 Ref #1765

author	Kim Alvefur <zash@zash.se>
date	Mon, 18 Jul 2022 22:47:54 +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.

Mercurial > prosody-modules

annotate mod_component_http/README.markdown @ 4976:75b6e5df65f9