http: use official IANA Status Codes

[jomo]

RFC 7231 states about HTTP status codes:

Note that this list is not exhaustive -- it does not include extension status codes defined in other specifications. The complete list of status codes is maintained by IANA. See Section 8.2 for
details.

Section 8.2:

The "Hypertext Transfer Protocol (HTTP) Status Code Registry" defines the namespace for the response status-code token (Section 6). The status code registry is maintained at
<http://www.iana.org/assignments/http-status-codes>.

This section replaces the registration procedure for HTTP Status Codes previously defined in Section 7.1 of [RFC2817].

The official list of HTTP Status Codes is maintained by the IANA here. There are other RFCs that define other codes, but these are not official.

From the io.js documentation:

A collection of all the standard HTTP response status codes

I have found a few issues in http.STATUS_CODES.

Missing status codes

These are official Status Codes, but are not defined in STATUS_CODES:

• 208 Already Reported
• 226 IM Used
• 421 Misdirected Request
• 508 Loop Detected

Status codes with wrong description

These codes have an alternate description that does not match the official standard:

code	Official description	Description in io.js
302	Found	Moved Temporarily
408	Request Timeout	Request Time-out
413	Payload Too Large	Request Entity Too Large
414	URI Too Long	Request-URI Too Large
416	Range Not Satisfiable	Requested Range Not Satisfiable
504	Gateway Timeout	Gateway Time-out

Non-Standard codes

These codes are not standardized by the IANA, but included anyway:

• 418 I'm a teapot

• 425 Unordered Collection
  According to a comment, this is defined in RFC 4918, but it's not. Not even in a draft of RFC 4918.

• 509 Bandwidth Limit Exceeded
  The only mention of this I could find is in Anti-DDoS Throttling of HTTP Requests by User-Agent:

  509 is the (non-standard) Bandwidth Limit Exceeded status code, which might indicate DDoS.

---

This PR adds missing codes and corrects those with a wrong description, but the falsely included (not official) codes have been kept.
IANA's RFC references have been added as comments.

[rlidwka]

Here are the real changes:

+  208 : 'Already Reported',
+  226 : 'IM Used',
-  302 : 'Moved Temporarily',
+  302 : 'Found',
+  306 : '(Unused)',
-  408 : 'Request Time-out',
+  408 : 'Request Timeout',
-  413 : 'Request Entity Too Large',
+  413 : 'Payload Too Large',
-  414 : 'Request-URI Too Large',
+  414 : 'URI Too Long',
-  416 : 'Requested Range Not Satisfiable',
+  416 : 'Range Not Satisfiable',
+  421 : 'Misdirected Request',
-  504 : 'Gateway Time-out',
+  504 : 'Gateway Timeout',
+  508 : 'Loop Detected',

Looks good to me. The description of 306 code looks odd though.

[jomo]

Ah, that code is officially (Unused):

306 (Unused)
The 306 status code was defined in a previous version of this specification, is no longer used, and the code is reserved.

I have removed it in my latest commit.

[domenic]

I'm not sure you want to add all the codes in the IANA registry. It seems better to just add the ones defined in HTTP. Extension status codes are just that---extensions. They are not necessarily more "official" or "standard" than the ones defined in HTTP.

In other words, the question is whether io.js wants to support the HTTP standard, or every single RFC the IETF ever puts out that ever defined a status code. Since e.g. I don't think the HTTP server of io.js supports RFC 3229, it doesn't seem appropriate to add 226 IM Used.

Also note from 7231

The reason phrases listed here are only recommendations -- they can be replaced by local equivalents without affecting the protocol.

