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

After boot, the forge loads its public pages' route modules in the background, so the first agent or stranger pays no import #14681

Merged opened this

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

Merged

scout/forge:scout/14662-after-boot-the-forge-loads-its-public-pa → main 6 commits fork 3 threads · 3 unresolved

  • Merged. scout/14662-after-boot-the-forge-loads-its-public-pa was merged into main as d2f1be5.

Review

Sign in to review this change.
6 files changed +229 −4
src/http/server.ts +21 −1
@@ -577,6 +577,7 @@ import { feedRoutes } from "./feed.ts";
577577 import type { Database } from "bun:sqlite";
578578 import { loadMcp, MCP_ROUTES } from "./mcp/load.ts";
579579 import { lazyRoutes } from "./lazy_routes.ts";
580 import { scheduleWarmUp, WARM, type Family } from "./warmup.ts";
580581 import { resourcePolicy } from "./corp.ts";
581582 import { agentsPage } from "../web/pages/agents.ts";
582583 import { openapiRoute } from "../contract/served.ts";
@@ -2577,6 +2578,8 @@ async function handleHook(app: App, request: Request): Promise<Response> {
25772578 // ---- wiring ----
25782579
25792580 export interface Servers {
2581 /** Resolves once the post-boot warm-up of the public families has run (#14662). */
2582 readonly warmed: Promise<void>;
25802583 readonly url: string;
25812584 /** Requests the listener still holds: 0 once every one has settled. */
25822585 readonly inFlight: number;
@@ -2756,7 +2759,8 @@ export function forgeHttp(app: App): ForgeHttp {
27562759 };
27572760 }
27582761
2759 export async function serve(app: App): Promise<Servers> {
2762 /** `options.warm` is off unless given: only the booting process (main.ts) warms. */
2763 export async function serve(app: App, options: { warm?: { families?: readonly Family[]; idleMs?: number } } = {}): Promise<Servers> {
27602764 keepReleaseAssets(app.config.dataDir);
27612765 const router = buildRouter();
27622766 const apiRouter = buildApiRouter();
@@ -3171,6 +3175,9 @@ export async function serve(app: App): Promise<Servers> {
31713175
31723176 // Set by `stopAccepting`: the port is the release's now.
31733177 let handedOver = false;
3178 // The warm-up waits for the first answer (#14662): boot to first answer is unchanged.
3179 let firstAnswered!: () => void;
3180 const firstAnswer = new Promise<void>((resolve) => (firstAnswered = resolve));
31743181 const web = Bun.serve({
31753182 port: app.config.port ?? 3000,
31763183 // A release swaps in beside this process on the same port (#1663).
@@ -3197,6 +3204,7 @@ export async function serve(app: App): Promise<Servers> {
31973204 return inFlight.during(request, performance.now(), async () => {
31983205 try {
31993206 const response = await handle(request, bound);
3207 firstAnswered();
32003208 return handedOver && response !== undefined ? withHeader(response, "connection", "close") : response;
32013209 } finally {
32023210 // Whatever door answered: the gate holds no request past its answer (#12901).
@@ -3211,7 +3219,18 @@ export async function serve(app: App): Promise<Servers> {
32113219
32123220 const internal = serveInternal(app);
32133221 const port = web.port ?? 0;
3222 // The public families warm through the server itself, as a stranger asks (#14662).
3223 // Over loopback: the request's origin is made canonical from `app.config.url` (`publicUrl`),
3224 // so the copy it caches is the one a stranger's request reads.
3225 const warm = scheduleWarmUp({
3226 families: options.warm === undefined ? [] : (options.warm.families ?? WARM),
3227 get: (path) => fetch(`http://localhost:${port}${path}`, { redirect: "manual" }),
3228 warn: (message, fields) => app.log.warn(message, fields),
outdated

The fallback sleep is never cancelled and the stop() case is not checked (only handedOver). Clear it on stop and bail if stopped. Also confirm this actually warmed on the preview: first /llms.txt still took 441 ms.

3229 firstAnswer,
3230 ...(options.warm?.idleMs === undefined ? {} : { idleMs: options.warm.idleMs }),
3231 });
32143232 return {
3233 warmed: warm.done,
32153234 url: `http://localhost:${port}`,
32163235 port,
32173236 get inFlight() {
@@ -3229,6 +3248,7 @@ export async function serve(app: App): Promise<Servers> {
32293248 await Bun.sleep(INFLIGHT_POLL_MS);
32303249 },
32313250 stop() {
3251 warm.cancel();
32323252 endOpen();
32333253 stopShells(app);
32343254 prerender();
src/http/warmup.ts added +111
@@ -0,0 +1,111 @@
1 /**
2 * After boot, once the first request has been answered and the listener has
3 * sat idle a moment, warm the public, signed-out paths (#14662), one family
4 * at a time, so the first agent or stranger pays neither the import nor the
5 * first render. Everything not named here stays lazy (#12521), so the memory
6 * it saved stays saved.
7 *
8 * A family is warmed by asking the running server for its page as a stranger
9 * would: the answer lands in the same per-origin caches a real request reads
10 * (the request's origin is the canonical one, so the warmed copy is the one
11 * served), and the render and the first JIT are paid here.
12 *
13 * The one list is `WARM`. /changelog, /search, /pricing and /templates are
14 * static imports already loaded at boot and have no family to load.
15 */
16
17 import { loadMcp } from "./mcp/load.ts";
18
19 /** Ask the running server for a public path, signed out. */
20 export type Get = (path: string) => Promise<Response>;
21
22 export interface Family {
23 readonly name: string;
24 /** The public paths that wait on it, for whoever reads the list. */
25 readonly paths: readonly string[];
26 readonly load: (get: Get) => Promise<unknown> | unknown;
27 }
28
outdated

openapiText is cached per origin; the request's origin may differ from app.config.url on the preview, so the first /openapi.json (29.8 ms vs 1.1 warm) misses the warmed copy. Warm the origin(s) requests really use, or key the cache so this one serves.

29 /** The public families, and only they. */
30 export const WARM: readonly Family[] = [
31 {
32 name: "MCP",
33 paths: ["/llms.txt", "/llms-full.txt", "/agents", "/.well-known/mcp"],
34 load: async (get) => {
35 await loadMcp();
36 await (await get("/llms.txt")).arrayBuffer();
37 },
38 },
39 {
40 name: "openapi",
41 paths: ["/openapi.json", "/contract/openapi.json"],
42 // Both encodings a client asks for are built once per document; this reads the plain one.
43 load: async (get) => void (await (await get("/openapi.json")).arrayBuffer()),
44 },
45 ];
46
47 /** How long the listener is left alone after its first answer. */
48 export const WARM_IDLE_MS = 500;
49 /** A forge nobody has asked yet warms after this long. */
50 export const WARM_FALLBACK_MS = 10_000;
51
52 export type Warn = (message: string, fields: { family: string; error: string }) => void;
53
54 /**
55 * Load each family in turn, a failure logged once with its name and left for
56 * the first request to retry (a load that fails is not kept). Stops early once `stopped()`.
57 */
58 export async function warmUp(families: readonly Family[], get: Get, warn: Warn, stopped: () => boolean = () => false): Promise<void> {
59 for (const family of families) {
60 if (stopped()) return;
61 try {
62 await family.load(get);
63 } catch (error) {
64 warn("warm-up: a family did not load; its first request will try again", {
65 family: family.name,
66 error: error instanceof Error ? error.message : String(error),
67 });
68 }
69 }
70 }
71
72 /**
73 * Warm once `firstAnswer` settles (or the fallback passes) and the listener
74 * has been idle `idleMs`. `cancel` clears the timers and ends it, so a
75 * stopped server leaves nothing behind.
76 */
77 export function scheduleWarmUp(options: {
78 families: readonly Family[];
79 get: Get;
80 warn: Warn;
81 firstAnswer: Promise<void>;
82 idleMs?: number;
83 fallbackMs?: number;
84 }): { done: Promise<void>; cancel(): void } {
85 let cancelled = false;
86 const timers = new Set<ReturnType<typeof setTimeout>>();
87 let release: () => void = () => {};
88 const wait = (ms: number) =>
89 new Promise<void>((resolve) => {
90 const timer = setTimeout(() => (timers.delete(timer), resolve()), ms);
91 timers.add(timer);
92 release = resolve;
93 });
94 const done = (async () => {
95 await Promise.race([options.firstAnswer, wait(options.fallbackMs ?? WARM_FALLBACK_MS)]);
96 for (const timer of timers) clearTimeout(timer);
97 timers.clear();
98 if (cancelled) return;
99 await wait(options.idleMs ?? WARM_IDLE_MS);
100 await warmUp(options.families, options.get, options.warn, () => cancelled);
101 })();
102 return {
103 done,
104 cancel() {
105 cancelled = true;
106 for (const timer of timers) clearTimeout(timer);
107 timers.clear();
108 release();
109 },
110 };
111 }
src/main.ts +2 −2
@@ -407,7 +407,7 @@ const tail = engineOn ? tailEvents(app.db, app.bus) : undefined;
407407 const loneWriter = engineOn ? tuneForSplit(app.db) : () => {};
408408 await refreshCatalogQuietly(app);
409409 if (readOnly) {
410 const servers = await serve(app);
410 const servers = await serve(app, { warm: {} });
411411 // Only the listener runs: no reconcile, perf watcher, timers, apps, crew,
412412 // checks, releases, mirrors, snapshots or nightly jobs. Reads are answered until a signal.
413413 app.log.info("forge is up, read-only standby", { url: servers.url, data: app.config.dataDir });
@@ -461,7 +461,7 @@ if (appDomain?.ok === true) holdAppHosts(app, appDomain.domain);
461461 await warmFlow(app);
462462 await warmPlans(app);
463463 await warmDisplays(app).catch(() => undefined);
464 const servers = await serve(app);
464 const servers = await serve(app, { warm: {} });
465465 markReady();
466466 // From here the flow's forge-wide readings are read once and shared for half a minute
467467 // (`flow/kept.ts`).
test/outbound-sweep.test.ts +1 −1
@@ -27,7 +27,7 @@ const ALLOWED: Record<string, { count: number; why: string }> = {
2727 "src/origins/discover.ts": { count: 1, why: "the exempt branch of discovery; every other probe is outboundFetch" },
2828 "src/git/hook-address.ts": { count: 1, why: "the forge's own internal listener: a unix socket or 127.0.0.1" },
2929 "src/cli/api.ts": { count: 1, why: "the workbench CLI on a person's own machine, talking to the forge they configured" },
30 "src/http/server.ts": { count: 1, why: "the forge's own unix socket" },
30 "src/http/server.ts": { count: 2, why: "the forge's own unix socket, and its own loopback port for the boot warm-up" },
3131 "src/http/rp.ts": { count: 2, why: "the parent forge's issuer, from this forge's configuration" },
3232 "src/actions/upstream.ts": { count: 2, why: "the parent forge's API, from the upstream credential the operator set" },
3333 "src/actions/cloud.ts": { count: 1, why: "the cloud provider API an admin connected; providers are named in code" },
test/timers-named.test.ts +3
@@ -70,6 +70,9 @@ const ALLOWED: readonly Allowed[] = [
7070 ...allow("setInterval", "an adopted cell's identity check: one kill(0) and a pid-file read a second per cell, ended when the cell is gone", [
7171 ["src/spawn/cell.ts", "() => { if (isCell()) return;"],
7272 ]),
73 ...allow("setTimeout", "the boot warm-up's idle wait: one timer, cleared by cancel when the server stops", [
74 ["src/http/warmup.ts", "() => (timers.delete(timer)"],
75 ]),
7376 ...allow("setInterval", `SSE heartbeat, ${PER_CONNECTION}`, [["src/http/sse.ts", "() => write("]]),
7477 ...allow("setInterval", `a talk stream's poll, ${PER_CONNECTION}`, [["src/web/pages/talk.ts", "tick"]]),
7578 ...allow("setInterval", `a shell session's idle check, ${PER_CONNECTION}`, [["src/machines/shell.ts", "() => { if (idle(session"]]),
test/warmup.test.ts added +91
@@ -0,0 +1,91 @@
1 /** After boot the public families warm in the background, after the first answer (#14662). */
2 import { afterAll, beforeAll, 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 } from "../src/app.ts";
7 import type { Ctx, Handler } from "../src/http/context.ts";
8 import { lazyRoutes } from "../src/http/lazy_routes.ts";
9 import { Router } from "../src/http/router.ts";
10 import { serve, type Servers } from "../src/http/server.ts";
11 import { WARM, warmUp, type Family } from "../src/http/warmup.ts";
12 import { quietLogs } from "./helpers/globals.ts";
13
14 quietLogs();
15
16 const IDLE = 300;
17 let dir: string;
18 let servers: Servers;
19 const loadedAt: Record<string, number> = {};
20 const paths: string[] = [];
21 let beforeFirst = 0;
22
23 beforeAll(async () => {
24 dir = await mkdtemp(join(tmpdir(), "forge-warmup-"));
25 // The real families, each noted when it begins, and the page it warms asked for as it is.
26 const families: Family[] = WARM.map((family) => ({
27 ...family,
28 load: (get) => {
29 loadedAt[family.name] = performance.now();
30 return family.load(async (path) => {
31 const res = await get(path);
32 paths.push(`${path} ${res.status}`);
33 return res;
34 });
35 },
36 }));
37 servers = await serve(createApp({ dataDir: dir, port: 0 }), { warm: { families, idleMs: IDLE } });
38 });
outdated

This does not prove the warm-up is after the first answer (one microtask is not a wait). Assert ordering by timestamps, and add a test that a failed load is retried on the first request (box 3).

39 afterAll(async () => {
40 servers.stop();
41 await rm(dir, { recursive: true, force: true });
42 });
43
44 test("the warm list names the public families: llms.txt and the cards, and openapi.json", () => {
45 const listed = WARM.flatMap((f) => f.paths);
46 for (const p of ["/llms.txt", "/openapi.json"]) expect(listed).toContain(p);
47 });
48
49 test("nothing warms before the first answer, and every family is loaded, in order, once `warmed` settles", async () => {
50 expect(loadedAt).toEqual({});
51 beforeFirst = performance.now();
52 expect((await fetch(`${servers.url}/`)).status).toBeLessThan(500);
53 await servers.warmed;
54 expect(Object.keys(loadedAt)).toEqual(WARM.map((f) => f.name));
55 // Each began no sooner than the idle period after the first answer was asked for.
56 for (const at of Object.values(loadedAt)) expect(at - beforeFirst).toBeGreaterThanOrEqual(IDLE - 5);
57 // The warm pages are the ones strangers read.
58 expect(paths).toEqual(["/llms.txt 200", "/openapi.json 200"]);
59 });
60
61 test("a family that fails is logged once with its name, and the first request loads it", async () => {
62 const warned: { message: string; family: string }[] = [];
63 let tries = 0;
64 const load = async () => {
65 if (++tries === 1) throw new Error("boom");
66 };
67 const families: Family[] = [
68 { name: "flaky", paths: ["/x"], load },
69 { name: "good", paths: [], load: () => undefined },
70 ];
71 await warmUp(families, async () => new Response(), (message, f) => warned.push({ message, family: f.family }));
72 expect(warned.map((w) => w.family)).toEqual(["flaky"]);
73 const router = new Router<Handler>();
74 lazyRoutes(router, "flaky", [["GET", "/x"]], async () => {
75 await load();
76 return (r) => void r.add("GET", "/x", () => new Response("loaded"));
77 });
78 const res = await router.match("GET", "/x")!.handler({} as Ctx);
79 expect(await res.text()).toBe("loaded");
80 expect(tries).toBe(2);
81 });
82
83 test("a stopped server never warms, and leaves no timer to do it", async () => {
84 let ran = false;
85 const quiet = await serve(createApp({ dataDir: await mkdtemp(join(tmpdir(), "forge-warmup-stop-")), port: 0 }), {
86 warm: { families: [{ name: "never", paths: [], load: () => void (ran = true) }], idleMs: 0 },
87 });
88 quiet.stop();
89 await quiet.warmed;
90 expect(ran).toBe(false);
91 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs