Prepare a documentation page for the smart markers

doc/modules/mod_smart_markers.md

@@ -0,0 +1,40 @@
+## Module Description
+
+Smart markers are an experimental feature, described in detail as our [Open XMPP Extension for markers](../open-extensions/smart-markers.md).
+
+## Options
+
+### `modules.mod_smart_markers.iqdisc`
+* **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"`
+
+### `modules.mod_smart_markers.keep_private`
+* **Syntax:** boolean
+* **Default:** `false`
+* **Example:** `keep_private = true`
+
+This indicates if markers are meant to be private to the sender of the marker (setting `keep_private` as `true`), or if they can be public.
+
+By default markers are public to the conversation where they are sent, so they'll be routed to all recipients, and anyone in the chat can see where its peers are at any time, i.e., the Facebook Messenger model; but they can be configured private, so markers won't be routed to anyone, and a user who fetches their status will only receive information for markers they have sent alone, i.e., the Slack model.
+
+## 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,78 @@
+This module allows the client to query for the most recent [chat markers][chat-markers].
+
+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
+
+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. It can be the bare jid of a user, or of MUC room.
+* `<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. This most often makes sense for big groupchats, as a potential filter to reduce the amount of markers that will be returned.
+
+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' peer='peer-bare-jid'>
+    <marker from='<sender-bare-jid>' 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.
+* `<sender-bare-jid>` is the bare jid of the peer who sent the marker, which can be the requester itself, or any peer in the conversation, for both 1:1 chats or groupchats.
+
+### Example: 1:1
+
+```xml
+<!-- Alice fetches markers in her conversation with Bob -->
+<iq id='iq-unique-id' type='get'>
+  <query xmlns='esl:xmpp:smart-markers:0' peer='bob@localhost' />
+</iq>
+
+<!-- She receives as an answer -->
+<iq from='alice@localhost' to='alice@localhost/res1' id='iq-unique-id' type='result'>
+  <query xmlns='esl:xmpp:smart-markers:0' peer='bob@localhost'>
+    <marker from='alice@localhost' id='ABCDEFGHIJ' type='displayed' timestamp='2022-02-26T09:11:05.634232Z'/>
+    <marker from='bob@localhost' id='KLMNOPQRST' type='displayed' timestamp='2022-02-26T09:11:07.382923Z'/>
+  </query>
+</iq>
+```
+
+### Example: groupchats
+
+```xml
+<!-- Alice fetches markers in a groupchat -->
+<iq id='iq-unique-id' type='get'>
+  <query xmlns='esl:xmpp:smart-markers:0' peer='room@muc.localhost' />
+</iq>
+
+<!-- She receives as an answer -->
+<iq from='alice@localhost' to='alice@localhost/res1' id='iq-unique-id' type='result'>
+  <query xmlns='esl:xmpp:smart-markers:0' peer='room@muc.localhost'>
+    <marker from='alice@localhost' id='XOLWEMUNTO' type='displayed' timestamp='2022-02-26T09:11:05.634232Z'/>
+    <marker from='bob@localhost' id='NNTMWMKSOE' type='displayed' timestamp='2022-02-26T09:11:07.382923Z'/>
+    <marker from='mike@localhost' id='OSNTETNHUR' type='displayed' timestamp='2022-02-26T09:13:07.382923Z'/>
+    <marker from='kate@localhost' id='SNWMENSTUH' type='displayed' timestamp='2022-02-26T09:12:07.382923Z'/>
+  </query>
+</iq>
+```
+
+[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'