ietf-nntp Proposed new HDR text

[Russ Allbery]

This is intended as a way to open a new discussion and give us something
to start from, not as the final text yet.  In particular, I have, for the
time being, dodged the entire issue of metadata and specified a command
that always and exclusively returns the actual values of the headers of
the articles.  I want to get agreement on those portions of the command
first, and then if someone feels so inspired, adding on metadata names
such as :Lines is simple enough.  (I think an argument could be made to
leave HDR alone there and to move forward with the separate HEADERS
extension, which is more flexible.)

Also, for the sake of serving as an example and because I find it clearer,
I've laid out this description along the lines of Clive's new format.
I'll be happy to reformat it into the existing form (or it's easy enough
to do that when it's added to the document) if we decide not to adopt that
format.

I've allowed HDR header without a range or message-id for consistency with
OVER and changed the response code to 225 from 221 to not conflict with
the 221 response from HEAD.  I've also specified that calling HDR on a
message-id returns an article number of 0 and is allowed outside of any
group.  I've also corrected the example that used 0- as a range to use 1-
instead, since that's for all practical purposes equivalent and doesn't
raise questions about whether 0- is a valid range.

I've also added the 503 response for HDR on a header not supported by the
server.  I've not put in any requirement that HDR be supported on any
particular set of headers; we can debate that further if people feel
that's necessary.

And, without further ado, here we go:

9.5.3  The HDR Extension

  This extension provides one new command, HDR.  The label for this
  extension is HDR.

9.5.3.1  HDR

9.5.3.1.1  Usage

  Syntax

      HDR header
      HDR header range
      HDR header <message-id>

  Responses

      225  Headers follow (mutliline response)
      412  No newsgroup selected
      430  No such article

  This command is streamable.

9.5.3.1.2  Description

  The HDR command retrieves specific headers from a specified range of
  articles in the currently selected group or an article specified by
  message-id.

  The required header parameter is the name of a header (e.g. "subject")
  in an article and is case-insensitive.  The range parameter of the
  second form of the HDR command may be any of the following:

   * an article number
   * an article number followed by a dash to indicate all following
   * an article number followed by a dash followed by another article
     number.

  The message-id parameter of the third form of the HDR command indicates
  a specific article.  The range and message-id arguments are mutually
  exclusive.  If neither are specified, information from the current
  article is displayed.

  A successful response consists of a 225 response followed by the
  requested list of headers.  This list is returned as a multiline
  response, with each line consisting of the article number, a US-ASCII
  space, and the contents of the header (without the header name or the
  colon and space that follow it).  The contents are modified as follows:
  all US-ASCII CRLF pairs are removed, and then each remaining US-ASCII
  NUL, TAB, CR, or LF character is replaced with a single US-ASCII space.
  (Note that this is the same transformation as is performed by the OVER
  extension.)

  The header content is in all cases taken from the article.  This means
  that, for example, a request for the header "Lines" returns the contents
  of the "Lines" header of the specified articles, not the Lines field
  returned by the OVER extension or any other server-generated value.

  If the article is specified by message-id rather than by article range,
  the article number is given as "0".  If the requested header is present
  but empty in a given article, a line for that article is included in the
  output but the header content portion of the line is empty.  If the
  requested header is not present in a given article, no line for that
  article is given in the output.  An empty response is therefore valid,
  indicating that the requested header is not present in any of the
  specified articles.

  If the optional argument is a message-id and no such article exists, a
  430 error response shall be returned.

  A server MAY only allow HDR commands for a limited set of headers (such
  as those present in the overview database).  If it does so, it MUST
  respond with a 503 error response to attempts to request other headers
  rather than returning erroneous results such as a successful empty
  response.

9.5.3.1.3  Examples

  Example of a successful retrieval of subject lines from a range of
  articles:

      [S] 200 NNTP Service Ready
      [C] GROUP misc.test
      [S] 211 1234 3000234 3002322 misc.test
      [C] HDR Subject 3000234-300238
      [S] 221 Header Follows
      [S] 3000234 I am just a test article
      [S] 3000237 Re: I am just a test article
      [S] 3000238 Ditto
      [S] .

  Example of a successful retrieval of the subject line from an article by
  message-id:

      [S] 200 NNTP Service Ready
      [C] GROUP misc.test
      [S] 211 1234 3000234 3002322 misc.test
      [C] HDR subject <i.am.a.test.article at example.com>
      [S] 221 Header information follows
      [S] 0 I am just a test article
      [S] .

  Example of a successful retrieval of the subject line from the current
  article:

      [S] 200 NNTP Service Ready
      [C] GROUP misc.test
      [S] 211 1234 3000234 3002322 misc.test
      [C] HDR subject
      [S] 221 Header information follows
      [S] 3000234 I am just a test article
      [S] .

  Example of an unsuccessful retrieval of a header from an article by
  message-id:

      [S] 200 NNTP Service Ready
      [C] HDR subject <i.am.not.there at example.com>
      [S] 430 No Such Article Found

  Example of an unsuccessful retrieval of headers from articles by number
  because no newsgroup was selected first:

      [S] 200 NNTP Service Ready
      [C] HDR subject 300256-
      [S] 412 No newsgroup selected

  Example of retrieving header information when the current group selected
  is empty:

      [S] 200 NNTP Service Ready
      [C] GROUP example.empty.newsgroup
      [S] 211 0 0 0 example.empty.newsgroup
      [C] HDR subject 1-
      [S] 221 Headers follow
      [S] .

  Example of an unsuccessful retrieval of headers because the server does
  not allow HDR commands for that header:

      [S] 200 NNTP Service Ready
      [C] GROUP misc.test
      [S] 211 1234 3000234 3002322 misc.test
      [C] HDR Content-Type 3000234-300238
      [S] 503 HDR not permitted on "Content-Type"

  Example of a failure due to restrictions configured into the server:

      [S] 200 NNTP Service Ready
      [C] GROUP news.group
      [S] 211 1234 3000234 3002322 misc.test
      [C] HDR Subject 3000234-300238
      [S] 502 Service Unavailable

-- 
Russ Allbery (rra at stanford.edu)             <http://www.eyrie.org/~eagle/>