@robota-sdk/agent-transport-ws 3.0.0-beta.100

package/src/ws-transport-configurable.ts

@@ -0,0 +1,337 @@
+/**
+ * Self-contained WS transport implementing IConfigurableTransport.
+ * Owns the WebSocket server lifecycle (ws package), started/stopped via the transport registry.
+ */
+
+import { createServer, type IncomingMessage, type Server } from 'node:http';
+
+import { createSessionMessageHandler } from '@robota-sdk/agent-transport';
+import { WebSocketServer } from 'ws';
+
+import { PayloadChannelRegistry } from './payload-channels.js';
+import {
+  hostAllowed,
+  originAllowed,
+  presentedToken,
+  resolveWsAdmission,
+  tokenMatches,
+} from './ws-connection-guards.js';
+import { toBytes } from './ws-message-data.js';
+import { WsSessionDelivery } from './ws-session-delivery.js';
+import {
+  DEFAULT_MAX_RETRIES,
+  DEFAULT_PORT,
+  configuredWsHandlerOptions,
+  transportLifecycleError,
+  validTransportOptions,
+} from './ws-transport-config.js';
+
+import type { IWsTransportConfig } from './ws-transport-config.js';
+import type { TUniversalValue } from '@robota-sdk/agent-core';
+import type { ISessionBinder, ISessionBinding } from '@robota-sdk/agent-interface-session';
+import type {
+  IChannelDescriptor,
+  IConfigurableTransport,
+  IPayloadChannel,
+  IPayloadChannelHost,
+  TChannelEventMap,
+} from '@robota-sdk/agent-interface-transport';
+import type { IProtocolSession } from '@robota-sdk/agent-transport';
+import type { RawData, WebSocket } from 'ws';
+
+/**
+ * RUNTIME-13: forced-terminate deadline for `stop()`. `WebSocketServer.close()` fires its callback only after
+ * every client socket is gone, so a still-connected client would hang `stop()` forever. We send a close frame
+ * (1001 "going away") to each client, then `terminate()` any socket still open at this deadline — the RFC 6455
+ * + `ws` + drain-then-force convention (a WS close handshake completes in well under a second; 5s is generous).
+ */
+const WS_STOP_TERMINATE_DEADLINE_MS = 5000;
+
+/**
+ * TRANS-001: the WS transport is a payload-agnostic CARRIER that routes by WebSocket frame opcode —
+ * TEXT frames go to the text-agent protocol profile (`createSessionMessageHandler`), BINARY frames go to the
+ * consumer-declared channels. The two profiles share one connection and never constrain each other.
+ */
+export class WsTransport implements IConfigurableTransport<IProtocolSession>, IPayloadChannelHost {
+  readonly name = 'ws';
+  readonly lifecycle = Object.freeze({ kind: 'service' as const });
+  readonly defaultEnabled = true;
+  readonly optionsSchema = {
+    port: { type: 'number', description: 'WebSocket server port', default: DEFAULT_PORT },
+    maxRetries: {
+      type: 'number',
+      description: 'Port retry attempts when port is occupied',
+      default: DEFAULT_MAX_RETRIES,
+    },
+  };
+
+  private session: IProtocolSession | null = null;
+  private stopFn: (() => Promise<void>) | null = null;
+  private state: 'detached' | 'attached' | 'starting' | 'ready' | 'stopping' = 'detached';
+  private startOperation: Promise<{ stop: () => Promise<void>; port: number }> | undefined;
+  private startCancelled = false;
+  private port: number;
+  private maxRetries: number;
+  private readonly token?: string;
+  private readonly allowedHosts: ReadonlySet<string>;
+  private readonly allowedOrigins: ReadonlySet<string>;
+  private readonly handlerOptions: ReturnType<typeof configuredWsHandlerOptions>;
+  private readonly sessionBinder: ISessionBinder<IProtocolSession> | undefined;
+  private readonly channels = new PayloadChannelRegistry();
+  private resolvedPort?: number;
+
+  constructor(config: IWsTransportConfig = {}) {
+    this.port = config.port ?? DEFAULT_PORT;
+    this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+    // SEC-001/SEC-008: secure by default, decided by the shared seam rather than a copy here — see
+    // SPEC § Transport Admission. A failed mint throws out of the constructor (fail-closed).
+    const admission = resolveWsAdmission(config);
+    if (admission.token !== null) this.token = admission.token;
+    this.allowedHosts = new Set(config.allowedHosts ?? []);
+    this.allowedOrigins = new Set(config.allowedOrigins ?? []);
+    this.handlerOptions = configuredWsHandlerOptions(config);
+    this.sessionBinder = config.sessionBinder;
+  }
+
+  attach(session: IProtocolSession): void {
+    this.session = session;
+    this.state = 'attached';
+  }
+
+  /**
+   * TRANS-001: declare an app-level channel carried on this transport's connections. The channel's
+   * events and opaque binary frames ride alongside the text-agent protocol on the SAME socket — the
+   * transport never inspects the payloads. Register before or after `start()`; a channel opened
+   * later is served by every already-connected client.
+   */
+  registerChannel<TEvents extends TChannelEventMap>(
+    descriptor: IChannelDescriptor<TEvents>,
+  ): IPayloadChannel<TEvents> {
+    return this.channels.registerChannel(descriptor);
+  }
+
+  /** Actually-bound port after start; undefined before start. */
+  get boundPort(): number | undefined {
+    return this.resolvedPort;
+  }
+
+  /**
+   * SEC-001: the resolved auth token (explicit or auto-minted), or `undefined` in the discouraged `open`
+   * mode. The surface reads this to deliver the token to the co-located client (a `0600` connection file /
+   * the served monitor's injected `ws-url`). Never logged by the transport itself.
+   */
+  get resolvedToken(): string | undefined {
+    return this.token;
+  }
+
+  async start(): Promise<void> {
+    if (!this.session) throw transportLifecycleError(this.name, 'not-attached');
+    if (this.state === 'starting' || this.state === 'ready' || this.state === 'stopping') {
+      throw transportLifecycleError(this.name, 'already-started');
+    }
+    this.state = 'starting';
+    this.startCancelled = false;
+    const operation = this.bindWithRetry(this.session, this.port, this.maxRetries);
+    this.startOperation = operation;
+    let handle: Awaited<typeof operation>;
+    try {
+      handle = await operation;
+    } catch (error) {
+      if (this.state === 'starting' && this.startOperation === operation) {
+        this.startOperation = undefined;
+        this.state = this.session ? 'attached' : 'detached';
+      }
+      throw error;
+    }
+    if (this.startCancelled || this.startOperation !== operation) {
+      await handle.stop();
+      this.state = this.session ? 'attached' : 'detached';
+      throw new Error('WsTransport startup was stopped.');
+    }
+    this.stopFn = handle.stop;
+    this.resolvedPort = handle.port;
+    this.startOperation = undefined;
+    this.state = 'ready';
+  }
+
+  async stop(): Promise<void> {
+    if (this.state === 'starting') {
+      this.state = 'stopping';
+      this.startCancelled = true;
+      try {
+        await this.startOperation;
+      } catch {
+        // The start caller owns bind failure; stop still clears lifecycle state.
+      }
+    }
+    await this.stopFn?.();
+    this.stopFn = null;
+    this.startOperation = undefined;
+    this.resolvedPort = undefined;
+    this.session = null;
+    this.state = 'detached';
+  }
+
+  /** TRANS-002 (issue #2480): persisted `port`/`maxRetries` reach the server through here, before start. */
+  configure(options: Record<string, TUniversalValue>): void {
+    if (this.state !== 'detached' && this.state !== 'attached') {
+      throw transportLifecycleError(this.name, 'already-started');
+    }
+    if (!this.validateOptions(options)) {
+      throw new TypeError('WsTransport options are invalid (port 1-65535, maxRetries >= 0).');
+    }
+    if (typeof options['port'] === 'number') this.port = options['port'];
+    if (typeof options['maxRetries'] === 'number') this.maxRetries = options['maxRetries'];
+  }
+
+  validateOptions(options: Record<string, TUniversalValue>): boolean {
+    return validTransportOptions(options);
+  }
+
+  /**
+   * The connection's binding, `{ binding: undefined }` without a binder, or `null` when the host
+   * would not bind it (shutting down, say): the socket is then closed before any session data.
+   */
+  private bindConnection(
+    ws: WebSocket,
+  ): { binding: ISessionBinding<IProtocolSession> | undefined } | null {
+    if (!this.sessionBinder) return { binding: undefined };
+    try {
+      return { binding: this.sessionBinder.bind('drive') };
+    } catch {
+      ws.close(1013, 'session unavailable');
+      return null;
+    }
+  }
+
+  private bindWithRetry(
+    session: IProtocolSession,
+    port: number,
+    retriesLeft: number,
+  ): Promise<{ stop: () => Promise<void>; port: number }> {
+    return this.tryBind(session, port).catch((err: NodeJS.ErrnoException) => {
+      if (err.code === 'EADDRINUSE' && retriesLeft > 0)
+        return this.bindWithRetry(session, port + 1, retriesLeft - 1);
+      throw err;
+    });
+  }
+
+  private tryBind(
+    session: IProtocolSession,
+    port: number,
+  ): Promise<{ stop: () => Promise<void>; port: number }> {
+    return new Promise((resolve, reject) => {
+      const httpServer: Server = createServer((_, res) => {
+        res.writeHead(400).end('WebSocket endpoint');
+      });
+
+      httpServer.on('error', (err: NodeJS.ErrnoException) => {
+        httpServer.close();
+        reject(err);
+      });
+
+      const expectedToken = this.token;
+      const allowedHosts = this.allowedHosts;
+      const allowedOrigins = this.allowedOrigins;
+      const channels = this.channels;
+      httpServer.listen(port, '127.0.0.1', () => {
+        const wss = new WebSocketServer({
+          server: httpServer,
+          // Reject disallowed Host/Origin before the protocol upgrade or any session data.
+          verifyClient: (
+            info: { origin: string; secure: boolean; req: IncomingMessage },
+            cb: (res: boolean, code?: number, message?: string) => void,
+          ) => {
+            if (!hostAllowed(info.req, allowedHosts)) {
+              cb(false, 403, 'Forbidden host');
+              return;
+            }
+            if (!originAllowed(info.req, allowedOrigins)) {
+              cb(false, 403, 'Forbidden origin');
+              return;
+            }
+            cb(true);
+          },
+        });
+
+        wss.on('connection', (ws: WebSocket, req: IncomingMessage) => {
+          // Reject unauthenticated peers before sending history or accepting prompt responses.
+          if (expectedToken !== undefined && !tokenMatches(expectedToken, presentedToken(req))) {
+            ws.close(1008, 'unauthorized');
+            return;
+          }
+
+          // #3189: with a binder, this connection gets its own session and directory, so its
+          // switch (and the `session_switched` that follows) stays on this connection. Every WS
+          // connection drives: this carrier has no observe role.
+          const bound = this.bindConnection(ws);
+          if (bound === null) return;
+          const { binding } = bound;
+          const connectionSession = binding?.session ?? session;
+          const delivery = new WsSessionDelivery(ws);
+          const handler = createSessionMessageHandler({
+            session: connectionSession,
+            deliver: delivery.deliver,
+            ...this.handlerOptions,
+            ...(binding ? { sessionDirectory: binding.directory } : {}),
+          });
+          delivery.bindProtocolCleanup(() => {
+            handler.cleanup();
+            binding?.release();
+          });
+
+          delivery.bindSinkDetach(
+            // ARCH-030: through the connection's own delivery, so payload frames share the text
+            // protocol's backpressure budget and its close policy. The bare `readyState` check plus
+            // `ws.send` that stood here was the last outbound path on this socket outside the
+            // boundary.
+            channels.addSink((frame: Uint8Array) => delivery.deliverBinary(frame)),
+          );
+
+          // Route by frame opcode: TEXT → the text-agent protocol profile, BINARY → the
+          // payload-agnostic channels. An unroutable channel frame is answered with an explicit
+          // `protocol_error` rather than silently dropped.
+          ws.on('message', (data: RawData, isBinary: boolean) => {
+            if (!isBinary) {
+              handler.onMessage(String(data));
+              return;
+            }
+            const result = channels.receive(toBytes(data));
+            if (!result.ok) delivery.deliver({ type: 'protocol_error', message: result.error });
+          });
+          ws.on('close', delivery.close);
+          ws.on('error', delivery.close);
+
+          delivery.deliver({
+            type: 'messages',
+            messages: connectionSession.getMessages(),
+            ...(this.handlerOptions.driverId ? { driverId: this.handlerOptions.driverId } : {}),
+          });
+          delivery.deliver({
+            type: 'execution_workspace_event',
+            snapshot: connectionSession.getExecutionWorkspaceSnapshot(),
+          });
+        });
+
+        resolve({
+          port,
+          stop: () =>
+            new Promise<void>((res) => {
+              // RUNTIME-13: graceful-then-forced shutdown. Send a close frame to each client so well-behaved
+              // peers close cleanly; terminate any socket still open at the deadline so `wss.close()`'s
+              // all-clients-gone callback can never hang. `verifyClient`/token gates are connection-time and
+              // untouched here (SEC-001 preserved).
+              for (const client of wss.clients) client.close(1001, 'server shutting down');
+              const deadline = setTimeout(() => {
+                for (const client of wss.clients) client.terminate();
+              }, WS_STOP_TERMINATE_DEADLINE_MS);
+              wss.close(() => {
+                clearTimeout(deadline);
+                httpServer.close(() => res());
+              });
+            }),
+        });
+      });
+    });
+  }
+}

