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

package/src/__tests__/webrtc-transport.test.ts

@@ -0,0 +1,349 @@
+import { runTransportLifecycleConformance } from '@robota-sdk/agent-interface-transport/testing';
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import { describe, expect, expectTypeOf, it, vi } from 'vitest';
+import { RTCPeerConnection } from 'werift';
+import type { IConfigurableTransport } from '@robota-sdk/agent-interface-transport';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+import type { IProtocolSession } from '@robota-sdk/agent-transport';
+
+import { WebRtcTransport } from '../webrtc-transport.js';
+import { createInMemorySignalingPair, type ISignalingClient } from '../signaling.js';
+import { WebRtcDeliveryLifecycle } from '../webrtc-delivery-lifecycle.js';
+
+/** Minimal stub session — only `getMessages` + no-op `on`/`off` are exercised by the get-messages round-trip. */
+function createStubSession(): IInteractiveSession {
+  return Object.assign(createTestInteractiveSession(), {
+    getMessages: vi.fn().mockReturnValue([{ role: 'user', content: 'hi' }]),
+    // ARCH-012: required. This double feeds `subscribeSessionEvents`, which calls it on every
+    // turn-authored event — omitting it throws the moment a case emits one.
+    getActiveDriverId: () => null,
+    on: vi.fn(),
+    off: vi.fn(),
+  });
+}
+
+/**
+ * The remote peer (answerer): consumes the host's offer via the injected signaling, opens the data channel,
+ * and speaks the `TClientMessage`/`TServerMessage` protocol. Resolves with the first `TServerMessage` received.
+ */
+function connectRemote(signaling: ISignalingClient): Promise<Record<string, unknown>> {
+  return new Promise((resolve, reject) => {
+    const peer = new RTCPeerConnection();
+    peer.onIceCandidate.subscribe((c) => {
+      if (c) signaling.send({ kind: 'ice', data: c.toJSON() });
+    });
+    let chain: Promise<void> = Promise.resolve();
+    signaling.onSignal((message) => {
+      chain = chain
+        .then(async () => {
+          if (message.kind === 'offer') {
+            await peer.setRemoteDescription(
+              message.data as Parameters<typeof peer.setRemoteDescription>[0],
+            );
+            const answer = await peer.createAnswer();
+            await peer.setLocalDescription(answer);
+            signaling.send({ kind: 'answer', data: peer.localDescription });
+          } else if (message.kind === 'ice') {
+            await peer.addIceCandidate(message.data as Parameters<typeof peer.addIceCandidate>[0]);
+          }
+        })
+        .catch(reject);
+    });
+    peer.onDataChannel.subscribe((channel) => {
+      channel.stateChanged.subscribe((state) => {
+        if (state === 'open') channel.send(JSON.stringify({ type: 'get-messages' }));
+      });
+      channel.onMessage.subscribe((data) => {
+        resolve(JSON.parse(typeof data === 'string' ? data : data.toString()));
+      });
+    });
+  });
+}
+
+describe('WebRtcTransport (REMOTE-002 Stage A — loopback)', () => {
+  it('accepts only the protocol session roles required by the carrier', () => {
+    const transport = new WebRtcTransport({
+      signaling: createInMemorySignalingPair()[0],
+      open: true,
+      openReason: 'type compatibility test',
+    });
+    expectTypeOf(transport).toMatchTypeOf<IConfigurableTransport<IProtocolSession>>();
+    expectTypeOf(transport.attach).toEqualTypeOf<(session: IProtocolSession) => void>();
+  });
+
+  it('has the collapsed webrtc metadata and is disabled by default', () => {
+    const [sig] = createInMemorySignalingPair();
+    const t = new WebRtcTransport({
+      signaling: sig,
+      open: true,
+      openReason: 'SEC-008: Stage-A loopback — this case is about signalling, not pairing',
+    });
+    expect(t.name).toBe('webrtc');
+    expect(t.defaultEnabled).toBe(false);
+  });
+
+  it('start() before attach() throws', async () => {
+    const [sig] = createInMemorySignalingPair();
+    const t = new WebRtcTransport({
+      signaling: sig,
+      open: true,
+      openReason: 'SEC-008: Stage-A loopback — this case is about signalling, not pairing',
+    });
+    await expect(t.start()).rejects.toMatchObject({
+      name: 'TransportLifecycleError',
+      code: 'not-attached',
+    });
+  });
+
+  it('unpaired send failure closes the carrier and reports without escaping the session event', async () => {
+    const handlers = new Map<string, (value: unknown) => void>();
+    const session = createTestInteractiveSession({
+      on: ((event: string, handler: (value: unknown) => void) => {
+        handlers.set(event, handler);
+      }) as IInteractiveSession['on'],
+      off: ((event: string) => {
+        handlers.delete(event);
+      }) as IInteractiveSession['off'],
+    });
+    const closeChannel = vi.fn();
+    const fakeWerift = {
+      RTCPeerConnection: function () {
+        return {
+          onIceCandidate: { subscribe: () => {} },
+          createDataChannel: () => ({
+            onMessage: { subscribe: () => {} },
+            send: () => {
+              throw new Error('unpaired channel closed');
+            },
+            close: closeChannel,
+          }),
+          createOffer: async () => ({ type: 'offer', sdp: 'a=fingerprint:sha-256 AA' }),
+          setLocalDescription: async () => {},
+          localDescription: { type: 'offer', sdp: 'a=fingerprint:sha-256 AA' },
+          close: async () => {},
+        };
+      },
+    } as unknown as import('../werift-loader.js').IWeriftModule;
+    const onDeliveryError = vi.fn();
+    const onDropped = vi.fn();
+    const transport = new WebRtcTransport({
+      signaling: { send: () => {}, onSignal: () => () => {}, close: () => {} },
+      open: true,
+      openReason: 'delivery lifecycle regression',
+      onDeliveryError,
+      onDropped,
+      loadWerift: () => fakeWerift,
+    });
+    transport.attach(session);
+    await transport.start();
+
+    expect(() =>
+      handlers.get('branch_event')?.({
+        kind: 'checkpoint_created',
+        checkpointId: 'turn-0001',
+        branchId: 'main',
+      }),
+    ).not.toThrow();
+    expect(closeChannel).toHaveBeenCalledTimes(1);
+    expect(onDeliveryError).toHaveBeenCalledWith(
+      expect.objectContaining({ message: 'unpaired channel closed' }),
+      'branch_event',
+    );
+    expect(onDropped).not.toHaveBeenCalled();
+    expect(handlers.size).toBe(0);
+    await transport.stop();
+  });
+
+  it('resets pairing and drop guards for every restart generation', () => {
+    const cleanup = vi.fn();
+    const onDropped = vi.fn();
+    const lifecycle = new WebRtcDeliveryLifecycle({
+      cleanup,
+      onDropped,
+      onDeliveryError: vi.fn(),
+    });
+
+    lifecycle.reset(1);
+    lifecycle.accept(1);
+    lifecycle.handleDrop(1);
+    lifecycle.handleDrop(1);
+    expect(cleanup).toHaveBeenCalledTimes(1);
+    expect(onDropped).toHaveBeenCalledTimes(1);
+
+    lifecycle.reset(2);
+    lifecycle.handleDrop(2);
+    lifecycle.accept(2);
+    lifecycle.handleDrop(1);
+    lifecycle.handleDrop(2);
+    expect(cleanup).toHaveBeenCalledTimes(2);
+    expect(onDropped).toHaveBeenCalledTimes(2);
+  });
+
+  it('ignores queued signaling, ICE, and channel callbacks from an older generation', async () => {
+    const sent: Array<{ readonly kind: string }> = [];
+    const signalHandlers: Array<(message: { kind: 'answer'; data: object }) => void> = [];
+    const iceHandlers: Array<(candidate: { toJSON(): object }) => void> = [];
+    const stateHandlers: Array<(state: string) => void> = [];
+    const setRemoteDescription = vi.fn().mockResolvedValue(undefined);
+    const onDropped = vi.fn();
+    const signaling: ISignalingClient = {
+      send: (message) => sent.push(message),
+      onSignal: (handler) => {
+        signalHandlers.push(handler as (message: { kind: 'answer'; data: object }) => void);
+        return () => {};
+      },
+      close: () => {},
+    };
+    const fakeWerift = {
+      RTCPeerConnection: function () {
+        return {
+          onIceCandidate: {
+            subscribe: (handler: (candidate: { toJSON(): object }) => void) =>
+              iceHandlers.push(handler),
+          },
+          createDataChannel: () => ({
+            onMessage: { subscribe: () => {} },
+            stateChanged: {
+              subscribe: (handler: (state: string) => void) => stateHandlers.push(handler),
+            },
+            send: () => {},
+            close: () => {},
+          }),
+          createOffer: async () => ({ type: 'offer', sdp: 'a=fingerprint:sha-256 AA' }),
+          setLocalDescription: async () => {},
+          setRemoteDescription,
+          addIceCandidate: vi.fn(),
+          localDescription: { type: 'offer', sdp: 'a=fingerprint:sha-256 AA' },
+          close: async () => {},
+        };
+      },
+    } as unknown as import('../werift-loader.js').IWeriftModule;
+    const transport = new WebRtcTransport({
+      signaling,
+      secret: 'pairing-secret',
+      onDropped,
+      loadWerift: () => fakeWerift,
+    });
+    transport.attach(createStubSession());
+    await transport.start();
+    const oldSignal = signalHandlers[0]!;
+    const oldIce = iceHandlers[0]!;
+    const oldState = stateHandlers[0]!;
+
+    oldSignal({ kind: 'answer', data: { sdp: 'a=fingerprint:sha-256 BB' } });
+    await transport.stop();
+    transport.attach(createStubSession());
+    await transport.start();
+    oldIce({ toJSON: () => ({ candidate: 'stale' }) });
+    oldState('closed');
+    await Promise.resolve();
+
+    expect(setRemoteDescription).not.toHaveBeenCalled();
+    expect(sent.filter(({ kind }) => kind === 'ice')).toEqual([]);
+    expect(onDropped).not.toHaveBeenCalled();
+    await transport.stop();
+  });
+
+  it('invokes the shared lifecycle conformance suite', async () => {
+    const sent: Array<{ readonly kind: string }> = [];
+    const signaling: ISignalingClient = {
+      send: (message) => sent.push(message),
+      onSignal: () => () => {},
+      close: () => {},
+    };
+    const fakeWerift = {
+      RTCPeerConnection: function () {
+        return {
+          onIceCandidate: { subscribe: () => {} },
+          createDataChannel: () => ({
+            onMessage: { subscribe: () => {} },
+            send: () => {},
+          }),
+          createOffer: async () => ({ type: 'offer', sdp: 'a=fingerprint:sha-256 AA' }),
+          setLocalDescription: async () => {},
+          localDescription: { type: 'offer', sdp: 'a=fingerprint:sha-256 AA' },
+          close: async () => {},
+        };
+      },
+    } as unknown as import('../werift-loader.js').IWeriftModule;
+
+    await runTransportLifecycleConformance({
+      subjectId: '@robota-sdk/agent-transport-webrtc#WebRtcTransport',
+      kind: 'service',
+      createAdapter: () =>
+        new WebRtcTransport({
+          signaling,
+          open: true,
+          openReason: 'ARCH-011 lifecycle conformance',
+          loadWerift: () => fakeWerift,
+        }),
+      createSession: createStubSession,
+      assertReady: () => {
+        if (!sent.some(({ kind }) => kind === 'offer')) throw new Error('offer not published');
+      },
+      assertStopped: () => {},
+    });
+  });
+
+  it('REMOTE-010: forceTurn → iceTransportPolicy:relay (NOT top-level forceTurn, which werift ignores) + turn: passes through', async () => {
+    // Inject a fake werift to capture the config the transport builds (a real relay-only peer + dead TURN would
+    // block ICE gathering). The mapping is proven against real werift empirically; this guards the regression:
+    // forceTurn MUST become iceTransportPolicy:'relay', never a top-level forceTurn werift silently drops.
+    let captured: Record<string, unknown> | undefined;
+    const fakeWerift = {
+      RTCPeerConnection: function (config?: Record<string, unknown>) {
+        captured = config;
+        return {
+          onIceCandidate: { subscribe: () => {} },
+          createDataChannel: () => ({ onMessage: { subscribe: () => {} }, send: () => {} }),
+          createOffer: async () => ({ type: 'offer', sdp: 'a=fingerprint:sha-256 AA' }),
+          setLocalDescription: async () => {},
+          localDescription: { sdp: 'a=fingerprint:sha-256 AA' },
+          close: async () => {},
+        };
+      },
+    } as unknown as import('../werift-loader.js').IWeriftModule;
+
+    const [sig] = createInMemorySignalingPair();
+    const t = new WebRtcTransport({
+      open: true,
+      openReason: 'SEC-008: Stage-A loopback — this case is about signalling, not pairing',
+      signaling: sig,
+      iceServers: [{ urls: 'turn:relay.example:3478', username: 'u', credential: 'c' }],
+      forceTurn: true,
+      loadWerift: () => fakeWerift,
+    });
+    t.attach(createStubSession());
+    await t.start();
+    expect(captured).toEqual({
+      iceServers: [{ urls: 'turn:relay.example:3478', username: 'u', credential: 'c' }],
+      iceTransportPolicy: 'relay',
+    });
+    expect(captured).not.toHaveProperty('forceTurn'); // werift ignores it → must not be emitted
+    await t.stop();
+  });
+
+  it('TC-03: establishes an RTCDataChannel between two peers and round-trips TClient→session→TServer through the shared handler', async () => {
+    const [hostSig, remoteSig] = createInMemorySignalingPair();
+    const session = createStubSession();
+    const host = new WebRtcTransport({
+      signaling: hostSig,
+      open: true,
+      openReason: 'SEC-008: Stage-A loopback — this case is about signalling, not pairing',
+    });
+    host.attach(session);
+
+    const remoteReply = connectRemote(remoteSig);
+    await host.start();
+
+    const reply = await remoteReply;
+    // The remote's `get-messages` reached the session via the reused handler; the host streamed back a
+    // `messages` TServerMessage carrying the stub session's messages — a full P2P round-trip, no network.
+    expect(reply.type).toBe('messages');
+    expect(reply.messages).toEqual([{ role: 'user', content: 'hi' }]);
+    expect(session.getMessages).toHaveBeenCalled();
+
+    await host.stop();
+  }, 15000);
+});