so it's not that big of a deal that io.js doesn't match perfectly (although I don't see a reason not to update it).

[jomo]

Hmm, well according to that RFC you linked:

The complete list of status codes is maintained by IANA.

And the documentation for http.STATUS_CODES:

A collection of all the standard HTTP response status codes

Thus I think it's irrelevant which RFCs the io HTTP server supports, and the actual code should just match the docs :)

[domenic]

Yes, but the question is whether io.js wants all the standard HTTP response status codes, or all the status codes in every IETF RFC.

[jomo]

I think we need to differ a bit here:

We have standard codes, official codes and RFC codes. There are also unofficial non-standard codes such as 425 and 509 that are already included in io.js.

There is, for example httpbis-http2 draft 17 which is, as the name implies, a draft. It defines 421 Misdirected Request which the IANA has already registered as official HTTP code. It is official, but it's not standard and it's not RFC.

And then there is rfc7168 which defines 418 I'm a teapot but "is not an Internet Standards Track specification", it's not registered by the IANA. It's not official and not standard, but it is RFC.

Apart from those two, I think the standard, official, and rfc codes are the same.

I haven't removed the non-standard codes in my commits, but if we also want to keep them we should have a criteria for including non-standard codes (there are a lot)

[brendanashworth]

I too am -1 on having all the codes defined in core. However, the docs state that it is a list of all the standard response codes, and @jomo has shown that core already contains non-standard codes.

I'm fairly sure removing any of the codes would be semver-major, so I think this is the only other alternative. +1 on this particular PR, with the hope of the entire setup being remedied in the future.

p.s. imo I think the comments about the specific RFCs just clog the diff, I don't support them being there

[jomo]

Why is it that much of a problem to define "all" the codes? We're talking about 4 missing status codes.
If we remove the non-standard codes, there's just one more status code included than we had before.

PS: sorry for the clogged diff. Some of the codes had RFC comments already, so I thought it would make sense to add them all.

[brendanashworth]

@jomo not so much a "problem", just general bikeshedding / difference of opinions.

[jomo]

Regarding the already included non-standard codes, I would personally prefer to remove 425 and 509, but keep 418 because it's used a lot. (and because teapots are awesome)
The two other codes aren't used so widely.

[brendanashworth]

@jomo if you undid the comments, I could sign off on this and go for consensus.

[jomo]

@brendanashworth I removed the RFC comments in my last commit.

[brendanashworth]

Perfect, this LGTM, and I'm good with semver-patch for changing the header fields. @domenic?

[domenic]

I feel fairly strongly we should not be adding 208, 226, 421, or 508, for the reasons I've been explaining throughout this thread.

[brendanashworth]

@domenic:

Yes, but the question is whether io.js wants all the standard HTTP response status codes, or all the status codes in every IETF RFC.

Implementing every IETF RFC would include stuff like the Coffee Pot RFC, which I'm assuming you are against (even though it is already added). The standard response codes are the ones outlined in the IANA page, which are linked to and regarded as the official "complete list of status codes" to the "only recommendations" codes listed in the RFC itself.

Otherwise, if you're pushing for maintaining adherence to only the codes in the RFC, what about legit codes used elsewhere? They belong in core too! IANA preserves most if not all of the codes we need, and it can serve as a mediator on issues like this one (which status responses belong in core). This is why we should stick with official list of IANA response codes.

[rlidwka]

I think all useful codes should be there, no matter where they are defined and if they are defined at all. Adding extra codes does not cost us anything.

[jomo]

But what are "useful codes"? Aren't all codes used somewhere useful, in a way?
Should we include codes that are widely used? But then: what is "widely used"?

I think sticking to the official/standard codes is the best option, otherwise people are more likely to use non-standard codes.

[domenic]

Indeed, that is why I think we should draw the line at codes in HTTP, and not everything in the IANA registry.

They belong in core too!

I don't agree with this.

[brendanashworth]

Drawing the line at the codes in the HTTP RFC means the removal of the following codes already in core, 16 in total:

• 102 Processing
• 207 Multi-Status
• 308 Permanent Redirect
• 418 I'm a teapot
• 422 Unprocessable Entity
• 423 Locked
• 424 Failed Dependency
• 425 Unordered Collection
• 428 Precondition Required
• 429 Too Many Requests
• 431 Request Header Fields Too Large
• 506 Variant Also Negotiates
• 507 Insufficient Storage
• 509 Bandwidth Limit Exceeded
• 510 Not Extended
• 511 Network Authentication Required

In comparison, aligning ourselves with the IANA status codes means adding just 4 more and keeping 3 for backwards compatibility. The truth is, they're already in core, this PR for the most part just makes it official and adds the last missing 4.

[trevnorris]

I'm +1 on @brendanashworth's point. We're not going to remove codes already in core, and it's not like we're adding many more.

[domenic]

Indeed, I am not really happy core includes that many non-HTTP codes in its HTTP module, but given that it does, I guess using the IANA registry as the line is the best way forward.

[brendanashworth]

Thank you everyone, I plan on merging tomorrow.

[brendanashworth]

@jomo would you like to add your name to the commit? Right now it is just:

Author: jomo <github@jomo.tv>

[bnoordhuis]

I don't think this should be semver-patch but at least semver-minor, maybe major.

I'm certain there are integration test suites out there that check status lines and changing the message for e.g. a 302 will break them.

You can argue that having such brittle tests is stupid (and I don't disagree) but that's besides the point. Semver-patch should never break working code.

[jomo]

@brendanashworth I'm fine with that commit name, thanks.

[brendanashworth]

@bnoordhuis good point, I'll track this for 3.x release.

Question: we allow contributors to pick their commit name (use a nickname), right? I remember discussion about this but I can't find the decision.

[brendanashworth]

Landed in 235036e on next. Thank you!

I figure this will make its way into a nightly somehow or another.