WebSockets
The remote manager provides webSocket() for a raw connection and
webSocketSession() (9.1.0) for a managed session with exponential backoff,
ping/pong zombie detection, and reconnect on network recovery.
Raw WebSocket
const ws = myApp.remote.webSocket(
"/ws/notifications", // ws:// / wss:// URL, or a path (scheme chosen by isSecure)
function( data ) {
// data is the parsed JSON message
console.log( "notification:", data );
},
true // isSecure → wss://
);
The URL is validated up front: an empty or non-string URL throws a TypeError
at the call site instead of producing ws://undefined/.... With
useTokens: true, the session token is appended as a ?token= query parameter.
A raw socket is exactly that — if it drops, it stays dropped. For anything that should survive network hiccups, use a session.
Managed sessions
webSocketSession( options ) returns a WebSocketSession:
const session = myApp.remote.webSocketSession( {
url: "/ws/notifications",
isSecure: true, // default: wss://
handleMessage: function( data ) {
// required — called with each parsed message
notificationBell.setState( { items: data.items } );
},
onOpen: function( socket ) {
// optional — called after each successful open; subscribe here
socket.send( JSON.stringify( { type: "subscribe", topic: "tasks" } ) );
},
ping: { // optional — zombie detection
interval: 30000, // ping every 30s
timeout: 5000, // force-close if no pong in 5s
send: ( socket ) => socket.send( JSON.stringify( { type: "ping" } ) ),
isPong: ( data ) => data.type === "pong"
},
beforeReconnect: async function() {
// optional — return false to give up permanently (e.g. logged out);
// throw to treat the failure as transient (backoff continues)
return myApp.authenticated;
},
backoff: { initial: 1000, max: 30000, jitter: true },
maxAttempts: Infinity
} );
What the session does for you:
- Exponential backoff with jitter between reconnect attempts (default 1s → 30s cap), so a flapping server isn’t met by a thundering herd.
- Ping/pong zombie detection — a half-open TCP connection that silently stopped delivering messages is force-closed so the reconnect logic can take over.
- Network awareness —
onlineandvisibilitychangeevents trigger an immediate reconnect attempt instead of waiting out the backoff timer. - State machine —
session.stateis one ofidle,connecting,open,reconnecting,closed.
Sending and closing
session.send( JSON.stringify( { type: "chat", text: "hello" } ) );
// → true if sent, false if the socket is not currently open
session.close(); // explicit shutdown — no more reconnects after this
Pattern: socket events into the event system
A common integration maps socket messages to pub/sub topics, so views can subscribe like they do to everything else:
const session = myApp.remote.webSocketSession( {
url: "/ws/events",
handleMessage: ( data ) => {
// data: { topic: "task.updated", payload: {...} }
myApp.events.publish( data.topic, data.payload );
},
onOpen: ( socket ) => socket.send( JSON.stringify( { type: "subscribe-all" } ) )
} );
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.