Re: [hybi] [permessage-deflate] Renaming s2c_ and c2s_ prefix to server_ and client_

[Joakim Erdfelt <[e-mail]>]

The problem is the language choices in the spec already.

Take this for example: (from Section
8.1.2.2<http://tools.ietf.org/html/draft-ietf-hybi-permessage-compression-13#section-8.1.2.2>of
draft-ietf-hybi-permessage-compression-13)

8.1.2.2.  c2s_max_window_bits

   A client MAY include the "c2s_max_window_bits" extension parameter in
   an offer.  This parameter has no value or a decimal integer value
   without leading zeroes between 8 to 15 inclusive indicating the
   base-2 logarithm of the LZ77 sliding window size.  Using this
   parameter, a client tells the peer server that the client supports
   the server-to-client "c2s_max_window_bits" extension parameter.  If
   the parameter has a value, the parameter also tells the peer server a
   hint that even if the server sends the "c2s_max_window_bits"
   extension parameter with a bigger value or doesn't send it at all,
   the client is not going to use LZ77 sliding window size greater than
   the size specified by the value to compress messages.

   If a received offer has the "c2s_max_window_bits" extension
   parameter, the server MAY include the "c2s_max_window_bits" extension
   parameter in the response to the offer.  If the "c2s_max_window_bits"
   extension parameter in the received offer has a value, the server may
   either ignore this value or use this value to avoid allocating an
   unnecessarily big LZ77 sliding window by specifying
   "c2s_max_window_bits" extension parameter with a value equal to or
   smaller than the received value in the response.  This server-to-
   client parameter has a decimal integer value without leading zeroes
   between 8 to 15 inclusive indicating the base-2 logarithm of the LZ77
   sliding window size.

       c2s_max_window_bits = 1*DIGIT

   Using this server-to-client parameter, a server limits the LZ77
   sliding window size that the client uses to compress messages.  This
   reduces the amount of memory that the server has to reserve for the
   connection, in the same way the "s2c_max_window_bits" extension
   parameter does for the client.

   If a received offer doesn't have the "c2s_max_window_bits" extension
   parameter, the server MUST NOT include the "c2s_max_window_bits"
   extension parameter in the response to the offer.


We start by talking of "c2s_" then half way through the first paragraph we
start talking about "server-to-client" and even point out the "c2s_"
parameter as an example of the "server-to-client".

The spec mixes the use of "c2s" and "client-to-server" in various places,
in what we can only assume is sometimes it refers the parameter, sometimes
it refers to the direction of the conversation, sometimes it refers to the
extension negotiation step, sometimes it refers to the extension
negotiation phase.

Months have been spent trying to decipher this spec by multiple people with
years of experience on ietf specs, both as consumers and participants.  the
spec should be able to sit on its own, with as clear of definition as
possible at the time, reducing as much of the "interpretation" and question
asking that will arise from the spec.

The "2s" and "2c" portions are irrelevant, and actually cause confusion as
you use the same language elsewhere.

proposal:

"c2s_" used in extension-param tokens should be "client_" to refer to
"client produced compression"
"s2c_" used in extension-param tokens should be "server_" to refer to
"server produced compression"

"client-to-server", and "server-to-client" use within spec should be
clarified, and never be left without a clarification.
   when referring to the extension negotiation request phase.
      consider "extension negotiation request" or "extension negotiation
offer" for current "client-to-server" use
      consider "extension negotiation response" or "extension negotiation
accept" for current "server-to-client" use.
   when referring to the flow of frames on a connected websocket.
      this is where the existing "Client-to-Server" terminology is
consistent with RFC6455 (see Section
5.3<http://tools.ietf.org/html/rfc6455#section-5.3>
).
      so feel free to start using for "Server-to-Client" here as well, but
not in the above.

another choice is to never leave "Client-to-Server" alone with no
clarification, always follow it with consistent verbiage, like RFC6455 does.

Its never "Client-to-Server" just to refer to a directionality, its a
compound concept, such as "Client-to-Server Masking" or "Client-to-Server
message".

