[][src]Struct websocket::client::builder::ClientBuilder

pub struct ClientBuilder<'u> { /* fields omitted */ }

Build clients with a builder-style API This makes it easy to create and configure a websocket connection:

The easiest way to connect is like this:

use websocket::ClientBuilder;

let client = ClientBuilder::new("ws://myapp.com")
    .unwrap()
    .connect_insecure()
    .unwrap();

But there are so many more possibilities:

use websocket::ClientBuilder;
use websocket::header::{Headers, Cookie};

let default_protos = vec!["ping", "chat"];
let mut my_headers = Headers::new();
my_headers.set(Cookie(vec!["userid=1".to_owned()]));

let mut builder = ClientBuilder::new("ws://myapp.com/room/discussion")
    .unwrap()
    .add_protocols(default_protos) // any IntoIterator
    .add_protocol("video-chat")
    .custom_headers(&my_headers);

// connect to a chat server with a user
let client = builder.connect_insecure().unwrap();

// clone the builder and take it with you
let not_logged_in = builder
    .clone()
    .clear_header::<Cookie>()
    .connect_insecure().unwrap();

You may have noticed we're not using SSL, have no fear, SSL is included! This crate's openssl dependency is optional (and included by default). One can use connect_secure to connect to an SSL service, or simply connect to choose either SSL or not based on the protocol (ws:// or wss://).

Methods

impl<'u> ClientBuilder<'u>
[src]

Create a client builder from an already parsed Url, because there is no need to parse this will never error.

use websocket::url::Url;

// the parsing error will be handled outside the constructor
let url = Url::parse("ws://bitcoins.pizza").unwrap();

let builder = ClientBuilder::from_url(&url);

The path of a URL is optional if no port is given then port 80 will be used in the case of ws:// and port 443 will be used in the case of wss://.

Create a client builder from a URL string, this will attempt to parse the URL immediately and return a ParseError if the URL is invalid. URLs must be of the form: [ws or wss]://[domain]:[port]/[path] The path of a URL is optional if no port is given then port 80 will be used in the case of ws:// and port 443 will be used in the case of wss://.

let builder = ClientBuilder::new("wss://mycluster.club");

Adds a user-defined protocol to the handshake, the server will be given a list of these protocols and will send back the ones it accepts.

let builder = ClientBuilder::new("wss://my-twitch-clone.rs").unwrap()
    .add_protocol("my-chat-proto");

let protos = &builder.get_header::<WebSocketProtocol>().unwrap().0;
assert!(protos.contains(&"my-chat-proto".to_string()));

Adds a user-defined protocols to the handshake. This can take many kinds of iterators.

let builder = ClientBuilder::new("wss://my-twitch-clone.rs").unwrap()
    .add_protocols(vec!["pubsub", "sub.events"]);

let protos = &builder.get_header::<WebSocketProtocol>().unwrap().0;
assert!(protos.contains(&"pubsub".to_string()));
assert!(protos.contains(&"sub.events".to_string()));

Removes all the currently set protocols.

Adds an extension to the connection. Unlike protocols, extensions can be below the application level (like compression). Currently no extensions are supported out-of-the-box but one can still use them by using their own implementation. Support is coming soon though.

let builder = ClientBuilder::new("wss://skype-for-linux-lol.com").unwrap()
    .add_extension(Extension {
        name: "permessage-deflate".to_string(),
        params: vec![],
    });

let exts = &builder.get_header::<WebSocketExtensions>().unwrap().0;
assert!(exts.first().unwrap().name == "permessage-deflate");

Adds some extensions to the connection. Currently no extensions are supported out-of-the-box but one can still use them by using their own implementation. Support is coming soon though.

let builder = ClientBuilder::new("wss://moxie-chat.org").unwrap()
    .add_extensions(vec![
        Extension {
            name: "permessage-deflate".to_string(),
            params: vec![],
        },
        Extension {
            name: "crypt-omemo".to_string(),
            params: vec![],
        },
    ]);

Remove all the extensions added to the builder.

Add a custom Sec-WebSocket-Key header. Use this only if you know what you're doing, and this almost never has to be used.

Remove the currently set Sec-WebSocket-Key header if any.

Set the version of the Websocket connection. Currently this library only supports version 13 (from RFC6455), but one could use this library to create the handshake then use an implementation of another websocket version.

Unset the websocket version to be the default (WebSocket 13).

Sets the Origin header of the handshake. Normally in browsers this is used to protect against unauthorized cross-origin use of a WebSocket server, but it is rarely send by non-browser clients. Still, it can be useful.

Remove the Origin header from the handshake.

This is a catch all to add random headers to your handshake, the process here is more manual.

let mut headers = Headers::new();
headers.set(Authorization("let me in".to_owned()));

let builder = ClientBuilder::new("ws://moz.illest").unwrap()
    .custom_headers(&headers);

Remove a type of header from the handshake, this is to be used with the catch all custom_headers.

Get a header to inspect it.

Connect to a server (finally)! This will use a Box<NetworkStream> to represent either an SSL connection or a normal TCP connection, what to use will be decided using the protocol of the URL passed in (e.g. ws:// or wss://)

If you have non-default SSL circumstances, you can use the ssl_config parameter to configure those.

let mut client = ClientBuilder::new("wss://supersecret.l33t").unwrap()
    .connect(None)
    .unwrap();

// send messages!
let message = Message::text("m337 47 7pm");
client.send_message(&message).unwrap();

Create an insecure (plain TCP) connection to the client. In this case no Box will be used, you will just get a TcpStream, giving you the ability to split the stream into a reader and writer (since SSL streams cannot be cloned).

let mut client = ClientBuilder::new("wss://supersecret.l33t").unwrap()
    .connect_insecure()
    .unwrap();

// split into two (for some reason)!
let (receiver, sender) = client.split().unwrap();

Create an SSL connection to the sever. This will only use an TlsStream, this is useful when you want to be sure to connect over SSL or when you want access to the TlsStream functions (without having to go through a Box).

Connects to a websocket server on any stream you would like. Possible streams:

  • Unix Sockets
  • Logging Middle-ware
  • SSH
use websocket::sync::stream::ReadWritePair;
use std::io::Cursor;

let accept = b"HTTP/1.1 101 Switching Protocols\r
Upgrade: websocket\r
Connection: Upgrade\r
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=\r
\r\n";

let input = Cursor::new(&accept[..]);
let output = Cursor::new(Vec::new());

let client = ClientBuilder::new("wss://test.ws").unwrap()
    .key(b"the sample nonce".clone())
    .connect_on(ReadWritePair(input, output))
    .unwrap();

let text = (client.into_stream().0).1.into_inner();
let text = String::from_utf8(text).unwrap();
assert!(text.contains("dGhlIHNhbXBsZSBub25jZQ=="), "{}", text);

Connect to a websocket server asynchronously.

This will use a Box<AsyncRead + AsyncWrite + Send> to represent either an SSL connection or a normal TCP connection, what to use will be decided using the protocol of the URL passed in (e.g. ws:// or wss://)

If you have non-default SSL circumstances, you can use the ssl_config parameter to configure those.

Example

use websocket::ClientBuilder;
use websocket::futures::{Future, Stream, Sink};
use websocket::Message;
use tokio_core::reactor::Core;

let mut core = Core::new().unwrap();

// let's randomly do either SSL or plaintext
let url = if rand::thread_rng().gen() {
    "ws://echo.websocket.org"
} else {
    "wss://echo.websocket.org"
};

// send a message and hear it come back
let echo_future = ClientBuilder::new(url).unwrap()
    .async_connect(None, &core.handle())
    .and_then(|(s, _)| s.send(Message::text("hallo").into()))
    .and_then(|s| s.into_future().map_err(|e| e.0))
    .map(|(m, _)| {
        assert_eq!(m, Some(Message::text("hallo").into()))
    });

core.run(echo_future).unwrap();

Asynchronously create an SSL connection to a websocket sever.

This method will only try to connect over SSL and fail otherwise, useful when you want to be sure to connect over SSL or when you want access to the TlsStream functions (without having to go through a Box).

If you have non-default SSL circumstances, you can use the ssl_config parameter to configure those.

Example

use websocket::ClientBuilder;
use websocket::futures::{Future, Stream, Sink};
use websocket::Message;
use tokio_core::reactor::Core;

let mut core = Core::new().unwrap();

// send a message and hear it come back
let echo_future = ClientBuilder::new("wss://echo.websocket.org").unwrap()
    .async_connect_secure(None, &core.handle())
    .and_then(|(s, _)| s.send(Message::text("hallo").into()))
    .and_then(|s| s.into_future().map_err(|e| e.0))
    .map(|(m, _)| {
        assert_eq!(m, Some(Message::text("hallo").into()))
    });

core.run(echo_future).unwrap();

Asynchronously create an insecure (plain TCP) connection to the client.

In this case no Box will be used, you will just get a TcpStream, giving you less allocations on the heap and direct access to TcpStream functions.

Example

use websocket::ClientBuilder;
use websocket::futures::{Future, Stream, Sink};
use websocket::Message;
use tokio_core::reactor::Core;

let mut core = Core::new().unwrap();

// send a message and hear it come back
let echo_future = ClientBuilder::new("ws://echo.websocket.org").unwrap()
    .async_connect_insecure(&core.handle())
    .and_then(|(s, _)| s.send(Message::text("hallo").into()))
    .and_then(|s| s.into_future().map_err(|e| e.0))
    .map(|(m, _)| {
        assert_eq!(m, Some(Message::text("hallo").into()))
    });

core.run(echo_future).unwrap();

Asynchronously connects to a websocket server on any stream you would like. Possible streams:

  • Unix Sockets
  • Bluetooth
  • Logging Middle-ware
  • SSH

The stream must be AsyncRead + AsyncWrite + Send + 'static.

Example

use websocket::header::WebSocketProtocol;
use websocket::ClientBuilder;
use websocket::sync::stream::ReadWritePair;
use websocket::futures::Future;
use websocket::async::Core;

let mut core = Core::new().unwrap();

let accept = b"\
HTTP/1.1 101 Switching Protocols\r\n\
Upgrade: websocket\r\n\
Sec-WebSocket-Protocol: proto-metheus\r\n\
Connection: Upgrade\r\n\
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=\r\n\
\r\n";

let input = Cursor::new(&accept[..]);
let output = Cursor::new(Vec::new());

let client = ClientBuilder::new("wss://test.ws").unwrap()
    .key(b"the sample nonce".clone())
    .async_connect_on(ReadWritePair(input, output))
    .map(|(_, headers)| {
        let proto: &WebSocketProtocol = headers.get().unwrap();
        assert_eq!(proto.0.first().unwrap(), "proto-metheus")
    });

core.run(client).unwrap();

Trait Implementations

impl<'u> Clone for ClientBuilder<'u>
[src]

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

impl<'u> Debug for ClientBuilder<'u>
[src]

Formats the value using the given formatter. Read more

Auto Trait Implementations

impl<'u> Send for ClientBuilder<'u>

impl<'u> !Sync for ClientBuilder<'u>

Blanket Implementations

impl<T, U> Into for T where
    U: From<T>, 
[src]

Performs the conversion.

impl<T> ToOwned for T where
    T: Clone
[src]

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

impl<T> From for T
[src]

Performs the conversion.

impl<T, U> TryFrom for T where
    T: From<U>, 
[src]

🔬 This is a nightly-only experimental API. (try_from)

The type returned in the event of a conversion error.

🔬 This is a nightly-only experimental API. (try_from)

Performs the conversion.

impl<T> Borrow for T where
    T: ?Sized
[src]

Immutably borrows from an owned value. Read more

impl<T> BorrowMut for T where
    T: ?Sized
[src]

Mutably borrows from an owned value. Read more

impl<T, U> TryInto for T where
    U: TryFrom<T>, 
[src]

🔬 This is a nightly-only experimental API. (try_from)

The type returned in the event of a conversion error.

🔬 This is a nightly-only experimental API. (try_from)

Performs the conversion.

impl<T> Any for T where
    T: 'static + ?Sized
[src]

🔬 This is a nightly-only experimental API. (get_type_id)

this method will likely be replaced by an associated static

Gets the TypeId of self. Read more

impl<T> Typeable for T where
    T: Any
[src]

Get the TypeId of this object.

impl<T> Erased for T
[src]