Proxy

Author: aritchie

Directory.Packages.props

@@ -14,6 +14,7 @@
         <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.10"/>
         <PackageVersion Include="Microsoft.Extensions.Logging.Console" Version="10.0.10"/>
         <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.10"/>
+        <PackageVersion Include="Microsoft.Extensions.Configuration.Abstractions" Version="10.0.10"/>
         <PackageVersion Include="Microsoft.Extensions.Configuration.CommandLine" Version="10.0.10"/>
         <PackageVersion Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.10"/>
         <PackageVersion Include="Microsoft.Extensions.Options" Version="10.0.10"/>

Shiny.Net.HttpServer.slnx

@@ -33,6 +33,7 @@
     <Project Path="src/Shiny.Net.HttpServer.Mediator/Shiny.Net.HttpServer.Mediator.csproj" />
     <Project Path="src/Shiny.Net.HttpServer.Mediator.SourceGenerators/Shiny.Net.HttpServer.Mediator.SourceGenerators.csproj" />
     <Project Path="src/Shiny.Net.HttpServer.Mobile/Shiny.Net.HttpServer.Mobile.csproj" />
+    <Project Path="src/Shiny.Net.HttpServer.Proxy/Shiny.Net.HttpServer.Proxy.csproj" />
     <Project Path="src/Shiny.Net.HttpServer.SourceGenerators/Shiny.Net.HttpServer.SourceGenerators.csproj" />
     <Project Path="src/Shiny.Net.HttpServer.Ssh/Shiny.Net.HttpServer.Ssh.csproj" />
     <Project Path="src/Shiny.Net.HttpServer.Testing/Shiny.Net.HttpServer.Testing.csproj" />

build.slnf

@@ -6,6 +6,7 @@
             "src\\Shiny.Net.HttpServer.Mobile\\Shiny.Net.HttpServer.Mobile.csproj",
             "src\\Shiny.Net.HttpServer.SourceGenerators\\Shiny.Net.HttpServer.SourceGenerators.csproj",
             "src\\Shiny.Net.HttpServer.Jwt\\Shiny.Net.HttpServer.Jwt.csproj",
+            "src\\Shiny.Net.HttpServer.Proxy\\Shiny.Net.HttpServer.Proxy.csproj",
             "src\\Shiny.Net.HttpServer.Grpc\\Shiny.Net.HttpServer.Grpc.csproj",
             "src\\Shiny.Net.HttpServer.AzureRelay\\Shiny.Net.HttpServer.AzureRelay.csproj",
             "src\\Shiny.Net.HttpServer.Mcp\\Shiny.Net.HttpServer.Mcp.csproj",

readme.md

