skills/docs/api-stack/api/api-ws/README.md

@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 — Per design doc §11.4, every WebSocket connection MUST have a bounded outbound queue. This module owns the abstract poli…
  • backpressure — Per design doc §11.4, every WebSocket connection MUST have a bounded outbound queue. This module owns the abstract poli…
• broker — A single-host deployment never needs a broker — the SubscriptionBus inside that process already sees every connection…
  • broker — A single-host deployment never needs a broker — the SubscriptionBus inside that process already sees every connection…
• capability-id — @suaveplan/api-types/capabilities owns the closed CapabilityId union for the whole API foundation. `@suaveplan/api-…
  • capability-id — @suaveplan/api-types/capabilities owns the closed CapabilityId union for the whole API foundation. `@suaveplan/api-…
• connection — @suaveplan/api-ws/connection declares the abstract WsConnection interface every concrete engine (api-ws-bun, futu…
  • connection — @suaveplan/api-ws/connection declares the abstract WsConnection interface every concrete engine (api-ws-bun, futu…
• connection-registry — Every plugin endpoint that opens a WebSocket connection registers it with a host-owned ConnectionRegistry. The regist…
  • connection-registry — Every plugin endpoint that opens a WebSocket connection registers it with a host-owned ConnectionRegistry. The regist…
• envelope — @suaveplan/api-ws/envelope owns the canonical Zod schema for every WebSocket frame that flows between the host and a…
  • envelope — @suaveplan/api-ws/envelope owns the canonical Zod schema for every WebSocket frame that flows between the host and a…
• error-codes — @suaveplan/api-ws owns the abstract WebSocket contract. Every public failure path raises a WsError carrying a stabl…
  • error-codes — @suaveplan/api-ws owns the abstract WebSocket contract. Every public failure path raises a WsError carrying a stabl…
• heartbeat — Every WebSocket connection that the Suaveplan API host accepts is policed by a heartbeat: the engine pings at a fixed c…
  • heartbeat — Every WebSocket connection that the Suaveplan API host accepts is policed by a heartbeat: the engine pings at a fixed c…
• reconnect-token — When the host closes a WebSocket connection cleanly (heartbeat failure, deploy, transient network issue), it issues a r…
  • reconnect-token — When the host closes a WebSocket connection cleanly (heartbeat failure, deploy, transient network issue), it issues a r…
• subscription-bus — SubscriptionBus is the broadcast surface every plugin uses to fan a payload out to every subscribed connection on the…
  • subscription-bus — SubscriptionBus is the broadcast surface every plugin uses to fan a payload out to every subscribed connection on the…
• testing — Every concrete WebSocket engine and broker the foundation publishes (api-ws-bun, api-ws-broker-in-memory, `api-ws-b…
  • conformance — 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
./connection-registry	ConnectionRegistry interface + InMemoryConnectionRegistry with (tenantId) and (topic, tenantId) indices. docs
./subscription-bus	SubscriptionBus<Payload> + InMemorySubscriptionBus; cross-tenant capability gate. docs
./broker	WsBroker multi-host fan-out contract — publish, subscribe, dispose. docs
./envelope	WsEnvelope Zod schema for wire frames; strict mode rejects unknown keys. docs
./backpressure	BackpressurePolicy + evaluateBackpressure (default maxQueuedMessages = 256). docs
./heartbeat	HeartbeatPolicy + evaluateHeartbeat (default heartbeatMs = 30000, two missed pongs to abort). docs
./reconnect-token	HMAC-SHA-256 reconnect-token envelope with 5-minute TTL; Web Crypto. docs
./capability-id	WS_CAPABILITY_IDS re-exports for "ws" and "ws.broadcast-cross-tenant". docs
./error-codes	WS_CODES registry (8 codes) + WsError + engine throw helpers. docs
./testing	runWsEngineConformance harness + inMemoryFactory reference. docs

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.