Prepare a documentation page for the smart markers

doc/modules/mod_smart_markers.md

@@ -0,0 +1,35 @@
+## Module Description
+
+Smart markers are an experimental feature, described in detail as our [Open XMPP Extension](../open-extensions/smart-markers.md).
+
+## Options
+
+### `modules.mod_smart_markers.iqdisc`
+* **Syntax:** array of strings, out of `"displayed"`, `"received"`, `"acknowledged"`
+* **Default:** `["displayed"]`
+* **Example:** `reset_markers = ["received"]`
+
+* **Syntax:** string, one of `"one_queue"`, `"no_queue"`, `"queues"`, `"parallel"`
+* **Default:** `"no_queue"`
+
+Strategy to handle incoming IQ requests. For details, please refer to
+[IQ processing policies](../configuration/Modules.md#iq-processing-policies).
+
+### `modules.mod_smart_markers.backend`
+* **Syntax:** string, only `"rdbms"` is supported at the moment.
+* **Default:** `"rdbms"`
+* **Example:** `backend = "rdbms"`
+
+## Example configuration
+
+```toml
+[modules.mod_smart_markers]
+  backend = "rdbms"
+  iqdisc = "parallel"
+```
+
+## Implementation details
+The current implementation has some limitations:
+
+* It does not verify that markers only move forwards, hence a user can, intentionally or accidentally, send a marker to an older message, and this would override newer ones.
+* It stores markers sent only for users served on a local domain. It does not store received markers, so if the peer is reached across federation, this module won't track markers for federated users. Therefore extensions that desire seeing not only the sender's markers but also the peer's markers, won't work with the current implementation across federated users.

doc/open-extensions/smart-markers.md

@@ -0,0 +1,39 @@
+When a client enters a conversation after being offline for a while, such client might want to know what was the last message-id that was marked according to the rules defined in [XEP-0333 - Chat Markers][chat-markers], in order to know where he left of, and build an enhanced UI.
+
+MongooseIM provides such functionality, using [mod_smart_markers](../modules/mod_smart_markers.md)
+
+## Namespace
+'esl:xmpp:smart-markers:0'
+
+## Fetching a conversation's latest markers
+
+### Individual fetch
+
+Given a peer, i.e., another user or a muc room, we can fetch the marker we last sent, to the main thread or any other sub-thread, with an IQ like the following:
+```xml
+<iq id='iq-unique-id' type='get'>
+  <query xmlns='esl:xmpp:smart-markers:0' peer='<peer-bare-jid>' [thread='<thread-id>' after='<RFC3339-timestamp>'] />
+</iq>
+```
+where:
+
+* `<peer-bare-jid>` MUST be the bare jid of the peer whose last marker wants to be checked.
+* `<thread>` is an optional attribute that indicates if the check refers to specific a thread in the conversation. If not provided, defaults to the main conversation thread.
+* `<after>` is an optional attribute indicating whether markers sent only after a certain timestamp are desired.
+
+Then the following would be received, was there to be any marker:
+```xml
+<iq from='user-bare-jid' to='user-jid' id='iq-unique-id' type='result'>
+  <query xmlns='esl:xmpp:smart-markers:0' entity='peer-bare-jid' >
+    <marker id='<message-id>' type='<type>' timestamp='<RFC3339>' [thread='<thread-id>'] />
+  </query>
+</iq>
+```
+where `peer-bare-jid` matches the requested bare jid and the subelements are `marker` xml payloads with the following attributes:
+
+* `<id>` is the message id associated to this marker.
+* `<type>` is a marker as described in [XEP-0333][chat-markers].
+* `<timestamp>` contains an RFC3339 timestamp indicating when the marker was sent
+* `<thread>` is an optional attribute that indicates if the marker refers to specific a thread in the conversation, or the main conversation if absent.
+
+[chat-markers]: https://xmpp.org/extensions/xep-0333.html

mkdocs.yml

@@ -60,6 +60,7 @@ nav:
   - 'Open XMPP Extensions':
       - 'MUC light': 'open-extensions/muc_light.md'
       - 'Inbox': 'open-extensions/inbox.md'
+      - 'Smart Markers': 'open-extensions/smart-markers.md'
       - 'Token-based reconnection': 'open-extensions/token-reconnection.md'
   - Configuration:
       - 'Configuration Files': 'configuration/configuration-files.md'
@@ -130,6 +131,7 @@ nav:
       - 'mod_register': 'modules/mod_register.md'
       - 'mod_roster': 'modules/mod_roster.md'
       - 'mod_shared_roster_ldap': 'modules/mod_shared_roster_ldap.md'
+      - 'mod_smart_markers': 'modules/mod_smart_markers.md'
       - 'mod_sic': 'modules/mod_sic.md'
       - 'mod_stream_management': 'modules/mod_stream_management.md'
       - 'mod_time': 'modules/mod_time.md'