Copy the README over from the Node version.
This commit is contained in:
James Coglan
@@ -0,0 +1,366 @@
|
||||
# websocket-extensions [](http://travis-ci.org/faye/websocket-extensions-ruby)
|
||||
|
||||
A minimal framework that supports the implementation of WebSocket extensions in
|
||||
a way that's decoupled from the main protocol. This library aims to allow a
|
||||
WebSocket extension to be written and used with any protocol library, by
|
||||
defining abstract representations of frames and messages that allow modules to
|
||||
co-operate.
|
||||
|
||||
`websocket-extensions` provides a container for registering extension plugins,
|
||||
and provides all the functions required to negotiate which extensions to use
|
||||
during a session via the `Sec-WebSocket-Extensions` header. By implementing the
|
||||
APIs defined in this document, an extension may be used by any WebSocket library
|
||||
based on this framework.
|
||||
|
||||
## Installation
|
||||
|
||||
```
|
||||
$ gem install websocket-extensions
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
There are two main audiences for this library: authors implementing the
|
||||
WebSocket protocol, and authors implementing extensions. End users of a
|
||||
WebSocket library or an extension should be able to use any extension by passing
|
||||
it as an argument to their chosen protocol library, without needing to know how
|
||||
either of them work, or how the `websocket-extensions` framework operates.
|
||||
|
||||
The library is designed with the aim that any protocol implementation and any
|
||||
extension can be used together, so long as they support the same abstract
|
||||
representation of frames and messages.
|
||||
|
||||
### Data types
|
||||
|
||||
The APIs provided by the framework rely on two data types; extensions will
|
||||
expect to be given data and to be able to return data in these formats:
|
||||
|
||||
#### `Frame`
|
||||
|
||||
`Frame` is a structure representing a single WebSocket frame of any type. Frames
|
||||
are simple objects that must have at least the following properties, which
|
||||
represent the data encoded in the frame:
|
||||
|
||||
| property | description |
|
||||
| ------------ | ------------------------------------------------------------------ |
|
||||
| `final` | `true` if the `FIN` bit is set, `false` otherwise |
|
||||
| `rsv1` | `true` if the `RSV1` bit is set, `false` otherwise |
|
||||
| `rsv2` | `true` if the `RSV2` bit is set, `false` otherwise |
|
||||
| `rsv3` | `true` if the `RSV3` bit is set, `false` otherwise |
|
||||
| `opcode` | the numeric opcode (`0`, `1`, `2`, `8`, `9`, or `10`) of the frame |
|
||||
| `masked` | `true` if the `MASK` bit is set, `false` otherwise |
|
||||
| `masking_key` | a 4-byte `Array` if `masked` is `true`, otherwise `nil` |
|
||||
| `length` | the numeric length of the frame's payload |
|
||||
| `payload` | an `Array` of bytes containing the (unmasked) application data |
|
||||
|
||||
If an extension modifies any of these fields, it should make sure it leaves the
|
||||
frame in a consistent state, e.g. `length` must mirror the actual length of
|
||||
`payload` at all times.
|
||||
|
||||
#### `Message`
|
||||
|
||||
A `Message` represents a complete application message, which can be formed from
|
||||
text, binary and continuation frames. It has the following properties:
|
||||
|
||||
| property | description |
|
||||
| -------- | ---------------------------------------------------------- |
|
||||
| `frames` | an array of `Frame` objects |
|
||||
| `data` | the concatenation of all the frame payloads in the message |
|
||||
|
||||
Again, if an extension modifies a `Message` it must leave it in a consistent
|
||||
state such that `data` is equal to the concatenated payloads in the `frames`
|
||||
array.
|
||||
|
||||
### For driver authors
|
||||
|
||||
A driver author is someone implementing the WebSocket protocol proper, and who
|
||||
wishes end users to be able to use WebSocket extensions with their library.
|
||||
|
||||
At the start of a WebSocket session, on both the client and the server side,
|
||||
they should begin by creating an extension container and adding whichever
|
||||
extensions they want to use.
|
||||
|
||||
```rb
|
||||
require 'websocket/extensions'
|
||||
require 'permessage_deflate'
|
||||
|
||||
exts = WebSocket::Extensions.new
|
||||
exts.add(PermessageDeflate)
|
||||
```
|
||||
|
||||
In the following examples, `exts` refers to this `Extensions` instance.
|
||||
|
||||
#### Client sessions
|
||||
|
||||
Clients will use the methods `generate_offer` and `activate(header)`.
|
||||
|
||||
As part of the handshake process, the client must send a
|
||||
`Sec-WebSocket-Extensions` header to advertise that it supports the registered
|
||||
extensions. This header should be generated using:
|
||||
|
||||
```rb
|
||||
request_headers['Sec-WebSocket-Extensions'] = exts.generate_offer
|
||||
```
|
||||
|
||||
This returns a string, for example `"permessage-deflate;
|
||||
client_max_window_bits"`, that represents all the extensions the client is
|
||||
offering to use, and their parameters. This string may contain multiple offers
|
||||
for the same extension.
|
||||
|
||||
When the client receives the handshake response from the server, it should pass
|
||||
the incoming `Sec-WebSocket-Extensions` header in to `exts` to activate the
|
||||
extensions the server has accepted:
|
||||
|
||||
```rb
|
||||
exts.activate(response_headers['Sec-WebSocket-Extensions'])
|
||||
```
|
||||
|
||||
If the server has sent any extension responses that the client does not
|
||||
recognize, or are in conflict with one another for use of RSV bits, or that use
|
||||
invalid parameters for the named extensions, then `exts.activate` will `raise`.
|
||||
In this event, the client driver should fail the connection with closing code
|
||||
`1010`.
|
||||
|
||||
#### Server sessions
|
||||
|
||||
Servers will use the method `generate_response(header)`.
|
||||
|
||||
A server session needs to generate a `Sec-WebSocket-Extensions` header to send
|
||||
in its handshake response:
|
||||
|
||||
```rb
|
||||
client_offer = request_env['HTTP_SEC_WEBSOCKET_EXTENSIONS']
|
||||
ext_response = exts.generate_response(client_offer)
|
||||
|
||||
response_headers['Sec-WebSocket-Extensions'] = ext_response
|
||||
```
|
||||
|
||||
Calling `exts.generate_response(header)` activates those extensions the client
|
||||
has asked to use, if they are registered, asks each extension for a set of
|
||||
response parameters, and returns a string containing the response parameters for
|
||||
all accepted extensions.
|
||||
|
||||
#### In both directions
|
||||
|
||||
Both clients and servers will use the methods `valid_frame_rsv(frame)`,
|
||||
`process_incoming_message(message)` and `process_outgoing_message(message)`.
|
||||
|
||||
The WebSocket protocol requires that frames do not have any of the `RSV` bits
|
||||
set unless there is an extension in use that allows otherwise. When processing
|
||||
an incoming frame, sessions should pass a `Frame` object to:
|
||||
|
||||
```rb
|
||||
exts.valid_frame_rsv(frame)
|
||||
```
|
||||
|
||||
If this method returns `false`, the session should fail the WebSocket connection
|
||||
with closing code `1002`.
|
||||
|
||||
To pass incoming messages through the extension stack, a session should
|
||||
construct a `Message` object according to the above datatype definitions, and
|
||||
call:
|
||||
|
||||
```rb
|
||||
message = exts.process_incoming_message(message)
|
||||
```
|
||||
|
||||
If any extensions fail to process the message, then this call will `raise` an
|
||||
error and the session should fail the WebSocket connection with closing code
|
||||
`1010`. Otherwise, `message` should be passed on to the application.
|
||||
|
||||
To pass outgoing messages through the extension stack, a session should
|
||||
construct a `Message` as before, and call:
|
||||
|
||||
```rb
|
||||
message = exts.process_outgoing_message(message)
|
||||
```
|
||||
|
||||
If any extensions fail to process the message, then this call will `raise` an
|
||||
error and the session should fail the WebSocket connection with closing code
|
||||
`1010`. Otherwise, each frame in `message.frames` should be written to the
|
||||
transport, after applying `frame.masking_key` to `frame.payload` if required.
|
||||
|
||||
At the end of the WebSocket session (either when the protocol is explicitly
|
||||
ended or the transport connection disconnects), the driver should call:
|
||||
|
||||
```rb
|
||||
exts.close
|
||||
```
|
||||
|
||||
### For extension authors
|
||||
|
||||
An extension author is someone implementing an extension that transforms
|
||||
WebSocket messages passing between the client and server. They would like to
|
||||
implement their extension once and have it work with any protocol library.
|
||||
|
||||
Extension authors will not install `websocket-extensions` or call it directly.
|
||||
Instead, they should implement the following API to allow their extension to
|
||||
plug into the `websocket-extensions` framework.
|
||||
|
||||
An `Extension` is any object that has the following properties:
|
||||
|
||||
| property | description |
|
||||
| -------- | ---------------------------------------------------------------------------- |
|
||||
| `name` | a string containing the name of the extension as used in negotiation headers |
|
||||
| `type` | a string, must be `"permessage"` |
|
||||
| `rsv1` | either `true` if the extension uses the RSV1 bit, `false` otherwise |
|
||||
| `rsv2` | either `true` if the extension uses the RSV2 bit, `false` otherwise |
|
||||
| `rsv3` | either `true` if the extension uses the RSV3 bit, `false` otherwise |
|
||||
|
||||
It must also implement the following methods:
|
||||
|
||||
```rb
|
||||
ext.create_client_session
|
||||
```
|
||||
|
||||
This returns a `ClientSession`, whose interface is defined below.
|
||||
|
||||
```rb
|
||||
ext.create_server_session(offers)
|
||||
```
|
||||
|
||||
This takes an array of offer params and returns a `ServerSession`, whose
|
||||
interface is defined below. For example, if the client handshake contains the
|
||||
offer header:
|
||||
|
||||
```
|
||||
Sec-WebSocket-Extensions: permessage-deflate; server_no_context_takeover; server_max_window_bits=8, \
|
||||
permessage-deflate; server_max_window_bits=15
|
||||
```
|
||||
|
||||
then the `permessage-deflate` extension will receive the call:
|
||||
|
||||
```rb
|
||||
ext.create_server_session([
|
||||
{'server_no_context_takeover' => true, 'server_max_window_bits' => 8},
|
||||
{'server_max_window_bits' => 15}
|
||||
])
|
||||
```
|
||||
|
||||
The extension must decide which set of parameters it wants to accept, if any,
|
||||
and return a `ServerSession` if it wants to accept the parameters and `nil`
|
||||
otherwise.
|
||||
|
||||
#### `ClientSession`
|
||||
|
||||
A `ClientSession` is the type returned by `ext.create_client_session`. It must
|
||||
implement the following methods, as well as the `Session` API listed below.
|
||||
|
||||
```rb
|
||||
clientSession.generate_offer
|
||||
# e.g. -> [
|
||||
# {'server_no_context_takeover' => true, 'server_max_window_bits' => 8},
|
||||
# {'server_max_window_bits' => 15}
|
||||
# ]
|
||||
```
|
||||
|
||||
This must return a set of parameters to include in the client's
|
||||
`Sec-WebSocket-Extensions` offer header. If the session wants to offer multiple
|
||||
configurations, it can return an array of sets of parameters as shown above.
|
||||
|
||||
```rb
|
||||
clientSession.activate(params) # -> true
|
||||
```
|
||||
|
||||
This must take a single set of parameters from the server's handshake response
|
||||
and use them to configure the client session. If the client accepts the given
|
||||
parameters, then this method must return `true`. If it returns any other value,
|
||||
the framework will interpret this as the client rejecting the response, and will
|
||||
`raise`.
|
||||
|
||||
#### `ServerSession`
|
||||
|
||||
A `ServerSession` is the type returned by `ext.create_server_session(offers)`. It
|
||||
must implement the following methods, as well as the `Session` API listed below.
|
||||
|
||||
```rb
|
||||
serverSession.generate_response
|
||||
# e.g. -> {'server_max_window_bits' => 8}
|
||||
```
|
||||
|
||||
This returns the set of parameters the server session wants to send in its
|
||||
`Sec-WebSocket-Extensions` response header. Only one set of parameters is
|
||||
returned to the client per extension. Server sessions that would confict on
|
||||
their use of RSV bits are not activated.
|
||||
|
||||
#### `Session`
|
||||
|
||||
The `Session` API must be implemented by both client and server sessions. It
|
||||
contains three methods: `valid_frame_rsv(frame)`,
|
||||
`process_incoming_message(message)` and `process_outgoing_message(message)`.
|
||||
|
||||
```rb
|
||||
session.valid_frame_rsv(frame)
|
||||
```
|
||||
|
||||
This takes a `Frame` as defined above, and returns a response indicating which
|
||||
RSV bits are allowed to be set on the frame. (If a session is having this method
|
||||
called, the session is active and should its bits can be used.) For example, the
|
||||
`permessage-deflate` extension allows the RSV1 bit to be set on `text` and
|
||||
`binary` frames, and implements this method like this:
|
||||
|
||||
```rb
|
||||
def valid_frame_rsv(frame)
|
||||
if [1, 2].include?(frame.opcode)
|
||||
{:rsv1 => true, :rsv2 => false, :rsv3 => false}
|
||||
else
|
||||
{:rsv1 => false, :rsv2 => false, :rsv3 => false}
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
Note that returning `false` for an `rsvX` field does not mean the session is
|
||||
forbidding its use; the framework assumes all RSV bits are banned unless a
|
||||
session indicates otherwise.
|
||||
|
||||
```rb
|
||||
message = session.process_incoming_message(message)
|
||||
```
|
||||
|
||||
The session must implement this method to take an incoming `Message` as defined
|
||||
above, transform it in any way it needs, then return it. If there is an error
|
||||
processing the message, this method should `raise` an error.
|
||||
|
||||
```rb
|
||||
message = session.process_outgoing_message(message)
|
||||
```
|
||||
|
||||
The session must implement this method to take an outgoing `Message` as defined
|
||||
above, transform it in any way it needs, then return it. If there is an error
|
||||
processing the message, this method should `raise` an error.
|
||||
|
||||
```rb
|
||||
session.close
|
||||
```
|
||||
|
||||
The framework will call this method when the WebSocket session ends, allowing
|
||||
the session to release any resources it's using.
|
||||
|
||||
## Examples
|
||||
|
||||
* Consumer: [websocket-driver](https://github.com/faye/websocket-driver-ruby)
|
||||
* Provider: [permessage-deflate](https://github.com/faye/permessage-deflate-ruby)
|
||||
|
||||
## License
|
||||
|
||||
(The MIT License)
|
||||
|
||||
Copyright (c) 2014 James Coglan
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy of
|
||||
this software and associated documentation files (the 'Software'), to deal in
|
||||
the Software without restriction, including without limitation the rights to
|
||||
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
|
||||
of the Software, and to permit persons to whom the Software is furnished to do
|
||||
so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
|
||||
Reference in New Issue
Block a user