@bleedingdev/modern-js-plugin-bff-extensions 3.9.0-ultramodern.9 → 3.9.3-ultramodern.10

package/src/backend-federation/identity.ts

@@ -17,59 +17,51 @@ export type BackendFederationIdentityIssue = {
   message: string;
 };
 
-/**
- * Shared expected-identity validation for loaded backend federation modules.
- * Compares the expose's `backendFederationContract.compatibility` identity
- * (`unitId`, `build`) against the consumer's expected delivery-unit identity.
- * Missing identity metadata is an error.
- */
-export function validateExpectedBackendFederationIdentity(
-  loaded: unknown,
-  expected: BackendFederationExpectedIdentity,
-): BackendFederationIdentityIssue[] {
-  const issues: BackendFederationIdentityIssue[] = [];
+/** Decode independently at each received-manifest / executed-expose boundary. */
+export function backendFederationCompatibility(loaded: unknown) {
   const contract = isRecord(loaded)
     ? loaded.backendFederationContract
     : undefined;
   const compatibility = isRecord(contract) ? contract.compatibility : undefined;
+  return isRecord(compatibility) ? compatibility : undefined;
+}
 
-  if (!isRecord(compatibility)) {
-    return [
-      {
-        path: 'backendFederationContract.compatibility',
-        message:
-          'loaded module declares no compatibility metadata; delivery-unit identity cannot be validated',
-      },
-    ];
-  }
-
-  const unitId = compatibility.unitId;
-  if (typeof unitId !== 'string' || unitId.length === 0) {
-    issues.push({
-      path: 'backendFederationContract.compatibility.unitId',
-      message: `missing delivery-unit id; expected ${expected.unitId}`,
-    });
-  } else if (unitId !== expected.unitId) {
-    issues.push({
-      path: 'backendFederationContract.compatibility.unitId',
-      message: `expected ${expected.unitId}, received ${unitId}`,
-    });
-  }
-
-  const build = compatibility.build;
-  if (typeof build !== 'string' || build.length === 0) {
-    issues.push({
-      path: 'backendFederationContract.compatibility.build',
-      message: `missing build marker; expected ${expected.buildMarker}`,
-    });
-  } else if (build !== expected.buildMarker) {
-    issues.push({
-      path: 'backendFederationContract.compatibility.build',
-      message: `expected ${expected.buildMarker}, received ${build}`,
-    });
-  }
+export function validateBackendFederationCompatibility(
+  compatibility: Record<string, unknown>,
+  expected: Record<string, string | undefined>,
+): BackendFederationIdentityIssue[] {
+  return Object.entries(expected).flatMap(([field, value]) =>
+    value === undefined ||
+    (typeof compatibility[field] === 'string' &&
+      compatibility[field].length > 0 &&
+      compatibility[field] === value)
+      ? []
+      : [
+          {
+            path: `backendFederationContract.compatibility.${field}`,
+            message: `expected ${value}, received ${typeof compatibility[field] === 'string' ? compatibility[field] : typeof compatibility[field]}`,
+          },
+        ],
+  );
+}
 
-  return issues;
+export function validateExpectedBackendFederationIdentity(
+  loaded: unknown,
+  expected: BackendFederationExpectedIdentity,
+): BackendFederationIdentityIssue[] {
+  const compatibility = backendFederationCompatibility(loaded);
+  return compatibility
+    ? validateBackendFederationCompatibility(compatibility, {
+        unitId: expected.unitId,
+        build: expected.buildMarker,
+      })
+    : [
+        {
+          path: 'backendFederationContract.compatibility',
+          message:
+            'loaded module declares no compatibility metadata; delivery-unit identity cannot be validated',
+        },
+      ];
 }
 
 export function formatBackendFederationIdentityIssues(

package/src/backend-federation/integrity-plugin.ts

@@ -0,0 +1,157 @@
+// @effect-diagnostics asyncFunction:off globalFetch:off strictBooleanExpressions:off
+
+import {
+  evaluateBackendFederationCommonJsEntry,
+  loadVerifiedBackendFederationEntry,
+} from '@modern-js/server-runtime-extensions/backend-federation-security';
+import {
+  Module,
+  type ModuleFederation,
+  type ModuleFederationRuntimePlugin,
+} from '@module-federation/runtime';
+
+import type {
+  BackendFederationEntryExports,
+  BackendFederationRemote,
+  BackendFederationRuntimeOptions,
+} from './types';
+
+type RemoteInfo = ConstructorParameters<typeof Module>[0]['remoteInfo'];
+
+export const PROVIDED_ENTRY_SCHEME = /^(?:binding|service|static):/u;
+
+function decodeDataUrl(remote: BackendFederationRemote) {
+  const commaIndex = remote.entry.indexOf(',');
+  if (commaIndex < 0) {
+    throw new Error(
+      `[BFF][Effect] Backend federation remote ${remote.name} has an invalid data URL entry.`,
+    );
+  }
+  return new TextEncoder().encode(
+    decodeURIComponent(remote.entry.slice(commaIndex + 1)),
+  );
+}
+
+// Node caches ES modules by URL, so every runtime importing the same file: or
+// data: module shares one container. Only evaluated CommonJS containers (the
+// verified network path) are isolated per runtime.
+async function importContainer(remote: BackendFederationRemote) {
+  const namespace = await import(/* webpackIgnore: true */ remote.entry);
+  return (namespace.default ?? namespace) as BackendFederationEntryExports;
+}
+
+/** One load path per entry scheme; anything else names the remote and fails. */
+function loadContainer(
+  remote: BackendFederationRemote,
+  options: BackendFederationRuntimeOptions,
+): Promise<BackendFederationEntryExports> {
+  const verified = Boolean(
+    remote.verification || options.entryPolicy?.expected,
+  );
+  const scheme = /^[a-z][a-z0-9+.-]*:/iu.exec(remote.entry)?.[0].toLowerCase();
+  if (scheme === 'https:' || scheme === 'http:') {
+    if (!verified) {
+      throw new Error(
+        `[BFF][Effect] Backend federation remote ${remote.name} requires verified entry bytes before network execution.`,
+      );
+    }
+    return loadVerifiedBackendFederationEntry({
+      ...options.entryPolicy,
+      remote,
+      ...(remote.verification ? { verification: remote.verification } : {}),
+    });
+  }
+  if (verified) {
+    throw new Error(
+      `[BFF][Effect] Backend federation remote ${remote.name} declares entry verification, but only http(s) entries are fetched and verified.`,
+    );
+  }
+  if (scheme === 'data:' && remote.type !== 'module') {
+    return Promise.resolve(
+      evaluateBackendFederationCommonJsEntry(
+        remote,
+        decodeDataUrl(remote),
+        options.entryPolicy?.evaluateCommonJs,
+      ),
+    );
+  }
+  if (scheme === 'data:' || scheme === 'file:') {
+    return importContainer(remote);
+  }
+  throw new Error(
+    `[BFF][Effect] Backend federation remote ${remote.name} uses unsupported entry ${remote.entry}. Use a verified http(s) entry, a data: or file: entry, or a binding:, service: or static: entry served by createBackendFederationLoadEntryPlugin().`,
+  );
+}
+
+export function registerRemoteContainer(
+  origin: ModuleFederation,
+  remoteInfo: RemoteInfo,
+  container: BackendFederationEntryExports,
+) {
+  const module = new Module({ host: origin, remoteInfo });
+  module.remoteEntryExports = container as InstanceType<
+    typeof Module
+  >['remoteEntryExports'];
+  origin.moduleCache.set(remoteInfo.name, module);
+}
+
+/**
+ * Loads each configured remote once per runtime and registers the resulting
+ * container with that runtime only, so Module Federation initializes it with
+ * the runtime's own share scope. Registered last, it replaces any container a
+ * caller plugin supplied for a scheme it owns.
+ */
+export function createBackendFederationIntegrityPlugin(
+  options: BackendFederationRuntimeOptions,
+  remotes: readonly BackendFederationRemote[],
+): ModuleFederationRuntimePlugin {
+  const loading = new Map<string, Promise<void>>();
+
+  const register = async (origin: ModuleFederation, remoteInfo: RemoteInfo) => {
+    const remote = remotes.find(
+      candidate => candidate.name === remoteInfo.name,
+    );
+    if (remote === undefined) {
+      throw new Error(
+        `[BFF][Effect] Missing backend federation remote ${remoteInfo.name}.`,
+      );
+    }
+    if (PROVIDED_ENTRY_SCHEME.test(remote.entry)) {
+      if (
+        origin.moduleCache.get(remote.name)?.remoteEntryExports === undefined
+      ) {
+        throw new Error(
+          `[BFF][Effect] Backend federation remote ${remote.name} has no entry provider for ${remote.entry}. Pass createBackendFederationLoadEntryPlugin() in plugins.`,
+        );
+      }
+      return;
+    }
+    const container = await loadContainer(remote, options);
+    if (typeof container?.get !== 'function') {
+      throw new Error(
+        `[BFF][Effect] Backend federation remote ${remote.name} entry must expose get().`,
+      );
+    }
+    registerRemoteContainer(origin, remoteInfo, container);
+  };
+
+  return {
+    name: 'modernjs-backend-federation-integrity',
+    afterMatchRemote({ origin, remoteInfo }) {
+      if (remoteInfo === undefined) {
+        return;
+      }
+      let pending = loading.get(remoteInfo.name);
+      if (pending === undefined) {
+        pending = register(origin, remoteInfo);
+        loading.set(remoteInfo.name, pending);
+        pending.catch(() => {
+          if (loading.get(remoteInfo.name) === pending) {
+            loading.delete(remoteInfo.name);
+          }
+        });
+      }
+      return pending;
+    },
+  };
+}

package/src/backend-federation/load.ts

@@ -5,7 +5,6 @@ import { createBackendFederationRuntime } from './runtime';
 import type {
   BackendFederatedEffectApiModule,
   BackendFederationIdentityLoadOptions,
-  BackendFederationLoadOptions,
 } from './types';
 import { normalizeExpose } from './utils';
 import { validateLoadedBackendFederatedEffectApi } from './validate-loaded';

package/src/backend-federation/node-shared.ts

@@ -0,0 +1,76 @@
+import { createRequire } from 'node:module';
+import type * as EffectContextModule from '@modern-js/bff-effect/context';
+import type * as EffectEdgeModule from '@modern-js/bff-effect/effect-edge';
+
+import type { BackendFederationRuntimeOptions } from './types';
+
+type HostShared = NonNullable<BackendFederationRuntimeOptions['shared']>;
+
+const fromAdapter = createRequire(import.meta.url);
+const effectPackageJson = fromAdapter.resolve(
+  '@modern-js/bff-effect/package.json',
+);
+const fromEffectPackage = createRequire(effectPackageJson);
+
+let hostShared: HostShared | undefined;
+
+/**
+ * Shares the package-private Effect handler factory registry and the Effect
+ * request storage with every backend container, so factories a remote creates
+ * with defineEffectBff are recognized by this host's module resolver and its
+ * endpoints read the context this host's dispatcher enters.
+ *
+ * Loaded on first call, not when this module loads: a CommonJS require() of
+ * the Effect ES modules throws while a concurrent import() is still loading
+ * them.
+ */
+export function effectBffHostShared(): HostShared {
+  if (hostShared !== undefined) {
+    return hostShared;
+  }
+  const {
+    EFFECT_BFF_CONTEXT_STORAGE_SHARE,
+    EFFECT_BFF_HANDLER_FACTORY_REGISTRY_SHARE,
+  } = fromEffectPackage(
+    '@modern-js/bff-effect/effect-edge',
+  ) as typeof EffectEdgeModule;
+  const { getEffectContextStorage } = fromEffectPackage(
+    '@modern-js/bff-effect/context',
+  ) as typeof EffectContextModule;
+  const handlerFactoryRegistry: unknown = fromEffectPackage(
+    `#effect-entry-shape-${'registry'}`,
+  );
+  const version = (fromAdapter(effectPackageJson) as { version: string })
+    .version;
+  hostShared = {
+    [EFFECT_BFF_HANDLER_FACTORY_REGISTRY_SHARE]: {
+      version,
+      lib: () => handlerFactoryRegistry,
+      shareConfig: { singleton: true, requiredVersion: false },
+    },
+    [EFFECT_BFF_CONTEXT_STORAGE_SHARE]: {
+      version,
+      lib: getEffectContextStorage,
+      shareConfig: { singleton: true, requiredVersion: false },
+    },
+  };
+  return hostShared;
+}
+
+/**
+ * Adds the host shares to caller shares. Their names are reserved: a caller
+ * replacement would make containers use a registry or a request storage this
+ * host never consults.
+ */
+export function withEffectBffHostShared(
+  shared: BackendFederationRuntimeOptions['shared'],
+): HostShared {
+  const host = effectBffHostShared();
+  const reserved = Object.keys(host).find(name => shared && name in shared);
+  if (reserved !== undefined) {
+    throw new Error(
+      `[BFF][Effect] Share ${reserved} is reserved for the Node host. Remove it from options.shared.`,
+    );
+  }
+  return { ...shared, ...host };
+}

package/src/backend-federation/node.ts

@@ -1,17 +1,21 @@
 import { evaluateNodeBackendFederationCommonJs } from '@modern-js/server-runtime-extensions/backend-federation-security/node';
-
 import { loadBackendFederatedEffectApi as loadUniversalBackendFederatedEffectApi } from './load';
+import { effectBffHostShared, withEffectBffHostShared } from './node-shared';
+
+/** Call for the `shared` option when building a custom runtime for Node hosts. */
+export { effectBffHostShared };
+
 import type {
   BackendFederatedEffectApiModule,
   BackendFederationIdentityLoadOptions,
-  BackendFederationLoadOptions,
 } from './types';
 
-export function loadBackendFederatedEffectApi(
+export async function loadBackendFederatedEffectApi(
   options: BackendFederationIdentityLoadOptions,
 ): Promise<BackendFederatedEffectApiModule> {
   return loadUniversalBackendFederatedEffectApi({
     ...options,
+    shared: withEffectBffHostShared(options.shared),
     entryPolicy: {
       ...options.entryPolicy,
       evaluateCommonJs:

package/src/backend-federation/plugin.ts

@@ -1,35 +1,83 @@
-import type { ModuleFederationRuntimePlugin } from '@module-federation/runtime';
+import type {
+  ModuleFederation,
+  ModuleFederationRuntimePlugin,
+} from '@module-federation/runtime';
 
-import type { BackendFederationLoadEntryPluginOptions } from './types';
+import {
+  PROVIDED_ENTRY_SCHEME,
+  registerRemoteContainer,
+} from './integrity-plugin';
+import type {
+  BackendFederationEntryExports,
+  BackendFederationLoadEntryPluginOptions,
+} from './types';
 
+function toContainer(entry: BackendFederationEntryExports) {
+  return {
+    get(id: string) {
+      return () => Promise.resolve(entry.get(id)).then(factory => factory());
+    },
+    init(...args: unknown[]) {
+      return entry.init?.(...args);
+    },
+  };
+}
+
+/**
+ * Serves binding:, service: and static: entries. The provider resolves each
+ * remote once per runtime and registers the container with that runtime only.
+ */
 export function createBackendFederationLoadEntryPlugin(
   options: BackendFederationLoadEntryPluginOptions,
 ): ModuleFederationRuntimePlugin {
+  const provided = new WeakMap<ModuleFederation, Map<string, Promise<void>>>();
+
   return {
     name: 'modernjs-backend-federation-load-entry',
-    loadEntry({ remoteInfo }) {
-      return Promise.resolve(
-        options.resolveEntry({
-          name: remoteInfo.name,
-          entry: remoteInfo.entry,
-          type: remoteInfo.type,
-          entryGlobalName: remoteInfo.entryGlobalName,
-          shareScope: remoteInfo.shareScope,
-        }),
-      ).then(entry => {
-        if (entry === undefined) {
-          return;
-        }
-        return {
-          get(id: string) {
-            return () =>
-              Promise.resolve(entry.get(id)).then(factory => factory());
-          },
-          init(...args: unknown[]) {
-            return entry.init?.(...args);
-          },
-        };
-      });
+    afterMatchRemote({ origin, remoteInfo }) {
+      if (
+        remoteInfo === undefined ||
+        !PROVIDED_ENTRY_SCHEME.test(remoteInfo.entry)
+      ) {
+        return;
+      }
+      let entries = provided.get(origin);
+      // The first provider that registers a container wins; later ones are
+      // not consulted.
+      if (
+        entries?.has(remoteInfo.name) !== true &&
+        origin.moduleCache.get(remoteInfo.name)?.remoteEntryExports !==
+          undefined
+      ) {
+        return;
+      }
+      if (entries === undefined) {
+        entries = new Map();
+        provided.set(origin, entries);
+      }
+      const runtimeEntries = entries;
+      let pending = runtimeEntries.get(remoteInfo.name);
+      if (pending === undefined) {
+        pending = Promise.resolve(
+          options.resolveEntry({
+            name: remoteInfo.name,
+            entry: remoteInfo.entry,
+            type: remoteInfo.type,
+          }),
+        ).then(entry => {
+          if (entry !== undefined) {
+            registerRemoteContainer(origin, remoteInfo, toContainer(entry));
+          }
+        });
+        const settled = pending;
+        runtimeEntries.set(remoteInfo.name, settled);
+        settled.catch(() => {
+          if (runtimeEntries.get(remoteInfo.name) === settled) {
+            runtimeEntries.delete(remoteInfo.name);
+          }
+        });
+      }
+      return pending;
     },
   };
 }

package/src/backend-federation/runtime.ts

@@ -1,99 +1,25 @@
 import { ModuleFederation } from '@module-federation/runtime';
 
-import { loadBackendFederationExpose } from './entry';
-import { createBackendFederationLoadEntryPlugin } from './plugin';
+import { createBackendFederationIntegrityPlugin } from './integrity-plugin';
 import { collectRemotes } from './remotes';
-import type {
-  BackendFederationRemote,
-  BackendFederationRuntimeOptions,
-} from './types';
-
-let nextRuntimeId = 0;
-
-function parseRemoteRequest(request: string) {
-  const [remoteName, ...exposeParts] = request.split('/');
-  if (
-    remoteName === undefined ||
-    remoteName.length === 0 ||
-    exposeParts.length === 0
-  ) {
-    return;
-  }
-  return remoteName;
-}
-
-function createLocalEntryPlugin(
-  options: BackendFederationRuntimeOptions,
-  remotes: BackendFederationRemote[],
-) {
-  return createBackendFederationLoadEntryPlugin({
-    resolveEntry(resolvedRemote) {
-      const remote = remotes.find(
-        candidate => candidate.name === resolvedRemote.name,
-      );
-      if (remote === undefined) {
-        return;
-      }
-      return {
-        get(expose: string) {
-          return () => loadBackendFederationExpose(remote, expose, options);
-        },
-      };
-    },
-  });
-}
-
-function isolateRegisteredRemoteEntries(remotes: BackendFederationRemote[]) {
-  const runtimeId = nextRuntimeId;
-  nextRuntimeId += 1;
-  return remotes.map(remote => ({
-    ...remote,
-    entry: `${remote.entry}#modernjs-backend-runtime-${runtimeId}`,
-  }));
-}
-
-class BackendFederationRuntime extends ModuleFederation {
-  readonly #remoteNames: ReadonlySet<string>;
-
-  constructor(
-    options: BackendFederationRuntimeOptions,
-    remotes: BackendFederationRemote[],
-  ) {
-    super({
-      name: options.hostName,
-      remotes: isolateRegisteredRemoteEntries(remotes),
-      shared: {},
-      plugins: [createLocalEntryPlugin(options, remotes)],
-    });
-    this.#remoteNames = new Set(remotes.map(remote => remote.name));
-  }
-
-  override loadRemote<T>(
-    request: string,
-    loadOptions?: NonNullable<Parameters<ModuleFederation['loadRemote']>[1]>,
-  ): Promise<T | null> {
-    const remoteName = parseRemoteRequest(request);
-    if (remoteName === undefined) {
-      return Promise.reject(
-        new Error(
-          `[BFF][Effect] Invalid backend federation request ${request}.`,
-        ),
-      );
-    }
-    if (!this.#remoteNames.has(remoteName)) {
-      return Promise.reject(
-        new Error(
-          `[BFF][Effect] Missing backend federation remote ${remoteName}.`,
-        ),
-      );
-    }
-    return super.loadRemote<T>(request, loadOptions);
-  }
-}
+import type { BackendFederationRuntimeOptions } from './types';
 
 export function createBackendFederationRuntime(
   options: BackendFederationRuntimeOptions,
 ): ModuleFederation {
   const remotes = collectRemotes(options);
-  return new BackendFederationRuntime(options, remotes);
+  return new ModuleFederation({
+    name: options.hostName,
+    // Remotes use the default share scope, where host shares are registered.
+    remotes: remotes.map(({ name, entry, type }) => ({
+      name,
+      entry,
+      ...(type ? { type } : {}),
+    })),
+    shared: options.shared ?? {},
+    plugins: [
+      ...(options.plugins ?? []),
+      createBackendFederationIntegrityPlugin(options, remotes),
+    ],
+  });
 }

package/src/backend-federation/types.ts

@@ -14,8 +14,6 @@ export type BackendFederationRemote = {
   name: string;
   entry: string;
   type?: 'commonjs-module' | 'module' | string;
-  entryGlobalName?: string;
-  shareScope?: string | string[];
   expose?: typeof BACKEND_FEDERATION_EFFECT_EXPOSE;
   verification?: BackendFederationRemoteEntryVerification;
 };
@@ -25,6 +23,8 @@ export type BackendFederationRuntimeOptions = {
   remote?: BackendFederationRemote;
   remotes?: BackendFederationRemote[];
   plugins?: ModuleFederationRuntimePlugin[];
+  /** Host shares handed to every remote container's `init()`. */
+  shared?: ConstructorParameters<typeof ModuleFederation>[0]['shared'];
   entryPolicy?: BackendFederationRemoteEntryPolicy;
 };
 
@@ -86,12 +86,3 @@ export type BackendFederationIdentityLoadOptions =
   BackendFederationLoadOptions & {
     expected: BackendFederationExpectedIdentity;
   };
-
-export type BackendFederationLoadEntryPlugin = ModuleFederationRuntimePlugin & {
-  loadEntry?: (args: {
-    remoteInfo: BackendFederationRemote;
-  }) =>
-    | BackendFederationEntryExports
-    | undefined
-    | Promise<BackendFederationEntryExports | undefined>;
-};