.

Author: SimonCropp

claude.md

@@ -21,7 +21,7 @@ dotnet run --project src/RemoteZip.Tests --configuration Release --no-build -- -
 
 ## What this library is
 
-One public type, `RemoteZipArchive`: reads a zip over HTTP range requests without downloading the whole file. Open = one suffix request for the tail → parse end-of-central-directory (EOCD) → parse central directory (fetched separately only if bigger than the tail). Read = one range request per entry (`local header + name + extra-slack + compressed data`), decompress, crc-check — or no request at all when the entry falls inside the retained tail. Batched reads coalesce entries whose ranges are within 8 KiB and issue the clusters that remain concurrently, bounded by `MaxConcurrency`.
+Two public types, `RemoteZipArchive` and `StubZipServer` (a test double for consumers, shipped in the same package — it depends on nothing beyond `HttpMessageHandler` and trims away when unreferenced, so a separate package would cost more than it saves): reads a zip over HTTP range requests without downloading the whole file. Batched reads come in entry-keyed and name-keyed forms (`Read`/`ReadText` over `IReadOnlyCollection` of entries or names); name-keyed results omit missing names rather than erroring, so callers probe optional files without existence checks. Open = one suffix request for the tail → parse end-of-central-directory (EOCD) → parse central directory (fetched separately only if bigger than the tail). Read = one range request per entry (`local header + name + extra-slack + compressed data`), decompress, crc-check — or no request at all when the entry falls inside the retained tail. Batched reads coalesce entries whose ranges are within 8 KiB and issue the clusters that remain concurrently, bounded by `MaxConcurrency`.
 
 Design constraints that are not obvious from the code alone:
 
@@ -34,7 +34,7 @@ Design constraints that are not obvious from the code alone:
 
 ## Test infrastructure
 
-- `StubZipServer` mimics nuget.org's observed behavior (206 slices, suffix ranges, 200-with-full-body for unsatisfiable ranges). Toggles: `SupportRanges` (range-less servers), `ExposeContentRange` (browser CORS simulation), `Delay` (needed before `MaxConcurrentRequests` can observe overlap — without it each response completes before the next request is issued). Batched reads hit the handler concurrently, so its logs are lock-guarded and their *order* is not meaningful; assert on counts.
+- `StubZipServer` (shipped public in `src/RemoteZip`, so the tests dogfood what consumers get) mimics nuget.org's observed behavior (206 slices, suffix ranges, 200-with-full-body for unsatisfiable ranges). Toggles: `SupportRanges` (range-less servers), `ExposeContentRange` (browser CORS simulation), `Delay` (needed before `MaxConcurrentRequests` can observe overlap — without it each response completes before the next request is issued). Batched reads hit the handler concurrently, so its logs are lock-guarded and their *order* is not meaningful; assert on counts.
 - `Zips.Padded` + `TailLength = 1024` is the pattern for forcing the ranged path; small zips otherwise fit entirely inside the default 128 KiB tail (`DownloadedWholeFile == true`) and reads cost zero requests.
 - **Padding goes last in a test zip, not first.** Since `TailCachedRangeReader` serves anything inside the tail for free, an entry written near the end of the file is read without a request. A fixture that pads first pushes its interesting entries to the end and silently stops testing the ranged path — it will pass, with a lower request count than the test asserts. `Zips.Padded` and the `ZipBuilder` fixtures all append `padding.bin` for this reason; `EntryInsideTail_ReadsWithoutAnotherRequest` is the one test that deliberately inverts it.
 - `ZipBuilder` hand-writes zip bytes for what `ZipArchive` can't produce: archive comments, oversized local extras, encrypted/unsupported-method flags, wrong crcs, zip64 records.

readme.md

@@ -67,6 +67,26 @@ public static async Task<string?> ReadNuspec(HttpClient http, string packageUrl)
 <!-- endSnippet -->
 
 
