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

Every page's `rel=alternate` link to /api/v1/here answers, not 404 #14426

Merged opened this

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

Merged

scout/forge:scout/14421-every-page-s-rel-alternate-link-to-api-v → main 8 commits fork 6 threads · 6 unresolved

  • Merged. scout/14421-every-page-s-rel-alternate-link-to-api-v was merged into main as e8a2a93.

Review

Sign in to review this change.
8 files changed +138 −21
src/actions/here.ts +23
@@ -68,6 +68,8 @@ export interface Action {
6868 export interface Manifest {
6969 readonly here:
7070 | { readonly kind: "forge" | "explore" | "search" | KeptPage }
71 /** A registered page of the forge's own: what it is, never its content. */
72 | { readonly kind: "page"; readonly path: string }
7173 | { readonly kind: "person"; readonly username: string }
7274 | { readonly kind: "org"; readonly org: string }
7375 | {
@@ -308,6 +310,27 @@ function pageManifest(
308310 });
309311 }
310312
313 /**
314 * The manifest for a page the router registers (`pageRoutePath` in the
315 * server): what it is, who you are, what you can do. Never the page's content.
316 */
317 export function registeredPageManifest(
318 app: App,
319 viewer: User | undefined,
320 scope: TokenScope | undefined,
321 origin: string,
322 path: string,
323 ): Manifest {
324 const pathname = path.split(/[?#]/, 1)[0]!;
325 return {
326 here: { kind: "page", path: pathname },
327 you: youFor(viewer, scope, undefined, app),
328 can: forgeActions(app, viewer, scope),
329 mcp: mcpPointers(origin),
330 docs: `${origin}/llms.txt`,
331 };
332 }
333
311334 function youFor(
312335 viewer: User | undefined,
313336 scope: TokenScope | undefined,
src/http/api.ts +14 −10
@@ -439,7 +439,8 @@ import { featureRoutes } from "./api/features.ts";
439439 import { upstreamRoutes } from "./api/upstream.ts";
440440 import type { Router } from "./router.ts";
441441 import { clientAddress } from "./peer.ts";
442 import { INVALID_TOKEN_HINT, INVALID_TOKEN_WORDS, manifestFor } from "../actions/here.ts";
442 import { INVALID_TOKEN_HINT, INVALID_TOKEN_WORDS, manifestFor, registeredPageManifest } from "../actions/here.ts";
443 import { ok } from "../kernel/result.ts";
443444 import { egressRowsFor, egressTotalsFor } from "../spawn/process_counters.ts";
444445 import { egressMetrics } from "../apps/egress_metrics.ts";
445446 import { forgeMetrics } from "../metrics/forge.ts";
@@ -1232,7 +1233,11 @@ export function boardsAdmin(ctx: Ctx): Response | undefined {
12321233 : forbidden();
12331234 }
12341235
1235 export function apiRoutes(router: Router<Handler>): void {
1236 /**
outdated

Module-level mutable hook with a silent fallback to false. Make it an explicit dependency instead.

1237 * `isPage` says whether a path is a public page the studio's router registers; it is given
1238 * rather than imported, so the API reaches no page layer.
1239 */
1240 export function apiRoutes(router: Router<Handler>, isPage: (path: string) => boolean): void {
12361241 passportRoutes(router);
12371242 // ── accounts ─────────────────────────────────────────────────────────
12381243
@@ -4176,15 +4181,14 @@ export function apiRoutes(router: Router<Handler>): void {
41764181 // A credential that matches nothing is not a signed-out visitor.
41774182 if (ctx.auth.refused === true) return apiError("invalid_token", 401, INVALID_TOKEN_WORDS, INVALID_TOKEN_HINT);
41784183 const path = ctx.url.searchParams.get("path") ?? "/";
4179 const found = timePhase(ctx.request, "here", () =>
4180 manifestFor(
4181 ctx.app,
4182 ctx.auth.user,
4183 ctx.auth.via === "token" ? ctx.auth.scope : undefined,
4184 ctx.url.origin,
4185 path.startsWith("/") ? path : `/${path}`,
4186 ),
4184 const at0 = path.startsWith("/") ? path : `/${path}`;
4185 const scope = ctx.auth.via === "token" ? ctx.auth.scope : undefined;
4186 let found = timePhase(ctx.request, "here", () =>
4187 manifestFor(ctx.app, ctx.auth.user, scope, ctx.url.origin, at0),
41874188 );
4189 // A page the router registers answers, whatever the account lookup said.
4190 if (!found.ok && isPage(at0.split(/[?#]/, 1)[0]!))
4191 found = ok(registeredPageManifest(ctx.app, ctx.auth.user, scope, ctx.url.origin, at0));
41884192 if (!found.ok) return notFound();
41894193 // A run token sees repository pages of its own repositories, and nothing
41904194 // else: not the forge, not another repository, not even that one exists.
src/http/server.ts +11 −1
@@ -671,6 +671,7 @@ import {
671671 type StoredResponse,
672672 } from "../core/idempotency.ts";
673673 import { sseStream, viewerStream } from "./sse.ts";
674 import { isAdminRoute } from "./route_marks.ts";
674675 import { Router } from "./router.ts";
675676 import { getUserById } from "../core/users.ts";
676677 import { appsRuntime } from "../apps/runtime.ts";
@@ -1890,7 +1891,7 @@ export function buildRouter(): Router<Handler> {
18901891 */
18911892 export function buildApiRouter(): Router<Handler> {
18921893 const router = new Router<Handler>();
1893 apiRoutes(router);
1894 apiRoutes(router, isPublicPage);
18941895 feedRoutes(router);
18951896 checksRecheckRoutes(router);
18961897 // What went live, as /changelog shows it; the page's own module answers.
@@ -1908,6 +1909,15 @@ function routeOf(path: string): string | undefined {
19081909 return (pages ??= buildRouter()).match("GET", path)?.pattern;
19091910 }
outdated

NOT_PAGES is another hand-kept list of heads, plus a file-extension regex on the pattern. A new non-page route will pass as a page until someone remembers to add it here. Mark the routes instead.

19101911
1912 /**
1913 * Whether `path` is a registered public GET page of the studio's router, with no
1914 * account in its pattern (those answer by their owner): read from the router, not a list.
1915 */
1916 export function isPublicPage(path: string): boolean {
1917 const hit = (pages ??= buildRouter()).match("GET", path);
1918 return hit !== undefined && !hit.pattern.startsWith("/:owner") && !isAdminRoute(hit.pattern);
1919 }
1920
19111921 let known: string[] | undefined;
19121922 /** Every pattern the studio's and the API's routers know, read once on first use. */
19131923 export function knownPatterns(): string[] {
src/web/layout.ts +2 −1
@@ -875,7 +875,8 @@ export function page(options: PageOptions, status = 200): Response {
875875 : undefined;
876876 const flash: Flash | undefined =
877877 options.flash ?? cookieFlash ?? (notice === undefined ? undefined : { tone: "attn", message: notice });
878 const links = pageLinks(ctx);
878 // A 404 names nothing, so it advertises no JSON twin of itself.
879 const links = pageLinks(ctx).filter((l) => !(status === 404 && l.rel === "alternate"));

Box 2: on the preview, a 404 still returns rel="alternate" in the Link header. This filter does not reach the header. Fix it where the header is emitted.

879880
880881 // The body's markup. Every `icon()` left a `<use>` behind; they are aimed
881882 // at the one hashed sprite file below, so no page carries a drawing.
test/api-list-shape.test.ts +5 −4
@@ -12,6 +12,8 @@ import { createApp, type App } from "../src/app.ts";
1212 import { createRepo } from "../src/actions/repos.ts";
1313 import { createIssue } from "../src/core/issues.ts";
1414 import { apiRoutes } from "../src/http/api.ts";
15 import type { Handler } from "../src/http/context.ts";
16 import { Router } from "../src/http/router.ts";
1517 import { serve, type Servers } from "../src/http/server.ts";
1618 import { seedAdmin } from "./helpers/admin.ts";
1719
@@ -30,10 +32,9 @@ const FILL: Record<string, string> = {
3032 };
3133
3234 const getPatterns = (): string[] => {
33 const seen: string[] = [];
34 const spy = { add(method: string, pattern: string) { if (method === "GET") seen.push(pattern); return spy; } };
35 apiRoutes(spy as never);
36 return [...new Set(seen)];
35 const router = new Router<Handler>();
36 apiRoutes(router, () => false);
37 return [...new Set(router.routes().filter((r) => r.method === "GET").map((r) => r.pattern))];
3738 };
3839
3940 let dataDir = "";
test/attention.test.ts +6 −1
@@ -53,6 +53,11 @@ const fixedLive: Live = {
5353 const fixedCaps = (html: string): string =>
5454 html.replace(/<p class="small" id="(cell-caps|cell-pids)"[^>]*>[\s\S]*?<\/p>/g, '<p class="small" id="$1">Each cell is capped.</p>');
5555
56 // The queue's "oldest has waited Ns" is the clock's, not the page's: a loaded machine reads 1s
57 // where a quiet one reads 0s, and the count of blocks moves with it.
58 const fixedWait = (html: string): string =>
59 html.replace(/has waited \d+s/g, "has waited 0s").replace(/(data-label="Oldest" >)\d+s/g, "$10s");
60
5661 beforeAll(async () => {
5762 root = mkdtempSync(join(tmpdir(), "forge-attention-"));
5863 app = createApp({ dataDir: root, port: 0, forgeRepo: "alice/forge" });
@@ -98,7 +103,7 @@ beforeAll(async () => {
98103 const res = await fetch(`${servers.url}${path}`, { headers: { cookie }, redirect: "follow" });
99104 if (res.status !== 200) throw new Error(`${name} ${path} answered ${res.status}`);
100105 const text = await res.text();
101 pages[name] = name === "system" ? fixedCaps(text) : text;
106 pages[name] = name === "system" ? fixedCaps(text) : name === "boards" ? fixedWait(text) : text;
102107 }
103108 });
104109 afterAll(() => {
test/here-pages.test.ts added +72
@@ -0,0 +1,72 @@
1 /** Every page the forge advertises an alternate for answers it (#14421). */
2 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
3 import { mkdtemp, rm } from "node:fs/promises";
4 import { tmpdir } from "node:os";
5 import { join } from "node:path";
6 import { createApp, type App } from "../src/app.ts";
7 import { buildRouter, isPublicPage, serve, type Servers } from "../src/http/server.ts";
8 import { quietLogs } from "./helpers/globals.ts";
9
10 quietLogs();
11
12 let dir: string, app: App, servers: Servers;
13 beforeAll(async () => {
14 dir = await mkdtemp(join(tmpdir(), "here-pages-"));
15 app = createApp({ dataDir: dir, port: 0 });
16 servers = await serve(app);
17 });
18 afterAll(async () => {
19 await servers.stop();
20 await rm(dir, { recursive: true, force: true });
21 });
22 const get = (p: string) => fetch(`${servers.url}${p}`, { redirect: "manual" });
23 const here = (p: string) => get(`/api/v1/here?path=${encodeURIComponent(p)}`);
24
25 /** The alternate a response advertises, in its Link header. */
26 const alternateOf = (res: Response) => /<([^>]+)>; rel="alternate"/.exec(res.headers.get("link") ?? "")?.[1];
27
28 describe("the alternate link", () => {
29 test("every literal public page advertises an alternate that answers 200 as exactly its own kind", async () => {
outdated

Box 3: this checks here for each path, not the alternate each page advertises. Fetch each page and follow its advertised alternate.

30 const paths = buildRouter()
31 .routes()
32 .filter((r) => r.method === "GET" && !r.pattern.includes(":") && !r.pattern.includes("*") && isPublicPage(r.pattern))
33 .map((r) => r.pattern);
34 expect(paths.length).toBeGreaterThan(10);
35 let followed = 0;
36 const kinds: Record<string, string> = {};
outdated

["page","forge"] passes whichever way it goes, so it would not catch a regression. Assert the exact kind.

37 for (const p of paths) {
38 const res = await get(p);
39 await res.body?.cancel();
40 const link = alternateOf(res);
41 if (link === undefined) continue; // a file or a redirect, not a page that advertises
42 followed++;
43 const twin = await get(link);
44 expect(`${p} ${twin.status}`).toBe(`${p} 200`);
45 const body = (await twin.json()) as { here: { kind: string; path: string } };
46 kinds[p] = body.here.kind;
47 if (body.here.kind === "page") expect(body.here.path).toBe(p);
48 }
49 expect(followed).toBeGreaterThan(5);
50 // Exactly the kind the forge already named for a path it knew; a page it did not is `page`.
51 expect(kinds["/privacy"]).toBe("forge");
52 expect(kinds["/signin"]).toBe("signin");
53 expect(kinds["/docs"]).toBe("docs");
54 expect(new Set(Object.values(kinds))).toEqual(new Set(["forge", "agents", "templates", "explore", "signin", "signup", "search", "docs", "changelog"]));
55 });
56
57 test("a registered page the forge named nothing for is exactly kind page, with its path", async () => {
58 const body = (await (await here("/-/confirm")).json()) as { here: unknown };
59 expect(body.here).toEqual({ kind: "page", path: "/-/confirm" });
60 });
61
62 test("a path the router does not register is nothing", async () => {
63 expect((await here("/nope-nothing-here")).status).toBe(404);
64 });
65
66 test("the 404 page advertises no alternate, in its markup or its Link header", async () => {
67 const res = await get("/nope-nothing-here");
68 expect(res.status).toBe(404);
69 expect(res.headers.get("link") ?? "").not.toContain("alternate");
70 expect(await res.text()).not.toContain('rel="alternate"');
71 });
72 });
test/route-timing-coverage.test.ts +5 −4
@@ -14,6 +14,8 @@ import { createApp, type App } from "../src/app.ts";
1414 import { createRepo } from "../src/actions/repos.ts";
1515 import { createIssue } from "../src/core/issues.ts";
1616 import { apiRoutes } from "../src/http/api.ts";
17 import type { Handler } from "../src/http/context.ts";
18 import { Router } from "../src/http/router.ts";
1719 import { serve, type Servers } from "../src/http/server.ts";
1820 import { seedAdmin } from "./helpers/admin.ts";
1921
@@ -43,10 +45,9 @@ const FILL: Record<string, string> = {
4345 };
4446
4547 const getPatterns = (): string[] => {
46 const seen: string[] = [];
47 const spy = { add(method: string, pattern: string) { if (method === "GET") seen.push(pattern); return spy; } };
48 apiRoutes(spy as never);
49 return [...new Set(seen)];
48 const router = new Router<Handler>();
49 apiRoutes(router, () => false);
50 return [...new Set(router.routes().filter((r) => r.method === "GET").map((r) => r.pattern))];
5051 };
5152
5253 let dataDir = "";

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs