draft-ietf-hybi-permessage-compression-14.txt   draft-ietf-hybi-permessage-compression-15.txt 
HyBi Working Group T. Yoshino HyBi Working Group T. Yoshino
Internet-Draft Google, Inc. Internet-Draft Google, Inc.
Intended status: Standards Track October 15, 2013 Intended status: Standards Track October 16, 2013
Expires: April 18, 2014 Expires: April 19, 2014
Compression Extensions for WebSocket Compression Extensions for WebSocket
draft-ietf-hybi-permessage-compression-14 draft-ietf-hybi-permessage-compression-15
Abstract Abstract
This document specifies a framework for creating WebSocket extensions This document specifies a framework for creating WebSocket extensions
that add compression functionality to the WebSocket Protocol. An that add compression functionality to the WebSocket Protocol. An
extension based on this framework compresses the payload data portion extension based on this framework compresses the payload data portion
of non-control WebSocket messages on a per-message basis using of non-control WebSocket messages on a per-message basis using
parameters negotiated during the opening handshake. This framework parameters negotiated during the opening handshake. This framework
provides a general method to apply a compression algorithm to the provides a general method to apply a compression algorithm to the
contents of WebSocket messages. For each compression algorithm, an contents of WebSocket messages. For each compression algorithm, an
skipping to change at page 1, line 41 skipping to change at page 1, line 41
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current. Drafts is at http://datatracker.ietf.org/drafts/current.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 18, 2014. This Internet-Draft will expire on April 19, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 20 skipping to change at page 2, line 20
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conformance Requirements and Terminology . . . . . . . . . . . 4 2. Conformance Requirements and Terminology . . . . . . . . . . . 4
3. Complementary Terminology . . . . . . . . . . . . . . . . . . 5 3. Complementary Terminology . . . . . . . . . . . . . . . . . . 5
4. WebSocket Per-message Compression Extension . . . . . . . . . 6 4. WebSocket Per-message Compression Extension . . . . . . . . . 6
5. Extension Negotiation . . . . . . . . . . . . . . . . . . . . 7 5. Extension Negotiation . . . . . . . . . . . . . . . . . . . . 7
5.1. Negotiation Examples . . . . . . . . . . . . . . . . . . . 9 5.1. Negotiation Examples . . . . . . . . . . . . . . . . . . . 9
6. Framing . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 6. Framing . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
6.1. Compression . . . . . . . . . . . . . . . . . . . . . . . 10 6.1. Compression . . . . . . . . . . . . . . . . . . . . . . . 11
6.2. Decompression . . . . . . . . . . . . . . . . . . . . . . 11 6.2. Decompression . . . . . . . . . . . . . . . . . . . . . . 12
7. Intermediaries . . . . . . . . . . . . . . . . . . . . . . . . 13 7. Intermediaries . . . . . . . . . . . . . . . . . . . . . . . . 14
8. permessage-deflate extension . . . . . . . . . . . . . . . . . 14 8. permessage-deflate extension . . . . . . . . . . . . . . . . . 15
8.1. Method Parameters . . . . . . . . . . . . . . . . . . . . 15 8.1. Method Parameters . . . . . . . . . . . . . . . . . . . . 16
8.1.1. Context Takeover Control . . . . . . . . . . . . . . . 15 8.1.1. Context Takeover Control . . . . . . . . . . . . . . . 16
8.1.2. Limiting the LZ77 sliding window size . . . . . . . . 16 8.1.2. Limiting the LZ77 sliding window size . . . . . . . . 18
8.1.3. Example . . . . . . . . . . . . . . . . . . . . . . . 18 8.1.3. Example . . . . . . . . . . . . . . . . . . . . . . . 20
8.2. Message Payload Transformation . . . . . . . . . . . . . . 19 8.2. Message Payload Transformation . . . . . . . . . . . . . . 21
8.2.1. Compression . . . . . . . . . . . . . . . . . . . . . 19 8.2.1. Compression . . . . . . . . . . . . . . . . . . . . . 21
8.2.2. Decompression . . . . . . . . . . . . . . . . . . . . 20 8.2.2. Decompression . . . . . . . . . . . . . . . . . . . . 22
8.2.3. Examples . . . . . . . . . . . . . . . . . . . . . . . 21 8.2.3. Examples . . . . . . . . . . . . . . . . . . . . . . . 23
8.3. Implementation Notes . . . . . . . . . . . . . . . . . . . 24 8.3. Implementation Notes . . . . . . . . . . . . . . . . . . . 26
8.4. Intermediaries . . . . . . . . . . . . . . . . . . . . . . 25 8.4. Intermediaries . . . . . . . . . . . . . . . . . . . . . . 27
9. Security Considerations . . . . . . . . . . . . . . . . . . . 26 9. Security Considerations . . . . . . . . . . . . . . . . . . . 28
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29
10.1. Registration of the "permessage-deflate" WebSocket 10.1. Registration of the "permessage-deflate" WebSocket
Extension Name . . . . . . . . . . . . . . . . . . . . . . 27 Extension Name . . . . . . . . . . . . . . . . . . . . . . 29
10.2. Registration of the "Per-message Compressed" WebSocket 10.2. Registration of the "Per-message Compressed" WebSocket
Framing Header Bit . . . . . . . . . . . . . . . . . . . . 27 Framing Header Bit . . . . . . . . . . . . . . . . . . . . 29
11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 28 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 30
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 31
12.1. Normative References . . . . . . . . . . . . . . . . . . . 29 12.1. Normative References . . . . . . . . . . . . . . . . . . . 31
12.2. Informative References . . . . . . . . . . . . . . . . . . 29 12.2. Informative References . . . . . . . . . . . . . . . . . . 31
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 30 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 32
1. Introduction 1. Introduction
This document specifies a framework to add compression functionality This document specifies a framework to add compression functionality
to the WebSocket Protocol [RFC6455]. This framework specifies how to to the WebSocket Protocol [RFC6455]. This framework specifies how to
define WebSocket Per-message Compression Extensions (PMCEs) define WebSocket Per-message Compression Extensions (PMCEs)
individually for various compression algorithms based on the individually for various compression algorithms based on the
extension concept of the WebSocket Protocol specified in Section 9 of extension concept of the WebSocket Protocol specified in Section 9 of
[RFC6455]. A WebSocket client and a peer WebSocket server negotiate [RFC6455]. A WebSocket client and a peer WebSocket server negotiate
use of a PMCE and determine parameters to configure the compression use of a PMCE and determine parameters to configure the compression
skipping to change at page 5, line 26 skipping to change at page 5, line 26
payload data portion of all frames representing a single message, as payload data portion of all frames representing a single message, as
well as how /data/ is formed from in Section 6.2 of [RFC6455]. well as how /data/ is formed from in Section 6.2 of [RFC6455].
Extension in use next to extension X means the extension listed next Extension in use next to extension X means the extension listed next
to X in the "Sec-WebSocket-Extensions" header in the server's opening to X in the "Sec-WebSocket-Extensions" header in the server's opening
handshake as defined in Section 9.1 of [RFC6455]. Such an extension handshake as defined in Section 9.1 of [RFC6455]. Such an extension
is applied to outgoing data from the application right after X on is applied to outgoing data from the application right after X on
sender side but applied right before X to incoming data from the sender side but applied right before X to incoming data from the
underlying transport. underlying transport.
Accept an extension offer means including a corresponding response in Extension negotiation offer means each element in the
the "Sec-WebSocket-Extensions" header in the server's opening "Sec-WebSocket-Extensions" header in the client's opening handshake.
handshake.
Decline an extension offer means not including a corresponding Extension negotiation response means each element in the
response in the "Sec-WebSocket-Extensions" header in the server's "Sec-WebSocket-Extensions" header in the server's opening handshake.
opening handshake.
Accept an extension negotiation offer means including a corresponding
extension negotiation response in the "Sec-WebSocket-Extensions"
header in the server's opening handshake.
Decline an extension negotiation offer means not including a
corresponding extension negotiation response in the
"Sec-WebSocket-Extensions" header in the server's opening handshake.
4. WebSocket Per-message Compression Extension 4. WebSocket Per-message Compression Extension
WebSocket Per-message Compression Extensions (PMCEs) are extensions WebSocket Per-message Compression Extensions (PMCEs) are extensions
to the WebSocket Protocol enabling compression functionality. PMCEs to the WebSocket Protocol enabling compression functionality. PMCEs
are built based on Section 9 of [RFC6455]. PMCEs are individually are built based on Section 9 of [RFC6455]. PMCEs are individually
defined for each compression algorithm to be implemented, and are defined for each compression algorithm to be implemented, and are
registered in the WebSocket Extension Name Registry created in registered in the WebSocket Extension Name Registry created in
Section 11.4 of [RFC6455]. Each PMCE refers to this framework and Section 11.4 of [RFC6455]. Each PMCE refers to this framework and
defines the following: defines the following:
skipping to change at page 7, line 23 skipping to change at page 7, line 23
compression algorithm of the PMCE. A client offers multiple PMCE compression algorithm of the PMCE. A client offers multiple PMCE
choices to the server by including multiple elements in the choices to the server by including multiple elements in the
"Sec-WebSocket-Extensions" header, one for each PMCE offered. The "Sec-WebSocket-Extensions" header, one for each PMCE offered. The
set of elements MAY include multiple PMCEs with the same extension set of elements MAY include multiple PMCEs with the same extension
name to offer use of the same algorithm with different configuration name to offer use of the same algorithm with different configuration
parameters. The order of elements means the client's preference. An parameters. The order of elements means the client's preference. An
element precedes another element has higher preference. It is element precedes another element has higher preference. It is
RECOMMENDED that a server accepts PMCEs with higher preference if the RECOMMENDED that a server accepts PMCEs with higher preference if the
server supports it. server supports it.
A PMCE negotiation offer informs requests and/or hints to the server.
A request in a PMCE negotiation offer indicates constraints on the
server's behavior that must be satisfied if the server accepts the
offer. A hint in a PMCE negotiation offer indicates information
about the client's behavior that the server may either safely ignore
or refer to when the server decides its behavior.
To accept use of an offered PMCE, a server includes a To accept use of an offered PMCE, a server includes a
"Sec-WebSocket-Extensions" header element with the extension name of "Sec-WebSocket-Extensions" header element with the extension name of
the PMCE in the "Sec-WebSocket-Extensions" header in the server's the PMCE in the "Sec-WebSocket-Extensions" header in the server's
opening handshake of the WebSocket connection. Extension parameters opening handshake of the WebSocket connection. Extension parameters
in the element represent the configuration parameters of the PMCE to in the element represent the configuration parameters of the PMCE to
use in detail. We call these extension parameters and their values use in detail. We call these extension parameters and their values
"agreed parameters". The element MUST represent a PMCE that is fully "agreed parameters". The element MUST represent a PMCE that is fully
supported by the server. The contents of the element doesn't need to supported by the server. The contents of the element doesn't need to
be exactly the same as one of the received offers. For example, an be exactly the same as one of the received extension negotiation
offer with an extension parameter "X" indicating availability of the offers. For example, an extension negotiation offer with an
feature X may be accepted with an element without the extension extension parameter "X" indicating availability of the feature X may
parameter meaning that the server declined use of the feature. be accepted with an element without the extension parameter meaning
that the server declined use of the feature.
"Agreed parameters" MUST represent how the requests and hints in the "Agreed parameters" MUST represent how the requests and hints in the
client's offer have been handled in addition to the server's requests client's extension negotiation offer have been handled in addition to
and hints on the client's behavior, so that the client can configure the server's requests and hints on the client's behavior, so that the
its behavior without identifying which PMCE offer has been accepted. client can configure its behavior without identifying which PMCE
extension negotiation offer has been accepted.
For example, if a client sends an offer with a parameter For example, if a client sends an extension negotiation offer
"enable_compression" and another without the parameter, the server including a parameter "enable_compression" and another without the
accepts the former by sending back an element including a parameter parameter, the server accepts the former by sending back an element
that acknowledges "enable_compression". The name of the including a parameter that acknowledges "enable_compression". The
acknowledging parameter doesn't need to be the same as the offer. name of the acknowledging parameter doesn't need to be the same as
the offer.
General negotiation flow will be like the followings. How to handle General negotiation flow will be like the followings. How to handle
parameters in detail will be specified in the specifications for each parameters in detail will be specified in the specifications for each
PMCEs. PMCEs.
A client makes an offer including parameters identifying the A client makes an offer including parameters identifying the
followings: followings:
o Hints about how the client is planning to compress data o Hints about how the client is planning to compress data
skipping to change at page 8, line 27 skipping to change at page 8, line 37
o How the server will compress data o How the server will compress data
The client uses these parameters from the server make a determination The client uses these parameters from the server make a determination
of its behavior based on them if it can and wants to proceed. of its behavior based on them if it can and wants to proceed.
Otherwise, the client starts closing handshake with close code 1010. Otherwise, the client starts closing handshake with close code 1010.
There can be compression features that can be applied separately for There can be compression features that can be applied separately for
each direction. For such features, the acknowledging parameter and each direction. For such features, the acknowledging parameter and
the parameter for the reverse direction must be chosen to be the parameter for the reverse direction must be chosen to be
distinguishable from each other. For example, we can add "s2c_" distinguishable from each other. For example, we can add "server_"
prefix to parameters affecting data sent from a server and "c2s_" prefix to parameters affecting data sent from a server and "client_"
prefix to ones affecting data sent from a client to make them prefix to ones affecting data sent from a client to make them
distinguishable. distinguishable.
A server MUST NOT accept a PMCE offer together with another extension A server MUST NOT accept a PMCE extension negotiation offer together
if the PMCE will conflict with the extension on use of the RSV1 bit. with another extension if the PMCE will conflict with the extension
A client that receives a response accepting a PMCE offer together on use of the RSV1 bit. A client that receives a response accepting
with such an extension MUST _Fail the WebSocket Connection_. a PMCE extension negotiation offer together with such an extension
MUST _Fail the WebSocket Connection_.
A server MUST NOT accept a PMCE offer together with another extension A server MUST NOT accept a PMCE extension negotiation offer together
if the PMCE will be applied to output of the extension and any of the with another extension if the PMCE will be applied to output of the
following conditions applies to the extension: extension and any of the following conditions applies to the
extension:
o The extension requires boundary of fragments to be preserved o The extension requires boundary of fragments to be preserved
between output from the extension at the sender and input to the between output from the extension at the sender and input to the
extension at the receiver. extension at the receiver.
o The extension uses the "Extension data" field or any of the o The extension uses the "Extension data" field or any of the
reserved bits on the WebSocket header as per-frame attribute. reserved bits on the WebSocket header as per-frame attribute.
A client receiving a response accepting a PMCE offer together with A client receiving a response accepting a PMCE extension negotiation
such an extension MUST _Fail the WebSocket Connection_. offer together with such an extension MUST _Fail the WebSocket
Connection_.
A server declines all offered PMCEs by not including any element with A server declines all offered PMCEs by not including any element with
PMCE names. If a server responds with no PMCE element in the PMCE names. If a server responds with no PMCE element in the
"Sec-WebSocket-Extensions" header, both endpoints proceed without "Sec-WebSocket-Extensions" header, both endpoints proceed without
Per-message Compression once _the WebSocket Connection is Per-message Compression once _the WebSocket Connection is
established_. established_.
If a server gives an invalid response, such as accepting a PMCE that If a server gives an invalid response, such as accepting a PMCE that
the client did not offer, the client MUST _Fail the WebSocket the client did not offer, the client MUST _Fail the WebSocket
Connection_. Connection_.
skipping to change at page 13, line 8 skipping to change at page 14, line 8
extension to process incoming messages, deliver the _A WebSocket extension to process incoming messages, deliver the _A WebSocket
Message Has Been Received_ event to the application layer with the Message Has Been Received_ event to the application layer with the
received message payload and header values as-is. Otherwise, pass received message payload and header values as-is. Otherwise, pass
the message payload and header values to the extension next to the the message payload and header values to the extension next to the
PMCE as-is. If the extension expects frames as input, build a frame PMCE as-is. If the extension expects frames as input, build a frame
for the message and pass it. for the message and pass it.
7. Intermediaries 7. Intermediaries
When an intermediary proxies a WebSocket connection, the intermediary When an intermediary proxies a WebSocket connection, the intermediary
MAY add, change or remove Per-message Compression on the messages. MAY add, change or remove Per-message Compression on the messages if
Such a change must not be made if the new combination of extensions the intermediary meets all of the following conditions:
after the change doesn't conform to the constraints of the
extensions. The elements in the "Sec-WebSocket-Extensions" for the o The intermediary understands that Per-message Compression.
PMCE in the opening handshakes with the connected client and server
must be altered by the intermediary accordingly to match the new o The intermediary can read all of proxied data including the
combination of extensions. opening handshake request, opening handshake response, and
messages.
o The intermediary can alter the proxied data before forwarding them
accordingly to conform to the constraints of the new combination
of extensions. For example, if a PMCE is removed from messages,
the corresponding element in the "Sec-WebSocket-Extensions" in the
opening handshake response must also be removed.
Otherwise, the intermediary MUST NOT make any change on the proxied
data.
8. permessage-deflate extension 8. permessage-deflate extension
This section specifies a specific PMCE called "permessage-deflate". This section specifies a specific PMCE called "permessage-deflate".
It compresses the payload of a message using the DEFLATE algorithm It compresses the payload of a message using the DEFLATE algorithm
[RFC1951] and the byte boundary aligning method introduced in [RFC1951] and the byte boundary aligning method introduced in
[RFC1979]. [RFC1979].
This section uses the term "byte" with the same meaning as RFC1951, This section uses the term "byte" with the same meaning as RFC1951,
i.e. 8 bits stored or transmitted as a unit (same as an octet). i.e. 8 bits stored or transmitted as a unit (same as an octet).
The registered extension name for this extension is The registered extension name for this extension is
"permessage-deflate". "permessage-deflate".
Four extension parameters are defined for permessage-deflate to help Four extension parameters are defined for permessage-deflate to help
endpoints manage per-connection resource usage. endpoints manage per-connection resource usage.
o "s2c_no_context_takeover" o "server_no_context_takeover"
o "c2s_no_context_takeover" o "client_no_context_takeover"
o "s2c_max_window_bits" o "server_max_window_bits"
o "c2s_max_window_bits" o "client_max_window_bits"
These represent two methods of constraining memory usage that may be These represent two methods (no_context_takeover and max_window_bits)
applied independently to either direction of WebSocket traffic. The of constraining memory usage that may be applied independently to
prefixes c2s and s2c are used to indicate the client-to-server either direction of WebSocket traffic. The extension parameters with
channel and the server-to-client channel respectively. All four the client_ prefix are used to negotiate DEFLATE parameters to
parameters are defined for both a client's offer and a server's control compression on messages sent by a client and received by a
server. The client refers to parameters with the client_ prefix to
configure its compressor, while the server refers to them to
configure its decompressor. The extension parameters with the
server_ prefix are used to negotiate DEFLATE parameters to control
compression on messages sent by a server and received by a client.
The server refers to parameters with the server_ prefix to configure
its compressor, while the client refers to them to configure its
decompressor. All four parameters are defined for both a client's
extension negotiation offer and a server's extension negotiation
response. response.
A server MUST decline an offer for this extension if any of the A server MUST decline an extension negotiation offer for this
following conditions is met: extension if any of the following conditions is met:
o The offer has any extension parameter not defined for use in an o The offer has any extension parameter not defined for use in an
offer. offer.
o The offer has any extension parameter with an invalid value. o The offer has any extension parameter with an invalid value.
o The offer has multiple extension parameters with the same name. o The offer has multiple extension parameters with the same name.
o The server doesn't support the offered configuration. o The server doesn't support the offered configuration.
A client MUST _Fail the WebSocket Connection_ if the peer server A client MUST _Fail the WebSocket Connection_ if the peer server
accepted an offer for this extension with a response meeting any of accepted an extension negotiation offer for this extension with an
the following condition: extension negotiation response meeting any of the following
condition:
o The response has any extension parameter not defined for use in a o The response has any extension parameter not defined for use in a
response. response.
o The response has any extension parameter with an invalid value. o The response has any extension parameter with an invalid value.
o The response has multiple extension parameters with the same name. o The response has multiple extension parameters with the same name.
o The client doesn't support the configuration the response o The client doesn't support the configuration the response
represents. represents.
The term "LZ77 sliding window" used in this section means the buffer The term "LZ77 sliding window" used in this section means the buffer
storing recently processed input. The LZ77 algorithm searches the storing recently processed input. The LZ77 algorithm searches the
buffer for match with the next input. buffer for match with the next input.
8.1. Method Parameters 8.1. Method Parameters
8.1.1. Context Takeover Control 8.1.1. Context Takeover Control
8.1.1.1. s2c_no_context_takeover 8.1.1.1. server_no_context_takeover
A client MAY include the "s2c_no_context_takeover" extension A client MAY include the "server_no_context_takeover" extension
parameter in an offer. This parameter has no value. Using this parameter in an extension negotiation offer. This extension
parameter, a client prevents the peer server from using the same LZ77 parameter has no value. By including this extension parameter in an
sliding window it used to build frames of the last sent message to extension negotiation offer, a client prevents the peer server from
build frames of the next message. If the peer server doesn't use the using the same LZ77 sliding window it used to build frames of the
same LZ77 sliding window to compress multiple messages, the client last sent message to build frames of the next message. If the peer
doesn't need to reserve memory to retain the LZ77 sliding window in server doesn't use the same LZ77 sliding window to compress multiple
between messages. messages, the client doesn't need to reserve memory to retain the
LZ77 sliding window in between messages.
A server accepts an offer with the "s2c_no_context_takeover" Absence of this extension parameter in an extension negotiation offer
extension parameter by including the "s2c_no_context_takeover" indicates that the client can receive a message which the server has
extension parameter in the response. This server-to-client parameter built using the same LZ77 sliding window the server used to build the
has no value. last sent message.
It is RECOMMENDED that a server supports the client-to-server A server accepts an extension negotiation offer including the
"s2c_no_context_takeover" extension parameter. "server_no_context_takeover" extension parameter by including the
"server_no_context_takeover" extension parameter in an extension
negotiation response. The "server_no_context_takeover" extension
parameter in an extension negotiation response has no value.
A server MAY include the "s2c_no_context_takeover" extension It is RECOMMENDED that a server supports the
parameter in a response even if the offer to accept by the response "server_no_context_takeover" extension parameter in an extension
doesn't have "s2c_no_context_takeover" extension parameter. negotiation offer.
8.1.1.2. c2s_no_context_takeover A server MAY include the "server_no_context_takeover" extension
parameter in an extension negotiation response even if the extension
negotiation offer being accepted by the extension negotiation
response didn't have the "server_no_context_takeover" extension
parameter.
A client MAY include the "c2s_no_context_takeover" extension 8.1.1.2. client_no_context_takeover
parameter in an offer. This parameter has no value. Using this
parameter, a client tells the peer server a hint that even if the
server doesn't send the "c2s_no_context_takeover" extension
parameter, the client is not going to use the same LZ77 sliding
window it used to build frames of the last sent message to build
frames of the next message.
A server MAY include the "c2s_no_context_takeover" extension A client MAY include the "client_no_context_takeover" extension
parameter in a response. If the received offer has the parameter in an extension negotiation offer. This extension
"c2s_no_context_takeover" extension parameter, the server may either parameter has no value. By including this extension parameter in an
ignore it or use it to avoid taking over an LZ77 sliding window extension negotiation offer, a client informs the peer server a hint
unnecessarily by specifying "c2s_no_context_takeover" extension that even if the server won't include the
parameter in the response. This parameter has no value. Using this "client_no_context_takeover" extension parameter in the extension
parameter, a server prevents the peer client from using the same LZ77 negotiation response to the offer, the client is not going to use the
sliding window it used to build frames of the last sent message to same LZ77 sliding window it used to build frames of the last sent
build frames for the next message. This reduces the amount of memory message to build frames of the next message.
that the server has to reserve for the connection, in the same way
the "s2c_no_context_takeover" extension parameter does for the
client.
A client MUST support server-to-client "c2s_no_context_takeover" A server MAY include the "client_no_context_takeover" extension
extension parameter. parameter in an extension negotiation response. If the received
extension negotiation offer includes the "client_no_context_takeover"
extension parameter, the server may either ignore it or use it to
avoid taking over an LZ77 sliding window unnecessarily by including
"client_no_context_takeover" extension parameter in the extension
negotiation response to the offer. The "client_no_context_takeover"
extension parameter in an extension negotiation response has no
value. By including the "client_no_context_takeover" extension
parameter in an extension negotiation response, a server prevents the
peer client from using the same LZ77 sliding window it used to build
frames of the last sent message to build frames for the next message.
This reduces the amount of memory that the server has to reserve for
the connection.
Absence of this extension parameter in an extension negotiation
response indicates that the server can receive a message which the
client has built using the same LZ77 sliding window the client used
to build the last sent message.
A client MUST support the "client_no_context_takeover" extension
parameter in an extension negotiation response.
8.1.2. Limiting the LZ77 sliding window size 8.1.2. Limiting the LZ77 sliding window size
8.1.2.1. s2c_max_window_bits 8.1.2.1. server_max_window_bits
A client MAY include the "s2c_max_window_bits" extension parameter in A client MAY include the "server_max_window_bits" extension parameter
an offer. This parameter has a decimal integer value without leading in an extension negotiation offer. This extension parameter has a
zeroes between 8 to 15 inclusive indicating the base-2 logarithm of decimal integer value without leading zeroes between 8 to 15
the LZ77 sliding window size. Absence of this parameter in an offer inclusive indicating the base-2 logarithm of the LZ77 sliding window
indicates that the client is ready to receive messages compressed size and MUST conform to the ABNF below.
using an LZ77 sliding window of up to 32,768 bytes.
s2c_max_window_bits = 1*DIGIT server_max_window_bits = 1*DIGIT
Using this parameter, a client limits the LZ77 sliding window size By including this parameter in an extension negotiation offer, a
that the server uses to compress messages. If the peer server uses client limits the LZ77 sliding window size that the server uses to
small LZ77 sliding window to compress messages, the client can reduce compress messages. If the peer server uses small LZ77 sliding window
the memory for the LZ77 sliding window. to compress messages, the client can reduce the memory for the LZ77
sliding window.
A server declines an offer with this parameter if the server doesn't A server declines an extension negotiation offer with this extension
support it. parameter if the server doesn't support it.
A server accepts an offer with this extension parameter by including Absence of this extension parameter in an extension negotiation offer
the "s2c_max_window_bits" extension parameter with the same or indicates that the client can receive messages compressed using an
smaller value as the offer in the response. This server-to-client LZ77 sliding window of up to 32,768 bytes.
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.
s2c_max_window_bits = 1*DIGIT A server accepts an extension negotiation offer with this extension
parameter by including the "server_max_window_bits" extension
parameter in the extension negotiation response with the same or
smaller value as the extension negotiation offer. The
"server_max_window_bits" extension parameter in an extension
negotiation response has a decimal integer value without leading
zeroes between 8 to 15 inclusive indicating the base-2 logarithm of
the LZ77 sliding window size and MUST conform to the ABNF below.
A server MAY include the "s2c_max_window_bits" extension parameter in server_max_window_bits = 1*DIGIT
a response even if the offer to accept by the response doesn't have
"s2c_max_window_bits" extension parameter.
8.1.2.2. c2s_max_window_bits A server MAY include the "server_max_window_bits" extension parameter
in an extension negotiation response even if the extension
negotiation offer being accepted by the extension negotiation
response didn't include the "server_max_window_bits" extension
parameter.
A client MAY include the "c2s_max_window_bits" extension parameter in 8.1.2.2. client_max_window_bits
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. If a value is
specified for this parameter, the value MUST conform to the ABNF
below.
c2s_max_window_bits = 1*DIGIT A client MAY include the "client_max_window_bits" extension parameter
in an extension negotiation offer. This extension 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. If a value is specified for this extension parameter,
the value MUST conform to the ABNF below.
Using this parameter, a client tells the peer server that the client client_max_window_bits = 1*DIGIT
supports the server-to-client "c2s_max_window_bits" extension
parameter, and optionally a hint by including a parameter value. 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 By including this extension parameter in an extension negotiation
parameter, the server MAY include the "c2s_max_window_bits" extension offer, a client informs the peer server that the client supports the
parameter in the response to the offer. If the "c2s_max_window_bits" "client_max_window_bits" extension parameter in an extension
extension parameter in the received offer has a value, the server may negotiation response, and optionally a hint by including an extension
either ignore this value or use this value to avoid allocating an parameter value. If the "client_max_window_bits" extension parameter
unnecessarily big LZ77 sliding window by specifying in an extension negotiation offer has a value, the extension
"c2s_max_window_bits" extension parameter with a value equal to or parameter also informs the peer server a hint that even if the server
smaller than the received value in the response. This server-to- won't includes the "client_max_window_bits" extension parameter in an
client parameter has a decimal integer value without leading zeroes extension negotiation response with a value greater than one in the
between 8 to 15 inclusive indicating the base-2 logarithm of the LZ77 extension negotiation offer or the server doesn't include the
sliding window size. extension parameter at all, the client is not going to use LZ77
sliding window size greater than the size specified by the value in
the extension negotiation offer to compress messages.
c2s_max_window_bits = 1*DIGIT 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 to the offer. If the "client_max_window_bits"
extension parameter in a 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
including the "client_max_window_bits" extension parameter in the
extension negotiation response to the offer with a value equal to or
smaller than the received value. The "client_max_window_bits"
extension parameter in an extension negotiation response has a
decimal integer value without leading zeroes between 8 to 15
inclusive indicating the base-2 logarithm of the LZ77 sliding window
size and MUST conform to the ABNF below.
Using this server-to-client parameter, a server limits the LZ77 client_max_window_bits = 1*DIGIT
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 By including this extension parameter in an extension negotiation
parameter, the server MUST NOT include the "c2s_max_window_bits" response, a server limits the LZ77 sliding window size that the
extension parameter in the response to the offer. client uses to compress messages. This reduces the amount of memory
that the server has to reserve for the connection.
Absence of this parameter in an response indicates that the server is If a received extension negotiation offer doesn't have the
ready to receive messages compressed using an LZ77 sliding window of "client_max_window_bits" extension parameter, the server MUST NOT
up to 32,768 bytes. include the "client_max_window_bits" extension parameter in an
extension negotiation response to the offer.
Absence of this extension parameter in an extension negotiation
response indicates that the server can receive messages compressed
using an LZ77 sliding window of up to 32,768 bytes.
8.1.3. Example 8.1.3. Example
The simplest "Sec-WebSocket-Extensions" header in a client's opening The simplest "Sec-WebSocket-Extensions" header in a client's opening
handshake to offer use of the permessage-deflate is the following: handshake to offer use of the permessage-deflate is the following:
Sec-WebSocket-Extensions: permessage-deflate Sec-WebSocket-Extensions: permessage-deflate
Since the "c2s_max_window_bits" extension parameter is not specified, Since the "client_max_window_bits" extension parameter is not
the server may not accept the offer with the "c2s_max_window_bits" included in this extension negotiation offer, the server MUST NOT
extension parameter. The simplest "Sec-WebSocket-Extensions" header accept the offer with an extension negotiation response including the
in a server's opening handshake to accept use of the permessage- "client_max_window_bits" extension parameter. The simplest
deflate is the same. "Sec-WebSocket-Extensions" header in a server's opening handshake to
accept use of the permessage-deflate is the same.
The following offer sent by a client is asking the server to use the The following extension negotiation offer sent by a client is asking
LZ77 sliding window size of 1,024 bytes or less and declaring that the server to use the LZ77 sliding window size of 1,024 bytes or less
the client can accept the "c2s_max_window_bits" extension parameter. and declaring that the client supports the "client_max_window_bits"
extension parameter in an extension negotiation response.
Sec-WebSocket-Extensions: Sec-WebSocket-Extensions:
permessage-deflate; permessage-deflate;
c2s_max_window_bits; s2c_max_window_bits=10 client_max_window_bits; server_max_window_bits=10
This offer might be rejected by the server because the server doesn't This extension negotiation offer might be rejected by the server
support the "s2c_max_window_bits" extension parameter. This is fine because the server doesn't support the "server_max_window_bits"
if the client cannot support a larger sliding window size, but if the extension parameter in an extension negotiation offer. This is fine
client wants to fallback to the "permessage-deflate" without the if the client cannot receive messages compressed using a larger
"s2c_max_window_bits" option, the client should offer the fallback sliding window size, but if the client wants to fallback to the
option explicitly like this: "permessage-deflate" without the "server_max_window_bits" extension
parameter, the client can offer the fallback option explicitly like
this:
Sec-WebSocket-Extensions: Sec-WebSocket-Extensions:
permessage-deflate; permessage-deflate;
c2s_max_window_bits; s2c_max_window_bits=10, client_max_window_bits; server_max_window_bits=10,
permessage-deflate; permessage-deflate;
c2s_max_window_bits client_max_window_bits
This example offers two configurations so that the server can accept This extension negotiation offer lists two configurations so that the
permessage-deflate by picking a supported one. To accept the first server can accept permessage-deflate by picking a supported one. To
option, the server might send back, for example: accept the first option, the server might send back, for example:
Sec-WebSocket-Extensions: Sec-WebSocket-Extensions:
permessage-deflate; s2c_max_window_bits=10 permessage-deflate; server_max_window_bits=10
And to accept the second option, the server might send back, for And to accept the second option, the server might send back, for
example: example:
Sec-WebSocket-Extensions: permessage-deflate Sec-WebSocket-Extensions: permessage-deflate
8.2. Message Payload Transformation 8.2. Message Payload Transformation
8.2.1. Compression 8.2.1. Compression
skipping to change at page 19, line 43 skipping to change at page 21, line 44
to 0 and DEFLATE blocks with the "BFINAL" bit set to 1. to 0 and DEFLATE blocks with the "BFINAL" bit set to 1.
o When any DEFLATE block with the "BFINAL" bit set to 1 doesn't end o When any DEFLATE block with the "BFINAL" bit set to 1 doesn't end
at byte boundary, an endpoint adds minimal padding bits of 0 to at byte boundary, an endpoint adds minimal padding bits of 0 to
make it end at byte boundary. The next DEFLATE block follows the make it end at byte boundary. The next DEFLATE block follows the
padded data if any. padded data if any.
An endpoint MUST NOT use an LZ77 sliding window longer than 32,768 An endpoint MUST NOT use an LZ77 sliding window longer than 32,768
bytes to compress messages to send. bytes to compress messages to send.
If the "agreed parameters" contain the "c2s_no_context_takeover" If the "agreed parameters" contain the "client_no_context_takeover"
extension parameter, the client MUST start compressing each new extension parameter, the client MUST start compressing each new
message with an empty LZ77 sliding window. Otherwise, the client MAY message with an empty LZ77 sliding window. Otherwise, the client MAY
take over the LZ77 sliding window used to build the last compressed take over the LZ77 sliding window used to build the last compressed
message. Note that even if the client has included the message. Note that even if the client has included the
"c2s_no_context_takeover" extension parameter in its offer, the "client_no_context_takeover" extension parameter in its offer, the
client MAY take over the LZ77 sliding window used to build the last client MAY take over the LZ77 sliding window used to build the last
compressed message if the "agreed parameters" doesn't contain the compressed message if the "agreed parameters" doesn't contain the
"c2s_no_context_takeover" extension parameter. The client-to-server "client_no_context_takeover" extension parameter. The client-to-
"c2s_no_context_takeover" extension parameter is just a hint for the server "client_no_context_takeover" extension parameter is just a
server to build a response. hint for the server to build a response.
If the "agreed parameters" contain the "s2c_no_context_takeover" If the "agreed parameters" contain the "server_no_context_takeover"
extension parameter, the server MUST start compressing each new extension parameter, the server MUST start compressing each new
message with an empty LZ77 sliding window. Otherwise, the server MAY message with an empty LZ77 sliding window. Otherwise, the server MAY
take over the LZ77 sliding window used to build the last compressed take over the LZ77 sliding window used to build the last compressed
message. message.
If the "agreed parameters" contain the "c2s_max_window_bits" If the "agreed parameters" contain the "client_max_window_bits"
extension parameter with a value of w, the client MUST NOT use an extension parameter with a value of w, the client MUST NOT use an
LZ77 sliding window longer than the w-th power of 2 bytes to compress LZ77 sliding window longer than the w-th power of 2 bytes to compress
messages to send. Note that even if the client has included in its messages to send. Note that even if the client has included in its
offer the "c2s_max_window_bits" extension parameter with a value offer the "client_max_window_bits" extension parameter with a value
smaller than one in the "agreed parameters", the client MAY use an smaller than one in the "agreed parameters", the client MAY use an
LZ77 sliding window with any size to compress messages to send as LZ77 sliding window with any size to compress messages to send as
long as the size conforms to the "agreed parameters". The client-to- long as the size conforms to the "agreed parameters". The client-to-
server "c2s_max_window_bits" extension parameter is just a hint for server "client_max_window_bits" extension parameter is just a hint
the server to build a response. for the server to build a response.
If the "agreed parameters" contain the "s2c_max_window_bits" If the "agreed parameters" contain the "server_max_window_bits"
extension parameter with a value of w, the server MUST NOT use an extension parameter with a value of w, the server MUST NOT use an
LZ77 sliding window longer than the w-th power of 2 bytes to compress LZ77 sliding window longer than the w-th power of 2 bytes to compress
messages to send. messages to send.
8.2.2. Decompression 8.2.2. Decompression
An endpoint uses the following algorithm to decompress a message. An endpoint uses the following algorithm to decompress a message.
1. Append 4 octets of 0x00 0x00 0xff 0xff to the tail end of the 1. Append 4 octets of 0x00 0x00 0xff 0xff to the tail end of the
payload of the message. payload of the message.
2. Decompress the resulting data using DEFLATE. 2. Decompress the resulting data using DEFLATE.
If the "agreed parameters" contain the "s2c_no_context_takeover" If the "agreed parameters" contain the "server_no_context_takeover"
extension parameter, the client MAY start decompressing each new extension parameter, the client MAY start decompressing each new
message with an empty LZ77 sliding window. Otherwise, the client message with an empty LZ77 sliding window. Otherwise, the client
MUST take over the LZ77 sliding window used to process the last MUST take over the LZ77 sliding window used to process the last
compressed message. compressed message.
If the "agreed parameters" contain the "c2s_no_context_takeover" If the "agreed parameters" contain the "client_no_context_takeover"
extension parameter, the server MAY start decompressing each new extension parameter, the server MAY start decompressing each new
message with an empty LZ77 sliding window. Otherwise, the server message with an empty LZ77 sliding window. Otherwise, the server
MUST take over the LZ77 sliding window used to process the last MUST take over the LZ77 sliding window used to process the last
compressed message. Note that even if the client has included the compressed message. Note that even if the client has included the
"c2s_no_context_takeover" extension parameter in its offer, the "client_no_context_takeover" extension parameter in its offer, the
server MUST take over the LZ77 sliding window used to process the server MUST take over the LZ77 sliding window used to process the
last compressed message if the "agreed parameters" doesn't contain last compressed message if the "agreed parameters" doesn't contain
the "c2s_no_context_takeover" extension parameter. The client-to- the "client_no_context_takeover" extension parameter. The client-to-
server "c2s_no_context_takeover" extension parameter is just a hint server "client_no_context_takeover" extension parameter is just a
for the server to build a response. hint for the server to build a response.
If the "agreed parameters" contain the "s2c_max_window_bits" If the "agreed parameters" contain the "server_max_window_bits"
extension parameter with a value of w, the client MAY reduce the size extension parameter with a value of w, the client MAY reduce the size
of its LZ77 sliding window to decompress received messages down to of its LZ77 sliding window to decompress received messages down to
the w-th power of 2 bytes. Otherwise, the client MUST use a 32,768 the w-th power of 2 bytes. Otherwise, the client MUST use a 32,768
byte LZ77 sliding window to decompress received messages. byte LZ77 sliding window to decompress received messages.
If the "agreed parameters" contain the "c2s_max_window_bits" If the "agreed parameters" contain the "client_max_window_bits"
extension parameter with a value of w, the server MAY reduce the size extension parameter with a value of w, the server MAY reduce the size
of its LZ77 sliding window to decompress received messages down to of its LZ77 sliding window to decompress received messages down to
the w-th power of 2 bytes. Otherwise, the server MUST use a 32,768 the w-th power of 2 bytes. Otherwise, the server MUST use a 32,768
byte LZ77 sliding window to decompress received messages. Note that byte LZ77 sliding window to decompress received messages. Note that
even if the client has included in its offer the even if the client has included in its offer the
"c2s_max_window_bits" extension parameter with a value smaller that "client_max_window_bits" extension parameter with a value smaller
one in the "agreed parameters", the client MUST use an LZ77 sliding that one in the "agreed parameters", the client MUST use an LZ77
window of a size that conforms the "agreed parameters" to compress sliding window of a size that conforms the "agreed parameters" to
messages to send. The client-to-server "c2s_max_window_bits" compress messages to send. The client-to-server
extension parameter is just a hint for the server to build a "client_max_window_bits" extension parameter is just a hint for the
response. server to build a response.
8.2.3. Examples 8.2.3. Examples
This section introduces examples of how the permessage-deflate This section introduces examples of how the permessage-deflate
transforms messages. transforms messages.
8.2.3.1. A message compressed using 1 compressed DEFLATE block 8.2.3.1. A message compressed using 1 compressed DEFLATE block
Suppose that an endpoint sends a text message "Hello". If the Suppose that an endpoint sends a text message "Hello". If the
endpoint uses 1 compressed DEFLATE block (compressed with fixed endpoint uses 1 compressed DEFLATE block (compressed with fixed
skipping to change at page 22, line 46 skipping to change at page 24, line 49
8.2.3.2. Sharing LZ77 Sliding Window 8.2.3.2. Sharing LZ77 Sliding Window
Suppose that a client has sent a message "Hello" as a compressed Suppose that a client has sent a message "Hello" as a compressed
message and will send the same message "Hello" again as a compressed message and will send the same message "Hello" again as a compressed
message. message.
0xf2 0x48 0xcd 0xc9 0xc9 0x07 0x00 0xf2 0x48 0xcd 0xc9 0xc9 0x07 0x00
This is the payload of the first message the client has sent. If the This is the payload of the first message the client has sent. If the
"agreed parameters" contain the "c2s_no_context_takeover" extension "agreed parameters" contain the "client_no_context_takeover"
parameter, the client compresses the payload of the next message into extension parameter, the client compresses the payload of the next
the same bytes (if the client uses the same "BTYPE" value and message into the same bytes (if the client uses the same "BTYPE"
"BFINAL" value). So, the payload of the second message will be: value and "BFINAL" value). So, the payload of the second message
will be:
0xf2 0x48 0xcd 0xc9 0xc9 0x07 0x00 0xf2 0x48 0xcd 0xc9 0xc9 0x07 0x00
When concatenated with the first message: When concatenated with the first message:
0xf2 0x48 0xcd 0xc9 0xc9 0x07 0x00 0xf2 0x48 0xcd 0xc9 0xc9 0xf2 0x48 0xcd 0xc9 0xc9 0x07 0x00 0xf2 0x48 0xcd 0xc9 0xc9
0x07 0x00 0x07 0x00
If the "agreed parameters" did not contain the If the "agreed parameters" did not contain the
"c2s_no_context_takeover" extension parameter, the client can "client_no_context_takeover" extension parameter, the client can
compress the payload of the next message into shorter bytes by compress the payload of the next message into shorter bytes by
referencing the history in the LZ77 sliding window. So, the payload referencing the history in the LZ77 sliding window. So, the payload
of the second message will be: of the second message will be:
0xf2 0x00 0x11 0x00 0x00 0xf2 0x00 0x11 0x00 0x00
When concatenated with the first message: When concatenated with the first message:
0xf2 0x48 0xcd 0xc9 0xc9 0x07 0x00 0xf2 0x00 0x11 0x00 0x00 0xf2 0x48 0xcd 0xc9 0xc9 0x07 0x00 0xf2 0x00 0x11 0x00 0x00
 End of changes. 75 change blocks. 
231 lines changed or deleted 310 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/