From c3b310f36399658aec011acd6dba928bec49bb41 Mon Sep 17 00:00:00 2001 From: Nelson Vides Date: Wed, 2 Feb 2022 14:48:15 +0100 Subject: [PATCH] Prepare a documentation page for the smart markers --- doc/modules/mod_smart_markers.md | 40 ++++++++++++++ doc/open-extensions/smart-markers.md | 78 ++++++++++++++++++++++++++++ mkdocs.yml | 2 + 3 files changed, 120 insertions(+) create mode 100644 doc/modules/mod_smart_markers.md create mode 100644 doc/open-extensions/smart-markers.md diff --git a/doc/modules/mod_smart_markers.md b/doc/modules/mod_smart_markers.md new file mode 100644 index 0000000000..cbcd441b51 --- /dev/null +++ b/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. diff --git a/doc/open-extensions/smart-markers.md b/doc/open-extensions/smart-markers.md new file mode 100644 index 0000000000..1bde18a3f4 --- /dev/null +++ b/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 + + + +``` +where: + +* `` 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. +* `` 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. +* `` 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 + + + + + +``` +where `peer-bare-jid` matches the requested bare jid and the subelements are `marker` xml payloads with the following attributes: + +* `` is the message id associated to this marker. +* `` is a marker as described in [XEP-0333][chat-markers]. +* `` contains an RFC3339 timestamp indicating when the marker was sent +* `` is an optional attribute that indicates if the marker refers to specific a thread in the conversation, or the main conversation if absent. +* `` 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 + + + + + + + + + + + + +``` + +### Example: groupchats + +```xml + + + + + + + + + + + + + + +``` + +[chat-markers]: https://xmpp.org/extensions/xep-0333.html diff --git a/mkdocs.yml b/mkdocs.yml index 28cd77c4ed..6f39f5ccde 100644 --- a/mkdocs.yml +++ b/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'