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

The boards list and the caller's board pins answer `{ items, next_cursor }` #5053

Parked opened this
Closed without merging

scout/forge:scout/5045-the-boards-list-and-the-caller-s-board-p → main 3 commits fork 1 thread · 1 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
7 files changed +94 −8
README.md +2 −2
@@ -1977,11 +1977,11 @@ work here.
19771977 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):
19781978 - the page (Pin to home / Unpin on `/boards/:slug`, Up / Down / Unpin on home);
19791979 - 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);
19811981 - the `board_pins` MCP tool (no `op` lists; `op` pin, unpin or move changes). `pins` is therefore not a board slug.
19821982 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.
19831983 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`
19851985 (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.
19861986 - **Issues** — labels, threaded comments, close/reopen, markdown.
19871987 - **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 }
outdated

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.

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 {
179179 updateProfile,
180180 } from "../actions/users.ts";
181181 import { EVENTS_LIMIT_MAX, eventsLimit, eventsPage, validEventsCursor } from "../core/events_page.ts";
182 import { listWindow, pageOf } from "../core/list_page.ts";
182183 import { audienceFor } from "../core/audience.ts";
183184 import {
184185 forkParentFor,
@@ -1553,14 +1554,25 @@ export function apiRoutes(router: Router<Handler>): void {
15531554 return apiError(e, e === "exists" || e === "branch_moved" ? 409 : 422, "that board could not be saved");
15541555 };
15551556
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
15561566 router.add("GET", "/api/v1/boards", async (ctx) => {
15571567 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
15581568 const denied = boardsAdmin(ctx);
15591569 if (denied) return denied;
1570 const win = boardsWindow(ctx);
1571 if (win instanceof Response) return win;
15601572 const listed = await timePhaseAsync(ctx.request, "boards", () => listAllBoards(ctx.app, ctx.auth.user));
15611573 return timePhase(ctx.request, "render", () =>
15621574 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))
15641576 : notFound());
15651577 });
15661578
@@ -1570,9 +1582,11 @@ export function apiRoutes(router: Router<Handler>): void {
15701582 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
15711583 const denied = boardsAdmin(ctx);
15721584 if (denied) return denied;
1585 const win = boardsWindow(ctx);
1586 if (win instanceof Response) return win;
15731587 const listed = await timePhaseAsync(ctx.request, "boards", () => listPinnedPanels(ctx.app, ctx.auth.user));
15741588 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());
15761590 });
15771591
15781592 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 () => {
5353 expect(got.status).toBe(200);
5454 expect(got.names).toEqual(["session", "boards", "render"]);
5555 }
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");
5757 });
5858
5959 test("a missing board still names its phases", async () => {
test/board-pins.test.ts +16 −1
@@ -124,7 +124,7 @@ describe("pinned panels", () => {
124124 method, headers: { authorization: `Bearer ${tok[who]}`, "content-type": "application/json" },
125125 ...(body === undefined ? {} : { body: JSON.stringify(body) }),
126126 });
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);
128128 expect(await titlesOf("alice")).toEqual(["Pin A", "Pin B", "Pin C2"]);
129129 expect((await api("alice", "POST", { op: "move", slug: "mine", title: "Pin C2", by: -1 })).status).toBe(200);
130130 expect(await titlesOf("alice")).toEqual(["Pin A", "Pin C2", "Pin B"]);
@@ -133,6 +133,21 @@ describe("pinned panels", () => {
133133 expect(await titlesOf("alice")).toEqual(["Pin C2", "Pin B", "Pin A"]);
134134 expect((await api("alice", "POST", { op: "pin", slug: "mine", title: "nope" })).status).toBe(404);
135135 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);
136151 expect((await api("bob", "GET")).status).toBe(403);
137152 expect((await api("bob", "POST", { op: "pin", slug: "mine", title: "Pin A" })).status).toBe(403);
138153 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", () => {
285285 const put = await api("/api/v1/boards/api-board", tok.admin, { method: "PUT", body: JSON.stringify(mine) });
286286 expect(put.status).toBe(200);
287287 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");
290291 const one = (await (await api("/api/v1/boards/api-board", tok.admin)).json()) as { title: string; refresh: string };
291292 expect([one.title, one.refresh]).toEqual(["Api board", "1m"]);
292293 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", () => {
294295 expect((await readBoard(app.reposRoot, "api-board"))?.title).toBe("Renamed");
295296 });
296297
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
297316 test("a board failing parseQuery is refused on write and drawn as an error panel on read", async () => {
298317 const bad = { ...mine, panels: [panel("Broken", { source: "runs", aggregate: "median" })] };
299318 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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs