Subject: [NNTP] Multi-line blocks

From: "Clive D.W. Feather" <[email-masked]>
Date: Mon, 11 Apr 2005 16:58:10 +0100

I received a private email the other day pointing out some wording
inconsistencies in draft 25. Having thought about it, I've decided to
invent a new term "multi-line data block" and rephrase other places to use
it. Here's the significant diffs - scream now or forever hold your peace.

[Near the end of section 3.1:]

========
    Each response MUST start with a three-digit response code that is
    sufficient to distinguish all responses.  Certain valid responses are
    defined to be multi-line; for all others, the response is contained
-   in a single line.  The first or only line of the response MUST NOT
-   exceed 512 octets, which includes the response code and the
-   terminating CRLF pair; an extension MAY specify a greater maximum for
-   commands that it defines, but not for any other command.
+   in a single line.  The initial line of the response MUST NOT exceed
+   512 octets, which includes the response code and the terminating CRLF
+   pair; an extension MAY specify a greater maximum for commands that it
+   defines, but not for any other command.  Single-line responses
+   consist of an initial line only.  Multi-line responses consist of an
+   initial line followed by a multi-line data block.
 
+   An NNTP server MAY have an inactivity autologout timer.  Such a timer
+   SHOULD be of at least three minutes duration, with the exception that
+   there MAY be a shorter limit on how long the server is willing to
+   wait for the first command from the client.  The receipt of any
+   command from the client during the timer interval SHOULD suffice to
+   reset the autologout timer.  Similarly, the receipt of any
+   significant amount of data from a client that is sending a multi-line
+   data block (such as during a POST or IHAVE command) SHOULD suffice to
+   reset the autologout timer.  When the timer expires, the server
+   SHOULD close the connection without sending any response to the
+   client.
+
+3.1.1  Multi-line data blocks
 
-   All multi-line responses MUST adhere to the following format:
+   A multi-line data block is used in certain commands and responses.
+   It MUST adhere to the following rules:
+
-   1.  The response consists of a sequence of one or more "lines", each
+   1.  The block consists of a sequence of one or more "lines", each
        being a stream of octets ending with a CRLF pair.  Apart from
        those line endings, the stream MUST NOT include the octets NUL,
        LF, or CR.
 
-   2.  The first such line contains the response code as with a single
-       line response.
+   2.  In a multi-line response, the block immediately follows the CRLF
+       at the end of the initial line of the response.  When used in any
+       other context, the specific command will define when the block is
+       sent.

-   3.  If any subsequent line begins with the "termination octet" ("."
-       or %x2E), that line MUST be "byte-stuffed" by pre-pending an
-       additional termination octet to that line of the response.
+   3.  If any line of the data block begins with the "termination octet"
+       ("." or %x2E), that line MUST be "byte-stuffed" by pre-pending an
+       additional termination octet to that line of the block.
 
-   4.  The lines of the response MUST be followed by a terminating line
+   4.  The lines of the block MUST be followed by a terminating line
        consisting of a single termination octet followed by a CRLF pair
-       in the normal way.  Thus a multi-line response is always
-       terminated with the five octets CRLF "." CRLF (%x0D.0A.2E.0D.0A).
+       in the normal way.  Thus a multi-line block is always terminated
+       with the five octets CRLF "." CRLF (%x0D.0A.2E.0D.0A).

-   5.  When interpreting a multi-line response, the "byte-stuffing" MUST
-       be undone; i.e. the client MUST ensure that, in any line
+   5.  When interpreting a multi-line block, the "byte-stuffing" MUST be
+       undone; i.e. the recipient MUST ensure that, in any line
        beginning with the termination octet followed by octets other
        than a CRLF pair, that initial termination octet is disregarded.
 
    6.  Likewise, the terminating line ("." CRLF or %x2E.0D.0A) MUST NOT
-       be considered part of the multi-line response; i.e. the client
+       be considered part of the multi-line block; i.e. the recipient
        MUST ensure that any line beginning with the termination octet
        followed immediately by a CRLF pair is disregarded; (the first
        CRLF pair of the terminating CRLF "." CRLF is, of course, part of
-       the last line of the response).
+       the last line of the block).
 
    Note that texts using an encoding (such as UTF-16 or UTF-32) that may
    contain the octets NUL, LF, or CR other than a CRLF pair cannot be
    reliably conveyed in the above format (that is, they violate the MUST
    requirement above).  However, except when stated otherwise, this
    specification does not require the content to be UTF-8 and therefore
    (subject to that same requirement) it MAY include octets above and
    below 128 mixed arbitrarily.
 
