From a97c94a194148fa55b5ba0905b6289bc003c9822 Mon Sep 17 00:00:00 2001 From: Seyed Yahya Shirazi Date: Sat, 7 Nov 2026 07:36:03 -0800 Subject: [PATCH 01/17] Capture job page fixtures from the backend --- scripts/capture-compute-job-fixtures.mjs | 538 ++++++++++++++++++ test/fixtures/compute/cancel.json | 121 ++++ test/fixtures/compute/errors-job.json | 148 +++++ .../compute/job-cancel-requested.json | 38 ++ test/fixtures/compute/job-failure-codes.json | 502 ++++++++++++++++ test/fixtures/compute/job-lifecycle.json | 68 +++ test/fixtures/compute/job-stale.json | 39 ++ test/fixtures/compute/job-states.json | 299 ++++++++++ test/fixtures/compute/logs.json | 78 +++ test/fixtures/compute/results.json | 141 +++++ 10 files changed, 1972 insertions(+) create mode 100644 scripts/capture-compute-job-fixtures.mjs create mode 100644 test/fixtures/compute/cancel.json create mode 100644 test/fixtures/compute/errors-job.json create mode 100644 test/fixtures/compute/job-cancel-requested.json create mode 100644 test/fixtures/compute/job-failure-codes.json create mode 100644 test/fixtures/compute/job-lifecycle.json create mode 100644 test/fixtures/compute/job-stale.json create mode 100644 test/fixtures/compute/job-states.json create mode 100644 test/fixtures/compute/logs.json create mode 100644 test/fixtures/compute/results.json diff --git a/scripts/capture-compute-job-fixtures.mjs b/scripts/capture-compute-job-fixtures.mjs new file mode 100644 index 00000000..40284117 --- /dev/null +++ b/scripts/capture-compute-job-fixtures.mjs @@ -0,0 +1,538 @@ +/** + * Capture the compute JOB PAGE fixtures from the REAL nemar-cli backend routes (website ADR 0030 and + * its phase E3 addendum; epic nemarOrg/website#493, issue #496). + * + * NEMAR_CLI_DIR= \ + * bun scripts/capture-compute-job-fixtures.mjs + * + * Captured from nemar-cli commit 27eecff9 (Epic D, `feature/issue-2021-epic-compute-users`; phases D1 + * to D4 and the copy keys are in it). The checkout needs `bun install` at its root and in `backend/`. + * + * Nothing is stood in for. The script runs outside `bun test` (step 0 of the phase plan: it can) on the + * backend's own lifecycle fixture (`backend/test/helpers/compute-lifecycle-fixture.ts`): real migrated + * SQLite, Miniflare's R2 for the results and records buckets, the real local S3 interface the signer + * addresses, and Epic A's Tapis stand-in (a real HTTP server built from Tapis's published + * specifications; no response of it was recorded from a real tenant). The REAL compute router + * (`makeRoutesApp`) is called with real hashed API keys, and the bodies are written unchanged. + * Two kinds of job are read: + * - rows written by `insertJob` with fixed times (the states, the failure codes, a recorded cancel): + * these rerun to the same bytes; + * - jobs taken through the real lifecycle (`makeJob`, `submitComputeJob`, `advanceComputeJob`, + * `playLauncher`, which plays the launcher's last step and is documented in the fixture): these + * carry fresh ids, times and presigned signatures on every run, so a rerun rewrites those files. + * Tests therefore read the identifiers out of the fixture, never a literal. + * + * Writes under test/fixtures/compute/: + * job-states.json GET /compute/me/jobs/:id, one job in each of the ten states + * job-failure-codes.json the same, one failed job per failure code (17) + * job-cancel-requested.json a running job with a cancel recorded + * job-stale.json a live job whose cluster read failed: `stale: true` + * job-lifecycle.json a job read at running and again at finished, through the real lifecycle + * logs.json GET /compute/jobs/:id/logs: live, ended (records copy), empty, hostile, + * over 1 MiB (headers and length only), not available yet + * results.json GET and POST renew of a finished job, a second page by cursor (a job with + * more outputs than one page; the first page is summarized, not stored), + * the expired and the not-finished refusals + * cancel.json POST /compute/jobs/:id/cancel: each outcome the route gives + * errors-job.json job_not_found for a foreign, an absent and a malformed id, on every + * job route; the credential refusals + * + * Every presigned address points at the local object-store stand-in and carries a test signature; the + * emails are @example.org; no body contains an identity. + */ + +import { mkdir, writeFile } from "node:fs/promises"; +import { dirname, join, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; + +const NEMAR_CLI_DIR = process.env.NEMAR_CLI_DIR; +if (!NEMAR_CLI_DIR) { + console.error("Set NEMAR_CLI_DIR to a checkout of nemar-cli's Epic D branch."); + process.exit(1); +} +const root = resolve(NEMAR_CLI_DIR); +const here = dirname(fileURLToPath(import.meta.url)); +const OUT = resolve(here, "..", "test", "fixtures", "compute"); + +const lifecycle = await import(join(root, "backend/test/helpers/compute-lifecycle-fixture.ts")); +const { makeRoutesApp } = await import(join(root, "backend/test/helpers/compute-routes-app.ts")); +const { insertJob, personWithKey } = await import( + join(root, "backend/test/helpers/compute-user-seed.ts") +); +const { submitComputeJob, advanceComputeJob } = await import( + join(root, "backend/src/services/compute-lifecycle.ts") +); +const { hashApiKey } = await import(join(root, "backend/src/services/token.ts")); +const { logKey } = await import(join(root, "backend/src/services/compute-records.ts")); +const { COMPUTE_STATES, COMPUTE_FAILURE_CODES } = await import( + join(root, "shared/compute-state.ts") +); +const { COMPUTE_LOG_MAX_BYTES, COMPUTE_RESULTS_PAGE_MAX } = await import( + join(root, "shared/contract/compute-submit.ts") +); +const { startLifecycleFixture, makeJob, playLauncher, reread, setTapisTimes, MINUTE } = lifecycle; + +const COMMIT = "27eecff9"; +const COMMAND = "NEMAR_CLI_DIR= bun scripts/capture-compute-job-fixtures.mjs"; + +const provenance = (route, request, note) => ({ + command: COMMAND, + nemar_cli_commit: COMMIT, + route, + request, + note, +}); + +const fx = await startLifecycleFixture(); +await fx.reset(); +const handle = makeRoutesApp(); +const db = fx.harness.db; + +let keySeq = 0; +async function keyFor(accountId) { + const key = `capture-job-key-${++keySeq}-0123456789abcdef0123456789abcdef`; + db.query("INSERT INTO tokens (user_id, api_key_hash, api_key_prefix) VALUES (?, ?, ?)").run( + accountId, + await hashApiKey(key), + key.slice(0, 8), + ); + return key; +} + +/** The headers a page or a test reads; the rest are transport. */ +const KEPT_HEADERS = [ + "content-type", + "cache-control", + "x-content-type-options", + "x-nemar-truncated", +]; + +/** One request through the real router; `text` bodies are kept as text, JSON as parsed. */ +async function call(method, path, key, over = {}) { + const headers = {}; + if (key) headers.Authorization = `Bearer ${key}`; + const res = await handle( + new Request(`http://api.test/compute${path}`, { method, headers }), + fx.env(over.env ?? {}), + ); + const bytes = new Uint8Array(await res.arrayBuffer()); + const text = new TextDecoder().decode(bytes); + const kept = {}; + for (const name of KEPT_HEADERS) { + const v = res.headers.get(name); + if (v !== null) kept[name] = v; + } + let body; + if ((res.headers.get("content-type") ?? "").includes("json")) body = JSON.parse(text); + return { status: res.status, headers: kept, bytes, text, body }; +} + +/** The shape every fixture stores for a JSON answer: the status and the body, unchanged. */ +const asJson = ({ status, body }) => ({ status, body }); +/** And for a log: the status, the kept headers and the text. */ +const asText = ({ status, headers, text }) => ({ + status, + headers, + ...(status === 200 ? { text } : { body: JSON.parse(text) }), +}); + +// --- Insert-based jobs: fixed times, so the bytes rerun the same ----------------------------------- + +const owner = await personWithKey(db, { access: "active" }); +const ownerKey = owner.key; +const T = { + created: "2026-11-05 09:00:00", + started: "2026-11-05 09:10:00", + ended: "2026-11-05 09:50:00", +}; +const readJob = async (id, key = ownerKey) => call("GET", `/me/jobs/${id}`, key); + +const jobStates = { + _provenance: provenance( + "GET /compute/me/jobs/:id", + "one job in each of the ten states, by id", + "Real route over rows written with fixed times. A live job has no Tapis job, so nothing is refreshed and `stale` is absent. Times are the database's `YYYY-MM-DD HH:MM:SS` UTC. The route serves no name, no fault attribution and no hold.", + ), +}; +for (const state of COMPUTE_STATES) { + const terminal = ["finished", "failed", "cancelled"].includes(state); + const ran = ["running", "archiving", "finished", "failed"].includes(state); + const id = insertJob(db, { + account_id: owner.id, + state, + created_at: T.created, + started_at: ran ? T.started : null, + ended_at: terminal ? T.ended : null, + charged_milli: state === "finished" ? 2_500 : state === "failed" ? 1_250 : 0, + partition: "shared", + memory_mb: state === "finished" ? 8192 : null, + }); + jobStates[state] = asJson(await readJob(id)); +} + +const jobFailureCodes = { + _provenance: provenance( + "GET /compute/me/jobs/:id", + "one failed job per failure code (COMPUTE_FAILURE_CODES, 17)", + "Real route over rows written with fixed times. The user view carries `failure_code` only: `failure_detail` and `platform_failure` are not served.", + ), +}; +for (const code of COMPUTE_FAILURE_CODES) { + const id = insertJob(db, { + account_id: owner.id, + state: "failed", + failure_code: code, + created_at: T.created, + started_at: T.started, + ended_at: T.ended, + charged_milli: 500, + }); + jobFailureCodes[code] = asJson(await readJob(id)); +} + +const cancelRequestedId = insertJob(db, { + account_id: owner.id, + state: "running", + created_at: T.created, + started_at: T.started, + cancel_requested_at: "2026-11-05 09:20:00", +}); +const jobCancelRequested = { + _provenance: provenance( + "GET /compute/me/jobs/:id", + "a running job with a cancel recorded", + "Real route over a row written with fixed times: `cancel_requested` is true while the state is still live.", + ), + running: asJson(await readJob(cancelRequestedId)), +}; + +// --- Lifecycle jobs: the real services, the Tapis stand-in, the launcher's last step played ----------- + +const HOSTILE_LOG = [ + "plain line", + "\u001b[31mred\u001b[0m and \u001b[2K cleared", + "link \u001b]8;;https://example.org\u0007text\u001b]8;;\u0007 end", + "progress 10%\rprogress 50%\rprogress 100%", + "nul \u0000 bell \u0007 next-line \u0085 end", + "override ‮gnp.exe and isolate ⁦x⁩ and zero​width", + ' & "quotes" back\\slash', + "Traceback (most recent call last):", + ' File "main.py", line 3, in ', + "ZeroDivisionError: division by zero", + "", +].join("\n"); + +const TRACEBACK = [ + "Traceback (most recent call last):", + ' File "main.py", line 3, in ', + " print(1 / 0)", + "ZeroDivisionError: division by zero", + "", +].join("\n"); + +async function owned(over = {}) { + const made = await makeJob(fx, over); + return { ...made, key: await keyFor(made.accountId) }; +} + +async function submitted(over = {}) { + const j = await owned(over); + const sub = await submitComputeJob(j.env, j.job.id); + if (!sub.ok) throw new Error(`could not submit: ${sub.outcome}`); + const uuid = (await reread(j.env, j.job.id)).tapis_uuid; + return { ...j, uuid }; +} + +async function running(over = {}) { + const j = await submitted(over); + fx.tapis.advance(j.uuid, "QUEUED"); + fx.tapis.advance(j.uuid, "RUNNING"); + await advanceComputeJob(j.env, j.job.id); + return j; +} + +async function finished(outputs, log) { + const j = await running(); + if (log !== undefined) fx.tapis.setOutput(j.uuid, "tapisjob.out", log); + await playLauncher(fx, j.env, await reread(j.env, j.job.id), j.uuid, { outputs }); + fx.tapis.advance(j.uuid, "FINISHED"); + setTapisTimes(fx, j.uuid, 30 * MINUTE, 0); + await advanceComputeJob(j.env, j.job.id); + const job = await reread(j.env, j.job.id); + if (job.state !== "finished") throw new Error(`the job is ${job.state}, not finished`); + return j; +} + +// A job seen at running, then at finished. +const lifecycleJob = await running(); +const lifecycleRunning = asJson(await readJob(lifecycleJob.job.id, lifecycleJob.key)); +const lifecycleLog = await call("GET", `/jobs/${lifecycleJob.job.id}/logs`, lifecycleJob.key); +fx.tapis.setOutput(lifecycleJob.uuid, "tapisjob.out", "step one\nstep two\n"); +const logLive = asText(await call("GET", `/jobs/${lifecycleJob.job.id}/logs`, lifecycleJob.key)); +await playLauncher( + fx, + lifecycleJob.env, + await reread(lifecycleJob.env, lifecycleJob.job.id), + lifecycleJob.uuid, + { + outputs: [ + { path: "report.txt", content: "the report\n" }, + { path: "figures/plot.json", content: '{"x":[1,2,3]}' }, + { path: "table.csv", content: "a,b\n1,2\n" }, + ], + }, +); +fx.tapis.advance(lifecycleJob.uuid, "FINISHED"); +setTapisTimes(fx, lifecycleJob.uuid, 30 * MINUTE, 0); +await advanceComputeJob(lifecycleJob.env, lifecycleJob.job.id); +const lifecycleFinished = asJson(await readJob(lifecycleJob.job.id, lifecycleJob.key)); +const jobLifecycle = { + _provenance: provenance( + "GET /compute/me/jobs/:id", + "one job through makeJob, submitComputeJob, QUEUED, RUNNING, FINISHED", + "Real route over a job taken through the real lifecycle against the Tapis stand-in; the launcher's last step (its files and `declared.json`) is played by the backend's own helper. Ids and times are of the run that wrote this file.", + ), + job_id: lifecycleJob.job.id, + running: lifecycleRunning, + finished: lifecycleFinished, +}; + +// A stale read: a live job whose stored read is older than a minute and a cluster that cannot answer. +const staleJob = await submitted(); +db.query( + "UPDATE compute_jobs SET tapis_synced_at = datetime('now', '-10 minutes') WHERE id = ?", +).run(staleJob.job.id); +fx.tapis.down(); +const staleRead = asJson(await readJob(staleJob.job.id, staleJob.key)); +fx.tapis.up(); +const jobStale = { + _provenance: provenance( + "GET /compute/me/jobs/:id", + "a submitted job whose last cluster read is ten minutes old, with the Tapis stand-in down", + "Real route: the refresh failed, so the stored record is served with `stale: true`.", + ), + job_id: staleJob.job.id, + submitted: staleRead, +}; + +// --- Logs --------------------------------------------------------------------------------------------- + +const logsHostileJob = await running(); +fx.tapis.setOutput(logsHostileJob.uuid, "tapisjob.out", HOSTILE_LOG); +const logHostile = asText( + await call("GET", `/jobs/${logsHostileJob.job.id}/logs`, logsHostileJob.key), +); + +const logsEmptyJob = await running(); +fx.tapis.setOutput(logsEmptyJob.uuid, "tapisjob.out", ""); +const logEmpty = asText(await call("GET", `/jobs/${logsEmptyJob.job.id}/logs`, logsEmptyJob.key)); + +const logsBigJob = await running(); +fx.tapis.setOutput(logsBigJob.uuid, "tapisjob.out", "x".repeat(COMPUTE_LOG_MAX_BYTES + 4096)); +const big = await call("GET", `/jobs/${logsBigJob.job.id}/logs`, logsBigJob.key); +const logTruncated = { + status: big.status, + headers: big.headers, + byte_length: big.bytes.length, + note: "Headers and length only: the body is the first 1 MiB of 'x', which the test rebuilds.", +}; + +const notStarted = await owned(); +const logNotAvailable = asText( + await call("GET", `/jobs/${notStarted.job.id}/logs`, notStarted.key), +); + +// An ended job: the log is read from the records copy the lifecycle made when the job ended. +const endedWithLog = await finished([{ path: "report.txt", content: "the report\n" }], TRACEBACK); +const logEnded = asText(await call("GET", `/jobs/${endedWithLog.job.id}/logs`, endedWithLog.key)); + +const logs = { + _provenance: provenance( + "GET /compute/jobs/:id/logs", + "a running job (from Tapis), an empty log, a hostile log, a log over 1 MiB, a job that has not started, an ended job", + "Real route. The body is the job's own bytes as `text/plain`, `nosniff`, `no-store`; `X-Nemar-Truncated: true` only when cut at 1 MiB. The route serves the FIRST 1 MiB and has no `tail` (nemar-cli#2094). The hostile log's bytes are written to the Tapis stand-in's output and read back through the route.", + ), + live: logLive, + live_before_output: asText(lifecycleLog), + ended: logEnded, + empty: logEmpty, + hostile: logHostile, + truncated: logTruncated, + not_available: logNotAvailable, +}; + +// --- Results ------------------------------------------------------------------------------------------ + +const resultsGet = asJson( + await call("GET", `/jobs/${lifecycleJob.job.id}/results`, lifecycleJob.key), +); +const resultsRenew = asJson( + await call("POST", `/jobs/${lifecycleJob.job.id}/results/renew`, lifecycleJob.key), +); + +// More outputs than one page: the first page is summarized, the second is stored whole. +const OUTPUTS = COMPUTE_RESULTS_PAGE_MAX + 2; +const manyOutputs = Array.from({ length: OUTPUTS }, (_, i) => ({ + path: `out/file-${String(i).padStart(5, "0")}.txt`, + content: `n${i}\n`, +})); +const many = await finished(manyOutputs); +const firstPage = await call("GET", `/jobs/${many.job.id}/results`, many.key); +const cursor = firstPage.body.next_after; +const secondPage = await call( + "GET", + `/jobs/${many.job.id}/results?after=${encodeURIComponent(cursor)}`, + many.key, +); +const resultsManyFirst = { + status: firstPage.status, + summary: { + file_count: firstPage.body.files.length, + total: firstPage.body.total, + truncated: firstPage.body.truncated, + next_after: firstPage.body.next_after, + bearer_links: firstPage.body.bearer_links, + notice: firstPage.body.notice, + expires_at: firstPage.body.expires_at, + first_path: firstPage.body.files[0].path, + last_path: firstPage.body.files.at(-1).path, + note: "The files array (1,000 presigned links) is elided; the second page below is stored whole.", + }, +}; + +const notFinished = await running(); +const resultsBadState = asJson( + await call("GET", `/jobs/${notFinished.job.id}/results`, notFinished.key), +); + +const expiredJob = await finished([{ path: "report.txt", content: "the report\n" }]); +db.query("UPDATE compute_jobs SET ended_at = datetime('now', '-40 days') WHERE id = ?").run( + expiredJob.job.id, +); +const resultsExpired = asJson( + await call("GET", `/jobs/${expiredJob.job.id}/results`, expiredJob.key), +); +const resultsExpiredRenew = asJson( + await call("POST", `/jobs/${expiredJob.job.id}/results/renew`, expiredJob.key), +); + +const failedJob = await owned(); +db.query( + "UPDATE compute_jobs SET state = 'failed', failure_code = 'runtime_error', ended_at = datetime('now') WHERE id = ?", +).run(failedJob.job.id); +const resultsFailed = asJson(await call("GET", `/jobs/${failedJob.job.id}/results`, failedJob.key)); + +const results = { + _provenance: provenance( + "GET|POST /compute/jobs/:id/results[/renew]", + "a finished job with three outputs; a job with more outputs than one page (cursor); a job that is not finished; a job whose retention passed; a failed job", + "Real routes. Both verbs mint NEW 7-day presigned links (a renewal is the same handler). Presigned addresses point at the local object-store stand-in and carry test signatures that expire. `bearer_links` and `notice` come from the route. Files are in path order. The retention rule is the backend's: expired once `now > ended_at + results_days` (the job in `expired` had its `ended_at` moved 40 days back).", + ), + job_id: lifecycleJob.job.id, + get: resultsGet, + renew: resultsRenew, + many_job_id: many.job.id, + many_first_page: resultsManyFirst, + many_second_page: asJson(secondPage), + bad_state: resultsBadState, + expired: resultsExpired, + expired_renew: resultsExpiredRenew, + failed: resultsFailed, +}; + +// --- Cancel ------------------------------------------------------------------------------------------- + +const toCancel = await running(); +const cancelRunning = asJson(await call("POST", `/jobs/${toCancel.job.id}/cancel`, toCancel.key)); +const cancelAgain = asJson(await call("POST", `/jobs/${toCancel.job.id}/cancel`, toCancel.key)); +const afterCancel = asJson(await readJob(toCancel.job.id, toCancel.key)); +// The cluster cannot be reached: the intent is recorded and the job is still live. +const cancelPending = await running(); +fx.tapis.down(); +const cancelClusterDown = asJson( + await call("POST", `/jobs/${cancelPending.job.id}/cancel`, cancelPending.key), +); +const cancelClusterDownAgain = asJson( + await call("POST", `/jobs/${cancelPending.job.id}/cancel`, cancelPending.key), +); +const readClusterDown = asJson(await readJob(cancelPending.job.id, cancelPending.key)); +fx.tapis.up(); +const neverStarted = await owned(); +const cancelNeverStarted = asJson( + await call("POST", `/jobs/${neverStarted.job.id}/cancel`, neverStarted.key), +); +const cancelEnded = asJson( + await call("POST", `/jobs/${endedWithLog.job.id}/cancel`, endedWithLog.key), +); +const cancel = { + _provenance: provenance( + "POST /compute/jobs/:id/cancel", + "a running job twice, a running job while the cluster cannot be reached, a job that never started, a finished job", + "Real route, no body, no key. A cancel never refuses by state: an ended job answers 200 `already_ended` with `cancelled: false`. The Tapis stand-in carries out the cancel of a running job at once, so the state is already `cancelled`; with the stand-in down the intent is recorded and the job stays live (`cluster_down`).", + ), + running: cancelRunning, + running_again: cancelAgain, + running_read_after: afterCancel, + cluster_down: cancelClusterDown, + cluster_down_again: cancelClusterDownAgain, + cluster_down_read_after: readClusterDown, + never_started: cancelNeverStarted, + finished: cancelEnded, +}; + +// --- Refusals ----------------------------------------------------------------------------------------- + +const stranger = await personWithKey(db, { access: "active" }); +const strangerKey = stranger.key; +const pending = await personWithKey(db, { status: "pending", access: "none" }); +const ABSENT = "job_000000000000000000000000"; +const jobRoutes = [ + ["GET", (id) => `/me/jobs/${id}`], + ["GET", (id) => `/jobs/${id}/logs`], + ["GET", (id) => `/jobs/${id}/results`], + ["POST", (id) => `/jobs/${id}/results/renew`], + ["POST", (id) => `/jobs/${id}/cancel`], +]; +const notFound = {}; +for (const [method, path] of jobRoutes) { + const label = `${method} ${path("")}`; + notFound[label] = { + foreign: asJson(await call(method, path(lifecycleJob.job.id), strangerKey)), + absent: asJson(await call(method, path(ABSENT), ownerKey)), + malformed: asJson(await call(method, path("nope"), ownerKey)), + }; +} +const errorsJob = { + _provenance: provenance( + "the job routes", + "a foreign job, an absent id and a malformed id on every job route; no credential; an account that is not approved", + "Real refusals. A foreign, an absent and a malformed id answer the same bytes on every route (no route is an oracle). The 401 and 403 are authMiddleware's own shapes.", + ), + job_not_found: notFound, + no_credential: asJson(await call("GET", `/me/jobs/${ABSENT}`, null)), + account_not_approved: asJson(await call("GET", `/me/jobs/${ABSENT}`, pending.key)), + invalid_after: asJson( + await call("GET", `/jobs/${many.job.id}/results?after=${"x".repeat(2000)}`, many.key), + ), +}; + +// --- Write -------------------------------------------------------------------------------------------- + +const files = { + "job-states.json": jobStates, + "job-failure-codes.json": jobFailureCodes, + "job-cancel-requested.json": jobCancelRequested, + "job-stale.json": jobStale, + "job-lifecycle.json": jobLifecycle, + "logs.json": logs, + "results.json": results, + "cancel.json": cancel, + "errors-job.json": errorsJob, +}; +await mkdir(OUT, { recursive: true }); +for (const [name, body] of Object.entries(files)) { + await writeFile(join(OUT, name), `${JSON.stringify(body, null, 2)}\n`); +} +console.log(`wrote ${Object.keys(files).length} files under ${OUT}`); +await fx.dispose(); +process.exit(0); diff --git a/test/fixtures/compute/cancel.json b/test/fixtures/compute/cancel.json new file mode 100644 index 00000000..451928c1 --- /dev/null +++ b/test/fixtures/compute/cancel.json @@ -0,0 +1,121 @@ +{ + "_provenance": { + "command": "NEMAR_CLI_DIR= bun scripts/capture-compute-job-fixtures.mjs", + "nemar_cli_commit": "27eecff9", + "route": "POST /compute/jobs/:id/cancel", + "request": "a running job twice, a running job while the cluster cannot be reached, a job that never started, a finished job", + "note": "Real route, no body, no key. A cancel never refuses by state: an ended job answers 200 `already_ended` with `cancelled: false`. The Tapis stand-in carries out the cancel of a running job at once, so the state is already `cancelled`; with the stand-in down the intent is recorded and the job stays live (`cluster_down`)." + }, + "running": { + "status": 200, + "body": { + "ok": true, + "state": "cancelled", + "outcome": "cancel_requested", + "cancelled": true + } + }, + "running_again": { + "status": 200, + "body": { + "ok": true, + "state": "cancelled", + "outcome": "already_cancelled", + "cancelled": true + } + }, + "running_read_after": { + "status": 200, + "body": { + "job": { + "id": "job_c833610cdf79be276f6a4d31", + "kind": "batch", + "source": "cli", + "state": "cancelled", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-07 15:35:59", + "started_at": "2026-11-07 15:35:59", + "ended_at": "2026-11-07 15:35:59", + "charged_milli": 1000, + "failure_code": null, + "cancel_requested": true + }, + "stale": false + } + }, + "cluster_down": { + "status": 200, + "body": { + "ok": true, + "state": "running", + "outcome": "cancel_requested", + "cancelled": true + } + }, + "cluster_down_again": { + "status": 200, + "body": { + "ok": true, + "state": "running", + "outcome": "cancel_requested", + "cancelled": true + } + }, + "cluster_down_read_after": { + "status": 200, + "body": { + "job": { + "id": "job_3b0e82679bfb6659f6d3c931", + "kind": "batch", + "source": "cli", + "state": "running", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-07 15:35:59", + "started_at": "2026-11-07 15:35:59", + "ended_at": null, + "charged_milli": 0, + "failure_code": null, + "cancel_requested": true + }, + "stale": false + } + }, + "never_started": { + "status": 200, + "body": { + "ok": true, + "state": "cancelled", + "outcome": "cancel_requested", + "cancelled": true + } + }, + "finished": { + "status": 200, + "body": { + "ok": true, + "state": "finished", + "outcome": "already_ended", + "cancelled": false + } + } +} diff --git a/test/fixtures/compute/errors-job.json b/test/fixtures/compute/errors-job.json new file mode 100644 index 00000000..7cbdd227 --- /dev/null +++ b/test/fixtures/compute/errors-job.json @@ -0,0 +1,148 @@ +{ + "_provenance": { + "command": "NEMAR_CLI_DIR= bun scripts/capture-compute-job-fixtures.mjs", + "nemar_cli_commit": "27eecff9", + "route": "the job routes", + "request": "a foreign job, an absent id and a malformed id on every job route; no credential; an account that is not approved", + "note": "Real refusals. A foreign, an absent and a malformed id answer the same bytes on every route (no route is an oracle). The 401 and 403 are authMiddleware's own shapes." + }, + "job_not_found": { + "GET /me/jobs/": { + "foreign": { + "status": 404, + "body": { + "error": "No such job.", + "code": "job_not_found" + } + }, + "absent": { + "status": 404, + "body": { + "error": "No such job.", + "code": "job_not_found" + } + }, + "malformed": { + "status": 404, + "body": { + "error": "No such job.", + "code": "job_not_found" + } + } + }, + "GET /jobs//logs": { + "foreign": { + "status": 404, + "body": { + "error": "No such job.", + "code": "job_not_found" + } + }, + "absent": { + "status": 404, + "body": { + "error": "No such job.", + "code": "job_not_found" + } + }, + "malformed": { + "status": 404, + "body": { + "error": "No such job.", + "code": "job_not_found" + } + } + }, + "GET /jobs//results": { + "foreign": { + "status": 404, + "body": { + "error": "No such job.", + "code": "job_not_found" + } + }, + "absent": { + "status": 404, + "body": { + "error": "No such job.", + "code": "job_not_found" + } + }, + "malformed": { + "status": 404, + "body": { + "error": "No such job.", + "code": "job_not_found" + } + } + }, + "POST /jobs//results/renew": { + "foreign": { + "status": 404, + "body": { + "error": "No such job.", + "code": "job_not_found" + } + }, + "absent": { + "status": 404, + "body": { + "error": "No such job.", + "code": "job_not_found" + } + }, + "malformed": { + "status": 404, + "body": { + "error": "No such job.", + "code": "job_not_found" + } + } + }, + "POST /jobs//cancel": { + "foreign": { + "status": 404, + "body": { + "error": "No such job.", + "code": "job_not_found" + } + }, + "absent": { + "status": 404, + "body": { + "error": "No such job.", + "code": "job_not_found" + } + }, + "malformed": { + "status": 404, + "body": { + "error": "No such job.", + "code": "job_not_found" + } + } + } + }, + "no_credential": { + "status": 401, + "body": { + "error": "Missing Authorization header" + } + }, + "account_not_approved": { + "status": 403, + "body": { + "error": "Account not approved", + "status": "pending", + "message": "Verify your email address to activate your account. Check your inbox for the verification link, or run 'nemar auth resend-verification' to get a new one." + } + }, + "invalid_after": { + "status": 400, + "body": { + "error": "The request is not valid.", + "code": "invalid_spec", + "field": "after" + } + } +} diff --git a/test/fixtures/compute/job-cancel-requested.json b/test/fixtures/compute/job-cancel-requested.json new file mode 100644 index 00000000..70c626b2 --- /dev/null +++ b/test/fixtures/compute/job-cancel-requested.json @@ -0,0 +1,38 @@ +{ + "_provenance": { + "command": "NEMAR_CLI_DIR= bun scripts/capture-compute-job-fixtures.mjs", + "nemar_cli_commit": "27eecff9", + "route": "GET /compute/me/jobs/:id", + "request": "a running job with a cancel recorded", + "note": "Real route over a row written with fixed times: `cancel_requested` is true while the state is still live." + }, + "running": { + "status": 200, + "body": { + "job": { + "id": "job_00000000000000000000001c", + "kind": "batch", + "source": "cli", + "state": "running", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": null, + "charged_milli": 0, + "failure_code": null, + "cancel_requested": true + }, + "stale": false + } + } +} diff --git a/test/fixtures/compute/job-failure-codes.json b/test/fixtures/compute/job-failure-codes.json new file mode 100644 index 00000000..ea20114b --- /dev/null +++ b/test/fixtures/compute/job-failure-codes.json @@ -0,0 +1,502 @@ +{ + "_provenance": { + "command": "NEMAR_CLI_DIR= bun scripts/capture-compute-job-fixtures.mjs", + "nemar_cli_commit": "27eecff9", + "route": "GET /compute/me/jobs/:id", + "request": "one failed job per failure code (COMPUTE_FAILURE_CODES, 17)", + "note": "Real route over rows written with fixed times. The user view carries `failure_code` only: `failure_detail` and `platform_failure` are not served." + }, + "code_fetch_failed": { + "status": 200, + "body": { + "job": { + "id": "job_00000000000000000000000b", + "kind": "batch", + "source": "cli", + "state": "failed", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": "2026-11-05 09:50:00", + "charged_milli": 500, + "failure_code": "code_fetch_failed", + "cancel_requested": false + }, + "stale": false + } + }, + "dataset_fetch_failed": { + "status": 200, + "body": { + "job": { + "id": "job_00000000000000000000000c", + "kind": "batch", + "source": "cli", + "state": "failed", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": "2026-11-05 09:50:00", + "charged_milli": 500, + "failure_code": "dataset_fetch_failed", + "cancel_requested": false + }, + "stale": false + } + }, + "entry_not_found": { + "status": 200, + "body": { + "job": { + "id": "job_00000000000000000000000d", + "kind": "batch", + "source": "cli", + "state": "failed", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": "2026-11-05 09:50:00", + "charged_milli": 500, + "failure_code": "entry_not_found", + "cancel_requested": false + }, + "stale": false + } + }, + "runtime_error": { + "status": 200, + "body": { + "job": { + "id": "job_00000000000000000000000e", + "kind": "batch", + "source": "cli", + "state": "failed", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": "2026-11-05 09:50:00", + "charged_milli": 500, + "failure_code": "runtime_error", + "cancel_requested": false + }, + "stale": false + } + }, + "out_of_memory": { + "status": 200, + "body": { + "job": { + "id": "job_00000000000000000000000f", + "kind": "batch", + "source": "cli", + "state": "failed", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": "2026-11-05 09:50:00", + "charged_milli": 500, + "failure_code": "out_of_memory", + "cancel_requested": false + }, + "stale": false + } + }, + "time_limit": { + "status": 200, + "body": { + "job": { + "id": "job_000000000000000000000010", + "kind": "batch", + "source": "cli", + "state": "failed", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": "2026-11-05 09:50:00", + "charged_milli": 500, + "failure_code": "time_limit", + "cancel_requested": false + }, + "stale": false + } + }, + "result_upload_failed": { + "status": 200, + "body": { + "job": { + "id": "job_000000000000000000000011", + "kind": "batch", + "source": "cli", + "state": "failed", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": "2026-11-05 09:50:00", + "charged_milli": 500, + "failure_code": "result_upload_failed", + "cancel_requested": false + }, + "stale": false + } + }, + "tapis_submit_failed": { + "status": 200, + "body": { + "job": { + "id": "job_000000000000000000000012", + "kind": "batch", + "source": "cli", + "state": "failed", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": "2026-11-05 09:50:00", + "charged_milli": 500, + "failure_code": "tapis_submit_failed", + "cancel_requested": false + }, + "stale": false + } + }, + "submit_timeout": { + "status": 200, + "body": { + "job": { + "id": "job_000000000000000000000013", + "kind": "batch", + "source": "cli", + "state": "failed", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": "2026-11-05 09:50:00", + "charged_milli": 500, + "failure_code": "submit_timeout", + "cancel_requested": false + }, + "stale": false + } + }, + "staging_failed": { + "status": 200, + "body": { + "job": { + "id": "job_000000000000000000000014", + "kind": "batch", + "source": "cli", + "state": "failed", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": "2026-11-05 09:50:00", + "charged_milli": 500, + "failure_code": "staging_failed", + "cancel_requested": false + }, + "stale": false + } + }, + "launch_failed": { + "status": 200, + "body": { + "job": { + "id": "job_000000000000000000000015", + "kind": "batch", + "source": "cli", + "state": "failed", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": "2026-11-05 09:50:00", + "charged_milli": 500, + "failure_code": "launch_failed", + "cancel_requested": false + }, + "stale": false + } + }, + "archive_failed": { + "status": 200, + "body": { + "job": { + "id": "job_000000000000000000000016", + "kind": "batch", + "source": "cli", + "state": "failed", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": "2026-11-05 09:50:00", + "charged_milli": 500, + "failure_code": "archive_failed", + "cancel_requested": false + }, + "stale": false + } + }, + "tapis_error": { + "status": 200, + "body": { + "job": { + "id": "job_000000000000000000000017", + "kind": "batch", + "source": "cli", + "state": "failed", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": "2026-11-05 09:50:00", + "charged_milli": 500, + "failure_code": "tapis_error", + "cancel_requested": false + }, + "stale": false + } + }, + "result_verification_failed": { + "status": 200, + "body": { + "job": { + "id": "job_000000000000000000000018", + "kind": "batch", + "source": "cli", + "state": "failed", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": "2026-11-05 09:50:00", + "charged_milli": 500, + "failure_code": "result_verification_failed", + "cancel_requested": false + }, + "stale": false + } + }, + "records_unavailable": { + "status": 200, + "body": { + "job": { + "id": "job_000000000000000000000019", + "kind": "batch", + "source": "cli", + "state": "failed", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": "2026-11-05 09:50:00", + "charged_milli": 500, + "failure_code": "records_unavailable", + "cancel_requested": false + }, + "stale": false + } + }, + "tapis_record_lost": { + "status": 200, + "body": { + "job": { + "id": "job_00000000000000000000001a", + "kind": "batch", + "source": "cli", + "state": "failed", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": "2026-11-05 09:50:00", + "charged_milli": 500, + "failure_code": "tapis_record_lost", + "cancel_requested": false + }, + "stale": false + } + }, + "upload_expired": { + "status": 200, + "body": { + "job": { + "id": "job_00000000000000000000001b", + "kind": "batch", + "source": "cli", + "state": "failed", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": "2026-11-05 09:50:00", + "charged_milli": 500, + "failure_code": "upload_expired", + "cancel_requested": false + }, + "stale": false + } + } +} diff --git a/test/fixtures/compute/job-lifecycle.json b/test/fixtures/compute/job-lifecycle.json new file mode 100644 index 00000000..30d3d293 --- /dev/null +++ b/test/fixtures/compute/job-lifecycle.json @@ -0,0 +1,68 @@ +{ + "_provenance": { + "command": "NEMAR_CLI_DIR= bun scripts/capture-compute-job-fixtures.mjs", + "nemar_cli_commit": "27eecff9", + "route": "GET /compute/me/jobs/:id", + "request": "one job through makeJob, submitComputeJob, QUEUED, RUNNING, FINISHED", + "note": "Real route over a job taken through the real lifecycle against the Tapis stand-in; the launcher's last step (its files and `declared.json`) is played by the backend's own helper. Ids and times are of the run that wrote this file." + }, + "job_id": "job_43ba0cc1a4808fad916c2c97", + "running": { + "status": 200, + "body": { + "job": { + "id": "job_43ba0cc1a4808fad916c2c97", + "kind": "batch", + "source": "cli", + "state": "running", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-07 15:35:57", + "started_at": "2026-11-07 15:35:57", + "ended_at": null, + "charged_milli": 0, + "failure_code": null, + "cancel_requested": false + }, + "stale": false + } + }, + "finished": { + "status": 200, + "body": { + "job": { + "id": "job_43ba0cc1a4808fad916c2c97", + "kind": "batch", + "source": "cli", + "state": "finished", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-07 15:35:57", + "started_at": "2026-11-07 15:05:57", + "ended_at": "2026-11-07 15:35:57", + "charged_milli": 2000, + "failure_code": null, + "cancel_requested": false + }, + "stale": false + } + } +} diff --git a/test/fixtures/compute/job-stale.json b/test/fixtures/compute/job-stale.json new file mode 100644 index 00000000..d750b2f4 --- /dev/null +++ b/test/fixtures/compute/job-stale.json @@ -0,0 +1,39 @@ +{ + "_provenance": { + "command": "NEMAR_CLI_DIR= bun scripts/capture-compute-job-fixtures.mjs", + "nemar_cli_commit": "27eecff9", + "route": "GET /compute/me/jobs/:id", + "request": "a submitted job whose last cluster read is ten minutes old, with the Tapis stand-in down", + "note": "Real route: the refresh failed, so the stored record is served with `stale: true`." + }, + "job_id": "job_50f3a028f61ee1ff1f2564ae", + "submitted": { + "status": 200, + "body": { + "job": { + "id": "job_50f3a028f61ee1ff1f2564ae", + "kind": "batch", + "source": "cli", + "state": "submitted", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-07 15:35:57", + "started_at": null, + "ended_at": null, + "charged_milli": 0, + "failure_code": null, + "cancel_requested": false + }, + "stale": true + } + } +} diff --git a/test/fixtures/compute/job-states.json b/test/fixtures/compute/job-states.json new file mode 100644 index 00000000..025dc016 --- /dev/null +++ b/test/fixtures/compute/job-states.json @@ -0,0 +1,299 @@ +{ + "_provenance": { + "command": "NEMAR_CLI_DIR= bun scripts/capture-compute-job-fixtures.mjs", + "nemar_cli_commit": "27eecff9", + "route": "GET /compute/me/jobs/:id", + "request": "one job in each of the ten states, by id", + "note": "Real route over rows written with fixed times. A live job has no Tapis job, so nothing is refreshed and `stale` is absent. Times are the database's `YYYY-MM-DD HH:MM:SS` UTC. The route serves no name, no fault attribution and no hold." + }, + "created": { + "status": 200, + "body": { + "job": { + "id": "job_000000000000000000000001", + "kind": "batch", + "source": "cli", + "state": "created", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": null, + "ended_at": null, + "charged_milli": 0, + "failure_code": null, + "cancel_requested": false + }, + "stale": false + } + }, + "uploading": { + "status": 200, + "body": { + "job": { + "id": "job_000000000000000000000002", + "kind": "batch", + "source": "cli", + "state": "uploading", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": null, + "ended_at": null, + "charged_milli": 0, + "failure_code": null, + "cancel_requested": false + }, + "stale": false + } + }, + "submitted": { + "status": 200, + "body": { + "job": { + "id": "job_000000000000000000000003", + "kind": "batch", + "source": "cli", + "state": "submitted", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": null, + "ended_at": null, + "charged_milli": 0, + "failure_code": null, + "cancel_requested": false + }, + "stale": false + } + }, + "queued": { + "status": 200, + "body": { + "job": { + "id": "job_000000000000000000000004", + "kind": "batch", + "source": "cli", + "state": "queued", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": null, + "ended_at": null, + "charged_milli": 0, + "failure_code": null, + "cancel_requested": false + }, + "stale": false + } + }, + "running": { + "status": 200, + "body": { + "job": { + "id": "job_000000000000000000000005", + "kind": "batch", + "source": "cli", + "state": "running", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": null, + "charged_milli": 0, + "failure_code": null, + "cancel_requested": false + }, + "stale": false + } + }, + "archiving": { + "status": 200, + "body": { + "job": { + "id": "job_000000000000000000000006", + "kind": "batch", + "source": "cli", + "state": "archiving", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": null, + "charged_milli": 0, + "failure_code": null, + "cancel_requested": false + }, + "stale": false + } + }, + "finished": { + "status": 200, + "body": { + "job": { + "id": "job_000000000000000000000007", + "kind": "batch", + "source": "cli", + "state": "finished", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": 8192, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": "2026-11-05 09:50:00", + "charged_milli": 2500, + "failure_code": null, + "cancel_requested": false + }, + "stale": false + } + }, + "failed": { + "status": 200, + "body": { + "job": { + "id": "job_000000000000000000000008", + "kind": "batch", + "source": "cli", + "state": "failed", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": "2026-11-05 09:10:00", + "ended_at": "2026-11-05 09:50:00", + "charged_milli": 1250, + "failure_code": "runtime_error", + "cancel_requested": false + }, + "stale": false + } + }, + "cancelled": { + "status": 200, + "body": { + "job": { + "id": "job_000000000000000000000009", + "kind": "batch", + "source": "cli", + "state": "cancelled", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": null, + "ended_at": "2026-11-05 09:50:00", + "charged_milli": 0, + "failure_code": null, + "cancel_requested": false + }, + "stale": false + } + }, + "unreported": { + "status": 200, + "body": { + "job": { + "id": "job_00000000000000000000000a", + "kind": "batch", + "source": "cli", + "state": "unreported", + "app_id": "nemar-launch", + "app_version": "1.0.0", + "partition": "shared", + "pool": "cpu", + "resources": { + "nodes": 1, + "cores_per_node": 4, + "memory_mb": null, + "gpus": 0, + "minutes": 60 + }, + "created_at": "2026-11-05 09:00:00", + "started_at": null, + "ended_at": null, + "charged_milli": 0, + "failure_code": null, + "cancel_requested": false + }, + "stale": false + } + } +} diff --git a/test/fixtures/compute/logs.json b/test/fixtures/compute/logs.json new file mode 100644 index 00000000..4a8515f3 --- /dev/null +++ b/test/fixtures/compute/logs.json @@ -0,0 +1,78 @@ +{ + "_provenance": { + "command": "NEMAR_CLI_DIR= bun scripts/capture-compute-job-fixtures.mjs", + "nemar_cli_commit": "27eecff9", + "route": "GET /compute/jobs/:id/logs", + "request": "a running job (from Tapis), an empty log, a hostile log, a log over 1 MiB, a job that has not started, an ended job", + "note": "Real route. The body is the job's own bytes as `text/plain`, `nosniff`, `no-store`; `X-Nemar-Truncated: true` only when cut at 1 MiB. The route serves the FIRST 1 MiB and has no `tail` (nemar-cli#2094). The hostile log's bytes are written to the Tapis stand-in's output and read back through the route." + }, + "live": { + "status": 200, + "headers": { + "content-type": "text/plain; charset=utf-8", + "cache-control": "no-store", + "x-content-type-options": "nosniff" + }, + "text": "step one\nstep two\n" + }, + "live_before_output": { + "status": 404, + "headers": { + "content-type": "application/json", + "cache-control": "no-store" + }, + "body": { + "error": "The job has no log yet.", + "code": "logs_not_available" + } + }, + "ended": { + "status": 200, + "headers": { + "content-type": "text/plain; charset=utf-8", + "cache-control": "no-store", + "x-content-type-options": "nosniff" + }, + "text": "Traceback (most recent call last):\n File \"main.py\", line 3, in \n print(1 / 0)\nZeroDivisionError: division by zero\n" + }, + "empty": { + "status": 200, + "headers": { + "content-type": "text/plain; charset=utf-8", + "cache-control": "no-store", + "x-content-type-options": "nosniff" + }, + "text": "" + }, + "hostile": { + "status": 200, + "headers": { + "content-type": "text/plain; charset=utf-8", + "cache-control": "no-store", + "x-content-type-options": "nosniff" + }, + "text": "plain line\n\u001b[31mred\u001b[0m and \u001b[2K cleared\nlink \u001b]8;;https://example.org\u0007text\u001b]8;;\u0007 end\nprogress 10%\rprogress 50%\rprogress 100%\nnul \u0000 bell \u0007 next-line … end\noverride ‮gnp.exe and isolate ⁦x⁩ and zero​width\n & \"quotes\" back\\slash\nTraceback (most recent call last):\n File \"main.py\", line 3, in \nZeroDivisionError: division by zero\n" + }, + "truncated": { + "status": 200, + "headers": { + "content-type": "text/plain; charset=utf-8", + "cache-control": "no-store", + "x-content-type-options": "nosniff", + "x-nemar-truncated": "true" + }, + "byte_length": 1048576, + "note": "Headers and length only: the body is the first 1 MiB of 'x', which the test rebuilds." + }, + "not_available": { + "status": 404, + "headers": { + "content-type": "application/json", + "cache-control": "no-store" + }, + "body": { + "error": "The job has no log yet.", + "code": "logs_not_available" + } + } +} diff --git a/test/fixtures/compute/results.json b/test/fixtures/compute/results.json new file mode 100644 index 00000000..68fcf1e0 --- /dev/null +++ b/test/fixtures/compute/results.json @@ -0,0 +1,141 @@ +{ + "_provenance": { + "command": "NEMAR_CLI_DIR= bun scripts/capture-compute-job-fixtures.mjs", + "nemar_cli_commit": "27eecff9", + "route": "GET|POST /compute/jobs/:id/results[/renew]", + "request": "a finished job with three outputs; a job with more outputs than one page (cursor); a job that is not finished; a job whose retention passed; a failed job", + "note": "Real routes. Both verbs mint NEW 7-day presigned links (a renewal is the same handler). Presigned addresses point at the local object-store stand-in and carry test signatures that expire. `bearer_links` and `notice` come from the route. Files are in path order. The retention rule is the backend's: expired once `now > ended_at + results_days` (the job in `expired` had its `ended_at` moved 40 days back)." + }, + "job_id": "job_43ba0cc1a4808fad916c2c97", + "get": { + "status": 200, + "body": { + "expires_at": "2026-11-14T15:35:57.000Z", + "files": [ + { + "path": "figures/plot.json", + "size": 13, + "sha256": "401592ba6d3e44c4697ec7f6e2c8500d8114f2b1b14d49e8cc1c1fb547f01040", + "url": "http://127.0.0.1:52938/nemar-compute-results/jobs/job_43ba0cc1a4808fad916c2c97/outputs/figures/plot.json?X-Amz-Expires=604800&X-Amz-Date=20261107T153557Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=STANDINKEYID%2F20261107%2Fauto%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=630055ce57a3b1dbcdee96587850039e865a02c9d33bbcb3b4be114659770d9c" + }, + { + "path": "report.txt", + "size": 11, + "sha256": "c7976f1dbff10006eb9bf2d22a7959fee2fdadff032f0b57844e54138a1f7d8e", + "url": "http://127.0.0.1:52938/nemar-compute-results/jobs/job_43ba0cc1a4808fad916c2c97/outputs/report.txt?X-Amz-Expires=604800&X-Amz-Date=20261107T153557Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=STANDINKEYID%2F20261107%2Fauto%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=3ddf4470d94ad32fb682b0a48aca48e8d48b2bf287b36c6d84beb1d252571a98" + }, + { + "path": "table.csv", + "size": 8, + "sha256": "492d5ea496056f1a6a6592241032fab764c321596317930b4fa0e1e8bc3b7470", + "url": "http://127.0.0.1:52938/nemar-compute-results/jobs/job_43ba0cc1a4808fad916c2c97/outputs/table.csv?X-Amz-Expires=604800&X-Amz-Date=20261107T153557Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=STANDINKEYID%2F20261107%2Fauto%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=239852ab0ecac640de980dc985a545421e56fa7e8ec8faa58df753271f0e242d" + } + ], + "total": 3, + "truncated": false, + "next_after": null, + "bearer_links": true, + "notice": "Anyone who holds a link can download that file until the link expires; keep them private." + } + }, + "renew": { + "status": 200, + "body": { + "expires_at": "2026-11-14T15:35:57.000Z", + "files": [ + { + "path": "figures/plot.json", + "size": 13, + "sha256": "401592ba6d3e44c4697ec7f6e2c8500d8114f2b1b14d49e8cc1c1fb547f01040", + "url": "http://127.0.0.1:52938/nemar-compute-results/jobs/job_43ba0cc1a4808fad916c2c97/outputs/figures/plot.json?X-Amz-Expires=604800&X-Amz-Date=20261107T153557Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=STANDINKEYID%2F20261107%2Fauto%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=630055ce57a3b1dbcdee96587850039e865a02c9d33bbcb3b4be114659770d9c" + }, + { + "path": "report.txt", + "size": 11, + "sha256": "c7976f1dbff10006eb9bf2d22a7959fee2fdadff032f0b57844e54138a1f7d8e", + "url": "http://127.0.0.1:52938/nemar-compute-results/jobs/job_43ba0cc1a4808fad916c2c97/outputs/report.txt?X-Amz-Expires=604800&X-Amz-Date=20261107T153557Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=STANDINKEYID%2F20261107%2Fauto%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=3ddf4470d94ad32fb682b0a48aca48e8d48b2bf287b36c6d84beb1d252571a98" + }, + { + "path": "table.csv", + "size": 8, + "sha256": "492d5ea496056f1a6a6592241032fab764c321596317930b4fa0e1e8bc3b7470", + "url": "http://127.0.0.1:52938/nemar-compute-results/jobs/job_43ba0cc1a4808fad916c2c97/outputs/table.csv?X-Amz-Expires=604800&X-Amz-Date=20261107T153557Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=STANDINKEYID%2F20261107%2Fauto%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=239852ab0ecac640de980dc985a545421e56fa7e8ec8faa58df753271f0e242d" + } + ], + "total": 3, + "truncated": false, + "next_after": null, + "bearer_links": true, + "notice": "Anyone who holds a link can download that file until the link expires; keep them private." + } + }, + "many_job_id": "job_9acd6e17f55a2c43f855187b", + "many_first_page": { + "status": 200, + "summary": { + "file_count": 1000, + "total": 1002, + "truncated": true, + "next_after": "out/file-00999.txt", + "bearer_links": true, + "notice": "Anyone who holds a link can download that file until the link expires; keep them private.", + "expires_at": "2026-11-14T15:35:58.000Z", + "first_path": "out/file-00000.txt", + "last_path": "out/file-00999.txt", + "note": "The files array (1,000 presigned links) is elided; the second page below is stored whole." + } + }, + "many_second_page": { + "status": 200, + "body": { + "expires_at": "2026-11-14T15:35:59.000Z", + "files": [ + { + "path": "out/file-01000.txt", + "size": 6, + "sha256": "12de08b5c8d278d6f63ca5b2dee1286c7330577bf8ffb6fe9ab0a3ff0b35d84b", + "url": "http://127.0.0.1:52938/nemar-compute-results/jobs/job_9acd6e17f55a2c43f855187b/outputs/out/file-01000.txt?X-Amz-Expires=604800&X-Amz-Date=20261107T153559Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=STANDINKEYID%2F20261107%2Fauto%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=5a784b8044b6c8872907f3fb7442edac9e4e7e6b0fedaabb1210d2bd1c075a22" + }, + { + "path": "out/file-01001.txt", + "size": 6, + "sha256": "691aea8bf48b1433ff3f8bee33d7b745a77a4b6c3cfcb5930c1915cc5acaa95c", + "url": "http://127.0.0.1:52938/nemar-compute-results/jobs/job_9acd6e17f55a2c43f855187b/outputs/out/file-01001.txt?X-Amz-Expires=604800&X-Amz-Date=20261107T153559Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=STANDINKEYID%2F20261107%2Fauto%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=e7dd3532c0e60128367ee3ca4889ecaedfbb5d83a172f47fe06086e17e4feb4a" + } + ], + "total": 1002, + "truncated": false, + "next_after": null, + "bearer_links": true, + "notice": "Anyone who holds a link can download that file until the link expires; keep them private." + } + }, + "bad_state": { + "status": 409, + "body": { + "error": "The job is not in a state that accepts this.", + "code": "bad_state" + } + }, + "expired": { + "status": 410, + "body": { + "error": "The results of this job have expired.", + "code": "results_expired" + } + }, + "expired_renew": { + "status": 410, + "body": { + "error": "The results of this job have expired.", + "code": "results_expired" + } + }, + "failed": { + "status": 409, + "body": { + "error": "The job is not in a state that accepts this.", + "code": "bad_state" + } + } +} From 1337ff1b89314727e5fd62ceeb55977b4c2bcd41 Mon Sep 17 00:00:00 2001 From: Seyed Yahya Shirazi Date: Sat, 7 Nov 2026 07:37:09 -0800 Subject: [PATCH 02/17] Transcribe job page vocabulary with drift test --- .github/workflows/ci.yml | 9 ++ src/lib/compute-contract.ts | 87 ++++++++++++++ test/compute-contract-drift.test.ts | 34 ++++++ test/compute-contract-drift.ts | 44 +++++++ test/compute-job-contract-drift.test.ts | 150 ++++++++++++++++++++++++ 5 files changed, 324 insertions(+) create mode 100644 test/compute-job-contract-drift.test.ts diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index da73b676..f868e9e1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -127,6 +127,11 @@ jobs: # shared/contract/compute-user.ts and compute.ts: the job states, front doors, usage groups, # page bounds and read-refusal words the /compute page branches on (phase E2). Same `dev` # pairing, strict, and red until the compute epic reaches nemar-cli `dev`. + # test/compute-job-contract-drift.test.ts is an ELEVENTH, against shared/compute-state.ts, + # shared/contract/compute-submit.ts and compute-responses.ts: the failure codes, the refusal + # statuses, the truncated-log header, the bounds and the cancel outcomes the job page + # (phase E3) branches on. Same `dev` pairing, strict, and red until the compute epic reaches + # nemar-cli `dev`. # test/compute-admin-contract-drift.test.ts is a TENTH: the compute state machine, the decision # words and the bounds the admin Compute tab branches on (compute-access-state.ts, # compute-state.ts, contract/compute-access.ts, contract/compute-admin.ts). Same `dev` pairing, @@ -141,6 +146,8 @@ jobs: /shared/contract/account-copy.ts /shared/contract/compute-access.ts /shared/contract/compute-admin.ts + /shared/contract/compute-responses.ts + /shared/contract/compute-submit.ts /shared/contract/compute-terms.ts /shared/contract/compute-user.ts /shared/contract/compute.ts @@ -160,6 +167,8 @@ jobs: NEMAR_CLI_ACCOUNT_COPY: nemar-cli-contract/shared/contract/account-copy.ts NEMAR_CLI_COMPUTE_ACCESS_CONTRACT: nemar-cli-contract/shared/contract/compute-terms.ts NEMAR_CLI_COMPUTE_CONTRACT: nemar-cli-contract/shared/contract/compute.ts + NEMAR_CLI_COMPUTE_RESPONSES_CONTRACT: nemar-cli-contract/shared/contract/compute-responses.ts + NEMAR_CLI_COMPUTE_SUBMIT_CONTRACT: nemar-cli-contract/shared/contract/compute-submit.ts NEMAR_CLI_COMPUTE_STATE: nemar-cli-contract/shared/compute-state.ts NEMAR_CLI_COMPUTE_USER_CONTRACT: nemar-cli-contract/shared/contract/compute-user.ts NEMAR_CLI_COMPUTE_ADMIN_CONTRACT: nemar-cli-contract/shared/contract/compute-admin.ts diff --git a/src/lib/compute-contract.ts b/src/lib/compute-contract.ts index f02c6e4d..800d4dd2 100644 --- a/src/lib/compute-contract.ts +++ b/src/lib/compute-contract.ts @@ -10,6 +10,12 @@ * - `shared/contract/compute-user.ts`: the page bounds, the usage groups, the minimum queue sample, * and the words a read refusal carries. * - `shared/contract/compute.ts`: the job id shape. + * - `shared/compute-state.ts` again (phase E3, the job page): the three groups of failure codes and + * the status each job-route refusal answers with. + * - `shared/contract/compute-submit.ts` (phase E3): the truncated-log header, the log and result-page + * bounds, and the one sentence this site transcribes (`upload_expired`; every other refusal sentence + * is shown as the backend served it). + * - `shared/contract/compute-responses.ts` (phase E3): the cancel outcomes. * * This is the ONE place the job-state and front-door vocabulary lives on this site * (`COMPUTE_JOB_STATES`, `COMPUTE_JOB_SOURCES`, ...): the dashboard and the admin compute tab import it. @@ -81,3 +87,84 @@ export function isComputeJobState(value: unknown): value is ComputeJobState { export function isTerminalComputeState(state: string): boolean { return (COMPUTE_TERMINAL_STATES as readonly string[]).includes(state); } + +// --- The job page (phase E3, website#496) --------------------------------------------------------- + +/** + * What the launcher on the node writes, in the order of its exit numbers (nemar-cli + * `LAUNCHER_FAILURE_CODES`). + */ +export const COMPUTE_LAUNCHER_FAILURE_CODES = [ + "code_fetch_failed", + "dataset_fetch_failed", + "entry_not_found", + "runtime_error", + "out_of_memory", + "time_limit", + "result_upload_failed", +] as const; + +/** The failures of the platform's own steps (nemar-cli `PLATFORM_FAILURE_CODES`; three repeat the launcher's). */ +export const COMPUTE_PLATFORM_FAILURE_CODES = [ + "code_fetch_failed", + "dataset_fetch_failed", + "tapis_submit_failed", + "submit_timeout", + "staging_failed", + "launch_failed", + "archive_failed", + "tapis_error", + "result_verification_failed", + "records_unavailable", + "result_upload_failed", + "tapis_record_lost", +] as const; + +/** Failures that are no launcher code (nemar-cli `SUBMITTER_FAILURE_CODES`). */ +export const COMPUTE_SUBMITTER_FAILURE_CODES = ["upload_expired"] as const; + +/** + * Every code a failed job may carry, each once, in the backend's order: the launcher's, the platform's + * rest, the submitter's. The groups above are transcribed and drift-tested separately so a code that + * moves between them still passes. + */ +export const COMPUTE_FAILURE_CODES: readonly string[] = [ + ...COMPUTE_LAUNCHER_FAILURE_CODES, + ...COMPUTE_PLATFORM_FAILURE_CODES.filter( + (c) => !(COMPUTE_LAUNCHER_FAILURE_CODES as readonly string[]).includes(c), + ), + ...COMPUTE_SUBMITTER_FAILURE_CODES, +]; + +/** What `POST /compute/jobs/:id/cancel` may answer in `outcome` today (the field is open). */ +export const COMPUTE_CANCEL_OUTCOMES = [ + "cancel_requested", + "already_cancelled", + "already_ended", +] as const; + +/** The response header on a log cut at {@link COMPUTE_LOG_MAX_BYTES}; its value is `true`. */ +export const COMPUTE_TRUNCATED_HEADER = "X-Nemar-Truncated"; + +/** The most bytes the log route returns: the FIRST 1 MiB of the log. */ +export const COMPUTE_LOG_MAX_BYTES = 1024 * 1024; + +/** The most result links one answer holds; `next_after` pages on. */ +export const COMPUTE_RESULTS_PAGE_MAX = 1000; + +/** The status each refusal of the job routes (log, results, renew, cancel, job read) answers with. */ +export const COMPUTE_JOB_ROUTE_STATUS = { + job_not_found: 404, + logs_not_available: 404, + bad_state: 409, + results_expired: 410, + invalid_spec: 400, + compute_disabled: 503, + storage_unavailable: 503, +} as const; + +export type ComputeJobRouteCode = keyof typeof COMPUTE_JOB_ROUTE_STATUS; + +/** The backend's sentence for a job whose code bundle was never finalized (nemar-cli `COMPUTE_SUBMIT_SENTENCES`). */ +export const COMPUTE_UPLOAD_EXPIRED_SENTENCE = + "The upload window closed and the job was ended; submit it again."; diff --git a/test/compute-contract-drift.test.ts b/test/compute-contract-drift.test.ts index 3ada178a..a3db86bb 100644 --- a/test/compute-contract-drift.test.ts +++ b/test/compute-contract-drift.test.ts @@ -2,8 +2,12 @@ import { describe, expect, it } from "vitest"; import { extractNumber, extractNumberMap, + extractProduct, extractRegexSource, extractSatisfiedArray, + extractSatisfiedNumberMap, + extractString, + extractStringMap, } from "./compute-contract-drift"; import { extractStringArray } from "./mail-contract-drift"; @@ -28,7 +32,37 @@ describe("the extractors", () => { ); }); + it("read the maps, strings and products the job page's contract files use", () => { + const map = [ + "export const STATUS = {", + " a: 403,", + " // 404: a note with a colon: and a number 12", + " b_c: 404,", + "} as const satisfies Record;", + ].join("\n"); + expect(extractSatisfiedNumberMap(map, "STATUS")).toEqual({ a: 403, b_c: 404 }); + const sentences = [ + "export const SENT = {", + " ...OTHER,", + ' one: "First sentence.",', + " two:", + ' "Second; with a semicolon.",', + "} as const satisfies Partial>;", + ].join("\n"); + expect(extractStringMap(sentences, "SENT")).toEqual({ + one: "First sentence.", + two: "Second; with a semicolon.", + }); + expect(extractString('export const H = "X-Nemar-Truncated";', "H")).toBe("X-Nemar-Truncated"); + expect(extractProduct("export const MAX = 1024 * 1024;", "MAX")).toBe(1_048_576); + expect(extractProduct("export const MAX = 1000;", "MAX")).toBe(1000); + }); + it("answer undefined for a computed value, never a guess", () => { + expect(extractProduct("export const N = make(5);", "N")).toBeUndefined(); + expect(extractSatisfiedNumberMap("export const M = build();", "M")).toBeUndefined(); + expect(extractStringMap("export const M = build();", "M")).toBeUndefined(); + expect(extractString("export const S = `a${b}`;", "S")).toBeUndefined(); expect(extractNumber("export const N = 5 * 5;", "N")).toBeUndefined(); expect(extractStringArray("export const L = make();", "L")).toBeUndefined(); expect(extractNumberMap("export const M = build();", "M")).toBeUndefined(); diff --git a/test/compute-contract-drift.ts b/test/compute-contract-drift.ts index 21bd77c6..8462a957 100644 --- a/test/compute-contract-drift.ts +++ b/test/compute-contract-drift.ts @@ -71,3 +71,47 @@ export function extractTargets(source: string, name: string): Record 0 ? out : undefined; } + +/** `export const NAME = { a: 403, // note\n b: 401 } as const satisfies Record<...>;` -> the numbers. */ +export function extractSatisfiedNumberMap( + source: string, + name: string, +): Record | undefined { + const m = stripComments(source).match( + new RegExp(`export\\s+const\\s+${name}\\s*=\\s*\\{([^}]*)\\}\\s*as\\s+const\\s+satisfies[^;]*;`), + ); + if (!m) return undefined; + const out: Record = {}; + for (const entry of m[1].matchAll(/(\w+)\s*:\s*(\d+)/g)) out[entry[1]] = Number(entry[2]); + return Object.keys(out).length > 0 ? out : undefined; +} + +/** `export const NAME = { a: "text", b:\n "more" } as const ...;` -> the strings (spread entries are skipped). */ +export function extractStringMap(source: string, name: string): Record | undefined { + const stripped = stripComments(source); + const start = stripped.search(new RegExp(`export\\s+const\\s+${name}\\s*=\\s*\\{`)); + if (start < 0) return undefined; + const end = stripped.indexOf("} as const", start); + if (end < 0) return undefined; + const out: Record = {}; + for (const m of stripped.slice(start, end).matchAll(/(\w+)\s*:\s*"((?:[^"\\]|\\.)*)"/g)) { + out[m[1]] = m[2]; + } + return Object.keys(out).length > 0 ? out : undefined; +} + +/** `export const NAME = "text";` -> the string. */ +export function extractString(source: string, name: string): string | undefined { + return stripComments(source).match( + new RegExp(`export\\s+const\\s+${name}\\s*=\\s*"((?:[^"\\\\]|\\\\.)*)"\\s*;`), + )?.[1]; +} + +/** `export const NAME = 1024 * 1024;` -> 1048576 (a product of whole numbers; anything else is `undefined`). */ +export function extractProduct(source: string, name: string): number | undefined { + const m = stripComments(source).match( + new RegExp(`export\\s+const\\s+${name}\\s*=\\s*(\\d+(?:\\s*\\*\\s*\\d+)*)\\s*;`), + ); + if (!m) return undefined; + return m[1].split("*").reduce((a, n) => a * Number(n.trim()), 1); +} diff --git a/test/compute-job-contract-drift.test.ts b/test/compute-job-contract-drift.test.ts new file mode 100644 index 00000000..02a39b43 --- /dev/null +++ b/test/compute-job-contract-drift.test.ts @@ -0,0 +1,150 @@ +/** + * Drift check between `src/lib/compute-contract.ts` and nemar-cli's job-route vocabulary (website ADR + * 0030 phase E3 addendum; epic nemarOrg/website#493, issue #496). + * + * Compared as TEXT, like the other contract drift tests: + * - `shared/compute-state.ts`: the launcher, platform and submitter failure codes (the job page has + * one sentence for each) and the status every refusal answers with; + * - `shared/contract/compute-submit.ts`: the truncated-log header, the log and result-page bounds and + * the one refusal sentence this site transcribes (`upload_expired`); + * - `shared/contract/compute-responses.ts`: the cancel outcomes. + * + * CI sparse-checks out nemar-cli `dev` and points `NEMAR_CLI_COMPUTE_STATE`, + * `NEMAR_CLI_COMPUTE_SUBMIT_CONTRACT` and `NEMAR_CLI_COMPUTE_RESPONSES_CONTRACT` at the files. When a + * variable is set it is strict: a missing file FAILS. Without them this looks for a sibling checkout + * and skips visibly when there is none. + * + * EXPECTED RED on a phase PR into the epic branch until the compute epic reaches nemar-cli `dev`. + */ + +import { describe, expect, it } from "vitest"; +import { + COMPUTE_CANCEL_OUTCOMES, + COMPUTE_JOB_ROUTE_STATUS, + COMPUTE_LAUNCHER_FAILURE_CODES, + COMPUTE_LOG_MAX_BYTES, + COMPUTE_PLATFORM_FAILURE_CODES, + COMPUTE_RESULTS_PAGE_MAX, + COMPUTE_SUBMITTER_FAILURE_CODES, + COMPUTE_TRUNCATED_HEADER, + COMPUTE_UPLOAD_EXPIRED_SENTENCE, +} from "../src/lib/compute-contract"; +import { + extractNumber, + extractProduct, + extractSatisfiedNumberMap, + extractString, + extractStringMap, +} from "./compute-contract-drift"; +import { compareLists, extractStringArray } from "./mail-contract-drift"; + +async function nodeFs(): Promise<{ + existsSync(path: string): boolean; + readFileSync(path: string, encoding: string): string; +}> { + const specifier = "node:fs"; + return await import(/* @vite-ignore */ specifier); +} + +async function nodeProcess(): Promise<{ cwd(): string; env: Record }> { + const specifier = "node:process"; + return await import(/* @vite-ignore */ specifier); +} + +const fs = await nodeFs(); +const proc = await nodeProcess(); + +function resolveFromCwd(maybeRelative: string): string { + return maybeRelative.startsWith("/") ? maybeRelative : `${proc.cwd()}/${maybeRelative}`; +} + +interface Source { + readonly envName: string; + readonly candidates: readonly string[]; +} + +function locate(src: Source): { path: string | undefined; strict: boolean } { + const fromEnv = proc.env[src.envName]; + if (fromEnv) return { path: resolveFromCwd(fromEnv), strict: true }; + const found = src.candidates + .map((rel) => decodeURIComponent(new URL(rel, import.meta.url).pathname)) + .find((p) => fs.existsSync(p)); + return { path: found, strict: false }; +} + +const STATE = locate({ + envName: "NEMAR_CLI_COMPUTE_STATE", + candidates: ["../../nemar-cli/shared/compute-state.ts"], +}); +const SUBMIT = locate({ + envName: "NEMAR_CLI_COMPUTE_SUBMIT_CONTRACT", + candidates: ["../../nemar-cli/shared/contract/compute-submit.ts"], +}); +const RESPONSES = locate({ + envName: "NEMAR_CLI_COMPUTE_RESPONSES_CONTRACT", + candidates: ["../../nemar-cli/shared/contract/compute-responses.ts"], +}); + +const SHOULD_SKIP = [STATE, SUBMIT, RESPONSES].some((s) => !s.strict && !s.path); +if (SHOULD_SKIP) { + console.info( + "[compute-job drift] skipped: no nemar-cli checkout found beside this one and the NEMAR_CLI_COMPUTE_* variables are unset.", + ); +} + +function read(src: { path: string | undefined }): string { + expect( + src.path && fs.existsSync(src.path), + `${src.path} is missing: the nemar-cli checkout step failed, or nemar-cli dev does not carry the compute epic yet`, + ).toBe(true); + return fs.readFileSync(src.path as string, "utf8"); +} + +describe.skipIf(SHOULD_SKIP)("the job page's vocabulary agrees with nemar-cli", () => { + it("has the same launcher failure codes in the same order", () => { + const theirs = extractStringArray(read(STATE), "LAUNCHER_FAILURE_CODES"); + expect( + compareLists("LAUNCHER_FAILURE_CODES", COMPUTE_LAUNCHER_FAILURE_CODES, theirs), + ).toBeNull(); + }); + + it("has the same platform failure codes", () => { + const theirs = extractStringArray(read(STATE), "PLATFORM_FAILURE_CODES"); + expect( + compareLists("PLATFORM_FAILURE_CODES", COMPUTE_PLATFORM_FAILURE_CODES, theirs), + ).toBeNull(); + }); + + it("has the same submitter failure codes", () => { + const theirs = extractStringArray(read(STATE), "SUBMITTER_FAILURE_CODES"); + expect( + compareLists("SUBMITTER_FAILURE_CODES", COMPUTE_SUBMITTER_FAILURE_CODES, theirs), + ).toBeNull(); + }); + + it("has the same status for every job-route refusal", () => { + const theirs = extractSatisfiedNumberMap(read(STATE), "COMPUTE_REFUSAL_STATUS"); + expect(theirs, "COMPUTE_REFUSAL_STATUS not found").toBeDefined(); + for (const [code, status] of Object.entries(COMPUTE_JOB_ROUTE_STATUS)) { + expect([code, theirs?.[code]]).toEqual([code, status]); + } + }); + + it("has the same truncated-log header and the same bounds", () => { + const source = read(SUBMIT); + expect(extractString(source, "COMPUTE_TRUNCATED_HEADER")).toBe(COMPUTE_TRUNCATED_HEADER); + expect(extractProduct(source, "COMPUTE_LOG_MAX_BYTES")).toBe(COMPUTE_LOG_MAX_BYTES); + expect(extractNumber(source, "COMPUTE_RESULTS_PAGE_MAX")).toBe(COMPUTE_RESULTS_PAGE_MAX); + }); + + it("has the same sentence for an upload that expired", () => { + const theirs = extractStringMap(read(SUBMIT), "COMPUTE_SUBMIT_SENTENCES"); + expect(theirs, "COMPUTE_SUBMIT_SENTENCES not found").toBeDefined(); + expect(theirs?.upload_expired).toBe(COMPUTE_UPLOAD_EXPIRED_SENTENCE); + }); + + it("has the same cancel outcomes", () => { + const theirs = extractStringArray(read(RESPONSES), "COMPUTE_CANCEL_OUTCOMES"); + expect(compareLists("COMPUTE_CANCEL_OUTCOMES", COMPUTE_CANCEL_OUTCOMES, theirs)).toBeNull(); + }); +}); From 1acca527ce290f8524f99bfe0c4adf69a2eae707 Mon Sep 17 00:00:00 2001 From: Seyed Yahya Shirazi Date: Sat, 7 Nov 2026 07:40:52 -0800 Subject: [PATCH 03/17] Add job page clients to the compute API --- src/lib/compute-api-job.test.ts | 450 ++++++++++++++++++++++++++++++++ src/lib/compute-api.test.ts | 9 +- src/lib/compute-api.ts | 292 ++++++++++++++++++++- 3 files changed, 737 insertions(+), 14 deletions(-) create mode 100644 src/lib/compute-api-job.test.ts diff --git a/src/lib/compute-api-job.test.ts b/src/lib/compute-api-job.test.ts new file mode 100644 index 00000000..3ebb54d4 --- /dev/null +++ b/src/lib/compute-api-job.test.ts @@ -0,0 +1,450 @@ +/** + * The compute client's job-page calls (phase E3, website#496). Every success case parses a body + * captured from the real routes by + * + * NEMAR_CLI_DIR= \ + * bun scripts/capture-compute-job-fixtures.mjs + * + * Transport conditions no route can be made to produce (a 502 with no JSON, a refused connection) use a + * real `Response`, as the repo's rule allows for failure paths. + */ +import { describe, expect, it } from "vitest"; +import cancel from "../../test/fixtures/compute/cancel.json"; +import errorsJob from "../../test/fixtures/compute/errors-job.json"; +import jobCancelRequested from "../../test/fixtures/compute/job-cancel-requested.json"; +import jobFailureCodes from "../../test/fixtures/compute/job-failure-codes.json"; +import jobLifecycle from "../../test/fixtures/compute/job-lifecycle.json"; +import jobStale from "../../test/fixtures/compute/job-stale.json"; +import jobStates from "../../test/fixtures/compute/job-states.json"; +import logs from "../../test/fixtures/compute/logs.json"; +import meActive from "../../test/fixtures/compute/me-active-with-usage.json"; +import results from "../../test/fixtures/compute/results.json"; +import { + ComputeApiError, + cancelComputeJob, + getComputeJob, + getComputeLogs, + getComputeResults, + isJobNotFound, + parseComputeCancel, + parseComputeJob, + parseComputeMe, + parseComputeResults, + renewComputeResults, +} from "./compute-api"; +import { COMPUTE_FAILURE_CODES, COMPUTE_JOB_STATES } from "./compute-contract"; + +const JOB_ID = "job_0123456789abcdef01234567"; + +function answering(res: Response) { + const seen: { url: string; init: RequestInit }[] = []; + const fn = (async (url: string, init: RequestInit) => { + seen.push({ url, init }); + return res; + }) as unknown as typeof fetch; + return { fn, seen }; +} + +const json = (body: unknown, status = 200): Response => + new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } }); + +async function failure(promise: Promise): Promise { + try { + await promise; + } catch (err) { + expect(err).toBeInstanceOf(ComputeApiError); + return err as ComputeApiError; + } + throw new Error("expected the call to fail"); +} + +describe("GET /compute/me/jobs/:id", () => { + it("parses a captured job in each of the ten states", () => { + for (const state of COMPUTE_JOB_STATES) { + const read = parseComputeJob(jobStates[state].body); + expect(read.job.state).toBe(state); + expect(read.job.resources.nodes).toBe(1); + expect(read.stale).toBe(false); + } + }); + + it("keeps the memory figure when set and null when not", () => { + expect(parseComputeJob(jobStates.finished.body).job.resources.memory_mb).toBe(8192); + expect(parseComputeJob(jobStates.running.body).job.resources.memory_mb).toBeNull(); + }); + + it("parses a failed job for each of the failure codes", () => { + for (const code of COMPUTE_FAILURE_CODES) { + const body = (jobFailureCodes as unknown as Record)[code].body; + const read = parseComputeJob(body); + expect([code, read.job.failure_code]).toEqual([code, code]); + expect(read.job.state).toBe("failed"); + } + }); + + it("reads a recorded cancel on a live job", () => { + const read = parseComputeJob(jobCancelRequested.running.body); + expect([read.job.state, read.job.cancel_requested]).toEqual(["running", true]); + }); + + it("reads stale: true, and a missing stale as false", () => { + expect(parseComputeJob(jobStale.submitted.body).stale).toBe(true); + const { stale: _drop, ...rest } = jobStates.running.body; + expect(parseComputeJob(rest).stale).toBe(false); + }); + + it("parses the lifecycle job at running and at finished", () => { + expect(parseComputeJob(jobLifecycle.running.body).job.id).toBe(jobLifecycle.job_id); + const done = parseComputeJob(jobLifecycle.finished.body).job; + expect([done.state, done.charged_milli > 0]).toEqual(["finished", true]); + }); + + it("copies only the keys the page reads", () => { + const body = structuredClone(jobStates.running.body) as Record; + (body.job as Record).tenant_pool = "platform"; + (body.job as Record).failure_detail = "oom"; + ((body.job as Record).resources as Record).hold_milli = 9; + body.extra = "x"; + const read = parseComputeJob(body); + expect(Object.keys(read.job).sort()).toEqual( + [ + "app_id", + "app_version", + "cancel_requested", + "charged_milli", + "created_at", + "ended_at", + "failure_code", + "id", + "kind", + "name", + "partition", + "pool", + "resources", + "source", + "started_at", + "state", + ].sort(), + ); + expect(Object.keys(read.job.resources).sort()).toEqual( + ["cores_per_node", "gpus", "memory_mb", "minutes", "nodes"].sort(), + ); + expect(Object.keys(read).sort()).toEqual(["job", "stale"]); + }); + + it("reads an optional name through, and none as null", () => { + expect(parseComputeJob(jobStates.running.body).job.name).toBeNull(); + const body = structuredClone(jobStates.running.body) as { job: Record }; + body.job.name = "my analysis"; + expect(parseComputeJob(body).job.name).toBe("my analysis"); + }); + + it("rejects a missing key or a wrong type as a shape error, never zeros", () => { + const bad = (mutate: (b: { job: Record }) => void) => { + const b = structuredClone(jobStates.running.body) as { job: Record }; + mutate(b); + return () => parseComputeJob(b); + }; + expect(bad((b) => delete b.job.resources)).toThrow(ComputeApiError); + expect(bad((b) => delete b.job.resources.minutes)).toThrow(ComputeApiError); + expect(bad((b) => (b.job.resources.nodes = "1"))).toThrow(ComputeApiError); + expect(bad((b) => (b.job.charged_milli = 1.5))).toThrow(ComputeApiError); + expect(bad((b) => (b.job.cancel_requested = 0))).toThrow(ComputeApiError); + expect(bad((b) => (b.job.name = 5))).toThrow(ComputeApiError); + expect(() => parseComputeJob(null)).toThrow(ComputeApiError); + expect(() => parseComputeJob({ job: jobStates.running.body.job, stale: "yes" })).toThrow( + ComputeApiError, + ); + }); + + it("asks for the job by id, with the SSR cookie, and sends nothing else", async () => { + const { fn, seen } = answering(json(jobStates.running.body)); + const read = await getComputeJob(JOB_ID, { fetch: fn, cookieHeader: "nemar_session=abc" }); + expect(read.job.state).toBe("running"); + expect(seen[0].url).toMatch(new RegExp(`/compute/me/jobs/${JOB_ID}$`)); + expect(seen[0].init.method).toBe("GET"); + expect((seen[0].init.headers as Record).Cookie).toBe("nemar_session=abc"); + }); + + it("refuses an id that is not a job id before sending anything", () => { + const { fn, seen } = answering(json({})); + for (const bad of ["", "nope", "job_XYZ", `${JOB_ID}/../logs`, `${JOB_ID}?x=1`]) { + expect(() => getComputeJob(bad, { fetch: fn })).toThrow(RangeError); + } + expect(seen).toEqual([]); + }); +}); + +describe("GET /compute/jobs/:id/logs", () => { + const live = logs.live; + + function logResponse(entry: { status: number; headers: Record; text?: string }) { + return new Response(entry.text ?? "", { status: entry.status, headers: entry.headers }); + } + + it("returns the text and no truncation for a log under 1 MiB", async () => { + const { fn, seen } = answering(logResponse(live)); + const log = await getComputeLogs(JOB_ID, { fetch: fn }); + expect(log).toEqual({ text: live.text, truncated: false }); + expect((seen[0].init.headers as Record).Accept).toBe("text/plain"); + }); + + it("reads X-Nemar-Truncated: true from the captured headers", async () => { + const t = logs.truncated; + expect(t.headers["x-nemar-truncated"]).toBe("true"); + const { fn } = answering( + new Response("x".repeat(1024), { status: t.status, headers: t.headers }), + ); + expect((await getComputeLogs(JOB_ID, { fetch: fn })).truncated).toBe(true); + }); + + it("treats any other value of the header, or none, as not truncated", async () => { + for (const value of ["false", "1", "TRUE", ""]) { + const { fn } = answering(new Response("a", { headers: { "X-Nemar-Truncated": value } })); + expect((await getComputeLogs(JOB_ID, { fetch: fn })).truncated).toBe(false); + } + }); + + it("returns an empty log as an empty string, not an error", async () => { + const { fn } = answering(logResponse(logs.empty)); + expect(await getComputeLogs(JOB_ID, { fetch: fn })).toEqual({ text: "", truncated: false }); + }); + + it("hands the hostile log back byte for byte (the page escapes it, the client does not)", async () => { + const { fn } = answering(logResponse(logs.hostile)); + const log = await getComputeLogs(JOB_ID, { fetch: fn }); + expect(log.text).toBe(logs.hostile.text); + expect(log.text).toContain("\u001b[31m"); + expect(log.text).toContain(" & 'q' back\\slash"; + expect(prepareLog(hostile).lines).toEqual([hostile]); + }); + + it("leaves an ordinary traceback identical after the pass", () => { + const traceback = [ + "Traceback (most recent call last):", + ' File "main.py", line 3, in ', + " print(1 / 0)", + "ZeroDivisionError: division by zero", + ]; + expect(prepareLog(`${traceback.join("\n")}\n`).lines).toEqual(traceback); + expect(prepareLog(traceback.join("\n")).lines).toEqual(traceback); + }); + + it("handles the real log the backend served for a hostile job", () => { + const { lines } = prepareLog(logs.hostile.text); + const joined = lines.join("\n"); + // Formatting is gone, the visible words stay. + expect(joined).toContain("red and cleared"); + expect(joined).toContain("link text end"); + expect(joined).not.toContain(ESC); + // The progress bar became lines, nothing was overwritten. + expect(lines).toContain("progress 10%"); + expect(lines).toContain("progress 50%"); + expect(lines).toContain("progress 100%"); + // The hostile characters are visible, and the markup is untouched. + expect(joined).toContain("nul \\x00 bell \\x07 next-line \\x85 end"); + expect(joined).toContain( + "override \\u202egnp.exe and isolate \\u2066x\\u2069 and zero\\u200bwidth", + ); + expect(joined).toContain(' &'); + // No control or bidirectional character survives. + // biome-ignore lint/suspicious/noControlCharactersInRegex: the point of the check. + expect(joined).not.toMatch(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f​-‏‪-‮⁦-⁩]/); + }); + + it("caps a 1 MiB single line at the line limit and says how much was cut", () => { + const line = "x".repeat(1024 * 1024); + const { lines } = prepareLog(line); + expect(lines.length).toBe(1); + expect(lines[0].startsWith("x".repeat(LOG_LINE_MAX))).toBe(true); + expect(lines[0]).toBe( + `${"x".repeat(LOG_LINE_MAX)}[line cut: ${1024 * 1024 - LOG_LINE_MAX} more characters]`, + ); + }); + + it("leaves a line of exactly the limit alone and cuts one character over", () => { + expect(prepareLog("y".repeat(LOG_LINE_MAX)).lines).toEqual(["y".repeat(LOG_LINE_MAX)]); + expect(prepareLog("y".repeat(LOG_LINE_MAX + 1)).lines).toEqual([ + `${"y".repeat(LOG_LINE_MAX)}[line cut: 1 more characters]`, + ]); + }); + + it("does not cut a surrogate pair in half", () => { + const text = `${"a".repeat(LOG_LINE_MAX - 1)}\u{1F600}\u{1F600}`; + const [line] = prepareLog(text).lines; + expect(line.includes("\ud83d[")).toBe(false); + expect(line).toMatch(/^a+\[line cut: 2 more characters\]$/); + }); + + it("counts the cut in whole characters, not code units", () => { + const text = `${"a".repeat(LOG_LINE_MAX)}\u{1F600}\u{1F600}\u{1F600}`; + expect(prepareLog(text).lines[0]).toMatch(/\[line cut: 3 more characters\]$/); + }); + + it("gives no lines for an empty log, and one empty line for a lone newline", () => { + expect(prepareLog("").lines).toEqual([]); + expect(prepareLog("\n").lines).toEqual([""]); + }); + + it("handles text that is not valid UTF-8 after decoding (U+FFFD stays)", () => { + const decoded = new TextDecoder().decode(new Uint8Array([0x61, 0xff, 0xfe, 0x62])); + expect(prepareLog(decoded).lines).toEqual(["a��b"]); + }); +}); + +describe("logWindow", () => { + const lines = Array.from({ length: 5431 }, (_, i) => `line ${i + 1}`); + + it("shows the last 200 lines by default and counts what is hidden", () => { + const w = logWindow(lines, LOG_TAIL_DEFAULT); + expect(w.total).toBe(5431); + expect(w.shown).toBe(200); + expect(w.hidden).toBe(5231); + expect(w.text.split("\n").length).toBe(200); + expect(w.text.startsWith("line 5232\n")).toBe(true); + expect(w.text.endsWith("line 5431")).toBe(true); + }); + + it("adds 1,000 earlier lines per step and stops at the start", () => { + const first = logWindow(lines, LOG_TAIL_DEFAULT); + const second = logWindow(lines, first.shown + LOG_EARLIER_STEP); + expect(second.shown).toBe(1200); + expect(second.hidden).toBe(4231); + const all = logWindow(lines, 99999); + expect([all.shown, all.hidden]).toEqual([5431, 0]); + expect(all.text.startsWith("line 1\n")).toBe(true); + }); + + it("shows a short log whole", () => { + const w = logWindow(["a", "b"], 200); + expect([w.text, w.hidden, w.shown, w.total]).toEqual(["a\nb", 0, 2, 2]); + }); + + it("shows an empty log as empty", () => { + expect(logWindow([], 200)).toEqual({ text: "", total: 0, shown: 0, hidden: 0 }); + }); + + it("refuses a count that is not a positive whole number", () => { + for (const bad of [0, -1, 1.5, Number.NaN]) { + expect(() => logWindow(["a"], bad)).toThrow(RangeError); + } + }); +}); diff --git a/src/lib/compute-logs.ts b/src/lib/compute-logs.ts new file mode 100644 index 00000000..312d5d50 --- /dev/null +++ b/src/lib/compute-logs.ts @@ -0,0 +1,93 @@ +/** + * A job's log made safe to show (website ADR 0030 phase E3, issue #496; ADR 0029). Pure: no DOM, no + * network. + * + * The log is the job's own output, so anything it prints can be in it: an escape sequence that rewrites + * a terminal, a carriage return that overwrites the line before it, a right-to-left override that + * reorders what follows, a zero-width character that hides a word, markup. The page shows it with + * `textContent` in a `
`, so markup is already inert; this module makes the rest visible:
+ *
+ *  1. ANSI escape sequences are removed as FORMATTING (color, cursor moves, hyperlinks), keeping the
+ *     text between them. A sequence that never ends is NOT removed and eats nothing: it is written out
+ *     in step 2 with the text after it, so a program cannot hide the rest of its log behind one.
+ *  2. Everything else goes through `displaySafeBody` (the Mail tab's set, nemar-cli's escape set):
+ *     `\r\n` and a bare `\r` become line breaks (nothing can be overwritten), newline and tab stay,
+ *     and every other control, bidirectional override or isolate, zero-width and invisible character is
+ *     WRITTEN OUT (`\x1b`, `‮`), which shows that something was there instead of cleaning it away
+ *     silently (the CLI drops them; ADR 0029 shows them).
+ *  3. Lines are capped at 2,000 characters with a visible count of what was cut, so a 1 MiB single line
+ *     cannot freeze the page.
+ *
+ * `<`, `>`, `&`, quotes and backslashes are never altered: an ordinary traceback survives unchanged.
+ */
+import { displaySafeBody } from "./mail-display";
+
+/** The longest line shown; a longer one ends with a visible note of how much was cut. */
+export const LOG_LINE_MAX = 2000;
+/** How many of the last lines show before "Show earlier lines". */
+export const LOG_TAIL_DEFAULT = 200;
+/** How many earlier lines each press of "Show earlier lines" adds. */
+export const LOG_EARLIER_STEP = 1000;
+
+// Terminated sequences only. Bodies may not contain a line break, so an OSC that never ends cannot
+// reach past its own line.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching ESC and BEL is the point.
+const OSC = /\u001b\][^\u0007\u001b\n]*(?:\u0007|\u001b\\)/g;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching ESC and the C1 CSI is the point.
+const CSI = /(?:\u001b\[|\u009b)[0-?]*[ -/]*[@-~]/g;
+// ESC, any intermediate bytes, one final byte: `ESC 7`, `ESC c`, `ESC ( B`. The introducers of a string
+// (`[` CSI, `]` OSC, P DCS, X SOS, ^ PM, _ APC) are not final bytes: when their long form did not match
+// they stay, and are written out below with the text after them.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching ESC is the point.
+const TWO_CHARACTER = /\u001b[ -/]*[0-?@-OQ-WYZ\\`-~]/g;
+
+/** Remove complete ANSI escape sequences, keeping the text between them. */
+export function stripAnsi(text: string): string {
+  // Order matters: the long forms first, or `ESC [` would be taken for a two-character form.
+  return text.replace(OSC, "").replace(CSI, "").replace(TWO_CHARACTER, "");
+}
+
+function capLine(line: string): string {
+  if (line.length <= LOG_LINE_MAX) return line;
+  let cut = LOG_LINE_MAX;
+  // Never end on half of a surrogate pair.
+  const last = line.charCodeAt(cut - 1);
+  if (last >= 0xd800 && last <= 0xdbff) cut -= 1;
+  const rest = [...line.slice(cut)].length;
+  return `${line.slice(0, cut)}[line cut: ${rest} more characters]`;
+}
+
+export interface PreparedLog {
+  /** The lines to show, safe to put in a text node. No trailing empty line for a final newline. */
+  readonly lines: readonly string[];
+}
+
+/** A log made safe: formatting removed, hostile characters written out, long lines capped. */
+export function prepareLog(text: string): PreparedLog {
+  if (text === "") return { lines: [] };
+  const lines = displaySafeBody(stripAnsi(text)).split("\n");
+  if (lines.length > 1 && lines[lines.length - 1] === "") lines.pop();
+  else if (lines.length === 1 && lines[0] === "") return { lines: [] };
+  return { lines: lines.map(capLine) };
+}
+
+export interface LogWindow {
+  /** The last `shown` lines, joined with newlines. */
+  readonly text: string;
+  readonly total: number;
+  readonly shown: number;
+  /** Earlier lines not shown. */
+  readonly hidden: number;
+}
+
+/** The last `want` lines of a prepared log (all of it when it is shorter). */
+export function logWindow(lines: readonly string[], want: number): LogWindow {
+  if (!Number.isInteger(want) || want < 1) throw new RangeError("a window is 1 or more lines");
+  const shown = Math.min(want, lines.length);
+  return {
+    text: lines.slice(lines.length - shown).join("\n"),
+    total: lines.length,
+    shown,
+    hidden: lines.length - shown,
+  };
+}

From dc4bac303e32083802e9ee1d36c25e4752f2ae07 Mon Sep 17 00:00:00 2001
From: Seyed Yahya Shirazi 
Date: Sat, 7 Nov 2026 08:31:42 -0800
Subject: [PATCH 05/17] Word the job failure codes

---
 src/lib/compute-failure.test.ts | 83 +++++++++++++++++++++++++++++++++
 src/lib/compute-failure.ts      | 69 +++++++++++++++++++++++++++
 2 files changed, 152 insertions(+)
 create mode 100644 src/lib/compute-failure.test.ts
 create mode 100644 src/lib/compute-failure.ts

diff --git a/src/lib/compute-failure.test.ts b/src/lib/compute-failure.test.ts
new file mode 100644
index 00000000..8e3e1345
--- /dev/null
+++ b/src/lib/compute-failure.test.ts
@@ -0,0 +1,83 @@
+/**
+ * The failure sentences of the job page (phase E3, website#496). The list of codes is the transcribed
+ * contract (`compute-contract.ts`, drift-tested against nemar-cli), so a code the backend adds fails
+ * `test/compute-job-contract-drift.test.ts` first and this file second.
+ */
+import { describe, expect, it } from "vitest";
+import {
+  COMPUTE_FAILURE_CODES,
+  COMPUTE_LAUNCHER_FAILURE_CODES,
+  COMPUTE_UPLOAD_EXPIRED_SENTENCE,
+} from "./compute-contract";
+import { FAILURE_SENTENCES, failureView } from "./compute-failure";
+
+const ID = "job_0123456789abcdef01234567";
+
+describe("failureView", () => {
+  it("has a plain sentence for each of the 17 codes", () => {
+    expect(COMPUTE_FAILURE_CODES.length).toBe(17);
+    for (const code of COMPUTE_FAILURE_CODES) {
+      const v = failureView(code, ID);
+      expect(v.known, code).toBe(true);
+      expect(v.sentence.length, code).toBeGreaterThan(10);
+      expect(v.sentence, code).toMatch(/[.]$/);
+      expect(v.code, code).toBe(code);
+    }
+    // And the table carries nothing the contract does not.
+    expect(Object.keys(FAILURE_SENTENCES).sort()).toEqual([...COMPUTE_FAILURE_CODES].sort());
+  });
+
+  it("points at the log for the seven launcher codes and at nothing for the other ten", () => {
+    for (const code of COMPUTE_FAILURE_CODES) {
+      const v = failureView(code, ID);
+      const launcher = (COMPUTE_LAUNCHER_FAILURE_CODES as readonly string[]).includes(code);
+      if (launcher) {
+        expect(v.logHint, code).toEqual({
+          lead: "Read the log below, or run ",
+          command: `nemar compute logs ${ID}`,
+        });
+      } else {
+        expect(v.logHint, code).toBeNull();
+      }
+    }
+    expect(COMPUTE_LAUNCHER_FAILURE_CODES.length).toBe(7);
+  });
+
+  it("names no one at fault and promises no refund", () => {
+    for (const code of COMPUTE_FAILURE_CODES) {
+      const { sentence } = failureView(code, ID);
+      expect(sentence, code).not.toMatch(/\b(your|you|fault|blame|because|refund|compensat)/i);
+    }
+  });
+
+  it("uses the backend's own sentence for an upload that expired", () => {
+    expect(failureView("upload_expired", ID).sentence).toBe(COMPUTE_UPLOAD_EXPIRED_SENTENCE);
+  });
+
+  it("prints an unknown code itself, with no log hint and no claim", () => {
+    const v = failureView("disk_on_fire", ID);
+    expect(v.known).toBe(false);
+    expect(v.code).toBe("disk_on_fire");
+    expect(v.sentence).toContain("disk_on_fire");
+    expect(v.logHint).toBeNull();
+  });
+
+  it("escapes a hostile or empty code", () => {
+    const hostile = failureView("a‮b\u0000c",
+      "http://evil.example/a",
+      "file:///etc/passwd",
+      "//evil.example/a",
+      "not a url",
+      "",
+      "vbscript:x",
+      "blob:https://x/y",
+    ]) {
+      expect(safeResultHref(bad), bad).toBeNull();
+    }
+  });
+
+  it("escapes the path and the checksum and formats the size", () => {
+    const row = resultRow({
+      path: "a‮/b\u0000.txt",
+      size: 11,
+      sha256: "ab".repeat(32),
+      url: "javascript:1",
+    });
+    expect(row.path).toBe("a\\u202e/b\\x00.txt");
+    expect(row.size).toBe("11 B");
+    expect(row.shaShort).toBe("abababababab");
+    expect(row.sha.length).toBe(64);
+    expect(row.href).toBeNull();
+  });
+
+  it("offers 100 more rows from the held page, then the next page by cursor, then nothing", () => {
+    const base = { total: 2500, nextAfter: "out/x" as string | null };
+    expect(resultsPaging({ ...base, held: 1000, shown: 100, offset: 0 })).toEqual({
+      showMore: RESULT_ROWS_STEP,
+      nextPageRemaining: null,
+    });
+    expect(resultsPaging({ ...base, held: 1000, shown: 950, offset: 0 }).showMore).toBe(50);
+    expect(resultsPaging({ ...base, held: 1000, shown: 1000, offset: 0 })).toEqual({
+      showMore: 0,
+      nextPageRemaining: 1500,
+    });
+    expect(
+      resultsPaging({ ...base, held: 1000, shown: 1000, offset: 1000 }).nextPageRemaining,
+    ).toBe(500);
+    expect(resultsPaging({ total: 3, nextAfter: null, held: 3, shown: 3, offset: 0 })).toEqual({
+      showMore: 0,
+      nextPageRemaining: null,
+    });
+  });
+
+  it("knows when links have expired, and treats an unreadable date as expired", () => {
+    const at = "2026-11-14T15:35:07.000Z";
+    const ms = Date.parse(at);
+    expect(linksExpired(at, ms - 1)).toBe(false);
+    expect(linksExpired(at, ms)).toBe(true);
+    expect(linksExpired("garbage", ms)).toBe(true);
+  });
+
+  it("says when a link outlives the files", () => {
+    const at = "2026-11-14T15:35:07.000Z";
+    expect(linksOutliveFiles(at, Date.parse(at) - 1)).toBe(true);
+    expect(linksOutliveFiles(at, Date.parse(at) + 1)).toBe(false);
+    expect(linksOutliveFiles(at, null)).toBe(false);
+  });
+});
+
+describe("cancelOutcome", () => {
+  const fx = (k: keyof typeof cancelFx) =>
+    cancelOutcome(parseComputeCancel((cancelFx[k] as { body: unknown }).body));
+
+  it("words every captured answer", () => {
+    expect(fx("running")).toMatchObject({ kind: "canceled", poll: false });
+    expect(fx("running_again").kind).toBe("canceled");
+    expect(fx("never_started").kind).toBe("canceled");
+    expect(fx("cluster_down")).toMatchObject({ kind: "recorded", poll: true });
+    expect(fx("cluster_down_again").kind).toBe("recorded");
+    const ended = fx("finished");
+    expect(ended.kind).toBe("ended");
+    expect(ended.sentence).toBe("The job had already ended (finished); nothing was canceled.");
+    expect(ended.poll).toBe(false);
+  });
+
+  it("words the rows the stand-in cannot make", () => {
+    const live = { state: "running", outcome: "already_cancelled", cancelled: true };
+    expect(cancelOutcome(live).kind).toBe("already_recorded");
+    expect(cancelOutcome({ ...live, outcome: "cancel_requested" }).kind).toBe("recorded");
+    // An older Worker has no `cancelled`: the outcome decides.
+    expect(cancelOutcome({ ...live, outcome: "cancel_requested", cancelled: null }).kind).toBe(
+      "recorded",
+    );
+    expect(cancelOutcome({ state: "failed", outcome: "already_ended", cancelled: null }).kind).toBe(
+      "ended",
+    );
+    expect(
+      cancelOutcome({ state: null, outcome: "already_ended", cancelled: false }).sentence,
+    ).toContain("unknown");
+    expect(
+      cancelOutcome({ state: "running", outcome: "something_new", cancelled: true }).kind,
+    ).toBe("unknown");
+  });
+
+  it("always asks for the job to be read again and promises no amount", () => {
+    for (const k of ["running", "cluster_down", "finished"] as const) {
+      expect(fx(k).refresh).toBe(true);
+      expect(fx(k).sentence).not.toMatch(/refund|SU|charged/i);
+    }
+  });
+});
+
+describe("nextPoll", () => {
+  const read = (state: string, changed = false): PollEvent => ({ kind: "read", state, changed });
+  const drive = (events: PollEvent[], start = 0, random = 0.5) => {
+    let state: PollState = initialPoll(start);
+    const steps = [];
+    for (const e of events) {
+      const out = nextPoll(state, e, start + 1000, random);
+      state = out.next;
+      steps.push(out.step);
+    }
+    return { steps, state };
+  };
+
+  it("starts at 10 s and doubles to 60 s while nothing changes", () => {
+    const { steps } = drive(Array(6).fill(read("running")));
+    expect(steps.map((s) => (s as { delayMs: number }).delayMs)).toEqual([
+      20_000, 40_000, 60_000, 60_000, 60_000, 60_000,
+    ]);
+    expect(initialPoll(0).delayMs).toBe(POLL_BASE_MS);
+  });
+
+  it("resets to 10 s on a change", () => {
+    const { steps } = drive([
+      read("running"),
+      read("running"),
+      read("archiving", true),
+      read("archiving"),
+    ]);
+    expect(steps.map((s) => (s as { delayMs: number }).delayMs)).toEqual([
+      20_000, 40_000, 10_000, 20_000,
+    ]);
+  });
+
+  it("stops on a terminal state, whatever the schedule before it was", () => {
+    for (const state of ["finished", "failed", "cancelled"]) {
+      for (const changed of [true, false]) {
+        const { steps } = drive([read("running"), read("running", true), read(state, changed)]);
+        expect(steps[2], `${state} ${changed}`).toEqual({ action: "stop", reason: "terminal" });
+      }
+    }
+  });
+
+  it("stays stopped: no event restarts a stopped poller", () => {
+    let state = nextPoll(initialPoll(0), read("finished", true), 5).next;
+    for (const e of [
+      read("running", true),
+      { kind: "visible", sinceLastReadMs: 99_999 } as PollEvent,
+      { kind: "error" } as PollEvent,
+    ]) {
+      const out = nextPoll(state, e, 10);
+      expect(out.step).toEqual({ action: "stop", reason: "terminal" });
+      state = out.next;
+    }
+  });
+
+  it("stops on a state this build does not know", () => {
+    expect(nextPoll(initialPoll(0), read("weird"), 5).step).toEqual({
+      action: "stop",
+      reason: "unknown_state",
+    });
+  });
+
+  it("keeps polling an unreported job: it may resume", () => {
+    expect(nextPoll(initialPoll(0), read("unreported"), 5).step.action).toBe("wait");
+  });
+
+  it("doubles on an error, and the fifth error in a row stops", () => {
+    const { steps } = drive(Array(POLL_ERROR_LIMIT).fill({ kind: "error" } as PollEvent));
+    expect(steps.slice(0, 4).map((s) => (s as { delayMs: number }).delayMs)).toEqual([
+      20_000, 40_000, 60_000, 60_000,
+    ]);
+    expect(steps[4]).toEqual({ action: "stop", reason: "errors" });
+  });
+
+  it("counts only consecutive errors: a good read clears them", () => {
+    const e = { kind: "error" } as PollEvent;
+    const { steps } = drive([e, e, e, e, read("running", true), e, e, e, e]);
+    expect(steps.every((s) => s.action === "wait")).toBe(true);
+  });
+
+  it("stops on a 401 and on a not-found", () => {
+    expect(nextPoll(initialPoll(0), { kind: "error", fatal: "session" }, 5).step).toEqual({
+      action: "stop",
+      reason: "session",
+    });
+    expect(nextPoll(initialPoll(0), { kind: "error", fatal: "not_found" }, 5).step).toEqual({
+      action: "stop",
+      reason: "not_found",
+    });
+  });
+
+  it("pauses when the tab is hidden, and refreshes at once on becoming visible after 5 s", () => {
+    expect(nextPoll(initialPoll(0), { kind: "hidden" }, 5).step).toEqual({ action: "pause" });
+    expect(nextPoll(initialPoll(0), { kind: "visible", sinceLastReadMs: 5_001 }, 5).step).toEqual({
+      action: "refresh_now",
+    });
+    expect(
+      nextPoll(initialPoll(0), { kind: "visible", sinceLastReadMs: 5_000 }, 5).step.action,
+    ).toBe("wait");
+  });
+
+  it("restarts the schedule at 10 s after a pause", () => {
+    let state = drive([read("running"), read("running"), read("running")]).state;
+    expect(state.delayMs).toBe(60_000);
+    state = nextPoll(state, { kind: "visible", sinceLastReadMs: 60_000 }, 5).next;
+    expect(state.delayMs).toBe(POLL_BASE_MS);
+  });
+
+  it("stops two hours after load, at exactly the boundary and not before", () => {
+    const s = initialPoll(1000);
+    expect(nextPoll(s, read("running"), 1000 + POLL_HARD_STOP_MS - 1).step.action).toBe("wait");
+    expect(nextPoll(s, read("running"), 1000 + POLL_HARD_STOP_MS).step).toEqual({
+      action: "stop",
+      reason: "hard_stop",
+    });
+    expect(
+      nextPoll(s, { kind: "visible", sinceLastReadMs: 1e9 }, 1000 + POLL_HARD_STOP_MS).step.action,
+    ).toBe("stop");
+  });
+
+  it("moves each delay by at most 15 percent", () => {
+    for (const [random, expected] of [
+      [0, 8_500],
+      [0.5, 10_000],
+      [0.999999, 11_500],
+    ] as const) {
+      const out = nextPoll(initialPoll(0), read("running", true), 5, random);
+      expect((out.step as { delayMs: number }).delayMs).toBe(expected);
+    }
+    expect(POLL_MAX_MS).toBe(60_000);
+  });
+});
diff --git a/src/lib/compute-job-view.ts b/src/lib/compute-job-view.ts
new file mode 100644
index 00000000..7f453e7e
--- /dev/null
+++ b/src/lib/compute-job-view.ts
@@ -0,0 +1,658 @@
+/**
+ * Pure view models for the job page `/compute/jobs/` (website ADR 0030 phase E3, issue #496). The
+ * server template, the browser script and the tests read one place. Nothing here decides what a state
+ * MEANS (the backend does); it decides what the page shows for each state it was told, and it claims
+ * only what the record carries: three times (created, started, ended), no per-stage times
+ * (nemar-cli#2097), no results expiry (nemar-cli#2096), no log tail (nemar-cli#2094), result links that
+ * download rather than render (nemar-cli#2095).
+ *
+ * Rules every function keeps:
+ *  - A backend string passes through `displaySafeLine` and is rendered as a text node by the callers.
+ *  - A state outside the closed ten is shown as its escaped word and nothing else.
+ *  - No function reads a clock: `nowMs` and the random number are arguments.
+ */
+import { ACCOUNT_COPY } from "./account-copy";
+import {
+  ComputeApiError,
+  type ComputeCancel,
+  type ComputeJobRead,
+  type ComputeResultFile,
+} from "./compute-api";
+import { type JobBadge, jobBadge, sourceLabel } from "./compute-badges";
+import {
+  COMPUTE_CANCEL_OUTCOMES,
+  isComputeJobState,
+  isTerminalComputeState,
+} from "./compute-contract";
+import { JOB_COPY } from "./compute-copy";
+import { type FailureView, failureView } from "./compute-failure";
+import {
+  dbTimeToIso,
+  formatDuration,
+  formatEpochUtcMinute,
+  formatUtcMinute,
+  formatUtcSecond,
+  parseDbTime,
+} from "./compute-format";
+import { COMPUTE_LABELS } from "./compute-labels";
+import { chargeText } from "./compute-view";
+import { formatBytes } from "./format";
+import { displaySafeLine } from "./mail-display";
+import type { IconName } from "./status-icons";
+
+const DAY_MS = 86_400_000;
+
+// --- State ---------------------------------------------------------------------------------------
+
+/** A known, ended state: the record will not change again. */
+export function isTerminal(state: string): boolean {
+  return isComputeJobState(state) && isTerminalComputeState(state);
+}
+
+/** A known state that has not ended: the page keeps asking. An unknown state is neither. */
+export function isLive(state: string): boolean {
+  return isComputeJobState(state) && !isTerminalComputeState(state);
+}
+
+/**
+ * Whether the page offers Cancel. The route refuses nothing by state (an ended job answers 200
+ * `already_ended`), so this is the PAGE's own choice: a known live state, with no cancel already
+ * recorded. Every front door is offered it, partner included; the backend resolves the intent.
+ */
+export function canCancel(job: { state: string; cancel_requested: boolean }): boolean {
+  return isLive(job.state) && !job.cancel_requested;
+}
+
+// --- Timeline ------------------------------------------------------------------------------------
+
+export type StepStatus = "passed" | "current" | "pending" | "unknown";
+
+export interface StepTime {
+  readonly label: string | null;
+  readonly text: string;
+  readonly iso: string | null;
+  readonly title: string;
+}
+
+export interface TimelineStep {
+  readonly key: "created" | "submitted" | "queued" | "running" | "archiving" | "terminal";
+  readonly label: string;
+  readonly status: StepStatus;
+  readonly statusWord: string;
+  readonly icon: IconName;
+  readonly time: StepTime | null;
+}
+
+export interface TimelineView {
+  readonly steps: readonly TimelineStep[];
+  /** The escaped raw word of a state this build does not know; the timeline is then empty. */
+  readonly unknownState: string | null;
+  readonly unreported: boolean;
+}
+
+const LIVE_INDEX: Readonly> = {
+  created: 0,
+  uploading: 0,
+  submitted: 1,
+  queued: 2,
+  running: 3,
+  archiving: 4,
+};
+
+const STEP_KEYS = ["created", "submitted", "queued", "running", "archiving"] as const;
+
+const STATUS_ICON: Readonly> = {
+  passed: "ok",
+  current: "progress",
+  pending: "neutral",
+  unknown: "flat",
+};
+
+function stepTime(value: string | null, label: string | null): StepTime | null {
+  if (value === null) return null;
+  return {
+    label,
+    text: formatUtcMinute(value),
+    iso: dbTimeToIso(value),
+    title: formatUtcSecond(value),
+  };
+}
+
+const STATE_LABEL = (state: string): string =>
+  isComputeJobState(state) ? jobBadge(state).label : displaySafeLine(state);
+
+/**
+ * The line of stages for a job. It claims only what is known: the record has three times, and Tapis may
+ * skip states, so a stage the record cannot vouch for reads "not known", never "done".
+ */
+export function timeline(job: {
+  state: string;
+  created_at: string;
+  started_at: string | null;
+  ended_at: string | null;
+}): TimelineView {
+  if (!isComputeJobState(job.state)) {
+    return { steps: [], unknownState: displaySafeLine(job.state), unreported: false };
+  }
+  const state = job.state;
+  const started = job.started_at !== null;
+  const terminal = isTerminalComputeState(state);
+  const statuses: StepStatus[] = [];
+  let terminalStatus: StepStatus;
+  if (Object.hasOwn(LIVE_INDEX, state)) {
+    const at = LIVE_INDEX[state];
+    for (let i = 0; i < STEP_KEYS.length; i++) {
+      statuses.push(i < at ? "passed" : i === at ? "current" : "pending");
+    }
+    terminalStatus = "pending";
+  } else if (state === "unreported") {
+    // A side state with no place on the line: through Running only if it started, else only Created.
+    for (let i = 0; i < STEP_KEYS.length; i++) {
+      statuses.push(i === 0 || (started && i <= 3) ? "passed" : "unknown");
+    }
+    terminalStatus = "unknown";
+  } else if (state === "finished") {
+    for (let i = 0; i < STEP_KEYS.length; i++) statuses.push("passed");
+    terminalStatus = "current";
+  } else {
+    // failed or cancelled: Archiving is never claimed.
+    for (let i = 0; i < STEP_KEYS.length; i++) {
+      statuses.push(i === 0 ? "passed" : i <= 3 && started ? "passed" : "unknown");
+    }
+    terminalStatus = "current";
+  }
+  const stateLabel = STATE_LABEL(state);
+  const steps: TimelineStep[] = STEP_KEYS.map((key, i) => {
+    const status = statuses[i];
+    const label =
+      key === "created" && state === "uploading" ? STATE_LABEL("uploading") : STATE_LABEL(key);
+    let time: StepTime | null = null;
+    if (status === "passed" || status === "current") {
+      if (key === "created") time = stepTime(job.created_at, null);
+      else if (key === "running") time = stepTime(job.started_at, JOB_COPY.timeline.started);
+    }
+    return {
+      key,
+      label,
+      status,
+      statusWord: JOB_COPY.timeline.stepWord[status],
+      icon: STATUS_ICON[status],
+      time,
+    };
+  });
+  steps.push({
+    key: "terminal",
+    label: terminal ? stateLabel : JOB_COPY.timeline.ended,
+    status: terminalStatus,
+    statusWord: JOB_COPY.timeline.stepWord[terminalStatus],
+    icon: terminal
+      ? state === "finished"
+        ? "ok"
+        : state === "failed"
+          ? "error"
+          : "neutral"
+      : STATUS_ICON[terminalStatus],
+    time: terminal ? stepTime(job.ended_at, null) : null,
+  });
+  return { steps, unknownState: null, unreported: state === "unreported" };
+}
+
+// --- The whole page ------------------------------------------------------------------------------
+
+export interface DetailRow {
+  readonly key: string;
+  readonly label: string;
+  readonly value: string;
+  /** Set for a time: the machine value and the tooltip. */
+  readonly time?: { readonly iso: string | null; readonly title: string };
+}
+
+export interface JobDetailView {
+  readonly id: string;
+  /** A name the job was given (not served today, nemar-cli#2079); escaped. */
+  readonly title: string | null;
+  readonly badge: JobBadge;
+  /** The state word, escaped. */
+  readonly state: string;
+  readonly known: boolean;
+  readonly live: boolean;
+  readonly terminal: boolean;
+  /** True only for a live job with a cancel on record. */
+  readonly cancelRequested: boolean;
+  readonly canCancel: boolean;
+  readonly stale: boolean;
+  readonly app: string;
+  readonly appVersion: string;
+  readonly frontDoor: string;
+  readonly timeline: TimelineView;
+  readonly rows: readonly DetailRow[];
+  readonly charge: { readonly text: string; readonly kind: "terminal" | "live" | "unknown" };
+  readonly failure: FailureView | null;
+  readonly unreportedNote: string | null;
+  readonly unitsNote: string;
+}
+
+function poolLabel(pool: string): string {
+  return Object.hasOwn(COMPUTE_LABELS.pools, pool)
+    ? COMPUTE_LABELS.pools[pool as "cpu" | "gpu"]
+    : displaySafeLine(pool);
+}
+
+export function jobDetailView(read: ComputeJobRead): JobDetailView {
+  const { job } = read;
+  const R = JOB_COPY.rows;
+  const known = isComputeJobState(job.state);
+  const live = isLive(job.state);
+  const terminal = isTerminal(job.state);
+  const charge = chargeText(job);
+  const rows: DetailRow[] = [
+    {
+      key: "partition",
+      label: R.partition,
+      value: `${displaySafeLine(job.partition)} (${poolLabel(job.pool)})`,
+    },
+    { key: "nodes", label: R.nodes, value: String(job.resources.nodes) },
+    { key: "cores", label: R.cores, value: String(job.resources.cores_per_node) },
+  ];
+  if (job.resources.gpus > 0) {
+    rows.push({ key: "gpus", label: R.gpus, value: String(job.resources.gpus) });
+  }
+  if (job.resources.memory_mb !== null) {
+    rows.push({
+      key: "memory",
+      label: R.memory,
+      value: `${job.resources.memory_mb.toLocaleString("en-US")} MB`,
+    });
+  }
+  rows.push({
+    key: "runtime",
+    label: R.runTime,
+    value: `${R.upTo} ${formatDuration(job.resources.minutes * 60)}`,
+  });
+  const timed = (key: string, label: string, value: string | null): void => {
+    if (value === null) return;
+    rows.push({
+      key,
+      label,
+      value: formatUtcMinute(value),
+      time: { iso: dbTimeToIso(value), title: formatUtcSecond(value) },
+    });
+  };
+  timed("created", R.created, job.created_at);
+  timed("started", R.started, job.started_at);
+  timed("ended", R.ended, job.ended_at);
+  return {
+    id: displaySafeLine(job.id),
+    title: job.name === null ? null : displaySafeLine(job.name),
+    badge: jobBadge(job.state),
+    state: displaySafeLine(job.state),
+    known,
+    live,
+    terminal,
+    cancelRequested: job.cancel_requested && live,
+    canCancel: canCancel(job),
+    stale: read.stale,
+    app: displaySafeLine(job.app_id),
+    appVersion: displaySafeLine(job.app_version),
+    frontDoor: sourceLabel(job.source),
+    timeline: timeline(job),
+    rows,
+    charge,
+    failure: job.failure_code === null ? null : failureView(job.failure_code, job.id),
+    unreportedNote:
+      job.state === "unreported" ? ACCOUNT_COPY["compute_page.unreported_note"] : null,
+    unitsNote: ACCOUNT_COPY["compute_page.units_note"],
+  };
+}
+
+// --- Results retention ---------------------------------------------------------------------------
+
+/** Three days or fewer left counts as "expiring"; website-owned. */
+export const RESULTS_EXPIRING_DAYS = 3;
+
+export type ResultsState = "not_ready" | "none" | "available" | "expiring" | "expired";
+
+export interface ResultsWindow {
+  readonly state: ResultsState;
+  readonly untilMs: number | null;
+  readonly untilText: string | null;
+  readonly untilIso: string | null;
+  readonly daysLeft: number | null;
+  readonly days: number | null;
+}
+
+/**
+ * Where a job's results stand, DERIVED from `ended_at` and `limits.results_days` until the server states
+ * a date (nemar-cli#2096). The rule is the backend's own (`resultsRetentionPassed`): expired once
+ * `now > ended_at + days`, so the instant itself is still available. The 410 stays authoritative: the
+ * page keeps its button in `expired` and lets the backend decide.
+ */
+export function resultsWindow(input: {
+  state: string;
+  endedAt: string | null;
+  resultsDays: number | null;
+  nowMs: number;
+}): ResultsWindow {
+  const none = (state: ResultsState, days: number | null = null): ResultsWindow => ({
+    state,
+    untilMs: null,
+    untilText: null,
+    untilIso: null,
+    daysLeft: null,
+    days,
+  });
+  if (input.state === "failed" || input.state === "cancelled") return none("none");
+  if (input.state !== "finished") return none("not_ready");
+  const ended = input.endedAt === null ? null : parseDbTime(input.endedAt);
+  if (ended === null || input.resultsDays === null) return none("available", input.resultsDays);
+  const untilMs = ended + input.resultsDays * DAY_MS;
+  const left = untilMs - input.nowMs;
+  const state: ResultsState =
+    left < 0 ? "expired" : left <= RESULTS_EXPIRING_DAYS * DAY_MS ? "expiring" : "available";
+  return {
+    state,
+    untilMs,
+    untilText: formatEpochUtcMinute(untilMs),
+    untilIso: new Date(untilMs).toISOString(),
+    daysLeft: left < 0 ? 0 : Math.ceil(left / DAY_MS),
+    days: input.resultsDays,
+  };
+}
+
+export interface ResultsPanelView {
+  readonly window: ResultsWindow;
+  readonly headline: string;
+  /** Whether the "Get download links" button shows. It stays in `expired`: the 410 decides. */
+  readonly canGetLinks: boolean;
+}
+
+export function resultsPanelView(input: {
+  state: string;
+  endedAt: string | null;
+  resultsDays: number | null;
+  nowMs: number;
+}): ResultsPanelView {
+  const w = resultsWindow(input);
+  const C = JOB_COPY.results;
+  let headline: string;
+  switch (w.state) {
+    case "not_ready":
+      headline = C.notReady;
+      break;
+    case "none":
+      headline = C.none;
+      break;
+    case "expired":
+      headline = C.expiredDerived(w.days ?? 0);
+      break;
+    case "expiring":
+      headline = C.expiring(w.daysLeft ?? 0, w.untilText ?? "");
+      break;
+    default:
+      headline =
+        w.untilText === null || w.days === null ? C.keptLimited : C.kept(w.days, w.untilText);
+  }
+  return { window: w, headline, canGetLinks: input.state === "finished" };
+}
+
+// --- Failures of the log, the results and the cancel ---------------------------------------------
+
+export interface FailureNotice {
+  readonly kind: "none" | "expired" | "not_ready" | "not_found" | "session" | "account" | "message";
+  readonly sentence: string;
+}
+
+function transport(err: unknown): FailureNotice {
+  const n = COMPUTE_LABELS.notice;
+  if (err instanceof ComputeApiError) {
+    if (err.code === "job_not_found") return { kind: "not_found", sentence: JOB_COPY.notFoundBody };
+    if (err.kind === "session") return { kind: "session", sentence: JOB_COPY.live.sessionEnded };
+    if (err.kind === "account") return { kind: "account", sentence: n.account };
+    const reason = n[err.kind === "rejected" ? "rejected" : err.kind];
+    return {
+      kind: "message",
+      sentence: err.sentence ? `${reason} ${displaySafeLine(err.sentence)}` : reason,
+    };
+  }
+  return { kind: "message", sentence: n.shape };
+}
+
+/** What the results panel says for a failed links call. A 410 is the expired state; a 409 means no files. */
+export function resultsFailure(err: unknown, resultsDays: number | null): FailureNotice {
+  if (err instanceof ComputeApiError) {
+    if (err.code === "results_expired") {
+      return { kind: "expired", sentence: JOB_COPY.results.expired410(resultsDays) };
+    }
+    if (err.code === "bad_state") return { kind: "not_ready", sentence: JOB_COPY.results.badState };
+  }
+  return transport(err);
+}
+
+/** What the log panel says for a failed log call. */
+export function logFailure(err: unknown, source: string): FailureNotice {
+  if (err instanceof ComputeApiError) {
+    if (err.code === "logs_not_available") {
+      return {
+        kind: "none",
+        sentence: source === "partner" ? JOB_COPY.logs.nonePartner : JOB_COPY.logs.none,
+      };
+    }
+    if (err.code === "storage_unavailable") {
+      return { kind: "message", sentence: JOB_COPY.logs.unavailable };
+    }
+  }
+  return transport(err);
+}
+
+// --- Result rows ---------------------------------------------------------------------------------
+
+/** Rows shown at first and added by each "Show more". */
+export const RESULT_ROWS_STEP = 100;
+
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "[::1]"]);
+
+/**
+ * The only way a result address reaches an `href`: `https:`, or `http:` on a loopback host (the local
+ * backend's object store, for the browser check). `javascript:`, `data:` and anything else render no
+ * link.
+ */
+export function safeResultHref(url: string): string | null {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return null;
+  }
+  if (parsed.protocol === "https:") return parsed.href;
+  if (parsed.protocol === "http:" && LOOPBACK.has(parsed.hostname)) return parsed.href;
+  return null;
+}
+
+export interface ResultRow {
+  readonly path: string;
+  readonly size: string;
+  readonly shaShort: string;
+  readonly sha: string;
+  /** Null renders "link unavailable". */
+  readonly href: string | null;
+}
+
+export function resultRow(file: ComputeResultFile): ResultRow {
+  return {
+    path: displaySafeLine(file.path),
+    size: formatBytes(file.size),
+    shaShort: displaySafeLine(file.sha256.slice(0, 12)),
+    sha: displaySafeLine(file.sha256),
+    href: safeResultHref(file.url),
+  };
+}
+
+export interface ResultsPaging {
+  /** How many more rows the next "Show more" adds from the page already held. */
+  readonly showMore: number;
+  /** Files beyond the held page that another call would fetch; null when there is nothing more. */
+  readonly nextPageRemaining: number | null;
+}
+
+/**
+ * What the list offers after `shown` of `held` rows are visible. The held page is up to 1,000 files;
+ * only when it is used up and the backend gave a cursor is a next call offered.
+ */
+export function resultsPaging(p: {
+  held: number;
+  shown: number;
+  offset: number;
+  total: number;
+  nextAfter: string | null;
+}): ResultsPaging {
+  const showMore = Math.max(0, Math.min(RESULT_ROWS_STEP, p.held - p.shown));
+  const remaining = p.total - (p.offset + p.held);
+  return {
+    showMore,
+    nextPageRemaining: showMore === 0 && p.nextAfter !== null && remaining > 0 ? remaining : null,
+  };
+}
+
+/** True once the links' own expiry has passed; an unreadable date counts as expired (never keep a link we cannot date). */
+export function linksExpired(expiresAtIso: string, nowMs: number): boolean {
+  const at = Date.parse(expiresAtIso);
+  return Number.isNaN(at) || at <= nowMs;
+}
+
+/** Whether the links outlive the files (a link minted late): the retention date is before the link expiry. */
+export function linksOutliveFiles(expiresAtIso: string, untilMs: number | null): boolean {
+  const at = Date.parse(expiresAtIso);
+  return untilMs !== null && !Number.isNaN(at) && at > untilMs;
+}
+
+// --- Cancel --------------------------------------------------------------------------------------
+
+export interface CancelOutcomeView {
+  readonly kind: "recorded" | "canceled" | "already_recorded" | "ended" | "unknown";
+  readonly sentence: string;
+  /** The job is always read again: the answer may have changed its state. */
+  readonly refresh: true;
+  /** Keep polling for the cluster to carry it out. */
+  readonly poll: boolean;
+}
+
+/**
+ * The words for the backend's cancel answer. The codes are the backend's; the sentences are the page's
+ * and promise nothing about a charge beyond what the dialog already said and the refreshed record shows.
+ */
+export function cancelOutcome(answer: ComputeCancel): CancelOutcomeView {
+  const C = JOB_COPY.cancel;
+  const known = (COMPUTE_CANCEL_OUTCOMES as readonly string[]).includes(answer.outcome);
+  const ended = answer.outcome === "already_ended" || answer.cancelled === false;
+  if (ended) {
+    const state = answer.state === null ? "unknown" : STATE_LABEL(answer.state).toLowerCase();
+    return { kind: "ended", sentence: C.ended(state), refresh: true, poll: false };
+  }
+  if (!known) return { kind: "unknown", sentence: C.unknown, refresh: true, poll: true };
+  if (answer.state === "cancelled") {
+    return { kind: "canceled", sentence: C.canceled, refresh: true, poll: false };
+  }
+  if (answer.outcome === "already_cancelled") {
+    return { kind: "already_recorded", sentence: C.alreadyRecorded, refresh: true, poll: true };
+  }
+  return { kind: "recorded", sentence: C.recorded, refresh: true, poll: true };
+}
+
+// --- Polling -------------------------------------------------------------------------------------
+
+export const POLL_BASE_MS = 10_000;
+export const POLL_MAX_MS = 60_000;
+export const POLL_ERROR_LIMIT = 5;
+export const POLL_HARD_STOP_MS = 2 * 3_600_000;
+export const POLL_JITTER = 0.15;
+/** On becoming visible, a read older than this is refreshed at once. */
+export const POLL_STALE_AFTER_MS = 5_000;
+
+export type StopReason =
+  | "terminal"
+  | "unknown_state"
+  | "errors"
+  | "hard_stop"
+  | "session"
+  | "not_found";
+
+export interface PollState {
+  /** The un-jittered delay last scheduled. */
+  readonly delayMs: number;
+  readonly errors: number;
+  /** When the page loaded (or Resume was pressed). */
+  readonly sinceMs: number;
+  readonly stopped: StopReason | null;
+}
+
+export function initialPoll(nowMs: number): PollState {
+  return { delayMs: POLL_BASE_MS, errors: 0, sinceMs: nowMs, stopped: null };
+}
+
+export type PollEvent =
+  | { readonly kind: "read"; readonly state: string; readonly changed: boolean }
+  | { readonly kind: "error"; readonly fatal?: "session" | "not_found" }
+  | { readonly kind: "hidden" }
+  | { readonly kind: "visible"; readonly sinceLastReadMs: number };
+
+export type PollStep =
+  | { readonly action: "wait"; readonly delayMs: number }
+  | { readonly action: "refresh_now" }
+  | { readonly action: "pause" }
+  | { readonly action: "stop"; readonly reason: StopReason };
+
+const jitter = (base: number, random: number): number =>
+  Math.round(base * (1 + (random * 2 - 1) * POLL_JITTER));
+
+/**
+ * The poller's whole schedule, pure (the browser module only holds the timer and the abort controller).
+ * The first read comes `POLL_BASE_MS` after load; an unchanged answer doubles the delay up to
+ * `POLL_MAX_MS` (the backend refreshes a live job from the cluster at most once a minute, so asking
+ * faster adds load and no freshness) and a changed one resets it; an error doubles it too, and the fifth
+ * in a row stops; a terminal or unknown state, a 401, a not-found and the two-hour mark stop for good;
+ * a hidden tab pauses and a visible one refreshes at once if the last read is stale. `random` is in
+ * [0, 1) and moves each delay by at most 15 percent. Once stopped it stays stopped.
+ */
+export function nextPoll(
+  prev: PollState,
+  event: PollEvent,
+  nowMs: number,
+  random = 0.5,
+): { step: PollStep; next: PollState } {
+  const stop = (reason: StopReason): { step: PollStep; next: PollState } => ({
+    step: { action: "stop", reason },
+    next: { ...prev, stopped: prev.stopped ?? reason },
+  });
+  if (prev.stopped !== null) return { step: { action: "stop", reason: prev.stopped }, next: prev };
+  if (nowMs - prev.sinceMs >= POLL_HARD_STOP_MS) return stop("hard_stop");
+  switch (event.kind) {
+    case "hidden":
+      return { step: { action: "pause" }, next: prev };
+    case "visible": {
+      const next = { ...prev, delayMs: POLL_BASE_MS };
+      return event.sinceLastReadMs > POLL_STALE_AFTER_MS
+        ? { step: { action: "refresh_now" }, next }
+        : { step: { action: "wait", delayMs: jitter(POLL_BASE_MS, random) }, next };
+    }
+    case "error": {
+      if (event.fatal) return stop(event.fatal);
+      const errors = prev.errors + 1;
+      if (errors >= POLL_ERROR_LIMIT)
+        return { ...stop("errors"), next: { ...prev, errors, stopped: "errors" } };
+      const base = Math.min(prev.delayMs * 2, POLL_MAX_MS);
+      return {
+        step: { action: "wait", delayMs: jitter(base, random) },
+        next: { ...prev, errors, delayMs: base },
+      };
+    }
+    case "read": {
+      if (!isComputeJobState(event.state)) return stop("unknown_state");
+      if (isTerminalComputeState(event.state)) return stop("terminal");
+      const base = event.changed ? POLL_BASE_MS : Math.min(prev.delayMs * 2, POLL_MAX_MS);
+      return {
+        step: { action: "wait", delayMs: jitter(base, random) },
+        next: { ...prev, errors: 0, delayMs: base },
+      };
+    }
+  }
+}

From ddc38f4829847a58ece1bdc006edf3065b83fa28 Mon Sep 17 00:00:00 2001
From: Seyed Yahya Shirazi 
Date: Sat, 7 Nov 2026 08:35:36 -0800
Subject: [PATCH 08/17] Forward the truncated header; skip cache for compute

---
 scripts/capture-compute-job-fixtures.mjs |  1 -
 src/lib/auth.test.ts                     |  5 ++
 src/lib/compute-api-job.test.ts          | 40 ++++++++++---
 src/middleware.test.ts                   | 41 +++++++++++++
 src/middleware.ts                        | 15 +++--
 src/pages/api/v1/[...path].ts            |  5 ++
 test/api-proxy-compute-log.test.ts       | 76 ++++++++++++++++++++++++
 7 files changed, 169 insertions(+), 14 deletions(-)
 create mode 100644 test/api-proxy-compute-log.test.ts

diff --git a/scripts/capture-compute-job-fixtures.mjs b/scripts/capture-compute-job-fixtures.mjs
index 40284117..fef18085 100644
--- a/scripts/capture-compute-job-fixtures.mjs
+++ b/scripts/capture-compute-job-fixtures.mjs
@@ -63,7 +63,6 @@ const { submitComputeJob, advanceComputeJob } = await import(
   join(root, "backend/src/services/compute-lifecycle.ts")
 );
 const { hashApiKey } = await import(join(root, "backend/src/services/token.ts"));
