@forgeax/engine-net-websocket 0.0.0-dev.8d955ade1c79

package/src/event-queue.ts

@@ -0,0 +1,43 @@
+import type { EndpointEvent } from '@forgeax/engine-net';
+
+export const DEFAULT_MAX_QUEUED_EVENTS = 1024;
+
+export class BoundedEventQueue {
+  readonly #events: EndpointEvent[] = [];
+  #closed = false;
+  #disconnectReason: string | undefined;
+
+  constructor(readonly maxQueuedEvents: number) {
+    if (!Number.isInteger(maxQueuedEvents) || maxQueuedEvents < 1) {
+      throw new RangeError('maxQueuedEvents must be a positive integer');
+    }
+  }
+
+  get closed(): boolean {
+    return this.#closed;
+  }
+
+  get disconnectReason(): string | undefined {
+    return this.#disconnectReason;
+  }
+
+  enqueue(event: EndpointEvent): boolean {
+    if (this.#closed) return false;
+    if (this.#events.length === this.maxQueuedEvents) {
+      this.close(`event queue overflow (maxQueuedEvents=${this.maxQueuedEvents})`);
+      return false;
+    }
+    this.#events.push(event);
+    return true;
+  }
+
+  close(reason: string): void {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#disconnectReason = reason;
+  }
+
+  drain(): EndpointEvent[] {
+    return this.#events.splice(0);
+  }
+}

package/src/node.ts

@@ -0,0 +1,224 @@
+import {
+  ENDPOINT_ERROR_HINTS,
+  ENDPOINT_EXPECTED,
+  EndpointError,
+  type EndpointEvent,
+  type NetEndpoint,
+  type PeerId,
+} from '@forgeax/engine-net';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import WebSocket, { WebSocketServer } from 'ws';
+import { BoundedEventQueue, DEFAULT_MAX_QUEUED_EVENTS } from './event-queue';
+import type { WebSocketConstructor } from './websocket-client-core';
+import { createWebSocketConnectorAdapter } from './websocket-connector';
+
+export interface ListenWebSocketEndpointOptions {
+  readonly port: number;
+  readonly host?: string;
+  readonly maxPeers?: number;
+  readonly maxQueuedEvents?: number | undefined;
+}
+
+export interface ConnectWebSocketClientEndpointOptions {
+  readonly maxQueuedEvents?: number | undefined;
+}
+
+/**
+ * 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 = {},
+): import('@forgeax/engine-net').NetEndpointConnector {
+  return createWebSocketConnectorAdapter(
+    {
+      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>> {
+  return new Promise((resolve) => {
+    const host = options.host ?? '127.0.0.1';
+    const address = `ws://${host}:${options.port}`;
+    let queue: BoundedEventQueue;
+    try {
+      queue = new BoundedEventQueue(options.maxQueuedEvents ?? DEFAULT_MAX_QUEUED_EVENTS);
+    } catch (cause) {
+      resolve(connectionFailed(address, cause));
+      return;
+    }
+
+    const terminalEvents: EndpointEvent[] = [];
+    const peers = new Map<PeerId, WebSocket>();
+    const disconnectedPeers = new Set<PeerId>();
+    const sockets = new Map<WebSocket, PeerId>();
+    const maxPeers = options.maxPeers ?? Number.POSITIVE_INFINITY;
+    let nextPeerId = 1;
+    let settled = false;
+    let closed = false;
+    const server = new WebSocketServer({ host, port: options.port, perMessageDeflate: false });
+
+    const endpoint: NetEndpoint = {
+      poll: () => [...queue.drain(), ...terminalEvents.splice(0)],
+      send: (peerId, data) => {
+        if (closed) return alreadyClosed('The WebSocket listener endpoint is closed.');
+        const socket = peers.get(peerId);
+        if (!socket && disconnectedPeers.has(peerId))
+          return err(
+            new EndpointError({
+              code: 'connection-closed',
+              expected: ENDPOINT_EXPECTED['connection-closed'],
+              hint: ENDPOINT_ERROR_HINTS['connection-closed'],
+              detail: { peerId },
+            }),
+          );
+        if (!socket)
+          return err(
+            new EndpointError({
+              code: 'peer-not-found',
+              expected: ENDPOINT_EXPECTED['peer-not-found'],
+              hint: ENDPOINT_ERROR_HINTS['peer-not-found'],
+              detail: { peerId },
+            }),
+          );
+        if (socket.readyState !== socket.OPEN)
+          return err(
+            new EndpointError({
+              code: 'connection-closed',
+              expected: ENDPOINT_EXPECTED['connection-closed'],
+              hint: ENDPOINT_ERROR_HINTS['connection-closed'],
+              detail: { peerId },
+            }),
+          );
+        try {
+          socket.send(data, { binary: true });
+          return ok(undefined);
+        } catch (cause) {
+          return err(
+            new EndpointError({
+              code: 'send-failed',
+              expected: ENDPOINT_EXPECTED['send-failed'],
+              hint: ENDPOINT_ERROR_HINTS['send-failed'],
+              detail: { peerId, cause: normalizeCause(cause) },
+            }),
+          );
+        }
+      },
+      close: () => {
+        if (closed) return alreadyClosed('The WebSocket listener endpoint is already closed.');
+        closed = true;
+        for (const socket of peers.values()) socket.close();
+        server.close();
+        return ok(undefined);
+      },
+    };
+
+    const enqueue = (event: EndpointEvent, socket?: WebSocket): void => {
+      if (queue.enqueue(event)) return;
+      if (event.kind !== 'peer-disconnected') {
+        terminalEvents.push({ kind: 'peer-disconnected', peerId: event.peerId });
+      }
+      socket?.close();
+    };
+
+    server.on('connection', (socket) => {
+      if (closed || peers.size >= maxPeers) {
+        socket.close();
+        return;
+      }
+      const peerId = nextPeerId++ as PeerId;
+      peers.set(peerId, socket);
+      sockets.set(socket, peerId);
+      enqueue({ kind: 'peer-connected', peerId }, socket);
+      socket.on('message', (data, isBinary) => {
+        if (!isBinary) {
+          socket.close();
+          return;
+        }
+        const bytes = toBytes(data);
+        if (!bytes) {
+          socket.close();
+          return;
+        }
+        enqueue({ kind: 'message', peerId, data: bytes }, socket);
+      });
+      socket.on('close', () => {
+        if (!peers.delete(peerId)) return;
+        disconnectedPeers.add(peerId);
+        sockets.delete(socket);
+        enqueue({ kind: 'peer-disconnected', peerId });
+      });
+      socket.on('error', () => socket.close());
+    });
+    server.on('error', (cause) => {
+      if (settled) return;
+      settled = true;
+      resolve(connectionFailed(address, cause));
+    });
+    server.on('listening', () => {
+      if (settled) return;
+      settled = true;
+      resolve(ok(endpoint));
+    });
+  });
+}
+
+function toBytes(data: unknown): Uint8Array | undefined {
+  if (data instanceof Uint8Array)
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  return undefined;
+}
+
+function connectionFailed(address: string, cause: unknown): Result<never, EndpointError> {
+  return err(
+    new EndpointError({
+      code: 'connection-failed',
+      expected: ENDPOINT_EXPECTED['connection-failed'],
+      hint: ENDPOINT_ERROR_HINTS['connection-failed'],
+      detail: { address, cause: normalizeCause(cause) },
+    }),
+  );
+}
+
+function alreadyClosed(cause: string): Result<never, EndpointError> {
+  return err(
+    new EndpointError({
+      code: 'already-closed',
+      expected: ENDPOINT_EXPECTED['already-closed'],
+      hint: ENDPOINT_ERROR_HINTS['already-closed'],
+      detail: { cause },
+    }),
+  );
+}
+
+function normalizeCause(cause: unknown): string {
+  if (cause instanceof Error) return cause.message;
+  if (typeof cause === 'string') return cause;
+  return 'WebSocket operation failed without a platform error message.';
+}

package/src/websocket-client-core.ts

@@ -0,0 +1,237 @@
+import {
+  ENDPOINT_ERROR_HINTS,
+  ENDPOINT_EXPECTED,
+  EndpointError,
+  type EndpointEvent,
+  type NetEndpoint,
+  type PeerId,
+} from '@forgeax/engine-net';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { BoundedEventQueue, DEFAULT_MAX_QUEUED_EVENTS } from './event-queue';
+
+export interface WebSocketLike {
+  readonly CONNECTING: number;
+  readonly OPEN: number;
+  readonly CLOSING: number;
+  readonly CLOSED: number;
+  readonly readyState: number;
+  binaryType?: string;
+  onopen: ((event: unknown) => void) | null;
+  onmessage: ((event: { data: unknown }) => void) | null;
+  onerror: ((event: unknown) => void) | null;
+  onclose: ((event: unknown) => void) | null;
+  send(data: Uint8Array): void;
+  close(): void;
+}
+
+export interface WebSocketConstructor {
+  new (url: string): WebSocketLike;
+}
+
+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;
+}
+
+const CLIENT_PEER_ID = 1 as PeerId;
+
+export function createWebSocketClientEndpoint(
+  WebSocket: WebSocketConstructor,
+  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);
+    } catch (cause) {
+      resolve(connectionFailed(options.url, cause));
+      return;
+    }
+
+    let socket: WebSocketLike;
+    try {
+      socket = new WebSocket(options.url);
+      socket.binaryType = 'arraybuffer';
+    } catch (cause) {
+      resolve(connectionFailed(options.url, cause));
+      return;
+    }
+
+    const terminalEvents: EndpointEvent[] = [];
+    let opened = false;
+    let settled = false;
+    let closed = false;
+    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: clientPeerId });
+    };
+
+    const endpoint: NetEndpoint = {
+      poll: () => [...queue.drain(), ...terminalEvents.splice(0)],
+      send: (peerId, data) => {
+        if (closed) return locallyClosed ? alreadyClosed() : connectionClosed(peerId);
+        if (peerId !== clientPeerId)
+          return err(
+            new EndpointError({
+              code: 'peer-not-found',
+              expected: ENDPOINT_EXPECTED['peer-not-found'],
+              hint: ENDPOINT_ERROR_HINTS['peer-not-found'],
+              detail: { peerId },
+            }),
+          );
+        if (socket.readyState !== socket.OPEN)
+          return err(
+            new EndpointError({
+              code: 'connection-closed',
+              expected: ENDPOINT_EXPECTED['connection-closed'],
+              hint: ENDPOINT_ERROR_HINTS['connection-closed'],
+              detail: { peerId },
+            }),
+          );
+        try {
+          socket.send(data);
+          return ok(undefined);
+        } catch (cause) {
+          return err(
+            new EndpointError({
+              code: 'send-failed',
+              expected: ENDPOINT_EXPECTED['send-failed'],
+              hint: ENDPOINT_ERROR_HINTS['send-failed'],
+              detail: { peerId, cause: normalizeCause(cause) },
+            }),
+          );
+        }
+      },
+      close: () => {
+        if (closed)
+          return err(
+            new EndpointError({
+              code: 'already-closed',
+              expected: ENDPOINT_EXPECTED['already-closed'],
+              hint: ENDPOINT_ERROR_HINTS['already-closed'],
+              detail: { cause: 'The WebSocket endpoint is already closed.' },
+            }),
+          );
+        locallyClosed = true;
+        disconnect('Endpoint close requested.');
+        socket.close();
+        return ok(undefined);
+      },
+    };
+
+    socket.onopen = () => {
+      if (settled) return;
+      removeAbortListener();
+      opened = true;
+      settled = true;
+      queue.enqueue({ kind: 'peer-connected', peerId: clientPeerId });
+      resolve(ok(endpoint));
+    };
+    socket.onmessage = ({ data }) => {
+      // Blob.arrayBuffer() is asynchronous. Serialize conversion so that
+      // ordered WebSocket messages retain their wire order after decoding.
+      messageTail = messageTail
+        .then(async () => {
+          const bytes = await options.toBytes(data);
+          if (!bytes || closed) return;
+          if (!queue.enqueue({ kind: 'message', peerId: clientPeerId, data: bytes })) {
+            socket.close();
+          }
+        })
+        .catch(() => undefined);
+    };
+    socket.onerror = (cause) => {
+      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;
+      }
+      disconnect(`WebSocket closed: ${normalizeCause(cause)}`);
+    };
+  });
+}
+
+function connectionFailed(address: string, cause: unknown): Result<never, EndpointError> {
+  return err(
+    new EndpointError({
+      code: 'connection-failed',
+      expected: ENDPOINT_EXPECTED['connection-failed'],
+      hint: ENDPOINT_ERROR_HINTS['connection-failed'],
+      detail: { address, cause: normalizeCause(cause) },
+    }),
+  );
+}
+
+function alreadyClosed(): Result<never, EndpointError> {
+  return err(
+    new EndpointError({
+      code: 'already-closed',
+      expected: ENDPOINT_EXPECTED['already-closed'],
+      hint: ENDPOINT_ERROR_HINTS['already-closed'],
+      detail: { cause: 'The WebSocket endpoint is closed.' },
+    }),
+  );
+}
+
+function connectionClosed(peerId: PeerId): Result<never, EndpointError> {
+  return err(
+    new EndpointError({
+      code: 'connection-closed',
+      expected: ENDPOINT_EXPECTED['connection-closed'],
+      hint: ENDPOINT_ERROR_HINTS['connection-closed'],
+      detail: { peerId },
+    }),
+  );
+}
+
+function normalizeCause(cause: unknown): string {
+  if (cause instanceof Error) return cause.message;
+  if (typeof cause === 'string') return cause;
+  return 'WebSocket operation failed without a platform error message.';
+}

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,
+      });
+    },
+  };
+}