diff --git a/docs/asgi.rst b/docs/asgi.rst index 61c0cfa..c7dbcd8 100644 --- a/docs/asgi.rst +++ b/docs/asgi.rst @@ -413,11 +413,17 @@ main response, and you should check for ``http_version = 2`` before sending them; if a protocol server or connection incapable of Server Push receives these, it should simply drop them. -The HTTP specs are somewhat vague on the subject of multiple headers; -RFC7230 explicitly says they must be merge-able with commas, while RFC6265 -says that ``Set-Cookie`` headers cannot be combined this way. This is why -request ``headers`` is a ``dict``, and response ``headers`` is a list of -tuples, which matches WSGI. +Multiple header fields with the same name are complex in HTTP. RFC 7230 +states that for any header field that can appear multiple times, it is exactly +equivalent to sending that header field only once with all the values joined by +commas. + +However, RFC 7230 and RFC 6265 make it clear that this rule does not apply to +the various headers used by HTTP cookies (``Cookie`` and ``Set-Cookie``). The +``Cookie`` header must only be sent once by a user-agent, but the +``Set-Cookie`` header may appear repeatedly and cannot be joined by commas. +For this reason, we can safely make the request ``headers`` a ``dict``, but +the response ``headers`` must be sent as a list of tuples, which matches WSGI. Request '''''''