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

package/src/backend-federation/validate-loaded.ts

@@ -0,0 +1,72 @@
+import type { BackendFederationExpectedIdentity } from './identity';
+import {
+  formatBackendFederationIdentityIssues,
+  validateExpectedBackendFederationIdentity,
+} from './identity';
+import type { BackendFederatedEffectApiModule } from './types';
+import { isRecord } from './utils';
+
+export function validateLoadedBackendFederatedEffectApi(
+  loaded: unknown,
+  options: {
+    allowMissingIdentityMetadata?: boolean;
+    expected?: BackendFederationExpectedIdentity;
+    remoteName: string;
+    remoteRequest: string;
+  },
+): BackendFederatedEffectApiModule {
+  if (!isRecord(loaded)) {
+    throw new Error(
+      `[BFF][Effect] Backend federation expose ${options.remoteRequest} must load an object module.`,
+    );
+  }
+
+  const backendContract = loaded.backendFederationContract;
+  if (
+    !isRecord(backendContract) ||
+    backendContract.strictEffectApproach !== true
+  ) {
+    throw new Error(
+      `[BFF][Effect] Backend federation expose ${options.remoteRequest} must expose strict Effect metadata (strictEffectApproach: true).`,
+    );
+  }
+
+  if (backendContract.runtimeFramework !== 'effect') {
+    throw new Error(
+      `[BFF][Effect] Backend federation expose ${options.remoteRequest} must expose strict Effect metadata (runtimeFramework: "effect").`,
+    );
+  }
+
+  if (
+    typeof backendContract.name === 'string' &&
+    backendContract.name !== options.remoteName
+  ) {
+    throw new Error(
+      `[BFF][Effect] Backend federation expose ${options.remoteRequest} metadata name mismatch: expected ${options.remoteName}, received ${backendContract.name}.`,
+    );
+  }
+
+  if (!('runtime' in loaded)) {
+    throw new Error(
+      `[BFF][Effect] Backend federation expose ${options.remoteRequest} must expose runtime.`,
+    );
+  }
+
+  if (options.expected !== undefined) {
+    const issues = validateExpectedBackendFederationIdentity(
+      loaded,
+      options.expected,
+      {
+        allowMissingIdentityMetadata:
+          options.allowMissingIdentityMetadata === true,
+      },
+    );
+    if (issues.length > 0) {
+      throw new Error(
+        `[BFF][Effect] Backend federation expose ${options.remoteRequest} delivery-unit identity mismatch: ${formatBackendFederationIdentityIssues(issues)}.`,
+      );
+    }
+  }
+
+  return loaded as BackendFederatedEffectApiModule;
+}

package/src/backend-federation-manifest/errors.ts

