Mercurial > prosody-modules

annotate mod_mam/README.markdown @ 3492:f59334da6df9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_conversejs: Show fallback text if converse.js fails to load (thanks MattJ) This can happen if javascript is enabled but 3rd party resources are blocked, or some other error happened.
author Kim Alvefur <zash@zash.se>
date Tue, 19 Mar 2019 19:43:13 +0100
parents b8805ab1d470
children 637d63b7398e
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: 1801
diff changeset
1 ---
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
2 labels:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
3 - 'Stage-Beta'
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
4 summary: 'XEP-0313: Message Archive Management'
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
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: 1801
diff changeset
7 Introduction
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
8 ============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9
1978
b91f27f21666 mod_mam/README: Use autolinks
Kim Alvefur <zash@zash.se>
parents: 1976
diff changeset
10 Implementation of [XEP-0313: Message Archive Management].
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
11
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
12 Details
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
13 =======
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
14
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
15 This module will archive all messages that match the simple rules setup
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
16 by the user, and allow the user to access this archive.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
17
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
18 Usage
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
19 =====
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
20
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
21 First copy the module to the prosody plugins directory.
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
22
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
23 Then add "mam" to your modules\_enabled list:
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
24
1820
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
25 ``` {.lua}
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
26 modules_enabled = {
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
27 -- ...
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
28 "mam",
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
29 -- ...
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
30 }
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
31 ```
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
32
1835
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
33 Configuration
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
34 =============
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
35
2012
cdba975e9b6e mod_mam/README: Add a summary of options
Kim Alvefur <zash@zash.se>
parents: 1978
diff changeset
36 Option summary
cdba975e9b6e mod_mam/README: Add a summary of options
Kim Alvefur <zash@zash.se>
parents: 1978
diff changeset
37 --------------
cdba975e9b6e mod_mam/README: Add a summary of options
Kim Alvefur <zash@zash.se>
parents: 1978
diff changeset
38
cdba975e9b6e mod_mam/README: Add a summary of options
Kim Alvefur <zash@zash.se>
parents: 1978
diff changeset
39 option type default
2022
77b9c7e5fd63 mod_mam: Allow interval between archive cleanup to be changed
Kim Alvefur <zash@zash.se>
parents: 2017
diff changeset
40 ------------------------------ ----------------------- -----------
2012
cdba975e9b6e mod_mam/README: Add a summary of options
Kim Alvefur <zash@zash.se>
parents: 1978
diff changeset
41 max\_archive\_query\_results number `50`
2017
d44ac0756c46 mod_mam: Enable archiving by default, less of a privacy issue if messages expire
Kim Alvefur <zash@zash.se>
parents: 2016
diff changeset
42 default\_archive\_policy boolean or `"roster"` `true`
2016
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
43 archive\_expires\_after string `"1w"`
2022
77b9c7e5fd63 mod_mam: Allow interval between archive cleanup to be changed
Kim Alvefur <zash@zash.se>
parents: 2017
diff changeset
44 archive\_cleanup\_interval number `4*60*60`
77b9c7e5fd63 mod_mam: Allow interval between archive cleanup to be changed
Kim Alvefur <zash@zash.se>
parents: 2017
diff changeset
45
2012
cdba975e9b6e mod_mam/README: Add a summary of options
Kim Alvefur <zash@zash.se>
parents: 1978
diff changeset
46
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
47 Storage backend
1835
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
48 ---------------
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
49
2015
7f90692bbd23 mod_mam/README: Fix footnote
Kim Alvefur <zash@zash.se>
parents: 2013
diff changeset
50 mod\_mam uses the store "archive2"[^1]. See [Prosodys data storage
1978
b91f27f21666 mod_mam/README: Use autolinks
Kim Alvefur <zash@zash.se>
parents: 1976
diff changeset
51 documentation][doc:storage] for information on how to configure storage.
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
52
2013
a8ec8491fdee mod_mam/README: Point out that mod_storage_sql only supports archives in 0.10
Kim Alvefur <zash@zash.se>
parents: 2012
diff changeset
53 For example, to use mod\_storage\_sql (requires Prosody 0.10 or later):
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
54
1820
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
55 ``` {.lua}
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
56 storage = {
1976
cd36e5bf00b3 Various READMEs: Update to reflect rename of mod_storage_sql2 → mod_storage_sql
Kim Alvefur <zash@zash.se>
parents: 1835
diff changeset
57 archive2 = "sql";
1820
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
58 }
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
59 ```
1801
5abf61915ab4 mod_mam/README: Add example of use with mod_storage_sql2
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
60
2023
98b4794b72e4 mod_mam: Include an in-memory fallback driver
Kim Alvefur <zash@zash.se>
parents: 2022
diff changeset
61 If no archive-capable storage backend can be opened then an in-memory
98b4794b72e4 mod_mam: Include an in-memory fallback driver
Kim Alvefur <zash@zash.se>
parents: 2022
diff changeset
62 one will be used as fallback.
98b4794b72e4 mod_mam: Include an in-memory fallback driver
Kim Alvefur <zash@zash.se>
parents: 2022
diff changeset
63
1835
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
64 Query size limits
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
65 -----------------
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
66
1804
3228fb928a93 mod_mam/README: Minor fixup
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
67 max_archive_query_results = 20;
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
68
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
69 This is the largest number of messages that are allowed to be retrieved
1835
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
70 in one request *page*. A query that does not fit in one page will
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
71 include a reference to the next page, letting clients page through the
2463
e2d955f6167f mod_mam/README: Fix typo
Kim Alvefur <zash@zash.se>
parents: 2037
diff changeset
72 result set. Setting large number is not recommended, as Prosody will be
1835
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
73 blocked while processing the request and will not be able to do anything
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
74 else.
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
75
2016
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
76 Archive expiry
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
77 --------------
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
78
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
79 Messages in the archive will expire after some time, by default one
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
80 week. This can be changed by setting `archive_expires_after`:
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
81
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
82 ``` {.lua}
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
83 archive_expires_after = "1d" -- one day
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
84
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
85 archive_expires_after = "1w" -- one week, the default
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
86
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
87 archive_expires_after = "2m" -- two months
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
88
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
89 archive_expires_after = "1y" -- one year
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
90
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
91 archive_expires_after = 60 * 60 -- one hour
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
92
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
93 archive_expires_after = "never" -- forever
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
94 ```
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
95
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
96 The format is an integer number of seconds or a multiple of a period
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
97 given by a suffix that can be one of `d` (day), `w` (week), `m` (month)
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
98 or `y` (year). No multiplier means seconds.
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
99
1835
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
100 Message matching policy
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
101 -----------------------
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
102
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
103 The MAM protocol includes a way for clients to control what messages
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
104 should be stored. This allows users to enable or disable archiving by
2017
d44ac0756c46 mod_mam: Enable archiving by default, less of a privacy issue if messages expire
Kim Alvefur <zash@zash.se>
parents: 2016
diff changeset
105 default or for specific contacts.
1835
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
106
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
107 ``` {.lua}
2017
d44ac0756c46 mod_mam: Enable archiving by default, less of a privacy issue if messages expire
Kim Alvefur <zash@zash.se>
parents: 2016
diff changeset
108 default_archive_policy = true
1835
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
109 ```
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
110
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
111 `default_archive_policy =` Meaning
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
112 ---------------------------- ------------------------------------------------------
2037
632aa9f49aed mod_mam/README: Update default_archive_policy table for new default (thanks xnyhps)
Kim Alvefur <zash@zash.se>
parents: 2023
diff changeset
113 `false` Store no messages.
1835
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
114 `"roster"` Store messages to/from contacts in the users roster.
2037
632aa9f49aed mod_mam/README: Update default_archive_policy table for new default (thanks xnyhps)
Kim Alvefur <zash@zash.se>
parents: 2023
diff changeset
115 `true` Store all messages. This is the default.
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
116
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
117 Compatibility
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
118 =============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
119
2499
b8805ab1d470 mod_mam/README: Note that mod_mam is included with prosody 0.10+
Kim Alvefur <zash@zash.se>
parents: 2463
diff changeset
120 ------- -----------------------
b8805ab1d470 mod_mam/README: Note that mod_mam is included with prosody 0.10+
Kim Alvefur <zash@zash.se>
parents: 2463
diff changeset
121 trunk Included with Prosody
b8805ab1d470 mod_mam/README: Note that mod_mam is included with prosody 0.10+
Kim Alvefur <zash@zash.se>
parents: 2463
diff changeset
122 0.10 Included with Prosody
2023
98b4794b72e4 mod_mam: Include an in-memory fallback driver
Kim Alvefur <zash@zash.se>
parents: 2022
diff changeset
123 0.9 Works
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
124 0.8 Does not work
2499
b8805ab1d470 mod_mam/README: Note that mod_mam is included with prosody 0.10+
Kim Alvefur <zash@zash.se>
parents: 2463
diff changeset
125 ------- -----------------------
b8805ab1d470 mod_mam/README: Note that mod_mam is included with prosody 0.10+
Kim Alvefur <zash@zash.se>
parents: 2463
diff changeset
126
1835
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
127
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
128 [^1]: Might be changed to "mam" at some point
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
129