@bleedingdev/modern-js-plugin-bff-extensions 3.8.3-ultramodern.2

package/src/backend-federation/entry.ts

@@ -0,0 +1,125 @@
+// @effect-diagnostics asyncFunction:off globalFetch:off strictBooleanExpressions:off
+
+import {
+  evaluateBackendFederationCommonJsEntry,
+  loadVerifiedBackendFederationEntry,
+} from '@modern-js/server-runtime-extensions/backend-federation-security';
+import type { ModuleFederationRuntimePlugin } from '@module-federation/runtime';
+
+import type {
+  BackendFederationEntryExports,
+  BackendFederationLoadEntryPlugin,
+  BackendFederationRemote,
+  BackendFederationRuntimeOptions,
+} from './types';
+import { isRecord, normalizeExpose } from './utils';
+
+function decodeDataUrl(url: string) {
+  const commaIndex = url.indexOf(',');
+  if (commaIndex < 0) {
+    throw new Error('[BFF][Effect] Invalid backend federation data URL entry.');
+  }
+  return decodeURIComponent(url.slice(commaIndex + 1));
+}
+
+async function readCommonJsEntrySource(remote: BackendFederationRemote) {
+  if (remote.entry.startsWith('data:')) {
+    return decodeDataUrl(remote.entry);
+  }
+
+  throw new Error(
+    `[BFF][Effect] Backend federation remote ${remote.name} cannot load CommonJS entry ${remote.entry}.`,
+  );
+}
+
+async function importModuleEntry(remote: BackendFederationRemote) {
+  const entry = await import(/* webpackIgnore: true */ remote.entry);
+  return (entry.default ?? entry) as BackendFederationEntryExports;
+}
+
+async function resolvePluginEntry(
+  remote: BackendFederationRemote,
+  plugins: ModuleFederationRuntimePlugin[] | undefined,
+) {
+  for (const plugin of plugins ?? []) {
+    const loadEntry = (plugin as BackendFederationLoadEntryPlugin).loadEntry;
+    if (typeof loadEntry !== 'function') {
+      continue;
+    }
+    const entry = await loadEntry({ remoteInfo: remote });
+    if (entry) {
+      return entry;
+    }
+  }
+}
+
+async function loadBackendFederationEntry(
+  remote: BackendFederationRemote,
+  options: BackendFederationRuntimeOptions,
+) {
+  const requiresVerification = Boolean(
+    remote.verification || options.entryPolicy?.expected,
+  );
+  const isNetworkEntry = /^https?:\/\//iu.test(remote.entry);
+  if (isNetworkEntry && !requiresVerification) {
+    throw new Error(
+      `[BFF][Effect] Backend federation remote ${remote.name} requires verified entry bytes before network execution.`,
+    );
+  }
+  if (requiresVerification) {
+    return loadVerifiedBackendFederationEntry({
+      ...options.entryPolicy,
+      remote,
+      ...(remote.verification ? { verification: remote.verification } : {}),
+    });
+  }
+
+  const pluginEntry = await resolvePluginEntry(remote, options.plugins);
+  if (pluginEntry) {
+    return pluginEntry;
+  }
+
+  if (remote.entryGlobalName) {
+    const globalEntry = (globalThis as Record<string, unknown>)[
+      remote.entryGlobalName
+    ];
+    if (isRecord(globalEntry)) {
+      return globalEntry as unknown as BackendFederationEntryExports;
+    }
+  }
+
+  if (remote.type === 'module' || remote.entry.startsWith('file:')) {
+    return importModuleEntry(remote);
+  }
+
+  return evaluateBackendFederationCommonJsEntry(
+    remote,
+    new TextEncoder().encode(await readCommonJsEntrySource(remote)),
+    options.entryPolicy?.evaluateCommonJs,
+  );
+}
+
+export async function loadBackendFederationExpose(
+  remote: BackendFederationRemote,
+  expose: string,
+  options: BackendFederationRuntimeOptions,
+) {
+  const entry = await loadBackendFederationEntry(remote, options);
+  if (typeof entry.init === 'function') {
+    await entry.init({ hostName: options.hostName });
+  }
+  if (typeof entry.get !== 'function') {
+    throw new Error(
+      `[BFF][Effect] Backend federation remote ${remote.name} entry must expose get().`,
+    );
+  }
+  const factory = await entry.get(expose);
+  if (typeof factory !== 'function') {
+    throw new Error(
+      `[BFF][Effect] Backend federation expose ${remote.name}/${normalizeExpose(
+        expose,
+      )} must load factory function.`,
+    );
+  }
+  return factory();
+}

package/src/backend-federation/identity.ts

