Crate rust_socketio

Expand description

Rust-socket.io is a socket.io client written in the Rust Programming Language.

§Example usage

use rust_socketio::{ClientBuilder, Payload, RawClient};
use serde_json::json;
use std::time::Duration;

// define a callback which is called when a payload is received
// this callback gets the payload as well as an instance of the
// socket to communicate with the server
let callback = |payload: Payload, socket: RawClient| {
       match payload {
           Payload::Text(values) => println!("Received: {:#?}", values),
           Payload::Binary(bin_data) => println!("Received bytes: {:#?}", bin_data),
           // This variant is deprecated, use Payload::Text instead
           Payload::String(str) => println!("Received: {}", str),
       }
       socket.emit("test", json!({"got ack": true})).expect("Server unreachable")
};

// get a socket that is connected to the admin namespace
let mut socket = ClientBuilder::new("http://localhost:4200/")
     .namespace("/admin")
     .on("test", callback)
     .on("error", |err, _| eprintln!("Error: {:#?}", err))
     .connect()
     .expect("Connection failed");

// emit to the "foo" event
let json_payload = json!({"token": 123});

socket.emit("foo", json_payload).expect("Server unreachable");

// define a callback, that's executed when the ack got acked
let ack_callback = |message: Payload, _: RawClient| {
    println!("Yehaa! My ack got acked?");
    println!("Ack data: {:#?}", message);
};

let json_payload = json!({"myAckData": 123});

// emit with an ack
let ack = socket
    .emit_with_ack("test", json_payload, Duration::from_secs(2), ack_callback)
    .expect("Server unreachable");

The main entry point for using this crate is the ClientBuilder which provides a way to easily configure a socket in the needed way. When the connect method is called on the builder, it returns a connected client which then could be used to emit messages to certain events. One client can only be connected to one namespace. If you need to listen to the messages in different namespaces you need to allocate multiple sockets.

§Current features

This implementation now supports all of the features of the socket.io protocol mentioned here. It generally tries to make use of websockets as often as possible. This means most times only the opening request uses http and as soon as the server mentions that he is able to use websockets, an upgrade is performed. But if this upgrade is not successful or the server does not mention an upgrade possibility, http-long polling is used (as specified in the protocol specs).

Here’s an overview of possible use-cases:

connecting to a server.
register callbacks for the following event types:
- open
- close
- error
- message
- custom events like “foo”, “on_payment”, etc.
send JSON data to the server (via serde_json which provides safe handling).
send JSON data to the server and receive an ack.
send and handle Binary data.

§Async version

This library provides an ability for being executed in an asynchronous context using tokio as the execution runtime. Please note that the current async implementation is in beta, the interface can be object to drastic changes. The async Client and ClientBuilder support a similar interface to the sync version and live in the asynchronous module. In order to enable the support, you need to enable the async feature flag:

rust_socketio = { version = "^0.4.1", features = ["async"] }

The following code shows the example above in async fashion:

use futures_util::FutureExt;
use rust_socketio::{
    asynchronous::{Client, ClientBuilder},
    Payload,
};
use serde_json::json;
use std::time::Duration;

#[tokio::main]
async fn main() {
    // define a callback which is called when a payload is received
    // this callback gets the payload as well as an instance of the
    // socket to communicate with the server
    let callback = |payload: Payload, socket: Client| {
        async move {
            match payload {
                Payload::Text(values) => println!("Received: {:#?}", values),
                Payload::Binary(bin_data) => println!("Received bytes: {:#?}", bin_data),
                // This is deprecated use Payload::Text instead
                Payload::String(str) => println!("Received: {}", str),
            }
            socket
                .emit("test", json!({"got ack": true}))
                .await
                .expect("Server unreachable");
        }
        .boxed()
    };

    // get a socket that is connected to the admin namespace
    let socket = ClientBuilder::new("http://localhost:4200/")
        .namespace("/admin")
        .on("test", callback)
        .on("error", |err, _| {
            async move { eprintln!("Error: {:#?}", err) }.boxed()
        })
        .connect()
        .await
        .expect("Connection failed");

    // emit to the "foo" event
    let json_payload = json!({"token": 123});
    socket
        .emit("foo", json_payload)
        .await
        .expect("Server unreachable");

    // define a callback, that's executed when the ack got acked
    let ack_callback = |message: Payload, _: Client| {
        async move {
            println!("Yehaa! My ack got acked?");
            println!("Ack data: {:#?}", message);
        }
        .boxed()
    };

    let json_payload = json!({"myAckData": 123});
    // emit with an ack
    socket
        .emit_with_ack("test", json_payload, Duration::from_secs(2), ack_callback)
        .await
        .expect("Server unreachable");

    socket.disconnect().await.expect("Disconnect failed");
}

Re-exports§

pub use error::Error;
pub use event::Event;
pub use payload::Payload;
pub use client::ClientBuilder;
pub use client::RawClient;
pub use client::TransportType;
pub use client::ClientBuilder as SocketBuilder;
pub use client::RawClient as Socket;

Modules§

asynchronous: Asynchronous version of the socket.io client. This module contains the async crate::asynchronous::Client as well as a builder (crate::asynchronous::ClientBuilder) that allows for configuring a client.
client: Defines client only structs
error: Deprecated import since 0.3.0-alpha-2, use Error in the crate root instead. Contains the error type which will be returned with every result in this crate.
event: Deprecated import since 0.3.0-alpha-2, use Event in the crate root instead. Defines the events that could be sent or received.
payload: Deprecated import since 0.3.0-alpha-2, use Event in the crate root instead. Defines the types of payload (binary or string), that could be sent or received.

Macros§

async_any_callback: A macro to wrap an async callback function to be used in the client.
async_callback: A macro to wrap an async callback function to be used in the client.