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

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

@@ -0,0 +1,240 @@
+// @effect-diagnostics asyncFunction:off extendsNativeError:off globalTimers:off newPromise:off strictBooleanExpressions:off
+
+import {
+  BackendFederationRemoteEntryError,
+  loadBoundedBackendFederationResource,
+  redactBackendFederationUrl,
+} from '@modern-js/server-runtime-extensions/backend-federation-security';
+import { BACKEND_FEDERATION_MANIFEST_FILE } from '../backend-federation';
+import {
+  assertManifestAdapter,
+  BackendFederationManifestAdapterError,
+} from './errors';
+import { isRecord } from './metadata';
+import type {
+  BackendFederationManifest,
+  BackendFederationManifestAdapterOptions,
+} from './types';
+
+function getProcessEnv() {
+  return typeof process !== 'undefined' ? process.env : undefined;
+}
+
+type ManifestReferenceSource = 'env' | 'path' | 'url';
+
+function resolveManifestReferenceSource(
+  options: Pick<
+    BackendFederationManifestAdapterOptions,
+    'manifestEnv' | 'manifestPath' | 'manifestUrl'
+  >,
+): ManifestReferenceSource | undefined {
+  if (options.manifestPath) {
+    return 'path';
+  }
+  if (options.manifestUrl) {
+    return 'url';
+  }
+  if (options.manifestEnv) {
+    return 'env';
+  }
+  return undefined;
+}
+
+export function resolveBackendFederationManifestReference(
+  options: Pick<
+    BackendFederationManifestAdapterOptions,
+    'env' | 'manifestEnv' | 'manifestPath' | 'manifestUrl'
+  >,
+) {
+  if (options.manifestPath) {
+    return options.manifestPath;
+  }
+
+  if (options.manifestUrl) {
+    return options.manifestUrl;
+  }
+
+  if (!options.manifestEnv) {
+    return undefined;
+  }
+
+  return (
+    options.env?.[options.manifestEnv] ?? getProcessEnv()?.[options.manifestEnv]
+  );
+}
+
+function assertExpectedIdentityForReference(
+  options: Pick<BackendFederationManifestAdapterOptions, 'expected'>,
+  source: ManifestReferenceSource | undefined,
+) {
+  if (source === undefined || source === 'path') {
+    return;
+  }
+
+  if (options.expected?.unitId && options.expected.buildMarker) {
+    return;
+  }
+
+  throw new BackendFederationManifestAdapterError(
+    'version_mismatch',
+    `[BFF][Effect] Backend federation ${source} manifest references require expected.unitId and expected.buildMarker.`,
+    undefined,
+    {
+      label: 'expected.deliveryUnit',
+      expected: 'unitId + buildMarker',
+      received: options.expected,
+      referenceSource: source,
+    },
+  );
+}
+
+function isHttpUrl(value: string) {
+  return /^https?:\/\//iu.test(value);
+}
+
+function referenceForDiagnostics(reference: string) {
+  return isHttpUrl(reference)
+    ? redactBackendFederationUrl(reference)
+    : '[local manifest]';
+}
+
+async function readFileReference(reference: string) {
+  const [{ fileURLToPath }, fs] = await Promise.all([
+    import('node:url'),
+    import('node:fs/promises'),
+  ]);
+  const filePath = reference.startsWith('file:')
+    ? fileURLToPath(reference)
+    : reference;
+
+  return fs.readFile(filePath, 'utf8');
+}
+
+export async function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number | undefined,
+  label: string,
+) {
+  if (!timeoutMs || timeoutMs <= 0) {
+    return promise;
+  }
+
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<T>((_, reject) => {
+        timeout = setTimeout(() => {
+          reject(
+            new BackendFederationManifestAdapterError(
+              'timeout',
+              `[BFF][Effect] ${label} timed out after ${timeoutMs}ms.`,
+            ),
+          );
+        }, timeoutMs);
+      }),
+    ]);
+  } finally {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+  }
+}
+
+export async function loadBackendFederationManifest(
+  options: Pick<
+    BackendFederationManifestAdapterOptions,
+    | 'env'
+    | 'expected'
+    | 'fetch'
+    | 'manifest'
+    | 'manifestEnv'
+    | 'manifestPolicy'
+    | 'manifestPath'
+    | 'manifestUrl'
+    | 'signal'
+    | 'timeoutMs'
+  >,
+): Promise<BackendFederationManifest> {
+  if (options.manifest) {
+    return options.manifest;
+  }
+
+  const reference = resolveBackendFederationManifestReference(options);
+  if (!reference) {
+    throw new BackendFederationManifestAdapterError(
+      'manifest_unavailable',
+      `[BFF][Effect] Backend federation manifest reference is missing. Pass manifest, manifestPath, manifestUrl, or manifestEnv for ${BACKEND_FEDERATION_MANIFEST_FILE}.`,
+    );
+  }
+  assertExpectedIdentityForReference(
+    options,
+    resolveManifestReferenceSource(options),
+  );
+  const referenceSource = resolveManifestReferenceSource(options);
+  if (referenceSource === 'path' && isHttpUrl(reference)) {
+    throw new BackendFederationManifestAdapterError(
+      'manifest_unavailable',
+      '[BFF][Effect] Backend federation manifestPath must identify an explicit local file. Use manifestUrl for HTTP(S) manifests.',
+    );
+  }
+  if (
+    (referenceSource === 'url' || referenceSource === 'env') &&
+    !isHttpUrl(reference)
+  ) {
+    throw new BackendFederationManifestAdapterError(
+      'manifest_unavailable',
+      `[BFF][Effect] Backend federation ${referenceSource} manifest references must use HTTP(S). Use manifestPath for an explicit local file.`,
+    );
+  }
+
+  try {
+    const diagnosticReference = referenceForDiagnostics(reference);
+    const source = isHttpUrl(reference)
+      ? new TextDecoder('utf-8', { fatal: true }).decode(
+          await loadBoundedBackendFederationResource(reference, {
+            allowInsecureHttp:
+              options.manifestPolicy?.allowInsecureHttp === true,
+            fetch: options.fetch,
+            kind: 'manifest',
+            maxBytes: options.manifestPolicy?.maxBytes,
+            signal: options.manifestPolicy?.signal ?? options.signal,
+            timeoutMs: options.manifestPolicy?.timeoutMs ?? options.timeoutMs,
+          }),
+        )
+      : await withTimeout(
+          readFileReference(reference),
+          options.manifestPolicy?.timeoutMs ?? options.timeoutMs,
+          'Backend federation local manifest',
+        );
+    const manifest = JSON.parse(source) as unknown;
+
+    assertManifestAdapter(
+      isRecord(manifest),
+      'manifest_invalid',
+      `[BFF][Effect] Backend federation manifest ${diagnosticReference} must be a JSON object.`,
+    );
+
+    return manifest;
+  } catch (error) {
+    if (error instanceof BackendFederationManifestAdapterError) {
+      throw error;
+    }
+
+    if (error instanceof BackendFederationRemoteEntryError) {
+      throw new BackendFederationManifestAdapterError(
+        error.code === 'timeout' ? 'timeout' : 'manifest_unavailable',
+        `[BFF][Effect] ${error.message}`,
+        error,
+        error.details,
+      );
+    }
+
+    throw new BackendFederationManifestAdapterError(
+      'manifest_unavailable',
+      `[BFF][Effect] Backend federation manifest ${referenceForDiagnostics(reference)} could not be loaded.`,
+      error,
+    );
+  }
+}

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

