ietf-nntp New HDR text (with metadata)

[Russ Allbery]

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

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

  The HDR command retrieves specific headers from an article or specified
  range of articles in the currently selected group or an article
  specified by message-id.  It can also return certain metadata about the
  article or articles.  The required header parameter is the name of a
  header (e.g. "subject") in an article, or the name of a metadata item,
  and is case-insensitive.  Names of metadata items always include a
  colon.

  Except where stated otherwise, metadata items are treated as if they
  were header values, and references to headers in this description
  apply equally to metadata items.

  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 or metadata items.  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) or metadata item.  Header
  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, if any, not the line
  count metadata or any other server-generated value.

  If the header occurs in a given article multiple times, only the value
  of the first occurrence is returned by HDR.

  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 not
  present in the article or if it is present but empty, a line for that
  article is included in the output but the header content portion of the
  line is empty.  If any article number in the provided range does not
  exist in the group, no line for that article number is included in the
  output.

  If the optional argument is a message-id and no such article exists, a
  430 error response shall be returned.  If the optional argument is an
  article number or number range and no article with that number or in
  that number range exists in the current group, a 423 error response
  shall be returned.  If HDR is sent without any arguments and no article
  is currently selected, a 420 error response shall be returned.

  A server MAY only allow HDR commands for a limited set of headers and
  metadata items (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.1  Responses

      225  Headers follow (multiline response)
      412  No newsgroup selected
      420  No article selected
      423  No article with that number
      430  No article with that message ID

9.5.3.1.2  Examples

  Example of a successful retrieval of subject lines from a range of
  articles (3000235 has no Subject header, and 3000236 is missing):

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

  Example of a successful retrieval of line counts from a range of
  articles:

      [S] 200 NNTP Service Ready
      [C] GROUP misc.test
      [S] 211 1234 3000234 3002322 misc.test
      [C] HDR :lines 3000234-300238
      [S] 225 Headers follow
      [S] 3000234 42
      [S] 3000235 5
      [S] 3000237 11
      [S] 3000238 2378
      [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] 225 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] 225 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 an unsuccessful retrieval of headers because the current
  group 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] 423 No articles in that range
      [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/>