feat(usefulproteomicsdatabases): thread CancellationToken through GetProjectFilesAsync

Address the actionable items from the PR #1088 review (nbollis):

- GetProjectFilesAsync accepts an optional CancellationToken, checks it
  per page, and passes it to GetAsync / ReadAsStringAsync so a long
  pagination sequence can be cancelled cooperatively.
- seal PrideArchiveClient (it owns a single HttpClient and is not a base
  type), which is the intended resolution of the non-virtual-Dispose note.
- Add <inheritdoc/> to Dispose().
- Tests: double Dispose is idempotent; an injected HttpClient survives the
  client's Dispose and stays usable; an injected HttpClient with no
  BaseAddress gets the PRIDE default; pageSize validation now covers a
  negative value; MaxPages cap is exercised at edge values 0 and 1.

The remaining review findings (Newtonsoft coupling, IHttpClientFactory,
IJsonSerializer/IPrideArchiveClient abstractions, thread-safe dispose,
User-Agent) were declined as inconsistent with mzLib conventions and
resolved on the PR.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016y1PW7eLKHQMHw7Ymp9p9p

Author: trishorts

mzLib/Test/DatabaseTests/PrideArchiveClientTests.cs

@@ -202,11 +202,12 @@ public void GetProjectFilesAsync_BlankAccession_ThrowsArgumentException()
         Assert.That(async () => await client.GetProjectFilesAsync("   "), Throws.ArgumentException);
     }
 
-    [Test]
-    public void GetProjectFilesAsync_NonPositivePageSize_ThrowsArgumentOutOfRange()
+    [TestCase(0)]
+    [TestCase(-1)]
+    public void GetProjectFilesAsync_NonPositivePageSize_ThrowsArgumentOutOfRange(int pageSize)
     {
         using var client = new PrideArchiveClient(new HttpClient(new StubHandler(_ => JsonResponse("[]"))));
-        Assert.That(async () => await client.GetProjectFilesAsync("PXD012345", 0), Throws.InstanceOf<ArgumentOutOfRangeException>());
+        Assert.That(async () => await client.GetProjectFilesAsync("PXD012345", pageSize), Throws.InstanceOf<ArgumentOutOfRangeException>());
     }
 
     [Test]
@@ -231,6 +232,47 @@ public void DefaultConstructor_And_Dispose_DoNotThrow()
         var client = new PrideArchiveClient();
         Assert.That(() => client.Dispose(), Throws.Nothing);
     }
+
+    [Test]
+    public void Dispose_CalledTwice_DoesNotThrow()
+    {
+        var client = new PrideArchiveClient(new HttpClient(new StubHandler(_ => JsonResponse("[]"))));
+        client.Dispose();
+        Assert.That(() => client.Dispose(), Throws.Nothing); // idempotent
+    }
+
+    [Test]
+    public void Dispose_InjectedHttpClient_IsNotDisposed_AndRemainsUsable()
+    {
+        var handler = new StubHandler(_ => JsonResponse("[]"));
+        var httpClient = new HttpClient(handler) { BaseAddress = new Uri(PrideArchiveClient.DefaultBaseAddress) };
+        var client = new PrideArchiveClient(httpClient); // caller retains ownership of httpClient
+
+        client.Dispose();
+
+        // the injected HttpClient must survive the client's Dispose (a disposed client would throw here)
+        Assert.That(async () => await httpClient.GetAsync("projects/x/files"), Throws.Nothing);
+        httpClient.Dispose();
+    }
+
+    [Test]
+    public void Constructor_InjectedHttpClientWithoutBaseAddress_SetsPrideDefault()
+    {
+        var httpClient = new HttpClient(new StubHandler(_ => JsonResponse("[]"))); // no BaseAddress
+        using var client = new PrideArchiveClient(httpClient);
+        Assert.That(httpClient.BaseAddress, Is.EqualTo(new Uri(PrideArchiveClient.DefaultBaseAddress)));
+    }
+
+    [TestCase(0)]
+    [TestCase(1)]
+    public void GetProjectFilesAsync_ServerIgnoresPaging_LowMaxPages_Throws(int maxPages)
+    {
+        // every page is full and carries no total_records header, so only the MaxPages cap can stop it
+        var handler = new StubHandler(_ => JsonResponse(Array(FileJson("a"), FileJson("b"))));
+        using var client = new PrideArchiveClient(new HttpClient(handler)) { MaxPages = maxPages };
+        Assert.That(async () => await client.GetProjectFilesAsync("PXD012345", pageSize: 2),
+            Throws.InstanceOf<HttpRequestException>());
+    }
 }
 
 /// <summary>

mzLib/UsefulProteomicsDatabases/PrideArchiveClient.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Collections.Generic;
 using System.Net.Http;
+using System.Threading;
 using System.Threading.Tasks;
 using Newtonsoft.Json;
 
@@ -16,7 +17,7 @@ namespace UsefulProteomicsDatabases
     /// per unit of work and dispose it. A constructor overload accepts an <see cref="HttpClient"/> to
     /// support testing and custom configuration.
     /// </remarks>
-    public class PrideArchiveClient : IDisposable
+    public sealed class PrideArchiveClient : IDisposable
     {
         /// <summary>The base address of the PRIDE Archive REST API (v3).</summary>
         public const string DefaultBaseAddress = "https://www.ebi.ac.uk/pride/ws/archive/v3/";
@@ -65,14 +66,17 @@ private PrideArchiveClient(HttpClient httpClient, bool ownsHttpClient)
         /// </summary>
         /// <param name="accession">The PRIDE project accession, e.g. "PXD012345".</param>
         /// <param name="pageSize">Files requested per page (default 100). The full manifest is returned regardless.</param>
+        /// <param name="cancellationToken">Cancels the (possibly multi-page) fetch.</param>
         /// <returns>
         /// The project's files. Empty if the project has no files or the accession is unknown (PRIDE
         /// returns an empty result for an unknown accession). Never null.
         /// </returns>
         /// <exception cref="ArgumentException">The accession is null, empty, or whitespace.</exception>
         /// <exception cref="ArgumentOutOfRangeException">The page size is not positive.</exception>
         /// <exception cref="HttpRequestException">The API returned a non-success status code.</exception>
-        public async Task<List<PrideArchiveFile>> GetProjectFilesAsync(string accession, int pageSize = 100)
+        /// <exception cref="OperationCanceledException">The operation was cancelled via <paramref name="cancellationToken"/>.</exception>
+        public async Task<List<PrideArchiveFile>> GetProjectFilesAsync(string accession, int pageSize = 100,
+            CancellationToken cancellationToken = default)
         {
             if (string.IsNullOrWhiteSpace(accession))
                 throw new ArgumentException("A PRIDE project accession is required.", nameof(accession));
@@ -84,14 +88,15 @@ public async Task<List<PrideArchiveFile>> GetProjectFilesAsync(string accession,
 
             while (true)
             {
+                cancellationToken.ThrowIfCancellationRequested();
                 string requestUri = $"projects/{Uri.EscapeDataString(accession)}/files?pageSize={pageSize}&page={page}";
-                using HttpResponseMessage response = await _httpClient.GetAsync(requestUri).ConfigureAwait(false);
+                using HttpResponseMessage response = await _httpClient.GetAsync(requestUri, cancellationToken).ConfigureAwait(false);
 
                 if (!response.IsSuccessStatusCode)
                     throw new HttpRequestException(
                         $"PRIDE Archive request failed with status {(int)response.StatusCode} {response.ReasonPhrase} for '{requestUri}'.");
 
-                string content = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
+                string content = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
                 List<PrideArchiveFile> pageFiles =
                     JsonConvert.DeserializeObject<List<PrideArchiveFile>>(content, JsonSettings) ?? new List<PrideArchiveFile>();
 
@@ -131,6 +136,7 @@ private static bool TryGetTotalRecords(HttpResponseMessage response, out long to
             return false;
         }
 
+        /// <inheritdoc/>
         public void Dispose()
         {
             if (_disposed)