Subject: progress on Issue 137

From: Julian Reschke <[email-masked]>
Date: Thu, 17 Feb 2011 17:27:28 +0100

Hi,

<http://trac.tools.ietf.org/wg/httpbis/trac/ticket/137> is one of these 
TODOs that are left-overs from splitting RFC 2616 into multiple pieces.

RFC 2616 did use ABNF not only to define parsing, but also to define 
legal values, such as method names, status codes, and header field names.

This doesn't make a lot of sense, as parsing a message into components 
and acting upon specific values are separate activities. So the goal is 
that the ABNF in Part 1 fully defines how to parse messages, and doesn't 
have references to other parts.

This left us with strange constructs like the Status-Code/Reason-Phrase 
ABNF appearing in both parts; in P1 just saying "3DIGIT", but in P2 
enumerating all of "our" status codes, plus an ABNF rule for extension 
codes.

(Similar problems exist for header field names and method names, btw.)

So, to resolve issue 137, I did the following changes in 
<http://trac.tools.ietf.org/wg/httpbis/trac/changeset/1124>:

- Made the ABNFs for Status-Code and Reason-Phrase identical to P1; note 
that their consistency is checked when we build the spec. It could be 
argued that those ABNF rules should only occur once; feedback appreciated.

- Consequently, as the enumeration of status-codes isn't in the ABNF 
anymore, I moved it into a non-normative "Overview" table. One could 
argue that it's not needed; but it's probably useful to easier find 
status code definitions, now that they are spread across multiple documents.

- Also, I removed some redundancy from the prose.

The new intro to Section 4, with the new subsection 4.1 now reads...:

-- snip --
4.  Status Code and Reason Phrase

    The Status-Code element is a 3-digit integer result code of the
    attempt to understand and satisfy the request.

    The Reason-Phrase is intended to give a short textual description of
    the Status-Code and is intended for the human user.  The client is
    not required to examine or display the Reason-Phrase.

      Status-Code    = 3DIGIT
      Reason-Phrase  = *( WSP / VCHAR / obs-text )

    HTTP status codes are extensible.  HTTP applications are not required
    to understand the meaning of all registered status codes, though such
    understanding is obviously desirable.  However, applications MUST
    understand the class of any status code, as indicated by the first
    digit, and treat any unrecognized response as being equivalent to the
    x00 status code of that class, with the exception that an
    unrecognized response MUST NOT be cached.  For example, if an
    unrecognized status code of 431 is received by the client, it can
    safely assume that there was something wrong with its request and
    treat the response as if it had received a 400 status code.  In such
    cases, user agents SHOULD present to the user the representation
    enclosed with the response, since that representation is likely to
    include human-readable information which will explain the unusual
    status.

4.1.  Overview of Status Codes

    The status codes listed below are defined in Section 8, Section 3 of
    [Part4], Section 3 of [Part5], and Section 3 of [Part7].  The reason
    phrases listed here are only recommendations -- they can be replaced
    by local equivalents without affecting the protocol.

    +-------------+------------------------------+----------------------+
    | Status-Code | Reason-Phrase                | Defined in...        |
    +-------------+------------------------------+----------------------+
    | 100         | Continue                     | Section 8.1.1        |
    | 101         | Switching Protocols          | Section 8.1.2        |
    | 200         | OK                           | Section 8.2.1        |
    | 201         | Created                      | Section 8.2.2        |
    | 202         | Accepted                     | Section 8.2.3        |
    | 203         | Non-Authoritative            | Section 8.2.4        |
    |             | Information                  |                      |
    | 204         | No Content                   | Section 8.2.5        |
    | 205         | Reset Content                | Section 8.2.6        |
    | 206         | Partial Content              | Section 3.1 of       |
    |             |                              | [Part5]              |
    | 300         | Multiple Choices             | Section 8.3.1        |
    | 301         | Moved Permanently            | Section 8.3.2        |
    | 302         | Found                        | Section 8.3.3        |
    | 303         | See Other                    | Section 8.3.4        |
    | 304         | Not Modified                 | Section 3.1 of       |
    |             |                              | [Part4]              |
    | 305         | Use Proxy                    | Section 8.3.6        |
    | 307         | Temporary Redirect           | Section 8.3.8        |
    | 400         | Bad Request                  | Section 8.4.1        |
    | 401         | Unauthorized                 | Section 3.1 of       |
    |             |                              | [Part7]              |
    | 402         | Payment Required             | Section 8.4.3        |
    | 403         | Forbidden                    | Section 8.4.4        |
    | 404         | Not Found                    | Section 8.4.5        |
    | 405         | Method Not Allowed           | Section 8.4.6        |
    | 406         | Not Acceptable               | Section 8.4.7        |
    | 407         | Proxy Authentication         | Section 3.2 of       |
    |             | Required                     | [Part7]              |
    | 408         | Request Time-out             | Section 8.4.9        |
    | 409         | Conflict                     | Section 8.4.10       |
    | 410         | Gone                         | Section 8.4.11       |
    | 411         | Length Required              | Section 8.4.12       |
    | 412         | Precondition Failed          | Section 3.2 of       |
    |             |                              | [Part4]              |
    | 413         | Request Entity Too Large     | Section 8.4.14       |
    | 414         | URI Too Long                 | Section 8.4.15       |
    | 415         | Unsupported Media Type       | Section 8.4.16       |
    | 416         | Requested range not          | Section 3.2 of       |
    |             | satisfiable                  | [Part5]              |
    | 417         | Expectation Failed           | Section 8.4.18       |
    | 426         | Upgrade Required             | Section 8.4.19       |
    | 500         | Internal Server Error        | Section 8.5.1        |
    | 501         | Not Implemented              | Section 8.5.2        |
    | 502         | Bad Gateway                  | Section 8.5.3        |
    | 503         | Service Unavailable          | Section 8.5.4        |
    | 504         | Gateway Time-out             | Section 8.5.5        |
    | 505         | HTTP Version not supported   | Section 8.5.6        |
    +-------------+------------------------------+----------------------+

    Note that this list is not exhaustive -- it does not include
    extension status codes defined in other specifications.
