everything-dev
Version:
A consolidated product package for building Module Federation apps with oRPC APIs.
437 lines (435 loc) • 13.9 kB
JavaScript
import { parseRuntimeRef, runtimeRefOf } from "./keys.mjs";
import { fetchConfigHistory, fetchRegistryKey, fetchRegistryKeyOrNull } from "./fastkv.mjs";
import { getExtendsRef, parseBosRef } from "../../utils/bos-ref.mjs";
import { PlatformReleaseManifestSchema } from "../platform/manifest-schema.mjs";
import { fetchParentConfig } from "../resolution/init-source.mjs";
import { MANIFEST_CACHE_TTL_MS, readManifestCache, writeManifestCache } from "./cache.mjs";
import { createHash } from "node:crypto";
//#region src/services/registry/resolution.ts
/**
* The resolution state machine (sprint registry-primitive, ticket 03): one
* authored pin or latest query in, one structured outcome out.
*
* Queries: `Pinned | Latest → Resolved | Unresolved`.
* - `Pinned(ref, release)` scans the extends chain's version records —
* immutable, so a root release never strands a child pin (#574).
* - `Latest(ref)` reads the manifest tag — the moving pointer.
* - `Unresolved` carries a structured reason (`absent | unreachable |
* integrityFailure`) plus manifest context: what the tag serves, the
* extends chain walked, and the dead-end diagnostic — when the chain
* terminates at a runtime that publishes no manifest legs, the outcome
* says so with the terminus's last write date (the permanent lesson of
* the false FastKV data-loss alarm: `dev.everything.dev` is an abandoned
* dead-end gateway; the release root is `dev.everything.near/everything.dev`).
* - The thin-tag digest chain: post-cutover the tag is `{ version, digest }`;
* resolution verifies the digest against the fetched version record's bytes
* before returning — a mismatch is `Unresolved(integrityFailure)`, never a
* silent pass.
*
* The cache (`registry/cache.ts`) is the stand-in layer: pin-match + TTL,
* offline dev only. All I/O is injectable — the test seam.
*/
/**
* The ONE extends-chain walk (child → root via registry parent configs): the
* resolution machine and the upgrade source resolution share this
* implementation. A fetch failure (throw or null) stops the walk — the chain
* gathered so far is still returned.
*/
async function walkExtendsChain(input) {
const fetchParent = input.fetchParent ?? (async (account, gateway) => fetchParentConfig(account, gateway).then((config) => config).catch(() => null));
const chain = [];
let repository = input.localRepository;
const startsRef = getExtendsRef(input.localConfig);
let cursor = typeof startsRef === "string" && startsRef.startsWith("bos://") ? parseBosRef(startsRef) ?? null : null;
const visited = /* @__PURE__ */ new Set();
let circularAt;
while (cursor) {
const ref = `bos://${cursor.account}/${cursor.gateway}`;
if (visited.has(ref)) {
circularAt = ref;
break;
}
visited.add(ref);
chain.push(cursor);
const parentConfig = await fetchParent(cursor.account, cursor.gateway);
if (!parentConfig) break;
if (typeof parentConfig.repository === "string" && parentConfig.repository) repository = parentConfig.repository;
const nextRef = getExtendsRef(parentConfig);
cursor = typeof nextRef === "string" && nextRef.startsWith("bos://") ? parseBosRef(nextRef) ?? null : null;
}
return {
chain,
...repository !== void 0 ? { repository } : {},
...circularAt ? { circularAt } : {}
};
}
const refOf = (node) => runtimeRefOf({
accountId: node.account,
gatewayId: node.gateway
});
/** True when the tag payload is the thin `{ version, digest }` pointer —
* the post-cutover wire that carries its own integrity reference. */
function isThinTag(value) {
return typeof value === "object" && value !== null && typeof value.version === "string" && typeof value.digest === "string";
}
function sha256Hex(text) {
return createHash("sha256").update(text).digest("hex");
}
async function probeDeadEnd(seams, terminus) {
try {
if (await seams.readManifestTag(refOf(terminus))) return void 0;
} catch {}
const deadEnd = { ref: refOf(terminus) };
if (seams.lastWriteAt) try {
const lastWrite = await seams.lastWriteAt(refOf(terminus));
if (lastWrite) deadEnd.lastWrite = lastWrite;
} catch {}
return deadEnd;
}
async function resolveRelease(input) {
const now = input.now ?? Date.now;
const seams = {
...preCutoverSeams(input.configDir ?? process.cwd(), now),
...input.seams
};
const { chain } = await walkExtendsChain({
localConfig: input.localConfig,
...input.localRepository !== void 0 ? { localRepository: input.localRepository } : {},
...input.fetchParent ? { fetchParent: input.fetchParent } : {}
});
const chainRefs = chain.map(refOf);
const writeCache = (manifest, node, provenance) => {
seams.cacheWrite({
schemaVersion: 1,
kind: "everything-dev/platform-manifest-cache",
resolvedAt: new Date(now()).toISOString(),
source: {
account: node.account,
gateway: node.gateway
},
manifest,
provenance
});
};
const deadEndProbe = async () => {
const terminus = chain.at(-1);
return terminus ? probeDeadEnd(seams, terminus) : void 0;
};
if (input.query.kind === "Pinned") {
const release = input.query.release;
for (const node of chain) {
let text;
try {
text = await seams.readVersionRecord(refOf(node), release);
} catch (error) {
const cached = seams.cacheRead(release);
if (cached.state === "hit") return {
state: "Resolved",
manifest: cached.record.manifest,
source: cached.record.source,
from: "cache",
provenance: cached.record.provenance ?? "slot",
fromCache: true
};
return {
state: "Unresolved",
reason: "unreachable",
detail: error instanceof Error ? error.message : String(error),
context: {
chain: chainRefs,
tagServes: "none",
failureAt: node
}
};
}
if (text !== null) {
let manifest;
try {
manifest = seams.parseManifest(JSON.parse(text));
} catch (error) {
return {
state: "Unresolved",
reason: "unreachable",
detail: error instanceof Error ? error.message : String(error),
context: {
chain: chainRefs,
tagServes: "none",
failureAt: node
}
};
}
writeCache(manifest, node, "slot");
return {
state: "Resolved",
manifest,
source: {
account: node.account,
gateway: node.gateway
},
from: "version",
provenance: "slot",
fromCache: false
};
}
}
const deadEnd = await deadEndProbe();
return {
state: "Unresolved",
reason: "absent",
detail: "no version record in the extends chain" + (chainRefs.length > 0 ? ` (${chainRefs.join(" → ")})` : "") + ` — the release's manifest leg never published ${release}; re-run the release deploy (or \`bos upgrade\` to re-pin)`,
context: {
chain: chainRefs,
tagServes: "none",
...deadEnd ? { deadEnd } : {}
}
};
}
let unreachable;
let tagServes = "none";
for (const node of chain) {
let tag;
try {
tag = await seams.readManifestTag(refOf(node));
} catch (error) {
unreachable = {
detail: error instanceof Error ? error.message : String(error),
node
};
break;
}
if (!tag) continue;
if (isThinTag(tag)) {
tagServes = "thin";
let text;
try {
text = await seams.readVersionRecord(refOf(node), tag.version);
} catch (error) {
return {
state: "Unresolved",
reason: "unreachable",
detail: error instanceof Error ? error.message : String(error),
context: {
chain: chainRefs,
tagServes,
failureAt: node
}
};
}
if (text === null) return {
state: "Unresolved",
reason: "absent",
detail: `the manifest tag names ${tag.version} but its version record is absent at ${refOf(node)}`,
context: {
chain: chainRefs,
tagServes
}
};
if (sha256Hex(text) !== tag.digest) return {
state: "Unresolved",
reason: "integrityFailure",
detail: `the manifest tag's digest does not match the version record's bytes at ${refOf(node)} — refusing`,
context: {
chain: chainRefs,
tagServes
}
};
let manifest;
try {
manifest = seams.parseManifest(JSON.parse(text));
} catch (error) {
return {
state: "Unresolved",
reason: "unreachable",
detail: error instanceof Error ? error.message : String(error),
context: {
chain: chainRefs,
tagServes,
failureAt: node
}
};
}
writeCache(manifest, node, "pointer");
return {
state: "Resolved",
manifest,
source: {
account: node.account,
gateway: node.gateway
},
from: "manifest",
provenance: "pointer",
fromCache: false
};
}
tagServes = "full";
let manifest;
try {
manifest = seams.parseManifest(tag);
} catch (error) {
unreachable = {
detail: error instanceof Error ? error.message : String(error),
node
};
break;
}
writeCache(manifest, node, "pointer");
return {
state: "Resolved",
manifest,
source: {
account: node.account,
gateway: node.gateway
},
from: "manifest",
provenance: "pointer",
fromCache: false
};
}
if (unreachable) return {
state: "Unresolved",
reason: "unreachable",
detail: unreachable.detail,
context: {
chain: chainRefs,
tagServes,
failureAt: unreachable.node
}
};
const cached = seams.cacheRead();
if (cached.state === "hit") return {
state: "Resolved",
manifest: cached.record.manifest,
source: cached.record.source,
from: "cache",
provenance: cached.record.provenance ?? "pointer",
fromCache: true
};
const deadEnd = await deadEndProbe();
return {
state: "Unresolved",
reason: "absent",
context: {
chain: chainRefs,
tagServes,
...deadEnd ? { deadEnd } : {}
}
};
}
function tagKeyOf(account, gateway) {
return `apps/${account}/${gateway}/platform.json`;
}
function versionKeyOf(account, gateway, version) {
return `apps/${account}/${gateway}/platform-versions/${version}.json`;
}
function preCutoverSeams(configDir, now) {
return {
async readManifestTag(ref) {
const { accountId, gatewayId } = parseRuntimeRef(ref);
return await fetchRegistryKeyOrNull(accountId, gatewayId, "platform.json") ?? null;
},
async readVersionRecord(ref, release) {
const { accountId, gatewayId } = parseRuntimeRef(ref);
const raw = await fetchRegistryKey(accountId, gatewayId, versionKeyOf(accountId, gatewayId, release));
return raw === null ? null : JSON.stringify(raw);
},
parseManifest(value) {
return PlatformReleaseManifestSchema.parse(value);
},
fetchParent(account, gateway) {
return fetchParentConfig(account, gateway).then((config) => config).catch(() => null);
},
cacheRead(pin) {
return readManifestCache({
configDir,
...pin !== void 0 ? { pin } : {},
now
});
},
cacheWrite(record) {
writeManifestCache({
configDir,
record
});
},
async lastWriteAt(ref) {
try {
const { accountId, gatewayId } = parseRuntimeRef(ref);
const ns = (await fetchConfigHistory({
accountId,
gatewayId,
limit: 1,
keyPath: tagKeyOf(accountId, gatewayId)
}))[0]?.blockTimestampNs;
if (!ns) return void 0;
const ms = Number(ns) / 1e6;
return Number.isFinite(ms) ? new Date(ms).toISOString() : void 0;
} catch {
return;
}
}
};
}
async function resolvePlatformManifest(opts) {
const pin = typeof opts.localConfig.platform === "string" && opts.localConfig.platform ? opts.localConfig.platform : void 0;
const overrides = {};
if (opts.fetchManifest) overrides.readManifestTag = async (ref) => {
const { accountId, gatewayId } = parseRuntimeRef(ref);
return opts.fetchManifest(accountId, gatewayId);
};
if (opts.fetchSlot) overrides.readVersionRecord = async (ref, release) => {
const { accountId, gatewayId } = parseRuntimeRef(ref);
const raw = await opts.fetchSlot(accountId, gatewayId, release);
return raw === null || raw === void 0 ? null : JSON.stringify(raw);
};
if (opts.cacheRead) overrides.cacheRead = (pinKey) => {
const record = opts.cacheRead?.();
if (!record) return { state: "miss" };
const now = (opts.now ?? Date.now)();
const ttl = opts.cacheTtlMs ?? 864e5;
const resolvedAt = Date.parse(record.resolvedAt);
if (Number.isNaN(resolvedAt) || now - resolvedAt > ttl) return {
state: "stale",
record
};
if (pinKey !== void 0 && record.manifest.frameworkVersion !== pinKey) return {
state: "stale",
record
};
return {
state: "hit",
record
};
};
if (opts.cacheWrite) overrides.cacheWrite = (record) => opts.cacheWrite?.(record);
const outcome = await resolveRelease({
query: pin ? {
kind: "Pinned",
release: pin
} : { kind: "Latest" },
localConfig: opts.localConfig,
configDir: opts.configDir,
...opts.now ? { now: opts.now } : {},
...Object.keys(overrides).length > 0 ? { seams: overrides } : {},
...opts.fetchParent ? { fetchParent: opts.fetchParent } : {}
});
if (outcome.state === "Resolved") return {
manifest: outcome.manifest,
source: outcome.source,
fromCache: outcome.fromCache,
provenance: outcome.provenance
};
const chainUrls = outcome.context.chain.join(" → ");
if (outcome.reason === "unreachable") {
if (pin) {
const node = outcome.context.failureAt;
const slotKey = node ? versionKeyOf(node.account, node.gateway, pin) : `platform-versions/${pin}.json`;
throw new Error(`platform pin ${pin}: the version slot read failed (${slotKey}): ${outcome.detail}`);
}
throw new Error(outcome.detail ?? "the manifest tag read failed");
}
if (pin) throw new Error(`platform pin ${pin}: no version slot in the extends chain` + (chainUrls ? ` (${chainUrls})` : "") + ` — the release's manifest leg never published it; re-run the release deploy (or \`bos upgrade\` to re-pin)`);
return null;
}
//#endregion
export { resolvePlatformManifest, resolveRelease, walkExtendsChain };
//# sourceMappingURL=resolution.mjs.map