docs/proposed-extensions/draft-kundrat-incthread.xml

   1 <?xml version="1.0" encoding="US-ASCII"?>
   2 <!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
   3
   4 <!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
   5 <!ENTITY RFC5234 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5234.xml">
   6 <!ENTITY RFC3501 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3501.xml">
   7 <!ENTITY RFC4466 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4466.xml">
   8 <!ENTITY RFC4731 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4731.xml">
   9 <!ENTITY RFC5256 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5256.xml">
  10 <!ENTITY RFC5267 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5267.xml">
  11 <!ENTITY DRAFT-inthread SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-morg-inthread-01.xml">
  12 ]>
  13 <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
  14 <?rfc strict="yes" ?>
  15 <?rfc toc="yes"?>
  16 <?rfc tocdepth="4"?>
  17 <?rfc symrefs="yes"?>
  18 <?rfc sortrefs="yes" ?>
  19 <?rfc compact="yes" ?>
  20 <?rfc subcompact="no" ?>
  21 <rfc category="std" docName="draft-kundrat-incthread-02" ipr="trust200902">
  22
  23   <front>
  24     <title abbrev="IMAP INCTHREAD Extension">IMAP Extension for Incremental Threading (INCTHREAD)</title>
  25
  26     <author fullname="Jan Kundrat" initials="J." surname="Kundrat">
  27       <address>
  28         <postal>
  29           <street>Eledrova 558</street>
  30           <city>Prague</city>
  31           <code>181 00</code>
  32           <country>CZ</country>
  33         </postal>
  34         <email>jkt@flaska.net</email>
  35       </address>
  36     </author>
  37
  38     <date year="2013" month="August" day="27"/>
  39
  40     <area>General</area>
  41     <workgroup>Internet Engineering Task Force</workgroup>
  42
  43     <keyword>IMAP</keyword>
  44     <keyword>THREAD</keyword>
  45     <keyword>INTHREAD</keyword>
  46     <keyword>incremental threading</keyword>
  47     <keyword>ESEARCH</keyword>
  48     <keyword>CONTEXT</keyword>
  49     <keyword>CONTEXT=SORT</keyword>
  50     <keyword>CONTEXT=SEARCH</keyword>
  51     <keyword>CONTEXT=THREAD</keyword>
  52
  53     <abstract>
  54         <t>This document describes the INCTHREAD IMAP extension which enables clients to retrieve incremental updates of
  55             the mailbox threading.  The extension repurposes the ESEARCH response for passing along the threading
  56             information and builds on top of Arnt Gulbrandsen's work on the INTHREAD search key.  The UID THREAD command
  57             is also extended to allow activating this extension.  Together, these changes make it possible for clients
  58             not to fetch the complete mailbox threading each time a new message arrives.</t>
  59     </abstract>
  60   </front>
  61
  62   <middle>
  63     <section title="Introduction">
  64         <t>Online IMAP clients which want to conserve the required bandwidth and also show messages in threads to their
  65             users have an option to delegate the message threading to the IMAP server through mechanisms outlines in
  66             <xref target="RFC5256"/>.  Using the UID SEARCH command, clients do not have to download the message headers
  67             (like the Message-Id, References and In-Reply-To), and can instead fetch the resulting thread mapping of all
  68             messages in a mailbox.</t>
  69
  70         <t>Unfortunately, the savings in transferred data are significantly reduced when clients have to fetch the
  71             thread mapping over and over again, for example when a new message arrives.  Even if the client downloads
  72             the relevant headers of new arrivals, these data alone are not sufficient to determine a proper place where
  73             to insert the newly arriving message.  Furthermore, a single newly arriving message could potentially affect
  74             placement of many messages (or even all of them in a pathological case due to joining of adjacent threads).
  75             This issue prevents using approach similar to the CONTEXT=SEARCH and CONTEXT=SORT extensions <xref
  76                 target="RFC5267"/> where only a position of the new arrival is communicated in an incremental
  77             manner.</t>
  78
  79         <t>This extension builds on Arnt Gulbrandsen's work <xref target="I-D.ietf-morg-inthread"/> and reuses the
  80             INTHREAD search key defined in said draft.  This search key is used to inform the server that the search
  81             conditions are to refer to all threads containing any messages which match the original search criteria.
  82             However, as the untagged THREAD response does not contain any data about the position of the affected thread
  83             among other threads in the mailbox, support for INTHREAD alone does not relieve the clients from performing
  84             additional operations due to missing information.  A naive workaround where the affected threads are always
  85             placed at the logical end of the mailbox would yield results different from the complete THREAD command when
  86             copying older messages.  Similarly, attempting to reuse the original thread position would significantly
  87             limit the usefulness of the REFS algorithm <xref target="I-D.ietf-morg-inthread"/> which sorts threads with
  88             "fresh messages" at the end of the view.</t>
  89
  90         <t>Because the THREAD response cannot transmit the position of the resulting thread relative to other threads in
  91             the mailbox, the ESEARCH response <xref target="RFC4731"/> is used and the UID THREAD command is extended to
  92             allow for specifying the return options in manner consistent with how SEARCH and UID SEARCH were modified by
  93             ESEARCH.  Finally, two new ESEARCH return options, the THREAD and the INCTHREAD, are defined.</t>
  94
  95         <t>These modifications together allow clients to delegate the threading operation completely to the server side
  96             without significantly increasing network traffic even on busy mailboxes.</t>
  97
  98         <section title="Drawbacks and Alternatives">
  99             <t>This extension can still transfer excessive amounts of data because the commands return complete threads
 100                 instead of incremental difference updates.  However, this approach allows for reusing the clients' and
 101                 servers' existing facilities, both for parsing and response processing.  In addition, unless the
 102                 protocol mandated history tracking of the threading tree, a much intrusive and resource-demanding
 103                 feature, the incremental updates would be only possible in case where the mailbox is currently selected.
 104                 This extension affirms the decision about threading requests to remain on the client side, letting it
 105                 use its policies about when to request full threading information and when to use the incremental
 106                 updates.</t>
 107
 108             <t>No support for automated updates of the threading data in the sense of the CONTEXT extension <xref
 109                     target="RFC5267"/> are defined at this point.  This might change based on feedback from other server
 110                 and client vendors.</t>
 111         </section>
 112
 113       <section title="Requirements Language">
 114         <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
 115         "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
 116         document are to be interpreted as described in <xref
 117         target="RFC2119">RFC 2119</xref>.</t>
 118       </section>
 119     </section>
 120
 121     <section title="IMAP Protocol Changes">
 122         <section title="New SEARCH Keys">
 123             <t>This document reuses the INTHREAD search key from <xref target="I-D.ietf-morg-inthread"/> with no changes
 124                 in its meaning or semantics.</t>
 125             <t>Please note that the "INTHREAD" search key and the "INCTHREAD" ESEARCH return option are two distinct
 126                 features.</t>
 127         </section>
 128
 129         <section title="Modified IMAP Commands">
 130             <section title="Modified UID THREAD Command">
 131                 <t>The UID THREAD command is extended with the following two return options:</t>
 132
 133                 <t><list style="hanging">
 134                         <t hangText="THREAD">Return the threading information through the ESEARCH response using syntax
 135                             similar to the untagged THREAD response.</t>
 136                         <t hangText="INCTHREAD">Return a dedicated INCTHREAD section for each thread found in the result
 137                             set.</t>
 138                 </list></t>
 139
 140                 <t>The THREAD and INCTHREAD return options are mutually exclusive.  Servers MUST return a tagged BAD
 141                     response if a client specifies both return options in a single UID THREAD command.</t>
 142
 143                 <t>Servers MUST use the ESEARCH response instead of the untagged THREAD response when responding to the
 144                     extended form of the UID THREAD command.</t>
 145
 146                 <t>The THREAD and UID THREAD are two distinct commands.  Because clients are not expected to rely on
 147                     transient identifiers like the message sequence numbers for threading retrieval and storage and
 148                     because of the requirement of using UIDs in the INCTHREAD response, no modification to the THREAD
 149                     command is defined.  This might change in future iterations of this draft if client authors express
 150                     sufficient interest.</t>
 151             </section>
 152         </section>
 153
 154         <section title="ESEARCH Extension">
 155             <t>Servers announcing the INCTHREAD capability support two new search return options:</t>
 156
 157             <t><list style="hanging">
 158                     <t hangText="THREAD">Method for conveying the threading information in a form similar to the THREAD
 159                         untagged response.</t>
 160
 161                     <t hangText="INCTHREAD">Response contains the threading information along with the specification of
 162                         a UID of the previous thread root.</t>
 163             </list></t>
 164
 165             <section title="The THREAD ESEARCH Return Value">
 166                 <t>The THREAD return value uses the same format as the threading data in the untagged THREAD responses
 167                     <xref target="RFC5256"/>.  This return value is defined to allow clients to easily match data
 168                     received over network with the tag of the command which caused them, as per the usual ESEARCH
 169                     rules.</t>
 170                 <t>Due to the rules of <xref target="RFC4466"/>, the <xref target="RFC5256"/>-styled response is
 171                     enclosed in one extra pair of parentheses when returned as ESEARCH data.  As an example, threading
 172                     data (1)(2 3) are encoded as ((1)(2 3)) when sent in the THREAD ESEARCH response.</t>
 173             </section>
 174
 175             <section title="The INCTHREAD ESEARCH Return Value">
 176                 <t>The INCTHREAD return value consists of "previous thread root UID" followed by "threading response
 177                     containing a single thread".  The UID of the previous thread root MUST be zero if the thread sorts
 178                     first in the resulting list of threads.  The tuple is enclosed in parentheses to conform to <xref
 179                         target="RFC4466"/>.</t>
 180
 181                 <t>A dedicated INCTHREAD record MUST be present for each thread contained in the result set.</t>
 182
 183                 <section title="Processing Incremental Threading Updates">
 184                     <t>At first, the client removes any messages referenced in the received INCTHREAD response from its
 185                         thread mapping.  This step is crucial to allow new arrivals joining previously independent
 186                         threads together.</t>
 187
 188                     <t>In the second step, the client extracts the threading information from the received INCTHREAD
 189                         response.  The threading data is parsed as in <xref target="RFC5256"/> and the newly formed
 190                         thread is inserted just behind a thread whose root message has UID specified in the "uid"
 191                         argument of the INCTHREAD response.</t>
 192
 193                     <t>If non-zero, the UID of the previous thread root message MUST refer to the previous thread in a
 194                         mapping which contains all messages from a mailbox.  In particular, no matter what additional
 195                         searching criteria the client has used, the previous thread MUST always be identified without
 196                         any search criteria being applied.</t>
 197
 198                     <t>If the client supports incremental threading, the INCTHREAD blocks of an ESEARCH response MUST be
 199                         processed in order.  In particular, inserting the newly formed threads to a proper location
 200                         shall happen immediately when the new thread is created because the subsequent responses COULD
 201                         refer to the root message of the just-inserted thread.</t>
 202
 203                     <t>If the UID is said to be zero (0), it is interpreted specially to mean that the newly formed
 204                         thread is the very first one among the list of threads in the mailbox.  Servers MUST NOT send a
 205                         number which does not refer to any thread root UID unless the number is 0 to indicate the very
 206                         first thread.</t>
 207
 208                     <t>Clients MUST deal with servers sending a UID which does not refer to any thread root or any
 209                         message in the mailbox.  Is is implementation-defined at which position such thread shall be
 210                         inserted, but the thread MUST appear in the list of threads.</t>
 211                 </section>
 212             </section>
 213         </section>
 214
 215         <section title="New Capabilities">
 216             <t>This document adds two new IMAP capabilities, the ETHREAD and INCTHREAD.</t>
 217
 218             <t>Servers announcing the ETHREAD capability support the extended UID THREAD command syntax and the THREAD
 219                 return option.</t>
 220
 221             <t>Servers supporting the INCTHREAD capability MUST support and announce the ETHREAD capability as well.</t>
 222         </section>
 223     </section>
 224
 225     <section title="Examples">
 226         <t>This section contains a few examples to illustrate how the INCTHREAD extension operates.</t>
 227
 228         <section title="General Mode of Operation">
 229             <t>Using the proposed extension, a typical communication between two compliant IMAP protocol speakers might
 230                 look like the following:</t>
 231
 232             <figure align="center">
 233                 <artwork align="left"><![CDATA[
 234 S: * 666 EXISTS
 235 C: x1 UID FETCH 665:* (FLAGS)
 236 S: * 666 FETCH (UID 1666 FLAGS ())
 237 S: x1 OK fetched
 238 C: x2 UID THREAD RETURN (INCTHREAD) REFS utf-8
 239       INTHREAD REFS 666
 240 S: * ESEARCH (TAG "x2") UID INCTHREAD (400
 241       (600 601 (640 666)(602 603)))
 242 S: x2 OK sent]]></artwork>
 243             </figure>
 244
 245             <t>The actual resulting message threading looks like the following:</t>
 246             <figure align="center">
 247                 <artwork align="left"><![CDATA[
 248 ...
 249  |
 250  | (All preceding threads are simply skipped.)
 251  |
 252  +-- 400
 253  |    +-- ...
 254  | (No data for the previous thread besides its root node is sent.)
 255  |
 256  +-- 600
 257  |    +-- 601
 258  |         +-- 640
 259  |         |    +-- 666  <-- the new arrival
 260  |         +-- 602
 261  |              +-- 603
 262  |
 263 ... (No data about any subsequent threads is included in the response.)]]></artwork>
 264             </figure>
 265         </section>
 266
 267         <section title="Inserting a Single Message">
 268             <t>Consider the following threading for a mailbox:</t>
 269
 270             <figure align="center">
 271                 <artwork align="left"><![CDATA[
 272 C: x1 UID THREAD (RETURN THREAD) REFS utf-8 ALL
 273 S: * ESEARCH (TAG "x2") UID THREAD ((1)(2)(3)(4))
 274 S: x1 OK Threading sent]]></artwork>
 275             </figure>
 276
 277             <t>Such a response corresponds to the following threading:</t>
 278             <figure align="center">
 279                 <artwork align="left"><![CDATA[
 280  +-- 1
 281  +-- 2
 282  +-- 3
 283  +-- 4]]></artwork>
 284             </figure>
 285
 286             <t>A new message arrives and the client asks for the reading information:</t>
 287             <figure align="center">
 288                 <artwork align="left"><![CDATA[
 289 S: * 5 EXISTS
 290 S: * 5 FETCH (UID 5)
 291 C: x2 UID THREAD (RETURN INCTHREAD) REFS utf-8 INTHREAD REFS UID 5
 292 S: * ESEARCH (TAG "x2") UID INCTHREAD (2 (3 5))
 293 S: x2 OK Threading sent]]></artwork>
 294             </figure>
 295
 296             <t>The updated threading information should look like the following:</t>
 297             <figure align="center">
 298                 <artwork align="left"><![CDATA[
 299  +-- 1
 300  +-- 2
 301  +-- 3
 302  |   +-- 5
 303  +-- 4]]></artwork>
 304             </figure>
 305
 306             <t>In this case, the thread with thread root with UID 4 is still considered "fresher" by the selected thread
 307                 algorithm.</t>
 308             <!--t><vspace blankLines="1"/></t-->
 309         </section>
 310
 311         <section title="Joining Threads">
 312             <t>The following example shows a more complicated scenario where independent threads are joined together.
 313                 This illustrates the need for clients to remove the referenced messages from their thread mapping:</t>
 314             <figure align="center">
 315                 <artwork align="left"><![CDATA[
 316 C: x1 UID THREAD (RETURN THREAD) REFS utf-8 ALL
 317 S: * ESEARCH (TAG "x2") UID THREAD ((1 2)(3 4)(5))
 318 S: x1 OK Threading sent]]></artwork>
 319             </figure>
 320
 321             <t>Such a response corresponds to the following threading:</t>
 322             <figure align="center">
 323                 <artwork align="left"><![CDATA[
 324  +-- 1
 325  |   +-- 2
 326  +-- 3
 327  |   +-- 4
 328  +-- 5]]></artwork>
 329             </figure>
 330
 331             <t>A new response arrives, joining the first two threads in the mailbox together:</t>
 332              <figure align="center">
 333                 <artwork align="left"><![CDATA[
 334 S: * 6 EXISTS
 335 S: * 6 FETCH (UID 6)
 336 C: x2 UID THREAD (RETURN INCTHREAD) REFS utf-8 INTHREAD REFS UID 6
 337 S: * ESEARCH (TAG "x2") UID INCTHREAD (0 (6 (1 2)(3 4)))
 338 S: x2 OK Threading sent]]></artwork>
 339             </figure>
 340
 341             <t>The newly formed thread remains at the beginning of a mailbox:</t>
 342             <figure align="center">
 343                 <artwork align="left"><![CDATA[
 344  +-- 6           <-- new arrival
 345  |   +-- 1       <-- previous thread #1
 346  |   |   +-- 2
 347  |   +-- 3       <-- previous thread #2
 348  |       +-- 4
 349  +-- 5           <-- previous thread #3 remains as a standalone thread]]></artwork>
 350             </figure>
 351         </section>
 352
 353     </section>
 354
 355     <section anchor="Acknowledgements" title="Acknowledgements">
 356         <t>This extension builds upon the SEARCH=INTHREAD extension <xref target="I-D.ietf-morg-inthread"/> and the
 357             THREAD extension <xref target="RFC5256"/>.</t>
 358     </section>
 359
 360     <section anchor="IANA" title="IANA Considerations">
 361       <t>IMAP4 capabilities are registered by publishing a standards track or IESG approved experimental RFC.  The
 362           registry is currently located at:</t>
 363       <t>http://www.iana.org/assignments/imap4-capabilities</t>
 364       <t>This document defines the ETHREAD and INCTHREAD IMAP capabilities.  IANA will be asked to add these capability
 365           to the registry.</t>
 366     </section>
 367
 368     <section title="Formal Syntax">
 369         <t>The following syntax specification uses the Augmented Backus-Naur
 370             Form (ABNF) notation as specified in <xref target="RFC5234"/>.</t>
 371
 372         <t>Non-terminals referenced but not defined below are as defined by <xref target="RFC3501"/>, <xref
 373                 target="RFC4466"/>, <xref target="RFC4731"/>, or <xref target="RFC5256"/>.</t>
 374
 375         <figure align="center">
 376             <artwork align="left" type="abnf"><![CDATA[
 377 capability          =/ "ETHREAD" / "INCTHREAD"
 378     ;; <capability> from [RFC3501]
 379
 380 modifier-ethread    = "THREAD"
 381
 382 modifier-incthread  = "INCTHREAD"
 383
 384 thread-return-opt   = modifier-thread / modifier-incthread
 385     ;; Similar to <search-return-opt> from [RFC4466]
 386
 387 ret-data-thread     = "THREAD" [SP "(" 1*thread-list ")" ]
 388     ;; <thread-list> from [RFC5256]
 389
 390 ret-data-incthread  = "INCTHREAD" SP "(" uid SP thread-list ")"
 391     ;; <uid> from [RFC3501]
 392     ;; <thread-list> from [RFC5256]
 393
 394 search-return-data  =/ ret-data-thread / ret-data-incthread
 395     ;; <search-return-data> from [RFC4466]
 396
 397 thread              =/ "UID" SP "THREAD" [thread-return-opts]
 398                        SP thread-alg SP search-criteria
 399     ;; <thread> and <thread-alg> from [RFC5256]
 400     ;; <search-criteria> from [RFC3501] as amended by
 401     ;;   [I-D.ietf-morg-inthread]
 402     ;;
 403     ;; The thread-return-opts MUST contain exactly one of
 404     ;;   modifier-thread or modifier-incthread
 405
 406 thread-return-opts  = SP "RETURN" SP "(" [thread-return-opt
 407                       *(SP thread-return-opt)] ")"
 408     ;; similar to the <search-return-opts> from [RFC4466]
 409
 410 ]]></artwork>
 411         </figure>
 412     </section>
 413
 414     <section anchor="Security" title="Security Considerations">
 415         <t>This document is believed to not have any security implications besides those already implied by <xref
 416                 target="RFC5256"/> and <xref target="I-D.ietf-morg-inthread"/>.</t>
 417     </section>
 418   </middle>
 419
 420   <back>
 421     <references title="Normative References">
 422       &RFC2119;
 423
 424       &RFC5234;
 425
 426       &RFC3501;
 427
 428       &RFC4466;
 429
 430       &RFC4731;
 431
 432       &RFC5256;
 433
 434       &DRAFT-inthread;
 435     </references>
 436
 437     <references title="Informative References">
 438       &RFC5267;
 439     </references>
 440
 441     <section anchor="changelog" title="Changelog">
 442         <section title="Changes in -02 since -01">
 443             <t><list style="symbols">
 444                 <t>Enclose the ESEARCH response data in parentheses to conform with RFC4466.
 445                    Thanks to Alexey Melnikov for his review.</t>
 446             </list></t>
 447         </section>
 448         <section title="Changes in -01 since -00">
 449             <t><list style="symbols">
 450                 <t>Added some clarifications that each INCTHREAD block MUST be processed immediately because the
 451                     subsequent block might refer to its results</t>
 452             </list></t>
 453         </section>
 454     </section>
 455   </back>
 456 </rfc>