ietf-nntp draft-ietf-nntpext-base-19

[Clive D.W. Feather]

Ken Murchison said:
> I had some time to sift through the latest draft while in the air:
> 
> 3.2.1:  The discussion of response codes for optional commands/variants 
> is confusing/contradictory.  In paragraph 2, it says that 500 MUST be 
> returned.  Paragraph 3 says that 501 MUST be returned.  The end of 
> paragraph 4 says that 500, 501 or 503 MAY be returned.  Which is it?

Existing wording in 3.1:

    Commands may have variants, using a second keyword immediately
    after the first to indicate which variant is required.  The only
    such commands in this specification are LIST and MODE.

to which I have appended:

    Note that such variants are sometimes referred to as if they were
    commands in their own right:  "the LIST ACTIVE" command should be
    read as shorthand for "the ACTIVE variant of the LIST command".

The idea is that 500 means "I don't understand the first word" while 501
means "I understand the first word but not the second". I thought the
wording in paragraph 3 was clear enough and, if not, the examples should
be. However, I've amended it to end:

    Note that where a command has variants depending on a second keyword
    (e.g. LIST ACTIVE and LIST NEWSGROUPS), then 501 MUST be used when
    the requested variant is not implemented but the base command is
    and 500 MUST only be used when the base command itself is not
    implemented.

The paragraph 4 wording matches existing practice, though I've added "as
appropriate" after "500 or 501". The particular problem is with LIST, where
the original implementation was - I believe - to return the contents of the
named file. So you get two common situations:

(1) The server "knows" that "LIST HEADERS" is not a valid option and just
returns 501 without further analysis.

(2) The server responds to "LIST HEADERS" by attempting to open the file
/var/lib/nntp/list.headers.content; if this fails, it returns its generic
"can't get the data" response of 503.

I don't believe we can pick one or the other, though the list may want to
debate it.

> 5.2.2:  This says that MODE READER should be used before using any 
> extensions advertised by LIST EXTENSIONS.  Well, some of those 
> extensions may not be reader-type commands, eg. CHECK/TAKETHIS.  I'd 
> suggest that the text be changed to say "or any reader-only commands 
> advertised via LIST EXTENSIONS".

You're misreading that text, though I can see why. It actually means the
opposite: "a command advertised by the server as available via LIST
EXTENSIONS" is meant to be the last entry in the list that begins "IHAVE".

New wording for 5.2.2:

    MODE READER SHOULD be sent by any client that intends to use any
    command in this specification (excluding section 8) other than
    IHAVE, HEAD, STAT, LIST ACTIVE, or LIST EXTENSIONS.  Servers MAY
    require that this command be issued before any commands other than
    the above are sent and MAY reject such commands until after a MODE
    READER command has been sent.

    Once MODE READER is sent, IHAVE (and any related extensions) MAY
    no longer be permitted, even if it were permitted before the MODE
    READER command.  The results of LIST EXTENSIONS MAY be different
    following a MODE READER command than prior to the issuing of that
    command.

    At all points in the session those commands currently listed by
    LIST EXTENSIONS must be available.  Therefore, if a command defined
    by an extension (including those in section 8) is only available
    before or after a MODE READER command, or if the effects of the
    extension will be changed by the command, the LIST EXTENSIONS
    command MUST produce different results that indicate the differences.

    The server MUST return a response using the same codes as the
    initial greeting (as described in section 5.1.1) to indicate its
    ability to provide reading service to the client.  Note that the
    response need not be the same as the one presented during the
    initial greeting.

    Servers are encouraged to not require this command even though
    clients SHOULD send it when appropriate.  It is present to support
    some news architectures that switch between modes based on whether
    a given connection is a peer-to-peer connection with another server
    or a news reading client.

Clearer?

> I'd also suggest that section 8 
> require that an extension discuss its behavior w.r.t MODE READER -- 
> whether it SHOULD be sent by the client before using the given extension 
> command(s).

Agreed and done.

> 8.6.1.1:  Just for consistency, the usage section should probably be 
> changed to use the same format as ARTICLE/HEAD/BODY/STAT/OVER, eg. only 
> two forms:
> 
>   HDR message-id
>   HDR [range]

Actually, I think it's better to change the former to match HDR; it saves
weasel-footnotes (which turned out to be incomplete) about which response
can happen when.

> 8.6.2.1:  Is LIST HEADERS optional or required?  I don't care either way 
> (especially if the server advertises HDR ALL), but since LIST 
> OVERVIEW.FMT is optional, I had to ask.

It's required if the extension is provided at all.

All optional commands are explicitly indicated and all remaining commands
are required. Within an extension, this applies if the extension is
provided; if it isn't, the commands are forbidden.

> 8.6.2.3:  The last example uses the :article-number metadata type. 
> Since this isn't documented anywhere, this should either be removed or 
> changed to :x-article-number.

I suppose that would be good practice, though it's not actually required.
I will do so.

> 9.1:  LIST HEADERS is missing from the grammar and over-command should 
> be changed to "OVER" [range-ref] since it now accepts a message-id as an 
> argument.

/me kicks self.

Thanks for the comments.

-- 
Clive D.W. Feather  | Work:  <clive at demon.net>   | Tel:    +44 20 8495 6138
Internet Expert     | Home:  <clive at davros.org>  | *** NOTE CHANGE ***
Demon Internet      | WWW: http://www.davros.org | Fax:    +44 870 051 9937
Thus plc            |                            | Mobile: +44 7973 377646