Struct my_rust_socketio::asynchronous::ClientBuilder
source · pub struct ClientBuilder { /* private fields */ }
Expand description
A builder class for a socket.io
socket. This handles setting up the client and
configuring the callback, the namespace and metadata of the socket. If no
namespace is specified, the default namespace /
is taken. The connect
method
acts the build
method and returns a connected Client
.
Implementations§
source§impl ClientBuilder
impl ClientBuilder
sourcepub fn new<T: Into<String>>(address: T) -> Self
pub fn new<T: Into<String>>(address: T) -> Self
Create as client builder from a URL. URLs must be in the form
[ws or wss or http or https]://[domain]:[port]/[path]
. The
path of the URL is optional and if no port is given, port 80
will be used.
Example
use rust_socketio::{Payload, asynchronous::{ClientBuilder, Client}};
use serde_json::json;
use futures_util::future::FutureExt;
#[tokio::main]
async fn main() {
let callback = |payload: Payload, socket: Client| {
async move {
match payload {
Payload::String(str) => println!("Received: {}", str),
Payload::Binary(bin_data) => println!("Received bytes: {:#?}", bin_data),
}
}.boxed()
};
let mut socket = ClientBuilder::new("http://localhost:4200")
.namespace("/admin")
.on("test", callback)
.connect()
.await
.expect("error while connecting");
// use the socket
let json_payload = json!({"token": 123});
let result = socket.emit("foo", json_payload).await;
assert!(result.is_ok());
}
sourcepub fn namespace<T: Into<String>>(self, namespace: T) -> Self
pub fn namespace<T: Into<String>>(self, namespace: T) -> Self
Sets the target namespace of the client. The namespace should start
with a leading /
. Valid examples are e.g. /admin
, /foo
.
If the String provided doesn’t start with a leading /
, it is
added manually.
sourcepub fn on<T: Into<Event>, F>(self, event: T, callback: F) -> Selfwhere
F: for<'a> FnMut(Payload, Client) -> BoxFuture<'static, ()> + 'static + Send + Sync,
pub fn on<T: Into<Event>, F>(self, event: T, callback: F) -> Selfwhere F: for<'a> FnMut(Payload, Client) -> BoxFuture<'static, ()> + 'static + Send + Sync,
Registers a new callback for a certain crate::event::Event
. The event could either be
one of the common events like message
, error
, open
, close
or a custom
event defined by a string, e.g. onPayment
or foo
.
Example
use rust_socketio::{asynchronous::ClientBuilder, Payload};
use futures_util::FutureExt;
#[tokio::main]
async fn main() {
let socket = ClientBuilder::new("http://localhost:4200/")
.namespace("/admin")
.on("test", |payload: Payload, _| {
async move {
match payload {
Payload::String(str) => println!("Received: {}", str),
Payload::Binary(bin_data) => println!("Received bytes: {:#?}", bin_data),
}
}
.boxed()
})
.on("error", |err, _| async move { eprintln!("Error: {:#?}", err) }.boxed())
.connect()
.await;
}
Issues with type inference for the callback method
Currently stable Rust does not contain types like AsyncFnMut
.
That is why this library uses the type FnMut(..) -> BoxFuture<_>
,
which basically represents a closure or function that returns a
boxed future that can be executed in an async executor.
The complicated constraints for the callback function
bring the Rust compiler to it’s limits, resulting in confusing error
messages when passing in a variable that holds a closure (to the on
method).
In order to make sure type inference goes well, the futures_util::FutureExt::boxed
method can be used on an async block (the future) to make sure the return type
is conform with the generic requirements. An example can be found here:
use rust_socketio::{asynchronous::ClientBuilder, Payload};
use futures_util::FutureExt;
#[tokio::main]
async fn main() {
let callback = |payload: Payload, _| {
async move {
match payload {
Payload::String(str) => println!("Received: {}", str),
Payload::Binary(bin_data) => println!("Received bytes: {:#?}", bin_data),
}
}
.boxed() // <-- this makes sure we end up with a `BoxFuture<_>`
};
let socket = ClientBuilder::new("http://localhost:4200/")
.namespace("/admin")
.on("test", callback)
.connect()
.await;
}
sourcepub fn on_any<F>(self, callback: F) -> Selfwhere
F: for<'a> FnMut(Event, Payload, Client) -> BoxFuture<'static, ()> + 'static + Send + Sync,
pub fn on_any<F>(self, callback: F) -> Selfwhere F: for<'a> FnMut(Event, Payload, Client) -> BoxFuture<'static, ()> + 'static + Send + Sync,
Registers a Callback for all crate::event::Event::Custom
and crate::event::Event::Message
.
Example
use rust_socketio::{asynchronous::ClientBuilder, Payload};
use futures_util::future::FutureExt;
#[tokio::main]
async fn main() {
let client = ClientBuilder::new("http://localhost:4200/")
.namespace("/admin")
.on_any(|event, payload, _client| {
async {
if let Payload::String(str) = payload {
println!("{}: {}", String::from(event), str);
}
}.boxed()
})
.connect()
.await;
}
sourcepub fn tls_config(self, tls_config: TlsConnector) -> Self
pub fn tls_config(self, tls_config: TlsConnector) -> Self
Uses a preconfigured TLS connector for secure communication. This configures
both the polling
as well as the websocket
transport type.
Example
use rust_socketio::{asynchronous::ClientBuilder, Payload};
use native_tls::TlsConnector;
use futures_util::future::FutureExt;
#[tokio::main]
async fn main() {
let tls_connector = TlsConnector::builder()
.use_sni(true)
.build()
.expect("Found illegal configuration");
let socket = ClientBuilder::new("http://localhost:4200/")
.namespace("/admin")
.on("error", |err, _| async move { eprintln!("Error: {:#?}", err) }.boxed())
.tls_config(tls_connector)
.connect()
.await;
}
sourcepub fn opening_header<T: Into<HeaderValue>, K: Into<String>>(
self,
key: K,
val: T
) -> Self
pub fn opening_header<T: Into<HeaderValue>, K: Into<String>>( self, key: K, val: T ) -> Self
Sets custom http headers for the opening request. The headers will be passed to the underlying transport type (either websockets or polling) and then get passed with every request thats made. via the transport layer.
Example
use rust_socketio::{asynchronous::ClientBuilder, Payload};
use futures_util::future::FutureExt;
#[tokio::main]
async fn main() {
let socket = ClientBuilder::new("http://localhost:4200/")
.namespace("/admin")
.on("error", |err, _| async move { eprintln!("Error: {:#?}", err) }.boxed())
.opening_header("accept-encoding", "application/json")
.connect()
.await;
}
sourcepub fn auth<T: Into<Value>>(self, auth: T) -> Self
pub fn auth<T: Into<Value>>(self, auth: T) -> Self
Sets authentification data sent in the opening request.
Example
use rust_socketio::{asynchronous::ClientBuilder};
use serde_json::json;
use futures_util::future::FutureExt;
#[tokio::main]
async fn main() {
let socket = ClientBuilder::new("http://localhost:4204/")
.namespace("/admin")
.auth(json!({ "password": "1337" }))
.on("error", |err, _| async move { eprintln!("Error: {:#?}", err) }.boxed())
.connect()
.await;
}
sourcepub fn transport_type(self, transport_type: TransportType) -> Self
pub fn transport_type(self, transport_type: TransportType) -> Self
Specifies which EngineIO TransportType
to use.
Example
use rust_socketio::{asynchronous::ClientBuilder, TransportType};
#[tokio::main]
async fn main() {
let socket = ClientBuilder::new("http://localhost:4200/")
// Use websockets to handshake and connect.
.transport_type(TransportType::Websocket)
.connect()
.await
.expect("connection failed");
}
sourcepub async fn connect(self) -> Result<Client, Error>
pub async fn connect(self) -> Result<Client, Error>
Connects the socket to a certain endpoint. This returns a connected
Client
instance. This method returns an std::result::Result::Err
value if something goes wrong during connection. Also starts a separate
thread to start polling for packets. Used with callbacks.
Example
use rust_socketio::{asynchronous::ClientBuilder, Payload};
use serde_json::json;
use futures_util::future::FutureExt;
#[tokio::main]
async fn main() {
let mut socket = ClientBuilder::new("http://localhost:4200/")
.namespace("/admin")
.on("error", |err, _| async move { eprintln!("Error: {:#?}", err) }.boxed())
.connect()
.await
.expect("connection failed");
// use the socket
let json_payload = json!({"token": 123});
let result = socket.emit("foo", json_payload).await;
assert!(result.is_ok());
}