Mercurial > prosody-modules

annotate mod_http_muc_kick/README.md @ 5658:7a4a6ded2bd6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_muc_adhoc_bots: Fix unbalanced quote in metadata section
author Kim Alvefur <zash@zash.se>
date Tue, 19 Sep 2023 15:03:01 +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