Mercurial > prosody-modules

annotate mod_muc_limits/README.markdown @ 5601:6680a1f53353

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_muc_limits: Reduce cost of multi-line messages, make configurable Typing a 5-line message preceded by a few chat states would have hit the default limit.
author Kim Alvefur <zash@zash.se>
date Sat, 15 Jul 2023 09:09:41 +0200
parents d52cc18f0aa8
children bae2f4830a93
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
1 ---
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
2 labels:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
3 - 'Stage-Beta'
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
4 summary: 'Impose rate-limits on a MUC'
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
5 ...
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
7 Introduction
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
8 ============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
10 This module allows you to control the maximum rate of 'events' in a MUC
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
11 room. This makes it useful to prevent room floods (whether malicious or
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
12 accidental).
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
14 Details
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
15 =======
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
16
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
17 This module limits the following events:
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
18
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
19 - Room joins
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
20 - Nick changes
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
21 - Status changes
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
22 - Messages (including private messages)
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
23
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
24 The limit is for the room as a whole, not individual occupants in the
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
25 room. Users with an affiliation (members, admins and owners) are not
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
26 limited.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
27
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
28 Configuration
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
29 =============
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
30
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
31 Add the module to the MUC host (not the global modules\_enabled):
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
32
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
33 Component "conference.example.com" "muc"
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
34 modules_enabled = { "muc_limits" }
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
35
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
36 You can define (globally or per-MUC component) the following options:
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
37
5601
6680a1f53353 mod_muc_limits: Reduce cost of multi-line messages, make configurable
Kim Alvefur <zash@zash.se>
parents: 5567
diff changeset
38 Name Default value Description
6680a1f53353 mod_muc_limits: Reduce cost of multi-line messages, make configurable
Kim Alvefur <zash@zash.se>
parents: 5567
diff changeset
39 --------------------------- --------------- ----------------------------------------------------------
6680a1f53353 mod_muc_limits: Reduce cost of multi-line messages, make configurable
Kim Alvefur <zash@zash.se>
parents: 5567
diff changeset
40 muc_event_rate 0.5 The maximum number of events per second.
6680a1f53353 mod_muc_limits: Reduce cost of multi-line messages, make configurable
Kim Alvefur <zash@zash.se>
parents: 5567
diff changeset
41 muc_burst_factor 6 Allow temporary bursts of this multiple.
6680a1f53353 mod_muc_limits: Reduce cost of multi-line messages, make configurable
Kim Alvefur <zash@zash.se>
parents: 5567
diff changeset
42 muc_max_nick_length 23 The maximum allowed length of user nicknames
6680a1f53353 mod_muc_limits: Reduce cost of multi-line messages, make configurable
Kim Alvefur <zash@zash.se>
parents: 5567
diff changeset
43 muc_max_char_count 5664 The maximum allowed number of bytes in a message
6680a1f53353 mod_muc_limits: Reduce cost of multi-line messages, make configurable
Kim Alvefur <zash@zash.se>
parents: 5567
diff changeset
44 muc_max_line_count 23 The maximum allowed number of lines in a message
6680a1f53353 mod_muc_limits: Reduce cost of multi-line messages, make configurable
Kim Alvefur <zash@zash.se>
parents: 5567
diff changeset
45 muc_limit_base_cost 1 Base cost of sending a stanza
6680a1f53353 mod_muc_limits: Reduce cost of multi-line messages, make configurable
Kim Alvefur <zash@zash.se>
parents: 5567
diff changeset
46 muc_line_count_multiplier 0.1 Additional cost of each newline in the body of a message
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
47
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
48 For more understanding of how these values are used, see the algorithm
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
49 section below.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
50
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
51 Algorithm
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
52 =========
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
53
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
54 A certain number of events are allowed per second, given by
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
55 muc\_event\_rate. An event rate of 1 allows one event per second, and
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
56 event rate of 3 allows three events per second, and 0.5 allows one event
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
57 every two seconds, and so on.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
58
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
59 Obviously MUC conversations are not exactly steady streams of events.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
60 Sometimes multiple people will talk at once. This is handled by the
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
61 muc\_burst\_factor option.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
62
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
63 A burst factor of 2 will allow 2 times as many events at once, for 2
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
64 seconds, before throttling will be triggered. A factor of 5, 5 times as
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
65 many events for 5 seconds.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
66
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
67 When the limit is reached, an error response will be generated telling
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
68 the user the MUC is overactive, and asking them to try again.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
69
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
70 Compatibility
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
71 =============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
72
3417
1534d0715d35 mod_muc_limits: Add support for new MUC API in Prosody 0.11
Kim Alvefur <zash@zash.se>
parents: 3402
diff changeset
73 ------- ------------------
1534d0715d35 mod_muc_limits: Add support for new MUC API in Prosody 0.11
Kim Alvefur <zash@zash.se>
parents: 3402
diff changeset
74 trunk Works
1534d0715d35 mod_muc_limits: Add support for new MUC API in Prosody 0.11
Kim Alvefur <zash@zash.se>
parents: 3402
diff changeset
75 0.11 Works
2770
7cd877aa6095 mod_muc_limits: Update compatibility table
Matthew Wild <mwild1@gmail.com>
parents: 2769
diff changeset
76 0.10 Works
7cd877aa6095 mod_muc_limits: Update compatibility table
Matthew Wild <mwild1@gmail.com>
parents: 2769
diff changeset
77 0.9 Works
1833
52e998bb4490 mod_muc_limits/README: Footnote formatting so pandoc understands it
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
78 0.8 Doesn't work[^1]
3417
1534d0715d35 mod_muc_limits: Add support for new MUC API in Prosody 0.11
Kim Alvefur <zash@zash.se>
parents: 3402
diff changeset
79 ------- ------------------
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
80
1833
52e998bb4490 mod_muc_limits/README: Footnote formatting so pandoc understands it
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
81 [^1]: This module can be made to work in 0.8 (and *maybe* previous
52e998bb4490 mod_muc_limits/README: Footnote formatting so pandoc understands it
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
82 versions) of Prosody by copying the new
52e998bb4490 mod_muc_limits/README: Footnote formatting so pandoc understands it
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
83 [util.throttle](http://hg.prosody.im/trunk/raw-file/fc8a22936b3c/util/throttle.lua)
52e998bb4490 mod_muc_limits/README: Footnote formatting so pandoc understands it
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
84 into your Prosody source directory (into the util/ subdirectory).