@pjts/webrtc-signalling 0.0.0-stage → 0.0.3

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# Domain-Driven Design TypeScript Utilities / WebRTC Signalling
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Two-party WebRTC signalling hub on top of `@pjts/websocket-server`. The application supplies a
+`SignalStorePort` (persistence + replay by `seq`) and a `RoomPolicyPort` (who may act as which party,
+what may be relayed when); the hub relays offers/answers/ICE between the two parties of a room.
+
+```ts
+const broadcaster = await createBroadcaster()            // in-process (single replica) or redis URL
+const hub = createSignallingHub({ store, rooms, broadcaster, parties: ['host', 'guest'] })
+await buildWsServer({ server: fastify.server, prefix: '/api/v1/rtc/ws', ...pick(hub, 'authorize', 'onMessage', 'onSubscribed') })
+```
+
+Client side: `@pjts/webrtc-client`. Channels: `<prefix>.<roomId>.<party>` (default prefix `rtc`).
+A party subscribes to its own inbox — `subscribe(channel, cb, () => ({ afterSeq }))` — and sends
+`{ type, payload }` with the `message` action on the same channel.

package/dist/InMemorySignalStore.d.ts

@@ -0,0 +1,9 @@
+import type { AppendSignal, Signal, SignalStorePort } from './hub';
+/** Reference store for tests and single-process demos — not durable. */
+export declare class InMemorySignalStore implements SignalStorePort {
+    private readonly signals;
+    private seq;
+    append(signal: AppendSignal): Promise<Signal>;
+    replay(roomId: string, to: string, afterSeq: number): Promise<Signal[]>;
+    countFrom(roomId: string, from: string): Promise<number>;
+}

package/dist/InMemorySignalStore.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemorySignalStore = void 0;
+/** Reference store for tests and single-process demos — not durable. */
+class InMemorySignalStore {
+    signals = [];
+    seq = 0;
+    async append(signal) {
+        const stored = { ...signal, seq: ++this.seq, at: new Date().toISOString() };
+        this.signals.push(stored);
+        return stored;
+    }
+    async replay(roomId, to, afterSeq) {
+        return this.signals.filter(s => s.roomId === roomId && s.to === to && s.seq > afterSeq);
+    }
+    async countFrom(roomId, from) {
+        return this.signals.filter(s => s.roomId === roomId && s.from === from).length;
+    }
+}
+exports.InMemorySignalStore = InMemorySignalStore;
+//# sourceMappingURL=InMemorySignalStore.js.map

package/dist/InMemorySignalStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemorySignalStore.js","sourceRoot":"","sources":["../src/InMemorySignalStore.ts"],"names":[],"mappings":";;;AAEA,wEAAwE;AACxE,MAAa,mBAAmB;IACb,OAAO,GAAa,EAAE,CAAA;IAC/B,GAAG,GAAG,CAAC,CAAA;IAER,KAAK,CAAC,MAAM,CAAC,MAAoB;QACtC,MAAM,MAAM,GAAW,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAA;QACnF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACzB,OAAO,MAAM,CAAA;IACf,CAAC;IAEM,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,EAAU,EAAE,QAAgB;QAC9D,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,GAAG,GAAG,QAAQ,CAAC,CAAA;IACzF,CAAC;IAEM,KAAK,CAAC,SAAS,CAAC,MAAc,EAAE,IAAY;QACjD,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,MAAM,CAAA;IAChF,CAAC;CACF;AAjBD,kDAiBC"}

package/dist/hub.d.ts

