angelia.io 5.0.0 → 5.0.2

package/client/index.js

@@ -47,6 +47,18 @@ const settle = reply => reply
 
 const noop = () => {}
 
+/**
+ * A reply that can no longer arrive isn't an error of the app's: only a caller
+ * reading the promise hears of it. A throwing callback still surfaces as unhandled.
+ *
+ * @template T
+ * @param {Promise<T>} promise
+ */
+const handled = promise => {
+	promise.catch(noop)
+	return promise
+}
+
 const newConnid = () =>
 	crypto.getRandomValues(new BigUint64Array(1))[0].toString(36)
 
@@ -104,6 +116,7 @@ export default class Client {
 	#isReconnect = false
 	#reconnect = true
 	#packFailed = false
+	#online = () => this.connect()
 
 	/** @param {ClientOptions} options */
 	constructor(options) {
@@ -135,6 +148,8 @@ export default class Client {
 	/** Open the socket; no-op while open or after `disconnect(true)`. */
 	connect() {
 		if (this.#io || !this.#reconnect) return
+		// The same function again is no second listener.
+		addEventListener('online', this.#online)
 
 		const url = new URL(this.options.url)
 		if (url.pathname === '/') url.pathname = DEFAULT_PATH
@@ -294,7 +309,7 @@ export default class Client {
 		}
 		// After `disconnect(true)` nothing will be sent: don't queue it.
 		if (!this.#reconnect) {
-			return callback ? Promise.reject(new Error(DISCONNECTED)) : undefined
+			return callback ? handled(Promise.reject(new Error(DISCONNECTED))) : undefined
 		}
 
 		if (callback) {
@@ -419,6 +434,7 @@ export default class Client {
 
 	/** After `disconnect(true)`: nothing will be sent or answered again. */
 	#shutdown() {
+		removeEventListener('online', this.#online)
 		this.#transport.terminate()
 		this.#messages = []
 		this.#cancelPending(DISCONNECTED)
@@ -463,7 +479,10 @@ export default class Client {
 					reject(err)
 				}
 			},
-			cancel: reject,
+			cancel: err => {
+				handled(promise)
+				reject(err)
+			},
 		})
 		return [id, promise]
 	}

package/client/transport.js

@@ -1,6 +1,6 @@
 /**
  * The Client's socket lives in a Web Worker, so the browser's own
- * send/receive work (expensive in Chromium) and the heartbeat reply stay
+ * send/receive work (expensive in Chromium) and the heartbeat stay
  * off the main thread (see `bench/browser`). Only strings cross
  * `postMessage`; everything else stays in Client.
  *
@@ -22,6 +22,8 @@
  * }} Transport
  */
 
+import { TIMEOUT_MS } from '../shared/protocol.js'
+
 /**
  * The Client only opens a connection after the previous one closed, so
  * the worker holds at most one socket and no ids are needed. Data frames
@@ -71,7 +73,7 @@ export function workerTransport() {
 		open(url, handlers) {
 			const live = (worker ??= spawn())
 			current = handlers
-			live.postMessage(['connect', url.toString()])
+			live.postMessage(['connect', url.toString(), TIMEOUT_MS])
 			return {
 				send: text => live.postMessage(text),
 				close: (code, reason) => live.postMessage(['close', code, reason]),
@@ -97,26 +99,63 @@ export function workerTransport() {
 function workerMain(scope) {
 	/** @type {WebSocket | null} */
 	let ws = null
+	/** @type {ReturnType<typeof setInterval> | undefined} */
+	let heartbeat
+	let received = 0
+	let sent = 0
+
+	/** @param {number} code */
+	const closed = code => {
+		ws = null
+		clearInterval(heartbeat)
+		scope.postMessage(['close', code])
+	}
+
+	/** @param {number} timeout */
+	const watch = timeout => {
+		heartbeat = setInterval(() => {
+			const socket = /** @type {WebSocket} */ (ws)
+			const now = Date.now()
+			if (now - received > timeout) {
+				// A dead connection never finishes the closing handshake: don't wait for it.
+				socket.onmessage = socket.onclose = null
+				closed(1006)
+				socket.close()
+			} else if (now - Math.min(received, sent) > timeout / 2 - 5000) {
+				// Either way: the server times out a client that only listens.
+				sent = now
+				socket.send('')
+			}
+		}, timeout / 2)
+	}
 
 	scope.onmessage = ({ data }) => {
 		if (typeof data === 'string') {
-			if (ws?.readyState === WebSocket.OPEN) ws.send(data)
+			if (ws?.readyState === WebSocket.OPEN) {
+				sent = Date.now()
+				ws.send(data)
+			}
 			return
 		}
-		const [type, value, reason] = data
+		const [type] = data
 		if (type === 'connect') {
-			const socket = new WebSocket(value)
+			const [, url, timeout] = data
+			const socket = new WebSocket(url)
 			ws = socket
-			socket.onopen = () => scope.postMessage(['open'])
-			socket.onclose = e => {
-				if (ws === socket) ws = null
-				scope.postMessage(['close', e.code])
+			socket.onopen = () => {
+				received = sent = Date.now()
+				watch(timeout)
+				scope.postMessage(['open'])
+			}
+			socket.onclose = e => closed(e.code)
+			socket.onmessage = e => {
+				received = Date.now()
+				if (e.data !== '') scope.postMessage(e.data)
 			}
-			socket.onmessage = e =>
-				e.data === '' ? socket.send('') : scope.postMessage(e.data)
 		} else if (type === 'close') {
+			const [, code, reason] = data
 			try {
-				ws?.close(value, reason)
+				ws?.close(code, reason)
 			} catch (err) {
 				scope.postMessage(['error', String(err)])
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "angelia.io",
-	"version": "5.0.0",
+	"version": "5.0.2",
 	"description": "WebSockets Server and Client API for node.js and the browser, with rooms support.",
 	"author": "@titoBouzout @boredofnames",
 	"license": "GPL",
@@ -43,7 +43,8 @@
 		"demo": "node tests/demo/server.js",
 		"bench:worker": "node bench/browser/run.js",
 		"bench:server": "node bench/node-receive.js",
-		"bench:fanout": "node bench/fanout.js"
+		"bench:fanout": "node bench/fanout.js",
+		"bench:message": "node bench/message.js"
 	},
 	"homepage": "https://github.com/titoBouzout/angelia.io",
 	"repository": {

package/readme.md

@@ -74,7 +74,6 @@ socket.on('gotIt', message => {
 | `hostname`        | String  | `127.0.0.1` | the hostname (interface) to bind to                                                                           |
 | `port`            | Number  | 3001        | the TCP port to listen on; `0` lets the OS pick one, read it from `Server.port` after `listen()`              |
 | `path`            | String  | `/angelia`  | the WebSocket path; clients connect to it by putting it in their `url`                                        |
-| `timeout`         | Number  | 60000       | time in milliseconds after a socket is considered gone, minimum value is 10000                                |
 | `maxMessageSize`  | Number  | 5           | max size of a single incoming message, in megabytes                                                           |
 | `skipUTF8Validation` | Boolean | true     | skip UTF-8 validation of incoming frames; pass `false` to close connections that send invalid UTF-8           |
 | `cert`            | String  | undefined   | path to a PEM-encoded TLS certificate file. With `privKey`, the server speaks `wss://`; otherwise `ws://`      |
@@ -115,7 +114,6 @@ them with the exported class: `import { Server } from
 | `port`                                | Number   | port used by this server                                                               |
 | `hostname`                            | String   | the interface the server listens on                                                    |
 | `path`                                | String   | the WebSocket path clients connect to                                                  |
-| `timeout`                             | Number   | after how long the socket is considered gone, in ms                                    |
 | `served`                              | Number   | count of sockets ever connected                                                        |
 | `bytesReceived`                       | Number   | sum of bytes the server has ever received                                              |
 | `bytesSent`                           | Number   | sum of bytes sent by the server                                                        |
@@ -131,7 +129,10 @@ them with the exported class: `import { Server } from
 | `on(Class)`                           | Function | attaches all methods of a `Class` as listeners                                         |
 | `emit(key, [value])`                  | Function | emits to all connected sockets                                                         |
 | `broadcast(sender, key, [value])`     | Function | emits to all connected sockets except sender                                           |
+| `send(message)`                       | Function | sends a `Message` to all connected sockets                                             |
+| `sendExcept(sender, message)`         | Function | sends a `Message` to all connected sockets except sender                               |
 | `sockets`                             | Set      | every currently connected socket                                                       |
+| `SocketClass`                         | Class    | class of the sockets it creates, `Socket` unless set before `listen`                   |
 | `reloadCerts()`                       | Function | re-read `cert`/`privKey` from disk and swap them in. Open connections are untouched. Safe to call manually (e.g. on `SIGHUP`); the watcher uses it internally |
 | `stop()`                              | Function | stops listening and drops every connection; `await using server = new Server()` calls it when the scope ends |
 
@@ -149,7 +150,6 @@ The `socket` object is given to you by a listener
 | `params`                       | Object   | the params sent via the client constructor (parsed from the WebSocket URL query); includes `connid`, a per-client id stable across reconnects. The reserved `m` param (URL-packed messages) is parsed off and not exposed here |
 | `since`                        | Number   | timestamp of first seen                                                                                                                                                                                                           |
 | `seen`                         | Number   | timestamp of last received message                                                                                                                                                                                                |
-| `ping`                         | Number   | delay with the socket in milliseconds (full round trip)                                                                                                                                                                           |
 | `closed`                       | Boolean  | whether the socket has disconnected                                                                                                                                                                                               |
 | `timedout`                     | Boolean  | whether we lost connection with this socket                                                                                                                                                                                       |
 | `bytesSent`                    | Number   | sum of bytes sent to this socket                                                                                                                                                                                                  |
@@ -159,8 +159,53 @@ The `socket` object is given to you by a listener
 | `rooms`                        | Set      | the rooms this socket is in                                                                                                                                                                                                       |
 | `request(key, [value])`        | Function | emits and returns a promise for the client's reply, rejected with an Error whose message starts with `disconnected:` if the socket closes first; without a value the listener gets `null` |
 | `emit(key, [value, callback])` | Function | emits to client; with a callback, returns a promise for its result, rejected with an Error whose message starts with `disconnected:` if the socket closes first                                                                                                                                                                                                              |
+| `send(message)` | Function | sends a `Message` to the client |
 | `disconnect([noReconnect, reason])` | Function | closes the WebSocket, pass `true` to prevent re-connections; `reason` (up to 123 bytes) is sent to the client                                                                                                              |
 
+### `Message`
+
+`emit` encodes once per fan-out, in the tick it sends. A `Message` is
+encoded once as it is made, and keeps its encoding for as long as you keep
+it, for a payload sent to sockets one at a time or again later, as a list
+sent to whoever arrives.
+
+```js
+import { Message } from 'angelia.io/server'
+
+const rooms = new Message('rooms', list)
+
+socket.send(rooms)
+room.send(rooms)
+room.sendExcept(socket, rooms)
+
+// equal text means an equal message
+if (rooms.json !== last.json) Server.send(rooms)
+```
+
+Later changes to the value never reach the wire, and `toJSON` runs as it
+is made rather than as it sends. A message carries no reply callback, as
+one belongs to a single socket: use `socket.emit` or `socket.request`.
+
+### Your own `Socket`
+
+Set `Server.SocketClass` before `listen` and each connection is your subclass, so what belongs to a user lives on the socket itself. `toJSON` says what sending a socket sends; by default it sends nothing of it.
+
+```js
+import Server, { Socket } from 'angelia.io/server'
+
+class User extends Socket {
+	username = ''
+	toJSON() {
+		return { username: this.username }
+	}
+}
+
+Server.SocketClass = User
+await Server.listen()
+```
+
+Listeners, hooks and every `sockets` then give you `User`s. Its constructor gets what `Socket`'s does, so pass them on with `super(...args)` if it has one.
+
 ### Server Listeners
 
 Listen to an event by creating a class with any name, and give to
@@ -236,11 +281,10 @@ the right one by name.
 | `listen()`                   | when the server has started listening                                                                                                             |
 | `connect(socket, request)`   | when a socket connects; `request` is `{ headers, url }` from the upgrade — read cookies / auth / custom headers here, it's not kept on the socket |
 | `disconnect(socket, code, reason)` | when a socket gets disconnected, with the WebSocket close code and reason (1006 and `''` when the connection just dropped)                                                                                                                |
-| `ping(socket)`               | when we got an update of the ping for a socket                                                                                                    |
 | `timeout(socket, delay)`     | when we are about to disconnect a timedout socket, gives the delay in milliseconds                                                                |
 | `garbage(socket, data)`      | when the client sends a message with no listener, a malformed one, or one named after a predefined event                                         |
 | `incoming(socket, messages)` | for debugging: ref to array of incoming messages received before dispatching to listeners                                                         |
-| `outgoing(socket, messages)` | for debugging: ref to array of outgoing messages before sending to socket                                                                         |
+| `outgoing(socket, messages)` | for debugging: ref to array of outgoing messages before sending to socket; changing a `Message`'s tuple here never changes what is sent           |
 
 ## Client API (Browser)
 
@@ -267,7 +311,7 @@ to `/angelia`, the server's default; include the path
 
 The WebSocket runs in a Web Worker: messages are still stringified and
 parsed on the main thread, but the browser's own send and receive work
-and the heartbeat reply happen off it. In Chromium that work is the
+and the heartbeat happen off it. In Chromium that work is the
 expensive part of moving large payloads; Firefox still routes a
 worker's socket events through the main thread, so it gains less.
 `npm run bench:worker` measures it.
@@ -322,10 +366,25 @@ down, or the page itself unloading) are retried after a random 2–4s
 delay, so clients don't all come back at once and a page being
 reloaded doesn't open a second connection on its way out.
 
+The client keeps the heartbeat: every 30s it sends an empty
+message to a server it hasn't heard from or written to for
+25s, which the server answers, and it takes a
+connection silent for over 60s for dead and reconnects. The server drops
+a socket it hasn't heard from for as long. These times are fixed.
+
+Going `online` reconnects at once if the client isn't connected, and does
+nothing if it is.
+
+A page Chromium keeps in its back/forward cache holds its connection
+open, unanswering, until the server times it out or the page is
+restored; either way the client reconnects as it is restored.
+
 On reconnect, any messages still queued for send are dropped, and
 pending reply promises (from `request`, or `emit` with a callback)
 reject with an Error whose message starts with `reconnecting:` as soon as the connection drops;
 after `disconnect(true)` they reject with an Error whose message starts with `disconnected:`.
+A caller that ignores the promise hears nothing of a lost reply, while a
+callback that throws still surfaces as an unhandled rejection.
 Messages queued before the first connection opened wait for it.
 The library can't tell which queued messages are safe to replay (a
 typing indicator: yes; a "transfer $100": maybe not), so recovery is
@@ -398,10 +457,13 @@ await Server.listen()
 | `get(id)`                             | method | gets room with such an `id`                    |
 | `join(socket, [id])`                  | method | adds socket to room `id`                       |
 | `leave(socket, [id])`                 | method | removes socket from room `id`                  |
+| `of(socket)`                          | method | iterates the rooms of this list `socket` is in, walking the socket's rooms, not the list's |
 | `sockets`                             | Set    | sockets across every room in this list, each once |
 | `rooms`                               | Map    | every room in this list, by id                 |
 | `emit(key, [value])`                  | method | emits to all sockets in this room list         |
 | `broadcast(socket, key, [value])`     | method | emits to other sockets in this room list       |
+| `send(message)`                       | method | sends a `Message` to all sockets in this room list |
+| `sendExcept(socket, message)`         | method | sends a `Message` to other sockets in this room list |
 
 ### Via a `Room`
 
@@ -451,9 +513,31 @@ await Server.listen()
 | `sockets`                             | Set     | sockets in the room                              |
 | `emit(key, [value])`                  | method  | emits to all sockets in the room                 |
 | `broadcast(socket, key, [value])`     | method  | emits to other sockets in the room               |
+| `send(message)`                       | method  | sends a `Message` to all sockets in the room     |
+| `sendExcept(socket, message)`         | method  | sends a `Message` to other sockets in the room   |
 | `id`                                  | any     | the room id                                      |
 | `join(socket)`                        | method  | adds a socket to the room                        |
-| `leave(socket)`                       | method  | removes a socket from the room                   |
+| `leave(socket)`                       | method  | removes a socket from the room; in a `Rooms` list, an emptied room is deleted unless `persistent` |
+
+### Your own `Emitter`
+
+`Server`, `Room` and `Rooms` send through `Emitter`, which only reads a
+`sockets` field. Extend it for something that sends to sockets it doesn't
+own, as what a room is doing right now:
+
+```js
+import { Emitter } from 'angelia.io/server'
+
+class Match extends Emitter {
+	constructor(room) {
+		super()
+		this.room = room
+	}
+	get sockets() {
+		return this.room.sockets
+	}
+}
+```
 
 ### `sockets` in `Server`, `Room` and `Rooms`
 

package/server/Emitter.js

@@ -1,19 +1,41 @@
 /** @import { ClientEvents, EventKey, EventValue } from './index.js' */
+/** @import { Message } from './Message.js' */
 /** @import { Socket } from './Socket.js' */
 
 /**
  * @typedef {{
  * 	sockets: Iterable<Socket>
- * 	broadcast(me: Socket | undefined, k: any, v?: any): void
  * }} HasSockets
  */
 
+/**
+ * @param {Iterable<Socket>} sockets
+ * @param {any[]} tuple
+ */
+function queueAll(sockets, tuple) {
+	for (const socket of sockets) {
+		socket.queue(tuple)
+	}
+}
+
+/**
+ * @param {Iterable<Socket>} sockets
+ * @param {Socket | undefined} me
+ * @param {any[]} tuple
+ */
+function queueExcept(sockets, me, tuple) {
+	for (const socket of sockets) {
+		if (me !== socket) {
+			socket.queue(tuple)
+		}
+	}
+}
+
 /**
  * Common emit / broadcast logic. Subclasses own the `sockets` field
- * (a Set on Server, Room and Rooms). Each fan-out builds the wire tuple
- * **once** and passes the same reference to every recipient —
- * `Server.cacheMessages` keys the encoded form by message identity, so
- * all sockets share a single encoding.
+ * (a Set on Server, Room and Rooms). Each fan-out queues **one** wire
+ * tuple on every recipient, and `Server.cacheMessages` keeps the encoded
+ * form on it, so all sockets share a single encoding.
  */
 export class Emitter {
 	/**
@@ -25,7 +47,7 @@ export class Emitter {
 	 * @param {EventValue<ClientEvents, K>} v
 	 */
 	emit(k, v) {
-		this.broadcast(undefined, k, v)
+		queueAll(this.sockets, [k, v])
 	}
 
 	/**
@@ -38,12 +60,27 @@ export class Emitter {
 	 * @param {EventValue<ClientEvents, K>} v
 	 */
 	broadcast(me, k, v) {
-		/** @type {[string, any]} */
-		const d = [k, v]
-		for (const socket of this.sockets) {
-			if (me !== socket) {
-				socket.queue(d)
-			}
-		}
+		queueExcept(this.sockets, me, [k, v])
+	}
+
+	/**
+	 * Send an encoded message to every socket in scope.
+	 *
+	 * @this {HasSockets}
+	 * @param {Message<any>} message
+	 */
+	send(message) {
+		queueAll(this.sockets, message.tuple)
+	}
+
+	/**
+	 * Send an encoded message to every socket in scope except `me`.
+	 *
+	 * @this {HasSockets}
+	 * @param {Socket | undefined} me
+	 * @param {Message<any>} message
+	 */
+	sendExcept(me, message) {
+		queueExcept(this.sockets, me, message.tuple)
 	}
 }

package/server/Message.js

@@ -0,0 +1,27 @@
+import { encoded } from './constants.js'
+import { stringify } from './utils.js'
+
+/** @import { ClientEvents, EventKey, EventValue } from './index.js' */
+
+/**
+ * A message encoded once, here, to send to any socket at any time with
+ * `send` / `sendExcept`. Later changes to `v` don't reach the wire.
+ *
+ * @template {EventKey<ClientEvents>} K
+ */
+export class Message {
+	/**
+	 * @param {K} k
+	 * @param {EventValue<ClientEvents, K>} v
+	 */
+	constructor(k, v) {
+		/**
+		 * @internal The wire tuple every send queues.
+		 * @type {any[]}
+		 */
+		this.tuple = [k, v]
+		/** The encoded text; equal text means an equal message. */
+		this.json = stringify(this.tuple)
+		this.tuple[encoded] = this.json
+	}
+}

package/server/Room.js

@@ -7,14 +7,20 @@ import { parent } from './constants.js'
 /** A group of sockets to emit to; subclass it to hook its lifecycle. */
 export class Room extends Emitter {
 	/** @type {Set<Socket>} */
-	sockets = new Set()
+	#sockets = new Set()
 	/** @type {any} Set by `Rooms` for its rooms; yours to set otherwise. */
 	id
-	/** Keep the room in its `Rooms` list when its last socket leaves. */
-	persistent = false
 	/** @type {Rooms<any> | undefined} The list the room belongs to, if any. */
 	;[parent]
 
+	/**
+	 * Off the room's own fields, as a subclass may spread its fields into
+	 * what it sends.
+	 */
+	get sockets() {
+		return this.#sockets
+	}
+
 	/**
 	 * Called when a `Rooms` list creates the room for `socket`.
 	 *
@@ -41,16 +47,30 @@ export class Room extends Emitter {
 		this[parent]?.sockets.add(socket)
 		this.onJoin(socket)
 	}
-	/** @param {Socket} socket */
+	/**
+	 * Leave the room; a room in a `Rooms` list that this empties is deleted
+	 * unless it's `persistent`.
+	 *
+	 * @param {Socket} socket
+	 */
 	leave(socket) {
 		if (!this.sockets.delete(socket)) return
 		socket.rooms.delete(this)
 		const list = this[parent]
 		if (list && !inList(socket, list)) list.sockets.delete(socket)
 		this.onLeave(socket)
+		if (list && !this.persistent && this.sockets.size === 0) {
+			list.rooms.delete(this.id)
+			this.onDelete(socket)
+			// Joins through a kept reference no longer reach this list.
+			this[parent] = undefined
+		}
 	}
 }
 
+/** Keep the room in its `Rooms` list when its last socket leaves. */
+Room.prototype.persistent = false
+
 /**
  * Whether `socket` is still in another room of `list`. Walks the
  * socket's own rooms, which stay few, not the list's members.

package/server/Rooms.js

@@ -51,7 +51,14 @@ export class Rooms extends Emitter {
 			room.id = id
 			this.rooms.set(id, room)
 
-			room.onCreate(socket)
+			// In the list while it runs, for it to find itself; a failed one is no room.
+			try {
+				room.onCreate(socket)
+			} catch (error) {
+				this.rooms.delete(id)
+				room[parent] = undefined
+				throw error
+			}
 		}
 		room.join(socket)
 	}
@@ -64,15 +71,19 @@ export class Rooms extends Emitter {
 	 * @param {any} [id]
 	 */
 	leave(socket, id) {
-		const room = this.rooms.get(id)
-		if (room) {
-			room.leave(socket)
-			if (!room.persistent && room.sockets.size === 0) {
-				this.rooms.delete(id)
-				room.onDelete(socket)
-				// Joins through a kept reference no longer reach this list.
-				room[parent] = undefined
-			}
+		this.rooms.get(id)?.leave(socket)
+	}
+
+	/**
+	 * The rooms of this list `socket` is in. Walks the socket's own rooms,
+	 * which stay few, not the list's. Leaving one while iterating is fine.
+	 *
+	 * @param {Socket} socket
+	 * @returns {Generator<R>}
+	 */
+	*of(socket) {
+		for (const room of socket.rooms) {
+			if (room[parent] === this) yield /** @type {R} */ (room)
 		}
 	}
 

package/server/Server.js

@@ -12,12 +12,16 @@ import {
 import {
 	DEFAULT_MAX_MESSAGE_SIZE_MB,
 	DEFAULT_PORT,
-	DEFAULT_TIMEOUT_MS,
 	LIFECYCLE_EVENTS,
 	MAX_PORT,
-	MIN_TIMEOUT_MS,
+	encoded,
+	framed,
 } from './constants.js'
-import { DEFAULT_PATH, PACKED_PARAM } from '../shared/protocol.js'
+import {
+	DEFAULT_PATH,
+	PACKED_PARAM,
+	TIMEOUT_MS,
+} from '../shared/protocol.js'
 
 import { Socket } from './Socket.js'
 import { Emitter } from './Emitter.js'
@@ -31,9 +35,6 @@ import { createServer as createHttpsServer } from 'node:https'
 
 import { WebSocketServer } from 'ws'
 
-// The heartbeat is a constant empty message — frame once, reuse forever.
-const PING = frame('')
-
 // Close code for a connection that ended without a close frame, which is
 // what `terminate()` does.
 const ABNORMAL_CLOSURE = 1006
@@ -50,8 +51,6 @@ const DEFAULT_WATCH_DEBOUNCE_MS = 1000
  * @property {number} [port] TCP port; `0` lets the OS pick one, readable
  *   from `port` after `listen()`.
  * @property {string} [path] WebSocket path clients connect to.
- * @property {number} [timeout] Milliseconds of silence after which a
- *   socket is considered gone.
  * @property {number} [maxMessageSize] Max size of a single incoming
  *   message, in megabytes.
  * @property {boolean} [skipUTF8Validation] Skip `ws`'s UTF-8 validation
@@ -83,7 +82,6 @@ const DEFAULT_WATCH_DEBOUNCE_MS = 1000
  * @property {() => void} [listen]
  * @property {(socket: Socket, request: ConnectRequest) => void} [connect]
  * @property {(socket: Socket, code: number, reason: string) => void} [disconnect]
- * @property {(socket: Socket) => void} [ping]
  * @property {(socket: Socket, delay: number) => void} [timeout]
  * @property {(socket: Socket, data: any) => void} [garbage]
  * @property {(socket: Socket, messages: any[]) => void} [incoming]
@@ -160,6 +158,13 @@ export class Server extends Emitter {
 	 * @type {Socket[]}
 	 */
 	drained = []
+	/**
+	 * Class of the sockets it creates; set it before `listen` to have each
+	 * connection be a subclass of `Socket`.
+	 *
+	 * @type {typeof Socket}
+	 */
+	SocketClass = Socket
 	/** @internal */
 	cacheSymbol = Symbol('cache')
 	/** @internal */
@@ -180,7 +185,6 @@ export class Server extends Emitter {
 		this.port = DEFAULT_PORT
 		this.path = DEFAULT_PATH
 
-		this.timeout = DEFAULT_TIMEOUT_MS
 
 		this.maxMessageSize = DEFAULT_MAX_MESSAGE_SIZE_MB
 
@@ -264,10 +268,6 @@ export class Server extends Emitter {
 
 		this.path = options.path || this.path
 
-		const timeout = +(options.timeout ?? 0)
-		this.timeout =
-			timeout >= MIN_TIMEOUT_MS ? timeout : DEFAULT_TIMEOUT_MS
-
 		const maxMessageSize = +(options.maxMessageSize ?? 0)
 		this.maxMessageSize =
 			maxMessageSize > 0 ? maxMessageSize : DEFAULT_MAX_MESSAGE_SIZE_MB
@@ -323,7 +323,7 @@ export class Server extends Emitter {
 		this.since = this.now
 
 		// `unref` so a stopped server doesn't hold the process alive.
-		this.#pingTimer = setInterval(this.ping, this.timeout / 2)
+		this.#pingTimer = setInterval(this.sweep, TIMEOUT_MS / 2)
 		this.#pingTimer.unref()
 
 		this.#nowTimer = setInterval(this.#updateNow, 500)
@@ -488,7 +488,7 @@ export class Server extends Emitter {
 	#onconnection = (io, request) => {
 		// URL-packed messages come off the params before `connect` sees them.
 		const [query, m] = params(request.url, PACKED_PARAM)
-		const socket = new Socket(io, request, this, query)
+		const socket = new this.SocketClass(io, request, this, query)
 
 		socket.listen()
 
@@ -511,8 +511,6 @@ export class Server extends Emitter {
 			else socket.garbage(m)
 		}
 
-		// ping on connect is usually high
-		setTimeout(() => this.#pingSocket(socket), 200).unref()
 	}
 
 	#onerror = err => {
@@ -550,91 +548,62 @@ export class Server extends Emitter {
 	}
 
 	/**
-	 * Cache the framed form of `messages` keyed by message identity, so a
-	 * fan-out stringifies and frames once per tick. Byte counters are
-	 * bumped in `Socket.write`.
+	 * The frame of `messages`. Each message stringifies once however many
+	 * batches it lands in, and a batch frames once per tick. Byte counters
+	 * are bumped in `Socket.write`.
 	 *
 	 * @internal Called from Socket.processQueue.
 	 * @param {any[]} messages
 	 * @returns {Buffer[]}
 	 */
 	cacheMessages(messages) {
-		// A fan-out is usually one message: key on it and skip the string.
-		let key = messages.length === 1 ? messages[0] : ''
-		if (key === '') {
-			for (const m of messages) {
-				if (!m[this.cacheSymbol]) {
-					m[this.cacheSymbol] = this.cached++
-				}
-				key += m[this.cacheSymbol] + ','
+		// A fan-out is usually one message: its frame lives on it, for as long as it does.
+		if (messages.length === 1) {
+			const m = messages[0]
+			if (m[framed]) {
+				this.messagesSentCacheHit++
+			} else {
+				m[framed] = frame(`[${m[encoded] ??= stringify(m)}]`)
+			}
+			return m[framed]
+		}
+		let key = ''
+		for (const m of messages) {
+			if (!m[this.cacheSymbol]) {
+				m[this.cacheSymbol] = this.cached++
 			}
+			key += m[this.cacheSymbol] + ','
 		}
-		let framed = this.cache.get(key)
-		if (framed) {
+		let batch = this.cache.get(key)
+		if (batch) {
 			this.messagesSentCacheHit++
 		} else {
-			framed = frame(stringify(messages))
-			this.cache.set(key, framed)
+			batch = frame(`[${messages.map(m => (m[encoded] ??= stringify(m))).join()}]`)
+			this.cache.set(key, batch)
 		}
-		return framed
-	}
-
-	// ping. Only `ping` is public so tests can drive the heartbeat
-	// sweep manually; the rest is internal.
-
-	/**
-	 * @internal Sockets silent for longer than this get pinged. The sweep runs every
-	 * `timeout / 2`; the margin makes sure a socket seen just after one
-	 * sweep is still pinged before the next one times it out.
-	 */
-	get timeoutCheck() {
-		return this.timeout / 2 - 5000
+		return batch
 	}
 
 	#updateNow = () => {
 		this.now = now()
 	}
 
-	/** @internal The heartbeat sweep; public so tests can run it. */
-	ping = () => {
+	/** @internal Drops sockets gone silent; public so tests can run it. */
+	sweep = () => {
 		this.#updateNow()
-		const check = this.timeoutCheck
 		for (const socket of this.sockets) {
 			const delay = this.now - socket.seen
 
-			if (delay > this.timeout) {
+			if (delay > TIMEOUT_MS) {
 				socket.timedout = true
 				this.hooks.timeout?.(socket, delay)
 				socket.io.terminate()
 				// Clean up now, as `disconnect()` does, not on the close event.
 				socket.onclose(ABNORMAL_CLOSURE, '')
-			} else if (delay > check) {
-				// `now` was just updated for the whole sweep.
-				socket.contacted = this.now
-				socket.write(PING)
 			}
 		}
 	}
 
-	/** @param {Socket} socket */
-	#pingSocket(socket) {
-		this.#updateNow()
-		socket.contacted = this.now
-		socket.write(PING)
-	}
-
-	/**
-	 * @internal Called from Socket.onmessage on heartbeat receipt.
-	 * @param {Socket} socket
-	 */
-	pong(socket) {
-		this.#updateNow()
-		socket.seen = this.now
-		socket.ping = this.now - socket.contacted
-
-		this.hooks.ping?.(socket)
-	}
-
 	/** `await using server = …` stops the server when the scope ends. */
 	[Symbol.asyncDispose]() {
 		return this.stop()
@@ -688,7 +657,6 @@ export class Server extends Emitter {
 			sockets: this.sockets.size,
 			served: this.served,
 			since: this.since,
-			timeout: this.timeout,
 			bytesSent: this.bytesSent,
 			bytesReceived: this.bytesReceived,
 			messagesSent: this.messagesSent,

package/server/Socket.js

@@ -1,4 +1,3 @@
-import { parent } from './constants.js'
 import {
 	NO_RECONNECT,
 	PROTOCOL_KEY,
@@ -16,10 +15,13 @@ import {
 import { WebSocket } from 'ws'
 
 /** @import { ClientEvents, ClientReplies, EventKey, EventValue } from './index.js' */
+/** @import { Message } from './Message.js' */
 /** @import { Room } from './Room.js' */
 /** @import { Server } from './Server.js' */
 
 const DISCONNECT = frame(stringify([[PROTOCOL_KEY, NO_RECONNECT]]))
+// The answer to a client's heartbeat, an empty message: frame once, reuse forever.
+const PONG = frame('')
 
 // Rejection message for replies the client can no longer send.
 const DISCONNECTED = 'disconnected: the socket closed before the client replied'
@@ -35,9 +37,6 @@ export class Socket {
 	/** Last callback id handed out; ids start at 1, as 0 means "none". */
 	#lastCallbackId = 0
 
-	/** @internal When the last ping was sent, to time the pong. */
-	contacted = 0
-
 	/**
 	 * @internal Messages waiting for the next batch.
 	 * @type {any[]}
@@ -78,9 +77,7 @@ export class Socket {
 
 		this.since = server.now
 		this.seen = server.now
-		this.contacted = server.now
 
-		this.ping = 0
 		this.timedout = false
 		this.closed = false
 
@@ -123,6 +120,15 @@ export class Socket {
 		this.queue([k, v])
 	}
 
+	/**
+	 * Queue an encoded message for the next batch.
+	 *
+	 * @param {Message<any>} message
+	 */
+	send(message) {
+		this.queue(message.tuple)
+	}
+
 	/**
 	 * @internal Queue a wire tuple; fan-outs pass one tuple to every
 	 * recipient so `Server.cacheMessages` encodes it once.
@@ -190,11 +196,11 @@ export class Socket {
 
 	/** @internal @param {Buffer} raw */
 	onmessage = raw => {
+		this.seen = this.server.now
 		if (raw.length === 0) {
-			this.server.pong(this)
+			this.write(PONG)
 			return
 		}
-		this.seen = this.server.now
 
 		this.server.bytesReceived += raw.length
 		this.bytesReceived += raw.length
@@ -227,9 +233,7 @@ export class Socket {
 
 		// Leaving deletes the room from this.rooms; Set iteration allows that.
 		for (const room of this.rooms) {
-			room[parent]
-				? room[parent].leave(this, room.id)
-				: room.leave(this)
+			room.leave(this)
 		}
 
 		this.server.hooks.disconnect?.(this, code, reason.toString())
@@ -379,6 +383,7 @@ export class Socket {
 		this.io._sender.sendFrame(chunks)
 	}
 
+	/** @returns {any} What sending a socket sends; a subclass says what. */
 	toJSON() {
 		return '[content of socket object omitted for toJSON]'
 	}
@@ -397,7 +402,6 @@ export class Socket {
 			params: this.params,
 			closed: this.closed,
 			timedout: this.timedout,
-			ping: this.ping,
 			since: this.since,
 			seen: this.seen,
 			rooms: [...this.rooms].map(room => room.id),

package/server/constants.js

@@ -1,11 +1,13 @@
 export const parent = Symbol('parent')
+// A wire tuple's JSON, and its frame as a batch of one.
+export const encoded = Symbol('encoded')
+export const framed = Symbol('framed')
 
 // Server events fired by the library itself; clients can't trigger them.
 export const LIFECYCLE_EVENTS = new Set([
 	'listen',
 	'connect',
 	'disconnect',
-	'ping',
 	'timeout',
 	'garbage',
 	'incoming',
@@ -14,9 +16,7 @@ export const LIFECYCLE_EVENTS = new Set([
 
 // Server defaults
 export const DEFAULT_PORT = 3001
-export const DEFAULT_TIMEOUT_MS = 60_000
 export const DEFAULT_MAX_MESSAGE_SIZE_MB = 5
 
 // Server bounds
-export const MIN_TIMEOUT_MS = 10_000
 export const MAX_PORT = 65535

package/server/index.js

@@ -1,3 +1,6 @@
 export { default, Server } from './Server.js'
+export { Emitter } from './Emitter.js'
+export { Message } from './Message.js'
 export { Room } from './Room.js'
 export { Rooms } from './Rooms.js'
+export { Socket } from './Socket.js'

package/shared/protocol.js

@@ -15,6 +15,9 @@ export const PROTOCOL_KEY = ''
 /** Command telling the client to close and not reconnect. */
 export const NO_RECONNECT = 'disconnect'
 
+/** Milliseconds of silence after which a connection counts as gone. */
+export const TIMEOUT_MS = 60_000
+
 /** WebSocket close frames carry at most this many bytes of reason. */
 const MAX_CLOSE_REASON_BYTES = 123
 

package/types/client/transport.d.ts

@@ -1,6 +1,6 @@
 /**
  * The Client's socket lives in a Web Worker, so the browser's own
- * send/receive work (expensive in Chromium) and the heartbeat reply stay
+ * send/receive work (expensive in Chromium) and the heartbeat stay
  * off the main thread (see `bench/browser`). Only strings cross
  * `postMessage`; everything else stays in Client.
  *

package/types/server/Emitter.d.ts

@@ -1,23 +1,17 @@
 /** @import { ClientEvents, EventKey, EventValue } from './index.js' */
+/** @import { Message } from './Message.js' */
 /** @import { Socket } from './Socket.js' */
 import type { ClientEvents, EventKey, EventValue } from './index.js';
+import type { Message } from './Message.js';
 import type { Socket } from './Socket.js';
 export type HasSockets = {
     sockets: Iterable<Socket>;
-    broadcast(me: Socket | undefined, k: any, v?: any): void;
 };
-/**
- * @typedef {{
- * 	sockets: Iterable<Socket>
- * 	broadcast(me: Socket | undefined, k: any, v?: any): void
- * }} HasSockets
- */
 /**
  * Common emit / broadcast logic. Subclasses own the `sockets` field
- * (a Set on Server, Room and Rooms). Each fan-out builds the wire tuple
- * **once** and passes the same reference to every recipient —
- * `Server.cacheMessages` keys the encoded form by message identity, so
- * all sockets share a single encoding.
+ * (a Set on Server, Room and Rooms). Each fan-out queues **one** wire
+ * tuple on every recipient, and `Server.cacheMessages` keeps the encoded
+ * form on it, so all sockets share a single encoding.
  */
 export declare class Emitter {
     /**
@@ -39,4 +33,19 @@ export declare class Emitter {
      * @param {EventValue<ClientEvents, K>} v
      */
     broadcast<K extends EventKey<ClientEvents>>(this: HasSockets, me: Socket | undefined, k: K, v: EventValue<ClientEvents, K>): void;
+    /**
+     * Send an encoded message to every socket in scope.
+     *
+     * @this {HasSockets}
+     * @param {Message<any>} message
+     */
+    send(this: HasSockets, message: Message<any>): void;
+    /**
+     * Send an encoded message to every socket in scope except `me`.
+     *
+     * @this {HasSockets}
+     * @param {Socket | undefined} me
+     * @param {Message<any>} message
+     */
+    sendExcept(this: HasSockets, me: Socket | undefined, message: Message<any>): void;
 }

package/types/server/Message.d.ts

@@ -0,0 +1,22 @@
+import type { ClientEvents, EventKey, EventValue } from './index.js';
+/** @import { ClientEvents, EventKey, EventValue } from './index.js' */
+/**
+ * A message encoded once, here, to send to any socket at any time with
+ * `send` / `sendExcept`. Later changes to `v` don't reach the wire.
+ *
+ * @template {EventKey<ClientEvents>} K
+ */
+export declare class Message<K extends EventKey<ClientEvents>> {
+    /**
+     * @internal The wire tuple every send queues.
+     * @type {any[]}
+     */
+    tuple: any[];
+    /** The encoded text; equal text means an equal message. */
+    json: string;
+    /**
+     * @param {K} k
+     * @param {EventValue<ClientEvents, K>} v
+     */
+    constructor(k: K, v: EventValue<ClientEvents, K>);
+}

package/types/server/Room.d.ts

@@ -5,13 +5,15 @@ import type { Socket } from './Socket.js';
 /** @import { Rooms } from './Rooms.js' */
 /** A group of sockets to emit to; subclass it to hook its lifecycle. */
 export declare class Room extends Emitter {
-    /** @type {Set<Socket>} */
-    sockets: Set<Socket>;
+    #private;
     /** @type {any} Set by `Rooms` for its rooms; yours to set otherwise. */
     id: any;
-    /** Keep the room in its `Rooms` list when its last socket leaves. */
-    persistent: boolean;
     [parent]: any;
+    /**
+     * Off the room's own fields, as a subclass may spread its fields into
+     * what it sends.
+     */
+    get sockets(): Set<Socket>;
     /**
      * Called when a `Rooms` list creates the room for `socket`.
      *
@@ -30,6 +32,11 @@ export declare class Room extends Emitter {
     onLeave(socket: Socket): void;
     /** @param {Socket} socket */
     join(socket: Socket): void;
-    /** @param {Socket} socket */
+    /**
+     * Leave the room; a room in a `Rooms` list that this empties is deleted
+     * unless it's `persistent`.
+     *
+     * @param {Socket} socket
+     */
     leave(socket: Socket): void;
 }

package/types/server/Rooms.d.ts

@@ -42,6 +42,14 @@ export declare class Rooms<R extends Room = Room> extends Emitter {
      * @param {any} [id]
      */
     leave(socket: Socket, id?: any): void;
+    /**
+     * The rooms of this list `socket` is in. Walks the socket's own rooms,
+     * which stay few, not the list's. Leaving one while iterating is fine.
+     *
+     * @param {Socket} socket
+     * @returns {Generator<R>}
+     */
+    of(socket: Socket): Generator<R>;
     /** @returns {R[]} */
     toJSON(): R[];
 }

package/types/server/Server.d.ts

@@ -17,11 +17,6 @@ export type ServerListenOptions = {
      * WebSocket path clients connect to.
      */
     path?: string;
-    /**
-     * Milliseconds of silence after which a
-     * socket is considered gone.
-     */
-    timeout?: number;
     /**
      * Max size of a single incoming
      * message, in megabytes.
@@ -66,7 +61,6 @@ export type PredefinedServerHandlers = {
     listen?: () => void;
     connect?: (socket: Socket, request: ConnectRequest) => void;
     disconnect?: (socket: Socket, code: number, reason: string) => void;
-    ping?: (socket: Socket) => void;
     timeout?: (socket: Socket, delay: number) => void;
     garbage?: (socket: Socket, data: any) => void;
     incoming?: (socket: Socket, messages: any[]) => void;
@@ -87,7 +81,6 @@ export declare class Server extends Emitter {
     hostname: string;
     port: number;
     path: string;
-    timeout: number;
     maxMessageSize: number;
     /**
      * When true, read `x-forwarded-for` from the upgrade headers for
@@ -122,6 +115,13 @@ export declare class Server extends Emitter {
     io: WebSocketServer | null;
     /** @type {import('node:http').Server | null} */
     httpServer: import('node:http').Server | null;
+    /**
+     * Class of the sockets it creates; set it before `listen` to have each
+     * connection be a subclass of `Socket`.
+     *
+     * @type {typeof Socket}
+     */
+    SocketClass: typeof Socket;
     constructor();
     /**
      * Start listening for WebSocket connections. Serves `wss://` when

package/types/server/Socket.d.ts

@@ -1,6 +1,7 @@
 import { inspect } from './utils.js';
 import { WebSocket } from 'ws';
 import type { ClientEvents, ClientReplies, EventKey, EventValue } from './index.js';
+import type { Message } from './Message.js';
 import type { Room } from './Room.js';
 import type { Server } from './Server.js';
 /** One client connection, handed to every event handler and hook. */
@@ -20,7 +21,6 @@ export declare class Socket {
     messagesReceived: number;
     since: number;
     seen: number;
-    ping: number;
     timedout: boolean;
     closed: boolean;
     /** @type {Set<Room>} The rooms this socket is in. */
@@ -79,6 +79,12 @@ export declare class Socket {
      * @returns {Promise<any> | void}
      */
     emit<K extends EventKey<ClientEvents>, R>(k: K, v: EventValue<ClientEvents, K>, callback: (reply: EventValue<ClientReplies, K>) => R): Promise<R>;
+    /**
+     * Queue an encoded message for the next batch.
+     *
+     * @param {Message<any>} message
+     */
+    send(message: Message<any>): void;
     /**
      * Emit and resolve with the client's reply; rejected with
      * a `disconnected:` Error if the socket closes first.
@@ -132,7 +138,8 @@ export declare class Socket {
      *   123 bytes; longer throws a `RangeError` before anything closes.
      */
     disconnect(noReconnect?: boolean, reason?: string): void;
-    toJSON(): string;
+    /** @returns {any} What sending a socket sends; a subclass says what. */
+    toJSON(): any;
     /**
      * `console.log(socket)` shows who it is and how it's doing, not internals.
      *

package/types/server/constants.d.ts

@@ -1,7 +1,7 @@
 export declare const parent: unique symbol;
+export declare const encoded: unique symbol;
+export declare const framed: unique symbol;
 export declare const LIFECYCLE_EVENTS: Set<string>;
 export declare const DEFAULT_PORT = 3001;
-export declare const DEFAULT_TIMEOUT_MS = 60000;
 export declare const DEFAULT_MAX_MESSAGE_SIZE_MB = 5;
-export declare const MIN_TIMEOUT_MS = 10000;
 export declare const MAX_PORT = 65535;

package/types/server/index.d.ts

@@ -1,7 +1,16 @@
 export { default, Server } from './Server.js'
+export { Emitter } from './Emitter.js'
+export { Message } from './Message.js'
 export { Room } from './Room.js'
 export { Rooms } from './Rooms.js'
-export type { Socket } from './Socket.js'
+export { Socket } from './Socket.js'
+
+declare module './Room.js' {
+	interface Room {
+		/** Keep the room in its `Rooms` list when its last socket leaves. */
+		persistent: boolean
+	}
+}
 
 /**
  * Event-map interfaces. Augment these from your app to get end-to-end

package/types/shared/protocol.d.ts

@@ -9,6 +9,8 @@ export declare const PACKED_PARAM = "m";
 export declare const PROTOCOL_KEY = "";
 /** Command telling the client to close and not reconnect. */
 export declare const NO_RECONNECT = "disconnect";
+/** Milliseconds of silence after which a connection counts as gone. */
+export declare const TIMEOUT_MS = 60000;
 /**
  * Throw before closing with a reason the WebSocket would reject, so a
  * bad reason fails with nothing half done.