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

Absorb: fire a feature's schedule #9916

Parked opened this
Closed without merging

scout/forge:scout/9883-absorb-fire-a-feature-s-schedule → main 15 commits fork 2 threads · 2 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
15 files changed +566 −15
docs/features/absorb.md +17 −5
@@ -57,7 +57,7 @@ What the feed holds about an app's repository (runs, pulls, issues, looks) shows
5757
5858 ## Without the crew
5959
60 Absorbing, settings, the menu entry and the page use no model and start no agent run. They work with the crew off and no model credential on the forge. `test/apps-features.test.ts` runs the whole flow that way. The forge never hands an app the crew's credential. A feature's schedule is the app's own: the app reads `FORGE_SETTING_*` and runs its own timer. An app that wants a model's judgment on top, such as an issue written from what it found, must do its work without one and treat the model as optional.
60 Absorbing, settings, the menu entry and the page use no model and start no agent run. They work with the crew off and no model credential on the forge. `test/apps-features.test.ts` runs the whole flow that way. The forge never hands an app the crew's credential. A feature's schedule is fired by the forge (below), with no model; the app does the work. An app that wants a model's judgment on top, such as an issue written from what it found, must do its work without one and treat the model as optional.
6161
6262 ## Settings are not secrets, except `secret`
6363
@@ -69,6 +69,22 @@ Other settings are stored as plain values. Anyone who can read the app's reposit
6969
7070 See `docs/features/absorb-review.md` for the findings of #9441.
7171
72 ## A schedule the forge fires
73
74 A feature may declare when the forge should knock:
75
76 ```json
77 "schedule": { "path": "/run", "hour": "runHourUtc", "days": "runDays" }
78 ```
79
80 `hour` names an `int` setting (min 0, max 23) and `days`, optional, a `days` setting; with no `days` the knock is daily. An admin moves the schedule with the settings form. Once an absorbed app's production is running, the forge sends it `POST <path>` in that UTC hour, once per hour and app (the slot is kept in `app_feature_fire`, so a restart does not knock twice). The call goes to the app's own port, not through the proxy, with a 30 second limit; the answer's status is kept and nothing else is read.
81
82 **Failure.** The slot is claimed before the call, so a knock that fails or is never answered is **not retried** in that hour. It is recorded: an HTTP status when the app answered, `-1` when it did not, `0` when the forge stopped mid-call. The settings page (`/settings/features/:slug`), `GET /api/v1/features/:slug` and the `features` MCP tool with a `slug` all carry the `schedule` sentence: the declared schedule and what the last knock got.
83
84 **Doors.** The settings page, the API and the MCP show it. The terminal screen (`src/tui/screens/features.ts`) is only the queue of declarations waiting for an admin's acceptance and shows no settings, so it shows no schedule either. There is no "fire now": the only way to see a real fire is to set the hour setting to the current UTC hour, and a preview's forge never knocks.
85
86 The app can tell the forge from a visitor: the request carries `x-forge-identity` with the role `schedule` and a `x-forge-signature` under the app's identity key, the same signing a visitor's request gets. The proxy drops a client's copy of those headers and of `x-forge-schedule`, so a visitor cannot send them. `x-forge-schedule` holds the slot (`2026-11-09T13`). An hour the forge was down for, or that failed, is not made up or retried, and a preview's forge does not knock. The schedule is a `Schedule` row on the feature's settings page and a line on its terminal settings screen. Code: `src/apps/schedule.ts`; test: `test/feature-schedule.test.ts`.
87
7288 ## Code and tests
7389
7490 - Code: `src/apps/feature.ts` (the declaration), `src/core/features.ts` (storage), `src/actions/features.ts` (the rules), `src/apps/feature_env.ts` (the environment), `src/web/pages/features.ts`, `src/http/api/features.ts`, `src/http/mcp/tools/features.ts`.
@@ -80,10 +96,6 @@ A pack's app may carry `"absorb": true` (a boolean, nothing else). `pack deploy`
8096
8197 Settings stay behind on a fork. A fork of another forge's app carries its `feature` block, which declares and does nothing; the new forge has its own settings (the declared defaults until an admin changes them) and its own admin decides on the absorb.
8298
83 ## Not done yet
84
85 Until then an absorbed app is a menu link with kept settings (Settings › Features says so). The forge does not yet fire a feature's schedule (#9883).
86
8799 ## MCP tools
88100
89101 A feature may declare `"tools": { "scan": { "description": "Run a scan now", "writes": true } }` (at most 12; `writes` is true unless it says `false`). The forge adds no tool to `/mcp` for them: the `features` tool lists them as `tools` with a `slug`, and `{ slug, tool, args }` calls one of an absorbed app. The forge POSTs `{ "args": … }` to the app's `/forge/tools/<name>` over loopback and returns its JSON (at most 64 KB, 10 seconds). A read tool answers at once for anyone who can read the app; a write tool is for someone who can write it, needs an `rw` token and plans first (`dryRun: false` does it). The plan of a write is told only once the call could be made (allowed, absorbed, running). These tools are MCP-only on purpose: they are an agent's door to the app, and the app's own page is the person's, so the terminal has no entry for them (a person reaches the app itself there). Code: `src/apps/feature_tools.ts`, `src/actions/feature_tools.ts`; tests: `test/feature-tools.test.ts`, `test/features.test.ts`.
src/actions/features.ts +14
@@ -30,6 +30,9 @@ import {
3030 keepDeclaration,
3131 featureSettings,
3232 getAbsorbed,
33 lastFire,
34 fireSays,
35 type Fired,
3336 listAbsorbed,
3437 setFeatureSettings as keepSettings,
3538 unabsorb,
@@ -90,6 +93,8 @@ export interface FeatureView {
9093 readonly tools: readonly ToolSpec[];
9194 /** Where the app comes from: the upstream only when the reader may read it. */
9295 readonly provenance: Provenance;
96 /** The declared schedule and its last knock, in words; null when the app declares none. */
97 readonly schedule: string | null;
9398 }
9499
95100 /**
@@ -209,6 +214,14 @@ export async function declaresFeature(app: App, actor: User | undefined, repo: R
209214 return read.ok && read.value !== undefined;
210215 }
211216
217 function scheduleSays(spec: FeatureSpec | undefined, absorbed: boolean, fired: Fired | undefined): string | null {
218 if (spec?.schedule === undefined) return null;
219 const { path, hour, days } = spec.schedule;
220 const when = `POST ${path} at the hour in ${hour}${days === undefined ? ", daily" : `, on ${days}`}`;
221 if (!absorbed) return `${when}, once absorbed`;
222 return fired === undefined ? `${when}; not fired yet` : `${when}; last ${fireSays(fired)}`;
223 }
224
212225 function viewOf(
213226 record: AppRecord,
214227 repo: Repo,
@@ -237,6 +250,7 @@ function viewOf(
237250 absorbedAt: absorbed?.absorbedAt ?? null,
238251 problem,
239252 provenance,
253 schedule: scheduleSays(spec, absorbed !== undefined, lastFire(app.db, record.id)),
240254 tools: spec?.tools ?? [],
241255 settings: (spec?.settings ?? []).map((s) => {
242256 const name = settingEnvName(s.key);
src/apps/feature.ts +36 −2
@@ -66,10 +66,25 @@ export interface FeatureSpec {
6666 /** The app path the forge's nav opens. */
6767 readonly page: string;
6868 readonly settings: readonly SettingSpec[];
69 /** When the forge knocks on the app: see `FeatureSchedule`. */
70 readonly schedule?: FeatureSchedule | undefined;
6971 /** MCP tools the app serves through the forge's `features` tool (`feature_tools.ts`). */
7072 readonly tools: readonly ToolSpec[];
7173 }
7274
75 /**
76 * `"schedule": { "path": "/run", "hour": "runHourUtc", "days": "runDays" }`:
77 * the forge sends the app a POST to `path` in the hour its `hour` setting
78 * (an `int`) names, on the days its `days` setting (a `days`) names, every day
79 * when `days` is left out. The two are names of declared settings, so an admin
80 * moves the schedule with the settings form.
81 */
82 export interface FeatureSchedule {
83 readonly path: string;
84 readonly hour: string;
85 readonly days?: string | undefined;
86 }
87
7388 const KEY = /^[a-z][a-zA-Z0-9]{0,39}$/;
7489 const CHOICE = /^[a-z0-9][a-z0-9._-]{0,39}$/;
7590 const NAME_MAX = 40;
@@ -116,11 +131,30 @@ export function parseFeature(forgeJson: Raw): Result<FeatureSpec | undefined, st
116131 }
117132 const envs = new Set(settings.map((s) => settingEnvName(s.key)));
118133 if (envs.size !== settings.length) return bad("two settings would share one FORGE_SETTING_ name");
134 const schedule = parseSchedule(block["schedule"], settings);
135 if (!schedule.ok) return schedule;
119136 for (const extra of Object.keys(block))
120 if (!["name", "summary", "page", "settings", "tools"].includes(extra)) return bad(`unknown field ${extra}`);
137 if (!["name", "summary", "page", "settings", "schedule", "tools"].includes(extra)) return bad(`unknown field ${extra}`);
121138 const tools = parseTools(block["tools"]);
122139 if (!tools.ok) return tools;
123 return ok({ tools: tools.value, name: name.trim(), summary: typeof summary === "string" && summary.trim() !== "" ? summary.trim() : null, page, settings });
140 return ok({ tools: tools.value, name: name.trim(), summary: typeof summary === "string" && summary.trim() !== "" ? summary.trim() : null, page, settings, ...(schedule.value === undefined ? {} : { schedule: schedule.value }) });
141 }
142
143 function parseSchedule(raw: unknown, settings: readonly SettingSpec[]): Result<FeatureSchedule | undefined, string> {
144 if (raw === undefined) return ok(undefined);
145 if (!isObject(raw)) return bad("schedule must be an object");
146 for (const extra of Object.keys(raw)) if (!["path", "hour", "days"].includes(extra)) return bad(`schedule: unknown field ${extra}`);
147 const path = raw["path"];
148 if (typeof path !== "string" || !path.startsWith("/") || path.startsWith("//") || path.length > 200 || /[\s\\]/.test(path))
149 return bad("schedule: path is a path on the app, starting with /");
150 const hour = raw["hour"];
151 const hourSpec = settings.find((s) => s.key === hour);
152 if (hourSpec === undefined || hourSpec.type !== "int" || (hourSpec.min ?? -1) < 0 || (hourSpec.max ?? 24) > 23)
153 return bad("schedule: hour names an int setting with min 0 and max 23");
154 const days = raw["days"];
155 if (days !== undefined && settings.find((s) => s.key === days)?.type !== "days")
156 return bad("schedule: days names a days setting");
157 return ok({ path, hour: hour as string, ...(days === undefined ? {} : { days: days as string }) });
124158 }
125159
126160 function parseSetting(key: string, raw: unknown): Result<SettingSpec, string> {
src/apps/proxy.ts +37 −2
@@ -320,7 +320,7 @@ export function identityKey(dataDir: string, appId: string): string {
320320 * dropped before the forge speaks, so a verified signature is the only
321321 * thing an app has to trust.
322322 */
323 export const IDENTITY_HEADERS = ["x-forge-identity", "x-forge-signature"];
323 export const IDENTITY_HEADERS = ["x-forge-identity", "x-forge-signature", "x-forge-schedule"];
324324
325325 export function identityHeaders(
326326 dataDir: string,
@@ -328,13 +328,48 @@ export function identityHeaders(
328328 grant: Grant | undefined,
329329 ): Record<string, string> {
330330 if (grant?.who === undefined) return {};
331 const identity = `${grant.who.id}|${grant.who.name}|${grant.who.role}|${grant.expiresMs}`;
331 return signIdentity(dataDir, appId, grant.who.id, grant.who.name, grant.who.role, grant.expiresMs);
332 }
333
334 /** The two identity headers for any speaker the forge vouches for: a visitor, or the forge itself (`schedule`). */
335 export function signIdentity(
336 dataDir: string,
337 appId: string,
338 id: string,
339 name: string,
340 role: string,
341 expiresMs: number,
342 ): Record<string, string> {
343 const identity = `${id}|${name}|${role}|${expiresMs}`;
332344 const signature = createHmac("sha256", identityKey(dataDir, appId))
333345 .update(identity)
334346 .digest("base64url");
335347 return { "x-forge-identity": identity, "x-forge-signature": signature };
336348 }
337349
350 /**
351 * What an app does with the two headers: the speaker they name, when the
352 * signature is the app's own key's and the expiry has not passed.
353 */
354 export function verifyIdentity(
355 dataDir: string,
356 appId: string,
357 identity: string | null,
358 signature: string | null,
359 now = Date.now(),
360 ): { id: string; name: string; role: string } | undefined {
361 if (identity === null || signature === null) return undefined;
362 const expected = createHmac("sha256", identityKey(dataDir, appId)).update(identity).digest("base64url");
363 const a = Buffer.from(signature);
364 const b = Buffer.from(expected);
365 if (a.length !== b.length || !timingSafeEqual(a, b)) return undefined;
366 const parts = identity.split("|");
367 if (parts.length !== 4) return undefined;
368 const [id, name, role, expires] = parts as [string, string, string, string];
369 if (!/^\d+$/.test(expires) || Number(expires) <= now) return undefined;
370 return { id, name, role };
371 }
372
338373 /** The URL the forge redirects a vouched-for visitor to. */
339374 export function grantUrl(
340375 runtime: AppsRuntime,
src/apps/schedule.ts added +137
@@ -0,0 +1,137 @@
1 /**
2 * A feature's schedule, fired by the forge. An absorbed app whose `feature`
3 * declares a `schedule` (`apps/feature.ts`) is sent a POST to its path in the
4 * hour its settings name. No timer lives in the app and no model is asked.
5 *
6 * The call goes straight to the app's own port, never through the proxy, and
7 * carries the same signed `x-forge-identity` a visitor's request would, with
8 * the role `schedule` (`signIdentity`, checked with `verifyIdentity`): the
9 * proxy strips a client's copy, so an app that verifies it knows the forge
10 * knocked. Once per hour and app: the slot is claimed before the call, so a
11 * restart inside the hour knocks no second time, and so a failed or unanswered
12 * knock is not retried that hour. An hour the forge was down for is not made
13 * up. Production only, and not in a preview's forge.
14 */
15
16 import { readFileSync } from "node:fs";
17 import { join } from "node:path";
18 import type { App } from "../app.ts";
19 import { listApps } from "../core/apps.ts";
20 import { crewOffInPreview } from "../crew/preview.ts";
21 import { claimFire, FIRE_FAILED, featureSettings, getAbsorbed, recordFire } from "../core/features.ts";
22 import { createLog } from "../kernel/log.ts";
23 import { DAYS, featureEnv, parseFeature, settingEnvName, type FeatureSchedule, type FeatureSpec } from "./feature.ts";
24 import { signIdentity } from "./proxy.ts";
25 import { appsRuntime, type AppsRuntime } from "./runtime.ts";
26
27 const log = createLog("feature-schedule");
28
29 export const SCHEDULE_TICK_MS = 60_000;
30 const FIRE_TIMEOUT_MS = 30_000;
31
32 /** The slot `now` is in when the schedule says to fire: `2026-11-08T13` (UTC hour), else undefined. */
33 export function slotDue(schedule: FeatureSchedule, env: Record<string, string>, now: number): string | undefined {
34 const hour = Number(env[settingEnvName(schedule.hour)]);
35 const at = new Date(now);
36 if (!Number.isInteger(hour) || at.getUTCHours() !== hour) return undefined;
37 if (schedule.days !== undefined) {
38 const days = (env[settingEnvName(schedule.days)] ?? "").split(",");
39 // getUTCDay: 0 is Sunday; DAYS starts on Monday.
40 if (!days.includes(DAYS[(at.getUTCDay() + 6) % 7] as string)) return undefined;
41 }
42 return at.toISOString().slice(0, 13);
43 }
44
45 /** The headers the app can check: the forge's signed identity, role `schedule`, and the slot. */
46 export function fireHeaders(dataDir: string, appId: string, slot: string, now: number): Record<string, string> {
47 return { ...signIdentity(dataDir, appId, "forge", "forge", "schedule", now + 60_000), "x-forge-schedule": slot };
48 }
49
50 export type Fire = (url: string, headers: Record<string, string>) => Promise<number>;
51
52 const knock: Fire = async (url, headers) => {
53 const r = await fetch(url, { method: "POST", headers, redirect: "manual", signal: AbortSignal.timeout(FIRE_TIMEOUT_MS) });
54 await r.body?.cancel();
55 return r.status;
56 };
57
58 /** The declaration of the commit an app runs, read once per commit: a minute's pass must not read a disk. */
59 const declared = new Map<string, { oid: string; spec: FeatureSpec | undefined }>();
60
61 function specOf(appId: string, oid: string, dir: string): FeatureSpec | undefined {
62 const known = declared.get(appId);
63 if (known?.oid === oid) return known.spec;
64 let spec: FeatureSpec | undefined;
65 try {
66 const parsed = JSON.parse(readFileSync(join(dir, "forge.json"), "utf8")) as unknown;
67 if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
68 const read = parseFeature(parsed as Record<string, unknown>);
69 spec = read.ok ? read.value : undefined;
70 }
71 } catch {
72 spec = undefined;
73 }
74 declared.set(appId, { oid, spec });
75 return spec;
76 }
77
78 /** One pass: knock on every absorbed app that is due and has not been knocked on this hour. Returns the slugs fired. */
79 export async function fireDue(
80 app: App,
81 now: number,
82 fire: Fire = knock,
83 runtime: Pick<AppsRuntime, "liveFor"> | undefined = appsRuntime(app),
84 ): Promise<string[]> {
85 if (runtime === undefined) return [];
86 const fired: string[] = [];
87 for (const record of listApps(app.db)) {
88 if (getAbsorbed(app.db, record.id) === undefined) continue;
89 const live = runtime.liveFor(record, "production");
90 if (live === undefined) continue;
91 const spec = specOf(record.id, live.commitOid, live.dir);
92 if (spec?.schedule === undefined) continue;
93 const slot = slotDue(spec.schedule, featureEnv(spec, featureSettings(app.db, record.id)), now);
94 if (slot === undefined || !claimFire(app.db, record.id, slot)) continue;
95 let status = FIRE_FAILED;
96 try {
97 status = await fire(`http://127.0.0.1:${live.port}${spec.schedule.path}`, fireHeaders(app.config.dataDir, record.id, slot, now));
98 } catch (error) {
99 log.warn("feature schedule not answered", { app: record.slug, error: String(error) });
100 }
101 recordFire(app.db, record.id, status);
102 fired.push(record.slug);
103 }
104 return fired;
105 }
106
107 /**
108 * Look every minute; the function returned stops it. Nothing starts in a
109 * preview (its copy of the data would knock twice) or without apps running.
110 */
111 export function startFeatureSchedule(
112 app: App,
113 options: {
114 readonly fire?: Fire;
115 readonly tickMs?: number;
116 readonly now?: () => number;
117 /** The clock that calls the tick; a test passes its own and calls the tick itself. */
118 readonly every?: (tick: () => Promise<void>, ms: number) => () => void;
119 readonly runtime?: Pick<AppsRuntime, "liveFor">;
120 readonly env?: Record<string, string | undefined>;
121 } = {},
122 ): (() => void) | undefined {
123 const runtime = options.runtime ?? appsRuntime(app);
124 if (runtime === undefined || crewOffInPreview(options.env)) return undefined;
125 const tick = (): Promise<void> =>
126 fireDue(app, (options.now ?? Date.now)(), options.fire, runtime).then(
127 () => undefined,
128 (error) => log.warn("feature schedule failed", { error: String(error) }),
129 );
130 const every =
131 options.every ??
132 ((run, ms) => {
133 const timer = setInterval(run, ms);
134 return () => clearInterval(timer);
135 });
136 return every(tick, options.tickMs ?? SCHEDULE_TICK_MS);
137 }
src/core/features.ts +43
@@ -68,6 +68,49 @@ export function setFeatureSettings(db: Database, appId: string, values: Readonly
6868 })();
6969 }
7070
71 /** Not answered yet: the slot is claimed and the knock is in flight (or the forge died in it). */
72 export const FIRE_PENDING = 0;
73 /** The knock got no answer: refused, timed out or unreachable. */
74 export const FIRE_FAILED = -1;
75
76 export interface Fired {
77 readonly slot: string;
78 readonly firedAt: string;
79 /** An HTTP status, or `FIRE_PENDING` / `FIRE_FAILED`. */
80 readonly status: number;
81 }
82
83 /** Claim an hour for an app: true when this call took it, false when it was already taken. */
84 export function claimFire(db: Database, appId: string, slot: string): boolean {
85 return (
86 db
87 .query(
88 `INSERT INTO app_feature_fire (app_id, slot) VALUES (?1, ?2)
89 ON CONFLICT (app_id) DO UPDATE SET slot = excluded.slot, fired_at = strftime('%Y-%m-%dT%H:%M:%fZ','now'), status = 0
90 WHERE slot <> excluded.slot`,
91 )
92 .run(appId, slot).changes > 0
93 );
94 }
95
96 export function recordFire(db: Database, appId: string, status: number): void {
97 db.query("UPDATE app_feature_fire SET status = ?2 WHERE app_id = ?1").run(appId, status);
98 }
99
100 /** The last knock on an app's schedule, if there was one. */
101 export function lastFire(db: Database, appId: string): Fired | undefined {
102 const r = db
103 .query<{ slot: string; fired_at: string; status: number }, [string]>("SELECT slot, fired_at, status FROM app_feature_fire WHERE app_id = ?1")
104 .get(appId);
105 return r === null ? undefined : { slot: r.slot, firedAt: r.fired_at, status: r.status };
106 }
107
108 /** What a knock came to, in a few words (a failed or unanswered hour is not made up). */
109 export function fireSays(f: Fired): string {
110 const how = f.status === FIRE_PENDING ? "no answer recorded" : f.status === FIRE_FAILED ? "the app did not answer, not retried" : `answered ${f.status}`;
111 return `${f.slot.replace("T", " ")}:00 UTC, ${how}`;
112 }
113
71114 /** Forget these kept settings (a cleared secret): the row goes, so it reads as not set. */
72115 export function clearFeatureSettings(db: Database, appId: string, keys: readonly string[]): void {
73116 const del = db.query("DELETE FROM app_feature_setting WHERE app_id = ?1 AND key = ?2");
src/core/migration-pins/20261108190000-feature-fire.pin added +1
@@ -0,0 +1,1 @@
1 27fddaeeccc9ff4a8936f0bbe7d49fd354e55989c2f4ccffc4bcee349f9a7d94
src/core/migrations/20261108190000-feature-fire.ts added +10
@@ -0,0 +1,10 @@
1 // The last hour the forge knocked on an absorbed feature's schedule, so a
2 // restart inside that hour does not knock twice. Additive.
3 export default `
4 CREATE TABLE app_feature_fire (
5 app_id TEXT PRIMARY KEY,
6 slot TEXT NOT NULL,
7 fired_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
8 status INTEGER NOT NULL DEFAULT 0
9 );
10 `;
src/main.ts +4
@@ -56,6 +56,7 @@ import { startMirrorOut } from "./origins/mirror-out.ts";
5656 import { startMirrorPulls } from "./origins/mirror-pulls.ts";
5757 import { startProbes } from "./contract/probes.ts";
5858 import { startNightly } from "./nightly/service.ts";
59 import { startFeatureSchedule } from "./apps/schedule.ts";
5960 import { startSnapshots } from "./snapshot/service.ts";
6061 import { resolveDestination } from "./snapshot/destination.ts";
6162 import { resolveMirror } from "./snapshot/mirror.ts";
@@ -484,6 +485,8 @@ const probes = apps === undefined ? undefined : startProbes(app, apps);
484485 // of what the gate excludes, filing the same `Flaky:` and `Red:` issues and
485486 // the quarantine pull (docs/DEVELOP.md).
486487 const nightly = appsOn ? startNightly(app, { forgeUrl, token: process.env["FORGE_TOKEN"] }) : undefined;
488 // An absorbed feature's schedule: the forge knocks on the app in its hour (not in a preview).
489 const featureSchedule = startFeatureSchedule(app);
487490 // The snapshot: everything that cannot be rebuilt, nightly, to what an
488491 // operator sealed on the Backups page, else the platform's (`S3_*`) or a
489492 // directory (`FORGE_SNAPSHOT_DIR`). A forge given none says so on that page.
@@ -874,6 +877,7 @@ function drain(signal: NodeJS.Signals): Promise<unknown> {
874877 drainStreams();
875878 clearInterval(deliveryTimer);
876879 clearInterval(nightlyScanTimer);
880 featureSchedule?.();
877881 clearInterval(heartbeatTimer);
878882 clearInterval(upstreamTimer);
879883 clearInterval(reachTimer);
src/tui/screens/featureswitch.ts +12 −1
@@ -18,6 +18,9 @@ import {
1818 import type { Ctx, Screen } from "../app/app.ts";
1919 import { binding } from "../app/keys.ts";
2020 import type { Session } from "../session.ts";
21 import { style } from "../term/style.ts";
22 import { truncate } from "../term/width.ts";
23 import { fill, len, split } from "../ui/layout.ts";
2124 import { ListState, drawList, promptScreen, runAsync, type ListRow } from "./common.ts";
2225 import type { PaletteEntry } from "./entries.ts";
2326
@@ -56,7 +59,15 @@ function settingsScreen(f: Session, ctx: Ctx, slug: string): Screen {
5659 keys: [binding(["j", "k"], "move cursor"), binding(["enter"], "change")],
5760 load: reload,
5861 render(area, s) {
59 drawList(s, area, ctx.theme.c, state, (view?.settings ?? []).map(settingRow));
62 const c = ctx.theme.c;
63 const note = view?.schedule ?? null;
64 if (note === null) {
65 drawList(s, area, c, state, (view?.settings ?? []).map(settingRow));
66 return;
67 }
68 const [head, body] = split(area, "v", [len(1), fill(1)]);
69 s.text(head!.x, head!.y, truncate(`Schedule: ${note}`, head!.w), style(c.mutedFg, c.bg), head!.x + head!.w);
70 drawList(s, body!, c, state, (view?.settings ?? []).map(settingRow));
6071 },
6172 key(e) {
6273 const settings = view?.settings ?? [];
src/web/pages/features.ts +6 −2
@@ -56,7 +56,11 @@ export function switchNote(f: Pick<FeatureView, "name" | "absorbed">): string {
5656
5757 /** Where the app comes from, on a feature's own page: `dl` rows, the upstream when a fork and who last changed it. */
5858 export function provenanceRows(p: FeatureView["provenance"]) {
59 const facts = provenanceFacts(p);
59 return factRows(provenanceFacts(p));
60 }
61
62 /** Label and value pairs as `dl` rows. */
63 export function factRows(facts: readonly { label: string; value: string }[]) {
6064 if (facts.length === 0) return null;
6165 return html`<dl class="status-rows">${facts.map((f) => html`<div class="status-row"><dt>${f.label}</dt><dd>${f.value}</dd></div>`)}</dl>`;
6266 }
@@ -199,7 +203,7 @@ function featureView(ctx: Ctx, f: FeatureView, refused?: Refused, items: readonl
199203 <h2>${f.name}</h2>
outdated

Design 1 and 8: the sentence is long, and it repeats "not retried" in two places. Make it one plain sentence. Also give the schedule a dl row beside the other facts (principle 7) rather than a loose paragraph. The same facts should reach src/tui/.

200204 ${f.absorbed ? badge("absorbed", { tone: "success" }) : badge("not absorbed", { variant: "outline" })}
201205 </div>
202 ${provenanceRows(f.provenance)}
206 ${factRows([...provenanceFacts(f.provenance), ...(f.schedule === null ? [] : [{ label: "Schedule", value: f.schedule }])])}
203207 ${f.settings.length === 0
204208 ? html`<p class="muted small">${f.problem ?? "This feature declares no settings."}</p>`
205209 : html`<form method="post" action="${base}">
test/apps-identity.test.ts +4 −1
@@ -101,6 +101,7 @@ describe("apps: identity, and a deploy that never answers", () => {
101101 fetch(request) {
102102 return Response.json({
103103 identity: request.headers.get("x-forge-identity"),
104 schedule: request.headers.get("x-forge-schedule"),
104105 signature: request.headers.get("x-forge-signature"),
105106 key: process.env.FORGE_APP_IDENTITY_KEY ?? "",
106107 });
@@ -135,9 +136,11 @@ describe("apps: identity, and a deploy that never answers", () => {
135136 // A client's own claim never reaches the app.
136137 "x-forge-identity": "evil|mallory|admin|9999999999999",
137138 "x-forge-signature": "AAAA",
139 "x-forge-schedule": "2026-11-09T13",
138140 },
139141 })
140 ).json()) as { identity: string; signature: string; key: string };
142 ).json()) as { identity: string; signature: string; key: string; schedule: string | null };
143 expect(heard.schedule).toBeNull(); // nor a client's claim to be the forge's timer
141144 expect(heard.key).toBe(identityKey(dataDir, record.id));
142145 const [id, name, role, expires] = heard.identity.split("|");
143146 expect(id).toBe(alice.id);
test/build-cart.test.ts +6 −1
@@ -77,7 +77,12 @@ describe("a pin's cart", () => {
7777 expect(res.status).toBe(202);
7878 expect(await res.json()).toMatchObject({ demo: { name: "fiesta-kart", version: "1", launch: "file", page: "/", showcase: true } });
7979 // karts is no app, so there is no build to capture from: the state says why.
80 await Bun.sleep(50);
80 // Wait for it to land rather than guess: a late failure must not overwrite the next test's capture.
81 for (let i = 0; i < 200; i++) {
82 const state = ((await (await api("karts/builds/v1/cart")).json()) as { capture: { state: string } }).capture.state;
83 if (state === "failed") break;
84 await Bun.sleep(25);
85 }
8186 expect(await (await api("karts/builds/v1/cart")).json()).toMatchObject({ capture: { state: "failed", error: "not_an_app" } });
8287 });
8388
test/feature-schedule.test.ts added +226
@@ -0,0 +1,226 @@
1 /**
2 * A feature's schedule, fired by the forge: the declaration names its hour
3 * and days by settings; the forge knocks once per hour on an absorbed app's
4 * production, signed as the forge; nothing is sent for an app that is not
5 * absorbed, off its hour or day, or already knocked on this hour.
6 */
7 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
8 import { mkdtemp, rm } from "node:fs/promises";
9 import { tmpdir } from "node:os";
10 import { join } from "node:path";
11 import { createApp, type App } from "../src/app.ts";
12 import { parseFeature } from "../src/apps/feature.ts";
13 import { SCHEDULE_TICK_MS, fireDue, fireHeaders, slotDue, startFeatureSchedule } from "../src/apps/schedule.ts";
14 import { verifyIdentity } from "../src/apps/proxy.ts";
15 import { getFeature } from "../src/actions/features.ts";
16 import { commitToBranch, createRepo } from "../src/actions/repos.ts";
17 import { createUser, type User } from "../src/core/users.ts";
18 import { createApp as insertApp } from "../src/core/apps.ts";
19 import { absorb, setFeatureSettings, unabsorb } from "../src/core/features.ts";
20 import { quietLogs } from "./helpers/globals.ts";
21
22 quietLogs();
23
24 const FEATURE = {
25 name: "Radar",
26 settings: {
27 runDays: { type: "days", default: ["mon", "thu"] },
28 runHourUtc: { type: "int", default: 13, min: 0, max: 23 },
29 other: { type: "string" },
30 },
31 schedule: { path: "/run", hour: "runHourUtc", days: "runDays" },
32 };
33 // 2026-11-09 is a Monday; 2026-11-10 a Tuesday.
34 const MON_13 = Date.UTC(2026, 10, 9, 13, 5);
35 const MON_14 = Date.UTC(2026, 10, 9, 14, 5);
36 const TUE_13 = Date.UTC(2026, 10, 10, 13, 5);
37
38 describe("the declaration", () => {
39 test("a schedule names an hour setting and optional days setting", () => {
40 const r = parseFeature({ feature: FEATURE });
41 if (!r.ok) throw new Error(r.error);
42 expect(r.value?.schedule).toEqual({ path: "/run", hour: "runHourUtc", days: "runDays" });
43 });
44 test("a wrong one is refused with the field named", () => {
45 const wrong = (schedule: unknown) => {
46 const r = parseFeature({ feature: { ...FEATURE, schedule } });
47 return r.ok ? "ok" : r.error;
48 };
49 expect(wrong({ path: "https://evil.example/", hour: "runHourUtc" })).toContain("path");
50 expect(wrong({ path: "//evil", hour: "runHourUtc" })).toContain("path");
51 expect(wrong({ path: "/run", hour: "nope" })).toContain("hour");
52 expect(wrong({ path: "/run", hour: "other" })).toContain("hour");
53 expect(wrong({ path: "/run", hour: "runHourUtc", days: "runHourUtc" })).toContain("days");
54 expect(wrong({ path: "/run", hour: "runHourUtc", x: 1 })).toContain("unknown field x");
55 expect(wrong("daily")).toContain("must be an object");
56 });
57 });
58
59 describe("when it is due", () => {
60 const schedule = { path: "/run", hour: "runHourUtc", days: "runDays" };
61 const env = { FORGE_SETTING_RUN_HOUR_UTC: "13", FORGE_SETTING_RUN_DAYS: "mon,thu" };
62 test("in its hour on its days", () => {
63 expect(slotDue(schedule, env, MON_13)).toBe("2026-11-09T13");
64 expect(slotDue(schedule, env, MON_14)).toBeUndefined();
65 expect(slotDue(schedule, env, TUE_13)).toBeUndefined();
66 });
67 test("without days, every day", () => {
68 expect(slotDue({ path: "/run", hour: "runHourUtc" }, env, TUE_13)).toBe("2026-11-10T13");
69 });
70 test("Sunday is Sunday", () => {
71 const sun = Date.UTC(2026, 10, 15, 13, 0);
72 expect(slotDue(schedule, { ...env, FORGE_SETTING_RUN_DAYS: "sun" }, sun)).toBe("2026-11-15T13");
73 });
74 });
75
76 describe("knocking", () => {
77 let dir: string;
78 let app: App;
79 let live: string;
80 let appId = "";
81 let admin: User;
82 const calls: { url: string; headers: Record<string, string> }[] = [];
83 const fire = async (url: string, headers: Record<string, string>) => {
84 calls.push({ url, headers });
85 return 204;
86 };
87 const runtime = { liveFor: () => ({ dir: live, port: 4321, commitOid: "c1" }) } as never;
88
89 beforeAll(async () => {
90 dir = await mkdtemp(join(tmpdir(), "forge-schedule-"));
91 live = join(dir, "checkout");
92 await Bun.write(join(live, "forge.json"), JSON.stringify({ app: { run: "x" }, feature: FEATURE }));
93 app = createApp({ dataDir: dir, port: 0, host: "forge.test" });
94 const user = await createUser(app.db, {
95 origin: "seed", trusted: true, username: "cy", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true,
96 });
97 if (!user.ok) throw new Error(user.error);
98 const repo = await createRepo(app, user.value, { name: "radar", visibility: "private", description: "" });
99 if (!repo.ok) throw new Error(String(repo.error));
100 const committed = await commitToBranch(app, user.value, repo.value, {
101 message: "Radar has a schedule",
102 files: [{ path: "forge.json", content: JSON.stringify({ app: { run: "x" }, feature: FEATURE }) }],
103 });
104 if (!committed.ok) throw new Error(JSON.stringify(committed.error));
105 const made = insertApp(app.db, { repoId: repo.value.id, slug: "radar", access: "private" });
106 if (!made.ok) throw new Error(made.error);
107 admin = user.value;
108 appId = made.value.id;
109 }, 60_000);
110 afterAll(async () => {
111 await rm(dir, { recursive: true, force: true });
112 });
113 const id = () => appId;
114
115 test("an app that is not absorbed is not knocked on", async () => {
116 expect(await fireDue(app, MON_13, fire, runtime)).toEqual([]);
117 expect(calls).toHaveLength(0);
118 });
119
120 test("an absorbed one is, once in its hour, signed as the forge", async () => {
121 absorb(app.db, id(), "admin", "Radar", "/");
122 expect(await fireDue(app, MON_14, fire, runtime)).toEqual([]);
123 expect(await fireDue(app, MON_13, fire, runtime)).toEqual(["radar"]);
124 expect(await fireDue(app, MON_13 + 60_000, fire, runtime)).toEqual([]);
125 expect(calls).toHaveLength(1);
126 expect(calls[0]?.url).toBe("http://127.0.0.1:4321/run");
127 const h = calls[0]?.headers ?? {};
128 expect(h["x-forge-schedule"]).toBe("2026-11-09T13");
129 expect(h["x-forge-identity"]?.split("|")[2]).toBe("schedule");
130 // The proxy's own verifier accepts it as the forge, for this app only.
131 const who = verifyIdentity(dir, id(), h["x-forge-identity"] ?? null, h["x-forge-signature"] ?? null, MON_13);
132 expect(who).toEqual({ id: "forge", name: "forge", role: "schedule" });
133 expect(verifyIdentity(dir, "another-app", h["x-forge-identity"] ?? null, h["x-forge-signature"] ?? null, MON_13)).toBeUndefined();
134 expect(verifyIdentity(dir, id(), h["x-forge-identity"] ?? null, "forged", MON_13)).toBeUndefined();
135 expect(verifyIdentity(dir, id(), h["x-forge-identity"] ?? null, h["x-forge-signature"] ?? null, MON_13 + 120_000)).toBeUndefined();
136 expect(app.db.query("SELECT status FROM app_feature_fire").get()).toEqual({ status: 204 });
137 });
138
139 test("the next slot knocks again; a moved hour follows the setting", async () => {
140 const nextWeek = MON_13 + 7 * 86_400_000;
141 expect(await fireDue(app, nextWeek, fire, runtime)).toEqual(["radar"]);
142 setFeatureSettings(app.db, id(), new Map([["runHourUtc", "14"]]), "admin");
143 expect(await fireDue(app, nextWeek + 3_600_000, fire, runtime)).toEqual(["radar"]);
144 });
145
146 test("an un-absorbed app is left alone, and a refused knock is not a crash", async () => {
147 unabsorb(app.db, id());
148 const before = calls.length;
149 expect(await fireDue(app, MON_14 + 14 * 86_400_000, fire, runtime)).toEqual([]);
150 expect(calls).toHaveLength(before);
151 absorb(app.db, id(), "admin", "Radar", "/");
152 const boom = async () => {
153 throw new Error("refused");
154 };
155 expect(await fireDue(app, MON_14 + 21 * 86_400_000, boom, runtime)).toEqual(["radar"]);
156 // A failed knock is told from one still in flight, and is not retried that hour.
157 expect(app.db.query("SELECT status FROM app_feature_fire").get()).toEqual({ status: -1 });
158 expect(await fireDue(app, MON_14 + 21 * 86_400_000 + 60_000, fire, runtime)).toEqual([]);
159 });
160
161 test("an hour outside 0-23 is refused as a setting, and the declared default stands", async () => {
162 const before = calls.length;
163 app.db.query("INSERT OR REPLACE INTO app_feature_setting (app_id, key, value, set_by) VALUES (?1, 'runHourUtc', '99', 'x')").run(id());
164 const day = Date.UTC(2026, 10, 30, 99 % 24, 0); // a Monday, at the hour 99 would wrap to
165 expect(await fireDue(app, day, fire, runtime)).toEqual([]);
166 expect(await fireDue(app, Date.UTC(2026, 10, 30, 13, 0), fire, runtime)).toEqual(["radar"]);
167 expect(calls).toHaveLength(before + 1);
168 });
169
170 test("a malformed forge.json is skipped, not a crash", async () => {
171 const other = join(dir, "broken");
172 await Bun.write(join(other, "forge.json"), "{ not json");
173 const broken = { liveFor: () => ({ dir: other, port: 1, commitOid: "broken" }) } as never;
174 const before = calls.length;
175 expect(await fireDue(app, Date.UTC(2026, 11, 7, 13, 0), fire, broken)).toEqual([]);
176 expect(calls).toHaveLength(before);
177 });
178
179 test("the settings page's view says what was fired, and what has not been", async () => {
180 const view = await getFeature(app, admin, "radar");
181 if (!view.ok) throw new Error(view.error);
182 expect(view.value.schedule).toContain("POST /run");
183 expect(view.value.schedule).toContain("last 2026-11-30 13:00 UTC, answered 204");
184 });
185
186 test("a real knock reaches a listening app with the headers", async () => {
187 const seen: Headers[] = [];
188 const server = Bun.serve({ port: 0, fetch: (r) => (seen.push(r.headers), new Response(null, { status: r.method === "POST" ? 202 : 405 })) });
189 try {
190 const real = { liveFor: () => ({ dir: live, port: server.port, commitOid: "real" }) } as never;
191 app.db.query("DELETE FROM app_feature_setting").run();
192 expect(await fireDue(app, Date.UTC(2027, 0, 4, 13, 0), undefined, real)).toEqual(["radar"]);
193 expect(seen).toHaveLength(1);
194 expect(verifyIdentity(dir, id(), seen[0]?.get("x-forge-identity") ?? null, seen[0]?.get("x-forge-signature") ?? null, Date.UTC(2027, 0, 4, 13, 0))?.role).toBe("schedule");
195 expect(app.db.query("SELECT status FROM app_feature_fire").get()).toEqual({ status: 202 });
196 } finally {
197 server.stop(true);
198 }
199 });
200
201 test("the timer is wired: it fires on its tick, and a preview starts none", async () => {
202 const hits: string[] = [];
203 app.db.query("DELETE FROM app_feature_fire").run();
204 const at = Date.UTC(2027, 0, 5, 13, 0); // a fixed clock: the real hour may turn mid-test
205 app.db.query("INSERT OR REPLACE INTO app_feature_setting (app_id, key, value, set_by) VALUES (?1, 'runHourUtc', '13', 'x')").run(id());
206 app.db.query("INSERT OR REPLACE INTO app_feature_setting (app_id, key, value, set_by) VALUES (?1, 'runDays', 'mon,tue,wed,thu,fri,sat,sun', 'x')").run(id());
207 let tick: (() => Promise<void>) | undefined;
208 const stop = startFeatureSchedule(app, {
209 fire: async (u) => (hits.push(u), 200),
210 now: () => at,
211 runtime,
212 env: {},
213 every: (run, ms) => ((tick = run), expect(ms).toBe(SCHEDULE_TICK_MS), () => undefined),
214 });
215 await tick?.();
216 stop?.();
217 expect(hits).toEqual(["http://127.0.0.1:4321/run"]);
218 expect(startFeatureSchedule(app, { runtime, env: { FORGE_APP_ENV: "preview" } })).toBeUndefined();
219 expect(startFeatureSchedule(app, { runtime, env: {} })?.call(null)).toBeUndefined();
220 });
221
222 test("the headers expire within a minute", () => {
223 const h = fireHeaders(dir, id(), "s", 1000);
224 expect(h["x-forge-identity"]?.endsWith("|61000")).toBe(true);
225 });
226 });
test/features-tui.test.ts +13 −1
@@ -24,7 +24,7 @@ quietLogs();
2424
2525 const FORGE_JSON = JSON.stringify({
2626 app: { run: "bun run src/server.ts" },
27 feature: { name: "Radar", page: "/", settings: { runHourUtc: { type: "int", default: 13, min: 0, max: 23, label: "Hour (UTC)" }, apiToken: { type: "secret", label: "API token" } } },
27 feature: { name: "Radar", page: "/", settings: { runHourUtc: { type: "int", default: 13, min: 0, max: 23, label: "Hour (UTC)" }, apiToken: { type: "secret", label: "API token" } }, schedule: { path: "/run", hour: "runHourUtc" } },
2828 });
2929
3030 describe("features in the terminal", () => {
@@ -116,6 +116,18 @@ describe("features in the terminal", () => {
116116 t.stop();
117117 });
118118
119 test("an absorbed app's settings screen says its schedule, as the page does", async () => {
120 const t = boot(ada);
121 await t.palette();
122 await t.press("enter");
123 await t.press("a");
124 await t.press("enter");
125 expect(t.text()).toContain("Schedule: POST /run at the hour in runHourUtc, daily; not fired yet");
126 await t.press("esc");
127 await t.press("a");
128 t.stop();
129 });
130
119131 test("a secret is masked, shown as kept, and a blank submit leaves it", async () => {
120132 const t = boot(ada);
121133 await t.palette();

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs