Proposal for minor spec changes (#554)

* Webserver -> web server

This was flagged by my spell check, and indeed it's hard to find
spellings online without the space. The Oxford Dictionary only knows it
with a space, so I thought it's worth correcting.

* Attempt to clarify optional keys

I wasn't sure about how to treat keys marked optional. After having
spoken to Andrew, this is my attempt at clarifying. Improvements
welcome!

* Order of header values MUST be kept

Order for HTTP header values matters, both in request and responses. So
we must make sure that we're keeping it.

Request:
> Some headers, such as Accept-Language can be sent by clients as
> several headers each with a different value rather than sending the
> header as a comma separated list.

http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getHeaders%28java.lang.String%29

Response:
Set-Cookie may be present multiple times, and only the last given value
is to be used.

I'm updating the Daphne test to verify the order in my pull request
there.

* Clarify that headers is a list of lists

The wording for 'server'/'client' and 'headers' was very similar, and I
was unsure if clients may be a list of lists (in anticipation of
protocols supporting that). I hope this small tweak makes it clearer
that only headers is a list of lists.
This commit is contained in:
Maik Hoepfel 2017-03-08 01:05:28 -06:00 committed by Andrew Godwin
parent 2101f285cb
commit 13c1fcb654

View File

@ -478,8 +478,9 @@ Message Formats
These describe the standardized message formats for the protocols this
specification supports. All messages are ``dicts`` at the top level,
and all keys are required unless otherwise specified (with a default to
use if the key is missing). Keys are unicode strings.
and all keys are required unless explicitly marked as optional. If a key is
marked optional, a default value is specified, which is to be assumed if
the key is missing. Keys are unicode strings.
The one common key across all protocols is ``reply_channel``, a way to indicate
the client-specific channel to send responses to. Protocols are generally
@ -557,10 +558,11 @@ Keys:
is mounted at; same as ``SCRIPT_NAME`` in WSGI. Optional, defaults
to ``""``.
* ``headers``: A list of ``[name, value]`` pairs, where ``name`` is the
* ``headers``: A list of ``[name, value]`` lists, where ``name`` is the
byte string header name, and ``value`` is the byte string
header value. Order should be preserved from the original HTTP request;
duplicates are possible and must be preserved in the message as received.
header value. Order of header values must be preserved from the original HTTP
request; order of header names is not important. Duplicates are possible and
must be preserved in the message as received.
Header names must be lowercased.
* ``body``: Body of the request, as a byte string. Optional, defaults to ``""``.
@ -622,9 +624,9 @@ Keys:
* ``status``: Integer HTTP status code.
* ``headers``: A list of ``[name, value]`` pairs, where ``name`` is the
* ``headers``: A list of ``[name, value]`` lists, where ``name`` is the
byte string header name, and ``value`` is the byte string
header value. Order should be preserved in the HTTP response. Header names
header value. Order must be preserved in the HTTP response. Header names
must be lowercased.
* ``content``: Byte string of HTTP body content.