feat: Support permessage-deflate extension

Author: housleyjk

Cargo.toml

@@ -7,26 +7,26 @@ license = "MIT"
 name = "ws"
 readme = "README.md"
 repository = "https://github.com/housleyjk/ws-rs"
-version = "0.4.8"
+version = "0.5.0"
 
 [dependencies]
-httparse = "1.1.2"
-log = "0.3.6"
-mio = "0.5.1"
-rand = "0.3.14"
-sha1 = "0.1.1"
-url = "1.1.1"
-
-[dependencies.openssl]
-optional = true
-version = "0.7.13"
+httparse = "*"
+log = "*"
+mio = "*"
+rand = "*"
+sha1 = "*"
+url = "*"
+openssl = { version = "*", optional = true }
+libz-sys = { version = "*", optional = true }
+libc = { version = "*", optional = true }
 
 [dev-dependencies]
-clap = "2.5.1"
-env_logger = "0.3.3"
-term = "0.4.4"
-time = "0.1.35"
+clap = "*"
+env_logger = "*"
+term = "*"
+time = "*"
 
 [features]
 default = []
+permessage-deflate = ["libz-sys", "libc"]
 ssl = ["openssl"]

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2015 Jason Housley
+Copyright (c) 2016 Jason Housley
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -17,116 +17,39 @@ Introduction
 [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![Crate](http://meritbadge.herokuapp.com/ws)](https://crates.io/crates/ws)
 
-This library provides an implementation of WebSockets, [RFC6455](https://tools.ietf.org/html/rfc6455) using [MIO](https://github.com/carllerche/mio).
-It allows for handling multiple connections on a single thread, and even spawning new client connections on the same thread. This makes for very fast
-and resource efficient WebSockets. The API design abstracts away the menial parts of the WebSocket protocol, masking and unmasking frames,
-which allows you to focus on application code and rely on WS-RS to handle protocol conformance. However, it is also possible to get low-level
-access to individual WebSocket frames if you need to write extensions or want to optimize around the WebSocket protocol.
+**[Homepage](https://ws-rs.org)**
 
-**[API documentation](http://housleyjk.github.io/ws-rs/ws)**
+**[API Documentation](https://ws-rs.org/docs)**
 
+This library provides an implementation of WebSockets,
+[RFC6455](https://tools.ietf.org/html/rfc6455) using [MIO](https://github.com/carllerche/mio). It
+allows for handling multiple connections on a single thread, and even spawning new client
+connections on the same thread. This makes for very fast and resource efficient WebSockets. The API
+design abstracts away the menial parts of the WebSocket protocol and allows you to focus on
+application code without worrying about protocol conformance. However, it is also possible to get
+low-level access to individual WebSocket frames if you need to write extensions or want to optimize
+around the WebSocket protocol.
 
-Examples
---------
-* [Server](https://github.com/housleyjk/ws-rs/tree/stable/examples/server.rs).
-A simple WebSocket echo server using closures.
-* [Client](https://github.com/housleyjk/ws-rs/tree/stable/examples/client.rs)
-A simple WebSocket client for connecting to an echo server using closures.
-* [Single Threaded](https://github.com/housleyjk/ws-rs/tree/stable/examples/shared.rs)
-An example of an echo client and an echo server on one thread using closures.
-* [Threads](https://github.com/housleyjk/ws-rs/tree/stable/examples/threaded.rs)
-An example of an echo client and an echo server on separate threads. This demonstrates using a struct as a WebSocket handler.
-* [Channels](https://github.com/housleyjk/ws-rs/tree/stable/examples/channel.rs)
-A more complex example using channels to communicate with a WebSocket handler to accomplish a separate task.
-* [Pong](https://github.com/housleyjk/ws-rs/tree/stable/examples/pong.rs)
-An example demonstrating how to send and recieve a custom ping/pong frame.
-
-Stability and Testing
----------------------
-
-WS-RS passes both the client and server sides of the [Autobahn Testsuite](http://autobahn.ws/testsuite/).
-To run the tests yourself, install the [Autobahn Testsuite](http://autobahn.ws/testsuite/).
-For example:
-
-```
-mkvirtualenv wstest --python=/usr/bin/python2
-pip install autobahntestsuite
-```
+Getting Started
+---------------
 
-To run the client tests, start the test server in one window:
-```
-cd tests
-wstest -m fuzzingserver
-```
-And run the WS-RS client in the other:
-```
-cargo run --example autobahn-client
-```
-
-To run the server tests, start the WS-RS server in one window:
-```
-cargo run --example autobahn-server
-```
-And run the test client in the other:
-```
-cd tests
-wstest -m fuzzingclient
-```
+For detailed installation and usage instructions, check out the [guide](https://ws-rs.org/guide).
 
-SSL
----
-WS-RS supports WebSocket connections using SSL (e.g. `wss://mysecure/websocket`). To enable the ssl feature, require WS-RS in your `Cargo.toml`
-file as so:
+Features
+--------
 
-``` TOML
-[dependencies.ws]
-version = "*"
-features = ["ssl"]
-```
+WS-RS provides a complete implementation of the WebSocket specification. There is also support for
+[ssl](https://ws-rs.org/guide/ssl) and
+[permessage-deflate](https://ws-rs.org/guide/permessage-deflate).
 
-Then simply specify the `wss` scheme to use an encypted connection.
+Testing
+-------
 
-```rust
-/// An encypted Websocket echo client
-connect("wss://localhost:3012", |ws| {
-    move |msg| {
-        ws.send(msg)
-    }
-})
-```
+WS-RS is thoroughly tested and passes the [Autobahn Test Suite](http://autobahn.ws/testsuite/) for 
+WebSockets, including the tests for `permessage-deflate`. Visit 
+[ws-rs.org](https://ws-rs.org/testing/results) to view the results of the latest test run.
 
 Contributing
 ------------
 
-Please report bugs and make feature requests [here](https://github.com/housleyjk/ws-rs/issues). I welcome pull requests.
-Unit tests for bugs are greatly appreciated.
-
-Comparison with other WebSocket libraries
------------------------------------------
-
-You don't need to use this library to the exclusion of other WebSocket libraries, in Rust or other languages,
-but if you find yourself considering which library to use, here is my opinion: choose the one that has the API
-you like the most. The API is generally more important than performance. The library API is what you will have to deal with as
-you build your WebSocket application. I've written WS-RS to have an API that fits my needs. If you don't like it,
-please make a [feature request](https://github.com/housleyjk/ws-rs/issues) to improve it or use another library
-that causes you less problems.
-
-However, if performance is what you value most and you want a WebSocket library in Rust, I would choose this one.
-Here is how it stacks up against some other common frameworks using the example [benchmark tool](https://github.com/housleyjk/ws-rs/tree/stable/examples/bench.rs)
-to open 10,000 simultaneous connections and send 10 messages. These results are **not** reliable as a serious benchmark:
-
-Library | Time (ms)
---------| ---------
-<a href="https://github.com/housleyjk/ws-rs">WS-RS</a> | 1,709
-<a href="https://libwebsockets.org/trac/libwebsockets">libwebsockets</a> | 2,067
-<a href="https://github.com/cyderize/rust-websocket">rust-websocket</a> | 8,950
-<a href="http://aaugustin.github.io/websockets/">\* websockets CPython 3.4.3</a> | 12,638
-<a href="http://autobahn.ws/python/">Autobahn CPython 2.7.10</a> | 48,902
-<a href="https://github.com/websockets/ws">\*\* NodeJS via ws</a> | 127,635
-
-\* websockets encountered a few (3) broken pipe errors<br>
-\*\* NodeJS encountered several (229) connection timeout errors
-
-Your results will vary. The system specs for this test were as follows:
-
-Intel(R) Core(TM) i3 CPU 560 @ 3.33GHz, 8GB RAM
+Please report bugs and make feature requests [here](https://github.com/housleyjk/ws-rs/issues).

examples/autobahn-client.rs

@@ -6,8 +6,12 @@ use std::rc::Rc;
 use std::cell::Cell;
 use ws::{connect, CloseCode, Message, Result};
 
+#[cfg(feature="permessage-deflate")]
+use ws::deflate::DeflateHandler;
+
 const AGENT: &'static str = "WS-RS";
 
+#[cfg(not(feature="permessage-deflate"))]
 fn main () {
 
     let total = get_case_count().unwrap();
@@ -30,6 +34,29 @@ fn main () {
     update_reports().unwrap();
 }
 
+#[cfg(feature="permessage-deflate")]
+fn main () {
+
+    let total = get_case_count().unwrap();
+    let mut case_id = 1;
+
+
+    while case_id <= total {
+
+        let case_url = format!("ws://127.0.0.1:9001/runCase?case={}&agent={}", case_id, AGENT);
+
+        connect(case_url, |out| {
+            DeflateHandler::new(move |msg| {
+                out.send(msg)
+            })
+        }).unwrap();
+
+        case_id += 1
+    }
+
+    update_reports().unwrap();
+}
+
 fn get_case_count() -> Result<u32> {
 
     // sadly we need to use a Cell because we need to set the total, and RC is immutable

examples/autobahn-server.rs

@@ -2,11 +2,29 @@
 /// example without printing output or comments.
 
 extern crate ws;
+extern crate env_logger;
 
+#[cfg(feature="permessage-deflate")]
+use ws::deflate::DeflateHandler;
+
+#[cfg(not(feature="permessage-deflate"))]
 fn main () {
+    env_logger::init().unwrap();
+
     ws::listen("127.0.0.1:3012", |out| {
         move |msg| {
             out.send(msg)
         }
     }).unwrap()
 }
+
+#[cfg(feature="permessage-deflate")]
+fn main () {
+    env_logger::init().unwrap();
+
+    ws::listen("127.0.0.1:3012", |out| {
+        DeflateHandler::new(move |msg| {
+            out.send(msg)
+        })
+    }).unwrap();
+}

src/communication.rs

@@ -79,13 +79,11 @@ impl Sender {
 
     /// Send a message to the endpoints of all connections.
     ///
-    /// Be careful with this method because it
-    /// does not discriminate between client and server connections, only connections that are not
-    /// part of *this* side of the WebSocket. If your WebSocket is only functioning as a server,
-    /// then usage is simple, however if you have a WebSocket that is listening for
-    /// connections and is also connected to another WebSocket, this method will broadcast a
-    /// message to all the clients connected and to the server at the other end of the single
-    /// client connection.
+    /// Be careful with this method. It does not discriminate between client and server connections.
+    /// If your WebSocket is only functioning as a server, then usage is simple, this method will
+    /// send a copy of the message to each connected client. However, if you have a WebSocket that
+    /// is listening for connections and is also connected to another WebSocket, this method will
+    /// broadcast a copy of the message to all the clients connected and to that WebSocket server.
     #[inline]
     pub fn broadcast<M>(&self, msg: M) -> Result<()>
         where M: Into<message::Message>