@antelopejs/dms-frontend 0.6.4 → 0.7.1

package/dist/materialize.js

@@ -114,11 +114,21 @@ function writePublicEndpoints(workspaceDir, layers) {
     };
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(workspaceDir, config_1.PUBLIC_ENDPOINTS_FILE), `${JSON.stringify(declared, null, 2)}\n`);
 }
+function holdsValue(value) {
+    if (typeof value === "string")
+        return value !== "";
+    if (value !== null && typeof value === "object")
+        return Object.values(value).some(holdsValue);
+    return false;
+}
 function writeServerOptions(workspaceDir, layers) {
     const modules = Object.fromEntries(layers.flatMap((layer) => layer.privateOptions
         ? [[(0, layers_1.getLayerSafeName)(layer), layer.privateOptions]]
         : []));
-    (0, config_1.writeSecretBearingFile)((0, node_path_1.join)(workspaceDir, config_1.SERVER_OPTIONS_FILE), `${JSON.stringify({ modules, environment: manifest_secrets_1.MANIFEST_SECRET_ENV }, null, 2)}\n`);
+    const write = Object.values(modules).some(holdsValue)
+        ? config_1.writeSecretBearingFile
+        : config_1.writeShareableFile;
+    write((0, node_path_1.join)(workspaceDir, config_1.SERVER_OPTIONS_FILE), `${JSON.stringify({ modules, environment: manifest_secrets_1.MANIFEST_SECRET_ENV }, null, 2)}\n`);
 }
 function writeFrontendModuleRegistry(workspaceDir, layers) {
     const registry = (0, derived_outputs_1.createFrontendModuleRegistry)(workspaceDir, layers);

package/dist/module-set.d.ts

@@ -14,3 +14,14 @@ export interface ModuleSetFollowOptions {
 export declare function moduleSetFingerprint(modules: readonly ModuleSetMember[]): string;
 export declare function followModuleSet(options: ModuleSetFollowOptions): () => void;
 export declare function reportFrontendReady(backendUrl: string, moduleNames: readonly string[], bootstrapSecret?: string): Promise<boolean>;
+export type BuildDrift = {
+    status: "matches";
+    served: string;
+} | {
+    status: "drifted";
+    served: string;
+} | {
+    status: "unknown";
+    reason: string;
+};
+export declare function compareWithBackend(backendUrl: string, builtDigest: string, digestOf: (modules: readonly ManifestModule[]) => string, bootstrapSecret?: string): Promise<BuildDrift>;

package/dist/module-set.js

@@ -4,6 +4,7 @@ exports.MODULE_SET_POLL_INTERVAL_MS = void 0;
 exports.moduleSetFingerprint = moduleSetFingerprint;
 exports.followModuleSet = followModuleSet;
 exports.reportFrontendReady = reportFrontendReady;
+exports.compareWithBackend = compareWithBackend;
 const manifest_1 = require("./manifest");
 const workspace_1 = require("./workspace");
 exports.MODULE_SET_POLL_INTERVAL_MS = 3000;
@@ -82,3 +83,20 @@ async function reportFrontendReady(backendUrl, moduleNames, bootstrapSecret) {
         return false;
     }
 }
+const DRIFT_CHECK_TIMEOUT_MS = 10_000;
+async function compareWithBackend(backendUrl, builtDigest, digestOf, bootstrapSecret) {
+    try {
+        const manifest = await Promise.race([
+            (0, manifest_1.fetchManifest)(backendUrl, undefined, bootstrapSecret),
+            new Promise((_resolve, reject) => setTimeout(() => reject(new Error("the backend did not answer in time")), DRIFT_CHECK_TIMEOUT_MS).unref()),
+        ]);
+        const served = digestOf(manifest.modules);
+        return { status: served === builtDigest ? "matches" : "drifted", served };
+    }
+    catch (error) {
+        return {
+            status: "unknown",
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist/private-values.d.ts

@@ -0,0 +1,9 @@
+import type { FrontendModuleOptions, ManifestModule } from "./workspace";
+export declare function withoutPrivateValues(modules: readonly ManifestModule[]): ManifestModule[];
+export declare const PRIVATE_OPTIONS_VARIABLE = "DMS_PRIVATE_OPTIONS";
+export interface UnfilledPrivateValue {
+    module: string;
+    path: string[];
+}
+export declare function parsePrivateOptions(raw: string | undefined): Record<string, FrontendModuleOptions>;
+export declare function unfilledPrivateValues(modules: Readonly<Record<string, FrontendModuleOptions>>, given: Readonly<Record<string, FrontendModuleOptions>>, covered: readonly (readonly string[])[]): UnfilledPrivateValue[];

package/dist/private-values.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRIVATE_OPTIONS_VARIABLE = void 0;
+exports.withoutPrivateValues = withoutPrivateValues;
+exports.parsePrivateOptions = parsePrivateOptions;
+exports.unfilledPrivateValues = unfilledPrivateValues;
+const config_1 = require("./config");
+function emptied(value) {
+    if (typeof value === "string")
+        return "";
+    if (Array.isArray(value))
+        return value.map(emptied);
+    if (value !== null && typeof value === "object")
+        return emptiedOptions(value);
+    return value;
+}
+function emptiedOptions(options) {
+    return Object.fromEntries(Object.entries(options).map(([key, value]) => [key, emptied(value)]));
+}
+function withoutPrivateValues(modules) {
+    return modules.map((module) => module.privateOptions
+        ? { ...module, privateOptions: emptiedOptions(module.privateOptions) }
+        : { ...module });
+}
+exports.PRIVATE_OPTIONS_VARIABLE = "DMS_PRIVATE_OPTIONS";
+function isOptions(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parsePrivateOptions(raw) {
+    if (!raw?.trim())
+        return {};
+    let given;
+    try {
+        given = JSON.parse(raw);
+    }
+    catch {
+        given = undefined;
+    }
+    if (!isOptions(given) || !Object.values(given).every(isOptions)) {
+        throw new config_1.UsageError({
+            title: `${exports.PRIVATE_OPTIONS_VARIABLE} is not a JSON object of options by module id`,
+            fixes: [
+                `Set it like ${exports.PRIVATE_OPTIONS_VARIABLE}='{"<module id>":{"<option>":"<value>"}}', with the ids of generated-server-options.json`,
+            ],
+        });
+    }
+    return given;
+}
+function readPath(options, path) {
+    let value = options;
+    for (const key of path) {
+        if (typeof value !== "object" || value === null)
+            return undefined;
+        if (!Object.prototype.hasOwnProperty.call(value, key))
+            return undefined;
+        value = value[key];
+    }
+    return value;
+}
+function* emptyStrings(value, path = []) {
+    if (value === "")
+        yield path;
+    else if (typeof value === "object" && value !== null)
+        for (const [key, child] of Object.entries(value))
+            yield* emptyStrings(child, [...path, key]);
+}
+function unfilledPrivateValues(modules, given, covered) {
+    const isCovered = (path) => covered.some((other) => other.length === path.length &&
+        other.every((key, index) => key === path[index]));
+    return Object.entries(modules).flatMap(([module, options]) => [...emptyStrings(options)]
+        .filter((path) => path.length > 0 && !isCovered(path))
+        .filter((path) => {
+        const value = readPath(given[module], path);
+        return typeof value !== "string" || value === "";
+    })
+        .map((path) => ({ module, path })));
+}

package/dist/snapshot.d.ts

@@ -0,0 +1,25 @@
+import type { Manifest, ManifestModule } from "./workspace";
+export declare const SNAPSHOT_FILE = "snapshot.json";
+export declare const SNAPSHOT_LAYERS_DIR = "layers";
+export declare const BUILD_ORIGIN_FILE = ".build-origin.json";
+declare const SNAPSHOT_FORMAT = 1;
+export interface FrontendSnapshot {
+    format: typeof SNAPSHOT_FORMAT;
+    backendUrl: string;
+    takenAt: string;
+    digest: string;
+    manifest: Manifest;
+}
+export interface BuildOrigin {
+    source: "snapshot" | "backend";
+    backendUrl: string;
+    takenAt: string;
+    digest: string;
+    authenticated: boolean;
+}
+export declare function manifestDigest(modules: readonly ManifestModule[]): string;
+export declare function writeSnapshot(dir: string, backendUrl: string, manifest: Manifest, layersSource: string): FrontendSnapshot;
+export declare function readSnapshot(dir: string): FrontendSnapshot;
+export declare function writeBuildOrigin(workspaceDir: string, origin: BuildOrigin): void;
+export declare function readBuildOrigin(workspaceDir: string): BuildOrigin | undefined;
+export {};

package/dist/snapshot.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILD_ORIGIN_FILE = exports.SNAPSHOT_LAYERS_DIR = exports.SNAPSHOT_FILE = void 0;
+exports.manifestDigest = manifestDigest;
+exports.writeSnapshot = writeSnapshot;
+exports.readSnapshot = readSnapshot;
+exports.writeBuildOrigin = writeBuildOrigin;
+exports.readBuildOrigin = readBuildOrigin;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const cli_1 = require("@antelopejs/core/cli");
+const config_1 = require("./config");
+const module_set_1 = require("./module-set");
+const private_values_1 = require("./private-values");
+exports.SNAPSHOT_FILE = "snapshot.json";
+exports.SNAPSHOT_LAYERS_DIR = "layers";
+exports.BUILD_ORIGIN_FILE = ".build-origin.json";
+const SNAPSHOT_FORMAT = 1;
+const DIGEST_LENGTH = 16;
+function manifestDigest(modules) {
+    return (0, node_crypto_1.createHash)("sha256")
+        .update((0, module_set_1.moduleSetFingerprint)(modules.map(({ path: _path, ...module }) => module)))
+        .digest("hex")
+        .slice(0, DIGEST_LENGTH);
+}
+function writeSnapshot(dir, backendUrl, manifest, layersSource) {
+    const modules = (0, private_values_1.withoutPrivateValues)(manifest.modules).map(({ path: _path, ...module }) => module);
+    const snapshot = {
+        format: SNAPSHOT_FORMAT,
+        backendUrl: (0, config_1.canonicalizeBackendUrl)(backendUrl),
+        takenAt: new Date().toISOString(),
+        digest: manifestDigest(modules),
+        manifest: { pack: manifest.pack, modules },
+    };
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    const layers = (0, node_path_1.join)(dir, exports.SNAPSHOT_LAYERS_DIR);
+    (0, node_fs_1.rmSync)(layers, { recursive: true, force: true });
+    (0, node_fs_1.cpSync)(layersSource, layers, { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(dir, exports.SNAPSHOT_FILE), `${JSON.stringify(snapshot, null, 2)}\n`);
+    return snapshot;
+}
+function readSnapshot(dir) {
+    const file = (0, node_path_1.join)(dir, exports.SNAPSHOT_FILE);
+    const refresh = "Take one: ajs dms snapshot -b <backend url> -o <dir>";
+    if (!(0, node_fs_1.existsSync)(file)) {
+        throw new cli_1.CliError({
+            title: `No snapshot in ${dir}`,
+            reason: `${exports.SNAPSHOT_FILE} is missing.`,
+            fixes: [refresh],
+        });
+    }
+    let snapshot;
+    try {
+        snapshot = JSON.parse((0, node_fs_1.readFileSync)(file, "utf8"));
+    }
+    catch (error) {
+        throw new cli_1.CliError({ title: `${file} is not valid JSON`, fixes: [refresh] }, { cause: error });
+    }
+    if (snapshot.format !== SNAPSHOT_FORMAT ||
+        !Array.isArray(snapshot.manifest?.modules) ||
+        typeof snapshot.backendUrl !== "string") {
+        throw new cli_1.CliError({
+            title: `${file} is not a snapshot this loader can build from`,
+            reason: `It needs format ${SNAPSHOT_FORMAT}, a backend URL and a manifest.`,
+            fixes: [refresh],
+        });
+    }
+    if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(dir, exports.SNAPSHOT_LAYERS_DIR))) {
+        throw new cli_1.CliError({
+            title: `The snapshot in ${dir} has no ${exports.SNAPSHOT_LAYERS_DIR} directory`,
+            fixes: [refresh],
+        });
+    }
+    return snapshot;
+}
+function writeBuildOrigin(workspaceDir, origin) {
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(workspaceDir, exports.BUILD_ORIGIN_FILE), `${JSON.stringify(origin, null, 2)}\n`);
+}
+function readBuildOrigin(workspaceDir) {
+    try {
+        const origin = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(workspaceDir, exports.BUILD_ORIGIN_FILE), "utf8"));
+        return typeof origin.digest === "string"
+            ? origin
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/workspace-setup.d.ts

@@ -2,6 +2,7 @@ import { type ChildProcess, type SpawnOptions } from "node:child_process";
 import { type PathMapper } from "./child-output";
 import { type ManifestSecrets } from "./manifest-secrets";
 import { ResolvedLayer } from "./workspace";
+import { type BuildOrigin, type FrontendSnapshot } from "./snapshot";
 export declare function computeDepsHash(layerPaths: string[], workspacePackage?: string, installInputs?: readonly string[]): string;
 export declare function needsInstall(workspaceDir: string, layerPaths: string[], force: boolean): boolean;
 export declare function saveDepsHash(workspaceDir: string, layerPaths: string[]): void;
@@ -27,6 +28,11 @@ export interface SetupWorkspaceOptions {
     clientUrl?: string;
     workspaceKey?: string;
     bootstrapSecret?: string;
+    workspaceDir?: string;
+    snapshot?: {
+        dir: string;
+        snapshot: FrontendSnapshot;
+    };
     beforeInstall?: () => Promise<void>;
 }
 export interface SetupWorkspaceResult {
@@ -35,5 +41,6 @@ export interface SetupWorkspaceResult {
     manifestFromCache: boolean;
     manifestFetchedAt?: string;
     manifestSecrets: ManifestSecrets;
+    buildOrigin: BuildOrigin;
 }
 export declare function setupWorkspace(opts: SetupWorkspaceOptions): Promise<SetupWorkspaceResult>;

package/dist/workspace-setup.js

@@ -19,6 +19,7 @@ const manifest_secrets_1 = require("./manifest-secrets");
 const renderer_range_1 = require("./renderer-range");
 const materialize_1 = require("./materialize");
 const workspace_1 = require("./workspace");
+const snapshot_1 = require("./snapshot");
 const cancellation_1 = require("./cancellation");
 const output_1 = require("./output");
 const config_1 = require("./config");
@@ -219,14 +220,25 @@ function manifestCacheUse(mode, offline) {
         return "offline";
     return mode === "build" ? "never" : "fallback";
 }
-async function setupWorkspace(opts) {
+async function snapshotLayers({ dir, snapshot }, workspaceDir) {
+    const { manifest, takenAt } = snapshot;
+    const cacheDir = (0, node_path_1.join)(dir, snapshot_1.SNAPSHOT_LAYERS_DIR);
+    (0, layers_1.assertCachedArchivesExist)(manifest.modules, cacheDir, takenAt);
+    (0, manifest_1.writeCachedManifest)(workspaceDir, manifest, "drop", takenAt);
+    return {
+        manifest,
+        fromCache: false,
+        layers: await (0, layers_1.buildLayersFromCache)(manifest.modules, cacheDir),
+    };
+}
+async function servedLayers(opts, workspaceDir) {
     const { backendUrl, force, mode, offline, clientUrl, bootstrapSecret } = opts;
-    const workspaceKey = opts.workspaceKey ?? (0, config_1.canonicalizeBackendUrl)(backendUrl);
-    const workspaceDir = (0, workspace_1.ensureWorkspace)(workspaceKey);
-    (0, workspace_1.writeWorkspaceMeta)(workspaceDir, backendUrl, workspaceKey);
-    const resolved = await (0, manifest_1.resolveManifest)(workspaceDir, backendUrl, manifestCacheUse(mode, offline), clientUrl, bootstrapSecret);
+    const resolved = await (0, manifest_1.resolveManifest)(workspaceDir, backendUrl, manifestCacheUse(mode, offline), {
+        clientUrl,
+        bootstrapSecret,
+        privateValues: mode === "build" ? "drop" : "keep",
+    });
     const { manifest, fromCache, fetchedAt } = resolved;
-    let layers;
     if (mode === "dev") {
         (0, layers_1.assertLayerPathsServed)(manifest.modules, backendUrl, {
             bootstrapSecret,
@@ -235,26 +247,45 @@ async function setupWorkspace(opts) {
         if (fromCache) {
             (0, manifest_1.assertCachedLayerPathsExist)(manifest.modules, fetchedAt);
         }
-        layers = (0, layers_1.buildLayersFromPaths)(manifest.modules);
+        return { ...resolved, layers: (0, layers_1.buildLayersFromPaths)(manifest.modules) };
     }
-    else {
-        const cacheDir = (0, node_path_1.join)(workspaceDir, ".layers-cache");
-        if (fromCache) {
-            if (!(0, node_fs_1.existsSync)(cacheDir)) {
-                throw new cli_1.CliError({
-                    title: "No layers archive was downloaded for this workspace",
-                    fixes: [
-                        "Run once without --offline, with the backend reachable, first",
-                    ],
-                });
-            }
-            (0, layers_1.assertCachedArchivesExist)(manifest.modules, cacheDir, fetchedAt);
+    const cacheDir = (0, node_path_1.join)(workspaceDir, ".layers-cache");
+    if (fromCache) {
+        if (!(0, node_fs_1.existsSync)(cacheDir)) {
+            throw new cli_1.CliError({
+                title: "No layers archive was downloaded for this workspace",
+                fixes: [
+                    "Run once without --offline, with the backend reachable, first",
+                ],
+            });
         }
-        else {
-            await (0, layers_1.downloadAndExtractLayers)(backendUrl, manifest.pack, cacheDir, force, bootstrapSecret);
-        }
-        layers = await (0, layers_1.buildLayersFromCache)(manifest.modules, cacheDir);
+        (0, layers_1.assertCachedArchivesExist)(manifest.modules, cacheDir, fetchedAt);
+    }
+    else {
+        await (0, layers_1.downloadAndExtractLayers)(backendUrl, manifest.pack, cacheDir, force, bootstrapSecret);
     }
+    return {
+        ...resolved,
+        layers: await (0, layers_1.buildLayersFromCache)(manifest.modules, cacheDir),
+    };
+}
+async function setupWorkspace(opts) {
+    const { backendUrl, force } = opts;
+    const workspaceKey = opts.workspaceKey ?? (0, config_1.canonicalizeBackendUrl)(backendUrl);
+    const workspaceDir = opts.workspaceDir
+        ? (0, workspace_1.ensureExplicitWorkspace)(opts.workspaceDir)
+        : (0, workspace_1.ensureWorkspace)(workspaceKey);
+    (0, workspace_1.writeWorkspaceMeta)(workspaceDir, backendUrl, workspaceKey);
+    const { manifest, fromCache, fetchedAt, layers } = opts.snapshot
+        ? await snapshotLayers(opts.snapshot, workspaceDir)
+        : await servedLayers(opts, workspaceDir);
+    const buildOrigin = {
+        source: opts.snapshot ? "snapshot" : "backend",
+        backendUrl: (0, config_1.canonicalizeBackendUrl)(backendUrl),
+        takenAt: opts.snapshot?.snapshot.takenAt ?? fetchedAt ?? new Date().toISOString(),
+        digest: (0, snapshot_1.manifestDigest)(manifest.modules),
+        authenticated: !!opts.snapshot || (!!opts.bootstrapSecret && !fromCache),
+    };
     (0, renderer_range_1.assertLayersSupportRenderer)(layers, { workspaceDir });
     (0, materialize_1.copyStaticTemplates)(workspaceDir);
     (0, materialize_1.writeWorkspacePackageJson)(workspaceDir, layers);
@@ -274,5 +305,6 @@ async function setupWorkspace(opts) {
         manifestFromCache: fromCache,
         manifestFetchedAt: fetchedAt,
         manifestSecrets: (0, manifest_secrets_1.collectManifestSecrets)(manifest.modules),
+        buildOrigin,
     };
 }

package/dist/workspace.d.ts

@@ -56,6 +56,7 @@ export declare function projectWorkspaceKey(projectDir: string): string;
 export declare function projectDirFromWorkspaceKey(workspaceKey: string | undefined): string | undefined;
 export declare function getWorkspaceDir(backendUrl: string): string;
 export declare function ensureWorkspace(workspaceKey: string): string;
+export declare function ensureExplicitWorkspace(dir: string): string;
 export interface WorkspaceEntry {
     dir: string;
     backendUrl: string;

package/dist/workspace.js

@@ -6,6 +6,7 @@ exports.projectWorkspaceKey = projectWorkspaceKey;
 exports.projectDirFromWorkspaceKey = projectDirFromWorkspaceKey;
 exports.getWorkspaceDir = getWorkspaceDir;
 exports.ensureWorkspace = ensureWorkspace;
+exports.ensureExplicitWorkspace = ensureExplicitWorkspace;
 exports.listWorkspaces = listWorkspaces;
 exports.directorySize = directorySize;
 exports.writeWorkspaceMeta = writeWorkspaceMeta;
@@ -38,6 +39,11 @@ function ensureWorkspace(workspaceKey) {
     (0, node_fs_1.chmodSync)(dir, config_1.WORKSPACE_DIR_MODE);
     return dir;
 }
+function ensureExplicitWorkspace(dir) {
+    const absolute = (0, node_path_1.resolve)(dir);
+    (0, node_fs_1.mkdirSync)(absolute, { recursive: true });
+    return absolute;
+}
 function listWorkspaces() {
     const listing = { workspaces: [], skipped: [] };
     if (!(0, node_fs_1.existsSync)(config_1.DMS_FRONTEND_HOME))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-frontend",
-  "version": "0.6.4",
+  "version": "0.7.1",
   "description": "Frontend-agnostic loader for AntelopeJS DMS, shipping the Vue 3 renderer (Vite, Inertia, SSR)",
   "keywords": [
     "antelope",

package/templates/vue/server/backend-response.mjs

@@ -4,7 +4,7 @@
 // allows.
 
 import { GENERIC_ERROR_MESSAGE } from "./auth/backend.mjs";
-import { isColdStart } from "./backend-wake.mjs";
+import { isWaitable } from "./backend-wake.mjs";
 import { isFrontendVisit, redirectFrontendVisit } from "./inertia.mjs";
 
 // What a JSON caller gets when the backend fails: the generic i18n key of the
@@ -47,7 +47,7 @@ async function refusalCode(response) {
 
 /** The error for a failed backend response, with its typed code if any. */
 export async function backendResponseError(response) {
-  const retryAfter = isColdStart(response)
+  const retryAfter = isWaitable(response)
     ? (response.headers.get("retry-after") ?? undefined)
     : undefined;
   return new BackendResponseError(

package/templates/vue/server/backend-wake.mjs

@@ -1,14 +1,14 @@
-// Waiting out a backend the platform is waking from sleep.
+// Waiting out a backend that is waking from sleep or still starting.
 //
 // A platform that scales the backend to zero answers the first requests with
 // a 503 while it starts a replica, marked with the cold-start header and a
-// Retry-After in whole seconds: all three make the signal, and a 503 missing
-// one of them goes out as it came. The header is a reserved resume
-// convention, not a proof of where the answer came from: a backend may set it
-// too, and then gets the same bounded wait. Only a GET or a HEAD is repeated;
-// a POST, PATCH or DELETE is sent once.
+// Retry-After in whole seconds; a DMS backend that listens before it is ready
+// answers 503 with a Retry-After too, without the header. A 503 with a
+// Retry-After in whole seconds is the signal, with or without the header; a
+// 503 without one goes out as it came. Only a GET or a HEAD is repeated; a
+// POST, PATCH or DELETE is sent once.
 //
-// The wait starts with the first cold-start answer and lasts at most the
+// The wait starts with the first waitable answer and lasts at most the
 // budget, the repeated requests included: one still waiting for its answer
 // when the budget runs out is aborted, and no request starts after it. It
 // ends at once when the client leaves.
@@ -18,7 +18,7 @@
 
 import { setTimeout as sleep } from "node:timers/promises";
 
-/** Header marking a 503 as a cold start to wait out. */
+/** Header a platform marks the 503 of a backend it is waking with. */
 export const COLD_START_HEADER = "x-antelope-cold-start";
 const COLD_START_VALUE = "1";
 const UNAVAILABLE = 503;
@@ -34,12 +34,14 @@ const MS_PER_SECOND = 1_000;
 const WHOLE_SECONDS = /^\d+$/;
 const WHOLE_MILLISECONDS = /^\d+$/;
 
-/** Whether `response` is a 503 marked as a cold start, with its Retry-After. */
-export function isColdStart(response) {
+/**
+ * Whether `response` is a 503 asking to come back after a Retry-After in
+ * whole seconds: a platform waking the backend (with the cold-start header)
+ * or a backend still starting.
+ */
+export function isWaitable(response) {
   return (
-    response.status === UNAVAILABLE &&
-    response.headers.get(COLD_START_HEADER) === COLD_START_VALUE &&
-    WHOLE_SECONDS.test(retryAfter(response))
+    response.status === UNAVAILABLE && WHOLE_SECONDS.test(retryAfter(response))
   );
 }
 
@@ -57,7 +59,7 @@ export function wakeBudgetMs(env = process.env) {
   return WHOLE_MILLISECONDS.test(raw) ? Number(raw) : DEFAULT_BUDGET_MS;
 }
 
-/** The pause a cold-start answer's Retry-After asks for, kept between bounds. */
+/** The pause a waitable answer's Retry-After asks for, kept between bounds. */
 function retryDelayMs(response) {
   return Math.min(
     MAX_DELAY_MS,
@@ -66,17 +68,15 @@ function retryDelayMs(response) {
 }
 
 /**
- * What the client gets once the budget is spent: the last cold-start answer's
- * status and headers, without the body its pause already discarded.
+ * What the client gets once the budget is spent: the last waitable answer's
+ * status, Retry-After and cold-start header if it had one, without the body
+ * its pause already discarded.
  */
 function expired(cold) {
-  return new Response(null, {
-    status: UNAVAILABLE,
-    headers: {
-      [COLD_START_HEADER]: COLD_START_VALUE,
-      "retry-after": retryAfter(cold),
-    },
-  });
+  const headers = { "retry-after": retryAfter(cold) };
+  if (cold.headers.get(COLD_START_HEADER) === COLD_START_VALUE)
+    headers[COLD_START_HEADER] = COLD_START_VALUE;
+  return new Response(null, { status: UNAVAILABLE, headers });
 }
 
 /**
@@ -102,9 +102,9 @@ async function repeat(url, init, deadline, now) {
 }
 
 /**
- * `fetch`, waiting out cold-start answers to a GET or a HEAD until `budgetMs`
+ * `fetch`, waiting out waitable 503s to a GET or a HEAD until `budgetMs`
  * from the first of them is spent or MAX_REPEATS repeats are sent. Then the
- * caller gets a cold-start 503 with its `Retry-After` to relay. The client
+ * caller gets the 503 with its `Retry-After` to relay. The client
  * leaving, through `init.signal`, ends the wait with its AbortError.
  */
 export async function fetchWaking(
@@ -116,7 +116,7 @@ export async function fetchWaking(
   let response = await fetch(url, init);
   if (!RETRYABLE_METHODS.has(method)) return response;
   const deadline = now() + budgetMs;
-  for (let repeats = 0; isColdStart(response); repeats += 1) {
+  for (let repeats = 0; isWaitable(response); repeats += 1) {
     const cold = response;
     const delay = retryDelayMs(cold);
     if (repeats >= MAX_REPEATS || now() + delay > deadline) return cold;