@forgeax/engine-net-websocket 0.1.2

package/src/node.ts

@@ -0,0 +1,201 @@
+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 { createWebSocketClientEndpoint } from './websocket-client-core';
+
+export interface ListenWebSocketEndpointOptions {
+  readonly port: number;
+  readonly host?: string;
+  readonly maxPeers?: number;
+  readonly maxQueuedEvents?: number | undefined;
+}
+
+export interface ConnectWebSocketClientEndpointOptions {
+  readonly maxQueuedEvents?: number | undefined;
+}
+
+export function connectWebSocketClientEndpoint(
+  url: string,
+  options: ConnectWebSocketClientEndpointOptions = {},
+): Promise<Result<NetEndpoint, EndpointError>> {
+  return createWebSocketClientEndpoint(
+    WebSocket as unknown as import('./websocket-client-core').WebSocketConstructor,
+    {
+      url,
+      maxQueuedEvents: options.maxQueuedEvents,
+      toBytes: toBytes,
+    },
+  );
+}
+
+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,203 @@
+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 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) => {
+    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 disconnect = (reason: string): void => {
+      if (closed) return;
+      closed = true;
+      queue.close(reason);
+      terminalEvents.push({ kind: 'peer-disconnected', peerId: CLIENT_PEER_ID });
+    };
+
+    const endpoint: NetEndpoint = {
+      poll: () => [...queue.drain(), ...terminalEvents.splice(0)],
+      send: (peerId, data) => {
+        if (closed) return locallyClosed ? alreadyClosed() : connectionClosed(peerId);
+        if (peerId !== CLIENT_PEER_ID)
+          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;
+      opened = true;
+      settled = true;
+      queue.enqueue({ kind: 'peer-connected', peerId: CLIENT_PEER_ID });
+      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: CLIENT_PEER_ID, data: bytes })) {
+            socket.close();
+          }
+        })
+        .catch(() => undefined);
+    };
+    socket.onerror = (cause) => {
+      if (opened) disconnect(`WebSocket error: ${normalizeCause(cause)}`);
+      else if (!settled) {
+        settled = true;
+        resolve(connectionFailed(options.url, cause));
+      }
+    };
+    socket.onclose = (cause) => {
+      if (!opened && !settled) {
+        settled = true;
+        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.';
+}