Add more examples, make Request Protocols a Vec

Tests all pass as well

Author: cyderize

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 
 name = "websocket"
-version = "0.4.1"
+version = "0.5.0"
 authors = ["cyderize <[email protected]>"]
 
 description = "A WebSocket (RFC6455) library for Rust."

README.md

@@ -10,7 +10,7 @@ Rust-WebSocket attempts to provide a framework for WebSocket connections (both c
 To add a library release version from [crates.io](https://crates.io/crates/websocket) to a Cargo project, add this to the 'dependencies' section of your Cargo.toml:
 
 ```INI
-websocket = "~0.4.0"
+websocket = "~0.5.0"
 ```
 
 To add the library's Git repository to a Cargo project, add this to your Cargo.toml:

src/lib.rs

@@ -35,8 +35,10 @@
 //! 				let key = request.key().unwrap();
 //! 				
 //! 				// Form a response from the key
-//!					// In this example, we don't deal with the requested protocol
-//! 				let response = WebSocketResponse::new(key.as_slice(), None);
+//!					/* In this example, we don't deal with the requested protocol
+//!					   Because of this, however, we need to a type annotation,
+//!					   which would usually not be required. */
+//! 				let response = WebSocketResponse::new::<String>(key.as_slice(), None);
 //! 				
 //! 				// Send the response to the client
 //! 				let _ = client.send_handshake_response(response);
@@ -60,7 +62,8 @@ extern crate serialize;
 
 pub use self::ws::client::WebSocketClient;
 
-/// Structs for manipulation of HTTP headers
+/// Structs for manipulation of HTTP headers. Used in conjunction with 
+/// WebSocketRequest and WebSocketResponse.
 pub mod headers {
 	pub use util::header::{HeaderCollection, Headers};
 	pub use url::ParseResult;

src/ws/client.rs

@@ -11,14 +11,12 @@ use std::clone::Clone;
 /// To use WebSocketClient, you must create one using either WebSocketClient::connect(),
 /// which is used for writing clients, or WebSocketClient::from_stream(), which creates
 /// a WebSocketClient from a TcpStream (typically used in a server).
-///
-/// An example client application:
 /// 
 /// ```no_run
 /// use websocket::WebSocketClient;
 /// use websocket::handshake::WebSocketRequest;
 /// 
-/// let request = WebSocketRequest::new("ws://127.0.0.1:1234", "myProtocol").unwrap();
+/// let request = WebSocketRequest::new("ws://127.0.0.1:1234", ["myProtocol"].as_slice()).unwrap();
 /// let key = request.key().unwrap();
 /// let mut client = WebSocketClient::connect(&request).unwrap();
 /// let response = client.receive_handshake_response().unwrap();
@@ -39,8 +37,8 @@ pub struct WebSocketClient {
 }
 
 impl WebSocketClient {
-	/// Connect to the WebSocket server using the given request. Use WebSocketRequest::new() to create a request for use
-	/// with this function.
+	/// Connect to the WebSocket server using the given request.
+	/// Use WebSocketRequest::new() to create a request for use with this function.
 	pub fn connect(request: &WebSocketRequest) -> IoResult<WebSocketClient> {
 		let host = try!(request.headers.get("Host").ok_or(
 			IoError {
@@ -64,6 +62,8 @@ impl WebSocketClient {
 	/// The mask parameter determines whether or not messages send to the remote endpoint will be masked.
 	/// If the client is connecting to a remote endpoint, set mask to true. If the client is the remote
 	/// endpoint (and therefore, the server is the local endpoint), set mask to false.
+	/// 
+	/// Nothing is sent to or read from the stream during the conversion.
 	pub fn from_stream(stream: TcpStream, mask: bool) -> WebSocketClient {
 		WebSocketClient {
 			stream: stream,
@@ -72,6 +72,7 @@ impl WebSocketClient {
 	}
 
 	/// Returns a copy of the underlying TcpStream for this WebSocketClient.
+	/// Note that writing to this stream will likely invalidate the WebSocket data stream.
 	pub fn stream(&self) -> TcpStream {
 		self.stream.clone()
 	}

src/ws/handshake/request.rs

@@ -6,13 +6,26 @@ extern crate url;
 use super::util::{ReadUntilStr, HeaderCollection, ReadHttpHeaders, WriteHttpHeaders};
 use super::version::HttpVersion;
 use url::{Url, ParseResult, ParseError};
+use std::fmt::Show;
 use std::rand;
 use std::io::{Reader, Writer, IoResult, IoError, IoErrorKind};
 use serialize::base64::{ToBase64, STANDARD};
 use std::clone::Clone;
 
 /// Represents a WebSocket handshake request, which is sent from the client to the server.
 /// Use the new() function to create a new request, and send it with the WebSocketClient::connect() function.
+/// Use the WebSocketClient.receive_handshake_request() method to read a WebSocketRequest from a remote client.
+/// 
+/// ```
+/// use websocket::handshake::WebSocketRequest;
+///
+/// let protocols = vec!["FirstPreference", "SecondPreference", "ThirdPreference"];
+/// let request = WebSocketRequest::new("ws://www.example.com:1234", protocols.as_slice()).unwrap();
+/// 
+/// assert_eq!(request.host().unwrap().as_slice(), "www.example.com:1234");
+/// assert_eq!(request.version().unwrap().as_slice(), "13");
+/// //...
+/// ```
 pub struct WebSocketRequest {
 	/// The resource name of the request. E.g. /path/to/resource for the URI ws://www.example.com/path/to/resource
 	pub resource_name: String,
@@ -26,7 +39,8 @@ pub struct WebSocketRequest {
 
 impl WebSocketRequest {
 	/// Creates a new WebSocket handshake request for use with WebSocketClient::connect().
-	pub fn new(uri: &str, protocol: &str) -> ParseResult<WebSocketRequest> {
+	/// The URI should use the ws:// scheme (wss:// not supported at this time).
+	pub fn new<A: Show>(uri: &str, protocols: &[A]) -> ParseResult<WebSocketRequest> {
 		let ws_uri = match Url::parse(uri) {
 			Ok(uri) => { uri }
 			Err(e) => { return Err(e); }
@@ -71,7 +85,10 @@ impl WebSocketRequest {
 
 		headers.insert("Sec-WebSocket-Key", key);
 		headers.insert("Sec-WebSocket-Version", "13");
-		headers.insert("Sec-WebSocket-Protocol", protocol);
+		
+		for protocol in protocols.iter() {
+			headers.insert("Sec-WebSocket-Protocol", protocol);
+		}
 
 		Ok(WebSocketRequest {
 			resource_name: resource_name,

src/ws/handshake/response.rs

@@ -6,13 +6,25 @@ use super::util::{str_eq_ignore_case, ReadUntilStr, HeaderCollection, ReadHttpHe
 use super::version::HttpVersion;
 use sha1::Sha1;
 use serialize::base64::{ToBase64, STANDARD};
+use std::fmt::Show;
 use std::io::{Reader, Writer, IoResult, IoError, IoErrorKind};
 use std::string::ToString;
 use std::clone::Clone;
 
 static MAGIC_GUID: &'static str = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
 
-/// Represents a WebSocket response from a server
+/// Represents a WebSocket response which is sent from the server to the client.
+/// Use the new() function to create a new response, and send it with the WebSocketClient::send_handshake_response() function.
+/// 
+/// ```
+/// use websocket::handshake::WebSocketResponse;
+///
+/// let response = WebSocketResponse::new("dGhlIHNhbXBsZSBub25jZQ==", Some("myProtocol"));
+/// 
+/// assert_eq!(response.accept().unwrap().as_slice(), "s3pPLMBiTxaQ9kYGzzhZRbK+xOo=");
+/// assert_eq!(response.upgrade().unwrap().as_slice(), "websocket");
+/// //...
+/// ```
 pub struct WebSocketResponse {
 	/// The HTTP version of this request
 	pub http_version: HttpVersion,
@@ -26,7 +38,7 @@ pub struct WebSocketResponse {
 
 impl WebSocketResponse {
 	/// Create a new WebSocket response based on the base-64 encoded key from a client.
-	pub fn new(key: &str, protocol: Option<String>) -> WebSocketResponse {
+	pub fn new<A: Show>(key: &str, protocol: Option<A>) -> WebSocketResponse {
 		let accept = WebSocketResponse::gen_accept(key.to_string());
 
 		let status_code = 101;
@@ -71,8 +83,20 @@ impl WebSocketResponse {
 	}
 
 	/// Short-cut to get the Sec-WebSocket-Version field value of this request
-	pub fn version(&self) -> Option<String> {
-		self.headers.get("Sec-WebSocket-Version")
+	/// This may be present when the handshake fails (it should not appear on a successful
+	/// handshake response.
+	pub fn version(&self) -> Option<Vec<String>> {
+		match self.headers.get("Sec-WebSocket-Version") {
+			Some(version) => {
+				let mut result: Vec<String> = Vec::new();
+				let mut values = version.as_slice().split_str(",");
+				for value in values {
+					result.push(value.trim().to_string());
+				}
+				Some(result)
+			}
+			None => { None }
+		}
 	}
 
 	/// Short-cut to get the Sec-WebSocket-Extensions field value of this request
@@ -107,10 +131,6 @@ impl WebSocketResponse {
 	/// the given key.
 	pub fn is_successful<A: ToString>(&self, key: A) -> bool {
 		self.status_code == 101 && 
-		match self.version() {
-			Some(version) => { version.as_slice() == "13" }
-			None => { false }
-		} && 
 		match self.upgrade() {
 			Some(upgrade) => { str_eq_ignore_case(upgrade.as_slice(), "websocket") }
 			None => { false }

src/ws/message/receive.rs

@@ -17,7 +17,7 @@ use std::str::from_utf8;
 /// # use websocket::handshake::WebSocketRequest;
 /// # #[allow(unused_must_use)]
 /// # fn foo() {
-/// # let request = WebSocketRequest::new("ws://127.0.0.1:1234", "None").unwrap();
+/// # let request = WebSocketRequest::new("ws://127.0.0.1:1234", ["None"].as_slice()).unwrap();
 /// # let mut client = WebSocketClient::connect(&request).unwrap();
 /// 
 /// let receiver = client.receiver();

src/ws/message/send.rs

@@ -17,7 +17,7 @@ use std::rand;
 /// # use websocket::handshake::WebSocketRequest;
 /// # #[allow(unused_must_use)]
 /// # fn foo() {
-/// # let request = WebSocketRequest::new("ws://127.0.0.1:1234", "None").unwrap();
+/// # let request = WebSocketRequest::new("ws://127.0.0.1:1234", ["None"].as_slice()).unwrap();
 /// # let mut client = WebSocketClient::connect(&request).unwrap();
 /// 
 /// let mut sender = client.sender(); // Get a sender
@@ -104,7 +104,7 @@ impl WebSocketSender {
 /// # use websocket::handshake::WebSocketRequest;
 /// # #[allow(unused_must_use)]
 /// # fn foo() {
-/// # let request = WebSocketRequest::new("ws://127.0.0.1:1234", "None").unwrap();
+/// # let request = WebSocketRequest::new("ws://127.0.0.1:1234", ["None"].as_slice()).unwrap();
 /// # let mut client = WebSocketClient::connect(&request).unwrap();
 /// # let mut sender = client.sender();
 /// // Get a WebSocketFragmentSerializer