everything-dev
Version:
A consolidated product package for building Module Federation apps with oRPC APIs.
137 lines • 6.04 kB
text/typescript
import { PlatformReleaseManifest } from "../platform/manifest-schema.cjs";
import { ManifestCacheRead, ManifestCacheRecord } from "./cache.cjs";
import { RuntimeRef } from "./keys.cjs";
//#region src/services/registry/resolution.d.ts
interface ExtendsChainNode {
account: string;
gateway: string;
}
interface ExtendsChainWalk {
/** child → root, nearest first — `chain[0]` is the local extends target */
chain: ExtendsChainNode[];
/** the most rootward `repository` seen — parent configs override the child's */
repository?: string;
/** set when the walk revisits a node — a pathological extends chain */
circularAt?: string;
}
/**
* 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.
*/
declare function walkExtendsChain(input: {
localConfig: Record<string, unknown>;
localRepository?: string;
fetchParent?: (account: string, gateway: string) => Promise<Record<string, unknown> | null>;
}): Promise<ExtendsChainWalk>;
type ResolutionQuery = {
readonly kind: "Pinned";
readonly release: string;
readonly ref?: RuntimeRef;
} | {
readonly kind: "Latest";
readonly ref?: RuntimeRef;
};
/** What the tag home serves: the thin `{ version, digest }` pointer
* (post-cutover), the full manifest (the pre-cutover pointer), or nothing. */
type TagServes = "thin" | "full" | "none";
interface DeadEndContext {
ref: RuntimeRef;
/** The terminus's last registry write, when the history endpoint served one. */
lastWrite?: string;
}
/** A type alias (not an interface) so the shape stays assignable to
* `Record<string, unknown>` across the RPC contract boundary. */
type ResolutionContext = {
/** child → root, nearest first — the chain that was scanned */
chain: readonly RuntimeRef[];
tagServes: TagServes;
/** the node a read or parse failed on, when the outcome is unreachable */
failureAt?: {
account: string;
gateway: string;
};
/** set when the chain terminates at a runtime that publishes no manifest
* legs — "is this the runtime you meant?" */
deadEnd?: DeadEndContext;
};
type ResolutionOutcome = {
readonly state: "Resolved";
readonly manifest: PlatformReleaseManifest;
/** the chain node that served the bytes */
readonly source: {
account: string;
gateway: string;
};
/** which home resolved the query: a version record (pinned), the
* manifest tag (latest), or the cache stand-in */
readonly from: "version" | "manifest" | "cache";
readonly provenance: "slot" | "pointer";
readonly fromCache: boolean;
} | {
readonly state: "Unresolved";
readonly reason: "absent" | "unreachable" | "integrityFailure";
readonly detail?: string;
readonly context: ResolutionContext;
};
interface ResolutionSeams {
/** The tag home (`manifest.json` post-cutover). Null = absent; throws =
* unreachable. */
readManifestTag(ref: RuntimeRef): Promise<unknown>;
/** The immutable version record's raw bytes (the digest chain verifies
* over text). Null = absent; throws = unreachable. */
readVersionRecord(ref: RuntimeRef, release: string): Promise<string | null>;
/** Parse a full manifest or record payload. Throws on a corrupt payload —
* the machine records it as unreachable. */
parseManifest(value: unknown): PlatformReleaseManifest;
fetchParent(account: string, gateway: string): Promise<Record<string, unknown> | null>;
cacheRead(pin?: string): ManifestCacheRead;
cacheWrite(record: ManifestCacheRecord): void;
/** Best-effort last-write date for the dead-end diagnostic — failures are
* swallowed (the field is simply omitted). */
lastWriteAt?(ref: RuntimeRef): Promise<string | undefined>;
}
declare function resolveRelease(input: {
query: ResolutionQuery;
localConfig: Record<string, unknown>;
localRepository?: string;
/** The cache location for the default (pre-cutover) seams. */
configDir?: string;
/** Partial overrides over the production seams — the test hook. */
seams?: Partial<ResolutionSeams>;
fetchParent?: (account: string, gateway: string) => Promise<Record<string, unknown> | null>;
now?: () => number;
}): Promise<ResolutionOutcome>;
interface ResolvedPlatformManifest {
manifest: PlatformReleaseManifest;
source: {
account: string;
gateway: string;
};
fromCache: boolean;
/** Where the resolved bytes came from (#574): an immutable version record
* (an exact pin's target) or the moving tag (unpinned "latest"
* resolution). */
provenance: "slot" | "pointer";
}
type PlatformManifestCache = ManifestCacheRecord;
interface ResolvePlatformManifestOptions {
configDir: string;
localConfig: Record<string, unknown>;
fetchManifest?: (account: string, gateway: string) => Promise<PlatformReleaseManifest | null>;
/** The immutable version-record read (#574) — an exact pin's target.
* Throws on read failure (distinct from a clean absent record). */
fetchSlot?: (account: string, gateway: string, version: string) => Promise<unknown>;
fetchParent?: (account: string, gateway: string) => Promise<Record<string, unknown> | null>;
cacheRead?: () => PlatformManifestCache | null;
cacheWrite?: (cached: PlatformManifestCache) => void;
/** injectable clock for the cache-freshness check (test seam) */
now?: () => number;
/** injectable freshness bound (test seam); defaults to {@link MANIFEST_CACHE_TTL_MS} */
cacheTtlMs?: number;
}
declare function resolvePlatformManifest(opts: ResolvePlatformManifestOptions): Promise<ResolvedPlatformManifest | null>;
//#endregion
export { DeadEndContext, ExtendsChainNode, ExtendsChainWalk, PlatformManifestCache, ResolutionContext, ResolutionOutcome, ResolutionQuery, ResolutionSeams, ResolvePlatformManifestOptions, ResolvedPlatformManifest, TagServes, resolvePlatformManifest, resolveRelease, walkExtendsChain };
//# sourceMappingURL=resolution.d.cts.map