# 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