@@ -0,0 +1,85 @@
+// @effect-diagnostics asyncFunction:off extendsNativeError:off globalTimers:off newPromise:off strictBooleanExpressions:off
+
+export type BackendFederationManifestAdapterErrorCode =
+  | 'manifest_unavailable'
+  | 'manifest_invalid'
+  | 'remote_unavailable'
+  | 'strict_effect_required'
+  | 'timeout'
+  | 'version_mismatch';
+
+export const BACKEND_FEDERATION_MANIFEST_ADAPTER_FAILURE_EVENT =
+  'modernjs:microvertical-server-fallback' as const;
+
+export class BackendFederationManifestAdapterError extends Error {
+  code: BackendFederationManifestAdapterErrorCode;
+  readonly failureEvent = BACKEND_FEDERATION_MANIFEST_ADAPTER_FAILURE_EVENT;
+  details?: Record<string, unknown>;
+
+  constructor(
+    code: BackendFederationManifestAdapterErrorCode,
+    message: string,
+    cause?: unknown,
+    details?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = 'BackendFederationManifestAdapterError';
+    this.code = code;
+
+    if (details) {
+      this.details = details;
+    }
+
+    if (cause !== undefined) {
+      (this as { cause?: unknown }).cause = cause;
+    }
+  }
+}
+
+export function assertManifestAdapter(
+  condition: unknown,
+  code: BackendFederationManifestAdapterErrorCode,
+  message: string,
+): asserts condition {
+  if (!condition) {
+    throw new BackendFederationManifestAdapterError(code, message);
+  }
+}
+
+export function assertVersionValue(
+  actual: string | undefined,
+  expected: string | undefined,
+  label: string,
+  details?: Record<string, unknown>,
+) {
+  if (expected === undefined) {
+    return;
+  }
+
+  if (actual !== expected) {
+    throw new BackendFederationManifestAdapterError(
+      'version_mismatch',
+      `[BFF][Effect] Backend federation ${label} mismatch: expected ${expected}, received ${actual ?? 'undefined'}.`,
+      undefined,
+      { label, expected, received: actual, ...details },
+    );
+  }
+}
+
+export function assertConsistentValue(
+  left: string | undefined,
+  right: string | undefined,
+  label: string,
+  details?: Record<string, unknown>,
+) {
+  if (left === undefined || right === undefined || left === right) {
+    return;
+  }
+
+  throw new BackendFederationManifestAdapterError(
+    'version_mismatch',
+    `[BFF][Effect] Backend federation ${label} mismatch: expected ${left}, received ${right}.`,
+    undefined,
+    { label, expected: left, received: right, ...details },
+  );
+}

package/src/backend-federation-manifest/index.ts

@@ -0,0 +1,11 @@
+export type { BackendFederationManifestAdapterErrorCode } from './errors';
+export { BackendFederationManifestAdapterError } from './errors';
+export { loadBackendFederationManifest } from './reference';
+export { resolveBackendFederationRemoteFromManifest } from './remote';
+export type {
+  BackendFederationManifest,
+  BackendFederationManifestAdapterFallback,
+  BackendFederationManifestAdapterOptions,
+  BackendFederationManifestFetchResponse,
+  BackendFederationVersionBoundaryExpectation,
+} from './types';

package/src/backend-federation-manifest/load.ts

@@ -0,0 +1,266 @@
+// @effect-diagnostics asyncFunction:off extendsNativeError:off globalTimers:off newPromise:off strictBooleanExpressions:off
+
+import {
+  BACKEND_FEDERATION_EFFECT_EXPOSE,
+  type BackendFederatedEffectApiModule,
+  type BackendFederationRemote,
+} from '../backend-federation';
+import { loadBackendFederatedEffectApi } from '../backend-federation/load';
+import { BackendFederationManifestAdapterError } from './errors';
+import { loadBackendFederationManifest } from './reference';
+import { resolveBackendFederationRemoteFromManifest } from './remote';
+import type {
+  BackendFederationManifest,
+  BackendFederationManifestAdapterOptions,
+} from './types';
+import {
+  classifyLoadError,
+  validateBackendFederationManifest,
+  validateLoadedBackendFederationContract,
+} from './validation';
+
+function createManifestLoadScope(
+  options: BackendFederationManifestAdapterOptions,
+) {
+  const controller = new AbortController();
+  const policyTimeouts = [
+    options.manifestPolicy?.timeoutMs,
+    options.entryPolicy?.timeoutMs,
+  ].filter((timeout): timeout is number => timeout !== undefined);
+  const configuredTimeouts = [options.timeoutMs, ...policyTimeouts].filter(
+    (timeout): timeout is number => timeout !== undefined,
+  );
+  for (const timeout of configuredTimeouts) {
+    if (!Number.isSafeInteger(timeout) || timeout < 0) {
+      throw new BackendFederationManifestAdapterError(
+        'manifest_invalid',
+        '[BFF][Effect] Backend federation timeoutMs must be a non-negative safe integer.',
+      );
+    }
+  }
+  const timeoutMs =
+    options.timeoutMs ??
+    (policyTimeouts.length > 0 ? Math.min(...policyTimeouts) : 0);
+  const inputSignals = [
+    options.signal,
+    options.manifestPolicy?.signal,
+    options.entryPolicy?.signal,
+  ].filter((signal): signal is AbortSignal => signal !== undefined);
+  const abortListeners: Array<[AbortSignal, () => void]> = [];
+  let timedOut = false;
+  const forwardAbort = (signal: AbortSignal) => {
+    controller.abort(signal.reason);
+  };
+  for (const signal of inputSignals) {
+    if (signal.aborted) {
+      forwardAbort(signal);
+      break;
+    }
+    const listener = () => forwardAbort(signal);
+    abortListeners.push([signal, listener]);
+    signal.addEventListener('abort', listener, { once: true });
+  }
+
+  const timeout =
+    timeoutMs > 0
+      ? setTimeout(() => {
+          if (controller.signal.aborted) {
+            return;
+          }
+          timedOut = true;
+          controller.abort(
+            new BackendFederationManifestAdapterError(
+              'timeout',
+              `[BFF][Effect] Backend federation load timed out after ${timeoutMs}ms.`,
+            ),
+          );
+        }, timeoutMs)
+      : undefined;
+
+  return {
+    cleanup() {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+      for (const [signal, listener] of abortListeners) {
+        signal.removeEventListener('abort', listener);
+      }
+    },
+    signal: controller.signal,
+    timedOut: () => timedOut,
+    timeoutMs,
+  };
+}
+
+function isRemoteManifestReference(
+  options: BackendFederationManifestAdapterOptions,
+) {
+  if (options.manifest !== undefined || options.manifestPath) {
+    return false;
+  }
+  return Boolean(options.manifestUrl || options.manifestEnv);
+}
+
+function hasPinnedRemoteEntryExpectation(
+  options: BackendFederationManifestAdapterOptions,
+) {
+  const expected = options.entryPolicy?.expected;
+  return (
+    typeof expected?.byteLength === 'number' &&
+    typeof expected.entryUrl === 'string' &&
+    typeof expected.remoteName === 'string' &&
+    typeof expected.sha256 === 'string'
+  );
+}
+
+function isCallerPinnedStaticRemote(
+  options: BackendFederationManifestAdapterOptions,
+  remote: BackendFederationRemote,
+) {
+  return (
+    options.remote?.entry === remote.entry &&
+    options.remote?.name === remote.name &&
+    /^(?:binding|service|static):/u.test(remote.entry)
+  );
+}
+
+function throwIfManifestLoadAborted(signal: AbortSignal) {
+  if (signal.aborted) {
+    throw new BackendFederationManifestAdapterError(
+      'remote_unavailable',
+      '[BFF][Effect] Backend federation load was aborted before remote execution.',
+      signal.reason,
+    );
+  }
+}
+
+export async function loadBackendFederatedEffectApiFromManifest(
+  options: BackendFederationManifestAdapterOptions,
+): Promise<BackendFederatedEffectApiModule> {
+  let manifest: BackendFederationManifest | undefined;
+  let remote: BackendFederationRemote | undefined;
+  let scope: ReturnType<typeof createManifestLoadScope> | undefined;
+
+  try {
+    scope = createManifestLoadScope(options);
+    throwIfManifestLoadAborted(scope.signal);
+    manifest = await loadBackendFederationManifest({
+      ...options,
+      manifestPolicy: {
+        ...options.manifestPolicy,
+        signal: scope.signal,
+        timeoutMs: 0,
+      },
+      signal: scope.signal,
+      timeoutMs: 0,
+    });
+    validateBackendFederationManifest(manifest, options.expected);
+    remote = resolveBackendFederationRemoteFromManifest(
+      manifest,
+      options.remote,
+    );
+    throwIfManifestLoadAborted(scope.signal);
+    const remoteManifest = isRemoteManifestReference(options);
+    if (remoteManifest && options.runtime !== undefined) {
+      throw new BackendFederationManifestAdapterError(
+        'manifest_invalid',
+        `[BFF][Effect] Backend federation remote ${remote.name} cannot use a custom runtime selected by a network manifest.`,
+      );
+    }
+    if (
+      remoteManifest &&
+      !/^https?:\/\//iu.test(remote.entry) &&
+      !isCallerPinnedStaticRemote(options, remote)
+    ) {
+      throw new BackendFederationManifestAdapterError(
+        'manifest_invalid',
+        `[BFF][Effect] Backend federation network manifests cannot select local, global, or plugin entry ${remote.entry}. Pin a static/service binding in caller configuration or use a verified HTTP(S) entry.`,
+      );
+    }
+    if (
+      remoteManifest &&
+      /^https?:\/\//iu.test(remote.entry) &&
+      !hasPinnedRemoteEntryExpectation(options)
+    ) {
+      throw new BackendFederationManifestAdapterError(
+        'manifest_invalid',
+        `[BFF][Effect] Backend federation remote ${remote.name} from a network manifest requires caller-pinned entryUrl, remoteName, sha256, and byteLength values.`,
+      );
+    }
+    if (
+      /^https?:\/\//iu.test(remote.entry) &&
+      remote.verification === undefined &&
+      options.entryPolicy?.expected === undefined
+    ) {
+      throw new BackendFederationManifestAdapterError(
+        'manifest_invalid',
+        `[BFF][Effect] Backend federation remote ${remote.name} requires entry.sha256 and entry.byteLength before network execution.`,
+      );
+    }
+    if (/^https?:\/\//iu.test(remote.entry) && options.runtime !== undefined) {
+      throw new BackendFederationManifestAdapterError(
+        'manifest_invalid',
+        `[BFF][Effect] Backend federation remote ${remote.name} cannot use a custom runtime for network entry execution.`,
+      );
+    }
+
+    const loaded = await loadBackendFederatedEffectApi({
+      hostName: options.hostName,
+      remote,
+      ...(options.plugins ? { plugins: options.plugins } : {}),
+      entryPolicy: {
+        ...options.entryPolicy,
+        signal: scope.signal,
+        timeoutMs: 0,
+      },
+      ...(options.runtime ? { runtime: options.runtime } : {}),
+      // MV-G23: route the manifest adapter through the raw loader's shared
+      // delivery-unit identity validation when an identity is expected.
+      ...(options.expected?.unitId && options.expected.buildMarker
+        ? {
+            expected: {
+              unitId: options.expected.unitId,
+              buildMarker: options.expected.buildMarker,
+            },
+            // The manifest's identity is already validated against
+            // `expected`; legacy exposes without identity metadata stay
+            // loadable (mismatching declared values still fail).
+            allowMissingIdentityMetadata: true,
+          }
+        : {}),
+    }).catch((error: unknown) => {
+      throw new BackendFederationManifestAdapterError(
+        scope?.timedOut() === true ? 'timeout' : classifyLoadError(error),
+        `[BFF][Effect] Backend federation remote ${remote?.name ?? 'unknown'} could not load ${remote?.expose ?? BACKEND_FEDERATION_EFFECT_EXPOSE}.`,
+        error,
+      );
+    });
+
+    validateLoadedBackendFederationContract(loaded, manifest, remote);
+
+    return loaded;
+  } catch (error) {
+    const adapterError =
+      scope?.timedOut() === true
+        ? new BackendFederationManifestAdapterError(
+            'timeout',
+            `[BFF][Effect] Backend federation load timed out after ${scope.timeoutMs}ms.`,
+            error,
+          )
+        : error instanceof BackendFederationManifestAdapterError
+          ? error
+          : new BackendFederationManifestAdapterError(
+              'remote_unavailable',
+              '[BFF][Effect] Backend federation manifest adapter failed.',
+              error,
+            );
+
+    if (options.fallback) {
+      return options.fallback(adapterError, { manifest, remote });
+    }
+
+    throw adapterError;
+  } finally {
+    scope?.cleanup();
+  }
+}

package/src/backend-federation-manifest/metadata.ts

@@ -0,0 +1,73 @@
+// @effect-diagnostics asyncFunction:off extendsNativeError:off globalTimers:off newPromise:off strictBooleanExpressions:off
+
+import {
+  backendFederationMetadata as sharedBackendFederationMetadata,
+  backendFederationVersionBoundary as sharedBackendFederationVersionBoundary,
+} from '@modern-js/utils/universal';
+import type { BackendFederationManifest } from './types';
+
+export function stringValue(value: unknown) {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+export function recordField(
+  value: Record<string, unknown> | undefined,
+  field: string,
+) {
+  const fieldValue = value?.[field];
+  return isRecord(fieldValue) ? fieldValue : undefined;
+}
+
+export function resolveRemoteEntryFromMetadata(
+  manifest: BackendFederationManifest,
+) {
+  const metaData = recordField(manifest, 'metaData');
+  const remoteEntry = recordField(metaData, 'remoteEntry');
+  const publicPath =
+    stringValue(metaData?.publicPath) ?? stringValue(metaData?.ssrPublicPath);
+  const entryName = stringValue(remoteEntry?.name);
+
+  if (!publicPath || !entryName) {
+    return undefined;
+  }
+
+  const entryPath = stringValue(remoteEntry?.path) ?? '';
+  const normalizedBase = publicPath.replace(/\/+$/u, '');
+  const normalizedPath = entryPath.replace(/^\/+|\/+$/gu, '');
+
+  return [normalizedBase, normalizedPath, entryName].filter(Boolean).join('/');
+}
+
+export function backendFederationMetadata(manifest: BackendFederationManifest) {
+  return sharedBackendFederationMetadata(manifest);
+}
+
+export function versionBoundaryMetadata(manifest: BackendFederationManifest) {
+  return sharedBackendFederationVersionBoundary(manifest);
+}
+
+export function deliveryUnitMetadata(
+  record: Record<string, unknown> | undefined,
+) {
+  return recordField(record, 'deliveryUnit');
+}
+
+/**
+ * Resolves the delivery-unit identity root for a manifest (ADR-0019 §3):
+ * prefers `versionBoundary.deliveryUnit`, falls back to the top-level
+ * `backendFederation.deliveryUnit` record. Both are additive/optional so
+ * legacy manifests without delivery-unit metadata continue to validate.
+ */
+export function manifestDeliveryUnit(
+  backendFederation: Record<string, unknown> | undefined,
+  boundary: Record<string, unknown> | undefined,
+) {
+  return {
+    boundary: deliveryUnitMetadata(boundary),
+    top: deliveryUnitMetadata(backendFederation),
+  };
+}

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

@@ -0,0 +1,19 @@
+import { evaluateNodeBackendFederationCommonJs } from '@modern-js/server-runtime-extensions/backend-federation-security/node';
+
+import type { BackendFederatedEffectApiModule } from '../backend-federation';
+import { loadBackendFederatedEffectApiFromManifest as loadUniversalBackendFederatedEffectApiFromManifest } from './load';
+import type { BackendFederationManifestAdapterOptions } from './types';
+
+export function loadBackendFederatedEffectApiFromManifest(
+  options: BackendFederationManifestAdapterOptions,
+): Promise<BackendFederatedEffectApiModule> {
+  return loadUniversalBackendFederatedEffectApiFromManifest({
+    ...options,
+    entryPolicy: {
+      ...options.entryPolicy,
+      evaluateCommonJs:
+        options.entryPolicy?.evaluateCommonJs ??
+        evaluateNodeBackendFederationCommonJs,
+    },
+  });
+}