UNPKG

everything-dev

Version:

A consolidated product package for building Module Federation apps with oRPC APIs.

437 lines (435 loc) • 13.9 kB
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