package/src/ws-transport.ts

@@ -0,0 +1,94 @@
+/**
+ * ITransportAdapter implementation for WebSocket transport.
+ *
+ * Wraps createSessionMessageHandler into the unified ITransportAdapter interface.
+ * After start(), the consumer must wire onMessage to their WebSocket.
+ */
+
+import { createOutboundDelivery, createSessionMessageHandler } from '@robota-sdk/agent-transport';
+
+import type { TUsageSurface } from '@robota-sdk/agent-interface-analytics';
+import type { TDriverId } from '@robota-sdk/agent-interface-session';
+import type {
+  ITransportAdapter,
+  ITransportLifecycleError,
+} from '@robota-sdk/agent-interface-transport';
+import type {
+  IProtocolSession,
+  ISessionMessageHandlerOptions,
+  TServerMessage,
+} from '@robota-sdk/agent-transport';
+
+export interface IWsTransportOptions {
+  /** Send a JSON message to the connected WebSocket client. */
+  send: (message: TServerMessage) => void;
+  /** Owning socket lifecycle callback for outbound session-event delivery failures. */
+  onDeliveryError?: (error: Error, event: string) => void;
+  personalUsageReporter?: ISessionMessageHandlerOptions['personalUsageReporter'];
+  usageReporter?: ISessionMessageHandlerOptions['usageReporter'];
+  storedSessionUsageReporter?: ISessionMessageHandlerOptions['storedSessionUsageReporter'];
+  sessionDirectory?: ISessionMessageHandlerOptions['sessionDirectory'];
+  settingsReporter?: ISessionMessageHandlerOptions['settingsReporter'];
+  driverId?: TDriverId;
+  surface?: TUsageSurface;
+}
+
+export interface IWsTransport extends ITransportAdapter<IProtocolSession> {
+  onMessage: ((data: string) => void) | null;
+}
+
+export function createWsTransport(options: IWsTransportOptions): IWsTransport {
+  let session: IProtocolSession | null = null;
+  let cleanup: (() => void) | null = null;
+  const lifecycleError = (code: ITransportLifecycleError['code']): ITransportLifecycleError =>
+    Object.assign(new Error(`WebSocket transport ${code}.`), {
+      name: 'TransportLifecycleError' as const,
+      code,
+      transportName: 'ws',
+    });
+
+  const transport: IWsTransport = {
+    name: 'ws',
+    lifecycle: Object.freeze({ kind: 'service' }),
+    onMessage: null,
+    attach(s: IProtocolSession) {
+      session = s;
+    },
+    async start() {
+      if (!session) throw lifecycleError('not-attached');
+      if (cleanup) throw lifecycleError('already-started');
+      // ARCH-030: this adapter is the carrier here, so it builds the connection's outbound boundary
+      // from its own injected sink and its own failure policy, then passes it down.
+      const deliver = createOutboundDelivery(options.send, (error, event) => {
+        handler.cleanup();
+        cleanup = null;
+        transport.onMessage = null;
+        options.onDeliveryError?.(error, event);
+      });
+      const handler = createSessionMessageHandler({
+        session,
+        deliver,
+        ...(options.driverId ? { driverId: options.driverId } : {}),
+        ...(options.surface ? { surface: options.surface } : {}),
+        ...(options.personalUsageReporter
+          ? { personalUsageReporter: options.personalUsageReporter }
+          : {}),
+        ...(options.usageReporter ? { usageReporter: options.usageReporter } : {}),
+        ...(options.storedSessionUsageReporter
+          ? { storedSessionUsageReporter: options.storedSessionUsageReporter }
+          : {}),
+        ...(options.sessionDirectory ? { sessionDirectory: options.sessionDirectory } : {}),
+        ...(options.settingsReporter ? { settingsReporter: options.settingsReporter } : {}),
+      });
+      cleanup = handler.cleanup;
+      this.onMessage = handler.onMessage;
+    },
+    async stop() {
+      cleanup?.();
+      cleanup = null;
+      this.onMessage = null;
+      session = null;
+    },
+  };
+  return transport;
+}