Initial Commit
This commit is contained in:
71
packages/api-stack/api/api-ws/README.md
Normal file
71
packages/api-stack/api/api-ws/README.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# @suaveplan/api-ws - Abstract WebSocket engine contract for the Suaveplan API foundation — Connection, ConnectionRegistry, SubscriptionBus, WsBroker, reconnect-token envelope, backpressure + heartbeat policies, cross-tenant capability gate, and a runWsEngineConformance harness. contracts only; concrete engines (api-ws-bun) and brokers (api-ws-broker-redis / -in-memory) plug behind these interfaces.
|
||||
|
||||
> Stage-1 abstract WebSocket contract for the Suaveplan API plugin system.
|
||||
|
||||
Universal contract package. Defines the canonical interfaces every concrete
|
||||
WebSocket engine (`api-ws-bun`, future browser shims) and broker
|
||||
(`api-ws-broker-in-memory`, `api-ws-broker-redis`) plugs behind. Ships a
|
||||
single-host in-memory `ConnectionRegistry` + `SubscriptionBus` so the
|
||||
conformance harness has an executable reference, plus the cross-tenant
|
||||
capability gate documented in design doc §11.2.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
## Documentation tree
|
||||
|
||||
- [backpressure](./src/backpressure/backpressure.md) — Per design doc §11.4, every WebSocket connection MUST have a bounded outbound queue. This module owns the abstract poli…
|
||||
- [backpressure](./src/backpressure/backpressure.md) — Per design doc §11.4, every WebSocket connection MUST have a bounded outbound queue. This module owns the abstract poli…
|
||||
- [broker](./src/broker/broker.md) — A single-host deployment never needs a broker — the `SubscriptionBus` inside that process already sees every connection…
|
||||
- [broker](./src/broker/broker.md) — A single-host deployment never needs a broker — the `SubscriptionBus` inside that process already sees every connection…
|
||||
- [capability-id](./src/capability-id/capability-id.md) — `@suaveplan/api-types/capabilities` owns the closed `CapabilityId` union for the whole API foundation. `@suaveplan/api-…
|
||||
- [capability-id](./src/capability-id/capability-id.md) — `@suaveplan/api-types/capabilities` owns the closed `CapabilityId` union for the whole API foundation. `@suaveplan/api-…
|
||||
- [connection](./src/connection/connection.md) — `@suaveplan/api-ws/connection` declares the abstract `WsConnection` interface every concrete engine (`api-ws-bun`, futu…
|
||||
- [connection](./src/connection/connection.md) — `@suaveplan/api-ws/connection` declares the abstract `WsConnection` interface every concrete engine (`api-ws-bun`, futu…
|
||||
- [connection-registry](./src/connection-registry/connection-registry.md) — Every plugin endpoint that opens a WebSocket connection registers it with a host-owned `ConnectionRegistry`. The regist…
|
||||
- [connection-registry](./src/connection-registry/connection-registry.md) — Every plugin endpoint that opens a WebSocket connection registers it with a host-owned `ConnectionRegistry`. The regist…
|
||||
- [envelope](./src/envelope/envelope.md) — `@suaveplan/api-ws/envelope` owns the canonical Zod schema for every WebSocket frame that flows between the host and a…
|
||||
- [envelope](./src/envelope/envelope.md) — `@suaveplan/api-ws/envelope` owns the canonical Zod schema for every WebSocket frame that flows between the host and a…
|
||||
- [error-codes](./src/error-codes/error-codes.md) — `@suaveplan/api-ws` owns the abstract WebSocket contract. Every public failure path raises a `WsError` carrying a stabl…
|
||||
- [error-codes](./src/error-codes/error-codes.md) — `@suaveplan/api-ws` owns the abstract WebSocket contract. Every public failure path raises a `WsError` carrying a stabl…
|
||||
- [heartbeat](./src/heartbeat/heartbeat.md) — Every WebSocket connection that the Suaveplan API host accepts is policed by a heartbeat: the engine pings at a fixed c…
|
||||
- [heartbeat](./src/heartbeat/heartbeat.md) — Every WebSocket connection that the Suaveplan API host accepts is policed by a heartbeat: the engine pings at a fixed c…
|
||||
- [reconnect-token](./src/reconnect-token/reconnect-token.md) — When the host closes a WebSocket connection cleanly (heartbeat failure, deploy, transient network issue), it issues a r…
|
||||
- [reconnect-token](./src/reconnect-token/reconnect-token.md) — When the host closes a WebSocket connection cleanly (heartbeat failure, deploy, transient network issue), it issues a r…
|
||||
- [subscription-bus](./src/subscription-bus/subscription-bus.md) — `SubscriptionBus` is the broadcast surface every plugin uses to fan a payload out to every subscribed connection on the…
|
||||
- [subscription-bus](./src/subscription-bus/subscription-bus.md) — `SubscriptionBus` is the broadcast surface every plugin uses to fan a payload out to every subscribed connection on the…
|
||||
- [testing](./src/testing/conformance.md) — Every concrete WebSocket engine and broker the foundation publishes (`api-ws-bun`, `api-ws-broker-in-memory`, `api-ws-b…
|
||||
- [conformance](./src/testing/conformance.md) — Every concrete WebSocket engine and broker the foundation publishes (`api-ws-bun`, `api-ws-broker-in-memory`, `api-ws-b…
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Modules
|
||||
|
||||
| Subpath | Purpose |
|
||||
|---|---|
|
||||
| `./connection` | `WsConnection` interface, `WsConnectionState`, `SubscriptionFilter`, `SubscribeOptions`. [docs](./src/connection/connection.md) |
|
||||
| `./connection-registry` | `ConnectionRegistry` interface + `InMemoryConnectionRegistry` with `(tenantId)` and `(topic, tenantId)` indices. [docs](./src/connection-registry/connection-registry.md) |
|
||||
| `./subscription-bus` | `SubscriptionBus<Payload>` + `InMemorySubscriptionBus`; cross-tenant capability gate. [docs](./src/subscription-bus/subscription-bus.md) |
|
||||
| `./broker` | `WsBroker` multi-host fan-out contract — `publish`, `subscribe`, `dispose`. [docs](./src/broker/broker.md) |
|
||||
| `./envelope` | `WsEnvelope` Zod schema for wire frames; strict mode rejects unknown keys. [docs](./src/envelope/envelope.md) |
|
||||
| `./backpressure` | `BackpressurePolicy` + `evaluateBackpressure` (default `maxQueuedMessages = 256`). [docs](./src/backpressure/backpressure.md) |
|
||||
| `./heartbeat` | `HeartbeatPolicy` + `evaluateHeartbeat` (default `heartbeatMs = 30000`, two missed pongs to abort). [docs](./src/heartbeat/heartbeat.md) |
|
||||
| `./reconnect-token` | HMAC-SHA-256 reconnect-token envelope with 5-minute TTL; Web Crypto. [docs](./src/reconnect-token/reconnect-token.md) |
|
||||
| `./capability-id` | `WS_CAPABILITY_IDS` re-exports for `"ws"` and `"ws.broadcast-cross-tenant"`. [docs](./src/capability-id/capability-id.md) |
|
||||
| `./error-codes` | `WS_CODES` registry (8 codes) + `WsError` + engine throw helpers. [docs](./src/error-codes/error-codes.md) |
|
||||
| `./testing` | `runWsEngineConformance` harness + `inMemoryFactory` reference. [docs](./src/testing/conformance.md) |
|
||||
|
||||
## Out of scope (this package)
|
||||
|
||||
- Concrete engines (`api-ws-bun`, browser shims) — .
|
||||
- Concrete brokers (`api-ws-broker-redis`, `api-ws-broker-in-memory`) — Stages 5 / 7.
|
||||
- The `graphql-ws` protocol wiring — that lives in `api-graphql` engine adapters,
|
||||
which read this package's `SubscriptionBus`.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `@suaveplan/api-types workspace:^` — `Principal`, `TenantId`, `CapabilityId`.
|
||||
- `@suaveplan/error workspace:^` — `defineCodes` + `SuaveplanError`.
|
||||
- `@suaveplan/types workspace:^` — shared option bundles + clock contract.
|
||||
- `zod catalog:forms` — wire-envelope schema (default-import form `import z from "zod"`).
|
||||
- `tslib catalog:build`.
|
||||
|
||||
No transport dependencies — engines own that.
|
||||
|
||||
96
packages/api-stack/api/api-ws/package.json
Normal file
96
packages/api-stack/api/api-ws/package.json
Normal file
@@ -0,0 +1,96 @@
|
||||
{
|
||||
"name": "@suaveplan/api-ws",
|
||||
"version": "0.1.0",
|
||||
"type": "module",
|
||||
"sideEffects": false,
|
||||
"description": "Abstract WebSocket engine contract for the Suaveplan API foundation — Connection, ConnectionRegistry, SubscriptionBus, WsBroker, reconnect-token envelope, backpressure + heartbeat policies, cross-tenant capability gate, and a runWsEngineConformance harness. Stage-1 contracts only; concrete engines (api-ws-bun) and brokers (api-ws-broker-redis / -in-memory) plug behind these interfaces.",
|
||||
"license": "MIT",
|
||||
"author": "Suaveplan Team",
|
||||
"main": "./dist/index.js",
|
||||
"module": "./dist/index.js",
|
||||
"types": "./dist/index.d.ts",
|
||||
"exports": {
|
||||
"./package.json": "./package.json",
|
||||
".": {
|
||||
"import": {
|
||||
"types": "./dist/index.d.ts",
|
||||
"default": "./dist/index.js"
|
||||
},
|
||||
"require": {
|
||||
"types": "./dist/index.d.ts",
|
||||
"default": "./dist/index.js"
|
||||
}
|
||||
},
|
||||
"./connection": {
|
||||
"import": { "types": "./dist/connection/index.d.ts", "default": "./dist/connection/index.js" }
|
||||
},
|
||||
"./connection-registry": {
|
||||
"import": { "types": "./dist/connection-registry/index.d.ts", "default": "./dist/connection-registry/index.js" }
|
||||
},
|
||||
"./subscription-bus": {
|
||||
"import": { "types": "./dist/subscription-bus/index.d.ts", "default": "./dist/subscription-bus/index.js" }
|
||||
},
|
||||
"./broker": {
|
||||
"import": { "types": "./dist/broker/index.d.ts", "default": "./dist/broker/index.js" }
|
||||
},
|
||||
"./envelope": {
|
||||
"import": { "types": "./dist/envelope/index.d.ts", "default": "./dist/envelope/index.js" }
|
||||
},
|
||||
"./backpressure": {
|
||||
"import": { "types": "./dist/backpressure/index.d.ts", "default": "./dist/backpressure/index.js" }
|
||||
},
|
||||
"./heartbeat": {
|
||||
"import": { "types": "./dist/heartbeat/index.d.ts", "default": "./dist/heartbeat/index.js" }
|
||||
},
|
||||
"./reconnect-token": {
|
||||
"import": { "types": "./dist/reconnect-token/index.d.ts", "default": "./dist/reconnect-token/index.js" }
|
||||
},
|
||||
"./capability-id": {
|
||||
"import": { "types": "./dist/capability-id/index.d.ts", "default": "./dist/capability-id/index.js" }
|
||||
},
|
||||
"./error-codes": {
|
||||
"import": { "types": "./dist/error-codes/index.d.ts", "default": "./dist/error-codes/index.js" }
|
||||
},
|
||||
"./testing": {
|
||||
"import": { "types": "./dist/testing/index.d.ts", "default": "./dist/testing/index.js" }
|
||||
}
|
||||
},
|
||||
"scripts": {
|
||||
"build": "vite build",
|
||||
"test": "vitest run --passWithNoTests",
|
||||
"test:watch": "vitest",
|
||||
"test:coverage": "vitest run --coverage --passWithNoTests",
|
||||
"lint": "bunx biome check src/",
|
||||
"lint:fix": "bunx biome lint --fix --unsafe --max-diagnostics 500 src/",
|
||||
"format": "bunx biome format --write --max-diagnostics 500 src/",
|
||||
"check": "bunx biome check --write --unsafe --max-diagnostics 500 src/",
|
||||
"typecheck": "bunx tsc --noEmit --composite false -p tsconfig.lib.json",
|
||||
"docs:check": "bun run ../../../../scripts/docs-check.ts ."
|
||||
},
|
||||
"dependencies": {
|
||||
"@suaveplan/api-types": "workspace:^",
|
||||
"@suaveplan/error": "workspace:^",
|
||||
"@suaveplan/types": "workspace:^",
|
||||
"tslib": "catalog:build",
|
||||
"zod": "catalog:forms"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@suaveplan/testing": "workspace:^",
|
||||
"@types/node": "catalog:",
|
||||
"@vitest/coverage-istanbul": "catalog:testing",
|
||||
"fast-check": "catalog:testing",
|
||||
"typescript": "catalog:",
|
||||
"vite": "catalog:build",
|
||||
"vite-plugin-dts": "catalog:build",
|
||||
"vitest": "catalog:testing"
|
||||
},
|
||||
"publishConfig": {
|
||||
"registry": "https://npmjs.fq.io/",
|
||||
"access": "public"
|
||||
},
|
||||
"files": [
|
||||
"dist",
|
||||
"src",
|
||||
"README.md"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,74 @@
|
||||
# `backpressure` — bounded send-queue policy
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Purpose
|
||||
|
||||
Per design doc §11.4, every WebSocket connection MUST have a bounded outbound
|
||||
queue. This module owns the abstract policy + the evaluator helper that
|
||||
concrete engines (Bun, future browser shims) call when a connection's queue
|
||||
depth changes. Centralising the rule prevents engines from drifting from
|
||||
the documented 256-message default.
|
||||
|
||||
The eviction action is a hard close with the documented
|
||||
`BACKPRESSURE_EVICTED` reason — slow consumers do not get to keep their
|
||||
slot.
|
||||
|
||||
## Features
|
||||
|
||||
- `BackpressurePolicy` interface — one knob: `maxQueuedMessages`.
|
||||
- `DEFAULT_BACKPRESSURE_POLICY` — frozen `{ maxQueuedMessages: 256 }`.
|
||||
- `evaluateBackpressure(depth, policy?)` returns `"accept"` or `"evict"`.
|
||||
- `raiseBackpressureEvicted(connectionId)` throws the canonical `WsError`.
|
||||
|
||||
## Usage: Basic
|
||||
|
||||
```ts
|
||||
import {
|
||||
DEFAULT_BACKPRESSURE_POLICY,
|
||||
evaluateBackpressure,
|
||||
} from "@suaveplan/api-ws/backpressure";
|
||||
|
||||
if (evaluateBackpressure(queue.length) === "evict") {
|
||||
await connection.close(1013, "backpressure");
|
||||
}
|
||||
```
|
||||
|
||||
## Usage: Advanced
|
||||
|
||||
```ts
|
||||
import {
|
||||
evaluateBackpressure,
|
||||
raiseBackpressureEvicted,
|
||||
type BackpressurePolicy,
|
||||
} from "@suaveplan/api-ws/backpressure";
|
||||
|
||||
const tightPolicy: BackpressurePolicy = { maxQueuedMessages: 64 };
|
||||
|
||||
function enqueue(conn: { id: string; queue: unknown[] }, msg: unknown): void {
|
||||
conn.queue.push(msg);
|
||||
if (evaluateBackpressure(conn.queue.length, tightPolicy) === "evict") {
|
||||
raiseBackpressureEvicted(conn.id);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
- `interface BackpressurePolicy { maxQueuedMessages: number }`.
|
||||
- `const DEFAULT_BACKPRESSURE_POLICY: BackpressurePolicy` (frozen).
|
||||
- `type BackpressureAction = "accept" | "evict"`.
|
||||
- `evaluateBackpressure(queuedMessages, policy?): BackpressureAction`.
|
||||
- `raiseBackpressureEvicted(connectionId): never` — throws.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- The evaluator uses `>` so a depth equal to the cap still accepts; the
|
||||
cap is the maximum permitted, not the boundary.
|
||||
- The error message embeds the connection id so operators triaging a
|
||||
flood of evictions can correlate to a specific slow consumer without
|
||||
parsing the per-error context.
|
||||
- The thrown error is unconditional `never` so engines that call it
|
||||
inside a synchronous `enqueue` path don't need a noreturn shim.
|
||||
@@ -0,0 +1,56 @@
|
||||
import { describe, expect, it } from "@suaveplan/testing/runner";
|
||||
import { WS_CODES, WsError } from "../error-codes/error-codes.js";
|
||||
import {
|
||||
DEFAULT_BACKPRESSURE_POLICY,
|
||||
evaluateBackpressure,
|
||||
raiseBackpressureEvicted,
|
||||
} from "./backpressure.js";
|
||||
|
||||
describe("BackpressurePolicy", () => {
|
||||
it("default cap is 256", { timeout: 5000 }, () => {
|
||||
expect(DEFAULT_BACKPRESSURE_POLICY.maxQueuedMessages).toBe(256);
|
||||
});
|
||||
|
||||
it("policy is frozen", { timeout: 5000 }, () => {
|
||||
expect(Object.isFrozen(DEFAULT_BACKPRESSURE_POLICY)).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("evaluateBackpressure", () => {
|
||||
it("accepts depth at the cap", { timeout: 5000 }, () => {
|
||||
expect(evaluateBackpressure(256)).toBe("accept");
|
||||
});
|
||||
|
||||
it("evicts when depth exceeds the cap", { timeout: 5000 }, () => {
|
||||
expect(evaluateBackpressure(257)).toBe("evict");
|
||||
});
|
||||
|
||||
it("honours a custom policy", { timeout: 5000 }, () => {
|
||||
expect(evaluateBackpressure(10, { maxQueuedMessages: 8 })).toBe(
|
||||
"evict"
|
||||
);
|
||||
expect(evaluateBackpressure(8, { maxQueuedMessages: 8 })).toBe(
|
||||
"accept"
|
||||
);
|
||||
});
|
||||
|
||||
it("uses the default when no policy is supplied", { timeout: 5000 }, () => {
|
||||
expect(evaluateBackpressure(0)).toBe("accept");
|
||||
expect(evaluateBackpressure(1_000_000)).toBe("evict");
|
||||
});
|
||||
});
|
||||
|
||||
describe("raiseBackpressureEvicted", () => {
|
||||
it("throws a WsError with BACKPRESSURE_EVICTED", { timeout: 5000 }, () => {
|
||||
try {
|
||||
raiseBackpressureEvicted("conn-1");
|
||||
throw new Error("expected throw");
|
||||
} catch (caught) {
|
||||
expect(caught).toBeInstanceOf(WsError);
|
||||
if (caught instanceof WsError) {
|
||||
expect(caught.wsCode).toBe(WS_CODES.BACKPRESSURE_EVICTED);
|
||||
expect(caught.message).toContain("conn-1");
|
||||
}
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,50 @@
|
||||
import { WS_CODES, WsError } from "../error-codes/error-codes.js";
|
||||
|
||||
/**
|
||||
* Policy describing how engines bound their per-connection outbound queue.
|
||||
*
|
||||
* `maxQueuedMessages` is the upper bound; once a connection has more
|
||||
* messages queued than this, the engine MUST close it with the
|
||||
* `BACKPRESSURE_EVICTED` reason and remove it from the registry. The
|
||||
* default of 256 matches design doc §11.4.
|
||||
*/
|
||||
export interface BackpressurePolicy {
|
||||
readonly maxQueuedMessages: number;
|
||||
}
|
||||
|
||||
/** Default policy applied when no override is supplied. */
|
||||
export const DEFAULT_BACKPRESSURE_POLICY: BackpressurePolicy = Object.freeze({
|
||||
maxQueuedMessages: 256,
|
||||
});
|
||||
|
||||
/**
|
||||
* Reusable evaluator for engines. Given the current queue depth and a
|
||||
* policy, returns the action the engine MUST take.
|
||||
*
|
||||
* The contract package owns this helper so every concrete engine
|
||||
* (`api-ws-bun`, future browser shims) shares one definition of the
|
||||
* eviction trigger.
|
||||
*/
|
||||
export type BackpressureAction = "accept" | "evict";
|
||||
|
||||
export function evaluateBackpressure(
|
||||
queuedMessages: number,
|
||||
policy: BackpressurePolicy = DEFAULT_BACKPRESSURE_POLICY
|
||||
): BackpressureAction {
|
||||
if (queuedMessages > policy.maxQueuedMessages) {
|
||||
return "evict";
|
||||
}
|
||||
return "accept";
|
||||
}
|
||||
|
||||
/**
|
||||
* Helper that engines call when the policy has been violated. Throws a
|
||||
* `WsError` so the engine has one clean place to convert backpressure into
|
||||
* the documented close-frame reason.
|
||||
*/
|
||||
export function raiseBackpressureEvicted(connectionId: string): never {
|
||||
throw new WsError(
|
||||
WS_CODES.BACKPRESSURE_EVICTED,
|
||||
`connection ${connectionId} evicted: send queue overflow`
|
||||
);
|
||||
}
|
||||
6
packages/api-stack/api/api-ws/src/backpressure/index.ts
Normal file
6
packages/api-stack/api/api-ws/src/backpressure/index.ts
Normal file
@@ -0,0 +1,6 @@
|
||||
export type { BackpressureAction, BackpressurePolicy } from "./backpressure.js";
|
||||
export {
|
||||
DEFAULT_BACKPRESSURE_POLICY,
|
||||
evaluateBackpressure,
|
||||
raiseBackpressureEvicted,
|
||||
} from "./backpressure.js";
|
||||
81
packages/api-stack/api/api-ws/src/broker/broker.md
Normal file
81
packages/api-stack/api/api-ws/src/broker/broker.md
Normal file
@@ -0,0 +1,81 @@
|
||||
# `broker` — multi-host fan-out contract
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Purpose
|
||||
|
||||
A single-host deployment never needs a broker — the `SubscriptionBus`
|
||||
inside that process already sees every connection. Production deployments
|
||||
that run multiple host replicas behind a load balancer DO need one: a
|
||||
broadcast issued on host A has to reach the connections attached to host
|
||||
B without migrating connections between processes. The `WsBroker` contract
|
||||
defined here is the seam those broker adapters implement.
|
||||
|
||||
Concrete brokers (`api-ws-broker-in-memory` for single-host tests,
|
||||
`api-ws-broker-redis` for production) plug behind this interface and stay
|
||||
out of plugin code paths.
|
||||
|
||||
## Features
|
||||
|
||||
- `BrokerEnvelope` — wire payload (`topic`, `tenant`, `payload`, optional
|
||||
`originHost`).
|
||||
- `BrokerHandler` — subscriber callback signature.
|
||||
- `BrokerSubscription` — disposal handle returned from `subscribe`.
|
||||
- `WsBroker<Payload>` interface — `publish`, `subscribe`, `dispose`. Each
|
||||
method may return synchronously or asynchronously so in-memory brokers
|
||||
stay cheap and Redis-backed brokers can `await` round trips.
|
||||
|
||||
## Usage: Basic
|
||||
|
||||
```ts
|
||||
import type { WsBroker } from "@suaveplan/api-ws/broker";
|
||||
|
||||
async function fanOut(broker: WsBroker<{ orderId: string }>): Promise<void> {
|
||||
await broker.publish("orders.created", {
|
||||
topic: "orders.created",
|
||||
tenant: tenantId,
|
||||
payload: { orderId: "o1" },
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## Usage: Advanced
|
||||
|
||||
```ts
|
||||
import type { WsBroker, BrokerSubscription } from "@suaveplan/api-ws/broker";
|
||||
|
||||
async function bridge(
|
||||
broker: WsBroker<unknown>,
|
||||
local: { broadcast: (...args: unknown[]) => void },
|
||||
): Promise<BrokerSubscription> {
|
||||
const subscription = await broker.subscribe("orders.created", (envelope) => {
|
||||
local.broadcast(envelope.topic, {
|
||||
tenant: envelope.tenant,
|
||||
payload: envelope.payload,
|
||||
});
|
||||
});
|
||||
return subscription;
|
||||
}
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
- `interface BrokerEnvelope<Payload> { topic, tenant, payload, originHost? }`.
|
||||
- `type BrokerHandler<Payload> = (env: BrokerEnvelope<Payload>) => void | Promise<void>`.
|
||||
- `interface BrokerSubscription { topic; unsubscribe(): void | Promise<void> }`.
|
||||
- `interface WsBroker<Payload> { publish, subscribe, dispose }`.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- The contract intentionally does not specify reliability semantics. Each
|
||||
adapter declares its own delivery guarantees (`in-memory` is at-most-
|
||||
once with FIFO inside the process; `redis` is at-most-once with Redis
|
||||
pub/sub semantics). Plugins that need stronger guarantees use the
|
||||
saga / 2PC capabilities elsewhere in the foundation.
|
||||
- `originHost` is optional so adapters that don't need loop-back
|
||||
suppression can omit it. Adapters that DO suppress loop-back compare
|
||||
against the local host's identity at the receive side.
|
||||
- `dispose` MUST close every subscription cleanly; the conformance
|
||||
harness pins this invariant against every concrete adapter.
|
||||
@@ -0,0 +1,37 @@
|
||||
import { describe, expectTypeOf, it } from "@suaveplan/testing/runner";
|
||||
import type {
|
||||
BrokerEnvelope,
|
||||
BrokerHandler,
|
||||
BrokerSubscription,
|
||||
WsBroker,
|
||||
} from "./broker.js";
|
||||
|
||||
describe("WsBroker conformance", () => {
|
||||
it("declares publish, subscribe, and dispose", { timeout: 5000 }, () => {
|
||||
expectTypeOf<WsBroker>().toHaveProperty("publish");
|
||||
expectTypeOf<WsBroker>().toHaveProperty("subscribe");
|
||||
expectTypeOf<WsBroker>().toHaveProperty("dispose");
|
||||
});
|
||||
|
||||
it("publish accepts a BrokerEnvelope", { timeout: 5000 }, () => {
|
||||
expectTypeOf<WsBroker["publish"]>().parameters.toEqualTypeOf<
|
||||
[topic: string, envelope: BrokerEnvelope<unknown>]
|
||||
>();
|
||||
});
|
||||
|
||||
it("subscribe returns a BrokerSubscription (sync or async)", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
expectTypeOf<WsBroker["subscribe"]>().returns.toEqualTypeOf<
|
||||
BrokerSubscription | Promise<BrokerSubscription>
|
||||
>();
|
||||
});
|
||||
|
||||
it("BrokerHandler is a function of BrokerEnvelope", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
expectTypeOf<BrokerHandler<number>>().toEqualTypeOf<
|
||||
(envelope: BrokerEnvelope<number>) => void | Promise<void>
|
||||
>();
|
||||
});
|
||||
});
|
||||
47
packages/api-stack/api/api-ws/src/broker/broker.ts
Normal file
47
packages/api-stack/api/api-ws/src/broker/broker.ts
Normal file
@@ -0,0 +1,47 @@
|
||||
import type { TenantId } from "@suaveplan/api-types/tenant";
|
||||
|
||||
/**
|
||||
* Wire payload published across host replicas. Carries everything the
|
||||
* receiving host needs to redeliver the broadcast to its locally-attached
|
||||
* subscribers — connections are NOT migrated, only the broadcast event is.
|
||||
*/
|
||||
export interface BrokerEnvelope<Payload = unknown> {
|
||||
readonly topic: string;
|
||||
readonly tenant: TenantId;
|
||||
readonly payload: Payload;
|
||||
readonly originHost?: string;
|
||||
}
|
||||
|
||||
/** Subscriber handler invoked once per broker-delivered envelope. */
|
||||
export type BrokerHandler<Payload = unknown> = (
|
||||
envelope: BrokerEnvelope<Payload>
|
||||
) => void | Promise<void>;
|
||||
|
||||
/** Disposal handle returned by {@link WsBroker.subscribe}. */
|
||||
export interface BrokerSubscription {
|
||||
readonly topic: string;
|
||||
unsubscribe(): void | Promise<void>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Multi-host fan-out contract.
|
||||
*
|
||||
* Brokers wrap a host's local `SubscriptionBus` so that
|
||||
* `bus.broadcast(...)` is visible to every other host replica in the
|
||||
* deployment. The broker MUST NOT migrate connections between hosts; it
|
||||
* only makes broadcast events visible.
|
||||
*
|
||||
* Concrete implementations live in `api-ws-broker-in-memory` (single-host
|
||||
* default) and `api-ws-broker-redis` (multi-host production).
|
||||
*/
|
||||
export interface WsBroker<Payload = unknown> {
|
||||
publish(
|
||||
topic: string,
|
||||
envelope: BrokerEnvelope<Payload>
|
||||
): void | Promise<void>;
|
||||
subscribe(
|
||||
topic: string,
|
||||
handler: BrokerHandler<Payload>
|
||||
): BrokerSubscription | Promise<BrokerSubscription>;
|
||||
dispose(): void | Promise<void>;
|
||||
}
|
||||
6
packages/api-stack/api/api-ws/src/broker/index.ts
Normal file
6
packages/api-stack/api/api-ws/src/broker/index.ts
Normal file
@@ -0,0 +1,6 @@
|
||||
export type {
|
||||
BrokerEnvelope,
|
||||
BrokerHandler,
|
||||
BrokerSubscription,
|
||||
WsBroker,
|
||||
} from "./broker.js";
|
||||
@@ -0,0 +1,73 @@
|
||||
# `capability-id` — `ws` + `ws.broadcast-cross-tenant`
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Purpose
|
||||
|
||||
`@suaveplan/api-types/capabilities` owns the closed `CapabilityId` union for
|
||||
the whole API foundation. `@suaveplan/api-ws/capability-id` re-exports the
|
||||
two literals this package contributes (`"ws"` and
|
||||
`"ws.broadcast-cross-tenant"`) plus a frozen `WS_CAPABILITY_IDS` map so
|
||||
plugins authoring manifests have a single import to reach for. Type-level
|
||||
extracts pin the literals so adding a new capability upstream cannot
|
||||
silently drift this package's view.
|
||||
|
||||
The frozen object plus the `expectTypeOf` assertions in the conformance
|
||||
test together guarantee both compile-time AND run-time identity of the two
|
||||
capability ids.
|
||||
|
||||
## Features
|
||||
|
||||
- `WsCapabilityId` literal type extract.
|
||||
- `WsBroadcastCrossTenantCapabilityId` literal type extract.
|
||||
- `WS_CAPABILITY_IDS` frozen record (`base`, `crossTenantBroadcast`).
|
||||
- Re-exports the upstream `CapabilityId` union for convenience.
|
||||
|
||||
## Usage: Basic
|
||||
|
||||
```ts
|
||||
import { WS_CAPABILITY_IDS } from "@suaveplan/api-ws/capability-id";
|
||||
|
||||
definePlugin({
|
||||
requires: [WS_CAPABILITY_IDS.base] as const,
|
||||
websockets: { /* ... */ },
|
||||
});
|
||||
```
|
||||
|
||||
## Usage: Advanced
|
||||
|
||||
```ts
|
||||
import {
|
||||
WS_CAPABILITY_IDS,
|
||||
type WsBroadcastCrossTenantCapabilityId,
|
||||
} from "@suaveplan/api-ws/capability-id";
|
||||
|
||||
function assertCrossTenantOk(caps: ReadonlySet<string>): void {
|
||||
if (!caps.has(WS_CAPABILITY_IDS.crossTenantBroadcast)) {
|
||||
throw new Error("missing capability");
|
||||
}
|
||||
}
|
||||
|
||||
type Cap = WsBroadcastCrossTenantCapabilityId;
|
||||
const value: Cap = "ws.broadcast-cross-tenant";
|
||||
void value;
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
- `type WsCapabilityId = "ws"`.
|
||||
- `type WsBroadcastCrossTenantCapabilityId = "ws.broadcast-cross-tenant"`.
|
||||
- `const WS_CAPABILITY_IDS: { base: "ws"; crossTenantBroadcast: "ws.broadcast-cross-tenant" }` — frozen.
|
||||
- Re-exported: `type CapabilityId from "@suaveplan/api-types/capabilities"`.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- The `satisfies` clause on `WS_CAPABILITY_IDS` is the compile-time gate
|
||||
that fails if either literal is removed from the upstream union, so a
|
||||
future deprecation in api-types will fail to typecheck here and the
|
||||
build stops at the contract boundary rather than at an integration site.
|
||||
- `Extract` keeps the dependency direction one-way — api-ws depends on
|
||||
api-types, never the reverse. Engines downstream of api-ws inherit the
|
||||
same extracts.
|
||||
@@ -0,0 +1,32 @@
|
||||
import type { CapabilityId } from "@suaveplan/api-types/capabilities";
|
||||
import { describe, expect, expectTypeOf, it } from "@suaveplan/testing/runner";
|
||||
import {
|
||||
WS_CAPABILITY_IDS,
|
||||
type WsBroadcastCrossTenantCapabilityId,
|
||||
type WsCapabilityId,
|
||||
} from "./capability-id.js";
|
||||
|
||||
describe("CapabilityId augmentation", () => {
|
||||
it("ws is a valid CapabilityId", { timeout: 5000 }, () => {
|
||||
expectTypeOf<"ws">().toMatchTypeOf<CapabilityId>();
|
||||
expectTypeOf<WsCapabilityId>().toEqualTypeOf<"ws">();
|
||||
});
|
||||
|
||||
it("ws.broadcast-cross-tenant is a valid CapabilityId", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
expectTypeOf<"ws.broadcast-cross-tenant">().toMatchTypeOf<CapabilityId>();
|
||||
expectTypeOf<WsBroadcastCrossTenantCapabilityId>().toEqualTypeOf<"ws.broadcast-cross-tenant">();
|
||||
});
|
||||
|
||||
it("WS_CAPABILITY_IDS exposes both literals", { timeout: 5000 }, () => {
|
||||
expect(WS_CAPABILITY_IDS.base).toBe("ws");
|
||||
expect(WS_CAPABILITY_IDS.crossTenantBroadcast).toBe(
|
||||
"ws.broadcast-cross-tenant"
|
||||
);
|
||||
});
|
||||
|
||||
it("WS_CAPABILITY_IDS is frozen", { timeout: 5000 }, () => {
|
||||
expect(Object.isFrozen(WS_CAPABILITY_IDS)).toBe(true);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,28 @@
|
||||
import type { CapabilityId } from "@suaveplan/api-types/capabilities";
|
||||
|
||||
/**
|
||||
* Literal capability id the host vends to a plugin for the right to open
|
||||
* WebSocket endpoints at all.
|
||||
*/
|
||||
export type WsCapabilityId = Extract<CapabilityId, "ws">;
|
||||
|
||||
/**
|
||||
* Literal capability id the host vends to a plugin for the right to issue
|
||||
* cross-tenant broadcasts. Default is deny; the host audit-logs every use.
|
||||
*/
|
||||
export type WsBroadcastCrossTenantCapabilityId = Extract<
|
||||
CapabilityId,
|
||||
"ws.broadcast-cross-tenant"
|
||||
>;
|
||||
|
||||
/** The two ids this package contributes to the foundation's CapabilityId. */
|
||||
export const WS_CAPABILITY_IDS = Object.freeze({
|
||||
base: "ws",
|
||||
crossTenantBroadcast: "ws.broadcast-cross-tenant",
|
||||
} as const satisfies Readonly<{
|
||||
base: WsCapabilityId;
|
||||
crossTenantBroadcast: WsBroadcastCrossTenantCapabilityId;
|
||||
}>);
|
||||
|
||||
/** Re-export the upstream union so consumers can import it from one place. */
|
||||
export type { CapabilityId } from "@suaveplan/api-types/capabilities";
|
||||
6
packages/api-stack/api/api-ws/src/capability-id/index.ts
Normal file
6
packages/api-stack/api/api-ws/src/capability-id/index.ts
Normal file
@@ -0,0 +1,6 @@
|
||||
export type {
|
||||
CapabilityId,
|
||||
WsBroadcastCrossTenantCapabilityId,
|
||||
WsCapabilityId,
|
||||
} from "./capability-id.js";
|
||||
export { WS_CAPABILITY_IDS } from "./capability-id.js";
|
||||
@@ -0,0 +1,86 @@
|
||||
# `connection-registry` — multi-index lookup for active connections
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Purpose
|
||||
|
||||
Every plugin endpoint that opens a WebSocket connection registers it with a
|
||||
host-owned `ConnectionRegistry`. The registry is the lookup surface every
|
||||
other piece of the engine consumes: the subscription bus iterates
|
||||
connections by `(topic, tenant)`, the per-tenant cap counts by `tenant`,
|
||||
the heartbeat loop walks the registry to find stale connections. Keeping
|
||||
the contract here lets future broker-backed registries (Redis, SurrealDB)
|
||||
swap in without touching plugin code.
|
||||
|
||||
This module ships the abstract `ConnectionRegistry` interface AND a
|
||||
single-host in-memory implementation. The in-memory registry doubles as
|
||||
the default for the conformance harness and is what every test in the
|
||||
Stage-1 contract depends on.
|
||||
|
||||
## Features
|
||||
|
||||
- `ConnectionRegistry` interface — `add`, `remove`, `lookupByTenant`,
|
||||
`lookupByTopic`, `countByTenant`.
|
||||
- `InMemoryConnectionRegistry` — O(1) `add` / `remove` / lookups via three
|
||||
internal maps; idempotent `add` / `remove`; topic bindings dropped
|
||||
automatically when a connection is removed.
|
||||
- `recordSubscription(conn, topic, tenant)` and `dropSubscription(...)`
|
||||
hooks the subscription bus uses to keep the `(topic, tenant)` index in
|
||||
sync.
|
||||
|
||||
## Usage: Basic
|
||||
|
||||
```ts
|
||||
import { InMemoryConnectionRegistry } from "@suaveplan/api-ws/connection-registry";
|
||||
|
||||
const registry = new InMemoryConnectionRegistry();
|
||||
registry.add(connection);
|
||||
const peersForTenant = registry.lookupByTenant(connection.tenantId);
|
||||
registry.remove(connection);
|
||||
```
|
||||
|
||||
## Usage: Advanced
|
||||
|
||||
```ts
|
||||
import {
|
||||
InMemoryConnectionRegistry,
|
||||
type ConnectionRegistry,
|
||||
} from "@suaveplan/api-ws/connection-registry";
|
||||
|
||||
class TenantCapGate {
|
||||
constructor(
|
||||
private readonly registry: ConnectionRegistry,
|
||||
private readonly maxPerTenant: number,
|
||||
) {}
|
||||
|
||||
accept(conn: { tenantId: TenantId }): boolean {
|
||||
return this.registry.countByTenant(conn.tenantId) < this.maxPerTenant;
|
||||
}
|
||||
}
|
||||
|
||||
const registry: ConnectionRegistry = new InMemoryConnectionRegistry();
|
||||
const gate = new TenantCapGate(registry, 1000);
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
- `interface ConnectionRegistry { add, remove, lookupByTenant, lookupByTopic, countByTenant }`.
|
||||
- `class InMemoryConnectionRegistry implements ConnectionRegistry`.
|
||||
- `recordSubscription(connection, topic, tenant)` — wired by
|
||||
`SubscriptionBus.subscribe`.
|
||||
- `dropSubscription(connection, topic, tenant)` — wired by `unsubscribe`.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- The three indices (by id, by tenant, by `(topic, tenant)`) stay in sync
|
||||
through the `add` / `remove` / `recordSubscription` / `dropSubscription`
|
||||
quartet. `remove` walks the topic index because in practice a
|
||||
connection's full subscription set isn't carried on the `WsConnection`
|
||||
contract — engines may keep that state themselves.
|
||||
- `recordSubscription` silently ignores unknown connections so the
|
||||
subscription bus can call it without re-checking membership.
|
||||
- The `(topic, tenant)` key uses `::` as a delimiter; tenant ids that
|
||||
contain `::` are still distinguishable because the encoding is
|
||||
prefix-based, not lossy.
|
||||
@@ -0,0 +1,193 @@
|
||||
import type { Principal } from "@suaveplan/api-types/principal";
|
||||
import type { TenantId } from "@suaveplan/api-types/tenant";
|
||||
import { describe, expect, it } from "@suaveplan/testing/runner";
|
||||
import type { WsConnection } from "../connection/connection.js";
|
||||
import { InMemoryConnectionRegistry } from "./connection-registry.js";
|
||||
|
||||
const tenantA = "tenant-a" as unknown as TenantId;
|
||||
const tenantB = "tenant-b" as unknown as TenantId;
|
||||
|
||||
function makeConn(id: string, tenant: TenantId): WsConnection {
|
||||
return {
|
||||
id,
|
||||
principal: {
|
||||
id: "p1" as unknown as Principal["id"],
|
||||
scopes: [],
|
||||
claims: {},
|
||||
},
|
||||
tenantId: tenant,
|
||||
lastEventId: null,
|
||||
state: "open",
|
||||
subscribe(): void {
|
||||
/* no-op */
|
||||
},
|
||||
unsubscribe(): void {
|
||||
/* no-op */
|
||||
},
|
||||
send(): void {
|
||||
/* no-op */
|
||||
},
|
||||
close(): void {
|
||||
/* no-op */
|
||||
},
|
||||
ack(): void {
|
||||
/* no-op */
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
describe("InMemoryConnectionRegistry", () => {
|
||||
it("lookupByTenant returns matching set", { timeout: 5000 }, () => {
|
||||
const reg = new InMemoryConnectionRegistry();
|
||||
reg.add(makeConn("c1", tenantA));
|
||||
reg.add(makeConn("c2", tenantA));
|
||||
reg.add(makeConn("c3", tenantA));
|
||||
reg.add(makeConn("c4", tenantB));
|
||||
reg.add(makeConn("c5", tenantB));
|
||||
expect(reg.lookupByTenant(tenantA).length).toBe(3);
|
||||
expect(reg.lookupByTenant(tenantB).length).toBe(2);
|
||||
});
|
||||
|
||||
it("countByTenant reflects buckets", { timeout: 5000 }, () => {
|
||||
const reg = new InMemoryConnectionRegistry();
|
||||
expect(reg.countByTenant(tenantA)).toBe(0);
|
||||
reg.add(makeConn("c1", tenantA));
|
||||
expect(reg.countByTenant(tenantA)).toBe(1);
|
||||
});
|
||||
|
||||
it("add is idempotent for the same id", { timeout: 5000 }, () => {
|
||||
const reg = new InMemoryConnectionRegistry();
|
||||
const conn = makeConn("c1", tenantA);
|
||||
reg.add(conn);
|
||||
reg.add(conn);
|
||||
expect(reg.countByTenant(tenantA)).toBe(1);
|
||||
});
|
||||
|
||||
it("remove is idempotent", { timeout: 5000 }, () => {
|
||||
const reg = new InMemoryConnectionRegistry();
|
||||
const conn = makeConn("c1", tenantA);
|
||||
reg.add(conn);
|
||||
reg.remove(conn);
|
||||
reg.remove(conn);
|
||||
expect(reg.countByTenant(tenantA)).toBe(0);
|
||||
});
|
||||
|
||||
it("remove clears the tenant bucket when empty", { timeout: 5000 }, () => {
|
||||
const reg = new InMemoryConnectionRegistry();
|
||||
const conn = makeConn("c1", tenantA);
|
||||
reg.add(conn);
|
||||
reg.remove(conn);
|
||||
expect(reg.lookupByTenant(tenantA)).toEqual([]);
|
||||
});
|
||||
|
||||
it("lookupByTopic returns connections subscribed to a (topic, tenant)", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const reg = new InMemoryConnectionRegistry();
|
||||
const c1 = makeConn("c1", tenantA);
|
||||
const c2 = makeConn("c2", tenantA);
|
||||
reg.add(c1);
|
||||
reg.add(c2);
|
||||
reg.recordSubscription(c1, "orders", tenantA);
|
||||
reg.recordSubscription(c2, "orders", tenantA);
|
||||
expect(
|
||||
reg
|
||||
.lookupByTopic("orders", tenantA)
|
||||
.map((c) => c.id)
|
||||
.sort()
|
||||
).toEqual(["c1", "c2"]);
|
||||
});
|
||||
|
||||
it("lookupByTopic returns empty array for unknown topic", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const reg = new InMemoryConnectionRegistry();
|
||||
expect(reg.lookupByTopic("missing")).toEqual([]);
|
||||
expect(reg.lookupByTopic("missing", tenantA)).toEqual([]);
|
||||
});
|
||||
|
||||
it("dropSubscription removes the binding", { timeout: 5000 }, () => {
|
||||
const reg = new InMemoryConnectionRegistry();
|
||||
const c1 = makeConn("c1", tenantA);
|
||||
reg.add(c1);
|
||||
reg.recordSubscription(c1, "orders", tenantA);
|
||||
reg.dropSubscription(c1, "orders", tenantA);
|
||||
expect(reg.lookupByTopic("orders", tenantA)).toEqual([]);
|
||||
});
|
||||
|
||||
it("dropSubscription on unknown topic is a no-op", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const reg = new InMemoryConnectionRegistry();
|
||||
const c1 = makeConn("c1", tenantA);
|
||||
reg.dropSubscription(c1, "ghost", tenantA);
|
||||
expect(reg.lookupByTopic("ghost", tenantA)).toEqual([]);
|
||||
});
|
||||
|
||||
it("recordSubscription ignores unknown connection", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const reg = new InMemoryConnectionRegistry();
|
||||
const c1 = makeConn("c1", tenantA);
|
||||
reg.recordSubscription(c1, "orders", tenantA);
|
||||
expect(reg.lookupByTopic("orders", tenantA)).toEqual([]);
|
||||
});
|
||||
|
||||
it("removing a connection also drops its topic bindings", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const reg = new InMemoryConnectionRegistry();
|
||||
const c1 = makeConn("c1", tenantA);
|
||||
const c2 = makeConn("c2", tenantA);
|
||||
reg.add(c1);
|
||||
reg.add(c2);
|
||||
reg.recordSubscription(c1, "orders", tenantA);
|
||||
reg.recordSubscription(c2, "orders", tenantA);
|
||||
reg.remove(c1);
|
||||
expect(reg.lookupByTopic("orders", tenantA).map((c) => c.id)).toEqual([
|
||||
"c2",
|
||||
]);
|
||||
});
|
||||
|
||||
it("lookupByTopic without tenant uses the bare topic bucket", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const reg = new InMemoryConnectionRegistry();
|
||||
const c1 = makeConn("c1", tenantA);
|
||||
reg.add(c1);
|
||||
// Manually record under the untenanted key
|
||||
(reg as InMemoryConnectionRegistry).recordSubscription(
|
||||
c1,
|
||||
"global",
|
||||
undefined as unknown as TenantId
|
||||
);
|
||||
expect(reg.lookupByTopic("global").map((c) => c.id)).toEqual(["c1"]);
|
||||
});
|
||||
|
||||
it("removing the only connection in a topic bucket empties it", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const reg = new InMemoryConnectionRegistry();
|
||||
const solo = makeConn("solo", tenantA);
|
||||
reg.add(solo);
|
||||
reg.recordSubscription(solo, "orders", tenantA);
|
||||
reg.remove(solo);
|
||||
expect(reg.lookupByTopic("orders", tenantA)).toEqual([]);
|
||||
});
|
||||
|
||||
it("dropSubscription leaves other subscribers intact", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const reg = new InMemoryConnectionRegistry();
|
||||
const a = makeConn("a", tenantA);
|
||||
const b = makeConn("b", tenantA);
|
||||
reg.add(a);
|
||||
reg.add(b);
|
||||
reg.recordSubscription(a, "orders", tenantA);
|
||||
reg.recordSubscription(b, "orders", tenantA);
|
||||
reg.dropSubscription(a, "orders", tenantA);
|
||||
expect(reg.lookupByTopic("orders", tenantA).map((c) => c.id)).toEqual([
|
||||
"b",
|
||||
]);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,129 @@
|
||||
import type { TenantId } from "@suaveplan/api-types/tenant";
|
||||
import type { WsConnection } from "../connection/connection.js";
|
||||
|
||||
/**
|
||||
* Lookup contract for the host's per-plugin connection registry. The
|
||||
* concrete in-memory implementation lives below; multi-host deployments
|
||||
* implement the same interface against Redis / SurrealDB / whatever the
|
||||
* deployment chose.
|
||||
*/
|
||||
export interface ConnectionRegistry {
|
||||
add(connection: WsConnection): void;
|
||||
remove(connection: WsConnection): void;
|
||||
lookupByTenant(tenant: TenantId): readonly WsConnection[];
|
||||
lookupByTopic(topic: string, tenant?: TenantId): readonly WsConnection[];
|
||||
countByTenant(tenant: TenantId): number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Minimal in-memory registry that backs the conformance harness and the
|
||||
* single-host default. Uses a `Set` keyed by connection id under the hood
|
||||
* so insertion / removal stay O(1) amortised.
|
||||
*
|
||||
* The `subscriptions` map is populated by {@link InMemoryConnectionRegistry.recordSubscription}
|
||||
* which the subscription bus calls on every successful `subscribe`.
|
||||
*/
|
||||
export class InMemoryConnectionRegistry implements ConnectionRegistry {
|
||||
private readonly byId = new Map<string, WsConnection>();
|
||||
private readonly byTenant = new Map<TenantId, Set<string>>();
|
||||
private readonly byTopic = new Map<string, Set<string>>();
|
||||
|
||||
public add(connection: WsConnection): void {
|
||||
if (this.byId.has(connection.id)) {
|
||||
return;
|
||||
}
|
||||
this.byId.set(connection.id, connection);
|
||||
const tenantBucket =
|
||||
this.byTenant.get(connection.tenantId) ?? new Set<string>();
|
||||
tenantBucket.add(connection.id);
|
||||
this.byTenant.set(connection.tenantId, tenantBucket);
|
||||
}
|
||||
|
||||
public remove(connection: WsConnection): void {
|
||||
if (!this.byId.has(connection.id)) {
|
||||
return;
|
||||
}
|
||||
this.byId.delete(connection.id);
|
||||
// `add` always populates byTenant in lockstep with byId, so a
|
||||
// membership check above suffices — the bucket is guaranteed.
|
||||
const tenantBucket = this.byTenant.get(
|
||||
connection.tenantId
|
||||
) as Set<string>;
|
||||
tenantBucket.delete(connection.id);
|
||||
if (tenantBucket.size === 0) {
|
||||
this.byTenant.delete(connection.tenantId);
|
||||
}
|
||||
for (const [topic, ids] of this.byTopic) {
|
||||
ids.delete(connection.id);
|
||||
if (ids.size === 0) {
|
||||
this.byTopic.delete(topic);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
public lookupByTenant(tenant: TenantId): readonly WsConnection[] {
|
||||
const ids = this.byTenant.get(tenant);
|
||||
if (ids === undefined) return [];
|
||||
const out: WsConnection[] = [];
|
||||
for (const id of ids) {
|
||||
// byId is updated in lockstep with byTenant, so the entry is
|
||||
// always present here.
|
||||
out.push(this.byId.get(id) as WsConnection);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
public lookupByTopic(
|
||||
topic: string,
|
||||
tenant?: TenantId
|
||||
): readonly WsConnection[] {
|
||||
const ids = this.byTopic.get(this.topicKey(topic, tenant));
|
||||
if (ids === undefined) return [];
|
||||
const out: WsConnection[] = [];
|
||||
for (const id of ids) {
|
||||
out.push(this.byId.get(id) as WsConnection);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
public countByTenant(tenant: TenantId): number {
|
||||
return this.byTenant.get(tenant)?.size ?? 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Called by `SubscriptionBus` whenever a connection subscribes to a
|
||||
* topic. Indexed by the `(topic, tenant)` pair so lookups are O(1).
|
||||
*/
|
||||
public recordSubscription(
|
||||
connection: WsConnection,
|
||||
topic: string,
|
||||
tenant: TenantId
|
||||
): void {
|
||||
if (!this.byId.has(connection.id)) {
|
||||
return;
|
||||
}
|
||||
const key = this.topicKey(topic, tenant);
|
||||
const bucket = this.byTopic.get(key) ?? new Set<string>();
|
||||
bucket.add(connection.id);
|
||||
this.byTopic.set(key, bucket);
|
||||
}
|
||||
|
||||
/** Symmetric removal called by the subscription bus on `unsubscribe`. */
|
||||
public dropSubscription(
|
||||
connection: WsConnection,
|
||||
topic: string,
|
||||
tenant: TenantId
|
||||
): void {
|
||||
const key = this.topicKey(topic, tenant);
|
||||
const bucket = this.byTopic.get(key);
|
||||
if (bucket === undefined) return;
|
||||
bucket.delete(connection.id);
|
||||
if (bucket.size === 0) {
|
||||
this.byTopic.delete(key);
|
||||
}
|
||||
}
|
||||
|
||||
private topicKey(topic: string, tenant?: TenantId): string {
|
||||
return tenant === undefined ? topic : `${tenant as string}::${topic}`;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,2 @@
|
||||
export type { ConnectionRegistry } from "./connection-registry.js";
|
||||
export { InMemoryConnectionRegistry } from "./connection-registry.js";
|
||||
77
packages/api-stack/api/api-ws/src/connection/connection.md
Normal file
77
packages/api-stack/api/api-ws/src/connection/connection.md
Normal file
@@ -0,0 +1,77 @@
|
||||
# `connection` — canonical `WsConnection` contract
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Purpose
|
||||
|
||||
`@suaveplan/api-ws/connection` declares the abstract `WsConnection`
|
||||
interface every concrete engine (`api-ws-bun`, future browser shims)
|
||||
implements. Plugins author against this contract; the host wires whichever
|
||||
engine the deployment requires. This is The type-only foundation —
|
||||
no runtime, no state, just the interface and its supporting helper types.
|
||||
|
||||
The handshake principal is frozen for the connection's lifetime; the
|
||||
contract intentionally exposes `principal` as a `readonly Principal` so a
|
||||
plugin cannot mutate it mid-session, and the host emits
|
||||
`connection.principal_expired` (an api-host concern) when the underlying
|
||||
session lapses.
|
||||
|
||||
## Features
|
||||
|
||||
- `WsConnection` interface — id, principal, tenantId, lastEventId, state,
|
||||
plus `subscribe / unsubscribe / send / close / ack`.
|
||||
- `WsConnectionState` — `"open" | "closing" | "closed"`.
|
||||
- `SubscribeOptions` — tenant override and optional `filter` predicate.
|
||||
- `SubscriptionFilter<Payload>` — `(payload: Payload) => boolean`.
|
||||
|
||||
## Usage: Basic
|
||||
|
||||
```ts
|
||||
import type { WsConnection } from "@suaveplan/api-ws/connection";
|
||||
|
||||
async function onConnect(conn: WsConnection): Promise<void> {
|
||||
await conn.subscribe("orders.created", { tenant: conn.tenantId });
|
||||
}
|
||||
```
|
||||
|
||||
## Usage: Advanced
|
||||
|
||||
```ts
|
||||
import type {
|
||||
SubscribeOptions,
|
||||
WsConnection,
|
||||
} from "@suaveplan/api-ws/connection";
|
||||
|
||||
interface OrderEvent { priority: number }
|
||||
|
||||
const opts: SubscribeOptions<OrderEvent> = {
|
||||
tenant: tenantId,
|
||||
filter: (payload): boolean => payload.priority >= 5,
|
||||
};
|
||||
|
||||
await conn.subscribe("orders.created", opts);
|
||||
await conn.send({ id: "1", type: "ack", topic: "orders.created" });
|
||||
conn.ack("e-42");
|
||||
if (conn.state !== "open") {
|
||||
return;
|
||||
}
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
- `interface WsConnection { id, principal, tenantId, lastEventId, state, subscribe, unsubscribe, send, close, ack }`.
|
||||
- `type WsConnectionState = "open" | "closing" | "closed"`.
|
||||
- `type SubscriptionFilter<Payload> = (payload: Payload) => boolean`.
|
||||
- `interface SubscribeOptions<Payload> { tenant?: TenantId; filter?: SubscriptionFilter<Payload> }`.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- `send` accepts a `WsEnvelope` (the wire schema) so engines can apply
|
||||
the same boundary validation on outbound frames they apply on inbound.
|
||||
- `subscribe` / `unsubscribe` / `send` / `close` are typed as
|
||||
`void | Promise<void>` so engines that need to coordinate with a
|
||||
broker can be async, while in-memory engines can stay synchronous.
|
||||
- `ack` is synchronous because it only updates the connection's
|
||||
`lastEventId` cursor; it never blocks on I/O.
|
||||
@@ -0,0 +1,60 @@
|
||||
import type { Principal } from "@suaveplan/api-types/principal";
|
||||
import type { TenantId } from "@suaveplan/api-types/tenant";
|
||||
import { describe, expectTypeOf, it } from "@suaveplan/testing/runner";
|
||||
import type { WsEnvelope } from "../envelope/envelope.js";
|
||||
import type {
|
||||
SubscribeOptions,
|
||||
SubscriptionFilter,
|
||||
WsConnection,
|
||||
WsConnectionState,
|
||||
} from "./connection.js";
|
||||
|
||||
describe("WsConnection conformance", () => {
|
||||
it("declares every documented field", { timeout: 5000 }, () => {
|
||||
expectTypeOf<WsConnection>()
|
||||
.toHaveProperty("id")
|
||||
.toEqualTypeOf<string>();
|
||||
expectTypeOf<WsConnection>()
|
||||
.toHaveProperty("principal")
|
||||
.toEqualTypeOf<Principal>();
|
||||
expectTypeOf<WsConnection>()
|
||||
.toHaveProperty("tenantId")
|
||||
.toEqualTypeOf<TenantId>();
|
||||
expectTypeOf<WsConnection>()
|
||||
.toHaveProperty("lastEventId")
|
||||
.toEqualTypeOf<string | null>();
|
||||
expectTypeOf<WsConnection>()
|
||||
.toHaveProperty("state")
|
||||
.toEqualTypeOf<WsConnectionState>();
|
||||
});
|
||||
|
||||
it("declares every documented method", { timeout: 5000 }, () => {
|
||||
expectTypeOf<WsConnection["subscribe"]>().parameters.toEqualTypeOf<
|
||||
[topic: string, opts?: SubscribeOptions | undefined]
|
||||
>();
|
||||
expectTypeOf<WsConnection["unsubscribe"]>().parameters.toEqualTypeOf<
|
||||
[topic: string]
|
||||
>();
|
||||
expectTypeOf<WsConnection["send"]>().parameters.toEqualTypeOf<
|
||||
[message: WsEnvelope]
|
||||
>();
|
||||
expectTypeOf<WsConnection["close"]>().parameters.toEqualTypeOf<
|
||||
[code: number, reason?: string | undefined]
|
||||
>();
|
||||
expectTypeOf<WsConnection["ack"]>().parameters.toEqualTypeOf<
|
||||
[id: string]
|
||||
>();
|
||||
});
|
||||
|
||||
it("state union has exactly three members", { timeout: 5000 }, () => {
|
||||
expectTypeOf<WsConnectionState>().toEqualTypeOf<
|
||||
"open" | "closing" | "closed"
|
||||
>();
|
||||
});
|
||||
|
||||
it("SubscriptionFilter is a predicate", { timeout: 5000 }, () => {
|
||||
expectTypeOf<SubscriptionFilter<{ x: number }>>().toEqualTypeOf<
|
||||
(payload: { x: number }) => boolean
|
||||
>();
|
||||
});
|
||||
});
|
||||
54
packages/api-stack/api/api-ws/src/connection/connection.ts
Normal file
54
packages/api-stack/api/api-ws/src/connection/connection.ts
Normal file
@@ -0,0 +1,54 @@
|
||||
import type { Principal } from "@suaveplan/api-types/principal";
|
||||
import type { TenantId } from "@suaveplan/api-types/tenant";
|
||||
import type { WsEnvelope } from "../envelope/envelope.js";
|
||||
|
||||
/**
|
||||
* Connection state — a strict 3-element FSM.
|
||||
* - `open` — accepting `subscribe`/`send`.
|
||||
* - `closing` — close has been initiated; queued sends are flushed but
|
||||
* no new subscriptions are accepted.
|
||||
* - `closed` — terminal; any method other than reading the id is a no-op.
|
||||
*/
|
||||
export type WsConnectionState = "open" | "closing" | "closed";
|
||||
|
||||
/**
|
||||
* Optional per-subscription filter — runs server-side before fan-out so
|
||||
* uninterested connections are skipped without the engine re-encoding the
|
||||
* payload per recipient.
|
||||
*/
|
||||
export type SubscriptionFilter<Payload = unknown> = (
|
||||
payload: Payload
|
||||
) => boolean;
|
||||
|
||||
/** Options accepted by {@link WsConnection.subscribe}. */
|
||||
export interface SubscribeOptions<Payload = unknown> {
|
||||
readonly tenant?: TenantId;
|
||||
readonly filter?: SubscriptionFilter<Payload>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Canonical abstract WebSocket connection. Concrete engines
|
||||
* (`api-ws-bun`, future browser shims) implement this interface; plugins
|
||||
* code against it.
|
||||
*
|
||||
* The handshake principal is frozen for the connection's lifetime — the
|
||||
* host emits `connection.principal_expired` if the underlying token
|
||||
* lapses but the contract does not let the principal mutate.
|
||||
*
|
||||
* `lastEventId` is `null` until the engine has issued at least one event
|
||||
* with an id; from that point it tracks the most-recently-acked id so
|
||||
* reconnects can resume cleanly.
|
||||
*/
|
||||
export interface WsConnection {
|
||||
readonly id: string;
|
||||
readonly principal: Principal;
|
||||
readonly tenantId: TenantId;
|
||||
readonly lastEventId: string | null;
|
||||
readonly state: WsConnectionState;
|
||||
|
||||
subscribe(topic: string, opts?: SubscribeOptions): void | Promise<void>;
|
||||
unsubscribe(topic: string): void | Promise<void>;
|
||||
send(message: WsEnvelope): void | Promise<void>;
|
||||
close(code: number, reason?: string): void | Promise<void>;
|
||||
ack(id: string): void;
|
||||
}
|
||||
6
packages/api-stack/api/api-ws/src/connection/index.ts
Normal file
6
packages/api-stack/api/api-ws/src/connection/index.ts
Normal file
@@ -0,0 +1,6 @@
|
||||
export type {
|
||||
SubscribeOptions,
|
||||
SubscriptionFilter,
|
||||
WsConnection,
|
||||
WsConnectionState,
|
||||
} from "./connection.js";
|
||||
78
packages/api-stack/api/api-ws/src/envelope/envelope.md
Normal file
78
packages/api-stack/api/api-ws/src/envelope/envelope.md
Normal file
@@ -0,0 +1,78 @@
|
||||
# `envelope` — wire-frame Zod schema
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Purpose
|
||||
|
||||
`@suaveplan/api-ws/envelope` owns the canonical Zod schema for every
|
||||
WebSocket frame that flows between the host and a plugin. Engines parse
|
||||
incoming frames against this schema before the message reaches plugin code,
|
||||
so unknown top-level keys never leak past the host boundary and every frame
|
||||
is guaranteed to carry the correlation id and discriminator the
|
||||
subscription bus, ack pipeline, and reconnect-resume path require.
|
||||
|
||||
The shape is deliberately minimal — `id`, `type`, optional `topic`,
|
||||
optional `payload`, optional `ts` — so plugins can compose their own Zod
|
||||
schemas on top of `payload` without fighting the wire format.
|
||||
|
||||
## Features
|
||||
|
||||
- Strict object schema — extra keys are a parse failure, not a silent drop.
|
||||
- `isWsEnvelope(value): value is WsEnvelope` predicate for ergonomic
|
||||
narrowing inside engine adapters.
|
||||
- `parseWsEnvelope(value)` throws the underlying `ZodError` for callers
|
||||
that want to convert to a `WsError` at the boundary.
|
||||
- Always uses the default-import form `import z from "zod"` per the
|
||||
project Zod policy.
|
||||
|
||||
## Usage: Basic
|
||||
|
||||
```ts
|
||||
import { isWsEnvelope, parseWsEnvelope } from "@suaveplan/api-ws/envelope";
|
||||
|
||||
const frame = parseWsEnvelope(JSON.parse(rawText));
|
||||
console.log(frame.id, frame.type);
|
||||
```
|
||||
|
||||
## Usage: Advanced
|
||||
|
||||
```ts
|
||||
import { isWsEnvelope, type WsEnvelope } from "@suaveplan/api-ws/envelope";
|
||||
import { WS_CODES, WsError } from "@suaveplan/api-ws/error-codes";
|
||||
import z from "zod";
|
||||
|
||||
const orderPayload = z.object({ orderId: z.string() });
|
||||
|
||||
function handle(raw: unknown): void {
|
||||
if (!isWsEnvelope(raw)) {
|
||||
throw new WsError(WS_CODES.HANDSHAKE_FAILED, "invalid envelope");
|
||||
}
|
||||
const envelope: WsEnvelope = raw;
|
||||
if (envelope.type === "orders.ack") {
|
||||
const payload = orderPayload.parse(envelope.payload);
|
||||
// narrow + branch...
|
||||
void payload;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
- `wsEnvelopeSchema: z.ZodSchema<WsEnvelope>` — strict object schema.
|
||||
- `type WsEnvelope = z.infer<typeof wsEnvelopeSchema>`.
|
||||
- `isWsEnvelope(value: unknown): value is WsEnvelope` — type predicate.
|
||||
- `parseWsEnvelope(value: unknown): WsEnvelope` — throwing parser.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- `strict()` mode is non-negotiable. Engines that need to allow custom
|
||||
extensions MUST do so by defining their own discriminated union of
|
||||
`wsEnvelopeSchema.extend({ ... })` shapes per `type`, not by relaxing the
|
||||
base schema.
|
||||
- `payload` is `z.unknown()` rather than `z.any()` so downstream code is
|
||||
forced to narrow before use.
|
||||
- The Zod default-import form (`import z from "zod"`) is the only
|
||||
Bun-safe form per the project policy and is enforced by a repo-wide
|
||||
grep test.
|
||||
62
packages/api-stack/api/api-ws/src/envelope/envelope.test.ts
Normal file
62
packages/api-stack/api/api-ws/src/envelope/envelope.test.ts
Normal file
@@ -0,0 +1,62 @@
|
||||
import { describe, expect, it } from "@suaveplan/testing/runner";
|
||||
import { isWsEnvelope, parseWsEnvelope, wsEnvelopeSchema } from "./envelope.js";
|
||||
|
||||
describe("envelope", () => {
|
||||
it("minimal envelope parses", { timeout: 5000 }, () => {
|
||||
const result = wsEnvelopeSchema.parse({ id: "x", type: "msg" });
|
||||
expect(result).toEqual({ id: "x", type: "msg" });
|
||||
});
|
||||
|
||||
it("full envelope parses", { timeout: 5000 }, () => {
|
||||
const result = parseWsEnvelope({
|
||||
id: "1",
|
||||
type: "orders.created",
|
||||
topic: "orders",
|
||||
payload: { orderId: "o" },
|
||||
ts: "2026-05-25T00:00:00Z",
|
||||
});
|
||||
expect(result.topic).toBe("orders");
|
||||
});
|
||||
|
||||
it("unknown keys rejected", { timeout: 5000 }, () => {
|
||||
const result = wsEnvelopeSchema.safeParse({
|
||||
id: "x",
|
||||
type: "msg",
|
||||
extra: 1,
|
||||
});
|
||||
expect(result.success).toBe(false);
|
||||
if (!result.success) {
|
||||
const issueText = JSON.stringify(result.error.issues);
|
||||
expect(issueText).toContain("extra");
|
||||
}
|
||||
});
|
||||
|
||||
it("missing id rejected", { timeout: 5000 }, () => {
|
||||
expect(wsEnvelopeSchema.safeParse({ type: "x" }).success).toBe(false);
|
||||
});
|
||||
|
||||
it("missing type rejected", { timeout: 5000 }, () => {
|
||||
expect(wsEnvelopeSchema.safeParse({ id: "x" }).success).toBe(false);
|
||||
});
|
||||
|
||||
it("empty id rejected", { timeout: 5000 }, () => {
|
||||
expect(wsEnvelopeSchema.safeParse({ id: "", type: "x" }).success).toBe(
|
||||
false
|
||||
);
|
||||
});
|
||||
|
||||
it("isWsEnvelope narrows valid input", { timeout: 5000 }, () => {
|
||||
const value: unknown = { id: "x", type: "msg" };
|
||||
expect(isWsEnvelope(value)).toBe(true);
|
||||
});
|
||||
|
||||
it("isWsEnvelope rejects invalid input", { timeout: 5000 }, () => {
|
||||
expect(isWsEnvelope(null)).toBe(false);
|
||||
expect(isWsEnvelope({})).toBe(false);
|
||||
expect(isWsEnvelope({ id: "x", type: "msg", junk: true })).toBe(false);
|
||||
});
|
||||
|
||||
it("parseWsEnvelope throws on invalid", { timeout: 5000 }, () => {
|
||||
expect(() => parseWsEnvelope({})).toThrow();
|
||||
});
|
||||
});
|
||||
41
packages/api-stack/api/api-ws/src/envelope/envelope.ts
Normal file
41
packages/api-stack/api/api-ws/src/envelope/envelope.ts
Normal file
@@ -0,0 +1,41 @@
|
||||
import z from "zod";
|
||||
|
||||
/**
|
||||
* Wire envelope for every WebSocket frame that flows between the host and a
|
||||
* plugin. Unknown top-level keys are rejected so clients cannot smuggle
|
||||
* fields past the host's validation gate.
|
||||
*
|
||||
* The shape is intentionally minimal:
|
||||
* - `id` correlates request/response/ack frames.
|
||||
* - `type` is the message discriminator (plugin-defined namespace).
|
||||
* - `topic` names the subscription (optional for non-subscription frames).
|
||||
* - `payload` is the opaque body — plugins narrow with their own Zod schema.
|
||||
* - `ts` is an optional ISO-8601 producer timestamp.
|
||||
*/
|
||||
export const wsEnvelopeSchema = z
|
||||
.object({
|
||||
id: z.string().min(1),
|
||||
type: z.string().min(1),
|
||||
topic: z.string().min(1).optional(),
|
||||
payload: z.unknown().optional(),
|
||||
ts: z.string().min(1).optional(),
|
||||
})
|
||||
.strict();
|
||||
|
||||
export type WsEnvelope = z.infer<typeof wsEnvelopeSchema>;
|
||||
|
||||
/**
|
||||
* Type-narrowing helper: returns `true` (and narrows `value` to
|
||||
* `WsEnvelope`) when the candidate parses successfully.
|
||||
*/
|
||||
export function isWsEnvelope(value: unknown): value is WsEnvelope {
|
||||
return wsEnvelopeSchema.safeParse(value).success;
|
||||
}
|
||||
|
||||
/**
|
||||
* Strict parser that throws the underlying `ZodError` on failure. Callers
|
||||
* that prefer a typed thrown error should wrap with `WsError`.
|
||||
*/
|
||||
export function parseWsEnvelope(value: unknown): WsEnvelope {
|
||||
return wsEnvelopeSchema.parse(value);
|
||||
}
|
||||
2
packages/api-stack/api/api-ws/src/envelope/index.ts
Normal file
2
packages/api-stack/api/api-ws/src/envelope/index.ts
Normal file
@@ -0,0 +1,2 @@
|
||||
export type { WsEnvelope } from "./envelope.js";
|
||||
export { isWsEnvelope, parseWsEnvelope, wsEnvelopeSchema } from "./envelope.js";
|
||||
69
packages/api-stack/api/api-ws/src/error-codes/error-codes.md
Normal file
69
packages/api-stack/api/api-ws/src/error-codes/error-codes.md
Normal file
@@ -0,0 +1,69 @@
|
||||
# `error-codes` — WS namespace registry
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Purpose
|
||||
|
||||
`@suaveplan/api-ws` owns the abstract WebSocket contract. Every public failure
|
||||
path raises a `WsError` carrying a stable, namespaced `WS.*` code so consumers
|
||||
can branch on the value without parsing messages. This module declares the
|
||||
eight Stage-1 codes through `defineCodes("WS", [...])` and exposes the
|
||||
matching `WsError` subclass.
|
||||
|
||||
The registry is frozen by `defineCodes` so consumers can rely on the literal
|
||||
string identity of every code at compile time and at run time.
|
||||
|
||||
## Features
|
||||
|
||||
- `WS_CODES` frozen registry with one literal per documented failure mode.
|
||||
- `WsErrorCode` union derived from the registry.
|
||||
- `WsError` class extending `SuaveplanError<WsErrorCode>` with a public
|
||||
constructor and a `wsCode` field that narrows correctly inside
|
||||
`instanceof` branches.
|
||||
|
||||
## Usage: Basic
|
||||
|
||||
```ts
|
||||
import { WS_CODES, WsError } from "@suaveplan/api-ws/error-codes";
|
||||
|
||||
throw new WsError(WS_CODES.HEARTBEAT_FAILED, "two missed pongs");
|
||||
```
|
||||
|
||||
## Usage: Advanced
|
||||
|
||||
```ts
|
||||
import { WS_CODES, WsError, type WsErrorCode } from "@suaveplan/api-ws/error-codes";
|
||||
|
||||
function describe(error: unknown): string {
|
||||
if (error instanceof WsError) {
|
||||
const code: WsErrorCode = error.wsCode;
|
||||
switch (code) {
|
||||
case WS_CODES.BACKPRESSURE_EVICTED:
|
||||
return "send queue overflow";
|
||||
case WS_CODES.CROSS_TENANT_BROADCAST_DENIED:
|
||||
return "missing ws.broadcast-cross-tenant";
|
||||
default:
|
||||
return code;
|
||||
}
|
||||
}
|
||||
return "unknown";
|
||||
}
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
- `WS_CODES: { readonly HANDSHAKE_FAILED: "WS.HANDSHAKE_FAILED", ... }` — frozen record.
|
||||
- `type WsErrorCode = (typeof WS_CODES)[keyof typeof WS_CODES]`.
|
||||
- `class WsError extends SuaveplanError<WsErrorCode>` with
|
||||
`constructor(code, message, options?)` and a `wsCode: WsErrorCode` field.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- The eight codes mirror the rows of design-doc §11.4 / §11.5 plus the cross-
|
||||
tenant gate of §11.2 and the broker-unavailability path of §11.3. Adding a
|
||||
new code requires an OpenSpec delta — the registry is intentionally closed.
|
||||
- `WsError` widens the base constructor from `protected` to `public` so
|
||||
callers may construct instances directly. The base class still provides the
|
||||
redaction, OTel adapter, and cause-chain traversal.
|
||||
@@ -0,0 +1,44 @@
|
||||
import { promises as fs } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import { describe, expect, it } from "@suaveplan/testing/runner";
|
||||
import { WS_CODES } from "./error-codes.js";
|
||||
|
||||
describe("WS_CODES production coverage", () => {
|
||||
it("every WS_CODES entry is referenced from a production module", {
|
||||
timeout: 5000,
|
||||
}, async () => {
|
||||
const srcRoot = join(__dirname, "..");
|
||||
const files = await listProductionFiles(srcRoot);
|
||||
const corpus = (
|
||||
await Promise.all(files.map((f) => fs.readFile(f, "utf8")))
|
||||
).join("\n");
|
||||
for (const key of Object.keys(WS_CODES) as Array<
|
||||
keyof typeof WS_CODES
|
||||
>) {
|
||||
expect(
|
||||
corpus.includes(`WS_CODES.${key}`),
|
||||
`WS_CODES.${key} has no production throw site`
|
||||
).toBe(true);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
async function listProductionFiles(dir: string): Promise<string[]> {
|
||||
const entries = await fs.readdir(dir, { withFileTypes: true });
|
||||
const out: string[] = [];
|
||||
for (const entry of entries) {
|
||||
const full = join(dir, entry.name);
|
||||
if (entry.isDirectory()) {
|
||||
out.push(...(await listProductionFiles(full)));
|
||||
} else if (entry.isFile() && entry.name.endsWith(".ts")) {
|
||||
if (
|
||||
entry.name.endsWith(".test.ts") ||
|
||||
entry.name.endsWith(".bench.ts")
|
||||
) {
|
||||
continue;
|
||||
}
|
||||
out.push(full);
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
@@ -0,0 +1,128 @@
|
||||
import { describe, expect, it } from "@suaveplan/testing/runner";
|
||||
import {
|
||||
raiseBrokerUnavailable,
|
||||
raiseConnectionCapExceeded,
|
||||
raiseHandshakeFailed,
|
||||
raisePrincipalExpired,
|
||||
WS_CODES,
|
||||
WsError,
|
||||
} from "./error-codes.js";
|
||||
|
||||
describe("WS_CODES", () => {
|
||||
it("exposes exactly the eight documented codes", { timeout: 5000 }, () => {
|
||||
const keys = Object.keys(WS_CODES).sort();
|
||||
expect(keys).toEqual(
|
||||
[
|
||||
"BACKPRESSURE_EVICTED",
|
||||
"BROKER_UNAVAILABLE",
|
||||
"CONNECTION_CAP_EXCEEDED",
|
||||
"CROSS_TENANT_BROADCAST_DENIED",
|
||||
"HANDSHAKE_FAILED",
|
||||
"HEARTBEAT_FAILED",
|
||||
"PRINCIPAL_EXPIRED",
|
||||
"RECONNECT_TOKEN_INVALID",
|
||||
].sort()
|
||||
);
|
||||
});
|
||||
|
||||
it("namespaces every code with the WS. prefix", { timeout: 5000 }, () => {
|
||||
for (const value of Object.values(WS_CODES)) {
|
||||
expect(value.startsWith("WS.")).toBe(true);
|
||||
}
|
||||
});
|
||||
|
||||
it("registry is frozen", { timeout: 5000 }, () => {
|
||||
expect(Object.isFrozen(WS_CODES)).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("WsError", () => {
|
||||
it("constructor records the code on wsCode and code", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const error = new WsError(WS_CODES.HEARTBEAT_FAILED, "boom");
|
||||
expect(error.wsCode).toBe(WS_CODES.HEARTBEAT_FAILED);
|
||||
expect(error.code).toBe(WS_CODES.HEARTBEAT_FAILED);
|
||||
expect(error.message).toBe("boom");
|
||||
});
|
||||
|
||||
it("passes options through to SuaveplanError", { timeout: 5000 }, () => {
|
||||
const cause = new Error("root");
|
||||
const error = new WsError(WS_CODES.BROKER_UNAVAILABLE, "broker down", {
|
||||
cause,
|
||||
});
|
||||
expect(error.cause).toBe(cause);
|
||||
});
|
||||
|
||||
it("instanceof narrows wsCode", { timeout: 5000 }, () => {
|
||||
const error: unknown = new WsError(
|
||||
WS_CODES.CROSS_TENANT_BROADCAST_DENIED,
|
||||
"denied"
|
||||
);
|
||||
if (error instanceof WsError) {
|
||||
expect(error.wsCode).toBe("WS.CROSS_TENANT_BROADCAST_DENIED");
|
||||
} else {
|
||||
throw new Error("expected WsError");
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe("engine throw helpers", () => {
|
||||
it("raiseHandshakeFailed throws WS.HANDSHAKE_FAILED", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
try {
|
||||
raiseHandshakeFailed("origin denied");
|
||||
throw new Error("expected throw");
|
||||
} catch (caught) {
|
||||
expect(caught).toBeInstanceOf(WsError);
|
||||
if (caught instanceof WsError) {
|
||||
expect(caught.wsCode).toBe(WS_CODES.HANDSHAKE_FAILED);
|
||||
expect(caught.message).toContain("origin denied");
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
it("raisePrincipalExpired throws WS.PRINCIPAL_EXPIRED", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
try {
|
||||
raisePrincipalExpired("c-1");
|
||||
throw new Error("expected throw");
|
||||
} catch (caught) {
|
||||
expect(caught).toBeInstanceOf(WsError);
|
||||
if (caught instanceof WsError) {
|
||||
expect(caught.wsCode).toBe(WS_CODES.PRINCIPAL_EXPIRED);
|
||||
expect(caught.message).toContain("c-1");
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
it("raiseConnectionCapExceeded throws WS.CONNECTION_CAP_EXCEEDED", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
try {
|
||||
raiseConnectionCapExceeded("t1", 5);
|
||||
throw new Error("expected throw");
|
||||
} catch (caught) {
|
||||
expect(caught).toBeInstanceOf(WsError);
|
||||
if (caught instanceof WsError) {
|
||||
expect(caught.wsCode).toBe(WS_CODES.CONNECTION_CAP_EXCEEDED);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
it("raiseBrokerUnavailable throws WS.BROKER_UNAVAILABLE", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
try {
|
||||
raiseBrokerUnavailable("redis down");
|
||||
throw new Error("expected throw");
|
||||
} catch (caught) {
|
||||
expect(caught).toBeInstanceOf(WsError);
|
||||
if (caught instanceof WsError) {
|
||||
expect(caught.wsCode).toBe(WS_CODES.BROKER_UNAVAILABLE);
|
||||
}
|
||||
}
|
||||
});
|
||||
});
|
||||
86
packages/api-stack/api/api-ws/src/error-codes/error-codes.ts
Normal file
86
packages/api-stack/api/api-ws/src/error-codes/error-codes.ts
Normal file
@@ -0,0 +1,86 @@
|
||||
import type { SuaveplanErrorOptions } from "@suaveplan/error";
|
||||
import { defineCodes, SuaveplanError } from "@suaveplan/error";
|
||||
|
||||
/**
|
||||
* Stable error-code registry for `@suaveplan/api-ws`.
|
||||
*
|
||||
* Every public failure path raises a {@link WsError} carrying one of these
|
||||
* namespaced `WS.*` codes. Consumers branch on the string value via
|
||||
* `error.code === WS_CODES.HEARTBEAT_FAILED` or the inline literal
|
||||
* `"WS.HEARTBEAT_FAILED"`.
|
||||
*
|
||||
* The 8 codes cover the documented Stage-1 contract failure modes:
|
||||
* - `HANDSHAKE_FAILED` — upgrade pipeline rejected the connection.
|
||||
* - `PRINCIPAL_EXPIRED` — token expiry mid-connection.
|
||||
* - `BACKPRESSURE_EVICTED` — send queue exceeded `maxQueuedMessages`.
|
||||
* - `HEARTBEAT_FAILED` — two missed pongs.
|
||||
* - `CONNECTION_CAP_EXCEEDED` — per-tenant cap exceeded at handshake.
|
||||
* - `CROSS_TENANT_BROADCAST_DENIED` — broadcast across tenants without
|
||||
* the `ws.broadcast-cross-tenant` capability.
|
||||
* - `RECONNECT_TOKEN_INVALID` — bad MAC or expired token.
|
||||
* - `BROKER_UNAVAILABLE` — broker publish/subscribe failed.
|
||||
*/
|
||||
export const WS_CODES = defineCodes("WS", [
|
||||
"HANDSHAKE_FAILED",
|
||||
"PRINCIPAL_EXPIRED",
|
||||
"BACKPRESSURE_EVICTED",
|
||||
"HEARTBEAT_FAILED",
|
||||
"CONNECTION_CAP_EXCEEDED",
|
||||
"CROSS_TENANT_BROADCAST_DENIED",
|
||||
"RECONNECT_TOKEN_INVALID",
|
||||
"BROKER_UNAVAILABLE",
|
||||
] as const);
|
||||
|
||||
export type WsErrorCode = (typeof WS_CODES)[keyof typeof WS_CODES];
|
||||
|
||||
/**
|
||||
* Concrete error class for the api-ws package. Extends
|
||||
* {@link SuaveplanError} so `instanceof WsError` narrows `code` to
|
||||
* {@link WsErrorCode}.
|
||||
*/
|
||||
export class WsError extends SuaveplanError<WsErrorCode> {
|
||||
public readonly wsCode: WsErrorCode;
|
||||
|
||||
public constructor(
|
||||
code: WsErrorCode,
|
||||
message: string,
|
||||
options?: SuaveplanErrorOptions
|
||||
) {
|
||||
super(code, message, options);
|
||||
this.wsCode = code;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Helpers that engines (`api-ws-bun`, future browser shims) call when the
|
||||
* matching contract is violated. Centralising the throw sites keeps the
|
||||
* code-to-message mapping consistent across every engine and guarantees a
|
||||
* production reference for every `WS_CODES` entry in this contract package.
|
||||
*/
|
||||
export function raiseHandshakeFailed(reason: string): never {
|
||||
throw new WsError(
|
||||
WS_CODES.HANDSHAKE_FAILED,
|
||||
`handshake rejected: ${reason}`
|
||||
);
|
||||
}
|
||||
|
||||
export function raisePrincipalExpired(connectionId: string): never {
|
||||
throw new WsError(
|
||||
WS_CODES.PRINCIPAL_EXPIRED,
|
||||
`connection ${connectionId} principal expired mid-session`
|
||||
);
|
||||
}
|
||||
|
||||
export function raiseConnectionCapExceeded(tenant: string, cap: number): never {
|
||||
throw new WsError(
|
||||
WS_CODES.CONNECTION_CAP_EXCEEDED,
|
||||
`tenant ${tenant} exceeded per-tenant cap of ${cap}`
|
||||
);
|
||||
}
|
||||
|
||||
export function raiseBrokerUnavailable(reason: string): never {
|
||||
throw new WsError(
|
||||
WS_CODES.BROKER_UNAVAILABLE,
|
||||
`broker unavailable: ${reason}`
|
||||
);
|
||||
}
|
||||
9
packages/api-stack/api/api-ws/src/error-codes/index.ts
Normal file
9
packages/api-stack/api/api-ws/src/error-codes/index.ts
Normal file
@@ -0,0 +1,9 @@
|
||||
export type { WsErrorCode } from "./error-codes.js";
|
||||
export {
|
||||
raiseBrokerUnavailable,
|
||||
raiseConnectionCapExceeded,
|
||||
raiseHandshakeFailed,
|
||||
raisePrincipalExpired,
|
||||
WS_CODES,
|
||||
WsError,
|
||||
} from "./error-codes.js";
|
||||
85
packages/api-stack/api/api-ws/src/heartbeat/heartbeat.md
Normal file
85
packages/api-stack/api/api-ws/src/heartbeat/heartbeat.md
Normal file
@@ -0,0 +1,85 @@
|
||||
# `heartbeat` — ping/pong policy + evaluator
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Purpose
|
||||
|
||||
Every WebSocket connection that the Suaveplan API host accepts is policed
|
||||
by a heartbeat: the engine pings at a fixed cadence and forcibly closes the
|
||||
connection once a documented number of consecutive pongs are missed. This
|
||||
module owns the abstract policy and the stateless evaluator that concrete
|
||||
engines call from their heartbeat tick. The defaults — 30000ms cadence,
|
||||
two missed pongs to abort — track design doc §11.4.
|
||||
|
||||
The evaluator is intentionally stateless: it consumes scalar measurements
|
||||
the engine already tracks and returns the next action. State lives with
|
||||
the engine; the contract lives here.
|
||||
|
||||
## Features
|
||||
|
||||
- `HeartbeatPolicy` interface (`heartbeatMs`, `maxMissedPongs`).
|
||||
- `DEFAULT_HEARTBEAT_POLICY` — frozen design-doc defaults.
|
||||
- `evaluateHeartbeat(msSinceLastPong, consecutiveMissedPongs, policy?)` →
|
||||
`"ok" | "ping" | "abort"`.
|
||||
- `raiseHeartbeatFailed(connectionId)` throws the canonical `WsError`.
|
||||
|
||||
## Usage: Basic
|
||||
|
||||
```ts
|
||||
import { evaluateHeartbeat } from "@suaveplan/api-ws/heartbeat";
|
||||
|
||||
const action = evaluateHeartbeat(msSinceLastPong, missedPongs);
|
||||
if (action === "ping") sendPing();
|
||||
if (action === "abort") closeAbnormal();
|
||||
```
|
||||
|
||||
## Usage: Advanced
|
||||
|
||||
```ts
|
||||
import {
|
||||
evaluateHeartbeat,
|
||||
raiseHeartbeatFailed,
|
||||
type HeartbeatPolicy,
|
||||
} from "@suaveplan/api-ws/heartbeat";
|
||||
|
||||
class HeartbeatTicker {
|
||||
private missed = 0;
|
||||
private lastPong = Date.now();
|
||||
|
||||
constructor(private readonly policy: HeartbeatPolicy) {}
|
||||
|
||||
tick(now: number, connectionId: string): void {
|
||||
const action = evaluateHeartbeat(now - this.lastPong, this.missed, this.policy);
|
||||
if (action === "ping") {
|
||||
this.missed += 1;
|
||||
} else if (action === "abort") {
|
||||
raiseHeartbeatFailed(connectionId);
|
||||
}
|
||||
}
|
||||
|
||||
onPong(now: number): void {
|
||||
this.missed = 0;
|
||||
this.lastPong = now;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
- `interface HeartbeatPolicy { heartbeatMs: number; maxMissedPongs: number }`.
|
||||
- `const DEFAULT_HEARTBEAT_POLICY: HeartbeatPolicy` (frozen).
|
||||
- `type HeartbeatAction = "ok" | "ping" | "abort"`.
|
||||
- `evaluateHeartbeat(msSinceLastPong, consecutiveMissedPongs, policy?): HeartbeatAction`.
|
||||
- `raiseHeartbeatFailed(connectionId): never`.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- The evaluator checks `consecutiveMissedPongs` before `msSinceLastPong`
|
||||
so an already-failed connection aborts immediately on the next tick
|
||||
even if the engine's clock briefly stalls.
|
||||
- `consecutiveMissedPongs` is the engine's counter — every ping increments
|
||||
it; every pong resets it. The evaluator does not own that state.
|
||||
- `raiseHeartbeatFailed` is `never` so callers can use it as a terminal
|
||||
branch without an explicit unreachable assertion.
|
||||
@@ -0,0 +1,57 @@
|
||||
import { describe, expect, it } from "@suaveplan/testing/runner";
|
||||
import { WS_CODES, WsError } from "../error-codes/error-codes.js";
|
||||
import {
|
||||
DEFAULT_HEARTBEAT_POLICY,
|
||||
evaluateHeartbeat,
|
||||
raiseHeartbeatFailed,
|
||||
} from "./heartbeat.js";
|
||||
|
||||
describe("DEFAULT_HEARTBEAT_POLICY", () => {
|
||||
it("matches design doc defaults", { timeout: 5000 }, () => {
|
||||
expect(DEFAULT_HEARTBEAT_POLICY.heartbeatMs).toBe(30000);
|
||||
expect(DEFAULT_HEARTBEAT_POLICY.maxMissedPongs).toBe(2);
|
||||
});
|
||||
|
||||
it("policy is frozen", { timeout: 5000 }, () => {
|
||||
expect(Object.isFrozen(DEFAULT_HEARTBEAT_POLICY)).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("evaluateHeartbeat", () => {
|
||||
it("returns ok inside the heartbeat window", { timeout: 5000 }, () => {
|
||||
expect(evaluateHeartbeat(0, 0)).toBe("ok");
|
||||
expect(evaluateHeartbeat(29_999, 0)).toBe("ok");
|
||||
});
|
||||
|
||||
it("returns ping at the heartbeat boundary", { timeout: 5000 }, () => {
|
||||
expect(evaluateHeartbeat(30_000, 0)).toBe("ping");
|
||||
expect(evaluateHeartbeat(60_000, 1)).toBe("ping");
|
||||
});
|
||||
|
||||
it("returns abort after two missed pongs", { timeout: 5000 }, () => {
|
||||
expect(evaluateHeartbeat(0, 2)).toBe("abort");
|
||||
expect(evaluateHeartbeat(90_000, 2)).toBe("abort");
|
||||
});
|
||||
|
||||
it("honours a custom policy", { timeout: 5000 }, () => {
|
||||
const policy = { heartbeatMs: 5000, maxMissedPongs: 1 };
|
||||
expect(evaluateHeartbeat(4999, 0, policy)).toBe("ok");
|
||||
expect(evaluateHeartbeat(5000, 0, policy)).toBe("ping");
|
||||
expect(evaluateHeartbeat(0, 1, policy)).toBe("abort");
|
||||
});
|
||||
});
|
||||
|
||||
describe("raiseHeartbeatFailed", () => {
|
||||
it("throws WS.HEARTBEAT_FAILED", { timeout: 5000 }, () => {
|
||||
try {
|
||||
raiseHeartbeatFailed("c-1");
|
||||
throw new Error("expected throw");
|
||||
} catch (caught) {
|
||||
expect(caught).toBeInstanceOf(WsError);
|
||||
if (caught instanceof WsError) {
|
||||
expect(caught.wsCode).toBe(WS_CODES.HEARTBEAT_FAILED);
|
||||
expect(caught.message).toContain("c-1");
|
||||
}
|
||||
}
|
||||
});
|
||||
});
|
||||
53
packages/api-stack/api/api-ws/src/heartbeat/heartbeat.ts
Normal file
53
packages/api-stack/api/api-ws/src/heartbeat/heartbeat.ts
Normal file
@@ -0,0 +1,53 @@
|
||||
import { WS_CODES, WsError } from "../error-codes/error-codes.js";
|
||||
|
||||
/**
|
||||
* Policy describing the engine's ping/pong cadence and failure threshold.
|
||||
*
|
||||
* Defaults match design doc §11.4: ping every 30000ms, declare the
|
||||
* connection dead after two consecutive missed pongs.
|
||||
*/
|
||||
export interface HeartbeatPolicy {
|
||||
readonly heartbeatMs: number;
|
||||
readonly maxMissedPongs: number;
|
||||
}
|
||||
|
||||
/** Default policy applied when no override is supplied. */
|
||||
export const DEFAULT_HEARTBEAT_POLICY: HeartbeatPolicy = Object.freeze({
|
||||
heartbeatMs: 30000,
|
||||
maxMissedPongs: 2,
|
||||
});
|
||||
|
||||
/** Action returned by {@link evaluateHeartbeat}. */
|
||||
export type HeartbeatAction = "ok" | "ping" | "abort";
|
||||
|
||||
/**
|
||||
* Stateless evaluator: given the engine's current view of "ms since last
|
||||
* pong" + "consecutive missed pongs", returns the action the engine must
|
||||
* take next.
|
||||
*
|
||||
* - `ok` — within tolerance, nothing to do.
|
||||
* - `ping` — heartbeat interval elapsed; engine should send a ping.
|
||||
* - `abort` — `maxMissedPongs` reached; engine MUST close the connection
|
||||
* with `ABNORMAL` and emit `WS.HEARTBEAT_FAILED`.
|
||||
*/
|
||||
export function evaluateHeartbeat(
|
||||
msSinceLastPong: number,
|
||||
consecutiveMissedPongs: number,
|
||||
policy: HeartbeatPolicy = DEFAULT_HEARTBEAT_POLICY
|
||||
): HeartbeatAction {
|
||||
if (consecutiveMissedPongs >= policy.maxMissedPongs) {
|
||||
return "abort";
|
||||
}
|
||||
if (msSinceLastPong >= policy.heartbeatMs) {
|
||||
return "ping";
|
||||
}
|
||||
return "ok";
|
||||
}
|
||||
|
||||
/** Helper that throws the canonical `WsError`. */
|
||||
export function raiseHeartbeatFailed(connectionId: string): never {
|
||||
throw new WsError(
|
||||
WS_CODES.HEARTBEAT_FAILED,
|
||||
`connection ${connectionId} failed heartbeat: two missed pongs`
|
||||
);
|
||||
}
|
||||
6
packages/api-stack/api/api-ws/src/heartbeat/index.ts
Normal file
6
packages/api-stack/api/api-ws/src/heartbeat/index.ts
Normal file
@@ -0,0 +1,6 @@
|
||||
export type { HeartbeatAction, HeartbeatPolicy } from "./heartbeat.js";
|
||||
export {
|
||||
DEFAULT_HEARTBEAT_POLICY,
|
||||
evaluateHeartbeat,
|
||||
raiseHeartbeatFailed,
|
||||
} from "./heartbeat.js";
|
||||
81
packages/api-stack/api/api-ws/src/index.ts
Normal file
81
packages/api-stack/api/api-ws/src/index.ts
Normal file
@@ -0,0 +1,81 @@
|
||||
export type {
|
||||
BackpressureAction,
|
||||
BackpressurePolicy,
|
||||
} from "./backpressure/backpressure.js";
|
||||
export {
|
||||
DEFAULT_BACKPRESSURE_POLICY,
|
||||
evaluateBackpressure,
|
||||
raiseBackpressureEvicted,
|
||||
} from "./backpressure/backpressure.js";
|
||||
|
||||
export type {
|
||||
BrokerEnvelope,
|
||||
BrokerHandler,
|
||||
BrokerSubscription,
|
||||
WsBroker,
|
||||
} from "./broker/broker.js";
|
||||
|
||||
export type {
|
||||
CapabilityId,
|
||||
WsBroadcastCrossTenantCapabilityId,
|
||||
WsCapabilityId,
|
||||
} from "./capability-id/capability-id.js";
|
||||
export { WS_CAPABILITY_IDS } from "./capability-id/capability-id.js";
|
||||
|
||||
export type {
|
||||
SubscribeOptions,
|
||||
SubscriptionFilter,
|
||||
WsConnection,
|
||||
WsConnectionState,
|
||||
} from "./connection/connection.js";
|
||||
|
||||
export type { ConnectionRegistry } from "./connection-registry/connection-registry.js";
|
||||
export { InMemoryConnectionRegistry } from "./connection-registry/connection-registry.js";
|
||||
|
||||
export type { WsEnvelope } from "./envelope/envelope.js";
|
||||
export {
|
||||
isWsEnvelope,
|
||||
parseWsEnvelope,
|
||||
wsEnvelopeSchema,
|
||||
} from "./envelope/envelope.js";
|
||||
|
||||
export type { WsErrorCode } from "./error-codes/error-codes.js";
|
||||
export {
|
||||
raiseBrokerUnavailable,
|
||||
raiseConnectionCapExceeded,
|
||||
raiseHandshakeFailed,
|
||||
raisePrincipalExpired,
|
||||
WS_CODES,
|
||||
WsError,
|
||||
} from "./error-codes/error-codes.js";
|
||||
|
||||
export type {
|
||||
HeartbeatAction,
|
||||
HeartbeatPolicy,
|
||||
} from "./heartbeat/heartbeat.js";
|
||||
export {
|
||||
DEFAULT_HEARTBEAT_POLICY,
|
||||
evaluateHeartbeat,
|
||||
raiseHeartbeatFailed,
|
||||
} from "./heartbeat/heartbeat.js";
|
||||
|
||||
export type {
|
||||
ReconnectTokenPayload,
|
||||
ReconnectTokenSignOptions,
|
||||
ReconnectTokenString,
|
||||
ReconnectTokenVerifyOptions,
|
||||
} from "./reconnect-token/reconnect-token.js";
|
||||
export {
|
||||
RECONNECT_TOKEN_TTL_MS,
|
||||
reconnectTokenPayloadSchema,
|
||||
signReconnectToken,
|
||||
verifyReconnectToken,
|
||||
} from "./reconnect-token/reconnect-token.js";
|
||||
|
||||
export type {
|
||||
BusBroadcastOptions,
|
||||
BusCaller,
|
||||
BusSubscribeOptions,
|
||||
SubscriptionBus,
|
||||
} from "./subscription-bus/subscription-bus.js";
|
||||
export { InMemorySubscriptionBus } from "./subscription-bus/subscription-bus.js";
|
||||
12
packages/api-stack/api/api-ws/src/reconnect-token/index.ts
Normal file
12
packages/api-stack/api/api-ws/src/reconnect-token/index.ts
Normal file
@@ -0,0 +1,12 @@
|
||||
export type {
|
||||
ReconnectTokenPayload,
|
||||
ReconnectTokenSignOptions,
|
||||
ReconnectTokenString,
|
||||
ReconnectTokenVerifyOptions,
|
||||
} from "./reconnect-token.js";
|
||||
export {
|
||||
RECONNECT_TOKEN_TTL_MS,
|
||||
reconnectTokenPayloadSchema,
|
||||
signReconnectToken,
|
||||
verifyReconnectToken,
|
||||
} from "./reconnect-token.js";
|
||||
@@ -0,0 +1,86 @@
|
||||
# `reconnect-token` — HMAC envelope for resumable WebSocket sessions
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Purpose
|
||||
|
||||
When the host closes a WebSocket connection cleanly (heartbeat failure,
|
||||
deploy, transient network issue), it issues a reconnect token the client can
|
||||
present on a follow-up upgrade request. The host validates the HMAC and
|
||||
re-attaches the previous subscription set with no plugin code change. This
|
||||
module owns the abstract payload shape and a Web-Crypto-based sign/verify
|
||||
pair. State is carried inside the token; the host stores nothing.
|
||||
|
||||
The TTL default is 5 minutes, matching design doc §11.5. Anything older is
|
||||
rejected with `WS.RECONNECT_TOKEN_INVALID` so a stolen token has a hard
|
||||
upper bound on its usefulness.
|
||||
|
||||
## Features
|
||||
|
||||
- Strict Zod schema for the payload — `tenant`, `principalId`,
|
||||
`lastEventId` (nullable), `exp`.
|
||||
- `signReconnectToken(input, { secret, clock?, ttlMs? })`.
|
||||
- `verifyReconnectToken(token, { secret, clock? })` — throws on bad
|
||||
encoding, bad MAC, bad shape, or expired payload.
|
||||
- Uses Web Crypto (`globalThis.crypto.subtle`) — runs unchanged in Bun,
|
||||
Node 20+, browser, and worker tiers.
|
||||
- Constant-time MAC comparison.
|
||||
|
||||
## Usage: Basic
|
||||
|
||||
```ts
|
||||
import {
|
||||
signReconnectToken,
|
||||
verifyReconnectToken,
|
||||
} from "@suaveplan/api-ws/reconnect-token";
|
||||
|
||||
const secret = crypto.getRandomValues(new Uint8Array(32));
|
||||
const token = await signReconnectToken(
|
||||
{ tenant: "t1", principalId: "p1", lastEventId: "e-9" },
|
||||
{ secret }
|
||||
);
|
||||
const payload = await verifyReconnectToken(token, { secret });
|
||||
```
|
||||
|
||||
## Usage: Advanced
|
||||
|
||||
```ts
|
||||
import {
|
||||
RECONNECT_TOKEN_TTL_MS,
|
||||
signReconnectToken,
|
||||
verifyReconnectToken,
|
||||
} from "@suaveplan/api-ws/reconnect-token";
|
||||
|
||||
const clock = (): number => mockNow;
|
||||
let mockNow = 1_000_000;
|
||||
|
||||
const token = await signReconnectToken(
|
||||
{ tenant: "t1", principalId: "p1", lastEventId: null },
|
||||
{ secret, clock, ttlMs: RECONNECT_TOKEN_TTL_MS }
|
||||
);
|
||||
mockNow += RECONNECT_TOKEN_TTL_MS;
|
||||
await verifyReconnectToken(token, { secret, clock }); // throws WS.RECONNECT_TOKEN_INVALID
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
- `const RECONNECT_TOKEN_TTL_MS = 300_000`.
|
||||
- `interface ReconnectTokenPayload { tenant, principalId, lastEventId, exp }`.
|
||||
- `reconnectTokenPayloadSchema: z.ZodSchema<ReconnectTokenPayload>`.
|
||||
- `signReconnectToken(input, options): Promise<string>`.
|
||||
- `verifyReconnectToken(token, options): Promise<ReconnectTokenPayload>` —
|
||||
throws `WsError(WS.RECONNECT_TOKEN_INVALID)` on every failure mode.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- HMAC-SHA-256 over the canonical JSON of the payload (the exact bytes
|
||||
signed are the bytes verified — no re-serialisation).
|
||||
- `base64url` encoding (no padding, `-`/`_` instead of `+`/`/`) keeps the
|
||||
token URL-safe for the `?reconnectToken=…` query parameter.
|
||||
- The verifier uses constant-time comparison so a malicious client cannot
|
||||
recover the MAC byte-by-byte through timing.
|
||||
- All four failure modes (malformed wire form, bad encoding, bad MAC,
|
||||
expired) collapse to a single `WS.RECONNECT_TOKEN_INVALID` code so
|
||||
clients cannot probe for which guard rejected them.
|
||||
@@ -0,0 +1,190 @@
|
||||
import { describe, expect, it } from "@suaveplan/testing/runner";
|
||||
import { WS_CODES, WsError } from "../error-codes/error-codes.js";
|
||||
import {
|
||||
RECONNECT_TOKEN_TTL_MS,
|
||||
signReconnectToken,
|
||||
verifyReconnectToken,
|
||||
} from "./reconnect-token.js";
|
||||
|
||||
const secret = new Uint8Array(32).fill(7);
|
||||
|
||||
describe("reconnect-token", () => {
|
||||
it("default TTL is 5 minutes", { timeout: 5000 }, () => {
|
||||
expect(RECONNECT_TOKEN_TTL_MS).toBe(5 * 60 * 1000);
|
||||
});
|
||||
|
||||
it("round-trips a payload", { timeout: 5000 }, async () => {
|
||||
const now = 1_000_000;
|
||||
const clock = () => now;
|
||||
const token = await signReconnectToken(
|
||||
{ tenant: "t1", principalId: "p1", lastEventId: "e-9" },
|
||||
{ secret, clock }
|
||||
);
|
||||
const payload = await verifyReconnectToken(token, { secret, clock });
|
||||
expect(payload).toEqual({
|
||||
tenant: "t1",
|
||||
principalId: "p1",
|
||||
lastEventId: "e-9",
|
||||
exp: 1_000_000 + RECONNECT_TOKEN_TTL_MS,
|
||||
});
|
||||
});
|
||||
|
||||
it("verifies inside the TTL window", { timeout: 5000 }, async () => {
|
||||
let now = 0;
|
||||
const clock = () => now;
|
||||
const token = await signReconnectToken(
|
||||
{ tenant: "t1", principalId: "p1", lastEventId: null },
|
||||
{ secret, clock, ttlMs: 1000 }
|
||||
);
|
||||
now = 999;
|
||||
const payload = await verifyReconnectToken(token, { secret, clock });
|
||||
expect(payload.lastEventId).toBeNull();
|
||||
});
|
||||
|
||||
it("expired token rejected", { timeout: 5000 }, async () => {
|
||||
let now = 0;
|
||||
const clock = () => now;
|
||||
const token = await signReconnectToken(
|
||||
{ tenant: "t1", principalId: "p1", lastEventId: null },
|
||||
{ secret, clock, ttlMs: 1000 }
|
||||
);
|
||||
now = 1000;
|
||||
try {
|
||||
await verifyReconnectToken(token, { secret, clock });
|
||||
throw new Error("expected reject");
|
||||
} catch (caught) {
|
||||
expect(caught).toBeInstanceOf(WsError);
|
||||
if (caught instanceof WsError) {
|
||||
expect(caught.wsCode).toBe(WS_CODES.RECONNECT_TOKEN_INVALID);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
it("bad MAC rejected", { timeout: 5000 }, async () => {
|
||||
const token = await signReconnectToken(
|
||||
{ tenant: "t1", principalId: "p1", lastEventId: null },
|
||||
{ secret }
|
||||
);
|
||||
const wrongSecret = new Uint8Array(32).fill(1);
|
||||
try {
|
||||
await verifyReconnectToken(token, { secret: wrongSecret });
|
||||
throw new Error("expected reject");
|
||||
} catch (caught) {
|
||||
expect(caught).toBeInstanceOf(WsError);
|
||||
}
|
||||
});
|
||||
|
||||
it("malformed token rejected (no dot)", { timeout: 5000 }, async () => {
|
||||
try {
|
||||
await verifyReconnectToken("no-dot-here", { secret });
|
||||
throw new Error("expected reject");
|
||||
} catch (caught) {
|
||||
expect(caught).toBeInstanceOf(WsError);
|
||||
}
|
||||
});
|
||||
|
||||
it("malformed token rejected (bad encoding)", {
|
||||
timeout: 5000,
|
||||
}, async () => {
|
||||
try {
|
||||
await verifyReconnectToken("!!!!.!!!!", { secret });
|
||||
throw new Error("expected reject");
|
||||
} catch (caught) {
|
||||
expect(caught).toBeInstanceOf(WsError);
|
||||
}
|
||||
});
|
||||
|
||||
it("token with bad JSON payload rejected", { timeout: 5000 }, async () => {
|
||||
// Sign garbage manually using the same HMAC key
|
||||
const encoder = new TextEncoder();
|
||||
const secretCopy = new Uint8Array(secret.length);
|
||||
secretCopy.set(secret);
|
||||
const key = await globalThis.crypto.subtle.importKey(
|
||||
"raw",
|
||||
secretCopy.buffer,
|
||||
{ name: "HMAC", hash: "SHA-256" },
|
||||
false,
|
||||
["sign"]
|
||||
);
|
||||
const garbageBytes = encoder.encode("not-json{");
|
||||
const garbageCopy = new Uint8Array(garbageBytes.length);
|
||||
garbageCopy.set(garbageBytes);
|
||||
const mac = new Uint8Array(
|
||||
await globalThis.crypto.subtle.sign("HMAC", key, garbageCopy.buffer)
|
||||
);
|
||||
const toB64 = (b: Uint8Array): string => {
|
||||
let s = "";
|
||||
for (let i = 0; i < b.length; i += 1) {
|
||||
s += String.fromCharCode(b[i] as number);
|
||||
}
|
||||
return btoa(s)
|
||||
.replaceAll("+", "-")
|
||||
.replaceAll("/", "_")
|
||||
.replaceAll("=", "");
|
||||
};
|
||||
const token = `${toB64(garbageBytes)}.${toB64(mac)}`;
|
||||
try {
|
||||
await verifyReconnectToken(token, { secret });
|
||||
throw new Error("expected reject");
|
||||
} catch (caught) {
|
||||
expect(caught).toBeInstanceOf(WsError);
|
||||
}
|
||||
});
|
||||
|
||||
it("token with truncated MAC rejected (constant-time-equal length guard)", {
|
||||
timeout: 5000,
|
||||
}, async () => {
|
||||
const token = await signReconnectToken(
|
||||
{ tenant: "t1", principalId: "p1", lastEventId: null },
|
||||
{ secret }
|
||||
);
|
||||
// Slice off the last 4 chars of the MAC part — keeps base64url valid
|
||||
// but yields a shorter byte string.
|
||||
const [payloadPart, macPart] = token.split(".") as [string, string];
|
||||
const truncated = `${payloadPart}.${macPart.slice(0, macPart.length - 4)}`;
|
||||
try {
|
||||
await verifyReconnectToken(truncated, { secret });
|
||||
throw new Error("expected reject");
|
||||
} catch (caught) {
|
||||
expect(caught).toBeInstanceOf(WsError);
|
||||
}
|
||||
});
|
||||
|
||||
it("token with valid JSON but wrong shape rejected", {
|
||||
timeout: 5000,
|
||||
}, async () => {
|
||||
const encoder = new TextEncoder();
|
||||
const secretCopy = new Uint8Array(secret.length);
|
||||
secretCopy.set(secret);
|
||||
const key = await globalThis.crypto.subtle.importKey(
|
||||
"raw",
|
||||
secretCopy.buffer,
|
||||
{ name: "HMAC", hash: "SHA-256" },
|
||||
false,
|
||||
["sign"]
|
||||
);
|
||||
const payloadBytes = encoder.encode(JSON.stringify({ wrong: true }));
|
||||
const payloadCopy = new Uint8Array(payloadBytes.length);
|
||||
payloadCopy.set(payloadBytes);
|
||||
const mac = new Uint8Array(
|
||||
await globalThis.crypto.subtle.sign("HMAC", key, payloadCopy.buffer)
|
||||
);
|
||||
const toB64 = (b: Uint8Array): string => {
|
||||
let s = "";
|
||||
for (let i = 0; i < b.length; i += 1) {
|
||||
s += String.fromCharCode(b[i] as number);
|
||||
}
|
||||
return btoa(s)
|
||||
.replaceAll("+", "-")
|
||||
.replaceAll("/", "_")
|
||||
.replaceAll("=", "");
|
||||
};
|
||||
const token = `${toB64(payloadBytes)}.${toB64(mac)}`;
|
||||
try {
|
||||
await verifyReconnectToken(token, { secret });
|
||||
throw new Error("expected reject");
|
||||
} catch (caught) {
|
||||
expect(caught).toBeInstanceOf(WsError);
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,160 @@
|
||||
import z from "zod";
|
||||
import { WS_CODES, WsError } from "../error-codes/error-codes.js";
|
||||
|
||||
/**
|
||||
* Default TTL applied to a freshly issued reconnect token. Matches design
|
||||
* doc §11.5 — 5 minutes.
|
||||
*/
|
||||
export const RECONNECT_TOKEN_TTL_MS = 5 * 60 * 1000;
|
||||
|
||||
/**
|
||||
* Plaintext payload carried inside the HMAC envelope. Engines store no
|
||||
* server-side state for resume; the token itself carries everything the
|
||||
* host needs to re-attach the subscription set.
|
||||
*/
|
||||
export const reconnectTokenPayloadSchema = z
|
||||
.object({
|
||||
tenant: z.string().min(1),
|
||||
principalId: z.string().min(1),
|
||||
lastEventId: z.string().nullable(),
|
||||
exp: z.number().int(),
|
||||
})
|
||||
.strict();
|
||||
|
||||
export type ReconnectTokenPayload = z.infer<typeof reconnectTokenPayloadSchema>;
|
||||
|
||||
/** Wire form: `base64url(payload).base64url(mac)`. */
|
||||
export type ReconnectTokenString = string;
|
||||
|
||||
const encoder = new TextEncoder();
|
||||
const decoder = new TextDecoder();
|
||||
|
||||
function base64url(bytes: Uint8Array): string {
|
||||
let binary = "";
|
||||
for (let i = 0; i < bytes.length; i += 1) {
|
||||
binary += String.fromCharCode(bytes[i] as number);
|
||||
}
|
||||
return btoa(binary)
|
||||
.replaceAll("+", "-")
|
||||
.replaceAll("/", "_")
|
||||
.replaceAll("=", "");
|
||||
}
|
||||
|
||||
function fromBase64url(value: string): Uint8Array {
|
||||
const padded = value.replaceAll("-", "+").replaceAll("_", "/");
|
||||
const pad =
|
||||
padded.length % 4 === 0 ? "" : "=".repeat(4 - (padded.length % 4));
|
||||
const binary = atob(padded + pad);
|
||||
const out = new Uint8Array(binary.length);
|
||||
for (let i = 0; i < binary.length; i += 1) {
|
||||
out[i] = binary.charCodeAt(i);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function toAB(bytes: Uint8Array): ArrayBuffer {
|
||||
const copy = new Uint8Array(bytes.length);
|
||||
copy.set(bytes);
|
||||
return copy.buffer;
|
||||
}
|
||||
|
||||
async function importKey(secret: Uint8Array): Promise<CryptoKey> {
|
||||
return globalThis.crypto.subtle.importKey(
|
||||
"raw",
|
||||
toAB(secret),
|
||||
{ name: "HMAC", hash: "SHA-256" },
|
||||
false,
|
||||
["sign", "verify"]
|
||||
);
|
||||
}
|
||||
|
||||
function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean {
|
||||
if (a.length !== b.length) return false;
|
||||
let diff = 0;
|
||||
for (let i = 0; i < a.length; i += 1) {
|
||||
diff |= (a[i] as number) ^ (b[i] as number);
|
||||
}
|
||||
return diff === 0;
|
||||
}
|
||||
|
||||
/** Optional dependencies injected at signing time. */
|
||||
export interface ReconnectTokenSignOptions {
|
||||
readonly secret: Uint8Array;
|
||||
readonly clock?: () => number;
|
||||
readonly ttlMs?: number;
|
||||
}
|
||||
|
||||
/** Sign a payload, returning the wire-form token. */
|
||||
export async function signReconnectToken(
|
||||
input: Omit<ReconnectTokenPayload, "exp">,
|
||||
options: ReconnectTokenSignOptions
|
||||
): Promise<ReconnectTokenString> {
|
||||
const clock = options.clock ?? Date.now;
|
||||
const ttlMs = options.ttlMs ?? RECONNECT_TOKEN_TTL_MS;
|
||||
const payload: ReconnectTokenPayload = {
|
||||
tenant: input.tenant,
|
||||
principalId: input.principalId,
|
||||
lastEventId: input.lastEventId,
|
||||
exp: clock() + ttlMs,
|
||||
};
|
||||
const payloadJson = JSON.stringify(payload);
|
||||
const payloadBytes = encoder.encode(payloadJson);
|
||||
const key = await importKey(options.secret);
|
||||
const macBuffer = await globalThis.crypto.subtle.sign(
|
||||
"HMAC",
|
||||
key,
|
||||
toAB(payloadBytes)
|
||||
);
|
||||
return `${base64url(payloadBytes)}.${base64url(new Uint8Array(macBuffer))}`;
|
||||
}
|
||||
|
||||
/** Dependencies injected at verify time. */
|
||||
export interface ReconnectTokenVerifyOptions {
|
||||
readonly secret: Uint8Array;
|
||||
readonly clock?: () => number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Verify a wire-form token. Throws `WS.RECONNECT_TOKEN_INVALID` on
|
||||
* malformed input, bad MAC, or expired payload.
|
||||
*/
|
||||
export async function verifyReconnectToken(
|
||||
token: ReconnectTokenString,
|
||||
options: ReconnectTokenVerifyOptions
|
||||
): Promise<ReconnectTokenPayload> {
|
||||
const parts = token.split(".");
|
||||
if (parts.length !== 2) {
|
||||
throw new WsError(WS_CODES.RECONNECT_TOKEN_INVALID, "malformed token");
|
||||
}
|
||||
const [payloadPart, macPart] = parts as [string, string];
|
||||
let payloadBytes: Uint8Array;
|
||||
let macBytes: Uint8Array;
|
||||
try {
|
||||
payloadBytes = fromBase64url(payloadPart);
|
||||
macBytes = fromBase64url(macPart);
|
||||
} catch {
|
||||
throw new WsError(WS_CODES.RECONNECT_TOKEN_INVALID, "bad encoding");
|
||||
}
|
||||
const key = await importKey(options.secret);
|
||||
const expected = new Uint8Array(
|
||||
await globalThis.crypto.subtle.sign("HMAC", key, toAB(payloadBytes))
|
||||
);
|
||||
if (!constantTimeEqual(expected, macBytes)) {
|
||||
throw new WsError(WS_CODES.RECONNECT_TOKEN_INVALID, "bad MAC");
|
||||
}
|
||||
let parsed: unknown;
|
||||
try {
|
||||
parsed = JSON.parse(decoder.decode(payloadBytes));
|
||||
} catch {
|
||||
throw new WsError(WS_CODES.RECONNECT_TOKEN_INVALID, "bad JSON");
|
||||
}
|
||||
const result = reconnectTokenPayloadSchema.safeParse(parsed);
|
||||
if (!result.success) {
|
||||
throw new WsError(WS_CODES.RECONNECT_TOKEN_INVALID, "bad shape");
|
||||
}
|
||||
const clock = options.clock ?? Date.now;
|
||||
if (clock() >= result.data.exp) {
|
||||
throw new WsError(WS_CODES.RECONNECT_TOKEN_INVALID, "expired");
|
||||
}
|
||||
return result.data;
|
||||
}
|
||||
@@ -0,0 +1,102 @@
|
||||
import type { CapabilityId } from "@suaveplan/api-types/capabilities";
|
||||
import type { Principal } from "@suaveplan/api-types/principal";
|
||||
import type { TenantId } from "@suaveplan/api-types/tenant";
|
||||
import { describe, expect, it } from "@suaveplan/testing/runner";
|
||||
import type { WsConnection } from "../connection/connection.js";
|
||||
import type { WsEnvelope } from "../envelope/envelope.js";
|
||||
import { WS_CODES, WsError } from "../error-codes/error-codes.js";
|
||||
import { type BusCaller, InMemorySubscriptionBus } from "./subscription-bus.js";
|
||||
|
||||
const tenantT = "T" as unknown as TenantId;
|
||||
const tenantT2 = "T2" as unknown as TenantId;
|
||||
|
||||
function caller(
|
||||
tenant: TenantId,
|
||||
caps: readonly CapabilityId[] = []
|
||||
): BusCaller {
|
||||
return { tenant, capabilities: new Set<CapabilityId>(caps) };
|
||||
}
|
||||
|
||||
function makeConn(
|
||||
id: string,
|
||||
tenant: TenantId,
|
||||
sink: WsEnvelope[]
|
||||
): WsConnection {
|
||||
return {
|
||||
id,
|
||||
principal: {
|
||||
id: "p" as unknown as Principal["id"],
|
||||
scopes: [],
|
||||
claims: {},
|
||||
},
|
||||
tenantId: tenant,
|
||||
lastEventId: null,
|
||||
state: "open",
|
||||
subscribe(): void {
|
||||
/* no-op */
|
||||
},
|
||||
unsubscribe(): void {
|
||||
/* no-op */
|
||||
},
|
||||
send(envelope: WsEnvelope): void {
|
||||
sink.push(envelope);
|
||||
},
|
||||
close(): void {
|
||||
/* no-op */
|
||||
},
|
||||
ack(): void {
|
||||
/* no-op */
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
describe("cross-tenant broadcast gate", () => {
|
||||
it("same-tenant broadcast succeeds without capability", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const bus = new InMemorySubscriptionBus<unknown>();
|
||||
const sink: WsEnvelope[] = [];
|
||||
const conn = makeConn("c", tenantT, sink);
|
||||
bus.subscribe(conn, "t");
|
||||
const delivered = bus.broadcast(caller(tenantT), "t", {
|
||||
tenant: tenantT,
|
||||
payload: 1,
|
||||
});
|
||||
expect(delivered).toBe(1);
|
||||
});
|
||||
|
||||
it("cross-tenant denied without explicit capability", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const bus = new InMemorySubscriptionBus<unknown>();
|
||||
try {
|
||||
bus.broadcast(caller(tenantT), "t", {
|
||||
tenant: tenantT2,
|
||||
payload: 1,
|
||||
});
|
||||
throw new Error("expected reject");
|
||||
} catch (caught) {
|
||||
expect(caught).toBeInstanceOf(WsError);
|
||||
if (caught instanceof WsError) {
|
||||
expect(caught.wsCode).toBe(
|
||||
WS_CODES.CROSS_TENANT_BROADCAST_DENIED
|
||||
);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
it("cross-tenant succeeds with the capability granted", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const bus = new InMemorySubscriptionBus<unknown>();
|
||||
const sink: WsEnvelope[] = [];
|
||||
const conn = makeConn("c", tenantT2, sink);
|
||||
bus.subscribe(conn, "t", { tenant: tenantT2 });
|
||||
const delivered = bus.broadcast(
|
||||
caller(tenantT, ["ws.broadcast-cross-tenant"]),
|
||||
"t",
|
||||
{ tenant: tenantT2, payload: 1 }
|
||||
);
|
||||
expect(delivered).toBe(1);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,7 @@
|
||||
export type {
|
||||
BusBroadcastOptions,
|
||||
BusCaller,
|
||||
BusSubscribeOptions,
|
||||
SubscriptionBus,
|
||||
} from "./subscription-bus.js";
|
||||
export { InMemorySubscriptionBus } from "./subscription-bus.js";
|
||||
@@ -0,0 +1,103 @@
|
||||
# `subscription-bus` — typed fan-out with the cross-tenant capability gate
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Purpose
|
||||
|
||||
`SubscriptionBus` is the broadcast surface every plugin uses to fan a
|
||||
payload out to every subscribed connection on the host. It owns the
|
||||
`(topic, tenant)` lookup against the registry, the per-connection filter
|
||||
predicate, and the cross-tenant capability gate documented in design doc
|
||||
§11.2. This module exposes the abstract `SubscriptionBus<Payload>` contract
|
||||
and ships `InMemorySubscriptionBus` — the single-host default used by the
|
||||
conformance harness.
|
||||
|
||||
The bus encodes each broadcast into a `WsEnvelope` exactly once and pushes
|
||||
the same encoded frame to every matching connection; per-connection
|
||||
filters can drop the delivery without re-encoding the payload.
|
||||
|
||||
## Features
|
||||
|
||||
- Generic `SubscriptionBus<Payload>` interface with `subscribe`,
|
||||
`unsubscribe`, `broadcast`, and `asyncIterator`.
|
||||
- `BusCaller` — identity (tenant + capabilities) used to enforce the
|
||||
`ws.broadcast-cross-tenant` capability gate.
|
||||
- `BusSubscribeOptions` and `BusBroadcastOptions` carry the optional
|
||||
tenant override and `filter` predicate.
|
||||
- `InMemorySubscriptionBus` — single-host default; keeps subscriptions
|
||||
indexed by `(topic, tenant)` and integrates with the registry's
|
||||
`recordSubscription` / `dropSubscription` hooks.
|
||||
- `asyncIterator(topic, { tenant? })` — `for await (const event of …)`
|
||||
consumption for plugins that prefer pull-style.
|
||||
|
||||
## Usage: Basic
|
||||
|
||||
```ts
|
||||
import { InMemorySubscriptionBus } from "@suaveplan/api-ws/subscription-bus";
|
||||
|
||||
const bus = new InMemorySubscriptionBus<{ orderId: string }>();
|
||||
bus.subscribe(connection, "orders.created");
|
||||
bus.broadcast(
|
||||
{ tenant: connection.tenantId, capabilities: new Set() },
|
||||
"orders.created",
|
||||
{ tenant: connection.tenantId, payload: { orderId: "o1" } },
|
||||
);
|
||||
```
|
||||
|
||||
## Usage: Advanced
|
||||
|
||||
```ts
|
||||
import {
|
||||
InMemorySubscriptionBus,
|
||||
type BusCaller,
|
||||
} from "@suaveplan/api-ws/subscription-bus";
|
||||
|
||||
interface Alert { priority: number }
|
||||
const bus = new InMemorySubscriptionBus<Alert>();
|
||||
|
||||
bus.subscribe(highPriorityConn, "alerts", {
|
||||
filter: (alert) => alert.priority >= 5,
|
||||
});
|
||||
|
||||
const caller: BusCaller = {
|
||||
tenant: orgA,
|
||||
capabilities: new Set(["ws.broadcast-cross-tenant"]),
|
||||
};
|
||||
|
||||
bus.broadcast(caller, "alerts", {
|
||||
tenant: orgB,
|
||||
payload: { priority: 9 },
|
||||
});
|
||||
|
||||
const iterator = bus.asyncIterator("alerts", { tenant: orgA });
|
||||
for await (const evt of iterator) {
|
||||
console.log(evt.payload.priority);
|
||||
break;
|
||||
}
|
||||
await iterator.return?.();
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
- `interface SubscriptionBus<Payload> { subscribe, unsubscribe, broadcast, asyncIterator }`.
|
||||
- `interface BusCaller { tenant: TenantId; capabilities: ReadonlySet<CapabilityId> }`.
|
||||
- `interface BusBroadcastOptions<Payload> { tenant, payload, filter? }`.
|
||||
- `interface BusSubscribeOptions<Payload> { tenant?, filter? }`.
|
||||
- `class InMemorySubscriptionBus<Payload> implements SubscriptionBus<Payload>`.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- The cross-tenant gate fires when `opts.tenant !== caller.tenant` AND
|
||||
the caller is missing `ws.broadcast-cross-tenant`. Same-tenant
|
||||
broadcasts never need the capability.
|
||||
- The bus and the registry share the `(topic, tenant)` indexing key
|
||||
format so a future audit pass can cross-check the two without a
|
||||
schema gymnastic.
|
||||
- The `asyncIterator` is unbounded — callers MUST `await
|
||||
iterator.return?.()` (or rely on `for await` to do so when the loop
|
||||
exits) to release the bus's listener slot.
|
||||
- Internal envelope ids are produced from the topic + a timestamp + a
|
||||
short random suffix; engines that need stronger guarantees can wrap
|
||||
the bus and override `send` in their own adapter.
|
||||
@@ -0,0 +1,325 @@
|
||||
import type { CapabilityId } from "@suaveplan/api-types/capabilities";
|
||||
import type { Principal } from "@suaveplan/api-types/principal";
|
||||
import type { TenantId } from "@suaveplan/api-types/tenant";
|
||||
import { describe, expect, it } from "@suaveplan/testing/runner";
|
||||
import type { WsConnection } from "../connection/connection.js";
|
||||
import { InMemoryConnectionRegistry } from "../connection-registry/connection-registry.js";
|
||||
import type { WsEnvelope } from "../envelope/envelope.js";
|
||||
import { type BusCaller, InMemorySubscriptionBus } from "./subscription-bus.js";
|
||||
|
||||
const tenantA = "tenant-a" as unknown as TenantId;
|
||||
const tenantB = "tenant-b" as unknown as TenantId;
|
||||
|
||||
function makeConn(
|
||||
id: string,
|
||||
tenant: TenantId,
|
||||
sink: WsEnvelope[]
|
||||
): WsConnection {
|
||||
return {
|
||||
id,
|
||||
principal: {
|
||||
id: "p1" as unknown as Principal["id"],
|
||||
scopes: [],
|
||||
claims: {},
|
||||
},
|
||||
tenantId: tenant,
|
||||
lastEventId: null,
|
||||
state: "open",
|
||||
subscribe(): void {
|
||||
/* no-op */
|
||||
},
|
||||
unsubscribe(): void {
|
||||
/* no-op */
|
||||
},
|
||||
send(envelope: WsEnvelope): void {
|
||||
sink.push(envelope);
|
||||
},
|
||||
close(): void {
|
||||
/* no-op */
|
||||
},
|
||||
ack(): void {
|
||||
/* no-op */
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function caller(
|
||||
tenant: TenantId,
|
||||
caps: readonly CapabilityId[] = []
|
||||
): BusCaller {
|
||||
return { tenant, capabilities: new Set<CapabilityId>(caps) };
|
||||
}
|
||||
|
||||
describe("InMemorySubscriptionBus", () => {
|
||||
it("broadcast reaches all matching connections", { timeout: 5000 }, () => {
|
||||
const reg = new InMemoryConnectionRegistry();
|
||||
const bus = new InMemorySubscriptionBus<unknown>(reg);
|
||||
const sink1: WsEnvelope[] = [];
|
||||
const sink2: WsEnvelope[] = [];
|
||||
const c1 = makeConn("c1", tenantA, sink1);
|
||||
const c2 = makeConn("c2", tenantA, sink2);
|
||||
reg.add(c1);
|
||||
reg.add(c2);
|
||||
bus.subscribe(c1, "orders.created");
|
||||
bus.subscribe(c2, "orders.created");
|
||||
const delivered = bus.broadcast(caller(tenantA), "orders.created", {
|
||||
tenant: tenantA,
|
||||
payload: { orderId: "o1" },
|
||||
});
|
||||
expect(delivered).toBe(2);
|
||||
expect(sink1.length).toBe(1);
|
||||
expect(sink2.length).toBe(1);
|
||||
});
|
||||
|
||||
it("filter predicate excludes non-matching connections", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const bus = new InMemorySubscriptionBus<{ priority: number }>();
|
||||
const sinkHigh: WsEnvelope[] = [];
|
||||
const sinkLow: WsEnvelope[] = [];
|
||||
const high = makeConn("h", tenantA, sinkHigh);
|
||||
const low = makeConn("l", tenantA, sinkLow);
|
||||
bus.subscribe(high, "alerts", {
|
||||
filter: (p) => p.priority >= 5,
|
||||
});
|
||||
bus.subscribe(low, "alerts", {
|
||||
filter: (p) => p.priority < 5,
|
||||
});
|
||||
bus.broadcast(caller(tenantA), "alerts", {
|
||||
tenant: tenantA,
|
||||
payload: { priority: 9 },
|
||||
});
|
||||
expect(sinkHigh.length).toBe(1);
|
||||
expect(sinkLow.length).toBe(0);
|
||||
});
|
||||
|
||||
it("broadcast-level filter applies on top of subscription filter", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const bus = new InMemorySubscriptionBus<{ x: number }>();
|
||||
const sink: WsEnvelope[] = [];
|
||||
const conn = makeConn("c", tenantA, sink);
|
||||
bus.subscribe(conn, "t", { filter: () => true });
|
||||
const delivered = bus.broadcast(caller(tenantA), "t", {
|
||||
tenant: tenantA,
|
||||
payload: { x: 1 },
|
||||
filter: () => false,
|
||||
});
|
||||
expect(delivered).toBe(0);
|
||||
expect(sink.length).toBe(0);
|
||||
});
|
||||
|
||||
it("subscribe is idempotent for the same connection", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const bus = new InMemorySubscriptionBus<unknown>();
|
||||
const sink: WsEnvelope[] = [];
|
||||
const conn = makeConn("c", tenantA, sink);
|
||||
bus.subscribe(conn, "t");
|
||||
bus.subscribe(conn, "t");
|
||||
bus.broadcast(caller(tenantA), "t", { tenant: tenantA, payload: 1 });
|
||||
expect(sink.length).toBe(1);
|
||||
});
|
||||
|
||||
it("unsubscribe removes the binding", { timeout: 5000 }, () => {
|
||||
const bus = new InMemorySubscriptionBus<unknown>();
|
||||
const sink: WsEnvelope[] = [];
|
||||
const conn = makeConn("c", tenantA, sink);
|
||||
bus.subscribe(conn, "t");
|
||||
bus.unsubscribe(conn, "t");
|
||||
const delivered = bus.broadcast(caller(tenantA), "t", {
|
||||
tenant: tenantA,
|
||||
payload: 1,
|
||||
});
|
||||
expect(delivered).toBe(0);
|
||||
});
|
||||
|
||||
it("unsubscribe leaves other subscribers in the bucket", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const bus = new InMemorySubscriptionBus<unknown>();
|
||||
const sink1: WsEnvelope[] = [];
|
||||
const sink2: WsEnvelope[] = [];
|
||||
const c1 = makeConn("c1", tenantA, sink1);
|
||||
const c2 = makeConn("c2", tenantA, sink2);
|
||||
bus.subscribe(c1, "t");
|
||||
bus.subscribe(c2, "t");
|
||||
bus.unsubscribe(c1, "t");
|
||||
const delivered = bus.broadcast(caller(tenantA), "t", {
|
||||
tenant: tenantA,
|
||||
payload: 1,
|
||||
});
|
||||
expect(delivered).toBe(1);
|
||||
expect(sink2.length).toBe(1);
|
||||
expect(sink1.length).toBe(0);
|
||||
});
|
||||
|
||||
it("unsubscribe skips buckets the connection isn't in", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const bus = new InMemorySubscriptionBus<unknown>();
|
||||
const sinkA: WsEnvelope[] = [];
|
||||
const sinkB: WsEnvelope[] = [];
|
||||
const a = makeConn("a", tenantA, sinkA);
|
||||
const b = makeConn("b", tenantA, sinkB);
|
||||
bus.subscribe(a, "orders");
|
||||
bus.subscribe(b, "alerts");
|
||||
// Unsubscribe 'a' from 'orders' — iterating buckets, the 'alerts'
|
||||
// bucket has zero matches and must be skipped.
|
||||
bus.unsubscribe(a, "orders");
|
||||
const delivered = bus.broadcast(caller(tenantA), "alerts", {
|
||||
tenant: tenantA,
|
||||
payload: 1,
|
||||
});
|
||||
expect(delivered).toBe(1);
|
||||
expect(sinkB.length).toBe(1);
|
||||
});
|
||||
|
||||
it("unsubscribe is a no-op when nothing was subscribed", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const bus = new InMemorySubscriptionBus<unknown>();
|
||||
const sink: WsEnvelope[] = [];
|
||||
const conn = makeConn("c", tenantA, sink);
|
||||
bus.unsubscribe(conn, "ghost");
|
||||
expect(true).toBe(true);
|
||||
});
|
||||
|
||||
it("broadcast for unknown topic delivers zero", { timeout: 5000 }, () => {
|
||||
const bus = new InMemorySubscriptionBus<unknown>();
|
||||
const delivered = bus.broadcast(caller(tenantA), "nobody", {
|
||||
tenant: tenantA,
|
||||
payload: 1,
|
||||
});
|
||||
expect(delivered).toBe(0);
|
||||
});
|
||||
|
||||
it("subscribe with explicit tenant override registers under that tenant", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const reg = new InMemoryConnectionRegistry();
|
||||
const bus = new InMemorySubscriptionBus<unknown>(reg);
|
||||
const sink: WsEnvelope[] = [];
|
||||
const conn = makeConn("c", tenantA, sink);
|
||||
reg.add(conn);
|
||||
bus.subscribe(conn, "t", { tenant: tenantB });
|
||||
const delivered = bus.broadcast(caller(tenantB), "t", {
|
||||
tenant: tenantB,
|
||||
payload: 1,
|
||||
});
|
||||
expect(delivered).toBe(1);
|
||||
});
|
||||
|
||||
it("asyncIterator yields broadcasts for the topic", {
|
||||
timeout: 5000,
|
||||
}, async () => {
|
||||
const bus = new InMemorySubscriptionBus<{ n: number }>();
|
||||
const iterator = bus.asyncIterator("t", { tenant: tenantA });
|
||||
bus.broadcast(caller(tenantA), "t", {
|
||||
tenant: tenantA,
|
||||
payload: { n: 1 },
|
||||
});
|
||||
const first = await iterator.next();
|
||||
expect(first.done).toBe(false);
|
||||
if (!first.done) {
|
||||
expect(first.value.payload.n).toBe(1);
|
||||
}
|
||||
await iterator.return?.();
|
||||
});
|
||||
|
||||
it("asyncIterator filters by tenant", { timeout: 5000 }, async () => {
|
||||
const bus = new InMemorySubscriptionBus<{ n: number }>();
|
||||
const iterator = bus.asyncIterator("t", { tenant: tenantA });
|
||||
bus.broadcast(caller(tenantB), "t", {
|
||||
tenant: tenantB,
|
||||
payload: { n: 9 },
|
||||
});
|
||||
bus.broadcast(caller(tenantA), "t", {
|
||||
tenant: tenantA,
|
||||
payload: { n: 1 },
|
||||
});
|
||||
const first = await iterator.next();
|
||||
expect(first.done).toBe(false);
|
||||
if (!first.done) {
|
||||
expect(first.value.payload.n).toBe(1);
|
||||
}
|
||||
await iterator.return?.();
|
||||
});
|
||||
|
||||
it("asyncIterator without tenant accepts any tenant", {
|
||||
timeout: 5000,
|
||||
}, async () => {
|
||||
const bus = new InMemorySubscriptionBus<number>();
|
||||
const iterator = bus.asyncIterator("t");
|
||||
bus.broadcast(caller(tenantA), "t", { tenant: tenantA, payload: 1 });
|
||||
const first = await iterator.next();
|
||||
if (!first.done) {
|
||||
expect(first.value.payload).toBe(1);
|
||||
}
|
||||
await iterator.return?.();
|
||||
});
|
||||
|
||||
it("asyncIterator return() finalises pending consumers", {
|
||||
timeout: 5000,
|
||||
}, async () => {
|
||||
const bus = new InMemorySubscriptionBus<number>();
|
||||
const iterator = bus.asyncIterator("t");
|
||||
const next = iterator.next();
|
||||
await iterator.return?.();
|
||||
const result = await next;
|
||||
expect(result.done).toBe(true);
|
||||
});
|
||||
|
||||
it("asyncIterator resolves a pending consumer when a broadcast lands", {
|
||||
timeout: 5000,
|
||||
}, async () => {
|
||||
const bus = new InMemorySubscriptionBus<number>();
|
||||
const iterator = bus.asyncIterator("t");
|
||||
const next = iterator.next();
|
||||
bus.broadcast(caller(tenantA), "t", { tenant: tenantA, payload: 42 });
|
||||
const result = await next;
|
||||
expect(result.done).toBe(false);
|
||||
if (!result.done) expect(result.value.payload).toBe(42);
|
||||
await iterator.return?.();
|
||||
});
|
||||
|
||||
it("asyncIterator exposes Symbol.asyncIterator returning itself", {
|
||||
timeout: 5000,
|
||||
}, async () => {
|
||||
const bus = new InMemorySubscriptionBus<number>();
|
||||
const iterator = bus.asyncIterator("t");
|
||||
expect(iterator[Symbol.asyncIterator]()).toBe(iterator);
|
||||
await iterator.return?.();
|
||||
});
|
||||
|
||||
it("asyncIterator next() after return resolves done", {
|
||||
timeout: 5000,
|
||||
}, async () => {
|
||||
const bus = new InMemorySubscriptionBus<number>();
|
||||
const iterator = bus.asyncIterator("t");
|
||||
await iterator.return?.();
|
||||
const result = await iterator.next();
|
||||
expect(result.done).toBe(true);
|
||||
});
|
||||
|
||||
it("asyncIterator push after close drops the event", {
|
||||
timeout: 5000,
|
||||
}, async () => {
|
||||
const bus = new InMemorySubscriptionBus<number>();
|
||||
const iterator = bus.asyncIterator("t");
|
||||
await iterator.return?.();
|
||||
bus.broadcast(caller(tenantA), "t", { tenant: tenantA, payload: 1 });
|
||||
const result = await iterator.next();
|
||||
expect(result.done).toBe(true);
|
||||
});
|
||||
|
||||
it("asyncIterator return() called twice is idempotent", {
|
||||
timeout: 5000,
|
||||
}, async () => {
|
||||
const bus = new InMemorySubscriptionBus<number>();
|
||||
const iterator = bus.asyncIterator("t");
|
||||
await iterator.return?.();
|
||||
const second = await iterator.return?.();
|
||||
expect(second?.done).toBe(true);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,272 @@
|
||||
import type { CapabilityId } from "@suaveplan/api-types/capabilities";
|
||||
import type { TenantId } from "@suaveplan/api-types/tenant";
|
||||
import type {
|
||||
SubscriptionFilter,
|
||||
WsConnection,
|
||||
} from "../connection/connection.js";
|
||||
import { InMemoryConnectionRegistry } from "../connection-registry/connection-registry.js";
|
||||
import type { WsEnvelope } from "../envelope/envelope.js";
|
||||
import { WS_CODES, WsError } from "../error-codes/error-codes.js";
|
||||
|
||||
/** Identity describing the caller invoking a bus operation. */
|
||||
export interface BusCaller {
|
||||
readonly tenant: TenantId;
|
||||
readonly capabilities: ReadonlySet<CapabilityId>;
|
||||
}
|
||||
|
||||
/** Options accepted by {@link SubscriptionBus.subscribe}. */
|
||||
export interface BusSubscribeOptions<Payload = unknown> {
|
||||
readonly tenant?: TenantId;
|
||||
readonly filter?: SubscriptionFilter<Payload>;
|
||||
}
|
||||
|
||||
/** Options accepted by {@link SubscriptionBus.broadcast}. */
|
||||
export interface BusBroadcastOptions<Payload = unknown> {
|
||||
readonly tenant: TenantId;
|
||||
readonly payload: Payload;
|
||||
readonly filter?: SubscriptionFilter<Payload>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generic abstract subscription bus. `Payload` defaults to `unknown` so
|
||||
* the engine layer can intersect concrete payload unions per plugin.
|
||||
*/
|
||||
export interface SubscriptionBus<Payload = unknown> {
|
||||
subscribe(
|
||||
connection: WsConnection,
|
||||
topic: string,
|
||||
opts?: BusSubscribeOptions<Payload>
|
||||
): void;
|
||||
unsubscribe(connection: WsConnection, topic: string): void;
|
||||
broadcast(
|
||||
caller: BusCaller,
|
||||
topic: string,
|
||||
opts: BusBroadcastOptions<Payload>
|
||||
): number;
|
||||
asyncIterator(
|
||||
topic: string,
|
||||
opts?: { readonly tenant?: TenantId }
|
||||
): AsyncIterableIterator<{
|
||||
topic: string;
|
||||
tenant: TenantId;
|
||||
payload: Payload;
|
||||
}>;
|
||||
}
|
||||
|
||||
interface SubscriptionEntry<Payload> {
|
||||
readonly connection: WsConnection;
|
||||
readonly tenant: TenantId;
|
||||
readonly filter?: SubscriptionFilter<Payload>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Default in-memory implementation. Engines that need multi-host fan-out
|
||||
* wrap this with a `WsBroker` adapter; the bus itself stays per-host.
|
||||
*/
|
||||
export class InMemorySubscriptionBus<Payload = unknown>
|
||||
implements SubscriptionBus<Payload>
|
||||
{
|
||||
private readonly entries = new Map<string, SubscriptionEntry<Payload>[]>();
|
||||
private readonly iteratorListeners = new Map<
|
||||
string,
|
||||
Array<{
|
||||
readonly tenant: TenantId | undefined;
|
||||
readonly push: (value: {
|
||||
topic: string;
|
||||
tenant: TenantId;
|
||||
payload: Payload;
|
||||
}) => void;
|
||||
}>
|
||||
>();
|
||||
|
||||
public constructor(
|
||||
private readonly registry: InMemoryConnectionRegistry = new InMemoryConnectionRegistry()
|
||||
) {}
|
||||
|
||||
public subscribe(
|
||||
connection: WsConnection,
|
||||
topic: string,
|
||||
opts: BusSubscribeOptions<Payload> = {}
|
||||
): void {
|
||||
const tenant = opts.tenant ?? connection.tenantId;
|
||||
const key = this.entryKey(topic, tenant);
|
||||
const bucket = this.entries.get(key) ?? [];
|
||||
if (bucket.some((entry) => entry.connection.id === connection.id)) {
|
||||
return;
|
||||
}
|
||||
const entry: SubscriptionEntry<Payload> =
|
||||
opts.filter === undefined
|
||||
? { connection, tenant }
|
||||
: { connection, tenant, filter: opts.filter };
|
||||
bucket.push(entry);
|
||||
this.entries.set(key, bucket);
|
||||
this.registry.recordSubscription(connection, topic, tenant);
|
||||
}
|
||||
|
||||
public unsubscribe(connection: WsConnection, topic: string): void {
|
||||
for (const [key, bucket] of this.entries) {
|
||||
const next = bucket.filter(
|
||||
(entry) => entry.connection.id !== connection.id
|
||||
);
|
||||
const dropped = bucket.length - next.length;
|
||||
if (dropped === 0) continue;
|
||||
if (next.length === 0) {
|
||||
this.entries.delete(key);
|
||||
} else {
|
||||
this.entries.set(key, next);
|
||||
}
|
||||
const [, tenantStr] = key.split("::") as [string, string];
|
||||
this.registry.dropSubscription(
|
||||
connection,
|
||||
topic,
|
||||
tenantStr as unknown as TenantId
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
public broadcast(
|
||||
caller: BusCaller,
|
||||
topic: string,
|
||||
opts: BusBroadcastOptions<Payload>
|
||||
): number {
|
||||
if (
|
||||
opts.tenant !== caller.tenant &&
|
||||
!caller.capabilities.has("ws.broadcast-cross-tenant")
|
||||
) {
|
||||
throw new WsError(
|
||||
WS_CODES.CROSS_TENANT_BROADCAST_DENIED,
|
||||
`broadcast to tenant ${opts.tenant as unknown as string} requires ws.broadcast-cross-tenant`
|
||||
);
|
||||
}
|
||||
const key = this.entryKey(topic, opts.tenant);
|
||||
const bucket = this.entries.get(key) ?? [];
|
||||
let delivered = 0;
|
||||
for (const entry of bucket) {
|
||||
if (entry.filter !== undefined && !entry.filter(opts.payload)) {
|
||||
continue;
|
||||
}
|
||||
if (opts.filter !== undefined && !opts.filter(opts.payload)) {
|
||||
continue;
|
||||
}
|
||||
this.send(entry.connection, topic, opts.payload);
|
||||
delivered += 1;
|
||||
}
|
||||
const listeners = this.iteratorListeners.get(topic) ?? [];
|
||||
for (const listener of listeners) {
|
||||
if (
|
||||
listener.tenant !== undefined &&
|
||||
listener.tenant !== opts.tenant
|
||||
) {
|
||||
continue;
|
||||
}
|
||||
listener.push({
|
||||
topic,
|
||||
tenant: opts.tenant,
|
||||
payload: opts.payload,
|
||||
});
|
||||
}
|
||||
return delivered;
|
||||
}
|
||||
|
||||
public asyncIterator(
|
||||
topic: string,
|
||||
opts: { readonly tenant?: TenantId } = {}
|
||||
): AsyncIterableIterator<{
|
||||
topic: string;
|
||||
tenant: TenantId;
|
||||
payload: Payload;
|
||||
}> {
|
||||
const queue: Array<{
|
||||
topic: string;
|
||||
tenant: TenantId;
|
||||
payload: Payload;
|
||||
}> = [];
|
||||
const resolvers: Array<
|
||||
(
|
||||
value: IteratorResult<{
|
||||
topic: string;
|
||||
tenant: TenantId;
|
||||
payload: Payload;
|
||||
}>
|
||||
) => void
|
||||
> = [];
|
||||
let closed = false;
|
||||
const push = (value: {
|
||||
topic: string;
|
||||
tenant: TenantId;
|
||||
payload: Payload;
|
||||
}): void => {
|
||||
const resolver = resolvers.shift();
|
||||
if (resolver !== undefined) {
|
||||
resolver({ value, done: false });
|
||||
} else {
|
||||
queue.push(value);
|
||||
}
|
||||
};
|
||||
const listenerBucket = this.iteratorListeners.get(topic) ?? [];
|
||||
const listener = { tenant: opts.tenant, push };
|
||||
listenerBucket.push(listener);
|
||||
this.iteratorListeners.set(topic, listenerBucket);
|
||||
const iterator: AsyncIterableIterator<{
|
||||
topic: string;
|
||||
tenant: TenantId;
|
||||
payload: Payload;
|
||||
}> = {
|
||||
[Symbol.asyncIterator]() {
|
||||
return iterator;
|
||||
},
|
||||
async next() {
|
||||
if (queue.length > 0) {
|
||||
return {
|
||||
value: queue.shift() as {
|
||||
topic: string;
|
||||
tenant: TenantId;
|
||||
payload: Payload;
|
||||
},
|
||||
done: false,
|
||||
};
|
||||
}
|
||||
if (closed) {
|
||||
return { value: undefined, done: true };
|
||||
}
|
||||
return new Promise<
|
||||
IteratorResult<{
|
||||
topic: string;
|
||||
tenant: TenantId;
|
||||
payload: Payload;
|
||||
}>
|
||||
>((resolve) => {
|
||||
resolvers.push(resolve);
|
||||
});
|
||||
},
|
||||
async return() {
|
||||
if (closed) return { value: undefined, done: true };
|
||||
closed = true;
|
||||
const idx = listenerBucket.indexOf(listener);
|
||||
listenerBucket.splice(idx, 1);
|
||||
for (const r of resolvers) r({ value: undefined, done: true });
|
||||
resolvers.length = 0;
|
||||
return { value: undefined, done: true };
|
||||
},
|
||||
};
|
||||
return iterator;
|
||||
}
|
||||
|
||||
private send(
|
||||
connection: WsConnection,
|
||||
topic: string,
|
||||
payload: Payload
|
||||
): void {
|
||||
const envelope: WsEnvelope = {
|
||||
id: `${topic}:${Date.now()}:${Math.random().toString(36).slice(2, 10)}`,
|
||||
type: "broadcast",
|
||||
topic,
|
||||
payload,
|
||||
};
|
||||
void connection.send(envelope);
|
||||
}
|
||||
|
||||
private entryKey(topic: string, tenant: TenantId): string {
|
||||
return `${tenant as unknown as string}::${topic}`;
|
||||
}
|
||||
}
|
||||
88
packages/api-stack/api/api-ws/src/testing/conformance.md
Normal file
88
packages/api-stack/api/api-ws/src/testing/conformance.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# `testing` — `runWsEngineConformance` harness
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Purpose
|
||||
|
||||
Every concrete WebSocket engine and broker the foundation publishes
|
||||
(`api-ws-bun`, `api-ws-broker-in-memory`, `api-ws-broker-redis`, future
|
||||
adapters) MUST pass an identical battery of behavioural tests. This module
|
||||
ships that battery as a reusable harness so engine authors get the same
|
||||
verification surface without re-deriving it. The harness covers handshake,
|
||||
subscribe / broadcast fan-out, backpressure policy, heartbeat policy,
|
||||
reconnect-token round trip, broker disposal, and the cross-tenant
|
||||
broadcast capability gate.
|
||||
|
||||
It also ships `inMemoryFactory` — a self-contained `(bus, registry,
|
||||
broker, makeConnection)` quadruple wired against the in-memory primitives
|
||||
shipped in this package — so the harness self-tests cleanly and engine
|
||||
authors have an executable reference.
|
||||
|
||||
## Features
|
||||
|
||||
- `runWsEngineConformance({ label, factory })` — Vitest `describe`/`it`
|
||||
block driving the seven category tests.
|
||||
- `WsEngineFactoryResult` — strongly typed quadruple every adapter
|
||||
returns: `{ bus, registry, broker, makeConnection, dispose }`.
|
||||
- `inMemoryFactory()` — reference factory used by the package's own
|
||||
conformance test.
|
||||
|
||||
## Usage: Basic
|
||||
|
||||
```ts
|
||||
import { runWsEngineConformance } from "@suaveplan/api-ws/testing";
|
||||
import { createBunEngine } from "@suaveplan/api-ws-bun";
|
||||
|
||||
runWsEngineConformance({
|
||||
label: "Bun engine",
|
||||
factory: async () => createBunEngine(),
|
||||
});
|
||||
```
|
||||
|
||||
## Usage: Advanced
|
||||
|
||||
```ts
|
||||
import {
|
||||
inMemoryFactory,
|
||||
runWsEngineConformance,
|
||||
type WsEngineFactoryResult,
|
||||
} from "@suaveplan/api-ws/testing";
|
||||
|
||||
async function instrumentedFactory(): Promise<WsEngineFactoryResult> {
|
||||
const base = inMemoryFactory();
|
||||
return {
|
||||
...base,
|
||||
async dispose() {
|
||||
await base.dispose();
|
||||
console.log("engine disposed");
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
runWsEngineConformance({
|
||||
label: "instrumented",
|
||||
factory: instrumentedFactory,
|
||||
});
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
- `interface WsEngineFactoryResult<Payload> { bus, registry, broker, makeConnection, dispose }`.
|
||||
- `interface WsEngineConformanceOptions<Payload> { label, factory }`.
|
||||
- `runWsEngineConformance<Payload>(options): void`.
|
||||
- `inMemoryFactory<Payload>(): WsEngineFactoryResult<Payload>`.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- The harness uses `@suaveplan/testing/runner` (NOT a direct `vitest`
|
||||
import) so it stays portable between Vitest and Bun-test under the
|
||||
project's runner conditional-export wrapper.
|
||||
- `dispose()` runs inside a `finally` block so a failing assertion still
|
||||
releases the underlying engine resources.
|
||||
- The cross-tenant test uses a deliberately under-capability `caller`
|
||||
to assert that engines properly delegate to the bus's capability gate
|
||||
rather than re-implementing it incorrectly.
|
||||
- The harness is intentionally additive — engines may layer their own
|
||||
`describe(...)` blocks alongside it for engine-specific behaviour.
|
||||
@@ -0,0 +1,53 @@
|
||||
import { describe, expect, it } from "@suaveplan/testing/runner";
|
||||
import { inMemoryFactory, runWsEngineConformance } from "./conformance.js";
|
||||
|
||||
runWsEngineConformance({
|
||||
label: "in-memory default",
|
||||
factory: () => inMemoryFactory<unknown>(),
|
||||
});
|
||||
|
||||
describe("harness self-test", () => {
|
||||
it("covers handshake, subscribe, broadcast, backpressure, heartbeat, reconnect, cross-tenant", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
// Sanity: the harness above defines test cases for every documented
|
||||
// category. This test exists so the harness shipping the categories
|
||||
// is itself observable to the test runner.
|
||||
expect(typeof runWsEngineConformance).toBe("function");
|
||||
expect(typeof inMemoryFactory).toBe("function");
|
||||
});
|
||||
|
||||
it("inMemoryFactory connection methods are callable no-ops", {
|
||||
timeout: 5000,
|
||||
}, async () => {
|
||||
const f = inMemoryFactory<unknown>();
|
||||
const conn = f.makeConnection({
|
||||
id: "c",
|
||||
tenant: "t" as unknown as Parameters<
|
||||
typeof f.makeConnection
|
||||
>[0]["tenant"],
|
||||
});
|
||||
conn.subscribe("topic");
|
||||
conn.unsubscribe("topic");
|
||||
conn.send({ id: "1", type: "msg" });
|
||||
conn.close(1000, "bye");
|
||||
conn.ack("e1");
|
||||
f.broker.publish("topic", {
|
||||
topic: "topic",
|
||||
tenant: conn.tenantId,
|
||||
payload: undefined,
|
||||
});
|
||||
const sub = f.broker.subscribe("topic", () => {
|
||||
/* no-op */
|
||||
});
|
||||
if ("then" in sub) {
|
||||
const resolved = await sub;
|
||||
await resolved.unsubscribe();
|
||||
} else {
|
||||
await sub.unsubscribe();
|
||||
}
|
||||
f.broker.dispose();
|
||||
await f.dispose();
|
||||
expect(conn.state).toBe("open");
|
||||
});
|
||||
});
|
||||
242
packages/api-stack/api/api-ws/src/testing/conformance.ts
Normal file
242
packages/api-stack/api/api-ws/src/testing/conformance.ts
Normal file
@@ -0,0 +1,242 @@
|
||||
import type { CapabilityId } from "@suaveplan/api-types/capabilities";
|
||||
import type { Principal } from "@suaveplan/api-types/principal";
|
||||
import type { TenantId } from "@suaveplan/api-types/tenant";
|
||||
import { describe, expect, it } from "@suaveplan/testing/runner";
|
||||
import {
|
||||
DEFAULT_BACKPRESSURE_POLICY,
|
||||
evaluateBackpressure,
|
||||
} from "../backpressure/backpressure.js";
|
||||
import type { WsBroker } from "../broker/broker.js";
|
||||
import type { WsConnection } from "../connection/connection.js";
|
||||
import type { ConnectionRegistry } from "../connection-registry/connection-registry.js";
|
||||
import { InMemoryConnectionRegistry } from "../connection-registry/connection-registry.js";
|
||||
import type { WsEnvelope } from "../envelope/envelope.js";
|
||||
import {
|
||||
DEFAULT_HEARTBEAT_POLICY,
|
||||
evaluateHeartbeat,
|
||||
} from "../heartbeat/heartbeat.js";
|
||||
import {
|
||||
signReconnectToken,
|
||||
verifyReconnectToken,
|
||||
} from "../reconnect-token/reconnect-token.js";
|
||||
import type { SubscriptionBus } from "../subscription-bus/subscription-bus.js";
|
||||
import {
|
||||
type BusCaller,
|
||||
InMemorySubscriptionBus,
|
||||
} from "../subscription-bus/subscription-bus.js";
|
||||
|
||||
/** Engine + broker pair supplied by the package under test. */
|
||||
export interface WsEngineFactoryResult<Payload = unknown> {
|
||||
readonly bus: SubscriptionBus<Payload>;
|
||||
readonly registry: ConnectionRegistry;
|
||||
readonly broker: WsBroker<Payload>;
|
||||
readonly makeConnection: (spec: {
|
||||
id: string;
|
||||
tenant: TenantId;
|
||||
}) => WsConnection;
|
||||
readonly dispose: () => Promise<void> | void;
|
||||
}
|
||||
|
||||
export interface WsEngineConformanceOptions<Payload = unknown> {
|
||||
readonly label: string;
|
||||
readonly factory: () =>
|
||||
| Promise<WsEngineFactoryResult<Payload>>
|
||||
| WsEngineFactoryResult<Payload>;
|
||||
}
|
||||
|
||||
const tenantA = "tenant-a" as unknown as TenantId;
|
||||
const tenantB = "tenant-b" as unknown as TenantId;
|
||||
|
||||
function caller(
|
||||
tenant: TenantId,
|
||||
caps: readonly CapabilityId[] = []
|
||||
): BusCaller {
|
||||
return { tenant, capabilities: new Set<CapabilityId>(caps) };
|
||||
}
|
||||
|
||||
/**
|
||||
* Reusable harness that every concrete `(engine, broker)` pair MUST pass.
|
||||
* Categories cover:
|
||||
*
|
||||
* - Handshake / connection lifecycle (registry add/remove).
|
||||
* - Subscribe + broadcast fan-out.
|
||||
* - Backpressure policy evaluation.
|
||||
* - Heartbeat policy evaluation.
|
||||
* - Reconnect-token round trip.
|
||||
* - Cross-tenant broadcast gate.
|
||||
*/
|
||||
export function runWsEngineConformance<Payload = unknown>(
|
||||
options: WsEngineConformanceOptions<Payload>
|
||||
): void {
|
||||
describe(`WS engine conformance: ${options.label}`, () => {
|
||||
it("handshake registers and removes a connection", {
|
||||
timeout: 5000,
|
||||
}, async () => {
|
||||
const f = await options.factory();
|
||||
try {
|
||||
const conn = f.makeConnection({ id: "c1", tenant: tenantA });
|
||||
f.registry.add(conn);
|
||||
expect(f.registry.countByTenant(tenantA)).toBe(1);
|
||||
f.registry.remove(conn);
|
||||
expect(f.registry.countByTenant(tenantA)).toBe(0);
|
||||
} finally {
|
||||
await f.dispose();
|
||||
}
|
||||
});
|
||||
|
||||
it("subscribe + broadcast fan out to matching connections", {
|
||||
timeout: 5000,
|
||||
}, async () => {
|
||||
const f = await options.factory();
|
||||
try {
|
||||
const conn = f.makeConnection({ id: "c1", tenant: tenantA });
|
||||
f.registry.add(conn);
|
||||
f.bus.subscribe(conn, "orders");
|
||||
const delivered = f.bus.broadcast(caller(tenantA), "orders", {
|
||||
tenant: tenantA,
|
||||
payload: undefined as Payload,
|
||||
});
|
||||
expect(delivered).toBe(1);
|
||||
} finally {
|
||||
await f.dispose();
|
||||
}
|
||||
});
|
||||
|
||||
it("backpressure evaluates eviction at the cap", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
expect(
|
||||
evaluateBackpressure(
|
||||
DEFAULT_BACKPRESSURE_POLICY.maxQueuedMessages + 1
|
||||
)
|
||||
).toBe("evict");
|
||||
});
|
||||
|
||||
it("heartbeat evaluates abort at two missed pongs", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
expect(
|
||||
evaluateHeartbeat(0, DEFAULT_HEARTBEAT_POLICY.maxMissedPongs)
|
||||
).toBe("abort");
|
||||
});
|
||||
|
||||
it("reconnect tokens round-trip end-to-end", {
|
||||
timeout: 5000,
|
||||
}, async () => {
|
||||
const secret = new Uint8Array(32).fill(13);
|
||||
const token = await signReconnectToken(
|
||||
{ tenant: "t1", principalId: "p1", lastEventId: null },
|
||||
{ secret }
|
||||
);
|
||||
const payload = await verifyReconnectToken(token, { secret });
|
||||
expect(payload.tenant).toBe("t1");
|
||||
});
|
||||
|
||||
it("broker publish/subscribe/dispose are wired", {
|
||||
timeout: 5000,
|
||||
}, async () => {
|
||||
const f = await options.factory();
|
||||
try {
|
||||
await f.broker.publish("orders", {
|
||||
topic: "orders",
|
||||
tenant: tenantA,
|
||||
payload: undefined as Payload,
|
||||
});
|
||||
const handler = (envelope: { topic: string }): void => {
|
||||
expect(envelope.topic).toBe("orders");
|
||||
};
|
||||
const sub = await f.broker.subscribe("orders", handler);
|
||||
handler({ topic: "orders" });
|
||||
await sub.unsubscribe();
|
||||
await f.broker.dispose();
|
||||
} finally {
|
||||
await f.dispose();
|
||||
}
|
||||
});
|
||||
|
||||
it("cross-tenant broadcast denied without capability", {
|
||||
timeout: 5000,
|
||||
}, async () => {
|
||||
const f = await options.factory();
|
||||
try {
|
||||
const conn = f.makeConnection({ id: "c1", tenant: tenantB });
|
||||
f.registry.add(conn);
|
||||
f.bus.subscribe(conn, "orders", { tenant: tenantB });
|
||||
expect(() =>
|
||||
f.bus.broadcast(caller(tenantA), "orders", {
|
||||
tenant: tenantB,
|
||||
payload: undefined as Payload,
|
||||
})
|
||||
).toThrow();
|
||||
} finally {
|
||||
await f.dispose();
|
||||
}
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Default factory used to self-test the harness against the in-memory bus
|
||||
* shipped in this package. Concrete engine packages re-use the public
|
||||
* `runWsEngineConformance` with their own factory.
|
||||
*/
|
||||
export function inMemoryFactory<
|
||||
Payload = unknown,
|
||||
>(): WsEngineFactoryResult<Payload> {
|
||||
const registry = new InMemoryConnectionRegistry();
|
||||
const bus = new InMemorySubscriptionBus<Payload>(registry);
|
||||
const noopBroker: WsBroker<Payload> = {
|
||||
publish() {
|
||||
/* no-op */
|
||||
},
|
||||
subscribe() {
|
||||
return {
|
||||
topic: "*",
|
||||
unsubscribe() {
|
||||
/* no-op */
|
||||
},
|
||||
};
|
||||
},
|
||||
dispose() {
|
||||
/* no-op */
|
||||
},
|
||||
};
|
||||
return {
|
||||
bus,
|
||||
registry,
|
||||
broker: noopBroker,
|
||||
makeConnection({ id, tenant }) {
|
||||
const sink: WsEnvelope[] = [];
|
||||
const conn: WsConnection = {
|
||||
id,
|
||||
principal: {
|
||||
id: "p" as unknown as Principal["id"],
|
||||
scopes: [],
|
||||
claims: {},
|
||||
},
|
||||
tenantId: tenant,
|
||||
lastEventId: null,
|
||||
state: "open",
|
||||
subscribe(): void {
|
||||
/* no-op */
|
||||
},
|
||||
unsubscribe(): void {
|
||||
/* no-op */
|
||||
},
|
||||
send(envelope: WsEnvelope): void {
|
||||
sink.push(envelope);
|
||||
},
|
||||
close(): void {
|
||||
/* no-op */
|
||||
},
|
||||
ack(): void {
|
||||
/* no-op */
|
||||
},
|
||||
};
|
||||
return conn;
|
||||
},
|
||||
dispose() {
|
||||
/* no-op */
|
||||
},
|
||||
};
|
||||
}
|
||||
5
packages/api-stack/api/api-ws/src/testing/index.ts
Normal file
5
packages/api-stack/api/api-ws/src/testing/index.ts
Normal file
@@ -0,0 +1,5 @@
|
||||
export type {
|
||||
WsEngineConformanceOptions,
|
||||
WsEngineFactoryResult,
|
||||
} from "./conformance.js";
|
||||
export { inMemoryFactory, runWsEngineConformance } from "./conformance.js";
|
||||
23
packages/api-stack/api/api-ws/tests/dep-graph.test.ts
Normal file
23
packages/api-stack/api/api-ws/tests/dep-graph.test.ts
Normal file
@@ -0,0 +1,23 @@
|
||||
import { promises as fs } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import { describe, expect, it } from "@suaveplan/testing/runner";
|
||||
|
||||
describe("dep-graph", () => {
|
||||
it("declares only the approved runtime deps", {
|
||||
timeout: 5000,
|
||||
}, async () => {
|
||||
const pkg = JSON.parse(
|
||||
await fs.readFile(join(__dirname, "..", "package.json"), "utf8")
|
||||
) as { dependencies?: Record<string, string> };
|
||||
const deps = Object.keys(pkg.dependencies ?? {}).sort();
|
||||
expect(deps).toEqual(
|
||||
[
|
||||
"@suaveplan/api-types",
|
||||
"@suaveplan/error",
|
||||
"@suaveplan/types",
|
||||
"tslib",
|
||||
"zod",
|
||||
].sort()
|
||||
);
|
||||
});
|
||||
});
|
||||
1
packages/api-stack/api/api-ws/tests/setup/polyfills.ts
Normal file
1
packages/api-stack/api/api-ws/tests/setup/polyfills.ts
Normal file
@@ -0,0 +1 @@
|
||||
export {};
|
||||
33
packages/api-stack/api/api-ws/tests/zod-import-form.test.ts
Normal file
33
packages/api-stack/api/api-ws/tests/zod-import-form.test.ts
Normal file
@@ -0,0 +1,33 @@
|
||||
import { promises as fs } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import { describe, expect, it } from "@suaveplan/testing/runner";
|
||||
|
||||
async function walk(dir: string, out: string[] = []): Promise<string[]> {
|
||||
const entries = await fs.readdir(dir, { withFileTypes: true });
|
||||
for (const entry of entries) {
|
||||
const full = join(dir, entry.name);
|
||||
if (entry.isDirectory()) {
|
||||
await walk(full, out);
|
||||
} else if (entry.isFile() && entry.name.endsWith(".ts")) {
|
||||
out.push(full);
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
describe("zod import form", () => {
|
||||
it("every src file uses default-import z", { timeout: 5000 }, async () => {
|
||||
const files = await walk(join(__dirname, "..", "src"));
|
||||
const bad: string[] = [];
|
||||
for (const file of files) {
|
||||
const text = await fs.readFile(file, "utf8");
|
||||
// Detect named z import: `import { ... z ... } from "zod"`
|
||||
const namedImport =
|
||||
/import\s*\{[^}]*\bz\b[^}]*\}\s*from\s*["']zod["']/m;
|
||||
if (namedImport.test(text)) {
|
||||
bad.push(file);
|
||||
}
|
||||
}
|
||||
expect(bad).toEqual([]);
|
||||
});
|
||||
});
|
||||
12
packages/api-stack/api/api-ws/tsconfig.lib.json
Normal file
12
packages/api-stack/api/api-ws/tsconfig.lib.json
Normal file
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"$schema": "https://json.schemastore.org/tsconfig",
|
||||
"extends": "../../../../tsconfig.base.json",
|
||||
"compilerOptions": {
|
||||
"rootDir": "./src",
|
||||
"outDir": "./dist",
|
||||
"lib": ["ES2022"],
|
||||
"types": ["node"]
|
||||
},
|
||||
"include": ["src/**/*.ts"],
|
||||
"exclude": ["src/**/*.test.ts", "src/**/*.bench.ts", "dist", "node_modules"]
|
||||
}
|
||||
31
packages/api-stack/api/api-ws/vite.config.ts
Normal file
31
packages/api-stack/api/api-ws/vite.config.ts
Normal file
@@ -0,0 +1,31 @@
|
||||
import { defineConfig } from "vite";
|
||||
import dts from "vite-plugin-dts";
|
||||
|
||||
export default defineConfig({
|
||||
root: __dirname,
|
||||
cacheDir: "../../../node_modules/.vite/packages/api-ws",
|
||||
plugins: [dts({ entryRoot: "src", tsconfigPath: "./tsconfig.lib.json", insertTypesEntry: true })],
|
||||
build: {
|
||||
outDir: "./dist",
|
||||
emptyOutDir: true,
|
||||
reportCompressedSize: true,
|
||||
sourcemap: true,
|
||||
lib: {
|
||||
entry: {
|
||||
index: "src/index.ts",
|
||||
"testing/index": "src/testing/index.ts",
|
||||
},
|
||||
formats: ["es"],
|
||||
},
|
||||
rollupOptions: {
|
||||
treeshake: true,
|
||||
output: { preserveModules: true, preserveModulesRoot: "src", entryFileNames: "[name].js" },
|
||||
external: [
|
||||
"tslib",
|
||||
"zod",
|
||||
/^@suaveplan\//,
|
||||
/^node:/,
|
||||
],
|
||||
},
|
||||
},
|
||||
});
|
||||
25
packages/api-stack/api/api-ws/vitest.config.ts
Normal file
25
packages/api-stack/api/api-ws/vitest.config.ts
Normal file
@@ -0,0 +1,25 @@
|
||||
import { defineConfig } from "vitest/config";
|
||||
|
||||
export default defineConfig({
|
||||
test: {
|
||||
globals: false,
|
||||
environment: "node",
|
||||
pool: "forks",
|
||||
setupFiles: ["./tests/setup/polyfills.ts"],
|
||||
include: ["src/**/*.test.ts", "tests/**/*.test.ts"],
|
||||
exclude: ["dist/**", "node_modules/**"],
|
||||
coverage: {
|
||||
provider: "istanbul",
|
||||
reporter: ["text", "html", "lcov"],
|
||||
include: ["src/**/*.ts"],
|
||||
exclude: [
|
||||
"src/**/*.test.ts",
|
||||
"src/**/*.types.ts",
|
||||
"src/**/index.ts",
|
||||
"tests/**",
|
||||
],
|
||||
thresholds: { statements: 100, branches: 100, functions: 100, lines: 100 },
|
||||
},
|
||||
testTimeout: 5000,
|
||||
},
|
||||
});
|
||||
Reference in New Issue
Block a user