Subject: Revision of p2 2.2.1 / who can generate a status code?

From: Mark Nottingham <[email-masked]>
Date: Tue, 3 Jul 2012 12:00:05 +1000

<https://svn.tools.ietf.org/svn/wg/httpbis/draft-ietf-httpbis/latest/p2-semantics.html#considerations.for.new.methods> currently has:

> When it is necessary to express new semantics for a HTTP request that aren't specific to a single application or media type, and currently defined methods are inadequate, it might be appropriate to register a new method.
> 
> HTTP methods are generic; that is, they are potentially applicable to any resource, not just one particular media type, "type" of resource, or application. As such, it is preferred that new HTTP methods be registered in a document that isn't specific to a single application, so that this is clear.
> 
> Due to the parsing rules defined in Section 3.3 of [Part1], definitions of HTTP methods cannot prohibit the presence of a message body on either the request or the response message (with responses to HEAD requests being the single exception). Definitions of new methods cannot change this rule, but they can specify that only zero-length bodies (as opposed to absent bodies) are allowed.
> 
> New method definitions need to indicate whether they are safe (Section 2.1.1), what semantics (if any) the request body has, and whether they are idempotent (Section 2.1.2). They also need to state whether they can be cached ([Part6]); in particular what conditions a cache may store the response, and under what conditions such a stored response may be used to satisfy a subsequent request.

Based on discussion, I suggest it be replaced with:

"""
When it is necessary to express new semantics for a HTTP request that aren't specific to a single application or media type, and currently defined methods are inadequate, it might be appropriate to register a new method.

HTTP methods are generic; that is, they are potentially applicable to any resource, not just one particular media type, "type" of resource, or application. As such, it is preferred that new HTTP methods be registered in a document that isn't specific to a single application, so that this is clear.

Due to the parsing rules defined in Section 3.3 of [Part1], definitions of HTTP methods cannot prohibit the presence of a message body on either the request or the response message (with responses to HEAD requests being the single exception). Definitions of new methods cannot change this rule, but they can specify that only zero-length bodies (as opposed to absent bodies) are allowed.

Definitions of new methods need to indicate:

* whether they are safe (Section 2.1.1),
* whether they are idempotent (Section 2.1.2),
* what semantics (if any) the request body has,
* whether proxies, origin servers (including gateways), intermediaries (proxy or gateway) or all servers can generate this status code,
* whether they can be cached ([Part6]); in particular what conditions a cache may store the response, and under what conditions such a stored response may be used to satisfy a subsequent request.
"""

Note that the new consideration -- identifying who can generate the status code -- implies (as Julian pointed out) that we should eat our own dogfood and define it for ours.

Looking through p2, this was actually easier than I thought it might be; most of the status codes already are pretty specific (using phrases like "the resource indicates...", which can logically be read to make it specific to origins). The only issues of interpretation I found are marked by "!" below.

O - Origin server (including gateways)
I - Intermediaries (proxy or gateway)
P - Proxies (not gateways)
S - All servers

 Informational 1xx
S   100 Continue
S   101 Switching Protocols

 Successful 2xx
O   200 OK
O   201 Created
O   202 Accepted
P   203 Non-Authoritative Information
O   204 No Content
O   205 Reset Content

 Redirection 3xx
O   300 Multiple Choices
O   301 Moved Permanently
O   302 Found
O   303 See Other
    305 Use Proxy
    306 (Unused)
O   307 Temporary Redirect

 Client Error 4xx
S   400 Bad Request
    402 Payment Required
O!  403 Forbidden
O   404 Not Found
O   405 Method Not Allowed
O   406 Not Acceptable
S   408 Request Timeout
O   409 Conflict
O   410 Gone
S   411 Length Required
S   413 Request Representation Too Large
S   414 URI Too Long
O   415 Unsupported Media Type
S   417 Expectation Failed
S   426 Upgrade Required

 Server Error 5xx
S   500 Internal Server Error
O!   501 Not Implemented
I   502 Bad Gateway
S   503 Service Unavailable
I   504 Gateway Timeout
S   505 HTTP Version Not Supported

Thoughts?

--
Mark Nottingham   http://www.mnot.net/

---

From: John Sullivan <[email-masked]>
Date: Tue, 3 Jul 2012 14:58:21 +0100

> P - Proxies (not gateways)

Does an intermediate selected through use of Max-Forwards count
as an origin for this purpose when fielding TRACE or OPTIONS?

> O!  403 Forbidden

Definitely S - see the previous discussion around 451 where it was
widely accepted that 403 was a legitimate response from an intermediate
that was unwilling for undisclosed reasons to proxy at all for a given
URI/client.

> S   500 Internal Server Error

Again, if an intermediate is refusing to handle TRACE/OPTIONS
targeted at it, this would seem the appropriate response.

John
--

---

From: Mark Nottingham <[email-masked]>
Date: Wed, 4 Jul 2012 05:26:47 +1000

> as an origin for this purpose when fielding TRACE or OPTIONS?

Good point. This will have to be special-cased in the text.

> that was unwilling for undisclosed reasons to proxy at all for a given

Personally, I agree. I think we can work around any potential issues here by making this just prose; i.e., "ought to" instead of MUST.

> targeted at it, this would seem the appropriate response.

Ack; same as above.

Thanks,

---

From: Amos Jeffries <[email-masked]>
Date: Wed, 04 Jul 2012 19:17:02 +1200

> * whether proxies, origin servers (including gateways), intermediaries (proxy or gateway) or all servers can generate this status code,

Clarity: "this status code"? this list context is about methods so far.

> * whether they can be cached ([Part6]); in particular what conditions a cache may store the response, and under what conditions such a stored response may be used to satisfy a subsequent request.

Clarity: is "they" talking about the method? request entity? or response 
entity?

AYJ

---

From: Amos Jeffries <[email-masked]>
Date: Wed, 04 Jul 2012 19:19:56 +1200

> as an origin for this purpose when fielding TRACE or OPTIONS?

Also, caching intermediaries serving from cache?

> that was unwilling for undisclosed reasons to proxy at all for a given

+1.

> targeted at it, this would seem the appropriate response.

+1.

AYJ

---

From: Amos Jeffries <[email-masked]>
Date: Wed, 04 Jul 2012 19:21:50 +1200

> Good point. This will have to be special-cased in the text.

Another one: CONNECT response from a proxy? you put 101 as "S".

AYJ

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 5 Jul 2012 16:45:25 +1000

Argh, sorry, I got proposals mixed up. I'll re-send.

On 04/07/2012, at 5:17 PM, Amos Jeffries wrote:

> Clarity: is "they" talking about the method? request entity? or response entity?