Add routing rules to the YARP application

[davidfowl]

Summary

Adds routing-rule features to the YARP application static-hosting experience so the pre-built app can cover common static site, SPA, edge frontend, and simple reverse-proxy composition scenarios without writing code.

This includes:

• Headers[] for static-host responses
• Redirects[] as routed short-circuit endpoints
• NavigationFallback.Exclude[] for paths that should not fall back to the SPA shell
• Rewrites[] using the ASP.NET Core rewrite middleware syntax
• ErrorPages for custom exact-code and Nxx wildcard error pages
• documentation for the request pipeline mental model
• realistic sample app configs under samples/YarpApplication.SampleApps

Mental model

The app is composed as a small request pipeline. Each feature has a clear position and responsibility:

1. Rewrites             mutate request path before routing
2. ErrorPages           wrap downstream 4xx/5xx responses and re-execute custom pages
3. Routing              select endpoints
4. Redirects            routed endpoints that short-circuit
5. Static files         serve existing files before proxy/fallback endpoints
6. Headers              mutate static-host responses only
7. Reverse proxy        proxy matched backend routes
8. Fallback exclusions  routed 404 endpoints for excluded SPA paths
9. SPA fallback         serve NavigationFallback.Path for remaining non-file routes

Important consequences:

• Rewrites run first, so every downstream feature sees the rewritten path.
• Redirects are endpoints, so they participate in routing and win before static/proxy/fallback behavior.
• Static files are special: the app preserves their historical precedence even though routing runs earlier, so existing files still win over catch-all proxy/fallback endpoints.
• Headers are static-host-only: they apply to static files and SPA fallback responses, but not proxied responses.
• Fallback exclusions are endpoint-routed 404s, which means excluded paths still compose with routing and error pages.
• Error pages wrap downstream behavior and re-execute the configured page while preserving the original status code.

Matching model

There are two intentional matching syntaxes.

Routed features use ASP.NET route templates

This applies to:

• Headers[].Match.Path
• Redirects[].Match.Path
• NavigationFallback.Exclude[].Path

Examples:

{ "Path": "/api/{**catch-all}" }
{ "Path": "/docs/{slug}" }

Redirects[].Destination can reference route values captured from the match:

{
  "Match": { "Path": "/docs/{**slug}" },
  "Destination": "/articles/{slug}",
  "StatusCode": 301
}

Rewrites use ASP.NET Core rewrite middleware syntax

No new rewrite DSL is invented. Rewrites use regex + replacement capture groups:

{
  "Regex": "^legacy/(.*)$",
  "Replacement": "api/$1"
}

SkipRemainingRules defaults to true, matching “first rewrite wins” behavior.

Error pages

ErrorPages maps status codes to custom pages:

{
  "ErrorPages": {
    "404": "/errors/not-found.html",
    "5xx": "/errors/server-error.html"
  }
}

Rules support:

• exact codes: "404", "503"
• class wildcards: "4xx", "5xx"
• exact code wins over wildcard

The implementation re-executes the request against the configured page, clears/resets response state so routed/proxied targets can run, and preserves the original HTTP status code before the response is sent.

Samples

Adds five config/static-file sample apps:

Sample	Demonstrates
01-marketing-site	Static site, SPA-style fallback, cache/security headers
02-docs-site	Legacy redirects, current-version rewrites, docs headers
03-dashboard-spa	SPA fallback plus /api proxy exclusion
04-commerce-errors	Branded exact and wildcard error pages
05-edge-composition	Rewrites, redirects, static assets, proxying, fallback exclusions, and error pages together

These are intentionally not .NET apps; they are realistic appsettings.json + wwwroot layouts for the YARP application.

Validation

• dotnet test test/Application.Tests/Yarp.Application.Tests.csproj
• Manual smoke of each sample config to confirm the app starts and representative routes work
• Code review pass found no significant issues