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

2.9 KiB
Raw Blame History

Configurable Route Table - Reverse Proxy

Module

Gateway

Status

VERIFIED

Description

The Gateway supports a ReverseProxy route type that forwards HTTP requests to an upstream service. Configured via StellaOpsRoute with Type = ReverseProxy, Path = URL prefix, TranslatesTo = upstream base URL. Features: prefix stripping (for non-regex routes), header forwarding (excluding hop-by-hop), upstream status code passthrough, custom header injection via Headers dictionary, regex-based path matching (IsRegex = true), timeout handling (returns 504), and connection error handling (returns 502).

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.ReverseProxy
    • StellaOpsRouteResolver (src/Router/StellaOps.Gateway.WebService/Routing/StellaOpsRouteResolver.cs) - Supports both prefix and regex matching for proxy routes
    • RouteDispatchMiddleware (src/Router/StellaOps.Gateway.WebService/Middleware/RouteDispatchMiddleware.cs) - HandleReverseProxy method using IHttpClientFactory, strips prefix, forwards headers, streams response
    • GatewayOptionsValidator (src/Router/StellaOps.Gateway.WebService/Configuration/GatewayOptionsValidator.cs) - Validates ReverseProxy route has valid HTTP(S) URL in TranslatesTo
  • Tests:
    • RouteTableIntegrationTests (src/Router/__Tests/StellaOps.Gateway.WebService.Tests/Integration/RouteTableIntegrationTests.cs) - 7 ReverseProxy integration tests
    • GatewayOptionsValidatorTests (src/Router/__Tests/StellaOps.Gateway.WebService.Tests/Configuration/GatewayOptionsValidatorTests.cs) - ReverseProxy URL validation tests

E2E Test Plan

  • Forward request to upstream: GET /proxy/echo returns proxied response from upstream with 200
  • Strip path prefix: GET /proxy/sub/path forwards as /sub/path to upstream
  • Forward request headers: custom headers (e.g., X-Test-Header) are forwarded to upstream
  • Pass through upstream status codes: 201, 400, 500 are returned as-is
  • Inject configured headers: route with Headers["X-Custom-Route"] = "injected-value" injects that header into upstream request
  • Regex path matching: route with IsRegex = true and pattern ^/api/v[0-9]+/.* matches GET /api/v2/data
  • Timeout handling: upstream timeout returns 504 Gateway Timeout

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-reverse-proxy/run-001/tier2-api-check.json
  • Verdict: PASS