mod_mam/README.markdown

   1 ---
   2 labels:
   3 - 'Stage-Merged'
   4 summary: 'XEP-0313: Message Archive Management'
   5 ...
   6
   7 Introduction
   8 ============
   9
  10 Implementation of [XEP-0313: Message Archive Management].
  11
  12 Details
  13 =======
  14
  15 This module will archive all messages that match the simple rules setup
  16 by the user, and allow the user to access this archive.
  17
  18 Usage
  19 =====
  20
  21 First copy the module to the prosody plugins directory.
  22
  23 Then add "mam" to your modules\_enabled list:
  24
  25 ``` {.lua}
  26 modules_enabled = {
  27     -- ...
  28     "mam",
  29     -- ...
  30 }
  31 ```
  32
  33 Configuration
  34 =============
  35
  36 Option summary
  37 --------------
  38
  39   option                         type                    default
  40   ------------------------------ ----------------------- -----------
  41   max\_archive\_query\_results   number                  `50`
  42   default\_archive\_policy       boolean or `"roster"`   `true`
  43   archive\_expires\_after        string                  `"1w"`
  44   archive\_cleanup\_interval     number                  `4*60*60`
  45
  46
  47 Storage backend
  48 ---------------
  49
  50 mod\_mam uses the store "archive2"[^1]. See [Prosodys data storage
  51 documentation][doc:storage] for information on how to configure storage.
  52
  53 For example, to use mod\_storage\_sql (requires Prosody 0.10 or later):
  54
  55 ``` {.lua}
  56 storage = {
  57   archive2 = "sql";
  58 }
  59 ```
  60
  61 If no archive-capable storage backend can be opened then an in-memory
  62 one will be used as fallback.
  63
  64 Query size limits
  65 -----------------
  66
  67     max_archive_query_results = 20;
  68
  69 This is the largest number of messages that are allowed to be retrieved
  70 in one request *page*. A query that does not fit in one page will
  71 include a reference to the next page, letting clients page through the
  72 result set. Setting large number is not recommended, as Prosody will be
  73 blocked while processing the request and will not be able to do anything
  74 else.
  75
  76 Archive expiry
  77 --------------
  78
  79 Messages in the archive will expire after some time, by default one
  80 week. This can be changed by setting `archive_expires_after`:
  81
  82 ``` {.lua}
  83 archive_expires_after = "1d" -- one day
  84
  85 archive_expires_after = "1w" -- one week, the default
  86
  87 archive_expires_after = "2m" -- two months
  88
  89 archive_expires_after = "1y" -- one year
  90
  91 archive_expires_after = 60 * 60 -- one hour
  92
  93 archive_expires_after = "never" -- forever
  94 ```
  95
  96 The format is an integer number of seconds or a multiple of a period
  97 given by a suffix that can be one of `d` (day), `w` (week), `m` (month)
  98 or `y` (year). No multiplier means seconds.
  99
 100 Message matching policy
 101 -----------------------
 102
 103 The MAM protocol includes a way for clients to control what messages
 104 should be stored. This allows users to enable or disable archiving by
 105 default or for specific contacts.
 106
 107 ``` {.lua}
 108 default_archive_policy = true
 109 ```
 110
 111   `default_archive_policy =`   Meaning
 112   ---------------------------- ------------------------------------------------------
 113   `false`                      Store no messages.
 114   `"roster"`                   Store messages to/from contacts in the users roster.
 115   `true`                       Store all messages. This is the default.
 116
 117 Compatibility
 118 =============
 119
 120   ------- -----------------------
 121   trunk   Included with Prosody
 122   0.10    Included with Prosody
 123   0.9     Works
 124   0.8     Does not work
 125   ------- -----------------------
 126
 127
 128 [^1]: Might be changed to "mam" at some point
 129