draft-ietf-hybi-permessage-compression-09.txt   draft-ietf-hybi-permessage-compression-10.txt 
HyBi Working Group T. Yoshino HyBi Working Group T. Yoshino
Internet-Draft Google, Inc. Internet-Draft Google, Inc.
Intended status: Standards Track April 25, 2013 Intended status: Standards Track June 19, 2013
Expires: October 27, 2013 Expires: December 21, 2013
Compression Extensions for WebSocket Compression Extensions for WebSocket
draft-ietf-hybi-permessage-compression-09 draft-ietf-hybi-permessage-compression-10
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 October 27, 2013. This Internet-Draft will expire on December 21, 2013.
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 28 skipping to change at page 2, line 28
5. Extension Negotiation . . . . . . . . . . . . . . . . . . . . 7 5. Extension Negotiation . . . . . . . . . . . . . . . . . . . . 7
5.1. Negotiation Examples . . . . . . . . . . . . . . . . . . . 8 5.1. Negotiation Examples . . . . . . . . . . . . . . . . . . . 8
6. Framing . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 6. Framing . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
6.1. Compression . . . . . . . . . . . . . . . . . . . . . . . 9 6.1. Compression . . . . . . . . . . . . . . . . . . . . . . . 9
6.2. Decompression . . . . . . . . . . . . . . . . . . . . . . 10 6.2. Decompression . . . . . . . . . . . . . . . . . . . . . . 10
7. Intermediaries . . . . . . . . . . . . . . . . . . . . . . . . 12 7. Intermediaries . . . . . . . . . . . . . . . . . . . . . . . . 12
8. permessage-deflate extension . . . . . . . . . . . . . . . . . 13 8. permessage-deflate extension . . . . . . . . . . . . . . . . . 13
8.1. Method Parameters . . . . . . . . . . . . . . . . . . . . 14 8.1. Method Parameters . . . . . . . . . . . . . . . . . . . . 14
8.1.1. Context Takeover Control . . . . . . . . . . . . . . . 14 8.1.1. Context Takeover Control . . . . . . . . . . . . . . . 14
8.1.2. Limiting the LZ77 sliding window size . . . . . . . . 15 8.1.2. Limiting the LZ77 sliding window size . . . . . . . . 15
8.1.3. Example . . . . . . . . . . . . . . . . . . . . . . . 15 8.1.3. Example . . . . . . . . . . . . . . . . . . . . . . . 16
8.2. Message Payload Transformation . . . . . . . . . . . . . . 16 8.2. Message Payload Transformation . . . . . . . . . . . . . . 17
8.2.1. Compression . . . . . . . . . . . . . . . . . . . . . 16 8.2.1. Compression . . . . . . . . . . . . . . . . . . . . . 17
8.2.2. Decompression . . . . . . . . . . . . . . . . . . . . 18 8.2.2. Decompression . . . . . . . . . . . . . . . . . . . . 18
8.2.3. Examples . . . . . . . . . . . . . . . . . . . . . . . 18 8.2.3. Examples . . . . . . . . . . . . . . . . . . . . . . . 19
8.3. Implementation Notes . . . . . . . . . . . . . . . . . . . 21 8.3. Implementation Notes . . . . . . . . . . . . . . . . . . . 22
8.4. Intermediaries . . . . . . . . . . . . . . . . . . . . . . 21 8.4. Intermediaries . . . . . . . . . . . . . . . . . . . . . . 22
9. Security Considerations . . . . . . . . . . . . . . . . . . . 23 9. Security Considerations . . . . . . . . . . . . . . . . . . . 23
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24
10.1. Registration of the "permessage-deflate" WebSocket 10.1. Registration of the "permessage-deflate" WebSocket
Extension Name . . . . . . . . . . . . . . . . . . . . . . 24 Extension Name . . . . . . . . . . . . . . . . . . . . . . 24
10.2. Registration of the "Per-message Compressed" WebSocket 10.2. Registration of the "Per-message Compressed" WebSocket
Framing Header Bit . . . . . . . . . . . . . . . . . . . . 24 Framing Header Bit . . . . . . . . . . . . . . . . . . . . 24
11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 25 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 25
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26
12.1. Normative References . . . . . . . . . . . . . . . . . . . 26 12.1. Normative References . . . . . . . . . . . . . . . . . . . 26
12.2. Informative References . . . . . . . . . . . . . . . . . . 26 12.2. Informative References . . . . . . . . . . . . . . . . . . 26
skipping to change at page 6, line 5 skipping to change at page 5, line 23
Message payload (or payload of a message) means concatenation of the Message payload (or payload of a message) means concatenation of the
payload data portion of all frames consisting the message. payload data portion of all frames consisting the message.
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. Such an extension is applied to outgoing data from the handshake. Such an extension is applied to outgoing data from the
application right after X on sender side but applied right before X application right after X on sender side but applied right before X
to incoming data from the underlying transport. to incoming data from the underlying transport.
Accept an extension offer means including a corresponding response in
the "Sec-WebSocket-Extensions" header in the server's opening
handshake.
Decline an extension offer means not including a corresponding
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 18 skipping to change at page 7, line 18
"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 client's the PMCE in the "Sec-WebSocket-Extensions" header in the client's
opening handshake of the WebSocket connection. Extension parameters opening handshake of the WebSocket connection. Extension parameters
in the element represent the PMCE offer in detail. For example, a in the element represent the PMCE offer in detail. For example, a
client lists preferred configuration parameter values for the client lists preferred configuration parameter values for the
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. parameters. The order of elements means the client's preference. An
element precedes another element has higher preference. It is
RECOMMENDED that a server accepts PMCEs with higher preference if the
server supports it.
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 offers. For example, an
skipping to change at page 13, line 18 skipping to change at page 13, line 18
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".
For an offer for this extension, the following 3 extension parameters For an offer for this extension, the following 4 extension parameters
are defined. are defined. If needed to distinguish from ones for a response,
these parameters are called with a prefix "client-to-server".
o "s2c_no_context_takeover" o "s2c_no_context_takeover"
o "c2s_no_context_takeover"
o "s2c_max_window_bits" o "s2c_max_window_bits"
o "c2s_max_window_bits" o "c2s_max_window_bits"
For a response for this extension, the following 4 extension For a response for this extension, the following 4 extension
parameters are defined. parameters are defined. If needed to distinguish from ones for an
offer, these parameters are called with a prefix "server-to-client".
o "s2c_no_context_takeover" o "s2c_no_context_takeover"
o "c2s_no_context_takeover" o "c2s_no_context_takeover"
o "s2c_max_window_bits" o "s2c_max_window_bits"
o "c2s_max_window_bits" o "c2s_max_window_bits"
A server MUST decline a "permessage-deflate" offer if any of the A server MUST decline an offer for this extension if any of the
following conditions is met: 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 server accepted A client MUST _Fail the WebSocket Connection_ if the peer server
a "permessage-deflate" offer with a response meeting any of the accepted an offer for this extension with a response meeting any of
following condition: 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
A client MAY attach the "s2c_no_context_takeover" extension 8.1.1.1. s2c_no_context_takeover
parameter. The "s2c_no_context_takeover" extension parameter has no
value. Using this extension parameter, a client can prevent the peer
server from using the same LZ77 sliding window it used to build
frames of the last sent message to build frames of the next message.
When the peer server doesn't use the same LZ77 sliding window to
compress multiple messages, the client doesn't need to reserve memory
to retain the LZ77 sliding window in between messages. A server
accepts an offer with this extension parameter by including the
"s2c_no_context_takeover" extension parameter in the response. A
server which accepted an offer with this extension parameter MUST
start the compression of each message with an empty LZ77 sliding
window.
It is RECOMMENDED that servers implement the A client MAY include the "s2c_no_context_takeover" extension
"s2c_no_context_takeover" parameter. parameter to an offer. This parameter has no value. Using this
parameter, a client prevents the peer server from using the same LZ77
sliding window it used to build frames of the last sent message to
build frames of the next message. If the peer server doesn't use the
same LZ77 sliding window to compress multiple messages, the client
doesn't need to reserve memory to retain the LZ77 sliding window in
between messages.
A server MAY attach the "c2s_no_context_takeover" extension A server accepts an offer with the "s2c_no_context_takeover"
parameter. The "c2s_no_context_takeover" extension parameter has no extension parameter by including the "s2c_no_context_takeover"
value. Using this extension parameter, a server can prevent the peer extension parameter in the response. This server-to-client parameter
client from using the same LZ77 sliding window it used to build has no value.
frames of the last sent message to build frames for the next message.
This can reduce the amount of memory that the server has to reserve
for the connection, in the same way the "s2c_no_context_takeover"
extension does for the client. A client that received this parameter
MUST start the compression of each message with an empty LZ77 sliding
window.
It is RECOMMENDED that clients implement the It is RECOMMENDED that a server supports the client-to-server
"c2s_no_context_takeover" parameter. "s2c_no_context_takeover" extension parameter.
8.1.2. Limiting the LZ77 sliding window size A server MAY include the "s2c_no_context_takeover" extension
parameter to a response even if the offer to accept by the response
doesn't have "s2c_no_context_takeover" extension parameter.
A client MAY attach the "s2c_max_window_bits" extension parameter to 8.1.1.2. c2s_no_context_takeover
limit the LZ77 sliding window size that the server uses to compress
messages. This extension parameter 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.
s2c_max_window_bits = 1*DIGIT A client MAY include the "c2s_no_context_takeover" extension
parameter to an offer. This parameter has no value. Using this
parameter, a client tells the peer server a hint that the client is
not likely 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 will decline an offer with this extension parameter if the A server MAY include the "c2s_no_context_takeover" extension
server doesn't support the extension parameter. A server accepts an parameter to a response. This parameter has no value. Using this
offer with this extension parameter by including the extension parameter, a server prevents the peer client from using the same LZ77
parameter with the same value as the offer in the response. If a sliding window it used to build frames of the last sent message to
server accepts an offer with this extension parameter, the server build frames for the next message. This reduces the amount of memory
MUST NOT use LZ77 sliding window size greater than the size specified that the server has to reserve for the connection, in the same way
by the extension parameter to compress messages. the "s2c_no_context_takeover" extension parameter does for the
client.
A client MAY attach the "c2s_max_window_bits" extension parameter if A client MUST support server-to-client "c2s_no_context_takeover"
the client can adjust LZ77 sliding window size based on the extension parameter.
"c2s_max_window_bits" sent by the server. This parameter has no
value.
If a server receives an offer with the "c2s_max_window_bits" 8.1.2. Limiting the LZ77 sliding window size
extension parameter, the server MAY include the "c2s_max_window_bits"
parameter in the response to the offer to limit the LZ77 sliding 8.1.2.1. s2c_max_window_bits
window size that the client uses to build messages. If a server
received and accepts an offer without the "c2s_max_window_bits" A client MAY include the "s2c_max_window_bits" extension parameter to
extension parameter, the server MUST NOT include the an offer. This parameter has a decimal integer value without leading
"c2s_max_window_bits" extension parameter in the response to the
offer. The "c2s_max_window_bits" extension parameter in the server's
opening handshake MUST have a decimal integer value without leading
zeroes between 8 to 15 inclusive indicating the base-2 logarithm of zeroes between 8 to 15 inclusive indicating the base-2 logarithm of
the LZ77 sliding window size. the LZ77 sliding window size.
s2c_max_window_bits = 1*DIGIT
Using this parameter, a client limits the LZ77 sliding window size
that the server uses to compress messages. If the peer server
doesn't use small 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
support it.
A server accepts an offer with this extension parameter by including
the "s2c_max_window_bits" extension parameter with the same or
smaller value as the offer 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.
s2c_max_window_bits = 1*DIGIT
A server MAY include the "s2c_max_window_bits" extension parameter to
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 client MAY include the "c2s_max_window_bits" extension parameter to
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 the client is not likely 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" parameter
in the response to the offer. 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 c2s_max_window_bits = 1*DIGIT
If a client received the "c2s_max_window_bits" extension parameter, Using this server-to-client parameter, a server limits the LZ77
the client MUST NOT use an LZ77 sliding window size greater than the sliding window size that the client uses to compress messages. This
size specified by the extension parameter to build messages. 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.
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 "c2s_max_window_bits" extension parameter is not specified,
the server may not accept the offer with the "c2s_max_window_bits" the server may not accept the offer with the "c2s_max_window_bits"
skipping to change at page 25, line 17 skipping to change at page 25, line 17
Special thanks to Patrick McManus who wrote up the initial Special thanks to Patrick McManus who wrote up the initial
specification of a DEFLATE-based compression extension for the specification of a DEFLATE-based compression extension for the
WebSocket Protocol to which I referred to write this specification. WebSocket Protocol to which I referred to write this specification.
Thank you to the following people who participated in discussions on Thank you to the following people who participated in discussions on
the HyBi WG and contributed ideas and/or provided detailed reviews the HyBi WG and contributed ideas and/or provided detailed reviews
(the list is likely to be incomplete): Adam Rice, Alexey Melnikov, (the list is likely to be incomplete): Adam Rice, Alexey Melnikov,
Arman Djusupov, Bjoern Hoehrmann, Brian McKelvey, Dario Crivelli, Arman Djusupov, Bjoern Hoehrmann, Brian McKelvey, Dario Crivelli,
Greg Wilkins, Inaki Baz Castillo, Jamie Lokier, Joakim Erdfelt, John Greg Wilkins, Inaki Baz Castillo, Jamie Lokier, Joakim Erdfelt, John
A. Tamplin, Julian Reschke, Kenichi Ishibashi, Mark Nottingham, Peter A. Tamplin, Julian Reschke, Kenichi Ishibashi, Mark Nottingham, Peter
Thorson, Roberto Peon and Simone Bordet. Note that people listed Thorson, Roberto Peon, Simone Bordet and Tobias Oberstein. Note that
above didn't necessarily endorse the end result of this work. people listed above didn't necessarily endorse the end result of this
work.
12. References 12. References
12.1. Normative References 12.1. Normative References
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008. Specifications: ABNF", STD 68, RFC 5234, January 2008.
[RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol",
RFC 6455, December 2011. RFC 6455, December 2011.
 End of changes. 25 change blocks. 
77 lines changed or deleted 127 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/