@api.global/typedsocket 5.1.2 → 6.0.0

package/ts/typedsocket.classes.typedsocket.ts

@@ -1,1156 +0,0 @@
-import * as plugins from './typedsocket.plugins.js';
-
-export type TTypedSocketSide = 'server' | 'client';
-export type TConnectionStatus = 'new' | 'connecting' | 'connected' | 'disconnected' | 'reconnecting';
-
-const TAG_PREFIX = '__typedsocket_tag__';
-
-/**
- * Internal TypedRequest interfaces for tag management
- */
-interface IReq_SetClientTag extends plugins.typedrequestInterfaces.ITypedRequest {
-  method: '__typedsocket_setTag';
-  request: { name: string; payload: any };
-  response: { success: boolean };
-}
-
-interface IReq_RemoveClientTag extends plugins.typedrequestInterfaces.ITypedRequest {
-  method: '__typedsocket_removeTag';
-  request: { name: string };
-  response: { success: boolean };
-}
-
-/**
- * Options for creating a TypedSocket client
- */
-export interface ITypedSocketClientOptions {
-  autoReconnect?: boolean;
-  maxRetries?: number;
-  initialBackoffMs?: number;
-  maxBackoffMs?: number;
-  abortSignal?: AbortSignal;
-}
-
-/**
- * Lifecycle controls for one TypedRequest sent over a TypedSocket.
- */
-export interface ITypedSocketRequestOptions {
-  timeoutMs?: number;
-  abortSignal?: AbortSignal;
-}
-
-export type TTypedSocketServerRouterInput =
-  | plugins.typedrequest.TypedRouter
-  | readonly plugins.typedrequest.TypedRouter[];
-
-interface IPendingServerRequest {
-  peerId: string;
-  cancel: (errorArg: Error) => void;
-  cleanupComplete: Promise<void>;
-}
-
-interface IComposedAbortSignal {
-  signal?: AbortSignal;
-  cleanup: () => void;
-}
-
-/**
- * Wrapper for SmartServe's IWebSocketPeer to provide tag compatibility
- */
-export interface ISmartServeConnectionWrapper {
-  peer: plugins.IWebSocketPeer;
-  getTagById(tagId: string): Promise<{ id: string; payload: any } | undefined>;
-}
-
-/**
- * Creates a wrapper around IWebSocketPeer for tag compatibility
- */
-function wrapSmartServePeer(peer: plugins.IWebSocketPeer): ISmartServeConnectionWrapper {
-  return {
-    peer,
-    async getTagById(tagId: string): Promise<{ id: string; payload: any } | undefined> {
-      if (!peer.tags.has(tagId)) {
-        return undefined;
-      }
-      const payload = peer.data.get(`${TAG_PREFIX}${tagId}`);
-      return { id: tagId, payload };
-    },
-  };
-}
-
-function composeAbortSignals(
-  configuredSignalArg?: AbortSignal,
-  requestSignalArg?: AbortSignal,
-): IComposedAbortSignal {
-  if (!configuredSignalArg || configuredSignalArg === requestSignalArg) {
-    return {
-      signal: requestSignalArg ?? configuredSignalArg,
-      cleanup: () => {},
-    };
-  }
-  if (!requestSignalArg) {
-    return {
-      signal: configuredSignalArg,
-      cleanup: () => {},
-    };
-  }
-
-  const abortController = new AbortController();
-  const configuredAbortListener = () => {
-    abortController.abort(configuredSignalArg.reason);
-  };
-  const requestAbortListener = () => {
-    abortController.abort(requestSignalArg.reason);
-  };
-  const cleanup = () => {
-    configuredSignalArg.removeEventListener('abort', configuredAbortListener);
-    requestSignalArg.removeEventListener('abort', requestAbortListener);
-  };
-
-  if (configuredSignalArg.aborted) {
-    configuredAbortListener();
-  } else if (requestSignalArg.aborted) {
-    requestAbortListener();
-  } else {
-    configuredSignalArg.addEventListener('abort', configuredAbortListener, { once: true });
-    requestSignalArg.addEventListener('abort', requestAbortListener, { once: true });
-  }
-
-  return {
-    signal: abortController.signal,
-    cleanup,
-  };
-}
-
-export class TypedSocket {
-  // ============================================================================
-  // STATIC METHODS
-  // ============================================================================
-
-  /**
-   * Creates a TypedSocket client using native WebSocket.
-   * Works in both browser and Node.js environments.
-   *
-   * @param typedrouterArg - TypedRouter for handling server-initiated requests
-   * @param serverUrlArg - Server URL (e.g., 'http://localhost:3000' or 'wss://example.com')
-   * @param options - Connection options
-   *
-   * @example
-   * ```typescript
-   * const typedRouter = new TypedRouter();
-   * const client = await TypedSocket.createClient(
-   *   typedRouter,
-   *   'http://localhost:3000',
-   *   { autoReconnect: true }
-   * );
-   * ```
-   */
-  public static async createClient(
-    typedrouterArg: plugins.typedrequest.TypedRouter,
-    serverUrlArg: string,
-    options: ITypedSocketClientOptions = {}
-  ): Promise<TypedSocket> {
-    const defaultOptions: Omit<Required<ITypedSocketClientOptions>, 'abortSignal'> = {
-      autoReconnect: true,
-      maxRetries: 100,
-      initialBackoffMs: 1000,
-      maxBackoffMs: 60000,
-    };
-    const opts = { ...defaultOptions, ...options };
-
-    const typedSocket = new TypedSocket('client', typedrouterArg);
-    typedSocket.clientOptions = opts;
-    typedSocket.serverUrl = serverUrlArg;
-    typedSocket.currentBackoff = opts.initialBackoffMs;
-
-    if (opts.abortSignal?.aborted) {
-      throw typedSocket.createAbortError();
-    }
-    if (opts.abortSignal) {
-      typedSocket.abortSignalListener = () => {
-        void typedSocket.stop();
-      };
-      opts.abortSignal.addEventListener('abort', typedSocket.abortSignalListener, { once: true });
-    }
-
-    try {
-      await typedSocket.connect();
-    } catch (error) {
-      await typedSocket.stop();
-      throw error;
-    }
-
-    return typedSocket;
-  }
-
-  /**
-   * Returns the current window location origin URL.
-   * Useful in browser environments for connecting to the same origin.
-   */
-  public static useWindowLocationOriginUrl = (): string => {
-    return plugins.smarturl.Smarturl.createFromUrl(globalThis.location.origin).toString();
-  };
-
-  /**
-   * Creates a server-side TypedSocket and composes its private protocol
-   * handlers into one or more isolated application routers.
-   *
-   * Call attachSmartServe() after constructing the SmartServe transport.
-   */
-  public static createServer(
-    typedRouterOrRoutersArg: TTypedSocketServerRouterInput,
-  ): TypedSocket {
-    const typedRouters = Array.isArray(typedRouterOrRoutersArg)
-      ? [...typedRouterOrRoutersArg]
-      : [typedRouterOrRoutersArg];
-    if (typedRouters.length === 0) {
-      throw new Error('TypedSocket.createServer requires at least one TypedRouter.');
-    }
-    if (new Set(typedRouters).size !== typedRouters.length) {
-      throw new Error('TypedSocket.createServer received the same TypedRouter more than once.');
-    }
-
-    const protocolRouter = new plugins.typedrequest.TypedRouter();
-    TypedSocket.registerTagHandlers(protocolRouter);
-    const protocolMethods = new Set(protocolRouter.getMethodNames());
-    for (const typedRouter of typedRouters) {
-      const collision = typedRouter
-        .getMethodNames()
-        .find((methodArg) => protocolMethods.has(methodArg));
-      if (collision) {
-        throw new Error(
-          `TypedSocket protocol handler collides with application method "${collision}".`,
-        );
-      }
-    }
-    const detachProtocolRouters: Array<() => void> = [];
-    try {
-      for (const typedRouter of typedRouters) {
-        detachProtocolRouters.push(typedRouter.addFallbackRouter(protocolRouter));
-      }
-    } catch (error) {
-      for (const detachProtocolRouter of detachProtocolRouters.reverse()) {
-        detachProtocolRouter();
-      }
-      throw error;
-    }
-
-    const typedSocket = new TypedSocket('server', typedRouters[0]);
-    typedSocket.serverTypedRouters = typedRouters;
-    typedSocket.detachProtocolRouters = detachProtocolRouters;
-    return typedSocket;
-  }
-
-  /**
-   * Creates and attaches a TypedSocket server to an existing SmartServe
-   * instance. Prefer createServer() plus attachSmartServe() when transport
-   * construction needs the composed routers first.
-   *
-   * @param smartServeArg - SmartServe instance configured with the application router
-   * @param typedRouterArg - Application TypedRouter used by SmartServe
-   *
-   * @example
-   * ```typescript
-   * const typedRouter = new TypedRouter();
-   * const smartServe = new SmartServe({
-   *   port: 3000,
-   *   websocket: {
-   *     typedRouter,
-   *     onConnectionOpen: (peer) => peer.tags.add('client')
-   *   }
-   * });
-   * await smartServe.start();
-   * const typedSocket = TypedSocket.fromSmartServe(smartServe, typedRouter);
-   * ```
-   */
-  public static fromSmartServe(
-    smartServeArg: plugins.SmartServe,
-    typedRouterArg: TTypedSocketServerRouterInput,
-  ): TypedSocket {
-    return TypedSocket
-      .createServer(typedRouterArg)
-      .attachSmartServe(smartServeArg);
-  }
-
-  /**
-   * Registers built-in TypedHandlers for tag management
-   */
-  private static registerTagHandlers(typedRouter: plugins.typedrequest.TypedRouter): void {
-    // Set tag handler
-    typedRouter.addTypedHandler<IReq_SetClientTag>(
-      new plugins.typedrequest.TypedHandler('__typedsocket_setTag', async (data, meta) => {
-        const peer = meta?.localData?.peer as plugins.IWebSocketPeer;
-        if (!peer) {
-          console.warn('setTag: No peer found in request context');
-          return { success: false };
-        }
-
-        peer.tags.add(data.name);
-        peer.data.set(`${TAG_PREFIX}${data.name}`, data.payload);
-
-        return { success: true };
-      })
-    );
-
-    // Remove tag handler
-    typedRouter.addTypedHandler<IReq_RemoveClientTag>(
-      new plugins.typedrequest.TypedHandler('__typedsocket_removeTag', async (data, meta) => {
-        const peer = meta?.localData?.peer as plugins.IWebSocketPeer;
-        if (!peer) {
-          console.warn('removeTag: No peer found in request context');
-          return { success: false };
-        }
-
-        peer.tags.delete(data.name);
-        peer.data.delete(`${TAG_PREFIX}${data.name}`);
-
-        return { success: true };
-      })
-    );
-  }
-
-  // ============================================================================
-  // INSTANCE PROPERTIES
-  // ============================================================================
-
-  public readonly side: TTypedSocketSide;
-  public readonly typedrouter: plugins.typedrequest.TypedRouter;
-
-  // Connection status observable
-  public statusSubject = new plugins.smartrx.rxjs.Subject<TConnectionStatus>();
-  private connectionStatus: TConnectionStatus = 'new';
-
-  // Client-specific properties
-  private websocket: WebSocket | null = null;
-  private clientOptions: (Omit<Required<ITypedSocketClientOptions>, 'abortSignal'> & Pick<ITypedSocketClientOptions, 'abortSignal'>) | null = null;
-  private serverUrl: string = '';
-  private retryCount = 0;
-  private currentBackoff = 1000;
-  private stopped = false;
-  private abortSignalListener?: () => void;
-  private stopListeners = new Set<() => void>();
-  private pendingRequests = new Map<string, {
-    resolve: (response: any) => void;
-    reject: (error: Error) => void;
-  }>();
-  // Tags set via setTag(), kept client-side so reconnects can restore them on
-  // the fresh server-side connection (server tags die with the old socket).
-  private clientTags = new Map<string, unknown>();
-  private clientTagMutations = new Map<string, symbol>();
-
-  // Server-specific properties (SmartServe mode)
-  private smartServeRef: plugins.SmartServe | null = null;
-  private serverTypedRouters: plugins.typedrequest.TypedRouter[] = [];
-  private detachProtocolRouters: Array<() => void> = [];
-  private serverStopping = false;
-  private unsubscribeSmartServeConnectionClose: (() => void) | null = null;
-  private pendingServerRequests = new Map<string, IPendingServerRequest>();
-  private pendingServerRequestIdsByPeerId = new Map<string, Set<string>>();
-
-  // ============================================================================
-  // CONSTRUCTOR
-  // ============================================================================
-
-  private constructor(
-    sideArg: TTypedSocketSide,
-    typedrouterArg: plugins.typedrequest.TypedRouter
-  ) {
-    this.side = sideArg;
-    this.typedrouter = typedrouterArg;
-  }
-
-  /**
-   * Attaches the SmartServe transport after server router composition.
-   */
-  public attachSmartServe(smartServeArg: plugins.SmartServe): this {
-    if (this.side !== 'server') {
-      throw new Error('attachSmartServe is only available on servers.');
-    }
-    if (this.serverStopping) {
-      throw new Error('Cannot attach SmartServe after the TypedSocket server has stopped.');
-    }
-    if (this.smartServeRef) {
-      if (this.smartServeRef === smartServeArg) {
-        return this;
-      }
-      throw new Error('TypedSocket server is already attached to a SmartServe instance.');
-    }
-
-    const unsubscribe = smartServeArg.subscribeWebSocketConnectionClose((peerArg) => {
-      this.cancelPendingServerRequestsForPeer(
-        peerArg.id,
-        new Error(`TypedSocket target connection closed: ${peerArg.id}`),
-      );
-    });
-    this.smartServeRef = smartServeArg;
-    this.unsubscribeSmartServeConnectionClose = unsubscribe;
-    return this;
-  }
-
-  // ============================================================================
-  // CLIENT METHODS
-  // ============================================================================
-
-  /**
-   * Connects the client to the server using native WebSocket
-   */
-  private async connect(): Promise<void> {
-    if (this.stopped || this.clientOptions?.abortSignal?.aborted) {
-      throw this.createAbortError();
-    }
-
-    const done = plugins.smartpromise.defer<void>();
-    let connectionSettled = false;
-    let connectionTimeout: ReturnType<typeof setTimeout> | undefined;
-    let abortConnection: (() => void) | undefined;
-
-    const settleConnection = (errorArg?: Error) => {
-      if (connectionSettled) {
-        return;
-      }
-      connectionSettled = true;
-      if (connectionTimeout) {
-        clearTimeout(connectionTimeout);
-      }
-      if (abortConnection) {
-        this.stopListeners.delete(abortConnection);
-        this.clientOptions?.abortSignal?.removeEventListener('abort', abortConnection);
-      }
-      if (errorArg) {
-        done.reject(errorArg);
-      } else {
-        done.resolve();
-      }
-    };
-
-    this.updateStatus('connecting');
-
-    // Convert HTTP URL to WebSocket URL
-    const wsUrl = this.toWebSocketUrl(this.serverUrl);
-    this.logDebug(`TypedSocket connecting to ${wsUrl}...`);
-
-    this.websocket = new WebSocket(wsUrl);
-
-    abortConnection = () => {
-      this.websocket?.close();
-      settleConnection(this.createAbortError());
-    };
-    this.stopListeners.add(abortConnection);
-    this.clientOptions?.abortSignal?.addEventListener('abort', abortConnection, { once: true });
-
-    connectionTimeout = setTimeout(() => {
-      if (this.connectionStatus !== 'connected') {
-        this.logTransient(`TypedSocket connection timeout for ${wsUrl}`);
-        this.websocket?.close();
-        settleConnection(new Error('Connection timeout'));
-      }
-    }, 10000);
-
-    this.websocket.onopen = async () => {
-      const openedWebsocket = this.websocket;
-      try {
-        await this.reapplyClientTags();
-        if (this.websocket !== openedWebsocket || openedWebsocket?.readyState !== WebSocket.OPEN) {
-          throw new Error('TypedSocket connection changed while restoring client tags');
-        }
-        this.logDebug('TypedSocket connected and client registration restored!');
-        this.retryCount = 0;
-        this.currentBackoff = this.clientOptions?.initialBackoffMs ?? 1000;
-        this.updateStatus('connected');
-        settleConnection();
-      } catch (error) {
-        const restorationError = error instanceof Error
-          ? error
-          : new Error(String(error));
-        this.logTransient(`TypedSocket client registration restoration failed: ${restorationError.message}`);
-        settleConnection(restorationError);
-        openedWebsocket?.close();
-      }
-    };
-
-    this.websocket.onmessage = async (event) => {
-      await this.handleMessage(event.data);
-    };
-
-    this.websocket.onclose = () => {
-      if (this.connectionStatus === 'connected') {
-        this.handleDisconnect();
-      } else {
-        this.rejectPendingClientRequests(new Error('TypedSocket disconnected'));
-        settleConnection(this.stopped || this.clientOptions?.abortSignal?.aborted
-          ? this.createAbortError()
-          : new Error('TypedSocket connection closed before it opened'));
-      }
-    };
-
-    this.websocket.onerror = () => {
-      // transient socket errors (network blips, proxy TLS hiccups) are expected
-      // and handled by reconnection; only exhausted retries surface as errors
-      this.logTransient(`TypedSocket websocket error on ${wsUrl}`);
-    };
-
-    try {
-      await done.promise;
-    } catch (err) {
-      if (connectionTimeout) {
-        clearTimeout(connectionTimeout);
-      }
-      if (this.shouldReconnect()) {
-        await this.scheduleReconnect();
-        if (this.connectionStatus !== 'connected') {
-          throw this.stopped || this.clientOptions?.abortSignal?.aborted ? this.createAbortError() : err;
-        }
-      } else {
-        throw err;
-      }
-    }
-  }
-
-  /**
-   * Converts an HTTP(S) URL to a WebSocket URL
-   */
-  private toWebSocketUrl(url: string): string {
-    const parsed = new URL(url);
-    const wsProtocol = (() => {
-      switch (parsed.protocol) {
-        case 'http:':
-        case 'ws:':
-          return 'ws:';
-        case 'https:':
-        case 'wss:':
-          return 'wss:';
-        default:
-          throw new Error('TypedSocket server URL must use http, https, ws, or wss.');
-      }
-    })();
-    return `${wsProtocol}//${parsed.host}${parsed.pathname}`;
-  }
-
-  /**
-   * Handles incoming WebSocket messages
-   */
-  private async handleMessage(data: string | ArrayBuffer): Promise<void> {
-    try {
-      const messageText = typeof data === 'string' ? data : new TextDecoder().decode(data);
-      const message = plugins.smartjson.parse(messageText) as plugins.typedrequestInterfaces.ITypedRequest;
-
-      // Check if this is a response to a pending request
-      if (message.correlation?.id && this.pendingRequests.has(message.correlation.id)) {
-        const pending = this.pendingRequests.get(message.correlation.id)!;
-        this.pendingRequests.delete(message.correlation.id);
-        pending.resolve(message);
-        return;
-      }
-
-      // Server-initiated request - route through TypedRouter
-      const response = await this.typedrouter.routeAndAddResponse(message);
-      if (response && this.websocket?.readyState === WebSocket.OPEN) {
-        this.websocket.send(plugins.smartjson.stringify(response));
-      }
-    } catch (err) {
-      console.error('TypedSocket failed to process message:', err);
-    }
-  }
-
-  /**
-   * Handles WebSocket disconnection
-   */
-  private handleDisconnect(): void {
-    if (this.connectionStatus === 'disconnected') {
-      return; // Already handled
-    }
-
-    this.updateStatus('disconnected');
-
-    // Reject all pending requests — the connection is gone and they'll never receive a response
-    this.rejectPendingClientRequests(new Error('TypedSocket disconnected'));
-
-    if (this.shouldReconnect()) {
-      this.scheduleReconnect();
-    }
-  }
-
-  /**
-   * Schedules a reconnection attempt with exponential backoff
-   */
-  private async scheduleReconnect(): Promise<void> {
-    if (!this.shouldReconnect()) return;
-    const clientOptions = this.clientOptions!;
-
-    this.updateStatus('reconnecting');
-    this.retryCount++;
-
-    // Exponential backoff with jitter
-    const jitter = this.currentBackoff * 0.2 * (Math.random() * 2 - 1);
-    const delay = Math.min(this.currentBackoff + jitter, clientOptions.maxBackoffMs);
-
-    this.logDebug(`TypedSocket reconnecting in ${Math.round(delay)}ms (attempt ${this.retryCount}/${clientOptions.maxRetries})`);
-
-    await this.waitForReconnectDelay(delay);
-
-    if (!this.shouldReconnect()) return;
-
-    // Increase backoff for next time
-    this.currentBackoff = Math.min(this.currentBackoff * 2, clientOptions.maxBackoffMs);
-
-    try {
-      await this.connect();
-    } catch (err) {
-      if (this.shouldReconnect()) {
-        this.logDebug(`TypedSocket reconnection attempt failed: ${err instanceof Error ? err.message : String(err)}`);
-      } else if (!this.stopped && !this.clientOptions?.abortSignal?.aborted) {
-        console.error(
-          `TypedSocket giving up on ${this.serverUrl} after ${this.retryCount} attempts:`,
-          err instanceof Error ? err.message : err,
-        );
-      }
-    }
-  }
-
-  /**
-   * Lifecycle chatter: hidden by default in browser devtools (verbose level)
-   * and irrelevant for servers, but available when debugging.
-   */
-  private logDebug(messageArg: string) {
-    console.debug(messageArg);
-  }
-
-  /**
-   * Failures that reconnection is expected to recover from. Logged as debug
-   * while retries remain; the final failure is reported by scheduleReconnect.
-   */
-  private logTransient(messageArg: string) {
-    if (this.shouldReconnect()) {
-      this.logDebug(messageArg);
-    } else if (!this.stopped && !this.clientOptions?.abortSignal?.aborted) {
-      console.warn(messageArg);
-    }
-  }
-
-  private shouldReconnect(): boolean {
-    return Boolean(
-      this.clientOptions?.autoReconnect &&
-      !this.stopped &&
-      !this.clientOptions.abortSignal?.aborted &&
-      this.retryCount < this.clientOptions.maxRetries,
-    );
-  }
-
-  private async waitForReconnectDelay(delayMsArg: number): Promise<void> {
-    await new Promise<void>((resolve) => {
-      let timeout: ReturnType<typeof setTimeout> | undefined;
-      let finished = false;
-      const finish = () => {
-        if (finished) return;
-        finished = true;
-        if (timeout) {
-          clearTimeout(timeout);
-        }
-        this.stopListeners.delete(finish);
-        this.clientOptions?.abortSignal?.removeEventListener('abort', finish);
-        resolve();
-      };
-      if (this.clientOptions?.abortSignal?.aborted) {
-        finish();
-        return;
-      }
-      if (this.stopped) {
-        finish();
-        return;
-      }
-      timeout = setTimeout(finish, delayMsArg);
-      this.stopListeners.add(finish);
-      this.clientOptions?.abortSignal?.addEventListener('abort', finish, { once: true });
-    });
-  }
-
-  private createAbortError(): Error {
-    return new Error('TypedSocket client startup aborted');
-  }
-
-  private rejectPendingClientRequests(errorArg: Error): void {
-    for (const pending of this.pendingRequests.values()) {
-      pending.reject(errorArg);
-    }
-    this.pendingRequests.clear();
-  }
-
-  /**
-   * Updates connection status and notifies subscribers
-   */
-  private updateStatus(status: TConnectionStatus): void {
-    if (this.connectionStatus !== status) {
-      this.connectionStatus = status;
-      this.statusSubject.next(status);
-    }
-  }
-
-  /**
-   * Sends a request to the server and waits for response (client-side)
-   */
-  private async sendRequest<T extends plugins.typedrequestInterfaces.ITypedRequest>(
-    request: T,
-    optionsArg: ITypedSocketRequestOptions = {},
-  ): Promise<T> {
-    if (!this.websocket || this.websocket.readyState !== WebSocket.OPEN) {
-      throw new Error('WebSocket not connected');
-    }
-
-    const timeoutMs = this.normalizeRequestTimeout(optionsArg.timeoutMs);
-    if (optionsArg.abortSignal?.aborted) {
-      throw new Error('TypedSocket request aborted');
-    }
-
-    request.correlation ||= {
-      id: plugins.smartstring.create.createCryptoRandomString(),
-      phase: 'request',
-    };
-    const correlationId = request.correlation.id;
-
-    return new Promise((resolve, reject) => {
-      let settled = false;
-      const cleanup = () => {
-        clearTimeout(timeout);
-        optionsArg.abortSignal?.removeEventListener('abort', onAbort);
-        this.pendingRequests.delete(correlationId);
-      };
-      const settle = (errorArg?: Error, responseArg?: T) => {
-        if (settled) {
-          return;
-        }
-        settled = true;
-        cleanup();
-        if (errorArg) {
-          reject(errorArg);
-        } else {
-          resolve(responseArg!);
-        }
-      };
-      const onAbort = () => settle(new Error('TypedSocket request aborted'));
-      const timeout = setTimeout(() => {
-        settle(new Error('TypedSocket request timed out'));
-      }, timeoutMs);
-
-      this.pendingRequests.set(correlationId, {
-        resolve: (response) => {
-          settle(undefined, response as T);
-        },
-        reject: (error) => {
-          settle(error);
-        },
-      });
-      optionsArg.abortSignal?.addEventListener('abort', onAbort, { once: true });
-      if (optionsArg.abortSignal?.aborted) {
-        onAbort();
-        return;
-      }
-
-      try {
-        this.websocket!.send(plugins.smartjson.stringify(request));
-      } catch (error) {
-        settle(error instanceof Error ? error : new Error(String(error)));
-      }
-    });
-  }
-
-  private normalizeRequestTimeout(timeoutMsArg: number | undefined): number {
-    const timeoutMs = timeoutMsArg ?? 30000;
-    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
-      throw new Error('TypedSocket request timeout must be a finite non-negative number');
-    }
-    return timeoutMs;
-  }
-
-  private cancelPendingServerRequestsForPeer(peerIdArg: string, errorArg: Error): void {
-    const correlationIds = this.pendingServerRequestIdsByPeerId.get(peerIdArg);
-    if (!correlationIds) {
-      return;
-    }
-    for (const correlationId of Array.from(correlationIds)) {
-      this.pendingServerRequests.get(correlationId)?.cancel(errorArg);
-    }
-  }
-
-  private async sendServerRequest<T extends plugins.typedrequestInterfaces.ITypedRequest>(
-    typedRequestDataArg: T,
-    targetArg: ISmartServeConnectionWrapper,
-    optionsArg: ITypedSocketRequestOptions,
-  ): Promise<T> {
-    const timeoutMs = this.normalizeRequestTimeout(optionsArg.timeoutMs);
-    if (this.serverStopping || !this.smartServeRef) {
-      throw new Error('TypedSocket server stopped');
-    }
-    if (optionsArg.abortSignal?.aborted) {
-      throw new Error('TypedSocket request aborted');
-    }
-
-    typedRequestDataArg.correlation ||= {
-      id: plugins.smartstring.create.createCryptoRandomString(),
-      phase: 'request',
-    };
-    const correlationId = typedRequestDataArg.correlation.id;
-    const peerId = targetArg.peer.id;
-    if (this.pendingServerRequests.has(correlationId)) {
-      throw new Error(`Duplicate in-flight TypedSocket correlation ID: ${correlationId}`);
-    }
-    const cancellation = plugins.smartpromise.defer<never>();
-    // A stop/abort may happen while InterestMap.addInterest is yielding. Attach
-    // a rejection handler immediately; Promise.race below still receives the
-    // original rejection once the interest exists.
-    void cancellation.promise.catch(() => {});
-    const cleanup = plugins.smartpromise.defer<void>();
-    let cancellationRequested = false;
-    const cancel = (errorArg: Error) => {
-      if (cancellationRequested) {
-        return;
-      }
-      cancellationRequested = true;
-      cancellation.reject(errorArg);
-    };
-    const pendingRequest: IPendingServerRequest = {
-      peerId,
-      cancel,
-      cleanupComplete: cleanup.promise,
-    };
-    this.pendingServerRequests.set(correlationId, pendingRequest);
-    const requestsForPeer = this.pendingServerRequestIdsByPeerId.get(peerId) ?? new Set<string>();
-    requestsForPeer.add(correlationId);
-    this.pendingServerRequestIdsByPeerId.set(peerId, requestsForPeer);
-
-    const onAbort = () => cancel(new Error('TypedSocket request aborted'));
-    const timeout = setTimeout(
-      () => cancel(new Error(`TypedSocket request timed out after ${timeoutMs}ms`)),
-      timeoutMs,
-    );
-    optionsArg.abortSignal?.addEventListener('abort', onAbort, { once: true });
-    if (optionsArg.abortSignal?.aborted) {
-      onAbort();
-    }
-
-    const destroyInterests: Array<() => void> = [];
-    try {
-      const interestPromises: Array<Promise<T>> = [];
-      for (const typedRouter of this.serverTypedRouters) {
-        const interestRegistration = typedRouter.fireEventInterestMap
-          .addInterest(correlationId, typedRequestDataArg)
-          .then((interestArg) => {
-            if (cancellationRequested || this.serverStopping) {
-              interestArg.destroy();
-            }
-            return interestArg;
-          });
-        const interest = await Promise.race([
-          interestRegistration,
-          cancellation.promise,
-        ]);
-        if (cancellationRequested || this.serverStopping) {
-          interest.destroy();
-          await cancellation.promise;
-        }
-        destroyInterests.push(() => interest.destroy());
-        interestPromises.push(interest.interestFullfilled as Promise<T>);
-      }
-      // Establish the rejecting race before send so synchronous close/abort and
-      // send failures all use the same cleanup path.
-      const response = Promise.race([
-        ...interestPromises,
-        cancellation.promise,
-      ]);
-      const targetIsStillConnected = this.smartServeRef
-        ?.getWebSocketConnections()
-        .some((peerArg) => peerArg.id === peerId) ?? false;
-      if (!targetIsStillConnected) {
-        cancel(new Error(`TypedSocket target connection closed: ${peerId}`));
-      }
-      if (this.serverStopping) {
-        cancel(new Error('TypedSocket server stopped'));
-      }
-      if (!cancellationRequested && targetIsStillConnected && !this.serverStopping) {
-        targetArg.peer.send(plugins.smartjson.stringify(typedRequestDataArg));
-      }
-      return await response;
-    } finally {
-      clearTimeout(timeout);
-      optionsArg.abortSignal?.removeEventListener('abort', onAbort);
-      this.pendingServerRequests.delete(correlationId);
-      const remainingRequestsForPeer = this.pendingServerRequestIdsByPeerId.get(peerId);
-      remainingRequestsForPeer?.delete(correlationId);
-      if (remainingRequestsForPeer?.size === 0) {
-        this.pendingServerRequestIdsByPeerId.delete(peerId);
-      }
-      for (const destroyInterest of destroyInterests) {
-        destroyInterest();
-      }
-      cleanup.resolve();
-    }
-  }
-
-  // ============================================================================
-  // PUBLIC API - SHARED
-  // ============================================================================
-
-  /**
-   * Creates a TypedRequest for the specified method.
-   * On clients, sends to the server.
-   * On servers, sends to the specified target connection.
-   */
-  public createTypedRequest<T extends plugins.typedrequestInterfaces.ITypedRequest>(
-    methodName: T['method'],
-    targetConnection?: ISmartServeConnectionWrapper,
-    optionsArg: ITypedSocketRequestOptions = {},
-  ): plugins.typedrequest.TypedRequest<T> {
-    const postMethod = async (
-      requestDataArg: plugins.typedrequestInterfaces.ITypedRequest,
-      postOptionsArg: plugins.typedrequest.ITypedTargetPostOptions = {},
-    ): Promise<plugins.typedrequestInterfaces.ITypedRequest> => {
-      const typedRequestData = requestDataArg as T;
-      const composedAbortSignal = composeAbortSignals(
-        optionsArg.abortSignal,
-        postOptionsArg.signal,
-      );
-      const requestOptions: ITypedSocketRequestOptions = {
-        ...optionsArg,
-        abortSignal: composedAbortSignal.signal,
-      };
-
-      try {
-        if (this.side === 'client') {
-          return await this.sendRequest(typedRequestData, requestOptions);
-        }
-
-        // Server-side: send to target connection
-        if (!this.smartServeRef) {
-          throw new Error('Server not initialized');
-        }
-
-        let target = targetConnection;
-        if (!target) {
-          const allConnections = this.smartServeRef.getWebSocketConnections();
-          if (allConnections.length === 1) {
-            const peer = allConnections[0];
-            target = wrapSmartServePeer(peer);
-          } else if (allConnections.length === 0) {
-            throw new Error('No WebSocket connections available');
-          } else {
-            throw new Error('Multiple connections available - specify targetConnection');
-          }
-        }
-
-        return await this.sendServerRequest(typedRequestData, target, requestOptions);
-      } finally {
-        composedAbortSignal.cleanup();
-      }
-    };
-
-    return new plugins.typedrequest.TypedRequest<T>(
-      new plugins.typedrequest.TypedTarget({
-        postMethod,
-        supportsAbortSignal: true,
-      }),
-      methodName
-    );
-  }
-
-  /**
-   * Gets the current connection status
-   */
-  public getStatus(): TConnectionStatus {
-    return this.connectionStatus;
-  }
-
-  /**
-   * Stops the TypedSocket client or cleans up server state
-   */
-  public async stop(): Promise<void> {
-    if (this.side === 'client') {
-      this.stopped = true;
-      for (const stopListener of Array.from(this.stopListeners)) {
-        stopListener();
-      }
-      this.stopListeners.clear();
-      if (this.clientOptions) {
-        this.clientOptions.autoReconnect = false;
-        if (this.clientOptions.abortSignal && this.abortSignalListener) {
-          this.clientOptions.abortSignal.removeEventListener('abort', this.abortSignalListener);
-        }
-      }
-      this.abortSignalListener = undefined;
-      if (this.websocket) {
-        this.websocket.close();
-        this.websocket = null;
-      }
-      for (const pendingRequest of this.pendingRequests.values()) {
-        pendingRequest.reject(new Error('TypedSocket stopped'));
-      }
-      this.pendingRequests.clear();
-    } else {
-      this.serverStopping = true;
-      const pendingRequests = Array.from(this.pendingServerRequests.values());
-      for (const pendingRequest of pendingRequests) {
-        pendingRequest.cancel(new Error('TypedSocket server stopped'));
-      }
-      await Promise.all(pendingRequests.map((pendingRequest) => pendingRequest.cleanupComplete));
-      this.unsubscribeSmartServeConnectionClose?.();
-      this.unsubscribeSmartServeConnectionClose = null;
-      this.smartServeRef = null;
-      for (const detachProtocolRouter of this.detachProtocolRouters.reverse()) {
-        detachProtocolRouter();
-      }
-      this.detachProtocolRouters = [];
-    }
-  }
-
-  // ============================================================================
-  // CLIENT-ONLY METHODS
-  // ============================================================================
-
-  /**
-   * Sets a tag on this client connection.
-   * Tags are stored on the server and can be used for filtering.
-   * @client-only
-   */
-  public async setTag<T extends plugins.typedrequestInterfaces.ITag>(
-    name: T['name'],
-    payload: T['payload']
-  ): Promise<void> {
-    if (this.side !== 'client') {
-      throw new Error('setTag is only available on clients');
-    }
-
-    const mutation = Symbol(name);
-    this.clientTagMutations.set(name, mutation);
-    try {
-      const request = this.createTypedRequest<IReq_SetClientTag>('__typedsocket_setTag');
-      const response = await request.fire({ name, payload });
-
-      if (!response.success) {
-        throw new Error('Failed to set tag on server');
-      }
-      if (this.clientTagMutations.get(name) === mutation) {
-        this.clientTags.set(name, payload);
-      }
-    } finally {
-      if (this.clientTagMutations.get(name) === mutation) {
-        this.clientTagMutations.delete(name);
-      }
-    }
-  }
-
-  /**
-   * Re-applies all client tags after a reconnect, since server-side tags are
-   * bound to the previous connection.
-   */
-  private async reapplyClientTags(): Promise<void> {
-    for (const [name, payload] of this.clientTags) {
-      const request = this.createTypedRequest<IReq_SetClientTag>('__typedsocket_setTag');
-      const response = await request.fire({ name, payload });
-      if (!response.success) {
-        throw new Error(`TypedSocket failed to restore tag ${name} after reconnect`);
-      }
-    }
-  }
-
-  /**
-   * Removes a tag from this client connection.
-   * @client-only
-   */
-  public async removeTag(name: string): Promise<void> {
-    if (this.side !== 'client') {
-      throw new Error('removeTag is only available on clients');
-    }
-
-    const mutation = Symbol(name);
-    this.clientTagMutations.set(name, mutation);
-    this.clientTags.delete(name);
-    try {
-      const request = this.createTypedRequest<IReq_RemoveClientTag>('__typedsocket_removeTag');
-      const response = await request.fire({ name });
-
-      if (!response.success) {
-        throw new Error('Failed to remove tag on server');
-      }
-    } finally {
-      if (this.clientTagMutations.get(name) === mutation) {
-        this.clientTagMutations.delete(name);
-      }
-    }
-  }
-
-  // ============================================================================
-  // SERVER-ONLY METHODS
-  // ============================================================================
-
-  /**
-   * Finds all connections matching the filter function.
-   * @server-only
-   */
-  public async findAllTargetConnections(
-    asyncFindFuncArg: (connectionArg: ISmartServeConnectionWrapper) => Promise<boolean>
-  ): Promise<ISmartServeConnectionWrapper[]> {
-    if (this.side !== 'server' || !this.smartServeRef) {
-      throw new Error('findAllTargetConnections is only available on servers');
-    }
-
-    const matchingConnections: ISmartServeConnectionWrapper[] = [];
-    for (const peer of this.smartServeRef.getWebSocketConnections()) {
-      const wrapper = wrapSmartServePeer(peer);
-      if (await asyncFindFuncArg(wrapper)) {
-        matchingConnections.push(wrapper);
-      }
-    }
-    return matchingConnections;
-  }
-
-  /**
-   * Finds the first connection matching the filter function.
-   * @server-only
-   */
-  public async findTargetConnection(
-    asyncFindFuncArg: (connectionArg: ISmartServeConnectionWrapper) => Promise<boolean>
-  ): Promise<ISmartServeConnectionWrapper | undefined> {
-    const allMatching = await this.findAllTargetConnections(asyncFindFuncArg);
-    return allMatching[0];
-  }
-
-  /**
-   * Finds all connections with the specified tag.
-   * @server-only
-   */
-  public async findAllTargetConnectionsByTag<TTag extends plugins.typedrequestInterfaces.ITag = any>(
-    keyArg: TTag['name'],
-    payloadArg?: TTag['payload']
-  ): Promise<ISmartServeConnectionWrapper[]> {
-    if (this.side !== 'server' || !this.smartServeRef) {
-      throw new Error('findAllTargetConnectionsByTag is only available on servers');
-    }
-
-    const peers = this.smartServeRef.getWebSocketConnectionsByTag(keyArg);
-    const results: ISmartServeConnectionWrapper[] = [];
-
-    for (const peer of peers) {
-      const wrapper = wrapSmartServePeer(peer);
-
-      // If payload specified, also filter by payload
-      if (payloadArg !== undefined) {
-        const tag = await wrapper.getTagById(keyArg);
-        if (plugins.smartjson.stringify(tag?.payload) !== plugins.smartjson.stringify(payloadArg)) {
-          continue;
-        }
-      }
-      results.push(wrapper);
-    }
-    return results;
-  }
-
-  /**
-   * Finds the first connection with the specified tag.
-   * @server-only
-   */
-  public async findTargetConnectionByTag<TTag extends plugins.typedrequestInterfaces.ITag = any>(
-    keyArg: TTag['name'],
-    payloadArg?: TTag['payload']
-  ): Promise<ISmartServeConnectionWrapper | undefined> {
-    const allResults = await this.findAllTargetConnectionsByTag(keyArg, payloadArg);
-    return allResults[0];
-  }
-}