react-websocket 3.6.0 → 4.0.0

package/README.md

@@ -12,7 +12,7 @@
 **[Documentation](https://mehmetkose.github.io/react-websocket/)** · [Getting started](https://mehmetkose.github.io/react-websocket/guide/getting-started) · [API](https://mehmetkose.github.io/react-websocket/api/) · [Recipes](https://mehmetkose.github.io/react-websocket/recipes) · [Changelog](CHANGELOG.md)
 
 - **Shared connections.** Components using the same URL share one socket. StrictMode, `<Activity>` and route transitions never open duplicates.
-- **Auto-reconnect.** Exponential backoff with jitter, plus an immediate retry when the browser comes back online or the tab becomes visible. Optional heartbeats detect dead links.
+- **Auto-reconnect.** Exponential backoff with full jitter, plus an immediate retry when the browser comes back online or the tab becomes visible. It backs off from a server that closes right after accepting, and stops on close codes that retrying can't fix. Optional heartbeats detect dead links.
 - **Send queue.** `send()` before the socket is open just works. The message goes out on connect. Mark input `volatile` so it's never replayed late, or `key` it so only the newest is sent. Put control messages first with `priority`, and drop stream data on a slow link with `maxBuffered`.
 - **Typed messages.** `json: true`, your own codec, or validation with any [Standard Schema](https://standardschema.dev) library (zod, valibot, arktype), with inferred types.
 - **Suspense.** `use(client.ready)` waits for the first connection, and reconnects never flash a fallback.
@@ -126,6 +126,7 @@ function Room() {
 | `createWebSocketSendRate(client, options?)` | `send(message, key)` coalesced per key at a rate that drops on a congested link |
 | `createWebSocketResponder(client, { request, respond, error })` | Answer the server's requests: `onRequest(method, handler)`, or a person through `useAgentApproval` |
 | `MessageError` | Reported to `onError` when a message fails `parse` or `schema` |
+| `retryableClose(close)` | The default `reconnect.shouldReconnect`: retries every close except `1002`, `1003` and `1008` |
 | `createWebSocketTimeline(client, { snapshot, interpolate, input })` | From `react-websocket/timeline`: interpolated server snapshots (`at()`) and predicted inputs (`predicted()`, `input()`) for multiplayer games |
 | `createChaosWebSocket(options)` | From `react-websocket/chaos`: a `WebSocket` class that adds latency, lost messages and dropped connections in development |
 
@@ -136,9 +137,9 @@ function Room() {
 | `json` | `false` | `JSON.parse` incoming and `JSON.stringify` outgoing messages |
 | `parse(data)` / `serialize(message)` | | Custom codec; takes precedence over `json` |
 | `schema` | | Standard Schema validation; types are inferred |
-| `reconnect` | `true` | `false`, or `{ maxAttempts, minDelay, maxDelay, factor, jitter, shouldReconnect }` |
+| `reconnect` | `true` | `false`, or `{ maxAttempts, minDelay, maxDelay, factor, jitter, minUptime, shouldReconnect }` |
 | `heartbeat` | | `{ interval, message, pong, timeout }` |
-| `queue` | `true` | `false`, or `{ limit }` |
+| `queue` | `true` (100 messages) | `false`, or `{ limit }` |
 | `logger` | | e.g. `console.debug` |
 | `WebSocket` | global | Custom implementation for tests, Node, or chaos testing |
 
@@ -149,7 +150,7 @@ function Room() {
 - [Shared clients](https://mehmetkose.github.io/react-websocket/guide/shared-clients) · [Messages and types](https://mehmetkose.github.io/react-websocket/guide/messages) · [Reconnecting and heartbeats](https://mehmetkose.github.io/react-websocket/guide/reconnecting)
 - [Suspense](https://mehmetkose.github.io/react-websocket/guide/suspense) · [Server rendering and Next.js](https://mehmetkose.github.io/react-websocket/guide/ssr) · [StrictMode, Activity and lifecycle](https://mehmetkose.github.io/react-websocket/guide/lifecycle)
 - [Authentication](https://mehmetkose.github.io/react-websocket/guide/authentication) · [Performance](https://mehmetkose.github.io/react-websocket/guide/performance) · [Real-time games](https://mehmetkose.github.io/react-websocket/guide/games) · [AI agents](https://mehmetkose.github.io/react-websocket/guide/agents) · [Testing](https://mehmetkose.github.io/react-websocket/guide/testing) · [Chaos testing](https://mehmetkose.github.io/react-websocket/guide/chaos) · [Without React](https://mehmetkose.github.io/react-websocket/guide/without-react)
-- [Recipes](https://mehmetkose.github.io/react-websocket/recipes) · [Troubleshooting](https://mehmetkose.github.io/react-websocket/troubleshooting) · [Migrating from v2](https://mehmetkose.github.io/react-websocket/migration)
+- [Recipes](https://mehmetkose.github.io/react-websocket/recipes) · [Troubleshooting](https://mehmetkose.github.io/react-websocket/troubleshooting) · [Migrating from v3](https://mehmetkose.github.io/react-websocket/migration-v3) · [Migrating from v2](https://mehmetkose.github.io/react-websocket/migration)
 
 The docs source lives in [`docs/`](docs). Run `npm run docs:dev` to browse it locally.
 
@@ -161,6 +162,10 @@ The docs source lives in [`docs/`](docs). Run `npm run docs:dev` to browse it lo
 | Runtimes | Modern browsers; Node via the `WebSocket` option |
 | Frameworks | Vite, Next.js (App and Pages Router), Remix/React Router, Astro islands, and any React setup |
 
+## Migrating from v3
+
+v4 changes no APIs, only four defaults: the backoff resets once a connection has stayed open for 5 seconds, close codes `1002`, `1003` and `1008` aren't retried, jitter is full, and the send queue holds 100 messages. Each has a one-line opt-out. See [Migrating from v3](https://mehmetkose.github.io/react-websocket/migration-v3).
+
 ## Migrating from v2
 
 v2 was a `<Websocket>` class component. v3 replaces it with hooks: `<Websocket url onMessage />` becomes `useWebSocket(url, { onMessage })`, and `ref.sendMessage(msg)` becomes `send(msg)`. See the [migration guide](https://mehmetkose.github.io/react-websocket/migration) for the full mapping.

package/dist/core.cjs

@@ -31,8 +31,26 @@ const RECONNECT_DEFAULTS = {
 	minDelay: 1e3,
 	maxDelay: 3e4,
 	factor: 2,
-	jitter: .5
+	jitter: 1,
+	minUptime: 5e3
 };
+const QUEUE_LIMIT = 100;
+/**
+* The default `reconnect.shouldReconnect`: retry every close except `1002` (protocol error),
+* `1003` (unsupported data) and `1008` (policy violation, often a rejected login), which
+* retrying the same way can't fix. Call it from your own `shouldReconnect` to keep that rule.
+*
+* @example
+* ```ts
+* createWebSocket(url, {
+*   // Also stop on our server's "invalid token" code.
+*   reconnect: { shouldReconnect: close => close.code !== 4001 && retryableClose(close) }
+* });
+* ```
+*/
+function retryableClose(close) {
+	return close.code !== 1002 && close.code !== 1003 && close.code !== 1008;
+}
 const READY_GRACE = 5e3;
 function createDeferred() {
 	let resolve;
@@ -84,7 +102,7 @@ function createClient(url, options = {}) {
 		...RECONNECT_DEFAULTS,
 		...typeof options.reconnect === "object" ? options.reconnect : {}
 	};
-	const queueLimit = options.queue === false ? 0 : typeof options.queue === "object" ? Math.max(0, options.queue.limit ?? Infinity) : Infinity;
+	const queueLimit = options.queue === false ? 0 : Math.max(0, (typeof options.queue === "object" ? options.queue.limit : void 0) ?? QUEUE_LIMIT);
 	let snapshot = {
 		status: "idle",
 		lastMessage: void 0,
@@ -109,8 +127,10 @@ function createClient(url, options = {}) {
 	let inbox = null;
 	let generation = 0;
 	let windowBound = false;
+	let failures = 0;
 	let retryTimer;
 	let teardownTimer;
+	let stableTimer;
 	let heartbeatTimer;
 	let pongTimer;
 	function set(patch) {
@@ -177,10 +197,12 @@ function createClient(url, options = {}) {
 			}, heartbeat.timeout);
 		}, heartbeat.interval);
 	}
-	function stopHeartbeat() {
+	/** Stop the timers that belong to the current open socket. */
+	function stopSocketTimers() {
 		clearInterval(heartbeatTimer);
 		clearTimeout(pongTimer);
-		heartbeatTimer = pongTimer = void 0;
+		clearTimeout(stableTimer);
+		heartbeatTimer = pongTimer = stableTimer = void 0;
 	}
 	/** Stop tracking `socket`. Its eventual close event is still reported unless `reportClose` is false. */
 	function detach(socket, reportClose) {
@@ -251,6 +273,7 @@ function createClient(url, options = {}) {
 				status: "open",
 				attempt: 0
 			});
+			if (retry) stableTimer = setTimeout(() => failures = 0, retry.minUptime);
 			startHeartbeat(socket);
 			ready?.resolve();
 			if (refs === 0 && !pinned) {
@@ -275,14 +298,14 @@ function createClient(url, options = {}) {
 		};
 	}
 	function handleClose(info) {
-		stopHeartbeat();
+		stopSocketTimers();
 		log("closed", info);
 		retryOrFail(info);
 		emit("close", info);
 	}
 	function retryOrFail(info, error) {
-		if (wanted && retry && snapshot.attempt < retry.maxAttempts && (retry.shouldReconnect?.(info) ?? true)) {
-			const attempt = snapshot.attempt + 1;
+		if (wanted && retry && failures < retry.maxAttempts && (retry.shouldReconnect ?? retryableClose)(info)) {
+			const attempt = ++failures;
 			const delay = backoff(attempt);
 			set({
 				status: "reconnecting",
@@ -297,7 +320,10 @@ function createClient(url, options = {}) {
 		opened = false;
 		unbindWindow();
 		pending = [];
-		set({ status: "closed" });
+		set({
+			status: "closed",
+			attempt: failures
+		});
 		rejectReady(reason);
 	}
 	function receive(event, socket) {
@@ -402,6 +428,7 @@ function createClient(url, options = {}) {
 			opened = false;
 			if (ready?.settled) ready = null;
 		}
+		failures = 0;
 		snapshot = {
 			...snapshot,
 			attempt: 0
@@ -423,7 +450,8 @@ function createClient(url, options = {}) {
 		generation++;
 		clearTimeout(retryTimer);
 		retryTimer = void 0;
-		stopHeartbeat();
+		failures = 0;
+		stopSocketTimers();
 		unbindWindow();
 		pending = [];
 		if (ws) {
@@ -446,7 +474,7 @@ function createClient(url, options = {}) {
 		if (!getImpl()) return;
 		clearTimeout(retryTimer);
 		retryTimer = void 0;
-		stopHeartbeat();
+		stopSocketTimers();
 		if (ws) {
 			const socket = ws;
 			detach(socket, true);
@@ -1232,5 +1260,6 @@ exports.createWebSocketResponder = createWebSocketResponder;
 exports.createWebSocketSendRate = createWebSocketSendRate;
 exports.createWebSocketState = createWebSocketState;
 exports.createWebSocketTopics = createWebSocketTopics;
+exports.retryableClose = retryableClose;
 
 //# sourceMappingURL=core.cjs.map