@@ -0,0 +1,97 @@
+// @effect-diagnostics strictBooleanExpressions:off
+
+import { isRecord } from './utils';
+
+/**
+ * Mandatory delivery-unit identity for public backend federation loads
+ * (MV-G23, ADR-0019 / RESOLUTION-0001 §2.3): consumers pass the record's
+ * `unitId` + `buildMarker` through to identity validation.
+ */
+export type BackendFederationExpectedIdentity = {
+  unitId: string;
+  buildMarker: string;
+};
+
+export type BackendFederationIdentityIssue = {
+  path: string;
+  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[] = [];
+  const contract = isRecord(loaded)
+    ? loaded.backendFederationContract
+    : undefined;
+  const compatibility = isRecord(contract) ? contract.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}`,
+    });
+  }
+
+  return issues;
+}
+
+export function formatBackendFederationIdentityIssues(
+  issues: BackendFederationIdentityIssue[],
+): string {
+  return issues.map(issue => `${issue.path}: ${issue.message}`).join('; ');
+}

package/src/backend-federation/index.ts

@@ -0,0 +1,30 @@
+// @effect-diagnostics asyncFunction:off globalFetch:off strictBooleanExpressions:off
+
+import {
+  BACKEND_FEDERATION_CONTRACT_VERSION,
+  BACKEND_FEDERATION_EFFECT_EXPOSE,
+  BACKEND_FEDERATION_MANIFEST_FILE,
+  BACKEND_FEDERATION_NODE_ADAPTER_VERSION,
+} from '@modern-js/utils/universal';
+
+export {
+  type BackendFederationExpectedIdentity,
+  type BackendFederationIdentityIssue,
+  validateExpectedBackendFederationIdentity,
+} from './identity';
+export { createBackendFederationLoadEntryPlugin } from './plugin';
+export { createBackendFederationRuntime } from './runtime';
+export type {
+  BackendFederatedEffectApiModule,
+  BackendFederationEntryExports,
+  BackendFederationIdentityLoadOptions,
+  BackendFederationLoadEntryPluginOptions,
+  BackendFederationRemote,
+  BackendFederationRuntimeOptions,
+} from './types';
+export {
+  BACKEND_FEDERATION_CONTRACT_VERSION,
+  BACKEND_FEDERATION_EFFECT_EXPOSE,
+  BACKEND_FEDERATION_MANIFEST_FILE,
+  BACKEND_FEDERATION_NODE_ADAPTER_VERSION,
+};

package/src/backend-federation/legacy-warning.ts

@@ -0,0 +1,2 @@
+export const LEGACY_LOAD_WARNING =
+  '[BFF][Effect] loadBackendFederatedEffectApi was called without an expected delivery-unit identity (expected.unitId + expected.buildMarker). Identity-less public backend loads are deprecated (ADR-0019/MV-G23) and will be rejected in a future major.';

package/src/backend-federation/load.ts

@@ -0,0 +1,102 @@
+import { BACKEND_FEDERATION_EFFECT_EXPOSE } from '@modern-js/utils/universal';
+import * as Effect from 'effect/Effect';
+import * as Logger from 'effect/Logger';
+
+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
+ * `expected.unitId` + `expected.buildMarker`.
+ */
+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) {
+    return Promise.reject(
+      new Error('[BFF][Effect] Missing backend federation remote name.'),
+    );
+  }
+
+  if (options.expected === undefined) {
+    warnLegacyLoad();
+  }
+
+  if (options.runtime !== undefined) {
+    const configuredRemote = collectRemotes(options).find(
+      remote => remote.name === remoteName,
+    );
+    if (
+      configuredRemote === undefined ||
+      !/^(?:binding|service|static):/u.test(configuredRemote.entry)
+    ) {
+      return Promise.reject(
+        new Error(
+          '[BFF][Effect] A custom Module Federation runtime requires a caller-pinned static or service-binding remote and cannot execute network backend federation entries.',
+        ),
+      );
+    }
+    if (
+      configuredRemote.verification !== undefined ||
+      options.entryPolicy?.expected !== undefined
+    ) {
+      return Promise.reject(
+        new Error(
+          '[BFF][Effect] A custom Module Federation runtime cannot bypass verified backend entry loading.',
+        ),
+      );
+    }
+  }
+
+  const runtime = options.runtime ?? createBackendFederationRuntime(options);
+  const expose =
+    options.expose ??
+    options.remote?.expose ??
+    BACKEND_FEDERATION_EFFECT_EXPOSE;
+  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.ts

@@ -0,0 +1,33 @@
+import { evaluateNodeBackendFederationCommonJs } from '@modern-js/server-runtime-extensions/backend-federation-security/node';
+
+import type { BackendFederationExpectedIdentity } from './identity';
+import { loadBackendFederatedEffectApi as loadUniversalBackendFederatedEffectApi } from './load';
+import type {
+  BackendFederatedEffectApiModule,
+  BackendFederationIdentityLoadOptions,
+  BackendFederationLoadOptions,
+} from './types';
+
+export 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,
+    entryPolicy: {
+      ...options.entryPolicy,
+      evaluateCommonJs:
+        options.entryPolicy?.evaluateCommonJs ??
+        evaluateNodeBackendFederationCommonJs,
+    },
+  });
+}

package/src/backend-federation/plugin.ts

@@ -0,0 +1,35 @@
+import type { ModuleFederationRuntimePlugin } from '@module-federation/runtime';
+
+import type { BackendFederationLoadEntryPluginOptions } from './types';
+
+export function createBackendFederationLoadEntryPlugin(
+  options: BackendFederationLoadEntryPluginOptions,
+): ModuleFederationRuntimePlugin {
+  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);
+          },
+        };
+      });
+    },
+  };
+}

package/src/backend-federation/remotes.ts

@@ -0,0 +1,17 @@
+import type { BackendFederationRuntimeOptions } from './types';
+
+export function collectRemotes(options: BackendFederationRuntimeOptions) {
+  const remotes = [...(options.remotes ?? [])];
+  const configuredRemote = options.remote;
+  if (configuredRemote !== undefined) {
+    const existingIndex = remotes.findIndex(
+      remote => remote.name === configuredRemote.name,
+    );
+    if (existingIndex >= 0) {
+      remotes[existingIndex] = configuredRemote;
+    } else {
+      remotes.push(configuredRemote);
+    }
+  }
+  return remotes;
+}

package/src/backend-federation/runtime.ts

@@ -0,0 +1,99 @@
+import { ModuleFederation } from '@module-federation/runtime';
+
+import { loadBackendFederationExpose } from './entry';
+import { createBackendFederationLoadEntryPlugin } from './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);
+  }
+}
+
+export function createBackendFederationRuntime(
+  options: BackendFederationRuntimeOptions,
+): ModuleFederation {
+  const remotes = collectRemotes(options);
+  return new BackendFederationRuntime(options, remotes);
+}

package/src/backend-federation/types.ts

@@ -0,0 +1,103 @@
+import type { EffectApiModule } from '@modern-js/bff-effect/effect';
+import type {
+  BackendFederationRemoteEntryPolicy,
+  BackendFederationRemoteEntryVerification,
+} from '@modern-js/server-runtime-extensions/backend-federation-security';
+import type { BACKEND_FEDERATION_EFFECT_EXPOSE } from '@modern-js/utils/universal';
+import type {
+  ModuleFederation,
+  ModuleFederationRuntimePlugin,
+} from '@module-federation/runtime';
+import type { BackendFederationExpectedIdentity } from './identity';
+
+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;
+};
+
+export type BackendFederationRuntimeOptions = {
+  hostName: string;
+  remote?: BackendFederationRemote;
+  remotes?: BackendFederationRemote[];
+  plugins?: ModuleFederationRuntimePlugin[];
+  entryPolicy?: BackendFederationRemoteEntryPolicy;
+};
+
+export type BackendFederationEntryExports = {
+  get: (
+    id: string,
+  ) =>
+    | (() => Promise<unknown> | unknown)
+    | Promise<() => Promise<unknown> | unknown>;
+  init?: (...args: unknown[]) => void | Promise<void>;
+};
+
+export type BackendFederatedEffectApiModule = EffectApiModule & {
+  backendFederationContract?: {
+    compatibility?: {
+      build?: unknown;
+      contractVersion?: unknown;
+      nodeAdapterVersion?: unknown;
+      packageName?: unknown;
+      /**
+       * ADR-0019 delivery-unit identity root, generator-emitted alongside
+       * manifest's `versionBoundary.deliveryUnit`. Additive/optional.
+       */
+      unitId?: unknown;
+      /** ADR-0019 delivery-unit source revision. Additive/optional. */
+      sourceRevision?: unknown;
+    };
+    name?: unknown;
+    role?: unknown;
+    runtimeFramework?: unknown;
+    strictEffectApproach?: unknown;
+  };
+  contract?: unknown;
+  operationContexts?: unknown;
+  runtime?: unknown;
+};
+
+export type BackendFederationLoadEntryPluginOptions = {
+  resolveEntry: (
+    remote: BackendFederationRemote,
+  ) =>
+    | BackendFederationEntryExports
+    | undefined
+    | Promise<BackendFederationEntryExports | undefined>;
+};
+
+export type BackendFederationLoadOptions = BackendFederationRuntimeOptions & {
+  runtime?: ModuleFederation;
+  remoteName?: string;
+  expose?: string;
+};
+
+/**
+ * Identity-aware public load options (MV-G23): the expected delivery-unit
+ * `unitId` + `buildMarker` are mandatory and validated against the loaded
+ * expose's compatibility metadata.
+ */
+export type BackendFederationIdentityLoadOptions =
+  BackendFederationLoadOptions & {
+    expected: BackendFederationExpectedIdentity;
+    /**
+     * Tolerate legacy exposes without identity metadata (mismatching declared
+     * values still fail). Prefer leaving this unset: identity-less exposes
+     * cannot be validated against a resolved delivery-unit record.
+     */
+    allowMissingIdentityMetadata?: boolean;
+  };
+
+export type BackendFederationLoadEntryPlugin = ModuleFederationRuntimePlugin & {
+  loadEntry?: (args: {
+    remoteInfo: BackendFederationRemote;
+  }) =>
+    | BackendFederationEntryExports
+    | undefined
+    | Promise<BackendFederationEntryExports | undefined>;
+};

package/src/backend-federation/utils.ts

@@ -0,0 +1,7 @@
+export function normalizeExpose(expose: string) {
+  return expose.replace(/^\.\//u, '');
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}