Public: anyone can read this; the crew can change it.
Absorb: fire a feature's schedule #9892
scout/forge:scout/9883-absorb-fire-a-feature-s-schedule → main 6 commits fork 1 thread · 1 unresolved
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 | ||
| 53 | 53 | |
| 54 | 54 | ## Without the crew |
| 55 | 55 | |
| 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. | |
| 57 | 57 | |
| 58 | 58 | ## Settings are not secrets |
| 59 | 59 | |
| @@ -63,6 +63,22 @@ Settings are stored as plain values. Anyone who can read the app's repository ca | ||
| 63 | 63 | |
| 64 | 64 | See `docs/features/absorb-review.md` for the findings of #9441. |
| 65 | 65 | |
| 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 | ||
| 66 | 82 | ## Code and tests |
| 67 | 83 | |
| 68 | 84 | - 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 | ||
| 76 | 92 | |
| 77 | 93 | ## Not done yet |
| 78 | 94 | |
| 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). | |
| 80 | 96 | |
| 81 | 97 | ## MCP tools |
| 82 | 98 |
src/actions/features.ts +14
| @@ -28,6 +28,9 @@ import { | ||
| 28 | 28 | keepDeclaration, |
| 29 | 29 | featureSettings, |
| 30 | 30 | getAbsorbed, |
| 31 | lastFire, | |
| 32 | fireSays, | |
| 33 | type Fired, | |
| 31 | 34 | listAbsorbed, |
| 32 | 35 | setFeatureSettings as keepSettings, |
| 33 | 36 | unabsorb, |
| @@ -86,6 +89,8 @@ export interface FeatureView { | ||
| 86 | 89 | readonly tools: readonly ToolSpec[]; |
| 87 | 90 | /** Where the app comes from: the upstream only when the reader may read it. */ |
| 88 | 91 | readonly provenance: Provenance; |
| 92 | /** The declared schedule and its last knock, in words; null when the app declares none. */ | |
| 93 | readonly schedule: string | null; | |
| 89 | 94 | } |
| 90 | 95 | |
| 91 | 96 | /** |
| @@ -205,6 +210,14 @@ export async function declaresFeature(app: App, actor: User | undefined, repo: R | ||
| 205 | 210 | return read.ok && read.value !== undefined; |
| 206 | 211 | } |
| 207 | 212 | |
| 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 | ||
| 208 | 221 | function viewOf( |
| 209 | 222 | record: AppRecord, |
| 210 | 223 | repo: Repo, |
| @@ -233,6 +246,7 @@ function viewOf( | ||
| 233 | 246 | absorbedAt: absorbed?.absorbedAt ?? null, |
| 234 | 247 | problem, |
| 235 | 248 | provenance, |
| 249 | schedule: scheduleSays(spec, absorbed !== undefined, lastFire(app.db, record.id)), | |
| 236 | 250 | tools: spec?.tools ?? [], |
| 237 | 251 | settings: (spec?.settings ?? []).map((s) => { |
| 238 | 252 | const name = settingEnvName(s.key); |
src/apps/feature.ts +36 −2
| @@ -66,10 +66,25 @@ export interface FeatureSpec { | ||
| 66 | 66 | /** The app path the forge's nav opens. */ |
| 67 | 67 | readonly page: string; |
| 68 | 68 | readonly settings: readonly SettingSpec[]; |
| 69 | /** When the forge knocks on the app: see `FeatureSchedule`. */ | |
| 70 | readonly schedule?: FeatureSchedule | undefined; | |
| 69 | 71 | /** MCP tools the app serves through the forge's `features` tool (`feature_tools.ts`). */ |
| 70 | 72 | readonly tools: readonly ToolSpec[]; |
| 71 | 73 | } |
| 72 | 74 | |
| 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 | ||
| 73 | 88 | const KEY = /^[a-z][a-zA-Z0-9]{0,39}$/; |
| 74 | 89 | const CHOICE = /^[a-z0-9][a-z0-9._-]{0,39}$/; |
| 75 | 90 | const NAME_MAX = 40; |
| @@ -116,11 +131,30 @@ export function parseFeature(forgeJson: Raw): Result<FeatureSpec | undefined, st | ||
| 116 | 131 | } |
| 117 | 132 | const envs = new Set(settings.map((s) => settingEnvName(s.key))); |
| 118 | 133 | 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; | |
| 119 | 136 | 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}`); | |
| 121 | 138 | const tools = parseTools(block["tools"]); |
| 122 | 139 | 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 }) }); | |
| 124 | 158 | } |
| 125 | 159 | |
| 126 | 160 | function parseSetting(key: string, raw: unknown): Result<SettingSpec, string> { |
src/apps/proxy.ts +36 −1
| @@ -328,13 +328,48 @@ export function identityHeaders( | ||
| 328 | 328 | grant: Grant | undefined, |
| 329 | 329 | ): Record<string, string> { |
| 330 | 330 | 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}`; | |
| 332 | 344 | const signature = createHmac("sha256", identityKey(dataDir, appId)) |
| 333 | 345 | .update(identity) |
| 334 | 346 | .digest("base64url"); |
| 335 | 347 | return { "x-forge-identity": identity, "x-forge-signature": signature }; |
| 336 | 348 | } |
| 337 | 349 | |
| 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 | ||
| 338 | 373 | /** The URL the forge redirects a vouched-for visitor to. */ |
| 339 | 374 | export function grantUrl( |
| 340 | 375 | 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 | ||
| 67 | 67 | for (const [key, value] of values) put.run(appId, key, value, by); |
| 68 | 68 | })(); |
| 69 | 69 | } |
| 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"; | ||
| 56 | 56 | import { startMirrorPulls } from "./origins/mirror-pulls.ts"; |
| 57 | 57 | import { startProbes } from "./contract/probes.ts"; |
| 58 | 58 | import { startNightly } from "./nightly/service.ts"; |
| 59 | import { startFeatureSchedule } from "./apps/schedule.ts"; | |
| 59 | 60 | import { startSnapshots } from "./snapshot/service.ts"; |
| 60 | 61 | import { resolveDestination } from "./snapshot/destination.ts"; |
| 61 | 62 | import { resolveMirror } from "./snapshot/mirror.ts"; |
| @@ -484,6 +485,8 @@ const probes = apps === undefined ? undefined : startProbes(app, apps); | ||
| 484 | 485 | // of what the gate excludes, filing the same `Flaky:` and `Red:` issues and |
| 485 | 486 | // the quarantine pull (docs/DEVELOP.md). |
| 486 | 487 | 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); | |
| 487 | 490 | // The snapshot: everything that cannot be rebuilt, nightly, to what an |
| 488 | 491 | // operator sealed on the Backups page, else the platform's (`S3_*`) or a |
| 489 | 492 | // directory (`FORGE_SNAPSHOT_DIR`). A forge given none says so on that page. |
| @@ -874,6 +877,7 @@ function drain(signal: NodeJS.Signals): Promise<unknown> { | ||
| 874 | 877 | drainStreams(); |
| 875 | 878 | clearInterval(deliveryTimer); |
| 876 | 879 | clearInterval(nightlyScanTimer); |
| 880 | featureSchedule?.(); | |
| 877 | 881 | clearInterval(heartbeatTimer); |
| 878 | 882 | clearInterval(upstreamTimer); |
| 879 | 883 | clearInterval(reachTimer); |
src/web/pages/features.ts +1
| @@ -194,6 +194,7 @@ function featureView(ctx: Ctx, f: FeatureView, refused?: Refused): Response { | ||
| 194 | 194 | ${f.absorbed ? badge("absorbed", { tone: "success" }) : badge("not absorbed", { variant: "outline" })} |
| 195 | 195 | </div> |
| 196 | 196 | ${provenanceRows(f.provenance)} |
| 197 | ${when(f.schedule !== null, () => html`<p class="muted small">${f.schedule}</p>`)} | |
| 197 | 198 | ${f.settings.length === 0 |
| 198 | 199 | ? html`<p class="muted small">${f.problem ?? "This feature declares no settings."}</p>` |
| 199 | 200 | : html`<form method="post" action="${base}"> |
test/crew-week.test.ts +1
| @@ -123,6 +123,7 @@ test("home says the whole crew's number", () => { | ||
| 123 | 123 | }); |
| 124 | 124 | |
| 125 | 125 | test("a repository that hit its ceiling yesterday restarts at its own time, spread over the morning", () => { |
| 126 | forgetStagger(); | |
| 126 | 127 | const midnight = new Date(Date.UTC(2026, 10, 3, 0, 5, 0)); |
| 127 | 128 | for (const r of repos) { |
| 128 | 129 | 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 | }); |
new above
offline
This splits the nightly comment from
const nightly. Move the schedule block after it.