Public: anyone can read this; the crew can change it.
The serve/work split switches on only when the machine has the cores #12357
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/12351-the-serve-work-split-switches-on-only-wh → main 7 commits fork 1 thread · 1 unresolved
8 files
changed +151
−17
docs/features/engine-shape.md added +12
| @@ -0,0 +1,12 @@ | ||
| 1 | # Engine shape | |
| 2 | ||
| 3 | The forge runs on one thread unless asked. `FORGE_ENGINE=worker` moves the | |
| 4 | engine's duties onto a Worker of the same process; `FORGE_ENGINE=inline` says | |
| 5 | the default out loud. | |
| 6 | ||
| 7 | A hosted child, a read-only standby and a test boot stay on one thread whatever | |
| 8 | the variable says. | |
| 9 | ||
| 10 | To see which shape runs and why, open `/system` and read "Engine shape", or open | |
| 11 | the System command in the terminal. Both read the same choice, made once at boot | |
| 12 | (`engine/mode.ts`). |
src/app.ts +2
| @@ -36,6 +36,8 @@ import { closeReadersUnder } from "./git/read.ts"; | ||
| 36 | 36 | import { dropAllPins } from "./git/pins_kept.ts"; |
| 37 | 37 | |
| 38 | 38 | export interface ForgeConfig { |
| 39 | /** The engine shape this boot chose and why (`engine/mode.ts`), for `/system`; none in a test. */ | |
| 40 | engine?: { mode: string; why: string }; | |
| 39 | 41 | /** Everything lives here: index db, bare repos, the internal socket. */ |
| 40 | 42 | dataDir: string; |
| 41 | 43 | /** |
src/engine/mode.ts +18 −6
| @@ -11,12 +11,24 @@ | ||
| 11 | 11 | |
| 12 | 12 | export type EngineMode = "inline" | "worker"; |
| 13 | 13 | |
| 14 | export function engineMode( | |
| 14 | /** The shape that runs and the reason, in plain words, for `/system` and the terminal. */ | |
| 15 | export interface EngineChoice { | |
| 16 | mode: EngineMode; | |
| 17 | why: string; | |
| 18 | } | |
| 19 | ||
| 20 | export function engineChoice( | |
| 15 | 21 | env: Record<string, string | undefined>, |
| 16 | 22 | where: { hosted: boolean; readOnly: boolean; optIn?: boolean }, |
| 17 | ): EngineMode { | |
| 18 | if (env["FORGE_ENGINE"] !== "worker") return "inline"; | |
| 19 | if (where.hosted || where.readOnly) return "inline"; | |
| 20 | if (env["NODE_ENV"] === "test" && where.optIn !== true) return "inline"; | |
| 21 | return "worker"; | |
| 23 | ): EngineChoice { | |
| 24 | if (where.hosted) return { mode: "inline", why: "this forge is a hosted child" }; | |
| 25 | if (where.readOnly) return { mode: "inline", why: "this forge is a read-only standby" }; | |
| 26 | if (env["NODE_ENV"] === "test" && where.optIn !== true) return { mode: "inline", why: "this is a test boot" }; | |
| 27 | if (env["FORGE_ENGINE"] === "worker") return { mode: "worker", why: "FORGE_ENGINE=worker is set" }; | |
| 28 | if (env["FORGE_ENGINE"] === "inline") return { mode: "inline", why: "FORGE_ENGINE=inline is set" }; | |
| 29 | return { mode: "inline", why: "FORGE_ENGINE is not set" }; | |
| 22 | 30 | } |
| 31 | ||
| 32 | /** The shape in words: what runs on which thread. */ | |
| 33 | export const shapeWords = (c: EngineChoice): string => | |
| 34 | c.mode === "worker" ? "the engine's duties run on a Worker, apart from serving" : "one thread serves and works"; |
src/main.ts +5 −2
| @@ -87,7 +87,7 @@ import { graphInstagram } from "./crew/instagram.ts"; | ||
| 87 | 87 | import { peopleOnCrews } from "./core/agents.ts"; |
| 88 | 88 | import { startNotifier } from "./crew/notify.ts"; |
| 89 | 89 | import { tailEvents } from "./core/event_tail.ts"; |
| 90 | import { engineMode } from "./engine/mode.ts"; | |
| 90 | import { engineChoice } from "./engine/mode.ts"; | |
| 91 | 91 | import { startEngine } from "./engine/host.ts"; |
| 92 | 92 | import { startDuties } from "./engine/duties.ts"; |
| 93 | 93 | import { startRetention } from "./system/retention.ts"; |
| @@ -271,8 +271,11 @@ watchStalls(loopLog, undefined, undefined, undefined, (late, at) => { | ||
| 271 | 271 | |
| 272 | 272 | const previewKey = previewIdentityKey(process.env); |
| 273 | 273 | |
| 274 | const engineShape = engineChoice(process.env, { hosted, readOnly }); | |
| 275 | ||
| 274 | 276 | const app = createApp({ |
| 275 | 277 | dataDir, |
| 278 | engine: engineShape, | |
| 276 | 279 | ...(readOnly ? { readOnly } : {}), |
| 277 | 280 | // A new forge starts with signup = invite (FORGE_SIGNUP below still wins). |
| 278 | 281 | seedSignup: true, |
| @@ -358,7 +361,7 @@ loadFlags(app.db); | ||
| 358 | 361 | loadTrustedHosts(app.db); |
| 359 | 362 | // With FORGE_ENGINE=worker the duties run on a Worker of their own (`engine/`), and what |
| 360 | 363 | // either thread appends the other hears from the outbox. Everywhere else: one thread, as ever. |
| 361 | const engineOn = engineMode(process.env, { hosted, readOnly }) === "worker"; | |
| 364 | const engineOn = engineShape.mode === "worker"; | |
| 362 | 365 | const tail = engineOn ? tailEvents(app.db, app.bus) : undefined; |
| 363 | 366 | // A write of the engine's is a few milliseconds. This thread waits for one with every request behind it, so |
| 364 | 367 | // it waits seconds, not the fifteen of a forge whose only other writer is itself: a stuck engine is ended (`engine/host.ts`). |
src/tui/screens/system.ts +11
| @@ -20,6 +20,8 @@ | ||
| 20 | 20 | * its own size and use against it (`selfLines`), and a parent each child's |
| 21 | 21 | * use against its size (`childLines`), both read through `spawn/usage.ts`. |
| 22 | 22 | * |
| 23 | * The engine shape this boot chose and why (`engineLines`) follows the egress line, as /system says it. | |
| 24 | * | |
| 23 | 25 | * Below the telemetry history, the five largest directories under the |
| 24 | 26 | * forge's data (#11800, `largestLines`), read through the cache /system and |
| 25 | 27 | * the MCP `system` tool share and gated as they are (`telemetryReader`). |
| @@ -46,6 +48,7 @@ import { Scroll, ago, confirmScreen, drawLines, hitScroll, later, pickerScreen } | ||
| 46 | 48 | import { largestDirs, type LargestDirs } from "../../system/largest_dirs.ts"; |
| 47 | 49 | import { dbSize, dbSizeNeed, type DbSize } from "../../system/db_size.ts"; |
| 48 | 50 | import type { PaletteEntry } from "./entries.ts"; |
| 51 | import { shapeWords } from "../../engine/mode.ts"; | |
| 49 | 52 | import { readHealth } from "../../actions/health.ts"; |
| 50 | 53 | import { egressReportedLine } from "../../system/egress_line.ts"; |
| 51 | 54 | import { featureHealth } from "../../system/feature_health.ts"; |
| @@ -419,6 +422,13 @@ export function memoryScreen(session: Session, ctx: Ctx): Screen { | ||
| 419 | 422 | } |
| 420 | 423 | |
| 421 | 424 | /** This forge's size and its use against it, a line each, as /system's "This forge's size" says it; none on a forge that is no cell child. */ |
| 425 | /** The engine shape and why, as /system says it; none where the boot recorded none. */ | |
| 426 | export function engineLines(engine: { mode: string; why: string } | undefined): string[] { | |
| 427 | if (engine === undefined) return []; | |
| 428 | const mode = engine.mode === "worker" ? "worker" : "inline"; | |
| 429 | return [`Engine: ${shapeWords({ mode, why: engine.why })}`, `Why: ${engine.why}`]; | |
| 430 | } | |
| 431 | ||
| 422 | 432 | export function selfLines(self: SelfUse | null): string[] { |
| 423 | 433 | if (self === null) return []; |
| 424 | 434 | const w = useWords(self.use); |
| @@ -470,6 +480,7 @@ export const entry: PaletteEntry = { | ||
| 470 | 480 | ctx.push(systemScreen(ctx, [ |
| 471 | 481 | ...forgeLines(readHealth(session.app, session.user)), |
| 472 | 482 | ...egressLines(session), |
| 483 | ...engineLines(session.app.config.engine), | |
| 473 | 484 | ...(self.length === 0 ? [] : ["", ...self]), |
| 474 | 485 | ...(kids.length === 0 ? [] : ["", ...kids]), |
| 475 | 486 | "", |
src/web/pages/system.ts +13
| @@ -51,6 +51,7 @@ import { featureHealth, type FeatureHealth } from "../../system/feature_health.t | ||
| 51 | 51 | import { egressReportedLine } from "../../system/egress_line.ts"; |
| 52 | 52 | import { BREAK_STEPS, MACHINES, declaredFooting, footing, offMachine, whereWords, type Footing, type Machine } from "../../system/footing.ts"; |
| 53 | 53 | import { laneWords, readOffsiteLane, type OffsiteLane } from "../../snapshot/offsite_lane.ts"; |
| 54 | import { shapeWords } from "../../engine/mode.ts"; | |
| 54 | 55 | import { badge, chartBox, disclosure, meter, pill, row, time } from "../ui.ts"; |
| 55 | 56 | import { LARGEST_DIRS, largestDirs, type LargestDirs } from "../../system/largest_dirs.ts"; |
| 56 | 57 | import { DB_FILE_CAP, DB_GROWTH_MAX, TOP, dbSize, dbSizeNeed, type DbSize } from "../../system/db_size.ts"; |
| @@ -146,6 +147,17 @@ export function selfSection(self: SelfUse | null): Html { | ||
| 146 | 147 | </section>`; |
| 147 | 148 | } |
| 148 | 149 | |
| 150 | /** The engine shape this boot chose and why; nothing in a forge that did not record one. */ | |
| 151 | export function engineSection(choice: { mode: string; why: string } | undefined): Html { | |
| 152 | if (choice === undefined) return html``; | |
| 153 | const mode = choice.mode === "worker" ? "worker" : "inline"; | |
| 154 | return html`<section class="settings-block" id="sys-engine"><h2>Engine shape</h2> | |
| 155 | <ul class="list" aria-label="Engine shape">${row({ | |
| 156 | title: shapeWords({ mode, why: choice.why }), | |
| 157 | facts: [{ label: "Why", value: choice.why }], | |
| 158 | })}</ul></section>`; | |
| 159 | } | |
| 160 | ||
| 149 | 161 | /** What this forge's own size section leaves to the page's `?`: who set the size and what is measured. */ |
| 150 | 162 | export const selfHelp = (self: SelfUse | null): Html | null => |
| 151 | 163 | self === null ? null : html`<p id="sys-self-help">Size is set by the forge that made this one. ${self.from === "process" ? "Memory and CPU count this process alone. " : ""}Disk is measured every 30 seconds.</p>`; |
| @@ -554,6 +566,7 @@ export async function systemPage(ctx: Ctx): Promise<Response> { | ||
| 554 | 566 | ${egressLine} |
| 555 | 567 | <p class="small mono" id="temps">${at("temps")}</p></section> |
| 556 | 568 | ${selfSection(self)} |
| 569 | ${engineSection(ctx.app.config.engine)} | |
| 557 | 570 | ${childrenSection(children)} |
| 558 | 571 | ${inProcessSection(inProcess)} |
| 559 | 572 | <section class="settings-block"><h2>Disks and network</h2> |
test/engine-shape.test.ts added +81
| @@ -0,0 +1,81 @@ | ||
| 1 | /** The engine shape on /system and in the terminal: which shape runs, and why. */ | |
| 2 | import { describe, expect, test } from "bun:test"; | |
| 3 | import { mkdtempSync } from "node:fs"; | |
| 4 | import { tmpdir } from "node:os"; | |
| 5 | import { join } from "node:path"; | |
| 6 | import { createApp } from "../src/app.ts"; | |
| 7 | import type { User } from "../src/core/users.ts"; | |
| 8 | import type { Ctx } from "../src/http/context.ts"; | |
| 9 | import { engineChoice } from "../src/engine/mode.ts"; | |
| 10 | import { engineLines } from "../src/tui/screens/system.ts"; | |
| 11 | import { systemPage } from "../src/web/pages/system.ts"; | |
| 12 | ||
| 13 | const where = { hosted: false, readOnly: false }; | |
| 14 | const fresh = (engine?: { mode: string; why: string }) => | |
| 15 | createApp({ dataDir: mkdtempSync(join(tmpdir(), "forge-shape-")), url: "https://x.test", port: 0, ...(engine ? { engine } : {}) }); | |
| 16 | const person = (id: string, isAdmin: boolean): User => ({ | |
| 17 | id, | |
| 18 | username: id, | |
| 19 | email: `${id}@x.test`, | |
| 20 | displayName: id, | |
| 21 | isAdmin, | |
| 22 | kind: "user", | |
| 23 | commitEmail: "noreply", | |
| 24 | createdAt: "2026-01-01T00:00:00Z", | |
| 25 | suspendedAt: null, | |
| 26 | removedAt: null, | |
| 27 | waitingAt: null, | |
| 28 | }); | |
| 29 | const page = async (app: ReturnType<typeof fresh>, user: User | undefined) => { | |
| 30 | const request = new Request("https://x.test/system"); | |
| 31 | const ctx: Ctx = { | |
| 32 | app, | |
| 33 | request, | |
| 34 | url: new URL(request.url), | |
| 35 | params: {}, | |
| 36 | auth: { user, scope: undefined, via: user ? "session" : "none" }, | |
| 37 | theme: undefined, | |
| 38 | }; | |
| 39 | const res = await systemPage(ctx); | |
| 40 | return { status: res.status, body: await res.text() }; | |
| 41 | }; | |
| 42 | ||
| 43 | describe("the choice", () => { | |
| 44 | test("says why, whichever shape runs", () => { | |
| 45 | expect(engineChoice({}, where).why).toBe("FORGE_ENGINE is not set"); | |
| 46 | expect(engineChoice({ FORGE_ENGINE: "worker" }, where).why).toBe("FORGE_ENGINE=worker is set"); | |
| 47 | expect(engineChoice({ FORGE_ENGINE: "inline" }, where)).toEqual({ mode: "inline", why: "FORGE_ENGINE=inline is set" }); | |
| 48 | expect(engineChoice({ FORGE_ENGINE: "worker" }, { ...where, hosted: true }).why).toContain("hosted child"); | |
| 49 | expect(engineChoice({ FORGE_ENGINE: "worker" }, { ...where, readOnly: true }).why).toContain("standby"); | |
| 50 | expect(engineChoice({ FORGE_ENGINE: "worker", NODE_ENV: "test" }, where).why).toContain("test boot"); | |
| 51 | }); | |
| 52 | }); | |
| 53 | ||
| 54 | describe("/system", () => { | |
| 55 | const admin = person("a", true); | |
| 56 | test("an admin who is a person reads the shape and why", async () => { | |
| 57 | const { body } = await page(fresh({ mode: "worker", why: "FORGE_ENGINE=worker is set" }), admin); | |
| 58 | expect(body).toContain("Engine shape"); | |
| 59 | expect(body).toContain("on a Worker"); | |
| 60 | expect(body).toContain("FORGE_ENGINE=worker is set"); | |
| 61 | }); | |
| 62 | test("a forge that recorded none has no section", async () => { | |
| 63 | expect((await page(fresh(), admin)).body).not.toContain("Engine shape"); | |
| 64 | }); | |
| 65 | test("a guest and a member do not see it", async () => { | |
| 66 | const app = fresh({ mode: "inline", why: "FORGE_ENGINE is not set" }); | |
| 67 | for (const user of [undefined, person("b", false)]) { | |
| 68 | expect((await page(app, user)).body).not.toContain("FORGE_ENGINE is not set"); | |
| 69 | } | |
| 70 | }); | |
| 71 | }); | |
| 72 | ||
| 73 | describe("the terminal", () => { | |
| 74 | test("gives the same words", () => { | |
| 75 | expect(engineLines({ mode: "inline", why: "FORGE_ENGINE is not set" })).toEqual([ | |
| 76 | "Engine: one thread serves and works", | |
| 77 | "Why: FORGE_ENGINE is not set", | |
| 78 | ]); | |
| 79 | expect(engineLines(undefined)).toEqual([]); | |
| 80 | }); | |
| 81 | }); |
test/engine-split.test.ts +9 −9
| @@ -15,7 +15,7 @@ import type { ForgeEvent } from "../src/core/events.ts"; | ||
| 15 | 15 | import { claimRun, createRun } from "../src/core/runs.ts"; |
| 16 | 16 | import { createUser } from "../src/core/users.ts"; |
| 17 | 17 | import { createRepo } from "../src/actions/repos.ts"; |
| 18 | import { engineMode } from "../src/engine/mode.ts"; | |
| 18 | import { engineChoice } from "../src/engine/mode.ts"; | |
| 19 | 19 | import { live } from "../src/tui/screens/common.ts"; |
| 20 | 20 | import { endOnSuspension } from "../src/tui/ssh.ts"; |
| 21 | 21 | import { serve, type Servers } from "../src/http/server.ts"; |
| @@ -59,23 +59,23 @@ const until = async (ok: () => boolean, ms = 10_000): Promise<void> => { | ||
| 59 | 59 | describe("the mode", () => { |
| 60 | 60 | test("is inline unless asked, and stays inline for a child, a standby and a test", () => { |
| 61 | 61 | const where = { hosted: false, readOnly: false }; |
| 62 | expect(engineMode({}, where)).toBe("inline"); | |
| 63 | expect(engineMode({ FORGE_ENGINE: "inline" }, where)).toBe("inline"); | |
| 64 | expect(engineMode({ FORGE_ENGINE: "worker" }, where)).toBe("worker"); | |
| 62 | expect(engineChoice({}, where).mode).toBe("inline"); | |
| 63 | expect(engineChoice({ FORGE_ENGINE: "inline" }, where).mode).toBe("inline"); | |
| 64 | expect(engineChoice({ FORGE_ENGINE: "worker" }, where).mode).toBe("worker"); | |
| 65 | 65 | expect( |
| 66 | engineMode({ FORGE_ENGINE: "worker" }, { ...where, hosted: true }), | |
| 66 | engineChoice({ FORGE_ENGINE: "worker" }, { ...where, hosted: true }).mode, | |
| 67 | 67 | ).toBe("inline"); |
| 68 | 68 | expect( |
| 69 | engineMode({ FORGE_ENGINE: "worker" }, { ...where, readOnly: true }), | |
| 69 | engineChoice({ FORGE_ENGINE: "worker" }, { ...where, readOnly: true }).mode, | |
| 70 | 70 | ).toBe("inline"); |
| 71 | 71 | expect( |
| 72 | engineMode({ FORGE_ENGINE: "worker", NODE_ENV: "test" }, where), | |
| 72 | engineChoice({ FORGE_ENGINE: "worker", NODE_ENV: "test" }, where).mode, | |
| 73 | 73 | ).toBe("inline"); |
| 74 | 74 | expect( |
| 75 | engineMode( | |
| 75 | engineChoice( | |
| 76 | 76 | { FORGE_ENGINE: "worker", NODE_ENV: "test" }, |
| 77 | 77 | { ...where, optIn: true }, |
| 78 | ), | |
| 78 | ).mode, | |
| 79 | 79 | ).toBe("worker"); |
| 80 | 80 | }); |
| 81 | 81 | }); |
new above
offline
Non-blocking: this comment belongs to
selfLines, which is now belowengineLines. Move it back so each function has its own.