Mercurial > prosody-modules

comparison mod_http_muc_kick/README.md @ 4642:9fc52ccfb445

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_http_muc_kick: Publish module
author Seve Ferrer <seve@delape.net>
date Tue, 10 Aug 2021 13:27:16 +0200
parents
children
comparison
equal deleted inserted replaced
4641:64fafbeba14d 4642:9fc52ccfb445
1 # Introduction
2
3
4 This module allows kicking users out of MUCs via HTTP.
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.
6
7 This module expects a JSON payload with the following keys:
8 * `nickname` Mandatory. The nickname of the user to be kicked.
9 * `muc` Mandatory. The JID of the muc to kick the user from.
10 * `reason` Optional. A comment explaining the reason of the kick (More details https://xmpp.org/extensions/xep-0045.html#example-91).
11
12 Example:
13 ```
14 {
15 nickname: "Bob",
16 muc: "snuggery@chat.example.org",
17 }
18 ```
19 If the user was kicked successfuly, the module will return a 200 status code.
20 Otherwise, the according status code will be returned in the response, as well as a JSON payload providing an error message.
21 ```
22 {
23 error: "Missing nickname and/or MUC"
24 }
25 ```
26
27 The path this module listens on is `/muc_kick`.
28 Example of a request to kick `Bob` from the `snuggery@chat.example.org` MUC using cURL:
29
30 ```
31 curl --header "Content-Type: application/json" \
32 --request POST \
33 -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
34 --data '{"nickname":"Bob","muc":"snuggery@chat.example.org"}' \
35 http://chat.example.org:5280/muc_kick
36 ```
37
38
39
40 # Configuring
41
42 ## Enabling
43
44 ``` {.lua}
45 Component "chat.example.org" "muc"
46
47 modules_enabled = {
48 "http_muc_kick";
49 }
50
51 http_muc_kick_authorization_header = "Basic YWxhZGRpbjpvcGVuc2VzYW1l" -- Check the Settings section below
52
53 ```
54
55
56 ## Settings
57
58 |Name |Description |Default |
59 |-----|------------|--------|
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 |
61
62 Even though there is no check on whether the Authorization header provided is a valid one,
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.
64