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

package/src/__tests__/ws-mesh-relay-client.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { WsMeshRelayClient } from '../ws-mesh-relay-client.js';
+import type { IWebSocketLike } from '../ws-signaling-client.js';
+
+const WS_CONNECTING = 0;
+const WS_OPEN = 1;
+const TOPIC = 't'.repeat(43);
+
+function createFakeSocket(): IWebSocketLike & {
+  readonly sent: Record<string, unknown>[];
+  readyState: number;
+  emit(event: 'open' | 'message' | 'error' | 'close', arg?: unknown): void;
+} {
+  const sent: Record<string, unknown>[] = [];
+  const listeners: Record<string, ((arg: unknown) => void)[]> = {};
+  return {
+    sent,
+    readyState: WS_CONNECTING,
+    send(data: string): void {
+      sent.push(JSON.parse(data) as Record<string, unknown>);
+    },
+    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);
+    },
+  };
+}
+
+describe('WsMeshRelayClient', () => {
+  it('declares presence first on open, then flushes messages queued before it', () => {
+    const socket = createFakeSocket();
+    const client = new WsMeshRelayClient({ url: 'ws://x', createSocket: () => socket });
+    client.send(TOPIC, { hello: 1 });
+    client.declarePresence([TOPIC]);
+    expect(socket.sent).toEqual([]);
+
+    socket.readyState = WS_OPEN;
+    socket.emit('open');
+
+    expect(socket.sent).toEqual([
+      { type: 'presence', topics: [TOPIC] },
+      { type: 'message', topic: TOPIC, data: { hello: 1 } },
+    ]);
+  });
+
+  it('routes delivered messages and absences, and reports relay refusals and an unrequested close', () => {
+    const socket = createFakeSocket();
+    const onError = vi.fn();
+    const client = new WsMeshRelayClient({ url: 'ws://x', createSocket: () => socket, onError });
+    const messages: unknown[] = [];
+    const absent: string[] = [];
+    client.onMessage((topic, data) => messages.push([topic, data]));
+    client.onAbsent((topic) => absent.push(topic));
+
+    socket.emit('message', JSON.stringify({ type: 'message', topic: TOPIC, data: 'x' }));
+    socket.emit('message', JSON.stringify({ type: 'absent', topic: TOPIC }));
+    socket.emit('message', 'not json');
+    socket.emit('message', JSON.stringify({ type: 'error', reason: 'rate-limited' }));
+    socket.emit('close');
+
+    expect(messages).toEqual([[TOPIC, 'x']]);
+    expect(absent).toEqual([TOPIC]);
+    expect(onError).toHaveBeenCalledTimes(2);
+    expect(String(onError.mock.calls[0]?.[0])).toMatch(/rate-limited/);
+  });
+
+  it('an intentional close is not an error, and nothing is sent after it', () => {
+    const socket = createFakeSocket();
+    const onError = vi.fn();
+    const client = new WsMeshRelayClient({ url: 'ws://x', createSocket: () => socket, onError });
+    socket.readyState = WS_OPEN;
+    client.close();
+    socket.emit('close');
+    client.send(TOPIC, 'late');
+    expect(onError).not.toHaveBeenCalled();
+    expect(socket.sent).toEqual([]);
+  });
+
+  it('bounds what it queues while the relay is unreachable', () => {
+    const socket = createFakeSocket();
+    const onError = vi.fn();
+    const client = new WsMeshRelayClient({ url: 'ws://x', createSocket: () => socket, onError });
+    for (let i = 0; i < 300; i += 1) client.send(TOPIC, i);
+    expect(onError).toHaveBeenCalled();
+    socket.readyState = WS_OPEN;
+    socket.emit('open');
+    expect(socket.sent.length).toBe(256);
+  });
+});

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,
+  );
+}

package/src/datachannel-loader.ts

@@ -0,0 +1,86 @@
+/**
+ * The WebRTC implementation this transport runs on: `node-datachannel` (libdatachannel, with DTLS by
+ * OpenSSL), an optional dependency loaded lazily.
+ *
+ * It is optional because it ships a native binary per platform. Where it cannot load — not installed,
+ * or no prebuilt binary for this platform — the transport is unavailable and says so at the point of
+ * use. There is deliberately no other implementation to fall back to: channel binding relies on this
+ * DTLS stack verifying handshake signatures.
+ */
+import { createRequire } from 'node:module';
+
+/** The slice of a `node-datachannel` data channel this transport drives. */
+export interface INdcDataChannel {
+  close(): void;
+  sendMessage(message: string): boolean;
+  isOpen(): boolean;
+  bufferedAmount(): number;
+  /** The label the opening side gave the channel. */
+  getLabel?(): string;
+  onOpen(callback: () => void): void;
+  onClosed(callback: () => void): void;
+  onError(callback: (error: string) => void): void;
+  onMessage(callback: (message: string | Buffer | ArrayBuffer) => void): void;
+}
+
+/** An ICE server as `node-datachannel` takes it. */
+export interface INdcIceServer {
+  readonly hostname: string;
+  readonly port: number;
+  readonly username?: string;
+  readonly password?: string;
+  readonly relayType?: 'TurnUdp' | 'TurnTcp' | 'TurnTls';
+}
+
+export interface INdcConfig {
+  iceServers: (string | INdcIceServer)[];
+  iceTransportPolicy?: 'all' | 'relay';
+  disableAutoNegotiation?: boolean;
+}
+
+/** The slice of a `node-datachannel` peer connection this transport drives. */
+export interface INdcPeerConnection {
+  close(): void;
+  setLocalDescription(type?: 'offer' | 'answer'): void;
+  setRemoteDescription(sdp: string, type: 'offer' | 'answer'): void;
+  localDescription(): { type: string; sdp: string } | null;
+  remoteFingerprint(): { value: string; algorithm: string };
+  addRemoteCandidate(candidate: string, mid: string): void;
+  createDataChannel(label: string): INdcDataChannel;
+  state(): string;
+  /** Diagnostics; not every build exposes them. */
+  iceState?(): string;
+  gatheringState?(): string;
+  signalingState?(): string;
+  onLocalDescription(callback: (sdp: string, type: string) => void): void;
+  onLocalCandidate(callback: (candidate: string, mid: string) => void): void;
+  onStateChange(callback: (state: string) => void): void;
+  onDataChannel(callback: (channel: INdcDataChannel) => void): void;
+}
+
+/** The subset of the `node-datachannel` module surface this transport constructs. */
+export interface IDataChannelModule {
+  PeerConnection: new (name: string, config: INdcConfig) => INdcPeerConnection;
+}
+
+/** Resolve a module by id. The default resolves the real module; tests inject a throwing resolver. */
+export type TModuleResolver = (id: string) => unknown;
+
+const defaultResolver: TModuleResolver = (id) => {
+  const requireFrom = createRequire(import.meta.url);
+  // eslint-disable-next-line @typescript-eslint/no-require-imports -- optional native dependency; resolved at runtime, never bundled
+  return requireFrom(id);
+};
+
+export function loadDataChannel(resolve: TModuleResolver = defaultResolver): IDataChannelModule {
+  try {
+    const module = resolve('node-datachannel') as Partial<IDataChannelModule> | undefined;
+    if (typeof module?.PeerConnection !== 'function') throw new Error('no PeerConnection export');
+    return module as IDataChannelModule;
+  } catch {
+    throw new Error(
+      `WebRTC transport unavailable — the optional dependency "node-datachannel" is not installed or has no ` +
+        `prebuilt binary for this platform (${process.platform}-${process.arch}).`,
+    );
+  }
+}