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

A pull's preview starts asleep: the first request builds and starts it #13790

Merged opened this

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

Merged

trevato/previews-start-asleep → main 7 commits 3 threads · 3 unresolved

  • Merged. trevato/previews-start-asleep was merged into main as 8636138.

Review

Sign in to review this change.
17 files changed +407 −54
docs/APPS.md +25 −5
@@ -48,7 +48,9 @@ Under the box, four starter sentences are plain links (no script):
4848 branch moving, and an agent cannot move it: the crew proposes through
4949 pulls, a person merges.
5050 - **Every open pull gets a preview** at `<name>--<pull number>.<host>`,
51 redeployed on each push and gone when the pull closes. Its data starts as
51 following each push and gone when the pull closes. It costs nothing until
52 it is asked for: after a push it is asleep at the new head, and the first
53 request builds and starts it (rule 2 below). Its data starts as
5254 a copy of production's — copy-on-write where the filesystem can — and
5355 never writes back. Merging moves code and touches no data.
5456 - **A webhook has a stable address.** `POST /__forge/hook/<pull>/<path>` on
@@ -372,10 +374,24 @@ around it. None is advisory.
372374 builder is sent to it, since none can push that branch; changes asked
373375 for on it go back to its author, and the crew never parks it
374376 (`crew/authors_pull.ts`, #7572).
375 2. **A preview lives exactly as long as its pull is open.** Opened: deployed.
376 Pushed: redeployed at the new head. Closed or merged: stopped, and its
377 data deleted. There is no orphan state; the sweep on boot rebuilds the
378 set of previews from the set of open pulls.
377 2. **A preview lives exactly as long as its pull is open.** Opened: recorded
378 at its head. Pushed: recorded at the new head. Closed or merged: stopped,
379 and its data deleted. There is no orphan state; the sweep on boot rebuilds
380 the set of previews from the set of open pulls.
381 **A preview starts asleep** (`apps/prepared.ts`). After a push it holds no
382 process and no checkout; its pull says `asleep until someone opens it`. The
383 first request for it (a person opening its address, an agent's `curl`,
384 *Wake it*) builds and starts it at that head: a person sees a page that
385 says it is waking and refreshes, a program's request waits up to 90
386 seconds for the answer, and every request that arrives meanwhile joins
387 the one start. It sleeps again on the ordinary window. Three things ask
388 at the push itself, and for those the deploy runs then, as it always did:
389 the head declares no `check` (or the forge runs none), so the deploy is
390 the pull's only verdict; the pull changes a page the forge pictures
391 (`src/web/` with `app.looks`, no `No look:` line), so its look can be
392 taken; or the head's `forge.json` says `"previews": "eager"` under `app`.
393 A preview that is up when a push arrives is redeployed at the new head:
394 someone is using it.
379395 A pull from someone who cannot write the repository is the exception:
380396 its preview and its check run nothing until a person who can write
381397 approves that exact head, and each new push waits for a new approval
@@ -568,6 +584,10 @@ pull that changes how the app runs is previewed the way it will run.
568584 says — the one per-app exception to it, shown on the app page. Previews
569585 still sleep as the forge says.
570586
587 `app.previews: "eager"` deploys every pull's preview at each push instead
588 of at the first request for it; `"asleep"` (the default) need not be
589 written. Anything else fails the deploy and says why.
590
571591 `toolbar`, at the top level, is `true` unless you set it to `false`. The
572592 forge adds one `<script>` tag to the HTML pages your app serves (before
573593 `</body>`, or at the end): a small pill in the bottom-right corner, collapsed
docs/features/forge-sleep.md +1
@@ -21,6 +21,7 @@ The apps a forge runs sleep too, and the profit slider on the economics page say
2121
2222 - **Move the slider.** Each sweep, once a minute, reads the slider's position. No restart is needed. Production sleeps after 10 min with no requests at position 0, after 1 day at 50 (the default) and never at 100. A quiet pull's preview stops after 1 day at 0, 3 days at 50 and never at 100. When an app goes to sleep, its deploy log names the window and the position, e.g. `asleep: nothing asked for it in 10 min (economy 0); the next request wakes it`.
2323 - **Keep one app awake.** Put `"always_on": true` under `app` in its `forge.json` and push. Its production never sleeps, whatever the position. Its previews still follow the slider. Any value other than `true` or `false` fails the deploy and says why. The app page shows the row "Sleeps: never (app.always_on)". The terminal's deploys screen adds "never sleeps (app.always_on)" to production's line.
24 - **Previews start asleep.** A push to a pull starts nothing: the preview is recorded at the new head, and its pull says `asleep until someone opens it`. Open the preview, or `curl` it, and the forge builds and starts it; a page says it is waking and refreshes, a program's request waits for the answer. A pull whose deploy is its only check, or that changes a pictured page, is still deployed at the push. To deploy every pull of one app at each push, put `"previews": "eager"` under `app` in its `forge.json`.
2425 - **Pin the preview age.** Setting `FORGE_PREVIEW_IDLE_DAYS` on the forge fixes a quiet pull's preview age, whatever the position. `0` keeps every preview warm. Leave it unset to follow the slider.
2526
2627 Code: `src/apps/sleep_window.ts` (windows, `previewIdleMs`), `src/apps/runtime.ts` (the sweep). Tests: `test/sleep-window.test.ts`, `test/apps-sleep-slider.test.ts`, `test/preview-idle-slider.test.ts`.
src/apps/env_phrase.ts +6
@@ -13,6 +13,12 @@ export const VERIFYING_NOTE = "serving — still verifying its tests";
1313 /** The tones an environment's word wears; the web's `Tone` and the terminal's both hold them. */
1414 export type EnvPhraseTone = "default" | "success" | "danger" | "attn";
1515
16 /**
17 * What a preview not started yet says of itself, on every door (`apps/prepared.ts`). Here, not
18 * there, because the web's static modules may import this file and no other of `apps/`.
19 */
20 export const PREPARED_WORDS = "asleep until someone opens it";
21
outdated

Principle 8: 'asleep: not started yet; the first request builds and starts it at <sha>' is a semicolon chain. Plain words: 'Asleep until someone opens it.' Show the commit as its own fact.

1622 /**
1723 * An environment's state in a person's words rather than a badge's —
1824 * `live`, `serving · tests failed`, `not up`, `not running` — for a head
src/apps/manifest.ts +6
@@ -22,6 +22,7 @@ import { parseToolchain, type ToolchainPin } from "./toolchain.ts";
2222 import { parseSchedules, type ScheduleSpec } from "./schedule_spec.ts";
2323 import { parseBeat, type BeatSpec } from "./beat_spec.ts";
2424 import { parseFeature, scheduleSpecs } from "./feature.ts";
25 import { PREVIEW_MODES } from "./prepared.ts";
2526
2627 export interface AppManifest {
2728 /** The command that serves on `$PORT`. Run through `sh -c`, `exec`-ed. */
@@ -206,6 +207,11 @@ export function parseManifest(
206207 const alwaysOn = app["always_on"];
207208 if (alwaysOn !== undefined && typeof alwaysOn !== "boolean")
208209 return invalid("forge.json: app.always_on must be true or false");
210 // Read at the push from the head's forge.json (`apps/prepared.ts`); refused here when it is
211 // neither.
212 const previews = app["previews"];
213 if (previews !== undefined && (typeof previews !== "string" || !PREVIEW_MODES.includes(previews)))
214 return invalid(`forge.json: app.previews must be one of ${PREVIEW_MODES.map((m) => `"${m}"`).join(", ")}`);
209215 const egress = egressField(parsed.value);
210216 if (!egress.ok) return egress;
211217 const limits = limitsField(app, "app");
src/apps/prepared.ts added +52
@@ -0,0 +1,52 @@
1 /**
2 * Whether a pull's preview is built at the push or at the first request for it. A preview costs
3 * nothing until someone or something asks: after a push it is recorded asleep at the head, with
4 * no checkout and no process, and the first request builds and starts it (`AppsRuntime.rouse`).
5 * Three things ask at the push itself, and for those the deploy runs as it always has and
6 * sleeps on the ordinary window:
7 *
8 * - `eager`: the head's `forge.json` says `app.previews: "eager"`;
9 * - `check`: the head declares no `check`, or this forge runs none (`FORGE_CHECKS=0`), so the
10 * preview's deploy (install, start, health, `app.test`) is the only verdict its pull gets;
11 * - `look`: the pull changes a page the forge pictures (`checks/look_pages.ts`), and a picture
12 * is taken of a preview that serves.
13 *
14 * Plain data in, plain data out.
15 */
16
17 /** What asks for a preview at the push. */
18 export type PushAsker = "eager" | "check" | "look";
19
20 /** What a prepared preview's log and pages call each asker. */
21 export const ASKER_WORDS: Readonly<Record<PushAsker, string>> = {
22 eager: 'forge.json says app.previews: "eager"',
23 check: "its deploy is the pull's check",
24 look: "the pull changes a page the forge pictures",
25 };
26
27 /** The values `app.previews` takes; unset is `asleep`. */
28 export const PREVIEW_MODES: readonly string[] = ["asleep", "eager"];
29
30 const isObject = (v: unknown): v is Record<string, unknown> =>
31 typeof v === "object" && v !== null && !Array.isArray(v);
32
33 /**
34 * What the head's `forge.json` alone says asks for the preview at the push. A file that is
35 * absent or does not parse declares no check: the deploy is what says so on the pull.
36 */
37 export function declaredAsker(forgeJson: string | undefined): "eager" | "check" | undefined {
38 if (forgeJson === undefined) return "check";
39 let parsed: unknown;
40 try {
41 parsed = JSON.parse(forgeJson);
42 } catch {
43 return "check";
44 }
45 if (!isObject(parsed)) return "check";
46 const app = parsed["app"];
47 if (isObject(app) && app["previews"] === "eager") return "eager";
48 return isObject(parsed["check"]) ? undefined : "check";
49 }
50
51 /** What the starting page and the `preview` tool say while the build a request asked for runs. */
52 export const WAKING_WORDS = "It was asleep until it was asked for, and is starting now.";
src/apps/proxy.ts +18 −3
@@ -752,6 +752,9 @@ function stillEntitled(
752752 );
753753 }
754754
755 /** How long a program's request waits for a preview it woke to be built and answer. */
756 export const ROUSE_WAIT_MS = 90_000;
757
755758 /** What the app's host tells a signed-in reader it may not enter. */
756759 export const NOT_ENTITLED_WORDS =
757760 "not found: this token can read the repository but may not enter its app. Ask a writer of the repository to add you to the app, or use a token of a writer or of the crew.";
@@ -1316,8 +1319,18 @@ export async function proxyApp(
13161319 wakeMs = performance.now() - woke;
13171320 }
13181321 const admitting = performance.now();
1319 const admitted = admit(runtime, request, target);
1322 let admitted = admit(runtime, request, target);
13201323 const sessionMs = performance.now() - admitting;
1324 // A preview not started yet is built for the request that asks (`admit` roused it). A person
1325 // is shown the starting page, which says so and refreshes; a program waits for it here, as it
1326 // waits for a wake, and every request that arrives meanwhile waits on the same deploy. Only
1327 // the starting answer waits: a caller who was refused learns nothing from the time.
1328 if (!admitted.ok && admitted.error.status === 503 && !navigating(request) && runtime.envStatus(target.app, target.env)?.waking === true) {
1329 const asked = performance.now();
1330 await runtime.served(target.app, target.env, AbortSignal.any([request.signal, AbortSignal.timeout(ROUSE_WAIT_MS)]));
1331 wakeMs += performance.now() - asked;
1332 admitted = admit(runtime, request, target);
1333 }
13211334 // A refused answer names no phases: wake runs before `admit`, so its time
13221335 // would tell a caller who may not read the app whether it was asleep. It
13231336 // is the forge's answer, never the app's, so it carries the floor: `/` of
@@ -1965,6 +1978,8 @@ export function unavailable(
19651978 // environment keeps its 502.
19661979 const absent = preview && !gone && status === undefined;
19671980 const words = servingWords(status, preview ? (gone ? "closed" : "open") : null);
1981 // A preview a request woke says so: it is being built for whoever asked, not for a push.
1982 const doing = status?.waking === true ? "waking" : "starting";
19681983 const build = envBuild(target.env) !== undefined;
19691984 const message =
19701985 reason ??
@@ -1998,7 +2013,7 @@ export function unavailable(
19982013 <meta charset="utf-8">
19992014 <meta name="viewport" content="width=device-width, initial-scale=1">
20002015 ${deploying ? '<meta http-equiv="refresh" content="3">' : ""}
2001 <title>${escape(name)} — ${deploying ? "starting" : gone ? "gone" : "not running"}</title>
2016 <title>${escape(name)} — ${deploying ? doing : gone ? "gone" : "not running"}</title>
20022017 <style>
20032018 :root { color-scheme: light dark; font: 16px/1.5 system-ui, sans-serif; }
20042019 body { max-width: 34rem; margin: 20vh auto; padding: 0 1.5rem; }
@@ -2006,7 +2021,7 @@ ${deploying ? '<meta http-equiv="refresh" content="3">' : ""}
20062021 p { margin: .5rem 0; opacity: .85; }
20072022 code { font-size: .9em; }
20082023 </style>
2009 <h1>${escape(name)} ${deploying ? "is starting" : gone ? "is gone" : "is not running"}</h1>
2024 <h1>${escape(name)} ${deploying ? `is ${doing}` : gone ? "is gone" : "is not running"}</h1>
20102025 <p>This is ${escape(where)}. ${escape(message)}</p>
20112026 ${deploying ? "<p>This page refreshes on its own.</p>" : ""}
20122027 ${runLink}
src/apps/runtime.ts +113 −32
@@ -17,6 +17,8 @@ import type { Database } from "bun:sqlite";
1717 import type { CertificateProbe } from "./certificate.ts";
1818 import { cellHides, grantsHere } from "../spawn/hosted-mark.ts";
1919 import { VERIFYING_NOTE } from "./env_phrase.ts";
20 import { ASKER_WORDS, declaredAsker, type PushAsker } from "./prepared.ts";
21 import { lookPagesAt } from "../checks/look_pages.ts";
2022 import { dropCheckouts, STRAY_CHECKOUT_AGE_MS } from "./dormant_checkout.ts";
2123 import { listEgressGrants } from "../core/egress_grants.ts";
2224 import { recordCarried } from "../core/carried.ts";
@@ -46,7 +48,7 @@ import { appTokenName, mintAppToken, renewAppToken, revokeAppToken } from "./tok
4648 import { askingOf } from "../perf/asking.ts";
4749 import type { ForgeEvent } from "../core/events.ts";
4850 import { announceRun } from "../actions/runs.ts";
49 import { requeueAbandonedChecks } from "../checks/service.ts";
51 import { checksFor, requeueAbandonedChecks } from "../checks/service.ts";
5052 import { checkInstallCache } from "../checks/install.ts";
5153 import { getPull, listPulls, type Pull } from "../core/pulls.ts";
5254 import { isContributionFork } from "../core/contribute.ts";
@@ -320,7 +322,18 @@ export interface EnvStatus {
320322 * stopped, and the last touch (push, comment, wake) it was measured from.
321323 * A stopped preview with this set is asleep, never failed.
322324 */
323 readonly dormant?: { readonly since: string; readonly idleSince: string } | undefined;
325 readonly dormant?:
326 | {
327 readonly since: string;
328 readonly idleSince: string;
329 /** Never started at this head: recorded asleep at the push (`apps/prepared.ts`). */
330 readonly prepared?: true | undefined;
331 }
332 | undefined;
333 /**
334 * Set while it comes up because a request asked for a preview that was stopped or not started.
335 */
336 readonly waking?: true | undefined;
324337 }
325338
326339 interface Live {
@@ -433,7 +446,7 @@ interface Environment {
433446 asleep?: Asleep | undefined;
434447 /** Stopped for want of a push or comment; asked for, it redeploys. */
435448 dormant?:
436 | { since: string; idleSince: string; commitOid: string }
449 | { since: string; idleSince: string; commitOid: string; prepared?: true }
437450 | undefined;
438451 /** Why the last wake did not happen (the owner's preview limit), for the page a visitor sees. */
439452 wakeRefused?: string | undefined;
@@ -651,6 +664,7 @@ export class AppsRuntime {
651664 state: "deploying",
652665 commitOid: state.deploying.run.commitOid,
653666 url,
667 ...(state.live === undefined && state.deploying.run.reason === "wake" ? { waking: true as const } : {}),
654668 ...(state.live === undefined
655669 ? {}
656670 : {
@@ -727,6 +741,7 @@ export class AppsRuntime {
727741 commitOid: state.queued.commitOid,
728742 url,
729743 runId: state.queued.id,
744 ...(state.queued.reason === "wake" ? { waking: true as const } : {}),
730745 };
731746 }
732747 if (state.dormant !== undefined) {
@@ -739,6 +754,7 @@ export class AppsRuntime {
739754 dormant: {
740755 since: state.dormant.since,
741756 idleSince: state.dormant.idleSince,
757 ...(state.dormant.prepared === true ? { prepared: true as const } : {}),
742758 },
743759 };
744760 }
@@ -932,7 +948,10 @@ export class AppsRuntime {
932948 continue;
933949 }
934950 }
935 this.requestDeploy(record, repo, env, head, reason);
951 // One at a time at boot: each decision reads git, and a forge coming back has every open
952 // pull to decide.
953 const decided = this.prepare(record, repo, pull, head, reason);
954 if (reason === "boot") await decided;
936955 }
937956 // Environments on disk for pulls that are no longer open.
938957 const root = join(appsRoot(this.app.config.dataDir), record.id);
@@ -1074,14 +1093,7 @@ export class AppsRuntime {
10741093 })) {
10751094 if (pull.crossRepo || pull.headBranch !== branch || deleted)
10761095 continue;
1077 this.requestDeploy(
1078 record,
1079 repo,
1080 previewEnv(pull.number),
1081 update.newOid,
1082 "push",
1083 event.actorId ?? undefined,
1084 );
1096 void this.prepare(record, repo, pull, update.newOid, "push", event.actorId ?? undefined);
10851097 }
10861098 }
10871099 return;
@@ -1092,14 +1104,8 @@ export class AppsRuntime {
10921104 const number = event.payload["number"];
10931105 const headOid = event.payload["headOid"];
10941106 if (typeof number !== "number" || typeof headOid !== "string") return;
1095 this.requestDeploy(
1096 record,
1097 repo,
1098 previewEnv(number),
1099 headOid,
1100 "push",
1101 event.actorId ?? undefined,
1102 );
1107 const pull = getPull(this.app.db, repo.id, number);
1108 if (pull) void this.prepare(record, repo, pull, headOid, "push", event.actorId ?? undefined);
11031109 return;
11041110 }
11051111 case "pull.opened":
@@ -1108,18 +1114,11 @@ export class AppsRuntime {
11081114 if (!pull) return;
11091115 const head = await this.pullHead(repo, pull);
11101116 if (head !== undefined)
1111 this.requestDeploy(
1112 record,
1113 repo,
1114 previewEnv(pull.number),
1115 head,
1116 "opened",
1117 event.actorId ?? undefined,
1118 );
1117 void this.prepare(record, repo, pull, head, "opened", event.actorId ?? undefined);
11191118 return;
11201119 }
1121 // An approval is what lets a reader's pull run: deploy its head now.
1122 // A guest's approval restarts its preview with the app's variables.
1120 // An approval is what lets a reader's pull run: its head may be asked for from now.
1121 // A guest's approval restarts a preview that is up with the app's variables.
11231122 case "pull.run_granted":
11241123 case "pull.guest_approved":
11251124 case "pull.reviewed": {
@@ -1151,10 +1150,10 @@ export class AppsRuntime {
11511150 if (!pull || pull.state !== "open") return;
11521151 const head = await this.pullHead(repo, pull);
11531152 if (head !== undefined)
1154 this.requestDeploy(
1153 void this.prepare(
11551154 record,
11561155 repo,
1157 previewEnv(pull.number),
1156 pull,
11581157 head,
11591158 // The same head may be serving already: start it again so it
11601159 // comes up holding the variables it ran without.
@@ -1278,6 +1277,88 @@ export class AppsRuntime {
12781277 return run;
12791278 }
12801279
1280 /**
1281 * A pull's preview at `head`, after a push, an opening or an approval. One that something asks
1282 * for at the push (`apps/prepared.ts`), or that is up or coming up already, deploys the
1283 * ordinary way. Any other costs nothing until it is asked for: it is recorded asleep at `head`
1284 * with no checkout and no process, and the first request builds and starts it (`rouse`).
1285 * Decided on the environment's chain, so a burst of pushes ends at the last head.
1286 */
1287 private prepare(record: AppRecord, repo: Repo, pull: Pull, head: string, reason: string, actorId?: string): Promise<void> {
1288 const env = previewEnv(pull.number);
1289 if (this.stopped || repo.archivedAt !== null || !accountActive(this.app.db, repo.ownerId)) return Promise.resolve();
1290 if (!this.mayRun(record, repo, env, head)) return Promise.resolve();
1291 const state = this.envFor(record, env);
1292 const decide = async (): Promise<void> => {
1293 if (this.stopped || this.envs.get(key(record.id, env)) !== state) return;
1294 const up =
1295 state.live !== undefined ||
1296 state.deploying !== undefined ||
1297 state.queued !== undefined ||
1298 state.waking !== undefined;
1299 // A repository that cannot be read is deployed, as it always was: the deploy says why.
1300 const asker = up ? "up" : await this.pushAsker(repo, pull, head, reason !== "boot").catch(() => "check" as const);
1301 if (asker !== undefined) {
1302 this.requestDeploy(record, repo, env, head, reason, actorId);
1303 return;
1304 }
1305 // Asleep at this very head already (a boot, an approval): it stays as it is.
1306 if (state.asleep?.commitOid === head || state.dormant?.commitOid === head) return;
1307 const now = new Date().toISOString();
1308 state.asleep = undefined;
1309 state.dormant = { since: now, idleSince: now, commitOid: head, prepared: true };
1310 state.lastError = undefined;
1311 state.lastErrorCommitOid = undefined;
1312 log.info("preview asleep until asked for", { app: record.slug, env, commit: head.slice(0, 7), reason });
1313 // An older head's checkout is dead weight now: the first request checks this one out.
1314 await dropCheckouts(this.app.config.dataDir, record.id, env);
1315 };
1316 const decided = state.chain.then(decide).catch((error: unknown) =>
1317 log.error("could not prepare a preview", { app: record.slug, env, error: String(error) }),
1318 );
1319 state.chain = decided;
1320 return decided;
1321 }
1322
1323 /** What asks for this pull's preview at the push, if anything does (`apps/prepared.ts`). */
1324 private async pushAsker(repo: Repo, pull: Pull, head: string, pictured: boolean): Promise<PushAsker | undefined> {
1325 // A forge that runs no checks (`FORGE_CHECKS=0`) judges every pull by its deploy.
1326 if (checksFor(this.app) === undefined) return "check";
1327 const dir = await pullDir(this.app.db, this.app.reposRoot, repo, pull);
1328 const asker =
1329 declaredAsker(await readFileAt(dir, head, "forge.json")) ??
1330 // A boot is no push: a head pictured before it has its pictures, and nothing new is owed one.
1331 (pictured && (await lookPagesAt(dir, pull.baseOid, head)).length > 0 ? ("look" as const) : undefined);
1332 if (asker !== undefined)
1333 log.info("preview deploys at the push", { repo: repo.name, pull: pull.number, why: ASKER_WORDS[asker] });
1334 return asker;
1335 }
1336
1337 /**
1338 * Wait for an environment a request asked for to answer: until its deploy serves or ends, or
1339 * `signal` aborts. Every caller waits on the one deploy; none starts another.
1340 */
1341 served(record: AppRecord, env: EnvName, signal: AbortSignal): Promise<void> {
1342 const state = this.envs.get(key(record.id, env));
1343 const coming = (): boolean =>
1344 state !== undefined &&
1345 state.live === undefined &&
1346 (state.queued !== undefined || state.deploying !== undefined);
1347 if (!coming() || signal.aborted) return Promise.resolve();
1348 return new Promise((resolve) => {
1349 const done = (): void => {
1350 off();
1351 signal.removeEventListener("abort", done);
1352 resolve();
1353 };
1354 const off = this.app.bus.subscribe((event) => {
1355 if (event.repoId === record.repoId && (event.kind === "app.serving" || event.kind === "run.finished") && !coming())
1356 done();
1357 });
1358 signal.addEventListener("abort", done, { once: true });
1359 });
1360 }
1361
12811362 /**
12821363 * Serve one commit now, at `build-<sha7>`. Asked again for a build already
12831364 * here, it redeploys nothing and hands back the same environment. A new
src/apps/serving_words.ts +6 −1
@@ -5,6 +5,8 @@
55 */
66
77 import { redactHeld } from "../kernel/log.ts";
8 import { PREPARED_WORDS } from "./env_phrase.ts";
9 import { WAKING_WORDS } from "./prepared.ts";
810 import type { EnvStatus } from "./runtime.ts";
911
1012 export type ServingState = "running" | "starting" | "failed" | "not_running" | "gone";
@@ -22,7 +24,8 @@ export interface ServingWords {
2224 export function servingWords(status: EnvStatus | undefined, pull: "open" | "closed" | null): ServingWords {
2325 const state = status?.state ?? "stopped";
2426 if (state === "running") return { state: "running", says: "It is running." };
25 if (state === "deploying") return { state: "starting", says: "A new version is starting." };
27 if (state === "deploying")
28 return { state: "starting", says: status?.waking === true ? WAKING_WORDS : "A new version is starting." };
2629 if (state === "failed" || (state === "asleep" && status?.error !== undefined))
2730 return { state: "failed", says: redactHeld(status?.error ?? "The last deploy failed.") };
2831 if (pull === "closed")
@@ -32,5 +35,7 @@ export function servingWords(status: EnvStatus | undefined, pull: "open" | "clos
3235 state: "not_running",
3336 says: "The preview is not running. It starts again with the next push to the pull, or with app_deploy redeploy.",
3437 };
38 if (status?.dormant?.prepared === true)
39 return { state: "not_running", says: `The preview is ${PREPARED_WORDS}.` };
3540 return { state: "not_running", says: "Nothing is running here yet." };
3641 }
src/tui/screens/pull.ts +3
@@ -147,6 +147,7 @@ import { runTone } from "./runwords.ts";
147147 import { Composer, threadLines, type ThreadEntry } from "./thread.ts";
148148 import { local, localRepo, whereRows, whereStrip } from "./where.ts";
149149 import { openAppTerminal } from "./apptty.ts";
150 import { PREPARED_WORDS } from "../../apps/env_phrase.ts";
150151
151152 /** One thread on the diff, as this screen holds it. */
152153 interface Thread {
@@ -1795,6 +1796,8 @@ function drawPreviewLine(
17951796 ? `asleep${preview.since === undefined ? "" : ` since ${ago(preview.since)}`}; wakes on a request`
17961797 : preview.dormant === undefined
17971798 ? "stopped"
1799 : preview.dormant.prepared === true
1800 ? PREPARED_WORDS
17981801 : `asleep since ${ago(preview.dormant.since)}; nobody touched the change since ${ago(preview.dormant.idleSince)}`;
17991802 x = s.text(
18001803 x,
src/web/ui.ts +2
@@ -26,6 +26,7 @@ import { icon, type IconName } from "./icons.ts";
2626 import { crewFace, scene, type SceneName } from "./pixel.ts";
2727 import { Html, html, raw, when } from "./html.ts";
2828 import { why } from "./setting_line.ts";
29 import { PREPARED_WORDS } from "../apps/env_phrase.ts";
2930 import { at, countAttr, listAttr, zeroAttr } from "./bind.ts";
3031
3132 export { icon, type IconName };
@@ -458,6 +459,7 @@ export function envStateBadge(state: EnvState, dormant = false): Html {
458459 export function dormantNote(env: EnvStatus): Html | null {
459460 const d = env.dormant;
460461 if (d === undefined) return null;
462 if (d.prepared === true) return html`${PREPARED_WORDS}`;
461463 return html`asleep ${time(d.since)} — nobody pushed or commented since
462464 ${time(d.idleSince)}; its data and pictures are kept`;
463465 }
test/apps-idle.test.ts +120 −9
@@ -1,7 +1,9 @@
11 /**
2 * A preview whose pull nobody has touched for days is stopped, not removed:
3 * its page says it is asleep and why, asking for it deploys it again, and a
4 * restart leaves it as it was.
2 * A preview costs nothing until someone or something asks for it: after a
3 * push it is asleep at the head with no process and no checkout, and the
4 * first request builds and starts it. One whose pull nobody has touched for
5 * days is stopped again, not removed: its page says it is asleep and why,
6 * asking for it deploys it again, and a restart leaves it as it was.
57 */
68 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
79 import { existsSync, mkdirSync, readdirSync } from "node:fs";
@@ -11,6 +13,8 @@ import { tmpdir } from "node:os";
1113 import { join } from "node:path";
1214 import { createApp, type App } from "../src/app.ts";
1315 import { AppsRuntime, type EnvStatus } from "../src/apps/runtime.ts";
16 import { WAKING_WORDS } from "../src/apps/prepared.ts";
17 import { provideChecksForTest, type ChecksHandle } from "../src/checks/service.ts";
1418 import { newApp } from "../src/actions/apps.ts";
1519 import { openPull } from "../src/actions/pulls.ts";
1620 import { commitToBranch } from "../src/actions/repos.ts";
@@ -30,11 +34,12 @@ describe("previews of idle pulls sleep", () => {
3034 let alice: User;
3135 let repo: Repo;
3236 let record: AppRecord;
33 // Three previews, deployed once for the file: deploying is the slow part,
34 // and no test here is about deploying.
37 // Three previews, asked for once for the file: deploying is the slow part.
3538 let fresh: number;
3639 let idle: number;
3740 let later: number;
41 /** The pull nothing ever asks for, and the head it was last pushed to. */
42 let calm: { number: number; head: string };
3843 const DOMAIN = "apps.test";
3944
4045 const options = () => ({
@@ -77,22 +82,44 @@ describe("previews of idle pulls sleep", () => {
7782 const running = (n: number) =>
7883 until(() => (envOf(n)?.state === "running" ? true : undefined));
7984
80 async function pull(name: string): Promise<number> {
85 /** Commit to a pull's branch, as a push does; the new head. */
86 async function push(name: string, files: { path: string; content: string }[]): Promise<string> {
8187 const branch = await commitToBranch(app, alice, repo, {
8288 branch: `feature/${name}`,
8389 base: "main",
8490 message: name,
85 files: [{ path: `${name}.md`, content: `${name}\n` }],
91 files,
8692 });
8793 if (!branch.ok) throw new Error(JSON.stringify(branch.error));
94 return branch.value.commitOid;
95 }
96
97 /** Open a pull and ask for nothing: its preview is left as the push left it. */
98 async function open(name: string, files = [{ path: `${name}.md`, content: `${name}\n` }]): Promise<{ number: number; head: string }> {
99 const head = await push(name, files);
88100 const opened = await openPull(app, alice, repo, {
89101 title: name,
90102 baseBranch: "main",
91103 headBranch: `feature/${name}`,
92104 });
93105 if (!opened.ok) throw new Error(String(opened.error));
94 await running(opened.value.number);
95 return opened.value.number;
106 return { number: opened.value.number, head };
107 }
108 /** A preview recorded asleep at a head, never started there. */
109 const prepared = (n: number, head: string) =>
110 until(() => (envOf(n)?.dormant?.prepared === true && envOf(n)?.commitOid === head ? true : undefined));
111 /** What a program asks: no page wanted, so the answer is waited for. */
112 const ask = (n: number) => fetch(`${servers.url}/`, { headers: { host: `hello--${n}.${DOMAIN}` } });
113 const deploys = (n: number) =>
114 listRuns(app.db, repo.id, { kind: "deploy", limit: 200 }).filter((r) => r.env === `pull-${n}`);
115
116 /** A pull whose preview someone asked for: the first request built and started it. */
117 async function pull(name: string): Promise<number> {
118 const { number, head } = await open(name);
119 await prepared(number, head);
120 expect((await ask(number)).status).toBe(200);
121 await running(number);
122 return number;
96123 }
97124
98125 /** Make a pull look untouched for `ms`: its row, and the pushes that opened it. */
@@ -111,6 +138,9 @@ describe("previews of idle pulls sleep", () => {
111138 beforeAll(async () => {
112139 dataDir = await mkdtemp(join(tmpdir(), "forge-idle-"));
113140 app = createApp({ dataDir, port: 0 });
141 // A forge that checks its pulls: the template's `check` is their verdict, not the deploy.
142 // (One that runs no checks deploys every push, which every other apps test covers.)
143 provideChecksForTest(app, { spareSlots: () => 0 } as unknown as ChecksHandle);
114144 servers = await serve(app);
115145 runtime = new AppsRuntime(app, options());
116146 await runtime.start();
@@ -142,6 +172,84 @@ describe("previews of idle pulls sleep", () => {
142172 await rm(dataDir, { recursive: true, force: true });
143173 });
144174
175 test("after a push a preview is asleep at the head: no process, no checkout, no deploy; production is untouched", async () => {
176 // Invariant: a push nothing asks about records the preview at its head and starts nothing.
177 const production = () => runtime.status(record).find((e) => e.env === "production");
178 await until(() => (production()?.state === "running" ? true : undefined));
179 const serving = production()!.commitOid;
180 const { number, head } = await open("calm");
181 await prepared(number, head);
182 const env = envOf(number)!;
183 expect(env.state).toBe("stopped");
184 expect(env.port).toBeUndefined();
185 expect(env.error).toBeUndefined();
186 expect(runtime.liveFor(record, `pull-${number}`)).toBeUndefined();
187 expect(checkouts(number)).toEqual([]);
188 expect(deploys(number)).toEqual([]);
189 // A second push moves the record to the new head and still starts nothing.
190 const next = await push("calm", [{ path: "calm.md", content: "calmer\n" }]);
191 await prepared(number, next);
192 calm = { number, head: next };
193 expect(deploys(number)).toEqual([]);
194 expect(checkouts(number)).toEqual([]);
195 // Production follows the default branch as it always has: running, at the commit it served.
196 expect(production()?.state).toBe("running");
197 expect(production()?.commitOid).toBe(serving);
198 // Both doors say what it is and what asking does.
199 const page = await (await fetch(`${servers.url}/alice/hello/pulls/${number}`)).text();
200 expect(page).toContain("Asleep");
201 expect(page).toContain("asleep until someone opens it");
202 expect(page).not.toContain("nobody pushed or commented since");
203 }, 120_000);
204
205 test("the first request wakes it at the pushed commit; requests that arrive meanwhile join the one start", async () => {
206 // Invariant: one "wake" deploy per sleeping preview however many ask at once; a person is
207 // shown what is happening, a program waits for the answer.
208 const { number, head } = await open("asked");
209 await prepared(number, head);
210 const host = { host: `hello--${number}.${DOMAIN}` };
211 const [first, second, person] = await Promise.all([
212 ask(number),
213 ask(number),
214 fetch(`${servers.url}/`, { headers: { ...host, accept: "text/html" } }),
215 ]);
216 expect(first.status).toBe(200);
217 expect(second.status).toBe(200);
218 // The person's page came back at once and says what the forge is doing.
219 expect(person.status).toBe(503);
220 const waking = await person.text();
221 expect(waking).toContain("hello is waking");
222 expect(waking).toContain(WAKING_WORDS);
223 expect(waking).toContain('http-equiv="refresh"');
224 const runs = deploys(number);
225 expect(runs.map((r) => r.reason)).toEqual(["wake"]);
226 expect(runs[0]!.commitOid).toBe(head);
227 expect(envOf(number)?.state).toBe("running");
228 expect(envOf(number)?.commitOid).toBe(head);
229 expect(checkouts(number)).toEqual([head.slice(0, 7)]);
230 // In use now: a push to it deploys the new head, as a push always did to a preview that is up.
231 const next = await push("asked", [{ path: "asked.md", content: "again\n" }]);
232 await until(() => (envOf(number)?.state === "running" && envOf(number)?.commitOid === next ? true : undefined));
233 expect(deploys(number).map((r) => r.reason).sort()).toEqual(["push", "wake"]);
234 }, 120_000);
235
236 test("what asks at the push still gets its preview: a pictured page changed, and app.previews eager", async () => {
237 // Invariant: a pull that changes a rendered file is deployed at the push so its look is
238 // taken; a head that says app.previews "eager" is deployed as before.
239 const declared = { egress: [], app: { run: "bun run src/server.ts", health: "/healthz", looks: ["/"] }, check: { run: "true" } };
240 const look = await open("pictured", [
241 { path: "forge.json", content: JSON.stringify(declared) },
242 { path: "src/web/home.ts", content: "export const home = 1;\n" },
243 ]);
244 await running(look.number);
245 expect(deploys(look.number).map((r) => r.reason)).toEqual(["opened"]);
246 const eager = await open("eager", [
247 { path: "forge.json", content: JSON.stringify({ ...declared, app: { ...declared.app, looks: [], previews: "eager" } }) },
248 ]);
249 await running(eager.number);
250 expect(deploys(eager.number).map((r) => r.reason)).toEqual(["opened"]);
251 }, 120_000);
252
145253 test("a pull touched an hour ago keeps its preview; one idle past the age loses its process, and its page says so", async () => {
146254 // Invariant: the sweep stops a preview idle past the age (state kept, page says asleep), and
147255 // spares a fresh one and production.
@@ -246,5 +354,8 @@ describe("previews of idle pulls sleep", () => {
246354 (r) => r.env === `pull-${later}`,
247355 ).length;
248356 expect(after).toBe(before);
357 // One never asked for comes back as it was: asleep at its head, nothing deployed for it.
358 await prepared(calm.number, calm.head);
359 expect(deploys(calm.number)).toEqual([]);
249360 }, 120_000);
250361 });
test/boundary-pull-egress.test.ts +2
@@ -20,6 +20,7 @@ import { getRepoById, type Repo } from "../src/core/repos.ts";
2020 import { listRuns, type Run } from "../src/core/runs.ts";
2121 import { readRunLog } from "../src/runs/log.ts";
2222 import {
23 askForPreview,
2324 deploySettled,
2425 startAppsForge,
2526 stopAppsForge,
@@ -135,6 +136,7 @@ describe("a pull's check and preview reach what its base branch reaches, until i
135136 const pull = getPull(app.db, repo.id, opened.value.number)!;
136137 const env = `pull-${pull.number}`;
137138 const check = await checkSettled(env, pushed.value.commitOid);
139 await askForPreview(app, repo.id, pull.number);
138140 const deploy = await deploySettled(
139141 app,
140142 repo.id,
test/build-journey.test.ts +2
@@ -17,6 +17,7 @@ import { createAgent } from "../src/actions/crew.ts";
1717 import { assignIssue, openIssue } from "../src/actions/issues.ts";
1818 import { createApp, type App } from "../src/app.ts";
1919 import { AppsRuntime } from "../src/apps/runtime.ts";
20 import { askForPreview } from "./helpers/apps-forge.ts";
2021 import { startChecks, type ChecksHandle } from "../src/checks/service.ts";
2122 import { getRepoById, type Repo } from "../src/core/repos.ts";
2223 import { getPull, listOpenPulls, type Pull } from "../src/core/pulls.ts";
@@ -100,6 +101,7 @@ const newPull = (known: ReadonlySet<number>) =>
100101
101102 /** The pull's preview is built and its tests have passed: its own deploy run says so. */
102103 async function tested(pull: Pull): Promise<void> {
104 await askForPreview(app, repo.id, pull.number);
103105 const built = await until("the pull's preview and its tests", () =>
104106 listRuns(app.db, repo.id, { kind: "deploy", env: `pull-${pull.number}` }).find((r) => r.state === "ok" || r.state === "failed"),
105107 );
test/fork-pull-approval.test.ts +7 −2
@@ -23,6 +23,7 @@ import { openPull, submitReview } from "../src/actions/pulls.ts";
2323 import { commitToBranch, createRepo, forkRepo } from "../src/actions/repos.ts";
2424 import { createApp, type App } from "../src/app.ts";
2525 import { AppsRuntime } from "../src/apps/runtime.ts";
26 import { askForPreview } from "./helpers/apps-forge.ts";
2627 import { startChecks, type ChecksHandle } from "../src/checks/service.ts";
2728 import type { AppRecord } from "../src/core/apps.ts";
2829 import type { Pull } from "../src/core/pulls.ts";
@@ -285,8 +286,9 @@ describe("a reader's fork pull runs nothing until a writer approves its head", (
285286 expect(runsFor(notes, "deploy", pull)).toHaveLength(0);
286287 });
287288
288 test("a writer's approval of that head starts the check and the preview", async () => {
289 // Invariant: a writer's approval of the head runs its check and its preview.
289 test("a writer's approval of that head starts the check and lets the preview be asked for", async () => {
290 // Invariant: a writer's approval of the head runs its check, and its preview deploys for the
291 // first who asks.
290292 const one = await forkPull(carol, lib, "approved");
291293 const two = await forkPull(carol, notes, "approved");
292294 await checkDecided(lib, one.pull);
@@ -295,6 +297,7 @@ describe("a reader's fork pull runs nothing until a writer approves its head", (
295297 expect(runsFor(notes, "deploy", two.pull)).toHaveLength(0);
296298 await approve(alice, lib, one.pull);
297299 await approve(alice, notes, two.pull);
300 await askForPreview(app, notes.id, two.pull.number);
298301 await ran(lib, "check", one.pull, one.head);
299302 await ran(notes, "deploy", two.pull, two.head);
300303 });
@@ -356,6 +359,7 @@ describe("a reader's fork pull runs nothing until a writer approves its head", (
356359 async function deployedPreview(branch: string) {
357360 const { pull, head } = await forkPull(carol, notes, branch);
358361 await approve(alice, notes, pull);
362 await askForPreview(app, notes.id, pull.number);
359363 const env = `pull-${pull.number}`;
360364 const deadline = Date.now() + 10_000;
361365 while (
@@ -434,6 +438,7 @@ describe("a reader's fork pull runs nothing until a writer approves its head", (
434438 });
435439 if (!opened.ok) throw new Error(String(opened.error));
436440 const env = `pull-${opened.value.number}`;
441 await askForPreview(app, notes.id, opened.value.number);
437442 const deadline = Date.now() + 10_000;
438443 while (envOf(env)?.state !== "running") {
439444 if (Date.now() > deadline) throw new Error("preview did not deploy");
test/guest-pull-env.test.ts +2
@@ -21,6 +21,7 @@ import { listRuns, type Run } from "../src/core/runs.ts";
2121 import { guestWaits } from "../src/origins/guest.ts";
2222 import { readRunLog } from "../src/runs/log.ts";
2323 import {
24 askForPreview,
2425 deploySettled,
2526 fetchAsHost,
2627 startAppsForge,
@@ -158,6 +159,7 @@ describe("a guest pull's check and preview, read from the processes themselves",
158159 expect(printed).not.toContain(SECRET);
159160 expect(printed).not.toContain("API_KEY=");
160161 expect(printed).not.toContain("FORGE_TOKEN=");
162 await askForPreview(app, repo.id, pull.number);
161163 const waiting = await deploySettled(app, repo.id, (r) => r.env === env && r.commitOid === first.value.commitOid);
162164 expect(waiting.state).toBe("ok");
163165 expect(await heldByPreview(pull)).toEqual({ apiKey: null, forgeToken: false });
test/helpers/apps-forge.ts +21 −2
@@ -11,8 +11,8 @@ import { join } from "node:path";
1111 import { createApp, type App } from "../../src/app.ts";
1212 import { setSsh } from "../../src/settings/ssh.ts";
1313 import { newApp } from "../../src/actions/apps.ts";
14 import { AppsRuntime } from "../../src/apps/runtime.ts";
15 import type { AppRecord } from "../../src/core/apps.ts";
14 import { AppsRuntime, appsRuntime as runtimeOf } from "../../src/apps/runtime.ts";
15 import { getAppByRepo, type AppRecord } from "../../src/core/apps.ts";
1616 import type { Repo } from "../../src/core/repos.ts";
1717 import { listRuns, type Run } from "../../src/core/runs.ts";
1818 import { createUser, type User } from "../../src/core/users.ts";
@@ -151,6 +151,25 @@ export async function deploySettled(
151151 throw new Error("run did not settle in time");
152152 }
153153
154 /**
155 * Ask for pull `number`'s preview, as its first visitor does. On a forge that checks its pulls a
156 * push starts no preview (`apps/prepared.ts`): once the push has recorded it asleep this rouses
157 * it, and one already up or coming up is left alone.
158 */
159 export async function askForPreview(app: App, repoId: string, number: number, timeoutMs = 30_000): Promise<void> {
160 const runtime = runtimeOf(app);
161 const record = getAppByRepo(app.db, repoId);
162 if (runtime === undefined || record === undefined) throw new Error("no app to ask a preview of");
163 const deadline = Date.now() + timeoutMs;
164 while (Date.now() < deadline) {
165 const status = runtime.envStatus(record, `pull-${number}`);
166 if (status?.state === "deploying" || status?.state === "running") return;
167 if (status?.dormant !== undefined) return runtime.rouse(record, `pull-${number}`);
168 await Bun.sleep(10);
169 }
170 throw new Error(`pull ${number}'s preview was never recorded`);
171 }
172
154173 /**
155174 * `hello`, the new-app scaffold, public and serving in production — where
156175 * `apps.test.ts`'s first test leaves it, for the files that start from there.
test/sleep-window.test.ts +21
@@ -5,6 +5,7 @@
55 import { describe, expect, test } from "bun:test";
66 import { asleepWords, sleepWindow } from "../src/apps/sleep_window.ts";
77 import { parseManifest } from "../src/apps/manifest.ts";
8 import { declaredAsker } from "../src/apps/prepared.ts";
89 import { envFacts } from "../src/web/ui.ts";
910
1011 const at = (position: number) => ({ kind: "slider" as const, position });
@@ -60,3 +61,23 @@ describe("app.always_on in forge.json", () => {
6061 expect(String(envFacts("/alice/hello", env))).not.toContain("data-always-on");
6162 });
6263 });
64
65 describe("what asks for a preview at the push", () => {
66 test("a head with a check asks for nothing; one without is deployed, its deploy being the pull's check", () => {
67 expect(declaredAsker(JSON.stringify({ app: { run: "x" }, check: { run: "bun test" } }))).toBeUndefined();
68 expect(declaredAsker(JSON.stringify({ app: { run: "x" } }))).toBe("check");
69 expect(declaredAsker(undefined)).toBe("check");
70 expect(declaredAsker("{not json")).toBe("check");
71 });
72
73 test('app.previews "eager" opts a repository back in; anything but the two modes is refused', () => {
74 expect(declaredAsker(JSON.stringify({ app: { previews: "eager" }, check: { run: "bun test" } }))).toBe("eager");
75 expect(declaredAsker(JSON.stringify({ app: { previews: "asleep" }, check: { run: "bun test" } }))).toBeUndefined();
76 const manifest = (previews: unknown) => parseManifest(JSON.stringify({ app: { run: "bun run s.ts", previews } }), undefined);
77 expect(manifest("eager").ok).toBe(true);
78 expect(manifest("asleep").ok).toBe(true);
79 const bad = manifest(true);
80 expect(bad.ok).toBe(false);
81 if (!bad.ok) expect(JSON.stringify(bad.error)).toContain('app.previews must be one of \\"asleep\\", \\"eager\\"');
82 });
83 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs