Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[markers] Prepare a documentation page for the smart markers #3535

Merged
merged 1 commit into from
Mar 14, 2022
Merged

[markers] Prepare a documentation page for the smart markers #3535

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions doc/modules/mod_smart_markers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`
NelsonVides marked this conversation as resolved.
Show resolved Hide resolved
* **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.
78 changes: 78 additions & 0 deletions doc/open-extensions/smart-markers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

user might want to know where other participants left off as well, that was the main intention of this module.

also please fix typo - left off

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

where other participants left off is not what beekeeper needs, so I'm not implementing that part, yet. Would probably require a different IQ, and very likely make it configurable, because some deployments might consider where other users are as private data to those other users only and they shouldn't be fetched otherwise.

Might add a note to state that such functionality will be implemented as well if that makes the doc better 🤔

Copy link
Collaborator

@DenysGonchar DenysGonchar Feb 8, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure that we want it in open source, if it's too BKPR specific.

The main idea was to let the user fetch all the latest chat markers (his own and other participants as well) for a conversation (1-2-1 or a group chat), and I believe that is the protocol that we need in open source.

if you wish to have a common implementation, you may want to add an optional field [from=<jid>] to cover BKPR's use case.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Putting here a short summary of an offline discussion with @NelsonVides:

  • IQ protocol can stay as is.
  • a new configuration option for smart markers module can be introduced to cover beekeeper's use case:
    • the behaviour must be consistent for the offline and the online use cases. If a user receives online chat markers, it must be possible to fetch offline chat markers as well.
    • when enabled, this option must ensure filtering of the online chat markers (i.e. no chat markers delivered to the users). As for the carbon copies - the user should receive carbon copies only for his own chat marker messages.
    • when enabled, this option must limit fetching from the DB only to the user's own chat markers.
    • by default, this option must be disabled to ensure the consistent behaviour with XEP-333.
    • The implementation of this configuration option must be done in a generic way (in mod_smart_markers:get_chat_markers() interface), there should be no difference in code for supporting this option in mod_offline_chatmarkers.erl nor in IQ protocol implementation.

Justification: such option allows implementing behaviour similar to a various existing popular messaging application (e.g. slack).


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
2 changes: 2 additions & 0 deletions mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down Expand Up @@ -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'
Expand Down