@vzn/vx-reapi 0.0.646 → 0.0.648

package/src/wire.ts

@@ -5,6 +5,7 @@
 
 import * as grpc from '@grpc/grpc-js'
 import * as protoLoader from '@grpc/proto-loader'
+import { AsyncLocalStorage } from 'node:async_hooks'
 import path from 'node:path'
 import {
   canDigest,
@@ -15,6 +16,7 @@ import {
   strField,
   type DigestFunctionName,
 } from './merkle.js'
+import { ui } from '@vzn/vx'
 
 /**
  * Default bytes per ByteStream message.
@@ -48,8 +50,11 @@ export const CHUNK_BYTES = 65535
  */
 export const SAFE_CHUNK_BYTES = 65535
 
-/** The oldest Bun whose http2 client survives a CHUNK_BYTES-sized message. */
-export const MIN_BUN = [1, 4, 0] as const
+/**
+ * The package's Bun floor (`engines.bun`). Its http2 client survives a
+ * CHUNK_BYTES-sized message from 1.4.0 on; the floor is core's, 1.4.4.
+ */
+export const MIN_BUN = [1, 4, 4] as const
 
 /**
  * Refuse to run on a Bun that would hang instead of uploading. A version this
@@ -165,7 +170,7 @@ async function unzstdBounded(data: Uint8Array, digest: Digest): Promise<Uint8Arr
 /** More bytes than the digest declares, refused before the rest arrive. */
 const overServed = (digest: Digest): Error =>
   new Error(
-    `@vzn/vx-reapi: blob integrity failure for ${digest.hash.slice(0, 16)}…: ` +
+    `blob integrity failure for ${digest.hash.slice(0, 16)}…: ` +
       `served past its declared ${digest.size_bytes} bytes`,
   )
 
@@ -180,7 +185,7 @@ const wireBound = (size: number): number => size + (size >> 8) + 1024
 function assertServed(size: number, hash: (() => string) | undefined, digest: Digest): void {
   if (size !== Number(digest.size_bytes)) {
     throw new Error(
-      `@vzn/vx-reapi: blob integrity failure for ${digest.hash.slice(0, 16)}…: ` +
+      `blob integrity failure for ${digest.hash.slice(0, 16)}…: ` +
         `size ${size} != declared ${digest.size_bytes}`,
     )
   }
@@ -188,7 +193,7 @@ function assertServed(size: number, hash: (() => string) | undefined, digest: Di
   const got = hash()
   if (got !== digest.hash) {
     throw new Error(
-      `@vzn/vx-reapi: blob integrity failure: bytes hash to ${got.slice(0, 16)}… ` +
+      `blob integrity failure: bytes hash to ${got.slice(0, 16)}… ` +
         `but were served for digest ${digest.hash.slice(0, 16)}…`,
     )
   }
@@ -305,11 +310,17 @@ function isRetryable(code: number | undefined): boolean {
   )
 }
 
+/** grpc-js ends an UNAVAILABLE with `Resolution note: ` and nothing after it. */
+function spent(err: unknown): unknown {
+  if (err instanceof Error) err.message = err.message.replace(/\s*Resolution note:\s*$/, '')
+  return err
+}
+
 const RETRY_DELAYS_MS = [100, 400, 1600]
 
 const deadlineOf = (bounds: grpc.CallOptions): number => (bounds.deadline as Date).getTime()
 
-const executionAborted = (): Error => new Error('reapi: execution aborted')
+const executionAborted = (): Error => new Error('execution aborted')
 
 /** A backoff an abort ends at once: the caller's deadline may fire mid-wait. */
 function abortableSleep(ms: number, signal: AbortSignal | undefined): Promise<void> {
@@ -328,6 +339,13 @@ function abortableSleep(ms: number, signal: AbortSignal | undefined): Promise<vo
 
 const NOT_FOUND = grpc.status.NOT_FOUND
 
+/**
+ * The action a call is made for, per async context: one client serves every
+ * task of a run at once, and a field on it named, on each action's uploads,
+ * whichever action had set it last.
+ */
+const currentAction = new AsyncLocalStorage<{ id: string }>()
+
 export interface ReapiOptions {
   /** `host:port` of the REAPI server; TLS unless `grpc://`, `http://` or a socket. */
   endpoint: string
@@ -385,6 +403,13 @@ export interface ReapiOptions {
   chunkBytes?: number
 }
 
+/**
+ * The longest a timer waits: one past 2^31-1 ms fires after 1 ms, so a
+ * month's bound gave up at once. Every deadline option is refused past it,
+ * as core refuses such an exec.timeout.
+ */
+export const MAX_TIMER_MS = 2 ** 31 - 1
+
 /** The ceiling a derived control-plane deadline never exceeds, however far
  *  `callTimeoutMs` is raised for a bulk transfer. */
 export const META_TIMEOUT_CAP_MS = 15_000
@@ -463,7 +488,7 @@ export class ReapiClient {
   private readonly correlatedInvocationsId: string
   /** Set when a call spent its retries on UNAVAILABLE; cleared by any answer. */
   private unreachable = false
-  /** Set per action so the server can group its RPCs under one action. */
+  /** The action last named (`nameAction`); a call outside any `inAction` carries it. */
   actionId = ''
   toolInvocationId = ''
 
@@ -489,9 +514,18 @@ export class ReapiClient {
     // and quotes it in the error, so an auth header's secret reached each
     // degrade warning (item 928). Refused once, here, by key alone.
     for (const [k, v] of Object.entries(this.headers)) {
+      // A name too: refused on every call, it degraded the cache to misses
+      // and read as an unreachable server to the executor. A `-bin` name
+      // takes bytes, which a string header is not.
+      const name = k.toLowerCase()
+      if (!/^[0-9a-z_.-]+$/.test(name) || name.endsWith('-bin')) {
+        throw new Error(
+          `reapi: header name ${JSON.stringify(k)} is not one gRPC metadata can carry (lowercase letters, digits, "-", "_" and ".", not ending "-bin")`,
+        )
+      }
       if (!/^[ -~]*$/.test(v)) {
         throw new Error(
-          `reapi: header ${JSON.stringify(k)} holds a character gRPC metadata cannot carry (printable ASCII only) — check it (its value is not printed)`,
+          `reapi(): header ${JSON.stringify(k)} holds a character gRPC metadata cannot carry (printable ASCII only) — check it (its value is not printed)`,
         )
       }
     }
@@ -503,22 +537,22 @@ export class ReapiClient {
     // Derived, not required: raising `callTimeoutMs` for a big upload must
     // not silently lengthen every metadata probe too.
     this.metaTimeoutMs = opts.metaTimeoutMs ?? Math.min(this.callTimeoutMs, META_TIMEOUT_CAP_MS)
-    this.onWarn = opts.onWarn ?? (() => undefined)
-    // A zero, negative or non-number deadline ended every call as it began.
+    // No listener is no reason to say nothing.
+    this.onWarn = opts.onWarn ?? ((m) => ui.say('warn', m))
+    // A zero, negative or non-number deadline ended every call as it began,
+    // and so did one past the longest timer.
     for (const [name, ms] of [
       ['callTimeoutMs', this.callTimeoutMs],
       ['metaTimeoutMs', this.metaTimeoutMs],
     ] as const) {
-      if (!(typeof ms === 'number' && Number.isFinite(ms) && ms > 0)) {
+      if (!(typeof ms === 'number' && ms > 0 && ms <= MAX_TIMER_MS)) {
         throw new Error(
-          `@vzn/vx-reapi: ${name} must be a positive number of ms (got ${JSON.stringify(ms)})`,
+          `reapi(): ${name} must be a positive number of ms up to ${MAX_TIMER_MS} (got ${typeof ms === 'number' ? String(ms) : JSON.stringify(ms)})`,
         )
       }
     }
     if (!Number.isInteger(this.chunkBytes) || this.chunkBytes < 1) {
-      throw new Error(
-        `@vzn/vx-reapi: chunkBytes must be a positive integer (got ${this.chunkBytes})`,
-      )
+      throw new Error(`reapi(): chunkBytes must be a positive integer (got ${this.chunkBytes})`)
     }
   }
 
@@ -570,7 +604,7 @@ export class ReapiClient {
         return res
       } catch (err) {
         const delay = this.retryDelay(attempt, (err as grpc.ServiceError).code)
-        if (delay === undefined) throw err
+        if (delay === undefined) throw spent(err)
         await Bun.sleep(delay)
       }
     }
@@ -612,12 +646,24 @@ export class ReapiClient {
     const tool = concat([strField(1, this.toolName), strField(2, this.toolVersion)])
     return concat([
       tool.length === 0 ? tool : lenField(1, tool),
-      strField(2, this.actionId),
+      strField(2, currentAction.getStore()?.id ?? this.actionId),
       strField(3, this.toolInvocationId),
       strField(4, this.correlatedInvocationsId),
     ])
   }
 
+  /** Runs `fn` as one action's calls: each carries the id `nameAction` gives it there. */
+  inAction<T>(fn: () => Promise<T>): Promise<T> {
+    return currentAction.run({ id: '' }, fn)
+  }
+
+  /** Names the action of the `inAction` this runs in, so the server groups its RPCs under it. */
+  nameAction(id: string): void {
+    const scope = currentAction.getStore()
+    if (scope !== undefined) scope.id = id
+    this.actionId = id
+  }
+
   /**
    * `GetCapabilities`. `execEnabled` is what decides whether this server can
    * take an `executor` at all — a cache-only deployment (bazel-remote)
@@ -680,11 +726,10 @@ export class ReapiClient {
     if (wanted !== undefined) {
       if (!caps.digestFunctions.includes(wanted)) {
         throw new Error(
-          `@vzn/vx-reapi: server does not support digest function ${wanted} (has ${caps.digestFunctions.join(', ')})`,
+          `server does not support digest function ${wanted} (has ${caps.digestFunctions.join(', ')})`,
         )
       }
-      if (!canDigest(wanted))
-        throw new Error(`@vzn/vx-reapi: this runtime cannot compute ${wanted}`)
+      if (!canDigest(wanted)) throw new Error(`this runtime cannot compute ${wanted}`)
       this.digestFunction = wanted
     } else {
       // Default stays SHA256 even when the server advertises stronger
@@ -776,7 +821,7 @@ export class ReapiClient {
       const code = r.status?.code ?? 0
       if (code !== 0) {
         throw new Error(
-          `reapi: BatchUpdateBlobs rejected ${r.digest?.hash}: code ${code} ${r.status?.message ?? ''}`,
+          `BatchUpdateBlobs rejected ${r.digest?.hash}: code ${code} ${r.status?.message ?? ''}`,
         )
       }
     }
@@ -974,7 +1019,7 @@ export class ReapiClient {
     inline?: { stdout: boolean; files: readonly string[] },
   ): Promise<ActionResult | null> {
     try {
-      return await this.unary<ActionResult>(
+      const result = await this.unary<ActionResult>(
         this.svc.ac,
         'getActionResult',
         {
@@ -987,6 +1032,7 @@ export class ReapiClient {
         this.meta(),
         this.boundedMeta(),
       )
+      return withNumericSizes(result)
     } catch (err) {
       if ((err as grpc.ServiceError).code === NOT_FOUND) return null
       throw err
@@ -1074,13 +1120,13 @@ export class ReapiClient {
           wireBytes > chunk
         ) {
           this.onWarn(
-            `vx/reapi: chunked write of ${digest.hash.slice(0, 12)} hit the ${chunk}-byte chunk stall (Bun http2 flow control); retrying at ${SAFE_CHUNK_BYTES}`,
+            `[vx] vx-reapi: chunked write of ${digest.hash.slice(0, 12)} hit the ${chunk}-byte chunk stall (Bun http2 flow control); retrying at ${SAFE_CHUNK_BYTES}`,
           )
           chunk = SAFE_CHUNK_BYTES
           continue
         }
         const delay = this.retryDelay(attempt, code)
-        if (delay === undefined) throw err
+        if (delay === undefined) throw spent(err)
         if (!compressed) {
           // Identity path: ask how far the server got and resume there.
           const status = await this.queryWriteStatus(resource).catch(() => null)
@@ -1097,6 +1143,7 @@ export class ReapiClient {
                 this.bounded(),
               )
               return
+              // quiet: a resume that fails starts afresh; its last failure throws
             } catch {
               // fall through to a fresh attempt
             }
@@ -1144,9 +1191,7 @@ export class ReapiClient {
           // failed the upload of an input two actions share (F-44).
           const expected = compressed ? total : digest.size_bytes
           if (committed !== expected && !(compressed && (committed > 0 || committed === -1))) {
-            return reject(
-              new Error(`reapi: short write for ${digest.hash}: ${committed}/${expected}`),
-            )
+            return reject(new Error(`short write for ${digest.hash}: ${committed}/${expected}`))
           }
           resolve()
         },
@@ -1155,6 +1200,7 @@ export class ReapiClient {
     })
     // Raced against every drain wait and awaited at the end; a failure that
     // lands between the two is not an unhandled rejection.
+    // quiet: raced and awaited below, where its error throws
     done.catch(() => undefined)
     let offset = startOffset
     let first = true
@@ -1204,7 +1250,7 @@ export class ReapiClient {
         return blob
       } catch (err) {
         const delay = this.retryDelay(attempt, (err as grpc.ServiceError).code)
-        if (delay === undefined) throw err
+        if (delay === undefined) throw spent(err)
         await Bun.sleep(delay)
       }
     }
@@ -1301,7 +1347,7 @@ export class ReapiClient {
         } catch (err) {
           const code = (err as grpc.ServiceError).code
           const delay = this.retryDelay(attempt++, code)
-          if (delay === undefined) throw err
+          if (delay === undefined) throw spent(err)
           await Bun.sleep(delay)
           open(size)
         }
@@ -1397,10 +1443,10 @@ export class ReapiClient {
         // An unnamed one cannot be re-attached, and a plain Error is not
         // retried.
         if (operationName === '') {
-          throw new Error('reapi: execution stream closed before the operation finished')
+          throw new Error('execution stream closed before the operation finished')
         }
         failure = new Error(
-          `reapi: execution stream for ${operationName} closed before the operation finished`,
+          `execution stream for ${operationName} closed before the operation finished`,
         )
       } catch (err) {
         const code = (err as grpc.ServiceError).code
@@ -1484,7 +1530,7 @@ export class ReapiClient {
       stream.on('end', () => {
         signal?.removeEventListener('abort', onAbort)
         if (last === undefined)
-          return reject(new Error('reapi: execution stream closed with no operation'))
+          return reject(new Error('execution stream closed with no operation'))
         resolve(last)
       })
     })
@@ -1559,6 +1605,34 @@ export class ReapiClient {
   }
 }
 
+/**
+ * proto-loader reads an int64 as a string (`longs: String`), and every reader
+ * of a result sums and compares `size_bytes` as a number: a record replay's
+ * batch budget concatenated `"12" + 128`, so each output file was a
+ * BatchReadBlobs round trip of its own, and an empty file grafted from a
+ * record encoded its `"0"` size where the canonical form omits it.
+ */
+function withNumericSizes(result: ActionResult): ActionResult {
+  const num = <D extends Digest | null | undefined>(d: D): D =>
+    d === null || d === undefined ? d : ({ ...d, size_bytes: Number(d.size_bytes) } as D)
+  return {
+    ...result,
+    ...(result.output_files === undefined
+      ? {}
+      : { output_files: result.output_files.map((f) => ({ ...f, digest: num(f.digest) })) }),
+    ...(result.output_directories === undefined
+      ? {}
+      : {
+          output_directories: result.output_directories.map((d) => ({
+            ...d,
+            tree_digest: num(d.tree_digest),
+          })),
+        }),
+    ...(result.stdout_digest === undefined ? {} : { stdout_digest: num(result.stdout_digest) }),
+    ...(result.stderr_digest === undefined ? {} : { stderr_digest: num(result.stderr_digest) }),
+  }
+}
+
 /** google.longrunning.Operation, narrowed to what Execute returns. */
 export interface Operation {
   name: string