@@ -0,0 +1,102 @@
+// @effect-diagnostics asyncFunction:off extendsNativeError:off globalTimers:off newPromise:off strictBooleanExpressions:off
+
+import {
+  BackendFederationRemoteEntryError,
+  resolveBackendFederationRemoteEntryVerification,
+} from '@modern-js/server-runtime-extensions/backend-federation-security';
+import { backendFederationExposeNames } from '@modern-js/utils/universal';
+import {
+  BACKEND_FEDERATION_EFFECT_EXPOSE,
+  type BackendFederationRemote,
+} from '../backend-federation';
+import {
+  assertManifestAdapter,
+  BackendFederationManifestAdapterError,
+} from './errors';
+import {
+  backendFederationMetadata,
+  recordField,
+  resolveRemoteEntryFromMetadata,
+  stringValue,
+} from './metadata';
+import type { BackendFederationManifest } from './types';
+
+export function resolveBackendFederationRemoteFromManifest(
+  manifest: BackendFederationManifest,
+  remoteOverride: Partial<BackendFederationRemote> = {},
+): BackendFederationRemote {
+  const backendFederation = backendFederationMetadata(manifest);
+  const entry = recordField(manifest, 'entry');
+  const metaData = recordField(manifest, 'metaData');
+  const remoteEntry = recordField(metaData, 'remoteEntry');
+  const remoteName =
+    remoteOverride.name ??
+    stringValue(backendFederation?.name) ??
+    stringValue(manifest.name) ??
+    stringValue(manifest.id);
+  const manifestEntryUrl =
+    stringValue(backendFederation?.containerEntry) ??
+    stringValue(entry?.url) ??
+    resolveRemoteEntryFromMetadata(manifest);
+  const remoteEntryUrl = remoteOverride.entry ?? manifestEntryUrl;
+  const remoteType =
+    remoteOverride.type ??
+    stringValue(backendFederation?.remoteType) ??
+    stringValue(entry?.type) ??
+    stringValue(remoteEntry?.type) ??
+    'module';
+  const expose =
+    remoteOverride.expose ??
+    backendFederationExposeNames(backendFederation)[0] ??
+    BACKEND_FEDERATION_EFFECT_EXPOSE;
+  let verification: BackendFederationRemote['verification'];
+  try {
+    const manifestVerification =
+      resolveBackendFederationRemoteEntryVerification(manifest);
+    verification =
+      remoteOverride.verification ??
+      (remoteEntryUrl === manifestEntryUrl ? manifestVerification : undefined);
+  } catch (cause) {
+    if (cause instanceof BackendFederationRemoteEntryError) {
+      throw new BackendFederationManifestAdapterError(
+        cause.code === 'identity_mismatch'
+          ? 'version_mismatch'
+          : 'manifest_invalid',
+        `[BFF][Effect] ${cause.message}`,
+        cause,
+        cause.details,
+      );
+    }
+    throw cause;
+  }
+
+  assertManifestAdapter(
+    remoteName,
+    'manifest_invalid',
+    '[BFF][Effect] Backend federation manifest must declare a remote name.',
+  );
+  assertManifestAdapter(
+    remoteEntryUrl,
+    'manifest_invalid',
+    '[BFF][Effect] Backend federation manifest must declare a backend remote entry URL.',
+  );
+  assertManifestAdapter(
+    expose === BACKEND_FEDERATION_EFFECT_EXPOSE,
+    'manifest_invalid',
+    `[BFF][Effect] Backend federation manifest expose must be ${BACKEND_FEDERATION_EFFECT_EXPOSE}.`,
+  );
+
+  return {
+    name: remoteName,
+    entry: remoteEntryUrl,
+    type: remoteType,
+    ...(verification ? { verification } : {}),
+    ...(remoteOverride.entryGlobalName
+      ? { entryGlobalName: remoteOverride.entryGlobalName }
+      : {}),
+    expose,
+    ...(remoteOverride.shareScope
+      ? { shareScope: remoteOverride.shareScope }
+      : {}),
+  };
+}

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

@@ -0,0 +1,73 @@
+// @effect-diagnostics asyncFunction:off extendsNativeError:off globalTimers:off newPromise:off strictBooleanExpressions:off
+
+import type {
+  BackendFederationRemoteEntryPolicy,
+  BackendFederationResourcePolicy,
+  BackendFederationResourceResponse,
+} from '@modern-js/server-runtime-extensions/backend-federation-security';
+import type {
+  ModuleFederation,
+  ModuleFederationRuntimePlugin,
+} from '@module-federation/runtime';
+import type {
+  BackendFederatedEffectApiModule,
+  BackendFederationRemote,
+} from '../backend-federation';
+import type { BackendFederationManifestAdapterError } from './errors';
+
+export type BackendFederationManifest = Record<string, unknown>;
+
+export type BackendFederationVersionBoundaryExpectation = {
+  buildVersion?: string;
+  /**
+   * Delivery-unit build marker (ADR-0019). Semantically the same value as
+   * `buildVersion`; treated as an alias. If both are set and disagree the
+   * expectation itself is invalid and fails closed before any manifest
+   * comparison runs.
+   */
+  buildMarker?: string;
+  contractVersion?: string;
+  nodeAdapterVersion?: string;
+  packageName?: string;
+  remoteName?: string;
+  /**
+   * Delivery-unit identity root (ADR-0019 §3). When set, the manifest's
+   * `backendFederation.versionBoundary.deliveryUnit.unitId` (or the
+   * top-level `backendFederation.deliveryUnit.unitId` fallback) must match.
+   */
+  unitId?: string;
+  version?: string;
+};
+
+export type BackendFederationManifestFetchResponse =
+  BackendFederationResourceResponse;
+
+export type BackendFederationManifestAdapterFallback = (
+  error: BackendFederationManifestAdapterError,
+  context: {
+    manifest?: BackendFederationManifest;
+    remote?: BackendFederationRemote;
+  },
+) => BackendFederatedEffectApiModule | Promise<BackendFederatedEffectApiModule>;
+
+export type BackendFederationManifestAdapterOptions = {
+  entryPolicy?: BackendFederationRemoteEntryPolicy;
+  env?: Record<string, string | undefined>;
+  expected?: BackendFederationVersionBoundaryExpectation;
+  fallback?: BackendFederationManifestAdapterFallback;
+  fetch?: (
+    url: string,
+    init?: RequestInit,
+  ) => Promise<BackendFederationManifestFetchResponse>;
+  hostName: string;
+  manifest?: BackendFederationManifest;
+  manifestEnv?: string;
+  manifestPolicy?: Omit<BackendFederationResourcePolicy, 'fetch'>;
+  manifestPath?: string;
+  manifestUrl?: string;
+  plugins?: ModuleFederationRuntimePlugin[];
+  remote?: Partial<BackendFederationRemote>;
+  runtime?: ModuleFederation;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+};

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

@@ -0,0 +1,255 @@
+// @effect-diagnostics asyncFunction:off extendsNativeError:off globalTimers:off newPromise:off strictBooleanExpressions:off
+
+import {
+  formatBackendFederationValidationErrors,
+  validateBackendFederationManifest as validateBackendFederationManifestContract,
+} from '@modern-js/utils/universal';
+import {
+  BACKEND_FEDERATION_CONTRACT_VERSION,
+  BACKEND_FEDERATION_NODE_ADAPTER_VERSION,
+  type BackendFederatedEffectApiModule,
+  type BackendFederationRemote,
+} from '../backend-federation';
+import {
+  assertConsistentValue,
+  assertManifestAdapter,
+  assertVersionValue,
+  BackendFederationManifestAdapterError,
+} from './errors';
+import {
+  backendFederationMetadata,
+  manifestDeliveryUnit,
+  recordField,
+  stringValue,
+  versionBoundaryMetadata,
+} from './metadata';
+import type {
+  BackendFederationManifest,
+  BackendFederationVersionBoundaryExpectation,
+} from './types';
+
+function resolveExpectedBuildMarker(
+  expected: BackendFederationVersionBoundaryExpectation,
+) {
+  if (
+    expected.buildVersion !== undefined &&
+    expected.buildMarker !== undefined &&
+    expected.buildVersion !== expected.buildMarker
+  ) {
+    throw new BackendFederationManifestAdapterError(
+      'version_mismatch',
+      `[BFF][Effect] Backend federation expected buildVersion/buildMarker mismatch: buildVersion ${expected.buildVersion}, buildMarker ${expected.buildMarker}.`,
+      undefined,
+      {
+        label: 'expected.buildVersion/buildMarker',
+        expected: expected.buildVersion,
+        received: expected.buildMarker,
+      },
+    );
+  }
+
+  // Intentionally no fallback to `buildVersion` here: this is only used to
+  // compare against manifest `deliveryUnit.buildMarker`, which is a
+  // separate, additive field. Callers that only pass `buildVersion` (the
+  // pre-ADR-0019 expectation shape) must not be forced to also match a
+  // delivery-unit build marker on the manifest.
+  return expected.buildMarker;
+}
+
+export function validateBackendFederationManifest(
+  manifest: BackendFederationManifest,
+  expected: BackendFederationVersionBoundaryExpectation = {},
+) {
+  const expectedBuildMarker = resolveExpectedBuildMarker(expected);
+  const backendFederation = backendFederationMetadata(manifest);
+  assertManifestAdapter(
+    backendFederation,
+    'manifest_invalid',
+    '[BFF][Effect] Backend federation manifest must declare backendFederation metadata.',
+  );
+  const manifestShape = validateBackendFederationManifestContract(manifest, {
+    expectedContractVersion: false,
+    expectedNodeAdapterVersion: false,
+    validateDeliveryUnit: false,
+  });
+  assertManifestAdapter(
+    manifestShape.ok,
+    'manifest_invalid',
+    `[BFF][Effect] Backend federation manifest schema invalid: ${formatBackendFederationValidationErrors(
+      manifestShape.errors,
+    )}.`,
+  );
+
+  assertManifestAdapter(
+    backendFederation.runtimeFramework === 'effect',
+    'strict_effect_required',
+    '[BFF][Effect] Backend federation manifest must declare runtimeFramework: "effect".',
+  );
+  assertManifestAdapter(
+    backendFederation.strictEffectApproach === true,
+    'strict_effect_required',
+    '[BFF][Effect] Backend federation manifest must declare strictEffectApproach: true.',
+  );
+
+  assertVersionValue(
+    stringValue(backendFederation.contractVersion),
+    expected.contractVersion ?? BACKEND_FEDERATION_CONTRACT_VERSION,
+    'manifest contractVersion',
+  );
+  assertVersionValue(
+    stringValue(backendFederation.nodeAdapterVersion),
+    expected.nodeAdapterVersion ?? BACKEND_FEDERATION_NODE_ADAPTER_VERSION,
+    'manifest nodeAdapterVersion',
+  );
+
+  const boundary = versionBoundaryMetadata(manifest);
+  assertVersionValue(
+    stringValue(backendFederation.name) ??
+      stringValue(manifest.name) ??
+      stringValue(manifest.id),
+    expected.remoteName,
+    'manifest remoteName',
+  );
+  assertVersionValue(
+    stringValue(boundary?.packageName),
+    expected.packageName,
+    'versionBoundary.packageName',
+  );
+  assertVersionValue(
+    stringValue(boundary?.version),
+    expected.version,
+    'versionBoundary.version',
+  );
+  assertVersionValue(
+    stringValue(boundary?.buildVersion),
+    expected.buildVersion,
+    'versionBoundary.buildVersion',
+  );
+  assertConsistentValue(
+    stringValue(manifest.version),
+    stringValue(boundary?.version),
+    'manifest versionBoundary.version',
+  );
+  assertConsistentValue(
+    stringValue(manifest.buildVersion),
+    stringValue(boundary?.buildVersion),
+    'manifest versionBoundary.buildVersion',
+  );
+
+  const deliveryUnit = manifestDeliveryUnit(backendFederation, boundary);
+  assertConsistentValue(
+    stringValue(deliveryUnit.boundary?.buildMarker),
+    stringValue(boundary?.buildVersion),
+    'versionBoundary.deliveryUnit.buildMarker vs versionBoundary.buildVersion',
+  );
+  assertConsistentValue(
+    stringValue(deliveryUnit.top?.unitId),
+    stringValue(deliveryUnit.boundary?.unitId),
+    'backendFederation.deliveryUnit.unitId vs versionBoundary.deliveryUnit.unitId',
+  );
+
+  const manifestUnitId =
+    stringValue(deliveryUnit.boundary?.unitId) ??
+    stringValue(deliveryUnit.top?.unitId);
+  assertVersionValue(manifestUnitId, expected.unitId, 'deliveryUnit.unitId');
+  assertVersionValue(
+    stringValue(deliveryUnit.boundary?.buildMarker),
+    expectedBuildMarker,
+    'deliveryUnit.buildMarker',
+  );
+}
+
+export function validateLoadedBackendFederationContract(
+  loaded: BackendFederatedEffectApiModule,
+  manifest: BackendFederationManifest,
+  remote: BackendFederationRemote,
+) {
+  const loadedContract = loaded.backendFederationContract;
+  const backendFederation = backendFederationMetadata(manifest);
+  const boundary = versionBoundaryMetadata(manifest);
+  const compatibility = recordField(loadedContract, 'compatibility');
+
+  assertManifestAdapter(
+    compatibility,
+    'version_mismatch',
+    `[BFF][Effect] Backend federation expose ${remote.name}/${remote.expose?.replace(
+      /^\.\//u,
+      '',
+    )} must declare compatibility metadata.`,
+  );
+  assertVersionValue(
+    stringValue(loadedContract?.role),
+    'microvertical-server',
+    'expose role',
+  );
+  assertVersionValue(
+    stringValue(loadedContract?.name),
+    remote.name,
+    'expose name',
+  );
+  assertVersionValue(
+    stringValue(compatibility.contractVersion),
+    stringValue(backendFederation?.contractVersion),
+    'expose contractVersion',
+  );
+  assertVersionValue(
+    stringValue(compatibility.nodeAdapterVersion),
+    stringValue(backendFederation?.nodeAdapterVersion),
+    'expose nodeAdapterVersion',
+  );
+  assertVersionValue(
+    stringValue(compatibility.packageName),
+    stringValue(boundary?.packageName),
+    'expose packageName',
+  );
+  assertVersionValue(
+    stringValue(compatibility.build),
+    stringValue(boundary?.buildVersion),
+    'expose buildVersion',
+  );
+
+  const deliveryUnit = manifestDeliveryUnit(backendFederation, boundary);
+  const manifestUnitId =
+    stringValue(deliveryUnit.boundary?.unitId) ??
+    stringValue(deliveryUnit.top?.unitId);
+  const manifestBuildMarker = stringValue(deliveryUnit.boundary?.buildMarker);
+
+  // Only enforced when both sides declare the field: absence on either side
+  // is a legacy manifest/expose and must stay backward compatible.
+  assertConsistentValue(
+    manifestUnitId,
+    stringValue(compatibility.unitId),
+    'deliveryUnit.unitId vs expose compatibility.unitId',
+  );
+  assertConsistentValue(
+    manifestBuildMarker,
+    stringValue(compatibility.build),
+    'deliveryUnit.buildMarker vs expose compatibility.build',
+  );
+}
+
+export function classifyLoadError(error: unknown) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (
+    (typeof error === 'object' &&
+      error !== null &&
+      'code' in error &&
+      error.code === 'timeout') ||
+    /timed out/iu.test(message)
+  ) {
+    return 'timeout' as const;
+  }
+
+  if (message.includes('delivery-unit identity mismatch')) {
+    return 'version_mismatch' as const;
+  }
+
+  if (
+    message.includes('strictEffectApproach') ||
+    message.includes('runtimeFramework')
+  ) {
+    return 'strict_effect_required' as const;
+  }
+
+  return 'remote_unavailable' as const;
+}