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

The feed is readable as JSON Feed at /feed.json, and the home page links to it as an alternate #14496

opened this

Check · Review · Land · Live — No review yet. Next: reviewer, no review yet.

Ready to land

scout/forge:scout/14480-the-feed-is-readable-as-json-feed-at-fee → main 4 commits fork

This pull asks to reach lab--forge-trevato-apps.open-platform.sh. Its preview and check reach what main reaches; the new host opens when the pull lands.

Review

Sign in to review this change.
10 files changed +150 −7
src/core/reserved.ts +1
@@ -133,6 +133,7 @@ export const SYSTEM_NAMES: readonly string[] = [
133133 "releases.json",
134134 "changelog.atom",
135135 "explore.atom",
136 "feed.json",
136137 "sw.js",
137138 "offline",
138139 "tell",
src/feed/json_feed.ts added +44
@@ -0,0 +1,44 @@
1 /**
2 * The public feed as JSON Feed 1.1 (https://jsonfeed.org/version/1.1): the
3 * rows `/feed` shows a stranger (`publicShips`, never a second filter), newest
4 * first, at most 50. Plain data in, a plain object out.
5 */
6
7 import type { Database } from "bun:sqlite";
8 import { publicShips } from "./public_ships.ts";
9
10 export const JSON_FEED_ITEMS = 50;
11 export const JSON_FEED_VERSION = "https://jsonfeed.org/version/1.1";
12
13 export interface JsonFeedItem {
14 id: string;
15 url: string;
16 title: string;
17 date_published: string;
18 }
19
20 export interface JsonFeed {
21 version: string;
22 title: string;
23 home_page_url: string;
24 feed_url: string;
25 items: JsonFeedItem[];
26 }
27
28 /** RFC 3339: the outbox stores UTC without a zone. */
29 const rfc3339 = (iso: string): string => (/Z$|[+-]\d\d:\d\d$/.test(iso) ? iso : `${iso.replace(" ", "T")}Z`);
30
31 export function jsonFeed(db: Database, origin: string): JsonFeed {
32 return {
33 version: JSON_FEED_VERSION,
34 title: "forge: what shipped on public apps",
35 home_page_url: `${origin}/feed`,
36 feed_url: `${origin}/feed.json`,
37 items: publicShips(db, JSON_FEED_ITEMS).map((s) => ({
38 id: `urn:forge:ship:${s.href.slice(1)}`,
39 url: `${origin}${s.href}`,
40 title: s.title,
41 date_published: rfc3339(s.at),
42 })),
43 };
44 }
src/http/json_feed_route.ts added +16
@@ -0,0 +1,16 @@
1 /**
2 * `GET /feed.json`: the stranger's feed as JSON Feed, whoever asks (no private item, no cookie
3 * read).
4 */
5
6 import { jsonFeed } from "../feed/json_feed.ts";
7 import { notePhase, takeSessionTime, timePhase } from "../core/route_timing.ts";
8 import type { Ctx } from "./context.ts";
9
10 export function feedJson(ctx: Ctx): Response {
11 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
12 const feed = timePhase(ctx.request, "feed", () => jsonFeed(ctx.app.db, ctx.url.origin));
13 return new Response(JSON.stringify(feed), {
14 headers: { "content-type": "application/feed+json; charset=utf-8", "cache-control": "public, max-age=60" },
15 });
16 }
src/http/marks/feed.json.json added +4
@@ -0,0 +1,4 @@
1 {
2 "head": "/feed.json",
3 "mark": "open"
4 }
src/http/server.ts +2
@@ -199,6 +199,7 @@ import { appReleasesPage } from "../web/pages/app_releases.ts";
199199 import { chainPage, checkSubmit, modeSubmit, proposeParentSubmit, severSubmit, takeSubmit } from "../web/pages/chain.ts";
200200 import { followingSubmit } from "../web/pages/following.ts";
201201 import { reconnectSubmit } from "../web/pages/frozen.ts";
202 import { feedJson } from "./json_feed_route.ts";
202203 import { activityAtom, changelogAtom, exploreAtom } from "../web/feeds.ts";
203204 import { auditCsv, auditPage, auditProbeSubmit } from "../web/pages/audit.ts";
204205 import { apiPage, appApiPage } from "../web/pages/api.ts";
@@ -1194,6 +1195,7 @@ export function buildRouter(): Router<Handler> {
11941195 router.add("GET", "/live/table", liveTableFragment);
11951196 router.add("GET", "/live/figures", liveFiguresFragment);
11961197 router.add("GET", "/feed", feedPage);
1198 router.add("GET", "/feed.json", feedJson);
11971199 // The home's late regions, each drawn alone (#7660).
11981200 for (const name of HOME_REGIONS) router.add("GET", `/live/home/${name}`, (ctx) => liveHomeFragment(ctx, name));
11991201 // Whether a hostname is an app's verified domain — what Caddy's
src/view/doc_sections.ts +6 −6
@@ -22,24 +22,24 @@ export const SECTION_TITLES: Record<DocSection, string> = {
2222 type Line = readonly [DocSection, string, string?];
2323
2424 export const DOC_LINES: Record<string, Line> = {
25 "guide-what-a-forge-is.md": ["start", "Git hosting, preview environments and a crew in one program."],
25 "guide-what-a-forge-is.md": ["start", "Git hosting, previews and a crew in one program."],
2626 "guide-first-app.md": ["start", "A live app in five minutes with git and curl."],
2727 "guide-tell-the-crew.md": ["start", "Request a change in your own words."],
2828 "guide-ship-and-undo.md": ["start", "Merge a change to ship it, or take one back."],
2929 "guide-your-apps.md": ["start", "Each app's settings and where to find them."],
3030 "guide-hosting.md": ["start", "Plans, and making a forge for someone else."],
3131 "guide-own-ai.md": ["start", "Connect your own model account to the crew."],
32 "guide-agents.md": ["start", "Connect AI assistants over MCP, git or the terminal."],
33 "guide-backups-moving.md": ["start", "Nightly copies, restore drills, moving."],
32 "guide-agents.md": ["start", "Connect AI assistants by MCP, git or terminal."],
33 "guide-backups-moving.md": ["start", "Nightly copies, restore drills, moves."],
3434 "guide-settings.md": ["start", "Every forge setting, by topic."],
35 "guide-when-wrong.md": ["start", "What to check first when something breaks."],
35 "guide-when-wrong.md": ["start", "What to check first when it breaks."],
3636 "VISION.md": ["start", "Why the forge exists."],
3737
3838 "README.md": ["run", "What it is and how to start it.", "Overview"],
3939 "REFERENCE.md": ["run", "How it runs, and every option.", "Full reference"],
4040 "OPERATING.md": ["run", "Configuration, health, limits, releases."],
4141 "SNAPSHOT.md": ["run", "Nightly snapshots and restoring from one."],
42 "RESTORE.md": ["run", "A printable card: back on a fresh machine."],
42 "RESTORE.md": ["run", "A printable card: restore on a fresh machine."],
4343 "RECOVERY.md": ["run", "A printable runbook for when it is down."],
4444 "SECURITY-RUNBOOK.md": ["run", "Leaked tokens, bad releases, sign-in."],
4545 "SPAWN.md": ["run", "A forge that makes forges for other people."],
@@ -47,7 +47,7 @@ export const DOC_LINES: Record<string, Line> = {
4747 "CLUSTER.md": ["run", "Checks as Kubernetes Jobs."],
4848
4949 "APPS.md": ["reference", "Apps, previews and runs, and their rules."],
50 "CREW.md": ["reference", "The crew, the forge's AI agents: runs, review, spend."],
50 "CREW.md": ["reference", "The forge's AI agents: runs, review, spend."],
5151 "STUDIO.md": ["reference", "The web interface, page by page."],
5252 "TOUR.md": ["reference", "Every feature, by every door."],
5353 "STATUS.md": ["reference", "What works today."],
src/web/layout.ts +1
@@ -956,6 +956,7 @@ export function page(options: PageOptions, status = 200): Response {
956956 href="${f.href}"
957957 />`,
958958 )}
959 <link rel="alternate" type="application/feed+json" href="/feed.json" />
959960 ${(options.moreFeeds ?? []).map(
960961 (f) => html`<link rel="alternate" type="application/atom+xml" title="${f.title}" href="${f.href}" />`,
961962 )}
test/design-audit.test.ts +1 −1
@@ -17,7 +17,7 @@ const doc = readFileSync("docs/design/audit.md", "utf8");
1717
1818 /** Routes that answer a file, a fragment, a redirect hop or a callback. */
1919 const NOT_PAGES =
20 /^\/(assets\/|\.well-known\/|icons\/|og\/|live\/|__forge\/|go\/|new\/issue$|events$|system\/stream$|talk\/stream$|settings\/teams\/stream$|sw\.js$|offline$|robots\.txt$|favicon\.ico$|apple-touch-icon(-precomposed)?\.png$|sitemap\.xml$|manifest\.webmanifest$|opensearch\.xml$|llms(-full)?\.txt$|openapi\.json$|releases\.json$|changelog\.atom$|explore\.atom$|docs(\/[^/]*)?$|audit\.csv$|settings\/traffic\/scrapes\/export$|fleet\/graph\/live$|fleet\/graph\.csv$|settings\/origins\/callback$|broker\/origins\/start$|home\/archived\/|settings\/backups\/live$|api\/v1(\/|$))/;
20 /^\/(assets\/|\.well-known\/|icons\/|og\/|live\/|__forge\/|go\/|new\/issue$|events$|system\/stream$|talk\/stream$|settings\/teams\/stream$|sw\.js$|offline$|robots\.txt$|favicon\.ico$|apple-touch-icon(-precomposed)?\.png$|sitemap\.xml$|manifest\.webmanifest$|opensearch\.xml$|llms(-full)?\.txt$|openapi\.json$|releases\.json$|changelog\.atom$|explore\.atom$|feed\.json$|docs(\/[^/]*)?$|audit\.csv$|settings\/traffic\/scrapes\/export$|fleet\/graph\/live$|fleet\/graph\.csv$|settings\/origins\/callback$|broker\/origins\/start$|home\/archived\/|settings\/backups\/live$|api\/v1(\/|$))/;
2121
2222 const getRoutes = [
2323 ...server.matchAll(/router\.add\(\s*"GET",\s*"([^"]+)"/g),
test/feed-json.test.ts added +74
@@ -0,0 +1,74 @@
1 /**
2 * /feed.json: JSON Feed 1.1 of what a stranger sees; never a private item; advertised in the head.
3 */
4 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
5 import { mkdtemp, rm } from "node:fs/promises";
6 import { tmpdir } from "node:os";
7 import { join } from "node:path";
8 import { openIssue } from "../src/actions/issues.ts";
9 import { createRepo } from "../src/actions/repos.ts";
10 import { createApp, type App } from "../src/app.ts";
11 import { createUser } from "../src/core/users.ts";
12 import { publicShips } from "../src/feed/public_ships.ts";
13 import { serve, type Servers } from "../src/http/server.ts";
14
15 describe("feed.json", () => {
16 let dataDir: string;
17 let app: App;
18 let servers: Servers;
19 let origin: string;
20
21 beforeAll(async () => {
22 dataDir = await mkdtemp(join(tmpdir(), "forge-feed-json-"));
23 app = createApp({ dataDir, port: 0 });
24 servers = await serve(app);
25 origin = `http://127.0.0.1:${servers.port}`;
26 const u = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
27 if (!u.ok) throw new Error(u.error);
28 let minute = 0;
29 for (const [name, visibility, title] of [["open", "public", "Open <b>ship</b>"], ["later", "public", "Later ship"], ["hush", "private", "Secret ship"]] as const) {
30 const made = await createRepo(app, u.value, { name, visibility });
31 if (!made.ok) throw new Error(String(made.error));
32 const issue = openIssue(app, u.value, made.value, { title });
33 if (!issue.ok) throw new Error(String(issue.error));
34 const at = new Date(Date.UTC(2026, 0, 1, 0, minute++)).toISOString();
35 app.db.query("INSERT INTO pull (issue_id, base_branch, head_branch, base_oid, head_oid, merged_at) VALUES (?1, 'main', 'b', '', '', ?2)").run(issue.value.id, at);
36 }
37 }, 30_000);
38
39 afterAll(async () => {
40 servers.stop();
41 app.close();
42 await rm(dataDir, { recursive: true, force: true });
43 });
44
45 test("answers JSON Feed 1.1, newest first, each item with id, url, title, date_published", async () => {
46 const res = await fetch(`${origin}/feed.json`);
47 expect(res.status).toBe(200);
48 expect(res.headers.get("content-type")).toContain("application/feed+json");
49 expect(res.headers.get("x-content-type-options")).toBe("nosniff");
50 const feed = (await res.json()) as { version: string; items: Record<string, string>[] };
51 expect(feed.version).toBe("https://jsonfeed.org/version/1.1");
52 expect(feed.items.map((i) => i["title"])).toEqual(["Later ship", "Open <b>ship</b>"]);
53 for (const item of feed.items) {
54 for (const key of ["id", "url", "title", "date_published"]) expect(typeof item[key]).toBe("string");
55 expect(Number.isNaN(Date.parse(item["date_published"]!))).toBe(false);
56 }
57 expect(feed.items[0]!["url"]).toBe(`${origin}/alice/later/pulls/1`);
58 });
59
60 test("holds the same items the page reads, and no private one", async () => {
61 const body = await (await fetch(`${origin}/feed.json`)).text();
62 expect(body).not.toContain("Secret ship");
63 expect(body).not.toContain("hush");
64 const feed = JSON.parse(body) as { items: { url: string }[] };
65 expect(feed.items.map((i) => new URL(i.url).pathname)).toEqual(publicShips(app.db, 50).map((s) => s.href));
66 });
67
68 test("the page head advertises it as an alternate", async () => {
69 for (const path of ["/", "/feed"]) {
70 const text = await (await fetch(`${origin}${path}`)).text();
71 expect(text).toMatch(/<link\s+rel="alternate"\s+type="application\/feed\+json"[^>]*href="\/feed\.json"/);
72 }
73 });
74 });
test/forge-looks.test.ts +1
@@ -49,6 +49,7 @@ const NOT_A_PAGE: Record<string, string> = {
4949 "/releases.json": "JSON feed of /releases",
5050 "/changelog.atom": "Atom feed of /changelog",
5151 "/explore.atom": "Atom feed of /explore",
52 "/feed.json": "JSON Feed of /feed",
5253 "/sitemap.xml": "XML for crawlers",
5354 "/manifest.webmanifest": "the install manifest, JSON",
5455 "/opensearch.xml": "the browser search description, XML",

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs