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

Absorb: fire a feature's schedule #9892

Parked opened this
Closed without merging

scout/forge:scout/9883-absorb-fire-a-feature-s-schedule → main 6 commits fork 1 thread · 1 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
12 files changed +513 −5
docs/features/absorb.md +18 −2
@@ -53,7 +53,7 @@ The forge reads the declaration from the commit it starts. A preview of a pull t
5353
5454 ## Without the crew
5555
56 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.
56 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.
5757
5858 ## Settings are not secrets
5959
@@ -63,6 +63,22 @@ Settings are stored as plain values. Anyone who can read the app's repository ca
6363
6464 See `docs/features/absorb-review.md` for the findings of #9441.
6565
66 ## A schedule the forge fires
67
68 A feature may declare when the forge should knock:
69
70 ```json
71 "schedule": { "path": "/run", "hour": "runHourUtc", "days": "runDays" }
72 ```
73
74 `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.
75
76 **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.
77
78 **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.
79
80 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. `x-forge-schedule` holds the slot (`2026-11-09T13`). An hour the forge was down for is not made up, and a preview's forge does not knock. Code: `src/apps/schedule.ts`; test: `test/feature-schedule.test.ts`.
81
6682 ## Code and tests
6783
6884 - 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`.
@@ -76,7 +92,7 @@ Settings stay behind on a fork. A fork of another forge's app carries its `featu
7692
7793 ## Not done yet
7894
79 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), show its feed items (#9884), keep `secret` settings (#9886) or show its health on `/system` (#9887).
95 Until then an absorbed app is a menu link with kept settings (Settings › Features says so). The forge does not yet show its feed items (#9884), keep `secret` settings (#9886) or show its health on `/system` (#9887).
8096
8197 ## MCP tools
8298
src/actions/features.ts +14
@@ -28,6 +28,9 @@ import {
2828 keepDeclaration,
2929 featureSettings,
3030 getAbsorbed,
31 lastFire,
32 fireSays,
33 type Fired,
3134 listAbsorbed,
3235 setFeatureSettings as keepSettings,
3336 unabsorb,
@@ -86,6 +89,8 @@ export interface FeatureView {
8689 readonly tools: readonly ToolSpec[];
8790 /** Where the app comes from: the upstream only when the reader may read it. */
8891 readonly provenance: Provenance;
92 /** The declared schedule and its last knock, in words; null when the app declares none. */
93 readonly schedule: string | null;
8994 }
9095
9196 /**
@@ -205,6 +210,14 @@ export async function declaresFeature(app: App, actor: User | undefined, repo: R
205210 return read.ok && read.value !== undefined;
206211 }
207212
213 function scheduleSays(spec: FeatureSpec | undefined, absorbed: boolean, fired: Fired | undefined): string | null {
214 if (spec?.schedule === undefined) return null;
215 const at = `${spec.schedule.hour}${spec.schedule.days === undefined ? ", daily" : ` on ${spec.schedule.days}`}`;
216 const base = `The forge sends POST ${spec.schedule.path} in the hour set by ${at}.`;
217 if (!absorbed) return `${base} It starts once the app is absorbed.`;
218 return fired === undefined ? `${base} It has not fired yet.` : `${base} ${fireSays(fired)}`;
219 }
220
208221 function viewOf(
209222 record: AppRecord,
210223 repo: Repo,
@@ -233,6 +246,7 @@ function viewOf(
233246 absorbedAt: absorbed?.absorbedAt ?? null,
234247 problem,
235248 provenance,
249 schedule: scheduleSays(spec, absorbed !== undefined, lastFire(app.db, record.id)),
236250 tools: spec?.tools ?? [],
237251 settings: (spec?.settings ?? []).map((s) => {
238252 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 +36 −1
@@ -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 +126
@@ -0,0 +1,126 @@
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 runtime?: Pick<AppsRuntime, "liveFor">;
117 readonly env?: Record<string, string | undefined>;
118 } = {},
119 ): (() => void) | undefined {
120 const runtime = options.runtime ?? appsRuntime(app);
121 if (runtime === undefined || crewOffInPreview(options.env)) return undefined;
122 const timer = setInterval(() => {
123 fireDue(app, Date.now(), options.fire, runtime).catch((error) => log.warn("feature schedule failed", { error: String(error) }));
124 }, options.tickMs ?? SCHEDULE_TICK_MS);
125 return () => clearInterval(timer);
126 }
src/core/features.ts +43
@@ -67,3 +67,46 @@ export function setFeatureSettings(db: Database, appId: string, values: Readonly
6767 for (const [key, value] of values) put.run(appId, key, value, by);
6868 })();
6969 }
70
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 /** A sentence for a knock: what a person reads on the settings page. */
109 export function fireSays(f: Fired): string {
110 const how = f.status === FIRE_PENDING ? "no answer recorded (the forge may have stopped mid-call)" : f.status === FIRE_FAILED ? "failed: the app did not answer" : `answered ${f.status}`;
111 return `Last fired for ${f.slot.replace("T", " ")}:00 UTC, ${how}. A failed or unanswered hour is not retried.`;
112 }
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;
outdated

This splits the nightly comment from const nightly. Move the schedule block after it.

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/web/pages/features.ts +1
@@ -194,6 +194,7 @@ function featureView(ctx: Ctx, f: FeatureView, refused?: Refused): Response {
194194 ${f.absorbed ? badge("absorbed", { tone: "success" }) : badge("not absorbed", { variant: "outline" })}
195195 </div>
196196 ${provenanceRows(f.provenance)}
197 ${when(f.schedule !== null, () => html`<p class="muted small">${f.schedule}</p>`)}
197198 ${f.settings.length === 0
198199 ? html`<p class="muted small">${f.problem ?? "This feature declares no settings."}</p>`
199200 : html`<form method="post" action="${base}">
test/crew-week.test.ts +1
@@ -123,6 +123,7 @@ test("home says the whole crew's number", () => {
123123 });
124124
125125 test("a repository that hit its ceiling yesterday restarts at its own time, spread over the morning", () => {
126 forgetStagger();
126127 const midnight = new Date(Date.UTC(2026, 10, 3, 0, 5, 0));
127128 for (const r of repos) {
128129 const run = createRun(app.db, { repoId: r.id, kind: "agent" });
test/feature-schedule.test.ts added +223
@@ -0,0 +1,223 @@
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 { 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 fired for 2026-11-30 13:00 UTC, answered 204");
184 expect(view.value.schedule).toContain("not retried");
185 });
186
187 test("a real knock reaches a listening app with the headers", async () => {
188 const seen: Headers[] = [];
189 const server = Bun.serve({ port: 0, fetch: (r) => (seen.push(r.headers), new Response(null, { status: r.method === "POST" ? 202 : 405 })) });
190 try {
191 const real = { liveFor: () => ({ dir: live, port: server.port, commitOid: "real" }) } as never;
192 app.db.query("DELETE FROM app_feature_setting").run();
193 expect(await fireDue(app, Date.UTC(2027, 0, 4, 13, 0), undefined, real)).toEqual(["radar"]);
194 expect(seen).toHaveLength(1);
195 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");
196 expect(app.db.query("SELECT status FROM app_feature_fire").get()).toEqual({ status: 202 });
197 } finally {
198 server.stop(true);
199 }
200 });
201
202 test("the timer is wired: it fires on its tick, and a preview starts none", async () => {
203 const hits: string[] = [];
204 app.db.query("DELETE FROM app_feature_fire").run();
205 const now = new Date();
206 app.db.query("INSERT OR REPLACE INTO app_feature_setting (app_id, key, value, set_by) VALUES (?1, 'runHourUtc', ?2, 'x')").run(id(), String(now.getUTCHours()));
207 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());
208 const stop = startFeatureSchedule(app, { fire: async (u) => (hits.push(u), 200), tickMs: 10, runtime });
209 try {
210 for (let i = 0; i < 400 && hits.length === 0; i++) await Bun.sleep(25);
211 } finally {
212 stop?.();
213 }
214 expect(hits).toEqual(["http://127.0.0.1:4321/run"]);
215 expect(startFeatureSchedule(app, { runtime, env: { FORGE_APP_ENV: "preview" } })).toBeUndefined();
216 expect(startFeatureSchedule(app, { runtime, env: {} })?.call(null)).toBeUndefined();
217 });
218
219 test("the headers expire within a minute", () => {
220 const h = fireHeaders(dir, id(), "s", 1000);
221 expect(h["x-forge-identity"]?.endsWith("|61000")).toBe(true);
222 });
223 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs