Documentation added

pull/1/head
Daniel Abramov 8 years ago
parent e1f65c4a20
commit e279aafd54
  1. 54
      src/lib.rs

@ -1,3 +1,21 @@
//! Async WebSocket usage.
//!
//! This library is an implementation of WebSocket handshakes and streams. It
//! is based on the crate which implements all required WebSocket protocol
//! logic. So this crate basically just brings tokio support / tokio integration
//! to it.
//!
//! Each WebSocket stream implements the required `Stream` and `Sink` traits,
//! so the socket is just a stream of messages coming in and going out.
//!
//! This crate primarily exports this ability through two extension traits,
//! `ClientHandshakeExt` and `ServerHandshakeExt`. These traits augment the
//! functionality provided by the `tungestenite` crate, on which this crate is
//! built. Configuration is done through `tungestenite` crate as well.
#![deny(missing_docs)]
#[macro_use]
extern crate futures; extern crate futures;
extern crate tokio_core; extern crate tokio_core;
extern crate tungstenite; extern crate tungstenite;
@ -13,23 +31,59 @@ use tungstenite::handshake::{Handshake, HandshakeResult};
use tungstenite::protocol::{WebSocket, Message}; use tungstenite::protocol::{WebSocket, Message};
use tungstenite::error::Error as WsError; use tungstenite::error::Error as WsError;
/// A wrapper around an underlying raw stream which implements the WebSocket
/// protocol.
///
/// A `WebSocketStream<S>` represents a handshake that has been completed
/// successfully and both the server and the client are ready for receiving
/// and sending data. Message from a `WebSocketStream<S>` are accessible
/// through the respective `Stream` and `Sink`. Check more information about
/// them in `futures-rs` crate documentation or have a look on the examples
/// and unit tests for this crate.
pub struct WebSocketStream<S> { pub struct WebSocketStream<S> {
inner: WebSocket<S>, inner: WebSocket<S>,
} }
/// Future returned from `ClientHandshakeExt::new_async` which will resolve
/// once the connection handshake has finished.
pub struct ClientHandshakeAsync<S> { pub struct ClientHandshakeAsync<S> {
inner: Option<ClientHandshake<S>>, inner: Option<ClientHandshake<S>>,
} }
/// Future returned from `ServerHandshakeExt::new_async` which will resolve
/// once the connection handshake has finished.
pub struct ServerHandshakeAsync<S: Io> { pub struct ServerHandshakeAsync<S: Io> {
inner: Option<ServerHandshake<S>>, inner: Option<ServerHandshake<S>>,
} }
/// Extension trait for the `ClientHandshake` type in the `tungstenite` crate.
pub trait ClientHandshakeExt { pub trait ClientHandshakeExt {
/// Create a handshake provided stream and assuming the provided request.
///
/// This function will internally call `ClientHandshake::new` to create a
/// handshake representation and returns a future representing the
/// resolution of the WebSocket handshake. The returned future will resolve
/// to either `WebSocketStream<S>` or `Error` depending if it's successful
/// or not.
///
/// This is typically used for clients who have already established, for
/// example, a TCP connection to the remove server.
fn new_async<S: Io>(stream: S, request: Request) -> ClientHandshakeAsync<S>; fn new_async<S: Io>(stream: S, request: Request) -> ClientHandshakeAsync<S>;
} }
/// Extension trait for the `ServerHandshake` type in the `tungstenite` crate.
pub trait ServerHandshakeExt { pub trait ServerHandshakeExt {
/// Accepts a new WebSocket connection with the provided stream.
///
/// This function will internally call `ServerHandshake::new` to create a
/// handshake representation and returns a future representing the
/// resolution of the WebSocket handshake. The returned future will resolve
/// to either `WebSocketStream<S>` or `Error` depending if it's successful
/// or not.
///
/// This is typically used after a socket has been accepted from a
/// `TcpListener`. That socket is then passed to this function to perform
/// the server half of the accepting a client's websocket connection.
fn new_async<S: Io>(stream: S) -> ServerHandshakeAsync<S>; fn new_async<S: Io>(stream: S) -> ServerHandshakeAsync<S>;
} }

Loading…
Cancel
Save