angelia.io 5.0.0 → 5.0.1

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.1",
 	"description": "WebSockets Server and Client API for node.js and the browser, with rooms support.",
 	"author": "@titoBouzout @boredofnames",
 	"license": "GPL",

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                                                        |
@@ -149,7 +147,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                                                                                                                                                                                                  |
@@ -236,7 +233,6 @@ 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                                                         |
@@ -267,7 +263,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 +318,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

package/server/Server.js

@@ -12,12 +12,14 @@ import {
 import {
 	DEFAULT_MAX_MESSAGE_SIZE_MB,
 	DEFAULT_PORT,
-	DEFAULT_TIMEOUT_MS,
 	LIFECYCLE_EVENTS,
 	MAX_PORT,
-	MIN_TIMEOUT_MS,
 } 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 +33,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 +49,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 +80,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]
@@ -180,7 +176,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 +259,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 +314,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)
@@ -511,8 +502,6 @@ export class Server extends Emitter {
 			else socket.garbage(m)
 		}
 
-		// ping on connect is usually high
-		setTimeout(() => this.#pingSocket(socket), 200).unref()
 	}
 
 	#onerror = err => {
@@ -579,62 +568,26 @@ export class Server extends Emitter {
 		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
-	}
-
 	#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 +641,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

@@ -20,6 +20,8 @@ import { WebSocket } from 'ws'
 /** @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
 
@@ -190,11 +187,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
@@ -397,7 +394,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

@@ -5,7 +5,6 @@ export const LIFECYCLE_EVENTS = new Set([
 	'listen',
 	'connect',
 	'disconnect',
-	'ping',
 	'timeout',
 	'garbage',
 	'incoming',
@@ -14,9 +13,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/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/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

package/types/server/Socket.d.ts

@@ -20,7 +20,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. */

package/types/server/constants.d.ts

@@ -1,7 +1,5 @@
 export declare const parent: 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/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.