@ouispec/agent-realtime 0.1.0

package/dist/testing/index.js

@@ -0,0 +1,87 @@
+/**
+ * @ouispec/agent-realtime/testing — what a product's tests need to
+ * run the real server: a Redis to meet in.
+ *
+ * `REDIS_URL` names one (CI runs a Redis service); otherwise a private
+ * `redis-server` is started on a free port and stopped afterwards. Neither
+ * available is an error, never a skipped test: the server cannot run without
+ * Redis, so neither can a test of it.
+ */
+import { spawn } from 'node:child_process';
+import net from 'node:net';
+function freePort() {
+    return new Promise((resolve, reject) => {
+        const srv = net.createServer();
+        srv.once('error', reject);
+        srv.listen(0, '127.0.0.1', () => {
+            const { port } = srv.address();
+            srv.close(() => resolve(port));
+        });
+    });
+}
+function reachable(host, port, timeoutMs) {
+    return new Promise((resolve) => {
+        const socket = net.connect({ host, port });
+        const done = (ok) => {
+            socket.destroy();
+            resolve(ok);
+        };
+        socket.setTimeout(timeoutMs, () => done(false));
+        socket.once('connect', () => done(true));
+        socket.once('error', () => done(false));
+    });
+}
+export async function startTestRedis() {
+    const url = process.env.REDIS_URL;
+    if (url) {
+        const parsed = new URL(url);
+        const config = {
+            host: parsed.hostname,
+            port: Number(parsed.port || 6379),
+            tls: parsed.protocol === 'rediss:',
+            ...(parsed.username ? { username: decodeURIComponent(parsed.username) } : {}),
+            ...(parsed.password ? { password: decodeURIComponent(parsed.password) } : {}),
+        };
+        if (!(await reachable(config.host, config.port, 2_000))) {
+            throw new Error(`REDIS_URL names ${config.host}:${config.port}, which is not reachable`);
+        }
+        return { config, stop: async () => { } };
+    }
+    const port = await freePort();
+    let child;
+    try {
+        child = spawn('redis-server', ['--port', String(port), '--bind', '127.0.0.1', '--save', '', '--appendonly', 'no'], {
+            stdio: 'ignore',
+        });
+    }
+    catch (err) {
+        throw new Error(`No REDIS_URL, and redis-server could not be started: ${String(err)}`, { cause: err });
+    }
+    const spawnError = new Promise((_, reject) => child.once('error', (err) => reject(new Error(`No REDIS_URL, and redis-server could not be started: ${err.message}`))));
+    const deadline = Date.now() + 5_000;
+    const ready = (async () => {
+        while (Date.now() < deadline) {
+            if (await reachable('127.0.0.1', port, 200))
+                return;
+            await new Promise((r) => setTimeout(r, 50));
+        }
+        throw new Error(`redis-server on port ${port} did not accept connections within 5 s`);
+    })();
+    try {
+        await Promise.race([ready, spawnError]);
+    }
+    catch (err) {
+        child.kill('SIGKILL');
+        throw err;
+    }
+    return {
+        config: { host: '127.0.0.1', port, tls: false },
+        stop: () => new Promise((resolve) => {
+            if (child.exitCode !== null)
+                return resolve();
+            child.once('exit', () => resolve());
+            child.kill('SIGTERM');
+        }),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The realtime server's seams (ADR-0227 §2.2). The product supplies every one;
+ * the server refuses to start, naming the seam, when one is missing. None has
+ * a default taken from any one product.
+ */
+import type { EventCatalog } from '@ouispec/agent-events';
+import type { ClientEvent } from './client-events/chain.js';
+import type { RealtimeLogger } from './logger.js';
+/**
+ * Auth verifier: verifies the product's own user tokens. Called once per
+ * socket, at connection; the identity it returns is the only identity any
+ * client event is authorized against.
+ */
+export interface AuthAdapter {
+    verify(token: string): Promise<AuthResult>;
+}
+export interface AuthResult {
+    userId: string;
+    accountId?: string;
+    platformAdmin?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Room policy: which rooms exist, which a socket is placed in by its identity,
+ * and who may join the rest.
+ *
+ * A room that `requiresToken` is joined only with a room token minted for this
+ * user and this exact room (`POST /internal/room-token`). The product decides
+ * who gets one, by running the resource's own read authorization before it
+ * asks for the token — for Closure, studio-api's `POST /realtime/room-tokens`.
+ * The server only signs and checks.
+ */
+export interface RoomPolicy {
+    /** A well-formed room name this product uses. Anything else is refused everywhere. */
+    isValidRoom(room: string): boolean;
+    /** The rooms a socket joins on connect, from its identity alone. It can never leave them. */
+    identityRooms(user: AuthResult): string[];
+    /** True when joining `room` needs a room token; tokens are minted only for these rooms. */
+    requiresToken(room: string): boolean;
+    /** For a room that needs no token: may this identity join it? */
+    canJoin(room: string, user: AuthResult): boolean;
+}
+/** What validates a payload. Joi schemas satisfy it. */
+export interface PayloadSchema {
+    validate(value: unknown, options?: Record<string, unknown>): {
+        value?: unknown;
+        error?: {
+            message: string;
+        };
+    };
+}
+/**
+ * An event a client may relay. With `events`, the declaration supplies the
+ * rooms it may go to and its data schema, and both fields may be left out;
+ * without them, both are required.
+ */
+export interface RelayRule {
+    /** The room prefix this event may be relayed to, e.g. 'avatar' for `avatar:{id}`. */
+    roomPrefix?: string;
+    /** The event's `data`. */
+    data?: PayloadSchema;
+}
+export interface RedisConfig {
+    host: string;
+    port: number;
+    tls: boolean;
+    username?: string;
+    password?: string;
+}
+export interface RoomTokenConfig {
+    /**
+     * Signs room tokens (HMAC-SHA256). At least 32 characters, one per
+     * environment, from the product's secret store. It is not the internal key:
+     * a token secret and an API key are different secrets.
+     */
+    secret: string;
+    /** How long a token admits its holder. Default 15 minutes. */
+    ttlMs?: number;
+}
+export interface ApprovalsConfig {
+    /**
+     * Signs approval tokens (HS256, ADR-0228 §2.3). At least 32 characters, one
+     * per environment, from the product's secret store. It is neither the
+     * internal key nor the room-token secret: an engine that verifies approval
+     * tokens holds this key and nothing else.
+     */
+    signingKey: string;
+}
+/** Everything the server needs. Every field without a `?` is a required seam. */
+export interface RealtimeServerConfig {
+    auth: AuthAdapter;
+    roomPolicy: RoomPolicy;
+    /** Guards every internal endpoint: emit, room tokens, UI action results, approvals. */
+    internalApiKey: string;
+    roomTokens: RoomTokenConfig;
+    /** The approval store: an irreversible action runs only on an approval the user gave (ADR-0228). */
+    approvals: ApprovalsConfig;
+    /**
+     * UI action results and room fan-out across instances meet here, so a
+     * worker's wait can be served by an instance other than the client's.
+     */
+    redis: RedisConfig;
+    /** Browser origins allowed to connect. Pass `['*']` only deliberately. */
+    corsOrigins: string[];
+    /** The port to listen on. `0` picks a free one (see `RealtimeServerInstance.port`). */
+    port: number;
+    /**
+     * The product's event declarations, with the platform's own
+     * (`createEventCatalog(PLATFORM_EVENTS, productEvents)`, ADR-0227 §2.4).
+     * Given them, `/api/emit` refuses an undeclared event, a payload its schema
+     * rejects and a room it is not declared for; a client relays only a
+     * declared notice; and every completion or failure is kept as its job's
+     * settlement (`GET /internal/events/settlements/:kind/:id`).
+     */
+    events?: EventCatalog;
+    /**
+     * The only events a client may relay to other clients: the room prefix each
+     * may go to, and its data schema. Anything not listed is refused, and a
+     * client relays only into rooms its socket has joined. Server events (turn,
+     * UI action and job events) must never be listed; with `events`, listing
+     * one fails at start-up.
+     */
+    relay?: Readonly<Record<string, RelayRule>>;
+    /**
+     * The product's own client events, beside the built-in `subscribe`,
+     * `unsubscribe`, `relay` and the OUI action result. Each goes through the
+     * same chain (declared, rate-limited, schema-checked, authorized).
+     */
+    clientEvents?: readonly ClientEvent[];
+    /** Structured logger; pino satisfies it. Default: JSON lines on the console. */
+    logger?: RealtimeLogger;
+    pingInterval?: number;
+    pingTimeout?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@ouispec/agent-realtime",
+  "version": "0.1.0",
+  "description": "Realtime server for agent turns and UI actions — declared client events, room tokens, the UI action result store, the approval store, declared product events and their job settlements, Redis fan-out; the product supplies auth, room policy and keys",
+  "homepage": "https://github.com/wesreid/oui/tree/main/packages/agent-realtime#readme",
+  "bugs": {
+    "url": "https://github.com/wesreid/oui/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wesreid/oui.git",
+    "directory": "packages/agent-realtime"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@socket.io/redis-adapter": "^8.3.0",
+    "cors": "^2.8.5",
+    "express": "^5.1.0",
+    "helmet": "^8.1.0",
+    "ioredis": "^5.6.0",
+    "joi": "^17.13.3",
+    "socket.io": "^4.8.0",
+    "@ouispec/agent-core": "^0.1.0",
+    "@ouispec/agent-events": "^0.1.0",
+    "oui-spec": "^0.6.1"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.0",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "socket.io-client": "^4.7.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rm -rf dist"
+  }
+}