@forgeax/engine-net-websocket 0.1.3 → 0.1.6

package/src/node.ts

@@ -9,7 +9,8 @@ import {
 import { err, ok, type Result } from '@forgeax/engine-types';
 import WebSocket, { WebSocketServer } from 'ws';
 import { BoundedEventQueue, DEFAULT_MAX_QUEUED_EVENTS } from './event-queue';
-import { createWebSocketClientEndpoint } from './websocket-client-core';
+import type { WebSocketConstructor } from './websocket-client-core';
+import { createWebSocketConnectorAdapter } from './websocket-connector';
 
 export interface ListenWebSocketEndpointOptions {
   readonly port: number;
@@ -22,20 +23,42 @@ export interface ConnectWebSocketClientEndpointOptions {
   readonly maxQueuedEvents?: number | undefined;
 }
 
-export function connectWebSocketClientEndpoint(
+/**
+ * Creates the Node WebSocket adapter for the public NetEndpointConnector.
+ * Each connect call accepts an AbortSignal and creates one replacement-capable
+ * NetEndpoint. Transport lifecycle and EndpointError results stay here;
+ * authoritative resync and replication policy stay with NetSession.
+ */
+export function createWebSocketConnector(
   url: string,
   options: ConnectWebSocketClientEndpointOptions = {},
-): Promise<Result<NetEndpoint, EndpointError>> {
-  return createWebSocketClientEndpoint(
-    WebSocket as unknown as import('./websocket-client-core').WebSocketConstructor,
+): import('@forgeax/engine-net').NetEndpointConnector {
+  return createWebSocketConnectorAdapter(
     {
-      url,
-      maxQueuedEvents: options.maxQueuedEvents,
-      toBytes: toBytes,
+      WebSocket: WebSocket as unknown as WebSocketConstructor,
+      toBytes,
     },
+    url,
+    options,
   );
 }
 
+/**
+ * Connects one Node WebSocket with the default one-shot AbortSignal.
+ * Use createWebSocketConnector when the caller must cancel or replace an
+ * endpoint through an explicit signal.
+ */
+export function connectWebSocketClientEndpoint(
+  url: string,
+  options: ConnectWebSocketClientEndpointOptions = {},
+): Promise<Result<NetEndpoint, EndpointError>> {
+  return createWebSocketConnector(url, options).connect(new AbortController().signal);
+}
+
+/**
+ * Starts a Node WebSocket listener that exposes NetEndpoint peer events and
+ * binary messages without owning NetSession or replication policy.
+ */
 export function listenWebSocketEndpoint(
   options: ListenWebSocketEndpointOptions,
 ): Promise<Result<NetEndpoint, EndpointError>> {

package/src/websocket-client-core.ts

@@ -31,6 +31,8 @@ export interface WebSocketConstructor {
 export interface WebSocketClientCoreOptions {
   readonly url: string;
   readonly maxQueuedEvents?: number | undefined;
+  readonly peerId?: PeerId;
+  readonly signal?: AbortSignal;
   readonly toBytes: (data: unknown) => Uint8Array | Promise<Uint8Array | undefined> | undefined;
 }
 
@@ -41,6 +43,13 @@ export function createWebSocketClientEndpoint(
   options: WebSocketClientCoreOptions,
 ): Promise<Result<NetEndpoint, EndpointError>> {
   return new Promise((resolve) => {
+    const clientPeerId = options.peerId ?? CLIENT_PEER_ID;
+    const signal = options.signal ?? new AbortController().signal;
+    if (signal.aborted) {
+      resolve(connectionFailed(options.url, 'WebSocket connection aborted.'));
+      return;
+    }
+
     let queue: BoundedEventQueue;
     try {
       queue = new BoundedEventQueue(options.maxQueuedEvents ?? DEFAULT_MAX_QUEUED_EVENTS);
@@ -65,18 +74,40 @@ export function createWebSocketClientEndpoint(
     let locallyClosed = false;
     let messageTail = Promise.resolve();
 
+    const removeAbortListener = (): void => {
+      signal.removeEventListener('abort', abortPendingConnection);
+    };
+
+    const abortPendingConnection = (): void => {
+      if (opened || settled) return;
+      settled = true;
+      try {
+        socket.close();
+      } catch {
+        // Closing a partially opened platform socket is best effort.
+      }
+      removeAbortListener();
+      resolve(connectionFailed(options.url, 'WebSocket connection aborted.'));
+    };
+
+    signal.addEventListener('abort', abortPendingConnection, { once: true });
+    if (signal.aborted) {
+      abortPendingConnection();
+      return;
+    }
+
     const disconnect = (reason: string): void => {
       if (closed) return;
       closed = true;
       queue.close(reason);
-      terminalEvents.push({ kind: 'peer-disconnected', peerId: CLIENT_PEER_ID });
+      terminalEvents.push({ kind: 'peer-disconnected', peerId: clientPeerId });
     };
 
     const endpoint: NetEndpoint = {
       poll: () => [...queue.drain(), ...terminalEvents.splice(0)],
       send: (peerId, data) => {
         if (closed) return locallyClosed ? alreadyClosed() : connectionClosed(peerId);
-        if (peerId !== CLIENT_PEER_ID)
+        if (peerId !== clientPeerId)
           return err(
             new EndpointError({
               code: 'peer-not-found',
@@ -127,9 +158,10 @@ export function createWebSocketClientEndpoint(
 
     socket.onopen = () => {
       if (settled) return;
+      removeAbortListener();
       opened = true;
       settled = true;
-      queue.enqueue({ kind: 'peer-connected', peerId: CLIENT_PEER_ID });
+      queue.enqueue({ kind: 'peer-connected', peerId: clientPeerId });
       resolve(ok(endpoint));
     };
     socket.onmessage = ({ data }) => {
@@ -139,7 +171,7 @@ export function createWebSocketClientEndpoint(
         .then(async () => {
           const bytes = await options.toBytes(data);
           if (!bytes || closed) return;
-          if (!queue.enqueue({ kind: 'message', peerId: CLIENT_PEER_ID, data: bytes })) {
+          if (!queue.enqueue({ kind: 'message', peerId: clientPeerId, data: bytes })) {
             socket.close();
           }
         })
@@ -149,12 +181,14 @@ export function createWebSocketClientEndpoint(
       if (opened) disconnect(`WebSocket error: ${normalizeCause(cause)}`);
       else if (!settled) {
         settled = true;
+        removeAbortListener();
         resolve(connectionFailed(options.url, cause));
       }
     };
     socket.onclose = (cause) => {
       if (!opened && !settled) {
         settled = true;
+        removeAbortListener();
         resolve(connectionFailed(options.url, cause));
         return;
       }

package/src/websocket-connector.ts

@@ -0,0 +1,35 @@
+import type { NetEndpointConnector, PeerId } from '@forgeax/engine-net';
+import {
+  createWebSocketClientEndpoint,
+  type WebSocketClientCoreOptions,
+  type WebSocketConstructor,
+} from './websocket-client-core';
+
+export interface WebSocketConnectorOptions {
+  readonly maxQueuedEvents?: number | undefined;
+}
+
+export interface WebSocketConnectorRuntime {
+  readonly WebSocket: WebSocketConstructor;
+  readonly toBytes: WebSocketClientCoreOptions['toBytes'];
+}
+
+export function createWebSocketConnectorAdapter(
+  runtime: WebSocketConnectorRuntime,
+  url: string,
+  options: WebSocketConnectorOptions = {},
+): NetEndpointConnector {
+  let nextPeerId = 1;
+  return {
+    connect: (signal) => {
+      const peerId = nextPeerId++ as PeerId;
+      return createWebSocketClientEndpoint(runtime.WebSocket, {
+        url,
+        maxQueuedEvents: options.maxQueuedEvents,
+        peerId,
+        signal,
+        toBytes: runtime.toBytes,
+      });
+    },
+  };
+}