38 lines
2.7 KiB
Markdown
38 lines
2.7 KiB
Markdown
# 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
|