package/src/__tests__/werift-loader.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+
+import { loadWerift } from '../werift-loader.js';
+
+describe('loadWerift (REMOTE-002 Stage A — throw-on-absence lazy-load, TC-05)', () => {
+  it('resolves the real werift module (RTCPeerConnection present) when installed', () => {
+    const mod = loadWerift();
+    expect(typeof mod.RTCPeerConnection).toBe('function');
+  });
+
+  it('throws an explicit "WebRTC transport unavailable" error when werift cannot be resolved — never a silent no-op', () => {
+    expect(() =>
+      loadWerift(() => {
+        throw new Error('Cannot find module "werift"');
+      }),
+    ).toThrow(/WebRTC transport unavailable — install the optional peer dependency "werift"/);
+  });
+});

package/src/__tests__/ws-signaling-client.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { WsSignalingClient, type IWebSocketLike } from '../ws-signaling-client.js';
+import type { ISignalMessage } from '../signaling.js';
+
+/**
+ * REMOTE-004 B2 — `WsSignalingClient` unit tests with an injected fake socket (no network). Cover pre-open
+ * buffering + flush and explicit error surfacing (relay `error` frame, close-before-join).
+ */
+
+const WS_CONNECTING = 0;
+const WS_OPEN = 1;
+
+function createFakeSocket(): IWebSocketLike & {
+  readonly sent: string[];
+  readyState: number;
+  emit(event: 'open' | 'message' | 'error' | 'close', arg?: unknown): void;
+} {
+  const sent: string[] = [];
+  const listeners: Record<string, ((arg: unknown) => void)[]> = {};
+  return {
+    sent,
+    readyState: WS_CONNECTING,
+    send(data: string): void {
+      sent.push(data);
+    },
+    close(): void {
+      /* no-op for the fake */
+    },
+    on(event, handler): void {
+      (listeners[event] ??= []).push(handler);
+    },
+    emit(event, arg): void {
+      for (const h of listeners[event] ?? []) h(arg);
+    },
+  };
+}
+
+function parse(raw: string): Record<string, unknown> {
+  return JSON.parse(raw) as Record<string, unknown>;
+}
+
+describe('WsSignalingClient (REMOTE-004 B2)', () => {
+  it('TC-02: buffers signals produced before open and flushes them (after the join) on open', () => {
+    const socket = createFakeSocket();
+    const client = new WsSignalingClient({
+      url: 'ws://x',
+      rendezvous: 'r',
+      createSocket: () => socket,
+    });
+    // send an offer before the socket opens
+    const offer: ISignalMessage = { kind: 'offer', data: { sdp: 'v=0' } };
+    client.send(offer);
+    expect(socket.sent).toHaveLength(0); // buffered, nothing on the wire yet
+
+    socket.readyState = WS_OPEN;
+    socket.emit('open');
+
+    // first frame is the join, then the flushed offer
+    expect(parse(socket.sent[0]!)).toEqual({ type: 'join', rendezvous: 'r' });
+    expect(parse(socket.sent[1]!)).toEqual({ type: 'signal', kind: 'offer', data: { sdp: 'v=0' } });
+  });
+
+  it('delivers inbound relay signals to onSignal handlers', () => {
+    const socket = createFakeSocket();
+    const client = new WsSignalingClient({
+      url: 'ws://x',
+      rendezvous: 'r',
+      createSocket: () => socket,
+    });
+    const received: ISignalMessage[] = [];
+    client.onSignal((m) => received.push(m));
+    socket.emit('message', JSON.stringify({ type: 'signal', kind: 'answer', data: { sdp: 'a' } }));
+    expect(received).toEqual([{ kind: 'answer', data: { sdp: 'a' } }]);
+  });
+
+  it('TC-02: surfaces a relay error frame via onError (no silent degrade)', () => {
+    const socket = createFakeSocket();
+    const onError = vi.fn();
+    new WsSignalingClient({ url: 'ws://x', rendezvous: 'r', onError, createSocket: () => socket });
+    socket.emit('message', JSON.stringify({ type: 'error', reason: 'rate-limited' }));
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect((onError.mock.calls[0]![0] as Error).message).toMatch(/rate-limited/);
+  });
+
+  it('TC-02: surfaces a close-before-join as an explicit error', () => {
+    const socket = createFakeSocket();
+    const onError = vi.fn();
+    new WsSignalingClient({ url: 'ws://x', rendezvous: 'r', onError, createSocket: () => socket });
+    socket.emit('close');
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect((onError.mock.calls[0]![0] as Error).message).toMatch(/closed before/);
+  });
+
+  it('does NOT treat an intentional close() as an error', () => {
+    const socket = createFakeSocket();
+    const onError = vi.fn();
+    const client = new WsSignalingClient({
+      url: 'ws://x',
+      rendezvous: 'r',
+      onError,
+      createSocket: () => socket,
+    });
+    client.close();
+    socket.emit('close');
+    expect(onError).not.toHaveBeenCalled();
+  });
+});

