Mercurial > prosody-modules

annotate mod_http_muc_kick/README.md @ 5536:96dec7681af8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_firewall: Update user marks to store instantly via map store The original approach was to keep marks in memory only, and persist them at shutdown. That saves I/O, at the cost of potentially losing marks on an unclean shutdown. This change persists marks instantly, which may have some performance overhead but should be more "correct". It also splits the marking/unmarking into an event which may be watched or even fired by other modules.
author Matthew Wild <mwild1@gmail.com>
date Thu, 08 Jun 2023 16:20:42 +0100
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