@bleedingdev/modern-js-federation-runtime 0.0.0 → 3.9.0-ultramodern.5

package/src/module-federation/distributed-ssr.tsx

@@ -0,0 +1,240 @@
+import { useRuntimeContext } from '@modern-js/runtime';
+import type { ComponentType, ReactNode } from 'react';
+
+export const DISTRIBUTED_SSR_FRAGMENTS_LOCALS_KEY =
+  '__modernDistributedSsrFragments';
+export const DISTRIBUTED_SSR_FRAGMENT_REQUEST_LOCALS_KEY =
+  '__modernDistributedSsrFragmentRequest';
+
+export type DistributedSsrFragment = {
+  boundaryId: string;
+  buildMarker?: string;
+  digest?: string;
+  expose: string;
+  html: string;
+  remote: string;
+  status: 'ready';
+};
+
+export type DistributedSsrFragmentFailure = {
+  boundaryId: string;
+  expose: string;
+  reason: string;
+  remote: string;
+  status: 'degraded';
+};
+
+type DistributedSsrFragmentResult =
+  | DistributedSsrFragment
+  | DistributedSsrFragmentFailure;
+
+export type DistributedSsrFragmentContext = {
+  fragments?: Record<
+    string,
+    DistributedSsrFragment | DistributedSsrFragmentFailure
+  >;
+  required: true;
+  resolve?: (
+    remote: string,
+    expose: string,
+    props: Record<string, unknown>,
+  ) => DistributedSsrFragmentResult | PromiseLike<DistributedSsrFragmentResult>;
+};
+
+export type DistributedSsrBoundaryProps<
+  Props extends object = Record<string, unknown>,
+> = {
+  children: ReactNode;
+  expose: string;
+  fallback: ReactNode;
+  fragmentProps?: Props;
+  remote: string;
+};
+
+export type CreateDistributedSsrComponentOptions<Props extends object> = {
+  createComponent: () => ComponentType<Props>;
+  expose: string;
+  fallback: ReactNode;
+  remote: string;
+};
+
+export function distributedSsrFragmentKey(remote: string, expose: string) {
+  return `${remote}::${expose}`;
+}
+
+function getDistributedSsrFragmentContext(
+  response: { locals?: unknown } | undefined,
+): DistributedSsrFragmentContext | undefined {
+  const locals = response?.locals;
+  if (typeof locals !== 'object' || locals === null) {
+    return undefined;
+  }
+
+  const context =
+    DISTRIBUTED_SSR_FRAGMENTS_LOCALS_KEY in locals
+      ? locals[DISTRIBUTED_SSR_FRAGMENTS_LOCALS_KEY]
+      : undefined;
+
+  if (typeof context !== 'object' || context === null) {
+    return undefined;
+  }
+
+  return context as DistributedSsrFragmentContext;
+}
+
+export function useDistributedSsrFragmentProps<Props extends object>({
+  boundaryId,
+  expose,
+}: {
+  boundaryId: string;
+  expose: string;
+}): Props {
+  const runtimeContext = useRuntimeContext();
+  const locals = runtimeContext.requestContext?.response?.locals;
+  const request =
+    typeof locals === 'object' &&
+    locals !== null &&
+    DISTRIBUTED_SSR_FRAGMENT_REQUEST_LOCALS_KEY in locals
+      ? locals[DISTRIBUTED_SSR_FRAGMENT_REQUEST_LOCALS_KEY]
+      : undefined;
+
+  if (
+    typeof request !== 'object' ||
+    request === null ||
+    !('boundaryId' in request) ||
+    request.boundaryId !== boundaryId ||
+    !('expose' in request) ||
+    request.expose !== expose
+  ) {
+    throw new Error(
+      `Distributed SSR fragment request contract mismatch for ${boundaryId} ${expose}.`,
+    );
+  }
+
+  const props = 'props' in request ? request.props : undefined;
+  if (typeof props !== 'object' || props === null || Array.isArray(props)) {
+    throw new Error(
+      `Distributed SSR fragment request props must be an object for ${boundaryId} ${expose}.`,
+    );
+  }
+
+  return props as Props;
+}
+
+function isThenable(
+  value:
+    | DistributedSsrFragmentResult
+    | PromiseLike<DistributedSsrFragmentResult>
+    | undefined,
+): value is PromiseLike<DistributedSsrFragmentResult> {
+  return (
+    value !== undefined && 'then' in value && typeof value.then === 'function'
+  );
+}
+
+/**
+ * Keeps the browser on the native Module Federation component while allowing
+ * servers that cannot execute remote code (notably workerd) to render a
+ * trusted fragment produced by the remote Worker itself.
+ *
+ * Node SSR has no distributed-fragment context and therefore renders the
+ * child normally, preserving Module Federation's in-process SSR path.
+ */
+export function DistributedSsrBoundary<
+  Props extends object = Record<string, unknown>,
+>({
+  children,
+  expose,
+  fallback,
+  fragmentProps,
+  remote,
+}: DistributedSsrBoundaryProps<Props>) {
+  const runtimeContext = useRuntimeContext();
+  const key = distributedSsrFragmentKey(remote, expose);
+  const attributes = {
+    'data-modern-distributed-ssr-boundary': key,
+  };
+
+  if (runtimeContext.isBrowser) {
+    return <div {...attributes}>{children}</div>;
+  }
+
+  const fragmentContext = getDistributedSsrFragmentContext(
+    runtimeContext.requestContext?.response,
+  );
+
+  // Node can execute the Module Federation server runtime. Only workerd's
+  // request adapter supplies a required distributed-fragment context.
+  if (fragmentContext === undefined) {
+    return <div {...attributes}>{children}</div>;
+  }
+
+  const resolverFragmentProps =
+    fragmentProps === undefined
+      ? {}
+      : Object.fromEntries(Object.entries(fragmentProps));
+  const fragmentOrPromise =
+    fragmentContext.resolve?.(remote, expose, resolverFragmentProps) ??
+    fragmentContext.fragments?.[key];
+  if (isThenable(fragmentOrPromise)) {
+    throw fragmentOrPromise;
+  }
+  const fragment = fragmentOrPromise;
+  if (fragment?.status === 'ready') {
+    return (
+      <div
+        {...attributes}
+        data-modern-distributed-ssr-build={fragment.buildMarker}
+        data-modern-distributed-ssr-digest={fragment.digest}
+        data-modern-distributed-ssr-status="ready"
+        // The fragment is accepted only after the Worker adapter verifies its
+        // declared boundary id and expose marker.
+        dangerouslySetInnerHTML={{ __html: fragment.html }}
+      />
+    );
+  }
+
+  return (
+    <div
+      {...attributes}
+      data-modern-distributed-ssr-reason={fragment?.reason ?? 'missing'}
+      data-modern-distributed-ssr-status="degraded"
+    >
+      {fallback}
+    </div>
+  );
+}
+
+/**
+ * Defers creation of the native Module Federation component until React
+ * actually renders that child. A workerd request with a verified distributed
+ * fragment never constructs the native remote, so its module cannot perform
+ * forbidden global-scope network I/O. Browser and Node rendering keep using
+ * the native Module Federation component unchanged.
+ */
+export function createDistributedSsrComponent<Props extends object>({
+  createComponent,
+  expose,
+  fallback,
+  remote,
+}: CreateDistributedSsrComponentOptions<Props>) {
+  let RemoteComponent: ComponentType<Props> | undefined;
+
+  function DeferredRemoteComponent(props: Props) {
+    RemoteComponent ??= createComponent();
+    return <RemoteComponent {...props} />;
+  }
+
+  return function DistributedSsrComponent(props: Props) {
+    return (
+      <DistributedSsrBoundary
+        expose={expose}
+        fallback={fallback}
+        fragmentProps={props}
+        remote={remote}
+      >
+        <DeferredRemoteComponent {...props} />
+      </DistributedSsrBoundary>
+    );
+  };
+}

package/src/module-federation/index.ts

@@ -0,0 +1,274 @@
+// @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,
+  };
+}