WebSockets

Raw WebSocket connections and managed sessions with automatic reconnection.

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 — online and visibilitychange events trigger an immediate reconnect attempt instead of waiting out the backoff timer.
  • State machine — session.state is one of idle, 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" } ) )
} );