package/src/admission-steps.ts

@@ -0,0 +1,55 @@
+/**
+ * Which admission step a channel still owes before the session may be exposed.
+ *
+ * Extracted from `pairing-gate.ts` because it is the one decision in that file that is a pure
+ * function of configuration and state — and because it is the ORDERING that carries the security
+ * argument, so it deserves to be readable and testable without a channel, a handshake or a session.
+ *
+ * The order is not arbitrary. Each step must run on a channel the previous one has already bound:
+ *
+ *   handshake     binds the CHANNEL — it terminates at the peer that knew the secret
+ *   local-proof   binds the ENVIRONMENT — that peer reached a 0700 directory owned by this user
+ *   handoff-grant binds the TRANSFER — one user, one destination, one channel, signed
+ *   operator-approval  the receiving operator allows THIS connection — asked last, once every proof
+ *                      has run, so the operator is asked only about a peer that is who it claims
+ *
+ * Each is opt-in, and configuring two means requiring both. That is strictly more restrictive than
+ * requiring either, which is the safe direction — and it is the correct reading for a hand-off
+ * between two sessions on ONE machine, which legitimately has both to present.
+ */
+
+/** The step still owed, or null when the session may be exposed. */
+export type TAdmissionStep = 'local-proof' | 'handoff-grant' | 'operator-approval' | null;
+
+/** What the gate has configured. Named structurally so this module needs none of the gate's types. */
+export interface IConfiguredAdmissionSteps {
+  readonly localPeer?: unknown;
+  readonly handoffGrant?: unknown;
+  readonly connectionApproval?: unknown;
+}
+
+/**
+ * The next step, given what is configured and what has already run.
+ *
+ * `completed` is the gate's current state rather than a set of finished steps, because the states
+ * ARE the record: reaching `handoff-grant` is only possible by having satisfied `local-proof` when
+ * one was required.
+ */
+export function nextAdmissionStep(
+  configured: IConfiguredAdmissionSteps,
+  completed: string,
+): TAdmissionStep {
+  const approved = completed === 'operator-approval';
+  if (
+    configured.localPeer !== undefined &&
+    completed !== 'local-proof' &&
+    completed !== 'handoff-grant' &&
+    !approved
+  ) {
+    return 'local-proof';
+  }
+  if (configured.handoffGrant !== undefined && completed !== 'handoff-grant' && !approved)
+    return 'handoff-grant';
+  if (configured.connectionApproval !== undefined && !approved) return 'operator-approval';
+  return null;
+}

