Merge pull request #3329 from esl/doc-mam-options

Document low-level MAM options
esl · Oct 13, 2021 · e5f6687 · e5f6687
2 parents 0497dd8 + f46b973
commit e5f6687
Show file tree

Hide file tree

Showing 8 changed files with 79 additions and 21 deletions.
diff --git a/big_tests/tests/mam_SUITE.erl b/big_tests/tests/mam_SUITE.erl
@@ -810,13 +810,6 @@ init_modules(elasticsearch, C, Config) ->
     init_module(host_type(), mod_mam_mnesia_prefs, [pm]),
     init_module(host_type(), mod_mam, addin_mam_options(C, Config)),
     Config;
-init_modules(rdbms_async, C, Config) ->
-    init_module(host_type(), mod_mam, addin_mam_options(C, Config)),
-    init_module(host_type(), mod_mam_rdbms_arch, [no_writer]),
-    init_module(host_type(), mod_mam_rdbms_async_writer, [pm, {flush_interval, 1}]), % 1ms
-    init_module(host_type(), mod_mam_rdbms_prefs, [pm]),
-    init_module(host_type(), mod_mam_rdbms_user, [pm]),
-    Config;
 init_modules(rdbms_async_pool, C, Config) ->
     init_module(host_type(), mod_mam, addin_mam_options(C, Config)),
     init_module(host_type(), mod_mam_rdbms_arch, [no_writer]),

diff --git a/doc/configuration/database-backends-configuration.md b/doc/configuration/database-backends-configuration.md
@@ -91,7 +91,7 @@ Please refer to the [RDBMS options](outgoing-connections.md#rdbms-options) for m
 **Version notice**
 
 The required minimum version of MySQL is `5.7.9`.
-This is mainly to benefit from the JSON data type and the default settings which works out of the box with MongooseIM.
+This is mainly to benefit from the JSON data type, and the default settings which work out of the box with MongooseIM.
 
 #### MySQL 8
 
@@ -192,7 +192,7 @@ MongooseIM is built with ODBC support by default.
 
 If muc_light's backend is set to ODBC and there are many rooms created in parallel in your system,
 there may be some deadlocks due to the `READ_COMMITTED_SNAPSHOT` set to `OFF` by default.
-In this case we recommend to set this database property to `ON`, this will enable row level locking which significantly reduces
+In this case we recommend setting this database property to `ON`, this will enable row level locking which significantly reduces
 deadlock chances around muc_light operations.
 
 This property can be set by the following `ALTER DATABASE` query:

diff --git a/doc/modules/mod_mam.md b/doc/modules/mod_mam.md
@@ -127,7 +127,7 @@ To disable archive for one-to-one messages please remove PM section or any PM re
 
 When enabled, MAM will store groupchat messages in recipients' individual archives. **USE WITH CAUTION!** May increase archive size significantly. Disabling this option for existing installation will neither remove such messages from MAM storage, nor will filter out them from search results.
 
-#### Enable MUC message archive
+### Enable MUC message archive
 
 Archive for MUC messages can be enabled in one of two ways:
 
@@ -145,7 +145,7 @@ Archive for MUC messages can be enabled in one of two ways:
   muc.backend = "rdbms" # enables MUC support and overrides its backend
 ```
 
-#### Disable MUC message archive
+### Disable MUC message archive
 
 To disable archive for MUC messages please remove MUC section or any MUC related option from the config file.
 
@@ -297,6 +297,71 @@ By default, `mod_mam` Cassandra backend requires `global` pool with `default` ta
 First, make sure that your ElasticSearch cluster has expected indexes and mappings in place.
 Please consult [Outgoing connections](../configuration/outgoing-connections.md#elasticsearch-options) page to learn how to properly configure ElasticSearch connection pool.
 
+### Low-level options
+
+These options allow for fine-grained control over MAM behaviour.
+
+#### `modules.mod_mam_meta.default_result_limit`
+* **Syntax:** non-negative integer
+* **Default:** `50`
+* **Example:** `modules.mod_mam_meta.default_result_limit = 100`
+
+This sets the default page size of returned results.
+
+#### `modules.mod_mam_meta.max_result_limit`
+* **Syntax:** non-negative integer
+* **Default:** `50`
+* **Example:** `modules.mod_mam_meta.max_result_limit = 100`
+
+This sets the maximum page size of returned results.
+
+#### `modules.mod_mam_meta.db_jid_format`
+
+* **Syntax:** string, one of `"mam_jid_rfc"`, `"mam_jid_mini"` or a module implementing `mam_jid` behaviour
+* **Default:** `"mam_jid_rfc"` for `mod_mam_muc_rdbms_arch`, `"mam_jid_mini"` for `mod_mam_rdbms_arch`
+* **Example:** `modules.mod_mam_meta.db_jid_format = "mam_jid_mini"`
+
+Sets the internal MAM jid encoder/decoder module for RDBMS.
+It is set to `"mam_jid_rfc"` when [`rdbms_message_format`](#modulesmod_mam_metardbms_message_format) is set to `"simple"`.
+
+#### `modules.mod_mam_meta.db_message_format`
+
+* **Syntax:** string, one of `"mam_message_xml"`, `"mam_message_eterm"`, `"mam_message_compressed_eterm"` or a module implementing `mam_message` behaviour
+* **Default:** different values for different backends, described below.
+* **Example:** `modules.mod_mam_meta.db_message_format = "mam_message_compressed_eterm"`
+
+Sets the internal MAM message encoder/decoder module.
+Default values for:
+
+* RDBMS: `"mam_message_compressed_eterm"` by default, and `"mam_message_xml"` when [`rdbms_message_format`](#modulesmod_mam_metardbms_message_format) is set to `"simple"`
+* Riak: `"mam_message_xml"`
+* Cassandra: `"mam_message_compressed_eterm"`  by default, and `"mam_message_xml"` when [`simple`](#modulesmod_mam_metasimple) is set to `true`
+
+#### `modules.mod_mam_meta.simple`
+
+* **Syntax:** boolean
+* **Default:** `false`
+* **Example:** `modules.mod_mam_meta.simple = true`
+
+Sets `db_message_format` to `"mam_message_xml"` for Cassandra.
+
+#### `modules.mod_mam_meta.extra_fin_element`
+
+* **Syntax:** string, a module implementing the `extra_fin_element/3` callback
+* **Default:** none
+* **Example:** `modules.mod_mam_meta.extra_fin_element = "example_mod"`
+
+This module can be used to add subelements to the `<fin>` element of the MAM lookup query response.
+It can be useful to be able to add information to a mam query, that doesn't belong to any specific message but to all of them.
+
+#### `modules.mod_mam_meta.extra_lookup_params`
+
+* **Syntax:** string, a module implementing the `extra_lookup_params/2` callback
+* **Default:** none
+* **Example:** `modules.mod_mam_meta.extra_lookup_params = "example_mod"`
+
+This module can be used to add extra lookup parameters to MAM lookup queries.
+
 ## Example configuration
 
 ```toml

diff --git a/src/mam/mod_mam_meta.erl b/src/mam/mod_mam_meta.erl
@@ -67,6 +67,11 @@ config_items() ->
       <<"archive_chat_markers">> => #option{type = boolean},
       <<"message_retraction">> => #option{type = boolean},
 
+      %% Common backend options
+      <<"user_prefs_store">> => #option{type = atom,
+                                        validate = {enum, [rdbms, cassandra, mnesia]}},
+      <<"full_text_search">> => #option{type = boolean},
+
       %% RDBMS-specific options
       <<"cache_users">> => #option{type = boolean},
       <<"rdbms_message_format">> => #option{type = atom,