@@ -19,6 +19,7 @@ JWT, OpenAPI, HPACK, QPACK — is built on what is in the box.
 | [Shiny.Net.HttpServer.Jwt](https://www.nuget.org/packages/Shiny.Net.HttpServer.Jwt) | JWT authentication on in-box crypto — no `Microsoft.IdentityModel` dependency |
 | [Shiny.Net.HttpServer.AzureRelay](https://www.nuget.org/packages/Shiny.Net.HttpServer.AzureRelay) | Azure Relay tunnel provider |
 | [Shiny.Net.HttpServer.Ssh](https://www.nuget.org/packages/Shiny.Net.HttpServer.Ssh) | SSH remote-forwarding tunnel provider, including zero-account quick tunnels |
+| [Shiny.Net.HttpServer.Proxy](https://www.nuget.org/packages/Shiny.Net.HttpServer.Proxy) | A reverse proxy — destination clusters, load balancing, active and passive health checks, session affinity, a transform pipeline, WebSocket and HTTP upgrade forwarding, and routes read from `IConfiguration` with hot reload |
 | [Shiny.Net.HttpServer.Mcp](https://www.nuget.org/packages/Shiny.Net.HttpServer.Mcp) | Model Context Protocol (Streamable HTTP) transport — host an MCP server without ASP.NET Core, including inside a MAUI app |
 | [Shiny.Net.HttpServer.Mediator](https://www.nuget.org/packages/Shiny.Net.HttpServer.Mediator) | Publishes Shiny.Mediator requests, commands and streams as endpoints generated at compile time. Generator included |
 | [Shiny.Net.HttpServer.DocumentDb](https://www.nuget.org/packages/Shiny.Net.HttpServer.DocumentDb) | Publishes a Shiny.DocumentDb type as a REST resource — list, by-id, count, CRUD, merge-patch and a live SSE tail |
@@ -130,7 +131,7 @@ is built on the one below and they compose in the same app.
 
 | | |
 | --- | --- |
-| **Core** | Routing with constraints and runtime-mutable routes, ASP.NET-shaped middleware that can read and rewrite both bodies of an exchange, a real `IServiceScope` per request, results in both `Results.*` and `IActionResult` spellings, RFC 9457 problem details and an exception-handler chain, per-endpoint request timeouts, and a reverse proxy route |
+| **Core** | Routing with constraints and runtime-mutable routes, ASP.NET-shaped middleware that can read and rewrite both bodies of an exchange, a real `IServiceScope` per request, results in both `Results.*` and `IActionResult` spellings, RFC 9457 problem details and an exception-handler chain, per-endpoint request timeouts |
 | **Caching** | Conditional requests for handlers that are not serving a file — `If-Match`, `If-None-Match`, `If-Modified-Since`, 304 and 412 — plus output caching with a bounded in-memory store, where the saving is battery rather than bandwidth |
 | **Diagnostics** | Health checks with liveness/readiness tags, telemetry on the in-box primitives — one `Activity` per request continuing the caller's `traceparent`, and the OpenTelemetry HTTP metrics an ASP.NET dashboard already reads — and W3C access logs, rolled and pruned, written off the request path |
 | **Formats** | Content negotiation in both directions — responses chosen from `Accept`, request bodies from `Content-Type`. JSON out of the box; XML, MessagePack and protobuf are one line each, and a format of your own is an `IOutputFormatter`/`IInputFormatter` pair. XML and MessagePack need no dependency and no attributes on your DTOs: they read the same `JsonTypeInfo` the JSON path reads, which is what keeps them AOT-clean where `XmlSerializer` cannot be |
@@ -140,6 +141,7 @@ is built on the one below and they compose in the same app.
 | **TLS** | Several endpoints with per-endpoint TLS, self-signed certificates generated in managed code (iOS and Android included), client certificates, and SPKI pinning for the app's own `HttpClient` |
 | **OpenAPI** | An OpenAPI 3.0.3 document built entirely from compile-time metadata and your `JsonSerializerContext` — no reflection, no document object model |
 | **Tunnelling** | A pluggable `ITunnelProvider`, the reference relay (both ends), SSH remote forwarding, zero-account quick tunnels, and Azure Relay |
+| **Proxy** | A reverse proxy that goes further than a forwarded route: destination clusters with five load-balancing policies, active probes and passive failure tracking that take a bad instance out of rotation, cookie or header session affinity, a composable transform pipeline for paths, queries and headers in both directions, WebSocket and HTTP upgrade forwarding, and routes read from `IConfiguration` and reloaded onto the running server without dropping the routes that did not change |
 | **Mediator** | Shiny.Mediator handlers published as endpoints — requests as JSON, commands as a status code, stream requests as Server-Sent Events, all bound at compile time |
 | **DocumentDb** | A document type as a complete HTTP resource, with filtering, cursor paging, sparse fieldsets, ETag/If-Match, RFC 7396 merge-patch, a live SSE tail, and server-side scopes enforced on both sides of a write |
 | **gRPC** | Unary, client-streaming, server-streaming and bidirectional methods, deadlines, per-message compression and status in trailers — plus gRPC-Web for browsers and anything on HTTP/1.1. Marshalling is yours, so nothing reflects over your messages |

skills/shiny-httpserver/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: shiny-httpserver
-description: Generate code using Shiny.Net.HttpServer — a dependency-light, AOT/trim-clean HTTP/1.1, HTTP/2 & HTTP/3 server that runs anywhere .NET runs, including .NET MAUI and native tvOS, where ASP.NET Core cannot. Covers routing, middleware, source-generated typed endpoints, results and JSON, content negotiation with XML/MessagePack/protobuf formatters in both directions, static files and Blazor WASM, uploads/downloads, WebSockets, SSE, sessions, OpenAPI, authentication (Basic/API key/cookie/JWT), authorization, CORS, rate limiting, IP filtering, TLS and self-signed certificates, tunnelling (relay, SSH, quick tunnels, Azure Relay, and supervised cloudflared/ngrok/tailscale agents), serving a directory over WebDAV, serving gRPC and gRPC-Web, hosting an MCP server with RFC 9728 OAuth discovery, health checks, OpenTelemetry-shaped metrics and tracing, W3C access logs, request timeouts, output caching and conditional requests, request decompression, antiforgery and browser security headers, reverse-proxy routes, mDNS/Bonjour advertising and discovery, MAUI lifecycle (background/foreground, Android foreground service, network rebinding), and an in-memory test harness.
+description: Generate code using Shiny.Net.HttpServer — a dependency-light, AOT/trim-clean HTTP/1.1, HTTP/2 & HTTP/3 server that runs anywhere .NET runs, including .NET MAUI and native tvOS, where ASP.NET Core cannot. Covers routing, middleware, source-generated typed endpoints, results and JSON, content negotiation with XML/MessagePack/protobuf formatters in both directions, static files and Blazor WASM, uploads/downloads, WebSockets, SSE, sessions, OpenAPI, authentication (Basic/API key/cookie/JWT), authorization, CORS, rate limiting, IP filtering, TLS and self-signed certificates, tunnelling (relay, SSH, quick tunnels, Azure Relay, and supervised cloudflared/ngrok/tailscale agents), serving a directory over WebDAV, serving gRPC and gRPC-Web, hosting an MCP server with RFC 9728 OAuth discovery, health checks, OpenTelemetry-shaped metrics and tracing, W3C access logs, request timeouts, output caching and conditional requests, request decompression, antiforgery and browser security headers, a reverse proxy with destination clusters, load balancing, health checks, session affinity, transforms, WebSocket forwarding and IConfiguration-driven routes, mDNS/Bonjour advertising and discovery, MAUI lifecycle (background/foreground, Android foreground service, network rebinding), and an in-memory test harness.
 auto_invoke: true
 triggers:
 - Shiny.Net.HttpServer
@@ -106,6 +106,23 @@ triggers:
 - ValidateAntiforgery
 - MapProxy
 - ProxyOptions
+- MapReverseProxy
+- AddReverseProxy
+- reverse proxy
+- YARP
+- ProxyCluster
+- ProxyDestination
+- LoadBalancingPolicy
+- ILoadBalancingPolicy
+- SessionAffinityMode
+- TransformBuilder
+- HttpForwarder
+- ReverseProxyRuntime
+- ReverseProxyConfiguration
+- ForwardUpgrades
+- load balancing
+- health checks for destinations
+- Shiny.Net.HttpServer.Proxy
 - AddHttpServerAdvertisement
 - IHttpServerAdvertiser
 - AddHttpServerLocator
@@ -296,6 +313,7 @@ must hold that line, or it fails on a trimmed device build.
 ```bash
 dotnet add package Shiny.Net.HttpServer                  # the server + the typed-endpoint generator
 dotnet add package Shiny.Net.HttpServer.Jwt              # JWT auth
+dotnet add package Shiny.Net.HttpServer.Proxy            # reverse proxy: clusters, LB, health, transforms
 dotnet add package Shiny.Net.HttpServer.Ssh              # SSH + quick tunnels
 dotnet add package Shiny.Net.HttpServer.AzureRelay       # Azure Relay tunnel (NOT AOT-clean)
 dotnet add package Shiny.Net.HttpServer.Mcp              # Model Context Protocol transport
@@ -1020,14 +1038,74 @@ var tokens = ctx.GetRequiredService<IAntiforgery>().GetTokens(ctx);
 
 ## Proxying to another server
 
+Needs `Shiny.Net.HttpServer.Proxy` and `using Shiny.Net.HttpServer.Proxy;` — it is **not** in the core
+package. This is tier 2 (routes): a proxy route is an ordinary route with a generated handler, so
+middleware, authentication and rate limiting apply to it exactly as they do to anything else.
+
+**One destination** — reach for this first, and only escalate when the ask names more than one:
+
 ```csharp
 app.MapProxy("/api/{*path}", "https://api.example.com");
 app.MapProxy("/printer/{*path}", "http://192.168.1.50", o => o.RewriteHost = false);
 ```
 
 Bodies stream both ways, `X-Forwarded-*` describe the original caller, an unreachable upstream is a
-**502** and one that will not answer is a **504**. A protocol upgrade is not forwarded — a WebSocket
-through this route will not work.
+**502**, one that will not answer is a **504**, and a WebSocket (or any HTTP/1.1 upgrade) is forwarded
+end to end — `o.ForwardUpgrades = false` turns that off.
+
+**A cluster** when there is more than one instance behind the route:
+
+```csharp
+app.MapProxy("/api/{*path}", cluster =>
+{
+    cluster.AddDestination("a", "https://a.internal");
+    cluster.AddDestination("b", "https://b.internal");
+
+    cluster.LoadBalancing = LoadBalancingPolicy.PowerOfTwoChoices;  // default; also RoundRobin,
+                                                                   // LeastRequests, Random, First
+    cluster.HealthCheck.Active.Enabled = true;                      // off by default — probes cost battery
+    cluster.HealthCheck.Active.Path = "/health";
+    cluster.SessionAffinity.Mode = SessionAffinityMode.Cookie;      // or Header
+});
+```
+
+Passive health (on for a cluster, off for the single-destination call) takes a destination out after
+`FailureThreshold` consecutive transport failures for `ReactivationPeriod`. When every destination is
+out, the route answers **503**.
+
+**Transforms** instead of `BeforeSend`/`AfterReceive` whenever the change is a path, query or header:
+
+```csharp
+cluster.Transforms
+    .RemovePathPrefix("/api")
+    .SetQueryValue("tenant", "acme")
+    .SetRequestHeader("X-Api-Key", key)
+    .RemoveResponseHeader("Server");
+```
+
+**From configuration** when the ask is routes that change without a rebuild. The shape matches YARP's,
+including `{**rest}` catch-alls, and it is parsed by hand rather than reflection-bound, so it stays
+AOT-clean:
+
+```csharp
+builder.AddReverseProxy(configuration.GetSection("ReverseProxy"));
+// no container: var proxy = app.MapReverseProxy(configuration.GetSection("ReverseProxy"));
+```
+
+```json
+{ "ReverseProxy": {
+    "Routes":   { "api": { "ClusterId": "backend", "Match": { "Path": "/api/{**rest}" },
+                           "Transforms": [ { "PathRemovePrefix": "/api" } ] } },
+    "Clusters": { "backend": { "LoadBalancingPolicy": "LeastRequests",
+                               "Destinations": { "d1": { "Address": "https://a.internal" } } } } } }
+```
+
+Reload is applied to the running server: routes swap atomically, clusters keep their health state, and
+routes mapped in code are untouched.
+
+- **Do not put a proxy on a tunnel without authentication and rate limiting in front of it**, and keep
+  the destination fixed rather than reading it from the request.
+- `HttpForwarder.ForwardAsync(ctx, "http://…")` forwards from inside a hand-written handler.
 
 ## Tunnelling
 

src/Shiny.Net.HttpServer.Proxy/HealthChecks.cs

@@ -0,0 +1,57 @@
+namespace Shiny.Net.HttpServer.Proxy;
+
+/// <summary>Both halves of a cluster's health story.</summary>
+public sealed class ClusterHealthCheckOptions
+{
+    /// <summary>Probing destinations on a timer, whether or not any traffic is flowing.</summary>
+    public ActiveHealthCheckOptions Active { get; } = new();
+
+    /// <summary>Watching what real requests do.</summary>
+    public PassiveHealthCheckOptions Passive { get; } = new();
+}
+
+/// <summary>Polling destinations to find out whether they are alive.</summary>
+public sealed class ActiveHealthCheckOptions
+{
+    /// <summary>Off by default: a probe every few seconds against every destination is not free,
+    /// and on a battery-powered device it is the kind of not-free that shows up in a graph.</summary>
+    public bool Enabled { get; set; }
+
+    /// <summary>How often each destination is probed.</summary>
+    public TimeSpan Interval { get; set; } = TimeSpan.FromSeconds(10);
+
+    /// <summary>How long a probe may take before it counts as a failure.</summary>
+    public TimeSpan Timeout { get; set; } = TimeSpan.FromSeconds(5);
+
+    /// <summary>Path probed on each destination, relative to its address (or its <see cref="ProxyDestination.Health"/>).</summary>
+    public string Path { get; set; } = "/health";
+
+    /// <summary>
+    /// Decides whether a probe response means healthy. The default accepts any 2xx.
+    /// <para>
+    /// Worth replacing when the upstream reports its own readiness in a body or a header — an
+    /// upstream that returns 200 while refusing work is exactly the case an active check exists for.
+    /// </para>
+    /// </summary>
+    public Func<HttpResponseMessage, bool>? Policy { get; set; }
+}
+
+/// <summary>Taking a destination out of rotation because real requests to it are failing.</summary>
+public sealed class PassiveHealthCheckOptions
+{
+    /// <summary>
+    /// On by default for a cluster, off for the single-destination <c>MapProxy</c> shorthand.
+    /// <para>
+    /// The distinction matters: with one destination there is nowhere else to send the request, so
+    /// quarantining it would only turn a 502 that names a real upstream failure into a 503 that
+    /// names nothing.
+    /// </para>
+    /// </summary>
+    public bool Enabled { get; set; } = true;
+
+    /// <summary>Consecutive failures before the destination is taken out.</summary>
+    public int FailureThreshold { get; set; } = 3;
+
+    /// <summary>How long it stays out before traffic is tried again.</summary>
+    public TimeSpan ReactivationPeriod { get; set; } = TimeSpan.FromSeconds(30);
+}