+### Reading by name
+
+For a known set of files, `Read` / `ReadText` accept names directly and return name-keyed results — no `Find` calls, no null checks, same coalescing:
+
+<!-- snippet: read-by-name -->
+<a id='snippet-read-by-name'></a>
+```cs
+public static async Task<string?> ReadLicense(HttpClient http, string url)
+{
+    var zip = await RemoteZipArchive.Open(http, url);
+
+    // Names with no matching entry are simply absent from the result.
+    var texts = await zip.ReadText(["license.md", "license.txt"]);
+    return texts.GetValueOrDefault("license.md") ?? texts.GetValueOrDefault("license.txt");
+}
+```
+<sup><a href='/src/RemoteZip.Tests/Usage.cs#L37-L46' title='Snippet source file'>snippet source</a> | <a href='#snippet-read-by-name' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+
 ## How it works
 
 Opening sends one suffix range request (`Range: bytes=-131072`) and parses the end-of-central-directory record from it. For typical archives the whole central directory is inside that tail, so enumeration costs exactly one request; an oversized central directory costs one more. Each `Read` then fetches `local header + entry data` in one range request, over-fetching by 512 bytes to cover local extra fields; a batched `Read` merges entries whose ranges are within 8 KB of each other.
@@ -106,6 +126,31 @@ var options = new RemoteZipOptions
 The server must support `Range` requests (`206 Partial Content`). For browser use it must also allow the `Range` header in its CORS policy (`Access-Control-Allow-Headers: range`). Exposing `Content-Range` is *not* required. nuget.org's flat container satisfies all of this, including from `localhost` origins.
 
 
+## Testing consumers
+
+`StubZipServer` ships in the package: an `HttpMessageHandler` that serves an in-memory `byte[]` with the Range semantics observed on nuget.org — 206 slices, suffix ranges, 200-with-full-body for unsatisfiable ranges. `SupportRanges = false` simulates a server without range support, `ExposeContentRange = false` simulates browser CORS hiding the header, and `Requests` / `HeaderLog` / `BytesServed` / `MaxConcurrentRequests` record the traffic so tests can assert fetch efficiency as well as correctness:
+
+<!-- snippet: stub-zip-server -->
+<a id='snippet-stub-zip-server'></a>
+```cs
+[Test]
+public async Task StubServesRanges()
+{
+    var server = new StubZipServer(SampleZipBytes());
+    using var client = new HttpClient(server);
+
+    var archive = await RemoteZipArchive.Open(client, "https://example/archive.zip");
+    var text = await archive.ReadText(archive.Find("readme.md")!);
+
+    await Assert.That(text).IsEqualTo("# Sample");
+    // Requests, HeaderLog, BytesServed and MaxConcurrentRequests record the traffic.
+    await Assert.That(server.Requests).Count().IsEqualTo(1);
+}
+```
+<sup><a href='/src/RemoteZip.Tests/TestingUsage.cs#L3-L17' title='Snippet source file'>snippet source</a> | <a href='#snippet-stub-zip-server' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+
 ## Limitations
 
 - Encrypted entries and compression methods other than stored/deflate throw.

src/Directory.Build.props

@@ -2,7 +2,7 @@
 <Project>
   <PropertyGroup>
     <NoWarn>CS1591;NU1608;NU1109;NU1901;PolyfillTargetsForNuget;SC023</NoWarn>
-    <Version>0.1.0</Version>
+    <Version>0.2.0</Version>
     <AssemblyVersion>1.0.0</AssemblyVersion>
     <Description>Read entries from a remote zip over HTTP range requests, without downloading the whole archive. Works from Blazor WebAssembly.</Description>
     <ResolveAssemblyReferencesSilent>true</ResolveAssemblyReferencesSilent>

src/RemoteZip.Tests/NameKeyedReadTests.cs

