Rust API
SocketIoExt adds socketio() to anything that implements tauri::Manager (App, AppHandle, Window, Webview, ...). It panics when the plugin is not registered.
use tauri_plugin_socketio::socketio_next::ClientBuilder;
use tauri_plugin_socketio::{Access, SocketIoExt};
// in setup or a command
let io = app.socketio();
io.reserve("core"); // in setup, before any await: webviews cannot take the id
let client = io.connect("chat", ClientBuilder::new("https://chat.example.com")).await?; // Access::Full
io.insert("core", my_client, Access::ReadOnly)?; // built elsewhere
io.get("core"); // Option<Client>
io.access("core"); // Option<Access>
io.ids(); // Vec<String>
io.remove("core"); // Option<Client>: unregisters, does not disconnect
io.subscribe("core", Some(vec!["tock".into()]), channel)?; // forward to a tauri::ipc::Channel
| Method | Behaviour |
|---|---|
connect(id, builder) -> Result<Client> | builds, connects, registers as Access::Full; AlreadyExists when the id is taken (the new client is dropped) |
insert(id, client, access) -> Result<()> | registers a client built elsewhere; AlreadyExists when the id is taken, never replaces |
reserve(id) | synchronous; a webview's connect with this id fails with Reserved, Rust's connect / insert work. Lasts for the app's life |
get(id) -> Option<Client>, access(id), ids() | lookups |
remove(id) -> Option<Client> | unregisters; its subscriptions stop and its pending server acks are dropped; does not disconnect (call disconnect().await on the returned client, or drop it: the last clone closes) |
subscribe(id, events, channel), unsubscribe(id, sub) | what attach uses, for Rust-side channels (no server acks are offered to them; any subscription can be ended from Rust) |
The JS disconnect() (Access::Full only) unregisters first, then disconnects, so its subscriptions still see the final closed state.
Read-only clients
When the socket belongs to Rust code that must stay free of Tauri, let that code build the client and hand it over:
// a Tauri-free crate
pub async fn start(url: &str) -> socketio_next::Result<socketio_next::Client> {
socketio_next::ClientBuilder::new(url).connect().await
}
// the app
.setup(|app| {
app.socketio().reserve("core"); // synchronous: before any page script can connect("core")
let handle = app.handle().clone();
tauri::async_runtime::spawn(async move {
let client = core::start("https://example.com").await?;
handle.socketio().insert("core", client.clone(), Access::ReadOnly)?;
// keep `client` in your own state to emit from Rust
Ok::<_, tauri_plugin_socketio::Error>(())
});
Ok(())
})
{ "identifier": "default", "windows": ["main"], "permissions": ["core:default", "socketio:allow-read"] }
const core = await attach('core')
core.on('news', render)
await core.emit('x') // rejects: AccessDenied
Access::ReadOnly clients refuse emit, emitWithAck, ack and disconnect from every webview whatever the capabilities allow; the permission sets only decide which commands a window may call at all. Server acks of a read-only client are not forwarded with an ackId answerable from JS; answer them in Rust.
Errors
tauri_plugin_socketio::Error: SocketIo(socketio_next::Error), UnknownClient, AlreadyExists, AccessDenied, UnknownAck, Reserved, UrlNotAllowed, TooManySubscriptions, NotConfigurable, InvalidOptions. Webviews receive them as SocketIoError with the variant name as kind.
Constants
| Constant | Value | What |
|---|---|---|
ACK_TTL | 2 min | how long a server ack waits for a webview's answer |
MAX_SUBSCRIPTIONS_PER_WEBVIEW | 64 | subscriptions per webview |
MAX_PENDING_ACKS_PER_WEBVIEW | 256 | unanswered server acks per webview and client; past that its own oldest is forgotten |