Module websocket

Support for websockets.

Using websockets is done with the following steps:

• The websocket client (usually the browser through some Javascript) must send a request to the server to initiate the process. Examples for how to do this in Javascript are out of scope of this documentation but should be easy to find on the web.
• The server written with rouille must answer that request with the start() function defined in this module. This function returns an error if the request is not a websocket initialization request.
• The start() function also returns a Receiver<Websocket> object. Once that Receiver contains a value, the connection has been initiated.
• You can then use the Websocket object to communicate with the client through the Read and Write traits.

Subprotocols

The websocket connection will produce either text or binary messages. But these messages do not have a meaning per se, and must also be interpreted in some way. The way messages are interpreted during a websocket connection is called a subprotocol.

When you call start() you have to indicate which subprotocol the connection is going to use. This subprotocol must match one of the subprotocols that were passed by the client during its request, otherwise start() will return an error. It is also possible to pass None, in which case the subprotocol is unknown to both the client and the server.

There are usually three ways to handle subprotocols on the server-side:

• You don’t really care about subprotocols because you use websockets for your own needs. You can just pass None to start(). The connection will thus never fail unless the client decides to.
• Your route only handles one subprotocol. Just pass this subprotocol to start() and you will get an error (which you can handle for example with try_or_400!) if it’s not supported by the client.
• Your route supports multiple subprotocols. This is the most complex situation as you will have to enumerate the protocols with requested_protocols() and choose one.

Example

use std::sync::Mutex;
use std::sync::mpsc::Receiver;

use rouille::Request;
use rouille::Response;
use rouille::websocket;

fn handle_request(request: &Request, websockets: &Mutex<Vec<Receiver<websocket::Websocket>>>)
                  -> Response
{
    let (response, websocket) = try_or_400!(websocket::start(request, Some("my-subprotocol")));
    websockets.lock().unwrap().push(websocket);
    response
}

Structs

• RequestedProtocolsIter
  Iterator to the list of protocols requested by the user.
• Websocket
  A successful websocket. An open channel of communication. Implements Read and Write.

Enums

• Message
  A message produced by a websocket connection.
• SendError
  Error that can happen when sending a message to the client.
• WebsocketError
  Error that can happen when attempting to start websocket.

Functions

• requested_protocols
  Returns a list of the websocket protocols requested by the client.
• start
  Builds a Response that initiates the websocket protocol.