@tonytomo/gosocket-client 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,98 @@
+# Changelog
+
+All notable changes to the Browser WebSocket Client SDK (`@ws-server/ws-client`) will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.0] - 2026-10-29
+
+### Added — JS SDK Phase J4 (Final Phase)
+
+- **Error Classification & Recovery Policy (PROTOCOL.md §4.7)**:
+  - 18-row classification table mapping every protocol `ErrorCode` to SDK recovery actions (`fatal`, `drop_intent`, `app_prompt`, `retry_backoff`, `ignore`).
+  - Pure `classifyError(code, frame?, overrides?)` function supporting caller overrides via `ClientConfig.errorPolicy`.
+  - `errorClassified` event emitted immediately before raw `error` frames with code, action, retry delay, and optional raw frame.
+  - `AUTH_FAILED` ↔ `UNAUTHORIZED` unification: browser auth heuristic emits `errorClassified { code: 'UNAUTHORIZED', action: 'fatal' }` before emitting `fatal { code: 'AUTH_FAILED' }`.
+- **Round-Trip Latency (RTT) Tracking & Ping API**:
+  - `client.ping(timeoutMs?)`: Explicit on-demand ping returning measured round-trip time in milliseconds, serialized to prevent interleaving.
+  - `client.rttStats()`: Latency summary (`last`, `min`, `max`, `mean` via exponential moving average $\alpha = 0.2$, `samples`), reset on every reconnect cycle and client close.
+  - Passive heartbeat RTT sampling enabled by default (opt-out via `heartbeat: { trackRtt: false }`).
+  - `rtt` event emitted with `{ sample, source: 'heartbeat' | 'on_demand', stats }`.
+- **Local Pre-Send Validation (PROTOCOL.md §§3.1, 3.6)**:
+  - Strict validation of room names (`^[a-zA-Z0-9_-]{1,64}$`) and channel names (`^[a-zA-Z0-9_-]{1,32}$`).
+  - Rejection of reserved `'presence'` channel name for outbound message publishing.
+  - Maximum text payload limit (`maxTextPayloadBytes: 65024`, reserving 512 bytes for message envelope).
+  - Maximum binary payload limit (`maxBinaryPayloadBytes: 65535`).
+  - Client-side validation throwing `ValidationError` with field, rule, limit, and truncated value.
+  - Escape hatches: `validation: { enabled: false }` or direct `client.send(frame)` bypassing local validation to test raw wire frames.
+- **Capability-Driven Pre-Flight Checks (PROTOCOL.md §8)**:
+  - Synchronous pre-flight checks in `createRoom()` against advertised `welcome.capabilities.limits`:
+    - `max_metadata_bytes`: JSON-encoded byte size check.
+    - `max_channels_per_room`: effective channel count check including `'presence'`, room preset channels, and custom channels.
+    - `max_rooms_per_key`: tracks owned rooms created on current connection, rejecting creation exceeding server limits before sending frames.
+  - Rejections throw `CapabilityLimitError` locally without sending wire frames or emitting `errorClassified`.
+- **Live Conformance Suite & CI Runner**:
+  - Live conformance suite running in Vitest against real server binaries in `test/live/` with `ws` Node polyfill.
+  - Conformance test runner `scripts/live-conformance-js.sh` orchestrating primary (18080), binary-disabled (18081), and policy-violation (18082) server instances.
+  - GitHub Actions CI workflow running JS unit tests and live conformance suite.
+
+## [0.3.0] - 2026-10-29
+
+### Added — JS SDK Phase J3
+
+- **Binary Channels (PROTOCOL.md §7)**:
+  - `BinaryMapBuilder` and `validateBinaryMap` ensuring channel IDs are integers in $[1, 254]$, rejecting reserved names (`""`, `"presence"`) and duplicate IDs/channels with construction-time validation.
+  - Global binary-ID uniqueness across rooms on a single connection (`binaryOwner` registry) with proactive pre-wire collision checks and `binaryIdCollision` event dispatch.
+  - Transactional reservation rollback when server join requests fail or reject.
+  - Inbound binary frame parsing using `ws.binaryType = 'arraybuffer'`, decoding 1-byte channel prefix and dispatching `binaryMessage` or `binaryUnknownChannel`.
+  - Binary publishing via `publishBinary` routing through reliable/unreliable lanes, shared token-bucket rate limiting, server backoff, and frame-type-distinct coalescing slots (`${room}:${channel}:binary`).
+- **Presence Cache (PROTOCOL.md §6)**:
+  - Local cached roster tracking with typed events: `presenceJoin`, `presenceLeave`, `presenceInvalidated`, `roomDeleted`.
+  - Self-exclusion filtering in `knownMembers(room)` and `selfLabel` connection tracking from welcome frames.
+  - Server count tracking in `lastServerMemberCount(room)`.
+  - Protocol violation detection (`self presence event`, `unknown presence event`, `presence event missing who`, `malformed presence payload`, `empty binary frame`, `binary frame on presence channel`).
+  - Automatic reconnection invalidation marking presence caches stale (`invalidReason: 'reconnected'`) and requiring explicit `resetPresence(room)` to clear.
+- **Sequence-Gap Detection (PROTOCOL.md §5.6)**:
+  - Per-`(room, channel)` monotonic sequence number tracking across text message frames.
+  - Forward sequence gap detection emitting `sequenceGap` with `prev`, `current`, `missed`, and `reliable` lane flag.
+  - Silent re-baselining on reconnection, backward sequences (e.g. room re-creation), duplicate sequences, and sequence 0.
+  - Optional `autoInvalidateOnReliableGap` configuration invalidating room presence caches when a sequence gap occurs on the reliable `presence` channel.
+- **Delete Room Ackless Semantics**:
+  - `deleteRoom` resolves cleanly on incoming `room_deleted` presence frames with caller identification, removing room intents and executing complete state cleanup via `clearRoomState(room)`.
+- **Comprehensive Cleanup Hooks (`clearRoomState`)**:
+  - Centralized eviction of binary owners, presence states, sequence states, rate limiters, coalescing slots, and applied policies upon room leave, delete, or session restore drop.
+- **New Events & Errors**:
+  - Events: `binaryMessage`, `binaryUnknownChannel`, `binaryIdCollision`, `binaryMappingChanged`, `presenceJoin`, `presenceLeave`, `presenceInvalidated`, `roomDeleted`, `sequenceGap`, `protocolViolation`.
+  - Errors: `BinaryMapValidationError`, `BinaryMapExhaustedError`, `BinaryIdCollisionError`, `BinaryChannelUnmappedError`, `BinaryPayloadTooLargeError`.
+
+## [0.2.0] - 2026-10-29
+
+### Added — JS SDK Phase J2
+
+- **Two-Lane Outbound Pipeline**: Reliable lane (bounded FIFO, drop-newest or close on overflow) and Unreliable lane (bounded FIFO, drop-oldest) matching server delivery semantics in PROTOCOL.md §5.4.
+- **Channel Policy System**: `ChannelPolicy`, `PolicyProvider`, and `presetsFor(kind, overrides)` reproducing PROTOCOL.md §5.2 room presets for `chat`, `game`, and `custom` room templates.
+- **Client-Side Token Bucket Rate Limiting**: Per `(room, channel)` limiters enforcing `rate = maxRate` and `burst = max(2, maxRate * 2)` to cooperatively preempt server rate violations.
+- **Inbound RATE_LIMITED Backoff Correlation**: Reader pauses local publishing on channels receiving server `RATE_LIMITED` frames, inferring target rooms from recent publish tracking.
+- **Message Coalescing**: Outbound state coalescing on unreliable channels with `'timer'` and browser-native `'raf'` (`requestAnimationFrame`) drivers and customizable `merge` functions.
+- **Writer Loop Scheduler**: Single async event loop writer pump with burst draining (reliable 32, unreliable 8) and microtask yields (`await Promise.resolve()`) per frame to avoid blocking UI rendering.
+- **Transport Backpressure Management**: Cooperative monitoring of `WebSocket.bufferedAmount` with high ($1 \text{ MiB}$) and low ($512 \text{ KiB}$) watermarks and hysteresis, pausing unreliable flushes under saturation.
+- **Generation-Scoped Queues**: Outbound queues discard pending frames on reconnect to prevent stale message delivery contradicting restored room states, emitting `queuesDiscarded` before session restore begins.
+- **Public API Additions**: Added `publish(req)`, `setChannelPolicy(room, channel, policy)`, `queueDepth()`, `bufferedAmount()`, and test seam `__flushNow()`.
+- **New Events & Errors**: Added events (`rateLimited`, `reliableOverflow`, `unreliableDropped`, `coalesced`, `queuesDiscarded`, `backpressure`, `policyApplied`) and errors (`NotReadyError`, `ChannelNotReliableError`, `RateLimitedError`).
+
+## [0.1.0] - 2026-10-29
+
+### Added — JS SDK Phase J1
+
+- **Connection Lifecycle State Machine**: Full lifecycle management covering `idle`, `connecting`, `awaiting_welcome`, `ready`, `reconnecting`, and `closed` states with typed event notifications.
+- **Browser-Native Authentication**: Query parameter authentication (`?key=...`) with mandatory key redaction in logs and error frames.
+- **401 Detection Heuristic**: Intelligent classification of browser-masked abnormal close (`1006`) errors into `AUTH_FAILED` fatal halts versus retryable network failures, supporting `'heuristic'`, `'never-fatal'`, and `'always-fatal'` modes alongside an `onAmbiguousAuth` callback.
+- **Exponential Reconnection**: Full-jitter, equal-jitter, and non-jitter exponential backoff with configurable base delays, maximum ceilings, retry ceilings, and `shouldReconnect` overrides.
+- **Serialized Session Restore**: Automatic rejoining of active room memberships upon reconnection in alphabetical room order, handling `ROOM_NOT_FOUND`, `FORBIDDEN_SCOPE`, `INVALID_PASSCODE`, `ROOM_FULL` (with `'drop'` and `'retry'` policies), and per-room deadlines.
+- **Heartbeat Management**: Application-level ping/pong liveness verification with configurable intervals and timeouts, forcing connection resets on missed deadlines.
+- **Capabilities Discovery**: Caching of server `welcome.capabilities` preserving S2 `null`-means-disabled semantics and emitting `capabilitiesChanged` on server version or capacity upgrades.
+- **Core Protocol API**: Async convenience wrappers for `createRoom`, `joinRoom`, `leaveRoom`, `deleteRoom`, `listRooms`, and low-level `send`.
+- **Error Hierarchy**: ES2022 error taxonomy rooted at `SdkError`, including `AuthError`, `ConnectError`, `PolicyViolationError`, `RequestTimeoutError`, `ConcurrentRequestError`, and `ServerError`.
+- **Transport & Clock Abstractions**: Dependency-injected `Transport` and `Clock` interfaces powering deterministic zero-wall-clock test suites with 100% fake-timer execution.
+

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tony Tomo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.