Mercurial > prosody-modules

annotate mod_mam_smart_retention/README.md @ 6562:5da6fb562df9 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_unified_push: Fix push error handling (fixes #2000) Use the error object that send_iq() passes as an argument to it's reject callback instead of attempting and failing to do the parsing in the callback itself.
author kmq
date Mon, 06 Jul 2026 14:23:57 +0200
parents 2d256ea0c157
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6349
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
1 ---
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
2 labels:
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
3 - Stage-Alpha
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
4 summary: Smart retention for MAM archives - expire delivered messages faster
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
5 ...
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
6
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
7 Description
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
8 ===========
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
9
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
10 This module removes messages from the archive after they have been delivered
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
11 to one or all of the user's clients.
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
12
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
13 Background
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
14 ==========
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
15
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
16 The first module for allowing clients to "catch up" with messages that were
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
17 received while they were offline was mod_offline. Due to the design of that
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
18 protocol, offline messages could only be delivered to a single client before
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19 the server deleted them.
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
20
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
21 The newer XEP-0313 protocol, implemented by mod_mam, allows servers to cache
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
22 messages for a configurable retention period. This allows clients to
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
23 synchronize with the user's incoming and outgoing messages, providing a more
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
24 flexible "catch up" protocol that is compatible with multiple devices.
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
25
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
26 The ideal retention period is long enough for all devices to catch up, but not
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
27 too long (increased storage and processing requirements on the server,
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
28 metadata accumulation, etc.).
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
29
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
30 This module takes a middle approach. If successful delivery of messages is
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
31 known, then they can be removed from the message archive before the global
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
32 retention period.
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
33
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
34 Caveats
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
35 =======
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
36
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
37 To work properly, this module expects clients that:
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
38
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
39 - Always use XEP-0198 Stream Management
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
40 - Always use XEP-0386 Bind 2
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
41 - Always query the archive using XEP-0313 during login, synchronizing all
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
42 messages in order (oldest to newest).
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
43
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
44 If clients do not fit these requirements, you may get unusual results (including,
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
45 in the worst case, expiring messages which have not been delivered).
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
46
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
47 Note also that cleanup of delivered messages is scheduled daily. This means
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
48 that even with the `"one"` strategy and no minimum retention time set,
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
49 messages are not removed immediately upon delivery, but only after the next
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
50 cleanup task runs.
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
51
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
52 Configuration
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
53 =============
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
54
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
55 Just load this module on a host that also has mod_mam. For example:
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
56
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
57 ```lua
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
58 modules_enabled = {
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
59 ...
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
60 "mam";
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
61 "mam_smart_retention";
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
62 ...
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
63 }
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
64 ```
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
65
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
66 You can then set the following options:
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
67
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
68 `smart_retention_strategy`
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
69 : Can be `"one"` (default) or `"all"`, depending on whether you want to expire
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
70 messages that have been delivered to at least one client, or wait until all
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
71 known clients have received them.
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
72
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
73 `smart_retention_min`
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
74 : An optional minimum amount of time to keep messages for, even if they have
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
75 already been delivered to clients.
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
76
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
77 Compatibility
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
78 =============
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
79
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
80 Requires Prosody trunk, commit 8fb7408ded73 or later. Not compatible with
2d256ea0c157 mod_mam_smart_retention: New experimental module for smart retention in MAM archives
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
81 Prosody 13.0 or earlier.