@@ -0,0 +1,88 @@
+public class NameKeyedReadTests
+{
+    static readonly RemoteZipOptions rangedOptions = new()
+    {
+        TailLength = 1024
+    };
+
+    [Test]
+    public async Task ReadByNames_MissingNamesAbsent_SingleCoalescedRequest()
+    {
+        var data = Zips.Padded(4096, ("docs/a.txt", "alpha"), ("docs/b.txt", "beta"));
+        var (client, server) = Zips.Serve(data);
+        using (client)
+        {
+            var zip = await RemoteZipArchive.Open(client, "https://example/archive.zip", rangedOptions);
+            var contents = await zip.Read(["docs/a.txt", "docs/b.txt", "missing.txt"]);
+
+            await Assert.That(contents.Count).IsEqualTo(2);
+            await Assert.That(Encoding.UTF8.GetString(contents["docs/a.txt"])).IsEqualTo("alpha");
+            await Assert.That(Encoding.UTF8.GetString(contents["docs/b.txt"])).IsEqualTo("beta");
+            await Assert.That(contents.ContainsKey("missing.txt")).IsFalse();
+            await Assert.That(server.Requests).Count().IsEqualTo(2);
+        }
+    }
+
+    [Test]
+    public async Task ReadByNames_DuplicateNamesCollapse()
+    {
+        var data = Zips.Padded(4096, ("a.txt", "alpha"));
+        var (client, _) = Zips.Serve(data);
+        using (client)
+        {
+            var zip = await RemoteZipArchive.Open(client, "https://example/archive.zip", rangedOptions);
+            var contents = await zip.Read(["a.txt", "a.txt"]);
+
+            await Assert.That(contents.Count).IsEqualTo(1);
+            await Assert.That(Encoding.UTF8.GetString(contents["a.txt"])).IsEqualTo("alpha");
+        }
+    }
+
+    [Test]
+    public async Task ReadTextByNames_HonorsByteOrderMark()
+    {
+        var data = Zips.Padded(4096, ("bom.txt", "hi"), ("plain.txt", "there"));
+        var (client, _) = Zips.Serve(data);
+        using (client)
+        {
+            var zip = await RemoteZipArchive.Open(client, "https://example/archive.zip", rangedOptions);
+            var texts = await zip.ReadText(["bom.txt", "plain.txt", "missing.txt"]);
+
+            await Assert.That(texts.Count).IsEqualTo(2);
+            await Assert.That(texts["bom.txt"]).IsEqualTo("hi");
+            await Assert.That(texts["plain.txt"]).IsEqualTo("there");
+        }
+    }
+
+    [Test]
+    public async Task ReadTextByEntries_KeyedByEntry()
+    {
+        var data = Zips.Padded(4096, ("a.txt", "alpha"), ("b.txt", "beta"));
+        var (client, _) = Zips.Serve(data);
+        using (client)
+        {
+            var zip = await RemoteZipArchive.Open(client, "https://example/archive.zip", rangedOptions);
+            var a = zip.Find("a.txt")!;
+            var b = zip.Find("b.txt")!;
+            var texts = await zip.ReadText([a, b]);
+
+            await Assert.That(texts[a]).IsEqualTo("alpha");
+            await Assert.That(texts[b]).IsEqualTo("beta");
+        }
+    }
+
+    [Test]
+    public async Task ReadByNames_EmptyInput_NoRequests()
+    {
+        var data = Zips.Padded(4096, ("a.txt", "alpha"));
+        var (client, server) = Zips.Serve(data);
+        using (client)
+        {
+            var zip = await RemoteZipArchive.Open(client, "https://example/archive.zip", rangedOptions);
+            var contents = await zip.Read(Array.Empty<string>());
+
+            await Assert.That(contents.Count).IsEqualTo(0);
+            await Assert.That(server.Requests).Count().IsEqualTo(1);
+        }
+    }
+}

src/RemoteZip.Tests/TestingUsage.cs

@@ -0,0 +1,21 @@
+public class TestingUsage
+{
+    // begin-snippet: stub-zip-server
+    [Test]
+    public async Task StubServesRanges()
+    {
+        var server = new StubZipServer(SampleZipBytes());
+        using var client = new HttpClient(server);
+
+        var archive = await RemoteZipArchive.Open(client, "https://example/archive.zip");
+        var text = await archive.ReadText(archive.Find("readme.md")!);
+
+        await Assert.That(text).IsEqualTo("# Sample");
+        // Requests, HeaderLog, BytesServed and MaxConcurrentRequests record the traffic.
+        await Assert.That(server.Requests).Count().IsEqualTo(1);
+    }
+    // end-snippet
+
+    static byte[] SampleZipBytes() =>
+        Zips.Normal(("readme.md", "# Sample"));
+}

src/RemoteZip.Tests/Usage.cs

@@ -34,6 +34,17 @@ public static async Task PrintRemoteZip(HttpClient http, string url)
     }
     // end-snippet
 
+    // begin-snippet: read-by-name
+    public static async Task<string?> ReadLicense(HttpClient http, string url)
+    {
+        var zip = await RemoteZipArchive.Open(http, url);
+
+        // Names with no matching entry are simply absent from the result.
+        var texts = await zip.ReadText(["license.md", "license.txt"]);
+        return texts.GetValueOrDefault("license.md") ?? texts.GetValueOrDefault("license.txt");
+    }
+    // end-snippet
+
     [Test]
     public async Task Runs()
     {
@@ -45,6 +56,18 @@ public async Task Runs()
         }
     }
 
+    [Test]
+    public async Task ReadLicenseRuns()
+    {
+        var data = Zips.Normal(("license.txt", "MIT"), ("lib/app.dll", "not really a dll"));
+        var (client, _) = Zips.Serve(data);
+        using (client)
+        {
+            var license = await ReadLicense(client, "https://example/archive.zip");
+            await Assert.That(license).IsEqualTo("MIT");
+        }
+    }
+
     [Test]
     public async Task BatchRuns()
     {

src/RemoteZip/RemoteZipArchive.cs

@@ -389,10 +389,81 @@ async Task<List<KeyValuePair<RemoteZipEntry, byte[]>>> ReadCluster(Cluster clust
 
     sealed record Cluster(long Start, long End, List<RemoteZipEntry> Entries);
 
+    /// <summary>
+    /// Downloads and decompresses the named entries, keyed by those names. A name with no
+    /// matching entry is simply absent from the result rather than an error, so probing
+    /// for optional files needs no existence checks. Fetching follows the same plan as the
+    /// entry batch: close entries coalesce into one request, remaining requests overlap.
+    /// </summary>
+    public async Task<IReadOnlyDictionary<string, byte[]>> Read(IReadOnlyCollection<string> fullNames, Cancel cancel = default)
+    {
+        var found = ResolveNames(fullNames);
+        var contents = await Read(found.Values, cancel);
+        var results = new Dictionary<string, byte[]>(found.Count);
+        foreach (var (name, entry) in found)
+        {
+            results[name] = contents[entry];
+        }
+
+        return results;
+    }
+
+    /// <summary>Downloads the named entries and decodes each as text, honoring byte-order marks.</summary>
+    public async Task<IReadOnlyDictionary<string, string>> ReadText(IReadOnlyCollection<string> fullNames, Cancel cancel = default)
+    {
+        var contents = await Read(fullNames, cancel);
+        var results = new Dictionary<string, string>(contents.Count);
+        foreach (var (name, bytes) in contents)
+        {
+            results[name] = await DecodeText(bytes, cancel);
+        }
+
+        return results;
+    }
+
+    /// <summary>Downloads and decompresses multiple entries, decoding each as text, honoring byte-order marks.</summary>
+    public async Task<IReadOnlyDictionary<RemoteZipEntry, string>> ReadText(IReadOnlyCollection<RemoteZipEntry> batch, Cancel cancel = default)
+    {
+        var contents = await Read(batch, cancel);
+        var results = new Dictionary<RemoteZipEntry, string>(contents.Count);
+        foreach (var (entry, bytes) in contents)
+        {
+            results[entry] = await DecodeText(bytes, cancel);
+        }
+
+        return results;
+    }
+
+    /// <summary>First matching entry per distinct name; names without a match are skipped.</summary>
+    Dictionary<string, RemoteZipEntry> ResolveNames(IReadOnlyCollection<string> fullNames)
+    {
+        var found = new Dictionary<string, RemoteZipEntry>(fullNames.Count);
+        foreach (var name in fullNames)
+        {
+            if (found.ContainsKey(name))
+            {
+                continue;
+            }
+
+            var entry = Find(name);
+            if (entry != null)
+            {
+                found[name] = entry;
+            }
+        }
+
+        return found;
+    }
+
     /// <summary>Downloads an entry and decodes it as text, honoring a byte-order mark.</summary>
     public async Task<string> ReadText(RemoteZipEntry entry, Cancel cancel = default)
     {
         var bytes = await Read(entry, cancel);
+        return await DecodeText(bytes, cancel);
+    }
+
+    static async Task<string> DecodeText(byte[] bytes, Cancel cancel)
+    {
         using var streamReader = new StreamReader(new MemoryStream(bytes));
         return await streamReader.ReadToEndAsync(cancel);
     }

src/RemoteZip.Tests/StubZipServer.cs src/RemoteZip/StubZipServer.cssrc/RemoteZip.Tests/StubZipServer.cs renamed to src/RemoteZip/StubZipServer.cs

@@ -1,33 +1,43 @@
+namespace RemoteZip;
+
 /// <summary>
-/// Serves a byte[] the way nuget.org's CDN was observed to behave: suffix and absolute
-/// ranges get 206 with the requested slice; an unsatisfiable range gets 200 with the whole
-/// file (not 416). Toggles simulate servers without range support and browser contexts
-/// where CORS hides Content-Range. Batched reads issue requests concurrently, so the logs
-/// are guarded and their order is not meaningful — assert on counts, not sequence.
+/// An <see cref="HttpMessageHandler" /> for testing consumers, serving a byte[] the way
+/// nuget.org's CDN was observed to behave: suffix and absolute ranges get 206 with the
+/// requested slice; an unsatisfiable range gets 200 with the whole file (not 416). Toggles
+/// simulate servers without range support and browser contexts where CORS hides
+/// Content-Range. Batched reads issue requests concurrently, so the logs are lock-guarded
+/// and their order is not meaningful — assert on counts, not sequence.
 /// </summary>
-class StubZipServer(byte[] data) : HttpMessageHandler
+public class StubZipServer(byte[] data) : HttpMessageHandler
 {
     readonly Lock padlock = new();
     int inFlight;
 
+    /// <summary>False simulates a server without range support: every response is a 200 with the full body.</summary>
     public bool SupportRanges { get; set; } = true;
 
+    /// <summary>False omits Content-Range from 206 responses, matching what browser CORS lets a caller see on nuget.org.</summary>
     public bool ExposeContentRange { get; set; } = true;
 
     /// <summary>
     /// Held open before responding. A non-zero delay is what makes overlapping requests
-    /// observable in <see cref="MaxConcurrentRequests" />; without it each response
+    /// observable via <see cref="MaxConcurrentRequests" />; without it each response
     /// completes before the next request is issued.
     /// </summary>
     public TimeSpan Delay { get; set; }
 
+    /// <summary>One entry per request: the Range header served, or "full".</summary>
     public List<string> Requests { get; } = [];
 
+    /// <summary>The full request headers of every request, for asserting on configured extras.</summary>
     public List<string> HeaderLog { get; } = [];
 
     /// <summary>High-water mark of requests in flight at the same time.</summary>
     public int MaxConcurrentRequests { get; private set; }
 
+    /// <summary>Total body bytes served, for asserting a consumer's fetch efficiency.</summary>
+    public long BytesServed { get; private set; }
+
     protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, Cancel cancel)
     {
         lock (padlock)
@@ -87,6 +97,7 @@ HttpResponseMessage Respond(HttpRequestMessage request)
 
         var slice = new byte[to - from + 1];
         Array.Copy(data, from, slice, 0, slice.Length);
+        Count(slice.Length);
         var response = new HttpResponseMessage(HttpStatusCode.PartialContent)
         {
             Content = new ByteArrayContent(slice)
@@ -107,9 +118,20 @@ void Log(string request)
         }
     }
 
-    HttpResponseMessage Full() =>
-        new(HttpStatusCode.OK)
+    void Count(long bytes)
+    {
+        lock (padlock)
+        {
+            BytesServed += bytes;
+        }
+    }
+
+    HttpResponseMessage Full()
+    {
+        Count(data.Length);
+        return new(HttpStatusCode.OK)
         {
             Content = new ByteArrayContent(data)
         };
+    }
 }