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 app-generated non-proxy 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
• YARP-aligned match criteria for routed app features: Path, Hosts, Methods, and QueryParameters
• 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 app-generated non-proxy responses
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 apply to app-generated responses: static files, redirects, fallback exclusions, SPA fallback, and custom error pages. They do not apply to proxied responses; use YARP response transforms for proxy headers.
• 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 YARP-style route criteria

This applies to:

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

Supported match criteria:

• Path — ASP.NET route template syntax, e.g. /api/{**catch-all} or /docs/{slug}. Omit Path to match all paths.
• Hosts — endpoint-routing host patterns, e.g. example.com, *.example.com, example.com:8443.
• Methods — HTTP methods, e.g. GET, HEAD, POST.
• QueryParameters — YARP-style query parameter matchers with Exact, Contains, NotContains, Prefix, and Exists modes.

Example:

{
  "Match": {
    "Path": "/docs/{slug}",
    "Hosts": [ "example.com", "*.example.com" ],
    "Methods": [ "GET", "HEAD" ],
    "QueryParameters": [
      {
        "Name": "preview",
        "Values": [ "true" ],
        "Mode": "Exact"
      }
    ]
  }
}

Redirects[].Destination can reference route values captured from Match.Path:

{
  "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

Values must be rooted request paths such as /errors/not-found.html. 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
• Markdown/schema validation for the application README and config schema
• Manual Caddy comparison fixture covering redirects, rewrites, static files, SPA fallback, fallback exclusions, error pages, and rewrite-to-proxy behavior

[Copilot]

Pull request overview

Adds declarative routing/static-hosting features to the prebuilt YARP application so common frontend/static-site scenarios can be configured without custom code, alongside expanded docs, tests, and sample app layouts.

Changes:

• Adds configurable Headers, Redirects, Rewrites, NavigationFallback.Exclude, and ErrorPages features to the application pipeline.
• Updates the request pipeline and configuration model/schema to support those features and document their ordering/behavior.
• Expands application tests and adds realistic sample app configurations demonstrating the new scenarios.

Show a summary per file

File	Description
test/Application.Tests/wwwroot/server-error.html	Adds test asset for custom 5xx error-page scenarios.
test/Application.Tests/wwwroot/404.html	Adds test asset for custom 404 error-page scenarios.
test/Application.Tests/YarpAppConfigBinderTests.cs	Adds binder coverage for new config sections and defaults.
test/Application.Tests/SpaFallbackTests.cs	Adds integration tests for routing rules, headers, rewrites, redirects, exclusions, and error pages.
src/Application/yarp-config.schema.json	Extends JSON schema for new routing/static-host config sections.
src/Application/README.md	Documents pipeline order, matching rules, and new config features.
src/Application/Program.cs	Reorders pipeline and wires in rewrites, error pages, headers, redirects, and exclusions.
src/Application/Features/StaticHostHeadersFeature.cs	Implements header application for static-file and SPA-fallback responses.
src/Application/Features/StaticFilesFeature.cs	Preserves static-file precedence when routing executes earlier.
src/Application/Features/RewritesFeature.cs	Adds rewrite-middleware integration from config.
src/Application/Features/RequestMatchEvaluator.cs	Adds shared route-template matching and destination expansion helpers.
src/Application/Features/RedirectsFeature.cs	Adds redirect endpoints with configurable status/destination behavior.
src/Application/Features/NavigationFallbackFeature.cs	Tags SPA fallback endpoint with custom metadata.
src/Application/Features/NavigationFallbackExclusionsFeature.cs	Adds routed 404 exclusions ahead of SPA fallback.
src/Application/Features/NavigationFallbackEndpointMetadata.cs	Defines marker metadata for fallback-specific behavior.
src/Application/Features/ErrorPagesFeature.cs	Adds status-code-based re-execution for custom error pages.
src/Application/Configuration/YarpAppConfigBinder.cs	Binds new config sections into the object model.
src/Application/Configuration/YarpAppConfig.cs	Adds new top-level config properties.
src/Application/Configuration/RewriteRule.cs	Adds config model for rewrite rules.
src/Application/Configuration/RequestMatch.cs	Adds shared path-match config model.
src/Application/Configuration/RedirectRule.cs	Adds config model for redirect rules.
src/Application/Configuration/NavigationFallbackOptions.cs	Adds fallback exclusion list to config.
src/Application/Configuration/HeaderRule.cs	Adds config model for static-host header rules.
samples/YarpApplication.SampleApps/README.md	Documents how to run the new sample app layouts.
samples/YarpApplication.SampleApps/05-edge-composition/wwwroot/index.html	Sample edge frontend landing page.
samples/YarpApplication.SampleApps/05-edge-composition/wwwroot/errors/server-error.html	Sample branded 5xx error page.
samples/YarpApplication.SampleApps/05-edge-composition/wwwroot/errors/not-found.html	Sample branded 404 error page.
samples/YarpApplication.SampleApps/05-edge-composition/wwwroot/assets/app.css	Sample static asset for edge-composition app.
samples/YarpApplication.SampleApps/05-edge-composition/appsettings.json	Demonstrates combined rewrites, redirects, exclusions, proxying, headers, and error pages.
samples/YarpApplication.SampleApps/04-commerce-errors/wwwroot/index.html	Sample commerce homepage.
samples/YarpApplication.SampleApps/04-commerce-errors/wwwroot/errors/server-error.html	Sample wildcard 5xx page.
samples/YarpApplication.SampleApps/04-commerce-errors/wwwroot/errors/not-found.html	Sample 404 page.
samples/YarpApplication.SampleApps/04-commerce-errors/wwwroot/errors/maintenance.html	Sample exact 503 page.
samples/YarpApplication.SampleApps/04-commerce-errors/appsettings.json	Demonstrates exact/wildcard error-page behavior with proxied checkout routes.
samples/YarpApplication.SampleApps/03-dashboard-spa/wwwroot/index.html	Sample SPA shell.
samples/YarpApplication.SampleApps/03-dashboard-spa/wwwroot/assets/site.css	Sample dashboard asset.
samples/YarpApplication.SampleApps/03-dashboard-spa/appsettings.json	Demonstrates SPA fallback exclusions plus proxy/API composition.
samples/YarpApplication.SampleApps/02-docs-site/wwwroot/index.html	Sample docs landing page.
samples/YarpApplication.SampleApps/02-docs-site/wwwroot/docs/v2/intro.html	Sample rewritten docs target.
samples/YarpApplication.SampleApps/02-docs-site/wwwroot/docs/intro.html	Sample redirect destination page.
samples/YarpApplication.SampleApps/02-docs-site/appsettings.json	Demonstrates redirects, rewrites, and docs-specific headers.
samples/YarpApplication.SampleApps/01-marketing-site/wwwroot/index.html	Sample marketing-site shell.
samples/YarpApplication.SampleApps/01-marketing-site/wwwroot/assets/site.css	Sample marketing asset.
samples/YarpApplication.SampleApps/01-marketing-site/appsettings.json	Demonstrates static hosting, fallback, and header rules.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 44/44 changed files
• Comments generated: 2