@vzn/vx-history-server 0.0.652 → 0.0.653

package/PROTOCOL.md

@@ -38,8 +38,9 @@ an upload with none is `403`.
 `POST /v1/timings/upload` (a token that writes) with
 `{ "timings": [{ "hash", "durationMs", "cores"?, "rssBytes"? }] }`, up to
 10 000, each task once: `204`. `hash` names the task's definition, a
-string of up to 512 characters (no lone surrogate) the server never
-reads. Each folds into its row of the token's repository and ref:
+string the server never reads of 1 to 512 ASCII characters, none a
+space, control, `"` or `\`: each is one byte in JSON, which the body
+limits count on. Each folds into its row of the token's repository and ref:
 
 - `durationMs` and `cores`: `old × 0.7 + new × 0.3`. A median needs the
   samples and a mean never forgets; this follows a task that got slower
@@ -59,8 +60,8 @@ the row's. A row not reported for `TIMING_DAYS` (30) is deleted.
 
 An upload may also carry `"outcomes": [{ "hash", "key", "outcome" }]`,
 up to 10 000, each task and key once: every cached task the run ran.
-`hash` is the task's definition, `key` its cache key (both up to 512
-characters), `outcome` one of:
+`hash` is the task's definition, `key` its cache key (each as `hash`
+above), `outcome` one of:
 
 - `pass`, `fail`: how it ended.
 - `flaky`: it passed on a retry, so the run saw it flake.
@@ -90,9 +91,14 @@ flaky, by any ref:
 ## Limits and errors
 
 `GET /v1/capabilities`: `{ "maxUploadTimings": 10000, "maxQueryHashes": 10000, "maxQueryRefs": 8 }`.
-A server takes both at their limits, each hash 512 characters: an
-upload body up to 17 960 100 bytes, a query's up to 6 010 000. Past
-that, `413`.
+Every `/v1/timings` answer, a refusal too, names them as
+`vx-max-upload-timings`, `vx-max-query-hashes` and `vx-max-query-refs`,
+so a client need not ask them apart: vx sends a run's query and upload
+whole, and one refused for its size again in parts of the limit its
+refusal names.
+A server takes both at their limits, each hash and key 512 characters
+and every ref 512: an upload body up to 17 960 100 bytes, a query's up
+to 6 010 000. Past that, `413`.
 
 Every refusal is `{ code, message }`, the message saying what to fix. A
 JSON body without `Content-Type: application/json` is `400`, an unknown

package/README.md

@@ -30,7 +30,8 @@ sends one query: its repository, the refs it reads (its branch, then the
 branch it merges into, then the default branch) and every task hash;
 the server answers each from the first ref that holds it. A token of
 another repository than the query names is refused. `AUDIENCE` is the
-`aud` a token must name: the origin clients reach the server at. On
+`aud` a token must name: the origin clients reach the server at (a URL
+is read as its origin; one that is no URL stops the server). On
 Workers, unset, it is that origin (Cloudflare routes only the Worker's
 own hostnames to it); on Bun and Docker it is required, since there the
 origin is the request's `Host` header, which a client picks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-history-server",
-  "version": "0.0.652",
+  "version": "0.0.653",
   "license": "MIT",
   "description": "The task timings a vx scheduler asks for, one folded row per task, that you host: on Bun with SQLite, on Cloudflare Workers with D1, or as a Docker image.",
   "keywords": [
@@ -45,7 +45,7 @@
     "miniflare: tests/worker.test.ts runs src/worker.ts in workerd with D1, as Workers deploy it."
   ],
   "dependencies": {
-    "@vzn/vx-devtools": "0.0.652"
+    "@vzn/vx-devtools": "0.0.653"
   },
   "repository": {
     "type": "git",

package/src/bun.ts

@@ -12,7 +12,7 @@ import { type Db, sqliteStore } from './store.js'
 const USAGE = `usage: vx-history-server [--db vx-history.sqlite] [--port 8080] [--host 0.0.0.0]
   ALLOW        who may take part, space separated, each issuer:owner/repo:workflow
                (README.md § CI tokens); only their jobs' OIDC tokens are taken
-  AUDIENCE     the aud a CI token names: the URL clients reach this server at
+  AUDIENCE     the aud a CI token names: the origin clients reach this server at
   READ_ACCESS  public: a request with no token reads a repository ALLOW names
   TIMING_DAYS  days a task's timings outlive its last report (default 30)`
 
