Mercurial > prosody-modules

annotate mod_muc_members_json/README.md @ 5668:ecfd7aece33b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_measure_modules: Report module statuses via OpenMetrics Someone in the chat asked about a health check endpoint, which reminded me of mod_http_status, which provides access to module statuses with full details. After that, this idea came about, which seems natural. As noted in the README, it could be used to monitor that critical modules are in fact loaded correctly. As more modules use the status API, the more useful this module and mod_http_status becomes.
author Kim Alvefur <zash@zash.se>
date Fri, 06 Oct 2023 18:34:39 +0200
parents 1cae6133e315
children aa94d5bb6b10
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5586
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
1 ---
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
2 labels:
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
3 - 'Stage-Beta'
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
4 summary: 'Import MUC membership info from a JSON file'
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
5 ...
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
6
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
7 Introduction
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
8 ============
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
9
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
10 This module allows you to import MUC membership information from an external
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
11 URL in JSON format.
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
12
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
13 Details
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
14 =======
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
15
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
16 If you have an organization or community and lots of members and/or channels,
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
17 it can be frustrating to manage MUC affiliations manually. This module will
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
18 fetch a JSON file from a configured URL, and use that to automatically set the
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19 MUC affiliations.
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
20
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
21 It also supports hats/badges.
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
22
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
23 Configuration
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
24 =============
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
25
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
26 Add the module to the MUC host (not the global modules\_enabled):
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
27
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
28 Component "conference.example.com" "muc"
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
29 modules_enabled = { "muc_members_json" }
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
30
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
31 You can define (globally or per-MUC component) the following options:
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
32
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
33 Name Description
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
34 --------------------- --------------------------------------------------
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
35 muc_members_json_url The URL to the JSON file describing memberships
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
36 muc_members_json_mucs The MUCs to manage, and their associated configuration
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
37
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
38 The `muc_members_json_mucs` setting determines which rooms will be managed by
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
39 the plugin, and how to map roles to hats (if desired).
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
40
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
41 ```
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
42 muc_members_json_mucs = {
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
43 myroom = {
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
44 member_hat = {
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
45 id = "urn:uuid:6a1b143a-1c5c-11ee-80aa-4ff1ce4867dc";
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
46 title = "Cool Member";
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
47 };
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
48 };
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
49 }
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
50 ```
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
51
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
52 JSON format
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
53 ===========
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
54
5655
1cae6133e315 mod_muc_members_json: Demonstrate support for more than one JID per list
Kim Alvefur <zash@zash.se>
parents: 5654
diff changeset
55 ``` json
5586
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
56 {
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
57 "members": [
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
58 {
5655
1cae6133e315 mod_muc_members_json: Demonstrate support for more than one JID per list
Kim Alvefur <zash@zash.se>
parents: 5654
diff changeset
59 "jids": [
1cae6133e315 mod_muc_members_json: Demonstrate support for more than one JID per list
Kim Alvefur <zash@zash.se>
parents: 5654
diff changeset
60 "user@example.com",
1cae6133e315 mod_muc_members_json: Demonstrate support for more than one JID per list
Kim Alvefur <zash@zash.se>
parents: 5654
diff changeset
61 "user2@example.com"
1cae6133e315 mod_muc_members_json: Demonstrate support for more than one JID per list
Kim Alvefur <zash@zash.se>
parents: 5654
diff changeset
62 ]
5586
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
63 },
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
64 {
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
65 "jids": ["user3@example.com"],
5654
31e56562f9bd mod_muc_members_json: Fix invalid JSON in README
Kim Alvefur <zash@zash.se>
parents: 5586
diff changeset
66 "roles": ["janitor"]
5586
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
67 }
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
68 ]
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
69 }
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
70 ```
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
71
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
72 Each member must have a `jids` field, and optionally a `roles` field.
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
73
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
74 Compatibility
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
75 =============
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
76
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
77 ------- ------------------
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
78 trunk Works
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
79 0.12 Works
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
80 ------- ------------------
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
81