Initial Commit

openspec/archive/2026-05-12-enterprise-network-websockets/tasks.md

@@ -0,0 +1,86 @@
+# Tasks: enterprise-network-websockets
+
+**Change ID**: enterprise-network-websockets
+**Package**: `@suaveplan/network-websockets`
+**Target path**: `universal/network/network-websockets`
+**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/logger`, `@suaveplan/retry`, `@suaveplan/serialize`
+
+---
+
+## 1. Scaffold
+
+- [x] Create `universal/network/network-websockets/` with `src/`, `tests/`, and all feature subdirectories.
+- [x] Write `package.json` at version `0.1.0`: `"sideEffects": false`, exports map, deps per `proposal.md`.
+- [x] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`.
+- [x] Write `vitest.config.ts` using `createTestConfig()`.
+- [x] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check` scripts.
+
+---
+
+## 2. Types and error codes
+
+- [x] Define all public types in `src/types/common.ts`: `WebSocketClientOptions`, `WebSocketMessage`, `MessageMeta`, `ReconnectOptions`, `HeartbeatOptions`, `ConnectionState`, `ConnectionEvent`, `MessageHandler`, `WebSocketAdapter`, `WebSocketHandle`.
+- [x] Write `src/types/common.md` (≥200 words, simple + advanced examples).
+- [x] Define error codes in `src/error-codes.ts`: `NetworkWebsocketsErrorCode` union, metadata, `registerNetworkWebsocketsErrorCodes()`.
+- [x] Write Zod schemas in `src/types/schemas.ts` + `src/types/schemas.md`.
+
+---
+
+## 3. Message queue (`src/core/queue/`)
+
+- [x] Implement bounded `MessageQueue` (ring buffer, `maxQueueSize`).
+- [x] `enqueue(message)` — returns `false` and throws `NetworkWebsocketsError(WS_QUEUE_FULL)` when full.
+- [x] `dequeue()` / `drain()` — returns next message or all queued.
+- [x] Write `queue.test.ts` + `queue.md`.
+
+---
+
+## 4. Heartbeat (`src/core/heartbeat/`)
+
+- [x] Implement `HeartbeatManager`:
+  - On `start()`, send a `ping` frame on every `intervalMs` interval (injectable `Clock`).
+  - On `pong` received, reset timer.
+  - On `timeoutMs` exceeded without pong, emit `timeout` event.
+- [x] Write `heartbeat.test.ts` + `heartbeat.md`.
+
+---
+
+## 5. Native WebSocket adapter (`src/adapters/`)
+
+- [x] Implement `createNativeWebSocketAdapter()` — wraps `globalThis.WebSocket` (browser) or `Bun.WebSocket` (Bun server).
+- [x] Guard with platform check; throw `WS_CONNECTION_FAILED` if WebSocket not available.
+- [x] Write `native-adapter.test.ts` (uses fake adapter from `@suaveplan/network-testing` if available, else skipped) + `native-adapter.md`.
+
+---
+
+## 6. WebSocket client (`src/core/client/`)
+
+- [x] Implement `createWebSocketClient(options)`:
+  - Validates options with Zod.
+  - Uses `options.adapter ?? createNativeWebSocketAdapter()`.
+  - State machine: `disconnected → connecting → connected`; reconnect loop via `@suaveplan/retry`.
+- [x] Implement `client.connect(signal?)` — starts connection, heartbeat.
+- [x] Implement `client.disconnect(code?, reason?)` — graceful close.
+- [x] Implement `client.send(message, signal?)` — enqueues if not connected; drains queue on connect; serializes via `@suaveplan/serialize`.
+- [x] Implement `client.subscribe(channel, handler)` — routes incoming messages by `message.channel`; returns unsubscribe.
+- [x] Implement `client.on(event, handler)` — connection lifecycle events.
+- [x] OTel: span `ws.connect`, counters `ws.messages_sent_total`, `ws.messages_received_total`.
+- [x] Write `client.test.ts` (≤500 lines) using injectable fake adapter.
+- [x] Write `client.md` (≥200 words).
+
+---
+
+## 7. Property-based tests (`tests/property.test.ts`)
+
+- [x] Message queue invariants: `enqueue` count - `dequeue` count = current queue depth.
+- [x] Channel routing: messages with `channel: 'X'` are always routed to `channel: 'X'` subscribers only.
+
+---
+
+## 8. Docs and verify
+
+- [x] All per-file `.md` files per layout in `proposal.md`.
+- [x] `universal/network/network-websockets/README.md`.
+- [x] `bunx turbo lint typecheck test test:coverage --filter=@suaveplan/network-websockets` — all green, 100% coverage.
+- [x] `bun scripts/publish.ts --package @suaveplan/network-websockets`.
+- [x] Update `CLAUDE.md`. Archive change folder.