@bleedingdev/modern-js-plugin-bff-extensions 3.9.0-ultramodern.2 → 3.9.0-ultramodern.20

package/src/backend-federation/identity.ts

@@ -17,77 +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: with an expectation present there is
- * no legacy escape hatch.
- */
-export function validateExpectedBackendFederationIdentity(
-  loaded: unknown,
-  expected: BackendFederationExpectedIdentity,
-  options: {
-    /**
-     * Tolerate exposes that declare no identity metadata (legacy modules).
-     * Mismatching declared values still fail. Used by the manifest adapter,
-     * whose manifest-side identity is already validated against `expected`;
-     * the raw identity-aware loader is strict.
-     */
-    allowMissingIdentityMetadata?: boolean;
-  } = {},
-): BackendFederationIdentityIssue[] {
-  const allowMissing = options.allowMissingIdentityMetadata === true;
-  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)) {
-    if (allowMissing) {
-      return [];
-    }
-    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) {
-    if (!allowMissing) {
-      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) {
-    if (!allowMissing) {
-      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/index.ts

@@ -5,7 +5,7 @@ import {
   BACKEND_FEDERATION_EFFECT_EXPOSE,
   BACKEND_FEDERATION_MANIFEST_FILE,
   BACKEND_FEDERATION_NODE_ADAPTER_VERSION,
-} from '@modern-js/utils/universal';
+} from '@modern-js/backend-federation-contracts';
 
 export {
   type BackendFederationExpectedIdentity,

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

@@ -1,31 +1,14 @@
-import { BACKEND_FEDERATION_EFFECT_EXPOSE } from '@modern-js/utils/universal';
-import * as Effect from 'effect/Effect';
-import * as Logger from 'effect/Logger';
+import { BACKEND_FEDERATION_EFFECT_EXPOSE } from '@modern-js/backend-federation-contracts';
 
-import { type BackendFederationExpectedIdentity } from './identity';
-import { LEGACY_LOAD_WARNING } from './legacy-warning';
 import { collectRemotes } from './remotes';
 import { createBackendFederationRuntime } from './runtime';
 import type {
   BackendFederatedEffectApiModule,
   BackendFederationIdentityLoadOptions,
-  BackendFederationLoadOptions,
 } from './types';
 import { normalizeExpose } from './utils';
 import { validateLoadedBackendFederatedEffectApi } from './validate-loaded';
 
-const legacyWarningLogger = Logger.withLeveledConsole(Logger.formatLogFmt);
-
-function warnLegacyLoad() {
-  Effect.runSync(
-    Effect.provideService(
-      Effect.logWarning(LEGACY_LOAD_WARNING),
-      Logger.CurrentLoggers,
-      new Set([legacyWarningLogger]),
-    ),
-  );
-}
-
 /**
  * Load a federated Effect API with mandatory delivery-unit identity
  * validation (MV-G23): the loaded expose's compatibility metadata must match
@@ -33,20 +16,6 @@ function warnLegacyLoad() {
  */
 export function loadBackendFederatedEffectApi(
   options: BackendFederationIdentityLoadOptions,
-): Promise<BackendFederatedEffectApiModule>;
-/**
- * @deprecated Pass `expected` (delivery-unit `unitId` + `buildMarker`).
- * Loads without an expected identity cannot be validated against a resolved
- * delivery-unit record and emit a runtime warning.
- */
-export function loadBackendFederatedEffectApi(
-  options: BackendFederationLoadOptions,
-): Promise<BackendFederatedEffectApiModule>;
-export function loadBackendFederatedEffectApi(
-  options: BackendFederationLoadOptions & {
-    expected?: BackendFederationExpectedIdentity;
-    allowMissingIdentityMetadata?: boolean;
-  },
 ): Promise<BackendFederatedEffectApiModule> {
   const remoteName = options.remote?.name ?? options.remoteName;
   if (remoteName === undefined || remoteName.length === 0) {
@@ -55,8 +24,12 @@ export function loadBackendFederatedEffectApi(
     );
   }
 
-  if (options.expected === undefined) {
-    warnLegacyLoad();
+  if (!options.expected?.unitId || !options.expected.buildMarker) {
+    return Promise.reject(
+      new Error(
+        '[BFF][Effect] Backend federation requires expected.unitId and expected.buildMarker.',
+      ),
+    );
   }
 
   if (options.runtime !== undefined) {
@@ -93,7 +66,6 @@ export function loadBackendFederatedEffectApi(
   const remoteRequest = `${remoteName}/${normalizeExpose(expose)}`;
   return runtime.loadRemote(remoteRequest).then(loaded =>
     validateLoadedBackendFederatedEffectApi(loaded, {
-      allowMissingIdentityMetadata: options.allowMissingIdentityMetadata,
       expected: options.expected,
       remoteName,
       remoteRequest,

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,28 +1,21 @@
 import { evaluateNodeBackendFederationCommonJs } from '@modern-js/server-runtime-extensions/backend-federation-security/node';
-
-import type { BackendFederationExpectedIdentity } from './identity';
 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>;
-/** @deprecated Pass `expected` delivery-unit identity. */
-export function loadBackendFederatedEffectApi(
-  options: BackendFederationLoadOptions,
-): Promise<BackendFederatedEffectApiModule>;
-export function loadBackendFederatedEffectApi(
-  options: BackendFederationLoadOptions & {
-    expected?: BackendFederationExpectedIdentity;
-    allowMissingIdentityMetadata?: boolean;
-  },
 ): 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;
     },
   };
 }