-const { logKey } = await import(join(root, "backend/src/services/compute-records.ts"));
 const { COMPUTE_STATES, COMPUTE_FAILURE_CODES } = await import(
   join(root, "shared/compute-state.ts")
 );
diff --git a/src/lib/auth.test.ts b/src/lib/auth.test.ts
index 4fe0df43..1549f0b4 100644
--- a/src/lib/auth.test.ts
+++ b/src/lib/auth.test.ts
@@ -33,6 +33,11 @@ describe("safeRedirectPath", () => {
     expect(safeRedirectPath("/path\nwith\nnewline")).toBe("/");
     expect(safeRedirectPath("/path\rwith\rcr")).toBe("/");
   });
+  it("keeps a job page path, which the mail link and a signed-out visit return to", () => {
+    const job = "/compute/jobs/job_0123456789abcdef01234567";
+    expect(safeRedirectPath(job)).toBe(job);
+    expect(safeRedirectPath(decodeURIComponent(encodeURIComponent(job)))).toBe(job);
+  });
   it("guards against URL-encoded protocol-relative URLs", () => {
     expect(safeRedirectPath("/%2F%2Fevil.com")).toBe("/");
     expect(safeRedirectPath("/%5C%5Cevil.com")).toBe("/");
diff --git a/src/lib/compute-api-job.test.ts b/src/lib/compute-api-job.test.ts
index 3ebb54d4..9415941d 100644
--- a/src/lib/compute-api-job.test.ts
+++ b/src/lib/compute-api-job.test.ts
@@ -140,17 +140,37 @@ describe("GET /compute/me/jobs/:id", () => {
   });
 
   it("rejects a missing key or a wrong type as a shape error, never zeros", () => {
-    const bad = (mutate: (b: { job: Record }) => void) => {
-      const b = structuredClone(jobStates.running.body) as { job: Record };
+    type Loose = { job: Record & { resources: Record } };
+    const bad = (mutate: (b: Loose) => void) => {
+      const b = structuredClone(jobStates.running.body) as unknown as Loose;
       mutate(b);
       return () => parseComputeJob(b);
     };
-    expect(bad((b) => delete b.job.resources)).toThrow(ComputeApiError);
-    expect(bad((b) => delete b.job.resources.minutes)).toThrow(ComputeApiError);
-    expect(bad((b) => (b.job.resources.nodes = "1"))).toThrow(ComputeApiError);
-    expect(bad((b) => (b.job.charged_milli = 1.5))).toThrow(ComputeApiError);
-    expect(bad((b) => (b.job.cancel_requested = 0))).toThrow(ComputeApiError);
-    expect(bad((b) => (b.job.name = 5))).toThrow(ComputeApiError);
+    const without = (o: Record, key: string) => {
+      Reflect.deleteProperty(o, key);
+    };
+    expect(bad((b) => without(b.job, "resources"))).toThrow(ComputeApiError);
+    expect(bad((b) => without(b.job.resources, "minutes"))).toThrow(ComputeApiError);
+    expect(
+      bad((b) => {
+        b.job.resources.nodes = "1";
+      }),
+    ).toThrow(ComputeApiError);
+    expect(
+      bad((b) => {
+        b.job.charged_milli = 1.5;
+      }),
+    ).toThrow(ComputeApiError);
+    expect(
+      bad((b) => {
+        b.job.cancel_requested = 0;
+      }),
+    ).toThrow(ComputeApiError);
+    expect(
+      bad((b) => {
+        b.job.name = 5;
+      }),
+    ).toThrow(ComputeApiError);
     expect(() => parseComputeJob(null)).toThrow(ComputeApiError);
     expect(() => parseComputeJob({ job: jobStates.running.body.job, stale: "yes" })).toThrow(
       ComputeApiError,
@@ -273,7 +293,9 @@ describe("results and renew", () => {
   });
 
   it("copies only the keys the page reads", () => {
-    const body = structuredClone(results.get.body) as Record;
+    const body = structuredClone(results.get.body) as unknown as Record & {
+      files: Record[];
+    };
     body.extra = 1;
     body.files[0].etag = "x";
     expect(Object.keys(parseComputeResults(body)).sort()).toEqual(
diff --git a/src/middleware.test.ts b/src/middleware.test.ts
index b5bc625c..33c48122 100644
--- a/src/middleware.test.ts
+++ b/src/middleware.test.ts
@@ -2378,6 +2378,47 @@ describe("the authorization page's headers", () => {
   });
 });
 
+describe("the compute pages never enter the edge cache (website#496)", () => {
+  const JOB = "/compute/jobs/job_0123456789abcdef01234567";
+
+  it("bypasses /compute and everything under it, and nothing that only starts with it", () => {
+    for (const path of ["/compute", "/compute/", JOB, "/compute/jobs"]) {
+      expect(routeBypassesEdgeCache(path), path).toBe(true);
+    }
+    for (const path of ["/computex", "/compute-x", "/discover", "/"]) {
+      expect(routeBypassesEdgeCache(path), path).toBe(false);
+    }
+  });
+
+  it("does not open the cache for a signed-out request to a job page, whatever the page says", async () => {
+    const opened: string[] = [];
+    const storage = {
+      open: async (name: string) => {
+        opened.push(name);
+        return { match: async () => undefined, put: async () => {} };
+      },
+    } as unknown as CacheStorage;
+    const make = (url: string, cookie: boolean) =>
+      ({
+        request: new Request(url),
+        locals: { runtime: { caches: storage } },
+        cookies: { has: () => cookie, get: () => undefined },
+      }) as unknown as APIContext;
+    const publicPage = async () =>
+      new Response("x", { headers: { "Cache-Control": "public, max-age=60" } });
+    for (const origin of [`https://${APP_HOST}`, "http://localhost:4321"]) {
+      for (const cookie of [false, true]) {
+        for (const path of ["/compute", JOB]) {
+          const res = (await onRequest(make(`${origin}${path}`, cookie), publicPage)) as Response;
+          expect(res.status, `${origin}${path} ${cookie}`).toBe(200);
+          expect(res.headers.get("x-nemar-cache"), `${origin}${path}`).toBeNull();
+        }
+      }
+    }
+    expect(opened).toEqual([]);
+  });
+});
+
 // Compute access on the session user (website ADR 0030). The bodies are the
 // real `GET /auth/me` answers captured for each state by
 // scripts/capture-compute-fixtures.mjs (nemar-cli 3a869903).
diff --git a/src/middleware.ts b/src/middleware.ts
index dba101f3..c32e389b 100644
--- a/src/middleware.ts
+++ b/src/middleware.ts
@@ -132,14 +132,21 @@ export function isOidcAuthorizeRoute(pathname: string): boolean {
 }
 
 /**
- * Routes whose responses never enter the edge cache, whatever they say: everything under `/oauth`.
- * Each answer there is per visitor and some carry a one-time code; the page sends `no-store`, and
- * this keeps the cache from even being consulted for them.
+ * Routes whose responses never enter the edge cache, whatever they say: everything under `/oauth`
+ * and everything under `/compute`. Each answer there is per visitor; `/oauth` carries one-time codes
+ * and a job page can carry bearer result links after a click (website#496). The page sends
+ * `no-store`, and this keeps the cache from even being consulted for them, so even a signed-out
+ * redirect or a mistaken header cannot put one in the shared cache.
  *
  * Exported for the middleware unit tests.
  */
 export function routeBypassesEdgeCache(pathname: string): boolean {
-  return pathname === "/oauth" || pathname.startsWith("/oauth/");
+  return (
+    pathname === "/oauth" ||
+    pathname.startsWith("/oauth/") ||
+    pathname === "/compute" ||
+    pathname.startsWith("/compute/")
+  );
 }
 
 /** Base connect-src for every route: same-site APIs plus the raw README host. */
diff --git a/src/pages/api/v1/[...path].ts b/src/pages/api/v1/[...path].ts
index d06d3619..a7747222 100644
--- a/src/pages/api/v1/[...path].ts
+++ b/src/pages/api/v1/[...path].ts
@@ -1,6 +1,7 @@
 import type { APIRoute } from "astro";
 import { apiBase, copySetCookies } from "../../../lib/api-base";
 import { apiFetch } from "../../../lib/api-fetch";
+import { COMPUTE_TRUNCATED_HEADER } from "../../../lib/compute-contract";
 import { isAuthorizationProxyPath, isSafeProxyPath } from "../../../lib/proxy-path";
 
 /**
@@ -118,6 +119,10 @@ const proxy: APIRoute = async ({ params, request }) => {
   const contentType = upstream.headers.get("content-type");
   if (contentType) respHeaders.set("Content-Type", contentType);
   respHeaders.set("Cache-Control", "no-store");
+  // The compute log route marks a log cut at 1 MiB with this header (website#496). It is the ONE
+  // upstream header besides the content type that the job page reads, and this is its only reader.
+  const truncated = upstream.headers.get(COMPUTE_TRUNCATED_HEADER);
+  if (truncated !== null) respHeaders.set(COMPUTE_TRUNCATED_HEADER, truncated);
   copySetCookies(upstream, respHeaders);
 
   return new Response(upstream.body, { status: upstream.status, headers: respHeaders });
diff --git a/test/api-proxy-compute-log.test.ts b/test/api-proxy-compute-log.test.ts
new file mode 100644
index 00000000..bd952296
--- /dev/null
+++ b/test/api-proxy-compute-log.test.ts
@@ -0,0 +1,76 @@
+/**
+ * The same-origin proxy and the compute log's `X-Nemar-Truncated` header (website#496). The upstream is
+ * a real binding answering what the real log route answers (headers captured in
+ * `test/fixtures/compute/logs.json`).
+ */
+import { describe, expect, it } from "vitest";
+import { COMPUTE_TRUNCATED_HEADER } from "../src/lib/compute-contract";
+import { type ApiBinding, runWithRequestContext } from "../src/lib/request-context";
+import { GET } from "../src/pages/api/v1/[...path]";
+import logs from "./fixtures/compute/logs.json";
+
+const JOB = "job_0123456789abcdef01234567";
+
+async function through(upstream: Response): Promise {
+  const binding: ApiBinding = { fetch: async () => upstream };
+  const request = new Request(`https://test.nemar.org/api/v1/compute/jobs/${JOB}/logs`);
+  return (await runWithRequestContext({ apiBinding: binding, visitorIp: "198.51.100.7" }, () =>
+    GET({ params: { path: `compute/jobs/${JOB}/logs` }, request } as unknown as Parameters<
+      typeof GET
+    >[0]),
+  )) as Response;
+}
+
+describe("the proxy and the truncated-log header", () => {
+  it("forwards the header the real route sets on a log cut at 1 MiB", async () => {
+    const t = logs.truncated;
+    const res = await through(new Response("x".repeat(64), { status: 200, headers: t.headers }));
+    expect(res.headers.get(COMPUTE_TRUNCATED_HEADER)).toBe("true");
+    expect(await res.text()).toBe("x".repeat(64));
+  });
+
+  it("sets nothing when the upstream sent none", async () => {
+    const res = await through(
+      new Response(logs.live.text, { status: 200, headers: logs.live.headers }),
+    );
+    expect(res.headers.has(COMPUTE_TRUNCATED_HEADER)).toBe(false);
+    expect(await res.text()).toBe(logs.live.text);
+    expect(res.headers.get("content-type")).toBe("text/plain; charset=utf-8");
+  });
+
+  it("still answers no-store when the upstream says public", async () => {
+    const res = await through(
+      new Response("a", {
+        headers: { "Cache-Control": "public, max-age=60", "X-Nemar-Truncated": "true" },
+      }),
+    );
+    expect(res.headers.get("cache-control")).toBe("no-store");
+  });
+
+  it("copies Set-Cookie as before and no other upstream header", async () => {
+    const upstream = new Response("a", { headers: { "X-Secret-Upstream": "1", Etag: "abc" } });
+    upstream.headers.append("Set-Cookie", "a=1; Path=/");
+    upstream.headers.append("Set-Cookie", "b=2; Path=/");
+    const res = await through(upstream);
+    expect(res.headers.getSetCookie()).toEqual(["a=1; Path=/", "b=2; Path=/"]);
+    expect(res.headers.has("x-secret-upstream")).toBe(false);
+    expect(res.headers.has("etag")).toBe(false);
+  });
+
+  it("is the only reader of the header in the source", async () => {
+    const files = import.meta.glob("/src/**/*.{ts,astro}", {
+      query: "?raw",
+      import: "default",
+      eager: true,
+    }) as Record;
+    const readers = Object.entries(files)
+      .filter(([, src]) =>
+        /x-nemar-truncated/i.test(src.replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, "")),
+      )
+      .map(([name]) => name);
+    // The literal is spelled in the contract transcription only; every reader imports the constant.
+    expect(
+      readers.filter((n) => !n.endsWith("compute-contract.ts") && !n.endsWith(".test.ts")),
+    ).toEqual([]);
+  });
+});

From 6eb9c1e90b1ffc4c0a327f2268715d0c10a20cb9 Mon Sep 17 00:00:00 2001
From: Seyed Yahya Shirazi 
Date: Sat, 7 Nov 2026 08:41:10 -0800
Subject: [PATCH 09/17] Add the compute job page

---
 src/components/ComputeJobActions.astro  |  31 ++
 src/components/ComputeJobLogs.astro     |  64 +++
 src/components/ComputeJobResults.astro  | 111 +++++
 src/components/ComputeJobTimeline.astro | 145 +++++++
 src/lib/compute-job-dom.ts              | 145 +++++++
 src/lib/compute-job-live.ts             | 137 ++++++
 src/lib/compute-job-page.ts             | 539 ++++++++++++++++++++++++
 src/pages/compute/jobs/[id].astro       | 395 +++++++++++++++++
 test/compute-dashboard-ui.test.ts       |  17 +-
 test/compute-job-ui.test.ts             | 336 +++++++++++++++
 10 files changed, 1919 insertions(+), 1 deletion(-)
 create mode 100644 src/components/ComputeJobActions.astro
 create mode 100644 src/components/ComputeJobLogs.astro
 create mode 100644 src/components/ComputeJobResults.astro
 create mode 100644 src/components/ComputeJobTimeline.astro
 create mode 100644 src/lib/compute-job-dom.ts
 create mode 100644 src/lib/compute-job-live.ts
 create mode 100644 src/lib/compute-job-page.ts
 create mode 100644 src/pages/compute/jobs/[id].astro
 create mode 100644 test/compute-job-ui.test.ts

diff --git a/src/components/ComputeJobActions.astro b/src/components/ComputeJobActions.astro
new file mode 100644
index 00000000..0c2bf6a3
--- /dev/null
+++ b/src/components/ComputeJobActions.astro
@@ -0,0 +1,31 @@
+---
+/**
+ * The Actions section of a job page (website ADR 0030 phase E3, #496): Cancel, for a live job only.
+ * It opens the shared `ConfirmDialog` (danger tone); the confirmed cancel is one `POST` made by
+ * `src/lib/compute-job-page.ts`, which shows the backend's outcome in words. The status line is where
+ * focus returns, because the button disappears after a successful cancel.
+ */
+import { JOB_COPY } from "../lib/compute-copy";
+import ConfirmDialog from "./ConfirmDialog.astro";
+
+interface Props {
+  canCancel: boolean;
+}
+const { canCancel } = Astro.props;
+const L = JOB_COPY.cancel;
+---
+
+
+ + + +
diff --git a/src/components/ComputeJobLogs.astro b/src/components/ComputeJobLogs.astro new file mode 100644 index 00000000..f66a15de --- /dev/null +++ b/src/components/ComputeJobLogs.astro @@ -0,0 +1,64 @@ +--- +/** + * The Log section of a job page (website ADR 0030 phase E3, #496). Nothing is read at page load: a log + * read can be a cluster read, so "Show log" asks for it. The text is the job's own output and is + * attacker-controlled: it is prepared by `src/lib/compute-logs.ts` (formatting removed, hostile + * characters written out, long lines capped) and set as `textContent` of the one `
` by
+ * `src/lib/compute-job-page.ts`. The backend returns the FIRST 1 MiB only (nemar-cli#2094 asks for a
+ * tail), so a cut log says so and points at the command line.
+ */
+import { JOB_COPY } from "../lib/compute-copy";
+
+interface Props {
+  jobId: string;
+}
+const { jobId } = Astro.props;
+const L = JOB_COPY.logs;
+---
+
+
+

+ +

+ + + + +

+ +

+ +
+ + diff --git a/src/components/ComputeJobResults.astro b/src/components/ComputeJobResults.astro new file mode 100644 index 00000000..be68b1e6 --- /dev/null +++ b/src/components/ComputeJobResults.astro @@ -0,0 +1,111 @@ +--- +/** + * The Results section of a job page (website ADR 0030 phase E3, #496). + * + * Viewing the page mints NOTHING and the server-rendered HTML carries no link: the download links are + * seven-day BEARER links, minted by the backend only when "Get download links" (or "Renew links") is + * pressed, written into this section by `src/lib/compute-job-page.ts` as `href` attributes with + * `rel="noopener noreferrer"`, and never stored, logged, copied or put in a URL. The backend's own + * `notice` about keeping them private is shown as served. + */ +import { JOB_COPY } from "../lib/compute-copy"; +import type { ResultsPanelView } from "../lib/compute-job-view"; + +interface Props { + jobId: string; + panel: ResultsPanelView; +} +const { jobId, panel } = Astro.props; +const L = JOB_COPY.results; +--- + +
+

{panel.headline}

+

+ +

+ + +

+ {L.allLead}nemar compute results {jobId} --download <dir>{L.allTail} +

+
+ + diff --git a/src/components/ComputeJobTimeline.astro b/src/components/ComputeJobTimeline.astro new file mode 100644 index 00000000..eb8ac235 --- /dev/null +++ b/src/components/ComputeJobTimeline.astro @@ -0,0 +1,145 @@ +--- +/** + * The state timeline and the details list of a job page (website ADR 0030 phase E3, #496). Both come + * from `jobDetailView` in `src/lib/compute-job-view.ts`; the browser rebuilds the same nodes from the + * same view (`src/lib/compute-job-dom.ts`), so the styles are GLOBAL and prefixed `.compute-job` (Astro + * scoped styles do not reach script-built nodes). Keep the class names in step with that module. + * + * The timeline claims only what the record carries: three times, no per-stage times. A step that is + * not known reads "not known" in words and carries a dash, never a check mark. The current step has a + * shape and the word, not a color alone. + */ +import { JOB_COPY } from "../lib/compute-copy"; +import type { JobDetailView } from "../lib/compute-job-view"; +import StatusIcon from "./admin/StatusIcon.astro"; + +interface Props { + view: JobDetailView; +} + +const { view } = Astro.props; +--- + +
    + {view.timeline.steps.map((step) => ( +
  1. + + + {step.label}{" "} + ({step.statusWord}) + {step.time && ( + + {step.time.label ? `${step.time.label} ` : ""} + + + )} + +
  2. + ))} +
+ + + diff --git a/src/lib/compute-job-dom.ts b/src/lib/compute-job-dom.ts new file mode 100644 index 00000000..07241e18 --- /dev/null +++ b/src/lib/compute-job-dom.ts @@ -0,0 +1,145 @@ +/** + * Browser-side nodes for the job page (website ADR 0030 phase E3, issue #496). The server renders the + * first view from `jobDetailView` in the Astro components; this module renders every later view from + * the SAME view models, so the two are thin renderers over one place (the precedent is + * `compute-jobs-dom.ts`). It builds DOM with `createElement`, `createElementNS` and `textContent` + * ONLY: a job's name, a log line or a file name is therefore a text node and can never become markup. + * `test/compute-job-ui.test.ts` forbids every markup-writing API in the job files. + * + * The class names are the contract with the global styles in the components (Astro's scoped styles do + * not reach script-built nodes); keep them in step with `ComputeJobTimeline.astro`, + * `ComputeJobResults.astro` and the page. + */ +import type { FailureView } from "./compute-failure"; +import type { DetailRow, ResultRow, TimelineView } from "./compute-job-view"; +import { iconPaths } from "./status-icons"; + +const SVG_NS = "http://www.w3.org/2000/svg"; + +export function el( + doc: Document, + tag: K, + className?: string, + text?: string, +): HTMLElementTagNameMap[K] { + const node = doc.createElement(tag); + if (className) node.className = className; + if (text !== undefined) node.textContent = text; + return node; +} + +function icon(doc: Document, name: string, size = 14): SVGSVGElement { + const svg = doc.createElementNS(SVG_NS, "svg"); + svg.setAttribute("viewBox", "0 0 16 16"); + svg.setAttribute("width", String(size)); + svg.setAttribute("height", String(size)); + svg.setAttribute("aria-hidden", "true"); + svg.setAttribute("focusable", "false"); + for (const d of iconPaths(name)) { + const path = doc.createElementNS(SVG_NS, "path"); + path.setAttribute("d", d); + svg.append(path); + } + return svg; +} + +function timeElement( + doc: Document, + text: string, + iso: string | null, + title: string, +): HTMLTimeElement { + const t = el(doc, "time", undefined, text); + if (iso) t.setAttribute("datetime", iso); + t.setAttribute("title", title); + return t; +} + +/** The items of the timeline `
    `; empty for a state this build does not know. */ +export function timelineItems(doc: Document, view: TimelineView): HTMLLIElement[] { + return view.steps.map((step) => { + const li = el(doc, "li", `compute-job-step compute-job-step--${step.status}`); + li.dataset.step = step.key; + if (step.status === "current") li.setAttribute("aria-current", "step"); + li.append(icon(doc, step.icon, 16)); + const text = el(doc, "span", "compute-job-step__text"); + text.append(el(doc, "span", "compute-job-step__label", step.label)); + text.append(" ", el(doc, "span", "visually-hidden", `(${step.statusWord})`)); + if (step.time) { + const when = el(doc, "span", "compute-job-step__time"); + if (step.time.label) when.append(`${step.time.label} `); + when.append(timeElement(doc, step.time.text, step.time.iso, step.time.title)); + text.append(when); + } + li.append(text); + return li; + }); +} + +/** The rows of the details `
    `, then the charge row. */ +export function detailRows( + doc: Document, + rows: readonly DetailRow[], + charge: { label: string; text: string; kind: string }, +): HTMLDivElement[] { + const make = (label: string, kind?: string): [HTMLDivElement, HTMLElement] => { + const wrap = el(doc, "div", "compute-job-row"); + const dd = el(doc, "dd", "compute-job-row__value"); + if (kind) dd.dataset.chargeKind = kind; + wrap.append(el(doc, "dt", "compute-job-row__label", label), dd); + return [wrap, dd]; + }; + const out: HTMLDivElement[] = rows.map((row) => { + const [wrap, dd] = make(row.label); + wrap.dataset.row = row.key; + if (row.time) dd.append(timeElement(doc, row.value, row.time.iso, row.time.title)); + else dd.textContent = row.value; + return wrap; + }); + const [wrap, dd] = make(charge.label, charge.kind); + wrap.dataset.row = "charged"; + dd.textContent = charge.text; + out.push(wrap); + return out; +} + +/** The failure sentence, and the log pointer where the log can help. */ +export function failureNodes(doc: Document, failure: FailureView): Node[] { + const out: Node[] = [el(doc, "p", "compute-job-failure__sentence", failure.sentence)]; + if (failure.logHint) { + const p = el(doc, "p", "compute-job-failure__hint", failure.logHint.lead); + p.append(el(doc, "code", undefined, failure.logHint.command), "."); + out.push(p); + } + out.push(el(doc, "p", "compute-job-failure__code", `Code: ${failure.code}`)); + return out; +} + +/** + * One result file. The address reaches `href` only if `row.href` (from `safeResultHref`) is non-null; the + * link opens in a new tab with no opener and no referrer, and is never copied anywhere else. + */ +export function resultRowElement( + doc: Document, + row: ResultRow, + words: { download: string; unavailable: string; sha: string }, +): HTMLLIElement { + const li = el(doc, "li", "compute-job-result"); + li.append(el(doc, "span", "compute-job-result__path", row.path)); + const meta = el(doc, "span", "compute-job-result__meta", row.size); + const sha = el(doc, "code", "compute-job-result__sha", row.shaShort); + sha.title = `${words.sha} ${row.sha}`; + meta.append(" ", sha); + li.append(meta); + if (row.href) { + const a = el(doc, "a", "compute-job-result__link", words.download); + a.setAttribute("href", row.href); + a.setAttribute("rel", "noopener noreferrer"); + a.setAttribute("referrerpolicy", "no-referrer"); + a.setAttribute("target", "_blank"); + li.append(a); + } else { + li.append(el(doc, "span", "compute-job-result__none", words.unavailable)); + } + return li; +} diff --git a/src/lib/compute-job-live.ts b/src/lib/compute-job-live.ts new file mode 100644 index 00000000..96f12fad --- /dev/null +++ b/src/lib/compute-job-live.ts @@ -0,0 +1,137 @@ +/** + * The browser side of the job page that touches a clock or a timer (website ADR 0030 phase E3, issue + * #496). It is the ONE job module allowed to: the schedule itself is pure (`nextPoll` in + * `compute-job-view.ts`, tested with an injected clock), and this file only holds the `setTimeout`, the + * `AbortController` and the page-visibility events. The source scan in `test/compute-dashboard-ui.test.ts` + * names this file as its single exception. + * + * `setTimeout` chains, never `setInterval`; at most one request in flight; a hidden tab clears the + * timer and aborts the request; `pagehide` aborts. + */ +import { + type PollEvent, + type PollState, + type PollStep, + type StopReason, + initialPoll, + nextPoll, +} from "./compute-job-view"; + +/** The current time in epoch milliseconds. */ +export function nowMs(): number { + return Date.now(); +} + +export interface PollerHandlers { + /** One read of the job; throw to report an error. Resolve with what the schedule needs to know. */ + read(signal: AbortSignal): Promise<{ state: string; changed: boolean }>; + /** Called when the poller stops for good (or is paused by the hard stop and can be resumed). */ + onStop(reason: StopReason): void; + /** Classify a thrown error: fatal ones end the poller at once. */ + fatal(err: unknown): "session" | "not_found" | undefined; +} + +export interface Poller { + /** Start (or restart) from a fresh schedule, as after Resume. */ + start(): void; + /** Read once now, outside the schedule (after a cancel), and continue the schedule from it. */ + refreshNow(): void; + stop(): void; +} + +export function createPoller(handlers: PollerHandlers): Poller { + let state: PollState = initialPoll(nowMs()); + let timer: ReturnType | undefined; + let controller: AbortController | undefined; + let lastReadAt = nowMs(); + let running = false; + + const clear = (): void => { + if (timer !== undefined) clearTimeout(timer); + timer = undefined; + }; + const abort = (): void => { + controller?.abort(); + controller = undefined; + }; + + const apply = (event: PollEvent): void => { + const out = nextPoll(state, event, nowMs(), Math.random()); + state = out.next; + handle(out.step); + }; + + const handle = (step: PollStep): void => { + clear(); + if (step.action === "stop") { + abort(); + running = false; + handlers.onStop(step.reason); + } else if (step.action === "pause") { + abort(); + } else if (step.action === "refresh_now") { + void tick(); + } else { + timer = setTimeout(() => void tick(), step.delayMs); + } + }; + + const tick = async (): Promise => { + clear(); + if (!running || controller) return; // one request in flight at most + const mine = new AbortController(); + controller = mine; + let event: PollEvent; + try { + const got = await handlers.read(mine.signal); + lastReadAt = nowMs(); + event = { kind: "read", state: got.state, changed: got.changed }; + } catch (err) { + if (mine.signal.aborted) { + if (controller === mine) controller = undefined; + return; // aborted on purpose (hidden tab, pagehide): the visibility event restarts it + } + event = { kind: "error", fatal: handlers.fatal(err) }; + } + if (controller === mine) controller = undefined; + if (running) apply(event); + }; + + const onVisibility = (): void => { + if (!running) return; + if (document.hidden) { + apply({ kind: "hidden" }); + clear(); + } else { + apply({ kind: "visible", sinceLastReadMs: nowMs() - lastReadAt }); + } + }; + document.addEventListener("visibilitychange", onVisibility); + window.addEventListener("pagehide", () => { + clear(); + abort(); + }); + + return { + start() { + state = initialPoll(nowMs()); + running = true; + lastReadAt = nowMs(); + clear(); + abort(); + if (!document.hidden) timer = setTimeout(() => void tick(), state.delayMs); + }, + refreshNow() { + if (!running) return; + clear(); + abort(); + state = { ...state, delayMs: 10_000 }; + void tick(); + }, + stop() { + running = false; + clear(); + abort(); + }, + }; +} diff --git a/src/lib/compute-job-page.ts b/src/lib/compute-job-page.ts new file mode 100644 index 00000000..a97c458c --- /dev/null +++ b/src/lib/compute-job-page.ts @@ -0,0 +1,539 @@ +/** + * The browser controller of `/compute/jobs/` (website ADR 0030 phase E3, issue #496): live refresh, + * the log, the result links and the cancel. Every word and rule comes from the pure modules + * (`compute-job-view.ts`, `compute-logs.ts`, `compute-copy.ts`); this file only reads the page's + * `data-*` hooks, calls the client (`compute-api.ts`) and writes the answer back as text nodes through + * `compute-job-dom.ts`. Nothing here writes markup. + * + * Rules this file keeps (each has a source scan in `test/compute-job-ui.test.ts`): + * - A result link is minted only by a click on "Get download links" or "Renew links", lives only in the + * DOM of this page, and is never written to storage, the URL, a log, the clipboard or an attribute + * other than `href`. `pageshow` with a persisted page clears the list. + * - Log text is never logged or counted in the console. + * - Timing comes from `compute-job-live.ts`, the one module that reads a clock. + */ +import { + ComputeApiError, + type ComputeJobRead, + type ComputeResults, + cancelComputeJob, + getComputeJob, + getComputeLogs, + getComputeMe, + getComputeResults, + renewComputeResults, +} from "./compute-api"; +import { JOB_COPY } from "./compute-copy"; +import { detailRows, el, failureNodes, resultRowElement, timelineItems } from "./compute-job-dom"; +import { createPoller, nowMs } from "./compute-job-live"; +import { + RESULT_ROWS_STEP, + type ResultRow, + cancelOutcome, + jobDetailView, + linksExpired, + linksOutliveFiles, + logFailure, + resultRow, + resultsFailure, + resultsPaging, + resultsPanelView, +} from "./compute-job-view"; +import { badgeElement } from "./compute-jobs-dom"; +import { LOG_EARLIER_STEP, LOG_TAIL_DEFAULT, logWindow, prepareLog } from "./compute-logs"; + +const LOG_REFRESH_COOLDOWN_MS = 10_000; + +function must(root: ParentNode, selector: string): T { + const node = root.querySelector(selector); + if (!node) throw new Error(`the job page is missing ${selector}`); + return node; +} + +function setText(node: Element, text: string): void { + node.textContent = text; +} + +/** Add "(your time: ...)" to a line that carries the instant it names in `data-until-iso`. */ +function addLocalTime(node: HTMLElement): void { + const iso = node.dataset.untilIso; + const when = iso ? new Date(iso) : null; + if (when && !Number.isNaN(when.getTime())) { + node.textContent = `${node.textContent ?? ""} (${JOB_COPY.results.yourTime}: ${when.toLocaleString()})`; + } +} + +export function initJobPage(root: HTMLElement): void { + const doc = root.ownerDocument; + const jobId = root.dataset.jobId ?? ""; + const source = root.dataset.source ?? ""; + let resultsDays: number | null = root.dataset.resultsDays + ? Number(root.dataset.resultsDays) + : null; + let current: ComputeJobRead | null = null; + let lastState = root.dataset.state ?? ""; + let lastCancel = root.dataset.cancelRequested === "true"; + let ended = false; + let readResultsDays = resultsDays !== null; + + const announce = must(root, "[data-job-announce]"); + const paused = must(root, "[data-job-paused]"); + const pausedText = must(root, "[data-job-paused-text]"); + const pausedSignIn = must(root, "[data-job-signin]"); + const pausedButton = must(root, "[data-job-resume]"); + + // --- applying a job ------------------------------------------------------------------------------ + + function applyJob(read: ComputeJobRead): { changed: boolean } { + const view = jobDetailView(read); + const changed = + view.state !== lastState || + view.cancelRequested !== lastCancel || + current === null || + current.job.charged_milli !== read.job.charged_milli || + current.stale !== read.stale; + const stateChanged = view.state !== lastState; + current = read; + root.dataset.state = view.state; + must(root, "[data-job-badge]").replaceChildren(badgeElement(doc, view.badge)); + must(root, "[data-job-cancel-note]").hidden = !view.cancelRequested; + must(root, "[data-job-stale]").hidden = !view.stale; + const unreported = must(root, "[data-job-unreported]"); + unreported.hidden = view.unreportedNote === null; + if (view.unreportedNote !== null) setText(unreported, view.unreportedNote); + must(root, "[data-job-timeline]").replaceChildren( + ...timelineItems(doc, view.timeline), + ); + const unknown = must(root, "[data-job-unknown-state]"); + unknown.hidden = view.timeline.unknownState === null; + if (view.timeline.unknownState !== null) { + setText(unknown, `${JOB_COPY.timeline.stateLine}: ${view.timeline.unknownState}`); + } + must(root, "[data-job-rows]").replaceChildren( + ...detailRows(doc, view.rows, { + label: JOB_COPY.rows.charged, + text: view.charge.text, + kind: view.charge.kind, + }), + ); + const failure = must(root, "[data-job-failure]"); + failure.hidden = view.failure === null; + failure + .querySelector("[data-job-failure-body]") + ?.replaceChildren(...(view.failure ? failureNodes(doc, view.failure) : [])); + must(root, "[data-cancel-block]").hidden = !view.canCancel; + if (stateChanged || view.cancelRequested !== lastCancel) { + setText( + announce, + `${JOB_COPY.live.announce(view.badge.label)}${view.cancelRequested ? ` ${JOB_COPY.cancel.requested}.` : ""}`, + ); + } + if (view.terminal && !ended) { + ended = true; + if (!must(root, "[data-logs-region]").hidden) { + const note = must(root, "[data-logs-ended-note]"); + note.hidden = false; + } + } + lastState = view.state; + lastCancel = view.cancelRequested; + void renderResultsPanel(read); + return { changed }; + } + + // --- results panel ------------------------------------------------------------------------------- + + async function renderResultsPanel(read: ComputeJobRead): Promise { + if (read.job.state === "finished" && !readResultsDays) { + readResultsDays = true; + try { + resultsDays = (await getComputeMe()).resultsDays; + } catch { + resultsDays = null; // the line then reads "kept for a limited time"; never blocks the page + } + } + const panel = resultsPanelView({ + state: read.job.state, + endedAt: read.job.ended_at, + resultsDays, + nowMs: nowMs(), + }); + const headline = must(root, "[data-results-headline]"); + setText(headline, panel.headline); + if (panel.window.untilIso) headline.dataset.untilIso = panel.window.untilIso; + else delete headline.dataset.untilIso; + if (panel.window.untilMs !== null) root.dataset.untilMs = String(panel.window.untilMs); + else delete root.dataset.untilMs; + addLocalTime(headline); + // Do not offer the button again once a 410 settled it. + must(root, "[data-results-get]").hidden = + !panel.canGetLinks || resultsGone || heldResults !== null; + } + + // --- the poller ---------------------------------------------------------------------------------- + + const poller = createPoller({ + async read(signal) { + const read = await getComputeJob(jobId, { signal }); + return { state: read.job.state, ...applyJob(read) }; + }, + fatal(err) { + if (err instanceof ComputeApiError) { + if (err.code === "job_not_found") return "not_found"; + if (err.kind === "session") return "session"; + } + return undefined; + }, + onStop(reason) { + if (reason === "terminal" || reason === "unknown_state") { + paused.hidden = true; + return; + } + paused.hidden = false; + pausedSignIn.hidden = reason !== "session"; + pausedButton.hidden = reason === "session" || reason === "not_found"; + pausedButton.textContent = + reason === "hard_stop" ? JOB_COPY.live.resume : JOB_COPY.live.refresh; + setText( + pausedText, + reason === "session" + ? JOB_COPY.live.sessionEnded + : reason === "not_found" + ? JOB_COPY.notFoundBody + : JOB_COPY.live.paused, + ); + }, + }); + pausedButton.addEventListener("click", () => { + paused.hidden = true; + // One read now, then the schedule from the start. + void getComputeJob(jobId) + .then((read) => { + applyJob(read); + if (jobDetailView(read).live) poller.start(); + }) + .catch(() => { + paused.hidden = false; + }); + }); + + // --- logs ---------------------------------------------------------------------------------------- + + const logsShow = must(root, "[data-logs-show]"); + const logsStatus = must(root, "[data-logs-status]"); + const logsRegion = must(root, "[data-logs-region]"); + const logsPre = must(root, "[data-logs-pre]"); + const logsCount = must(root, "[data-logs-count]"); + const logsEarlier = must(root, "[data-logs-earlier]"); + const logsTruncated = must(root, "[data-logs-truncated]"); + let logLines: readonly string[] = []; + let logShown = LOG_TAIL_DEFAULT; + let logTruncatedFlag = false; + let logController: AbortController | undefined; + let logBusy = false; + + function renderLog(): void { + if (logLines.length === 0) { + logsRegion.hidden = true; + logsCount.hidden = true; + logsEarlier.hidden = true; + return; + } + const w = logWindow(logLines, logShown); + logsPre.textContent = w.text; + logsRegion.hidden = false; + logsCount.hidden = false; + setText( + logsCount, + w.hidden === 0 + ? JOB_COPY.logs.countAll(w.total, logTruncatedFlag) + : JOB_COPY.logs.count(w.shown, w.total, logTruncatedFlag), + ); + logsEarlier.hidden = w.hidden === 0; + logsTruncated.hidden = !logTruncatedFlag; + } + + async function loadLog(): Promise { + if (logBusy) return; + logBusy = true; + logController?.abort(); + const mine = new AbortController(); + logController = mine; + logsShow.disabled = true; + logsStatus.hidden = false; + setText(logsStatus, JOB_COPY.logs.loading); + try { + const log = await getComputeLogs(jobId, { signal: mine.signal }); + const prepared = prepareLog(log.text); + logLines = prepared.lines; + logShown = LOG_TAIL_DEFAULT; + logTruncatedFlag = log.truncated; + logsShow.textContent = JOB_COPY.logs.refresh; + must(root, "[data-logs-ended-note]").hidden = true; + if (prepared.lines.length === 0) { + setText(logsStatus, JOB_COPY.logs.empty); + logsTruncated.hidden = !log.truncated; + } else { + logsStatus.hidden = true; + setText(logsStatus, ""); + } + renderLog(); + } catch (err) { + if (mine.signal.aborted) return; + logLines = []; + renderLog(); + const failure = logFailure(err, source); + setText(logsStatus, failure.sentence); + if (failure.kind === "none") logsShow.textContent = JOB_COPY.logs.refresh; + if (failure.kind === "not_found") onNotFound(); + } finally { + logBusy = false; + // Each press may be a cluster read of up to 1 MiB: a short pause before the next. + setTimeout(() => { + logsShow.disabled = false; + }, LOG_REFRESH_COOLDOWN_MS); + } + } + logsShow.addEventListener("click", () => void loadLog()); + logsEarlier.addEventListener("click", () => { + logShown += LOG_EARLIER_STEP; + renderLog(); + }); + + // --- results ------------------------------------------------------------------------------------- + + const resultsGet = must(root, "[data-results-get]"); + const resultsStatus = must(root, "[data-results-status]"); + const resultsPanel = must(root, "[data-results-panel]"); + const resultsList = must(root, "[data-results-list]"); + const resultsSummary = must(root, "[data-results-summary]"); + const resultsExpiry = must(root, "[data-results-expiry]"); + const resultsOutlive = must(root, "[data-results-outlive]"); + const resultsNotice = must(root, "[data-results-notice]"); + const resultsMore = must(root, "[data-results-more]"); + const resultsNext = must(root, "[data-results-next]"); + const resultsFirst = must(root, "[data-results-first]"); + const resultsRenew = must(root, "[data-results-renew]"); + let heldResults: { rows: ResultRow[]; response: ComputeResults } | null = null; + let resultsShown = RESULT_ROWS_STEP; + let resultsOffset = 0; + let resultsAfter: string | null = null; + let resultsGone = false; + let resultsBusy = false; + + function clearResults(): void { + heldResults = null; + resultsList.replaceChildren(); + resultsPanel.hidden = true; + if (current) void renderResultsPanel(current); + } + + function renderResults(): void { + if (heldResults === null) return; + const { rows, response } = heldResults; + resultsPanel.hidden = false; + resultsGet.hidden = true; + const words = { + download: JOB_COPY.results.download, + unavailable: JOB_COPY.results.unavailableLink, + sha: JOB_COPY.results.sha, + }; + resultsList.replaceChildren( + ...rows.slice(0, resultsShown).map((r) => resultRowElement(doc, r, words)), + ); + const from = resultsOffset + 1; + const to = resultsOffset + rows.length; + setText( + resultsSummary, + response.truncated || resultsOffset > 0 + ? JOB_COPY.results.showingRange(from, to, response.total) + : JOB_COPY.results.filesCount(response.total), + ); + setText(resultsNotice, response.notice); + const until = new Date(response.expires_at); + const when = Number.isNaN(until.getTime()) + ? response.expires_at + : `${until.toISOString().slice(0, 16).replace("T", " ")} UTC (${JOB_COPY.results.yourTime}: ${until.toLocaleString()})`; + setText(resultsExpiry, JOB_COPY.results.linksExpire(when)); + const untilMs = Number(root.dataset.untilMs ?? ""); + resultsOutlive.hidden = !linksOutliveFiles( + response.expires_at, + Number.isNaN(untilMs) ? null : untilMs, + ); + const paging = resultsPaging({ + held: rows.length, + shown: Math.min(resultsShown, rows.length), + offset: resultsOffset, + total: response.total, + nextAfter: response.next_after, + }); + resultsMore.hidden = paging.showMore === 0; + setText(resultsMore, JOB_COPY.results.showMore(paging.showMore)); + resultsNext.hidden = paging.nextPageRemaining === null; + if (paging.nextPageRemaining !== null) { + setText(resultsNext, JOB_COPY.results.nextPage(paging.nextPageRemaining)); + } + resultsFirst.hidden = resultsOffset === 0; + } + + /** Replace the rows with a notice when the links' own expiry has passed: no stale link stays in the DOM. */ + function expireLinksIfDue(): void { + if (heldResults === null) return; + if (!linksExpired(heldResults.response.expires_at, nowMs())) return; + heldResults = null; + resultsList.replaceChildren(); + resultsMore.hidden = true; + resultsNext.hidden = true; + resultsFirst.hidden = true; + setText(resultsStatus, JOB_COPY.results.linksExpired); + resultsStatus.hidden = false; + } + + async function fetchResults(after: string | null, renew: boolean, offset: number): Promise { + if (resultsBusy) return; + resultsBusy = true; + for (const b of [resultsGet, resultsRenew, resultsNext, resultsFirst, resultsMore]) { + b.disabled = true; + } + resultsStatus.hidden = false; + setText(resultsStatus, JOB_COPY.results.loading); + try { + const response = renew + ? await renewComputeResults(jobId, after) + : await getComputeResults(jobId, after); + heldResults = { rows: response.files.map(resultRow), response }; + resultsAfter = after; + resultsOffset = offset; + resultsShown = RESULT_ROWS_STEP; + resultsStatus.hidden = true; + setText(resultsStatus, ""); + renderResults(); + } catch (err) { + const failure = resultsFailure(err, resultsDays); + setText(resultsStatus, failure.sentence); + if (failure.kind === "expired") { + resultsGone = true; + heldResults = null; + resultsPanel.hidden = true; + resultsGet.hidden = true; + } + if (failure.kind === "not_ready") resultsGet.hidden = true; + if (failure.kind === "not_found") onNotFound(); + } finally { + resultsBusy = false; + for (const b of [resultsGet, resultsRenew, resultsNext, resultsFirst, resultsMore]) { + b.disabled = false; + } + } + } + resultsGet.addEventListener("click", () => void fetchResults(null, false, 0)); + resultsRenew.addEventListener("click", () => { + expireLinksIfDue(); + void fetchResults(resultsAfter, true, resultsOffset); + }); + resultsMore.addEventListener("click", () => { + resultsShown += RESULT_ROWS_STEP; + renderResults(); + }); + resultsNext.addEventListener("click", () => { + const next = heldResults?.response.next_after ?? null; + if (next === null || heldResults === null) return; + void fetchResults(next, false, resultsOffset + heldResults.rows.length); + }); + resultsFirst.addEventListener("click", () => void fetchResults(null, false, 0)); + doc.addEventListener("visibilitychange", () => { + if (!doc.hidden) expireLinksIfDue(); + }); + // A page restored from the back-forward cache must not bring bearer links back. + window.addEventListener("pageshow", (event) => { + if (event.persisted) { + resultsStatus.hidden = true; + clearResults(); + } + }); + + // --- cancel -------------------------------------------------------------------------------------- + + const cancelOpen = must(root, "[data-cancel-open]"); + const cancelStatus = must(root, "[data-cancel-status]"); + let cancelBusy = false; + + cancelOpen.addEventListener("click", () => { + if (cancelBusy) return; + doc.dispatchEvent( + new CustomEvent<{ dialogId: string }>("nemar:open-confirm-dialog", { + detail: { dialogId: "compute-cancel" }, + }), + ); + }); + + doc.addEventListener("nemar:confirm-dialog-confirm", (event) => { + if ((event as CustomEvent<{ dialogId: string }>).detail?.dialogId !== "compute-cancel") return; + void doCancel(); + }); + + async function reread(): Promise { + try { + const read = await getComputeJob(jobId); + applyJob(read); + return read; + } catch { + return null; + } + } + + async function doCancel(): Promise { + if (cancelBusy) return; + cancelBusy = true; + cancelOpen.disabled = true; + cancelOpen.setAttribute("aria-busy", "true"); + cancelStatus.hidden = false; + setText(cancelStatus, JOB_COPY.cancel.working); + try { + const answer = await cancelComputeJob(jobId); + const outcome = cancelOutcome(answer); + setText(cancelStatus, outcome.sentence); + await reread(); + if (outcome.poll) poller.refreshNow(); + } catch (err) { + if (err instanceof ComputeApiError && err.code === "job_not_found") { + onNotFound(); + } else if (err instanceof ComputeApiError && err.kind === "session") { + setText(cancelStatus, JOB_COPY.live.sessionEnded); + } else if (err instanceof ComputeApiError && err.kind === "account") { + setText(cancelStatus, err.sentence ?? JOB_COPY.cancel.notRecorded); + } else { + // The answer may have been lost after the cancel went through: the job record says which. + setText(cancelStatus, JOB_COPY.cancel.unclear); + const read = await reread(); + if (read?.job.cancel_requested) setText(cancelStatus, JOB_COPY.cancel.recorded); + else if (read) setText(cancelStatus, JOB_COPY.cancel.notRecorded); + } + } finally { + cancelBusy = false; + cancelOpen.disabled = false; + cancelOpen.removeAttribute("aria-busy"); + // The button may be gone now; the status is where focus belongs. + cancelStatus.focus(); + } + } + + // --- a job that is not there --------------------------------------------------------------------- + + function onNotFound(): void { + poller.stop(); + root.replaceChildren( + el(doc, "h1", "compute-job__title", JOB_COPY.notFoundTitle), + el(doc, "p", undefined, JOB_COPY.notFoundBody), + ); + } + + // --- start --------------------------------------------------------------------------------------- + + const headline = must(root, "[data-results-headline]"); + if (headline.dataset.untilIso && root.dataset.untilMs === undefined) { + root.dataset.untilMs = String(Date.parse(headline.dataset.untilIso)); + } + addLocalTime(headline); + if (root.dataset.live === "true") poller.start(); +} diff --git a/src/pages/compute/jobs/[id].astro b/src/pages/compute/jobs/[id].astro new file mode 100644 index 00000000..9cf8a3c9 --- /dev/null +++ b/src/pages/compute/jobs/[id].astro @@ -0,0 +1,395 @@ +--- +/** + * `/compute/jobs/`: one job of the signed-in person, its state as it changes, its resources and + * charge, its log on request, its result links on request (renewable) and a cancel for a live job + * (website ADR 0030 phase E3; epic nemarOrg/website#493, issue #496). App host only. This is the page + * the "results ready" email links to (`computeJobPageUrl` in nemar-cli), so it must be safe to open from + * a mail client: the server-rendered HTML names no result and carries no link. + * + * Order matters here, and `test/compute-job-ui.test.ts` pins it: + * 1. `Cache-Control: private, no-store` and `Referrer-Policy: no-referrer` are set BEFORE any return, + * so the 404 and the notices carry them too (ADR 0021 keeps a page-set no-referrer); + * 2. a signed-out visitor goes to login with `next=` this path; + * 3. an id that is not `job_` and 24 hex digits is the SAME 404 as an unknown one, without calling the + * API; a job that is absent or somebody else's is that 404 too, so the page is no oracle; + * 4. the job is read over the service binding with the visitor's cookie; + * 5. only for a finished job, `GET /compute/me` for `limits.results_days` (its own try/catch: a failure + * degrades one line to "kept for a limited time" and never blocks the page). + * This frontmatter never imports the log or result clients: viewing a job mints nothing. + */ +import ComputeBadge from "../../../components/ComputeBadge.astro"; +import ComputeJobActions from "../../../components/ComputeJobActions.astro"; +import ComputeJobLogs from "../../../components/ComputeJobLogs.astro"; +import ComputeJobResults from "../../../components/ComputeJobResults.astro"; +import ComputeJobTimeline from "../../../components/ComputeJobTimeline.astro"; +import ComputePanel from "../../../components/ComputePanel.astro"; +import ComputePanelNotice from "../../../components/ComputePanelNotice.astro"; +import Base from "../../../layouts/Base.astro"; +import { apiFetch } from "../../../lib/api-fetch"; +import { getSession } from "../../../lib/auth"; +import { + ComputeApiError, + type ComputeInit, + type ComputeJobRead, + getComputeJob, + getComputeMe, +} from "../../../lib/compute-api"; +import { COMPUTE_JOB_ID_RE } from "../../../lib/compute-contract"; +import { JOB_COPY } from "../../../lib/compute-copy"; +import { nowMs } from "../../../lib/compute-job-live"; +import { jobDetailView, resultsPanelView } from "../../../lib/compute-job-view"; +import { COMPUTE_LABELS } from "../../../lib/compute-labels"; +import { noticeFor } from "../../../lib/compute-view"; + +// 1. Before any return. +Astro.response.headers.set("Cache-Control", "private, no-store"); +Astro.response.headers.set("Referrer-Policy", "no-referrer"); + +const id = Astro.params.id ?? ""; +const path = `/compute/jobs/${id}`; + +// 2. Signed out: login, then back here. +const session = getSession(Astro.locals); +if (!session) { + return Astro.redirect(`/login?next=${encodeURIComponent(path)}`); +} + +const cookieHeader = Astro.request.headers.get("cookie") ?? undefined; +const init: ComputeInit = { cookieHeader, fetch: apiFetch }; + +type Outcome = + | { kind: "ok"; read: ComputeJobRead } + | { kind: "not_found" } + | { kind: "not_available" } + | { kind: "account"; sentence: string | null } + | { kind: "failed"; error: unknown }; + +// 3 and 4. +let outcome: Outcome; +if (!COMPUTE_JOB_ID_RE.test(id)) { + outcome = { kind: "not_found" }; +} else { + try { + outcome = { kind: "ok", read: await getComputeJob(id, init) }; + } catch (error) { + console.error( + `[compute-job] read failed: ${error instanceof ComputeApiError ? `${error.kind} ${error.status}` : String(error)}`, + ); + if (error instanceof ComputeApiError && error.code === "job_not_found") { + outcome = { kind: "not_found" }; + } else if (error instanceof ComputeApiError && error.kind === "session") { + return Astro.redirect(`/login?next=${encodeURIComponent(path)}`); + } else if (error instanceof ComputeApiError && error.kind === "account") { + outcome = { kind: "account", sentence: error.sentence ?? null }; + } else if ( + error instanceof ComputeApiError && + error.kind === "unavailable" && + error.status === 404 + ) { + // A 404 with no job_not_found code is the release gate: an API without the compute routes. + outcome = { kind: "not_available" }; + } else { + outcome = { kind: "failed", error }; + } + } +} +if (outcome.kind === "not_found") Astro.response.status = 404; + +// 5. The retention policy, only for a finished job. +let resultsDays: number | null = null; +if (outcome.kind === "ok" && outcome.read.job.state === "finished") { + try { + resultsDays = (await getComputeMe(init)).resultsDays; + } catch (error) { + console.error( + `[compute-job] policy read failed: ${error instanceof ComputeApiError ? `${error.kind} ${error.status}` : String(error)}`, + ); + } +} + +const view = outcome.kind === "ok" ? jobDetailView(outcome.read) : null; +const results = + outcome.kind === "ok" + ? resultsPanelView({ + state: outcome.read.job.state, + endedAt: outcome.read.job.ended_at, + resultsDays, + nowMs: nowMs(), + }) + : null; +const source = outcome.kind === "ok" ? outcome.read.job.source : ""; +const L = JOB_COPY; +--- + + +
    +

    {L.back}

    + + {outcome.kind === "not_found" && ( +
    +

    {L.notFoundTitle}

    +

    {L.notFoundBody}

    +
    + )} + + {outcome.kind === "not_available" && ( +
    +

    {L.notAvailableTitle}

    +

    {L.notAvailableBody}

    +
    + )} + + {outcome.kind === "account" && ( +
    +

    {L.pageTitle}

    +

    {COMPUTE_LABELS.access.forbidden}

    + {outcome.sentence &&

    {outcome.sentence}

    } +
    + )} + + {outcome.kind === "failed" && ( + <> +

    {L.pageTitle}

    + + + )} + + {view && results && outcome.kind === "ok" && ( +
    +
    +

    + {L.jobHeading} {view.id} +

    + {view.title &&

    {view.title}

    } +

    + {L.app}: {view.app} {view.appVersion} + {L.frontDoor}: {view.frontDoor} +

    +

    + + + + +

    + + + +

    +
    + + + + + + +
    + {view.rows.map((row) => ( +
    +
    {row.label}
    +
    + {row.time ? : row.value} +
    +
    + ))} +
    +
    {L.rows.charged}
    +
    {view.charge.text}
    +
    +
    +

    {view.unitsNote}

    +
    + + + + + + + + + + + + + + +
    + )} +
    + + + + + diff --git a/test/compute-dashboard-ui.test.ts b/test/compute-dashboard-ui.test.ts index ab37099e..fa7b84d0 100644 --- a/test/compute-dashboard-ui.test.ts +++ b/test/compute-dashboard-ui.test.ts @@ -47,6 +47,18 @@ const ALL_COMPUTE: Record = { ...Object.fromEntries(LIB_FILES), }; +/** The only Compute file that may read the clock: the job page's poller (`test/compute-job-ui.test.ts` pins that nothing else of the job page does). */ +const CLOCK_EXCEPTION = "/src/lib/compute-job-live.ts"; + +/** Files whose purpose is to hold the page's sentences: website-owned wording (website#496). */ +const SENTENCE_FILES = [ + "compute-labels.ts", + "compute-copy.ts", + "compute-failure.ts", + // The one backend sentence transcribed by hand (`upload_expired`), drift-tested. + "compute-contract.ts", +]; + /** Source with comments removed and runs of whitespace collapsed, so a formatter's line breaks do not matter. */ function flat(src: string): string { return src @@ -116,6 +128,9 @@ describe("the page", () => { it("asks for the server's default window and never builds a date from a clock", () => { expect(PAGE).toContain("getComputeUsage(init)"); for (const [name, src] of Object.entries(ALL_COMPUTE)) { + // The one named exception (website#496): the job page's poller holds the timer and reads the + // clock; its schedule is pure and tested with an injected clock (compute-job-view.test.ts). + if (name === CLOCK_EXCEPTION) continue; expect(code(src), name).not.toMatch(/Date\.now\(|new Date\(\)/); } }); @@ -304,7 +319,7 @@ describe("copy", () => { it("types no long sentence at a call site: those live in compute-labels.ts or the copy table", () => { const offenders: string[] = []; for (const [name, src] of Object.entries(ALL_COMPUTE)) { - if (name.endsWith("compute-labels.ts")) continue; + if (SENTENCE_FILES.some((f) => name.endsWith(f))) continue; const stripped = code(src); for (const m of stripped.matchAll(/(["'`])((?:\\.|(?!\1)[^\\\n]){40,})\1/g)) { // A message thrown for a developer (a RangeError) is not text a visitor reads. diff --git a/test/compute-job-ui.test.ts b/test/compute-job-ui.test.ts new file mode 100644 index 00000000..da39dae9 --- /dev/null +++ b/test/compute-job-ui.test.ts @@ -0,0 +1,336 @@ +/** + * Wiring guards for the job page (website ADR 0030 phase E3; epic nemarOrg/website#493, issue #496). + * + * Source-level assertions, like `compute-dashboard-ui.test.ts`: Astro files have no rendering harness in + * this repo, so reading the source is the honest cheap check; the browser check against the real local + * backend covers the rest. The behavior of the pieces has its own tests: `compute-job-view.test.ts`, + * `compute-logs.test.ts`, `compute-failure.test.ts`, `compute-api-job.test.ts`. + */ +import { describe, expect, it } from "vitest"; +import ACTIONS from "../src/components/ComputeJobActions.astro?raw"; +import LOGS from "../src/components/ComputeJobLogs.astro?raw"; +import RESULTS from "../src/components/ComputeJobResults.astro?raw"; +import TIMELINE from "../src/components/ComputeJobTimeline.astro?raw"; +import PAGE from "../src/pages/compute/jobs/[id].astro?raw"; + +const libs = import.meta.glob("/src/lib/compute-*.ts", { + query: "?raw", + import: "default", + eager: true, +}) as Record; + +/** Every file that belongs to the job page. */ +const JOB_LIBS = [ + "compute-job-view.ts", + "compute-job-dom.ts", + "compute-job-live.ts", + "compute-job-page.ts", + "compute-logs.ts", + "compute-failure.ts", + "compute-copy.ts", +]; +const JOB: Record = { + "pages/compute/jobs/[id].astro": PAGE, + "ComputeJobActions.astro": ACTIONS, + "ComputeJobLogs.astro": LOGS, + "ComputeJobResults.astro": RESULTS, + "ComputeJobTimeline.astro": TIMELINE, + ...Object.fromEntries( + JOB_LIBS.map((name) => { + const src = libs[`/src/lib/${name}`]; + if (src === undefined) throw new Error(`${name} is missing`); + return [name, src]; + }), + ), +}; + +function code(src: string): string { + return src + .replace(//g, "") + .replace(/\/\*[\s\S]*?\*\//g, "") + .replace(/(^|[^:])\/\/[^\n]*/g, "$1") + .replace(//g, ""); +} +const flat = (src: string): string => code(src).replace(/\s+/g, " "); + +/** The frontmatter of the page: everything before the closing fence. */ +const FRONTMATTER = PAGE.slice(PAGE.indexOf("---") + 3, PAGE.indexOf("\n---", 4)); +const PAGE_SCRIPT = PAGE.slice(PAGE.indexOf(" & "q" back\\slash', + "x".repeat(5000), + ].join("\n"), + ); + await finish(hostile, uh, { outputs: [], failureCode: "runtime_error" }); + + const big = await make(rich, "big_log"); + const lines = Array.from({ length: 40_000 }, (_, i) => `line ${i + 1} ${"y".repeat(20)}`).join( + "\n", + ); + const ub = await toRunning(big); + fx.tapis.setOutput(ub, "tapisjob.out", lines); + await finish(big, ub, { outputs: [], failureCode: "runtime_error" }); + + const failed = await make(rich, "failed"); + const u2 = await toRunning(failed); + fx.tapis.setOutput( + u2, + "tapisjob.out", + 'Traceback (most recent call last):\n File "main.py", line 3\nZeroDivisionError: division by zero\n', + ); + await finish(failed, u2, { outputs: [], failureCode: "runtime_error" }); + + const many = await make(rich, "many_results"); + const u3 = await toRunning(many); + await finish(many, u3, { + outputs: Array.from({ length: 1002 }, (_, i) => ({ + // `.dat`, not `.txt`: `bun run dev` answers a URL that ends in `.txt` (the cursor of the second page + // is the last path) as a static file lookup and 500s; a deployed build is not known to. + path: `out/file-${String(i).padStart(5, "0")}.dat`, + content: `n${i}\n`, + })), + }); + + for (const [label, daysAgo] of [ + ["expiring", 28], + ["expired", 31], + ]) { + const id = await make(rich, label); + const uuid = await toRunning(id); + await finish(id, uuid, { outputs }); + db.query("UPDATE compute_jobs SET ended_at = datetime('now', ?) WHERE id = ?").run( + `-${daysAgo} days`, + id, + ); + } + + const foreign = await make(frozen, "foreign"); + await toRunning(foreign); + + // A job that advances by itself every 20 s: submitted, queued, running, finished. + const watch = await make(rich, "watch"); + const watchUuid = await submit(watch); + let step = 0; + const timer = setInterval(async () => { + try { + step += 1; + if (step === 1) fx.tapis.advance(watchUuid, "QUEUED"); + if (step === 2) { + fx.tapis.advance(watchUuid, "RUNNING"); + fx.tapis.setOutput(watchUuid, "tapisjob.out", "watch job running\n"); + } + if (step === 3) { + fx.tapis.setOutput(watchUuid, "tapisjob.out", "watch job running\nwatch job done\n"); + await playLauncher(fx, env, await reread(env, watch), watchUuid, { outputs }); + fx.tapis.advance(watchUuid, "FINISHED"); + setTimeout(() => {}, 0); + } + // The backend refreshes a live job from the stand-in at most once a minute per read: age the + // stored read so the next page read picks the change up. + db.query( + "UPDATE compute_jobs SET tapis_synced_at = datetime('now', '-5 minutes') WHERE id = ?", + ).run(watch); + if (step >= 3) clearInterval(timer); + } catch (err) { + console.error(`watch job step failed: ${err instanceof Error ? err.message : err}`); + clearInterval(timer); + } + }, 20_000); + timer.unref?.(); +} +if (SEED_COMPUTE_JOBS) await seedComputeJobs(); + const cookies = {}; for (const p of [...PERSONAS, ...ADMIN_PERSONAS]) cookies[p.who] = await signIn(`${p.who}@nemar.test`); @@ -593,6 +774,9 @@ if (fx) { const outDir = join(import.meta.dir, "..", ".local-backend"); await mkdir(outDir, { recursive: true }); await writeFile(join(outDir, "cookies.json"), `${JSON.stringify(cookies, null, 2)}\n`); +if (SEED_COMPUTE_JOBS) { + await writeFile(join(outDir, "jobs.json"), `${JSON.stringify(seededJobs, null, 2)}\n`); +} console.log(`nemar-cli backend on http://localhost:${PORT} (in-memory database; restart resets)`); console.log(""); @@ -603,6 +787,13 @@ console.log( "Session cookies (paste as `nemar_session` for localhost:4321; also in .local-backend/cookies.json):", ); for (const [who, cookie] of Object.entries(cookies)) console.log(` ${who.padEnd(14)} ${cookie}`); +if (SEED_COMPUTE_JOBS) { + console.log(""); + console.log( + "Job page jobs (also in .local-backend/jobs.json), open /compute/jobs/ as `jobs`:", + ); + for (const [label, id] of Object.entries(seededJobs)) console.log(` ${label.padEnd(14)} ${id}`); +} console.log(""); console.log( "Admin Compute tab: sign in as `owner` or `adminself` (a non-owner administrator whose own", diff --git a/src/components/ComputeJobResults.astro b/src/components/ComputeJobResults.astro index be68b1e6..fad88118 100644 --- a/src/components/ComputeJobResults.astro +++ b/src/components/ComputeJobResults.astro @@ -20,7 +20,7 @@ const L = JOB_COPY.results; ---
    -

    {panel.headline}

    +

    {panel.headline}

    diff --git a/src/lib/compute-copy.ts b/src/lib/compute-copy.ts index 809947d2..dbb2ebb0 100644 --- a/src/lib/compute-copy.ts +++ b/src/lib/compute-copy.ts @@ -101,6 +101,7 @@ export const JOB_COPY = { badState: "NEMAR has no result files for this job.", loading: "Getting the links", yourTime: "your time", + localTime: (when: string) => `In your time zone: ${when}.`, linksExpire: (until: string) => `Links expire ${until}.`, filesCount: (total: number) => `${total.toLocaleString("en-US")} ${total === 1 ? "file" : "files"}`, diff --git a/src/lib/compute-job-page.ts b/src/lib/compute-job-page.ts index a97c458c..61750f7d 100644 --- a/src/lib/compute-job-page.ts +++ b/src/lib/compute-job-page.ts @@ -59,7 +59,7 @@ function addLocalTime(node: HTMLElement): void { const iso = node.dataset.untilIso; const when = iso ? new Date(iso) : null; if (when && !Number.isNaN(when.getTime())) { - node.textContent = `${node.textContent ?? ""} (${JOB_COPY.results.yourTime}: ${when.toLocaleString()})`; + node.textContent = `${node.textContent ?? ""} ${JOB_COPY.results.localTime(when.toLocaleString())}`; } } @@ -160,8 +160,10 @@ export function initJobPage(root: HTMLElement): void { }); const headline = must(root, "[data-results-headline]"); setText(headline, panel.headline); - if (panel.window.untilIso) headline.dataset.untilIso = panel.window.untilIso; - else delete headline.dataset.untilIso; + // The local time is only added where the line names the date (not for a derived "expired"). + if (panel.window.untilIso && panel.window.state !== "expired") { + headline.dataset.untilIso = panel.window.untilIso; + } else delete headline.dataset.untilIso; if (panel.window.untilMs !== null) root.dataset.untilMs = String(panel.window.untilMs); else delete root.dataset.untilMs; addLocalTime(headline); diff --git a/src/pages/compute/jobs/[id].astro b/src/pages/compute/jobs/[id].astro index 9cf8a3c9..837002b1 100644 --- a/src/pages/compute/jobs/[id].astro +++ b/src/pages/compute/jobs/[id].astro @@ -271,6 +271,9 @@ const L = JOB_COPY; .compute-job__signin { color: var(--color-link); font-weight: var(--fw-semibold); + min-block-size: 44px; + display: inline-flex; + align-items: center; } .compute-job__header { display: grid; From 8295d425a977742b8d07386bea0df94488005cbc Mon Sep 17 00:00:00 2001 From: Seyed Yahya Shirazi Date: Sat, 7 Nov 2026 08:58:59 -0800 Subject: [PATCH 11/17] Document the job page --- .../0030-compute-pages-follow-adr-0010-phase-3.md | 15 ++++++++++++++- .context/local-backend.md | 15 +++++++++++++++ AGENTS.md | 5 ++++- CHANGELOG.md | 10 ++++++++++ 4 files changed, 43 insertions(+), 2 deletions(-) diff --git a/.context/decisions/0030-compute-pages-follow-adr-0010-phase-3.md b/.context/decisions/0030-compute-pages-follow-adr-0010-phase-3.md index 675967bc..0940fa79 100644 --- a/.context/decisions/0030-compute-pages-follow-adr-0010-phase-3.md +++ b/.context/decisions/0030-compute-pages-follow-adr-0010-phase-3.md @@ -80,6 +80,19 @@ The captured fixtures in `test/fixtures/compute/` gain a `GET /compute/me` captu - **Shared copy.** Seven keys were added to nemar-cli's contract and transcribed (`compute_page.*`, `compute_access.granted.link`), and `compute_access.granted.body` no longer promises submission from the website: jobs are submitted with the command line. - **Still open from the hand-off above:** replacing `compute-terms.ts` and `COMPUTE_REQUESTS_ENABLED` with `access.current_terms_version` and `access.requests_open` is a follow-up; `/compute` already reads `requests_open` (falling back to `terms_published`) for its own "request" link. +## Addendum: the job page (phase E3, website#496, 2026-11-07) + +`/compute/jobs/` reads `GET /compute/me/jobs/:id` and, on request, the log, the result links and the cancel (nemar-cli Epic D, phase D3). The decisions that are expensive to reverse: + +- **Bearer result links are minted only by a click and live only in the DOM.** The server-rendered page carries no link and calls neither the log nor the results client (a source scan fails the build otherwise). "Get download links" and "Renew links" are the only callers; a link reaches an `href` only through `safeResultHref` (`https:`, or `http:` on loopback for the local backend), with `rel="noopener noreferrer"` and no referrer, and is never written to storage, the URL, the console, an attribute other than `href` or the clipboard. A page restored from the back-forward cache clears the list, and rows are replaced when the links' own expiry passes. The backend's `notice` about keeping them private is shown as served, not retyped. +- **The log is inert text, and hostile characters are shown, not removed.** ANSI formatting is stripped as formatting; everything else goes through `displaySafeBody` (ADR 0029), so a bare carriage return becomes a line break (nothing can be overwritten) and a control, override, isolate or zero-width character is written out (`\x1b`, `\u202e`). A sequence that never ends is not stripped and swallows nothing after it. Lines are capped at 2,000 characters. The backend serves the FIRST 1 MiB with `X-Nemar-Truncated: true`, so a long log shows its beginning and says so (nemar-cli#2094 asks for a tail). The proxy forwards that one header and its constant has one reader. +- **The page claims only what the record carries.** The job has three times (created, started, ended) and no per-stage times (nemar-cli#2097), so the timeline shows a time on three steps and a step it cannot vouch for reads "not known", never "done"; Archiving is never claimed for a failed or canceled job. No sentence says whose fault a failure was (the user view serves no attribution) or promises a refund. The 17 failure codes, the cancel outcomes, the refusal statuses, the header and the bounds are transcribed and drift-tested (`test/compute-job-contract-drift.test.ts`); the wording is website-owned (`compute-copy.ts`, `compute-failure.ts`), and the cancel dialog repeats the CLI's own charge rule. +- **Polling is cheap by construction.** The first read is 10 seconds after load; an unchanged answer doubles the delay to 60 (the backend refreshes a live job from the cluster at most once a minute, so asking faster adds load and no freshness), a change resets it, a fifth error in a row stops it, a hidden tab pauses it and a visible one refreshes at once, an ended or unknown state stops it for good, and it stops after two hours with a Resume button. The schedule is pure (`nextPoll`, an injected clock); `compute-job-live.ts` is the one job module that reads a clock or holds a timer, which `test/compute-dashboard-ui.test.ts` names as its single exception. +- **The retention date is derived until the server states it.** `ended_at` plus `limits.results_days` gives "kept until", with the backend's own strict `now > ended + days` rule; the 410 stays authoritative and the button stays until the backend says so (nemar-cli#2096 asks for the date). A page never promises a charge beyond the dialog's sentence and the refreshed record. +- **One 404, never an oracle.** An absent, foreign or malformed id is one page with status 404 (a malformed id without calling the API), the headers `Cache-Control: private, no-store` and `Referrer-Policy: no-referrer` are set before any return, and `/compute` joins `/oauth` in `routeBypassesEdgeCache`. + +Dev-server note: `bun run dev` answers a URL that ends in `.txt` (here, a results cursor that is a path ending in `.txt`) as a static file lookup and 500s; a deployed build was not tested. The local seed uses `.dat` outputs. + ## Addendum: the dataset page dialog (phase E5, website#498, 2026-11-07) The dataset page's "Compute instructions" dialog now describes `nemar compute` instead of an S3 prefix and a Neuroscience Gateway flow that never shipped. The decisions that are expensive to reverse: @@ -96,5 +109,5 @@ Receipts for this addendum: website#498, #493; nemar-cli#2021, #2024, #2090, #20 ## Receipts -- website#493 (epic), website#494 (phase E1), website#495 (phase E2), website#498 (phase E5); nemar-cli#2021 (Epic D), #2071 (phase D1, commit 3a869903). +- website#493 (epic), website#494 (phase E1), website#495 (phase E2), website#496 (phase E3), website#498 (phase E5); nemar-cli#2094 to #2097; nemar-cli#2021 (Epic D), #2071 (phase D1, commit 3a869903). - ADRs 0006, 0007, 0010, 0014, 0015, 0029; nemar-cli ADRs 0040, 0042, 0118. diff --git a/.context/local-backend.md b/.context/local-backend.md index 03cf6a6e..1246445f 100644 --- a/.context/local-backend.md +++ b/.context/local-backend.md @@ -94,3 +94,18 @@ Worked on 2026-11-07. Differences from production: the compute switch reads `off exact production environment), so Reconciliation shows its paused banner; no mail is sent, so a decision answers `email_sent: false` and the row says the person could not be emailed. Browser windows cannot be narrower than about 600 px in the Chrome tools; check 375 px in devtools. + +## The job page (website#496) + +`--seed-compute-jobs` (with `--seed-compute` and `LOCAL_BACKEND_JOBS=1`) makes the job page's jobs for +the account `localjobs` (sign in with the `jobs` cookie) through the real services and the Tapis +stand-in: a finished job (three outputs, a log), a running one, one to cancel, a failed job with a +hostile log, one with a log over 1 MiB, one with 1,002 outputs (a second page of links), one whose +results expire in two days, one whose results are past the 30 days (the real 410), a running job of +another account (the 404 check) and a job that advances by itself every 20 seconds (queued, running, +finished). Ids are printed and written to `.local-backend/jobs.json`. The seed runs the backend with +`ENVIRONMENT=development` (compute only runs in `production` or `development`); mail stays fenced. +The seed takes about 40 seconds, and the watch job starts advancing when it ends: open it at once. +Result links point at the local object store on `127.0.0.1`, which is why `safeResultHref` accepts +`http:` on loopback. Not reachable here: a `stale: true` job (needs the stand-in down at read time; +covered by the captured fixture) and a real 5xx. diff --git a/AGENTS.md b/AGENTS.md index b76133f2..d52b7b98 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -77,6 +77,7 @@ src/ upload.astro upload/success.astro upload flow (dropzone + BIDS pre-check + full BIDS validation in a worker + direct-to-storage PUTs) settings.astro account: name/email/ORCID/GitHub/profile self-service; CLI keys card; compute access card compute/index.astro compute dashboard (app host, ADR 0030): access, balances, usage chart per pool, jobs with Load more, queue waits; each read and panel fails alone + compute/jobs/[id].astro one compute job (app host, ADR 0030 E3): timeline, resources and charge, failure sentence, log and result links on request (bearer links minted only by a click), cancel; private no-store, one 404 for absent, foreign or malformed ids; the page the results-ready mail links to admin/publication-requests.astro admin-only (role=admin; 404s for others) admin/mail.astro admin/mail/{[id],queues,away}.astro admin Mail tab: tickets, queues, away windows (ADR 0029); email is escaped text only admin/compute.astro admin Compute tab (website#497, ADR 0030): Requests (grant, deny, suspend, revoke by id, each through ComputeDecisionDialog) and read-only Pools, Usage, Flagged jobs, Reconciliation; a section the backend does not serve says so and links its nemar-cli issue; nothing owner-only or cost-bearing is offered @@ -98,6 +99,8 @@ src/ compute-view.ts compute-labels.ts compute-badges.ts pure view models (panelsFor, access, balances, queue, jobRowView, usage), the page's short labels (sentences live in account-copy.ts), job-state badges compute-format.ts compute-chart.ts integer milli-SU formatting (`suFixed`: the CLI's three-decimal digits; `formatSu`: the shortest exact decimal, the same rule as nemar-cli's `formatSu`) and the usage chart geometry (nice ceiling from the stacked total, hand-rolled SVG, ADR 0007) compute-jobs-dom.ts builds appended job rows with createElement/textContent only + compute-job-view.ts compute-logs.ts compute-failure.ts compute-copy.ts the job page's pure modules (E3): timeline, canCancel, retention window, results rows, cancel outcome words and the polling schedule (`nextPoll`, no clock); `prepareLog` (ANSI stripped, hostile characters written out, long lines capped); one sentence per failure code; the website-owned sentences + compute-job-dom.ts compute-job-page.ts compute-job-live.ts the job page's browser side: nodes from the same view models (createElement and textContent only), the controller (poll, log, results, cancel), and the ONE job module that reads a clock or holds a timer compute-admin-api.ts admin Compute client (browser-safe): access list and decisions by id, pools, jobs by flag, unmatched accounting rows, access report, status, the badge count; { error, code } reader, decision failure classes, no POST retry compute-admin-contract.ts hand copy of the closed lists the Compute tab branches on (drift-tested, test/compute-admin-contract-drift.test.ts, strict via NEMAR_CLI_COMPUTE_ADMIN_CONTRACT) compute-admin-view.ts pure view models for the Compute tab: request row, allowed buttons, decision and failure sentences, pool and job rows, parameters, pager @@ -128,7 +131,7 @@ src/ eeg-viewer.css global signal-viewer styles (runtime-built DOM), imported by BidsTree and the embed test/ fixtures/ qa-aggregates, qa-file-dataqual, qa-hed-summary (Phase 3) - fixtures/compute/ captured from the real nemar-cli routes, never hand-written: `NEMAR_CLI_DIR= bun scripts/capture-compute-fixtures.mjs` (access, E1) and `bun scripts/capture-compute-read-fixtures.mjs` (me, usage, jobs, errors; E2); `fixtures/compute/cli-help/` is the real `nemar ... --help-all` text the dialog's commands are checked against: `NEMAR_CLI_DIR= bun scripts/capture-compute-cli-help.mjs` (E5) + fixtures/compute/ captured from the real nemar-cli routes, never hand-written: `NEMAR_CLI_DIR= bun scripts/capture-compute-fixtures.mjs` (access, E1), `bun scripts/capture-compute-read-fixtures.mjs` (me, usage, jobs, errors; E2) and `bun scripts/capture-compute-job-fixtures.mjs` (job, log, results, cancel, refusals; E3, on the backend's lifecycle fixture and Tapis stand-in); `fixtures/compute/cli-help/` is the real `nemar ... --help-all` text the dialog's commands are checked against: `NEMAR_CLI_DIR= bun scripts/capture-compute-cli-help.mjs` (E5) public/ static logos + brain hero assets (og/ cards are generated, gitignored) public/brand/ GENERATED press logo kit (SVG, PDF, transparent PNG; color, reverse, black, white); rebuild with `bun scripts/generate-brand-kit.mjs`, never hand-edit public/vendor/bids-validator// GENERATED worker bundle of the BIDS validator + SHA256SUMS + provenance + licenses (ADR 0028); never hand-edited diff --git a/CHANGELOG.md b/CHANGELOG.md index 457d6749..3760a346 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,16 @@ The release pull request from `staging` to `main` moves those entries under the ### Added +- **The compute job page** (website#496, epic website#493 phase E3; nemar-cli epic #2021 phase D3, website ADR 0030 addendum). + `/compute/jobs/` shows one job: its state on a timeline that claims only what the record carries (three times), its resources and charge (the same three-decimal digits as `nemar compute status`), a plain sentence for each of the 17 failure codes, its log on request, its result links on request (renewable), and a cancel for a live job. + A live job refreshes itself every 10 seconds, backing off to 60 while nothing changes, pausing in a hidden tab and stopping at an ended state. + The log is shown as inert text with hostile characters written out (`\x1b`, `\u202e`) rather than silently dropped; a log cut at 1 MiB says so and points at `nemar compute logs` (the end of a long log cannot be read yet: nemar-cli#2094). + Result links are bearer links: viewing the page mints none, only the button does, and they are never stored, logged or copied. + The page is the one the "results ready" email links to, answers the same 404 for an absent, foreign or malformed id, and is never edge-cached (`/compute` joins `/oauth` in `routeBypassesEdgeCache`). + The API proxy forwards one more response header, `X-Nemar-Truncated`. + Backend gaps filed: nemar-cli#2094 (log tail), #2095 (links as attachments), #2096 (state when results are deleted), #2097 (per-stage times). + `scripts/capture-compute-job-fixtures.mjs` captures nine fixture files from the real router, and `scripts/local-backend.mjs --seed-compute-jobs` seeds jobs through the real services and the Tapis stand-in. + - **The `/compute` dashboard** (website#495, epic website#493 phase E2; nemar-cli epic #2021 phase D2, website ADR 0030 addendum). A signed-in person sees their compute access, CPU and GPU balances (granted, held, charged, available, in the same three-decimal service units `nemar compute balance` prints), a daily usage chart per pool stacked by partition (hand-rolled SVG, themed by new `--chart-*` tokens, with the numbers in a table beside it), their jobs from every front door with "Load more", and the platform's recent queue waits ("Not enough data" with the count when fewer than five jobs started). A person without active access sees why and how to ask, not an error; a suspended or ended account keeps its history read-only; one failed read shows one notice that says the figures are missing, not zero. From b1e3cf967c37d883c7d8ba48d641211af8c1eb23 Mon Sep 17 00:00:00 2001 From: Seyed Yahya Shirazi Date: Sat, 7 Nov 2026 09:12:22 -0800 Subject: [PATCH 12/17] Give job read and cancel longer deadlines --- src/lib/compute-api-job.test.ts | 64 ++++++++++++++++++++++++++++++++- src/lib/compute-api.ts | 29 +++++++++++++-- 2 files changed, 89 insertions(+), 4 deletions(-) diff --git a/src/lib/compute-api-job.test.ts b/src/lib/compute-api-job.test.ts index 9415941d..cf96a411 100644 --- a/src/lib/compute-api-job.test.ts +++ b/src/lib/compute-api-job.test.ts @@ -8,7 +8,7 @@ * Transport conditions no route can be made to produce (a 502 with no JSON, a refused connection) use a * real `Response`, as the repo's rule allows for failure paths. */ -import { describe, expect, it } from "vitest"; +import { afterEach, describe, expect, it, vi } from "vitest"; import cancel from "../../test/fixtures/compute/cancel.json"; import errorsJob from "../../test/fixtures/compute/errors-job.json"; import jobCancelRequested from "../../test/fixtures/compute/job-cancel-requested.json"; @@ -20,6 +20,9 @@ import logs from "../../test/fixtures/compute/logs.json"; import meActive from "../../test/fixtures/compute/me-active-with-usage.json"; import results from "../../test/fixtures/compute/results.json"; import { + COMPUTE_CANCEL_TIMEOUT_MS, + COMPUTE_JOB_READ_TIMEOUT_MS, + COMPUTE_LOG_TIMEOUT_MS, ComputeApiError, cancelComputeJob, getComputeJob, @@ -470,3 +473,62 @@ describe("the retention policy in GET /compute/me", () => { expect(() => parseComputeMe(body)).toThrow(ComputeApiError); }); }); + +// The suite above proves the calls work, not which deadline each one carries. A job read can wait on the +// backend's cluster read (about 8 s) and a cancel on the cancel plus its read-back, so the 5 s default +// would show a false error for a slow cluster. Spy on the static with no override so the fallback is +// observable. +describe("deadlines", () => { + afterEach(() => { + vi.restoreAllMocks(); + }); + + it("names deadlines longer than the backend work behind them", () => { + expect(COMPUTE_JOB_READ_TIMEOUT_MS).toBeGreaterThan(8_000); + expect(COMPUTE_CANCEL_TIMEOUT_MS).toBeGreaterThan(COMPUTE_JOB_READ_TIMEOUT_MS); + expect(COMPUTE_LOG_TIMEOUT_MS).toBeGreaterThan(COMPUTE_JOB_READ_TIMEOUT_MS); + }); + + it("gives the job read the job-read deadline", async () => { + const spy = vi.spyOn(AbortSignal, "timeout"); + await getComputeJob(JOB_ID, { fetch: answering(json(jobStates.running.body)).fn }); + expect(spy).toHaveBeenCalledWith(COMPUTE_JOB_READ_TIMEOUT_MS); + }); + + it("gives the cancel the cancel deadline", async () => { + const spy = vi.spyOn(AbortSignal, "timeout"); + await cancelComputeJob(JOB_ID, { fetch: answering(json(cancel.running.body)).fn }); + expect(spy).toHaveBeenCalledWith(COMPUTE_CANCEL_TIMEOUT_MS); + }); + + it("gives the log read the log deadline", async () => { + const spy = vi.spyOn(AbortSignal, "timeout"); + await getComputeLogs(JOB_ID, { fetch: answering(new Response("a")).fn }); + expect(spy).toHaveBeenCalledWith(COMPUTE_LOG_TIMEOUT_MS); + }); + + it("lets a slow cluster answer: a read that takes longer than 5 s still gets the stale record", async () => { + // The caller's deadline is the named one, not the 5 s default: a fetch that checks its own signal + // at the default's length sees it still open. + const timeouts: number[] = []; + const real = AbortSignal.timeout.bind(AbortSignal); + vi.spyOn(AbortSignal, "timeout").mockImplementation((ms: number) => { + timeouts.push(ms); + return real(ms); + }); + const read = await getComputeJob(JOB_ID, { + fetch: answering(json(jobStale.submitted.body)).fn, + }); + expect(read.stale).toBe(true); + expect(Math.max(...timeouts)).toBeGreaterThan(5_000); + }); + + it("an explicit timeoutMs from the caller still wins", async () => { + const spy = vi.spyOn(AbortSignal, "timeout"); + await getComputeJob(JOB_ID, { + fetch: answering(json(jobStates.running.body)).fn, + timeoutMs: 1_234, + }); + expect(spy).toHaveBeenCalledWith(1_234); + }); +}); diff --git a/src/lib/compute-api.ts b/src/lib/compute-api.ts index 3630456f..cfb16eef 100644 --- a/src/lib/compute-api.ts +++ b/src/lib/compute-api.ts @@ -532,9 +532,10 @@ async function computeGet( query: URLSearchParams, init: ComputeInit, parse: (body: unknown) => T, + defaultTimeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS, ): Promise { return readJson( - await computeRequest("GET", path, query, init, "application/json", DEFAULT_REQUEST_TIMEOUT_MS), + await computeRequest("GET", path, query, init, "application/json", defaultTimeoutMs), parse, ); } @@ -559,9 +560,10 @@ async function computePost( query: URLSearchParams, init: ComputeInit, parse: (body: unknown) => T, + defaultTimeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS, ): Promise { return readJson( - await computeRequest("POST", path, query, init, "application/json", DEFAULT_REQUEST_TIMEOUT_MS), + await computeRequest("POST", path, query, init, "application/json", defaultTimeoutMs), parse, ); } @@ -609,6 +611,20 @@ export function listComputeJobs( /** The longest the log read waits: the backend may read the cluster for several seconds first. */ export const COMPUTE_LOG_TIMEOUT_MS = 30_000; +/** + * The longest a job read waits. A live job older than a minute is read back from the cluster first + * (the backend's read is bounded at about 8 s), so the 5 s default would turn a slow cluster into a + * false error instead of the stored record with `stale: true`. + */ +export const COMPUTE_JOB_READ_TIMEOUT_MS = 12_000; + +/** + * The longest a cancel waits. The backend carries the cancel out at the cluster and reads the job back + * before it answers, so a slow cluster must still end in the cancel's own outcome, not in a timeout the + * page reads as "could not tell". + */ +export const COMPUTE_CANCEL_TIMEOUT_MS = 20_000; + function jobPath(id: string, rest: string): string { // The id goes into a URL path: nothing that is not a job id may. if (!COMPUTE_JOB_ID_RE.test(id)) @@ -618,7 +634,13 @@ function jobPath(id: string, rest: string): string { /** One of the caller's jobs; `stale` says the cluster could not be asked and the stored record is shown. */ export function getComputeJob(id: string, init: ComputeInit = {}): Promise { - return computeGet(jobPath(id, "me/jobs/:id"), new URLSearchParams(), init, parseComputeJob); + return computeGet( + jobPath(id, "me/jobs/:id"), + new URLSearchParams(), + init, + parseComputeJob, + COMPUTE_JOB_READ_TIMEOUT_MS, + ); } /** @@ -679,5 +701,6 @@ export function cancelComputeJob(id: string, init: ComputeInit = {}): Promise Date: Sat, 7 Nov 2026 09:14:09 -0800 Subject: [PATCH 13/17] Test the held result links as a pure state --- src/lib/compute-copy.ts | 2 + src/lib/compute-job-page.ts | 152 +++++++++------------- src/lib/compute-job-results-state.test.ts | 138 ++++++++++++++++++++ src/lib/compute-job-results-state.ts | 125 ++++++++++++++++++ src/lib/compute-job-view.test.ts | 7 + src/lib/compute-job-view.ts | 13 +- test/compute-job-ui.test.ts | 5 +- 7 files changed, 347 insertions(+), 95 deletions(-) create mode 100644 src/lib/compute-job-results-state.test.ts create mode 100644 src/lib/compute-job-results-state.ts diff --git a/src/lib/compute-copy.ts b/src/lib/compute-copy.ts index dbb2ebb0..73a86e44 100644 --- a/src/lib/compute-copy.ts +++ b/src/lib/compute-copy.ts @@ -99,6 +99,8 @@ export const JOB_COPY = { expired410: (days: number | null) => `The results of this job were deleted${days === null ? "" : ` after ${days} ${days === 1 ? "day" : "days"}`}. This page keeps the job's record (state, resources and charge) and its log.`, badState: "NEMAR has no result files for this job.", + badStatePartner: + "NEMAR has no result files for this job yet. A partner job's results appear once NEMAR has checked the job.", loading: "Getting the links", yourTime: "your time", localTime: (when: string) => `In your time zone: ${when}.`, diff --git a/src/lib/compute-job-page.ts b/src/lib/compute-job-page.ts index 61750f7d..7213d0a4 100644 --- a/src/lib/compute-job-page.ts +++ b/src/lib/compute-job-page.ts @@ -15,7 +15,6 @@ import { ComputeApiError, type ComputeJobRead, - type ComputeResults, cancelComputeJob, getComputeJob, getComputeLogs, @@ -27,16 +26,23 @@ import { JOB_COPY } from "./compute-copy"; import { detailRows, el, failureNodes, resultRowElement, timelineItems } from "./compute-job-dom"; import { createPoller, nowMs } from "./compute-job-live"; import { - RESULT_ROWS_STEP, - type ResultRow, + EMPTY_HOLD, + type ResultsHold, + expireIfDue, + handlePageshow, + holdPage, + markGone, + resultsUi, + setStatus, + showMore, +} from "./compute-job-results-state"; +import { cancelOutcome, jobDetailView, - linksExpired, linksOutliveFiles, logFailure, resultRow, resultsFailure, - resultsPaging, resultsPanelView, } from "./compute-job-view"; import { badgeElement } from "./compute-jobs-dom"; @@ -167,9 +173,9 @@ export function initJobPage(root: HTMLElement): void { if (panel.window.untilMs !== null) root.dataset.untilMs = String(panel.window.untilMs); else delete root.dataset.untilMs; addLocalTime(headline); - // Do not offer the button again once a 410 settled it. - must(root, "[data-results-get]").hidden = - !panel.canGetLinks || resultsGone || heldResults !== null; + // Derived from the job, never from what the panel showed last: a restored page needs it back. + canGetLinks = panel.canGetLinks; + renderResults(); } // --- the poller ---------------------------------------------------------------------------------- @@ -316,79 +322,50 @@ export function initJobPage(root: HTMLElement): void { const resultsNext = must(root, "[data-results-next]"); const resultsFirst = must(root, "[data-results-first]"); const resultsRenew = must(root, "[data-results-renew]"); - let heldResults: { rows: ResultRow[]; response: ComputeResults } | null = null; - let resultsShown = RESULT_ROWS_STEP; - let resultsOffset = 0; - let resultsAfter: string | null = null; - let resultsGone = false; + let hold: ResultsHold = EMPTY_HOLD; + let canGetLinks = !resultsGet.hidden; let resultsBusy = false; - function clearResults(): void { - heldResults = null; - resultsList.replaceChildren(); - resultsPanel.hidden = true; - if (current) void renderResultsPanel(current); - } - + /** The one place the results panel is written: from the hold and from what the JOB allows. */ function renderResults(): void { - if (heldResults === null) return; - const { rows, response } = heldResults; - resultsPanel.hidden = false; - resultsGet.hidden = true; + const ui = resultsUi(hold, canGetLinks); + resultsGet.hidden = ui.getHidden; + resultsPanel.hidden = ui.panelHidden; const words = { download: JOB_COPY.results.download, unavailable: JOB_COPY.results.unavailableLink, sha: JOB_COPY.results.sha, }; - resultsList.replaceChildren( - ...rows.slice(0, resultsShown).map((r) => resultRowElement(doc, r, words)), - ); - const from = resultsOffset + 1; - const to = resultsOffset + rows.length; + resultsList.replaceChildren(...ui.visibleRows.map((r) => resultRowElement(doc, r, words))); + resultsStatus.hidden = ui.status === null; + setText(resultsStatus, ui.status ?? ""); + const held = hold.held; + if (held === null) return; + const from = hold.offset + 1; + const to = hold.offset + held.rows.length; setText( resultsSummary, - response.truncated || resultsOffset > 0 - ? JOB_COPY.results.showingRange(from, to, response.total) - : JOB_COPY.results.filesCount(response.total), + held.response.truncated || hold.offset > 0 + ? JOB_COPY.results.showingRange(from, to, held.response.total) + : JOB_COPY.results.filesCount(held.response.total), ); - setText(resultsNotice, response.notice); - const until = new Date(response.expires_at); + setText(resultsNotice, held.response.notice); + const until = new Date(held.response.expires_at); const when = Number.isNaN(until.getTime()) - ? response.expires_at + ? held.response.expires_at : `${until.toISOString().slice(0, 16).replace("T", " ")} UTC (${JOB_COPY.results.yourTime}: ${until.toLocaleString()})`; setText(resultsExpiry, JOB_COPY.results.linksExpire(when)); const untilMs = Number(root.dataset.untilMs ?? ""); resultsOutlive.hidden = !linksOutliveFiles( - response.expires_at, + held.response.expires_at, Number.isNaN(untilMs) ? null : untilMs, ); - const paging = resultsPaging({ - held: rows.length, - shown: Math.min(resultsShown, rows.length), - offset: resultsOffset, - total: response.total, - nextAfter: response.next_after, - }); - resultsMore.hidden = paging.showMore === 0; - setText(resultsMore, JOB_COPY.results.showMore(paging.showMore)); - resultsNext.hidden = paging.nextPageRemaining === null; - if (paging.nextPageRemaining !== null) { - setText(resultsNext, JOB_COPY.results.nextPage(paging.nextPageRemaining)); - } - resultsFirst.hidden = resultsOffset === 0; - } - - /** Replace the rows with a notice when the links' own expiry has passed: no stale link stays in the DOM. */ - function expireLinksIfDue(): void { - if (heldResults === null) return; - if (!linksExpired(heldResults.response.expires_at, nowMs())) return; - heldResults = null; - resultsList.replaceChildren(); - resultsMore.hidden = true; - resultsNext.hidden = true; - resultsFirst.hidden = true; - setText(resultsStatus, JOB_COPY.results.linksExpired); - resultsStatus.hidden = false; + resultsMore.hidden = ui.moreCount === 0; + setText(resultsMore, JOB_COPY.results.showMore(ui.moreCount)); + resultsNext.hidden = ui.nextRemaining === null; + if (ui.nextRemaining !== null) + setText(resultsNext, JOB_COPY.results.nextPage(ui.nextRemaining)); + resultsFirst.hidden = ui.firstHidden; } async function fetchResults(after: string | null, renew: boolean, offset: number): Promise { @@ -397,29 +374,18 @@ export function initJobPage(root: HTMLElement): void { for (const b of [resultsGet, resultsRenew, resultsNext, resultsFirst, resultsMore]) { b.disabled = true; } - resultsStatus.hidden = false; - setText(resultsStatus, JOB_COPY.results.loading); + hold = setStatus(hold, JOB_COPY.results.loading); + renderResults(); try { const response = renew ? await renewComputeResults(jobId, after) : await getComputeResults(jobId, after); - heldResults = { rows: response.files.map(resultRow), response }; - resultsAfter = after; - resultsOffset = offset; - resultsShown = RESULT_ROWS_STEP; - resultsStatus.hidden = true; - setText(resultsStatus, ""); - renderResults(); + hold = holdPage(hold, { rows: response.files.map(resultRow), response }, after, offset); } catch (err) { - const failure = resultsFailure(err, resultsDays); - setText(resultsStatus, failure.sentence); - if (failure.kind === "expired") { - resultsGone = true; - heldResults = null; - resultsPanel.hidden = true; - resultsGet.hidden = true; - } - if (failure.kind === "not_ready") resultsGet.hidden = true; + const failure = resultsFailure(err, resultsDays, source); + hold = setStatus(hold, failure.sentence); + if (failure.kind === "expired") hold = markGone(hold, failure.sentence); + if (failure.kind === "not_ready") canGetLinks = false; if (failure.kind === "not_found") onNotFound(); } finally { resultsBusy = false; @@ -427,31 +393,33 @@ export function initJobPage(root: HTMLElement): void { b.disabled = false; } } + renderResults(); } resultsGet.addEventListener("click", () => void fetchResults(null, false, 0)); resultsRenew.addEventListener("click", () => { - expireLinksIfDue(); - void fetchResults(resultsAfter, true, resultsOffset); + hold = expireIfDue(hold, nowMs()); + renderResults(); + void fetchResults(hold.after, true, hold.offset); }); resultsMore.addEventListener("click", () => { - resultsShown += RESULT_ROWS_STEP; + hold = showMore(hold); renderResults(); }); resultsNext.addEventListener("click", () => { - const next = heldResults?.response.next_after ?? null; - if (next === null || heldResults === null) return; - void fetchResults(next, false, resultsOffset + heldResults.rows.length); + const held = hold.held; + if (held === null || held.response.next_after === null) return; + void fetchResults(held.response.next_after, false, hold.offset + held.rows.length); }); resultsFirst.addEventListener("click", () => void fetchResults(null, false, 0)); doc.addEventListener("visibilitychange", () => { - if (!doc.hidden) expireLinksIfDue(); + if (doc.hidden) return; + hold = expireIfDue(hold, nowMs()); + renderResults(); }); // A page restored from the back-forward cache must not bring bearer links back. window.addEventListener("pageshow", (event) => { - if (event.persisted) { - resultsStatus.hidden = true; - clearResults(); - } + hold = handlePageshow(hold, event.persisted); + renderResults(); }); // --- cancel -------------------------------------------------------------------------------------- diff --git a/src/lib/compute-job-results-state.test.ts b/src/lib/compute-job-results-state.test.ts new file mode 100644 index 00000000..457b62fc --- /dev/null +++ b/src/lib/compute-job-results-state.test.ts @@ -0,0 +1,138 @@ +/** + * What the job page holds of the result links, and when it must let go (phase E3, website#496). The + * links are the real ones the backend minted (`test/fixtures/compute/results.json`). These are the rules + * a security review asked to be tested rather than read: nothing stale stays after the links expire, + * nothing comes back from the back-forward cache, and the button returns after a restore. + */ +import { describe, expect, it } from "vitest"; +import results from "../../test/fixtures/compute/results.json"; +import { parseComputeResults } from "./compute-api"; +import { + EMPTY_HOLD, + type ResultsHold, + expireIfDue, + handlePageshow, + holdPage, + markGone, + resultsUi, + setStatus, + showMore, +} from "./compute-job-results-state"; +import { RESULT_ROWS_STEP, resultRow } from "./compute-job-view"; + +const response = parseComputeResults(results.get.body); +const expiresMs = Date.parse(response.expires_at); +const held = { rows: response.files.map(resultRow), response }; +const withLinks = (): ResultsHold => holdPage(EMPTY_HOLD, held, null, 0); + +describe("holding a page", () => { + it("shows the panel and the rows, and hides the get button", () => { + const ui = resultsUi(withLinks(), true); + expect(ui.panelHidden).toBe(false); + expect(ui.getHidden).toBe(true); + expect(ui.visibleRows.length).toBe(3); + expect(ui.visibleRows.every((r) => r.href !== null)).toBe(true); + }); + + it("shows the get button and no panel when nothing is held", () => { + const ui = resultsUi(EMPTY_HOLD, true); + expect([ui.panelHidden, ui.getHidden, ui.visibleRows.length]).toEqual([true, false, 0]); + }); + + it("never offers the get button for a job that cannot have results", () => { + expect(resultsUi(EMPTY_HOLD, false).getHidden).toBe(true); + }); + + it("shows 100 rows at first and adds 100 a press", () => { + const rows = Array.from({ length: 250 }, (_, i) => ({ ...held.rows[0], path: `f${i}` })); + let hold = holdPage(EMPTY_HOLD, { rows, response: { ...response, total: 250 } }, null, 0); + expect(resultsUi(hold, true).visibleRows.length).toBe(RESULT_ROWS_STEP); + expect(resultsUi(hold, true).moreCount).toBe(100); + hold = showMore(showMore(hold)); + const ui = resultsUi(hold, true); + expect([ui.visibleRows.length, ui.moreCount]).toEqual([250, 0]); + }); +}); + +describe("expiry of the links", () => { + it("keeps the links while they are alive, up to and including the instant", () => { + const hold = withLinks(); + expect(expireIfDue(hold, expiresMs - 1)).toBe(hold); + // `linksExpired` counts the instant itself as expired: a link is not kept to its last moment. + expect(expireIfDue(hold, expiresMs).held?.rows.length).toBe(0); + }); + + it("drops every row after expires_at, says so, and keeps Renew's place", () => { + const hold = holdPage(EMPTY_HOLD, held, "out/x", 1000); + const after = expireIfDue(hold, expiresMs + 1); + const ui = resultsUi(after, true); + expect(ui.visibleRows).toEqual([]); + expect(ui.status).toBe("These links have expired. Renew them."); + // The panel stays (its Renew button is in it) and the position is kept. + expect(ui.panelHidden).toBe(false); + expect([after.after, after.offset]).toEqual(["out/x", 1000]); + // No link survives in memory either. + expect(JSON.stringify(after)).not.toContain("X-Amz"); + expect(after.held?.response.files).toEqual([]); + }); + + it("does nothing when nothing is held, or the rows are already gone", () => { + expect(expireIfDue(EMPTY_HOLD, expiresMs + 1)).toBe(EMPTY_HOLD); + const gone = expireIfDue(withLinks(), expiresMs + 1); + expect(expireIfDue(gone, expiresMs + 99)).toBe(gone); + }); + + it("treats a links date it cannot read as expired", () => { + const bad = holdPage( + EMPTY_HOLD, + { rows: held.rows, response: { ...response, expires_at: "garbage" } }, + null, + 0, + ); + expect(expireIfDue(bad, 0).held?.rows.length).toBe(0); + }); +}); + +describe("a page restored from the back-forward cache", () => { + it("drops every held link, the status and the position, and brings the button back", () => { + const shown = setStatus(holdPage(EMPTY_HOLD, held, "cursor", 1000), "Getting the links"); + expect(resultsUi(shown, true).getHidden).toBe(true); + const restored = handlePageshow(shown, true); + const ui = resultsUi(restored, true); + expect(ui.visibleRows).toEqual([]); + expect(ui.panelHidden).toBe(true); + expect(ui.status).toBeNull(); + // The regression: the button must come back for a finished job, derived from the job's own state. + expect(ui.getHidden).toBe(false); + expect([restored.held, restored.after, restored.offset]).toEqual([null, null, 0]); + expect(JSON.stringify(restored)).not.toContain("X-Amz"); + }); + + it("leaves an ordinary pageshow alone", () => { + const hold = withLinks(); + expect(handlePageshow(hold, false)).toBe(hold); + }); + + it("does not bring the button back after the backend said 410", () => { + const gone = markGone(withLinks(), "The results of this job were deleted."); + const restored = handlePageshow(gone, true); + expect(resultsUi(restored, true).getHidden).toBe(true); + }); + + it("does not bring the button back for a job that cannot have results", () => { + expect(resultsUi(handlePageshow(withLinks(), true), false).getHidden).toBe(true); + }); +}); + +describe("410", () => { + it("drops the links, keeps the sentence and removes the button for good", () => { + const gone = markGone(withLinks(), "deleted"); + const ui = resultsUi(gone, true); + expect([ui.panelHidden, ui.getHidden, ui.status, ui.visibleRows.length]).toEqual([ + true, + true, + "deleted", + 0, + ]); + }); +}); diff --git a/src/lib/compute-job-results-state.ts b/src/lib/compute-job-results-state.ts new file mode 100644 index 00000000..91b7cc21 --- /dev/null +++ b/src/lib/compute-job-results-state.ts @@ -0,0 +1,125 @@ +/** + * The result links a job page holds, as a pure state machine (website ADR 0030 phase E3, issue #496). + * + * The links are seven-day BEARER links, so what the page may hold, and when it must let go, is the + * security-relevant part of the results panel. It lives here, not in the DOM controller, so that it is + * tested: the controller (`compute-job-page.ts`) only calls these functions and renders what + * `resultsUi` says. Nothing here reads a clock (`nowMs` is an argument) or touches the DOM. + * + * - `holdPage`: a minted page is held, from the first row, at an offset in the whole list. + * - `expireIfDue`: once the links' own `expires_at` has passed the rows are DROPPED (no stale link + * stays in memory or in the page) and the panel says so; the cursor and offset stay, so Renew still + * renews the page that was shown. + * - `handlePageshow`: a page restored from the back-forward cache drops every held link and every + * status, and the "Get download links" button comes back (it is derived from the job, not from + * whatever the page last showed). + * - `markGone`: the backend said 410; the button never returns. + */ +import type { ComputeResults } from "./compute-api"; +import { JOB_COPY } from "./compute-copy"; +import { RESULT_ROWS_STEP, type ResultRow, linksExpired, resultsPaging } from "./compute-job-view"; + +export interface HeldResults { + readonly rows: readonly ResultRow[]; + readonly response: ComputeResults; +} + +export interface ResultsHold { + readonly held: HeldResults | null; + /** Rows of the held page that are visible. */ + readonly shown: number; + /** Where the held page starts in the whole list (0 for the first page). */ + readonly offset: number; + /** The cursor the held page was fetched with (null for the first page). */ + readonly after: string | null; + /** The backend answered 410: the results are gone and no button comes back. */ + readonly gone: boolean; + /** The one status line of the panel; null for none. */ + readonly status: string | null; +} + +export const EMPTY_HOLD: ResultsHold = { + held: null, + shown: RESULT_ROWS_STEP, + offset: 0, + after: null, + gone: false, + status: null, +}; + +export function holdPage( + hold: ResultsHold, + held: HeldResults, + after: string | null, + offset: number, +): ResultsHold { + return { ...hold, held, after, offset, shown: RESULT_ROWS_STEP, status: null }; +} + +export function setStatus(hold: ResultsHold, status: string | null): ResultsHold { + return { ...hold, status }; +} + +export function showMore(hold: ResultsHold): ResultsHold { + return { ...hold, shown: hold.shown + RESULT_ROWS_STEP }; +} + +/** The backend said the results are gone: drop everything held and never offer the button again. */ +export function markGone(hold: ResultsHold, status: string): ResultsHold { + return { ...hold, held: null, gone: true, status }; +} + +/** + * Drop the rows once the links have expired, keeping the page's position so Renew still works. A hold + * with nothing held, or links still alive, is returned unchanged. + */ +export function expireIfDue(hold: ResultsHold, nowMs: number): ResultsHold { + if (hold.held === null || hold.held.rows.length === 0) return hold; + if (!linksExpired(hold.held.response.expires_at, nowMs)) return hold; + return { + ...hold, + held: { rows: [], response: { ...hold.held.response, files: [] } }, + status: JOB_COPY.results.linksExpired, + }; +} + +/** A page restored from the back-forward cache must not bring bearer links, or a stale status, back. */ +export function handlePageshow(hold: ResultsHold, persisted: boolean): ResultsHold { + if (!persisted) return hold; + return { ...hold, held: null, status: null, shown: RESULT_ROWS_STEP, offset: 0, after: null }; +} + +export interface ResultsUi { + readonly panelHidden: boolean; + /** "Get download links": back whenever the job can have results, nothing is held and 410 did not say gone. */ + readonly getHidden: boolean; + readonly visibleRows: readonly ResultRow[]; + readonly status: string | null; + readonly moreCount: number; + readonly nextRemaining: number | null; + readonly firstHidden: boolean; +} + +/** What the results panel shows for a hold. `canGetLinks` comes from the JOB, never from what was shown last. */ +export function resultsUi(hold: ResultsHold, canGetLinks: boolean): ResultsUi { + const held = hold.held; + const paging = + held === null + ? { showMore: 0, nextPageRemaining: null } + : resultsPaging({ + held: held.rows.length, + shown: Math.min(hold.shown, held.rows.length), + offset: hold.offset, + total: held.response.total, + nextAfter: held.response.next_after, + }); + return { + panelHidden: held === null, + getHidden: !canGetLinks || hold.gone || held !== null, + visibleRows: held === null ? [] : held.rows.slice(0, hold.shown), + status: hold.status, + moreCount: paging.showMore, + nextRemaining: paging.nextPageRemaining, + firstHidden: hold.offset === 0, + }; +} diff --git a/src/lib/compute-job-view.test.ts b/src/lib/compute-job-view.test.ts index 438b4cf4..780c5156 100644 --- a/src/lib/compute-job-view.test.ts +++ b/src/lib/compute-job-view.test.ts @@ -375,6 +375,13 @@ describe("resultsFailure and logFailure", () => { "deleted.", ); expect(resultsFailure(err("rejected", 409, "bad_state"), 30).kind).toBe("not_ready"); + expect(resultsFailure(err("rejected", 409, "bad_state"), 30, "cli").sentence).toBe( + "NEMAR has no result files for this job.", + ); + // A partner job's files are the person's only once NEMAR has checked it, as for the log. + expect(resultsFailure(err("rejected", 409, "bad_state"), 30, "partner").sentence).toMatch( + /appear once NEMAR has checked the job/, + ); }); it("maps a 404 job_not_found to not-found and a bare 404 to a message", () => { diff --git a/src/lib/compute-job-view.ts b/src/lib/compute-job-view.ts index 7f453e7e..2eb24de4 100644 --- a/src/lib/compute-job-view.ts +++ b/src/lib/compute-job-view.ts @@ -418,12 +418,21 @@ function transport(err: unknown): FailureNotice { } /** What the results panel says for a failed links call. A 410 is the expired state; a 409 means no files. */ -export function resultsFailure(err: unknown, resultsDays: number | null): FailureNotice { +export function resultsFailure( + err: unknown, + resultsDays: number | null, + source = "", +): FailureNotice { if (err instanceof ComputeApiError) { if (err.code === "results_expired") { return { kind: "expired", sentence: JOB_COPY.results.expired410(resultsDays) }; } - if (err.code === "bad_state") return { kind: "not_ready", sentence: JOB_COPY.results.badState }; + if (err.code === "bad_state") { + // A partner job's files are the person's only once NEMAR has checked the job; say so, as the log does. + const sentence = + source === "partner" ? JOB_COPY.results.badStatePartner : JOB_COPY.results.badState; + return { kind: "not_ready", sentence }; + } } return transport(err); } diff --git a/test/compute-job-ui.test.ts b/test/compute-job-ui.test.ts index da39dae9..378062b1 100644 --- a/test/compute-job-ui.test.ts +++ b/test/compute-job-ui.test.ts @@ -25,6 +25,7 @@ const JOB_LIBS = [ "compute-job-dom.ts", "compute-job-live.ts", "compute-job-page.ts", + "compute-job-results-state.ts", "compute-logs.ts", "compute-failure.ts", "compute-copy.ts", @@ -165,8 +166,10 @@ describe("result links are bearer links", () => { }); it("clears the list when a page comes back from the back-forward cache", () => { + // The rule itself is tested behaviorally (compute-job-results-state.test.ts); here only that the + // listener calls it with the event's own flag. expect(flat(JOB["compute-job-page.ts"])).toMatch( - /"pageshow", \(event\) => \{ if \(event\.persisted\)/, + /"pageshow", \(event\) => \{ hold = handlePageshow\(hold, event\.persisted\);/, ); }); From 3ad52e786292e61ef376e6df50b9af4ded76730e Mon Sep 17 00:00:00 2001 From: Seyed Yahya Shirazi Date: Sat, 7 Nov 2026 09:16:45 -0800 Subject: [PATCH 14/17] Write out direction marks in job logs --- src/lib/compute-logs.test.ts | 6 ++++++ src/lib/compute-logs.ts | 7 ++++--- src/lib/mail-display.test.ts | 9 +++++++++ src/lib/mail-display.ts | 11 ++++++++--- 4 files changed, 27 insertions(+), 6 deletions(-) diff --git a/src/lib/compute-logs.test.ts b/src/lib/compute-logs.test.ts index 6564d9fd..751237b1 100644 --- a/src/lib/compute-logs.test.ts +++ b/src/lib/compute-logs.test.ts @@ -80,6 +80,12 @@ describe("prepareLog", () => { expect(lines).toEqual(["a\\u202eb\\u2066c\\u2069d\\u200be"]); }); + it("writes out the three implicit direction marks too (LRM, RLM, ALM), unlike mail", () => { + expect(prepareLog("a\u200eb\u200fc\u061cd").lines).toEqual(["a\\u200eb\\u200fc\\u061cd"]); + const joined = prepareLog("x\u200e\u200f\u061cy").lines.join(""); + expect(joined).not.toMatch(/[\u200e\u200f\u061c]/); + }); + it("writes out a stray ESC as a visible escape", () => { expect(prepareLog(`x${ESC}\u00e9`).lines).toEqual(["x\\x1b\u00e9"]); }); diff --git a/src/lib/compute-logs.ts b/src/lib/compute-logs.ts index 312d5d50..326c3f96 100644 --- a/src/lib/compute-logs.ts +++ b/src/lib/compute-logs.ts @@ -12,8 +12,9 @@ * in step 2 with the text after it, so a program cannot hide the rest of its log behind one. * 2. Everything else goes through `displaySafeBody` (the Mail tab's set, nemar-cli's escape set): * `\r\n` and a bare `\r` become line breaks (nothing can be overwritten), newline and tab stay, - * and every other control, bidirectional override or isolate, zero-width and invisible character is - * WRITTEN OUT (`\x1b`, `‮`), which shows that something was there instead of cleaning it away + * and every other control, bidirectional character (the three implicit marks too: a program's log + * has no right-to-left prose to protect, so they are written out here, unlike in mail), zero-width + * and invisible character is WRITTEN OUT (`\x1b`, `‮`), which shows that something was there instead of cleaning it away * silently (the CLI drops them; ADR 0029 shows them). * 3. Lines are capped at 2,000 characters with a visible count of what was cut, so a 1 MiB single line * cannot freeze the page. @@ -65,7 +66,7 @@ export interface PreparedLog { /** A log made safe: formatting removed, hostile characters written out, long lines capped. */ export function prepareLog(text: string): PreparedLog { if (text === "") return { lines: [] }; - const lines = displaySafeBody(stripAnsi(text)).split("\n"); + const lines = displaySafeBody(stripAnsi(text), { escapeMarks: true }).split("\n"); if (lines.length > 1 && lines[lines.length - 1] === "") lines.pop(); else if (lines.length === 1 && lines[0] === "") return { lines: [] }; return { lines: lines.map(capLine) }; diff --git a/src/lib/mail-display.test.ts b/src/lib/mail-display.test.ts index dbdf87c8..fc3fabe9 100644 --- a/src/lib/mail-display.test.ts +++ b/src/lib/mail-display.test.ts @@ -65,6 +65,12 @@ describe("displaySafeLine", () => { expect(displaySafeLine(input)).toBe(expected); }); + it("writes out the three direction marks too when asked, and keeps newline and tab", () => { + expect(displaySafeBody("a\u200eb\u200fc\u061cd\n\te", { escapeMarks: true })).toBe( + "a\\u200eb\\u200fc\\u061cd\n\te", + ); + }); + it("leaves ordinary text, including non-Latin scripts and emoji, alone", () => { const text = "Re: Zugang für Daten – ورود به سامانه 研究"; expect(displaySafeLine(text)).toBe(text); @@ -94,6 +100,9 @@ describe("the wider escape set (mirrors nemar-cli display-name)", () => { it("keeps exactly newline, tab, LRM, RLM and ALM in a body", () => { expect(displaySafeBody("a\n\tb\u200ec\u200fd\u061ce")).toBe("a\n\tb\u200ec\u200fd\u061ce"); expect(displaySafeBody("a\u200bb\u200cc\u2066d")).toBe("a\\u200bb\\u200cc\\u2066d"); + // The default is unchanged by the option: marks stay unless asked. + expect(displaySafeBody("a\u200eb", {})).toBe("a\u200eb"); + expect(displaySafeBody("a\u200eb", { escapeMarks: false })).toBe("a\u200eb"); }); it("writes a line's escapes the way a body does, apart from newline and tab", () => { diff --git a/src/lib/mail-display.ts b/src/lib/mail-display.ts index f5a0b911..13ef6e46 100644 --- a/src/lib/mail-display.ts +++ b/src/lib/mail-display.ts @@ -35,6 +35,9 @@ const UNSAFE_CHARACTERS = /** What a body keeps besides ordinary text: newline, tab and the three implicit direction marks. */ const BODY_KEPT: ReadonlySet = new Set(["\n", "\t", "\u200e", "\u200f", "\u061c"]); +/** What a body keeps when the direction marks are written out too: newline and tab only. */ +const BODY_KEPT_NO_MARKS: ReadonlySet = new Set(["\n", "\t"]); + function escapeCharacter(c: string): string { if (c === "\n") return "\\n"; if (c === "\r") return "\\r"; @@ -52,12 +55,14 @@ export function displaySafeLine(text: string): string { /** * A message body: line endings normalized to `\n`, newlines and tabs kept, everything else in - * the set written out except the three direction marks. + * the set written out except the three direction marks. `escapeMarks` writes those out too: a + * program's log has no right-to-left prose to protect (the job page passes it; mail does not). */ -export function displaySafeBody(text: string): string { +export function displaySafeBody(text: string, options: { escapeMarks?: boolean } = {}): string { + const kept = options.escapeMarks === true ? BODY_KEPT_NO_MARKS : BODY_KEPT; return text .replace(/\r\n?/g, "\n") - .replace(UNSAFE_CHARACTERS, (c) => (BODY_KEPT.has(c) ? c : escapeCharacter(c))); + .replace(UNSAFE_CHARACTERS, (c) => (kept.has(c) ? c : escapeCharacter(c))); } // --------------------------------------------------------------------------- From 4783ac8db89a2f581307431ba13bd71971dc3d6a Mon Sep 17 00:00:00 2001 From: Seyed Yahya Shirazi Date: Sat, 7 Nov 2026 09:16:45 -0800 Subject: [PATCH 15/17] Scan job files for navigation and beacons --- test/compute-job-ui.test.ts | 129 ++++++++++++++++++++++++++++++++++-- 1 file changed, 123 insertions(+), 6 deletions(-) diff --git a/test/compute-job-ui.test.ts b/test/compute-job-ui.test.ts index 378062b1..f87a996c 100644 --- a/test/compute-job-ui.test.ts +++ b/test/compute-job-ui.test.ts @@ -45,12 +45,72 @@ const JOB: Record = { ), }; +/** + * Source with its comments removed and its string, template and regular-expression literals LEFT + * ALONE, so a `//` inside `"http://..."` or a pattern is never taken for a comment (a scan built on a + * comment-stripping regex missed code after one). A small scanner, not a parser: enough for these files. + */ +function stripJsComments(src: string): string { + let out = ""; + let i = 0; + // A `/` starts a regular expression when the last significant character cannot end an operand. + const startsRegex = (): boolean => { + const before = out.trimEnd(); + if (before === "") return true; + const last = before[before.length - 1]; + return "(,=:[!&|?{};+-*%<>~^".includes(last) || /\b(return|typeof|case|in|of)$/.test(before); + }; + while (i < src.length) { + const c = src[i]; + const next = src[i + 1]; + if (c === "/" && next === "/") { + while (i < src.length && src[i] !== "\n") i++; + } else if (c === "/" && next === "*") { + const end = src.indexOf("*/", i + 2); + i = end < 0 ? src.length : end + 2; + } else if (c === '"' || c === "'" || c === "`") { + let j = i + 1; + while (j < src.length && src[j] !== c) j += src[j] === "\\" ? 2 : 1; + out += src.slice(i, j + 1); + i = j + 1; + } else if (c === "/" && startsRegex()) { + let j = i + 1; + let inClass = false; + while (j < src.length && (src[j] !== "/" || inClass)) { + if (src[j] === "\\") j++; + else if (src[j] === "[") inClass = true; + else if (src[j] === "]") inClass = false; + j++; + } + out += src.slice(i, j + 1); + i = j + 1; + } else { + out += c; + i++; + } + } + return out; +} + +/** The scripts and the frontmatter of an Astro file (the code), as one string. */ +function astroCode(src: string): string { + const parts: string[] = []; + const front = /^---\n([\s\S]*?)\n---/.exec(src); + if (front) parts.push(front[1]); + for (const m of src.matchAll(/]*>([\s\S]*?)<\/script>/g)) parts.push(m[1]); + return parts.map(stripJsComments).join("\n"); +} + +/** What a scan reads: comments removed, `