Initial Commit
This commit is contained in:
@@ -0,0 +1,167 @@
|
||||
# OpenSpec Change: enterprise-websocket-gateway
|
||||
|
||||
- **Change ID**: enterprise-websocket-gateway
|
||||
- **Package**: `@suaveplan/websocket-gateway`
|
||||
- **Category**: api/framework
|
||||
- **Target path**: `api/framework/websocket-gateway`
|
||||
- **Status**: SUPERSEDED-BY-GENESIS-WAVE
|
||||
- **Date**: 2026-04-24
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/websocket-gateway` on the genesis branch from scratch at enterprise quality. The package provides a WebSocket gateway layer for the Suaveplan API tier: connection lifecycle management (`connect` / `disconnect` / `reconnect`), message routing (topic-based publish/subscribe + RPC-style request/reply), authentication via JWT (injected `@suaveplan/jwt-tenant` verifier), per-connection rate limiting, backpressure via bounded send queues, heartbeat/ping-pong with configurable intervals, and a Hono WebSocket upgrade adapter. Backed by `@suaveplan/events` for internal message fan-out. Genesis adds structured errors, Zod message schemas, OTel instrumentation, and a benchmark suite.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
Package does not exist on genesis — fresh build. No reference enterprise spec file found; design based on `@suaveplan/api-gateway` pattern and the Hono WebSocket API.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | `WebSocketGatewayError` hierarchy |
|
||||
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `EventBusLike` |
|
||||
| `@suaveplan/logger` (`workspace:^`) | Per-connection structured logging |
|
||||
| `@suaveplan/events` (`workspace:^`) | Internal topic fan-out |
|
||||
| `@suaveplan/rate-limiter` (`workspace:^`) | Per-connection message rate limiting |
|
||||
| `@suaveplan/api` (`workspace:^`) | Hono app type |
|
||||
| `hono` (`catalog:server`) | `upgradeWebSocket` helper |
|
||||
| `zod` (`catalog:forms`) | Message schema validation |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Spans + metrics |
|
||||
| `tslib` (`catalog:build`) | Runtime helpers |
|
||||
|
||||
---
|
||||
|
||||
## Public API surface
|
||||
|
||||
### Core
|
||||
|
||||
```ts
|
||||
function createWebSocketGateway(options: WebSocketGatewayOptions): WebSocketGateway
|
||||
|
||||
interface WebSocketGateway {
|
||||
handleUpgrade(app: HonoApp, path: string): void
|
||||
publish(topic: string, message: unknown): void
|
||||
broadcast(message: unknown): void
|
||||
getConnection(id: string): WsConnection | undefined
|
||||
connectionCount(): number
|
||||
close(): Promise<void>
|
||||
}
|
||||
|
||||
interface WsConnection {
|
||||
id: string
|
||||
userId?: string
|
||||
tenantId?: string
|
||||
subscribe(topic: string): void
|
||||
unsubscribe(topic: string): void
|
||||
send(message: unknown): void
|
||||
close(): void
|
||||
}
|
||||
```
|
||||
|
||||
### Types
|
||||
|
||||
```ts
|
||||
interface WebSocketGatewayOptions {
|
||||
maxConnections?: number
|
||||
sendQueueSize?: number
|
||||
heartbeatIntervalMs?: number
|
||||
pingTimeoutMs?: number
|
||||
rateLimiter?: RateLimiterLike
|
||||
authenticate?: (token: string) => Promise<WsAuthResult>
|
||||
logger?: LoggerLike
|
||||
eventBus?: EventBusLike
|
||||
}
|
||||
|
||||
interface WsAuthResult { userId: string; tenantId: string; claims: Record<string, unknown> }
|
||||
type WsMessageHandler = (conn: WsConnection, message: unknown) => void | Promise<void>
|
||||
```
|
||||
|
||||
### Error codes
|
||||
|
||||
```ts
|
||||
type WsGatewayErrorCode =
|
||||
| "WS_MAX_CONNECTIONS"
|
||||
| "WS_AUTH_FAILED"
|
||||
| "WS_RATE_LIMITED"
|
||||
| "WS_QUEUE_FULL"
|
||||
| "WS_INVALID_MESSAGE"
|
||||
| "WS_CONNECTION_NOT_FOUND"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Genesis additions
|
||||
|
||||
1. **Zod message envelope schema** — `{ type: string, topic?: string, payload: unknown, id?: string }` validated on every inbound message.
|
||||
2. **OTel** — `ws.connections_active` gauge, `ws.messages_received_total` / `ws.messages_sent_total` counters, `ws.message_processing_duration_ms` histogram.
|
||||
3. **Heartbeat** — ping frame sent every `heartbeatIntervalMs` (default 30 s); connection closed if pong not received within `pingTimeoutMs` (default 10 s).
|
||||
4. **Backpressure** — outbound send queue per connection; drops oldest messages when full (with counter `ws.queue_drops_total`).
|
||||
5. **Topic-based pub/sub** — `connection.subscribe(topic)` / `gateway.publish(topic, msg)` fan-out.
|
||||
6. **Benchmark suite** — measure message throughput and concurrent connection overhead.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
api/framework/websocket-gateway/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
constants/index.ts
|
||||
types/
|
||||
common.ts
|
||||
common.md
|
||||
errors/
|
||||
ws-errors.ts
|
||||
ws-errors.md
|
||||
ws-errors.test.ts
|
||||
index.ts
|
||||
core/
|
||||
gateway/
|
||||
gateway.ts
|
||||
gateway.md
|
||||
gateway.types.ts
|
||||
gateway.test.ts
|
||||
index.ts
|
||||
connection/
|
||||
connection.ts
|
||||
connection.md
|
||||
connection.test.ts
|
||||
index.ts
|
||||
router/
|
||||
ws-router.ts
|
||||
ws-router.md
|
||||
ws-router.test.ts
|
||||
index.ts
|
||||
heartbeat/
|
||||
heartbeat.ts
|
||||
heartbeat.md
|
||||
heartbeat.test.ts
|
||||
index.ts
|
||||
adapters/
|
||||
hono-ws-adapter/
|
||||
hono-ws-adapter.ts
|
||||
hono-ws-adapter.md
|
||||
hono-ws-adapter.test.ts
|
||||
index.ts
|
||||
__benchmarks__/
|
||||
ws-gateway.bench.ts
|
||||
tests/
|
||||
integration.test.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
Downstream: any real-time feature (notifications, live collaboration, chat). Prerequisites: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/logger`, `@suaveplan/events`, `@suaveplan/rate-limiter`, `@suaveplan/api`.
|
||||
Reference in New Issue
Block a user