@vzn/vx-cache 0.0.650 → 0.0.652

package/README.md

@@ -31,7 +31,8 @@ export default {
 
 - `url` is the server's base URL (`https://cache.example.com`, without `/v1`), or `VX_CACHE_URL`.
   It must be `https://`: every request carries the CI token, so `http://`
-  is taken only to this machine (`127.0.0.1`, `::1`, `localhost`). The
+  is taken only to this machine (`127.0.0.1`, `::1`, `localhost`). It
+  takes no `?query` or `#fragment`: each route is appended to it. The
   option is checked when the config loads, `VX_CACHE_URL` when a run
   opens the cache.
 - `issuer` (the CI issuer's URL, as its tokens name it) and `repository`
@@ -83,7 +84,7 @@ 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 is sent again, three tries in
+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
@@ -91,13 +92,13 @@ 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.650",
+  "version": "0.0.652",
   "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.650"
+    "@vzn/vx": "^0.0.652"
   },
   "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
@@ -140,8 +148,12 @@ async function jsonUpTo(res: Response, max: number, what: string): Promise<unkno
 
 /** Capabilities and a CI token are a few hundred bytes: room to spare. */
 const SMALL_ANSWER_BYTES = 64 * 1024
-/** A check's answer per hash asked: a hash, a size and a scope in JSON are under 150 bytes. */
-const CHECK_BYTES_PER_HASH = 512
+/**
+ * A check's answer per hash asked: a hash (up to 128), a size and a scope
+ * (up to 512, a long branch's) in JSON are under 700 bytes. At 512 an
+ * answer under the longest scopes was refused as too long.
+ */
+const CHECK_BYTES_PER_HASH = 1024
 
 /**
  * `s` with each C0/C1 control and DEL written as `\xNN`: a server's words
@@ -406,8 +418,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,18 +812,28 @@ 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
-    // Sent again after a 5xx or a 429, up to three tries, as the token's ask:
-    // the server failing to read GitHub's keys once lost a DTE worker's entry
-    // (2026-10-29). A PUT names its hash, so a second one stores the same bytes.
+    // 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++) {
-      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,
-      })
+      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)
@@ -837,15 +859,22 @@ 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.
  */
 function secure(url: string): boolean {
-  if (/^https:\/\/\S/.test(url)) return true
-  if (!/^http:\/\/\S/.test(url)) return false
-  const host = URL.parse(url)?.hostname
-  return host === '127.0.0.1' || host === '[::1]' || host === 'localhost'
+  // Parsed as the request will be: a scheme in any case, no url it cannot carry.
+  const u = URL.parse(url)
+  if (u === null || u.host === '') return false
+  if (u.protocol === 'https:') return true
+  if (u.protocol !== 'http:') return false
+  return u.hostname === '127.0.0.1' || u.hostname === '[::1]' || u.hostname === 'localhost'
 }
 
 /** Options over `VX_CACHE_URL`; `undefined`: no server named. */
@@ -860,11 +889,19 @@ 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 appended to the url: past a `?` or `#` it was query or
+  // fragment, and every request asked the server's root.
+  if (/[?#]/.test(url))
+    throw new UserError(
+      `vxCache(): ${from} takes no ?query or #fragment: each route is appended to it, 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,
@@ -931,14 +968,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