Crate rust_socketio

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

Example usage

use rust_socketio::{SocketBuilder, Payload, Socket};
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, mut socket: Socket| {
       match payload {
           Payload::String(str) => println!("Received: {}", str),
           Payload::Binary(bin_data) => println!("Received bytes: {:#?}", bin_data),
       }
       socket.emit("test", json!({"got ack": true})).expect("Server unreachable")
};

// get a socket that is connected to the admin namespace
let mut socket = SocketBuilder::new("http://localhost:4200")
     .set_namespace("/admin")
     .expect("illegal namespace")
     .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, _| {
    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 SocketBuilder 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.

Re-exports

pub use socketio::event::Event;
pub use socketio::payload::Payload;

Modules

error	Contains the error type which will be returned with every result in this crate. Handles all kinds of errors.
socketio	Contains the types and the code concerning the socket.io protocol.

Structs

HeaderMap	A set of HTTP headers
HeaderValue	Represents an HTTP header field value.
Socket	A socket which handles communication with the server. It’s initialized with a specific address as well as an optional namespace to connect to. If None is given the server will connect to the default namespace "/".
SocketBuilder	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 Socket.

Traits

IntoHeaderName

A marker trait used to identify values that can be used as insert keys to a HeaderMap.