-- snip --

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Sat, 19 Feb 2011 13:59:45 +0100

On 17.02.2011 17:27, Julian Reschke wrote:
> ...

We had the same problem for the definition of "Method". I just raised a 
separate issue for that 
(<http://trac.tools.ietf.org/wg/httpbis/trac/ticket/275>), and resolved 
it similarly to #137. See 
<http://trac.tools.ietf.org/wg/httpbis/trac/changeset/1128> - the P2 
section "Method" now starts with:

-- snip --
2.  Method

    The Method token indicates the method to be performed on the target
    resource (Section 4.3 of [Part1]).  The method is case-sensitive.

      Method         = token

    The list of methods allowed by a resource can be specified in an
    Allow header field (Section 9.1).  The status code of the response
    always notifies the client whether a method is currently allowed on a
    resource, since the set of allowed methods can change dynamically.
    An origin server SHOULD respond with the status code 405 (Method Not
    Allowed) if the method is known by the origin server but not allowed
    for the resource, and 501 (Not Implemented) if the method is
    unrecognized or not implemented by the origin server.  The methods
    GET and HEAD MUST be supported by all general-purpose servers.  All
    other methods are OPTIONAL; however, if the above methods are
    implemented, they MUST be implemented with the same semantics as
    those specified in Section 7.

2.1.  Overview of Methods

    The methods listed below are defined in Section 7.

    +-------------+---------------+
    | Method Name | Defined in... |
    +-------------+---------------+
    | OPTIONS     | Section 7.2   |
    | GET         | Section 7.3   |
    | HEAD        | Section 7.4   |
    | POST        | Section 7.5   |
    | PUT         | Section 7.6   |
    | DELETE      | Section 7.7   |
    | TRACE       | Section 7.8   |
    | CONNECT     | Section 7.9   |
    +-------------+---------------+

    Note that this list is not exhaustive -- it does not include methods
    defined in other specifications.

-- snip --

Best regards, Julian

---

From: Ben Niven-Jenkins <[email-masked]>
Date: Tue, 22 Feb 2011 13:20:59 +0000

Julian,

On 17 Feb 2011, at 16:27, Julian Reschke wrote:
> So, to resolve issue 137, I did the following changes in <http://trac.tools.ietf.org/wg/httpbis/trac/changeset/1124>:
> 
> - Made the ABNFs for Status-Code and Reason-Phrase identical to P1; note that their consistency is checked when we build the spec. It could be argued that those ABNF rules should only occur once; feedback appreciated.
> 

Given that the ABNF you are referring to is pretty basic/simple and unlikely to change I don't see an issue with repeating it, it's not likely that the ABNF in P2 is likely to get out of step with the 'authoritative' ABNF in P1.

> - Consequently, as the enumeration of status-codes isn't in the ABNF anymore, I moved it into a non-normative "Overview" table. One could argue that it's not needed; but it's probably useful to easier find status code definitions, now that they are spread across multiple documents.
> 

I think it is not harmful and may be useful so the table seems an OK idea to me.

>   not required to examine or display the Reason-Phrase.

Maybe use "a human user"?

>   by local equivalents without affecting the protocol.

I had to think about this a little to parse it, because I didn't know if "Section 8" was referring to P2 or P4. Maybe it should say "Section 8 of this document, Section 3 of [Part4]..." to make it a little easier to parse (for me at least).

Ben

---

From: Julian Reschke <[email-masked]>
Date: Tue, 22 Feb 2011 14:42:22 +0100

Thanks for the review; see changes in 
<http://trac.tools.ietf.org/wg/httpbis/trac/changeset/1137>.

Best regards, Julian