Messages and errors
The JS API handles the channel for you; this page describes it for Rust-side channels (subscribe) and for debugging.
Channel messages
A subscription's channel carries:
type Message =
| { type: 'state'; state: ConnectionState; snapshot?: boolean }
| { type: 'event'; event: string; args: unknown[]; binary?: number[][]; ackId?: number }
The first state message carries snapshot: true: the state at subscribe time, also returned by connect / attach; nothing older follows it on that channel.
States
{ status: 'connecting', attempt }
{ status: 'connected', sid, recovered }
{ status: 'disconnected', reason, error? }
{ status: 'reconnecting', attempt, delay, error? }
{ status: 'closed', reason, error? }
Reasons are socket.io-client's strings (io server disconnect, io client disconnect, ping timeout, transport close, transport error, parse error) plus connect rejected, reconnect failed, client dropped.
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.
Server acks
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). Once a disconnect starts, no ack is offered any more. Read-only clients offer no acks to webviews.
Errors
Rejections are SocketIoError with kind, message and data. Messages never contain URLs or query values.
kind | When |
|---|---|
ConnectRejected | the server's middleware refused the namespace; data is its err.data |
ConnectTimeout | the first connect attempt timed out |
NotConnected, Disconnected, Closed, AckTimeout | as in the Rust client |
AccessDenied | the client is read-only |
UnknownClient | no client with that id |
AlreadyExists | the id is in use |
Reserved | Rust reserved the id |
UnknownAck | the ack was answered, expired or belongs to another client or webview |
UrlNotAllowed | the URL is outside allow_url_prefix |
TooManySubscriptions | the webview has 64 subscriptions |
InvalidOptions | a wrong option type or value, or a refused header (the value is not echoed) |
NotConfigurable | setAuth / setHeaders / setQuery / reconnect on a client Rust connected |
WebsocketClosed | data: { code, reason } |
ProxyFailed | the proxy refused |
HttpStatus, Websocket, Http, TlsProviderMissing, ... | engine failures by name; HttpStatus has data.status and data.message |
Ipc | a rejection that is not the plugin's (a command the capability does not allow) |