@@ -77,12 +82,7 @@ config_items() ->
       <<"max_batch_size">> => #option{type = integer,
                                       validate = non_negative},
 
-      %% Common backend options
-      <<"user_prefs_store">> => #option{type = atom,
-                                        validate = {enum, [rdbms, cassandra, mnesia]}},
-      <<"full_text_search">> => #option{type = boolean},
-
-      %% Undocumented low-level options
+      %% Low-level options
       <<"default_result_limit">> => #option{type = integer,
                                             validate = non_negative},
       <<"max_result_limit">> => #option{type = integer,

diff --git a/src/mam/mod_mam_muc_rdbms_arch.erl b/src/mam/mod_mam_muc_rdbms_arch.erl
@@ -28,7 +28,7 @@
 
 -export([get_mam_muc_gdpr_data/3]).
 
-%% Called from mod_mam_rdbms_async_writer
+%% Called from mod_mam_muc_rdbms_async_pool_writer
 -export([prepare_message/2, retract_message/2, prepare_insert/2]).
 -export([extend_params_with_sender_id/2]).
 

diff --git a/src/mam/mod_mam_muc_rdbms_async_pool_writer.erl b/src/mam/mod_mam_muc_rdbms_async_pool_writer.erl
@@ -35,7 +35,7 @@
 -include("jlib.hrl").
 
 -record(state, {flush_interval      :: non_neg_integer(), %% milliseconds
-                max_batch_size     :: non_neg_integer(),
+                max_batch_size      :: non_neg_integer(),
                 host_type           :: mongooseim:host_type(),
                 acc=[]              :: list(),
                 flush_interval_tref :: reference() | undefined

diff --git a/src/mam/mod_mam_rdbms_arch.erl b/src/mam/mod_mam_rdbms_arch.erl
@@ -28,7 +28,7 @@
 
 -export([get_mam_pm_gdpr_data/3]).
 
-%% Called from mod_mam_rdbms_async_writer
+%% Called from mod_mam_rdbms_async_pool_writer
 -export([prepare_message/2, retract_message/2, prepare_insert/2]).
 
 -ignore_xref([behaviour_info/1, remove_archive/4, remove_domain/3]).

diff --git a/src/mam/mod_mam_rdbms_async_pool_writer.erl b/src/mam/mod_mam_rdbms_async_pool_writer.erl
@@ -174,7 +174,7 @@ worker_spec(WriterProc, N, HostType, MaxSize) ->
      permanent,
      5000,
      worker,
-     [mod_mam_rdbms_async_writer]}.
+     [mod_mam_rdbms_async_pool_writer]}.
 
 stop_worker(Proc) ->
     supervisor:terminate_child(mod_mam_sup, Proc),