stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
main
git.stella-ops.org/docs/features/checked/gateway/configurable-route-table-websocket-proxy.md
master 9911b7d73c save checkpoint
2026-02-12 21:02:43 +02:00

2.7 KiB
Raw Permalink Blame History

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