tauri-plugin-socketio
A Tauri 2 plugin for Socket.IO v4 on top of socketio-next: one registry of named clients that Rust and the webviews share.
- Rust connects clients through the plugin, or registers clients it built itself — for example in core code that must not depend on Tauri — optionally read-only for the webview.
- JS connects its own clients (
connect) or attaches to registered ones (attach) with an API close to socket.io-client:emit,emitWithAck,on/once/off/onAny, acks for server callbacks, binary anywhere in the arguments. - Events and state transitions go to each webview over its own IPC channel, in order, filtered by event name if asked. Subscriptions end when the webview reloads or closes.
The socket runs in Rust: no CORS, no browser websocket limits, TLS through rustls (or the platform library), and the connection survives page reloads.
Install
# src-tauri/Cargo.toml
[]
= "0.1"
// src-tauri/src/lib.rs
default
.plugin
// src-tauri/capabilities/default.json
JS
import { connect, attach, list, SocketIoError } from 'tauri-plugin-socketio-api'
const socket = await connect('chat', {
url: 'https://chat.example.com', // the path is the namespace, like socket.io-client
auth: { token },
transports: ['websocket'], // default: polling upgraded to websocket
reconnectionDelay: 500,
events: ['message', 'typing'], // optional: forward only these events to this webview
})
socket.on('message', (text, from) => console.log(from, text))
socket.on('question', (q, ack) => ack('answer')) // the server emitted with a callback
socket.onAny((event, ...args) => console.debug(event, args))
const off = socket.onState((s) => console.log(s.status)) // connecting / connected / disconnected / reconnecting / closed
await socket.emit('message', 'hi', new Uint8Array([1, 2, 3]))
const [sum] = await socket.emitWithAck('add', [1, 2], { timeout: 5000 })
socket.connected; socket.id; socket.lastState
await socket.state(); await socket.linkInfo() // ... packetsIn/Out, bytesIn/Out, sessions
await socket.setAuth({ token: fresh }) // used from the next connect attempt
await socket.setHeaders({ authorization: `Bearer ${fresh}` }); await socket.setQuery({ v: '2' })
await socket.reconnect() // after `closed` (rejected, attempts used up, server disconnect)
await socket.close() // stop receiving here; the client stays connected
await socket.disconnect() // leave, close, unregister (every webview sees `closed`)
const core = await attach('core') // a client Rust registered
await list() // [{ id, access: 'full' | 'readOnly', namespace, state }]
Options (milliseconds for durations): url, namespace, path, query, headers
(extraHeaders), auth, transports (['polling', 'websocket'], ['websocket'],
['polling'] or 'websocket-upgrade'), timeout, reconnection, reconnectionAttempts,
reconnectionDelay, reconnectionDelayMax, randomizationFactor, reconnectOnDisconnect,
bufferWhileDisconnected, ca (PEM certificates of a private CA; checks cannot be turned
off), plus events (the forwarding filter). Auth, headers and query are read again before every
connect attempt, so setAuth / setHeaders / setQuery take effect on the next reconnect;
they and reconnect work on clients a webview connected (NotConfigurable for Rust's,
AccessDenied for read-only ones).
Timing. connect attaches the subscription before connecting, so the events the server
sends right after the connect are not lost. When connect / attach resolve, the socket
already has the current state (socket.connected, socket.id); messages that arrived before
are held until the next task (states older than that snapshot are dropped). Add handlers right
after the await.
Ids are unique. connect with an id in use rejects with AlreadyExists — typically after a
page reload, since the client lives in Rust. attach(id) to it, or disconnect it first.
Binary. Uint8Array, ArrayBuffer, typed arrays and DataViews anywhere in the arguments
are sent as socket.io attachments; incoming attachments arrive as Uint8Arrays. On the IPC
they are { args, binary }, where {"_placeholder":true,"num":n} in args stands for
binary[n] (socket.io-parser's encoding; encodeArgs / decodeArgs are exported). Without
attachments nothing is replaced: a JSON object that looks like a placeholder stays JSON. Bytes
cross the IPC as arrays of numbers, so prefer the websocket for large blobs.
Errors are SocketIoError with kind, message and data: ConnectRejected (data is
the server middleware's err.data), ConnectTimeout, NotConnected, AckTimeout,
Disconnected, Closed, AccessDenied, UnknownClient, AlreadyExists, UnknownAck,
Reserved, UrlNotAllowed, TooManySubscriptions, InvalidOptions (a wrong option type or
value; the value is not echoed), NotConfigurable, WebsocketClosed (data: { code, reason }),
ProxyFailed, engine
failures by name (HttpStatus with data.status and data.message, Websocket, Http, TlsProviderMissing,
...), and Ipc for a rejection that is not the plugin's (a command the capability does not
allow). Messages never contain URLs or query values.
Rust
use ClientBuilder;
use ;
// in setup or a command; `app` is anything that implements `tauri::Manager`
let io = app.socketio;
io.reserve; // in setup, before any await: webviews cannot take the id
let client = io.connect.await?; // Access::Full
io.insert?; // built elsewhere
io.get; // Option<Client>
io.access; // Option<Access>
io.ids; // Vec<String>
io.remove; // Option<Client>: unregisters, does not disconnect
io.subscribe?; // 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.
tauri_plugin_socketio::socketio_next re-exports the client crate.
Read-only clients (Rust owns the socket)
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
// the app
.setup
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 (ack is refused); answer them in Rust.
Security
-
Reserve Rust's ids. Rust usually registers its clients after an
await(the connect). Until then any page script withallow-connectcouldconnectunder the same id, and Rust'sinsertwould fail withAlreadyExistswhileget(id)returned the page's client. Callreserve(id)insetup. -
The CSP does not cover these sockets. They run in Rust, so
connect-srcdoes not limit them: withallow-connecta page can reach any host with any headers. Restrict it:.pluginWhat is enforced: the scheme, the host, the port, and the engine.io path (the
pathoption, default/socket.io/) under the prefix's path on a/boundary. The URL's own path is the namespace and is not part of the check, nor is thenamespaceoption. Query and headers changed later (setQuery,setHeaders) andreconnectcannot move the target. Withoutallow_url_prefixevery URL is allowed (init()). Rust'sconnect/insertare never restricted. -
Headers from the webview are limited.
Host,Connection,Upgrade,Content-Length,Transfer-Encoding,Cookie(cookies come from the jar),Sec-WebSocket-*andProxy-*are refused withInvalidOptionsnaming the header, in the connect options and insetHeaders. Rust's clients are not limited. Grantallow-readinstead ofdefaultto windows that only observe. -
Webviews are isolated.
unsubscribeandackact only on the calling webview's subscriptions and on acks offered to it (UnknownAckotherwise). A webview has at mostMAX_SUBSCRIPTIONS_PER_WEBVIEW(64) subscriptions and, per client, at mostMAX_PENDING_ACKS_PER_WEBVIEW(256) unanswered server acks; past that its own oldest ack is forgotten, never another webview's.
Permissions
| Identifier | Commands |
|---|---|
socketio:default |
everything below |
socketio:allow-read |
list, subscribe, unsubscribe, state, link_info |
socketio:allow-connect / allow-disconnect |
connect / disconnect |
socketio:allow-emit / allow-emit-with-ack / allow-ack |
emit / emit_with_ack / ack |
socketio:allow-set-auth / allow-set-headers / allow-set-query / allow-reconnect |
set_auth / set_headers / set_query / reconnect |
socketio:allow-subscribe, allow-unsubscribe, allow-list, allow-state, allow-link-info |
one each |
Every allow-* has a deny-*. The full table is in
permissions/autogenerated/reference.md.
Messages and limits
A subscription's channel carries { type: 'state', state } (the first one is the state at
subscribe time) and { type: 'event', event, args, binary?, ackId? }. State objects are
{ status: 'connecting', attempt }, { status: 'connected', sid, recovered },
{ status: 'disconnected', reason, error? }, { status: 'reconnecting', attempt, delay, error? },
{ status: 'closed', reason, error? } with socket.io-client's reason strings (io server disconnect, io client disconnect, ping timeout, transport close, transport error,
parse error) plus connect rejected, reconnect failed, client dropped.
A server ack gets one ackId, offered to every webview subscribed to the event; the first
answer wins, later ones fail with UnknownAck. Acks wait for ACK_TTL (2 min); see Security
for the budgets. Once a disconnect starts, no ack is offered any more.
A failed first connect can send the attempt's states (connecting, closed) on the channel
before the promise rejects; guest-js drops that socket, the rejection is the answer.
The first state message of a subscription carries snapshot: true: the state at subscribe
time, also returned by connect / attach; nothing older follows it on that channel.
TLS, mobile
Features: rustls (default) and native-tls, forwarded to socketio-next. If any crate in your
build enables reqwest 0.13's rustls-no-provider — tauri-plugin-updater does — keep rustls
on, or connects fail with TlsProviderMissing (see socketio-next's README). On Android and iOS
rustls with the bundled webpki roots works without setup.
Troubleshooting
| Symptom | Check |
|---|---|
Ipc: ... not allowed |
The window's capability lacks the command (socketio:default or the allow-* you need). |
AlreadyExists after a reload |
The client survived the reload in Rust: attach(id), or disconnect() it before connect. |
AccessDenied |
The client was registered Access::ReadOnly; drive it from Rust. |
UnknownClient right at startup |
Rust registers its client after its first connect; retry attach or wait for list(). |
Reserved |
Rust reserved the id; attach to it instead. |
UrlNotAllowed |
Add the server to Builder::allow_url_prefix. |
UnknownAck |
The ack was answered already, expired (ACK_TTL) or belongs to another client. |
TlsProviderMissing |
See TLS above. |
| Missed events | Add handlers right after await connect(...); check the events filter. |
| Anything else about the connection | socketio-next's troubleshooting table; RUST_LOG=socketio_next=debug. |
Example
examples/tauri-app: Rust registers a read-only core client and drives
it, the webview attaches to it and connects its own chat client. Run just servers at the
repository root, then pnpm install && pnpm tauri dev in the example.
License
MIT