@bleedingdev/modern-js-federation-runtime 3.9.0-ultramodern.11 → 3.9.0-ultramodern.13

package/dist/types/module-federation/telemetry.d.ts

@@ -0,0 +1,71 @@
+export declare const MODULE_FEDERATION_FALLBACK_SIGNAL_EVENT = "modernjs:mf-runtime-fallback";
+export declare const MODULE_FEDERATION_RECOVERY_SIGNAL_EVENT = "modernjs:mf-runtime-recovery";
+export declare const DEFAULT_RUNTIME_FALLBACK_SIGNAL_ENDPOINT = "/_modern/contract-gates/runtime-fallback";
+export declare 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;
+    /** Positive reporting deadline; defaults to one second. */
+    timeoutMs?: number;
+    /** Observe the exact payload and await delivery explicitly in tests. */
+    observe?: (payload: ModuleFederationFallbackTelemetryPayload, delivery: Promise<ModuleFederationFallbackTelemetryEmitResult>) => void;
+};
+export type ModuleFederationFallbackTelemetryEmitResult = {
+    dispatched: boolean;
+    posted: boolean;
+    postStatus?: number;
+};
+export declare class ModuleFederationRemoteLoadTimeoutError extends Error {
+    constructor(remote: string, timeoutMs: number);
+}
+export declare class ModuleFederationRemoteLoadError extends Error {
+    readonly remote: string;
+    readonly attempts: number;
+    readonly causeError: Error;
+    constructor(remote: string, attempts: number, causeError: Error);
+}
+export declare class ModuleFederationRemoteComponentContractError extends Error {
+    constructor(remote: string, exportName: string);
+}
+export declare function classifyModuleFederationFallback(error: unknown): ModuleFederationFallbackClassification;
+export declare function createModuleFederationFallbackTelemetry(input: ModuleFederationFallbackTelemetryInput): ModuleFederationFallbackTelemetryPayload;
+export declare function toModuleFederationFallbackAttributes(payload: ModuleFederationFallbackTelemetryPayload): Record<string, string>;
+export declare function emitModuleFederationFallbackTelemetry(input: ModuleFederationFallbackTelemetryInput, options?: ModuleFederationFallbackTelemetryEmitOptions): Promise<ModuleFederationFallbackTelemetryEmitResult>;
+/** Dispatch once locally; remote delivery is bounded and best effort. */
+export declare function emitModuleFederationFallbackPayload(payload: ModuleFederationFallbackTelemetryPayload, options?: ModuleFederationFallbackTelemetryEmitOptions): Promise<ModuleFederationFallbackTelemetryEmitResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bleedingdev/modern-js-federation-runtime",
-  "version": "3.9.0-ultramodern.11",
+  "version": "3.9.0-ultramodern.13",
   "description": "Federated surface consumption, distributed SSR, and bounded manifest recovery.",
   "license": "MIT",
   "repository": {
@@ -62,25 +62,25 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@modern-js/surface-resolution": "npm:@bleedingdev/modern-js-surface-resolution@3.9.0-ultramodern.11"
+    "@modern-js/surface-resolution": "npm:@bleedingdev/modern-js-surface-resolution@3.9.0-ultramodern.13"
   },
   "peerDependencies": {
-    "@modern-js/runtime": "3.9.0-ultramodern.11",
+    "@modern-js/runtime": "3.9.0-ultramodern.13",
     "react": "^19.2.8"
   },
   "devDependencies": {
-    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.9.0-ultramodern.11",
-    "@modern-js/tsconfig": "npm:@bleedingdev/modern-js-tsconfig@3.9.0-ultramodern.11",
-    "@rsbuild/core": "2.2.3",
-    "@rslib/core": "1.0.0",
+    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.9.0-ultramodern.13",
+    "@modern-js/tsconfig": "npm:@bleedingdev/modern-js-tsconfig@3.9.0-ultramodern.13",
+    "@rsbuild/core": "2.2.9",
+    "@rslib/core": "1.0.2",
     "@scripts/rstest-config": "2.66.0",
-    "@types/node": "^26.4.1",
-    "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.7",
+    "@types/node": "^26.6.2",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "esbuild": "^0.28.2",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
     "typescript": "^7.0.2"
   },
   "publishConfig": {

package/src/module-federation/consume-surface.ts

@@ -23,14 +23,7 @@
  * consumption during a rollout window should be driven by expand/contract, not
  * by silent degrade.
  */
-import {
-  classifyModuleFederationFallback,
-  createModuleFederationFallbackTelemetry,
-  emitModuleFederationFallbackTelemetry,
-  type ModuleFederationFallbackClassification,
-  type ModuleFederationFallbackTelemetryEmitOptions,
-  type ModuleFederationFallbackTelemetryPayload,
-} from './index';
+
 import {
   createDiscoveryError,
   type DiscoveryError,
@@ -44,6 +37,15 @@ import {
   type SurfaceResolutionProvider,
   validateSurfaceRef,
 } from './surface-resolution-types';
+import {
+  classifyModuleFederationFallback,
+  createModuleFederationFallbackTelemetry,
+  emitModuleFederationFallbackPayload,
+  emitModuleFederationFallbackTelemetry,
+  type ModuleFederationFallbackClassification,
+  type ModuleFederationFallbackTelemetryEmitOptions,
+  type ModuleFederationFallbackTelemetryPayload,
+} from './telemetry';
 
 /** Where in the consumption lifecycle a failure was raised. */
 export type SurfaceConsumptionPhase = 'discovery' | 'load' | 'mount';
@@ -100,7 +102,7 @@ export type SurfaceConsumerOptions<T> = {
    * omitted.
    *
    * - `'noncritical'`: the degraded handler's result is returned and the
-   *   failure is swallowed — the promise never rejects.
+   *   failure is swallowed — a failed degraded handler resolves undefined.
    * - `'critical'`: the degraded handler still runs (telemetry + fallback-UI
    *   obligations hold), but the returned promise then REJECTS with the typed
    *   failure so callers / rollout machinery observe it. Prefer expand/contract
@@ -154,7 +156,7 @@ async function reportFailure<T>(
     error?: unknown;
     resolved?: ResolvedDeliveryUnit;
   },
-): Promise<T> {
+): Promise<T | undefined> {
   const remote = toRemoteString(ref);
   const telemetry = createModuleFederationFallbackTelemetry({
     appName: options.appName,
@@ -173,24 +175,7 @@ async function reportFailure<T>(
     status: 'degraded',
   });
 
-  // Fire-and-forget style, but awaited so tests can assert emission. Emission
-  // failures must never mask the degraded path.
-  try {
-    await emitModuleFederationFallbackTelemetry(
-      {
-        appName: options.appName,
-        classification: base.classification,
-        error: base.error ?? base.discoveryError,
-        metadata: telemetry.metadata,
-        phase: base.phase,
-        remote,
-        status: 'degraded',
-      },
-      options.telemetry ?? {},
-    );
-  } catch {
-    // Telemetry sink failure is itself a degraded condition; swallow it.
-  }
+  void emitModuleFederationFallbackPayload(telemetry, options.telemetry);
 
   const failure: SurfaceConsumptionFailure = {
     ref,
@@ -234,7 +219,7 @@ async function reportFailure<T>(
     // telemetry, then for noncritical resolve undefined; for critical reject
     // with the ORIGINAL typed error (never the handler's).
     try {
-      await emitModuleFederationFallbackTelemetry(
+      void emitModuleFederationFallbackTelemetry(
         {
           appName: options.appName,
           classification: base.classification,
@@ -252,7 +237,7 @@ async function reportFailure<T>(
     if (critical) {
       throw reason;
     }
-    return undefined as T;
+    return undefined;
   }
 
   if (critical) {
@@ -266,14 +251,14 @@ async function reportFailure<T>(
  * load failure the required degraded handler runs (telemetry + fallback UI).
  *
  * For a `noncritical` consumption (see {@link SurfaceConsumerOptions.classification})
- * this resolves to the degraded value and never rejects, so a failing
+ * this resolves to the degraded value (or undefined if the handler fails), so a failing
  * consumption is isolated from any sibling. For a `critical` consumption (the
  * default) it rejects with the typed failure AFTER the degraded handler has
  * run, so callers / rollout machinery observe the failure.
  */
 export async function consumeSurface<T>(
   options: SurfaceConsumerOptions<T>,
-): Promise<T> {
+): Promise<T | undefined> {
   let ref: ParsedSurfaceRef;
   if (typeof options.ref === 'string') {
     const parsed = parseSurfaceRef(options.ref);
@@ -360,7 +345,7 @@ export function createSurfaceConsumer(
   return function consume<T>(
     options: Omit<SurfaceConsumerOptions<T>, keyof typeof base> &
       Partial<Pick<SurfaceConsumerOptions<T>, keyof typeof base>>,
-  ): Promise<T> {
+  ): Promise<T | undefined> {
     return consumeSurface<T>({
       ...base,
       ...options,

package/src/module-federation/index.ts

@@ -10,265 +10,4 @@ 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';