package/src/channel-delivery.ts

@@ -0,0 +1,44 @@
+/**
+ * The data channel's outbound delivery boundary (ARCH-030).
+ *
+ * Both places that build a bare `createSessionMessageHandler` in this package — `PairingGate`'s no-`resumeBridge`
+ * branch and `WebRtcTransport`'s no-secret branch — need exactly the same thing: serialize a
+ * `TServerMessage` onto an `RTCDataChannel` and route a send failure into that carrier's own failure
+ * policy. Written inline at both sites it was two copies of one decision, and it pushed both files past
+ * their size ceilings. One owner, named after what it is.
+ */
+
+import { createOutboundDelivery } from '@robota-sdk/agent-transport';
+
+import type { TOutboundDeliver } from '@robota-sdk/agent-transport';
+
+/**
+ * The slice of `RTCDataChannel` an outbound boundary needs.
+ *
+ * `bufferedAmount` is optional because the slice is structural — a test double may omit it — but a
+ * real `RTCDataChannel` always has it, so the production path reports a real number rather than a
+ * placeholder (ARCH-030 / issue #1734).
+ */
+export interface IDataChannelSink {
+  send: (data: string) => void;
+  readonly bufferedAmount?: number;
+}
+
+/**
+ * Build the connection's outbound boundary over a data channel.
+ *
+ * @param channel - the data channel to serialize onto. `send` may throw once the channel is closing.
+ * @param onDeliveryError - this carrier's failure policy, invoked at most once (the boundary latches).
+ */
+export function createChannelDelivery(
+  channel: IDataChannelSink,
+  onDeliveryError: (error: Error, event: string) => void,
+): TOutboundDeliver {
+  return createOutboundDelivery(
+    (message) => channel.send(JSON.stringify(message)),
+    (error, event) => onDeliveryError(error, event),
+    // Read at CALL time, not captured: `bufferedAmount` is a live property and a value read once
+    // would answer with the backpressure of the moment the boundary was built.
+    () => channel.bufferedAmount,
+  );
+}