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 8380a751..d441f943 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 @@ -68,7 +68,19 @@ The captured fixtures in `test/fixtures/compute/` gain a `GET /compute/me` captu - **Read the terms version server-side in the page frontmatter now.** Not available until D2 serves `GET /compute/me`; the transcription and its drift test are the bridge. - **Show the backend's sentence for the profile refusals.** Rejected: it lists raw field names (`given_name, affiliation`); the linked, worded list is what the CLI prints. +## Addendum: the dashboard (phase E2, website#495, 2026-11-07) + +`/compute` reads nemar-cli's `GET /compute/me`, `/compute/me/usage` and `/compute/me/jobs` (Epic D, phase D2). The decisions that are expensive to reverse: + +- **Independent panels.** The account read comes first because it names the state; usage and the first page of jobs then run in parallel, each in its own `try/catch`. A failed read degrades one panel with a notice that says the figures are missing, which is not zero. A guard that rejects a body is a `shape` error, never an empty list or zeros. A 404 on the account read is the release gate (an API without the compute routes) and shows one notice; a 401 redirects to sign-in; a 403 is the backend's "not approved" for an unverified account, never a compute-access answer. +- **One chart per pool.** CPU and GPU service units are different currencies, so the usage chart is drawn once per pool (daily net charge, stacked by partition, at most three offered partitions plus "other") and the two are never added. Usage rows reach a pool only through `limits.partitions[].pool`; a correction that names no job, or a partition no longer offered, is shown as a separate "Adjustments and other partitions" line rather than guessed into a pool (nemar-cli#2078 asks for `pool` as a usage group). +- **Three-decimal parity with the CLI.** `suFixed` is the CLI's own function of that name (integer milli-SU in, `12.500` out, no thousands separator, a negative stays negative), and sums go through an exact adder; nothing printed passes through a float. A finished job with no charge prints `0.000`; a live one reads "Not charged yet" (the CLI prints `-` for both). +- **No synthesized figures.** Only `pools.cpu` and `pools.gpu` are read, by name, so a pool or platform figure the Worker adds later cannot reach the markup. A partner job's front door is the plain label "Partner site". The frozen sentence shows for an ACTIVE account only (the CLI's rule). A state outside the closed six shows its escaped raw word and nothing else. "New jobs are paused" is not shown because no read serves it (nemar-cli#2080). +- **Untrusted text is inert.** Every backend string (an app, a partition, a state) is escaped through `displaySafeLine` and rendered as a text node, in the template and in the "Load more" script (`createElement` and `textContent` only; a test forbids every markup-writing API in the Compute files). A job id reaches an `href` only if it is `job_` and 24 hex digits. +- **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. + ## Receipts -- website#493 (epic), website#494 (phase E1); nemar-cli#2021 (Epic D), #2071 (phase D1, commit 3a869903). +- website#493 (epic), website#494 (phase E1), website#495 (phase E2); 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/handoff.md b/.context/handoff.md index c225b243..313325b9 100644 --- a/.context/handoff.md +++ b/.context/handoff.md @@ -1,6 +1,16 @@ # Handoff — nemar.org website -**Last session:** 2026-11-06. +**Last session:** 2026-11-07. + +## 2026-11-07: The compute dashboard (website#495, epic website#493 phase E2) + +Branch `feature/issue-495-compute-dashboard`, PR into the epic branch. ADR 0030 addendum. Depends on nemar-cli's Epic D branch (phase D2 routes) and its copy PR #2082 (seven keys, reworded `compute_access.granted.body`). + +- **Recipe:** `NEMAR_CLI_DIR= PORT=8791 bun scripts/local-backend.mjs --seed-compute`, then `PUBLIC_API_BASE_URL=http://localhost:8791 bun run dev`; cookies for `rich`, `frozen`, `overrun`, `granted` print with the others (`.context/local-backend.md`). +- **Fixtures** (`test/fixtures/compute/*.json`, 13 new files) are captured by `scripts/capture-compute-read-fixtures.mjs` from the real router; a rerun writes the same bytes. +- **Drift gates:** `test/compute-user-contract-drift.test.ts` (`NEMAR_CLI_COMPUTE_STATE`, `_USER_CONTRACT`, `_CONTRACT`) and the account-copy drift test are red in CI until the compute epic and #2082 reach nemar-cli `dev`. Never put them on `staging` earlier. +- **Release gate:** do not promote until the production API serves `GET /compute/me`; a site talking to an API without it shows one "not available" notice. +- **Follow-ups:** a usage window selector, a `?state=` filter, the ADR 0030 hand-off (drop `compute-terms.ts` and `COMPUTE_REQUESTS_ENABLED`), the job page (E3). Backend gaps: nemar-cli#2078 (pool as a usage group), #2079 (job name), #2080 (are new jobs accepted). ## 2026-11-06: Compute access card in Settings (website#494, epic website#493 phase E1) diff --git a/.context/local-backend.md b/.context/local-backend.md index 6c97b36c..dc621666 100644 --- a/.context/local-backend.md +++ b/.context/local-backend.md @@ -49,6 +49,18 @@ got is not `127.0.0.1`. `test/local-backend-guard.test.ts` runs the refusals. http://localhost:8787/admin/compute/access/grant/localrequested ``` +## Seeding the compute dashboard (`--seed-compute`) + +```bash +NEMAR_CLI_DIR=/path/to/nemar-cli-checkout bun scripts/local-backend.mjs --seed-compute +``` + +Adds, with the backend's own test helpers and ledger services (never a stand-in): `localrich` (active; a CPU and a GPU grant, charges on several days of the last 30 on both pools, one administrator's correction naming no job, an open hold, 40 jobs over the ten states and four front doors with enough finished ones for a second page, and queue samples with figures, a real zero and a thin sample), `localfrozen` (a frozen pool), `localoverrun` (a negative available) and `localgranted` (granted through the REAL admin routes, access then a pool grant: no jobs, no charges). Their cookies print with the others. `PORT=` moves the backend (and `PUBLIC_API_BASE_URL` with it). The loopback guards are unchanged. + +There is no unverified persona: signing in by emailed code verifies the email. `bun run dev` without `PUBLIC_API_BASE_URL` has the `@nemar.cpending` mock for that screen. The database refuses a markup-bearing `app_id` (a CHECK on `compute_jobs`), so the "hostile text" case is covered by unit tests, not by a seeded row. + +A second browser profile on the same host shares cookies; use `http://127.0.0.1:4321` beside `http://localhost:4321` to keep two sessions apart. + ## What differs from production - `ENVIRONMENT` is `test`: the backend takes compute requests whether or not the terms are diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e59d9b84..26e208eb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -123,13 +123,20 @@ jobs: # the compute terms version a request must name (website ADR 0030, interim until phase D2's # GET /compute/me serves it). Same `dev` pairing, strict, and red until the compute epic # reaches nemar-cli `dev`; the ref stays `dev`. + # test/compute-user-contract-drift.test.ts is a NINTH, against shared/compute-state.ts and + # 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`. - uses: actions/checkout@v4 with: repository: nemarOrg/nemar-cli path: nemar-cli-contract sparse-checkout: | + /shared/compute-state.ts /shared/contract/account-copy.ts /shared/contract/compute-terms.ts + /shared/contract/compute-user.ts + /shared/contract/compute.ts /shared/contract/docs-auth.ts /shared/contract/mail-admin.ts /shared/contract/oidc-authorize.ts @@ -145,6 +152,9 @@ jobs: env: 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_STATE: nemar-cli-contract/shared/compute-state.ts + NEMAR_CLI_COMPUTE_USER_CONTRACT: nemar-cli-contract/shared/contract/compute-user.ts NEMAR_CLI_DOCS_CONTRACT: nemar-cli-contract/shared/contract/docs-auth.ts NEMAR_CLI_MAIL_ADMIN_CONTRACT: nemar-cli-contract/shared/contract/mail-admin.ts NEMAR_CLI_OIDC_AUTHORIZE_CONTRACT: nemar-cli-contract/shared/contract/oidc-authorize.ts diff --git a/AGENTS.md b/AGENTS.md index d229624c..d19b8add 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -75,7 +75,8 @@ src/ api/v1/[...path].ts generic authenticated API proxy dashboard.astro my-datasets list + publish status (app host) 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 + 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 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 about.astro support.astro community.astro @@ -91,6 +92,10 @@ src/ dashboard-api.ts admin-api.ts collaborators-api.ts upload-client.ts authenticated API clients mail-admin-api.ts admin Mail client (browser-safe): tickets, queues, away window, reply failure classes, badge count, staff directory mail-admin-contract.ts hand copy of nemar-cli shared/contract/mail-admin.ts (drift-tested, test/mail-admin-contract-drift.test.ts) + compute-api.ts compute-contract.ts browser-safe client for GET /compute/me, /me/usage, /me/jobs (guards copy out only the keys read; a rejected body is a `shape` error, never zeros) and the hand copy of the vocabulary it needs, the one place the job-state and front-door words live here (drift-tested, test/compute-user-contract-drift.test.ts; extractors in test/compute-contract-drift.ts) + 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 mail-display.ts escape set for ticket text, thread order, reply draft state machine and its sessionStorage form device-auth-api.ts device-authorization grant client: lookup/confirm/deny, list keys device-authorize.ts pure view model for /cli/authorize (no mirrored refusal vocabulary) @@ -117,6 +122,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) 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 3aebdf39..457d6749 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,13 @@ The release pull request from `staging` to `main` moves those entries under the ### Added +- **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. + `/compute` is an app-host route, linked from the user menu for active, suspended and ended accounts and from the active Compute card in Settings. + Seven shared copy keys were added (`compute_page.*`, `compute_access.granted.link`) and `compute_access.granted.body` now says jobs are submitted with the command line; they come with nemar-cli's phase PR, so the account-copy drift test is red until it reaches `dev`. + `scripts/local-backend.mjs --seed-compute` seeds the dashboard's data through the real backend helpers. + - **A compute access card in Settings** (website#494, epic website#493 phase E1; nemar-cli epic #2021 phase D1, ADR 0030). Beside the upload-access card, `#compute-access` shows the account's compute-access state (not requested, requested, active, suspended, not granted, ended) and, for a verified account that has never asked, a request form: a purpose of 20 to 1,000 characters, a required checkbox for the compute terms (with the version, linking the terms page), and the refusal list a refused request returns, as links to the fields to fix. Every sentence is a transcribed copy key, the same words the CLI prints. diff --git a/scripts/capture-compute-read-fixtures.mjs b/scripts/capture-compute-read-fixtures.mjs new file mode 100644 index 00000000..eebe6ff9 --- /dev/null +++ b/scripts/capture-compute-read-fixtures.mjs @@ -0,0 +1,477 @@ +/** + * Capture the compute READ fixtures from the REAL nemar-cli backend routes (website ADR 0030 and its + * phase E2 addendum; epic nemarOrg/website#493, issue #495). + * + * NEMAR_CLI_DIR= \ + * bun scripts/capture-compute-read-fixtures.mjs + * + * Captured from nemar-cli commit e0685a25 (Epic D phase D4, squash on + * `feature/issue-2021-epic-compute-users`; phases D1 to D4 are in it). The checkout needs + * `bun install` at its root and in `backend/`. Nothing is stood in for: the script imports the + * backend's own test helpers (`backend/test/helpers/compute-user-seed.ts`: `readApp`, `personWithKey`, + * `insertJob`, `chargeAt`, `correctionAt`; `compute-seed.ts`: `fundAccount`, `fundPlatform`; + * `d1.ts`: `freshDb`), seeds a real migrated SQLite database through the real ledger services + * (`placeHold`, `settleProvisional`, so the pool totals come from the ledger's own triggers), calls + * the REAL compute router with a real hashed API key, and writes the bodies unchanged. + * + * Writes under test/fixtures/compute/: + * me-states.json GET /compute/me, one per access state (and `none` with requests open) + * me-active-with-usage.json granted, held and charged all non-zero; queue samples with figures + * me-frozen.json an active account whose pool is frozen + * me-overrun.json a negative available_milli + * me-thin-queue.json a partition with 3 samples (null figures, with the count) next to one with figures + * usage-day-partition.json GET /compute/me/usage?group=day,partition over a fixed window + * usage-empty.json a fresh account: rows [] + * usage-outlier.json one large day among small ones + * jobs-page1.json, jobs-page2.json limit=2, then the page `next_after` points at + * jobs-all-states.json one job in each of the ten states + * jobs-empty.json { jobs: [], next_after: null } + * errors.json the real refusals + * + * Every request time in the seed is fixed (explicit `created_at` and ledger times, explicit `from` and + * `to` on the usage request), so a rerun writes the same bytes. Only the queue samples are placed + * relative to now (the route measures the last 7 days); their figures are seconds and counts, which are + * stable. 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 { freshDb, realD1 } = await import(join(root, "backend/test/helpers/d1.ts")); +const seeds = await import(join(root, "backend/test/helpers/compute-user-seed.ts")); +const { fundAccount, fundPlatform } = await import( + join(root, "backend/test/helpers/compute-seed.ts") +); +const { placeHold, settleProvisional } = await import( + join(root, "backend/src/services/compute-ledger.ts") +); +const { COMPUTE_STATES } = await import(join(root, "shared/compute-state.ts")); +const { insertJob, jobIdFor, personWithKey, readApp, chargeAt, correctionAt, sqliteAt } = seeds; + +const COMMIT = "e0685a25"; +const COMMAND = "NEMAR_CLI_DIR= bun scripts/capture-compute-read-fixtures.mjs"; +const WINDOW = { from: "2026-10-09", to: "2026-11-07" }; + +function provenance(route, request, note) { + return { command: COMMAND, nemar_cli_commit: COMMIT, route, request, note }; +} + +/** A fresh database, the platform `people` budget funded, and a helper to find a pool id. */ +async function world() { + const db = freshDb(); + const d1 = realD1(db); + await fundPlatform(d1, "people", 1_000_000_000); + await fundPlatform(d1, "people", 1_000_000_000, "gpu"); + const budget = (word) => + db + .query( + "SELECT id FROM compute_pools WHERE holder_kind = 'platform' AND holder_ref = 'people' AND pool = ?", + ) + .get(word).id; + return { db, d1, budget }; +} + +async function get(db, key, path, env) { + const res = await readApp(db, env).call(path, { key }); + return { status: res.status, body: res.body }; +} + +/** Stamp the dates a state has, so the access object is the same on every run. */ +function stamp(db, personId, state) { + const requested = state === "none" ? null : "2026-10-20 09:30:00"; + const granted = ["active", "suspended", "revoked"].includes(state) ? "2026-10-24 14:05:00" : null; + db.query( + `UPDATE users SET compute_access_requested_at = ?, compute_access_granted_at = ?, + compute_terms_version = ? WHERE id = ?`, + ).run(requested, granted, state === "none" ? null : "2026-11-draft", personId); +} + +/** Queue samples: `n` jobs that started an hour ago after waiting the given seconds. */ +function queueSamples(db, partition, waits) { + const now = Date.now(); + for (const wait of waits) { + insertJob(db, { + partition, + pool: partition.startsWith("gpu") ? "gpu" : "cpu", + account_id: 999_999, + started_at: sqliteAt(now - 3_600_000), + remote_submitted_at: sqliteAt(now - 3_600_000 - wait * 1000), + }); + } +} + +// --- me-states.json ------------------------------------------------------------------------------- + +const meStates = { + _provenance: provenance( + "GET /compute/me", + "one account per access state, no query", + "Real route over a real migrated database. Zero pools and empty queue samples are true: nothing was granted and no job started. The access stamps are written with fixed values. `none_requests_open` is the same account read with a non-production environment, where requests are open.", + ), +}; +for (const state of ["none", "requested", "active", "suspended", "denied", "revoked"]) { + const { db } = await world(); + const person = await personWithKey(db, { access: state }); + stamp(db, person.id, state); + meStates[state] = await get(db, person.key, "/me"); + if (state === "none") { + meStates.none_requests_open = await get(db, person.key, "/me", { ENVIRONMENT: "development" }); + } +} + +// --- the rich account: balances, usage by day and partition, jobs --------------------------------- + +const rich = await world(); +const richPerson = await personWithKey(rich.db, { access: "active" }); +stamp(rich.db, richPerson.id, "active"); +const cpuPool = await fundAccount(rich.d1, richPerson.id, 100_000, "cpu"); +const gpuPool = await fundAccount(rich.d1, richPerson.id, 40_000, "gpu"); + +/** One finished job, charged `milli` at the time `at` on `partition`. */ +function chargedJob(partition, milli, at, over = {}) { + const pool = partition.startsWith("gpu") ? "gpu" : "cpu"; + const id = insertJob(rich.db, { + account_id: richPerson.id, + partition, + pool, + state: "finished", + charged_milli: milli, + created_at: over.created_at ?? at, + started_at: at, + ended_at: at, + source: over.source ?? "cli", + app_id: over.app_id ?? "nemar-launch", + }); + chargeAt(rich.db, { accountId: richPerson.id, jobId: id, milli, at, pool }); + return id; +} + +// Oct 9 .. Nov 7, charged on several days. Day boundaries: 23:59:59 and 00:00:00. +chargedJob("shared", 4_000, "2026-10-12 08:00:00"); +chargedJob("compute", 12_500, "2026-10-12 23:59:59"); +chargedJob("shared", 2_500, "2026-10-13 00:00:00", { source: "web" }); +chargedJob("shared", 6_000, "2026-10-20 10:00:00"); +chargedJob("debug", 500, "2026-10-20 11:00:00"); +chargedJob("compute", 9_000, "2026-10-27 15:30:00"); +chargedJob("shared", 3_250, "2026-11-03 09:00:00", { source: "partner" }); +chargedJob("shared", 1_750, "2026-11-03 21:00:00"); +chargedJob("gpu-shared", 5_000, "2026-10-14 12:00:00"); +chargedJob("gpu", 8_000, "2026-10-28 12:00:00"); +chargedJob("gpu-shared", 1_500, "2026-11-05 12:00:00"); +// A refund on a day with no other charge in that partition: a NET negative row. +{ + const id = insertJob(rich.db, { + account_id: richPerson.id, + partition: "debug", + state: "failed", + created_at: "2026-10-22 09:00:00", + started_at: "2026-10-22 09:00:00", + ended_at: "2026-10-22 09:05:00", + }); + chargeAt(rich.db, { + accountId: richPerson.id, + jobId: id, + milli: -300, + at: "2026-10-22 09:10:00", + }); +} +// An administrator's correction that names no job: partition is null in the usage rows. +correctionAt(rich.db, { accountId: richPerson.id, milli: 1_000, at: "2026-10-30 10:00:00" }); +correctionAt(rich.db, { + accountId: richPerson.id, + milli: 750, + at: "2026-10-30 10:30:00", + pool: "gpu", +}); + +// One live job with a hold: the held figure is real. +{ + const job = jobIdFor(); + const hold = await placeHold(rich.d1, { + poolId: cpuPool, + budgetPoolId: rich.budget("cpu"), + amountMilli: 20_000, + jobId: job, + }); + if (!hold.ok) throw new Error(`hold: ${JSON.stringify(hold)}`); + insertJob(rich.db, { + id: job, + account_id: richPerson.id, + partition: "shared", + state: "running", + held_milli: 20_000, + created_at: "2026-11-06 20:00:00", + started_at: "2026-11-06 20:05:00", + }); +} +void gpuPool; +void settleProvisional; + +// Queue samples with figures on two partitions (waits in seconds; stable whatever the date). +queueSamples(rich.db, "shared", [10, 20, 30, 40, 50, 75, 3700]); +queueSamples(rich.db, "gpu-shared", [0, 0, 0, 0, 0]); + +const meActive = { + _provenance: provenance( + "GET /compute/me", + "no query", + "An active account with a CPU grant of 100.000 SU and a GPU grant of 40.000 SU, charges across several days, one open hold of 20.000 SU, and queue samples with figures (a median of 0 seconds on gpu-shared is a real value).", + ), + ...(await get(rich.db, richPerson.key, "/me")), +}; + +const usageDayPartition = { + _provenance: provenance( + "GET /compute/me/usage", + `group=day,partition&from=${WINDOW.from}&to=${WINDOW.to}`, + "Several days on both pools, a 23:59:59 and a 00:00:00 entry on neighboring days, a net-negative refund row, an administrator's correction (null partition) on both pools, and quiet days that have no row. The window is explicit so the file is reproducible; the page itself asks for the server's default window.", + ), + ...(await get( + rich.db, + richPerson.key, + `/me/usage?group=day,partition&from=${WINDOW.from}&to=${WINDOW.to}`, + )), +}; + +// Jobs: pages of two over the rich account (newest first). +const page1Path = "/me/jobs?limit=2"; +const jobsPage1 = await get(rich.db, richPerson.key, page1Path); +const cursor = jobsPage1.body.next_after; +if (typeof cursor !== "string") throw new Error("page one has no next_after"); +const jobsPage2 = await get( + rich.db, + richPerson.key, + `/me/jobs?limit=2&after=${encodeURIComponent(cursor)}`, +); +jobsPage1._provenance = provenance( + "GET /compute/me/jobs", + "limit=2", + "The first page of a rich account's jobs; next_after continues it.", +); +jobsPage2._provenance = provenance( + "GET /compute/me/jobs", + "limit=2&after=", + "The page next_after of jobs-page1.json points at.", +); + +// --- me-frozen, me-overrun, me-thin-queue --------------------------------------------------------- + +const frozen = await world(); +const frozenPerson = await personWithKey(frozen.db, { access: "active" }); +stamp(frozen.db, frozenPerson.id, "active"); +const frozenPool = await fundAccount(frozen.d1, frozenPerson.id, 50_000, "cpu"); +frozen.db.query("UPDATE compute_pools SET frozen = 1 WHERE id = ?").run(frozenPool); +const meFrozen = { + _provenance: provenance( + "GET /compute/me", + "no query", + "An active account with a frozen CPU pool: frozen is true, the balance is still stated.", + ), + ...(await get(frozen.db, frozenPerson.key, "/me")), +}; + +const overrun = await world(); +const overrunPerson = await personWithKey(overrun.db, { access: "active" }); +stamp(overrun.db, overrunPerson.id, "active"); +await fundAccount(overrun.d1, overrunPerson.id, 10_000, "cpu"); +{ + const id = insertJob(overrun.db, { + account_id: overrunPerson.id, + partition: "shared", + state: "finished", + charged_milli: 12_500, + created_at: "2026-11-01 10:00:00", + }); + chargeAt(overrun.db, { + accountId: overrunPerson.id, + jobId: id, + milli: 12_500, + at: "2026-11-01 11:00:00", + }); +} +const meOverrun = { + _provenance: provenance( + "GET /compute/me", + "no query", + "A CPU grant of 10.000 SU charged 12.500 SU: available_milli is -2500, an integer, not clamped.", + ), + ...(await get(overrun.db, overrunPerson.key, "/me")), +}; + +const thin = await world(); +const thinPerson = await personWithKey(thin.db, { access: "active" }); +stamp(thin.db, thinPerson.id, "active"); +await fundAccount(thin.d1, thinPerson.id, 8_000, "cpu"); +queueSamples(thin.db, "shared", [10, 20, 30, 40, 50]); +queueSamples(thin.db, "compute", [5, 6, 7]); +const meThin = { + _provenance: provenance( + "GET /compute/me", + "no query", + "shared has five samples (figures), compute has three (null figures with the count), the rest have none.", + ), + ...(await get(thin.db, thinPerson.key, "/me")), +}; + +// --- usage-empty, usage-outlier ------------------------------------------------------------------- + +const fresh = await world(); +const freshPerson = await personWithKey(fresh.db, { access: "active" }); +stamp(fresh.db, freshPerson.id, "active"); +await fundAccount(fresh.d1, freshPerson.id, 25_000, "cpu"); +const usageEmpty = { + _provenance: provenance( + "GET /compute/me/usage", + `group=day,partition&from=${WINDOW.from}&to=${WINDOW.to}`, + "A freshly granted account with no charge: rows is [], which is true.", + ), + ...(await get( + fresh.db, + freshPerson.key, + `/me/usage?group=day,partition&from=${WINDOW.from}&to=${WINDOW.to}`, + )), +}; +const jobsEmpty = { + _provenance: provenance("GET /compute/me/jobs", "no query", "A fresh account has no jobs."), + ...(await get(fresh.db, freshPerson.key, "/me/jobs")), +}; + +const outlier = await world(); +const outlierPerson = await personWithKey(outlier.db, { access: "active" }); +stamp(outlier.db, outlierPerson.id, "active"); +await fundAccount(outlier.d1, outlierPerson.id, 500_000, "cpu"); +for (const [day, milli] of [ + ["2026-10-10", 500], + ["2026-10-11", 750], + ["2026-10-15", 400], + ["2026-10-20", 250_000], + ["2026-10-21", 600], + ["2026-11-01", 300], +]) { + const id = insertJob(outlier.db, { + account_id: outlierPerson.id, + partition: "shared", + state: "finished", + charged_milli: milli, + created_at: `${day} 06:00:00`, + }); + chargeAt(outlier.db, { + accountId: outlierPerson.id, + jobId: id, + milli, + at: `${day} 07:00:00`, + }); +} +const usageOutlier = { + _provenance: provenance( + "GET /compute/me/usage", + `group=day,partition&from=${WINDOW.from}&to=${WINDOW.to}`, + "One large day (250.000 SU) among days under 1 SU on one partition.", + ), + ...(await get( + outlier.db, + outlierPerson.key, + `/me/usage?group=day,partition&from=${WINDOW.from}&to=${WINDOW.to}`, + )), +}; + +// --- jobs in all ten states, and a hostile app id ------------------------------------------------- + +const states = await world(); +const statesPerson = await personWithKey(states.db, { access: "active" }); +stamp(states.db, statesPerson.id, "active"); +await fundAccount(states.d1, statesPerson.id, 100_000, "cpu"); +COMPUTE_STATES.forEach((state, i) => { + const terminal = ["finished", "failed", "cancelled"].includes(state); + insertJob(states.db, { + account_id: statesPerson.id, + state, + source: ["cli", "web", "partner", "pipeline"][i % 4], + partition: i % 3 === 0 ? "gpu-shared" : "shared", + pool: i % 3 === 0 ? "gpu" : "cpu", + gpus: i % 3 === 0 ? 1 : 0, + created_at: `2026-11-0${(i % 7) + 1} 1${i % 10}:00:00`, + started_at: ["running", "archiving", "finished", "failed"].includes(state) + ? `2026-11-0${(i % 7) + 1} 1${i % 10}:05:00` + : null, + ended_at: terminal ? `2026-11-0${(i % 7) + 1} 1${i % 10}:45:00` : null, + charged_milli: state === "finished" ? 2_500 : state === "failed" ? 0 : 0, + }); +}); +// A cancel requested on a live job, and an explicit zero-charge finished job are covered above: +// `cancelled` and `finished` ... add one live job with cancel_requested_at set. +insertJob(states.db, { + account_id: statesPerson.id, + state: "running", + created_at: "2026-11-07 09:00:00", + started_at: "2026-11-07 09:05:00", + cancel_requested_at: "2026-11-07 09:30:00", +}); +const jobsAllStates = { + _provenance: provenance( + "GET /compute/me/jobs", + "limit=25", + "One job in each of the ten states over the four front doors, plus a running job with a cancel requested.", + ), + ...(await get(states.db, statesPerson.key, "/me/jobs?limit=25")), +}; + +// There is no hostile-text fixture on purpose: compute_jobs CHECKs app_id and app_version to +// [A-Za-z0-9._+-] (migration 0115), so the route cannot serve markup there. The page still treats +// every backend string as inert text; the tests feed hand-built unit inputs for that, not a +// captured body. + +// --- errors.json ---------------------------------------------------------------------------------- + +const errs = await world(); +const errPerson = await personWithKey(errs.db, { access: "active" }); +const pending = await personWithKey(errs.db, { status: "pending", access: "none" }); +const errors = { + _provenance: provenance( + "GET /compute/me*", + "the refusals below", + "Real refusals. On the read routes the sentence is in `error` and the machine word in `code` (the reverse of what api-base.ts readError assumes). The 401 and the 403 are authMiddleware's own shapes, which is what a cookie session meets.", + ), + invalid_cursor: await get(errs.db, errPerson.key, "/me/jobs?after=garbage"), + invalid_limit: await get(errs.db, errPerson.key, "/me/jobs?limit=0"), + invalid_state: await get(errs.db, errPerson.key, "/me/jobs?state=bogus"), + invalid_group: await get(errs.db, errPerson.key, "/me/usage?group=bogus"), + invalid_range: await get(errs.db, errPerson.key, "/me/usage?from=2026-13-01&to=2026-11-07"), + no_credential: await get(errs.db, null, "/me"), + account_not_approved: await get(errs.db, pending.key, "/me"), +}; + +// --- write ---------------------------------------------------------------------------------------- + +const files = { + "me-states.json": meStates, + "me-active-with-usage.json": meActive, + "me-frozen.json": meFrozen, + "me-overrun.json": meOverrun, + "me-thin-queue.json": meThin, + "usage-day-partition.json": usageDayPartition, + "usage-empty.json": usageEmpty, + "usage-outlier.json": usageOutlier, + "jobs-page1.json": jobsPage1, + "jobs-page2.json": jobsPage2, + "jobs-all-states.json": jobsAllStates, + "jobs-empty.json": jobsEmpty, + "errors.json": errors, +}; + +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}`); +process.exit(0); diff --git a/scripts/local-backend.mjs b/scripts/local-backend.mjs index 0c052849..479f7c66 100644 --- a/scripts/local-backend.mjs +++ b/scripts/local-backend.mjs @@ -25,6 +25,18 @@ * `WEB_ORIGIN` that is not loopback, and it checks the socket it got. * `test/local-backend-guard.test.ts` runs those refusals. * + * Options: + * --seed-compute also seeds the compute dashboard's data (website phase E2, #495), with the backend's + * own helpers and ledger services, never a stand-in: `localrich` (active; grants, + * charges across the last 30 days on both pools, one administrator's correction, + * an open hold, 40 jobs in all ten states, queue samples with figures), `localfrozen` + * (a frozen pool), `localoverrun` (a negative available), `localgranted` (granted + * through the REAL admin routes: access, then a pool grant; no jobs, no charges). + * There is no unverified persona: signing in by emailed code verifies the email, so + * the real flow cannot leave one signed in (`bun run dev` without + * PUBLIC_API_BASE_URL has the `@nemar.cpending` mock for that screen). The + * loopback guards below are unchanged. + * * Environment: * NEMAR_CLI_DIR required; the nemar-cli checkout (bun install at its root * and in backend/) @@ -201,6 +213,21 @@ const PERSONAS = [ { who: "noprofile", compute_access: "none", given_name: null, city: null, affiliation: null }, { who: "noorcid", compute_access: "none", identity: false }, ]; +const SEED_COMPUTE = process.argv.includes("--seed-compute"); +if (SEED_COMPUTE) { + const active = { + compute_access: "active", + compute_access_requested_at: STAMPS.requested, + compute_access_granted_at: STAMPS.granted, + }; + PERSONAS.push( + { who: "rich", ...active }, + { who: "frozen", ...active }, + { who: "overrun", ...active }, + // Asks, then is granted through the real admin routes below. + { who: "granted", compute_access: "requested", compute_access_requested_at: STAMPS.requested }, + ); +} for (const p of PERSONAS) { const { who, ...rest } = p; insertUser({ username: `local${who}`, email: `${who}@nemar.test`, ...rest }); @@ -252,6 +279,164 @@ if (server.hostname !== "127.0.0.1") { refuse(`the server bound ${server.hostname}, not 127.0.0.1.`); } + +/** The compute dashboard's data (--seed-compute): the backend's own seed helpers and ledger services. */ +async function seedComputeData() { + const seeds = await import(join(root, "backend/test/helpers/compute-user-seed.ts")); + const { fundAccount, fundPlatform } = await import(join(root, "backend/test/helpers/compute-seed.ts")); + const { placeHold } = await import(join(root, "backend/src/services/compute-ledger.ts")); + const { COMPUTE_STATES } = await import(join(root, "shared/compute-state.ts")); + const { insertJob, jobIdFor, chargeAt, correctionAt, sqliteAt } = seeds; + const d1 = realD1(db); + const idOf = (name) => db.query("SELECT id FROM users WHERE username = ?").get(`local${name}`).id; + const now = Date.now(); + const DAY = 86_400_000; + /** A time `days` days and `hours` hours ago, as SQLite text (UTC). */ + const ago = (days, hours = 0) => sqliteAt(now - days * DAY - hours * 3_600_000); + const budget = (word) => + db + .query( + "SELECT id FROM compute_pools WHERE holder_kind = 'platform' AND holder_ref = 'people' AND pool = ?", + ) + .get(word).id; + + await fundPlatform(d1, "people", 1_000_000_000); + await fundPlatform(d1, "people", 1_000_000_000, "gpu"); + + // --- rich: charges on several days of the last 30, a correction, a hold, jobs in all ten states. + const rich = idOf("rich"); + const cpu = await fundAccount(d1, rich, 100_000, "cpu"); + await fundAccount(d1, rich, 40_000, "gpu"); + const charged = (partition, milli, days, hours = 0, source = "cli") => { + const pool = partition.startsWith("gpu") ? "gpu" : "cpu"; + const at = ago(days, hours); + const id = insertJob(db, { + account_id: rich, + partition, + pool, + source, + state: "finished", + charged_milli: milli, + created_at: ago(days, hours + 1), + started_at: at, + ended_at: at, + }); + chargeAt(db, { accountId: rich, jobId: id, milli, at, pool }); + }; + charged("shared", 4_000, 24); + charged("compute", 12_500, 24, 2); + charged("shared", 2_500, 23, 0, "web"); + charged("shared", 6_000, 17); + charged("debug", 500, 17, 1); + charged("compute", 9_000, 10); + charged("shared", 3_250, 3, 0, "partner"); + charged("shared", 1_750, 3, 3); + charged("gpu-shared", 5_000, 21); + charged("gpu", 8_000, 9); + charged("gpu-shared", 1_500, 2, 0, "pipeline"); + correctionAt(db, { accountId: rich, milli: 1_000, at: ago(8) }); + { + const held = jobIdFor(); + const hold = await placeHold(d1, { + poolId: cpu, + budgetPoolId: budget("cpu"), + amountMilli: 20_000, + jobId: held, + }); + if (!hold.ok) throw new Error(`could not place the seed hold: ${JSON.stringify(hold)}`); + insertJob(db, { + id: held, + account_id: rich, + partition: "shared", + state: "running", + held_milli: 20_000, + created_at: ago(0, 3), + started_at: ago(0, 2), + }); + } + // One job in each of the ten states, over the four front doors (the running one asks to be canceled)... + COMPUTE_STATES.forEach((state, i) => { + const terminal = ["finished", "failed", "cancelled"].includes(state); + insertJob(db, { + account_id: rich, + state, + source: ["cli", "web", "partner", "pipeline"][i % 4], + partition: i % 3 === 0 ? "gpu-shared" : "shared", + pool: i % 3 === 0 ? "gpu" : "cpu", + gpus: i % 3 === 0 ? 1 : 0, + created_at: ago(1, i), + started_at: ["running", "archiving", "finished", "failed"].includes(state) ? ago(1, i - 1) : null, + ended_at: terminal ? ago(1, i - 2) : null, + cancel_requested_at: state === "running" ? ago(0, 1) : null, + }); + }); + // ...and enough finished ones that "Load more" has a second page. + for (let i = 0; i < 30; i++) { + insertJob(db, { + account_id: rich, + state: i % 5 === 0 ? "failed" : "finished", + created_at: ago(12 + i / 4, i), + started_at: ago(12 + i / 4, i), + ended_at: ago(12 + i / 4, i), + }); + } + // Queue samples (the whole platform, not this person): figures, a real zero, and a thin sample. + const sample = (partition, wait) => + insertJob(db, { + partition, + pool: partition.startsWith("gpu") ? "gpu" : "cpu", + account_id: null, + source: "pipeline", + started_at: ago(1), + remote_submitted_at: sqliteAt(now - DAY - wait * 1000), + }); + for (const wait of [10, 20, 30, 40, 50, 75, 3700]) sample("shared", wait); + for (const wait of [0, 0, 0, 0, 0]) sample("gpu-shared", wait); + for (const wait of [5, 6, 7]) sample("compute", wait); + + // --- frozen: a pool the backend reports as frozen. + const frozen = idOf("frozen"); + const frozenPool = await fundAccount(d1, frozen, 50_000, "cpu"); + db.query("UPDATE compute_pools SET frozen = 1 WHERE id = ?").run(frozenPool); + + // --- overrun: charged past the grant, so available is negative. + const overrun = idOf("overrun"); + await fundAccount(d1, overrun, 10_000, "cpu"); + { + const id = insertJob(db, { + account_id: overrun, + partition: "shared", + state: "finished", + charged_milli: 12_500, + created_at: ago(2, 1), + }); + chargeAt(db, { accountId: overrun, jobId: id, milli: 12_500, at: ago(2) }); + } + + // --- granted: through the REAL admin routes (access, then a pool grant). No jobs, no charges. + const asOwner = (path, body) => + call(path, { + method: "POST", + headers: { + Authorization: `Bearer ${OWNER_KEY}`, + "content-type": "application/json", + "Idempotency-Key": `seed-${body?.pool ?? "access"}-${path.length}`, + }, + body: body ? JSON.stringify(body) : undefined, + }); + const accessRes = await asOwner("/admin/compute/access/grant/localgranted"); + if (!accessRes.ok) throw new Error(`grant failed: ${accessRes.status} ${await accessRes.text()}`); + const grantedId = idOf("granted"); + for (const [pool, amount] of [["cpu", 25_000], ["gpu", 10_000]]) { + const res = await asOwner(`/admin/compute/pools/by-id/${grantedId}/grant`, { + pool, + amount_milli: amount, + }); + if (!res.ok) throw new Error(`pool grant failed: ${res.status} ${await res.text()}`); + } +} +if (SEED_COMPUTE) await seedComputeData(); + const cookies = {}; for (const p of PERSONAS) cookies[p.who] = await signIn(`${p.who}@nemar.test`); diff --git a/src/components/ComputeAccessPanel.astro b/src/components/ComputeAccessPanel.astro new file mode 100644 index 00000000..da8112d1 --- /dev/null +++ b/src/components/ComputeAccessPanel.astro @@ -0,0 +1,75 @@ +--- +/** + * The Access panel of /compute: the state as a badge, the state's own sentences from the shared copy + * (`ACCOUNT_COPY`, mirrored from nemar-cli), and a link to the request card in Settings when a request + * is open. Every sentence comes from `accessView` in `src/lib/compute-view.ts`; nothing is typed here. + * An account whose state this build does not know shows the escaped raw word in a neutral pill and + * nothing else: the page decides nothing the backend did not state. + */ +import { COMPUTE_LABELS } from "../lib/compute-labels"; +import type { AccessView } from "../lib/compute-view"; +import ComputeBadge from "./ComputeBadge.astro"; +import ComputePanel from "./ComputePanel.astro"; + +interface Props { + view: AccessView; +} + +const { view } = Astro.props; +--- + + +
+ {COMPUTE_LABELS.access.status} + + {view.grantedSince && ( + {COMPUTE_LABELS.access.since} {view.grantedSince} + )} +
+ {view.paragraphs.map((text) =>

{text}

)} + {view.link && ( +

+ {view.link.label} +

+ )} +
+ + diff --git a/src/components/ComputeBadge.astro b/src/components/ComputeBadge.astro new file mode 100644 index 00000000..1f8d894f --- /dev/null +++ b/src/components/ComputeBadge.astro @@ -0,0 +1,76 @@ +--- +/** + * Status pill for the /compute page: the icon-plus-words badge of the admin portal + * (`ImportStatusBadge.astro`, `UserStatusBadge.astro`), used for a job's state and for the access + * state. Tone comes from `src/lib/compute-badges.ts` and `compute-view.ts`; a value this build does + * not know arrives as a neutral pill carrying its escaped raw word. + * + * The styles are GLOBAL on purpose and prefixed `.compute-badge`: the jobs table's "Load more" script + * builds the same pill with `createElement` (`src/lib/compute-jobs-dom.ts`), and Astro's scoped styles + * would not reach an element created in the browser. The class names are the contract between the two. + * SYNC: `ImportStatusBadge.astro` has the same shape with scoped styles; keep the tones in step. + */ +import type { BadgeTone } from "../lib/admin-badges"; +import type { IconName } from "../lib/status-icons"; +import StatusIcon from "./admin/StatusIcon.astro"; + +interface Props { + label: string; + tone: BadgeTone; + icon: IconName; +} + +const { label, tone, icon } = Astro.props; +--- + + + + {label} + + + diff --git a/src/components/ComputeBalances.astro b/src/components/ComputeBalances.astro new file mode 100644 index 00000000..416cfa0d --- /dev/null +++ b/src/components/ComputeBalances.astro @@ -0,0 +1,117 @@ +--- +/** + * The Balances panel of /compute: one card per pool, CPU then GPU, each with Granted, Held, Charged and + * Available in service units and a bar of available over granted. The two pools are different + * currencies and are never added together. Numbers come from `balancesView` (integer milli-SU, three + * decimals, the digits `nemar compute balance` prints). The bar is decoration (`aria-hidden`); a + * negative available prints as negative in the danger tone, with a sign, never as zero. + */ +import { COMPUTE_LABELS } from "../lib/compute-labels"; +import type { BalancesView } from "../lib/compute-view"; +import ComputePanel from "./ComputePanel.astro"; + +interface Props { + view: BalancesView; +} + +const { view } = Astro.props; +--- + + +
+ {view.pools.map((pool) => ( +
+

{pool.name}

+
+ {pool.rows.map((row) => ( +
+
{row.label}
+
+ {row.text} +
+
+ ))} +
+ {pool.barPercent === null ? ( +

{COMPUTE_LABELS.balance.nothingGranted}

+ ) : ( + + )} +
+ ))} +
+ {view.notes.map((note) =>

{note}

)} +
+ + diff --git a/src/components/ComputeJobsTable.astro b/src/components/ComputeJobsTable.astro new file mode 100644 index 00000000..768c1884 --- /dev/null +++ b/src/components/ComputeJobsTable.astro @@ -0,0 +1,304 @@ +--- +/** + * The Jobs panel of /compute: the person's jobs from every front door, newest first. Rows come from + * `jobRowView` in `src/lib/compute-view.ts`, the same place the browser script reads for later pages + * (`src/lib/compute-jobs-dom.ts`), so the two renderers cannot disagree. + * + * - There is no job name (the user job has none): a job is its id and its app. Each id links to its page. + * - "Load more" is a plain link to `/compute?after=#jobs`, so it works without JavaScript (the + * server then renders that page); the script intercepts it, fetches the next page through the + * `/api/v1` proxy and APPENDS rows. The cursor is opaque: it is read from the last answer each time + * and never computed. A failure keeps the same cursor and offers a retry. + * - Backend text is only ever a text node: the template escapes, the script uses `textContent`. + * - Narrow screens: below 640 px each row becomes a stacked block (id and state, then app, partition and + * front door, then created and charged), each value labeled by `data-label`; DOM order is reading order. + * + * The styles are GLOBAL and prefixed `.compute-jobs` because the script builds rows in the browser, which + * Astro's scoped styles do not reach. + */ +import { COMPUTE_LABELS } from "../lib/compute-labels"; +import type { JobsView } from "../lib/compute-view"; +import ComputeBadge from "./ComputeBadge.astro"; +import ComputePanel from "./ComputePanel.astro"; + +interface Props { + view: JobsView; +} + +const { view } = Astro.props; +const L = COMPUTE_LABELS.jobs; +--- + + + {view.empty ? ( +

{L.empty}

+ ) : ( +
+ + + + + + + + + + + + + + {view.rows.map((row) => ( + + + + + + + + + + ))} + +
{L.job}{L.state}{L.app}{L.partition}{L.frontDoor}{L.created}{L.charged}
+ {row.href ? ( + {row.id} + ) : ( + {row.id} + )} + + + {row.cancelRequested && {L.cancelRequested}} + + {row.app}{" "}{row.appVersion} + {row.partition}{row.frontDoor} + + + {row.charged} +
+
+ )} + + + + +

+ +

+ {view.loadMoreHref && view.nextAfter && ( + {L.loadMore} + )} + {L.refresh} +

+
+ + + + diff --git a/src/components/ComputePanel.astro b/src/components/ComputePanel.astro new file mode 100644 index 00000000..2b434d72 --- /dev/null +++ b/src/components/ComputePanel.astro @@ -0,0 +1,40 @@ +--- +/** + * The card every /compute panel sits in: a titled section on the admin portal's card ground + * (`--admin-surface`, which the chart colors are checked against). The title is the section's + * accessible name. Panels fail independently, so each one is wrapped on its own. + */ +interface Props { + id: string; + title: string; + /** Extra attributes for the section, e.g. a data attribute a test or the browser check reads. */ + attrs?: Record; +} + +const { id, title, attrs = {} } = Astro.props; +--- + +
+

{title}

+ +
+ + diff --git a/src/components/ComputePanelNotice.astro b/src/components/ComputePanelNotice.astro new file mode 100644 index 00000000..15835057 --- /dev/null +++ b/src/components/ComputePanelNotice.astro @@ -0,0 +1,79 @@ +--- +/** + * What a /compute panel shows when its read (or its view builder) failed: an error icon, "Could not + * load ", the reason class, the backend's own sentence as inert text when it sent one, a line + * saying the figures are MISSING (which is not zero), and a way to try again. One failed panel never + * blanks the page. The text comes from `noticeFor` in `src/lib/compute-view.ts`. + * SYNC: the same shape as `admin/SectionErrorNotice.astro`; keep the two in step. + */ +import type { NoticeView } from "../lib/compute-view"; +import StatusIcon from "./admin/StatusIcon.astro"; + +interface Props { + notice: NoticeView; + /** Where "Try again" goes; defaults to the page itself. */ + retryHref?: string; + /** An extra link, e.g. back to the first page of jobs after a bad cursor. */ + extraLink?: { href: string; label: string }; + /** Drop "Try again" when `extraLink` is the better retry (a bad cursor would fail the same way). */ + hideRetry?: boolean; +} + +const { notice, retryHref = "/compute", extraLink, hideRetry = false } = Astro.props; +--- + +
+ +
+

{notice.title}

+

{notice.reason} {notice.missing}

+ {notice.sentence &&

{notice.sentence}

} +

+ {!hideRetry && {notice.retryLabel}} + {extraLink && {extraLink.label}} +

+
+
+ + diff --git a/src/components/ComputeQueueTable.astro b/src/components/ComputeQueueTable.astro new file mode 100644 index 00000000..5bd85f53 --- /dev/null +++ b/src/components/ComputeQueueTable.astro @@ -0,0 +1,87 @@ +--- +/** + * The "Recent queue waits" panel of /compute (active accounts only): per offered partition, the median + * and 90th percentile wait from scheduler submission to start over the last days, and how many jobs + * that rests on. A null figure reads "Not enough data" with the count beside it, never a dash and never + * zero; a real zero reads `0s`. The panel says what happened on the whole platform, never "your wait". + * Cells come from `queueView` in `src/lib/compute-view.ts`. + */ +import { COMPUTE_LABELS } from "../lib/compute-labels"; +import type { QueueView } from "../lib/compute-view"; +import ComputePanel from "./ComputePanel.astro"; + +interface Props { + view: QueueView; +} + +const { view } = Astro.props; +const L = COMPUTE_LABELS.queue; +--- + + +

{view.intro}

+ {view.empty ? ( +

{view.emptyText}

+ ) : ( +
+ + + + + + + + + + + {view.rows.map((row) => ( + + + + + + + ))} + +
{L.partition}{L.median}{L.p90}{L.counted}
{row.partition}{row.median}{row.p90}{row.counted}
+
+ )} +

{view.note}

+
+ + diff --git a/src/components/ComputeUsageChart.astro b/src/components/ComputeUsageChart.astro new file mode 100644 index 00000000..bbdbcc97 --- /dev/null +++ b/src/components/ComputeUsageChart.astro @@ -0,0 +1,343 @@ +--- +/** + * One pool's usage chart for /compute: a daily bar chart of net service units charged, each bar stacked + * by partition (website ADR 0007: hand-rolled SVG, every color a token, both themes equal, no chart + * library). Geometry comes from `computeUsageChart` and the text from `usageView`; this file only draws. + * + * Rendering follows `admin/MetricSparkline.astro`: the SVG holds only bars and gridlines and stretches to + * its container (`preserveAspectRatio="none"`, `vector-effect="non-scaling-stroke"` on lines). The AXIS + * LABELS are HTML positioned by percentage, so the text stays crisp and never scales down on a phone. + * Below 480 px only three x labels show (first, middle, last). + * + * Accessibility: a `
` with a `
`; the SVG is `role="img"` named by a `` and + * described by a `<desc>` that give the total, the number of days with charges and the busiest day; each + * bar carries a `<title>`. A real table of the same numbers sits in a `<details>`, NOT hidden, so a + * keyboard or low-vision user, or a copy of the page without CSS, still has the data. A segment is never + * told apart by color alone: the legend lists the series in stacking order with their totals. + * + * No animation or transition at all, so `prefers-reduced-motion` is satisfied by construction. + */ +import { COMPUTE_LABELS } from "../lib/compute-labels"; +import type { PoolUsageView } from "../lib/compute-view"; + +interface Props { + view: PoolUsageView; +} + +const { view } = Astro.props; +const { chart } = view; +const ids = { title: `compute-chart-${view.pool}-title`, desc: `compute-chart-${view.pool}-desc` }; +const lastX = chart.xLabels.regular.length - 1; +--- + +<figure class="compute-chart" data-compute-chart={view.pool}> + <figcaption class="compute-chart__caption">{view.caption}</figcaption> + + <ul class="compute-chart__legend" aria-label={`${view.name} series`}> + {view.legend.map((entry) => ( + <li class="compute-chart__legend-item"> + <span class={`compute-chart__swatch compute-chart__swatch--${entry.colorIndex + 1}`} aria-hidden="true" /> + <span>{entry.name}</span> + <span class="compute-chart__legend-total">{entry.totalText}</span> + </li> + ))} + </ul> + + <div class="compute-chart__plot"> + <div class="compute-chart__yaxis" aria-hidden="true"> + {chart.ticks.map((tick) => ( + <span class="compute-chart__ytick" style={`top: ${tick.topPercent}%`}>{tick.label}</span> + ))} + </div> + <div class="compute-chart__area"> + <svg + class="compute-chart__svg" + viewBox={`0 0 ${chart.viewBoxWidth} ${chart.viewBoxHeight}`} + preserveAspectRatio="none" + role="img" + aria-labelledby={`${ids.title} ${ids.desc}`} + > + <title id={ids.title}>{view.caption} + {view.summary} + {chart.ticks.map((tick) => ( + + ))} + {chart.days.map((bar, i) => + bar.segments.length > 0 ? ( + + {view.barTitles[i]} + {bar.segments.map((seg) => ( + + ))} + + ) : null, + )} + + {chart.empty &&

{COMPUTE_LABELS.usage.empty}

} + + + + + + {view.table.rows.length > 0 && ( +
+ {COMPUTE_LABELS.usage.showNumbers} +
+ + + + + {view.table.headers.map((h) => )} + + + + {view.table.rows.map((row) => ( + + + {row.cells.map((cell) => )} + + + ))} + +
{COMPUTE_LABELS.usage.numbersNote}
{h}
{row.label}{cell}{row.total}
+
+
+ )} + {view.negativeNote &&

{view.negativeNote}

} +
+ + diff --git a/src/components/UserMenu.astro b/src/components/UserMenu.astro index 9590f402..e353c195 100644 --- a/src/components/UserMenu.astro +++ b/src/components/UserMenu.astro @@ -1,4 +1,5 @@ --- +import { deriveComputeAccessState } from "../lib/account-tier"; import type { AuthSession } from "../lib/auth"; import { SIGN_IN_TITLE } from "../lib/copy"; @@ -8,6 +9,12 @@ interface Props { const { session } = Astro.props; const initial = session?.user?.email?.[0]?.toUpperCase() ?? "?"; +// Compute is in the menu for the states in which a person has, or had, a balance and jobs (website ADR +// 0030 phase E2). For `none`, `requested`, `denied` and an absent state it stays out: the Settings card +// is that person's way in. +const computeState = deriveComputeAccessState(session?.user)?.state; +const showCompute = + computeState === "active" || computeState === "suspended" || computeState === "revoked"; --- { @@ -46,6 +53,11 @@ const initial = session?.user?.email?.[0]?.toUpperCase() ?? "?";
  • My datasets
  • + {showCompute && ( +
  • + Compute +
  • + )}
  • Settings
  • diff --git a/src/lib/account-copy.test.ts b/src/lib/account-copy.test.ts index 305cf45a..53a39847 100644 --- a/src/lib/account-copy.test.ts +++ b/src/lib/account-copy.test.ts @@ -137,6 +137,39 @@ describe("compute access copy (nemar-cli 3a869903)", () => { }); }); +describe("compute page copy (nemar-cli epic #2021 phase E2)", () => { + /** The seven keys the `/compute` page added to nemar-cli's contract. */ + const PAGE_KEYS = [ + "compute_page.frozen.body", + "compute_page.units_note", + "compute_page.available_note", + "compute_page.queue_note", + "compute_page.usage_note", + "compute_page.unreported_note", + "compute_access.granted.link", + ] as const; + + it("has all seven keys, each a non-empty string with no placeholder", () => { + expect(PAGE_KEYS).toHaveLength(7); + for (const key of PAGE_KEYS) { + expect(Object.hasOwn(ACCOUNT_COPY, key), key).toBe(true); + expect(ACCOUNT_COPY[key].trim().length, key).toBeGreaterThan(0); + expect(ACCOUNT_COPY[key], key).not.toMatch(/\{\w+\}/); + } + }); + + it("says jobs are submitted with the command line, not from the website", () => { + // The epic builds no web submission; the sentence used to promise one. + expect(ACCOUNT_COPY["compute_access.granted.body"]).toContain("`nemar compute` command line"); + expect(ACCOUNT_COPY["compute_access.granted.body"]).not.toContain("from there"); + }); + + it("promises neither an allocation (the default may be zero) nor a human review", () => { + expect(ACCOUNT_COPY["compute_access.granted.body"]).not.toMatch(/allocation/i); + expect(ACCOUNT_COPY["compute_page.unreported_note"]).not.toMatch(/administrator|admin/i); + }); +}); + describe("what the copy must never say", () => { // The sentences these pages used to carry are the reason website#301 // existed: `pending` stopped meaning "an admin is looking at you", and diff --git a/src/lib/account-copy.ts b/src/lib/account-copy.ts index fbd5753d..f9897433 100644 --- a/src/lib/account-copy.ts +++ b/src/lib/account-copy.ts @@ -117,7 +117,7 @@ export const ACCOUNT_COPY = { // ------------------------------------------------------------------------- "compute_access.section.title": "Compute access", "compute_access.section.lede": - "A separate grant from upload access. An admin reviews each request against export-control and local-jurisdiction rules and the purpose you state, and a grant opens a starting allocation of service units.", + "A separate grant from upload access. An admin reviews each request against export-control and local-jurisdiction rules and the purpose you state, and a grant lets you use compute within the limits an administrator sets.", "compute_access.state.none": "Not requested", "compute_access.state.requested": "Requested", "compute_access.state.active": "Active", @@ -140,7 +140,8 @@ export const ACCOUNT_COPY = { "compute_access.requested.body": "We’ll email you when there’s a decision. Everything else on your account keeps working in the meantime.", "compute_access.granted.body": - "Compute access is active. Your starting allocation is on your compute page, and you can submit jobs from there or with `nemar compute`.", + "Compute access is active. Your balances are on your compute page, and you submit jobs with the `nemar compute` command line.", + "compute_access.granted.link": "Open your compute page", "compute_access.closed.body": "This request has been answered and cannot be asked again. If you think that is a mistake, contact support and an admin will take another look.", // A suspended account is not a request that was answered: its access exists and is paused. @@ -150,6 +151,24 @@ export const ACCOUNT_COPY = { "Compute access is not open yet: the compute terms are not published. Please check back later.", "compute_access.docs_link": "How compute access works", + // ------------------------------------------------------------------------- + // The compute page (`/compute`, website ADR 0030 phase E2, nemar-cli epic + // #2021 phase E2). The first two are also printed by `nemar compute + // balance`, so the two surfaces say one thing. Transcribed from nemar-cli + // `shared/contract/account-copy.ts`. + // ------------------------------------------------------------------------- + "compute_page.frozen.body": + "Your pools are frozen, so new jobs are refused. Contact support to find out why.", + "compute_page.units_note": "Amounts are service units (SU).", + "compute_page.available_note": + "Available is granted minus held minus charged and can be negative after an overrun.", + "compute_page.queue_note": + "It describes the queue of the whole platform, not yours, and it is a recent average, not a promise.", + "compute_page.usage_note": + "Net charge by UTC day of the charge, not the day a job was created. A day with no charge has no bar.", + "compute_page.unreported_note": + "NEMAR has not heard from the cluster about this job for a while. It may still finish.", + // ------------------------------------------------------------------------- // Profile gaps: the sentence, its two halves, and the vocabulary they use // diff --git a/src/lib/compute-api.test.ts b/src/lib/compute-api.test.ts new file mode 100644 index 00000000..a2d86a0b --- /dev/null +++ b/src/lib/compute-api.test.ts @@ -0,0 +1,422 @@ +/** + * The compute read client. Every success case parses a body captured from the real routes: + * + * NEMAR_CLI_DIR= \ + * bun scripts/capture-compute-read-fixtures.mjs + * + * The transport conditions that no route can be made to produce (a 502 with no JSON, a timeout, a + * refused connection) use a real `Response` or a real aborted signal, which the repo's rule allows for + * failure paths. + */ +import { describe, expect, it } from "vitest"; +import errors from "../../test/fixtures/compute/errors.json"; +import jobsAll from "../../test/fixtures/compute/jobs-all-states.json"; +import jobsEmpty from "../../test/fixtures/compute/jobs-empty.json"; +import jobsPage1 from "../../test/fixtures/compute/jobs-page1.json"; +import jobsPage2 from "../../test/fixtures/compute/jobs-page2.json"; +import meActive from "../../test/fixtures/compute/me-active-with-usage.json"; +import meOverrun from "../../test/fixtures/compute/me-overrun.json"; +import meStates from "../../test/fixtures/compute/me-states.json"; +import meThin from "../../test/fixtures/compute/me-thin-queue.json"; +import usageDay from "../../test/fixtures/compute/usage-day-partition.json"; +import usageEmpty from "../../test/fixtures/compute/usage-empty.json"; +import { + ComputeApiError, + computeUrl, + getComputeMe, + getComputeUsage, + listComputeJobs, + parseComputeJobs, + parseComputeMe, + parseComputeUsage, +} from "./compute-api"; + +const json = (body: unknown, status = 200): Response => + new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } }); + +/** A fetch that answers one fixed Response and remembers the request. */ +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 }; +} + +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"); +} + +type Body = typeof meActive.body; + +describe("GET /compute/me", () => { + it("parses every captured access state", () => { + for (const state of [ + "none", + "requested", + "active", + "suspended", + "denied", + "revoked", + ] as const) { + const me = parseComputeMe(meStates[state].body); + expect(me.access.state).toBe(state); + expect(me.pools.cpu.granted_milli).toBe(0); + expect(me.queue.length).toBeGreaterThan(0); + } + }); + + it("keeps requests_open when sent and leaves it out when absent", () => { + expect(parseComputeMe(meStates.none.body).access.requests_open).toBe(false); + expect(parseComputeMe(meStates.none_requests_open.body).access.requests_open).toBe(true); + const { requests_open: _drop, ...access } = meStates.none.body.access; + const without = parseComputeMe({ ...meStates.none.body, access }); + expect("requests_open" in without.access).toBe(false); + }); + + it("parses balances exactly, a hold included", () => { + const me = parseComputeMe(meActive.body); + expect(me.pools.cpu).toEqual({ + granted_milli: 100_000, + held_milli: 20_000, + charged_milli: 40_200, + available_milli: 39_800, + }); + expect(me.frozen).toBe(false); + expect(me.partitions.map((p) => p.name)).toEqual([ + "shared", + "compute", + "debug", + "gpu-shared", + "gpu", + "gpu-debug", + ]); + }); + + it("keeps a negative available_milli negative", () => { + expect(parseComputeMe(meOverrun.body).pools.cpu.available_milli).toBe(-2_500); + }); + + it("keeps null queue figures null, with the count", () => { + const me = parseComputeMe(meThin.body); + const compute = me.queue.find((q) => q.partition === "compute"); + expect(compute).toMatchObject({ median_seconds: null, p90_seconds: null, count: 3 }); + expect(me.queue.find((q) => q.partition === "shared")?.median_seconds).toBe(30); + }); + + it("keeps a zero-second figure as 0, which is not null", () => { + const me = parseComputeMe(meActive.body); + expect(me.queue.find((q) => q.partition === "gpu-shared")?.median_seconds).toBe(0); + }); + + it("drops a pool the Worker adds and any key it does not read", () => { + const body = { + ...meActive.body, + pools: { + ...meActive.body.pools, + tenant: { granted_milli: 9, held_milli: 0, charged_milli: 0, available_milli: 9 }, + }, + platform_remaining_milli: 123, + extra: { anything: true }, + }; + const me = parseComputeMe(body); + expect(Object.keys(me.pools)).toEqual(["cpu", "gpu"]); + expect(Object.keys(me)).toEqual(["access", "pools", "frozen", "partitions", "queue"]); + expect(JSON.stringify(me)).not.toContain("tenant"); + expect(JSON.stringify(me)).not.toContain("platform_remaining"); + }); + + it("passes a state word it has never seen", () => { + const body = { ...meActive.body, access: { ...meActive.body.access, state: "paused" } }; + expect(parseComputeMe(body).access.state).toBe("paused"); + }); + + it.each([ + ["a missing gpu pool", (b: Body) => ({ ...b, pools: { cpu: b.pools.cpu } })], + [ + "a float amount", + (b: Body) => ({ ...b, pools: { ...b.pools, cpu: { ...b.pools.cpu, held_milli: 1.5 } } }), + ], + [ + "a string amount", + (b: Body) => ({ ...b, pools: { ...b.pools, cpu: { ...b.pools.cpu, granted_milli: "100" } } }), + ], + [ + "a negative granted amount", + (b: Body) => ({ ...b, pools: { ...b.pools, cpu: { ...b.pools.cpu, granted_milli: -1 } } }), + ], + [ + "an unsafe integer", + (b: Body) => ({ + ...b, + pools: { ...b.pools, cpu: { ...b.pools.cpu, charged_milli: 2 ** 60 } }, + }), + ], + ["frozen not a boolean", (b: Body) => ({ ...b, frozen: "no" })], + ["queue not an array", (b: Body) => ({ ...b, queue: {} })], + [ + "a queue count missing", + (b: Body) => ({ + ...b, + queue: [{ partition: "shared", median_seconds: 1, p90_seconds: 2, window_days: 7 }], + }), + ], + [ + "a negative queue figure", + (b: Body) => ({ ...b, queue: [{ ...b.queue[0], median_seconds: -1 }] }), + ], + [ + "requests_open a string", + (b: Body) => ({ ...b, access: { ...b.access, requests_open: "yes" } }), + ], + ["access missing", (b: Body) => ({ ...b, access: null })], + ["a body that is a list", () => []], + ])("rejects %s as a shape error, never as zeros", (_name, mutate) => { + expect(() => parseComputeMe(mutate(structuredClone(meActive.body)))).toThrow(ComputeApiError); + try { + parseComputeMe(mutate(structuredClone(meActive.body))); + } catch (err) { + expect((err as ComputeApiError).kind).toBe("shape"); + } + }); +}); + +describe("GET /compute/me/usage", () => { + it("parses the captured rows, a correction's null partition included", () => { + const usage = parseComputeUsage(usageDay.body); + expect(usage.from).toBe("2026-10-09"); + expect(usage.to).toBe("2026-11-07"); + expect(usage.rows).toHaveLength(usageDay.body.rows.length); + expect(usage.rows.find((r) => r.partition === null)?.charged_milli).toBe(1_750); + expect(usage.rows.find((r) => r.charged_milli < 0)?.charged_milli).toBe(-300); + }); + + it("returns an empty list only for a body that says rows is empty", () => { + expect(parseComputeUsage(usageEmpty.body).rows).toEqual([]); + expect(() => parseComputeUsage({ ...usageEmpty.body, rows: undefined })).toThrow( + ComputeApiError, + ); + expect(() => parseComputeUsage({ ...usageEmpty.body, rows: "none" })).toThrow(ComputeApiError); + }); + + it("rejects a grouping without day and partition, and an unsafe or float amount", () => { + expect(() => parseComputeUsage({ ...usageDay.body, group: ["day"] })).toThrow(ComputeApiError); + const row = { ...usageDay.body.rows[0], charged_milli: 1.5 }; + expect(() => parseComputeUsage({ ...usageDay.body, rows: [row] })).toThrow(ComputeApiError); + }); + + it("asks for group=day,partition and no window, so the server's default window rules", async () => { + const { fn, seen } = answering(json(usageDay.body)); + const usage = await getComputeUsage({ fetch: fn }); + expect(usage.rows.length).toBeGreaterThan(0); + expect(seen[0].url).toBe("/api/v1/compute/me/usage?group=day%2Cpartition"); + expect(seen[0].url).not.toContain("from="); + }); +}); + +describe("GET /compute/me/jobs", () => { + it("parses a page and its cursor", () => { + const page = parseComputeJobs(jobsPage1.body); + expect(page.jobs).toHaveLength(2); + expect(page.next_after).toBe(jobsPage1.body.next_after); + expect(page.jobs[0]).toMatchObject({ kind: "batch", cancel_requested: false }); + }); + + it("parses the last page, whose cursor is null", () => { + expect(parseComputeJobs(jobsEmpty.body)).toEqual({ jobs: [], next_after: null }); + expect(parseComputeJobs(jobsPage2.body).jobs).toHaveLength(2); + }); + + it("parses one job in each of the ten states and keeps cancel_requested", () => { + const page = parseComputeJobs(jobsAll.body); + const states = new Set(page.jobs.map((j) => j.state)); + for (const s of [ + "created", + "uploading", + "submitted", + "queued", + "running", + "archiving", + "finished", + "failed", + "cancelled", + "unreported", + ]) { + expect(states.has(s), s).toBe(true); + } + expect(page.jobs.some((j) => j.cancel_requested)).toBe(true); + }); + + it("copies only the keys the page reads", () => { + const page = parseComputeJobs(jobsPage1.body); + expect(Object.keys(page.jobs[0]).sort()).toEqual( + [ + "id", + "kind", + "source", + "state", + "app_id", + "app_version", + "partition", + "pool", + "created_at", + "started_at", + "ended_at", + "charged_milli", + "failure_code", + "cancel_requested", + ].sort(), + ); + }); + + it("treats an empty jobs list as different from a rejected body", () => { + expect(parseComputeJobs(jobsEmpty.body).jobs).toEqual([]); + for (const bad of [ + { jobs: "none", next_after: null }, + { next_after: null }, + { jobs: [] }, // next_after absent: not 'last page' + { jobs: [{ ...jobsPage1.body.jobs[0], charged_milli: 1.5 }], next_after: null }, + { jobs: [{ ...jobsPage1.body.jobs[0], cancel_requested: "no" }], next_after: null }, + { jobs: [{ ...jobsPage1.body.jobs[0], id: 7 }], next_after: null }, + { jobs: [{ ...jobsPage1.body.jobs[0], started_at: undefined }], next_after: null }, + ]) { + expect(() => parseComputeJobs(bad)).toThrow(ComputeApiError); + } + }); + + it("builds the URL, and an after cursor containing | round-trips exactly", async () => { + const cursor = jobsPage1.body.next_after as string; + expect(cursor).toContain("|"); + const { fn, seen } = answering(json(jobsPage2.body)); + await listComputeJobs({ after: cursor }, { fetch: fn }); + const url = new URL(seen[0].url, "http://x.test"); + expect(url.pathname).toBe("/api/v1/compute/me/jobs"); + expect(url.searchParams.get("limit")).toBe("25"); + expect(url.searchParams.get("after")).toBe(cursor); + expect(seen[0].url).toContain("%7C"); + }); + + it("refuses a limit the route would refuse, before sending", () => { + for (const limit of [0, 101, 1.5, -1]) { + expect(() => listComputeJobs({ limit })).toThrow(RangeError); + } + }); +}); + +describe("where the call goes", () => { + it("uses the proxy in the browser and the API directly with a cookie", () => { + expect(computeUrl("/me", new URLSearchParams())).toBe("/api/v1/compute/me"); + expect(computeUrl("/me", new URLSearchParams(), "nemar_session=abc")).toMatch( + /^https?:\/\/.+\/compute\/me$/, + ); + }); + + it("sends the visitor's cookie on the SSR path and asks for JSON", async () => { + const { fn, seen } = answering(json(meActive.body)); + await getComputeMe({ fetch: fn, cookieHeader: "nemar_session=abc" }); + expect((seen[0].init.headers as Record).Cookie).toBe("nemar_session=abc"); + expect((seen[0].init.headers as Record).Accept).toBe("application/json"); + expect(seen[0].init.method).toBe("GET"); + }); +}); + +describe("errors", () => { + it("maps no session to `session`", async () => { + const { fn } = answering(json(errors.no_credential.body, 401)); + const err = await failure(getComputeMe({ fetch: fn })); + expect(err).toMatchObject({ kind: "session", status: 401 }); + }); + + it("maps an unapproved account to `account` with the backend's message", async () => { + const { fn } = answering(json(errors.account_not_approved.body, 403)); + const err = await failure(getComputeMe({ fetch: fn })); + expect(err.kind).toBe("account"); + expect(err.sentence).toBe(errors.account_not_approved.body.message); + }); + + it.each([ + ["invalid_cursor", 400], + ["invalid_limit", 400], + ["invalid_state", 400], + ["invalid_group", 400], + ["invalid_range", 400], + ] as const)("reads %s from `code` and the sentence from `error`", async (code, status) => { + const body = errors[code].body; + const { fn } = answering(json(body, status)); + const err = await failure(getComputeMe({ fetch: fn })); + expect(err.kind).toBe("rejected"); + expect(err.code).toBe(code); + expect(err.sentence).toBe(body.error); + }); + + it("maps a 404 and a 5xx to `unavailable`", async () => { + expect( + (await failure(getComputeMe({ fetch: answering(json({ error: "not_found" }, 404)).fn }))) + .kind, + ).toBe("unavailable"); + expect( + (await failure(getComputeMe({ fetch: answering(json({ error: "boom" }, 500)).fn }))).kind, + ).toBe("unavailable"); + }); + + it("maps policy_unavailable (503) to `unavailable` and keeps the code", async () => { + const body = { error: "The policy could not be read.", code: "policy_unavailable" }; + const err = await failure(getComputeMe({ fetch: answering(json(body, 503)).fn })); + expect(err).toMatchObject({ kind: "unavailable", code: "policy_unavailable", status: 503 }); + }); + + it("takes a proxy transport word as a code, not as a sentence to show", async () => { + const err = await failure( + getComputeMe({ fetch: answering(json({ error: "upstream_unreachable" }, 502)).fn }), + ); + expect(err.kind).toBe("unavailable"); + expect(err.code).toBe("upstream_unreachable"); + expect(err.sentence).toBeUndefined(); + }); + + it("survives a 502 with no JSON body", async () => { + const res = new Response("Bad gateway", { status: 502 }); + const err = await failure(getComputeMe({ fetch: answering(res).fn })); + expect(err).toMatchObject({ kind: "unavailable", status: 502 }); + expect(err.sentence).toBeUndefined(); + }); + + it("maps a 200 that is not JSON to `shape`", async () => { + const res = new Response("not json", { status: 200 }); + expect((await failure(getComputeMe({ fetch: answering(res).fn }))).kind).toBe("shape"); + }); + + it("maps a 200 with a wrong body to `shape`", async () => { + const err = await failure(getComputeMe({ fetch: answering(json({ pools: [] })).fn })); + expect(err.kind).toBe("shape"); + }); + + it("maps a refused connection to `network` and a missed deadline to `timeout`", async () => { + const refused = (async () => { + throw new TypeError("fetch failed"); + }) as unknown as typeof fetch; + expect((await failure(getComputeMe({ fetch: refused }))).kind).toBe("network"); + const slow = ((_url: string, init: RequestInit) => + new Promise((_resolve, reject) => { + init.signal?.addEventListener("abort", () => reject(init.signal?.reason)); + })) as unknown as typeof fetch; + expect((await failure(getComputeMe({ fetch: slow, timeoutMs: 5 }))).kind).toBe("timeout"); + }); + + it("lets a caller's own abort through untouched", async () => { + const controller = new AbortController(); + controller.abort(); + const aborted = ((_url: string, init: RequestInit) => + Promise.reject(init.signal?.reason)) as unknown as typeof fetch; + await expect( + getComputeMe({ fetch: aborted, signal: controller.signal }), + ).rejects.not.toBeInstanceOf(ComputeApiError); + }); +}); diff --git a/src/lib/compute-api.ts b/src/lib/compute-api.ts new file mode 100644 index 00000000..5e3ebc11 --- /dev/null +++ b/src/lib/compute-api.ts @@ -0,0 +1,417 @@ +/** + * Compute read client: `GET /compute/me`, `/compute/me/usage` and `/compute/me/jobs` (website ADR 0030 + * phase E2 addendum; nemar-cli `shared/contract/compute-user.ts`). All three answer for every access + * state and with compute switched off, because they read the ledger and the job index. + * + * Browser-safe: this module imports nothing from `./api-fetch.ts` (which pulls in a Node module the + * browser bundle must not carry; `test/client-bundle-guard.test.ts`). SSR callers pass + * `{ cookieHeader, fetch: apiFetch }`; browser callers pass nothing and go through the same-origin + * `/api/v1` proxy, which forwards the session cookie. + * + * Three rules shape the parsers: + * - A body the guard rejects is a `shape` error, NEVER an empty list or zeros. The page then says the + * figures are missing, which is not the same as zero. + * - The guards are tolerant of extra keys and unknown words (the contract schemas are open) and strict + * about the type of every key the page reads. They copy out ONLY those keys, so a key the Worker adds + * later, or a pool it did not announce, cannot reach the markup by iteration. In particular only + * `pools.cpu` and `pools.gpu` are read, by name. + * - On these routes the sentence is in `error` and the machine word in `code`, the reverse of what + * `readError` in `./api-base.ts` assumes, so this client has its own error parser. + */ +import { dashboardApiBase } from "./api-base"; +import { COMPUTE_JOBS_PAGE_DEFAULT, COMPUTE_JOBS_PAGE_MAX } from "./compute-contract"; +import { DEFAULT_REQUEST_TIMEOUT_MS, resolveSignal } from "./request-deadline"; + +// --- Errors --------------------------------------------------------------------------------------- + +/** + * What kind of failure it was, which decides what the page says: + * `session` (401: sign in again), `account` (403: the account is not active; `sentence` is the + * backend's message), `unavailable` (404, 5xx or `policy_unavailable`: the server cannot answer now), + * `rejected` (another 4xx: the request was refused, with its `code`), `timeout`, `network`, and + * `shape` (the answer was not the contract's). + */ +export type ComputeErrorKind = + | "session" + | "account" + | "unavailable" + | "rejected" + | "timeout" + | "network" + | "shape"; + +export class ComputeApiError extends Error { + constructor( + readonly kind: ComputeErrorKind, + readonly status: number, + readonly code?: string, + readonly sentence?: string, + ) { + super(sentence ?? `compute read failed: ${kind} (${status})`); + this.name = "ComputeApiError"; + } +} + +const TRANSPORT_WORD = /^[a-z][a-z0-9_]*$/; + +interface ErrorBody { + readonly code?: string; + readonly sentence?: string; +} + +/** + * Reads `{ error: , code: }`, and the 403 `{ error, status, message }` shape. Neutral by + * name and exported so the admin compute tab reads the same envelope with the same function. + */ +export async function readComputeError(res: Response): Promise { + let body: unknown; + try { + body = await res.json(); + } catch { + return {}; + } + if (!body || typeof body !== "object" || Array.isArray(body)) return {}; + const { error, code, message } = body as Record; + const word = typeof code === "string" && TRANSPORT_WORD.test(code) ? code : undefined; + // The 403 "Account not approved" shape carries the explanation in `message`. + if (typeof message === "string" && message.trim().length > 0) { + return { code: word, sentence: message }; + } + if (typeof error === "string" && error.trim().length > 0) { + // The proxy answers with a bare word (`upstream_unreachable`): that is a code, not a sentence. + if (TRANSPORT_WORD.test(error)) return { code: word ?? error }; + return { code: word, sentence: error }; + } + return { code: word }; +} + +function kindOf(status: number, code: string | undefined): ComputeErrorKind { + if (status === 401) return "session"; + if (status === 403) return "account"; + if (status === 404 || status >= 500 || code === "policy_unavailable") return "unavailable"; + return "rejected"; +} + +// --- Shapes --------------------------------------------------------------------------------------- + +export interface ComputePool { + readonly granted_milli: number; + readonly held_milli: number; + readonly charged_milli: number; + /** May be negative: an overrun, or a grant corrected below what is used. */ + readonly available_milli: number; +} + +export interface ComputeAccess { + /** A string: today one of six, but the page decides nothing the backend did not state. */ + readonly state: string; + readonly requested_at: string | null; + readonly granted_at: string | null; + readonly terms_version: string | null; + readonly current_terms_version: string; + readonly terms_published: boolean; + readonly requests_open?: boolean; +} + +export interface ComputeQueueEstimate { + readonly partition: string; + readonly median_seconds: number | null; + readonly p90_seconds: number | null; + readonly count: number; + readonly window_days: number; +} + +export interface ComputeMe { + readonly access: ComputeAccess; + /** Exactly these two, by name. */ + readonly pools: { readonly cpu: ComputePool; readonly gpu: ComputePool }; + readonly frozen: boolean; + /** The partitions offered to people, with the pool each draws on. */ + readonly partitions: readonly { readonly name: string; readonly pool: string }[]; + readonly queue: readonly ComputeQueueEstimate[]; +} + +export interface ComputeUsageRow { + readonly day: string; + readonly partition: string | null; + readonly charged_milli: number; + readonly jobs: number; +} + +export interface ComputeUsage { + readonly from: string; + readonly to: string; + readonly rows: readonly ComputeUsageRow[]; +} + +export interface ComputeJob { + readonly id: string; + readonly kind: string; + readonly source: string; + readonly state: string; + readonly app_id: string; + readonly app_version: string; + readonly partition: string; + readonly pool: string; + readonly created_at: string; + readonly started_at: string | null; + readonly ended_at: string | null; + readonly charged_milli: number; + readonly failure_code: string | null; + readonly cancel_requested: boolean; +} + +export interface ComputeJobsPage { + readonly jobs: readonly ComputeJob[]; + /** The cursor for the next page, opaque to the client; null on the last page. */ + readonly next_after: string | null; +} + +// --- Guards --------------------------------------------------------------------------------------- + +function shape(what: string): never { + // The detail is for the log; the page shows the reason class, not this. + throw new ComputeApiError("shape", 200, undefined, `unexpected ${what}`); +} + +function record(value: unknown, what: string): Record { + if (value === null || typeof value !== "object" || Array.isArray(value)) shape(what); + return value as Record; +} + +function str(o: Record, key: string, what: string): string { + const v = o[key]; + if (typeof v !== "string") shape(`${what} ${key}`); + return v as string; +} + +function nullableStr(o: Record, key: string, what: string): string | null { + const v = o[key]; + if (v === null) return null; + if (typeof v !== "string") shape(`${what} ${key}`); + return v as string; +} + +function bool(o: Record, key: string, what: string): boolean { + const v = o[key]; + if (typeof v !== "boolean") shape(`${what} ${key}`); + return v as boolean; +} + +function integer( + o: Record, + key: string, + what: string, + nonNegative = true, +): number { + const v = o[key]; + if (typeof v !== "number" || !Number.isSafeInteger(v) || (nonNegative && v < 0)) { + shape(`${what} ${key}`); + } + return v as number; +} + +function nullableInteger(o: Record, key: string, what: string): number | null { + if (o[key] === null) return null; + return integer(o, key, what); +} + +function array(o: Record, key: string, what: string): unknown[] { + const v = o[key]; + if (!Array.isArray(v)) shape(`${what} ${key}`); + return v as unknown[]; +} + +function pool(value: unknown, which: string): ComputePool { + const o = record(value, `${which} pool`); + return { + granted_milli: integer(o, "granted_milli", which), + held_milli: integer(o, "held_milli", which), + charged_milli: integer(o, "charged_milli", which), + available_milli: integer(o, "available_milli", which, false), + }; +} + +/** `GET /compute/me`, copied out key by key. */ +export function parseComputeMe(body: unknown): ComputeMe { + const root = record(body, "compute account"); + const access = record(root.access, "access"); + const pools = record(root.pools, "pools"); + const limits = record(root.limits, "limits"); + const requestsOpen = access.requests_open; + if (requestsOpen !== undefined && typeof requestsOpen !== "boolean") + shape("access requests_open"); + return { + access: { + state: str(access, "state", "access"), + requested_at: nullableStr(access, "requested_at", "access"), + granted_at: nullableStr(access, "granted_at", "access"), + terms_version: nullableStr(access, "terms_version", "access"), + current_terms_version: str(access, "current_terms_version", "access"), + terms_published: bool(access, "terms_published", "access"), + ...(requestsOpen === undefined ? {} : { requests_open: requestsOpen }), + }, + // By name, never by iteration: a pool the Worker adds later is not this page's to draw. + pools: { cpu: pool(pools.cpu, "cpu"), gpu: pool(pools.gpu, "gpu") }, + frozen: bool(root, "frozen", "account"), + partitions: array(limits, "partitions", "limits").map((p) => { + const o = record(p, "partition"); + return { name: str(o, "name", "partition"), pool: str(o, "pool", "partition") }; + }), + queue: array(root, "queue", "account").map((q) => { + const o = record(q, "queue estimate"); + return { + partition: str(o, "partition", "queue"), + median_seconds: nullableInteger(o, "median_seconds", "queue"), + p90_seconds: nullableInteger(o, "p90_seconds", "queue"), + count: integer(o, "count", "queue"), + window_days: integer(o, "window_days", "queue"), + }; + }), + }; +} + +/** `GET /compute/me/usage?group=day,partition`, copied out key by key. */ +export function parseComputeUsage(body: unknown): ComputeUsage { + const root = record(body, "usage"); + const group = array(root, "group", "usage"); + if (!group.includes("day") || !group.includes("partition")) shape("usage grouping"); + return { + from: str(root, "from", "usage"), + to: str(root, "to", "usage"), + rows: array(root, "rows", "usage").map((r) => { + const o = record(r, "usage row"); + return { + day: str(o, "day", "usage row"), + partition: nullableStr(o, "partition", "usage row"), + charged_milli: integer(o, "charged_milli", "usage row", false), + jobs: integer(o, "jobs", "usage row"), + }; + }), + }; +} + +function job(value: unknown): ComputeJob { + const o = record(value, "job"); + return { + id: str(o, "id", "job"), + kind: str(o, "kind", "job"), + source: str(o, "source", "job"), + state: str(o, "state", "job"), + app_id: str(o, "app_id", "job"), + app_version: str(o, "app_version", "job"), + partition: str(o, "partition", "job"), + pool: str(o, "pool", "job"), + created_at: str(o, "created_at", "job"), + started_at: nullableStr(o, "started_at", "job"), + ended_at: nullableStr(o, "ended_at", "job"), + charged_milli: integer(o, "charged_milli", "job"), + failure_code: nullableStr(o, "failure_code", "job"), + cancel_requested: bool(o, "cancel_requested", "job"), + }; +} + +/** `GET /compute/me/jobs`. `next_after` must be present: its absence is a shape error, not "last page". */ +export function parseComputeJobs(body: unknown): ComputeJobsPage { + const root = record(body, "job list"); + if (!("next_after" in root)) shape("job list next_after"); + return { + jobs: array(root, "jobs", "job list").map(job), + next_after: nullableStr(root, "next_after", "job list"), + }; +} + +// --- Transport ------------------------------------------------------------------------------------ + +export interface ComputeInit { + readonly signal?: AbortSignal; + /** `fetch`, or `apiFetch` on the server (it takes a string or a URL). */ + readonly fetch?: (input: string, init?: RequestInit) => Promise; + /** SSR: the visitor's `Cookie` header. Absent in the browser, which uses the `/api/v1` proxy. */ + readonly cookieHeader?: string; + readonly timeoutMs?: number; +} + +/** The URL of a read route, from the SSR base or the same-origin proxy. */ +export function computeUrl(path: string, query: URLSearchParams, cookieHeader?: string): string { + const qs = query.toString(); + return `${dashboardApiBase(cookieHeader)}/compute${path}${qs ? `?${qs}` : ""}`; +} + +async function computeGet( + path: string, + query: URLSearchParams, + init: ComputeInit, + parse: (body: unknown) => T, +): Promise { + const fetchImpl = init.fetch ?? fetch; + const headers: Record = { Accept: "application/json" }; + if (init.cookieHeader) headers.Cookie = init.cookieHeader; + let res: Response; + try { + res = await fetchImpl(computeUrl(path, query, init.cookieHeader), { + method: "GET", + headers, + credentials: "include", + signal: resolveSignal( + { signal: init.signal, timeoutMs: init.timeoutMs }, + DEFAULT_REQUEST_TIMEOUT_MS, + ), + }); + } catch (err) { + if (err instanceof DOMException && err.name === "TimeoutError") { + throw new ComputeApiError("timeout", 0); + } + if (err instanceof DOMException && err.name === "AbortError") throw err; + throw new ComputeApiError("network", 0); + } + if (!res.ok) { + const { code, sentence } = await readComputeError(res); + throw new ComputeApiError(kindOf(res.status, code), res.status, code, sentence); + } + let body: unknown; + try { + body = await res.json(); + } catch { + throw new ComputeApiError("shape", res.status, undefined, "unreadable body"); + } + return parse(body); +} + +/** The caller's access, balances, partitions and queue estimates. Answers in every access state. */ +export function getComputeMe(init: ComputeInit = {}): Promise { + return computeGet("/me", new URLSearchParams(), init, parseComputeMe); +} + +/** + * The net charge by UTC day and partition. No `from`/`to`: the server's default window (the 30 days + * ending today, UTC) is authoritative, and the chart's axis comes from the answer's own `from` and `to`. + */ +export function getComputeUsage(init: ComputeInit = {}): Promise { + return computeGet( + "/me/usage", + new URLSearchParams({ group: "day,partition" }), + init, + parseComputeUsage, + ); +} + +export interface ListComputeJobsInput { + /** The opaque `next_after` of the previous page. Passed back unchanged, URL-encoded by the query. */ + readonly after?: string | null; + readonly limit?: number; +} + +/** One page of the caller's jobs, newest first, from every front door. */ +export function listComputeJobs( + input: ListComputeJobsInput = {}, + init: ComputeInit = {}, +): Promise { + const limit = input.limit ?? COMPUTE_JOBS_PAGE_DEFAULT; + if (!Number.isInteger(limit) || limit < 1 || limit > COMPUTE_JOBS_PAGE_MAX) { + throw new RangeError("limit is a whole number from 1 to 100"); + } + const query = new URLSearchParams({ limit: String(limit) }); + if (input.after) query.set("after", input.after); + return computeGet("/me/jobs", query, init, parseComputeJobs); +} diff --git a/src/lib/compute-badges.test.ts b/src/lib/compute-badges.test.ts new file mode 100644 index 00000000..7ecd9b9f --- /dev/null +++ b/src/lib/compute-badges.test.ts @@ -0,0 +1,82 @@ +import { describe, expect, it } from "vitest"; +import { COMPUTE_BADGE_TONES_IN_USE, jobBadge, sourceLabel } from "./compute-badges"; +import { COMPUTE_JOB_SOURCES, COMPUTE_JOB_STATES } from "./compute-contract"; + +describe("jobBadge", () => { + it.each([ + ["created", "Created", "neutral", "neutral"], + ["uploading", "Uploading", "info", "progress"], + ["submitted", "Submitted", "info", "progress"], + ["queued", "Queued", "info", "progress"], + ["running", "Running", "info", "progress"], + ["archiving", "Archiving", "info", "progress"], + ["finished", "Finished", "success", "ok"], + ["failed", "Failed", "danger", "error"], + ["cancelled", "Canceled", "neutral", "neutral"], + ["unreported", "Unreported", "warning", "warn"], + ])("%s reads %s as %s with the %s icon", (state, label, tone, icon) => { + expect(jobBadge(state)).toEqual({ label, tone, icon, known: true }); + }); + + it("covers every state the contract lists", () => { + for (const state of COMPUTE_JOB_STATES) expect(jobBadge(state).known, state).toBe(true); + }); + + it("uses five tones, and no two tones share an icon", () => { + expect([...COMPUTE_BADGE_TONES_IN_USE].sort()).toEqual([ + "danger", + "info", + "neutral", + "success", + "warning", + ]); + const icons = COMPUTE_BADGE_TONES_IN_USE.map((tone) => { + const state = COMPUTE_JOB_STATES.find((s) => jobBadge(s).tone === tone) as string; + return jobBadge(state).icon; + }); + expect(new Set(icons).size).toBe(icons.length); + }); + + it("renders a state this build does not know as its raw word in a neutral pill", () => { + expect(jobBadge("paused")).toEqual({ + label: "paused", + tone: "neutral", + icon: "neutral", + known: false, + }); + }); + + it("does not mistake an object key for a state", () => { + for (const word of ["constructor", "__proto__", "toString", "hasOwnProperty"]) { + const badge = jobBadge(word); + expect(badge.known, word).toBe(false); + expect(badge.label, word).toBe(word); + expect(badge.tone, word).toBe("neutral"); + } + }); + + it("escapes control and direction characters in an unknown word", () => { + expect(jobBadge("a‮b\u0007").label).toBe("a\\u202eb\\x07"); + }); + + it("gives an empty word a defined answer", () => { + expect(jobBadge("").label).toBe("Unknown"); + }); +}); + +describe("sourceLabel", () => { + it("has plain words for the four front doors, and none says who pays", () => { + expect(COMPUTE_JOB_SOURCES.map(sourceLabel)).toEqual([ + "Command line", + "Website", + "Partner site", + "NEMAR pipeline", + ]); + }); + + it("prints a source it does not know as the escaped raw word", () => { + expect(sourceLabel("robot")).toBe("robot"); + expect(sourceLabel("constructor")).toBe("constructor"); + expect(sourceLabel("x‮")).toBe("x\\u202e"); + }); +}); diff --git a/src/lib/compute-badges.ts b/src/lib/compute-badges.ts new file mode 100644 index 00000000..d0ffb7c1 --- /dev/null +++ b/src/lib/compute-badges.ts @@ -0,0 +1,79 @@ +/** + * Labels, tones and icons for a compute job's state, and the words for its front door (website ADR 0030 + * phase E2 addendum). Built on `./admin-badges.ts`, whose lookups give a neutral raw-text pill for a + * value this build has no entry for: the website and the API deploy independently, so a state the API + * grows is a normal condition, not a bug. The raw word still goes through `displaySafeLine` so a strange + * one cannot carry a control or direction character into the pill. + * + * Five tones are in use (neutral, info, success, danger, warning). Each has its own icon shape and the + * word itself, so a state is never carried by color alone. + */ +import { type BadgeTone, badgeIcon, badgeLabel, badgeTone } from "./admin-badges"; +import type { ComputeJobSource, ComputeJobState } from "./compute-contract"; +import { displaySafeLine } from "./mail-display"; +import type { IconName } from "./status-icons"; + +export const COMPUTE_STATE_LABELS: Readonly> = { + created: "Created", + uploading: "Uploading", + submitted: "Submitted", + queued: "Queued", + running: "Running", + archiving: "Archiving", + finished: "Finished", + failed: "Failed", + cancelled: "Canceled", + unreported: "Unreported", +}; + +export const COMPUTE_STATE_TONES: Readonly> = { + created: "neutral", + uploading: "info", + submitted: "info", + queued: "info", + running: "info", + archiving: "info", + finished: "success", + failed: "danger", + cancelled: "neutral", + unreported: "warning", +}; + +export interface JobBadge { + readonly label: string; + readonly tone: BadgeTone; + readonly icon: IconName; + /** False for a state this build has no entry for: the pill then carries the raw word. */ + readonly known: boolean; +} + +/** The pill for a job state; a neutral raw-text pill for a state this build does not know. */ +export function jobBadge(state: string): JobBadge { + const known = Object.hasOwn(COMPUTE_STATE_LABELS, state); + const tone = badgeTone(state, COMPUTE_STATE_TONES); + return { + label: known ? badgeLabel(state, COMPUTE_STATE_LABELS) : displaySafeLine(badgeLabel(state, {})), + tone, + icon: badgeIcon(tone), + known, + }; +} + +export const COMPUTE_SOURCE_LABELS: Readonly> = { + cli: "Command line", + web: "Website", + partner: "Partner site", + pipeline: "NEMAR pipeline", +}; + +/** The words for a front door; the escaped raw word for one this build does not know. */ +export function sourceLabel(source: string): string { + return Object.hasOwn(COMPUTE_SOURCE_LABELS, source) + ? COMPUTE_SOURCE_LABELS[source as ComputeJobSource] + : displaySafeLine(source); +} + +/** Every tone the badges use, so a test can pin that each has its own icon. */ +export const COMPUTE_BADGE_TONES_IN_USE: readonly BadgeTone[] = [ + ...new Set(Object.values(COMPUTE_STATE_TONES)), +]; diff --git a/src/lib/compute-chart.test.ts b/src/lib/compute-chart.test.ts new file mode 100644 index 00000000..4a2e9406 --- /dev/null +++ b/src/lib/compute-chart.test.ts @@ -0,0 +1,405 @@ +/** + * Chart geometry. The known-usage cases run on a fixture captured from the real route: + * + * NEMAR_CLI_DIR= \ + * bun scripts/capture-compute-read-fixtures.mjs + * + * (test/fixtures/compute/usage-day-partition.json, usage-empty.json, usage-outlier.json). The edge + * cases that no single route call can produce (a 366 day window, a fourth partition) use inline rows + * of the same shape. + */ +import { describe, expect, it } from "vitest"; +import day from "../../test/fixtures/compute/usage-day-partition.json"; +import empty from "../../test/fixtures/compute/usage-empty.json"; +import outlier from "../../test/fixtures/compute/usage-outlier.json"; +import { + BAND, + MIN_VISIBLE_UNITS, + PLOT_HEIGHT, + type UsageRow, + computeUsageChart, + niceCeiling, + niceStep, +} from "./compute-chart"; + +const CPU = ["shared", "compute", "debug"]; +const GPU = ["gpu-shared", "gpu", "gpu-debug"]; + +function rowsOf(body: { rows: unknown[] }, partitions: string[]): UsageRow[] { + return (body.rows as UsageRow[]).filter( + (r) => r.partition !== null && partitions.includes(r.partition), + ); +} + +describe("niceStep and niceCeiling", () => { + it.each([ + [0, 500, 1000], + [1, 1, 1], + [4, 1, 4], + [5, 2, 6], + [13_500, 5_000, 15_000], + [16_200, 5_000, 20_000], + [250_000, 100_000, 300_000], + [1_000, 500, 1_000], + [1_001, 500, 1_500], + [8_000, 2_000, 8_000], + ])("max %i has step %i and ceiling %i", (max, step, ceiling) => { + expect(niceStep(max)).toBe(step); + expect(niceCeiling(max)).toBe(ceiling); + }); + + it("always gives at most four intervals", () => { + for (const max of [1, 3, 7, 99, 101, 999, 1_234, 98_765, 1_000_001, 12_345_678_901]) { + expect(niceCeiling(max) / niceStep(max), String(max)).toBeLessThanOrEqual(4); + expect(niceCeiling(max)).toBeGreaterThanOrEqual(max); + } + }); + + it("takes and returns integers", () => { + for (const max of [0, 1, 17, 12_500, 250_000]) { + expect(Number.isInteger(niceStep(max))).toBe(true); + expect(Number.isInteger(niceCeiling(max))).toBe(true); + } + expect(() => niceStep(-1)).toThrow(RangeError); + expect(() => niceStep(1.5)).toThrow(RangeError); + }); +}); + +describe("the cpu chart of the captured fixture", () => { + const chart = computeUsageChart({ + from: day.body.from, + to: day.body.to, + rows: rowsOf(day.body, CPU), + partitions: CPU, + otherLabel: "Other partitions", + }); + + it("has one band per day of the window, 30 here", () => { + expect(chart.days).toHaveLength(30); + expect(chart.viewBoxWidth).toBe(30 * BAND); + expect(chart.days[0].day).toBe("2026-10-09"); + expect(chart.days[29].day).toBe("2026-11-07"); + expect(chart.days[3].x).toBe(3 * BAND + 1); + expect(chart.days[3].width).toBe(BAND - 2); + }); + + it("takes its ceiling from the largest STACKED day, not the largest segment", () => { + // Oct 12 stacks compute 12.500 + shared 4.000 = 16.500; the largest single segment is 12.500. + // Nov 3 stacks 5.000 (shared) alone. A ceiling from the largest segment would be 15.000. + const stacked = 16_500; + const largestSegment = 12_500; + expect(Math.max(...chart.days.map((d) => d.drawnMilli))).toBe(stacked); + expect(niceCeiling(largestSegment)).toBe(15_000); + expect(chart.ceilingMilli).toBe(niceCeiling(stacked)); + expect(chart.ceilingMilli).toBe(20_000); + expect(chart.stepMilli).toBe(5_000); + expect(chart.ticks.map((t) => t.label)).toEqual(["0", "5", "10", "15", "20"]); + }); + + it("stacks the segments of a day from the bottom in the order of the offered list", () => { + const oct12 = chart.days.find((d) => d.day === "2026-10-12"); + expect(oct12?.segments.map((s) => [s.seriesIndex, s.milli])).toEqual([ + [0, 4_000], // shared + [1, 12_500], // compute + ]); + const [shared, compute] = oct12?.segments ?? []; + expect(shared.height).toBe(20); // 4000 / 20000 * 100 + expect(shared.y).toBe(80); + expect(compute.height).toBe(62.5); + expect(compute.y).toBe(17.5); // sits on top of shared: 100 - 20 - 62.5 + }); + + it("draws a quiet day as nothing, and a day with no row at zero", () => { + const quiet = chart.days.find((d) => d.day === "2026-10-10"); + expect(quiet?.segments).toEqual([]); + expect(quiet?.drawnMilli).toBe(0); + }); + + it("never draws below the baseline: a net-negative partition-day is omitted, counted and tabled", () => { + const refund = chart.days.find((d) => d.day === "2026-10-22"); + expect(refund?.segments).toEqual([]); + expect(chart.omitted.cells).toEqual([{ day: "2026-10-22", seriesIndex: 2, milli: -300 }]); + expect(chart.omitted.negativeMilli).toBe(-300); + const tabled = chart.table.find((r) => r.day === "2026-10-22"); + expect(tabled?.cells).toEqual([null, null, -300]); + for (const bar of chart.days) { + for (const seg of bar.segments) { + expect(seg.height).toBeGreaterThan(0); + expect(seg.y + seg.height).toBeLessThanOrEqual(PLOT_HEIGHT + 0.001); + } + } + }); + + it("totals what is drawn exactly and names the busiest day", () => { + // shared 4000+2500+6000+5000, compute 12500+9000, debug 500 + expect(chart.totalMilli).toBe(4_000 + 2_500 + 6_000 + 5_000 + 12_500 + 9_000 + 500); + expect(chart.busiest).toEqual({ day: "2026-10-12", milli: 16_500 }); + expect(chart.daysWithCharges).toBe(5); // Oct 22 nets negative + expect(chart.empty).toBe(false); + }); + + it("lists only the days that have a row in the table, in order", () => { + expect(chart.table.map((r) => r.day)).toEqual([ + "2026-10-12", + "2026-10-13", + "2026-10-20", + "2026-10-22", + "2026-10-27", + "2026-11-03", + ]); + expect(chart.table[0].netMilli).toBe(16_500); + expect(chart.series.map((s) => s.name)).toEqual(CPU); + }); + + it("carries a series total that includes the negative net row", () => { + const debug = chart.series.find((s) => s.name === "debug"); + expect(debug?.netMilli).toBe(500 - 300); + }); + + it("offers about six x labels and three on a phone, first and last included", () => { + expect(chart.xLabels.regular.length).toBeGreaterThanOrEqual(5); + expect(chart.xLabels.regular.length).toBeLessThanOrEqual(6); + expect(chart.xLabels.sparse.map((l) => l.index)).toEqual([0, 15, 29]); + expect(chart.xLabels.regular[0].text).toBe("Oct 9"); + expect(chart.xLabels.sparse.at(-1)?.text).toBe("Nov 7"); + expect(chart.xLabels.sparse[0].leftPercent).toBeCloseTo((0.5 / 30) * 100, 2); + }); +}); + +describe("the gpu chart of the same fixture", () => { + const chart = computeUsageChart({ + from: day.body.from, + to: day.body.to, + rows: rowsOf(day.body, GPU), + partitions: GPU, + otherLabel: "Other partitions", + }); + it("is a separate currency with its own ceiling", () => { + expect(chart.totalMilli).toBe(5_000 + 8_000 + 1_500); + expect(chart.ceilingMilli).toBe(8_000); // the largest day stacks 8.000 + }); +}); + +describe("a window with nothing in it", () => { + const chart = computeUsageChart({ + from: empty.body.from, + to: empty.body.to, + rows: [], + partitions: CPU, + otherLabel: "Other partitions", + }); + it("keeps an axis of 1 SU and draws nothing", () => { + expect(empty.body.rows).toEqual([]); + expect(chart.empty).toBe(true); + expect(chart.totalMilli).toBe(0); + expect(chart.busiest).toBeNull(); + expect(chart.ceilingMilli).toBe(1_000); + expect(chart.ticks.map((t) => t.label)).toEqual(["0", "0.5", "1"]); + expect(chart.days.every((d) => d.segments.length === 0)).toBe(true); + expect(chart.table).toEqual([]); + }); +}); + +describe("one large outlier", () => { + const chart = computeUsageChart({ + from: outlier.body.from, + to: outlier.body.to, + rows: rowsOf(outlier.body, CPU), + partitions: CPU, + otherLabel: "Other partitions", + }); + it("scales to the outlier and still shows the small days", () => { + expect(chart.ceilingMilli).toBe(300_000); + const big = chart.days.find((d) => d.day === "2026-10-20"); + expect(big?.segments[0].height).toBeCloseTo((250_000 / 300_000) * 100, 2); + const small = chart.days.find((d) => d.day === "2026-10-15"); + // 400 milli-SU is far under one unit of height: it is still visible, at the minimum. + expect(small?.segments[0].height).toBe(MIN_VISIBLE_UNITS); + }); +}); + +describe("a stack never leaves the plot", () => { + it("when tiny segments raised to the minimum sit on a bar that fills the ceiling", () => { + // 399.998 + 0.001 + 0.001 = 400.000, which is the ceiling; the two 0.001 segments are raised to + // one unit each, so the large one gives up 2 units instead of the stack reaching 102. + const chart = computeUsageChart({ + from: "2026-11-01", + to: "2026-11-01", + rows: [ + { day: "2026-11-01", partition: "shared", charged_milli: 399_998, jobs: 1 }, + { day: "2026-11-01", partition: "compute", charged_milli: 1, jobs: 1 }, + { day: "2026-11-01", partition: "debug", charged_milli: 1, jobs: 1 }, + ], + partitions: CPU, + otherLabel: "Other", + }); + expect(chart.ceilingMilli).toBe(400_000); + const segs = chart.days[0].segments; + expect(segs).toHaveLength(3); + expect(segs[1].height).toBe(MIN_VISIBLE_UNITS); + expect(segs[2].height).toBe(MIN_VISIBLE_UNITS); + const top = segs[segs.length - 1]; + expect(top.y).toBeGreaterThanOrEqual(0); + expect(segs.reduce((sum, s) => sum + s.height, 0)).toBeLessThanOrEqual(PLOT_HEIGHT + 0.001); + expect(segs[0].height).toBeCloseTo(PLOT_HEIGHT - 2 * MIN_VISIBLE_UNITS, 2); + }); + + it("for every day of every fixture", () => { + for (const body of [day.body, outlier.body]) { + const chart = computeUsageChart({ + from: body.from, + to: body.to, + rows: rowsOf(body, CPU), + partitions: CPU, + otherLabel: "Other", + }); + for (const bar of chart.days) { + const total = bar.segments.reduce((sum, s) => sum + s.height, 0); + expect(total).toBeLessThanOrEqual(PLOT_HEIGHT + 0.001); + for (const seg of bar.segments) expect(seg.y).toBeGreaterThanOrEqual(-0.001); + } + } + }); +}); + +describe("a single day", () => { + it("is one band with its own label", () => { + const chart = computeUsageChart({ + from: "2026-11-03", + to: "2026-11-03", + rows: [{ day: "2026-11-03", partition: "shared", charged_milli: 2_500, jobs: 1 }], + partitions: CPU, + otherLabel: "Other", + }); + expect(chart.days).toHaveLength(1); + expect(chart.viewBoxWidth).toBe(BAND); + expect(chart.xLabels.regular.map((l) => l.text)).toEqual(["Nov 3"]); + expect(chart.xLabels.sparse.map((l) => l.text)).toEqual(["Nov 3"]); + expect(chart.ceilingMilli).toBe(3_000); + }); +}); + +describe("window edges", () => { + it("spans a month boundary and a year boundary", () => { + const chart = computeUsageChart({ + from: "2026-12-30", + to: "2027-01-02", + rows: [], + partitions: CPU, + otherLabel: "Other", + }); + expect(chart.days.map((d) => d.day)).toEqual([ + "2026-12-30", + "2026-12-31", + "2027-01-01", + "2027-01-02", + ]); + }); + + it("accepts 366 days and refuses 367", () => { + const ok = computeUsageChart({ + from: "2026-01-01", + to: "2027-01-01", + rows: [], + partitions: CPU, + otherLabel: "Other", + }); + expect(ok.days).toHaveLength(366); + expect(ok.xLabels.regular.length).toBeLessThanOrEqual(6); + expect(() => + computeUsageChart({ + from: "2026-01-01", + to: "2027-01-02", + rows: [], + partitions: CPU, + otherLabel: "Other", + }), + ).toThrow(RangeError); + }); + + it("refuses a window that is not two days or ends before it starts", () => { + for (const [from, to] of [ + ["2026-11-05", "2026-11-04"], + ["x", "2026-11-04"], + ["2026-11-05", "2026-02-30"], + ]) { + expect(() => + computeUsageChart({ from, to, rows: [], partitions: CPU, otherLabel: "Other" }), + ).toThrow(RangeError); + } + }); +}); + +describe("rows the geometry cannot place are an error, never a silent drop", () => { + const base = { from: "2026-11-01", to: "2026-11-03", partitions: CPU, otherLabel: "Other" }; + it("a row outside the window", () => { + expect(() => + computeUsageChart({ + ...base, + rows: [{ day: "2026-12-01", partition: "shared", charged_milli: 1, jobs: 1 }], + }), + ).toThrow(RangeError); + }); + it("a null partition or one this chart was not given", () => { + expect(() => + computeUsageChart({ + ...base, + rows: [{ day: "2026-11-01", partition: null, charged_milli: 1, jobs: 0 }], + }), + ).toThrow(RangeError); + expect(() => + computeUsageChart({ + ...base, + rows: [{ day: "2026-11-01", partition: "gpu", charged_milli: 1, jobs: 1 }], + }), + ).toThrow(RangeError); + }); +}); + +describe("colors", () => { + const rows = (names: string[]): UsageRow[] => + names.map((partition, i) => ({ + day: "2026-11-02", + partition, + charged_milli: 1_000 * (i + 1), + jobs: 1, + })); + + it("are by position in the offered list, so they survive a window where a partition is absent", () => { + const wide = computeUsageChart({ + from: "2026-11-01", + to: "2026-11-03", + rows: rows(["shared", "compute", "debug"]), + partitions: CPU, + otherLabel: "Other", + }); + const narrow = computeUsageChart({ + from: "2026-11-04", + to: "2026-11-06", + rows: [{ day: "2026-11-05", partition: "debug", charged_milli: 700, jobs: 1 }], + partitions: CPU, + otherLabel: "Other", + }); + const colorOf = (c: ReturnType, name: string) => + c.series.find((s) => s.name === name)?.colorIndex; + expect(colorOf(wide, "debug")).toBe(2); + expect(colorOf(narrow, "debug")).toBe(2); + expect(narrow.days.find((d) => d.day === "2026-11-05")?.segments[0].seriesIndex).toBe(2); + }); + + it("never need a fifth: partitions past the third share one 'other' series", () => { + const names = ["a", "b", "c", "d", "e"]; + const chart = computeUsageChart({ + from: "2026-11-01", + to: "2026-11-03", + rows: rows(names), + partitions: names, + otherLabel: "Other partitions", + }); + expect(chart.series.map((s) => s.name)).toEqual(["a", "b", "c", "Other partitions"]); + expect(chart.series.map((s) => s.colorIndex)).toEqual([0, 1, 2, 3]); + expect(chart.series[3].partitions).toEqual(["d", "e"]); + // d (4000) and e (5000) stack as one series of 9000. + expect(chart.days[1].segments.at(-1)?.milli).toBe(9_000); + }); +}); diff --git a/src/lib/compute-chart.ts b/src/lib/compute-chart.ts new file mode 100644 index 00000000..db12957c --- /dev/null +++ b/src/lib/compute-chart.ts @@ -0,0 +1,341 @@ +/** + * Geometry for the `/compute` usage chart (website ADR 0007: hand-rolled SVG, no chart library). + * + * Pure and integer-based where it matters: amounts are whole milli-SU and every total goes through + * `sumMilli`; only the SVG coordinates are fractions, rounded to three decimals, and none of them is + * ever printed. The chart is a daily bar chart of the NET charge of one pool, each bar stacked by + * partition, over the window the API answered for (the page never builds a date from a clock). + * + * What the geometry refuses to do, and says so instead: + * - It never draws below the baseline. A partition-day whose net charge is negative (a refund or a + * correction) is left out of the bar, counted in `omitted`, and still listed in the table. + * - The y ceiling comes from the largest STACKED day total, never from the largest single segment. + * - A quiet day has no row in the API and draws nothing; it is a zero-height bar, which is true. + * - Colors are by the partition's place in the offered list, not by data order, so a color keeps its + * meaning from one window to the next. A fifth series never exists: partitions past the third share + * the "other" series. + */ + +import { dayFromEpoch, epochDay, formatDayShort, formatSu, sumMilli } from "./compute-format"; + +/** The most days a window may span (the API refuses more). */ +const MAX_DAYS = 366; +/** Series with their own color; any partition past this many shares the last series, "other". */ +export const CHART_SERIES_COLORS = 4; +const NAMED_SERIES = CHART_SERIES_COLORS - 1; + +/** The viewBox is `BAND` units wide per day and `PLOT_HEIGHT` units tall; the SVG stretches to fit. */ +export const BAND = 10; +export const PLOT_HEIGHT = 100; +/** A bar is inset this far from each side of its band, leaving a gap between neighbors. */ +const BAR_INSET = 1; +/** A non-zero segment is never thinner than this many viewBox units (about 2 px on the tall chart). */ +export const MIN_VISIBLE_UNITS = 1; + +/** One row of `GET /compute/me/usage?group=day,partition`, as the client guard hands it over. */ +export interface UsageRow { + readonly day: string; + readonly partition: string | null; + readonly charged_milli: number; + readonly jobs: number; +} + +export interface ChartInput { + readonly from: string; + readonly to: string; + /** Only the rows of ONE pool (the caller decides which pool a row belongs to). */ + readonly rows: readonly UsageRow[]; + /** The partitions offered for this pool, in the backend's order. */ + readonly partitions: readonly string[]; + /** The name of the shared series for partitions past the third. */ + readonly otherLabel: string; +} + +export interface ChartSeries { + /** 0..3, the token `--chart-series-`. */ + readonly colorIndex: number; + readonly name: string; + /** The partitions this series stands for (one, or the shared "other" series' several). */ + readonly partitions: readonly string[]; + /** The net total over the window, negative rows included, for the table and the legend. */ + readonly netMilli: number; +} + +export interface Segment { + readonly seriesIndex: number; + readonly milli: number; + /** viewBox units from the top of the plot. */ + readonly y: number; + readonly height: number; +} + +export interface DayBar { + readonly day: string; + readonly label: string; + readonly x: number; + readonly width: number; + /** Bottom to top. */ + readonly segments: readonly Segment[]; + /** The sum of the segments drawn (positive net charges only). */ + readonly drawnMilli: number; +} + +export interface Tick { + readonly milli: number; + readonly label: string; + /** Percent from the top of the plot. */ + readonly topPercent: number; +} + +export interface XLabel { + readonly index: number; + readonly text: string; + /** Percent from the left of the plot, at the middle of the band. */ + readonly leftPercent: number; +} + +export interface TableRow { + readonly day: string; + readonly label: string; + /** Net milli per series, null when the series had no row that day. */ + readonly cells: readonly (number | null)[]; + readonly netMilli: number; +} + +export interface UsageChart { + readonly viewBoxWidth: number; + readonly viewBoxHeight: number; + readonly days: readonly DayBar[]; + readonly series: readonly ChartSeries[]; + readonly ticks: readonly Tick[]; + readonly ceilingMilli: number; + readonly stepMilli: number; + readonly xLabels: { readonly regular: readonly XLabel[]; readonly sparse: readonly XLabel[] }; + /** The sum of everything drawn. */ + readonly totalMilli: number; + /** The day with the largest drawn total, or null when nothing is drawn. */ + readonly busiest: { readonly day: string; readonly milli: number } | null; + readonly daysWithCharges: number; + /** Partition-days whose net charge is negative: not drawn, counted, and listed in the table. */ + readonly omitted: { + readonly cells: readonly { + readonly day: string; + readonly seriesIndex: number; + readonly milli: number; + }[]; + readonly negativeMilli: number; + }; + /** Only the days that have a row, in order: the numbers behind the bars. */ + readonly table: readonly TableRow[]; + /** True when no row was drawn. */ + readonly empty: boolean; +} + +const round3 = (n: number): number => Math.round(n * 1000) / 1000; + +/** + * The step between ticks: 1, 2 or 5 times a power of ten milli-SU, the smallest that gives at most four + * intervals up to `maxMilli`. Integers in, integer out. An all-zero range gets 500 (a 1 SU ceiling). + */ +export function niceStep(maxMilli: number): number { + if (!Number.isSafeInteger(maxMilli) || maxMilli < 0) { + throw new RangeError("the largest total is a non-negative whole number of milli-SU"); + } + if (maxMilli === 0) return 500; + const target = Math.ceil(maxMilli / 4); + for (let power = 1; power <= Number.MAX_SAFE_INTEGER / 10; power *= 10) { + for (const multiple of [1, 2, 5]) { + if (multiple * power >= target) return multiple * power; + } + } + throw new RangeError("the largest total is too large to chart"); +} + +/** The ceiling: the next multiple of the step at or above the maximum (1 SU when there is nothing). */ +export function niceCeiling(maxMilli: number): number { + const step = niceStep(maxMilli); + return maxMilli === 0 ? 1000 : Math.ceil(maxMilli / step) * step; +} + +function windowDays(from: string, to: string): string[] { + const a = epochDay(from); + const b = epochDay(to); + if (a === null || b === null) throw new RangeError("the window is not two days"); + if (b < a) throw new RangeError("the window ends before it starts"); + if (b - a + 1 > MAX_DAYS) throw new RangeError("the window is longer than the API allows"); + const out: string[] = []; + for (let e = a; e <= b; e++) out.push(dayFromEpoch(e)); + return out; +} + +function pickLabels(count: number, wanted: number): number[] { + if (count <= wanted) return Array.from({ length: count }, (_, i) => i); + const picks = new Set(); + for (let i = 0; i < wanted; i++) picks.add(Math.round((i * (count - 1)) / (wanted - 1))); + return [...picks].sort((x, y) => x - y); +} + +/** Series for the offered partitions: the first three each their own, the rest share "other". */ +function buildSeries( + partitions: readonly string[], + otherLabel: string, +): { names: ChartSeries[]; indexOf: (partition: string) => number } { + const distinct = [...new Set(partitions)]; + const named = distinct.length > CHART_SERIES_COLORS ? NAMED_SERIES : distinct.length; + const names: ChartSeries[] = []; + for (let i = 0; i < named; i++) { + names.push({ colorIndex: i, name: distinct[i], partitions: [distinct[i]], netMilli: 0 }); + } + const rest = distinct.slice(named); + if (rest.length > 0) { + names.push({ + colorIndex: CHART_SERIES_COLORS - 1, + name: otherLabel, + partitions: rest, + netMilli: 0, + }); + } + return { + names, + indexOf: (partition) => { + const own = names.findIndex((s) => s.partitions.includes(partition)); + if (own >= 0) return own; + // A partition that is not offered: the caller routed it here by mistake. Say so. + throw new RangeError("a row belongs to a partition this chart was not given"); + }, + }; +} + +export function computeUsageChart(input: ChartInput): UsageChart { + const dayList = windowDays(input.from, input.to); + const dayIndex = new Map(dayList.map((d, i) => [d, i] as const)); + const { names, indexOf } = buildSeries(input.partitions, input.otherLabel); + + // Net per (day, series), summed with the exact adder. + const cells = new Map(); + const negativeCells: { day: string; seriesIndex: number; milli: number }[] = []; + for (const row of input.rows) { + if (row.partition === null) throw new RangeError("a null-partition row has no pool to chart"); + const di = dayIndex.get(row.day); + if (di === undefined) throw new RangeError("a row is outside the window"); + const si = indexOf(row.partition); + const key = `${di}:${si}`; + cells.set(key, [...(cells.get(key) ?? []), row.charged_milli]); + } + const net = (di: number, si: number): number | null => { + const values = cells.get(`${di}:${si}`); + return values ? sumMilli(values) : null; + }; + + // Day totals of the DRAWN (positive) segments: the ceiling comes from these stacks. + const drawnTotals = dayList.map((_, di) => + sumMilli(names.map((_s, si) => Math.max(0, net(di, si) ?? 0))), + ); + const maxStack = drawnTotals.reduce((a, b) => Math.max(a, b), 0); + const step = niceStep(maxStack); + const ceiling = niceCeiling(maxStack); + + const days: DayBar[] = dayList.map((day, di) => { + const segments: Segment[] = []; + // The positive net charges of the day, bottom to top, with their heights before any floor. + const parts: { seriesIndex: number; milli: number; height: number }[] = []; + names.forEach((_s, si) => { + const value = net(di, si); + if (value === null) return; + if (value <= 0) { + if (value < 0) negativeCells.push({ day, seriesIndex: si, milli: value }); + return; + } + parts.push({ seriesIndex: si, milli: value, height: (value / ceiling) * PLOT_HEIGHT }); + }); + // A segment is never thinner than the floor, but raising tiny ones must not push the stack past the + // plot (the SVG draws outside its box): the segments above the floor give up the difference. + const floored = parts.filter((p) => p.height < MIN_VISIBLE_UNITS); + const roomy = parts.filter((p) => p.height >= MIN_VISIBLE_UNITS); + const roomySum = roomy.reduce((sum, p) => sum + p.height, 0); + const room = PLOT_HEIGHT - floored.length * MIN_VISIBLE_UNITS; + const factor = roomySum > room && roomySum > 0 ? room / roomySum : 1; + let offset = 0; + for (const part of parts) { + const height = round3( + part.height < MIN_VISIBLE_UNITS ? MIN_VISIBLE_UNITS : part.height * factor, + ); + offset = round3(offset + height); + segments.push({ + seriesIndex: part.seriesIndex, + milli: part.milli, + y: round3(PLOT_HEIGHT - offset), + height, + }); + } + return { + day, + label: formatDayShort(day), + x: di * BAND + BAR_INSET, + width: BAND - 2 * BAR_INSET, + segments, + drawnMilli: drawnTotals[di], + }; + }); + + const series = names.map((s, si) => ({ + ...s, + netMilli: sumMilli(dayList.map((_, di) => net(di, si) ?? 0)), + })); + + const ticks: Tick[] = []; + for (let milli = 0; milli <= ceiling; milli += step) { + ticks.push({ + milli, + label: formatSu(milli), + topPercent: round3(100 - (milli / ceiling) * 100), + }); + } + + const label = (index: number): XLabel => ({ + index, + text: formatDayShort(dayList[index]), + leftPercent: round3(((index + 0.5) / dayList.length) * 100), + }); + const regular = pickLabels(dayList.length, 6).map(label); + const sparse = pickLabels(dayList.length, 3).map(label); + + let busiest: UsageChart["busiest"] = null; + drawnTotals.forEach((milli, di) => { + if (milli > 0 && (busiest === null || milli > busiest.milli)) { + busiest = { day: dayList[di], milli }; + } + }); + + const table: TableRow[] = []; + dayList.forEach((day, di) => { + const row = names.map((_s, si) => net(di, si)); + if (row.every((c) => c === null)) return; + table.push({ + day, + label: formatDayShort(day), + cells: row, + netMilli: sumMilli(row.map((c) => c ?? 0)), + }); + }); + + return { + viewBoxWidth: dayList.length * BAND, + viewBoxHeight: PLOT_HEIGHT, + days, + series, + ticks, + ceilingMilli: ceiling, + stepMilli: step, + xLabels: { regular, sparse }, + totalMilli: sumMilli(drawnTotals), + busiest, + daysWithCharges: drawnTotals.filter((m) => m > 0).length, + omitted: { + cells: negativeCells, + negativeMilli: sumMilli(negativeCells.map((c) => c.milli)), + }, + table, + empty: drawnTotals.every((m) => m === 0), + }; +} diff --git a/src/lib/compute-contract.ts b/src/lib/compute-contract.ts new file mode 100644 index 00000000..f02c6e4d --- /dev/null +++ b/src/lib/compute-contract.ts @@ -0,0 +1,83 @@ +/** + * The vocabulary the `/compute` page depends on, copied by hand from nemar-cli (website ADR 0030 and + * its phase E2 addendum; ADR 0015: transcribed, not imported). `test/compute-user-contract-drift.test.ts` + * reads the originals as text, so a word that moves on one side fails CI instead of rendering as an + * unknown pill. + * + * Sources, all in nemar-cli: + * - `shared/compute-state.ts`: the ten job states, the terminal ones, the four front doors. + * - `shared/compute-access-state.ts`: see `./compute-access-state.ts` (already transcribed). + * - `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. + * + * 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. + * A leaf module on purpose: it imports nothing and is safe in the browser bundle. It carries words and + * numbers only; what they mean is the backend's (ADR 0030). + */ + +/** Every state of a job, in the order of the backend's table. */ +export const COMPUTE_JOB_STATES = [ + "created", + "uploading", + "submitted", + "queued", + "running", + "archiving", + "finished", + "failed", + "cancelled", + "unreported", +] as const; + +export type ComputeJobState = (typeof COMPUTE_JOB_STATES)[number]; + +/** A terminal job never moves again, so its charge is settled once. */ +export const COMPUTE_TERMINAL_STATES = ["finished", "failed", "cancelled"] as const; + +/** The front door that submitted a job. */ +export const COMPUTE_JOB_SOURCES = ["cli", "web", "partner", "pipeline"] as const; + +export type ComputeJobSource = (typeof COMPUTE_JOB_SOURCES)[number]; + +/** The groups `GET /compute/me/usage` may be grouped by. */ +export const COMPUTE_USAGE_GROUPS = ["day", "app", "partition", "source"] as const; + +/** The most jobs one page of `GET /compute/me/jobs` holds, and the page when `limit` is absent. */ +export const COMPUTE_JOBS_PAGE_DEFAULT = 25; +export const COMPUTE_JOBS_PAGE_MAX = 100; + +/** The longest usage window the route answers for, both ends counted. */ +export const COMPUTE_WINDOW_MAX_DAYS = 366; + +/** Fewer started jobs than this give null queue figures with the count. */ +export const COMPUTE_QUEUE_MIN_SAMPLES = 5; + +/** A job id: `job_` and 24 lowercase hex digits. */ +export const COMPUTE_JOB_ID_RE = /^job_[0-9a-f]{24}$/; + +/** Every word a read route answers a refusal with, and its status. */ +export const COMPUTE_USER_ERROR_STATUS = { + forbidden_credential: 403, + insufficient_scope: 403, + invalid_token: 401, + missing_credential: 401, + invalid_range: 400, + invalid_group: 400, + invalid_state: 400, + invalid_limit: 400, + invalid_cursor: 400, + job_not_found: 404, + policy_unavailable: 503, +} as const; + +export type ComputeUserErrorCode = keyof typeof COMPUTE_USER_ERROR_STATUS; + +export function isComputeJobState(value: unknown): value is ComputeJobState { + return typeof value === "string" && (COMPUTE_JOB_STATES as readonly string[]).includes(value); +} + +export function isTerminalComputeState(state: string): boolean { + return (COMPUTE_TERMINAL_STATES as readonly string[]).includes(state); +} diff --git a/src/lib/compute-format.test.ts b/src/lib/compute-format.test.ts new file mode 100644 index 00000000..1948fb46 --- /dev/null +++ b/src/lib/compute-format.test.ts @@ -0,0 +1,161 @@ +/** + * Formatters for the /compute page. Vectors for `suFixed` and `formatDuration` are copied from + * nemar-cli's `suFixed` and `durationText` (src/commands/compute-read.ts), so the page and + * `nemar compute balance` print the same digits. + */ +import { describe, expect, it } from "vitest"; +import { + dayFromEpoch, + dbTimeToIso, + epochDay, + formatDayShort, + formatDuration, + formatSu, + formatUtcDate, + formatUtcMinute, + formatUtcSecond, + parseDbTime, + suFixed, + sumMilli, +} from "./compute-format"; + +describe("suFixed", () => { + it.each([ + [0, "0.000"], + [1, "0.001"], + [999, "0.999"], + [1000, "1.000"], + [12500, "12.500"], + [123456789012, "123456789.012"], + [-500, "-0.500"], + [-1, "-0.001"], + [-1000, "-1.000"], + [-12345, "-12.345"], + [Number.MAX_SAFE_INTEGER, "9007199254740.991"], + ])("%i milli is %s", (milli, text) => { + expect(suFixed(milli)).toBe(text); + }); + + it("prints a negative balance as negative, never as zero", () => { + expect(suFixed(-2500)).toBe("-2.500"); + expect(suFixed(-2500)).not.toBe("0.000"); + }); + + it.each([Number.NaN, 1.5, Number.MAX_SAFE_INTEGER + 1, Number.POSITIVE_INFINITY])( + "throws for %s instead of printing a wrong figure", + (bad) => { + expect(() => suFixed(bad)).toThrow(RangeError); + }, + ); + + it("has no thousands separator, so the digits match the CLI", () => { + expect(suFixed(1234567890)).toBe("1234567.890"); + }); +}); + +describe("formatSu", () => { + it.each([ + [0, "0"], + [2500, "2.5"], + [10000, "10"], + [250, "0.25"], + [1, "0.001"], + [-500, "-0.5"], + [500000, "500"], + ])("%i milli is %s", (milli, text) => { + expect(formatSu(milli)).toBe(text); + }); + it("throws for a float", () => { + expect(() => formatSu(0.5)).toThrow(RangeError); + }); +}); + +describe("sumMilli", () => { + it("adds integers exactly", () => { + expect(sumMilli([])).toBe(0); + expect(sumMilli([4000, 12500, -300])).toBe(16200); + }); + it("is exact where floats are not", () => { + // 0.1 + 0.2 in SU would be 0.30000000000000004; in milli-SU it is 300. + expect(sumMilli([100, 200])).toBe(300); + }); + it("throws for a non-integer or a sum that leaves the safe range", () => { + expect(() => sumMilli([1, 1.5])).toThrow(RangeError); + expect(() => sumMilli([Number.MAX_SAFE_INTEGER, 1])).toThrow(RangeError); + }); +}); + +describe("formatDuration", () => { + it.each([ + [0, "0s"], + [37, "37s"], + [59, "59s"], + [60, "1m 0s"], + [252, "4m 12s"], + [3599, "59m 59s"], + [3600, "1h 0m"], + [3900, "1h 5m"], + [90000, "25h 0m"], + ])("%i seconds is %s", (seconds, text) => { + expect(formatDuration(seconds)).toBe(text); + }); + it("throws for a negative, a float or NaN", () => { + expect(() => formatDuration(-1)).toThrow(RangeError); + expect(() => formatDuration(1.5)).toThrow(RangeError); + expect(() => formatDuration(Number.NaN)).toThrow(RangeError); + }); +}); + +describe("database times are UTC whatever the machine's zone", () => { + it("parses field by field, not as local time", () => { + // Local-time parsing would differ from this on any machine whose offset is not zero. + expect(parseDbTime("2026-11-05 12:00:00")).toBe(Date.UTC(2026, 10, 5, 12)); + expect(dbTimeToIso("2026-11-05 12:00:00")).toBe("2026-11-05T12:00:00Z"); + }); + it("formats to the minute and to the second", () => { + expect(formatUtcMinute("2026-11-05 12:07:59")).toBe("2026-11-05 12:07 UTC"); + expect(formatUtcSecond("2026-11-05 12:07:59")).toBe("2026-11-05 12:07:59 UTC"); + }); + it("formats the UTC date, not the viewer's", () => { + expect(formatUtcDate("2026-10-20 23:59:59")).toBe("Oct 20, 2026"); + expect(formatUtcDate("2026-01-01 00:00:00")).toBe("Jan 1, 2026"); + expect(formatUtcDate("soon")).toBe("soon"); + }); + it("rejects a shape or an impossible instant, and returns the text unchanged", () => { + for (const bad of [ + "", + "2026-11-05T12:00:00Z", + "2026-13-05 12:00:00", + "2026-02-30 12:00:00", + "x", + ]) { + expect(parseDbTime(bad), bad).toBeNull(); + expect(dbTimeToIso(bad), bad).toBeNull(); + expect(formatUtcMinute(bad), bad).toBe(bad); + } + }); +}); + +describe("days", () => { + it("round-trips an epoch day", () => { + const e = epochDay("2026-11-03"); + expect(e).not.toBeNull(); + expect(dayFromEpoch(e as number)).toBe("2026-11-03"); + expect((epochDay("2026-11-04") as number) - (e as number)).toBe(1); + }); + it("crosses a month and a year boundary", () => { + expect(dayFromEpoch((epochDay("2026-10-31") as number) + 1)).toBe("2026-11-01"); + expect(dayFromEpoch((epochDay("2026-12-31") as number) + 1)).toBe("2027-01-01"); + expect(dayFromEpoch((epochDay("2028-02-28") as number) + 1)).toBe("2028-02-29"); + }); + it("rejects what is not a day", () => { + expect(epochDay("2026-02-30")).toBeNull(); + expect(epochDay("2026-1-1")).toBeNull(); + expect(epochDay("")).toBeNull(); + }); + it("labels a day without a locale", () => { + expect(formatDayShort("2026-11-03")).toBe("Nov 3"); + expect(formatDayShort("2026-01-15")).toBe("Jan 15"); + expect(formatDayShort("garbage")).toBe("garbage"); + }); +}); diff --git a/src/lib/compute-format.ts b/src/lib/compute-format.ts new file mode 100644 index 00000000..1dea0a02 --- /dev/null +++ b/src/lib/compute-format.ts @@ -0,0 +1,155 @@ +/** + * Pure formatters for the `/compute` page (website ADR 0030 phase E2 addendum). + * + * Money is whole thousandths of a service unit (milli-SU) end to end. Nothing here divides by 1000 as a + * float, so the digits on the page are the digits `nemar compute balance` prints (`suFixed` there). + * A helper that is handed something that is not an amount THROWS `RangeError`: a wrong figure must never + * print as zero. The client guards (`./compute-api.ts`) reject such a body as a `shape` error first, and + * the view models run inside each panel's own `try/catch`, so a throw costs that panel, not the page + * (Astro drops a component whose render throws, so nothing in a template calls these directly). + */ + +function assertAmount(milli: number): void { + if (!Number.isSafeInteger(milli)) throw new RangeError("an amount is a whole number of milli-SU"); +} + +/** Whole milli-SU as SU with exactly three decimals: 12500 is `12.500`, -500 is `-0.500`. Integer math only. */ +export function suFixed(milli: number): string { + assertAmount(milli); + const abs = Math.abs(milli); + const whole = Math.floor(abs / 1000); + const fraction = String(abs % 1000).padStart(3, "0"); + return `${milli < 0 ? "-" : ""}${whole}.${fraction}`; +} + +/** + * The shortest exact decimal of whole milli-SU: 2500 is `2.5`, 10000 is `10`, -500 is `-0.5`. The same + * rule as `formatSu` in nemar-cli `shared/contract/compute.ts`; this page uses it for axis ticks (every + * tick is an exact multiple of the step), and `suFixed` for every amount a person compares with the CLI. + */ +export function formatSu(milli: number): string { + assertAmount(milli); + const abs = Math.abs(milli); + const whole = Math.floor(abs / 1000); + const fraction = String(abs % 1000) + .padStart(3, "0") + .replace(/0+$/, ""); + return `${milli < 0 ? "-" : ""}${whole}${fraction ? `.${fraction}` : ""}`; +} + +/** The sum of whole amounts; throws when a value, or the running sum, leaves the safe integer range. */ +export function sumMilli(values: readonly number[]): number { + let total = 0; + for (const value of values) { + assertAmount(value); + total += value; + if (!Number.isSafeInteger(total)) throw new RangeError("a sum of amounts left the safe range"); + } + return total; +} + +/** Whole seconds as `38s`, `4m 12s`, `1h 5m` (the CLI's `durationText`). `0` is `0s`, a real value. */ +export function formatDuration(seconds: number): string { + if (!Number.isSafeInteger(seconds) || seconds < 0) { + throw new RangeError("a duration is a non-negative whole number of seconds"); + } + if (seconds < 60) return `${seconds}s`; + if (seconds < 3600) return `${Math.floor(seconds / 60)}m ${seconds % 60}s`; + return `${Math.floor(seconds / 3600)}h ${Math.floor((seconds % 3600) / 60)}m`; +} + +const DB_TIME_RE = /^(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})$/; +const DAY_RE = /^(\d{4})-(\d{2})-(\d{2})$/; + +/** + * The backend's database time (`YYYY-MM-DD HH:MM:SS`, UTC, no zone marker) as epoch milliseconds, or + * null when it is not that shape or not a real instant. Parsed field by field with `Date.UTC`: the bare + * string is read as LOCAL time by some engines, which would move every time by the viewer's offset. + */ +export function parseDbTime(text: string): number | null { + const m = DB_TIME_RE.exec(text); + if (!m) return null; + const [y, mo, d, h, mi, s] = m.slice(1).map(Number); + const ms = Date.UTC(y, mo - 1, d, h, mi, s); + const back = new Date(ms); + if ( + back.getUTCFullYear() !== y || + back.getUTCMonth() !== mo - 1 || + back.getUTCDate() !== d || + back.getUTCHours() !== h || + back.getUTCMinutes() !== mi || + back.getUTCSeconds() !== s + ) { + return null; + } + return ms; +} + +/** The ISO 8601 instant (`2026-11-05T12:00:00Z`) for a database time, or null when it does not parse. */ +export function dbTimeToIso(text: string): string | null { + const ms = parseDbTime(text); + return ms === null ? null : `${new Date(ms).toISOString().slice(0, 19)}Z`; +} + +/** + * A database time as `YYYY-MM-DD HH:MM UTC`. A value that does not parse is returned as it came, so a + * strange time shows as text instead of as a wrong time (the caller renders it as a text node). + */ +export function formatUtcMinute(text: string): string { + const ms = parseDbTime(text); + return ms === null ? text : `${new Date(ms).toISOString().slice(0, 16).replace("T", " ")} UTC`; +} + +/** A database time as `YYYY-MM-DD HH:MM:SS UTC`, for a tooltip; the original text when it does not parse. */ +export function formatUtcSecond(text: string): string { + const ms = parseDbTime(text); + return ms === null ? text : `${new Date(ms).toISOString().slice(0, 19).replace("T", " ")} UTC`; +} + +const MONTHS = [ + "Jan", + "Feb", + "Mar", + "Apr", + "May", + "Jun", + "Jul", + "Aug", + "Sep", + "Oct", + "Nov", + "Dec", +] as const; + +/** The epoch day (days since 1970-01-01) of a `YYYY-MM-DD` day, or null when it is not a real day. */ +export function epochDay(day: string): number | null { + const m = DAY_RE.exec(day); + if (!m) return null; + const [y, mo, d] = m.slice(1).map(Number); + const ms = Date.UTC(y, mo - 1, d); + const back = new Date(ms); + if (back.getUTCFullYear() !== y || back.getUTCMonth() !== mo - 1 || back.getUTCDate() !== d) { + return null; + } + return ms / 86_400_000; +} + +/** The `YYYY-MM-DD` day for an epoch day. */ +export function dayFromEpoch(epoch: number): string { + return new Date(epoch * 86_400_000).toISOString().slice(0, 10); +} + +/** `2026-11-03` as `Nov 3`, locale-free so the server and the browser agree; the input when it is not a day. */ +export function formatDayShort(day: string): string { + const m = DAY_RE.exec(day); + if (!m || epochDay(day) === null) return day; + return `${MONTHS[Number(m[2]) - 1]} ${Number(m[3])}`; +} + +/** A database time as `Oct 20, 2026` (the UTC date), locale-free; the original text when it does not parse. */ +export function formatUtcDate(text: string): string { + const ms = parseDbTime(text); + if (ms === null) return text; + const d = new Date(ms); + return `${MONTHS[d.getUTCMonth()]} ${d.getUTCDate()}, ${d.getUTCFullYear()}`; +} diff --git a/src/lib/compute-jobs-dom.ts b/src/lib/compute-jobs-dom.ts new file mode 100644 index 00000000..fb45e924 --- /dev/null +++ b/src/lib/compute-jobs-dom.ts @@ -0,0 +1,108 @@ +/** + * Browser-side rows for the /compute jobs table's "Load more" (website ADR 0030 phase E2). + * + * The server renders the first page from `jobRowView` in `ComputeJobsTable.astro`; this module renders + * every later page from the SAME `jobRowView`, so the two are thin renderers over one place. It builds + * DOM with `createElement`, `createElementNS` and `textContent` ONLY. Backend strings (an app id, a + * partition, an unknown state) are therefore text nodes and can never become markup; + * `test/compute-dashboard-ui.test.ts` forbids `innerHTML`, `insertAdjacentHTML`, `outerHTML` and + * `set:html` in every Compute file to keep it that way. + * + * The class names are the contract with the table's global styles; keep them in step with + * `ComputeJobsTable.astro` and `ComputeBadge.astro`. + */ +import { COMPUTE_LABELS } from "./compute-labels"; +import type { JobRowView } from "./compute-view"; +import { iconPaths } from "./status-icons"; + +const SVG_NS = "http://www.w3.org/2000/svg"; + +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): SVGSVGElement { + const svg = doc.createElementNS(SVG_NS, "svg"); + svg.setAttribute("viewBox", "0 0 16 16"); + svg.setAttribute("width", "14"); + svg.setAttribute("height", "14"); + 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; +} + +/** The same pill as `ComputeBadge.astro`, as DOM. */ +export function badgeElement( + doc: Document, + badge: { label: string; tone: string; icon: string }, +): HTMLSpanElement { + const pill = el(doc, "span", `compute-badge compute-badge--${badge.tone}`); + pill.append(icon(doc, badge.icon), el(doc, "span", undefined, badge.label)); + return pill; +} + +function cell(doc: Document, label: string, className: string): HTMLTableCellElement { + const td = el(doc, "td", className); + td.dataset.label = label; + return td; +} + +/** One job as a table row. */ +export function jobRowElement(doc: Document, row: JobRowView): HTMLTableRowElement { + const L = COMPUTE_LABELS.jobs; + const tr = el(doc, "tr", "compute-jobs__row"); + + const id = cell(doc, L.job, "compute-jobs__cell compute-jobs__cell--id"); + if (row.href) { + const a = el(doc, "a", "compute-jobs__link", row.id); + a.setAttribute("href", row.href); + id.append(a); + } else { + id.append(el(doc, "span", "compute-jobs__id", row.id)); + } + + const state = cell(doc, L.state, "compute-jobs__cell compute-jobs__cell--state"); + state.append(badgeElement(doc, row.state)); + if (row.cancelRequested) { + state.append(el(doc, "span", "compute-jobs__cancel", L.cancelRequested)); + } + + const app = cell(doc, L.app, "compute-jobs__cell compute-jobs__cell--app"); + app.append( + el(doc, "span", undefined, row.app), + " ", + el(doc, "span", "compute-jobs__version", row.appVersion), + ); + + const partition = cell(doc, L.partition, "compute-jobs__cell"); + partition.textContent = row.partition; + + const door = cell(doc, L.frontDoor, "compute-jobs__cell"); + door.textContent = row.frontDoor; + + const created = cell(doc, L.created, "compute-jobs__cell compute-jobs__cell--created"); + const time = el(doc, "time", undefined, row.createdText); + if (row.createdIso) time.setAttribute("datetime", row.createdIso); + time.setAttribute("title", row.createdTitle); + created.append(time); + + const charged = cell(doc, L.charged, "compute-jobs__cell compute-jobs__cell--charged"); + charged.dataset.chargeKind = row.chargeKind; + charged.textContent = row.charged; + + tr.append(id, state, app, partition, door, created, charged); + return tr; +} diff --git a/src/lib/compute-labels.ts b/src/lib/compute-labels.ts new file mode 100644 index 00000000..b61f97c2 --- /dev/null +++ b/src/lib/compute-labels.ts @@ -0,0 +1,103 @@ +/** + * The short UI words of the `/compute` page: headings, column headers, button text, empty and error + * states (website ADR 0030 phase E2 addendum). Sentences that the command line also says are NOT here: + * they live in `./account-copy.ts` (mirrored from nemar-cli, ADR 0015). What is here is a label or a + * description of this page's own state, which the CLI does not print. + * + * `test/compute-dashboard-ui.test.ts` fails if a page or component under /compute types a long + * sentence outside this file and the copy table, which is how a sentence stays in one place. + */ + +export const COMPUTE_LABELS = { + pageTitle: "Compute", + pageDescription: "Your compute access, balances, usage and jobs.", + panels: { + access: "Access", + balances: "Balances", + usage: "Usage", + jobs: "Jobs", + queue: "Recent queue waits", + }, + pools: { cpu: "CPU", gpu: "GPU" }, + balance: { + granted: "Granted", + held: "Held", + charged: "Charged", + available: "Available", + nothingGranted: "Nothing granted", + }, + access: { + status: "Status", + since: "since", + forbidden: "This account cannot use compute yet.", + }, + usage: { + title: "Net charge per day in SU", + empty: "No charges in this period.", + showNumbers: "Show the numbers", + numbersNote: "Only days with a charge are listed.", + day: "Day", + total: "Total", + other: "Other partitions", + adjustmentsLine: "Adjustments and other partitions", + noJob: "No job", + partition: "Partition", + amount: "Amount", + negativeNote: + "A day with a net refund or correction in a partition is not drawn as a bar; it is in the table.", + window: "UTC days", + }, + jobs: { + job: "Job", + state: "State", + app: "App", + partition: "Partition", + frontDoor: "Front door", + created: "Created", + charged: "Charged", + empty: "No jobs yet.", + loadMore: "Load more", + loading: "Loading", + retry: "Retry", + loadFailed: "Could not load more jobs.", + refresh: "Refresh", + notChargedYet: "Not charged yet", + chargeUnknown: "Not known", + cancelRequested: "Cancel requested", + firstPage: "Back to the first page", + }, + queue: { + intro: + "Waits between the scheduler receiving a job and starting it, for recent jobs on the whole platform.", + partition: "Partition", + median: "Median", + p90: "90th percentile", + counted: "Jobs counted", + notEnough: "Not enough data", + none: "No partitions are offered right now.", + }, + notice: { + title: "Could not load", + missing: "The figures are missing, not zero.", + retry: "Try again", + session: "Your session expired. Sign in again.", + account: "This account cannot use compute yet.", + unavailable: "The server could not answer just now.", + timeout: "The server did not answer in time.", + network: "The server could not be reached.", + shape: "The server's answer was not in the expected form.", + rejected: "The server refused the request.", + notAvailableTitle: "Compute is not available on this server yet", + notAvailableBody: "The page cannot show your compute account until the server supports it.", + }, +} as const; + +/** The plural-aware word for a number of days in a queue window. */ +export function daysText(days: number): string { + return days === 1 ? "1 day" : `${days} days`; +} + +/** The polite announcement after "Load more" appended rows. */ +export function loadedText(count: number): string { + return `Loaded ${count} more ${count === 1 ? "job" : "jobs"}.`; +} diff --git a/src/lib/compute-view.test.ts b/src/lib/compute-view.test.ts new file mode 100644 index 00000000..140bb154 --- /dev/null +++ b/src/lib/compute-view.test.ts @@ -0,0 +1,483 @@ +/** + * View models of the /compute page, on bodies captured from the real routes + * (`bun scripts/capture-compute-read-fixtures.mjs` with NEMAR_CLI_DIR set; see the script header). + * A few cases need a value no route can serve (a hostile app id, which the database refuses; a pool the + * Worker has not announced). Those take a captured body and change the one field, parsed through the + * same guard the page uses. + */ +import { describe, expect, it } from "vitest"; +import jobsAll from "../../test/fixtures/compute/jobs-all-states.json"; +import jobsPage1 from "../../test/fixtures/compute/jobs-page1.json"; +import meActive from "../../test/fixtures/compute/me-active-with-usage.json"; +import meFrozen from "../../test/fixtures/compute/me-frozen.json"; +import meOverrun from "../../test/fixtures/compute/me-overrun.json"; +import meStates from "../../test/fixtures/compute/me-states.json"; +import meThin from "../../test/fixtures/compute/me-thin-queue.json"; +import usageDay from "../../test/fixtures/compute/usage-day-partition.json"; +import usageEmpty from "../../test/fixtures/compute/usage-empty.json"; +import { ACCOUNT_COPY } from "./account-copy"; +import { + ComputeApiError, + parseComputeJobs, + parseComputeMe, + parseComputeUsage, +} from "./compute-api"; +import { COMPUTE_QUEUE_MIN_SAMPLES } from "./compute-contract"; +import { + accessView, + balancesView, + jobRowView, + jobsView, + noticeFor, + panelsFor, + queueView, + usageView, +} from "./compute-view"; + +const me = (body: unknown) => parseComputeMe(body); + +describe("panelsFor", () => { + it("shows all five panels for an active account and reads the ledger", () => { + expect(panelsFor("active")).toEqual({ + access: true, + balances: true, + usage: true, + jobs: true, + queue: true, + readLedger: true, + }); + }); + + it("keeps history and balance read-only for a suspended or ended account, with no queue", () => { + for (const state of ["suspended", "revoked"]) { + expect(panelsFor(state), state).toEqual({ + access: true, + balances: true, + usage: true, + jobs: true, + queue: false, + readLedger: true, + }); + } + }); + + it("shows the Access panel alone, and reads nothing, for every other state", () => { + for (const state of ["none", "requested", "denied", "paused", "constructor", "", null]) { + const plan = panelsFor(state); + expect(plan, String(state)).toEqual({ + access: true, + balances: false, + usage: false, + jobs: false, + queue: false, + readLedger: false, + }); + } + }); + + it("reads nothing for an unverified account whatever state it carries", () => { + expect(panelsFor("active", { unverified: true }).readLedger).toBe(false); + expect(panelsFor("active", { unverified: true }).balances).toBe(false); + }); +}); + +describe("noticeFor", () => { + it("names the panel, says the figures are missing, and gives the reason class", () => { + const n = noticeFor("Usage", new ComputeApiError("timeout", 0)); + expect(n.title).toBe("Could not load usage"); + expect(n.missing).toBe("The figures are missing, not zero."); + expect(n.reason).toBe("The server did not answer in time."); + expect(n.sentence).toBeNull(); + }); + + it("carries the backend's sentence as escaped text, but not a shape error's own", () => { + const rejected = noticeFor( + "Jobs", + new ComputeApiError( + "rejected", + 400, + "invalid_cursor", + "after is not a cursor this route gave.‮", + ), + ); + expect(rejected.sentence).toBe("after is not a cursor this route gave.\\u202e"); + const shaped = noticeFor("Jobs", new ComputeApiError("shape", 200, undefined, "ours")); + expect(shaped.sentence).toBeNull(); + }); + + it("treats a builder's RangeError as an unexpected response, not a crash", () => { + expect(noticeFor("Balances", new RangeError("x")).reason).toBe( + "The server's answer was not in the expected form.", + ); + }); +}); + +describe("accessView", () => { + it("none with requests closed says the terms are unpublished and offers no link", () => { + const view = accessView("none", me(meStates.none.body)); + expect(view.badge.label).toBe("Not requested"); + expect(view.paragraphs).toEqual([ACCOUNT_COPY["compute_access.terms_unpublished.body"]]); + expect(view.link).toBeNull(); + }); + + it("none with requests open links the request card in Settings", () => { + const view = accessView("none", me(meStates.none_requests_open.body)); + expect(view.link).toEqual({ + href: "/settings#compute-access", + label: ACCOUNT_COPY["compute_access.request.cta"], + }); + expect(view.paragraphs).toEqual([]); + }); + + it("falls back to terms_published when the API sends no requests_open", () => { + const body = structuredClone(meStates.none.body) as { access: Record }; + body.access.requests_open = undefined; + body.access.terms_published = true; + expect(accessView("none", me(body)).link).not.toBeNull(); + body.access.terms_published = false; + expect(accessView("none", me(body)).link).toBeNull(); + }); + + it("none says only the state when the account read failed", () => { + const view = accessView("none", null); + expect(view.paragraphs).toEqual([]); + expect(view.link).toBeNull(); + }); + + it("requested prints the dated lede and the body", () => { + const view = accessView("requested", me(meStates.requested.body)); + expect(view.paragraphs).toEqual([ + "An admin is reviewing your request from Oct 20, 2026.", + ACCOUNT_COPY["compute_access.requested.body"], + ]); + }); + + it("requested falls back to the undated lede", () => { + expect(accessView("requested", null).paragraphs[0]).toBe( + ACCOUNT_COPY["compute_access.requested.lede"], + ); + }); + + it("suspended, denied and revoked use their own sentences", () => { + expect(accessView("suspended", me(meStates.suspended.body)).paragraphs).toEqual([ + ACCOUNT_COPY["compute_access.suspended.body"], + ]); + for (const state of ["denied", "revoked"] as const) { + expect(accessView(state, me(meStates[state].body)).paragraphs).toEqual([ + ACCOUNT_COPY["compute_access.closed.body"], + ]); + } + expect(accessView("revoked", null).badge.label).toBe("Ended"); + }); + + it("shows the frozen sentence only for an active account whose pool is frozen", () => { + const frozen = me(meFrozen.body); + expect(frozen.frozen).toBe(true); + expect(accessView("active", frozen, { frozen: frozen.frozen }).paragraphs).toEqual([ + ACCOUNT_COPY["compute_page.frozen.body"], + ]); + expect(accessView("active", me(meActive.body), { frozen: false }).paragraphs).toEqual([]); + // The CLI's rule, not the issue's: every other state already has its own sentence. + for (const state of ["suspended", "revoked", "denied", "requested", "none"]) { + expect(accessView(state, frozen, { frozen: true }).frozen, state).toBe(false); + } + }); + + it("gives an active account the date it began", () => { + expect(accessView("active", me(meActive.body)).grantedSince).toBe("Oct 24, 2026"); + }); + + it("prints a state outside the six as inert raw text in a neutral badge, and decides nothing", () => { + const view = accessView("paused‮", null); + expect(view.known).toBe(false); + expect(view.badge).toMatchObject({ label: "paused\\u202e", tone: "neutral" }); + expect(view.paragraphs).toEqual([]); + expect(view.link).toBeNull(); + expect(accessView("constructor", null).known).toBe(false); + }); +}); + +describe("balancesView", () => { + it("prints the CLI's digits for the active fixture, CPU then GPU", () => { + const view = balancesView(me(meActive.body)); + expect(view.pools.map((p) => p.name)).toEqual(["CPU", "GPU"]); + expect(view.pools[0].rows.map((r) => [r.label, r.text])).toEqual([ + ["Granted", "100.000"], + ["Held", "20.000"], + ["Charged", "40.200"], + ["Available", "39.800"], + ]); + expect(view.pools[1].rows.map((r) => r.text)).toEqual(["40.000", "0.000", "15.250", "24.750"]); + expect(view.pools[0].barPercent).toBeCloseTo(39.8, 3); + }); + + it("prints a negative available as negative, flagged, with an empty bar", () => { + const view = balancesView(me(meOverrun.body)); + const cpu = view.pools[0]; + expect(cpu.rows.find((r) => r.key === "available")).toMatchObject({ + text: "-2.500", + negative: true, + }); + expect(cpu.negativeAvailable).toBe(true); + expect(cpu.barPercent).toBe(0); + expect(view.anyNegative).toBe(true); + }); + + it("says nothing was granted, with no bar, rather than a bar of NaN", () => { + const view = balancesView(me(meStates.active.body)); + expect(view.pools.every((p) => p.nothingGranted && p.barPercent === null)).toBe(true); + expect(view.pools[0].rows.map((r) => r.text)).toEqual(["0.000", "0.000", "0.000", "0.000"]); + }); + + it("carries the units and available notes from the shared copy", () => { + expect(balancesView(me(meActive.body)).notes).toEqual([ + ACCOUNT_COPY["compute_page.units_note"], + ACCOUNT_COPY["compute_page.available_note"], + ]); + }); + + it("never renders a pool the Worker adds, a shared allocation or a platform figure", () => { + const body = { + ...meActive.body, + pools: { + ...meActive.body.pools, + tenant: { + granted_milli: 777_000, + held_milli: 0, + charged_milli: 0, + available_milli: 777_000, + }, + }, + platform_remaining_milli: 123_456, + shared_allocation: { granted_milli: 888_000 }, + }; + const view = balancesView(me(body)); + expect(view.pools).toHaveLength(2); + const text = JSON.stringify(view); + for (const leaked of ["777", "123.456", "888", "tenant", "platform", "shared"]) { + expect(text, leaked).not.toContain(leaked); + } + expect(view.pools.map((p) => p.pool)).toEqual(["cpu", "gpu"]); + }); +}); + +describe("queueView", () => { + it("prints durations for a partition with figures, and 0s for a real zero", () => { + const view = queueView(me(meActive.body)); + const shared = view.rows.find((r) => r.partition === "shared"); + expect(shared).toMatchObject({ + median: "40s", + p90: "1h 1m", + counted: "7 in 7 days", + thin: false, + }); + const gpuShared = view.rows.find((r) => r.partition === "gpu-shared"); + expect(gpuShared).toMatchObject({ median: "0s", p90: "0s", thin: false }); + }); + + it("reads 'Not enough data' with the count and the minimum when a figure is null", () => { + const view = queueView(me(meThin.body)); + const compute = view.rows.find((r) => r.partition === "compute"); + expect(COMPUTE_QUEUE_MIN_SAMPLES).toBe(5); + expect(compute).toMatchObject({ + median: "Not enough data", + p90: "Not enough data", + counted: "3 of 5 in 7 days", + thin: true, + }); + for (const row of view.rows) { + for (const cell of [row.median, row.p90, row.counted]) { + expect(cell).not.toBe("-"); + expect(cell).not.toBe(""); + expect(cell).not.toBe("0"); + } + } + }); + + it("a partition nobody has waited on yet shows a count of 0 of 5, not a dash", () => { + const view = queueView(me(meThin.body)); + expect(view.rows.find((r) => r.partition === "debug")?.counted).toBe("0 of 5 in 7 days"); + }); + + it("says no partitions are offered for an empty queue", () => { + const body = { ...meActive.body, queue: [] }; + const view = queueView(me(body)); + expect(view.empty).toBe(true); + expect(view.emptyText).toBe("No partitions are offered right now."); + }); + + it("ends with the shared note, and never promises a wait", () => { + const view = queueView(me(meActive.body)); + expect(view.note).toBe(ACCOUNT_COPY["compute_page.queue_note"]); + expect(JSON.stringify(view)).not.toMatch(/estimated wait|your wait/i); + }); +}); + +describe("jobRowView", () => { + const jobs = parseComputeJobs(jobsAll.body).jobs; + const first = parseComputeJobs(jobsPage1.body).jobs[0]; + + it("links a well-formed id and times it in UTC", () => { + const row = jobRowView(first); + expect(row.href).toBe(`/compute/jobs/${first.id}`); + expect(row.createdIso).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/); + expect(row.createdText).toMatch(/ UTC$/); + expect(row.frontDoor).toBe("Command line"); + }); + + it("prints a true zero for a finished job and 'Not charged yet' for a live one", () => { + const base = jobs.find((j) => j.state === "running") as (typeof jobs)[number]; + expect(jobRowView({ ...base, charged_milli: 0 })).toMatchObject({ + charged: "Not charged yet", + chargeKind: "live", + }); + const finished = jobs.find((j) => j.state === "finished") as (typeof jobs)[number]; + expect(jobRowView({ ...finished, charged_milli: 0 })).toMatchObject({ + charged: "0.000", + chargeKind: "terminal", + }); + expect(jobRowView(finished).charged).toBe("2.500"); + const failed = jobs.find((j) => j.state === "failed") as (typeof jobs)[number]; + expect(jobRowView(failed).charged).toBe("0.000"); + }); + + it("does not claim zero or 'not yet' for a state it does not know", () => { + const row = jobRowView({ ...first, state: "paused", charged_milli: 0 }); + expect(row.chargeKind).toBe("unknown"); + expect(row.charged).toBe("Not known"); + expect(row.state).toMatchObject({ known: false, label: "paused", tone: "neutral" }); + expect(jobRowView({ ...first, state: "paused", charged_milli: 1500 }).charged).toBe("1.500"); + }); + + it("marks a cancel request on a live job only", () => { + const running = jobs.find((j) => j.cancel_requested) as (typeof jobs)[number]; + expect(jobRowView(running).cancelRequested).toBe(true); + expect(jobRowView({ ...running, state: "finished" }).cancelRequested).toBe(false); + }); + + it("renders no link for an id that fails the pattern, rather than a guessed one", () => { + for (const id of ["job_xyz", "../admin", `job_${"G".repeat(24)}`, "javascript:alert(1)", ""]) { + expect(jobRowView({ ...first, id }).href, id).toBeNull(); + } + }); + + it("keeps hostile text inert: it is escaped, never interpreted", () => { + const row = jobRowView({ + ...first, + app_id: '‮evil\u0007', + app_version: "1.0", + partition: "