Public: anyone can read this; the crew can change it.
The boards list and the caller's board pins answer `{ items, next_cursor }` #5053
scout/forge:scout/5045-the-boards-list-and-the-caller-s-board-p → main 3 commits fork 1 thread · 1 unresolved
7 files
changed +94
−8
README.md +2 −2
| @@ -1977,11 +1977,11 @@ work here. | ||
| 1977 | 1977 | Any panel has **Pin to home** / **Unpin** on its board page (a same-origin POST); pins are per admin, kept in `board_pin` (slug + panel title + position, `boards/pins.ts`), and home draws them under the KPI row in that person's order with Up, Down and Unpin beside each (`web/studio/pinned.ts`). A pin whose panel is gone is skipped, does not count toward the limit of 24, and is dropped at that person's next pin; nobody sees another's pins. All doors go through `actions/board-pins.ts` (an admin who is a person; anyone else gets not-found): |
| 1978 | 1978 | - the page (Pin to home / Unpin on `/boards/:slug`, Up / Down / Unpin on home); |
| 1979 | 1979 | - the terminal: on a board's screen `[` `]` mark a panel, `p` pins or unpins it, `<` `>` move a pinned one; the dashboard lists the pinned panels by title; |
| 1980 | - `GET /api/v1/boards/pins` (the list, in order) and `POST /api/v1/boards/pins` with `{"op":"pin|unpin|move","slug":"…","title":"…","by":-1|1}` (`by` for move only); | |
| 1980 | - `GET /api/v1/boards/pins` (the list, in order, as `{ items, next_cursor }` with `limit` 1–200, default 50, and `cursor`) and `POST /api/v1/boards/pins` with `{"op":"pin|unpin|move","slug":"…","title":"…","by":-1|1}` (`by` for move only); | |
| 1981 | 1981 | - the `board_pins` MCP tool (no `op` lists; `op` pin, unpin or move changes). `pins` is therefore not a board slug. |
| 1982 | 1982 | The first boot also writes the starting boards, **Usage**, **Serving**, **Crew**, **Releases**, **Apps**, **Security**, **Throughput**, **Reach** and **Forges**; Serving is the forge's event-loop lag p99 beside the checks and crew runs running, so checks' concurrency is raised on numbers. Apps' per-app panels show repo ids until a source exposes a safe name; Security (sign-ins, failed sign-ins, tokens by scope, admin actions, from the admin-only `signins`, `tokens` and `adminActions` sources and `usage`) shows no token text, hash, payload or IP; Throughput is items entering each stage from issue to live, per hour, from the `stages` source. Each is written once: `.offered` in that repo records them, so an edit stays and a deletion sticks. |
| 1983 | 1983 | A live board (any `refresh` but `off`; the form offers off or on, and `10s` and `1m` are still accepted and mean the same) redraws its grid when a run, pull, check, issue or usage event arrives, through the live-region swap |
| 1984 | (`/boards/:slug/live`, etag'd, one fetch per burst). The same doors are in the API: `GET /api/v1/boards`, `GET|PUT|DELETE /api/v1/boards/:slug`, and each panel's data as JSON or CSV at `GET /api/v1/boards/:slug/panels/:id?from=&to=&step=5m&format=csv`, bucketed in SQL to the step and never cut short (`docs/APPS.md`); each panel's card links `json` and `csv` (a plain download link) beside `explore` | |
| 1984 | (`/boards/:slug/live`, etag'd, one fetch per burst). The same doors are in the API: `GET /api/v1/boards` (`{ items, next_cursor }`, paged like the pins), `GET|PUT|DELETE /api/v1/boards/:slug`, and each panel's data as JSON or CSV at `GET /api/v1/boards/:slug/panels/:id?from=&to=&step=5m&format=csv`, bucketed in SQL to the step and never cut short (`docs/APPS.md`); each panel's card links `json` and `csv` (a plain download link) beside `explore` | |
| 1985 | 1985 | (an agent or anyone but an admin is 403; a panel whose query cannot run is refused with 422). The same four doors are MCP tools (`boards`, `board_write`, `board_delete`; `boards` with a `slug` reads one, and with a `panel` too that panel's data, with the same `from`, `to` and `step`) and, for the same person, a **Boards** screen in the terminal that lists boards and shows a board's panels as text, each with what its data holds now (a time panel's last bucket and step, another's row count). No dependency was added. |
| 1986 | 1986 | - **Issues** — labels, threaded comments, close/reopen, markdown. |
| 1987 | 1987 | - **Pull requests** — open from a branch, a **beautiful diff viewer** (syntax |
src/core/list_page.ts added +21
| @@ -0,0 +1,21 @@ | ||
| 1 | import { eventsLimit } from "./events_page.ts"; | |
| 2 | ||
| 3 | /** `?limit=&cursor=` for a short list kept whole in memory: the cursor is the offset of the next item. */ | |
| 4 | export type ListWindow = { limit: number; offset: number }; | |
| 5 | ||
| 6 | export function listWindow( | |
| 7 | limit: string | null, | |
| 8 | cursor: string | null, | |
| 9 | ): { ok: true; value: ListWindow } | { ok: false; error: "invalid_limit" | "invalid_cursor" } { | |
| 10 | const n = eventsLimit(limit ?? undefined); | |
| 11 | if (n === undefined) return { ok: false, error: "invalid_limit" }; | |
| 12 | if (cursor !== null && !/^[1-9]\d{0,5}$/.test(cursor)) return { ok: false, error: "invalid_cursor" }; | |
| 13 | return { ok: true, value: { limit: n, offset: cursor === null ? 0 : Number(cursor) } }; | |
| 14 | } | |
| 15 | ||
| 16 | /** One page of `all`: `{ items, next_cursor }`, the cursor null at the end. */ | |
| 17 | export function pageOf<T>(all: T[], w: ListWindow): { items: T[]; next_cursor: string | null } { | |
| 18 | const items = all.slice(w.offset, w.offset + w.limit); | |
| 19 | const end = w.offset + items.length; | |
| 20 | return { items, next_cursor: end < all.length ? String(end) : null }; | |
| 21 | } |
src/http/api.ts +16 −2
| @@ -179,6 +179,7 @@ import { | ||
| 179 | 179 | updateProfile, |
| 180 | 180 | } from "../actions/users.ts"; |
| 181 | 181 | import { EVENTS_LIMIT_MAX, eventsLimit, eventsPage, validEventsCursor } from "../core/events_page.ts"; |
| 182 | import { listWindow, pageOf } from "../core/list_page.ts"; | |
| 182 | 183 | import { audienceFor } from "../core/audience.ts"; |
| 183 | 184 | import { |
| 184 | 185 | forkParentFor, |
| @@ -1553,14 +1554,25 @@ export function apiRoutes(router: Router<Handler>): void { | ||
| 1553 | 1554 | return apiError(e, e === "exists" || e === "branch_moved" ? 409 : 422, "that board could not be saved"); |
| 1554 | 1555 | }; |
| 1555 | 1556 | |
| 1557 | // `?limit=&cursor=` of the boards and pins lists, or the 422 that refuses them. | |
| 1558 | const boardsWindow = (ctx: Ctx) => { | |
| 1559 | const w = listWindow(ctx.url.searchParams.get("limit"), ctx.url.searchParams.get("cursor")); | |
| 1560 | if (w.ok) return w.value; | |
| 1561 | return w.error === "invalid_limit" | |
| 1562 | ? apiError("invalid_limit", 422, `limit is a whole number from 1 to ${LIST_LIMIT_MAX}`) | |
| 1563 | : apiError("invalid_cursor", 422, "cursor is the next_cursor of a page before"); | |
| 1564 | }; | |
| 1565 | ||
| 1556 | 1566 | router.add("GET", "/api/v1/boards", async (ctx) => { |
| 1557 | 1567 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); |
| 1558 | 1568 | const denied = boardsAdmin(ctx); |
| 1559 | 1569 | if (denied) return denied; |
| 1570 | const win = boardsWindow(ctx); | |
| 1571 | if (win instanceof Response) return win; | |
| 1560 | 1572 | const listed = await timePhaseAsync(ctx.request, "boards", () => listAllBoards(ctx.app, ctx.auth.user)); |
| 1561 | 1573 | return timePhase(ctx.request, "render", () => |
| 1562 | 1574 | listed.ok |
| 1563 | ? json({ boards: listed.value.map((b) => ({ slug: b.slug, ...b.board })) }) | |
| 1575 | ? json(pageOf(listed.value.map((b) => ({ slug: b.slug, ...b.board })), win)) | |
| 1564 | 1576 | : notFound()); |
| 1565 | 1577 | }); |
| 1566 | 1578 | |
| @@ -1570,9 +1582,11 @@ export function apiRoutes(router: Router<Handler>): void { | ||
| 1570 | 1582 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); |
| 1571 | 1583 | const denied = boardsAdmin(ctx); |
| 1572 | 1584 | if (denied) return denied; |
| 1585 | const win = boardsWindow(ctx); | |
| 1586 | if (win instanceof Response) return win; | |
| 1573 | 1587 | const listed = await timePhaseAsync(ctx.request, "boards", () => listPinnedPanels(ctx.app, ctx.auth.user)); |
| 1574 | 1588 | return timePhase(ctx.request, "render", () => |
| 1575 | listed.ok ? json({ pins: listed.value.map((p) => ({ slug: p.slug, title: p.title, panel: p.panel })) }) : notFound()); | |
| 1589 | listed.ok ? json(pageOf(listed.value.map((p) => ({ slug: p.slug, title: p.title, panel: p.panel })), win)) : notFound()); | |
| 1576 | 1590 | }); |
| 1577 | 1591 | |
| 1578 | 1592 | router.add("POST", "/api/v1/boards/pins", async (ctx) => { |
test/api-boards-timing.test.ts +1 −1
| @@ -53,7 +53,7 @@ test("each board read names session, boards, render in order", async () => { | ||
| 53 | 53 | expect(got.status).toBe(200); |
| 54 | 54 | expect(got.names).toEqual(["session", "boards", "render"]); |
| 55 | 55 | } |
| 56 | expect(JSON.parse((await phases("/api/v1/boards")).body).boards[0].slug).toBe("ops"); | |
| 56 | expect(JSON.parse((await phases("/api/v1/boards")).body).items[0].slug).toBe("ops"); | |
| 57 | 57 | }); |
| 58 | 58 | |
| 59 | 59 | test("a missing board still names its phases", async () => { |
test/board-pins.test.ts +16 −1
| @@ -124,7 +124,7 @@ describe("pinned panels", () => { | ||
| 124 | 124 | method, headers: { authorization: `Bearer ${tok[who]}`, "content-type": "application/json" }, |
| 125 | 125 | ...(body === undefined ? {} : { body: JSON.stringify(body) }), |
| 126 | 126 | }); |
| 127 | const titlesOf = async (who: string) => ((await (await api(who, "GET")).json()) as { pins: { title: string }[] }).pins.map((p) => p.title); | |
| 127 | const titlesOf = async (who: string) => ((await (await api(who, "GET")).json()) as { items: { title: string }[] }).items.map((p) => p.title); | |
| 128 | 128 | expect(await titlesOf("alice")).toEqual(["Pin A", "Pin B", "Pin C2"]); |
| 129 | 129 | expect((await api("alice", "POST", { op: "move", slug: "mine", title: "Pin C2", by: -1 })).status).toBe(200); |
| 130 | 130 | expect(await titlesOf("alice")).toEqual(["Pin A", "Pin C2", "Pin B"]); |
| @@ -133,6 +133,21 @@ describe("pinned panels", () => { | ||
| 133 | 133 | expect(await titlesOf("alice")).toEqual(["Pin C2", "Pin B", "Pin A"]); |
| 134 | 134 | expect((await api("alice", "POST", { op: "pin", slug: "mine", title: "nope" })).status).toBe(404); |
| 135 | 135 | expect((await api("alice", "POST", { op: "dance" })).status).toBe(422); |
| 136 | const get = async (q: string) => | |
| 137 | (await (await fetch(servers.url + "/api/v1/boards/pins" + q, { headers: { authorization: `Bearer ${tok["alice"]}` } })).json()) as | |
| 138 | { items: { title: string }[]; next_cursor: string | null }; | |
| 139 | const first = await get("?limit=2"); | |
| 140 | expect(first.items.map((p) => p.title)).toEqual(["Pin C2", "Pin B"]); | |
| 141 | expect(first.next_cursor).toBe("2"); | |
| 142 | const last = await get("?limit=2&cursor=2"); | |
| 143 | expect(last.items.map((p) => p.title)).toEqual(["Pin A"]); | |
| 144 | expect(last.next_cursor).toBeNull(); | |
| 145 | for (const q of ["?limit=0", "?limit=201", "?limit=x"]) { | |
| 146 | const bad = await fetch(servers.url + "/api/v1/boards/pins" + q, { headers: { authorization: `Bearer ${tok["alice"]}` } }); | |
| 147 | expect(bad.status).toBe(422); | |
| 148 | } | |
| 149 | const badCursor = await fetch(servers.url + "/api/v1/boards/pins?cursor=zz", { headers: { authorization: `Bearer ${tok["alice"]}` } }); | |
| 150 | expect(badCursor.status).toBe(422); | |
| 136 | 151 | expect((await api("bob", "GET")).status).toBe(403); |
| 137 | 152 | expect((await api("bob", "POST", { op: "pin", slug: "mine", title: "Pin A" })).status).toBe(403); |
| 138 | 153 | expect(await titlesOf("carol")).toEqual([]); // her "Pin C" was renamed away: not shown |
test/boards-store.test.ts +21 −2
| @@ -285,8 +285,9 @@ describe("/api/v1/boards", () => { | ||
| 285 | 285 | const put = await api("/api/v1/boards/api-board", tok.admin, { method: "PUT", body: JSON.stringify(mine) }); |
| 286 | 286 | expect(put.status).toBe(200); |
| 287 | 287 | expect((await readBoard(app.reposRoot, "api-board"))?.panels.length).toBe(3); |
| 288 | const list = (await (await api("/api/v1/boards", tok.admin)).json()) as { boards: { slug: string }[] }; | |
| 289 | expect(list.boards.map((b) => b.slug)).toContain("api-board"); | |
| 288 | const list = (await (await api("/api/v1/boards", tok.admin)).json()) as { items: { slug: string }[]; next_cursor: string | null }; | |
| 289 | expect(list.next_cursor).toBeNull(); | |
| 290 | expect(list.items.map((b) => b.slug)).toContain("api-board"); | |
| 290 | 291 | const one = (await (await api("/api/v1/boards/api-board", tok.admin)).json()) as { title: string; refresh: string }; |
| 291 | 292 | expect([one.title, one.refresh]).toEqual(["Api board", "1m"]); |
| 292 | 293 | const again = await api("/api/v1/boards/api-board", tok.admin, { method: "PUT", body: JSON.stringify({ ...mine, title: "Renamed" }) }); |
| @@ -294,6 +295,24 @@ describe("/api/v1/boards", () => { | ||
| 294 | 295 | expect((await readBoard(app.reposRoot, "api-board"))?.title).toBe("Renamed"); |
| 295 | 296 | }); |
| 296 | 297 | |
| 298 | test("the list pages with limit and next_cursor to the end, and refuses a bad limit", async () => { | |
| 299 | const all = (await (await api("/api/v1/boards", tok.admin)).json()) as { items: { slug: string }[] }; | |
| 300 | const seen: string[] = []; | |
| 301 | let cursor: string | null = null; | |
| 302 | let pages = 0; | |
| 303 | do { | |
| 304 | const res = await api("/api/v1/boards?limit=1" + (cursor ? `&cursor=${cursor}` : ""), tok.admin); | |
| 305 | const page = (await res.json()) as { items: { slug: string }[]; next_cursor: string | null }; | |
| 306 | expect(page.items.length).toBe(1); | |
| 307 | seen.push(page.items[0]!.slug); | |
| 308 | cursor = page.next_cursor; | |
| 309 | pages++; | |
| 310 | } while (cursor && pages < 100); | |
| 311 | expect(seen).toEqual(all.items.map((b) => b.slug)); | |
| 312 | for (const q of ["limit=0", "limit=201", "limit=abc", "cursor=x"]) | |
| 313 | expect((await api("/api/v1/boards?" + q, tok.admin)).status).toBe(422); | |
| 314 | }); | |
| 315 | ||
| 297 | 316 | test("a board failing parseQuery is refused on write and drawn as an error panel on read", async () => { |
| 298 | 317 | const bad = { ...mine, panels: [panel("Broken", { source: "runs", aggregate: "median" })] }; |
| 299 | 318 | const res = await api("/api/v1/boards/broken", tok.admin, { method: "PUT", body: JSON.stringify(bad) }); |
test/list_page.test.ts added +17
| @@ -0,0 +1,17 @@ | ||
| 1 | import { expect, test } from "bun:test"; | |
| 2 | import { listWindow, pageOf } from "../src/core/list_page.ts"; | |
| 3 | ||
| 4 | test("a window defaults to 50 from the start and refuses what is not a page", () => { | |
| 5 | expect(listWindow(null, null)).toEqual({ ok: true, value: { limit: 50, offset: 0 } }); | |
| 6 | expect(listWindow("200", "7")).toEqual({ ok: true, value: { limit: 200, offset: 7 } }); | |
| 7 | expect(listWindow("0", null)).toEqual({ ok: false, error: "invalid_limit" }); | |
| 8 | expect(listWindow("201", null)).toEqual({ ok: false, error: "invalid_limit" }); | |
| 9 | expect(listWindow(null, "-1")).toEqual({ ok: false, error: "invalid_cursor" }); | |
| 10 | }); | |
| 11 | ||
| 12 | test("pages walk to a null cursor", () => { | |
| 13 | const all = [1, 2, 3]; | |
| 14 | expect(pageOf(all, { limit: 2, offset: 0 })).toEqual({ items: [1, 2], next_cursor: "2" }); | |
| 15 | expect(pageOf(all, { limit: 2, offset: 2 })).toEqual({ items: [3], next_cursor: null }); | |
| 16 | expect(pageOf(all, { limit: 2, offset: 9 })).toEqual({ items: [], next_cursor: null }); | |
| 17 | }); |
new above
offline
Low: an offset cursor can skip or repeat an item when the list changes between page reads. That is fine at this size. If boards ever grow large, key the cursor on the last slug instead.