@culpeo/async-ws 0.2.0 → 1.1.0

package/CHANGELOG.md

@@ -1,11 +1,34 @@
 # Changelog
 
+## 1.1.0
+
+### Minor Changes
+
+- 89a662e: ### Adopt existing WebSocket connections
+
+  New static method `WebSocketClient.fromSocket(socket, options?)` wraps an already-open WebSocket (e.g. from a `WebSocketServer` connection event) into a ready-to-use `WebSocketClient`. Node.js only.
+
+## 1.0.0
+
+### Major Changes
+
+- 6b68e4c: ### Connect timeout and abort signal
+
+  `connect()` now accepts `timeout` (milliseconds) and `signal` (AbortSignal) options to cancel connection attempts.
+
+  ### Keep-alive ping/pong (Node.js)
+
+  New `keepAlive` constructor option sends periodic pings and terminates the connection if no pong is received. Not available in browsers.
+
+  ### Exposed WebSocket properties
+
+  Added read-only `protocol`, `url`, `bufferedAmount`, and `extensions` properties that delegate to the underlying socket.
+
 ## 0.2.0
 
 ### Minor Changes
 
 - 9453a7c: Initial release
-
   - Cross-platform WebSocket client for Node.js and browsers
   - Promise-based `connect()`, `send()`, `receive()`, `close()` API
   - Async iteration with `for await...of`

package/README.md

@@ -15,6 +15,10 @@
 - Async iteration support with `for await...of`
 - Message buffering for messages that arrive before `receive()` is called
 - Configurable `maxBufferSize` with oldest-message eviction when full
+- Connect timeout and `AbortSignal` support
+- Keep-alive with automatic ping/pong (Node.js)
+- Server-side socket adoption with `fromSocket()` (Node.js)
+- Exposed WebSocket properties (`protocol`, `url`, `bufferedAmount`, `extensions`)
 - Clean close information via `lastCloseInfo`
 - TypeScript-first with bundled type definitions
 - Binary and text message support
@@ -45,7 +49,7 @@ await client.connect("wss://echo.websocket.events");
 await client.send("hello");
 
 const message = await client.receive();
-console.log(message.data);   // string | ArrayBuffer
+console.log(message.data); // string | ArrayBuffer
 console.log(message.binary); // boolean
 
 await client.close();
@@ -69,6 +73,9 @@ Creates a new client instance.
   - Maximum number of incoming messages to keep buffered before they are consumed
   - Default: `0` (unlimited)
   - When the limit is reached, the oldest buffered message is dropped
+- `keepAlive?: KeepAliveOptions`
+  - Enables automatic ping/pong keep-alive (Node.js only)
+  - Throws if used in a browser environment
 
 #### Properties
 
@@ -87,6 +94,38 @@ Returns the current client state:
 - `"closed"`
 - `"errored"`
 