@@ -0,0 +1,72 @@
+import type { WebSocketBroadcaster } from '@pjts/websocket-server';
+/** A persisted signal. `seq` is monotonic per room and is the replay cursor. */
+export interface Signal {
+    seq: number;
+    roomId: string;
+    /** A party name, or `server` for hub-originated events. */
+    from: string;
+    to: string;
+    type: string;
+    payload: unknown;
+    at: string;
+}
+export interface AppendSignal {
+    roomId: string;
+    from: string;
+    to: string;
+    type: string;
+    payload: unknown;
+}
+/** Persistence for signals. The hub keeps no state of its own. */
+export interface SignalStorePort {
+    append(signal: AppendSignal): Promise<Signal>;
+    /** Signals addressed to `to` with `seq > afterSeq`, ascending. */
+    replay(roomId: string, to: string, afterSeq: number): Promise<Signal[]>;
+    /** How many signals `from` has sent in the room (bounds ICE storms). */
+    countFrom(roomId: string, from: string): Promise<number>;
+}
+/** The application decides who is who and what may be relayed when (e.g. a waiting room). */
+export interface RoomPolicyPort {
+    /** May the bearer of `token` act as `party` in `roomId`? Used for subscribe and message alike. */
+    authorize(roomId: string, party: string, token: string | null): Promise<boolean>;
+    /** May `from` relay a signal of `type` right now? */
+    mayRelay(roomId: string, from: string, type: string): Promise<boolean>;
+}
+export interface SignallingHubConfig {
+    store: SignalStorePort;
+    rooms: RoomPolicyPort;
+    broadcaster: Pick<WebSocketBroadcaster, 'broadcast'>;
+    /** The two party slots of every room, e.g. `['host', 'guest']`. */
+    parties: [string, string];
+    /** Channel prefix — channels are `<prefix>.<roomId>.<party>`. Default `rtc`. */
+    channelPrefix?: string;
+    /** Max JSON size of a relayed payload. Default 16 KiB. */
+    maxPayloadBytes?: number;
+    /** Max signals one party may send per room. Default 500. */
+    maxSignalsPerParty?: number;
+}
+export declare const SERVER_PARTY = "server";
+export declare class SignallingError extends Error {
+}
+interface ParsedChannel {
+    roomId: string;
+    party: string;
+}
+/**
+ * Two-party WebRTC signalling over `@pjts/websocket-server`. Each party subscribes to its own inbox
+ * `<prefix>.<roomId>.<party>` (optionally with `{ afterSeq }` to replay history) and sends upstream
+ * `message` actions on the same channel with `{ type, payload }`. The hub asks the policy, persists the
+ * signal, and pushes it to the *other* party's inbox. Server-side events go through `emit`.
+ *
+ * Wire it by spreading `authorize`, `onMessage` and `onSubscribed` into `buildWsServer`.
+ */
+export declare const createSignallingHub: (config: SignallingHubConfig) => {
+    authorize: (channel: string, token: string | null) => Promise<boolean>;
+    onMessage: (channel: string, data: Record<string, unknown>, token: string | null) => Promise<void>;
+    onSubscribed: (channel: string, params: Record<string, unknown>, deliver: (msg: Record<string, unknown>) => void, token: string | null) => Promise<void>;
+    emit: (roomId: string, to: string, type: string, payload?: unknown) => Promise<Signal>;
+    channelFor: (roomId: string, party: string) => string;
+    parse: (channel: string) => ParsedChannel | null;
+};
+export type SignallingHub = ReturnType<typeof createSignallingHub>;
+export {};