-   This document does not place any limit on the length of a subsequent
-   line in a multi-line response.  However, the standards that define
-   the format of articles may do so.
+   This document does not place any limit on the length of a line in a
+   multi-line block.  However, the standards that define the format of
+   articles may do so.
-
-   An NNTP server MAY have an inactivity autologout timer.  Such a timer
-   SHOULD be of at least three minutes duration, with the exception that
-   there MAY be a shorter limit on how long the server is willing to
-   wait for the first command from the client.  The receipt of any
-   command from the client during the timer interval SHOULD suffice to
-   reset the autologout timer.  Similarly, the receipt of any
-   significant amount of data from the client while in the midst of
-   sending a multi-line message to the server (such as during a POST or
-   IHAVE command) SHOULD suffice to reset the autologout timer.  When
-   the timer expires, the server SHOULD close the connection without
-   sending any response to the client.
 
 3.2  Response Codes
 
[...]

    Certain responses contain arguments such as numbers and names in
    addition to the status indicator.  In those cases, to simplify
    interpretation by the client the number and type of such arguments is
-   fixed for each response code, as is whether or not the code
-   introduces a multi-line response.  Any extension MUST follow this
-   principle as well.  Note that, for historical reasons, the 211
-   response code is an exception to this in that the response may be
-   multi-line or not depending on the command (GROUP or LISTGROUP) that
+   fixed for each response code, as is whether or not the code is
+   single-line or multi-line.  Any extension MUST follow this principle
+   as well.  Note that, for historical reasons, the 211 response code is
+   an exception to this in that the response may be single-line or
+   multi-line depending on the command (GROUP or LISTGROUP) that
    generated it.  In all other cases, the client MUST only use the
    status indicator itself to determine the nature of the response.  The
    exact response codes that can be returned by any given command are
========

Many changes along the lines of:

========
-   The capability list is returned as a multi-line response following
+   The capability list is returned as a multi-line data block following
    the 101 response code.  Each capability is described by a separate
    capability line.
========
and
========
-   If the information is available, it is returned as a multi-line
-   response following the 225 response code and contains one line for
-   each article in the range that exists (note that unless the argument
-   is a range including a dash, there will be at most one line but it
-   will still be in multi-line format).  The line consists of
[...]
+   If the information is available, it is returned as a multi-line data
+   block following the 225 response code and contains one line for each
+   article in the range that exists (note that unless the argument is a
+   range including a dash, there will be at most one line in the data
+   block).  The line consists of
[...]
========

I've consistently used "multi-line" and not "multiline"; this has involved
scattered changes.
 
In POST:
 
========
 
-   If posting is permitted, the article MUST be in the format specified
-   in Section 3.6 and MUST be sent by the client to the server in the
-   manner specified (in Section 3.1) for multi-line responses (except
-   that there is no initial line containing a response code).  Thus a
-   single dot (".") on a line indicates the end of the text, and lines
-   starting with a dot in the original text have that dot doubled during
-   transmission.
+   If posting is permitted, the article MUST be in the format specified
+   in Section 3.6 and MUST be sent by the client to the server as a
+   multi-line data block (see Section 3.1.1).  Thus a single dot (".")
+   on a line indicates the end of the text, and lines starting with a
+   dot in the original text have that dot doubled during transmission.
 
========

In IHAVE:
 
========
 
-   If transmission of the article is requested, the client MUST send the
-   entire article, including headers and body, in the format defined
-   above (Section 3.1) for multi-line responses (except that there is no
-   initial line containing a response code).  Thus a single dot (".") on
-   a line indicates the end of the text, and lines starting with a dot
-   in the original text have that dot doubled during transmission.  The
+   If transmission of the article is requested, the client MUST send the
+   entire article, including headers and body, to the server as a multi-
+   line data block (see Section 3.1.1).  Thus a single dot (".") on a
+   line indicates the end of the text, and lines starting with a dot in
+   the original text have that dot doubled during transmission.  The
    server MUST return either a 235 response, indicating that the article
    was successfully transferred, a 436 response, indicating that the
    transfer failed but should be tried again later, or a 437 response,
    indicating that the article was rejected.

