@vzn/vx-history 0.0.0 → 0.0.648

package/src/history-server.ts

@@ -0,0 +1,354 @@
+// The client of a vx-history server (`@vzn/vx-history-server`, its
+// PROTOCOL.md): each task's numbers asked once a run, and the run's own
+// timings sent once at its end. A query names the issuer, repository and
+// refs the workspace reads, plainly; a CI job's request carries its OIDC
+// token, which writes its own ref, and with no token a run only reads (a
+// server with `READ_ACCESS=public`). A refusal is never swallowed: it is said with the
+// server's status and words.
+
+import type { TaskOutcome } from '@vzn/vx'
+
+/** One task's numbers, as the server folds and answers them. */
+export interface ServerTiming {
+  readonly durationMs: number
+  readonly cores?: number
+  readonly rssBytes?: number
+}
+
+/** Every request's deadline: a run never waits on history longer. */
+const DEADLINE_MS = 10_000
+/** Tries of a request, to the server or GitHub's OIDC endpoint, before it fails (`tried`). */
+const ATTEMPTS = 3
+
+/** The issuer and repository a workspace names, as a key holds them: the issuer's URL with no trailing slash, `org/name` lowercased. */
+export interface Named {
+  readonly issuer: string
+  readonly repository: string
+}
+
+/** Whether this job has a token: GitHub's OIDC endpoint, or GitLab's `VX_HISTORY_TOKEN`. */
+const hasToken = (env: Record<string, string | undefined>): boolean =>
+  (!!env.ACTIONS_ID_TOKEN_REQUEST_URL && !!env.ACTIONS_ID_TOKEN_REQUEST_TOKEN) ||
+  !!env.VX_HISTORY_TOKEN
+
+/** A task the run ran and that succeeded, as the server takes its timing; else undefined. */
+export function timingOf(o: TaskOutcome): ServerTiming | undefined {
+  if (o.status !== 'success') return undefined
+  // Core's need (history.ts NEED_SQL): at most the machine's cores, and no
+  // reading where the share is 0. Uncapped, a crowded 4-core worker sent 8
+  // and a DTE plan booked that; an Infinity went as null and the server
+  // refused the whole upload.
+  const need =
+    o.cpuMs === undefined || o.durationMs <= 0
+      ? undefined
+      : Math.min(o.cpuMs / (o.durationMs * (o.cpuShare ?? 1)), o.whereCores ?? Infinity)
+  // A share rounded to 0 divides by it, and the server refuses the upload.
+  const cores = need !== undefined && Number.isFinite(need) ? need : undefined
+  return {
+    durationMs: Math.max(0, aloneMs(o)),
+    ...(cores === undefined ? {} : { cores }),
+    ...(o.peakRssBytes === undefined ? {} : { rssBytes: o.peakRssBytes }),
+  }
+}
+
+/**
+ * How long it would have taken alone, as core's local history stores it
+ * (`run-history.ts` aloneMs): on a crowded DTE worker (`cpuShare` < 1) each
+ * thread waited for a core. Sent as it ran, every crowded run raised the
+ * shared number a forecast reads (2026-10-26).
+ */
+function aloneMs(o: TaskOutcome): number {
+  const { durationMs: d, cpuMs: c, cpuShare: s } = o
+  if (c === undefined || s === undefined || !(s > 0 && s < 1) || !(d > 0)) return Math.round(d)
+  return Math.round(d - (c / s - c) / Math.max(1, c / (d * s)))
+}
+
+/** {@link DEADLINE_MS}, or `stop` first. */
+const deadline = (stop?: AbortSignal): AbortSignal => {
+  const c = new AbortController()
+  setTimeout(() => c.abort(new Error(`no answer within ${DEADLINE_MS} ms`)), DEADLINE_MS).unref()
+  return stop === undefined ? c.signal : AbortSignal.any([c.signal, stop])
+}
+
+/**
+ * `s` with each C0/C1 control and DEL written as `\xNN`: a server's words
+ * reach the terminal, and an `ESC ]` or `\r` in them retitled it or
+ * overwrote the line before (core's `printable`, L-31).
+ */
+const printable = (s: string): string =>
+  // oxlint-disable-next-line no-control-regex
+  s.replace(/[\x00-\x1f\x7f-\x9f]/g, (c) => `\\x${c.charCodeAt(0).toString(16).padStart(2, '0')}`)
+
+/** A refusal, named by its status and the server's own `message`. */
+async function refusal(res: Response): Promise<Error> {
+  // quiet: with the body unread, the status alone names the refusal
+  const text = (await res.text().catch(() => '')).slice(0, 2048)
+  let said = text
+  try {
+    const m = (JSON.parse(text) as { message?: unknown }).message
+    if (typeof m === 'string') said = m
+  } catch {
+    // quiet: not JSON, so the text is what it said
+  }
+  said = printable(said.replace(/\s+/g, ' ').trim().slice(0, 200))
+  return new Error(`HTTP ${res.status}${said === '' ? '' : `: ${said}`}`)
+}
+
+/** A 200's JSON; one that is none (a website's page) names the likely fault, the url. */
+async function jsonOf(res: Response, path: string): Promise<unknown> {
+  const text = await res.text()
+  try {
+    return JSON.parse(text)
+  } catch {
+    const type = res.headers.get('content-type') ?? 'no content type'
+    throw new Error(
+      `${path} answered ${res.status} with ${type}, not JSON: is the url a vx-history server?`,
+    )
+  }
+}
+
+/**
+ * A redirect, never followed: fetch drops only `Authorization` on one to
+ * another origin, so `headers` (a proxy's secret) went where a 307 named.
+ */
+async function redirected(res: Response, from: string): Promise<Error> {
+  await res.body?.cancel()
+  const to = res.headers.get('location')
+  return new Error(
+    `HTTP ${res.status}${to === null ? '' : ` to ${new URL(to, from).href}`}: not followed, as it would carry the server's headers; name the server's own URL`,
+  )
+}
+
+/** A JWT's `exp` in ms; 0 when it names none. */
+function expiryOf(jwt: string): number {
+  try {
+    const exp = (
+      JSON.parse(Buffer.from(jwt.split('.')[1] ?? '', 'base64url').toString()) as {
+        exp?: unknown
+      }
+    ).exp
+    return typeof exp === 'number' ? exp * 1000 : 0
+  } catch {
+    // quiet: an unreadable exp is no known expiry; the server refuses the token
+    return 0
+  }
+}
+
+/** A whole count a server keeps (its own check): a sum of thousands stays finite. */
+const isCount = (n: unknown): n is number =>
+  typeof n === 'number' && Number.isSafeInteger(n) && n >= 0
+
+interface Limits {
+  readonly maxUploadTimings: number
+  readonly maxQueryHashes: number
+}
+
+export class HistoryServer {
+  private token: Promise<string> | undefined
+  private held: { jwt: string; exp: number } | undefined
+  private limits: Promise<Limits> | undefined
+  // A refused token is refused again: the run's later calls stay unasked and unsaid.
+  private refused = false
+
+  constructor(
+    readonly url: string,
+    private readonly named: Named,
+    private readonly env: Record<string, string | undefined> = Bun.env,
+    private readonly fetchImpl: typeof fetch = fetch,
+    private readonly headers: Readonly<Record<string, string>> = {},
+    private readonly wait: (ms: number) => Promise<void> = Bun.sleep,
+  ) {}
+
+  /** Whether the run has a token to send: with none it reads only. */
+  get writes(): boolean {
+    return hasToken(this.env)
+  }
+
+  /**
+   * The job's token: GitHub's OIDC token for the server's origin, asked
+   * again a minute before it ends (it lives minutes, a run can outlive it),
+   * else `VX_HISTORY_TOKEN`.
+   */
+  private bearer(signal?: AbortSignal): Promise<string> {
+    const held = this.held
+    if (held !== undefined && (held.exp === 0 || Date.now() < held.exp - 60_000)) {
+      return Promise.resolve(held.jwt)
+    }
+    this.token ??= (async () => {
+      const ask = this.env.ACTIONS_ID_TOKEN_REQUEST_URL
+      if (ask === undefined || ask === '') return { jwt: this.env.VX_HISTORY_TOKEN ?? '', exp: 0 }
+      const u = new URL(ask)
+      u.searchParams.set('audience', new URL(this.url).origin)
+      const res = await this.askGithub(u, signal)
+      if (!res.ok) throw new Error(`GitHub's OIDC endpoint: ${(await refusal(res)).message}`)
+      const jwt = ((await res.json()) as { value?: unknown }).value
+      if (typeof jwt !== 'string' || jwt === '') throw new Error("GitHub's OIDC endpoint: no token")
+      return { jwt, exp: expiryOf(jwt) }
+    })()
+      .then((t) => (this.held = t).jwt)
+      .finally(() => (this.token = undefined))
+    return this.token
+  }
+
+  /**
+   * One answer, asked again while `again(status)` (`undefined`: no answer)
+   * holds, up to three tries, 1 s then 2 s apart: the upload is sent once, at the run's end,
+   * and one 503 there, or from GitHub's OIDC endpoint (as vx-cache asks
+   * it, #4571), lost the run's timings.
+   */
+  private async tried(
+    send: () => Promise<Response>,
+    again: (status: number | undefined) => boolean,
+  ): Promise<Response> {
+    for (let attempt = 1; ; attempt++) {
+      let res: Response | undefined
+      let failure: unknown
+      try {
+        res = await send()
+      } catch (err) {
+        failure = err
+      }
+      if (!again(res?.status)) {
+        if (res === undefined) throw failure
+        return res
+      }
+      if (attempt === ATTEMPTS) {
+        if (res === undefined) throw failure
+        return res
+      }
+      await res?.body?.cancel()
+      await this.wait(1000 * attempt)
+    }
+  }
+
+  /** GitHub's OIDC endpoint: a 4xx is final. */
+  private askGithub(ask: URL, signal?: AbortSignal): Promise<Response> {
+    return this.tried(
+      () =>
+        this.fetchImpl(ask, {
+          headers: { authorization: `bearer ${this.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN ?? ''}` },
+          signal: deadline(signal),
+        }),
+      (status) => status === undefined || status === 429 || status >= 500,
+    )
+  }
+
+  private async call(path: string, body?: unknown, signal?: AbortSignal): Promise<Response> {
+    const bearer = this.writes ? await this.bearer(signal) : ''
+    const json = body === undefined ? undefined : JSON.stringify(body)
+    // A 500 is the server's own failure, maybe after the fold: sent again, a
+    // run would count twice. The edge's 502, 503 and 504 and a 429 come
+    // before it. No answer is not asked again: a server down or misnamed
+    // would add seconds to every run's end.
+    const url = `${this.url}${path}`
+    const res = await this.tried(
+      () =>
+        this.fetchImpl(url, {
+          method: json === undefined ? 'GET' : 'POST',
+          headers: {
+            ...this.headers,
+            ...(bearer === '' ? {} : { authorization: `Bearer ${bearer}` }),
+            ...(json === undefined ? {} : { 'content-type': 'application/json' }),
+          },
+          ...(json === undefined ? {} : { body: json }),
+          signal: deadline(signal),
+          redirect: 'manual',
+        }),
+      (status) => status !== undefined && (status === 429 || (status >= 502 && status <= 504)),
+    )
+    if (res.status >= 300 && res.status < 400) throw await redirected(res, url)
+    if (res.status === 401 && bearer === '') {
+      // Off CI: the bare 401 said nothing of why or what to do (2026-10-26).
+      const err = await refusal(res)
+      const fix =
+        this.env.GITHUB_ACTIONS === 'true'
+          ? 'give the job `permissions: id-token: write`'
+          : this.env.GITLAB_CI === 'true'
+            ? 'name an id_tokens entry VX_HISTORY_TOKEN'
+            : 'off CI, a server reads only with READ_ACCESS=public'
+      throw new Error(`${err.message}: a read with no CI token was refused (${fix})`)
+    }
+    if (res.status === 401) {
+      // The bare "HTTP 401: wrong audience" named neither what was sent nor what to check.
+      this.refused = true
+      const err = await refusal(res)
+      throw new Error(
+        `${err.message}: the token was refused (this workspace names ${this.named.repository} at ${this.named.issuer}; the server's ALLOW must name it, and the token's audience be ${new URL(this.url).origin}); the history server is off for this run`,
+      )
+    }
+    if (!res.ok) throw await refusal(res)
+    return res
+  }
+
+  /** `/v1/capabilities`, asked once a run, and again after a failed ask: nothing is guessed. */
+  private limitsNow(): Promise<Limits> {
+    const asked = (this.limits ??= (async () => {
+      const body = (await jsonOf(
+        await this.call('/v1/capabilities'),
+        '/v1/capabilities',
+      )) as Partial<Limits> | null
+      const n = (v: unknown) => (typeof v === 'number' && Number.isSafeInteger(v) && v > 0 ? v : 0)
+      const limits = {
+        maxUploadTimings: n(body?.maxUploadTimings),
+        maxQueryHashes: n(body?.maxQueryHashes),
+      }
+      if (limits.maxUploadTimings === 0 || limits.maxQueryHashes === 0) {
+        throw new Error('/v1/capabilities named no maxUploadTimings or maxQueryHashes')
+      }
+      return limits
+    })())
+    // quiet: the awaited ask rethrows it; this only forgets it
+    asked.catch(() => {
+      if (this.limits === asked) this.limits = undefined
+    })
+    return asked
+  }
+
+  /** Each held hash's numbers under the first of `refs` that holds them: one request a run. */
+  async query(
+    refs: readonly string[],
+    hashes: readonly string[],
+  ): Promise<Map<string, ServerTiming>> {
+    if (hashes.length === 0 || this.refused) return new Map()
+    const per = (await this.limitsNow()).maxQueryHashes
+    const parts = await Promise.all(
+      Array.from({ length: Math.ceil(hashes.length / per) }, async (_, i) => {
+        const res = await this.call('/v1/timings/query', {
+          ...this.named,
+          refs,
+          hashes: hashes.slice(i * per, (i + 1) * per),
+        })
+        const body = (await jsonOf(res, '/v1/timings/query')) as { timings?: unknown } | null
+        if (typeof body?.timings !== 'object' || body.timings === null) {
+          throw new Error('the query answered no `timings` object')
+        }
+        return Object.entries(body.timings as Record<string, ServerTiming | null>)
+      }),
+    )
+    // Only numbers a server folds (PROTOCOL.md): `1e309` parses to Infinity,
+    // and kept as a forecast it made a NaN weight that failed every later
+    // run of the cache in `schedule`.
+    const out = new Map<string, ServerTiming>()
+    for (const [hash, t] of parts.flat()) {
+      if (!isCount(t?.durationMs)) continue
+      out.set(hash, {
+        durationMs: t.durationMs,
+        ...(typeof t.cores === 'number' && Number.isFinite(t.cores) && t.cores >= 0
+          ? { cores: t.cores }
+          : {}),
+        ...(isCount(t.rssBytes) ? { rssBytes: t.rssBytes } : {}),
+      })
+    }
+    return out
+  }
+
+  /** The run's timings, by task definition hash, in uploads of at most `maxUploadTimings`; `stop` abandons them. */
+  async upload(timings: ReadonlyMap<string, ServerTiming>, stop?: AbortSignal): Promise<void> {
+    if (timings.size === 0 || this.refused) return
+    const per = (await this.limitsNow()).maxUploadTimings
+    const all = [...timings].map(([hash, t]) => ({ hash, ...t }))
+    for (let i = 0; i < all.length; i += per) {
+      await this.call('/v1/timings/upload', { timings: all.slice(i, i + per) }, stop)
+    }
+  }
+}

