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

package/src/rtc-peer.ts

@@ -0,0 +1,429 @@
+/**
+ * One WebRTC peer connection and its data channels, over `node-datachannel`.
+ *
+ * The native binding takes a single callback per event and aborts the process when a callback throws,
+ * so every callback here is registered once, fans out to handlers, and never lets an exception reach
+ * the binding: a throwing handler closes the connection instead. Negotiation is explicit (no automatic
+ * offers or answers), so a connection produces exactly the descriptions its owner asks for, and no ICE
+ * server is contacted unless one is configured.
+ */
+import {
+  loadDataChannel,
+  type IDataChannelModule,
+  type INdcDataChannel,
+  type INdcIceServer,
+  type INdcPeerConnection,
+} from './datachannel-loader.js';
+
+import type { IIceServer } from './webrtc-transport-options.js';
+
+export type TRtcPeerState =
+  'new' | 'connecting' | 'connected' | 'disconnected' | 'failed' | 'closed';
+export type TRtcChannelState = 'connecting' | 'open' | 'closed';
+
+/** Why and how a connection or channel ended, for a refusal a person can act on. */
+export interface IRtcPeerDiagnostics {
+  readonly state: TRtcPeerState;
+  readonly ice?: string;
+  readonly gathering?: string;
+  readonly signaling?: string;
+  /** The states the connection went through, in order. */
+  readonly history: readonly TRtcPeerState[];
+  /** `local`: this side closed it; `handler-error`: a handler threw and the connection was closed. */
+  readonly closedBy?: 'local' | 'handler-error';
+  readonly handlerError?: string;
+  readonly localCandidates: number;
+  readonly remoteCandidates: number;
+}
+
+const MAX_HISTORY = 16;
+
+function reading(read: (() => string) | undefined): string | undefined {
+  try {
+    return read?.();
+  } catch {
+    return undefined;
+  }
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export interface IRtcCandidate {
+  readonly candidate: string;
+  readonly mid: string;
+}
+
+export interface IRtcPeerOptions {
+  readonly iceServers?: readonly IIceServer[];
+  /** Relay (TURN) candidates only. */
+  readonly forceTurn?: boolean;
+  /** Test seam: the `node-datachannel` module. */
+  readonly loadDataChannel?: () => IDataChannelModule;
+}
+
+/**
+ * How long a closed channel's stream stays up. The implementation resets the stream as soon as it is
+ * told to close, and a message sent just before is then lost to the peer.
+ */
+const CHANNEL_CLOSE_GRACE_MS = 250;
+
+/** Remote candidates kept while the remote description is still on its way. */
+const MAX_EARLY_CANDIDATES = 64;
+
+const DEFAULT_PORTS: Readonly<Record<string, number>> = { stun: 3478, turn: 3478, turns: 5349 };
+
+/** One configured ICE server in the binding's form. Throws on a url it cannot represent. */
+export function toNativeIceServer(server: IIceServer): string | INdcIceServer {
+  const match =
+    /^(stuns?|turns?):([^:?]+|\[[^\]]+\])(?::(\d{1,5}))?(?:\?transport=(udp|tcp))?$/i.exec(
+      server.urls,
+    );
+  if (!match) throw new Error(`unsupported ICE server url: ${server.urls}`);
+  const scheme = match[1]!.toLowerCase();
+  const hostname = match[2]!.replace(/^\[|\]$/g, '');
+  const port = match[3] !== undefined ? Number(match[3]) : (DEFAULT_PORTS[scheme] ?? 3478);
+  if (scheme === 'stun' || scheme === 'stuns') return `stun:${hostname}:${port}`;
+  return {
+    hostname,
+    port,
+    ...(server.username !== undefined ? { username: server.username } : {}),
+    ...(server.credential !== undefined ? { password: server.credential } : {}),
+    relayType:
+      scheme === 'turns' ? 'TurnTls' : match[4]?.toLowerCase() === 'tcp' ? 'TurnTcp' : 'TurnUdp',
+  };
+}
+
+function textOf(message: string | Buffer | ArrayBuffer): string {
+  if (typeof message === 'string') return message;
+  return Buffer.from(message as ArrayBuffer).toString('utf8');
+}
+
+export class RtcChannel {
+  private stateValue: TRtcChannelState;
+  private closeCauseValue?: string;
+  private closedLocally = false;
+  private readonly messageHandlers = new Set<(text: string) => void>();
+  private readonly stateHandlers = new Set<(state: TRtcChannelState) => void>();
+
+  public constructor(
+    private readonly native: INdcDataChannel,
+    private readonly fault: (error: unknown) => void,
+  ) {
+    this.stateValue = native.isOpen() ? 'open' : 'connecting';
+    native.onOpen(() => this.guard(() => this.setState('open')));
+    native.onClosed(() => this.guard(() => this.closedWith('closed by the peer or the transport')));
+    native.onError((error) => this.guard(() => this.closedWith(`error: ${error}`)));
+    native.onMessage((message) =>
+      this.guard(() => {
+        // Closed here, the stream only waits out its grace: nothing more is taken from it.
+        if (this.closedLocally) return;
+        const text = textOf(message);
+        for (const handler of this.messageHandlers) handler(text);
+      }),
+    );
+  }
+
+  private guard(action: () => void): void {
+    try {
+      action();
+    } catch (error) {
+      // A throwing handler must not reach the native binding; the connection is closed instead.
+      this.closeCauseValue ??= `handler error: ${describeError(error)}`;
+      this.fault(error);
+    }
+  }
+
+  private closedWith(cause: string): void {
+    this.closeCauseValue ??= cause;
+    this.setState('closed');
+  }
+
+  /** Why the channel closed, once it has. */
+  public get closeCause(): string | undefined {
+    return this.closeCauseValue;
+  }
+
+  private setState(state: TRtcChannelState): void {
+    if (this.stateValue === state || this.stateValue === 'closed') return;
+    this.stateValue = state;
+    for (const handler of this.stateHandlers) handler(state);
+  }
+
+  public get readyState(): TRtcChannelState {
+    return this.stateValue;
+  }
+
+  /** The label the opening side gave the channel; empty when the implementation does not say. */
+  public get label(): string {
+    try {
+      return this.native.getLabel?.() ?? '';
+    } catch {
+      return '';
+    }
+  }
+
+  public get bufferedAmount(): number {
+    try {
+      return this.native.bufferedAmount();
+    } catch {
+      return 0;
+    }
+  }
+
+  /** Throws when the channel is not open or the message cannot be sent. */
+  public send(text: string): void {
+    if (this.stateValue !== 'open') throw new Error('data channel is not open');
+    this.native.sendMessage(text);
+  }
+
+  public onMessage(handler: (text: string) => void): () => void {
+    this.messageHandlers.add(handler);
+    return () => this.messageHandlers.delete(handler);
+  }
+
+  public onStateChange(handler: (state: TRtcChannelState) => void): () => void {
+    this.stateHandlers.add(handler);
+    return () => this.stateHandlers.delete(handler);
+  }
+
+  /**
+   * Closed for this side at once; the stream is reset after a grace, so what was sent just before
+   * still reaches the peer.
+   */
+  public close(): void {
+    if (this.stateValue === 'closed') return;
+    this.closedLocally = true;
+    const native = this.native;
+    setTimeout(() => {
+      try {
+        native.close();
+      } catch {
+        /* already closing */
+      }
+    }, CHANNEL_CLOSE_GRACE_MS).unref?.();
+    this.closedWith('closed by this side');
+  }
+}
+
+export class RtcPeer {
+  private readonly native: INdcPeerConnection;
+  private stateValue: TRtcPeerState = 'new';
+  private readonly stateHandlers = new Set<(state: TRtcPeerState) => void>();
+  private readonly candidateHandlers = new Set<(candidate: IRtcCandidate) => void>();
+  private readonly channelHandlers = new Set<(channel: RtcChannel) => void>();
+  private readonly descriptionWaiters: ((sdp: string) => void)[] = [];
+  private hasRemoteDescription = false;
+  private readonly history: TRtcPeerState[] = [];
+  private closedBy?: 'local' | 'handler-error';
+  private handlerError?: string;
+  private localCandidateCount = 0;
+  private remoteCandidateCount = 0;
+  /**
+   * Local candidates gathered before the remote description, handed out right after it. An offerer's
+   * candidates let the answerer reach it and start DTLS; the binding makes the remote description the
+   * DTLS layer checks the peer's certificate against only after the ICE layer has it, so a handshake
+   * that arrives while the answer is being applied is refused. Holding the candidates until the
+   * answer is applied keeps the answerer from reaching this side before then.
+   */
+  private readonly heldLocalCandidates: IRtcCandidate[] = [];
+  /** Remote candidates that arrived before the remote description, applied right after it. */
+  private readonly earlyCandidates: IRtcCandidate[] = [];
+  private closed = false;
+
+  public constructor(options: IRtcPeerOptions = {}) {
+    const module = (options.loadDataChannel ?? loadDataChannel)();
+    this.native = new module.PeerConnection('agent', {
+      iceServers: (options.iceServers ?? []).map(toNativeIceServer),
+      ...(options.forceTurn === true ? { iceTransportPolicy: 'relay' as const } : {}),
+      disableAutoNegotiation: true,
+    });
+    this.native.onStateChange((state) =>
+      this.guard(() => {
+        if (state === this.stateValue || this.stateValue === 'closed') return;
+        this.stateValue = state as TRtcPeerState;
+        this.remember(this.stateValue);
+        for (const handler of this.stateHandlers) handler(this.stateValue);
+      }),
+    );
+    this.native.onLocalCandidate((candidate, mid) =>
+      this.guard(() => {
+        // The binding writes the SDP attribute form; the wire form has no `a=` prefix.
+        const value = candidate.startsWith('a=') ? candidate.slice(2) : candidate;
+        if (value.length === 0) return;
+        if (!this.hasRemoteDescription) {
+          this.heldLocalCandidates.push({ candidate: value, mid });
+          return;
+        }
+        this.handOut({ candidate: value, mid });
+      }),
+    );
+    this.native.onLocalDescription((sdp) =>
+      this.guard(() => {
+        for (const waiter of this.descriptionWaiters.splice(0)) waiter(sdp);
+      }),
+    );
+    this.native.onDataChannel((native) =>
+      this.guard(() => {
+        const channel = new RtcChannel(native, (error) => this.fault(error));
+        for (const handler of this.channelHandlers) handler(channel);
+      }),
+    );
+  }
+
+  private guard(action: () => void): void {
+    try {
+      action();
+    } catch (error) {
+      // A throwing handler must not reach the native binding; the connection is closed instead.
+      this.fault(error);
+    }
+  }
+
+  private fault(error: unknown): void {
+    if (this.closed) return;
+    this.closedBy = 'handler-error';
+    this.handlerError = describeError(error);
+    this.close();
+  }
+
+  private remember(state: TRtcPeerState): void {
+    if (this.history.length < MAX_HISTORY) this.history.push(state);
+  }
+
+  /** What the connection went through, for explaining why it ended. */
+  public diagnostics(): IRtcPeerDiagnostics {
+    const ice = reading(this.native.iceState?.bind(this.native));
+    const gathering = reading(this.native.gatheringState?.bind(this.native));
+    const signaling = reading(this.native.signalingState?.bind(this.native));
+    return {
+      state: this.stateValue,
+      ...(ice !== undefined ? { ice } : {}),
+      ...(gathering !== undefined ? { gathering } : {}),
+      ...(signaling !== undefined ? { signaling } : {}),
+      history: [...this.history],
+      ...(this.closedBy !== undefined ? { closedBy: this.closedBy } : {}),
+      ...(this.handlerError !== undefined ? { handlerError: this.handlerError } : {}),
+      localCandidates: this.localCandidateCount,
+      remoteCandidates: this.remoteCandidateCount,
+    };
+  }
+
+  public get state(): TRtcPeerState {
+    return this.stateValue;
+  }
+
+  public createDataChannel(label: string): RtcChannel {
+    return new RtcChannel(this.native.createDataChannel(label), (error) => this.fault(error));
+  }
+
+  private localDescription(type: 'offer' | 'answer'): Promise<string> {
+    return new Promise<string>((resolve, reject) => {
+      this.descriptionWaiters.push(resolve);
+      try {
+        this.native.setLocalDescription(type);
+      } catch (error) {
+        const at = this.descriptionWaiters.indexOf(resolve);
+        if (at >= 0) this.descriptionWaiters.splice(at, 1);
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+  }
+
+  /** Create and apply the local offer; resolves with its SDP. */
+  public createOffer(): Promise<string> {
+    return this.localDescription('offer');
+  }
+
+  /** Apply the remote offer, then create and apply the answer; resolves with its SDP. */
+  public async acceptOffer(sdp: string): Promise<string> {
+    this.native.setRemoteDescription(sdp, 'offer');
+    this.remoteDescriptionApplied();
+    return this.localDescription('answer');
+  }
+
+  public acceptAnswer(sdp: string): void {
+    this.native.setRemoteDescription(sdp, 'answer');
+    this.remoteDescriptionApplied();
+  }
+
+  private remoteDescriptionApplied(): void {
+    this.hasRemoteDescription = true;
+    for (const candidate of this.earlyCandidates.splice(0)) this.addRemoteCandidate(candidate);
+    const held = this.heldLocalCandidates.splice(0);
+    this.guard(() => {
+      for (const candidate of held) this.handOut(candidate);
+    });
+  }
+
+  private handOut(candidate: IRtcCandidate): void {
+    if (this.closed) return;
+    this.localCandidateCount += 1;
+    for (const handler of this.candidateHandlers) handler(candidate);
+  }
+
+  /**
+   * Apply a remote candidate. One that arrives before the remote description waits for it (bounded);
+   * one the binding refuses is dropped.
+   */
+  public addRemoteCandidate(candidate: IRtcCandidate): void {
+    if (this.closed) return;
+    if (!this.hasRemoteDescription) {
+      if (this.earlyCandidates.length < MAX_EARLY_CANDIDATES) this.earlyCandidates.push(candidate);
+      return;
+    }
+    try {
+      this.native.addRemoteCandidate(candidate.candidate, candidate.mid);
+      this.remoteCandidateCount += 1;
+    } catch {
+      // allow-fallback: an unusable candidate is one path fewer, not a failure of the connection
+    }
+  }
+
+  /**
+   * The fingerprint of the certificate the DTLS layer accepted, once connected; `undefined` before.
+   * The DTLS layer (OpenSSL) accepts a certificate only after verifying the peer's handshake signature
+   * with it and matching it against the remote description's fingerprint.
+   */
+  public remoteFingerprint(): { readonly value: string; readonly algorithm: string } | undefined {
+    if (this.stateValue !== 'connected') return undefined;
+    try {
+      const fingerprint = this.native.remoteFingerprint();
+      return fingerprint.value.length > 0 ? fingerprint : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  public onStateChange(handler: (state: TRtcPeerState) => void): () => void {
+    this.stateHandlers.add(handler);
+    return () => this.stateHandlers.delete(handler);
+  }
+
+  public onLocalCandidate(handler: (candidate: IRtcCandidate) => void): () => void {
+    this.candidateHandlers.add(handler);
+    return () => this.candidateHandlers.delete(handler);
+  }
+
+  public onDataChannel(handler: (channel: RtcChannel) => void): () => void {
+    this.channelHandlers.add(handler);
+    return () => this.channelHandlers.delete(handler);
+  }
+
+  public close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.closedBy ??= 'local';
+    try {
+      this.native.close();
+    } catch {
+      /* already closed */
+    }
+    if (this.stateValue !== 'closed') {
+      this.stateValue = 'closed';
+      this.remember('closed');
+      for (const handler of this.stateHandlers) handler('closed');
+    }
+  }
+}

package/src/session-attachment.ts

@@ -0,0 +1,96 @@
+/**
+ * Wiring an admitted channel to the session — the step immediately after the gate says yes.
+ *
+ * "How session frames travel once admission is settled" is a different subject from "what may reach
+ * the session at all", which is the gate's. Split out for the same reason the frame vocabulary and
+ * the controllers already were: `pairing-gate.ts` is at its size limit, and the rule there is to
+ * split rather than extend.
+ *
+ * Two carriers, chosen by whether a resume bridge exists. Neither decides anything about admission —
+ * by the time either runs, that question is closed.
+ */
+
+import {
+  HISTORY_PAGE_MAX_BYTES,
+  createSessionMessageHandler,
+  type ISessionMessageHandlerOptions,
+  type SessionResumeBridge,
+} from '@robota-sdk/agent-transport';
+
+import { createChannelDelivery } from './channel-delivery.js';
+
+import type { IPairingChannel } from './pairing-gate-options.js';
+import type { IProtocolSession } from '@robota-sdk/agent-transport';
+
+export interface IAttachSessionOptions {
+  readonly channel: IPairingChannel;
+  readonly session: IProtocolSession;
+  readonly resumeBridge?: SessionResumeBridge;
+  readonly createHandler?: typeof createSessionMessageHandler;
+  readonly personalUsageReporter?: ISessionMessageHandlerOptions['personalUsageReporter'];
+  readonly usageReporter?: ISessionMessageHandlerOptions['usageReporter'];
+  readonly storedSessionUsageReporter?: ISessionMessageHandlerOptions['storedSessionUsageReporter'];
+  readonly surface?: ISessionMessageHandlerOptions['surface'];
+  readonly commandSurfaceLocality?: ISessionMessageHandlerOptions['commandSurfaceLocality'];
+}
+
+export interface IAttachedSession {
+  /** Where post-accept inbound frames go. */
+  readonly onSessionMessage: (data: string) => void;
+  /** Detach (bridge) or dispose (handler). The gate calls this on teardown. */
+  readonly cleanup: () => void;
+}
+
+/**
+ * Attach the admitted channel to the session.
+ *
+ * `viaReconnect` is threaded through rather than inferred: on a reconnect the bridge must hold live
+ * forwarding until the client's `resume` replays the buffered tail, and getting that backwards
+ * delivers new frames ahead of the replay — an ordering bug that looks like data loss.
+ */
+export function attachSession(
+  options: IAttachSessionOptions,
+  viaReconnect: boolean,
+  onDeliveryError: (error: Error, event: string) => void,
+): IAttachedSession {
+  const bridge = options.resumeBridge;
+  if (bridge) {
+    // REMOTE-013 E4: route the session through the persistent bridge. Attach this channel as the
+    // sink; post-accept inbound frames (incl. resume/ack) go to the bridge; cleanup DETACHES it
+    // (never disposes — the bridge is owned by the transport across reconnects).
+    bridge.attach((data) => options.channel.send(data), {
+      awaitResume: viaReconnect,
+      onDeliveryError,
+      // ARCH-030: without this the bridge's boundary has no backpressure reading, so the replay
+      // path — the burst this budget exists for — runs unbudgeted while every other outbound path
+      // on the same connection is guarded. Read at call time; `bufferedAmount` is live.
+      pendingBytes: () => options.channel.bufferedAmount,
+    });
+    return {
+      onSessionMessage: (data) => bridge.onClientMessage(data),
+      cleanup: () => bridge.detach(),
+    };
+  }
+
+  const create = options.createHandler ?? createSessionMessageHandler;
+  // ARCH-030: the gate is the carrier on this branch — its own channel sink, its own failure policy.
+  const { onMessage, cleanup } = create({
+    session: options.session,
+    deliver: createChannelDelivery(options.channel, onDeliveryError),
+    // A data channel carries a fraction of the inbound limit; a frame over it makes `send` throw and
+    // closes the channel, so an app view or tool result larger than a history page is refused.
+    maxFrameBytes: HISTORY_PAGE_MAX_BYTES,
+    ...(options.personalUsageReporter
+      ? { personalUsageReporter: options.personalUsageReporter }
+      : {}),
+    ...(options.usageReporter ? { usageReporter: options.usageReporter } : {}),
+    ...(options.storedSessionUsageReporter
+      ? { storedSessionUsageReporter: options.storedSessionUsageReporter }
+      : {}),
+    ...(options.surface ? { surface: options.surface } : {}),
+    ...(options.commandSurfaceLocality
+      ? { commandSurfaceLocality: options.commandSurfaceLocality }
+      : {}),
+  });
+  return { onSessionMessage: onMessage, cleanup };
+}

package/src/signaling.ts

@@ -0,0 +1,62 @@
+/**
+ * Signaling port (REMOTE-002). The WebRTC transport is decoupled from any concrete signaling server via this
+ * port: it exchanges opaque SDP/ICE blobs by rendezvous id. The port carries **only** SDP offers/answers + ICE
+ * candidates — never session content — so a signaling server (or the in-memory test pair) is content-blind.
+ */
+
+/** The kinds of signal a peer exchanges through the relay. */
+export type TSignalKind = 'offer' | 'answer' | 'ice';
+
+/** An opaque signaling message relayed by rendezvous id. `data` is an SDP description or an ICE candidate. */
+export interface ISignalMessage {
+  readonly kind: TSignalKind;
+  /** Opaque payload (serialized SDP or ICE candidate). The signaling layer never inspects it. */
+  readonly data: unknown;
+}
+
+/** Port a WebRTC peer uses to reach its counterpart at a rendezvous id. */
+export interface ISignalingClient {
+  /** Send a signal to the counterpart at the rendezvous. */
+  send(message: ISignalMessage): void;
+  /** Subscribe to signals from the counterpart. Returns an unsubscribe function. */
+  onSignal(handler: (message: ISignalMessage) => void): () => void;
+  /** Tear down the signaling channel. */
+  close(): void;
+}
+
+/**
+ * An in-process pair of {@link ISignalingClient}s wired directly to each other — for tests + loopback only
+ * (no server, no network). Each side's `send` is delivered to the other side's handlers on a microtask.
+ */
+export function createInMemorySignalingPair(): [ISignalingClient, ISignalingClient] {
+  const handlersA: ((m: ISignalMessage) => void)[] = [];
+  const handlersB: ((m: ISignalMessage) => void)[] = [];
+  let open = true;
+
+  function make(
+    ownHandlers: ((m: ISignalMessage) => void)[],
+    peerHandlers: ((m: ISignalMessage) => void)[],
+  ): ISignalingClient {
+    return {
+      send(message) {
+        if (!open) return;
+        queueMicrotask(() => {
+          for (const h of peerHandlers) h(message);
+        });
+      },
+      onSignal(handler) {
+        ownHandlers.push(handler);
+        return () => {
+          const i = ownHandlers.indexOf(handler);
+          if (i >= 0) ownHandlers.splice(i, 1);
+        };
+      },
+      close() {
+        open = false;
+        ownHandlers.length = 0;
+      },
+    };
+  }
+
+  return [make(handlersA, handlersB), make(handlersB, handlersA)];
+}