annotate mod_post_msg/README.markdown @ 5119:048e339706ba

mod_rest: Remove manual reference expansion in schema This hack was originally added to reduce the number of definitions of common attributes (type, to, from etc) and payloads (e.g. delay). This predated pointers and references, and until now was needed because parsing picked out the correct stanza kind from the schema, which broke internal references. Removing this hack paves the way for allowing the schema to be configured or customized more easily.
author Kim Alvefur <zash@zash.se>
date Tue, 20 Dec 2022 21:48:28 +0100
parents 5e8b54deeb30
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
1 ---
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
2 summary: 'Receives HTTP POST request, parses it and relays it into XMPP.'
2983
fa3665b7602f mod_post_msg/README: Normalize markdown syntax
Kim Alvefur <zash@zash.se>
parents: 2982
diff changeset
3 ---
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
4
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
5 Introduction
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6 ============
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
7
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
8 Sometimes it's useful to have different interfaces to access XMPP.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9
2985
7467509abdbb mod_post_msg/README: Update Introduction text
Kim Alvefur <zash@zash.se>
parents: 2984
diff changeset
10 This module allows sending XMPP
7467509abdbb mod_post_msg/README: Update Introduction text
Kim Alvefur <zash@zash.se>
parents: 2984
diff changeset
11 [`<message>`](https://xmpp.org/rfcs/rfc6121.html#message) stanzas via a
7467509abdbb mod_post_msg/README: Update Introduction text
Kim Alvefur <zash@zash.se>
parents: 2984
diff changeset
12 simple HTTP API.
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
14 Example usage
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
15 -------------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
16
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
17 curl http://example.com:5280/msg/user -u me@example.com:mypassword -H "Content-Type: text/plain" -d "Server@host has just crashed!"
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
18
2983
fa3665b7602f mod_post_msg/README: Normalize markdown syntax
Kim Alvefur <zash@zash.se>
parents: 2982
diff changeset
19 This would send a message to user\@example.com from me\@example.com
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
20
2984
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
21 Details
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
22 =======
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
23
2987
2af0be50b287 mod_post_msg/README: Describe the URL format
Kim Alvefur <zash@zash.se>
parents: 2986
diff changeset
24 URL format
2af0be50b287 mod_post_msg/README: Describe the URL format
Kim Alvefur <zash@zash.se>
parents: 2986
diff changeset
25 ----------
2af0be50b287 mod_post_msg/README: Describe the URL format
Kim Alvefur <zash@zash.se>
parents: 2986
diff changeset
26
2af0be50b287 mod_post_msg/README: Describe the URL format
Kim Alvefur <zash@zash.se>
parents: 2986
diff changeset
27 /msg/ [recipient [@host] ].
2af0be50b287 mod_post_msg/README: Describe the URL format
Kim Alvefur <zash@zash.se>
parents: 2986
diff changeset
28
2af0be50b287 mod_post_msg/README: Describe the URL format
Kim Alvefur <zash@zash.se>
parents: 2986
diff changeset
29 The base URL defaults to `/msg`. This can be configured via Prosodys
2af0be50b287 mod_post_msg/README: Describe the URL format
Kim Alvefur <zash@zash.se>
parents: 2986
diff changeset
30 [HTTP path settings][doc:http].
2af0be50b287 mod_post_msg/README: Describe the URL format
Kim Alvefur <zash@zash.se>
parents: 2986
diff changeset
31
2988
3cc78e6a8758 mod_post_msg/README: Document how authentication is performed
Kim Alvefur <zash@zash.se>
parents: 2987
diff changeset
32 Authentication
3cc78e6a8758 mod_post_msg/README: Document how authentication is performed
Kim Alvefur <zash@zash.se>
parents: 2987
diff changeset
33 --------------
3cc78e6a8758 mod_post_msg/README: Document how authentication is performed
Kim Alvefur <zash@zash.se>
parents: 2987
diff changeset
34
3cc78e6a8758 mod_post_msg/README: Document how authentication is performed
Kim Alvefur <zash@zash.se>
parents: 2987
diff changeset
35 Authentication is done by HTTP Basic.
3cc78e6a8758 mod_post_msg/README: Document how authentication is performed
Kim Alvefur <zash@zash.se>
parents: 2987
diff changeset
36
3cc78e6a8758 mod_post_msg/README: Document how authentication is performed
Kim Alvefur <zash@zash.se>
parents: 2987
diff changeset
37 Authentication: Basic BASE64( "username@virtualhost:password" )
3cc78e6a8758 mod_post_msg/README: Document how authentication is performed
Kim Alvefur <zash@zash.se>
parents: 2987
diff changeset
38
2984
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
39 Payload formats
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
40 ---------------
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
41
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
42 Supported formats are:
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
43
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
44 `text/plain`
2986
e85cf5a443e2 mod_post_msg/README: Clarify 'body' fields
Kim Alvefur <zash@zash.se>
parents: 2985
diff changeset
45 : The HTTP body is used as plain text message payload, in the `<body>`
e85cf5a443e2 mod_post_msg/README: Clarify 'body' fields
Kim Alvefur <zash@zash.se>
parents: 2985
diff changeset
46 element.
2984
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
47
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
48 `application/x-www-form-urlencoded`
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
49 : Allows more fields to be specified.
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
50
2989
926aaaeb0d21 mod_post_msg: Add support for a JSON based format similar to what mod_component_http uses
Kim Alvefur <zash@zash.se>
parents: 2988
diff changeset
51 `application/json`
926aaaeb0d21 mod_post_msg: Add support for a JSON based format similar to what mod_component_http uses
Kim Alvefur <zash@zash.se>
parents: 2988
diff changeset
52 : Similar to form data.
926aaaeb0d21 mod_post_msg: Add support for a JSON based format similar to what mod_component_http uses
Kim Alvefur <zash@zash.se>
parents: 2988
diff changeset
53
926aaaeb0d21 mod_post_msg: Add support for a JSON based format similar to what mod_component_http uses
Kim Alvefur <zash@zash.se>
parents: 2988
diff changeset
54 Which one is selected via the `Content-Type` HTTP header.
926aaaeb0d21 mod_post_msg: Add support for a JSON based format similar to what mod_component_http uses
Kim Alvefur <zash@zash.se>
parents: 2988
diff changeset
55
2984
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
56 ### Data fields
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
57
2989
926aaaeb0d21 mod_post_msg: Add support for a JSON based format similar to what mod_component_http uses
Kim Alvefur <zash@zash.se>
parents: 2988
diff changeset
58 The form data and JSON formats allow the following fields:
2984
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
59
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
60 `to`
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
61 : Can be used instead of having the receiver in the URL.
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
62
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
63 `type`
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
64 : [Message type.](https://xmpp.org/rfcs/rfc6121.html#message-syntax-type)
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
65
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
66 `body`
2986
e85cf5a443e2 mod_post_msg/README: Clarify 'body' fields
Kim Alvefur <zash@zash.se>
parents: 2985
diff changeset
67 : Plain text message payload which goes in the `<body>` element.
2984
1e7d221bba8d mod_post_msg/README: Document the payload formats
Kim Alvefur <zash@zash.se>
parents: 2983
diff changeset
68
2982
ae7ca7bc9c9b mod_post_msg/README: Reword about borrowing
Kim Alvefur <zash@zash.se>
parents: 2981
diff changeset
69 Acknowledgements
4240
455ae6156f5c mod_post_msg: Tweak header level
Kim Alvefur <zash@zash.se>
parents: 2989
diff changeset
70 ================
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
71
2982
ae7ca7bc9c9b mod_post_msg/README: Reword about borrowing
Kim Alvefur <zash@zash.se>
parents: 2981
diff changeset
72 Some code originally borrowed from mod\_webpresence
4241
5e8b54deeb30 mod_post_msg: Advertise mod_rest, the spiritual successor
Kim Alvefur <zash@zash.se>
parents: 4240
diff changeset
73
5e8b54deeb30 mod_post_msg: Advertise mod_rest, the spiritual successor
Kim Alvefur <zash@zash.se>
parents: 4240
diff changeset
74 See also
5e8b54deeb30 mod_post_msg: Advertise mod_rest, the spiritual successor
Kim Alvefur <zash@zash.se>
parents: 4240
diff changeset
75 ========
5e8b54deeb30 mod_post_msg: Advertise mod_rest, the spiritual successor
Kim Alvefur <zash@zash.se>
parents: 4240
diff changeset
76
5e8b54deeb30 mod_post_msg: Advertise mod_rest, the spiritual successor
Kim Alvefur <zash@zash.se>
parents: 4240
diff changeset
77 [mod_rest] is a more advanced way to send messages and more via HTTP,
5e8b54deeb30 mod_post_msg: Advertise mod_rest, the spiritual successor
Kim Alvefur <zash@zash.se>
parents: 4240
diff changeset
78 with a very similar API.
5e8b54deeb30 mod_post_msg: Advertise mod_rest, the spiritual successor
Kim Alvefur <zash@zash.se>
parents: 4240
diff changeset
79