package/src/history-view.ts

@@ -0,0 +1,110 @@
+// `vx history`'s pretty table, apart from the verb that reads the history:
+// a pure function of the rows, so its thresholds and its unit breaks are
+// pinned without a run.
+
+import { ui } from '@vzn/vx'
+import type { Budgets, ResourceEstimate } from './index.js'
+
+export interface HistoryRow {
+  id: string
+  runs: number
+  p50DurationMs: number | null
+  maxPeakRssBytes: number | null
+  maxCpuParallelism: number | null
+  reservation: ResourceEstimate | null
+  declared: boolean
+}
+
+const MB = 1024 * 1024
+
+/**
+ * The table: every task with an execution in the window or a reservation,
+ * then a count of the ones with neither. `memoryDeclared` says where the
+ * memory budget came from (the option, or what the process may use).
+ * Painted as core's tables are (a dim header, each id in its hue).
+ */
+export function historyBlock(
+  rows: readonly HistoryRow[],
+  window: number,
+  budgets: Budgets,
+  memoryDeclared: boolean,
+): ui.Block {
+  const seen = rows.filter((r) => r.runs > 0 || r.reservation !== null)
+  const lines: ui.Inline[] = [
+    [
+      ui.cmd('history:'),
+      ui.dim(
+        ` last ${window} runs · budgets ${budgets.cpus} core${budgets.cpus === 1 ? '' : 's'} (the default worker count; --concurrency changes it per run) · ${budgets.memory} MB` +
+          `${memoryDeclared ? ' (the memory option)' : ' (what this process may use)'}`,
+      ),
+    ],
+  ]
+  if (seen.length === 0) {
+    lines.push(ui.dim('no task has an execution in the window — run something first'))
+  } else {
+    const idW = Math.max(...seen.map((r) => Bun.stringWidth(r.id)), 4)
+    lines.push(
+      ui.dim(
+        `  ${'task'.padEnd(idW)}  ${'runs'.padStart(4)}  ${'p50'.padStart(7)}  ${'peak rss'.padStart(8)}  ${'cpu'.padStart(5)}  reserves`,
+      ),
+    )
+    for (const r of seen) {
+      const amounts =
+        r.reservation === null
+          ? []
+          : [
+              ...(r.reservation.memory !== undefined ? [`${r.reservation.memory} MB`] : []),
+              ...(r.reservation.cpus !== undefined
+                ? [`${r.reservation.cpus} core${r.reservation.cpus === 1 ? '' : 's'}`]
+                : []),
+            ]
+      // A declaration of nothing (`{ memory: 0 }`) still names itself.
+      const reserve =
+        (amounts.length === 0 ? '—' : amounts.join(' · ')) +
+        (r.reservation !== null && r.declared ? ' (declared)' : '')
+      lines.push([
+        '  ',
+        ui.id(r.id),
+        ' '.repeat(idW - Bun.stringWidth(r.id)),
+        `  ${String(r.runs).padStart(4)}  ${fmtMs(r.p50DurationMs).padStart(7)}  ` +
+          `${fmtBytes(r.maxPeakRssBytes).padStart(8)}  ${(r.maxCpuParallelism === null ? '—' : `${r.maxCpuParallelism.toFixed(1)}×`).padStart(5)}  ${reserve}`,
+      ])
+    }
+    const silent = rows.length - seen.length
+    if (silent > 0) {
+      lines.push(
+        ui.dim(
+          `  ${silent} task${silent === 1 ? '' : 's'} with no execution in the window reserve${silent === 1 ? 's' : ''} nothing`,
+        ),
+      )
+    }
+  }
+  return { lines: (c) => lines.map((l) => ui.inline(l, c)) }
+}
+
+/** The table as plain text, as a pipe gets it. */
+export function renderHistory(
+  rows: readonly HistoryRow[],
+  window: number,
+  budgets: Budgets,
+  memoryDeclared: boolean,
+): string {
+  return ui.render([historyBlock(rows, window, budgets, memoryDeclared)], { enabled: false })
+}
+
+// Each unit is chosen by the rounded value: 59 999 ms printed `60.00s`,
+// 119.7 s `1m 60s`, and a byte under 1 MiB `1024 KB`.
+function fmtMs(ms: number | null): string {
+  if (ms === null) return '—'
+  if (Math.round(ms) < 1000) return `${Math.round(ms)}ms`
+  if (Math.round(ms / 10) < 6000) return `${(ms / 1000).toFixed(2)}s`
+  const s = Math.round(ms / 1000)
+  return `${Math.floor(s / 60)}m ${s % 60}s`
+}
+
+function fmtBytes(n: number | null): string {
+  if (n === null) return '—'
+  if (Math.round(n / 1024) < 1024) return `${Math.round(n / 1024)} KB`
+  if (Math.round(n / MB) < 1024) return `${(n / MB).toFixed(0)} MB`
+  return `${(n / (1024 * MB)).toFixed(1)} GB`
+}