Public: anyone can read this; the crew can change it.
Absorb: fire a feature's schedule #9916
scout/forge:scout/9883-absorb-fire-a-feature-s-schedule → main 15 commits fork 2 threads · 2 unresolved
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 | ||
| 57 | 57 | |
| 58 | 58 | ## Without the crew |
| 59 | 59 | |
| 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. | |
| 61 | 61 | |
| 62 | 62 | ## Settings are not secrets, except `secret` |
| 63 | 63 | |
| @@ -69,6 +69,22 @@ Other settings are stored as plain values. Anyone who can read the app's reposit | ||
| 69 | 69 | |
| 70 | 70 | See `docs/features/absorb-review.md` for the findings of #9441. |
| 71 | 71 | |
| 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 | ||
| 72 | 88 | ## Code and tests |
| 73 | 89 | |
| 74 | 90 | - 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` | ||
| 80 | 96 | |
| 81 | 97 | 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. |
| 82 | 98 | |
| 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 | ||
| 87 | 99 | ## MCP tools |
| 88 | 100 | |
| 89 | 101 | 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 { | ||
| 30 | 30 | keepDeclaration, |
| 31 | 31 | featureSettings, |
| 32 | 32 | getAbsorbed, |
| 33 | lastFire, | |
| 34 | fireSays, | |
| 35 | type Fired, | |
| 33 | 36 | listAbsorbed, |
| 34 | 37 | setFeatureSettings as keepSettings, |
| 35 | 38 | unabsorb, |
| @@ -90,6 +93,8 @@ export interface FeatureView { | ||
| 90 | 93 | readonly tools: readonly ToolSpec[]; |
| 91 | 94 | /** Where the app comes from: the upstream only when the reader may read it. */ |
| 92 | 95 | readonly provenance: Provenance; |
| 96 | /** The declared schedule and its last knock, in words; null when the app declares none. */ | |
| 97 | readonly schedule: string | null; | |
| 93 | 98 | } |
| 94 | 99 | |
| 95 | 100 | /** |
| @@ -209,6 +214,14 @@ export async function declaresFeature(app: App, actor: User | undefined, repo: R | ||
| 209 | 214 | return read.ok && read.value !== undefined; |
| 210 | 215 | } |
| 211 | 216 | |
| 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 | ||
| 212 | 225 | function viewOf( |
| 213 | 226 | record: AppRecord, |
| 214 | 227 | repo: Repo, |
| @@ -237,6 +250,7 @@ function viewOf( | ||
| 237 | 250 | absorbedAt: absorbed?.absorbedAt ?? null, |
| 238 | 251 | problem, |
| 239 | 252 | provenance, |
| 253 | schedule: scheduleSays(spec, absorbed !== undefined, lastFire(app.db, record.id)), | |
| 240 | 254 | tools: spec?.tools ?? [], |
| 241 | 255 | settings: (spec?.settings ?? []).map((s) => { |
| 242 | 256 | 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 +37 −2
| @@ -320,7 +320,7 @@ export function identityKey(dataDir: string, appId: string): string { | ||
| 320 | 320 | * dropped before the forge speaks, so a verified signature is the only |
| 321 | 321 | * thing an app has to trust. |
| 322 | 322 | */ |
| 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"]; | |
| 324 | 324 | |
| 325 | 325 | export function identityHeaders( |
| 326 | 326 | dataDir: string, |
| @@ -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 +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 | ||
| 68 | 68 | })(); |
| 69 | 69 | } |
| 70 | 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 | /** 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 | ||
| 71 | 114 | /** Forget these kept settings (a cleared secret): the row goes, so it reads as not set. */ |
| 72 | 115 | export function clearFeatureSettings(db: Database, appId: string, keys: readonly string[]): void { |
| 73 | 116 | 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"; | ||
| 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/tui/screens/featureswitch.ts +12 −1
| @@ -18,6 +18,9 @@ import { | ||
| 18 | 18 | import type { Ctx, Screen } from "../app/app.ts"; |
| 19 | 19 | import { binding } from "../app/keys.ts"; |
| 20 | 20 | 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"; | |
| 21 | 24 | import { ListState, drawList, promptScreen, runAsync, type ListRow } from "./common.ts"; |
| 22 | 25 | import type { PaletteEntry } from "./entries.ts"; |
| 23 | 26 | |
| @@ -56,7 +59,15 @@ function settingsScreen(f: Session, ctx: Ctx, slug: string): Screen { | ||
| 56 | 59 | keys: [binding(["j", "k"], "move cursor"), binding(["enter"], "change")], |
| 57 | 60 | load: reload, |
| 58 | 61 | 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)); | |
| 60 | 71 | }, |
| 61 | 72 | key(e) { |
| 62 | 73 | const settings = view?.settings ?? []; |
src/web/pages/features.ts +6 −2
| @@ -56,7 +56,11 @@ export function switchNote(f: Pick<FeatureView, "name" | "absorbed">): string { | ||
| 56 | 56 | |
| 57 | 57 | /** Where the app comes from, on a feature's own page: `dl` rows, the upstream when a fork and who last changed it. */ |
| 58 | 58 | 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 }[]) { | |
| 60 | 64 | if (facts.length === 0) return null; |
| 61 | 65 | return html`<dl class="status-rows">${facts.map((f) => html`<div class="status-row"><dt>${f.label}</dt><dd>${f.value}</dd></div>`)}</dl>`; |
| 62 | 66 | } |
| @@ -199,7 +203,7 @@ function featureView(ctx: Ctx, f: FeatureView, refused?: Refused, items: readonl | ||
| 199 | 203 | <h2>${f.name}</h2> |
| 200 | 204 | ${f.absorbed ? badge("absorbed", { tone: "success" }) : badge("not absorbed", { variant: "outline" })} |
| 201 | 205 | </div> |
| 202 | ${provenanceRows(f.provenance)} | |
| 206 | ${factRows([...provenanceFacts(f.provenance), ...(f.schedule === null ? [] : [{ label: "Schedule", value: f.schedule }])])} | |
| 203 | 207 | ${f.settings.length === 0 |
| 204 | 208 | ? html`<p class="muted small">${f.problem ?? "This feature declares no settings."}</p>` |
| 205 | 209 | : 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", () => { | ||
| 101 | 101 | fetch(request) { |
| 102 | 102 | return Response.json({ |
| 103 | 103 | identity: request.headers.get("x-forge-identity"), |
| 104 | schedule: request.headers.get("x-forge-schedule"), | |
| 104 | 105 | signature: request.headers.get("x-forge-signature"), |
| 105 | 106 | key: process.env.FORGE_APP_IDENTITY_KEY ?? "", |
| 106 | 107 | }); |
| @@ -135,9 +136,11 @@ describe("apps: identity, and a deploy that never answers", () => { | ||
| 135 | 136 | // A client's own claim never reaches the app. |
| 136 | 137 | "x-forge-identity": "evil|mallory|admin|9999999999999", |
| 137 | 138 | "x-forge-signature": "AAAA", |
| 139 | "x-forge-schedule": "2026-11-09T13", | |
| 138 | 140 | }, |
| 139 | 141 | }) |
| 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 | |
| 141 | 144 | expect(heard.key).toBe(identityKey(dataDir, record.id)); |
| 142 | 145 | const [id, name, role, expires] = heard.identity.split("|"); |
| 143 | 146 | expect(id).toBe(alice.id); |
test/build-cart.test.ts +6 −1
| @@ -77,7 +77,12 @@ describe("a pin's cart", () => { | ||
| 77 | 77 | expect(res.status).toBe(202); |
| 78 | 78 | expect(await res.json()).toMatchObject({ demo: { name: "fiesta-kart", version: "1", launch: "file", page: "/", showcase: true } }); |
| 79 | 79 | // 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 | } | |
| 81 | 86 | expect(await (await api("karts/builds/v1/cart")).json()).toMatchObject({ capture: { state: "failed", error: "not_an_app" } }); |
| 82 | 87 | }); |
| 83 | 88 |
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(); | ||
| 24 | 24 | |
| 25 | 25 | const FORGE_JSON = JSON.stringify({ |
| 26 | 26 | 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" } }, | |
| 28 | 28 | }); |
| 29 | 29 | |
| 30 | 30 | describe("features in the terminal", () => { |
| @@ -116,6 +116,18 @@ describe("features in the terminal", () => { | ||
| 116 | 116 | t.stop(); |
| 117 | 117 | }); |
| 118 | 118 | |
| 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 | ||
| 119 | 131 | test("a secret is masked, shown as kept, and a blank submit leaves it", async () => { |
| 120 | 132 | const t = boot(ada); |
| 121 | 133 | await t.palette(); |
new above
offline
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
dlrow beside the other facts (principle 7) rather than a loose paragraph. The same facts should reachsrc/tui/.