[markers] Prepare a documentation page for the smart markers #3535
Conversation
This comment was marked as outdated.
This comment was marked as outdated.
Codecov Report
@@ Coverage Diff @@
## feature/smart_markers #3535 +/- ##
======================================================
Coverage 80.83% 80.83%
======================================================
Files 425 425
Lines 32273 32273
======================================================
Hits 26087 26087
Misses 6186 6186
Continue to review full report at Codecov.
|
doc/open-extensions/smart-markers.md
Outdated
|
|
||
| * `<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. |
There was a problem hiding this comment.
Please add some note that this field makes sense for group chats only.
There was a problem hiding this comment.
Wait, why only for groupchats? I might want to know which one was the last marker I sent to a regular user, just as much as to a room as well, and filtering by thread or timestamp applies the same 🤔
There was a problem hiding this comment.
just add one actual example for each possible destination. I.e. for groupchat and for one2one. Including a date as a date ;)
Something like:
# Query for markers in a room
Request
Result
# Query for markers in one2one conversation
Request
Result
There was a problem hiding this comment.
It can be a generic implementation, but it brings the most value for group chats. Since there will be not more than just 2 chat markers for 1-2-1 chats.
doc/open-extensions/smart-markers.md
Outdated
| ``` | ||
| where: | ||
|
|
||
| * `<peer-bare-jid>` MUST be the bare jid of the peer whose last marker wants to be checked. |
There was a problem hiding this comment.
Please state explicitly that it can be either user or muc/muclight jid
| @@ -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. | |||
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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 🤔
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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).
doc/open-extensions/smart-markers.md
Outdated
|
|
||
| * `<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. |
There was a problem hiding this comment.
just add one actual example for each possible destination. I.e. for groupchat and for one2one. Including a date as a date ;)
Something like:
# Query for markers in a room
Request
Result
# Query for markers in one2one conversation
Request
Result
NelsonVides
force-pushed
the
markers/docs
branch
from
58da0e3
to
1b359c6
Compare
This comment was marked as outdated.
This comment was marked as outdated.
NelsonVides
changed the title
NelsonVides
force-pushed
the
markers/docs
branch
from
1b359c6
to
3638301
Compare
This comment was marked as outdated.
This comment was marked as outdated.
NelsonVides
force-pushed
the
markers/docs
branch
from
3638301
to
69f904f
Compare
This comment was marked as outdated.
This comment was marked as outdated.
NelsonVides
force-pushed
the
markers/docs
branch
from
69f904f
to
767a635
Compare
This comment was marked as outdated.
This comment was marked as outdated.
NelsonVides
force-pushed
the
markers/docs
branch
from
767a635
to
8518373
Compare
This comment was marked as outdated.
This comment was marked as outdated.
NelsonVides
force-pushed
the
markers/docs
branch
from
8518373
to
c3b310f
Compare
|
small_tests_24 / small_tests / c3b310f small_tests_23 / small_tests / c3b310f dynamic_domains_mysql_redis_24 / mysql_redis / c3b310f dynamic_domains_pgsql_mnesia_24 / pgsql_mnesia / c3b310f dynamic_domains_pgsql_mnesia_23 / pgsql_mnesia / c3b310f ldap_mnesia_23 / ldap_mnesia / c3b310f ldap_mnesia_24 / ldap_mnesia / c3b310f internal_mnesia_24 / internal_mnesia / c3b310f dynamic_domains_mssql_mnesia_24 / odbc_mssql_mnesia / c3b310f pgsql_mnesia_24 / pgsql_mnesia / c3b310f mysql_redis_24 / mysql_redis / c3b310f elasticsearch_and_cassandra_24 / elasticsearch_and_cassandra_mnesia / c3b310f pgsql_mnesia_23 / pgsql_mnesia / c3b310f mssql_mnesia_24 / odbc_mssql_mnesia / c3b310f riak_mnesia_24 / riak_mnesia / c3b310f |
These documents explain the functionality that
mod_smart_markersoffer alone, together with an iq-protocol not currently implemented, but that I'd like to start reviewing in order to make the implementation cleaner.Note that for the iq-protocol, I didn't want to use Forms like we did for inbox, maybe because I imagine Forms as being actual forms presented to the user that the user fills on its own, while this request is more programmatically filled, but also, because I find forms much harder to implement, parse, validate, and test, and considering this module will already need all the removal hooks (remove_domain, remove_user, forget_room, affiliations_changed...), I didn't want to introduce more complexity to it.