From ccf36f634c2fd2a5e385f9632a6291cff42f19ab Mon Sep 17 00:00:00 2001 From: Dave Cridland Date: Tue, 21 Jan 2020 09:21:28 +0000 Subject: [PATCH] ProtoXEP: Inbox --- inbox/inbox.xml | 161 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 inbox/inbox.xml diff --git a/inbox/inbox.xml b/inbox/inbox.xml new file mode 100644 index 00000000..3197dc59 --- /dev/null +++ b/inbox/inbox.xml @@ -0,0 +1,161 @@ + + +%ents; + + +]> + + +
+ Inbox + This specification proposes a mechanism by which clients can find a list of ongoing conversations and their state. + &LEGALNOTICE; + XXXX + ProtoXEP + Standards Track + Standards + + XMPP Core + XEP-0313 + + + + inbox + &dcridland; + + 0.0.1 + 2019-12-30 + dwd + +
    +
  • Initial Revision
    • +
+ + +
+ + +

When initially run, a messaging client typically shows some list of contacts and chatrooms, and whether any new + messages are present in each.

+

The current mechanism for achieving this UX involves a complete synchronization of the server-side archive, and is both + time-consuming and bandwidth-intensive. This specification proposes a solution to directly obtain such data from + the server.

+

Moreover, the information gathered by the server to support this can be used in support of mobile push notifications.

+ +

Nomenclature used for instant messages versus ancillary messages will need to be adjusted to make it consistent + with &xep0422; et al.

+ + + + + +

Support for this protocol is advertised by the Service Discovery protocol defined in &xep0030; using a feature + of &ns;.

+ + +

The Inbox consists semantically of a list of conversations in order of last activity. Each conversation is + identified by a jid - for group chats this would be the chatroom, and for individual contacts this would be their + bare jid.

+

Each Inbox entry includes a count of messages considered new, the last MAM stanza-id relating to this conversation, + and the last MAM result for this conversation, as defined by &xep0313;. In addition, a client-controlled boolean + marker can be used to indicate a manual "set unread" state.

+

Finding more messages from this conversation can be achieved via a MAM query using with to specify the + conversation required.

+ + + + + +

An &IQ; of type "get" is used, containing a single element <inbox/>, containing an optional RSM + filter as specified by &xep0059;. This will typically be sent only to the user's own bare jid. The server + responds with a sequence of &MESSAGE; stanzas, each containing an <entry/> element qualified by the + &ns; namespace with a number of attributes:

+
    +
  • jid - contains the Jid of the conversation for this entry.
    • +
  • unread - contains a count of messages which are deemed to be unread by the server.
    • +
  • marked - a boolean indicating that a client has explicitly marked the conversation for some reason.
    • +
+

The <entry/> element contains the latest instant message, if any, which is encapsulated as a + <result/> element as defined by &xep0313;. This contains collated fastenings if supported by the + server.

+

After all entries required have been returned, the server then responds with an &IQ; result containing a + <fin/> element qualified by &ns;. This contains the RSM data, a total count of conversation + entries within the inbox, a count of conversations with unread messages, and a total count of unread messages.

+

Any counter of unread SHOULD be accurate, however client implementors please note that due to heuristics + involved and other issues these counters can be inaccurate at times.

+ + +

A client MAY at any time set a conversation as marked by sending an &IQ; of type "set" containing something or + other. This causes the server to set the "marked" flag on a conversation. A client SHOULD display a marked + conversation in the same way as an unread conversation, and explicitly removed the marked flag when the + conversation is considered re-read.

+

Removing a marked flag, even when the conversation is not currently marked, causes the unread counter for that + conversation to be set to zero.

+ + + + +

Servers MUST track which instant messages sent to clients remain unread.

+
    +
  • An instant message is always read if it is followed by an instant message which is read.
    • +
  • An instant message always starts unread.
    • +
  • A Chat Marker (see &xep0333;) of "displayed" or "acknowledged" causes the message to be read (and also causes + all prior messages to be read by implication).
    • +
  • A Message Receipt (see &xep0184;) does not cause messages to be considered unread. Perhaps it should?
    • +
  • Unmarking a conversation always sets the unread counter to zero, and by implication sets all messages to be + read.
    • +
+ + + +

Let us assume a user has only two contacts they have exchanges messages with, and a single chatroom. Asking for their inbox is simple:

+ + + + ]]> +

The server responds with a list of conversations:

+ + + + + + Greetings from Alpha Centauri! + + + + + + ]]> +

After the list of messages, the server completes its response with a the reply to the original IQ.

+ + + + + ]]> + + + +

TODO - Hopefully roughly given by the examples.

+ + + +

TODO

+ + + +

This XEP requires no interaction with &IANA;.

+ + + +

None.

+ + + +

The author notes that this protocol is heavily based on the mod_inbox system of MongooseIM. In addition, Kevin Smith provided useful feedback which has shaped this specification.

+ + +