natsnet/docs/plans/2026-02-27-batch-26-websocket-design.md

# Batch 26 (WebSocket) Design

## Context Snapshot

- Batch: `26 - WebSocket`
- Scope: `37 features`, `86 tests`
- Dependencies: `16 (Client Core first half)`, `18 (Server Core)`
- Go source: `golang/nats-server/server/websocket.go` (+ `websocket_test.go` for tests)
- Current state:
  - Batch status is `pending`.
  - Batch is **not ready** (`batch ready` currently lists only batches 0, 1, 5, 8).
  - .NET websocket code is largely stubbed in `dotnet/src/ZB.MOM.NatsNet.Server/WebSocket/WebSocketTypes.cs`.
  - Multiple websocket-related stubs exist outside the websocket folder (`ClientConnection`, `NatsServer.Lifecycle`, `NatsServer.Listeners`).

## Goals

1. Port all 37 Batch 26 websocket features from `server/websocket.go` with behaviorally equivalent logic.
2. Port and verify all 86 Batch 26 mapped tests with no fake/stub assertions.
3. Remove websocket-specific stubs (`NotImplementedException`, placeholder comments, always-false flags) in runtime paths touched by this batch.
4. Keep implementation idiomatic C# while preserving protocol correctness (frame parsing, masking, compression, upgrade validation, close/status handling).

## Non-Goals

1. Rewriting unrelated subsystems (MQTT, full leaf routing internals, non-websocket JetStream internals).
2. Performance tuning beyond parity with Go logic and existing .NET architecture.
3. Advancing blocked dependencies (Batches 16/18) inside this batch plan.

## Approaches Considered

### Approach A: Monolithic Port in `WebSocketTypes.cs`

- Description: Implement all websocket behavior inside the existing single file.
- Pros: Minimal file churn.
- Cons: Hard to review/test, encourages oversized methods, mixes protocol codec, HTTP upgrade, and server lifecycle logic in one place.

### Approach B (Recommended): Split by Concern with Partial Integration

- Description: Keep websocket-focused primitives in `WebSocket/` and wire server/client integration through partial class methods in `NatsServer` and `ClientConnection`.
- Pros: Clear boundaries, easier per-feature verification, easier targeted tests, aligns with existing partial-class architecture in `NatsServer`.
- Cons: More file edits and some type movement from current stubs.

### Approach C: Rely on `System.Net.WebSockets` High-Level Abstractions

- Description: Use framework websocket APIs for framing/handshake and adapt behavior.
- Pros: Less low-level frame code.
- Cons: Poor fit for NATS semantics (manual handshake headers, no-masking extension, explicit frame control, compression toggles, client/leaf modes). Higher behavior drift risk vs Go.

## Recommended Design (Approach B)

### 1) Component Boundaries

1. Frame/read-path primitives:
   - `WsReadInfo` state machine (`init`, `Read`, `ReadByte`, `NextCBuf`, `Decompress`, `Unmask`).
   - Static helpers for `WsGet`, `WsIsControlFrame`, frame-header creation/fill, masking utilities, close payload creation.
2. Client websocket behavior:
   - `ClientConnection` websocket methods (`WsRead`, control frame handling/enqueue, close mapping, outbound collapse).
   - `IsWebSocket()` no longer hardcoded false once websocket state exists on connection.
3. HTTP upgrade + option validation:
   - Handshake validation and response (`WsUpgrade`, header checks, accept key, compression negotiation, origin checks).
   - Options parsing/validation (`ValidateWebsocketOptions`, origin/header settings, auth override).
4. Server lifecycle/listener integration:
   - Start/close websocket listener and include it in readiness checks.
   - Keep server INFO websocket connect URLs updated and propagated.

### 2) Data Flow

1. Upgrade flow:
   - HTTP request validation -> origin check -> extension negotiation -> connection hijack -> 101 response -> websocket context creation.
2. Inbound frame flow:
   - Header decode -> mask enforcement -> payload size handling -> optional control-frame handling -> optional decompression -> payload slices returned for parser.
3. Outbound frame flow:
   - Pending buffers -> optional compression -> fragmentation rules (browser/safari constraints) -> optional masking -> queued frames + close frame semantics.

### 3) Error Handling Model

1. Protocol violations map to websocket close frames with RFC status codes, then close/read termination behavior.
2. Handshake failures return HTTP status + server-side error logging.
3. Decompression limit violations map to payload errors (max payload).
4. Any runtime branch that cannot be implemented due dependency/runtime gap is marked `deferred` with explicit reason, never stubbed.

### 4) File-Level Plan

Likely touched files:

- Source:
  - `dotnet/src/ZB.MOM.NatsNet.Server/WebSocket/WebSocketTypes.cs` (replace stubs/split responsibilities)
  - `dotnet/src/ZB.MOM.NatsNet.Server/WebSocket/WebSocketConstants.cs`
  - `dotnet/src/ZB.MOM.NatsNet.Server/ClientConnection.cs`
  - `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Listeners.cs`
  - `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Lifecycle.cs`
  - `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Init.cs`
  - `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.cs`
- Tests:
  - `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/WebSocketHandlerTests.Impltests.cs`
  - `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamFileStoreTests.Impltests.cs`
  - `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/NatsConsumerTests.Impltests.cs`
  - `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/LeafNodeHandlerTests.Impltests.cs`
  - `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests1.Impltests.cs`
  - `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests2.Impltests.cs`
  - New backlog classes likely required by mapping:
    - `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/CoreBenchmarks.Impltests.cs`
    - `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/PublishBenchmarks.Impltests.cs`
    - `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/LeafNodeProxyTests.Impltests.cs`

### 5) Test Strategy

1. Use strict ID-driven mapping from PortTracker for all 86 tests.
2. For websocket functional tests, port assertions against frame semantics, handshake negotiation, header behavior, compression behavior, and outbound framing.
3. For benchmark-mapped test IDs:
   - If deterministic behavioral assertions can be extracted, port as regular unit tests.
   - If benchmark-only and non-deterministic/perf-only, mark `n_a` or `deferred` with explicit reason and evidence.
4. Add anti-stub checks to prevent placeholder tests passing as real.

### 6) Risks and Mitigations

1. Risk: Dependency batches 16/18 incomplete.
   - Mitigation: strict preflight gate, do not start batch until dependencies are complete.
2. Risk: Silent stub regressions in broad ImplBacklog files.
   - Mitigation: mandatory grep-based stub scans and per-ID evidence before status updates.
3. Risk: Frame/compression edge-case mismatch.
   - Mitigation: prioritize low-level frame tests first, then server/upgrade paths.
4. Risk: Benchmarks misclassified as verified tests.
   - Mitigation: explicit benchmark decision gate (real deterministic test vs `n_a`/`deferred` with reason).

## Design Decision

Proceed with **Approach B** (split-by-concern websocket port with partial integration into `NatsServer`/`ClientConnection`), executed via a strict verification-first implementation plan.