@bleedingdev/modern-js-federation-runtime 3.9.3-ultramodern.7 → 3.9.3-ultramodern.9

package/src/module-federation/native-browser-dev-refresh.ts

@@ -0,0 +1,373 @@
+/** The normal MF instance surface used by a browser development replacement. */
+export interface NativeBrowserDevHost {
+  readonly name: string;
+  readonly options: Readonly<Record<string, unknown>>;
+  readonly shareScopeMap: Record<
+    string,
+    Record<string, Record<string, Shared>>
+  >;
+  readonly moduleCache: Map<string, unknown>;
+  readonly loaderHook?: {
+    readonly lifecycle: {
+      readonly fetch: {
+        emit(
+          url: string,
+          init: RequestInit,
+          remote: unknown,
+          context: {
+            readonly initiator: 'loadRemote';
+            readonly id: string;
+            readonly resourceType: 'manifest';
+            readonly url: string;
+          },
+        ): Promise<unknown>;
+      };
+    };
+  };
+  initShareScopeMap(
+    name: string,
+    scope: Record<string, Record<string, Shared>>,
+    options: { hostShareScopeMap: NativeBrowserDevHost['shareScopeMap'] },
+  ): void;
+  loadRemote<T>(id: string, options: { loadFactory: false }): Promise<T | null>;
+}
+
+interface Shared {
+  readonly loaded?: boolean;
+  readonly loading?: unknown;
+  readonly lib?: unknown;
+  readonly get?: unknown;
+}
+
+export interface NativeBrowserDevGraph {
+  /** Existing completed graph revision, also used in immutable asset URLs. */
+  readonly revision: string;
+  /** Native JSON manifest whose entry AND chunks belong to this revision. */
+  readonly remote: Readonly<{ name: string; alias: string; entry: string }>;
+}
+
+interface StagingHost {
+  readonly host: NativeBrowserDevHost;
+  /** Rearm cached, unexecuted runtime hot listeners without starting a socket. */
+  prepareFactory?(): void;
+  /** Retire only this attempt's transport/listeners; never shared providers. */
+  release(): void;
+}
+
+interface PublisherReplacement {
+  readonly commitStarted: boolean;
+  execute<T>(factory: () => T): T;
+}
+
+const COMMIT_ERROR = Symbol.for(
+  'ultramodern.federation.browser-dev-commit-error.v1',
+);
+
+/** Propagates an observed native mutation; it does not grant native authority. */
+class NativeBrowserDevCommitError extends Error {
+  readonly [COMMIT_ERROR] = true;
+  declare readonly revision: string;
+
+  constructor(revision: string, cause: unknown) {
+    super(
+      `Native browser refresh failed after ownership transfer began: ${cause instanceof Error ? cause.message : String(cause)}`,
+      { cause },
+    );
+    this.name = 'NativeBrowserDevCommitError';
+    Object.defineProperty(this, 'revision', {
+      value: revision,
+      enumerable: true,
+    });
+  }
+}
+
+/** A remote runtime can receive this error from a different host runtime copy. */
+export function isNativeBrowserDevCommitError(
+  error: unknown,
+  revision: string,
+): error is NativeBrowserDevCommitError {
+  return (
+    error instanceof Error &&
+    Reflect.get(error, COMMIT_ERROR) === true &&
+    Reflect.get(error, 'revision') === revision
+  );
+}
+
+/** Trusted coordinators use this only after observing an actual native commit. */
+export function nativeBrowserDevCommitFailure(
+  revision: string,
+  cause: unknown,
+): Error {
+  return new NativeBrowserDevCommitError(revision, cause);
+}
+
+interface SelectedShare {
+  readonly scope: string;
+  readonly name: string;
+  readonly version: string;
+  readonly provider: Shared;
+  readonly lib: unknown;
+  readonly get: unknown;
+}
+
+const selectedShares = (host: NativeBrowserDevHost): SelectedShare[] =>
+  Object.entries(host.shareScopeMap).flatMap(([scope, packages]) =>
+    Object.entries(packages).flatMap(([name, versions]) =>
+      Object.entries(versions)
+        .filter(([, provider]) => provider.loaded || provider.loading)
+        .map(([version, provider]) => ({
+          scope,
+          name,
+          version,
+          provider,
+          lib: provider.lib,
+          get: provider.get,
+        })),
+    ),
+  );
+
+function assertSelectedShares(
+  host: NativeBrowserDevHost,
+  shares: readonly SelectedShare[],
+): void {
+  for (const share of shares) {
+    const provider =
+      host.shareScopeMap[share.scope]?.[share.name]?.[share.version];
+    if (
+      provider !== share.provider ||
+      provider.lib !== share.lib ||
+      provider.get !== share.get
+    )
+      throw new Error(
+        `Native browser refresh changed the selected shared provider ${share.name}.`,
+      );
+  }
+}
+
+/**
+ * Load a new container without evicting the working host. MF admission and async
+ * chunk loading finish before Octane executes the synchronous exposed graph.
+ * Native execution owns declaration rollback and retirement of the old graph.
+ * It cannot undo arbitrary module side effects or the browser's ESM cache: a
+ * consumed, failed graph needs a newer completed revision for another attempt.
+ *
+ * The compiler supplies a public ModuleFederation constructor adapter and an
+ * attempt-owned transport release function. No global MF cache is deleted here.
+ */
+export function createNativeBrowserDevRefresh<Boundary>(options: {
+  readonly host: NativeBrowserDevHost;
+  readonly id: string;
+  readonly boundary: Boundary;
+  readonly prepareReplacement: (boundary: Boundary) => PublisherReplacement;
+  readonly createHost: (
+    options: Readonly<Record<string, unknown>>,
+  ) => StagingHost;
+}) {
+  let active: StagingHost | undefined;
+  let pending: Promise<unknown> | undefined;
+  let disposed = false;
+  const consumed = new Set<string>();
+  const recovery = new Set<StagingHost>();
+  const released = new WeakSet<StagingHost>();
+
+  const release = (stage: StagingHost) => {
+    if (released.has(stage)) return;
+    released.add(stage);
+    try {
+      stage.release();
+    } finally {
+      stage.host.moduleCache.clear();
+    }
+  };
+
+  return {
+    replace<T>(graph: NativeBrowserDevGraph): Promise<T> {
+      if (disposed)
+        return Promise.reject(new Error('Native browser refresh is disposed.'));
+      if (pending)
+        return Promise.reject(
+          new Error(
+            'Native browser refresh already has an active replacement.',
+          ),
+        );
+      if (!/^[a-f0-9]{64}$/u.test(graph.revision))
+        return Promise.reject(
+          new Error('Native browser graph revision is invalid.'),
+        );
+      if (consumed.has(graph.revision))
+        return Promise.reject(
+          new Error(
+            'Native browser graph was already consumed; rebuild before retrying.',
+          ),
+        );
+      // A cross-runtime outcome must come from this attempt's actual native
+      // commit, never from arbitrary objects thrown by a factory or loader.
+      const commitErrors = new WeakSet<Error>();
+      const task = (async (): Promise<T> => {
+        const host = options.host;
+        const shares = selectedShares(host);
+        // Prepare from the actual live boundary before async loading. execute
+        // revalidates all captured native owners after that loading completes.
+        const replacement = options.prepareReplacement(options.boundary);
+        const stage = options.createHost({
+          ...host.options,
+          name: `${host.name}:native-dev:${graph.revision}`,
+          id: `${host.name}:native-dev:${graph.revision}`,
+          remotes: [{ ...graph.remote }],
+          // Reuse actual initialized scopes, not reconstructed shared configs.
+          shared: {},
+        });
+        if (stage.host === host || stage.host === active?.host)
+          throw new Error(
+            'Native browser refresh requires an isolated staging host.',
+          );
+        let accepted = false;
+        let module!: T;
+        let failed = false;
+        let failure: unknown;
+        try {
+          for (const [name, scope] of Object.entries(host.shareScopeMap)) {
+            stage.host.initShareScopeMap(name, scope, {
+              hostShareScopeMap: host.shareScopeMap,
+            });
+            if (stage.host.shareScopeMap[name] !== scope)
+              throw new Error(
+                'Native browser refresh lost the actual shared scope.',
+              );
+          }
+          const factory = await stage.host.loadRemote<() => T>(options.id, {
+            loadFactory: false,
+          });
+          if (disposed)
+            throw new Error(
+              'Native browser refresh was disposed while loading.',
+            );
+          if (typeof factory !== 'function')
+            throw new Error(
+              'Native browser refresh did not receive an exposed factory.',
+            );
+          assertSelectedShares(host, shares);
+          stage.prepareFactory?.();
+          consumed.add(graph.revision);
+          try {
+            module = replacement.execute(factory);
+          } catch (error) {
+            if (replacement.commitStarted) {
+              // Native callbacks can fail after the first irreversible owner
+              // mutation. Retain both graphs for native recovery, surface the
+              // failure, and never describe this as an old-owner rollback.
+              if (active) recovery.add(active);
+              active = stage;
+              accepted = true;
+            }
+            throw error;
+          }
+          const previous = active;
+          active = stage;
+          accepted = true;
+          // Native commit has completed. Never pretend later observer or
+          // transport errors rolled that commit back or discard its owner.
+          assertSelectedShares(host, shares);
+          // A failed retirement must not release the newly accepted owner.
+          const retired = new Set(recovery);
+          recovery.clear();
+          if (previous) retired.add(previous);
+          const errors: unknown[] = [];
+          for (const retained of retired) {
+            try {
+              release(retained);
+            } catch (error) {
+              errors.push(error);
+            }
+          }
+          if (errors.length)
+            throw new AggregateError(
+              errors,
+              'Native browser refresh retirement failed.',
+            );
+        } catch (error) {
+          failed = true;
+          failure = error;
+        }
+        const retired = new Set<StagingHost>();
+        if (disposed && active === stage) {
+          active = undefined;
+          for (const retained of recovery) retired.add(retained);
+          recovery.clear();
+          retired.add(stage);
+        } else if (!accepted) retired.add(stage);
+        const cleanupErrors: unknown[] = [];
+        for (const retained of retired) {
+          try {
+            release(retained);
+          } catch (error) {
+            cleanupErrors.push(error);
+          }
+        }
+        if (cleanupErrors.length) {
+          failure = new AggregateError(
+            failed ? [failure, ...cleanupErrors] : cleanupErrors,
+            'Native browser refresh cleanup failed.',
+          );
+          failed = true;
+        }
+        if (failed) {
+          if (accepted) {
+            const committedFailure = nativeBrowserDevCommitFailure(
+              graph.revision,
+              failure,
+            );
+            commitErrors.add(committedFailure);
+            throw committedFailure;
+          }
+          throw failure;
+        }
+        return module;
+      })().catch(error => {
+        if (
+          error instanceof Error &&
+          Reflect.get(error, COMMIT_ERROR) === true &&
+          !commitErrors.has(error)
+        )
+          throw new Error(
+            `Native browser graph failed before its own ownership transfer: ${error.message}`,
+            { cause: error },
+          );
+        throw error;
+      });
+      pending = task;
+      void task
+        .finally(() => {
+          if (pending === task) pending = undefined;
+        })
+        .catch(() => {});
+      return task;
+    },
+    /** The original host remains untouched, including sibling remote loaders. */
+    get activeHost(): NativeBrowserDevHost {
+      return active?.host ?? options.host;
+    },
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      const previous = active;
+      active = undefined;
+      const retained = new Set(recovery);
+      recovery.clear();
+      if (previous) retained.add(previous);
+      const errors: unknown[] = [];
+      for (const stage of retained) {
+        try {
+          release(stage);
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+      if (errors.length)
+        throw new AggregateError(
+          errors,
+          'Native browser refresh cleanup failed.',
+        );
+    },
+  };
+}

package/src/module-federation/native-browser-dev-runtime-plugin.ts

@@ -0,0 +1,276 @@
+import {
+  createNativeBrowserDevRefresh,
+  isNativeBrowserDevCommitError,
+  type NativeBrowserDevGraph,
+  type NativeBrowserDevHost,
+  nativeBrowserDevCommitFailure,
+} from './native-browser-dev-refresh';
+import { readRendererFederationContract } from './renderer-contract';
+
+export const NATIVE_BROWSER_DEV_BOUNDARY = Symbol.for(
+  'ultramodern.federation.browser-dev-boundary.v1',
+);
+const REGISTRY = Symbol.for('ultramodern.federation.browser-dev-routing.v1');
+
+interface Replacement {
+  readonly commitStarted: boolean;
+  execute<T>(factory: () => T): T;
+}
+interface Reference {
+  readonly host: NativeBrowserDevHost;
+  readonly remote: NativeBrowserDevGraph['remote'];
+  readonly boundary: object;
+  readonly prepare: (boundary: object) => Replacement;
+}
+interface Binding {
+  readonly id: string;
+  readonly remoteName: string;
+  readonly references: Set<Reference>;
+  readonly coordinator: ReturnType<typeof createNativeBrowserDevRefresh>;
+}
+interface Registry {
+  readonly sources: WeakMap<object, Map<string, Binding>>;
+  readonly bindings: Set<Binding>;
+}
+
+function registry(): Registry {
+  const root = globalThis as typeof globalThis & { [REGISTRY]?: Registry };
+  if (!root[REGISTRY])
+    Object.defineProperty(root, REGISTRY, {
+      value: { sources: new WeakMap(), bindings: new Set() } satisfies Registry,
+    });
+  return root[REGISTRY]!;
+}
+
+function firstReference(binding: Binding): Reference {
+  const reference = binding.references.values().next().value;
+  if (!reference)
+    throw new Error('Native browser refresh has no mounted boundary owner.');
+  return reference;
+}
+
+/**
+ * This registry routes work to actual mounted boundary references; its names
+ * grant no native authority. Octane revalidates the exact compiled root, lease,
+ * physical document and every surviving owner inside the opaque capability.
+ */
+export function createNativeBrowserDevRuntimePlugin(options: {
+  readonly remotes: readonly NativeBrowserDevGraph['remote'][];
+  readonly prepareReplacement: Reference['prepare'];
+  readonly createHost: Parameters<
+    typeof createNativeBrowserDevRefresh
+  >[0]['createHost'];
+}) {
+  return {
+    name: 'ultramodern-native-browser-dev-refresh',
+    beforeInit<T extends { origin: NativeBrowserDevHost }>(args: T): T {
+      const host = args.origin;
+      if (Object.hasOwn(host, NATIVE_BROWSER_DEV_BOUNDARY)) return args;
+      Object.defineProperty(host, NATIVE_BROWSER_DEV_BOUNDARY, {
+        value(id: string, source: object, boundary: object): () => void {
+          const remote = options.remotes.find(remote =>
+            id.startsWith(`${remote.alias}/`),
+          );
+          if (!remote)
+            throw new Error(
+              `Native browser refresh has no registered remote for ${id}.`,
+            );
+          const state = registry();
+          let sources = state.sources.get(source);
+          if (!sources) state.sources.set(source, (sources = new Map()));
+          let binding = sources.get(id);
+          if (binding && binding.remoteName !== remote.name)
+            throw new Error(
+              'Native browser refresh source has conflicting remote ownership.',
+            );
+          if (!binding) {
+            const references = new Set<Reference>();
+            const current = (): Reference => firstReference(created);
+            const created: Binding = {
+              id,
+              remoteName: remote.name,
+              references,
+              coordinator: createNativeBrowserDevRefresh({
+                get host() {
+                  return current().host;
+                },
+                id,
+                boundary: references,
+                prepareReplacement() {
+                  const reference = current();
+                  return reference.prepare(reference.boundary);
+                },
+                createHost: options.createHost,
+              }),
+            };
+            binding = created;
+            sources.set(id, binding);
+            state.bindings.add(binding);
+          }
+          const reference: Reference = {
+            host,
+            remote,
+            boundary,
+            prepare: options.prepareReplacement,
+          };
+          binding.references.add(reference);
+          const owned = binding;
+          let released = false;
+          return () => {
+            if (released) return;
+            released = true;
+            owned.references.delete(reference);
+            if (owned.references.size) return;
+            sources!.delete(id);
+            state.bindings.delete(owned);
+            owned.coordinator.dispose();
+          };
+        },
+      });
+      return args;
+    },
+  };
+}
+
+/** One synchronous exposed graph execution serves all of its mounted instances. */
+export async function replaceNativeBrowserDevRemote(
+  graph: NativeBrowserDevGraph,
+): Promise<number> {
+  const bindings = [...registry().bindings].filter(
+    binding => binding.remoteName === graph.remote.name,
+  );
+  if (!bindings.length)
+    throw new Error(
+      'Native browser refresh has no mounted publisher for this remote.',
+    );
+  let committed = 0;
+  try {
+    for (const binding of bindings) {
+      await binding.coordinator.replace(graph);
+      committed++;
+    }
+  } catch (error) {
+    // Separate exposed roots are not an atomic remote-wide transaction. If an
+    // earlier root committed, its runtime must survive a later root's failure.
+    if (committed && !isNativeBrowserDevCommitError(error, graph.revision))
+      throw nativeBrowserDevCommitFailure(graph.revision, error);
+    throw error;
+  }
+  return bindings.length;
+}
+
+export interface NativeBrowserDevPublication extends NativeBrowserDevGraph {
+  readonly buildId: string;
+  readonly runtimeHash: string;
+}
+
+const record = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/** Discover the latest completed graph through this mounted host's transport. */
+export async function readNativeBrowserDevPublication(
+  remoteName: string,
+  options: { readonly signal: AbortSignal; readonly revisionHeader: string },
+): Promise<NativeBrowserDevPublication> {
+  const binding = [...registry().bindings].find(
+    binding => binding.remoteName === remoteName,
+  );
+  if (!binding)
+    throw new Error(
+      'Native browser refresh has no mounted publisher for discovery.',
+    );
+  const reference = firstReference(binding);
+  const remote = reference.remote;
+  const host = reference.host;
+  const init: RequestInit = { cache: 'no-store', signal: options.signal };
+  const context = {
+    initiator: 'loadRemote' as const,
+    id: binding.id,
+    resourceType: 'manifest' as const,
+    url: remote.entry,
+  };
+  const hook = host.loaderHook?.lifecycle.fetch;
+  const request = (async () => {
+    const hooked = await hook?.emit(remote.entry, init, remote, context);
+    const response =
+      hooked instanceof Response
+        ? hooked
+        : await globalThis.fetch(remote.entry, init);
+    if (options.signal.aborted) {
+      void response.body?.cancel().catch(() => {});
+      throw options.signal.reason;
+    }
+    if (!response.ok) {
+      void response.body?.cancel().catch(() => {});
+      throw new Error(
+        `Native browser manifest discovery failed: ${response.status}`,
+      );
+    }
+    const manifest: unknown = await response.json();
+    const revision = response.headers.get(options.revisionHeader);
+    const links = [
+      ...(response.headers.get('link') ?? '').matchAll(
+        /<([^>]+)>\s*;([^,]*)/gu,
+      ),
+    ].filter(([, , parameters]) =>
+      /\brel\s*=\s*"?ultramodern-completed-graph"?(?:\s|;|$)/u.test(
+        parameters!,
+      ),
+    );
+    if (!revision || !/^[a-f0-9]{64}$/u.test(revision) || links.length !== 1)
+      throw new Error(
+        'Native browser manifest has no unique completed graph coordinate.',
+      );
+    const entry = new URL(links[0]![1]!, remote.entry);
+    if (
+      !['http:', 'https:'].includes(entry.protocol) ||
+      entry.username ||
+      entry.password ||
+      entry.hash
+    )
+      throw new Error('Native browser completed graph URL is invalid.');
+    const namespace = /\/__ultramodern_mf__\/([a-f0-9]+)\//u.exec(
+      entry.pathname,
+    );
+    if (!namespace)
+      throw new Error(
+        'Native browser graph is not in the immutable runtime namespace.',
+      );
+    const metadata =
+      record(manifest) && record(manifest.metaData)
+        ? manifest.metaData.ultramodernRenderer
+        : undefined;
+    const contract = readRendererFederationContract(metadata);
+    const buildIds = new Set(
+      Object.values(contract.identities).map(identity => identity.buildId),
+    );
+    if (buildIds.size !== 1)
+      throw new Error(
+        'Native browser graph has conflicting renderer build identities.',
+      );
+    return {
+      revision,
+      runtimeHash: namespace[1]!,
+      buildId: [...buildIds][0]!,
+      remote: { ...remote, entry: entry.href },
+    };
+  })();
+  let removeAbort!: () => void;
+  const aborted = new Promise<never>((_resolve, reject) => {
+    const abort = () => reject(options.signal.reason);
+    removeAbort = () => options.signal.removeEventListener('abort', abort);
+    if (options.signal.aborted) abort();
+    else options.signal.addEventListener('abort', abort, { once: true });
+  });
+  try {
+    return await Promise.race([request, aborted]);
+  } finally {
+    removeAbort();
+  }
+}
+
+export function hasNativeBrowserDevPublisher(remoteName: string): boolean {
+  return [...registry().bindings].some(
+    binding => binding.remoteName === remoteName,
+  );
+}