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

2.8 KiB
Raw Blame History

Configurable Route Table - Error Page Fallback (404/500)

Module

Gateway

Status

VERIFIED

Description

The Gateway supports NotFoundPage and ServerErrorPage route types that serve custom HTML error pages for 404 and 500+ responses respectively. Configured via StellaOpsRoute with Type = NotFoundPage or Type = ServerErrorPage, TranslatesTo = path to an HTML file on disk. When any route in the pipeline produces a 404 or 500+ response with an empty body, the ErrorPageFallbackMiddleware intercepts and serves the configured HTML page. Includes a fast-path optimization that skips response body buffering entirely when no error pages are configured. Falls back to a JSON error response when the configured error page file is missing.

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.NotFoundPage and StellaOpsRouteType.ServerErrorPage
    • ErrorPageFallbackMiddleware (src/Router/StellaOps.Gateway.WebService/Middleware/ErrorPageFallbackMiddleware.cs) - Intercepts 404/500 responses, serves configured HTML pages, fast-path for no-error-page config
    • GatewayOptionsValidator (src/Router/StellaOps.Gateway.WebService/Configuration/GatewayOptionsValidator.cs) - Validates error page routes have non-empty TranslatesTo file paths
    • Program.cs (src/Router/StellaOps.Gateway.WebService/Program.cs) - Registers error routes in DI and ErrorPageFallbackMiddleware at end of pipeline
  • Tests:
    • RouteTableIntegrationTests (src/Router/__Tests/StellaOps.Gateway.WebService.Tests/Integration/RouteTableIntegrationTests.cs) - Error page behavior verified through route resolution tests (unmatched paths return 404)

E2E Test Plan

  • Unmatched route returns 404 with custom HTML page: GET /unmatched/path returns 404 with Content-Type: text/html and custom page content
  • 404 response status code is preserved: response status is 404 (not 200)
  • 500 error page: trigger a 500 response and verify custom HTML page is served with Content-Type: text/html
  • Fast-path: when no error pages configured, responses pass through without buffering overhead
  • JSON fallback: when error page file is missing on disk, returns JSON error {"error":"not_found","status":404}

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