ietf-nntp OVER extension
Clive D.W. Feather
clive at demon.net
Tue Jul 2 05:57:48 PDT 2002
Okay, here's new text. I've been through my mail and applied all the issues
I can find.
NNTP proposed text
9.5.2 The OVER Extension
Last changed 2002-07-02 13:00 UTC
There was a suggestion that OVER could take a message-ID. This would need
to be optional; to allow it, include the lines prefixed with $, while to
forbid it exclude those lines.
After further thought, I've decided that it's better to include a generic
metadata description, even if it isn't used very much.
[I'm not sure where this first bit best fits.]
X.X Article metadata
Some commands in this memo refer to "article metadata". This is
data about articles that does not occur within the article itself.
Each metadata item has a name, which must include at least one colon
other than at the end. Note that a historical feature of the
LIST OVERVIEW.FMT command means that metadata names SHOULD NOT end
with ":full".
When generating a metadata item, the server MUST compute it for itself
and not trust any related value provided in the article. [In particular,
a Lines: or Bytes: header in the article MUST NOT be assumed to specify
the correct value.]
This memo defines two metadata items: "line:count" and "byte:count".
X.X.1 The line:count metadata item
The line:count metadata item for an article is a decimal integer.
It is the number of lines in the article body (excluding the blank
line separating headers and body); equivalently, it is two less than
the number of US-ASCII CRLF pairs that the BODY command would return
for that article (the extra two are those following the response code
and the termination octet).
X.X.2 The byte:count metadata item
The byte:count metadata item for an article is a decimal integer.
It is the number of bytes in the entire article - both headers, body,
and separating blank line - except that the US-ASCII CRLF at the end
of each line counts as one byte, not two.
9.5.2 The OVER Extension
This extension provides two commands, OVER and LIST OVERVIEW.FMT. The
label for this extension is OVER. If the extension is implemented then
both commands MUST be provided.
The OVER extension provides access to a database of header lines
extracted from incoming articles. Only certain headers are included
in the database. The database also includes some article metadata.
The information stored in the database may change over time. The
LIST OVERVIEW.FMT command describes the information that would be
stored for an article arriving at the same time as the command was
executed.
9.5.2.1 OVER
OVER [range]
$ OVER <message-id>
The OVER command returns the contents of the headers and metadata in
the database for the article(s) specified from the current selected
group.
The optional range argument may be any of the following:
o an article number
o an article number followed by a dash to indicate all
following
o an article number followed by a dash followed by another
article number
If no argument is specified, then information from the current article
is displayed. Successful responses start with a 224 response followed
by the overview information for all matched messages. This is a multiline
response with one line per article. A 412 error response is returned if
no newsgroup is currently selected and a 420 error response if no article
is selected in the current newsgroup. A 423 error response is returned if
there are no articles in the indicated range.
For a successful response, the returned information consists of one line
per article, sorted in numerical order of article number. Each line
consists of a number of fields separated by an US-ASCII TAB character.
A field may be empty (in which case there will be two adjacent US-ASCII
TABs), and a sequence of trailing US-ASCII TABs may be omitted.
The first 8 fields MUST be the following, in order:
article number
"Subject" header
"From" header
"Date" header
"Message-ID" header
"References" header
byte:count metadata item
line:count metadata item
Any subsequent fields are the contents of the other headers and metadata
held in the database.
For the five mandatory headers, the content of each field MUST be
based on the original header with the header name and following colon
and space removed. If the article does not contain that header, or if
there is nothing following the colon and space, the field MUST be
empty. For the two mandatory metadata items, the content of the field
MUST be just the value, with no other text.
For all subsequent fields that contain headers, the content MUST be
based on the entire header including the name. For all subsequent
fields that contain metadata, the field consists of the metadata name,
a single US-ASCII space, and then the value.
For all fields, the value is processed by first removing all US-ASCII
CRLF pairs and then replacing each remaining US-ASCII NUL, TAB, CR, or
LF character with a single US-ASCII space (for example, CR LF LF TAB
will become two spaces). If there is no such header in the article,
or no such metadata item, or no header or item stored in the database
for that article, the corresponding field MUST be empty.
$ A server MAY, but is not required to, support the second form of the
$ command, specifying a message-ID. If it does, no newsgroup need be
$ selected and the article number in the output is replaced by "0".
The server SHOULD NOT produce output for articles that no longer
exist.
9.5.2.1.1 Responses
$ First form (optional range specified):
224 Overview information follows (multi-line response)
412 No newsgroup currently selected
423 No article(s) selected
plus generic responses 400, 401, 403, 500, 501, 502, 503
$ Second form (message-ID specified):
$
$ 224 Overview information follows (multi-line response)
$ 430 No article found with that message-id
$
$ plus generic responses 400, 401, 403, 500, 501, 502, 503
9.5.2.1.2 Examples
Please note that, in these examples, US-ASCII TAB has been replaced
by vertical bar and that some lines have been folded for readability
(shown by ++ in the left margin).
Example of a successful retrieval of overview information for an
article (using no article number)
[S] 200 NNTP Service Ready
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] OVER
[S] 224 Overview information follows
[S] 3000234|I am just a test article|nobody at nowhere.to
++ (Demo User)|6 Oct 1998 04:38:40 -0500|<45223423 at to.to>||
++ 4822|37|Distribution: uk
[S] .
Example of a successful retrieval of overview information for a
range of articles
[S] 200 NNTP Service Ready
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] OVER 3000234-3000240
[S] 224 Overview information follows
[S] 3000234|I am just a test article|nobody at nowhere.to
++ (Demo User)|6 Oct 1998 04:38:40 -0500|<45223423 at to.to>||
++ 4822|37|Distribution: uk
[S] 3000235|Another test article|nobody at nowhere.to
++ (Demo User)|6 Oct 1998 04:38:45 -0500|<45223425 at to.to>||
++ 4818|37|Distribution: fi
[S] 3000238|Re: I am just a test article|somebody at elsewhere.to|
++ 7 Oct 1998 11:38:40 +1200|<kfwer3v at elsewhere.to>|
++ <45223423 at to.to>|9234|51
[S] .
Note the missing "References" header in the first two lines, the
missing trailing field in the last line, and that there are only
results for those articles that still exist.
$ Example of a successful retrieval of overview information for an
$ article (using the message-ID)
$
$ [S] 200 NNTP Service Ready
$ [C] OVER <45223423 at to.to>
$ [S] 224 Overview information follows
$ [S] 0|I am just a test article|nobody at nowhere.to (Demo User)|
$ ++ 6 Oct 1998 04:38:40 -0500|<45223423 at to.to>||4822|37|
$ ++ Distribution: uk
$ [S] .
Example of an unsuccessful retrieval of overview information on an
article by number
[S] 200 NNTP Service Ready
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] OVER 300256
[S] 423 No such article in this group
Example of an unsuccessful retrieval of overview information by number
because no newsgroup was selected first
[S] 200 NNTP Service Ready
[C] OVER
[S] 412 No newsgroup selected
Example of an attempt to retrieve an article 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] OVER
[S] 420 No current article selected
9.5.2.2 LIST OVERVIEW.FMT
LIST OVERVIEW.FMT
The LIST OVERVIEW.FMT command returns a description of the fields in
the database. The fields MUST be listed in the order that they will
be returned by the OVER command for a newly-received article (the
information stored for articles may change over time).
If the command is successful, the description is returned as a multi-line
response following a 215 response code, one line per field. The first 7
lines MUST be exactly:
Subject:
From:
Date:
Message-ID:
References:
byte:count
line:count
except that, for compatibility with existing implementations, the last
two lines MAY instead be:
Bytes:
Lines:
even though they refer to metadata, not headers.
All subsequent lines MUST consist of either a header name followed by
":full", or the name of a piece of metadata.
There are no leading or trailing spaces in the output.
Note: the 7 fixed lines describe the 2nd to 8th fields of the OVER
output. The "full" suffix is a reminder that the corresponding fields
include the header name.
This command MAY generate different results if used more than once in
a session.
9.5.2.2.1 Responses
215 Information follows (multi-line response)
plus generic responses 400, 401, 403, 501, 502, 503
9.5.2.2.2 Examples
Example of LIST OVERVIEW.FMT output corresponding to the example
OVER output above, using the preferred format:
[S] 200 NNTP Service Ready
[C] LIST OVERVIEW.FMT
[S] 215 Order of fields in overview database.
[S] Subject:
[S] From:
[S] Date:
[S] Message-ID:
[S] References:
[S] byte:count
[S] line:count
[S] Distribution:full
[S] .
Example of LIST OVERVIEW.FMT output corresponding to the example
OVER output above, using the alternative format:
[S] 200 NNTP Service Ready
[C] LIST OVERVIEW.FMT
[S] 215 Order of fields in overview database.
[S] Subject:
[S] From:
[S] Date:
[S] Message-ID:
[S] References:
[S] Bytes:
[S] Lines:
[S] Distribution:full
[S] .
--
Clive D.W. Feather | Work: <clive at demon.net> | Tel: +44 20 8371 1138
Internet Expert | Home: <clive at davros.org> | Fax: +44 870 051 9937
Demon Internet | WWW: http://www.davros.org | Mobile: +44 7973 377646
Thus plc | | NOTE: fax number change
More information about the ietf-nntp
mailing list