diff --git a/CHANGELOG.md b/CHANGELOG.md index dd5f35d..5bb391b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,127 +1,128 @@ ### 0.7.0 / 2017-09-11 -* Add `ping` and `pong` to the set of events users can listen to +- Add `ping` and `pong` to the set of events users can listen to ### 0.6.5 / 2017-01-22 -* Provide a pure-Ruby fallback for the native unmasking code +- Provide a pure-Ruby fallback for the native unmasking code ### 0.6.4 / 2016-05-20 -* Amend warnings issued when running with -W2 -* Make sure message strings passed in by the app are transcoded to UTF-8 -* Copy strings if necessary for frozen-string compatibility +- Amend warnings issued when running with -W2 +- Make sure message strings passed in by the app are transcoded to UTF-8 +- Copy strings if necessary for frozen-string compatibility ### 0.6.3 / 2015-11-06 -* Reject draft-76 handshakes if their Sec-WebSocket-Key headers are invalid -* Throw a more helpful error if a client is created with an invalid URL +- Reject draft-76 handshakes if their Sec-WebSocket-Key headers are invalid +- Throw a more helpful error if a client is created with an invalid URL ### 0.6.2 / 2015-07-18 -* When the peer sends a close frame with no error code, emit 1000 +- When the peer sends a close frame with no error code, emit 1000 ### 0.6.1 / 2015-07-13 -* Fix how events are stored in `EventEmitter` to fix a backward-compatibility +- Fix how events are stored in `EventEmitter` to fix a backward-compatibility violation introduced in the last release -* Use the `Array#pack` and `String#unpack` methods for reading/writing numbers +- Use the `Array#pack` and `String#unpack` methods for reading/writing numbers to buffers rather than including duplicate logic for this ### 0.6.0 / 2015-07-08 -* Use `SecureRandom` to generate the `Sec-WebSocket-Key` header -* Allow the parser to recover cleanly if event listeners raise an error -* Let the `on()` method take a lambda as a positional argument rather than a block -* Add a `pong` method for sending unsolicited pong frames +- Use `SecureRandom` to generate the `Sec-WebSocket-Key` header +- Allow the parser to recover cleanly if event listeners raise an error +- Let the `on()` method take a lambda as a positional argument rather than a + block +- Add a `pong` method for sending unsolicited pong frames ### 0.5.4 / 2015-03-29 -* Don't emit extra close frames if we receive a close frame after we already +- Don't emit extra close frames if we receive a close frame after we already sent one -* Fail the connection when the driver receives an invalid +- Fail the connection when the driver receives an invalid `Sec-WebSocket-Extensions` header ### 0.5.3 / 2015-02-22 -* Don't treat incoming data as WebSocket frames if a client driver is closed +- Don't treat incoming data as WebSocket frames if a client driver is closed before receiving the server handshake ### 0.5.2 / 2015-02-19 -* Don't emit multiple `error` events +- Don't emit multiple `error` events ### 0.5.1 / 2014-12-18 -* Don't allow drivers to be created with unrecognized options +- Don't allow drivers to be created with unrecognized options ### 0.5.0 / 2014-12-13 -* Support protocol extensions via the websocket-extensions module +- Support protocol extensions via the websocket-extensions module ### 0.4.0 / 2014-11-08 -* Support connection via HTTP proxies using `CONNECT` +- Support connection via HTTP proxies using `CONNECT` ### 0.3.5 / 2014-10-04 -* Fix bug where the `Server` driver doesn't pass `ping` callbacks to its +- Fix bug where the `Server` driver doesn't pass `ping` callbacks to its delegate -* Fix an arity error when calling `fail_request` -* Allow `close` to be called before `start` to close the driver +- Fix an arity error when calling `fail_request` +- Allow `close` to be called before `start` to close the driver ### 0.3.4 / 2014-07-06 -* Don't hold references to frame buffers after a message has been emitted -* Make sure that `protocol` and `version` are exposed properly by the TCP driver -* Correct HTTP header parsing based on RFC 7230; header names cannot contain +- Don't hold references to frame buffers after a message has been emitted +- Make sure that `protocol` and `version` are exposed properly by the TCP driver +- Correct HTTP header parsing based on RFC 7230; header names cannot contain backslashes ### 0.3.3 / 2014-04-24 -* Fix problems with loading C and Java native extension code -* Correct the acceptable characters used in the HTTP parser -* Correct the draft-76 status line reason phrase +- Fix problems with loading C and Java native extension code +- Correct the acceptable characters used in the HTTP parser +- Correct the draft-76 status line reason phrase ### 0.3.2 / 2013-12-29 -* Expand `max_length` to cover sequences of continuation frames and +- Expand `max_length` to cover sequences of continuation frames and `draft-{75,76}` -* Decrease default maximum frame buffer size to 64MB -* Stop parsing when the protocol enters a failure mode, to save CPU cycles +- Decrease default maximum frame buffer size to 64MB +- Stop parsing when the protocol enters a failure mode, to save CPU cycles ### 0.3.1 / 2013-12-03 -* Add a `max_length` option to limit allowed frame size +- Add a `max_length` option to limit allowed frame size ### 0.3.0 / 2013-09-09 -* Support client URLs with Basic Auth credentials +- Support client URLs with Basic Auth credentials ### 0.2.3 / 2013-08-04 -* Fix bug in EventEmitter#emit when listeners are removed +- Fix bug in EventEmitter#emit when listeners are removed ### 0.2.2 / 2013-08-04 -* Fix bug in EventEmitter#listener_count for unregistered events +- Fix bug in EventEmitter#listener_count for unregistered events ### 0.2.1 / 2013-07-05 -* Queue sent messages if the client has not begun trying to connect -* Encode all strings sent to I/O as `ASCII-8BIT` +- Queue sent messages if the client has not begun trying to connect +- Encode all strings sent to I/O as `ASCII-8BIT` ### 0.2.0 / 2013-05-12 -* Add API for setting and reading headers -* Add Driver.server() method for getting a driver for TCP servers +- Add API for setting and reading headers +- Add Driver.server() method for getting a driver for TCP servers ### 0.1.0 / 2013-05-04 -* First stable release +- First stable release ### 0.0.0 / 2013-04-22 -* First release -* Proof of concept for people to try out -* Might be unstable +- First release +- Proof of concept for people to try out +- Might be unstable diff --git a/README.md b/README.md index 68ec61c..43c7926 100644 --- a/README.md +++ b/README.md @@ -10,21 +10,21 @@ pluggable I/O. Due to this design, you get a lot of things for free. In particular, if you hook this module up to some I/O object, it will do all of this for you: -* Select the correct server-side driver to talk to the client -* Generate and send both server- and client-side handshakes -* Recognize when the handshake phase completes and the WS protocol begins -* Negotiate subprotocol selection based on `Sec-WebSocket-Protocol` -* Negotiate and use extensions via the +- Select the correct server-side driver to talk to the client +- Generate and send both server- and client-side handshakes +- Recognize when the handshake phase completes and the WS protocol begins +- Negotiate subprotocol selection based on `Sec-WebSocket-Protocol` +- Negotiate and use extensions via the [websocket-extensions](https://github.com/faye/websocket-extensions-ruby) module -* Buffer sent messages until the handshake process is finished -* Deal with proxies that defer delivery of the draft-76 handshake body -* Notify you when the socket is open and closed and when messages arrive -* Recombine fragmented messages -* Dispatch text, binary, ping, pong and close frames -* Manage the socket-closing handshake process -* Automatically reply to ping frames with a matching pong -* Apply masking to messages sent by the client +- Buffer sent messages until the handshake process is finished +- Deal with proxies that defer delivery of the draft-76 handshake body +- Notify you when the socket is open and closed and when messages arrive +- Recombine fragmented messages +- Dispatch text, binary, ping, pong and close frames +- Manage the socket-closing handshake process +- Automatically reply to ping frames with a matching pong +- Apply masking to messages sent by the client This library was originally extracted from the [Faye](http://faye.jcoglan.com) project but now aims to provide simple WebSocket support for any Ruby server or @@ -43,12 +43,12 @@ $ gem install websocket-driver To build either a server-side or client-side socket, the only requirement is that you supply a `socket` object with these methods: -* `socket.url` - returns the full URL of the socket as a string. -* `socket.write(string)` - writes the given string to a TCP stream. +- `socket.url` - returns the full URL of the socket as a string. +- `socket.write(string)` - writes the given string to a TCP stream. Server-side sockets require one additional method: -* `socket.env` - returns a Rack-style env hash that will contain some of the +- `socket.env` - returns a Rack-style env hash that will contain some of the following fields. Their values are strings containing the value of the named header, unless stated otherwise. * `HTTP_CONNECTION` @@ -193,8 +193,8 @@ and send outgoing data. Client drivers have two additional methods for reading the HTTP data that was sent back by the server: -* `driver.status` - the integer value of the HTTP status code -* `driver.headers` - a hash-like object containing the response headers +- `driver.status` - the integer value of the HTTP status code +- `driver.headers` - a hash-like object containing the response headers ### HTTP Proxies @@ -261,9 +261,9 @@ frames. The `options` argument is optional, and is a hash. It may contain the following keys: -* `:max_length` - the maximum allowed size of incoming message frames, in bytes. +- `:max_length` - the maximum allowed size of incoming message frames, in bytes. The default value is `2^26 - 1`, or 1 byte short of 64 MiB. -* `:protocols` - an array of strings representing acceptable subprotocols for +- `:protocols` - an array of strings representing acceptable subprotocols for use over the socket. The driver will negotiate one of these to use via the `Sec-WebSocket-Protocol` header if supported by the other peer.