Skip to content

Switch NuGet API to V3 Registration for version queries and V3 Flat Container for downloads#32

Merged
Arthurvdv merged 1 commit into
mainfrom
feature/nuget-v3-registration-api
Apr 23, 2026
Merged

Switch NuGet API to V3 Registration for version queries and V3 Flat Container for downloads#32
Arthurvdv merged 1 commit into
mainfrom
feature/nuget-v3-registration-api

Conversation

@Arthurvdv

Copy link
Copy Markdown
Member

Problem

The User-Agent: ALCops-VSCode/{version} header added in v1.3.0 does not appear in NuGet.org download statistics. Investigation revealed two issues:

  1. Downloads used the V2 API (www.nuget.org/api/v2/package/), which redirects to globalcdn.nuget.org. NuGet.org tracks download statistics from CDN logs on api.nuget.org (V3 Flat Container), so V2 downloads are not captured in the client breakdown.

  2. Version queries used the V3 Flat Container index, which returns all versions including unlisted ones. This is a latent bug: the extension could suggest unlisted versions for update.

Changes

Version queries: V3 Flat Container → V3 Registration API

  • Use the registration5-gz-semver2 hive which provides catalogEntry.listed per version
  • Filter out unlisted versions before applying channel logic (stable/beta/alpha)
  • Handle gzip-compressed responses (zlib.gunzipSync)
  • Handle paginated responses: for packages with 128+ versions, NuGet returns external page references instead of inlined data. These are now fetched in parallel via Promise.all.

Downloads: V2 → V3 Flat Container

  • URL changed from www.nuget.org/api/v2/package/{id}/{version} to api.nuget.org/v3-flatcontainer/{id}/{version}/{id}.{version}.nupkg
  • This is the CDN endpoint NuGet.org tracks for download statistics
  • Consistent with how NuGet.Client, PSResourceGet, and NuGetForUnity download packages

Code quality

  • Extracted fetchJsonWithGzip<T>() helper for reusable HTTP+gzip+JSON fetching
  • Extracted parseRegistrationIndex() as a pure testable function
  • Added 12 new unit tests (30 total, up from 18)
  • Tests cover: registration index parsing, listing status handling, paginated page fetching with mocked HTTP, URL lowercasing, error handling

Testing

  • npm run lint
  • npm run typecheck
  • npm run unit-test ✅ (30/30 pass)
  • npm run bundle

…Container

- Replace V3 Flat Container index with V3 Registration API (registration5-gz-semver2)
  for version queries, adding listing-awareness to exclude unlisted packages
- Switch package downloads from V2 API (www.nuget.org/api/v2/package/) to V3 Flat
  Container (api.nuget.org/v3-flatcontainer/), fixing User-Agent not appearing in
  NuGet.org download statistics
- Handle paginated Registration API responses for packages with 128+ versions by
  fetching external pages in parallel
- Extract fetchJsonWithGzip helper for reusable HTTP+gzip+JSON fetching
- Extract parseRegistrationIndex as pure testable function
- Add 12 new unit tests covering registration parsing and HTTP pagination

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@Arthurvdv Arthurvdv merged commit 2a69a6b into main Apr 23, 2026
1 check passed
@Arthurvdv Arthurvdv deleted the feature/nuget-v3-registration-api branch April 23, 2026 11:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant