@bleedingdev/modern-js-federation-runtime 3.9.0-ultramodern.9 → 3.9.3-ultramodern.2

package/src/module-federation/index.ts

@@ -1,274 +1,8 @@
 // @effect-diagnostics asyncFunction:off extendsNativeError:off globalFetch:off strictBooleanExpressions:off
 
 export * from './consume-surface';
-export * from './distributed-ssr';
-export {
-  DISTRIBUTED_SSR_FRAGMENT_REQUEST_LOCALS_KEY,
-  useDistributedSsrFragmentProps,
-} from './distributed-ssr';
 export * from './last-known-good';
 export * from './manifest-recovery-runtime-plugin';
 export * from './surface-resolution-types';
 
-export const MODULE_FEDERATION_FALLBACK_SIGNAL_EVENT =
-  'modernjs:mf-runtime-fallback';
-
-export const MODULE_FEDERATION_RECOVERY_SIGNAL_EVENT =
-  'modernjs:mf-runtime-recovery';
-
-export const DEFAULT_RUNTIME_FALLBACK_SIGNAL_ENDPOINT =
-  '/_modern/contract-gates/runtime-fallback';
-
-export const DEFAULT_RUNTIME_FALLBACK_SIGNAL_AUTH_HEADER =
-  'x-modernjs-runtime-signal-token';
-
-export type ModuleFederationFallbackClassification =
-  | 'timeout'
-  | 'network'
-  | 'contract'
-  | 'version-skew'
-  | 'remote-unavailable';
-
-export type ModuleFederationFallbackStatus =
-  | 'degraded'
-  | 'failed'
-  | 'recovered';
-
-export type ModuleFederationFallbackTelemetryInput = {
-  appName: string;
-  classification: ModuleFederationFallbackClassification;
-  entry?: string;
-  error?: unknown;
-  eventName?: string;
-  exportName?: string;
-  metadata?: Record<string, unknown>;
-  phase: 'discovery' | 'load' | 'mount' | 'hydrate' | 'recover';
-  remote: string;
-  runtimeDigest?: string;
-  status?: ModuleFederationFallbackStatus;
-};
-
-export type ModuleFederationFallbackTelemetryPayload = {
-  appName: string;
-  entry?: string;
-  eventName: string;
-  phase: ModuleFederationFallbackTelemetryInput['phase'];
-  reason: ModuleFederationFallbackClassification;
-  runtimeDigest?: string;
-  schemaVersion: 1;
-  metadata: {
-    classification: ModuleFederationFallbackClassification;
-    errorMessage?: string;
-    errorName?: string;
-    exportName?: string;
-    remote: string;
-    runtimeDigest?: string;
-    status: ModuleFederationFallbackStatus;
-  } & Record<string, unknown>;
-};
-
-export type ModuleFederationFallbackTelemetryEmitOptions = {
-  authHeaderName?: string;
-  authToken?: string;
-  endpoint?: string;
-  fetchImpl?: typeof fetch;
-  postSignal?: boolean;
-};
-
-export type ModuleFederationFallbackTelemetryEmitResult = {
-  dispatched: boolean;
-  posted: boolean;
-  postStatus?: number;
-};
-
-export class ModuleFederationRemoteLoadTimeoutError extends Error {
-  constructor(remote: string, timeoutMs: number) {
-    super(`Loading remote "${remote}" timed out after ${timeoutMs}ms`);
-    this.name = 'ModuleFederationRemoteLoadTimeoutError';
-  }
-}
-
-export class ModuleFederationRemoteLoadError extends Error {
-  readonly remote: string;
-  readonly attempts: number;
-  readonly causeError: Error;
-
-  constructor(remote: string, attempts: number, causeError: Error) {
-    super(
-      `Unable to load remote "${remote}" after ${attempts} attempt${
-        attempts > 1 ? 's' : ''
-      }: ${causeError.message}`,
-    );
-    this.name = 'ModuleFederationRemoteLoadError';
-    this.remote = remote;
-    this.attempts = attempts;
-    this.causeError = causeError;
-  }
-}
-
-export class ModuleFederationRemoteComponentContractError extends Error {
-  constructor(remote: string, exportName: string) {
-    super(
-      `Remote "${remote}" export "${exportName}" is not a valid React component`,
-    );
-    this.name = 'ModuleFederationRemoteComponentContractError';
-  }
-}
-
-function toError(error: unknown) {
-  if (error instanceof Error) {
-    return error;
-  }
-
-  return new Error(
-    typeof error === 'string' ? error : 'Unknown remote load error',
-  );
-}
-
-export function classifyModuleFederationFallback(
-  error: unknown,
-): ModuleFederationFallbackClassification {
-  const normalizedError = toError(error);
-  if (normalizedError instanceof ModuleFederationRemoteLoadError) {
-    return classifyModuleFederationFallback(normalizedError.causeError);
-  }
-  if (normalizedError instanceof ModuleFederationRemoteLoadTimeoutError) {
-    return 'timeout';
-  }
-  if (normalizedError instanceof ModuleFederationRemoteComponentContractError) {
-    return 'contract';
-  }
-
-  const message = normalizedError.message;
-  if (
-    /version|requiredVersion|singleton|share scope|shared module/i.test(message)
-  ) {
-    return 'version-skew';
-  }
-  if (/network|fetch|script|timeout|chunk|loading/i.test(message)) {
-    return 'network';
-  }
-
-  return 'remote-unavailable';
-}
-
-export function createModuleFederationFallbackTelemetry(
-  input: ModuleFederationFallbackTelemetryInput,
-): ModuleFederationFallbackTelemetryPayload {
-  const error = input.error !== undefined ? toError(input.error) : undefined;
-  const status = input.status ?? 'degraded';
-  const eventName =
-    input.eventName ??
-    (status === 'recovered'
-      ? MODULE_FEDERATION_RECOVERY_SIGNAL_EVENT
-      : MODULE_FEDERATION_FALLBACK_SIGNAL_EVENT);
-  const metadata: ModuleFederationFallbackTelemetryPayload['metadata'] = {
-    ...(input.metadata ?? {}),
-    classification: input.classification,
-    remote: input.remote,
-    status,
-  };
-
-  if (input.exportName !== undefined) {
-    metadata.exportName = input.exportName;
-  }
-  if (input.runtimeDigest !== undefined) {
-    metadata.runtimeDigest = input.runtimeDigest;
-  }
-  if (error !== undefined) {
-    metadata.errorName = error.name;
-    metadata.errorMessage = error.message;
-  }
-
-  const payload: ModuleFederationFallbackTelemetryPayload = {
-    appName: input.appName,
-    eventName,
-    metadata,
-    phase: input.phase,
-    reason: input.classification,
-    schemaVersion: 1,
-  };
-
-  if (input.entry !== undefined) {
-    payload.entry = input.entry;
-  }
-  if (input.runtimeDigest !== undefined) {
-    payload.runtimeDigest = input.runtimeDigest;
-  }
-
-  return payload;
-}
-
-export function toModuleFederationFallbackAttributes(
-  payload: ModuleFederationFallbackTelemetryPayload,
-): Record<string, string> {
-  return {
-    'data-mf-fallback-app': payload.appName,
-    'data-mf-fallback-classification': payload.reason,
-    'data-mf-fallback-phase': payload.phase,
-    'data-mf-fallback-remote': String(payload.metadata.remote),
-    'data-mf-fallback-status': String(payload.metadata.status),
-    'data-mf-telemetry-event': payload.eventName,
-  };
-}
-
-export async function emitModuleFederationFallbackTelemetry(
-  input: ModuleFederationFallbackTelemetryInput,
-  options: ModuleFederationFallbackTelemetryEmitOptions = {},
-): Promise<ModuleFederationFallbackTelemetryEmitResult> {
-  const payload = createModuleFederationFallbackTelemetry(input);
-
-  if (
-    typeof window !== 'undefined' &&
-    typeof window.dispatchEvent === 'function' &&
-    typeof CustomEvent !== 'undefined'
-  ) {
-    window.dispatchEvent(
-      new CustomEvent(payload.eventName, {
-        detail: payload,
-      }),
-    );
-  }
-
-  const shouldPost = options.postSignal === true || Boolean(options.endpoint);
-  if (!shouldPost) {
-    return {
-      dispatched: true,
-      posted: false,
-    };
-  }
-
-  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
-  if (typeof fetchImpl !== 'function') {
-    return {
-      dispatched: true,
-      posted: false,
-    };
-  }
-
-  const headers = new Headers({
-    'content-type': 'application/json',
-  });
-  if (options.authToken !== undefined && options.authToken.length > 0) {
-    headers.set(
-      options.authHeaderName ?? DEFAULT_RUNTIME_FALLBACK_SIGNAL_AUTH_HEADER,
-      options.authToken,
-    );
-  }
-
-  const response = await fetchImpl(
-    options.endpoint ?? DEFAULT_RUNTIME_FALLBACK_SIGNAL_ENDPOINT,
-    {
-      body: JSON.stringify(payload),
-      headers,
-      method: 'POST',
-      keepalive: true,
-    },
-  );
-
-  return {
-    dispatched: true,
-    posted: true,
-    postStatus: response.status,
-  };
-}
+export * from './telemetry';

package/src/module-federation/manifest-recovery-runtime-plugin.ts

@@ -63,8 +63,12 @@ const getErrorStatus = (error: unknown) => {
 };
 
 const isRetryableError = (error: unknown) => {
+  // Module Federation parses the manifest body without checking the HTTP
+  // status, so a 503 error page reaches this hook as a JSON SyntaxError.
+  // Recovery fetches again and reads the real status: a retryable status
+  // retries, and a successful response with malformed JSON stops there.
   if (error instanceof SyntaxError) {
-    return false;
+    return true;
   }
 
   const message = getErrorMessage(error);

package/src/module-federation/renderer-contract.ts

@@ -0,0 +1,176 @@
+import {
+  assertRendererProfileCompatibility,
+  formatBackendFederationValidationErrors,
+  type RendererIdentity,
+  type RendererPackageIdentity,
+  type RendererProfile,
+  validateRendererIdentity,
+  validateRendererProfile,
+} from '@modern-js/backend-federation-contracts';
+
+export const RENDERER_FEDERATION_METADATA_KEY = 'ultramodernRenderer';
+export const RENDERER_FEDERATION_SCHEMA = 'ultramodern.renderer-federation';
+export const RENDERER_FEDERATION_SCHEMA_VERSION = 1;
+
+/** The consuming renderer tuple; application and source identities are independent. */
+export interface RendererFederationCompatibility {
+  readonly profile: RendererProfile;
+  readonly runtime: RendererPackageIdentity;
+  readonly bootstrap: RendererPackageIdentity;
+}
+
+/** Finalized native build authority for both browser and SSR remote entries. */
+export interface RendererFederationContract
+  extends RendererFederationCompatibility {
+  readonly schema: typeof RENDERER_FEDERATION_SCHEMA;
+  readonly schemaVersion: typeof RENDERER_FEDERATION_SCHEMA_VERSION;
+  readonly identities: Readonly<Record<string, RendererIdentity>>;
+}
+
+export const rendererFederationError = (message: string): Error =>
+  new Error(`Renderer federation manifest contract: ${message}`);
+
+const record = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const exactFields = (
+  value: Record<string, unknown>,
+  fields: readonly string[],
+  label: string,
+): void => {
+  const unknown = Object.keys(value).filter(key => !fields.includes(key));
+  const missing = fields.filter(key => !Object.hasOwn(value, key));
+  if (unknown.length || missing.length)
+    throw rendererFederationError(
+      `${label} fields differ (unknown=${unknown.join(',')}; missing=${missing.join(',')}).`,
+    );
+};
+
+const assertProfile = (value: unknown): RendererProfile => {
+  const result = validateRendererProfile(value, 'rendererProfile');
+  if (!result.ok)
+    throw rendererFederationError(
+      formatBackendFederationValidationErrors(result.errors),
+    );
+  const profile = value as RendererProfile;
+  return Object.freeze({
+    ...profile,
+    compiler: Object.freeze({ ...profile.compiler }),
+    hydration: Object.freeze({ ...profile.hydration }),
+    router: Object.freeze({ ...profile.router }),
+  });
+};
+
+// The shared contract's compiler package validator also owns exact package
+// names/versions for runtime and bootstrap; do not maintain another semver ABI.
+const assertPackage = (
+  value: unknown,
+  profile: RendererProfile,
+  label: string,
+): RendererPackageIdentity => {
+  const result = validateRendererProfile(
+    { ...profile, compiler: value },
+    label,
+  );
+  if (!result.ok)
+    throw rendererFederationError(
+      formatBackendFederationValidationErrors(result.errors),
+    );
+  return Object.freeze({ ...(value as RendererPackageIdentity) });
+};
+
+export function readRendererFederationCompatibility(
+  value: unknown,
+): RendererFederationCompatibility {
+  if (!record(value))
+    throw rendererFederationError('the consuming renderer tuple is absent.');
+  exactFields(value, ['profile', 'runtime', 'bootstrap'], 'compatibility');
+  const profile = assertProfile(value.profile);
+  return Object.freeze({
+    profile,
+    runtime: assertPackage(value.runtime, profile, 'runtime'),
+    bootstrap: assertPackage(value.bootstrap, profile, 'bootstrap'),
+  });
+}
+
+export function readRendererFederationContract(
+  value: unknown,
+): RendererFederationContract {
+  if (!record(value))
+    throw rendererFederationError('renderer publication metadata is absent.');
+  exactFields(
+    value,
+    [
+      'schema',
+      'schemaVersion',
+      'profile',
+      'runtime',
+      'bootstrap',
+      'identities',
+    ],
+    'publication',
+  );
+  if (
+    value.schema !== RENDERER_FEDERATION_SCHEMA ||
+    value.schemaVersion !== RENDERER_FEDERATION_SCHEMA_VERSION
+  )
+    throw rendererFederationError('unsupported renderer publication schema.');
+  const compatibility = readRendererFederationCompatibility({
+    profile: value.profile,
+    runtime: value.runtime,
+    bootstrap: value.bootstrap,
+  });
+  if (!record(value.identities) || !Object.keys(value.identities).length)
+    throw rendererFederationError(
+      'finalized application entry identities are absent.',
+    );
+  const identities: Record<string, RendererIdentity> = Object.create(null);
+  let appId: string | undefined;
+  for (const [entryName, valueIdentity] of Object.entries(value.identities)) {
+    const result = validateRendererIdentity(
+      valueIdentity,
+      `identities.${entryName}`,
+    );
+    if (!result.ok)
+      throw rendererFederationError(
+        formatBackendFederationValidationErrors(result.errors),
+      );
+    const identity = valueIdentity as RendererIdentity;
+    if (
+      identity.entryName !== entryName ||
+      identity.renderer !== compatibility.profile.renderer ||
+      identity.protocolVersion !== compatibility.profile.protocolVersion ||
+      (appId !== undefined && identity.appId !== appId)
+    )
+      throw rendererFederationError(
+        `incoherent publication identity for ${entryName}.`,
+      );
+    appId = identity.appId;
+    identities[entryName] = Object.freeze({ ...identity });
+  }
+  return Object.freeze({
+    schema: RENDERER_FEDERATION_SCHEMA,
+    schemaVersion: RENDERER_FEDERATION_SCHEMA_VERSION,
+    ...compatibility,
+    identities: Object.freeze(identities),
+  });
+}
+
+export function assertRendererFederationCompatibility(
+  expected: RendererFederationCompatibility,
+  actual: RendererFederationCompatibility,
+): void {
+  try {
+    assertRendererProfileCompatibility(expected.profile, actual.profile);
+  } catch (error) {
+    throw rendererFederationError(
+      error instanceof Error ? error.message : String(error),
+    );
+  }
+  for (const field of ['runtime', 'bootstrap'] as const)
+    for (const key of ['name', 'version'] as const)
+      if (expected[field][key] !== actual[field][key])
+        throw rendererFederationError(
+          `${field}.${key} must match the consuming renderer tuple.`,
+        );
+}