+#### `client.protocol`
+
+```ts
+readonly protocol: string
+```
+
+Returns the negotiated subprotocol, or `""` when not connected.
+
+#### `client.url`
+
+```ts
+readonly url: string
+```
+
+Returns the URL of the WebSocket connection, or `""` when not connected.
+
+#### `client.bufferedAmount`
+
+```ts
+readonly bufferedAmount: number
+```
+
+Returns the number of bytes queued for transmission, or `0` when not connected.
+
+#### `client.extensions`
+
+```ts
+readonly extensions: string
+```
+
+Returns the negotiated extensions, or `""` when not connected.
+
 #### `client.lastCloseInfo`
 
 ```ts
@@ -95,7 +134,39 @@ readonly lastCloseInfo: WebSocketCloseInfo | null
 
 Returns close metadata from the most recent close event, or `null` if the socket has not closed yet.
 
-#### Methods
+#### Static Methods
+
+#### `fromSocket()`
+
+```ts
+static fromSocket(rawSocket: unknown, options?: ClientOptions): WebSocketClient
+```
+
+Wraps an already-open WebSocket into a `WebSocketClient` in the `"open"` state, ready to send and receive. Intended for server scenarios where a `WebSocketServer` hands you an established connection.
+
+**Node.js only.** Throws in browser builds.
+
+```ts
+import { WebSocketServer } from "ws";
+import { WebSocketClient } from "@culpeo/async-ws";
+
+const wss = new WebSocketServer({ port: 8080 });
+
+wss.on("connection", async (socket) => {
+  const client = WebSocketClient.fromSocket(socket);
+
+  for await (const msg of client) {
+    console.log("received:", msg.data);
+    await client.send("echo: " + msg.data);
+  }
+});
+```
+
+The client takes ownership of the socket lifecycle — calling `close()` will close the underlying socket. Call `fromSocket()` immediately in the `connection` handler to avoid missing messages.
+
+Accepts any WebSocket-compatible object (validated structurally, not via `instanceof`), so it works even when multiple copies of the `ws` package are installed.
+
+#### Instance Methods
 
 #### `connect()`
 
@@ -116,6 +187,8 @@ Rejects when:
 
 - `protocols?: string | string[]` — WebSocket subprotocols to request
 - `headers?: Record<string, string>` — custom handshake headers in Node.js
+- `timeout?: number` — connection timeout in milliseconds; rejects if the connection is not established within this time
+- `signal?: AbortSignal` — an abort signal to cancel the connection attempt
 
 > In browsers, passing `headers` throws because the native WebSocket API does not support custom headers.
 
@@ -182,6 +255,8 @@ Behavior:
 interface ConnectOptions {
   protocols?: string | string[];
   headers?: Record<string, string>;
+  timeout?: number;
+  signal?: AbortSignal;
 }
 ```
 
@@ -192,11 +267,24 @@ Connection-time options.
 ```ts
 interface ClientOptions {
   maxBufferSize?: number;
+  keepAlive?: KeepAliveOptions;
 }
 ```
 
 Client-level configuration.
 
+### `KeepAliveOptions`
+
+```ts
+interface KeepAliveOptions {
+  interval: number;
+  timeout?: number;
+}
+```
+
+- `interval` — milliseconds between pings
+- `timeout` — milliseconds to wait for a pong before terminating the connection (default: `interval`)
+
 ### `WebSocketMessage`
 
 ```ts
@@ -276,7 +364,7 @@ This is useful when you want a stream-like consumer loop without manually callin
 
 All core operations are async and communicate failure by rejecting:
 
-- `connect()` rejects on invalid state, connection failure, or early close
+- `connect()` rejects on invalid state, connection failure, early close, timeout, or abort
 - `send()` rejects when called before the socket is open or when the adapter fails to send
 - `receive()` rejects when the client is not in a receivable state and no buffered messages remain
 - `close()` rejects for invalid close codes
@@ -324,6 +412,77 @@ When the buffer is full:
 
 This makes buffering predictable for bursty message streams while keeping the public API simple.
 
+## Connection Timeout and Abort
+
+Use `timeout` to reject if the connection isn't established within a deadline:
+
+```ts
+await client.connect("wss://example.com/ws", { timeout: 5000 });
+```
+
+Use `signal` to cancel a connection attempt at any time:
+
+```ts
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 3000);
+
+await client.connect("wss://example.com/ws", { signal: controller.signal });
+```
+
+Both can be combined:
+
+```ts
+await client.connect("wss://example.com/ws", {
+  timeout: 10000,
+  signal: controller.signal,
+});
+```
+
+## Server-Side Socket Adoption (Node.js)
+
+Use `fromSocket()` to wrap connections from a `WebSocketServer`:
+
+```ts
+import { WebSocketServer } from "ws";
+import { WebSocketClient } from "@culpeo/async-ws";
+
+const wss = new WebSocketServer({ port: 8080 });
+
+wss.on("connection", async (socket) => {
+  const client = WebSocketClient.fromSocket(socket);
+
+  const msg = await client.receive();
+  await client.send("got: " + msg.data);
+  await client.close();
+});
+```
+
+The same `ClientOptions` are supported:
+
+```ts
+const client = WebSocketClient.fromSocket(socket, {
+  maxBufferSize: 100,
+  keepAlive: { interval: 30000 },
+});
+```
+
+## Keep-Alive (Node.js)
+
+Enable automatic ping/pong to detect dead connections:
+
+```ts
+const client = new WebSocketClient({
+  keepAlive: { interval: 30000, timeout: 5000 },
+});
+
+await client.connect("wss://example.com/ws");
+```
+
+- Sends a ping every `interval` milliseconds
+- If no pong is received within `timeout` milliseconds, the connection is terminated
+- `timeout` defaults to `interval` if omitted
+- **Not available in browsers** — the constructor throws if `keepAlive` is configured in a browser environment
+
 ## Building from Source
 
 ```bash

