@vzn/vx-cache 0.0.649 → 0.0.651

package/README.md

@@ -83,18 +83,21 @@ workflow would carry a token that writes nowhere the run reads. A job
 uses a lent token over its own and never lends one on, nor any once
 its remote is off for the run.
 
+An upload answered with a 5xx or a 429, or whose connection reset, is sent again, three tries in
+all: a PUT names its hash, so a second one stores the same bytes.
+
 A refused token is said once and turns the remote off for the run; a
 refused write (a job that reads only) turns off writes alone. Any other
 refusal is a warning naming the server's own words, and the task reads
 as a miss.
 
-Every read names scopes, each a ref's hash (no ref goes on the wire
-plain). A check names the run's refs in order (its branch, then the
+Every read names scopes, each a ref, percent-encoded. A check names the run's refs in order (its branch, then the
 branch it merges into, then the default branch; on CI `github()` or
 `gitlab()` from `@vzn/vx-ci` names them, so declare it too: without it
 a run reads git's branch and the default branch only), and the first ref
-holding a hash answers it; its download names that ref. A run that reads
-no ref says so and stays local. The run asks the server's limits once
+holding a hash answers it; its download names that ref. A ref longer
+than a scope may be (512 characters, percent-encoded) is said and not
+read; the others are. A run that reads no ref says so and stays local. The run asks the server's limits once
 (`/v1/capabilities`) and checks in chunks of its `maxCheckHashes`
 lookups, all at once; a run reading more refs than one check takes
 (Workers' default is 6) spreads each hash's scopes over several. It

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-cache",
-  "version": "0.0.649",
+  "version": "0.0.651",
   "license": "MIT",
   "description": "vxCache(): a vx cache plugin for a server that speaks the vx-cache protocol, such as @vzn/vx-cache-server.",
   "keywords": [
@@ -32,7 +32,7 @@
     "jose: the tests sign the CI tokens the server checks."
   ],
   "peerDependencies": {
-    "@vzn/vx": "^0.0.649"
+    "@vzn/vx": "^0.0.651"
   },
   "repository": {
     "type": "git",

package/src/index.ts

@@ -68,6 +68,8 @@ function expiryOf(jwt: string): number {
 const LEND_MARGIN_MS = 5 * 60_000
 /** Tries of GitHub's OIDC endpoint before the remote turns off (`askOnce`). */
 const ASK_ATTEMPTS = 3
+/** A connection that dropped, not a server that answered: an upload is sent again. */
+const RESET = new Set(['ECONNRESET', 'EPIPE', 'ECONNREFUSED'])
 /** Uploads open at once; more wait. */
 const IN_FLIGHT = 4
 
@@ -103,9 +105,15 @@ function proxyHeaders(
   return out
 }
 
-/** A ref's scope, an issuer or a repository on the wire: its SHA-256's first 128 bits in hex, never the value (2026-10-25). */
-const scopeOf = (ref: string): string =>
-  new Bun.CryptoHasher('sha256').update(ref).digest('hex').slice(0, 32)
+/** An issuer or a repository on the wire: its SHA-256's first 128 bits in hex, never the value (2026-10-25). */
+const hashOf = (text: string): string =>
+  new Bun.CryptoHasher('sha256').update(text).digest('hex').slice(0, 32)
+
+/** A ref's scope on the wire: the ref, percent-encoded, its folder's name on the server (2026-11-03). */
+const scopeOf = (ref: string): string => encodeURIComponent(ref)
+
+/** The longest scope a server takes (PROTOCOL.md § Keys), so a folder's name fits a bucket's key. */
+const SCOPE_MAX = 512
 
 /**
  * A body's first `max` bytes as text, the rest cancelled unread, and
@@ -406,8 +414,8 @@ export class VxCacheLayer implements RemoteCacheLayer {
   ) {
     this.endpoint = config.url
     this.named = {
-      'vx-issuer': scopeOf(config.issuer),
-      'vx-repository': scopeOf(config.repository),
+      'vx-issuer': hashOf(config.issuer),
+      'vx-repository': hashOf(config.repository),
     }
   }
 
@@ -800,16 +808,35 @@ export class VxCacheLayer implements RemoteCacheLayer {
   private async upload(item: { hash: string; body: Blob }): Promise<void | false> {
     // Queued before the remote or its writes were turned off.
     if (this.disabled || this.writesRefused) return false
-    const res = await this.request(`/v1/artifacts/${item.hash}`, {
-      method: 'PUT',
-      body: item.body,
-      headers: { 'content-type': 'application/octet-stream' },
-      timeoutMs: this.config.uploadTimeoutMs,
-      write: true,
-      paced: true,
-    })
-    if (res === undefined) return false
-    if (!res.ok) throw await refusal(res)
+    // Sent again after a 5xx, a 429 or a reset connection, up to three tries,
+    // as the token's ask: the server failing to read GitHub's keys once, and
+    // one ECONNRESET, each lost a DTE worker's entry (2026-10-29). A PUT
+    // names its hash, so a second one stores the same bytes. A deadline is
+    // not retried: the upload already had its time.
+    for (let attempt = 1; ; attempt++) {
+      let res: Response | undefined
+      try {
+        res = await this.request(`/v1/artifacts/${item.hash}`, {
+          method: 'PUT',
+          body: item.body,
+          headers: { 'content-type': 'application/octet-stream' },
+          timeoutMs: this.config.uploadTimeoutMs,
+          write: true,
+          paced: true,
+        })
+      } catch (err) {
+        if (!RESET.has((err as { code?: unknown }).code as string) || attempt === ASK_ATTEMPTS)
+          throw err
+        await this.wait(1000 * attempt)
+        continue
+      }
+      if (res === undefined) return false
+      if (res.ok) return
+      if ((res.status !== 429 && res.status < 500) || attempt === ASK_ATTEMPTS)
+        throw await refusal(res)
+      await res.body?.cancel()
+      await this.wait(1000 * attempt)
+    }
   }
 }
 
@@ -828,6 +855,11 @@ function namedOf(options: VxCacheOptions): { issuer: string; repository: string
 /** The longest delay a timer holds. */
 const MAX_TIMER_MS = 2 ** 31 - 1
 
+/** `url` as a refusal may print it: a `user:pass@` would reach the CI log. */
+function shown(url: string): string {
+  return url.replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/?#]*@/i, '$1***@')
+}
+
 /**
  * https, or http to this machine: every request carries the CI token, and
  * http:// to another host sent it in clear.
@@ -851,11 +883,13 @@ export function resolveVxCacheConfig(
   const from = options.url === undefined ? 'VX_CACHE_URL' : 'url'
   if (!secure(url))
     throw new UserError(
-      `vxCache(): ${from} must be https (http only to 127.0.0.1, ::1 or localhost), got ${url}`,
+      `vxCache(): ${from} must be https (http only to 127.0.0.1, ::1 or localhost), got ${shown(url)}`,
     )
   // Each route is the url's /v1/…: one that names /v1 asked /v1/v1/…, and every answer was a 404.
   if (url.endsWith('/v1'))
-    throw new UserError(`vxCache(): ${from} is the server's base, without /v1: ${url.slice(0, -3)}`)
+    throw new UserError(
+      `vxCache(): ${from} is the server's base, without /v1: ${shown(url.slice(0, -3))}`,
+    )
   return {
     url,
     ...named,
@@ -922,14 +956,24 @@ export function vxCache(options: VxCacheOptions): VxPlugin {
             ? '[vx] vx-cache: this job gets no OIDC token (give it `permissions: id-token: write`): it reads only'
             : '[vx] vx-cache: no CI token for the cache server (name an id_tokens entry VX_CACHE_TOKEN): it reads only',
         )
-      if (ctx.refs.length === 0) {
+      // A scope the server cannot name was a 400 on every check, and the
+      // run read nothing, its base branch's artifacts too.
+      const refs = [...new Set(ctx.refs)].filter((ref) => {
+        const length = scopeOf(ref).length
+        if (length <= SCOPE_MAX) return true
+        ctx.warn(
+          `[vx] vx-cache: ${ref} is ${length} characters percent-encoded, over the ${SCOPE_MAX} a cache folder's name takes: the run does not read it`,
+        )
+        return false
+      })
+      if (refs.length === 0) {
         ctx.warn(
           '[vx] vx-cache: the run reads no ref, so it names no key; remote cache off for this run',
         )
         return undefined
       }
       const layer = new VxCacheLayer(config)
-      layer.refs = [...new Set(ctx.refs)]
+      layer.refs = refs
       layer.lent = ctx.lent
       layer.warn = ctx.warn
       return layer