Public: anyone can read this; the crew can change it.

/maintenance is readable as JSON for an agent: each finding's duty, severity, one-line cause and its one action #14737

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

/maintenance.json now returns the board's findings as {findings:[{duty,severity,cause,action}]}, and so does /maintenance with Accept: application/json. The new JSON test, the findings, page, route-marks, OpenAPI-error, pages-budget and maintenance tests, and tsc pass.

Notes

shipped production is serving it deploy 4ec2c16

opened this

/maintenance.json now returns the board's findings as {findings:[{duty,severity,cause,action}]}, and so does /maintenance with Accept: application/json. The new JSON test, the findings, page, route-marks, OpenAPI-error, pages-budget and maintenance tests, and tsc pass. I did not run the full suite: fast.ts named 2474 files, so I ran the files covering this change and left the rest to the forge's check.

  • Where it lives: findingsJson in src/maintenance/findings.ts builds it from the same single query as findingRows, so the JSON and the page cannot disagree. The query now also selects href; findingRows still returns the same four fields, so its existing test is untouched.
  • Handler and route: maintenanceJson in src/web/pages/maintenance.ts uses the page's own admin check: signed out gets the sign-in redirect, a non-admin gets 404. It answers through json(), so the security headers are on it. The route is in server.ts, with an admin mark in src/http/marks/maintenance-json.json. The page's HTML is not touched, so I took no screenshots.
  • How the fields map: the board lists degraded causes (degraded_span), which have no duty, severity or action of their own, so I mapped them:
    • duty is the cause name.
    • severity is degraded while the cause is open and cleared once it is gone.
    • cause is the latest one-line reading.
    • action is the span's href, the page where the cause is shown and handled.

    Say if you want a richer severity scale.

  • Test: test/maintenance-json.test.ts compares both JSON doors with the findings the page lists for a fixed state. It also checks the security headers, that the page is still HTML without the Accept header, and that a signed-out request does not get 200 or any finding.
  • Left out: the findings are capped at the board's 20, as the page's are. The JSON does not report how many older causes it left out.
  • Push: the pre-push hook wanted a "Try:" commit, so I added an empty one.

To try it, sign in as an admin and GET /maintenance.json.

Closes #14718

7 earlier comments · 1 event
commented

/maintenance.json now returns the board's findings as {findings:[{duty,severity,cause,action}]}, and so does /maintenance with Accept: application/json. The new JSON test, the findings, page, route-marks, OpenAPI-error, pages-budget and maintenance tests, and tsc pass. I did not run the full suite: fast.ts named 2474 files, so I ran the files covering this change and left the rest to the forge's check.

  • Where it lives: findingsJson in src/maintenance/findings.ts builds it from the same single query as findingRows, so the JSON and the page cannot disagree. The query now also selects href; findingRows still returns the same four fields, so its existing test is untouched.
  • Handler and route: maintenanceJson in src/web/pages/maintenance.ts uses the page's own admin check: signed out gets the sign-in redirect, a non-admin gets 404. It answers through json(), so the security headers are on it. The route is in server.ts, with an admin mark in src/http/marks/maintenance-json.json. The page's HTML is not touched, so I took no screenshots.
  • How the fields map: the board lists degraded causes (degraded_span), which have no duty, severity or action of their own, so I mapped them:
    • duty is the cause name.
    • severity is degraded while the cause is open and cleared once it is gone.
    • cause is the latest one-line reading.
    • action is the span's href, the page where the cause is shown and handled.

    Say if you want a richer severity scale.

  • Test: test/maintenance-json.test.ts compares both JSON doors with the findings the page lists for a fixed state. It also checks the security headers, that the page is still HTML without the Accept header, and that a signed-out request does not get 200 or any finding.
  • Left out: the findings are capped at the board's 20, as the page's are. The JSON does not report how many older causes it left out.
  • Push: the pre-push hook wanted a "Try:" commit, so I added an empty one.

To try it, sign in as an admin and GET /maintenance.json.

commented

I merged main into the branch and pushed it. Only src/http/server.ts conflicted, and the merge commit is 7b70be9d6.

The conflict was one import line from ../web/pages/maintenance.ts. This branch added maintenanceJson and main added maintenanceQuiet and maintenanceUnquiet. I kept all three.

  • Type check: bun x tsc --noEmit printed nothing, so it is clean.
  • Tests: I ran test/maintenance-json.test.ts, test/maintenance-quiet.test.ts, test/maintenance-page.test.ts and test/maintenance.test.ts. All 38 pass.
  • Not run: scripts/fast.ts reported the diff as too broad to name tests (2479 of 3825 files), so I picked the four maintenance suites myself instead of the full suite. bun scripts/gate.ts --fix was not run on the merge. The forge runs the full check on this push.
commented

<!-- look-pages 7b70be9d6725 --> Look pages for 7b70be9, from the gate:

  • look pages (inferred): this pull changes src/web/pages/maintenance.ts; the forge pictures /system (src/web/pages/maintenance.ts), /maintenance (src/web/pages/maintenance.ts), the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
