@atproto/ws-client 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @atproto/ws-client
+
+## 0.0.2
+
+### Patch Changes
+
+- [#4348](https://github.com/bluesky-social/atproto/pull/4348) [`1dd20d3a8`](https://github.com/bluesky-social/atproto/commit/1dd20d3a81cda29392d8d63d13082254ec5f68a8) Thanks [@dholms](https://github.com/dholms)! - Move WebSocketKeepAlive into its own package

package/LICENSE.txt

@@ -0,0 +1,7 @@
+Dual MIT/Apache-2.0 License
+
+Copyright (c) 2022-2025 Bluesky Social PBC, and Contributors
+
+Except as otherwise noted in individual files, this software is licensed under the MIT license (<http://opensource.org/licenses/MIT>), or the Apache License, Version 2.0 (<http://www.apache.org/licenses/LICENSE-2.0>).
+
+Downstream projects and end users may chose either license individually, or both together, at their discretion. The motivation for this dual-licensing is the additional software patent assurance provided by Apache 2.0.

package/README.md

@@ -0,0 +1,15 @@
+# @atproto/ws-client: WebSocket Client Library
+
+Shared Typescript library for managing a long-lived WebSocket client connection, including a heartbeat mechanism to ensure the connection remains active.
+
+[![NPM](https://img.shields.io/npm/v/@atproto/ws-client)](https://www.npmjs.com/package/@atproto/ws-client)
+[![Github CI Status](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml/badge.svg)](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml)
+
+## License
+
+This project is dual-licensed under MIT and Apache 2.0 terms:
+
+- MIT license ([LICENSE-MIT.txt](https://github.com/bluesky-social/atproto/blob/main/LICENSE-MIT.txt) or http://opensource.org/licenses/MIT)
+- Apache License, Version 2.0, ([LICENSE-APACHE.txt](https://github.com/bluesky-social/atproto/blob/main/LICENSE-APACHE.txt) or http://www.apache.org/licenses/LICENSE-2.0)
+
+Downstream projects and end users may chose either license individually, or both together, at their discretion. The motivation for this dual-licensing is the additional software patent assurance provided by Apache 2.0.

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import { ClientOptions, WebSocket } from 'ws';
+export declare class WebSocketKeepAlive {
+    opts: ClientOptions & {
+        getUrl: () => Promise<string>;
+        maxReconnectSeconds?: number;
+        signal?: AbortSignal;
+        heartbeatIntervalMs?: number;
+        onReconnectError?: (error: unknown, n: number, initialSetup: boolean) => void;
+    };
+    ws: WebSocket | null;
+    initialSetup: boolean;
+    reconnects: number | null;
+    constructor(opts: ClientOptions & {
+        getUrl: () => Promise<string>;
+        maxReconnectSeconds?: number;
+        signal?: AbortSignal;
+        heartbeatIntervalMs?: number;
+        onReconnectError?: (error: unknown, n: number, initialSetup: boolean) => void;
+    });
+    [Symbol.asyncIterator](): AsyncGenerator<Uint8Array>;
+    startHeartbeat(ws: WebSocket): void;
+}
+export default WebSocketKeepAlive;
+export declare class DisconnectError extends Error {
+    wsCode: CloseCode;
+    xrpcCode?: string | undefined;
+    constructor(wsCode?: CloseCode, xrpcCode?: string | undefined);
+}
+export declare enum CloseCode {
+    Normal = 1000,
+    Abnormal = 1006,
+    Policy = 1008
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,SAAS,EAAyB,MAAM,IAAI,CAAA;AAGpE,qBAAa,kBAAkB;IAMpB,IAAI,EAAE,aAAa,GAAG;QAC3B,MAAM,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;QAC7B,mBAAmB,CAAC,EAAE,MAAM,CAAA;QAC5B,MAAM,CAAC,EAAE,WAAW,CAAA;QACpB,mBAAmB,CAAC,EAAE,MAAM,CAAA;QAC5B,gBAAgB,CAAC,EAAE,CACjB,KAAK,EAAE,OAAO,EACd,CAAC,EAAE,MAAM,EACT,YAAY,EAAE,OAAO,KAClB,IAAI,CAAA;KACV;IAfI,EAAE,EAAE,SAAS,GAAG,IAAI,CAAO;IAC3B,YAAY,UAAO;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAO;gBAG9B,IAAI,EAAE,aAAa,GAAG;QAC3B,MAAM,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;QAC7B,mBAAmB,CAAC,EAAE,MAAM,CAAA;QAC5B,MAAM,CAAC,EAAE,WAAW,CAAA;QACpB,mBAAmB,CAAC,EAAE,MAAM,CAAA;QAC5B,gBAAgB,CAAC,EAAE,CACjB,KAAK,EAAE,OAAO,EACd,CAAC,EAAE,MAAM,EACT,YAAY,EAAE,OAAO,KAClB,IAAI,CAAA;KACV;IAGI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,cAAc,CAAC,UAAU,CAAC;IA8D3D,cAAc,CAAC,EAAE,EAAE,SAAS;CA4B7B;AAED,eAAe,kBAAkB,CAAA;AAMjC,qBAAa,eAAgB,SAAQ,KAAK;IAE/B,MAAM,EAAE,SAAS;IACjB,QAAQ,CAAC,EAAE,MAAM;gBADjB,MAAM,GAAE,SAA4B,EACpC,QAAQ,CAAC,EAAE,MAAM,YAAA;CAI3B;AAGD,oBAAY,SAAS;IACnB,MAAM,OAAO;IACb,QAAQ,OAAO;IACf,MAAM,OAAO;CACd"}

package/dist/index.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CloseCode = exports.DisconnectError = exports.WebSocketKeepAlive = void 0;
+const ws_1 = require("ws");
+const common_1 = require("@atproto/common");
+class WebSocketKeepAlive {
+    constructor(opts) {
+        Object.defineProperty(this, "opts", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: opts
+        });
+        Object.defineProperty(this, "ws", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "initialSetup", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: true
+        });
+        Object.defineProperty(this, "reconnects", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+    }
+    async *[Symbol.asyncIterator]() {
+        const maxReconnectMs = 1000 * (this.opts.maxReconnectSeconds ?? 64);
+        while (true) {
+            if (this.reconnects !== null) {
+                const duration = this.initialSetup
+                    ? Math.min(1000, maxReconnectMs)
+                    : backoffMs(this.reconnects++, maxReconnectMs);
+                await (0, common_1.wait)(duration);
+            }
+            const url = await this.opts.getUrl();
+            this.ws = new ws_1.WebSocket(url, this.opts);
+            const ac = new AbortController();
+            if (this.opts.signal) {
+                forwardSignal(this.opts.signal, ac);
+            }
+            this.ws.once('open', () => {
+                this.initialSetup = false;
+                this.reconnects = 0;
+                if (this.ws) {
+                    this.startHeartbeat(this.ws);
+                }
+            });
+            this.ws.once('close', (code, reason) => {
+                if (code === CloseCode.Abnormal) {
+                    // Forward into an error to distinguish from a clean close
+                    ac.abort(new AbnormalCloseError(`Abnormal ws close: ${reason.toString()}`));
+                }
+            });
+            try {
+                const wsStream = (0, ws_1.createWebSocketStream)(this.ws, {
+                    signal: ac.signal,
+                    readableObjectMode: true, // Ensures frame bytes don't get buffered/combined together
+                });
+                for await (const chunk of wsStream) {
+                    yield chunk;
+                }
+            }
+            catch (_err) {
+                const err = (0, common_1.isErrnoException)(_err) && _err.code === 'ABORT_ERR'
+                    ? _err.cause
+                    : _err;
+                if (err instanceof DisconnectError) {
+                    // We cleanly end the connection
+                    this.ws?.close(err.wsCode);
+                    break;
+                }
+                this.ws?.close(); // No-ops if already closed or closing
+                if (isReconnectable(err)) {
+                    this.reconnects ?? (this.reconnects = 0); // Never reconnect with a null
+                    this.opts.onReconnectError?.(err, this.reconnects, this.initialSetup);
+                    continue;
+                }
+                else {
+                    throw err;
+                }
+            }
+            break; // Other side cleanly ended stream and disconnected
+        }
+    }
+    startHeartbeat(ws) {
+        let isAlive = true;
+        let heartbeatInterval = null;
+        const checkAlive = () => {
+            if (!isAlive) {
+                return ws.terminate();
+            }
+            isAlive = false; // expect websocket to no longer be alive unless we receive a "pong" within the interval
+            ws.ping();
+        };
+        checkAlive();
+        heartbeatInterval = setInterval(checkAlive, this.opts.heartbeatIntervalMs ?? 10 * common_1.SECOND);
+        ws.on('pong', () => {
+            isAlive = true;
+        });
+        ws.once('close', () => {
+            if (heartbeatInterval) {
+                clearInterval(heartbeatInterval);
+                heartbeatInterval = null;
+            }
+        });
+    }
+}
+exports.WebSocketKeepAlive = WebSocketKeepAlive;
+exports.default = WebSocketKeepAlive;
+class AbnormalCloseError extends Error {
+    constructor() {
+        super(...arguments);
+        Object.defineProperty(this, "code", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 'EWSABNORMALCLOSE'
+        });
+    }
+}
+class DisconnectError extends Error {
+    constructor(wsCode = CloseCode.Policy, xrpcCode) {
+        super();
+        Object.defineProperty(this, "wsCode", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: wsCode
+        });
+        Object.defineProperty(this, "xrpcCode", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: xrpcCode
+        });
+    }
+}
+exports.DisconnectError = DisconnectError;
+// https://www.rfc-editor.org/rfc/rfc6455#section-7.4.1
+var CloseCode;
+(function (CloseCode) {
+    CloseCode[CloseCode["Normal"] = 1000] = "Normal";
+    CloseCode[CloseCode["Abnormal"] = 1006] = "Abnormal";
+    CloseCode[CloseCode["Policy"] = 1008] = "Policy";
+})(CloseCode || (exports.CloseCode = CloseCode = {}));
+function isReconnectable(err) {
+    // Network errors are reconnectable.
+    // AuthenticationRequired and InvalidRequest XRPCErrors are not reconnectable.
+    // @TODO method-specific XRPCErrors may be reconnectable, need to consider. Receiving
+    // an invalid message is not current reconnectable, but the user can decide to skip them.
+    if ((0, common_1.isErrnoException)(err) && typeof err.code === 'string') {
+        return networkErrorCodes.includes(err.code);
+    }
+    return false;
+}
+const networkErrorCodes = [
+    'EWSABNORMALCLOSE',
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ECONNABORTED',
+    'EPIPE',
+    'ETIMEDOUT',
+    'ECANCELED',
+];
+function backoffMs(n, maxMs) {
+    const baseSec = Math.pow(2, n); // 1, 2, 4, ...
+    const randSec = Math.random() - 0.5; // Random jitter between -.5 and .5 seconds
+    const ms = 1000 * (baseSec + randSec);
+    return Math.min(ms, maxMs);
+}
+function forwardSignal(signal, ac) {
+    if (signal.aborted) {
+        return ac.abort(signal.reason);
+    }
+    else {
+        signal.addEventListener('abort', () => ac.abort(signal.reason), {
+            // @ts-ignore https://github.com/DefinitelyTyped/DefinitelyTyped/pull/68625
+            signal: ac.signal,
+        });
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["import { ClientOptions, WebSocket, createWebSocketStream } from 'ws'\nimport { SECOND, isErrnoException, wait } from '@atproto/common'\n\nexport class WebSocketKeepAlive {\n  public ws: WebSocket | null = null\n  public initialSetup = true\n  public reconnects: number | null = null\n\n  constructor(\n    public opts: ClientOptions & {\n      getUrl: () => Promise<string>\n      maxReconnectSeconds?: number\n      signal?: AbortSignal\n      heartbeatIntervalMs?: number\n      onReconnectError?: (\n        error: unknown,\n        n: number,\n        initialSetup: boolean,\n      ) => void\n    },\n  ) {}\n\n  async *[Symbol.asyncIterator](): AsyncGenerator<Uint8Array> {\n    const maxReconnectMs = 1000 * (this.opts.maxReconnectSeconds ?? 64)\n    while (true) {\n      if (this.reconnects !== null) {\n        const duration = this.initialSetup\n          ? Math.min(1000, maxReconnectMs)\n          : backoffMs(this.reconnects++, maxReconnectMs)\n        await wait(duration)\n      }\n      const url = await this.opts.getUrl()\n      this.ws = new WebSocket(url, this.opts)\n      const ac = new AbortController()\n      if (this.opts.signal) {\n        forwardSignal(this.opts.signal, ac)\n      }\n      this.ws.once('open', () => {\n        this.initialSetup = false\n        this.reconnects = 0\n        if (this.ws) {\n          this.startHeartbeat(this.ws)\n        }\n      })\n      this.ws.once('close', (code, reason) => {\n        if (code === CloseCode.Abnormal) {\n          // Forward into an error to distinguish from a clean close\n          ac.abort(\n            new AbnormalCloseError(`Abnormal ws close: ${reason.toString()}`),\n          )\n        }\n      })\n\n      try {\n        const wsStream = createWebSocketStream(this.ws, {\n          signal: ac.signal,\n          readableObjectMode: true, // Ensures frame bytes don't get buffered/combined together\n        })\n        for await (const chunk of wsStream) {\n          yield chunk\n        }\n      } catch (_err) {\n        const err =\n          isErrnoException(_err) && _err.code === 'ABORT_ERR'\n            ? _err.cause\n            : _err\n        if (err instanceof DisconnectError) {\n          // We cleanly end the connection\n          this.ws?.close(err.wsCode)\n          break\n        }\n        this.ws?.close() // No-ops if already closed or closing\n        if (isReconnectable(err)) {\n          this.reconnects ??= 0 // Never reconnect with a null\n          this.opts.onReconnectError?.(err, this.reconnects, this.initialSetup)\n          continue\n        } else {\n          throw err\n        }\n      }\n      break // Other side cleanly ended stream and disconnected\n    }\n  }\n\n  startHeartbeat(ws: WebSocket) {\n    let isAlive = true\n    let heartbeatInterval: NodeJS.Timeout | null = null\n\n    const checkAlive = () => {\n      if (!isAlive) {\n        return ws.terminate()\n      }\n      isAlive = false // expect websocket to no longer be alive unless we receive a \"pong\" within the interval\n      ws.ping()\n    }\n\n    checkAlive()\n    heartbeatInterval = setInterval(\n      checkAlive,\n      this.opts.heartbeatIntervalMs ?? 10 * SECOND,\n    )\n\n    ws.on('pong', () => {\n      isAlive = true\n    })\n    ws.once('close', () => {\n      if (heartbeatInterval) {\n        clearInterval(heartbeatInterval)\n        heartbeatInterval = null\n      }\n    })\n  }\n}\n\nexport default WebSocketKeepAlive\n\nclass AbnormalCloseError extends Error {\n  code = 'EWSABNORMALCLOSE'\n}\n\nexport class DisconnectError extends Error {\n  constructor(\n    public wsCode: CloseCode = CloseCode.Policy,\n    public xrpcCode?: string,\n  ) {\n    super()\n  }\n}\n\n// https://www.rfc-editor.org/rfc/rfc6455#section-7.4.1\nexport enum CloseCode {\n  Normal = 1000,\n  Abnormal = 1006,\n  Policy = 1008,\n}\n\nfunction isReconnectable(err: unknown): boolean {\n  // Network errors are reconnectable.\n  // AuthenticationRequired and InvalidRequest XRPCErrors are not reconnectable.\n  // @TODO method-specific XRPCErrors may be reconnectable, need to consider. Receiving\n  // an invalid message is not current reconnectable, but the user can decide to skip them.\n  if (isErrnoException(err) && typeof err.code === 'string') {\n    return networkErrorCodes.includes(err.code)\n  }\n  return false\n}\n\nconst networkErrorCodes = [\n  'EWSABNORMALCLOSE',\n  'ECONNRESET',\n  'ECONNREFUSED',\n  'ECONNABORTED',\n  'EPIPE',\n  'ETIMEDOUT',\n  'ECANCELED',\n]\n\nfunction backoffMs(n: number, maxMs: number) {\n  const baseSec = Math.pow(2, n) // 1, 2, 4, ...\n  const randSec = Math.random() - 0.5 // Random jitter between -.5 and .5 seconds\n  const ms = 1000 * (baseSec + randSec)\n  return Math.min(ms, maxMs)\n}\n\nfunction forwardSignal(signal: AbortSignal, ac: AbortController) {\n  if (signal.aborted) {\n    return ac.abort(signal.reason)\n  } else {\n    signal.addEventListener('abort', () => ac.abort(signal.reason), {\n      // @ts-ignore https://github.com/DefinitelyTyped/DefinitelyTyped/pull/68625\n      signal: ac.signal,\n    })\n  }\n}\n"]}

package/jest.config.js

@@ -0,0 +1,8 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  displayName: 'WebSocket Client',
+  transform: { '^.+\\.(j|t)s$': '@swc/jest' },
+  transformIgnorePatterns: ['/node_modules/.pnpm/(?!(get-port)@)'],
+  setupFiles: ['<rootDir>/../../jest.setup.ts'],
+  moduleNameMapper: { '^(\\.\\.?\\/.+)\\.js$': ['$1.ts', '$1.js'] },
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@atproto/ws-client",
+  "version": "0.0.2",
+  "license": "MIT",
+  "description": "Websocket client library",
+  "keywords": [
+    "atproto",
+    "xrpc"
+  ],
+  "homepage": "https://atproto.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bluesky-social/atproto",
+    "directory": "packages/ws-client"
+  },
+  "engines": {
+    "node": ">=18.7.0"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "ws": "^8.12.0",
+    "@atproto/common": "^0.4.12"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.4",
+    "get-port": "^6.1.2",
+    "jest": "^28.1.2",
+    "typescript": "^5.6.3"
+  },
+  "scripts": {
+    "test": "jest",
+    "build": "tsc --build tsconfig.build.json"
+  }
+}

package/src/index.ts

@@ -0,0 +1,174 @@
+import { ClientOptions, WebSocket, createWebSocketStream } from 'ws'
+import { SECOND, isErrnoException, wait } from '@atproto/common'
+
+export class WebSocketKeepAlive {
+  public ws: WebSocket | null = null
+  public initialSetup = true
+  public reconnects: number | null = null
+
+  constructor(
+    public opts: ClientOptions & {
+      getUrl: () => Promise<string>
+      maxReconnectSeconds?: number
+      signal?: AbortSignal
+      heartbeatIntervalMs?: number
+      onReconnectError?: (
+        error: unknown,
+        n: number,
+        initialSetup: boolean,
+      ) => void
+    },
+  ) {}
+
+  async *[Symbol.asyncIterator](): AsyncGenerator<Uint8Array> {
+    const maxReconnectMs = 1000 * (this.opts.maxReconnectSeconds ?? 64)
+    while (true) {
+      if (this.reconnects !== null) {
+        const duration = this.initialSetup
+          ? Math.min(1000, maxReconnectMs)
+          : backoffMs(this.reconnects++, maxReconnectMs)
+        await wait(duration)
+      }
+      const url = await this.opts.getUrl()
+      this.ws = new WebSocket(url, this.opts)
+      const ac = new AbortController()
+      if (this.opts.signal) {
+        forwardSignal(this.opts.signal, ac)
+      }
+      this.ws.once('open', () => {
+        this.initialSetup = false
+        this.reconnects = 0
+        if (this.ws) {
+          this.startHeartbeat(this.ws)
+        }
+      })
+      this.ws.once('close', (code, reason) => {
+        if (code === CloseCode.Abnormal) {
+          // Forward into an error to distinguish from a clean close
+          ac.abort(
+            new AbnormalCloseError(`Abnormal ws close: ${reason.toString()}`),
+          )
+        }
+      })
+
+      try {
+        const wsStream = createWebSocketStream(this.ws, {
+          signal: ac.signal,
+          readableObjectMode: true, // Ensures frame bytes don't get buffered/combined together
+        })
+        for await (const chunk of wsStream) {
+          yield chunk
+        }
+      } catch (_err) {
+        const err =
+          isErrnoException(_err) && _err.code === 'ABORT_ERR'
+            ? _err.cause
+            : _err
+        if (err instanceof DisconnectError) {
+          // We cleanly end the connection
+          this.ws?.close(err.wsCode)
+          break
+        }
+        this.ws?.close() // No-ops if already closed or closing
+        if (isReconnectable(err)) {
+          this.reconnects ??= 0 // Never reconnect with a null
+          this.opts.onReconnectError?.(err, this.reconnects, this.initialSetup)
+          continue
+        } else {
+          throw err
+        }
+      }
+      break // Other side cleanly ended stream and disconnected
+    }
+  }
+
+  startHeartbeat(ws: WebSocket) {
+    let isAlive = true
+    let heartbeatInterval: NodeJS.Timeout | null = null
+
+    const checkAlive = () => {
+      if (!isAlive) {
+        return ws.terminate()
+      }
+      isAlive = false // expect websocket to no longer be alive unless we receive a "pong" within the interval
+      ws.ping()
+    }
+
+    checkAlive()
+    heartbeatInterval = setInterval(
+      checkAlive,
+      this.opts.heartbeatIntervalMs ?? 10 * SECOND,
+    )
+
+    ws.on('pong', () => {
+      isAlive = true
+    })
+    ws.once('close', () => {
+      if (heartbeatInterval) {
+        clearInterval(heartbeatInterval)
+        heartbeatInterval = null
+      }
+    })
+  }
+}
+
+export default WebSocketKeepAlive
+
+class AbnormalCloseError extends Error {
+  code = 'EWSABNORMALCLOSE'
+}
+
+export class DisconnectError extends Error {
+  constructor(
+    public wsCode: CloseCode = CloseCode.Policy,
+    public xrpcCode?: string,
+  ) {
+    super()
+  }
+}
+
+// https://www.rfc-editor.org/rfc/rfc6455#section-7.4.1
+export enum CloseCode {
+  Normal = 1000,
+  Abnormal = 1006,
+  Policy = 1008,
+}
+
+function isReconnectable(err: unknown): boolean {
+  // Network errors are reconnectable.
+  // AuthenticationRequired and InvalidRequest XRPCErrors are not reconnectable.
+  // @TODO method-specific XRPCErrors may be reconnectable, need to consider. Receiving
+  // an invalid message is not current reconnectable, but the user can decide to skip them.
+  if (isErrnoException(err) && typeof err.code === 'string') {
+    return networkErrorCodes.includes(err.code)
+  }
+  return false
+}
+
+const networkErrorCodes = [
+  'EWSABNORMALCLOSE',
+  'ECONNRESET',
+  'ECONNREFUSED',
+  'ECONNABORTED',
+  'EPIPE',
+  'ETIMEDOUT',
+  'ECANCELED',
+]
+
+function backoffMs(n: number, maxMs: number) {
+  const baseSec = Math.pow(2, n) // 1, 2, 4, ...
+  const randSec = Math.random() - 0.5 // Random jitter between -.5 and .5 seconds
+  const ms = 1000 * (baseSec + randSec)
+  return Math.min(ms, maxMs)
+}
+
+function forwardSignal(signal: AbortSignal, ac: AbortController) {
+  if (signal.aborted) {
+    return ac.abort(signal.reason)
+  } else {
+    signal.addEventListener('abort', () => ac.abort(signal.reason), {
+      // @ts-ignore https://github.com/DefinitelyTyped/DefinitelyTyped/pull/68625
+      signal: ac.signal,
+    })
+  }
+}

package/tests/keepalive.test.ts

@@ -0,0 +1,50 @@
+import getPort from 'get-port'
+import { WebSocketServer } from 'ws'
+import { wait } from '@atproto/common'
+import { CloseCode, WebSocketKeepAlive } from '../src'
+
+describe('WebSocketKeepAlive', () => {
+  it('uses a heartbeat to reconnect if a connection is dropped', async () => {
+    // we run a server that, on first connection, pauses for longer than the heartbeat interval (doesn't return "pong"s)
+    // on second connection, it sends a message and then closes
+    const port = await getPort()
+    const server = new WebSocketServer({ port })
+    let firstConnection = true
+    let firstWasClosed = false
+    server.on('connection', async (socket) => {
+      if (firstConnection === true) {
+        firstConnection = false
+        socket.pause()
+        await wait(600)
+        // shouldn't send this message because the socket would be closed
+        socket.send(Buffer.from('error message'), (err) => {
+          if (err) throw err
+          socket.close(CloseCode.Normal)
+        })
+        socket.on('close', () => {
+          firstWasClosed = true
+        })
+      } else {
+        socket.send(Buffer.from('test message'), (err) => {
+          if (err) throw err
+          socket.close(CloseCode.Normal)
+        })
+      }
+    })
+
+    const wsKeepAlive = new WebSocketKeepAlive({
+      getUrl: async () => `ws://localhost:${port}`,
+      heartbeatIntervalMs: 500,
+    })
+
+    const messages: Uint8Array[] = []
+    for await (const msg of wsKeepAlive) {
+      messages.push(msg)
+    }
+
+    expect(messages).toHaveLength(1)
+    expect(Buffer.from(messages[0]).toString()).toBe('test message')
+    expect(firstWasClosed).toBe(true)
+    server.close()
+  })
+})

package/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig/node.json",
+  "compilerOptions": {
+    "noImplicitAny": true,
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["./src"]
+}

package/tsconfig.build.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/index.ts"],"version":"5.8.3"}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "include": [],
+  "references": [
+    { "path": "./tsconfig.build.json" },
+    { "path": "./tsconfig.tests.json" }
+  ]
+}

package/tsconfig.tests.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig/tests.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["./tests"]
+}

package/tsconfig.tests.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./tests/keepalive.test.ts"],"version":"5.8.3"}