Add zip-backed static file source

Introduce `ZipFileSource` to serve static assets from zip archives on disk or embedded in an assembly, including optional precompressed sidecars for Blazor publish output. Generalize precompressed lookups behind `IPrecompressedFileSource` so middleware and composite sources preserve `.br`/`.gz` assets, then add coverage for embedded archives, ranges, fallbacks, concurrency, and composite behavior. Update the README and skill docs to recommend zip sources for packaged web assets, and bump the version to 1.0.5.

Author: aritchie

readme.md

@@ -134,7 +134,7 @@ is built on the one below and they compose in the same app.
 | **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 |
 | **Protocols** | HTTP/1.1, HTTP/2 (own HPACK), HTTP/3 (own QPACK), WebSockets, Server-Sent Events, trailing headers on all three versions. Never guessed — ALPN over TLS, connection preface over cleartext. WebSockets carry permessage-deflate, keepalive pings, and a registry for broadcasting to a group |
-| **Content** | Static files from disk *or* embedded resources, a published Blazor WebAssembly app, streaming multipart uploads, downloads with byte ranges and conditional GETs, a file browser over a directory, and brotli/gzip/deflate compression in both directions |
+| **Content** | Static files from disk, embedded resources *or* a zip archive (on disk or embedded), a published Blazor WebAssembly app, streaming multipart uploads, downloads with byte ranges and conditional GETs, a file browser over a directory, and brotli/gzip/deflate compression in both directions |
 | **Security** | Authentication and authorization split ASP.NET-style, with Basic, API key, cookie and JWT schemes; policies, roles and claims; CORS, rate limiting and IP filtering, all with per-endpoint policies; signed double-submit antiforgery, the browser security headers, HSTS and an HTTPS redirect |
 | **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 |

skills/shiny-httpserver/SKILL.md

@@ -55,6 +55,9 @@ triggers:
 - UseStaticFiles
 - UseEmbeddedFiles
 - UseBlazorWebAssembly
+- ZipFileSource
+- serve a zip
+- serve static files from a zip
 - MapFileBrowser
 - FileDownloadResult
 - ReadMultipartAsync
@@ -741,6 +744,28 @@ app.UseBlazorWebAssembly("./wwwroot");                            // SPA + preco
 app.MapFileBrowser("/files", o => o.RootPath = FileSystem.AppDataDirectory).RequireAuthorization();
 ```
 
+**Four sources**, all `IStaticFileSource` and all usable with any of the above:
+`PhysicalFileSource` (a directory), `EmbeddedFileSource` (loose embedded resources),
+`ZipFileSource` (a zip on disk or embedded in the assembly), `CompositeFileSource` (tried in order —
+a directory in front of the packaged copy is the development arrangement).
+
+```csharp
+// A packaged Blazor publish, zipped into the app - one embedded resource instead of thousands,
+// and the paths survive instead of being flattened into the resource name.
+app.UseBlazorWebAssembly(
+    new ZipFileSource(typeof(App).Assembly, "MyApp.wwwroot.zip")
+    {
+        PrecompressedEncodings = ["br", "gzip"]   // a publish zips its .br/.gz sidecars too
+    }
+);
+
+new ZipFileSource("./content/site.zip");            // on disk
+new ZipFileSource("./site.zip", "wwwroot");         // zipped with its parent folder
+```
+
+- Prefer `ZipFileSource` over `EmbeddedFileSource` for a **publish output**: `EmbeddedFileSource` has
+  to un-mangle dotted resource names, which is ambiguous for `site.min.css`, and thousands of loose
+  resources inflate the assembly. A zip keeps real paths and stays compressed.
 - Unknown file extensions are **not served** by default. Add `ContentTypeOverrides[".x"]` rather than
   turning on `ServeUnknownFileTypes`.
 - `MapFileBrowser("/", …)` mounts the browser on the whole site — the shape a "serve this directory"

src/Shiny.Net.HttpServer/StaticFiles/IStaticFileSource.cs

@@ -42,14 +42,34 @@ public interface IStaticFileSource
     bool TryGetFile(string relativePath, out StaticFile file);
 }
 
+/// <summary>
+/// A source that can serve a precompressed sidecar in place of the file that was asked for -
+/// <c>app.wasm.br</c> for <c>app.wasm</c>.
+/// <para>
+/// Separate from <see cref="IStaticFileSource"/> because not every source has the notion: sidecars
+/// are a property of how content was published, and a source over content that was not published
+/// that way has nothing to offer. The middleware asks for this and falls back to the plain lookup
+/// when a source does not implement it.
+/// </para>
+/// </summary>
+public interface IPrecompressedFileSource : IStaticFileSource
+{
+    /// <summary>
+    /// Resolves a path, preferring a sidecar whose coding appears in
+    /// <paramref name="acceptedEncodings"/>. Returns the original file when there is no usable one,
+    /// so a caller never has to try both.
+    /// </summary>
+    bool TryGetFile(string relativePath, IReadOnlyList<string>? acceptedEncodings, out StaticFile file);
+}
+
 /// <summary>
 /// Serves files from a directory on disk.
 /// <para>
 /// Every resolved path is checked to be inside the root after normalization *and* after following
 /// links, because a symlink is the one way a path that looks contained can leave.
 /// </para>
 /// </summary>
-public sealed class PhysicalFileSource : IStaticFileSource
+public sealed class PhysicalFileSource : IPrecompressedFileSource
 {
     readonly string root;
 
@@ -293,15 +313,27 @@ static IEnumerable<string> CandidatePaths(string resourceSuffix)
 /// picked up without a rebuild, embedded resources behind it so the packaged app still works.
 /// </para>
 /// </summary>
-public sealed class CompositeFileSource(params IStaticFileSource[] sources) : IStaticFileSource
+public sealed class CompositeFileSource(params IStaticFileSource[] sources) : IPrecompressedFileSource
 {
     readonly IStaticFileSource[] sources = sources ?? throw new ArgumentNullException(nameof(sources));
 
     public bool TryGetFile(string relativePath, out StaticFile file)
+        => this.TryGetFile(relativePath, acceptedEncodings: null, out file);
+
+    /// <summary>
+    /// Asks each source in turn, letting the ones that understand sidecars offer theirs. Without
+    /// this the composite would flatten every source it holds down to the plain lookup, and putting
+    /// a directory in front of a published archive would quietly cost the precompressed assets.
+    /// </summary>
+    public bool TryGetFile(string relativePath, IReadOnlyList<string>? acceptedEncodings, out StaticFile file)
     {
         foreach (var source in this.sources)
         {
-            if (source.TryGetFile(relativePath, out file))
+            var found = acceptedEncodings is { Count: > 0 } && source is IPrecompressedFileSource precompressed
+                ? precompressed.TryGetFile(relativePath, acceptedEncodings, out file)
+                : source.TryGetFile(relativePath, out file);
+
+            if (found)
                 return true;
         }
 

src/Shiny.Net.HttpServer/StaticFiles/StaticFileMiddleware.cs

@@ -140,8 +140,8 @@ bool TryResolveFile(string path, IReadOnlyList<string>? accepted, out StaticFile
     {
         contentType = string.Empty;
 
-        var found = accepted is { Count: > 0 } && this.options.Source is PhysicalFileSource physical
-            ? physical.TryGetFile(path, accepted, out file)
+        var found = accepted is { Count: > 0 } && this.options.Source is IPrecompressedFileSource precompressed
+            ? precompressed.TryGetFile(path, accepted, out file)
             : this.options.Source.TryGetFile(path, out file);
 
         if (!found)