@edgehero/pi-dispatch 1.10.3 → 2.1.0

package/src/backend-registry.mjs

@@ -1,3 +1,6 @@
+// The one import this module takes, and it is an import-free leaf for that reason (issue #339).
+import { scrubCredentials } from "./redact.mjs";
+
 /**
  * Reap several backends and combine the tri-state CONSERVATIVELY.
  *
@@ -29,13 +32,80 @@ export async function reapAll(reaps = [], { log = () => {} } = {}) {
 			// catch reached the caller before this function existed, and the caller logged it. Swallowing it
 			// here without a word would delete an operator-visible signal about a venue that could not be
 			// swept, so the log seam is threaded through rather than assumed to be somebody else's job.
-			log("reaper_skipped", { reason: err?.message });
+			log("reaper_skipped", { reason: scrubCredentials(err?.message) });
 			reaped = false;
 		}
 	}
 	return { reaped };
 }
 
+/**
+ * The `code` on the error the registry throws for a venue it does not hold, and ONLY that error.
+ *
+ * A CODE, not a message match: the processor catches this one refusal at pickup (a venue this worker never
+ * built is refused and recorded rather than retried) and must let every OTHER throw through -- a registered
+ * venue's own `containerName` failing is a broken adapter, and swallowing that would run the job under a
+ * null container name that nothing could stop by name.
+ */
+export const BACKEND_NOT_REGISTERED = "BACKEND_NOT_REGISTERED";
+
+/**
+ * The per-venue preflights a bundle MAY carry (issue #354), each with what a venue that carries none answers.
+ *
+ * OPTIONAL, not in the required list, because requiring them would break every adapter written against the
+ * five-function contract `docs/backends.md` publishes, and because the absent answer is not a guess: it is what
+ * every non-local venue got before this, when both were `start.mjs` closures that returned exactly these for
+ * any venue but `local`. `observationPreflight` admits (nothing about this host is observed for a venue with no
+ * `observedBy`), and `jobUserPreflight` runs the image's own USER. Kept equal to the processor's own defaults for
+ * those two deps, so a wiring that omits the registry and one whose venue omits the member agree.
+ *
+ * What absence cannot be is SAFE for a venue whose table entry is observation-gated: that venue's words would
+ * then hold with nothing observing them. `start.mjs` refuses such a bundle at boot, because this module cannot
+ * read the table (it imports only the redactor).
+ */
+export const OPTIONAL_PREFLIGHT_DEFAULTS = Object.freeze({
+	observationPreflight: () => ({ ok: true }),
+	jobUserPreflight: () => ({ user: null, home: null }),
+});
+
+/** The venue's own member when it carries one, else the absent answer, as a promise either way. */
+async function optionalPreflight(bundle, fn, ...args) {
+	return typeof bundle[fn] === "function" ? bundle[fn](...args) : OPTIONAL_PREFLIGHT_DEFAULTS[fn]();
+}
+
+/**
+ * The NAME of the venue a job resolves to: its own `run.backend`, else the deployment default.
+ *
+ * ONE DERIVATION FOR DISPATCH AND FOR EVERY STORE THAT RECORDS A VENUE (issue #277). The registry dispatches
+ * on it and the run record writes it down. A copy of the expression per store would be one more place a
+ * later change could land in one and not the others, and the whole value of a recorded venue is that it IS
+ * what dispatched: a record naming a venue the registry did not choose is an audit trail that lies.
+ *
+ * ABSENT MEANS THE KEY IS ABSENT, `undefined` and nothing else. The loader writes no `backend` key for a
+ * trigger that names no venue, and the processor's blessed gate tests `!== undefined`, so an explicit `null`
+ * is a NAME the gate refuses rather than a request for the default. Resolving it with `??` would record the
+ * default on a job the processor refused for naming something else. No producer writes a null today; this
+ * keeps the three readers agreeing if one ever does.
+ *
+ * TAKES JOB DATA, NEVER THE BULLMQ WRAPPER. A wrapper's own keys are `id` and `data`, so `wrapper.backend`
+ * is always undefined and every job would resolve to the default in silence -- the defect `index.mjs`
+ * records beside `containerName`, which shipped once. Callers holding a wrapper pass `wrapper.data`.
+ *
+ * `null` WHEN NEITHER IS KNOWN, never a guessed `local`. Only a dependency-injection seam reaches that (every
+ * wired caller is handed `config.defaultBackend`), and a consumer must fail closed on it: the record stores
+ * the null, and the registry refuses a job it cannot name. A default here would hide a dropped wire today and
+ * become a wrong answer the day `PI_BACKENDS` names a remote venue first.
+ *
+ * HERE rather than in `backends.mjs`, whose `backendFor(name)` falls back to the TABLE's default -- a
+ * different question, and putting the two side by side invites answering one with the other. And a free
+ * function rather than a registry method, because a store constructed in `startWorker` before any bundle
+ * exists could not reach one -- the temporal dead zone `reapAll` above already records.
+ */
+export function resolveBackendName(data, defaultName) {
+	const named = data?.backend;
+	return named !== undefined ? named : (defaultName ?? null);
+}
+
 /**
  * WHICH backend runs THIS job, and the one place that decides (issue #227).
  *
@@ -83,6 +153,12 @@ export function makeBackendRegistry({ bundles = [], defaultName, blessed = null,
 			// exactly the case the list exists to refund.
 			throw new Error(`backend registry: ${JSON.stringify(bundle.name)} must declare neverStartedExits as an array of integers ([] if it normalises to container-never-started itself)`);
 		}
+		// OPTIONAL, but a present one must be callable (issue #354). Absent is a real answer, today's non-local
+		// behaviour (see `OPTIONAL_PREFLIGHT_DEFAULTS`); a truthy non-function is a typo'd adapter, and admitting it would
+		// land as a TypeError on the pre-spend path at the first pickup, the failure the required list above exists for.
+		for (const fn of Object.keys(OPTIONAL_PREFLIGHT_DEFAULTS)) {
+			if (bundle[fn] !== undefined && typeof bundle[fn] !== "function") throw new Error(`backend registry: ${JSON.stringify(bundle.name)} has a ${fn} that is not a function`);
+		}
 		byName.set(bundle.name, bundle);
 	}
 	if (byName.size === 0) throw new Error("backend registry: at least one backend must be registered");
@@ -117,10 +193,12 @@ export function makeBackendRegistry({ bundles = [], defaultName, blessed = null,
 
 	/** The bundle this job runs in. Throws for a name no gate should have let through. */
 	function backendFor(job) {
-		const name = job?.backend ?? defaultName;
+		const name = resolveBackendName(job, defaultName);
 		const bundle = byName.get(name);
 		if (!bundle) {
-			throw new Error(`backend registry: no backend named ${JSON.stringify(name)} is registered (have: ${[...byName.keys()].join(", ")})`);
+			const err = new Error(`backend registry: no backend named ${JSON.stringify(name)} is registered (have: ${[...byName.keys()].join(", ")})`);
+			err.code = BACKEND_NOT_REGISTERED;
+			throw err;
 		}
 		return bundle;
 	}
@@ -140,6 +218,11 @@ export function makeBackendRegistry({ bundles = [], defaultName, blessed = null,
 		runContainer: (args) => backendFor(args?.job).runContainer(args),
 		imagePreflight: (job) => backendFor(job).imagePreflight(job),
 		egressPreflight: (job) => backendFor(job).egressPreflight(job),
+		// The two OPTIONAL per-venue preflights (issue #354), dispatched through the same resolution as every
+		// required one, so an unregistered name still throws BACKEND_NOT_REGISTERED rather than being waved
+		// through by a default. A venue that carries none gets the answer the processor's own defaults give.
+		observationPreflight: (job) => optionalPreflight(backendFor(job), "observationPreflight", job),
+		jobUserPreflight: (job, opts) => optionalPreflight(backendFor(job), "jobUserPreflight", job, opts),
 		stopContainer: (name, job) => backendFor(job).stopContainer(name, job),
 		// ON THE SURFACE, not reached for through `backendFor` by a call site. Both are per-job backend
 		// FACTS rather than functions, and an earlier draft left them off: the wiring rebuilt