# Configurable Route Table - WebSocket Proxy

## Module
Gateway

## Status
VERIFIED

## Description
The Gateway supports a `WebSocket` route type that accepts WebSocket upgrade requests and proxies them bidirectionally to an upstream WebSocket server. Configured via `StellaOpsRoute` with `Type = WebSocket`, `Path` = URL prefix, `TranslatesTo` = upstream WebSocket URL (ws:// or wss://). The middleware accepts the client WebSocket, opens a `ClientWebSocket` connection to the upstream, and pumps messages in both directions. Supports text messages, binary messages, and close frame propagation.

## Implementation Details
- **Modules**: `src/Router/__Libraries/StellaOps.Router.Gateway/`, `src/Router/StellaOps.Gateway.WebService/`
- **Key Classes**:
  - `StellaOpsRoute` (`src/Router/__Libraries/StellaOps.Router.Gateway/Configuration/StellaOpsRoute.cs`) - Route model with `StellaOpsRouteType.WebSocket`
  - `StellaOpsRouteResolver` (`src/Router/StellaOps.Gateway.WebService/Routing/StellaOpsRouteResolver.cs`) - Resolves WebSocket routes by path prefix
  - `RouteDispatchMiddleware` (`src/Router/StellaOps.Gateway.WebService/Middleware/RouteDispatchMiddleware.cs`) - `HandleWebSocket` method: accepts client WS, connects upstream `ClientWebSocket`, bidirectional pump loop
  - `GatewayOptionsValidator` (`src/Router/StellaOps.Gateway.WebService/Configuration/GatewayOptionsValidator.cs`) - Validates WebSocket route has valid ws:// or wss:// URL in TranslatesTo
  - `Program.cs` (`src/Router/StellaOps.Gateway.WebService/Program.cs`) - Registers `app.UseWebSockets()` in the pipeline
- **Tests**:
  - `RouteTableIntegrationTests` (`src/Router/__Tests/StellaOps.Gateway.WebService.Tests/Integration/RouteTableIntegrationTests.cs`) - 4 WebSocket integration tests
  - `GatewayOptionsValidatorTests` (`src/Router/__Tests/StellaOps.Gateway.WebService.Tests/Configuration/GatewayOptionsValidatorTests.cs`) - WebSocket URL validation tests

## E2E Test Plan
- [ ] WebSocket upgrade succeeds: connect to `ws://host/ws/echo` and verify state is Open
- [ ] Text message round-trip: send "Hello WebSocket" text message, receive same text echo back
- [ ] Binary message round-trip: send binary payload `[0x01, 0x02, 0x03, 0xFF]`, receive identical binary echo
- [ ] Close handshake: send close frame with NormalClosure, verify connection state becomes Closed

## Verification
- **Run ID**: run-001
- **Date**: 2026-02-12
- **Method**: Tier 0 source verification + Tier 1 build/code review (224/224 tests pass) + Tier 2a live HTTP API testing
- **Build**: PASS (0 errors, 0 warnings)
- **Tests**: PASS (224/224 Gateway tests pass)
- **Tier 2a Evidence**: `docs/qa/feature-checks/runs/gateway/configurable-route-table-websocket-proxy/run-001/tier2-api-check.json`
- **Verdict**: PASS