package/dist/browser/index.js

@@ -10,7 +10,17 @@ function socketSend(socket, data) {
         return Promise.reject(new Error("WebSocket is not open"));
     }
     try {
-        socket.send(data);
+        if (ArrayBuffer.isView(data)) {
+            if (data.buffer instanceof SharedArrayBuffer) {
+                throw new Error("SharedArrayBuffer-backed views are not supported. " +
+                    "Copy into a regular ArrayBuffer before sending.");
+            }
+            // Zero-copy: create a Uint8Array view over the same ArrayBuffer
+            socket.send(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+        }
+        else {
+            socket.send(data);
+        }
         return Promise.resolve();
     }
     catch (err) {
@@ -42,6 +52,19 @@ function attachListeners(socket, onOpen, onMessage, onClose, onError) {
 function socketClose(socket, code, reason) {
     socket.close(code, reason);
 }
+function socketTerminate(socket) {
+    socket.close();
+}
+function socketPing(_socket) {
+    throw new Error("Ping is not supported in browsers.");
+}
+function attachPongListener(_socket, _onPong) {
+    return () => { };
+}
+function adoptSocket(_rawSocket) {
+    throw new Error("fromSocket() is not supported in browsers. " +
+        "Browsers cannot accept server-side WebSocket connections.");
+}
 
 /**
  * Imperative WebSocket client that works in both browser and Node.js.
@@ -62,7 +85,71 @@ class WebSocketClient {
         this.terminalError = null;
         this.closeInfo = null;
         this.removeListeners = null;
+        this.keepAliveTimer = null;
+        this.pongTimer = null;
+        this.removePongListener = null;
+        this.connectionId = 0;
         this.maxBufferSize = options?.maxBufferSize ?? 0;
+        if (options?.keepAlive) {
+            {
+                throw new Error("keepAlive is not supported in browsers. " +
+                    "The browser handles WebSocket ping/pong at the protocol level automatically.");
+            }
+        }
+    }
+    /**
+     * Adopt an already-open WebSocket (e.g. from a `WebSocketServer` connection event).
+     *
+     * Returns a `WebSocketClient` in the "open" state, ready to send/receive.
+     * The client takes ownership of the socket lifecycle: calling `close()`
+     * will close the underlying socket.
+     *
+     * **Node.js only.** Throws in browser builds.
+     *
+     * Call this immediately in the server's `connection` handler to avoid
+     * missing messages:
+     *
+     * ```ts
+     * wss.on("connection", (socket) => {
+     *   const client = WebSocketClient.fromSocket(socket);
+     *   const msg = await client.receive();
+     * });
+     * ```
+     */
+    static fromSocket(rawSocket, options) {
+        const client = new WebSocketClient(options);
+        const socket = adoptSocket();
+        client.socket = socket;
+        setBinaryType(socket);
+        client.state = "open";
+        const currentConnectionId = ++client.connectionId;
+        client.removeListeners = attachListeners(socket, 
+        // onOpen — already open, won't fire
+        () => { }, 
+        // onMessage
+        (data, binary) => {
+            client.enqueueMessage({ data, binary });
+        }, 
+        // onClose
+        (code, reason, wasClean) => {
+            if (currentConnectionId !== client.connectionId)
+                return;
+            client.closeInfo = { code, reason, wasClean };
+            client.state = "closed";
+            client.cleanup();
+            if (client.buffer.length === 0) {
+                client.rejectAllWaiters(new Error(`WebSocket closed (code: ${code}, reason: ${reason})`));
+            }
+        }, 
+        // onError
+        (error) => {
+            if (currentConnectionId !== client.connectionId)
+                return;
+            client.terminalError = error;
+            client.rejectAllWaiters(error);
+        });
+        client.startKeepAlive();
+        return client;
     }
     /** Current connection state. */
     get readyState() {
@@ -72,16 +159,41 @@ class WebSocketClient {
     get lastCloseInfo() {
         return this.closeInfo;
     }
+    /** The negotiated subprotocol, or empty string if none. */
+    get protocol() {
+        return this.socket?.protocol ?? "";
+    }
+    /** The URL of the WebSocket connection. */
+    get url() {
+        return this.socket?.url ?? "";
+    }
+    /** The number of bytes of data queued for sending. */
+    get bufferedAmount() {
+        return this.socket?.bufferedAmount ?? 0;
+    }
+    /** The extensions negotiated by the server. */
+    get extensions() {
+        return this.socket?.extensions ?? "";
+    }
     /**
      * Connect to a WebSocket server.
      * Resolves when the connection is open. Rejects on error.
      */
     connect(url, options) {
-        if (this.state !== "idle" && this.state !== "closed" && this.state !== "errored") {
+        if (this.state !== "idle" &&
+            this.state !== "closed" &&
+            this.state !== "errored") {
             return Promise.reject(new Error(`Cannot connect: client is in "${this.state}" state`));
         }
+        if (options?.timeout !== undefined && options.timeout <= 0) {
+            return Promise.reject(new Error("timeout must be greater than 0."));
+        }
+        if (options?.signal?.aborted) {
+            return Promise.reject(new Error("Connection aborted."));
+        }
         this.reset();
         this.state = "connecting";
+        const currentConnectionId = ++this.connectionId;
         return new Promise((resolve, reject) => {
             try {
                 this.socket = createWebSocket(url, options);
@@ -89,19 +201,63 @@ class WebSocketClient {
             }
             catch (err) {
                 this.state = "errored";
-                this.terminalError = err instanceof Error ? err : new Error(String(err));
+                this.terminalError =
+                    err instanceof Error ? err : new Error(String(err));
                 reject(this.terminalError);
                 return;
             }
             let settled = false;
+            let timeoutId = null;
+            const settle = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timeoutId !== null) {
+                    clearTimeout(timeoutId);
+                    timeoutId = null;
+                }
+                if (options?.signal) {
+                    options.signal.removeEventListener("abort", onAbort);
+                }
+                fn();
+            };
+            const onAbort = () => {
+                settle(() => {
+                    this.state = "closed";
+                    this.terminalError = new Error("Connection aborted.");
+                    if (this.socket) {
+                        socketTerminate(this.socket);
+                    }
+                    // Don't call cleanup() here — socketTerminate() emits
+                    // error/close asynchronously; let onClose handle cleanup.
+                    reject(this.terminalError);
+                });
+            };
+            if (options?.timeout !== undefined) {
+                timeoutId = setTimeout(() => {
+                    settle(() => {
+                        this.state = "closed";
+                        this.terminalError = new Error(`Connection timed out after ${options.timeout}ms.`);
+                        if (this.socket) {
+                            socketTerminate(this.socket);
+                        }
+                        // Don't call cleanup() here — socketTerminate() emits
+                        // error/close asynchronously; let onClose handle cleanup.
+                        reject(this.terminalError);
+                    });
+                }, options.timeout);
+            }
+            if (options?.signal) {
+                options.signal.addEventListener("abort", onAbort, { once: true });
+            }
             this.removeListeners = attachListeners(this.socket, 
             // onOpen
             () => {
-                if (!settled) {
-                    settled = true;
+                settle(() => {
                     this.state = "open";
+                    this.startKeepAlive();
                     resolve();
-                }
+                });
             }, 
             // onMessage
             (data, binary) => {
@@ -109,14 +265,16 @@ class WebSocketClient {
             }, 
             // onClose
             (code, reason, wasClean) => {
+                // Ignore close events from a stale connection (e.g., after
+                // timeout/abort triggered a reconnect on the same client).
+                if (currentConnectionId !== this.connectionId)
+                    return;
                 this.closeInfo = { code, reason, wasClean };
-                this.state;
                 this.state = "closed";
                 this.cleanup();
-                if (!settled) {
-                    settled = true;
+                settle(() => {
                     reject(new Error(`WebSocket closed before opening (code: ${code}, reason: ${reason})`));
-                }
+                });
                 // Only reject pending waiters once buffer is drained
                 if (this.buffer.length === 0) {
                     this.rejectAllWaiters(new Error(`WebSocket closed (code: ${code}, reason: ${reason})`));
@@ -124,11 +282,13 @@ class WebSocketClient {
             }, 
             // onError
             (error) => {
+                // Ignore error events from a stale connection.
+                if (currentConnectionId !== this.connectionId)
+                    return;
                 this.terminalError = error;
-                if (!settled) {
-                    settled = true;
+                settle(() => {
                     reject(error);
-                }
+                });
                 // Reject any pending receive() waiters immediately
                 this.rejectAllWaiters(error);
                 // Don't call cleanup() here — per spec, a close event always
@@ -176,7 +336,9 @@ class WebSocketClient {
      * Resolves when the close handshake completes.
      */
     close(code, reason) {
-        if (this.state === "closed" || this.state === "idle" || this.state === "errored") {
+        if (this.state === "closed" ||
+            this.state === "idle" ||
+            this.state === "errored") {
             return Promise.resolve();
         }
         if (!this.socket) {
@@ -186,7 +348,9 @@ class WebSocketClient {
             // Already closing — wait for the close event via a one-shot listener
             return new Promise((resolve) => {
                 if (this.socket) {
-                    this.socket.addEventListener("close", () => resolve(), { once: true });
+                    this.socket.addEventListener("close", () => resolve(), {
+                        once: true,
+                    });
                 }
                 else {
                     resolve();
@@ -251,11 +415,50 @@ class WebSocketClient {
             waiter.reject(error);
         }
     }
+    startKeepAlive() {
+        if (!this.keepAliveConfig || !this.socket)
+            return;
+        const { interval, timeout } = this.keepAliveConfig;
+        const pongTimeout = timeout ?? interval;
+        this.removePongListener = attachPongListener(this.socket);
+        this.keepAliveTimer = setInterval(() => {
+            if (this.state !== "open" || !this.socket)
+                return;
+            socketPing(this.socket);
+            // Clear any existing pong watchdog before starting a new one
+            // to prevent multiple timers when timeout > interval.
+            if (this.pongTimer !== null) {
+                clearTimeout(this.pongTimer);
+            }
+            this.pongTimer = setTimeout(() => {
+                if (this.state === "open" && this.socket) {
+                    this.terminalError = new Error(`Keep-alive timeout: no pong received within ${pongTimeout}ms.`);
+                    socketTerminate(this.socket);
+                }
+            }, pongTimeout);
+        }, interval);
+    }
+    stopKeepAlive() {
+        if (this.keepAliveTimer !== null) {
+            clearInterval(this.keepAliveTimer);
+            this.keepAliveTimer = null;
+        }
+        if (this.pongTimer !== null) {
+            clearTimeout(this.pongTimer);
+            this.pongTimer = null;
+        }
+        if (this.removePongListener) {
+            this.removePongListener();
+            this.removePongListener = null;
+        }
+    }
     cleanup() {
+        this.stopKeepAlive();
         if (this.removeListeners) {
             this.removeListeners();
             this.removeListeners = null;
         }
+        this.socket = null;
     }
     reset() {
         this.socket = null;
@@ -264,6 +467,7 @@ class WebSocketClient {
         this.terminalError = null;
         this.closeInfo = null;
         this.removeListeners = null;
+        this.stopKeepAlive();
     }
 }