Suspicions/Theories:

The language choices of this spec probably come from the overall attempt at
being neutral to what side (client or server) the spec is documenting from.
If you look at the overall language of RFC6455, you see that it is
presented from the point of view of the Client, with the Server roles and
responsibilities being explained only when needed to.  Otherwise, both
sides are assumed to be the same in behavior.
If RFC6455 used the same techniques as the permessage-deflate spec, then
you'd have 2 sections: Client, fully documented with barely a mention of
server, then Server, fully documented we barely a mention of client.

Permessage-deflate could have been documented the same way as RFC6455, but
it isn't, so now you have extra work to be careful in your language
choices, eliminate ambiguity, make things more clear.


Our the final translation of the permessage-deflate extension spec, as
written:

Simplified Neutral Language:
Incoming frames/messages are compressed when RSV1 is set
Outgoing frames/messages can be compressed, but set RSV1 if you do.
Configuration of Incoming frames/messages compression is controlled by
Extension Parameters for the opposite side of yourself.
Configuration of Outgoing frames/messages compression is controlled by
Extension Parameters for your side.

Side Specific Language:
client_* Extension Parameters are for controlling frames/messages
compression produced by client
server_* Extension Parameters are for controlling frames/messages
compression produced by server

Here's the example of same Section 8.1.2.2 with the proposed change: (quick
edit)

8.1.2.2.  client_max_window_bits

   A client MAY include the "client_max_window_bits" extension parameter in
   an extension negotiation offer.  This parameter MAY have no value or a
decimal integer value
   without leading zeroes between 8 to 15 inclusive indicating the
   base-2 logarithm of the LZ77 sliding window size.  The use of this
   parameter in a extension negotiation offer informs the peer server that
   the client supports the "client_max_window_bits" extension parameter.
   If the parameter has a value, the parameter also tells the peer server a
   hint that even if the server sends the "client_max_window_bits"
   extension parameter on the extension negotiation response with a bigger
value,
   or doesn't send it at all, the client is not going to use LZ77 sliding
window
   size greater than the size specified by the value to compress messages.

   If a received extension negotiation offer has the
"client_max_window_bits" extension
   parameter, the server MAY include the "client_max_window_bits" extension
   parameter in the extension negotiation response.  If the
"client_max_window_bits"
   extension parameter in the received extension negotiation offer has a
value, the server may
   either ignore this value or use this value to avoid allocating an
   unnecessarily big LZ77 sliding window by specifying
   "client_max_window_bits" extension parameter with a value equal to or
   smaller than the received value in the response.
   The extension negotiation accept parameter value MUST have a decimal
   integer value without leading zeroes between 8 to 15 inclusive
   indicating the base-2 logarithm of the LZ77 sliding window size.

       client_max_window_bits = 1*DIGIT

   The use of the extension negotiation response parameter allows a server
to limit the LZ77
   sliding window size that the client uses to compress messages.  This
   reduces the amount of memory that the server has to reserve for the
   connection, in the same way the "server_max_window_bits" extension
   parameter does for the client.

   If a received extension negotiation offer doesn't have the
"client_max_window_bits" extension
   parameter, the server MUST NOT include the "client_max_window_bits"
   extension parameter in the extension negotiation response to the offer.

Hope this helps explain where we are coming from.


--
Joakim Erdfelt <[e-mail]>
webtide.com <http://www.webtide.com/> - intalio.com/jetty
Expert advice, services and support from from the Jetty & CometD experts
eclipse.org/jetty - cometd.org


On Tue, Oct 15, 2013 at 7:08 AM, Takeshi Yoshino <[e-mail]>wrote:

> Thanks, all.
>
> Joakim, please show Jetty's opinion again. Then, I'll make decision to
> move forward.
>
> Tobias: neutral
> Peter: neutral slight preference for s2c_
> Takeshi: neutral slight preference for s2c_
> Joakim: preference for server_
>
>