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

The serve/work split switches on only when the machine has the cores #12357

Merged opened this

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

Merged

scout/forge:scout/12351-the-serve-work-split-switches-on-only-wh → main 7 commits fork 1 thread · 1 unresolved

  • Merged. scout/12351-the-serve-work-split-switches-on-only-wh was merged into main as 0af2c9c.

Review

Sign in to review this change.
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";
3636 import { dropAllPins } from "./git/pins_kept.ts";
3737
3838 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 };
3941 /** Everything lives here: index db, bare repos, the internal socket. */
4042 dataDir: string;
4143 /**
src/engine/mode.ts +18 −6
@@ -11,12 +11,24 @@
1111
1212 export type EngineMode = "inline" | "worker";
1313
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(
1521 env: Record<string, string | undefined>,
1622 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" };
2230 }
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";
8787 import { peopleOnCrews } from "./core/agents.ts";
8888 import { startNotifier } from "./crew/notify.ts";
8989 import { tailEvents } from "./core/event_tail.ts";
90 import { engineMode } from "./engine/mode.ts";
90 import { engineChoice } from "./engine/mode.ts";
9191 import { startEngine } from "./engine/host.ts";
9292 import { startDuties } from "./engine/duties.ts";
9393 import { startRetention } from "./system/retention.ts";
@@ -271,8 +271,11 @@ watchStalls(loopLog, undefined, undefined, undefined, (late, at) => {
271271
272272 const previewKey = previewIdentityKey(process.env);
273273
274 const engineShape = engineChoice(process.env, { hosted, readOnly });
275
274276 const app = createApp({
275277 dataDir,
278 engine: engineShape,
276279 ...(readOnly ? { readOnly } : {}),
277280 // A new forge starts with signup = invite (FORGE_SIGNUP below still wins).
278281 seedSignup: true,
@@ -358,7 +361,7 @@ loadFlags(app.db);
358361 loadTrustedHosts(app.db);
359362 // With FORGE_ENGINE=worker the duties run on a Worker of their own (`engine/`), and what
360363 // 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";
362365 const tail = engineOn ? tailEvents(app.db, app.bus) : undefined;
363366 // A write of the engine's is a few milliseconds. This thread waits for one with every request behind it, so
364367 // 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 @@
2020 * its own size and use against it (`selfLines`), and a parent each child's
2121 * use against its size (`childLines`), both read through `spawn/usage.ts`.
2222 *
23 * The engine shape this boot chose and why (`engineLines`) follows the egress line, as /system says it.
24 *
2325 * Below the telemetry history, the five largest directories under the
2426 * forge's data (#11800, `largestLines`), read through the cache /system and
2527 * the MCP `system` tool share and gated as they are (`telemetryReader`).
@@ -46,6 +48,7 @@ import { Scroll, ago, confirmScreen, drawLines, hitScroll, later, pickerScreen }
4648 import { largestDirs, type LargestDirs } from "../../system/largest_dirs.ts";
4749 import { dbSize, dbSizeNeed, type DbSize } from "../../system/db_size.ts";
4850 import type { PaletteEntry } from "./entries.ts";
51 import { shapeWords } from "../../engine/mode.ts";
4952 import { readHealth } from "../../actions/health.ts";
5053 import { egressReportedLine } from "../../system/egress_line.ts";
5154 import { featureHealth } from "../../system/feature_health.ts";
@@ -419,6 +422,13 @@ export function memoryScreen(session: Session, ctx: Ctx): Screen {
419422 }

Non-blocking: this comment belongs to selfLines, which is now below engineLines. Move it back so each function has its own.

420423
421424 /** 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
422432 export function selfLines(self: SelfUse | null): string[] {
423433 if (self === null) return [];
424434 const w = useWords(self.use);
@@ -470,6 +480,7 @@ export const entry: PaletteEntry = {
470480 ctx.push(systemScreen(ctx, [
471481 ...forgeLines(readHealth(session.app, session.user)),
472482 ...egressLines(session),
483 ...engineLines(session.app.config.engine),
473484 ...(self.length === 0 ? [] : ["", ...self]),
474485 ...(kids.length === 0 ? [] : ["", ...kids]),
475486 "",
src/web/pages/system.ts +13
@@ -51,6 +51,7 @@ import { featureHealth, type FeatureHealth } from "../../system/feature_health.t
5151 import { egressReportedLine } from "../../system/egress_line.ts";
5252 import { BREAK_STEPS, MACHINES, declaredFooting, footing, offMachine, whereWords, type Footing, type Machine } from "../../system/footing.ts";
5353 import { laneWords, readOffsiteLane, type OffsiteLane } from "../../snapshot/offsite_lane.ts";
54 import { shapeWords } from "../../engine/mode.ts";
5455 import { badge, chartBox, disclosure, meter, pill, row, time } from "../ui.ts";
5556 import { LARGEST_DIRS, largestDirs, type LargestDirs } from "../../system/largest_dirs.ts";
5657 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 {
146147 </section>`;
147148 }
148149
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
149161 /** What this forge's own size section leaves to the page's `?`: who set the size and what is measured. */
150162 export const selfHelp = (self: SelfUse | null): Html | null =>
151163 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> {
554566 ${egressLine}
555567 <p class="small mono" id="temps">${at("temps")}</p></section>
556568 ${selfSection(self)}
569 ${engineSection(ctx.app.config.engine)}
557570 ${childrenSection(children)}
558571 ${inProcessSection(inProcess)}
559572 <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";
1515 import { claimRun, createRun } from "../src/core/runs.ts";
1616 import { createUser } from "../src/core/users.ts";
1717 import { createRepo } from "../src/actions/repos.ts";
18 import { engineMode } from "../src/engine/mode.ts";
18 import { engineChoice } from "../src/engine/mode.ts";
1919 import { live } from "../src/tui/screens/common.ts";
2020 import { endOnSuspension } from "../src/tui/ssh.ts";
2121 import { serve, type Servers } from "../src/http/server.ts";
@@ -59,23 +59,23 @@ const until = async (ok: () => boolean, ms = 10_000): Promise<void> => {
5959 describe("the mode", () => {
6060 test("is inline unless asked, and stays inline for a child, a standby and a test", () => {
6161 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");
6565 expect(
66 engineMode({ FORGE_ENGINE: "worker" }, { ...where, hosted: true }),
66 engineChoice({ FORGE_ENGINE: "worker" }, { ...where, hosted: true }).mode,
6767 ).toBe("inline");
6868 expect(
69 engineMode({ FORGE_ENGINE: "worker" }, { ...where, readOnly: true }),
69 engineChoice({ FORGE_ENGINE: "worker" }, { ...where, readOnly: true }).mode,
7070 ).toBe("inline");
7171 expect(
72 engineMode({ FORGE_ENGINE: "worker", NODE_ENV: "test" }, where),
72 engineChoice({ FORGE_ENGINE: "worker", NODE_ENV: "test" }, where).mode,
7373 ).toBe("inline");
7474 expect(
75 engineMode(
75 engineChoice(
7676 { FORGE_ENGINE: "worker", NODE_ENV: "test" },
7777 { ...where, optIn: true },
78 ),
78 ).mode,
7979 ).toBe("worker");
8080 });
8181 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs