1
0
mirror of https://github.com/moparisthebest/xeps synced 2024-10-31 15:35:07 -04:00
xeps/xep-0201.xml
Peter Saint-Andre 1a5ae1674b typo
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@410 4b5297f7-1745-476d-ba37-a9c6900126ab
2007-01-24 16:19:17 +00:00

176 lines
11 KiB
XML

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Best Practices for Message Threads</title>
<abstract>This specification defines recommended handling of XMPP message threads.</abstract>
&LEGALNOTICE;
<number>0201</number>
<status>Experimental</status>
<type>Informational</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>N/A</shortname>
&stpeter;
&ianpaterson;
&ksmith;
<revision>
<version>0.2</version>
<date>2007-01-23</date>
<initials>psa/ks</initials>
<remark><p>Equalized treatment of different message types (chat and groupchat not preferred over normal); required the use of UUIDs; specified use of In-Reply-To header; added Kevin Smith as co-author.</p></remark>
</revision>
<revision>
<version>0.1</version>
<date>2006-12-20</date>
<initials>psa</initials>
<remark><p>Initial version.</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2006-12-14</date>
<initials>psa</initials>
<remark>Corrected SHIM example; added XMPP Registrar considerations.</remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2006-12-13</date>
<initials>psa/ip</initials>
<remark>First draft.</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>Although message threads are re-used in XMPP extension protocols such as &xep0085; and &xep0155;, the semantics of message threads have never been well specified (e.g., in &rfc3921;). This document attempts to clearly specify the meaning and handling of message threads for implementation by XMPP clients and for potential inclusion in &rfc3921bis;.</p>
</section1>
<section1 topic='Motivation' anchor='motivation'>
<p>Threads matter because they enable XMPP clients to:</p>
<ul>
<li>Track conversation topics within the context of a one-to-one chat session, a &xep0045; room, or exchange of normal messages.</li>
<li>Restart a conversation from message history.</li>
<li>Enable clients to distinguish between different conversation threads when presenting a user's message, chat, and groupchat histories, thus providing a more coherent user interface (e.g. by collapsing threads to a single history entry).</li>
<li>Separate logical sessions from physical interface objects such as windows.</li>
<li>Route XMPP stanzas internally (e.g., dispatching different content types to different windows), thus facilitating the creation of more robust plugin architectures.</li>
</ul>
</section1>
<section1 topic='Semantics' anchor='semantics'>
<p>Section 2.1.2.3 of <cite>RFC 3921</cite> currently states the following regarding the semantics of the ThreadID:</p>
<p class='indent'>The &lt;thread/&gt; element contains non-human-readable XML character data specifying an identifier that is used for tracking a conversation thread (sometimes referred to as an "instant messaging session") between two entities.</p>
<p>The description in <cite>RFC 3921</cite> is deemed to be too limiting, since it ignores the potential use of the ThreadID when exchanging message stanzas of types other than 'chat'. Therefore we proposal the following description:</p>
<p class='indent'>The primary use of the XMPP &lt;thread/&gt; element is to uniquely identify a conversation thread or "chat session" between two entities instantiated by &lt;message/&gt; stanzas of type 'chat'. However, the XMPP &lt;thread/&gt; element may also be used to uniquely identify an analogous thread between two entities instantiated by &lt;message/&gt; stanzas of type 'headline' or 'normal', or among multiple entities in the context of a multi-user chat room instantiated by &lt;message/&gt; stanzas of type 'groupchat'. It may also be used for &lt;message/&gt; stanzas not related to a conversation, such as a game session or between plugins.</p>
</section1>
<section1 topic='Uniqueness' anchor='unique'>
<p>Section 2.1.2.3 of <cite>RFC 3921</cite> currently states the following uniqueness requirement:</p>
<p class='indent'>The value of the &lt;thread/&gt; element ... MUST be unique to that conversation thread within the stream and MUST be consistent throughout that conversation (a client that receives a message from the same full JID but with a different thread ID MUST assume that the message in question exists outside the context of the existing conversation thread).</p>
<p>The uniqueness requirement in <cite>RFC 3921</cite> is not deemed strong enough since it is desirable that a ThreadID could be used to (for instance) restart a conversation at a later date. Therefore we propose the following uniqueness requirement:</p>
<p class='indent'>The value of the &lt;thread/&gt; element MUST be a universally unique identifier (UUID) as described in &rfc4122;.</p>
</section1>
<section1 topic='Handling' anchor='handling'>
<p>In the context of &lt;message/&gt; stanzas of type 'chat' exchanged between two entities, the value of the &lt;thread/&gt; element shall be considered equivalent to a unique identifier for the chat session or conversation thread. If an entity receives such a message with a new or unknown ThreadID, it SHOULD treat the message as part of a session with unnegotiated parameters (i.e., as equivalent to the first message in a chat session that has been negotiated via <cite>XEP-0155</cite> with no parameters specified). An entity SHOULD destroy the thread when it sends or receives a <cite>XEP-0155</cite> "terminate" action and MAY destroy the thread when it goes offline, but SHOULD NOT destroy the thread if a human user merely closes a window in a client interface.</p>
<p>When sending a &lt;message/&gt; stanza of type 'normal', the value of the &lt;thread/&gt; element is used to uniquely identify a conversation thread which may not be progressing in real-time. A &lt;message/&gt; stanza of type 'normal' SHOULD always use a new &lt;thread/&gt; element identifier unless it is written in direct reply to another &lt;message/&gt; stanza, in which case the &lt;thread/&gt; element of the original &lt;message/&gt; should be used. Determining what constitutes a &lt;message/&gt; stanza written in reply to another is a matter left to individual implementation, but it is envisaged that in most cases it would be the result of, e.g., the user clicking a 'reply' button when reading the contents of the previous stanza; alternatively, the entity that replies can include an "In-Reply-To" header as described in the <link url='#impl'>Implementation Notes</link> section of this document.</p>
<p>To ensure the uniqueness of ThreadIDs in the context of a multi-user chat room, the multi-use chat service MAY provide a way for room occupants to request a unique ThreadID; definition of such methods is out of scope for this specification.</p>
<p>There are no special handling requirements related to threads in the context of &lt;message/&gt; stanzas of type 'headline'.</p>
<p>When displaying historical conversations within a user interface, a client SHOULD provide a visual indication of thread membership of messages. Methods for such indications include (non-exhaustively) the grouping of all messages within a thread together, providing an index of threads, or formatting all messages within a thread in a cohesive manner, e.g. with a uniform coloring.</p>
</section1>
<section1 topic='Inclusion' anchor='inclusion'>
<p>Depending on the type of the message (i.e., the value of the 'type' attribute), the &lt;thread/&gt; should be included as follows:</p>
<table caption='When to Include Threads'>
<tr>
<th>Message Type</th>
<th>Inclusion</th>
</tr>
<tr>
<td>chat</td>
<td>RECOMMENDED</td>
</tr>
<tr>
<td>groupchat</td>
<td>OPTIONAL</td>
</tr>
<tr>
<td>headline</td>
<td>OPTIONAL</td>
</tr>
<tr>
<td>normal</td>
<td>OPTIONAL</td>
</tr>
</table>
</section1>
<section1 topic='SHIM Header' anchor='shim'>
<p>In some contexts it may be desirable to enforce thread-like semantics when exchanging XMPP &lt;iq/&gt; stanzas. Because <cite>RFC 3920</cite> disallows more than one direct child element of the &lt;iq/&gt; stanza, it is not possible to include the &lt;thread/&gt; element for tracking purposes. Therefore we define a "ThreadID" &xep0131; header with the same semantics as the &lt;thread/&gt; element, but with the syntax of a SHIM header:</p>
<example caption='ThreadID header'><![CDATA[
<iq from='romeo@montague.net/home'
to='joogle@botster.shakespeare.lit'
type='get'
id='create1'>
<command xmlns='http://jabber.org/protocol/commands'
node='create'
action='execute'>
<headers xmlns='http://jabber.org/protocol/shim'>
<header name='ThreadID'>e0ffe42b28561960c6b12b944a092794b9683a38</header>
</headers>
</command>
</iq>
]]></example>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
<p>An entity that needs to track replies to particular messages may do so by including an 'id' attribute with the &MESSAGE; stanza.</p>
<example caption='Message with ID'><![CDATA[
<message
to='romeo@example.net/orchard'
from='juliet@example.com/balcony'
id='asiwe8289ljfdalk'
type='chat'
xml:lang='en'>
<body>Art thou not Romeo, and a Montague?</body>
<thread>e0ffe42b28561960c6b12b944a092794b9683a38</thread>
</message>
]]></example>
<p>The entity that replies then MAY include an "In-Reply-To" header:</p>
<example caption='Reply'><![CDATA[
<message
to='juliet@example.com/balcony'
from='romeo@example.net/orchard'
type='chat'
id='pertio4387435ilq'
xml:lang='en'>
<body>Neither, fair saint, if either thee dislike.</body>
<thread>e0ffe42b28561960c6b12b944a092794b9683a38</thread>
<headers xmlns='http://jabber.org/protocol/shim'>
<header name='In-Reply-To'>asiwe8289ljfdalk</header>
</headers>
</message>
]]></example>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>An entity that generates the UUID used as the ThreadID MUST ensure that the UUID does not reveal personally-identifying information about the entity.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='SHIM Headers Registry' anchor='registrar-shim'>
<p>The XMPP Registrar shall add "ThreadID" to its registry of SHIM headers. The submission is as follows:</p>
<code><![CDATA[
<header>
<name>ThreadID</name>
<desc>
This header has the same semantics as the thread child element
of the XMPP message stanza but is for use in IQ stanzas.
</desc>
<doc>XEP-0201</doc>
</header>
]]></code>
</section2>
</section1>
</xep>