Skip to content

fix: order versions by createTime desc so latest is reachable on >1000-version packages#6

Open
vladimirtomecko wants to merge 1 commit into
rolang:masterfrom
vladimirtomecko:orderby-createtime-desc
Open

fix: order versions by createTime desc so latest is reachable on >1000-version packages#6
vladimirtomecko wants to merge 1 commit into
rolang:masterfrom
vladimirtomecko:orderby-createtime-desc

Conversation

@vladimirtomecko
Copy link
Copy Markdown

Problem

GAR's versions.list endpoint:

  • Defaults to ASC ordering by createTime (oldest first).
  • Server-side caps pageSize at 1,000 regardless of requested value (documented at the link above: "Maximum page size is 1,000.").

The existing single-page fetch in ArtifactRegistryUrlConnection always returns the oldest 1,000 versions for any package that has more than 1,000 versions. The newest releases are unreachable, so the synthesized maven-metadata.xml ends up with stale <latest> / <release> values and downstream consumers (Coursier, sbt, Scala Steward, etc.) silently never see new versions.

Real-world example from our org: a Maven artifact had 1,343 published versions in GAR; the latest in maven-metadata.xml came back as a version that was several months old, while the actual newest version (released hours earlier) was invisible. Scala Steward did not propose any bump and silently skipped the dependency on every run.

Fix

Add orderBy=createTime desc to the versions.list request. The first (and, in practice, only) page now contains the newest 1,000 versions, which is what Maven-metadata consumers need to resolve the latest version.

       newUrl.put("fields", "versions.name,versions.createTime")
       newUrl.put("pageSize", 1000)
+      // Default ASC ordering hides the latest versions on packages with >1000 versions (server-side pageSize cap is 1000).
+      newUrl.put("orderBy", "createTime desc")

Why this syntax should be correct

  • orderBy is documented as a query param on versions.list (Optional. The field to order the results by.).
  • <field> desc suffix is the standard Google list-ordering syntax defined in AIP-132:

    Values should be a comma separated list of fields. For example: \"foo,bar\".
    To specify descending order for a field, users append a \" desc\" suffix; for example: \"foo desc, bar\".

  • createTime is a documented field on the Version resource.

Verification

Probed live against a GAR repo (pageSize=10):

Without orderBy:

0.0.100 (2023-08-22)
0.0.101 (2023-08-24)
0.0.103 (2023-09-05)
...

With orderBy=createTime desc:

1.863.6 (2026-05-21)
1.863.5 (2026-05-21)
1.863.4 (2026-05-21)
...

Tried pageSize=2000, 5000, 10000 — server returns at most 1,000 items in every case (matches docs), so the only correct fix for the "hide latest" symptom is to flip the ordering.

Scope / non-goals

This is the minimal change that unblocks consumers for the "resolve latest version" use case, which covers all Maven-metadata usage of the URL handler.

Resolving a specific old version that is older than the newest 1,000 still requires the consumer to know the exact version (Coursier already passes the version directly in the artifact URL — only metadata listings hit versions.list). Full pagination via nextPageToken could be added later as an additive change; this PR is deliberately limited to the one-line fix that resolves the latest-version bug.

…0-version packages

GAR's versions.list endpoint defaults to ASC ordering by createTime and
caps server-side pageSize at 1000 regardless of requested value. For any
package with more than 1000 versions, the existing single-page fetch
returns the oldest 1000 — the newest releases are unreachable, so the
synthesized maven-metadata.xml advertises stale `<latest>` / `<release>`
values and Coursier/sbt consumers (and downstream tools like Scala
Steward) never see new versions.

Adding `orderBy=createTime desc` flips the first page to newest-first,
so the most recent 1000 versions are visible — sufficient for the
"resolve latest version" use case that Maven metadata is built for.

The `desc` suffix follows the standard Google list-ordering syntax
defined in AIP-132. `createTime` is a documented sortable field on
the GAR Version resource.

Docs:
- versions.list reference (states "Maximum page size is 1,000"):
  https://cloud.google.com/artifact-registry/docs/reference/rest/v1/projects.locations.repositories.packages.versions/list
- AIP-132 (List), section on order_by syntax with `desc` suffix:
  https://google.aip.dev/132

Verified empirically against a live GAR repo: with the parameter,
versions.list returns 1.863.6, 1.863.5, 1.863.4, ... (newest first);
without it, the same call returns 0.0.100, 0.0.101, ... (oldest first).
@Awethon
Copy link
Copy Markdown

Awethon commented May 22, 2026

@rolang, could you please take a look?

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.

2 participants