package/dist/hub.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSignallingHub = exports.SignallingError = exports.SERVER_PARTY = void 0;
+exports.SERVER_PARTY = 'server';
+class SignallingError extends Error {
+}
+exports.SignallingError = SignallingError;
+const TYPE_RE = /^[a-z][a-z0-9_.-]{0,63}$/i;
+/**
+ * Two-party WebRTC signalling over `@pjts/websocket-server`. Each party subscribes to its own inbox
+ * `<prefix>.<roomId>.<party>` (optionally with `{ afterSeq }` to replay history) and sends upstream
+ * `message` actions on the same channel with `{ type, payload }`. The hub asks the policy, persists the
+ * signal, and pushes it to the *other* party's inbox. Server-side events go through `emit`.
+ *
+ * Wire it by spreading `authorize`, `onMessage` and `onSubscribed` into `buildWsServer`.
+ */
+const createSignallingHub = (config) => {
+    const prefix = config.channelPrefix ?? 'rtc';
+    const maxPayloadBytes = config.maxPayloadBytes ?? 16 * 1024;
+    const maxSignalsPerParty = config.maxSignalsPerParty ?? 500;
+    const [partyA, partyB] = config.parties;
+    const channelFor = (roomId, party) => `${prefix}.${roomId}.${party}`;
+    const parse = (channel) => {
+        const chunks = channel.split('.');
+        if (chunks.length < 3 || chunks[0] !== prefix)
+            return null;
+        const party = chunks[chunks.length - 1];
+        const roomId = chunks.slice(1, -1).join('.');
+        if (!roomId || (party !== partyA && party !== partyB))
+            return null;
+        return { roomId, party };
+    };
+    const otherParty = (party) => (party === partyA ? partyB : partyA);
+    const deliverable = (signal) => ({ uuid: `${signal.roomId}:${signal.seq}`, ...signal });
+    const push = async (signal) => {
+        await config.broadcaster.broadcast([channelFor(signal.roomId, signal.to)], deliverable(signal));
+    };
+    const authorize = async (channel, token) => {
+        const parsed = parse(channel);
+        if (!parsed)
+            return false;
+        return config.rooms.authorize(parsed.roomId, parsed.party, token);
+    };
+    /** Called by the WS server after `authorize` passed for the channel. */
+    const onMessage = async (channel, data) => {
+        const parsed = parse(channel);
+        if (!parsed)
+            throw new SignallingError('Unknown channel');
+        const type = data.type;
+        if (typeof type !== 'string' || !TYPE_RE.test(type))
+            throw new SignallingError('Invalid signal type');
+        const payload = data.payload ?? null;
+        if (JSON.stringify(payload).length > maxPayloadBytes)
+            throw new SignallingError('Signal too large');
+        if (!(await config.rooms.mayRelay(parsed.roomId, parsed.party, type))) {
+            throw new SignallingError('Signal not allowed');
+        }
+        if ((await config.store.countFrom(parsed.roomId, parsed.party)) >= maxSignalsPerParty) {
+            throw new SignallingError('Too many signals');
+        }
+        const signal = await config.store.append({
+            roomId: parsed.roomId,
+            from: parsed.party,
+            to: otherParty(parsed.party),
+            type,
+            payload,
+        });
+        await push(signal);
+    };
+    /** Replays history after `params.afterSeq` (default 0) to the subscribing socket only. */
+    const onSubscribed = async (channel, params, deliver) => {
+        const parsed = parse(channel);
+        if (!parsed)
+            return;
+        const afterSeq = Number(params.afterSeq) || 0;
+        const history = await config.store.replay(parsed.roomId, parsed.party, afterSeq);
+        history.forEach(signal => deliver(deliverable(signal)));
+    };
+    /** Server-originated event (presence, admission, end…) — persisted and pushed like any signal. */
+    const emit = async (roomId, to, type, payload = null) => {
+        if (to !== partyA && to !== partyB)
+            throw new SignallingError(`Unknown party '${to}'`);
+        const signal = await config.store.append({ roomId, from: exports.SERVER_PARTY, to, type, payload });
+        await push(signal);
+        return signal;
+    };
+    return { authorize, onMessage, onSubscribed, emit, channelFor, parse };
+};
+exports.createSignallingHub = createSignallingHub;
+//# sourceMappingURL=hub.js.map

package/dist/hub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub.js","sourceRoot":"","sources":["../src/hub.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './hub';
+export * from './InMemorySignalStore';

package/dist/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./hub"), exports);
+tslib_1.__exportStar(require("./InMemorySignalStore"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,gDAAqB;AACrB,gEAAqC"}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@pjts/webrtc-signalling",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.3",
+  "description": "Piotr Józefów DDD utility package — two-party WebRTC signalling hub over @pjts/websocket-server",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "author": "Piotr Józefów",
+  "license": "MIT",
+  "engines": {
+    "node": "^18.14.0"
+  },
+  "engineStrict": true,
+  "scripts": {
+    "lint": "eslint src/ --ext .js,.jsx,.ts,.tsx",
+    "test": "NODE_ENV=test jest --coverage=false --verbose",
+    "test:watch": "NODE_ENV=test jest --coverage=false --watchAll --testNamePattern=",
+    "build": "rm -rf ./dist && tsc",
+    "package": "npm run build && npm publish --access=public",
+    "prepare": "npm install @pjts/core@latest @pjts/websocket-client@latest @pjts/websocket-server@latest --save-dev & npm version patch"
+  },
+  "peerDependencies": {
+    "@pjts/websocket-server": ">=0.0.59"
+  },
+  "devDependencies": {
+    "@pjts/core": "^0.0.90",
+    "@pjts/websocket-client": "^0.0.59",
+    "@pjts/websocket-server": "^0.0.60",
+    "@types/jest": "29.4.0",
+    "@types/node": "18.13.0",
+    "jest": "29.4.2",
+    "ts-jest": "29.0.5",
+    "typescript": "4.9.5"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  }
+}