@bleedingdev/modern-js-federation-runtime 0.0.0 → 3.9.0-ultramodern.6

package/src/module-federation/last-known-good.ts

@@ -0,0 +1,292 @@
+// @effect-diagnostics asyncFunction:off strictBooleanExpressions:off
+/**
+ * G24a/b — last-known-good (LKG) provider wrapper.
+ *
+ * RESOLUTION-0001 §2.2: the LKG cache "wraps any provider; serves the last
+ * complete record on provider failure, marked `compatibility: 'degraded'`". It
+ * is universal — no DOM/fetch/framework coupling — so the same wrapper works in
+ * the browser, Node, and Cloudflare.
+ *
+ * Rollback semantics (ADR-0019 / CONTEXT.md Rollback): the delivery UNIT is
+ * the unit of rollback. The cache stores exactly ONE whole
+ * {@link ResolvedDeliveryUnit} per (unitId, env) key — never per (ref, env) —
+ * so every surface of a unit shares one snapshot and a fresh success swaps that
+ * snapshot atomically for all of them (two surfaces can never be served from
+ * different cached build markers). It never stores or serves a partial record,
+ * and it never mixes locations across build markers — a served degraded record
+ * is a byte-for-byte prior success with only its compatibility verdict flipped
+ * to `degraded`. Only a compatible record is promoted to last-known-good;
+ * degraded and incompatible provider results remain live responses without
+ * replacing the recovery snapshot. The ref's external-major participates in
+ * lookup validation but not in the storage key.
+ */
+import { selectResolvedSurface } from '@modern-js/surface-resolution';
+import {
+  createDiscoveryError,
+  type DiscoveryResult,
+  deliveryUnitResolutionKey,
+  type EnvironmentId,
+  type ParsedSurfaceRef,
+  type ResolvedDeliveryUnit,
+  type SurfaceResolutionProvider,
+} from './surface-resolution-types';
+
+export const LAST_KNOWN_GOOD_PROVIDER_NAME = 'last-known-good';
+
+/** One cached complete record plus the time it was stored. */
+export type LkgRecord = {
+  resolved: ResolvedDeliveryUnit;
+  storedAt: number;
+  /**
+   * External-major selector the record was resolved against. Participates in
+   * lookup validation — a cached record is only served for a matching major —
+   * but never in the storage key, which is (unitId, env) so all surfaces of a
+   * unit share one atomically-swapped record.
+   */
+  major?: number;
+};
+
+/**
+ * Pluggable storage hook. The default is an in-memory Map; callers may supply a
+ * durable store (KV, disk, etc). Reads/writes may be async. A store only ever
+ * receives whole records.
+ */
+export type LkgStorage = {
+  read(key: string): (LkgRecord | undefined) | Promise<LkgRecord | undefined>;
+  write(key: string, record: LkgRecord): void | Promise<void>;
+};
+
+export type LkgFreshnessPolicy = {
+  /**
+   * Maximum age, in ms, a stored record may be served after a provider
+   * failure. When omitted, a served record never expires by age. A record
+   * older than this yields a typed `stale-record` discovery error.
+   */
+  maxStaleMs?: number;
+};
+
+export type LastKnownGoodOptions = {
+  /** The wrapped provider (env/static, Zephyr, or any other). */
+  provider: SurfaceResolutionProvider;
+  /** Pluggable storage; defaults to a process-local in-memory Map. */
+  storage?: LkgStorage;
+  freshness?: LkgFreshnessPolicy;
+  /** Clock injection for deterministic freshness tests. */
+  now?: () => number;
+};
+
+/** Default process-local in-memory storage. */
+export function createInMemoryLkgStorage(): LkgStorage {
+  const map = new Map<string, LkgRecord>();
+  return {
+    read(key) {
+      return map.get(key);
+    },
+    write(key, record) {
+      map.set(key, record);
+    },
+  };
+}
+
+/** Flip a resolved record's verdict to degraded without mutating the input. */
+function markDegraded(
+  resolved: ResolvedDeliveryUnit,
+  reason: string,
+): ResolvedDeliveryUnit {
+  return {
+    ...resolved,
+    compatibility: {
+      ...resolved.compatibility,
+      status: 'degraded',
+      reason,
+    },
+  };
+}
+
+function staleRecordResult(
+  ref: ParsedSurfaceRef,
+  env: EnvironmentId,
+  ageMs: number,
+  maxStaleMs: number,
+): DiscoveryResult {
+  return {
+    ok: false,
+    error: createDiscoveryError(
+      'stale-record',
+      ref,
+      `Last-known-good record for surface is stale: age ${ageMs}ms exceeds maxStaleMs ${maxStaleMs}ms`,
+      { env, ageMs, maxStaleMs },
+    ),
+  };
+}
+
+function resolutionAnswersRef(
+  resolved: ResolvedDeliveryUnit,
+  ref: ParsedSurfaceRef,
+): boolean {
+  const selected = selectResolvedSurface(resolved, ref);
+  return selected.ok && selected.surface.servedMajor === ref.major;
+}
+
+/**
+ * Wrap a provider with a last-known-good cache. On success the whole record is
+ * cached (atomic swap). On provider failure (typed discovery error or a thrown
+ * error) the last complete record is served, marked degraded — unless it has
+ * expired per {@link LkgFreshnessPolicy}, in which case a typed `stale-record`
+ * error is returned. If there is no cached record, the original failure is
+ * passed through (a thrown error becomes a `provider-unavailable` discovery
+ * error).
+ */
+export function createLastKnownGoodProvider(
+  options: LastKnownGoodOptions,
+): SurfaceResolutionProvider {
+  const storage = options.storage ?? createInMemoryLkgStorage();
+  const now =
+    options.now ??
+    (() => Math.floor(performance.timeOrigin + performance.now()));
+  const maxStaleMs = options.freshness?.maxStaleMs;
+  let nextResolutionGeneration = 0;
+  const latestCacheableGenerationByKey = new Map<string, number>();
+  const writeTailByKey = new Map<string, Promise<void>>();
+
+  async function cacheCompatibleResolution(
+    key: string,
+    generation: number,
+    record: LkgRecord,
+  ): Promise<void> {
+    latestCacheableGenerationByKey.set(
+      key,
+      Math.max(latestCacheableGenerationByKey.get(key) ?? 0, generation),
+    );
+    // This orders writes made by this wrapper instance. LkgStorage has no
+    // revisioned CAS contract, so it intentionally makes no cross-process claim.
+    const previous = writeTailByKey.get(key) ?? Promise.resolve();
+    const write = previous
+      .catch(() => undefined)
+      .then(async () => {
+        if (latestCacheableGenerationByKey.get(key) !== generation) {
+          return;
+        }
+        await storage.write(key, record);
+      });
+    writeTailByKey.set(key, write);
+    try {
+      await write;
+    } finally {
+      if (writeTailByKey.get(key) === write) {
+        writeTailByKey.delete(key);
+      }
+    }
+  }
+
+  async function serveFromCache(
+    ref: ParsedSurfaceRef,
+    env: EnvironmentId,
+    fallback: () => DiscoveryResult,
+  ): Promise<DiscoveryResult> {
+    const key = deliveryUnitResolutionKey(ref.unitId, env);
+    const cached = await storage.read(key);
+    if (!cached) {
+      return fallback();
+    }
+
+    // The external-major participates in lookup validation: a record resolved
+    // against a different major is not a valid last-known-good for this ref.
+    if (cached.major !== ref.major) {
+      return fallback();
+    }
+
+    // A unit-level cache entry is only usable when it contains the exact
+    // requested surface materialization. The storage key intentionally lets
+    // sibling surfaces share one atomic snapshot, but it must not turn one
+    // cached surface into evidence that every possible surface exists.
+    if (!resolutionAnswersRef(cached.resolved, ref)) {
+      return fallback();
+    }
+
+    // Only a previously compatible record is a last-known-good snapshot.
+    // Defend against pluggable stores that contain degraded or incompatible
+    // records even though the write path below rejects both.
+    if (cached.resolved.compatibility.status !== 'compatible') {
+      return fallback();
+    }
+
+    const ageMs = now() - cached.storedAt;
+    if (maxStaleMs !== undefined && ageMs > maxStaleMs) {
+      return staleRecordResult(ref, env, ageMs, maxStaleMs);
+    }
+
+    return {
+      ok: true,
+      unit: markDegraded(
+        cached.resolved,
+        `served last-known-good record (age ${ageMs}ms) after provider failure`,
+      ),
+    };
+  }
+
+  return {
+    name: LAST_KNOWN_GOOD_PROVIDER_NAME,
+    async resolve(
+      ref: ParsedSurfaceRef,
+      env: EnvironmentId,
+    ): Promise<DiscoveryResult> {
+      const key = deliveryUnitResolutionKey(ref.unitId, env);
+      const generation = ++nextResolutionGeneration;
+
+      let resolution: DiscoveryResult;
+      try {
+        resolution = await options.provider.resolve(ref, env);
+      } catch (error) {
+        return serveFromCache(ref, env, () => ({
+          ok: false,
+          error: createDiscoveryError(
+            'provider-unavailable',
+            ref,
+            error instanceof Error
+              ? error.message
+              : 'provider threw a non-error value',
+            { env, provider: options.provider.name },
+          ),
+        }));
+      }
+
+      if (!resolution.ok) {
+        // Preserve the resolver's own typed failure when no LKG record exists.
+        const failure = resolution;
+        return serveFromCache(ref, env, () => failure);
+      }
+
+      if (!resolutionAnswersRef(resolution.unit, ref)) {
+        return serveFromCache(ref, env, () => ({
+          ok: false,
+          error: createDiscoveryError(
+            'identity-mismatch',
+            ref,
+            `Provider ${options.provider.name} returned a delivery unit that does not answer the requested surface.`,
+            {
+              env,
+              provider: options.provider.name,
+              recordUnitId: resolution.unit.unitId,
+              availableSurfaces: resolution.unit.surfaces.map(
+                surface => surface.surfaceId,
+              ),
+            },
+          ),
+        }));
+      }
+
+      // Fresh compatible success: swap the whole record atomically. Degraded
+      // and incompatible refreshes are still returned live, but neither can
+      // replace the prior known-good snapshot used for recovery.
+      if (resolution.unit.compatibility.status === 'compatible') {
+        await cacheCompatibleResolution(key, generation, {
+          resolved: resolution.unit,
+          storedAt: now(),
+          major: ref.major,
+        });
+      }
+      return resolution;
+    },
+  };
+}

