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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/14662-after-boot-the-forge-loads-its-public-pa → main 6 commits fork 3 threads · 3 unresolved
6 files
changed +229
−4
src/http/server.ts +21 −1
| @@ -577,6 +577,7 @@ import { feedRoutes } from "./feed.ts"; | ||
| 577 | 577 | import type { Database } from "bun:sqlite"; |
| 578 | 578 | import { loadMcp, MCP_ROUTES } from "./mcp/load.ts"; |
| 579 | 579 | import { lazyRoutes } from "./lazy_routes.ts"; |
| 580 | import { scheduleWarmUp, WARM, type Family } from "./warmup.ts"; | |
| 580 | 581 | import { resourcePolicy } from "./corp.ts"; |
| 581 | 582 | import { agentsPage } from "../web/pages/agents.ts"; |
| 582 | 583 | import { openapiRoute } from "../contract/served.ts"; |
| @@ -2577,6 +2578,8 @@ async function handleHook(app: App, request: Request): Promise<Response> { | ||
| 2577 | 2578 | // ---- wiring ---- |
| 2578 | 2579 | |
| 2579 | 2580 | export interface Servers { |
| 2581 | /** Resolves once the post-boot warm-up of the public families has run (#14662). */ | |
| 2582 | readonly warmed: Promise<void>; | |
| 2580 | 2583 | readonly url: string; |
| 2581 | 2584 | /** Requests the listener still holds: 0 once every one has settled. */ |
| 2582 | 2585 | readonly inFlight: number; |
| @@ -2756,7 +2759,8 @@ export function forgeHttp(app: App): ForgeHttp { | ||
| 2756 | 2759 | }; |
| 2757 | 2760 | } |
| 2758 | 2761 | |
| 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> { | |
| 2760 | 2764 | keepReleaseAssets(app.config.dataDir); |
| 2761 | 2765 | const router = buildRouter(); |
| 2762 | 2766 | const apiRouter = buildApiRouter(); |
| @@ -3171,6 +3175,9 @@ export async function serve(app: App): Promise<Servers> { | ||
| 3171 | 3175 | |
| 3172 | 3176 | // Set by `stopAccepting`: the port is the release's now. |
| 3173 | 3177 | 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)); | |
| 3174 | 3181 | const web = Bun.serve({ |
| 3175 | 3182 | port: app.config.port ?? 3000, |
| 3176 | 3183 | // A release swaps in beside this process on the same port (#1663). |
| @@ -3197,6 +3204,7 @@ export async function serve(app: App): Promise<Servers> { | ||
| 3197 | 3204 | return inFlight.during(request, performance.now(), async () => { |
| 3198 | 3205 | try { |
| 3199 | 3206 | const response = await handle(request, bound); |
| 3207 | firstAnswered(); | |
| 3200 | 3208 | return handedOver && response !== undefined ? withHeader(response, "connection", "close") : response; |
| 3201 | 3209 | } finally { |
| 3202 | 3210 | // Whatever door answered: the gate holds no request past its answer (#12901). |
| @@ -3211,7 +3219,18 @@ export async function serve(app: App): Promise<Servers> { | ||
| 3211 | 3219 | |
| 3212 | 3220 | const internal = serveInternal(app); |
| 3213 | 3221 | 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), | |
| 3229 | firstAnswer, | |
| 3230 | ...(options.warm?.idleMs === undefined ? {} : { idleMs: options.warm.idleMs }), | |
| 3231 | }); | |
| 3214 | 3232 | return { |
| 3233 | warmed: warm.done, | |
| 3215 | 3234 | url: `http://localhost:${port}`, |
| 3216 | 3235 | port, |
| 3217 | 3236 | get inFlight() { |
| @@ -3229,6 +3248,7 @@ export async function serve(app: App): Promise<Servers> { | ||
| 3229 | 3248 | await Bun.sleep(INFLIGHT_POLL_MS); |
| 3230 | 3249 | }, |
| 3231 | 3250 | stop() { |
| 3251 | warm.cancel(); | |
| 3232 | 3252 | endOpen(); |
| 3233 | 3253 | stopShells(app); |
| 3234 | 3254 | 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; | ||
| 407 | 407 | const loneWriter = engineOn ? tuneForSplit(app.db) : () => {}; |
| 408 | 408 | await refreshCatalogQuietly(app); |
| 409 | 409 | if (readOnly) { |
| 410 | const servers = await serve(app); | |
| 410 | const servers = await serve(app, { warm: {} }); | |
| 411 | 411 | // Only the listener runs: no reconcile, perf watcher, timers, apps, crew, |
| 412 | 412 | // checks, releases, mirrors, snapshots or nightly jobs. Reads are answered until a signal. |
| 413 | 413 | 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); | ||
| 461 | 461 | await warmFlow(app); |
| 462 | 462 | await warmPlans(app); |
| 463 | 463 | await warmDisplays(app).catch(() => undefined); |
| 464 | const servers = await serve(app); | |
| 464 | const servers = await serve(app, { warm: {} }); | |
| 465 | 465 | markReady(); |
| 466 | 466 | // From here the flow's forge-wide readings are read once and shared for half a minute |
| 467 | 467 | // (`flow/kept.ts`). |
test/outbound-sweep.test.ts +1 −1
| @@ -27,7 +27,7 @@ const ALLOWED: Record<string, { count: number; why: string }> = { | ||
| 27 | 27 | "src/origins/discover.ts": { count: 1, why: "the exempt branch of discovery; every other probe is outboundFetch" }, |
| 28 | 28 | "src/git/hook-address.ts": { count: 1, why: "the forge's own internal listener: a unix socket or 127.0.0.1" }, |
| 29 | 29 | "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" }, | |
| 31 | 31 | "src/http/rp.ts": { count: 2, why: "the parent forge's issuer, from this forge's configuration" }, |
| 32 | 32 | "src/actions/upstream.ts": { count: 2, why: "the parent forge's API, from the upstream credential the operator set" }, |
| 33 | 33 | "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[] = [ | ||
| 70 | 70 | ...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", [ |
| 71 | 71 | ["src/spawn/cell.ts", "() => { if (isCell()) return;"], |
| 72 | 72 | ]), |
| 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 | ]), | |
| 73 | 76 | ...allow("setInterval", `SSE heartbeat, ${PER_CONNECTION}`, [["src/http/sse.ts", "() => write("]]), |
| 74 | 77 | ...allow("setInterval", `a talk stream's poll, ${PER_CONNECTION}`, [["src/web/pages/talk.ts", "tick"]]), |
| 75 | 78 | ...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 | }); |
new above
offline
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.