From 5cd32c168b23a29ee0e6a16d69eeddbbab932808 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Sharma?= Date: Sun, 10 May 2020 16:45:58 -0700 Subject: [PATCH] [SDK] Usability improvements (#516) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 | 2 +- samples/Sample01_Download.cs | 4 +-- src/BaGet.Core/Mirror/MirrorService.cs | 2 +- .../{ => Models}/ResponseAndResult.cs | 0 src/BaGet.Protocol/NuGetClient.cs | 27 +++++++++++++------ .../PackageContent/IPackageContentClient.cs | 4 +-- .../PackageContent/PackageContentClient.cs | 8 +++--- .../PackageContent/RawPackageContentClient.cs | 4 +-- .../PackageMetadata/IPackageMetadataClient.cs | 14 +++++----- .../PackageMetadata/PackageMetadataClient.cs | 7 +++-- .../RawPackageMetadataClient.cs | 12 +++------ src/BaGet.Protocol/readme.md | 2 +- .../RawPackageMetadataClientTests.cs | 6 ++--- 13 files changed, 46 insertions(+), 46 deletions(-) rename src/BaGet.Protocol/{ => Models}/ResponseAndResult.cs (100%) diff --git a/docs/tools/sdk.md b/docs/tools/sdk.md index b6ef2426..1c41e180 100644 --- a/docs/tools/sdk.md +++ b/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}"); } diff --git a/samples/Sample01_Download.cs b/samples/Sample01_Download.cs index e1d21273..e3488f9a 100644 --- a/samples/Sample01_Download.cs +++ b/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"); } diff --git a/src/BaGet.Core/Mirror/MirrorService.cs b/src/BaGet.Core/Mirror/MirrorService.cs index 1b8d3e1e..88bebadc 100644 --- a/src/BaGet.Core/Mirror/MirrorService.cs +++ b/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(); } diff --git a/src/BaGet.Protocol/ResponseAndResult.cs b/src/BaGet.Protocol/Models/ResponseAndResult.cs similarity index 100% rename from src/BaGet.Protocol/ResponseAndResult.cs rename to src/BaGet.Protocol/Models/ResponseAndResult.cs diff --git a/src/BaGet.Protocol/NuGetClient.cs b/src/BaGet.Protocol/NuGetClient.cs index 7b3c9964..775cceb5 100644 --- a/src/BaGet.Protocol/NuGetClient.cs +++ b/src/BaGet.Protocol/NuGetClient.cs @@ -12,7 +12,7 @@ namespace BaGet.Protocol { /// - /// The allows you to interact with a NuGet server. + /// The client to interact with a NuGet server. /// public class NuGetClient { @@ -114,9 +114,9 @@ public virtual async Task ExistsAsync( /// /// The package could not be found. /// - public virtual async Task GetPackageStreamAsync(string packageId, NuGetVersion packageVersion, CancellationToken cancellationToken = default) + public virtual async Task 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 GetPackageStreamAsync(string packageId, NuGetV /// /// The package could not be found. /// - public virtual async Task GetPackageManifestStreamAsync(string packageId, NuGetVersion packageVersion, CancellationToken cancellationToken = default) + public virtual async Task 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> ListPackageVersionsAsync( /// Whether to include unlisted versions. /// A token to cancel the task. /// The package's versions, or an empty list if the package does not exist. - public virtual async Task> ListPackageVersionsAsync(string packageId, bool includeUnlisted, CancellationToken cancellationToken = default) + public virtual async Task> ListPackageVersionsAsync( + string packageId, + bool includeUnlisted, + CancellationToken cancellationToken = default) { if (!includeUnlisted) { @@ -195,7 +201,9 @@ public virtual async Task> ListPackageVersionsAsync( /// The package ID. /// A token to cancel the task. /// The package's metadata, or an empty list if the package does not exist. - public virtual async Task> GetPackageMetadataAsync(string packageId, CancellationToken cancellationToken = default) + public virtual async Task> GetPackageMetadataAsync( + string packageId, + CancellationToken cancellationToken = default) { var result = new List(); @@ -240,7 +248,10 @@ public virtual async Task> GetPackageMetadataAsyn /// /// The package could not be found. /// - public virtual async Task GetPackageMetadataAsync(string packageId, NuGetVersion packageVersion, CancellationToken cancellationToken = default) + public virtual async Task GetPackageMetadataAsync( + string packageId, + NuGetVersion packageVersion, + CancellationToken cancellationToken = default) { var registrationIndex = await _metadataClient.GetRegistrationIndexOrNullAsync(packageId, cancellationToken); diff --git a/src/BaGet.Protocol/PackageContent/IPackageContentClient.cs b/src/BaGet.Protocol/PackageContent/IPackageContentClient.cs index 12321b44..33422254 100644 --- a/src/BaGet.Protocol/PackageContent/IPackageContentClient.cs +++ b/src/BaGet.Protocol/PackageContent/IPackageContentClient.cs @@ -34,7 +34,7 @@ Task GetPackageVersionsOrNullAsync( /// /// The package's content stream, or null if the package does not exist. The stream may not be seekable. /// - Task GetPackageContentStreamOrNullAsync( + Task DownloadPackageOrNullAsync( string packageId, NuGetVersion packageVersion, CancellationToken cancellationToken = default); @@ -49,7 +49,7 @@ Task GetPackageContentStreamOrNullAsync( /// /// The package's manifest stream, or null if the package does not exist. The stream may not be seekable. /// - Task GetPackageManifestStreamOrNullAsync( + Task DownloadPackageManifestOrNullAsync( string packageId, NuGetVersion packageVersion, CancellationToken cancellationToken = default); diff --git a/src/BaGet.Protocol/PackageContent/PackageContentClient.cs b/src/BaGet.Protocol/PackageContent/PackageContentClient.cs index c151a5ab..a42c00fd 100644 --- a/src/BaGet.Protocol/PackageContent/PackageContentClient.cs +++ b/src/BaGet.Protocol/PackageContent/PackageContentClient.cs @@ -18,24 +18,24 @@ public PackageContentClient(NuGetClientFactory clientFactory) _clientfactory = clientFactory ?? throw new ArgumentNullException(nameof(clientFactory)); } - public async Task GetPackageContentStreamOrNullAsync( + public async Task 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 GetPackageManifestStreamOrNullAsync( + public async Task 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 GetPackageVersionsOrNullAsync( diff --git a/src/BaGet.Protocol/PackageContent/RawPackageContentClient.cs b/src/BaGet.Protocol/PackageContent/RawPackageContentClient.cs index 15db69e9..87bf27b3 100644 --- a/src/BaGet.Protocol/PackageContent/RawPackageContentClient.cs +++ b/src/BaGet.Protocol/PackageContent/RawPackageContentClient.cs @@ -48,7 +48,7 @@ public async Task GetPackageVersionsOrNullAsync( } /// - public async Task GetPackageContentStreamOrNullAsync( + public async Task DownloadPackageOrNullAsync( string packageId, NuGetVersion packageVersion, CancellationToken cancellationToken = default) @@ -69,7 +69,7 @@ public async Task GetPackageContentStreamOrNullAsync( } /// - public async Task GetPackageManifestStreamOrNullAsync( + public async Task DownloadPackageManifestOrNullAsync( string packageId, NuGetVersion packageVersion, CancellationToken cancellationToken = default) diff --git a/src/BaGet.Protocol/PackageMetadata/IPackageMetadataClient.cs b/src/BaGet.Protocol/PackageMetadata/IPackageMetadataClient.cs index ee18e941..e417effd 100644 --- a/src/BaGet.Protocol/PackageMetadata/IPackageMetadataClient.cs +++ b/src/BaGet.Protocol/PackageMetadata/IPackageMetadataClient.cs @@ -27,21 +27,19 @@ public interface IPackageMetadataClient /// /// The URL of the page, from the . /// A token to cancel the task. - /// The registration index page, or null if the page does not exist. + /// The registration index page. Task GetRegistrationPageAsync( string pageUrl, CancellationToken cancellationToken = default); /// - /// Get the metadata for a single package version, if the package exists. + /// Get the metadata for a single package version. /// - /// The package's id. - /// The package's version. + /// The URL of the leaf, from the . /// A token to cancel the task. - /// The registration leaf, or null if the package does not exist. - Task GetRegistrationLeafOrNullAsync( - string packageId, - NuGetVersion packageVersion, + /// The registration leaf. + Task GetRegistrationLeafAsync( + string leafUrl, CancellationToken cancellationToken = default); } } diff --git a/src/BaGet.Protocol/PackageMetadata/PackageMetadataClient.cs b/src/BaGet.Protocol/PackageMetadata/PackageMetadataClient.cs index adb21a86..9406e519 100644 --- a/src/BaGet.Protocol/PackageMetadata/PackageMetadataClient.cs +++ b/src/BaGet.Protocol/PackageMetadata/PackageMetadataClient.cs @@ -35,14 +35,13 @@ public async Task GetRegistrationPageAsync( return await client.GetRegistrationPageAsync(pageUrl, cancellationToken); } - public async Task GetRegistrationLeafOrNullAsync( - string packageId, - NuGetVersion packageVersion, + public async Task 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); } } } diff --git a/src/BaGet.Protocol/PackageMetadata/RawPackageMetadataClient.cs b/src/BaGet.Protocol/PackageMetadata/RawPackageMetadataClient.cs index 53fd02ed..8d19023e 100644 --- a/src/BaGet.Protocol/PackageMetadata/RawPackageMetadataClient.cs +++ b/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 GetRegistrationPageAsync( } /// - public async Task GetRegistrationLeafOrNullAsync( - string packageId, - NuGetVersion packageVersion, + public async Task 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(url, cancellationToken); + var response = await _httpClient.DeserializeUrlAsync(leafUrl, cancellationToken); if (response.StatusCode == HttpStatusCode.NotFound) { diff --git a/src/BaGet.Protocol/readme.md b/src/BaGet.Protocol/readme.md index d1b9592a..b8c36fc3 100644 --- a/src/BaGet.Protocol/readme.md +++ b/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}"); } diff --git a/tests/BaGet.Protocol.Tests/RawPackageMetadataClientTests.cs b/tests/BaGet.Protocol.Tests/RawPackageMetadataClientTests.cs index 97c727b9..352ca31e 100644 --- a/tests/BaGet.Protocol.Tests/RawPackageMetadataClientTests.cs +++ b/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);