API for headers

[Hagen]

I think it's great to be ultra correct on headers, but the double
array is troublesome, it leads to code like:

> userRequest.headers.some(function(line) {
> if (line[0] === "Content-Length") {
> expectedBytes = parseInt(line[1]);
> return true;
> }
> return false;
>
> });

How about changing it to a hash, but with an array as value? Bonus
points for leaving out the array, when array.length==1.

[ryan dahl]

> I think it's great to be ultra correct on headers, but the double
> array is troublesome, it leads to code like:

> [...]

> How about changing it to a hash, but with an array as value? Bonus
> points for leaving out the array, when array.length==1.

That's how it's done in Rack - I dislike it - at least as the
low-level server interface. You end up having to have checks
everywhere for the type of the value. It also does not allow one to
specify the order of the headers. The order is mostly irrelevent but,
for example, the RFC says

The order in which header fields with the same field-name are received
is therefore significant to the interpretation of the combined field value,
and thus a proxy MUST NOT change the order of these field values when
a message is forwarded.

So choosing a hash to represent headers would preclude one from
writing RFC conformant proxies in Node.

I fully expect higher level HTTP libraries to provide more
user-friendly API to message headers. But for a lowest-level
interfacing-with-web-server API, I think it's good.

[Alexandre.Morgaut]

Hi again,

I have the same problem with the way you can access specific headers
I sent a spreadsheet to the ServerJS mozilla's wiki which try to
specify some standards over SSJS APIs
(kind of "SOM" for "Server Object Model") and by the way, I added your
API to the existing list:
https://wiki.mozilla.org/ServerJS/Existing_APIs

My speadsheet try to show the differents existing API to manipulate
HTTP Servers incoming request's :
http://spreadsheets.google.com/pub?key=rMWeXQ2LvhKWqQQ_zEdb8aQ&single=true&gid=0&output=html
(accessible from : https://wiki.mozilla.org/ServerJS/WSGI )
All contributions for this spreadsheet are welcome, I did it a bit
quickly for my own needs.

The fact are:
- It's not easy to access a specific header with your API
- It's a requirement to have the possibility to access to any
information about the received HTTP headers, but some headers are
quite already used and a direct access to them is a good benefit (but
I agree it can be in a higher level library)

As Hagen said, It would be easier to have something like that :

var length = userRequest.headers["Content-Length"][0];
var warnings = userRequest.headers["Warning"];

So you could access each values set to headers respecting their order
but with an easier way to access them

For the second point, you can see that even CGI gave more importance
to some headers fields giving them specific names like "Content-
Length", and "Host"
HTTP request can not have more than one "Content-Length" header, it
would be non-sense, and its value must be a number to be valid. But I
agree that if you access the body from a string, you just have to call
"body.length"

[Urban Hafner]

Alexandre.Morgaut wrote:

> The fact are:
> - It's not easy to access a specific header with your API
> - It's a requirement to have the possibility to access to any
> information about the received HTTP headers, but some headers are
> quite already used and a direct access to them is a good benefit (but
> I agree it can be in a higher level library)

I agree with Ryan here (and with you I guess), that this should go into
a higher level library. I currently working on one [1] (although there's
not much there and it might go slow). There's also a list of projects on
the wiki [2] that might list things that go into that direction (e.g.
maybe node_chat already contains code that goes into that direction).

If you want to you can open an issue on coltrane [3] and I'll try to
integrate your suggestions. But I can't tell you when I'll be able to
get to it. The project is still early stages and I'm still figuring out
the basics.

Urban

[1] http://github.com/ujh/coltrane/tree/master
[2] http://wiki.github.com/ry/node
[3] http://github.com/ujh/coltrane/issues

[Urban Hafner]

Alexandre.Morgaut wrote:

> My speadsheet try to show the differents existing API to manipulate
> HTTP Servers incoming request's :
> http://spreadsheets.google.com/pub?key=rMWeXQ2LvhKWqQQ_zEdb8aQ&single=true&gid=0&output=html
> (accessible from : https://wiki.mozilla.org/ServerJS/WSGI )
> All contributions for this spreadsheet are welcome, I did it a bit
> quickly for my own needs.

BTW. Thanks for all the work on the spreadsheet! That seems like an
awesome resource to have.

Urban

[Urban Hafner]

Urban Hafner wrote:

> If you want to you can open an issue on coltrane [3] and I'll try to
> integrate your suggestions. But I can't tell you when I'll be able to
> get to it. The project is still early stages and I'm still figuring out
> the basics.

Did it myself: http://github.com/ujh/coltrane/issues/#issue/9 Any added
info is welcome.

Urban

[ryan dahl]

function makeSimpleHeaders (node_headers) {
var h = {};
for (var i = 0; i < node_headers.length; i++) {
var field = node_headers[i][0];
var value = node_headers[i][1];
if (h.hasOwnProperty(field)) {
if (h[field] instanceof Array) {
h[field].push(value);
} else {
h[field] = [h[field], value];
}
} else {
h[field] = value;
}
}
return h;
}

[Alexandre.Morgaut]

> (...) the RFC says

>
>   The order in which header fields with the same field-name are received
>   is therefore significant to the interpretation of the combined field value,
>   and thus a proxy MUST NOT change the order of these field values when
>   a message is forwarded.

The RFC also says just before : "The order in which header fields with
differing field names are received is not significant."

http://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2

What is significant is "the order in which header fields with the same
field-name are received" (even with different case)

It says : "Multiple message-header fields with the same field-name MAY
be present in a message if and only if the entire field-value for that
header field is defined as a comma-separated list [i.e., #(values)].
It MUST be possible to combine the multiple header fields into one
"field-name: field-value" pair, without changing the semantics of the
message, by appending each subsequent field-value to the first, each
separated by a comma."

This should apply also to all extended HTTP headers (like "Cookie")

so with these header fields :

Accept: text/plain
Accept-Charset: utf-8
accept: text/html

The "Accept" header should be readable as "text/plain, text/html"

I saw only one possible exception to this rule for the moment, it is
the "Warning" headers which might appear several times but doesn't
looks like they can be combined as a comma separated list

I updated my spreadsheet with a like "(o)" marker in the description
to show all the fields which must appear only must for the request to
be valid :
http://spreadsheets.google.com/pub?key=rMWeXQ2LvhKWqQQ_zEdb8aQ&single=true&gid=0&output=html

I hope this can help

[ry]

Okay - I give in. I've changed the API for headers to use an object in
0db7390eb8969c020af81d53cf4ce8926fa7cef1. The main reason is to reduce
the number of objects that are created by individual http messages.
For client requests and server respones node will still accept the old
array-of-arrays header.

> be valid :http://spreadsheets.google.com/pub?key=rMWeXQ2LvhKWqQQ_zEdb8aQ&single...

[ry]

> I've changed the API for headers to use an object in
> 0db7390eb8969c020af81d53cf4ce8926fa7cef1.

typo. I meant 316e2833f017150d58392f5ee82d86438ec22d5f.