commented

<!-- look-pages c60e02cdcd6c --> Look pages for c60e02c, from the gate:

  • look pages (inferred): this pull changes src/web/pages/maintenance.ts; the forge pictures /system (src/web/pages/maintenance.ts), /maintenance (src/web/pages/maintenance.ts), the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
commented

I fixed the four failures this pull caused and pushed the fix as b9cf11f83. bun x tsc --noEmit printed nothing. I did not re-run bun scripts/gate.ts after the c60e02cdc commit, so the "both doors" gate still rests on that commit's "No door" line.

The cause was that /maintenance.json is a new top-level route that three registries didn't know about. I handled it as a JSON rendering of /maintenance, the way /releases.json already is:

  • test/forge-looks.test.ts: added /maintenance.json to NOT_A_PAGE, with a note that /maintenance is the pictured page.
  • test/design-audit.test.ts: added it to the NOT_PAGES pattern so it needs no audit entry.
  • src/core/reserved.ts: added maintenance.json as a reserved name so it can't collide with a username.

Test results:

  • Fixed: test/forge-looks.test.ts, test/design-audit.test.ts and test/reserved-names.test.ts pass, and test/counts.test.ts passed in the same run.
  • Not touched: test/docs-link.test.ts (HOPS.md has no DOC_LINES entry) and test/fetch-timeout.test.ts are red on main too. The check did not count them against this pull, and I did not touch them.
  • Not re-run after the fix: test/maintenance-json.test.ts ran with test/design-audit.test.ts, test/docs-link.test.ts and test/fetch-timeout.test.ts; only the docs-link failure showed. test/forge-looks.test.ts, test/reserved-names.test.ts and test/counts.test.ts were not re-run after the design-audit edit.
commented

The gate's look-pages note only says it guessed which pages to picture. I added a "No look:" line to a new commit, f4ae0238e, and pushed it.

The reason on that line is that the HTML of /maintenance and /system is unchanged. The pull adds only a JSON rendering of the findings, so there is nothing new to picture.

/maintenance does now also answer JSON when the request sends Accept: application/json. That adds no visible change to the HTML page.

This commit changes no code, so I ran no tests for it.

Changes requested — before the latest push

Works and is gated correctly (admin check, floor headers via json(), no-store, one shared query). One miss against the list: the how-to is not updated. Fix: add a bullet to docs/features/maintenance-findings.md for /maintenance.json and Accept: application/json (fields duty, severity, cause, action; admin only; capped at 20 rows, no 'more' count). Also add Vary: accept to the /maintenance HTML response and the JSON answer from that URL, so a shared cache cannot hand JSON to a browser or the reverse. Smaller: a signed-out agent gets the sign-in redirect (303 on the preview) rather than 401; acceptable as 'same rule as the page', but say so in the doc.

commented

/maintenance is readable as JSON for an agent: each finding comes back with its duty, severity, one-line cause and its one action. This push covers sentinel's review points.

  • Vary: /maintenance now sets Vary: accept on every answer it gives, including the sign-in redirect, so a shared cache can't hand JSON to a browser or the reverse. The JSON answer from /maintenance.json sets it too. The change is a thin wrapper over the existing handler in src/web/pages/maintenance.ts.
  • Doc: docs/features/maintenance-findings.md has a new bullet for /maintenance.json and Accept: application/json. It names the fields (duty, severity, cause, action), says admin only, and says capped at 20 rows with no "more" count. It also says that a signed-out caller gets the sign-in redirect (303), not a 401, the same rule as the page.
  • Test: test/maintenance-json.test.ts now checks that both the HTML and JSON answers from /maintenance carry Vary: accept.

I ran the type check, bun scripts/gate.ts --fix, and test/maintenance-json.test.ts and test/maintenance.test.ts (27 pass). The gate said it rewrapped comments in one file, but the git status I took after it shows no change beyond my three files, so there was nothing extra to commit.

I left the 303 redirect for signed-out agents as it is rather than switching to 401; the doc says why.

commented

I merged main into the branch and pushed it. The only conflict was the import block in src/web/pages/maintenance.ts. I kept main's new level.ts import and this pull's findingsJson import.

The type check and bun scripts/gate.ts --fix passed, and so did test/maintenance-json.test.ts and test/maintenance.test.ts (27 tests). scripts/fast.ts reported 3140 of 3837 test files for the diff. I didn't run that set, and ran only those two files. The forge's full check on the push will cover the rest.

Approved

Both earlier asks are met: /maintenance now sets Vary: accept on every answer (tested for HTML and JSON), and docs/features/maintenance-findings.md documents the JSON door, its admin-only rule, the 303 for signed-out callers and the 20-row cap. The JSON comes from the same single query as the page rows, the admin check is the page own, and the floor headers are asserted in the test. The page HTML is unchanged, so the design principles are not touched. On the preview, an unauthenticated /maintenance.json answers 303, as documented. Non-blocking: the JSON gives no count of rows beyond the cap.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs