Struct evzht9h3nznqzwl::client::builder::ClientBuilder
[−]
[src]
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]
fn from_url(address: &'u Url) -> Self
[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://
.
fn new(address: &str) -> Result<Self, ParseError>
[src]
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");
fn add_protocol<P>(self, protocol: P) -> Self where
P: Into<String>,
[src]
P: Into<String>,
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()));
fn add_protocols<I, S>(self, protocols: I) -> Self where
I: IntoIterator<Item = S>,
S: Into<String>,
[src]
I: IntoIterator<Item = S>,
S: Into<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()));
fn clear_protocols(self) -> Self
[src]
Removes all the currently set protocols.
fn add_extension(self, extension: Extension) -> Self
[src]
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");
fn add_extensions<I>(self, extensions: I) -> Self where
I: IntoIterator<Item = Extension>,
[src]
I: IntoIterator<Item = Extension>,
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![], }, ]);
fn clear_extensions(self) -> Self
[src]
Remove all the extensions added to the builder.
fn key(self, key: [u8; 16]) -> Self
[src]
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.
fn clear_key(self) -> Self
[src]
Remove the currently set Sec-WebSocket-Key
header if any.
fn version(self, version: WebSocketVersion) -> Self
[src]
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.
fn clear_version(self) -> Self
[src]
Unset the websocket version to be the default (WebSocket 13).
fn origin(self, origin: String) -> Self
[src]
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.
fn clear_origin(self) -> Self
[src]
Remove the Origin header from the handshake.
fn custom_headers(self, custom_headers: &Headers) -> Self
[src]
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);
fn clear_header<H>(self) -> Self where
H: Header + HeaderFormat,
[src]
H: Header + HeaderFormat,
Remove a type of header from the handshake, this is to be used
with the catch all custom_headers
.
fn get_header<H>(&self) -> Option<&H> where
H: Header + HeaderFormat,
[src]
H: Header + HeaderFormat,
Get a header to inspect it.
fn connect(
&mut self,
ssl_config: Option<TlsConnector>
) -> WebSocketResult<Client<Box<NetworkStream + Send>>>
[src]
&mut self,
ssl_config: Option<TlsConnector>
) -> WebSocketResult<Client<Box<NetworkStream + Send>>>
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();
fn connect_insecure(&mut self) -> WebSocketResult<Client<TcpStream>>
[src]
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();
fn connect_secure(
&mut self,
ssl_config: Option<TlsConnector>
) -> WebSocketResult<Client<TlsStream<TcpStream>>>
[src]
&mut self,
ssl_config: Option<TlsConnector>
) -> WebSocketResult<Client<TlsStream<TcpStream>>>
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
).
fn connect_on<S>(&mut self, stream: S) -> WebSocketResult<Client<S>> where
S: Stream,
[src]
S: Stream,
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);
fn async_connect(
self,
ssl_config: Option<TlsConnector>,
handle: &Handle
) -> ClientNew<Box<Stream + Send>>
[src]
self,
ssl_config: Option<TlsConnector>,
handle: &Handle
) -> ClientNew<Box<Stream + Send>>
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();
fn async_connect_secure(
self,
ssl_config: Option<TlsConnector>,
handle: &Handle
) -> ClientNew<TlsStream<TcpStream>>
[src]
self,
ssl_config: Option<TlsConnector>,
handle: &Handle
) -> ClientNew<TlsStream<TcpStream>>
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();
fn async_connect_insecure(self, handle: &Handle) -> ClientNew<TcpStream>
[src]
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();
fn async_connect_on<S>(self, stream: S) -> ClientNew<S> where
S: Stream + Send + 'static,
[src]
S: Stream + Send + 'static,
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]
fn clone(&self) -> ClientBuilder<'u>
[src]
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0[src]
Performs copy-assignment from source
. Read more