@@ -78,7 +78,9 @@ function main(argv: string[]): void {
   // header, which the client picks. Workers know their own hostnames.
   const audience = env.AUDIENCE?.trim() ?? ''
   if (audience === '')
-    fail(`set AUDIENCE: the aud a CI token names, the URL clients reach this server at\n${USAGE}`)
+    fail(
+      `set AUDIENCE: the aud a CI token names, the origin clients reach this server at\n${USAGE}`,
+    )
   const handle = createHistoryServer({
     store: sqliteStore(db),
     authorize: oidcTokenAuth({

package/src/server.ts

@@ -99,7 +99,7 @@ export function createHistoryServer(opts: ServerOptions): (req: Request) => Prom
       hashes.length > MAX_QUERY_HASHES ||
       !hashes.every((h) => isOpaque(h))
     ) {
-      throw new Refusal(400, `hashes: a list of up to ${MAX_QUERY_HASHES} strings`)
+      throw new Refusal(400, `hashes: a list of up to ${MAX_QUERY_HASHES}, each ${OPAQUE_IS}`)
     }
     const repo = (await authorize(req, { issuer, repository }))!
     await schema()
@@ -133,6 +133,15 @@ export function createHistoryServer(opts: ServerOptions): (req: Request) => Prom
   }
 
   return async (req) => {
+    const res = await answer(req)
+    // Every /v1/timings answer, a refusal too: a client learns the limits
+    // from its first request, and was asked none apart (2026-11-06).
+    if (new URL(req.url).pathname.startsWith('/v1/timings/'))
+      for (const [header, value] of limitHeaders) res.headers.set(header, value)
+    return res
+  }
+
+  async function answer(req: Request): Promise<Response> {
     const path = new URL(req.url).pathname
     try {
       const search = new URL(req.url).search
@@ -168,13 +177,25 @@ export function createHistoryServer(opts: ServerOptions): (req: Request) => Prom
   }
 }
 
+/** The limits as every `/v1/timings` answer names them (PROTOCOL.md § Limits and errors). */
+const limitHeaders = [
+  ['vx-max-upload-timings', String(MAX_UPLOAD_TIMINGS)],
+  ['vx-max-query-hashes', String(MAX_QUERY_HASHES)],
+  ['vx-max-query-refs', String(MAX_QUERY_REFS)],
+] as const
+
 const field = (body: unknown, key: string): unknown =>
   typeof body === 'object' && body !== null ? (body as Record<string, unknown>)[key] : undefined
 
-// A lone surrogate is stored as bytes that read back as U+FFFD: the row
-// answers to a hash no client asked for.
-const isOpaque = (s: unknown): s is string =>
-  typeof s === 'string' && s.length > 0 && s.length <= MAX_STRING && !/\p{Cs}/u.test(s)
+/**
+ * Each character one byte in JSON, so the body limits hold `MAX_STRING`
+ * of them: 10 000 hashes of 512 `é` (two bytes each) were a 413 at the
+ * limits the protocol promised, and a control is six (`\u0001`).
+ */
+const OPAQUE = new RegExp(`^[\\x21\\x23-\\x5b\\x5d-\\x7e]{1,${MAX_STRING}}$`)
+const OPAQUE_IS = `1 to ${MAX_STRING} ASCII characters, none a space, control, " or \\`
+
+const isOpaque = (s: unknown): s is string => typeof s === 'string' && OPAQUE.test(s)
 
 const isCount = (n: unknown): n is number =>
   typeof n === 'number' && Number.isSafeInteger(n) && n >= 0
@@ -209,7 +230,7 @@ function parseReports(body: unknown): Report[] {
     const durationMs = field(x, 'durationMs')
     const cores = field(x, 'cores')
     const rssBytes = field(x, 'rssBytes')
-    if (!isOpaque(hash)) bad(`hash: a string of up to ${MAX_STRING} characters`)
+    if (!isOpaque(hash)) bad(`hash: ${OPAQUE_IS}`)
     // One row per task: a second report of it in one upload would fold twice.
     if (seen.has(hash as string)) bad('hash: each task once')
     seen.add(hash as string)
@@ -245,8 +266,8 @@ function parseOutcomes(body: unknown): Outcome[] {
     const hash = field(x, 'hash')
     const key = field(x, 'key')
     const outcome = field(x, 'outcome')
-    if (!isOpaque(hash)) bad(`hash: a string of up to ${MAX_STRING} characters`)
-    if (!isOpaque(key)) bad(`key: a string of up to ${MAX_STRING} characters`)
+    if (!isOpaque(hash)) bad(`hash: ${OPAQUE_IS}`)
+    if (!isOpaque(key)) bad(`key: ${OPAQUE_IS}`)
     const id = `${hash as string}\0${key as string}`
     if (seen.has(id)) bad('key: each task and key once')
     seen.add(id)