Mercurial > prosody-modules

annotate mod_http_muc_kick/README.md @ 4942:e7b9bc629ecc

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_rest: Add special handling to catch MAM results from remote hosts Makes MAM queries to remote hosts works. As the comment says, MAM results from users' local archives or local MUCs are returned via origin.send() which is provided in the event and thus already worked. Results from remote hosts go via normal stanza routing and events, which need this extra handling to catch. This pattern of iq-set, message+, iq-result is generally limited to MAM. Closest similar thing might be MUC join, but to really handle that you would need the webhook callback mechanism.
author Kim Alvefur <zash@zash.se>
date Mon, 16 May 2022 19:47:09 +0200
parents 9fc52ccfb445
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4642
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
1 # Introduction
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
2
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
3
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
4 This module allows kicking users out of MUCs via HTTP.
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
5 It can be used in combination with [mod_muc_http_auth](https://modules.prosody.im/mod_muc_http_auth.html) as a complement to externalize MUC access.
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
6
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
7 This module expects a JSON payload with the following keys:
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
8 * `nickname` Mandatory. The nickname of the user to be kicked.
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
9 * `muc` Mandatory. The JID of the muc to kick the user from.
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
10 * `reason` Optional. A comment explaining the reason of the kick (More details https://xmpp.org/extensions/xep-0045.html#example-91).
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
11
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
12 Example:
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
13 ```
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
14 {
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
15 nickname: "Bob",
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
16 muc: "snuggery@chat.example.org",
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
17 }
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
18 ```
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
19 If the user was kicked successfuly, the module will return a 200 status code.
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
20 Otherwise, the according status code will be returned in the response, as well as a JSON payload providing an error message.
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
21 ```
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
22 {
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
23 error: "Missing nickname and/or MUC"
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
24 }
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
25 ```
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
26
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
27 The path this module listens on is `/muc_kick`.
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
28 Example of a request to kick `Bob` from the `snuggery@chat.example.org` MUC using cURL:
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
29
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
30 ```
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
31 curl --header "Content-Type: application/json" \
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
32 --request POST \
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
33 -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
34 --data '{"nickname":"Bob","muc":"snuggery@chat.example.org"}' \
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
35 http://chat.example.org:5280/muc_kick
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
36 ```
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
37
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
38
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
39
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
40 # Configuring
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
41
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
42 ## Enabling
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
43
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
44 ``` {.lua}
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
45 Component "chat.example.org" "muc"
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
46
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
47 modules_enabled = {
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
48 "http_muc_kick";
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
49 }
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
50
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
51 http_muc_kick_authorization_header = "Basic YWxhZGRpbjpvcGVuc2VzYW1l" -- Check the Settings section below
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
52
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
53 ```
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
54
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
55
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
56 ## Settings
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
57
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
58 |Name |Description |Default |
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
59 |-----|------------|--------|
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
60 |http_muc_kick_authorization_header| Value of the Authorization header expected by every request when trying to kick a user. Example: `Basic dXNlcm5hbWU6cGFzc3dvcmQ=`| nil |
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
61
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
62 Even though there is no check on whether the Authorization header provided is a valid one,
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
63 please be aware that if `http_muc_kick_authorization_header` is nil, the module will not load as a reminder that some authorization should be enforced for this module.
9fc52ccfb445 mod_http_muc_kick: Publish module
Seve Ferrer <seve@delape.net>
parents:
diff changeset
64