feat: resolve latest patch for a major.minor version (#293)

* feat: resolve latest patch for a major.minor version Allow the version input and version-file entries to be a major.minor value like 3.14 / v3.14, resolving to the newest available patch (e.g. v3.14.4). Resolution probes the download host directly: sequential HEAD requests for helm-v{major}.{minor}.{n} against downloadBaseURL, taking the highest that returns 200. Works with any file-serving mirror and needs no token or extra dependency, and cannot resolve to a version that is not downloadable. Only major.minor.n URLs are probed, so prereleases are never considered. - Add isMajorMinorShaped, helmPatchExists, and resolveLatestPatchVersion. - Walk stops after 3 consecutive 404s (look-ahead) to tolerate a skipped patch number, with a 100-probe safety cap; hitting the cap throws instead of returning a bogus version. - Wire resolution into run() and relax getVersionFromToolVersionsFile to accept a major.minor value. * feat: support .x/.* wildcards and harden patch probing Extend the major.minor latest-patch resolution to accept wildcard patch syntax (`3.12.x`, `v3.12.x`, `3.12.*`), matching the syntax requested in Azure/setup-helm#109. The following smaller fixes were made based on Copilot review feedback: - helmPatchExists now treats only 404 as "patch absent"; any other non-2xx status (403/405/429/5xx) and network errors are thrown, so rate-limiting, outages, or a host that disallows HEAD can no longer be misread as a missing patch (which could yield a stale version or a false "No Helm releases found"). - Clarify the version-file validation error to reflect that both a full version and a major.minor value are accepted, with concrete examples. - Tests: use vi.spyOn(globalThis, 'fetch') instead of vi.stubGlobal so restoreAllMocks() reliably restores fetch and the mock never leaks across tests; add coverage for wildcards and the non-404 throw path. * ### feat: single-request listing fast-path + semver.org validation **Listing fast-path (with fallback).** Following the discussion about enumeration, `resolveLatestPatchVersion` now first tries a single Azure Blob container-listing request against the download host (which `get.helm.sh` backs), and only falls back to the sequential HEAD-probe walk if the host doesn't return a valid listing. Enumeration and download stay on the **same host**, so there's no risk of resolving a version the host can't serve, and it still works on any mirror. - Default host: resolution now takes **1 request** instead of ~8 probes (verified live: `3.9`→`v3.9.4`, `3.12`→`v3.12.3`, `3.14`→`v3.14.4`, `3.16`→`v3.16.4`, `2.17`→`v2.17.0`). - Non-listing hosts fall back to probing; prereleases and `.sha256` sidecars are excluded from the listing parse. **semver.org regex.** Per review feedback, `isSemVerShaped` now uses the official regex from semver.org (with an added optional leading `v` for Helm tags) instead of the hand-rolled one. Added tests for the listing fast-path, the fallback, and a non-listing response; full suite is green (`npm test`, `typecheck`, `format-check`).
2026-08-03 17:04:25 +00:00 · 2026-07-20 12:27:29 -07:00
parent 78f94bcee2
commit 249bb27705
3 changed files with 384 additions and 18 deletions
@@ -31,15 +31,17 @@ export async function run() {
      version = 'latest'
   }

-   if (version !== 'latest' && version[0] !== 'v') {
+   const downloadBaseURL = core.getInput('downloadBaseURL', {required: false})
+
+   if (version.toLocaleLowerCase() === 'latest') {
+      version = await getLatestHelmVersion()
+   } else if (isMajorMinorShaped(version)) {
+      version = await resolveLatestPatchVersion(downloadBaseURL, version)
+      core.info(`Resolved latest patch Helm version to '${version}'`)
+   } else if (version[0] !== 'v') {
      version = getValidVersion(version)
      core.info(`Normalized Helm version to '${version}'`)
   }
-   if (version.toLocaleLowerCase() === 'latest') {
-      version = await getLatestHelmVersion()
-   }
-
-   const downloadBaseURL = core.getInput('downloadBaseURL', {required: false})

   core.startGroup(`Installing ${version}`)
   const cachedPath = await downloadHelm(downloadBaseURL, version)
@@ -62,16 +64,29 @@ export function getValidVersion(version: string): string {
   return 'v' + version
 }

-// Matches a semantic version (major.minor.patch) with an optional leading 'v'
-// and optional pre-release / build-metadata suffixes, e.g. '3.14.0', 'v3.14.0',
-// '3.14.0-rc.1'.
-const semVerShape = /^v?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/
+// Matches a complete semantic version (major.minor.patch with optional
+// pre-release / build metadata). This is the official regex suggested at
+// https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
+// with an added optional leading 'v' to accept Helm-style tags (e.g. 'v3.14.0').
+const semVerShape =
+   /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/

 // Returns true when version looks like a semantic version
 export function isSemVerShaped(version: string): boolean {
   return semVerShape.test(version)
 }

+// Matches a major.minor version with an optional leading 'v' and either no
+// patch component or a wildcard patch ('.x' / '.*'), e.g. '3.14', 'v3.14',
+// '3.14.x', 'v3.14.*'.
+const majorMinorShape = /^v?\d+\.\d+(?:\.[x*])?$/
+
+// Returns true when version is a major.minor value (optionally with a wildcard
+// patch such as '.x' or '.*')
+export function isMajorMinorShaped(version: string): boolean {
+   return majorMinorShape.test(version)
+}
+
 // Reads a .tool-versions file and returns the helm version declared in it
 export function getVersionFromToolVersionsFile(filePath: string): string {
   if (!fs.existsSync(filePath)) {
@@ -82,9 +97,9 @@ export function getVersionFromToolVersionsFile(filePath: string): string {
   if (!version) {
      throw new Error(`No helm version found in '${filePath}'`)
   }
-   if (!isSemVerShaped(version)) {
+   if (!isSemVerShaped(version) && !isMajorMinorShaped(version)) {
      throw new Error(
-         `The helm version '${version}' in '${filePath}' is not a valid semantic version`
+         `The helm version '${version}' in '${filePath}' is not valid. Provide a full version (e.g. '3.14.0') or a major.minor version (e.g. '3.14' or '3.14.x')`
      )
   }
   return version
@@ -121,6 +136,130 @@ export async function getLatestHelmVersion(): Promise<string> {
   }
 }

+// Number of consecutive missing patches to probe before concluding the walk,
+// and an upper bound to keep resolution from running unbounded.
+const patchLookahead = 3
+const maxPatch = 100
+
+// Sends a HEAD request for the given version's download URL. Returns true when
+// the artifact exists (2xx) and false only when it is definitively absent
+// (404). Any other status (403/405/429/5xx, ...) and genuine network errors are
+// thrown, so transient failures, rate-limiting, or a host that disallows HEAD
+// are never mistaken for a missing patch.
+export async function helmPatchExists(
+   baseURL: string,
+   version: string
+): Promise<boolean> {
+   const url = getHelmDownloadURL(baseURL, version)
+   const response = await fetch(url, {method: 'HEAD'})
+   if (response.ok) {
+      return true
+   }
+   if (response.status === 404) {
+      return false
+   }
+   throw new Error(
+      `Unexpected HTTP ${response.status} while checking for Helm artifact at ${url}`
+   )
+}
+
+// Attempts to resolve the latest patch in a single request via the Azure Blob
+// container-listing API that backs get.helm.sh. Returns the newest stable patch
+// version, or null when the host does not support listing (any non-listing
+// response, empty result, or error) so the caller can fall back to probing.
+// Only 'major.minor.patch-<platform>' names are matched, so prereleases and
+// sidecar files (.sha256, ...) are ignored.
+export async function resolveLatestPatchViaListing(
+   baseURL: string,
+   major: string,
+   minor: string
+): Promise<string | null> {
+   let body: string
+   try {
+      const listURL = new URL(baseURL)
+      listURL.searchParams.set('restype', 'container')
+      listURL.searchParams.set('comp', 'list')
+      listURL.searchParams.set('prefix', `helm-v${major}.${minor}.`)
+      const response = await fetch(listURL.toString())
+      if (!response.ok) {
+         return null
+      }
+      body = await response.text()
+   } catch {
+      return null
+   }
+
+   if (!body.includes('<EnumerationResults')) {
+      return null
+   }
+
+   const patchPattern = new RegExp(
+      `helm-v${major}\\.${minor}\\.(\\d+)-(?:darwin|linux|windows)`,
+      'g'
+   )
+   let latestPatch = -1
+   for (const match of body.matchAll(patchPattern)) {
+      const patch = Number(match[1])
+      if (patch > latestPatch) {
+         latestPatch = patch
+      }
+   }
+
+   if (latestPatch < 0) {
+      return null
+   }
+   return `v${major}.${minor}.${latestPatch}`
+}
+
+// Resolves a major.minor value (e.g. '3.14' or 'v3.14') to the newest available
+// patch (e.g. 'v3.14.4'). Fast path: a single container-listing request (which
+// get.helm.sh supports). When the host does not support listing, it falls back
+// to probing the download host for sequential patches. Only 'major.minor.n'
+// artifacts are considered, so prereleases are never selected.
+export async function resolveLatestPatchVersion(
+   baseURL: string,
+   version: string
+): Promise<string> {
+   const [major, minor] = (
+      version[0] === 'v' ? version.slice(1) : version
+   ).split('.')
+
+   const listed = await resolveLatestPatchViaListing(baseURL, major, minor)
+   if (listed) {
+      return listed
+   }
+
+   if (!(await helmPatchExists(baseURL, `v${major}.${minor}.0`))) {
+      throw new Error(`No Helm releases found for ${major}.${minor}`)
+   }
+
+   let latestPatch = 0
+   let consecutiveMisses = 0
+   for (
+      let patch = 1;
+      patch <= maxPatch && consecutiveMisses < patchLookahead;
+      patch++
+   ) {
+      if (await helmPatchExists(baseURL, `v${major}.${minor}.${patch}`)) {
+         latestPatch = patch
+         consecutiveMisses = 0
+      } else {
+         consecutiveMisses++
+      }
+   }
+
+   // The look-ahead is what should end the walk. Exhausting maxPatch without a
+   // trailing run of misses means the host answered 200 for every probe (e.g. a
+   // catch-all mirror), so the resolved version cannot be trusted.
+   if (consecutiveMisses < patchLookahead) {
+      throw new Error(
+         `Unable to resolve latest patch for ${major}.${minor} (exceeded ${maxPatch} probes)`
+      )
+   }
+
+   return `v${major}.${minor}.${latestPatch}`
+}
+
 export function getArch(): string {
   return os.arch() === 'x64' ? 'amd64' : os.arch()
 }