[SDK] Usability improvements (loic-sharma#516)

Improves `BaGet.Protocol`:

* Renamed `GetPackageStreamAsync` to `DownloadPackageAsync`
* Renamed `GetPackageManifestStreamAsync` to `DownloadPackageManifestAsync`
* Replaced `GetRegistrationLeafOrNullAsync` by `GetRegistrationLeafAsync` which accepts a URL to a registration leaf. The previous method made assumptions that may not be correct on all V3 servers.

⚠ These are breaking changes!

docs/tools/sdk.md

@@ -33,7 +33,7 @@ NuGetClient client = new NuGetClient("https://api.nuget.org/v3/index.json");
 string packageId = "Newtonsoft.Json";
 NuGetVersion packageVersion = new NuGetVersion("12.0.1");
 
-using (Stream packageStream = await client.GetPackageStreamAsync(packageId, packageVersion))
+using (Stream packageStream = await client.DownloadPackageAsync(packageId, packageVersion))
 {
     Console.WriteLine($"Downloaded package {packageId} {packageVersion}");
 }

samples/Sample01_Download.cs

@@ -17,7 +17,7 @@ public async Task DownloadPackage()
             string packageId = "Newtonsoft.Json";
             NuGetVersion packageVersion = new NuGetVersion("12.0.1");
 
-            using (Stream packageStream = await client.GetPackageStreamAsync(packageId, packageVersion))
+            using (Stream packageStream = await client.DownloadPackageAsync(packageId, packageVersion))
             {
                 Console.WriteLine($"Downloaded package {packageId} {packageVersion}");
             }
@@ -32,7 +32,7 @@ public async Task DownloadPackageManifest()
             string packageId = "Newtonsoft.Json";
             NuGetVersion packageVersion = new NuGetVersion("12.0.1");
 
-            using (Stream manifestStream = await client.GetPackageManifestStreamAsync(packageId, packageVersion))
+            using (Stream manifestStream = await client.DownloadPackageManifestAsync(packageId, packageVersion))
             {
                 Console.WriteLine($"Downloaded package {packageId} {packageVersion}'s nuspec");
             }

src/BaGet.Core/Mirror/MirrorService.cs

@@ -203,7 +203,7 @@ private async Task IndexFromSourceAsync(string id, NuGetVersion version, Cancell
 
             try
             {
-                using (var stream = await _upstreamClient.GetPackageStreamAsync(id, version, cancellationToken))
+                using (var stream = await _upstreamClient.DownloadPackageAsync(id, version, cancellationToken))
                 {
                     packageStream = await stream.AsTemporaryFileStreamAsync();
                 }

src/BaGet.Protocol/NuGetClient.cs

@@ -12,7 +12,7 @@
 namespace BaGet.Protocol
 {
     /// <summary>
-    /// The <see cref="NuGetClient"/> allows you to interact with a NuGet server.
+    /// The client to interact with a NuGet server.
     /// </summary>
     public class NuGetClient
     {
@@ -114,9 +114,9 @@ public virtual async Task<bool> ExistsAsync(
         /// <exception cref="PackageNotFoundException">
         ///     The package could not be found.
         /// </exception>
-        public virtual async Task<Stream> GetPackageStreamAsync(string packageId, NuGetVersion packageVersion, CancellationToken cancellationToken = default)
+        public virtual async Task<Stream> DownloadPackageAsync(string packageId, NuGetVersion packageVersion, CancellationToken cancellationToken = default)
         {
-            var stream = await _contentClient.GetPackageContentStreamOrNullAsync(packageId, packageVersion, cancellationToken);
+            var stream = await _contentClient.DownloadPackageOrNullAsync(packageId, packageVersion, cancellationToken);
 
             if (stream == null)
             {
@@ -136,9 +136,12 @@ public virtual async Task<Stream> GetPackageStreamAsync(string packageId, NuGetV
         /// <exception cref="PackageNotFoundException">
         ///     The package could not be found.
         /// </exception>
-        public virtual async Task<Stream> GetPackageManifestStreamAsync(string packageId, NuGetVersion packageVersion, CancellationToken cancellationToken = default)
+        public virtual async Task<Stream> DownloadPackageManifestAsync(
+            string packageId,
+            NuGetVersion packageVersion,
+            CancellationToken cancellationToken = default)
         {
-            var stream = await _contentClient.GetPackageManifestStreamOrNullAsync(packageId, packageVersion, cancellationToken);
+            var stream = await _contentClient.DownloadPackageManifestOrNullAsync(packageId, packageVersion, cancellationToken);
 
             if (stream == null)
             {
@@ -172,7 +175,10 @@ public virtual async Task<IReadOnlyList<NuGetVersion>> ListPackageVersionsAsync(
         /// <param name="includeUnlisted">Whether to include unlisted versions.</param>
         /// <param name="cancellationToken">A token to cancel the task.</param>
         /// <returns>The package's versions, or an empty list if the package does not exist.</returns>
-        public virtual async Task<IReadOnlyList<NuGetVersion>> ListPackageVersionsAsync(string packageId, bool includeUnlisted, CancellationToken cancellationToken = default)
+        public virtual async Task<IReadOnlyList<NuGetVersion>> ListPackageVersionsAsync(
+            string packageId,
+            bool includeUnlisted,
+            CancellationToken cancellationToken = default)
         {
             if (!includeUnlisted)
             {
@@ -195,7 +201,9 @@ public virtual async Task<IReadOnlyList<NuGetVersion>> ListPackageVersionsAsync(
         /// <param name="packageId">The package ID.</param>
         /// <param name="cancellationToken">A token to cancel the task.</param>
         /// <returns>The package's metadata, or an empty list if the package does not exist.</returns>
-        public virtual async Task<IReadOnlyList<PackageMetadata>> GetPackageMetadataAsync(string packageId, CancellationToken cancellationToken = default)
+        public virtual async Task<IReadOnlyList<PackageMetadata>> GetPackageMetadataAsync(
+            string packageId,
+            CancellationToken cancellationToken = default)
         {
             var result = new List<PackageMetadata>();
 
@@ -240,7 +248,10 @@ public virtual async Task<IReadOnlyList<PackageMetadata>> GetPackageMetadataAsyn
         /// <exception cref="PackageNotFoundException">
         ///     The package could not be found.
         /// </exception>
-        public virtual async Task<PackageMetadata> GetPackageMetadataAsync(string packageId, NuGetVersion packageVersion, CancellationToken cancellationToken = default)
+        public virtual async Task<PackageMetadata> GetPackageMetadataAsync(
+            string packageId,
+            NuGetVersion packageVersion,
+            CancellationToken cancellationToken = default)
         {
             var registrationIndex = await _metadataClient.GetRegistrationIndexOrNullAsync(packageId, cancellationToken);
 

src/BaGet.Protocol/PackageContent/IPackageContentClient.cs

@@ -34,7 +34,7 @@ Task<PackageVersionsResponse> GetPackageVersionsOrNullAsync(
         /// <returns>
         /// The package's content stream, or null if the package does not exist. The stream may not be seekable.
         /// </returns>
-        Task<Stream> GetPackageContentStreamOrNullAsync(
+        Task<Stream> DownloadPackageOrNullAsync(
             string packageId,
             NuGetVersion packageVersion,
             CancellationToken cancellationToken = default);
@@ -49,7 +49,7 @@ Task<Stream> GetPackageContentStreamOrNullAsync(
         /// <returns>
         /// The package's manifest stream, or null if the package does not exist. The stream may not be seekable.
         /// </returns>
-        Task<Stream> GetPackageManifestStreamOrNullAsync(
+        Task<Stream> DownloadPackageManifestOrNullAsync(
             string packageId,
             NuGetVersion packageVersion,
             CancellationToken cancellationToken = default);

src/BaGet.Protocol/PackageContent/PackageContentClient.cs

@@ -18,24 +18,24 @@ public PackageContentClient(NuGetClientFactory clientFactory)
                 _clientfactory = clientFactory ?? throw new ArgumentNullException(nameof(clientFactory));
             }
 
-            public async Task<Stream> GetPackageContentStreamOrNullAsync(
+            public async Task<Stream> DownloadPackageOrNullAsync(
                 string packageId,
                 NuGetVersion packageVersion,
                 CancellationToken cancellationToken = default)
             {
                 var client = await _clientfactory.GetPackageContentClientAsync(cancellationToken);
 
-                return await client.GetPackageContentStreamOrNullAsync(packageId, packageVersion, cancellationToken);
+                return await client.DownloadPackageOrNullAsync(packageId, packageVersion, cancellationToken);
             }
 
-            public async Task<Stream> GetPackageManifestStreamOrNullAsync(
+            public async Task<Stream> DownloadPackageManifestOrNullAsync(
                 string packageId,
                 NuGetVersion packageVersion,
                 CancellationToken cancellationToken = default)
             {
                 var client = await _clientfactory.GetPackageContentClientAsync(cancellationToken);
 
-                return await client.GetPackageManifestStreamOrNullAsync(packageId, packageVersion, cancellationToken);
+                return await client.DownloadPackageManifestOrNullAsync(packageId, packageVersion, cancellationToken);
             }
 
             public async Task<PackageVersionsResponse> GetPackageVersionsOrNullAsync(

src/BaGet.Protocol/PackageContent/RawPackageContentClient.cs

@@ -48,7 +48,7 @@ public async Task<PackageVersionsResponse> GetPackageVersionsOrNullAsync(
         }
 
         /// <inheritdoc />
-        public async Task<Stream> GetPackageContentStreamOrNullAsync(
+        public async Task<Stream> DownloadPackageOrNullAsync(
             string packageId,
             NuGetVersion packageVersion,
             CancellationToken cancellationToken = default)
@@ -69,7 +69,7 @@ public async Task<Stream> GetPackageContentStreamOrNullAsync(
         }
 
         /// <inheritdoc />
-        public async Task<Stream> GetPackageManifestStreamOrNullAsync(
+        public async Task<Stream> DownloadPackageManifestOrNullAsync(
             string packageId,
             NuGetVersion packageVersion,
             CancellationToken cancellationToken = default)

src/BaGet.Protocol/PackageMetadata/IPackageMetadataClient.cs

@@ -27,21 +27,19 @@ public interface IPackageMetadataClient
         /// </summary>
         /// <param name="pageUrl">The URL of the page, from the <see cref="RegistrationIndexResponse"/>.</param>
         /// <param name="cancellationToken">A token to cancel the task.</param>
-        /// <returns>The registration index page, or null if the page does not exist.</returns>
+        /// <returns>The registration index page.</returns>
         Task<RegistrationPageResponse> GetRegistrationPageAsync(
             string pageUrl,
             CancellationToken cancellationToken = default);
 
         /// <summary>
-        /// Get the metadata for a single package version, if the package exists.
+        /// Get the metadata for a single package version.
         /// </summary>
-        /// <param name="packageId">The package's id.</param>
-        /// <param name="packageVersion">The package's version.</param>
+        /// <param name="leafUrl">The URL of the leaf, from the <see cref="RegistrationIndexPageItem"/>.</param>
         /// <param name="cancellationToken">A token to cancel the task.</param>
-        /// <returns>The registration leaf, or null if the package does not exist.</returns>
-        Task<RegistrationLeafResponse> GetRegistrationLeafOrNullAsync(
-            string packageId,
-            NuGetVersion packageVersion,
+        /// <returns>The registration leaf.</returns>
+        Task<RegistrationLeafResponse> GetRegistrationLeafAsync(
+            string leafUrl,
             CancellationToken cancellationToken = default);
     }
 }

src/BaGet.Protocol/PackageMetadata/PackageMetadataClient.cs

@@ -35,14 +35,13 @@ public async Task<RegistrationPageResponse> GetRegistrationPageAsync(
                 return await client.GetRegistrationPageAsync(pageUrl, cancellationToken);
             }
 
-            public async Task<RegistrationLeafResponse> GetRegistrationLeafOrNullAsync(
-                string packageId,
-                NuGetVersion packageVersion,
+            public async Task<RegistrationLeafResponse> GetRegistrationLeafAsync(
+                string leafUrl,
                 CancellationToken cancellationToken = default)
             {
                 var client = await _clientfactory.GetPackageMetadataClientAsync(cancellationToken);
 
-                return await client.GetRegistrationLeafOrNullAsync(packageId, packageVersion, cancellationToken);
+                return await client.GetRegistrationLeafAsync(leafUrl, cancellationToken);
             }
         }
     }

src/BaGet.Protocol/PackageMetadata/RawPackageMetadataClient.cs

@@ -4,7 +4,6 @@
 using System.Threading;
 using System.Threading.Tasks;
 using BaGet.Protocol.Models;
-using NuGet.Versioning;
 
 namespace BaGet.Protocol.Internal
 {
@@ -54,16 +53,11 @@ public async Task<RegistrationPageResponse> GetRegistrationPageAsync(
         }
 
         /// <inheritdoc />
-        public async Task<RegistrationLeafResponse> GetRegistrationLeafOrNullAsync(
-            string packageId,
-            NuGetVersion packageVersion,
+        public async Task<RegistrationLeafResponse> GetRegistrationLeafAsync(
+            string leafUrl,
             CancellationToken cancellationToken = default)
         {
-            var id = packageId.ToLowerInvariant();
-            var version = packageVersion.ToNormalizedString().ToLowerInvariant();
-
-            var url = $"{_packageMetadataUrl}/{id}/{version}.json";
-            var response = await _httpClient.DeserializeUrlAsync<RegistrationLeafResponse>(url, cancellationToken);
+            var response = await _httpClient.DeserializeUrlAsync<RegistrationLeafResponse>(leafUrl, cancellationToken);
 
             if (response.StatusCode == HttpStatusCode.NotFound)
             {

src/BaGet.Protocol/readme.md

@@ -39,7 +39,7 @@ NuGetClient client = new NuGetClient("https://api.nuget.org/v3/index.json");
 string packageId = "Newtonsoft.Json";
 NuGetVersion packageVersion = new NuGetVersion("12.0.1");
 
-using (Stream packageStream = await client.GetPackageStreamAsync(packageId, packageVersion))
+using (Stream packageStream = await client.DownloadPackageAsync(packageId, packageVersion))
 {
     Console.WriteLine($"Downloaded package {packageId} {packageVersion}");
 }

tests/BaGet.Protocol.Tests/RawPackageMetadataClientTests.cs

@@ -82,8 +82,7 @@ public async Task GetRegistrationPageDeprecated()
         [Fact]
         public async Task GetsRegistrationLeaf()
         {
-            var version = NuGetVersion.Parse("1.0.0");
-            var result = await _target.GetRegistrationLeafOrNullAsync("Test.Package", version);
+            var result = await _target.GetRegistrationLeafAsync(TestData.RegistrationLeafListedUrl);
 
             Assert.NotNull(result);
             Assert.True(result.Listed);
@@ -103,8 +102,7 @@ public async Task GetsRegistrationLeaf()
         [Fact]
         public async Task GetsRegistrationLeafUnlisted()
         {
-            var version = NuGetVersion.Parse("2.0.0+build");
-            var result = await _target.GetRegistrationLeafOrNullAsync("Paged.Package", version);
+            var result = await _target.GetRegistrationLeafAsync(TestData.RegistrationLeafUnlistedUrl);
 
             Assert.NotNull(result);
             Assert.False(result.Listed);