package/src/module-federation/manifest-recovery-runtime-plugin.ts

@@ -0,0 +1,215 @@
+const DEFAULT_ATTEMPTS = 3;
+const DEFAULT_RETRY_DELAY_MS = 100;
+const DEFAULT_TIMEOUT_MS = 1_000;
+const MAX_ATTEMPTS = 5;
+const MAX_RETRY_DELAY_MS = 1_000;
+const MAX_TIMEOUT_MS = 5_000;
+
+const RETRYABLE_HTTP_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
+
+const NON_RETRYABLE_ERROR_PATTERNS = [
+  /RUNTIME-013/i,
+  /invalid manifest/i,
+  /manifest (?:schema|contract|version|identity)/i,
+  /(?:incompatible|mismatch).*(?:manifest|remote)/i,
+];
+
+type ErrorLoadRemoteArgs = {
+  id?: string;
+  error?: unknown;
+  lifecycle?: string;
+};
+
+export type ModuleFederationManifestRecoveryPluginOptions = {
+  attempts?: number;
+  retryDelayMs?: number;
+  timeoutMs?: number;
+  fetchImpl?: typeof fetch;
+  waitImpl?: (milliseconds: number) => Promise<void>;
+};
+
+const clampInteger = (
+  value: number | undefined,
+  fallback: number,
+  minimum: number,
+  maximum: number,
+) => {
+  if (value === undefined || !Number.isFinite(value)) {
+    return fallback;
+  }
+
+  return Math.min(maximum, Math.max(minimum, Math.floor(value)));
+};
+
+const getErrorMessage = (error: unknown) => {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return typeof error === 'string' ? error : '';
+};
+
+const getErrorStatus = (error: unknown) => {
+  if (
+    typeof error === 'object' &&
+    error !== null &&
+    'status' in error &&
+    typeof error.status === 'number'
+  ) {
+    return error.status;
+  }
+
+  return undefined;
+};
+
+const isRetryableError = (error: unknown) => {
+  if (error instanceof SyntaxError) {
+    return false;
+  }
+
+  const message = getErrorMessage(error);
+
+  if (NON_RETRYABLE_ERROR_PATTERNS.some(pattern => pattern.test(message))) {
+    return false;
+  }
+
+  const status = getErrorStatus(error);
+  if (status !== undefined) {
+    return RETRYABLE_HTTP_STATUSES.has(status);
+  }
+
+  if (
+    error instanceof Error &&
+    ['AbortError', 'TimeoutError'].includes(error.name)
+  ) {
+    return true;
+  }
+
+  return (
+    error instanceof TypeError ||
+    /(?:fetch failed|network|ECONNREFUSED|ECONNRESET|ETIMEDOUT|EAI_AGAIN)/i.test(
+      message,
+    )
+  );
+};
+
+const isHttpManifestUrl = (id: string | undefined): id is string => {
+  if (id === undefined || id.length === 0) {
+    return false;
+  }
+
+  try {
+    const url = new URL(id);
+    return (
+      (url.protocol === 'http:' || url.protocol === 'https:') &&
+      url.pathname.endsWith('.json')
+    );
+  } catch {
+    return false;
+  }
+};
+
+const defaultWait = (milliseconds: number): Promise<void> =>
+  new Promise<void>(resolve => {
+    setTimeout(resolve, milliseconds);
+  });
+
+const fetchWithTimeout = (
+  fetchImpl: typeof fetch,
+  url: string,
+  timeoutMs: number,
+) =>
+  fetchImpl(url, {
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+
+/**
+ * Gives server-side manifest loading a small, bounded recovery window.
+ *
+ * Returning `undefined` deliberately hands control back to Module Federation:
+ * its runtime preserves the original typed RUNTIME-003 error and invalidates
+ * the rejected manifest promise. Parsed manifests are returned without schema
+ * interpretation so runtime-core remains the authority for RUNTIME-013.
+ */
+export const createModuleFederationManifestRecoveryPlugin = (
+  options: ModuleFederationManifestRecoveryPluginOptions = {},
+) => {
+  const attempts = clampInteger(
+    options.attempts,
+    DEFAULT_ATTEMPTS,
+    1,
+    MAX_ATTEMPTS,
+  );
+  const retryDelayMs = clampInteger(
+    options.retryDelayMs,
+    DEFAULT_RETRY_DELAY_MS,
+    0,
+    MAX_RETRY_DELAY_MS,
+  );
+  const timeoutMs = clampInteger(
+    options.timeoutMs,
+    DEFAULT_TIMEOUT_MS,
+    1,
+    MAX_TIMEOUT_MS,
+  );
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  const waitImpl = options.waitImpl ?? defaultWait;
+
+  const recoverManifest = (url: string, attempt: number): Promise<unknown> => {
+    const fetchManifest = () =>
+      Promise.resolve()
+        .then(() => fetchWithTimeout(fetchImpl, url, timeoutMs))
+        .then(
+          response => {
+            if (!response.ok) {
+              if (
+                !RETRYABLE_HTTP_STATUSES.has(response.status) ||
+                attempt === attempts - 1
+              ) {
+                return undefined;
+              }
+
+              return recoverManifest(url, attempt + 1);
+            }
+
+            return Promise.resolve()
+              .then(() => response.json())
+              .then(
+                manifest => manifest,
+                () => undefined,
+              );
+          },
+          error => {
+            if (!isRetryableError(error) || attempt === attempts - 1) {
+              return undefined;
+            }
+
+            return recoverManifest(url, attempt + 1);
+          },
+        );
+
+    if (attempt > 0 && retryDelayMs > 0) {
+      return waitImpl(retryDelayMs).then(fetchManifest);
+    }
+
+    return fetchManifest();
+  };
+
+  return {
+    name: 'modern-js-manifest-recovery-plugin',
+    errorLoadRemote(args: ErrorLoadRemoteArgs) {
+      if (
+        args.lifecycle !== 'afterResolve' ||
+        !isHttpManifestUrl(args.id) ||
+        !isRetryableError(args.error) ||
+        typeof fetchImpl !== 'function'
+      ) {
+        return Promise.resolve(undefined);
+      }
+
+      return recoverManifest(args.id, 0);
+    },
+  };
+};
+
+export default createModuleFederationManifestRecoveryPlugin;

package/src/module-federation/surface-resolution-types.ts

@@ -0,0 +1,60 @@
+/**
+ * Surface-resolution types for the module-federation runtime.
+ *
+ * Thin re-export of the canonical module in `@modern-js/surface-resolution`
+ * (`packages/toolkit/surface-resolution/src/surface-resolution/`,
+ * RESOLUTION-0001). Kept as a file so existing `./surface-resolution-types`
+ * imports stay stable. Only helpers the canonical module deliberately does not
+ * ship (the (ref, env) cache key) live here, implemented against canonical
+ * types.
+ */
+import {
+  type EnvironmentId,
+  formatSurfaceRef,
+  type ParsedSurfaceRef,
+} from '@modern-js/surface-resolution';
+
+export {
+  type CompatibilityStatus,
+  type CompatibilityVerdict,
+  createDiscoveryError,
+  type DiscoveryError,
+  type DiscoveryErrorCode,
+  type DiscoveryResult,
+  type EnvironmentId,
+  formatSurfaceRef,
+  type ParsedSurfaceRef,
+  parseSurfaceRef,
+  type ResolvedDeliveryUnit,
+  type ResolvedSurface,
+  type ResolvedSurfaceKind,
+  type ResolvedSurfaceLocation,
+  type ResolvedSurfaceLocationPlatform,
+  type SurfaceRefParseError,
+  type SurfaceRefParseResult,
+  type SurfaceResolutionProvider,
+  validateSurfaceRef,
+} from '@modern-js/surface-resolution';
+
+/** Stable cache/identity key for a (ref, env) pair. */
+export function surfaceResolutionKey(
+  ref: ParsedSurfaceRef,
+  env: EnvironmentId,
+): string {
+  return `${env}::${formatSurfaceRef(ref)}`;
+}
+
+/**
+ * Stable cache key for a (deliveryUnit, env) pair — ONE record per unit per
+ * env (ADR-0019 atomicity). All surfaces of a unit share this key so a refresh
+ * replaces the whole unit snapshot atomically for every surface, and two
+ * surfaces of the same unit can never be served from different cached
+ * snapshots. The ref's external-major participates in lookup validation (see
+ * the LKG provider), not in this key.
+ */
+export function deliveryUnitResolutionKey(
+  unitId: string,
+  env: EnvironmentId,
+): string {
+  return `${env}::${unitId}`;
+}

package/README.md

@@ -1,3 +0,0 @@
-# @bleedingdev/modern-js-federation-runtime
-
-This 0.0.0 version only registers the package name so npm trusted publishing can be configured. It contains no runtime implementation. Use the subsequent UltraModern.js release, published from the repository workflow with provenance.