save checkpoint

docs/features/checked/gateway/configurable-route-table-error-page-fallback.md

@@ -0,0 +1,36 @@
+# 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