1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257
//! Rust-socket.io is a socket.io client written in the Rust Programming Language.
//! ## Example usage
//!
//! ``` rust
//! 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::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 = 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](https://github.com/socketio/socket.io-protocol).
//! 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:
//! ```toml
//! rust_socketio = { version = "0.4.0-alpha.1", features = ["async"] }
//! ```
//!
//! The following code shows the example above in async fashion:
//!
//! ``` rust
//! 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::String(str) => println!("Received: {}", str),
//! Payload::Binary(bin_data) => println!("Received bytes: {:#?}", bin_data),
//! }
//! 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");
//! }
//! ```
#![allow(clippy::rc_buffer)]
#![warn(clippy::complexity)]
#![warn(clippy::style)]
#![warn(clippy::perf)]
#![warn(clippy::correctness)]
/// Defines client only structs
pub mod client;
/// Deprecated import since 0.3.0-alpha-2, use Event in the crate root instead.
/// Defines the events that could be sent or received.
pub mod event;
pub(crate) mod packet;
/// 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.
pub mod payload;
pub(self) mod socket;
/// 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.
pub mod error;
#[cfg(feature = "async")]
/// 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.
pub mod asynchronous;
pub use error::Error;
pub use {event::Event, payload::Payload};
pub use client::{ClientBuilder, RawClient, TransportType};
// TODO: 0.4.0 remove
#[deprecated(since = "0.3.0-alpha-2", note = "Socket renamed to Client")]
pub use client::{ClientBuilder as SocketBuilder, RawClient as Socket};
#[cfg(test)]
pub(crate) mod test {
use url::Url;
/// The socket.io server for testing runs on port 4200
const SERVER_URL: &str = "http://localhost:4200";
pub(crate) fn socket_io_server() -> Url {
let url = std::env::var("SOCKET_IO_SERVER").unwrap_or_else(|_| SERVER_URL.to_owned());
let mut url = Url::parse(&url).unwrap();
if url.path() == "/" {
url.set_path("/socket.io/");
}
url
}
// The socket.io auth server for testing runs on port 4204
const AUTH_SERVER_URL: &str = "http://localhost:4204";
pub(crate) fn socket_io_auth_server() -> Url {
let url =
std::env::var("SOCKET_IO_AUTH_SERVER").unwrap_or_else(|_| AUTH_SERVER_URL.to_owned());
let mut url = Url::parse(&url).unwrap();
if url.path() == "/" {
url.set_path("/socket.io/");
}
url
}
// The socket.io restart server for testing runs on port 4205
const RESTART_SERVER_URL: &str = "http://localhost:4205";
pub(crate) fn socket_io_restart_server() -> Url {
let url = std::env::var("SOCKET_IO_RESTART_SERVER")
.unwrap_or_else(|_| RESTART_SERVER_URL.to_owned());
let mut url = Url::parse(&url).unwrap();
if url.path() == "/" {
url.set_path("/socket.io/");
}
url
}
// The socket.io restart url auth server for testing runs on port 4206
const RESTART_URL_AUTH_SERVER_URL: &str = "http://localhost:4206";
pub(crate) fn socket_io_restart_url_auth_server() -> Url {
let url = std::env::var("SOCKET_IO_RESTART_URL_AUTH_SERVER")
.unwrap_or_else(|_| RESTART_URL_AUTH_SERVER_URL.to_owned());
let mut url = Url::parse(&url).unwrap();
if url.path() == "/" {
url.set_path("/socket.io/");
}
url
}
}