[hybi] method of allocation of reserved bits to extensions

[Brodie Thiesfield <[e-mail]>]

All,

The WebSocket spec permits extensions to use reserved bits, however I
can't see that it provides any way to negotiate which bit should be
used in the presence of multiple extensions competing for a reserved
bit. If a negotiation method is not prescribed, each extension will
just state "using RSV1" or similar in their spec and then either that
bit will become the "extension X bit" or that extension will not be
compatible with other extensions that want to use the same bit.

For example, a "deflate-payload" extension that allows optional
compression might want to use a bit in the frame to denote
compression. If it is used with the "mux-a-million" extension that
also wants to use a reserved bit, both server and client need to agree
on which bits are used. The server needs to allocate these reserved
bits to the extensions that require them.

I propose the following addition to the extensions section:


8.2 Negotiating Reserved Bits

An extension may require or desire the use of a reserved bit in the
framing for proper operation. It is the responsibility of the server
to allocate the reserved bits to those extensions that require them.
Because the server must know all extension requirements before
negotiating its use, requirements for mandatory or optional use of a
reserved frame bit is assumed to be known by the server. Extensions
that allocated a reserved frame bit will have that allocation included
in the response as a bit allocation header.

If an extension requires the use of one or more reserved bits but it
has not been allocated all required bits, the extension MUST NOT be
included in the list of negotiated extensions in the response. If an
extension can optionally use a reserved bit but it has not been
allocated the bit, the extension MAY be included in the list of
negotiated extensions but a bit allocation will not be present in the
response for that extension. The selection of extensions and
allocation of reserved frame bits to the extensions is at the
discretion of the server. Extensions MUST NOT depend on the reserved
bit staying the same as any previous allocation.

The server MUST return a bit reservation header, and include an entry
for each extension that has been allocated a reserved frame bit:

bit-reservation-header = "Sec-WebSocket-Reserved-Bits:" bit-allocation
bit-allocation = extension-token "=" allocated-bits
allocated-bits = bitnum *(";" bitnum)
bitnum = 1#digit

The bitnum is the number of the reserved bit corresponding to the
WebSocket protocol specification section 4.2 where "1" is RSV1, "2" is
RSV2, etc.

For example, to allocate RSV3 to deflate-payload and RSV1 to
mux-a-million would add the following two headers to the response:

Sec-WebSocket-Reserved-Bits: deflate-payload=3
Sec-WebSocket-Reserved-Bits: mux-a-million=1

Note that like other HTTP headers, this header MAY be split or
combined across multiple lines.  Ergo, the following header is
equivalent to the two headers above:

Sec-WebSocket-Reserved-Bits: deflate-payload=3, mux-a-million=1

If an extension has been allocated the use of multiple bits, multiple
allocations MUST follow it's token. An extension token MUST NOT appear
more than once in the Sec-WebSocket-Reserved-Bits header. For example,
if it assumed that the "mux-a-million" extension requires the use of a
single bit, but can optionally use another bit. If the server
allocates two bits to the extension, the following header may be
returned:

Sec-WebSocket-Reserved-Bits: mux-a-million=1;3

The order of the bits within the allocated-bits field is significant
and should be interpreted as appropriate by the extension. The order
of the bit-allocation fields within the Sec-WebSocket-Reserved-Bits is
not significant.

If an extension is negotiated which requires a frame bit, but the
server fails to allocate that frame bit, the client MUST disconnect.


However the allocation works, for the sake of extensibility of the
protocol, I think that we need to get some method of allocating these
bits into the spec before final. Note that I have used the Sec- header
prefix just for consistency with other headers.

Regards,
Brodie