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-static-files-serving.md
master 9911b7d73c save checkpoint
2026-02-12 21:02:43 +02:00

2.9 KiB
Raw Permalink Blame History

Configurable Route Table - Static Files Serving

Module

Gateway

Status

VERIFIED

Description

The Gateway supports a StaticFiles route type that serves directory contents mapped to a URL prefix. Configured via StellaOpsRoute with Type = StaticFiles, Path = URL prefix, TranslatesTo = physical directory path. Supports SPA fallback (serving index.html for extensionless paths) when the route's Headers["x-spa-fallback"] is set to "true". Files are served with correct MIME types via FileExtensionContentTypeProvider. Multiple StaticFiles routes can coexist with isolated path scopes.

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.StaticFiles
    • StellaOpsRouteResolver (src/Router/StellaOps.Gateway.WebService/Routing/StellaOpsRouteResolver.cs) - First-match-wins route resolution engine
    • RouteDispatchMiddleware (src/Router/StellaOps.Gateway.WebService/Middleware/RouteDispatchMiddleware.cs) - HandleStaticFiles method uses PhysicalFileProvider and FileExtensionContentTypeProvider
    • GatewayOptionsValidator (src/Router/StellaOps.Gateway.WebService/Configuration/GatewayOptionsValidator.cs) - Validates StaticFiles route has non-empty TranslatesTo directory path
  • Tests:
    • RouteTableIntegrationTests (src/Router/__Tests/StellaOps.Gateway.WebService.Tests/Integration/RouteTableIntegrationTests.cs) - 8 StaticFiles integration tests
    • GatewayOptionsValidatorTests (src/Router/__Tests/StellaOps.Gateway.WebService.Tests/Configuration/GatewayOptionsValidatorTests.cs) - StaticFiles validation tests

E2E Test Plan

  • Serve a file from a mapped directory: GET /app/index.html returns HTML content with 200 and Content-Type: text/html
  • Serve a nested file: GET /app/assets/style.css returns CSS content with 200 and Content-Type: text/css
  • Return 404 for missing file: GET /app/missing.txt returns 404
  • Verify MIME types: .html -> text/html, .css -> text/css, .js -> application/javascript, .json -> application/json
  • SPA fallback: GET /app/some/route (extensionless) returns index.html when x-spa-fallback=true
  • Multiple mappings isolation: /app/ and /docs/ serve from different directories without interference

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