========

Formal syntax changes:

========
 
-     encoded-article = content-lines termination
+     encoded-article = multi-line-data-block
        ; after undoing the "byte-stuffing", this MUST match <article>
 
[...]
 
-     response = simple-response / multiline-response
+     response = simple-response / multi-line-response
-     simple-response =
-           simple-response-content [SP trailing-comment] CRLF
-     multiline-response = simple-response content-lines termination
+     simple-response = initial-response-line
+     multi-line-response = initial-response-line multi-line-data-block
+     initial-response-line =
+           simple-response-content [SP trailing-comment] CRLF

[...]
 
 9.3.3  Multi-line response contents
 
-   This syntax defines the content of the various multi-line responses
-   (more precisely, the part of the response in <content-lines>), in
-   each case after any "byte-stuffing" has been undone.
+   This syntax defines the content of the various multi-line responses;
+   more precisely, it defines the part of the response in the multi-line
+   data block after any "byte-stuffing" has been undone.

-     multiline-response-content = article-response /
+     multi-line-response-content = article-response /
            body-response /
[...]
 
+     multi-line-data-block = content-lines termination
+     content-lines = *([content-text] CRLF)
+     content-text = (".." / B-NONDOT) *B-CHAR
+     termination = "." CRLF
+
      article-number = 1*16DIGIT
-     content-lines = *([content-text] CRLF)
-     content-text = (".." / B-NONDOT) *B-CHAR
      header-name = 1*A-NOTCOLON
      keyword = ALPHA 2*11(ALPHA / DIGIT / "." / "-")
      message-id = "<" 1*248A-NOTGT ">"
      newsgroup-name = 1*wildmat-exact
-     termination = "." CRLF
      token = 1*P-CHAR
========

-- 
Clive D.W. Feather  | Work:  <[email-masked]>   | Tel:    +44 20 8495 6138
Internet Expert     | Home:  <[email-masked]>  | Fax:    +44 870 051 9937
Demon Internet      | WWW: http://www.davros.org | Mobile: +44 7973 377646
Thus plc            |                            |

---

From: Ken Murchison <[email-masked]>
Date: Mon, 11 Apr 2005 12:33:38 -0400

> it. Here's the significant diffs - scream now or forever hold your peace.

I can live with these changes.  If I don't see any objections over the 
next few days, I'll make any necessary wording changes to the extension 
drafts.

-- 
Kenneth Murchison     Oceana Matrix Ltd.
Software Engineer     21 Princeton Place
716-662-8973 x26      Orchard Park, NY 14127
--PGP Public Key--    http://www.oceana.com/~ken/ksm.pgp

---

From: Russ Allbery <[email-masked]>
Date: Mon, 11 Apr 2005 11:35:41 -0700

Clive D W Feather <[email-masked]> writes:

> invent a new term "multi-line data block" and rephrase other places to
> use it. Here's the significant diffs - scream now or forever hold your
> peace.

I'm fine with that.

-- 
Russ Allbery ([email-masked])             <http://www.eyrie.org/~eagle/>

---

From: [email-masked] (Peter Robinson)
Date: Tue, 12 Apr 2005 23:22:18 +0100

Clive D.W. Feather <[email-masked]> wrote:

> [...] I've decided to invent a new term "multi-line data block" and
> rephrase other places to use it. Here's the significant diffs - scream now
> or forever hold your peace.

I'm slightly worried about making changes to the fundamentals at this
stage.  But it does crystallise a useful concept, so I say do it.
Carefully.

[...]

> +       with the five octets CRLF "." CRLF (%x0D.0A.2E.0D.0A).

The last sentence is not strictly true since an 'empty' multi-line block
consists only of the last three of those octets.

> +       the last line of the block).

And again, that's not strictly true for an empty block.

Regards,

Peter

---

From: "Clive D.W. Feather" <[email-masked]>
Date: Mon, 25 Apr 2005 09:59:52 +0100

> consists only of the last three of those octets.

Good catch. I've changed it to say "Thus, unless it is empty, a ...".

I've also changed "one or more" to "zero or more" in item 1 of that list.

> And again, that's not strictly true for an empty block.

Changed to "... CRLF of a non-empty block is, of course, ...".

Thanks.