# @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. ## 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… ## 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` + `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.