@bleedingdev/modern-js-plugin-bff 3.5.0-ultramodern.3 → 3.5.0-ultramodern.30

package/dist/esm-node/runtime/effect/backend-federation.mjs

@@ -0,0 +1,133 @@
+import "node:module";
+const BACKEND_FEDERATION_EFFECT_EXPOSE = './effect-api';
+const BACKEND_FEDERATION_MANIFEST_FILE = 'backend-mf-manifest.json';
+const BACKEND_FEDERATION_CONTRACT_VERSION = 'microvertical-server-effect-v1';
+const BACKEND_FEDERATION_NODE_ADAPTER_VERSION = 'backend-mf-effect-v1';
+function normalizeExpose(expose) {
+    return expose.replace(/^\.\//u, '');
+}
+function exposeForRemoteRequest(expose) {
+    return `./${normalizeExpose(expose)}`;
+}
+function isRecord(value) {
+    return 'object' == typeof value && null !== value;
+}
+function collectRemotes(options) {
+    const remotes = [
+        ...options.remotes ?? []
+    ];
+    if (options.remote) {
+        const existingIndex = remotes.findIndex((remote)=>remote.name === options.remote?.name);
+        if (existingIndex >= 0) remotes[existingIndex] = options.remote;
+        else remotes.push(options.remote);
+    }
+    return remotes;
+}
+function parseRemoteRequest(request) {
+    const [remoteName, ...exposeParts] = request.split('/');
+    if (!remoteName || 0 === exposeParts.length) throw new Error(`[BFF][Effect] Invalid backend federation request ${request}.`);
+    return {
+        remoteName,
+        expose: exposeForRemoteRequest(exposeParts.join('/'))
+    };
+}
+function decodeDataUrl(url) {
+    const commaIndex = url.indexOf(',');
+    if (commaIndex < 0) throw new Error('[BFF][Effect] Invalid backend federation data URL entry.');
+    return decodeURIComponent(url.slice(commaIndex + 1));
+}
+async function readCommonJsEntrySource(remote) {
+    if (remote.entry.startsWith('data:')) return decodeDataUrl(remote.entry);
+    if (remote.entry.startsWith('http://') || remote.entry.startsWith('https://')) {
+        const response = await fetch(remote.entry);
+        if (!response.ok) throw new Error(`[BFF][Effect] Failed to load backend federation remote ${remote.name}: ${response.status}`);
+        return response.text();
+    }
+    throw new Error(`[BFF][Effect] Backend federation remote ${remote.name} cannot load CommonJS entry ${remote.entry}.`);
+}
+function evaluateCommonJsEntry(remote, source) {
+    const module = {
+        exports: {}
+    };
+    const exports = module.exports;
+    const evaluate = new Function('module', 'exports', 'globalThis', source);
+    evaluate(module, exports, globalThis);
+    const entry = module.exports.default ?? module.exports;
+    if (!isRecord(entry)) throw new Error(`[BFF][Effect] Backend federation remote ${remote.name} entry must load object module.`);
+    return entry;
+}
+async function importModuleEntry(remote) {
+    const entry = await import(remote.entry);
+    return entry.default ?? entry;
+}
+async function resolvePluginEntry(remote, plugins) {
+    for (const plugin of plugins ?? []){
+        const loadEntry = plugin.loadEntry;
+        if ('function' != typeof loadEntry) continue;
+        const entry = await loadEntry({
+            remoteInfo: remote
+        });
+        if (entry) return entry;
+    }
+}
+async function loadBackendFederationEntry(remote, plugins) {
+    const pluginEntry = await resolvePluginEntry(remote, plugins);
+    if (pluginEntry) return pluginEntry;
+    if (remote.entryGlobalName) {
+        const globalEntry = globalThis[remote.entryGlobalName];
+        if (isRecord(globalEntry)) return globalEntry;
+    }
+    if ('module' === remote.type || remote.entry.startsWith('file:')) return importModuleEntry(remote);
+    return evaluateCommonJsEntry(remote, await readCommonJsEntrySource(remote));
+}
+async function loadBackendFederationExpose(remote, expose, options) {
+    const entry = await loadBackendFederationEntry(remote, options.plugins);
+    if ('function' == typeof entry.init) await entry.init({
+        hostName: options.hostName
+    });
+    if ('function' != typeof entry.get) throw new Error(`[BFF][Effect] Backend federation remote ${remote.name} entry must expose get().`);
+    const factory = await entry.get(expose);
+    if ('function' != typeof factory) throw new Error(`[BFF][Effect] Backend federation expose ${remote.name}/${normalizeExpose(expose)} must load factory function.`);
+    return factory();
+}
+function createBackendFederationRuntime(options) {
+    const remotes = collectRemotes(options);
+    return {
+        async loadRemote (request) {
+            const { remoteName, expose } = parseRemoteRequest(request);
+            const remote = remotes.find((candidate)=>candidate.name === remoteName);
+            if (!remote) throw new Error(`[BFF][Effect] Missing backend federation remote ${remoteName}.`);
+            return loadBackendFederationExpose(remote, expose, options);
+        }
+    };
+}
+function createBackendFederationLoadEntryPlugin(options) {
+    return {
+        name: 'modernjs-backend-federation-load-entry',
+        async loadEntry ({ remoteInfo }) {
+            return options.resolveEntry({
+                name: remoteInfo.name,
+                entry: remoteInfo.entry,
+                type: remoteInfo.type,
+                entryGlobalName: remoteInfo.entryGlobalName,
+                shareScope: remoteInfo.shareScope
+            });
+        }
+    };
+}
+async function loadBackendFederatedEffectApi(options) {
+    const remoteName = options.remote?.name ?? options.remoteName;
+    if (!remoteName) throw new Error('[BFF][Effect] Missing backend federation remote name.');
+    const runtime = options.runtime ?? createBackendFederationRuntime(options);
+    const expose = options.expose ?? options.remote?.expose ?? BACKEND_FEDERATION_EFFECT_EXPOSE;
+    const remoteRequest = `${remoteName}/${normalizeExpose(expose)}`;
+    const loaded = await runtime.loadRemote(remoteRequest);
+    if (!isRecord(loaded)) throw new Error(`[BFF][Effect] Backend federation expose ${remoteRequest} must load an object module.`);
+    const backendContract = loaded.backendFederationContract;
+    if (!isRecord(backendContract) || true !== backendContract.strictEffectApproach) throw new Error(`[BFF][Effect] Backend federation expose ${remoteRequest} must expose strict Effect metadata (strictEffectApproach: true).`);
+    if ('effect' !== backendContract.runtimeFramework) throw new Error(`[BFF][Effect] Backend federation expose ${remoteRequest} must expose strict Effect metadata (runtimeFramework: "effect").`);
+    if ('string' == typeof backendContract.name && backendContract.name !== remoteName) throw new Error(`[BFF][Effect] Backend federation expose ${remoteRequest} metadata name mismatch: expected ${remoteName}, received ${backendContract.name}.`);
+    if (!('runtime' in loaded)) throw new Error(`[BFF][Effect] Backend federation expose ${remoteRequest} must expose api and runtime.`);
+    return loaded;
+}
+export { BACKEND_FEDERATION_CONTRACT_VERSION, BACKEND_FEDERATION_EFFECT_EXPOSE, BACKEND_FEDERATION_MANIFEST_FILE, BACKEND_FEDERATION_NODE_ADAPTER_VERSION, createBackendFederationLoadEntryPlugin, createBackendFederationRuntime, loadBackendFederatedEffectApi };

package/dist/esm-node/runtime/effect/dispatch.mjs

@@ -0,0 +1,64 @@
+import "node:module";
+import { createSafeFailureResponse } from "../safe-failure.mjs";
+import { createEffectOperationContext } from "./operation-context.mjs";
+function normalizeEffectBffPrefix(prefix) {
+    if (!prefix || '/' === prefix) return '';
+    return prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
+}
+function removeEffectBffPrefixFromPath(pathname, prefix) {
+    const normalized = normalizeEffectBffPrefix(prefix);
+    if (!normalized || pathname !== normalized && !pathname.startsWith(`${normalized}/`)) return pathname;
+    const sliced = pathname.slice(normalized.length);
+    return sliced.startsWith('/') ? sliced : `/${sliced}`;
+}
+function matchesEffectBffPrefix(pathname, prefix) {
+    const normalized = normalizeEffectBffPrefix(prefix);
+    return !normalized || pathname === normalized || pathname.startsWith(`${normalized}/`);
+}
+function createEffectBffMountedRequest(req, prefix) {
+    const url = new URL(req.url);
+    const nextPath = removeEffectBffPrefixFromPath(url.pathname, prefix);
+    if (nextPath !== url.pathname) {
+        url.pathname = nextPath;
+        return new Request(url, req);
+    }
+    return req;
+}
+function createEffectBffDispatchContext(originalRequest, mountedRequest, options) {
+    const path = options.path ?? new URL(originalRequest.url).pathname;
+    const method = options.method ?? originalRequest.method;
+    const env = options.env ?? {};
+    return {
+        request: mountedRequest,
+        env,
+        path,
+        method,
+        operationContext: createEffectOperationContext({
+            request: mountedRequest,
+            env,
+            path,
+            method
+        })
+    };
+}
+async function dispatchEffectBffRequestWithContext(handler, request, options) {
+    const requestPath = new URL(request.url).pathname;
+    if (!matchesEffectBffPrefix(requestPath, options.prefix)) return new Response('', {
+        status: 404
+    });
+    const mountedRequest = createEffectBffMountedRequest(request, options.prefix);
+    const effectContext = createEffectBffDispatchContext(request, mountedRequest, options);
+    try {
+        const response = await options.runWithEffectContext(effectContext, ()=>handler(mountedRequest, effectContext));
+        if (!(response instanceof Response)) throw new Error('[BFF][Effect] Effect handler must return Response instance.');
+        return new Response(response.body, response);
+    } catch (error) {
+        if (error instanceof Response) return new Response(error.body, error);
+        if (options.onError) {
+            const errorResponse = await options.onError(error, effectContext);
+            if (errorResponse instanceof Response) return errorResponse;
+        }
+        return createSafeFailureResponse(error);
+    }
+}
+export { createEffectBffDispatchContext, createEffectBffMountedRequest, dispatchEffectBffRequestWithContext, matchesEffectBffPrefix, normalizeEffectBffPrefix, removeEffectBffPrefixFromPath };

package/dist/esm-node/runtime/effect/edge.mjs

@@ -1,71 +1,15 @@
 import "node:module";
-import { createSafeFailureResponse } from "../safe-failure.mjs";
+import { dispatchEffectBffRequestWithContext } from "./dispatch.mjs";
 import { runWithEffectContext, useEffectContext, useOperationContext } from "./edge-context.mjs";
 import { resolveEffectBffModuleHandler } from "./module.mjs";
-import { createEffectOperationContext } from "./operation-context.mjs";
 export * from "./handler.mjs";
-function normalizePrefix(prefix) {
-    if (!prefix || '/' === prefix) return '';
-    return prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
-}
-function removePrefixFromPath(pathname, prefix) {
-    const normalized = normalizePrefix(prefix);
-    if (!normalized || pathname !== normalized && !pathname.startsWith(`${normalized}/`)) return pathname;
-    const sliced = pathname.slice(normalized.length);
-    return sliced.startsWith('/') ? sliced : `/${sliced}`;
-}
-function matchesPrefix(pathname, prefix) {
-    const normalized = normalizePrefix(prefix);
-    return !normalized || pathname === normalized || pathname.startsWith(`${normalized}/`);
-}
-function createRequestForMountedPrefix(req, prefix) {
-    const url = new URL(req.url);
-    const nextPath = removePrefixFromPath(url.pathname, prefix);
-    if (nextPath === url.pathname) return req;
-    url.pathname = nextPath;
-    return new Request(url, req);
-}
-function createEdgeEffectContext(originalRequest, effectRequest, options) {
-    const originalPath = options.path || new URL(originalRequest.url).pathname;
-    const method = options.method || originalRequest.method;
-    return {
-        request: effectRequest,
-        env: options.env || {},
-        path: originalPath,
-        method,
-        operationContext: createEffectOperationContext({
-            request: effectRequest,
-            env: options.env || {},
-            path: originalPath,
-            method
-        })
-    };
-}
-function createRuntimeErrorResponse(error) {
-    return createSafeFailureResponse(error);
-}
 async function dispatchEffectBffRequest(handler, request, options = {}) {
-    const requestPathname = new URL(request.url).pathname;
-    if (!matchesPrefix(requestPathname, options.prefix)) return new Response(null, {
-        status: 404
+    return dispatchEffectBffRequestWithContext(handler, request, {
+        ...options,
+        runWithEffectContext: runWithEffectContext
     });
-    const effectRequest = createRequestForMountedPrefix(request, options.prefix);
-    const effectContext = createEdgeEffectContext(request, effectRequest, options);
-    try {
-        const response = await runWithEffectContext(effectContext, ()=>handler.length > 1 ? handler(effectRequest, effectContext) : handler(effectRequest));
-        if (!(response instanceof Response)) throw new Error('[BFF][Effect] Effect handler must return a Response instance.');
-        return new Response(response.body, response);
-    } catch (error) {
-        if (error instanceof Response) return new Response(error.body, error);
-        if (options.onError) {
-            const errorResponse = await options.onError(error, effectContext);
-            if (errorResponse instanceof Response) return errorResponse;
-        }
-        return createRuntimeErrorResponse(error);
-    }
 }
-const createEffectBffTestHandler = createEffectBffEdgeHandler;
-async function createEffectBffEdgeHandler(options) {
+async function createEffectBffEdgeDispatcher(options) {
     const loaded = await resolveEffectBffModuleHandler(options.module, {
         openapi: options.openapi,
         dataPlatform: options.dataPlatform,
@@ -73,7 +17,7 @@ async function createEffectBffEdgeHandler(options) {
     });
     if (!loaded) throw new Error('[BFF][Effect] Invalid Effect edge module. Export defineEffectBff(...) or a { api, layer } HttpApi module.');
     return {
-        handler: (request, dispatchOptions = {})=>dispatchEffectBffRequest(loaded.handler, request, {
+        dispatch: (request, dispatchOptions = {})=>dispatchEffectBffRequest(loaded.handler, request, {
                 ...dispatchOptions,
                 prefix: options.prefix,
                 onError: options.onError
@@ -83,4 +27,14 @@ async function createEffectBffEdgeHandler(options) {
         }
     };
 }
-export { createEffectBffEdgeHandler, createEffectBffTestHandler, createEffectOperationContext, dispatchEffectBffRequest, runWithEffectContext, useEffectContext, useOperationContext };
+const createEffectBffTestHandler = createEffectBffEdgeHandler;
+async function createEffectBffEdgeHandler(options) {
+    const dispatcher = await createEffectBffEdgeDispatcher(options);
+    return {
+        handler: dispatcher.dispatch,
+        dispose: dispatcher.dispose
+    };
+}
+export { BACKEND_FEDERATION_CONTRACT_VERSION, BACKEND_FEDERATION_EFFECT_EXPOSE, BACKEND_FEDERATION_MANIFEST_FILE, BACKEND_FEDERATION_NODE_ADAPTER_VERSION, createBackendFederationLoadEntryPlugin, createBackendFederationRuntime, loadBackendFederatedEffectApi } from "./backend-federation.mjs";
+export { createEffectOperationContext } from "./operation-context.mjs";
+export { createEffectBffEdgeDispatcher, createEffectBffEdgeHandler, createEffectBffTestHandler, dispatchEffectBffRequest, runWithEffectContext, useEffectContext, useOperationContext };

package/dist/esm-node/runtime/effect/endpoint-contracts.mjs

@@ -1,5 +1,6 @@
 import "node:module";
 import { createOperationContractHash } from "@modern-js/bff-core";
+import { classifyEffectBffEntryModule, isValidatorAwareHandlerFactory } from "./entry-shape.mjs";
 function ensureLeadingSlash(pathname) {
     return pathname.startsWith('/') ? pathname : `/${pathname}`;
 }
@@ -49,19 +50,13 @@ function createEffectOperationContractSource(endpoint) {
         routePath: endpoint.routePath
     };
 }
-function isRecord(value) {
-    return 'object' == typeof value && null !== value;
-}
 async function extractHttpApiFromModule(mod, isHttpApi) {
-    if (!isRecord(mod)) return null;
-    if (isHttpApi(mod.api)) return mod.api;
-    const entry = mod.default;
-    if (isRecord(entry) && isHttpApi(entry.api)) return entry.api;
-    if ('function' == typeof entry && 0 === entry.length) {
-        const output = await entry();
-        if (isRecord(output) && isHttpApi(output.api)) return output.api;
-    }
-    return null;
+    const facts = classifyEffectBffEntryModule(mod, {
+        isRequestHandler: (value)=>'function' == typeof value,
+        isValidatorAwareHandlerFactory: isValidatorAwareHandlerFactory,
+        isHttpApi
+    });
+    return !facts?.legacyShape && facts?.api !== void 0 && facts.hasRuntimeLayer && (void 0 === facts.createHandler || facts.createHandlerValidatorAware) ? facts.api : null;
 }
 function createEffectEndpointContractHash(endpoint, requestId) {
     return createOperationContractHash(createEffectOperationContractSource(endpoint), requestId);

package/dist/esm-node/runtime/effect/entry-shape.mjs

@@ -0,0 +1,37 @@
+import "node:module";
+const EFFECT_VALIDATOR_AWARE_FACTORY = Symbol.for('modernjs.effect.validatorAware');
+function isValidatorAwareHandlerFactory(factory) {
+    return Boolean('function' == typeof factory && factory[EFFECT_VALIDATOR_AWARE_FACTORY]);
+}
+const strictEffectApproachMessage = '[BFF][Effect] strictEffectApproach is enforced: Effect API entries export defineEffectBff(...) or { api, layer } HttpApi module. Raw handler exports, default request handlers, unbranded custom createHandler factories not valid Effect API entries.';
+function isEffectEntryRecord(value) {
+    return 'object' == typeof value && null !== value;
+}
+function classifyEffectBffEntryModule(value, predicates) {
+    if (!isEffectEntryRecord(value)) return null;
+    const rootModule = value;
+    if (predicates.isRequestHandler(rootModule.handler)) return createEntryShapeFacts(rootModule, predicates, '`handler` export');
+    const defaultEntry = rootModule.default;
+    if (predicates.isRequestHandler(defaultEntry)) return createEntryShapeFacts(rootModule, predicates, 'default request handler');
+    const module = isEffectEntryRecord(defaultEntry) ? {
+        ...rootModule,
+        ...defaultEntry
+    } : rootModule;
+    if (predicates.isRequestHandler(module.handler)) return createEntryShapeFacts(module, predicates, '`handler` export');
+    return createEntryShapeFacts(module, predicates);
+}
+function createEntryShapeFacts(module, predicates, legacyShape) {
+    const createHandler = 'function' == typeof module.createHandler ? module.createHandler : void 0;
+    const api = predicates.isHttpApi(module.api) ? module.api : void 0;
+    const hasRuntimeLayer = void 0 !== module.layer;
+    return {
+        module,
+        legacyShape,
+        createHandler,
+        createHandlerValidatorAware: void 0 !== createHandler && predicates.isValidatorAwareHandlerFactory(createHandler),
+        api,
+        layer: module.layer,
+        hasRuntimeLayer
+    };
+}
+export { EFFECT_VALIDATOR_AWARE_FACTORY, classifyEffectBffEntryModule, isEffectEntryRecord, isValidatorAwareHandlerFactory, strictEffectApproachMessage };

package/dist/esm-node/runtime/effect/handler.mjs

@@ -4,6 +4,7 @@ import { HttpRouter, HttpServer, HttpServerResponse, HttpTraceContext } from "ef
 import { HttpApiBuilder, OpenApi } from "effect/unstable/httpapi";
 import { RpcSerialization, RpcServer } from "effect/unstable/rpc";
 import { DEFAULT_DATA_BATCH_ENDPOINT, DEFAULT_DATA_BATCH_HEADER, DEFAULT_DATA_ENVELOPE_HEADER, decodeRequestEnvelopeHeader, validateRequestEnvelope, validateSelectionPlan } from "../data-platform/index.mjs";
+import { EFFECT_VALIDATOR_AWARE_FACTORY, isValidatorAwareHandlerFactory } from "./entry-shape.mjs";
 import * as __rspack_external_effect_Config_29be8a92 from "effect/Config";
 import * as __rspack_external_effect_Effect_194ac36c from "effect/Effect";
 import * as __rspack_external_effect_Option_4d691636 from "effect/Option";
@@ -15,10 +16,6 @@ import * as __rspack_external_effect_Context_f1289ca3 from "effect/Context";
 const emptyEffectServiceContext = __rspack_external_effect_Context_f1289ca3.empty();
 const isEffectServiceContext = (context)=>'object' == typeof context && null !== context && 'mapUnsafe' in context;
 const toEffectServiceContext = (context)=>isEffectServiceContext(context) ? context : emptyEffectServiceContext;
-const EFFECT_VALIDATOR_AWARE_FACTORY = Symbol.for('modernjs.effect.validatorAware');
-function isValidatorAwareHandlerFactory(factory) {
-    return 'function' == typeof factory && true === factory[EFFECT_VALIDATOR_AWARE_FACTORY];
-}
 function normalizeOpenApiPath(pathname) {
     if (!pathname.startsWith('/')) return `/${pathname}`;
     return pathname;

package/dist/esm-node/runtime/effect/index.mjs

@@ -1,6 +1,9 @@
 import "node:module";
 import * as __rspack_external__effect_opentelemetry_8bbbb5af from "@effect/opentelemetry";
+export * from "./backend-federation.mjs";
 export * from "./handler.mjs";
+export { BACKEND_FEDERATION_CONTRACT_VERSION, BACKEND_FEDERATION_EFFECT_EXPOSE, BACKEND_FEDERATION_MANIFEST_FILE, BACKEND_FEDERATION_NODE_ADAPTER_VERSION, createBackendFederationLoadEntryPlugin, createBackendFederationRuntime, loadBackendFederatedEffectApi } from "./backend-federation.mjs";
+export { BackendFederationManifestAdapterError, loadBackendFederatedEffectApiFromManifest, loadBackendFederationManifest, resolveBackendFederationRemoteFromManifest } from "./backend-federation-manifest.mjs";
 export { createEffectOperationContext, runWithEffectContext, useEffectContext, useOperationContext } from "./context.mjs";
 export { createEffectBffEdgeHandler, createEffectBffTestHandler, dispatchEffectBffRequest } from "./edge.mjs";
 export { __rspack_external__effect_opentelemetry_8bbbb5af as OpenTelemetry };

package/dist/esm-node/runtime/effect/module.mjs

@@ -1,24 +1,15 @@
 import "node:module";
 import { HttpApi } from "effect/unstable/httpapi";
-import { createHttpApiHandler, isValidatorAwareHandlerFactory } from "./handler.mjs";
+import { classifyEffectBffEntryModule, isValidatorAwareHandlerFactory, strictEffectApproachMessage } from "./entry-shape.mjs";
+import { createHttpApiHandler } from "./handler.mjs";
 import * as __rspack_external_effect_Context_f1289ca3 from "effect/Context";
-function isRecord(value) {
-    return 'object' == typeof value && null !== value;
-}
-function includesRuntimeExports(value) {
-    return 'api' in value || 'layer' in value || 'createHandler' in value || 'handler' in value;
-}
 function isRequestHandler(value) {
     return 'function' == typeof value;
 }
-function isEffectApiDefinition(module) {
-    return HttpApi.isHttpApi(module.api) && void 0 !== module.layer;
-}
 function isEffectServiceContext(context) {
     return 'object' == typeof context && null !== context && 'mapUnsafe' in context;
 }
 const emptyEffectServiceContext = __rspack_external_effect_Context_f1289ca3.empty();
-const strictEffectApproachMessage = '[BFF][Effect] strictEffectApproach is enforced: Effect API entries must export defineEffectBff(...) or a { api, layer } HttpApi module. Raw handler exports, default request handlers, and unbranded custom createHandler factories are not valid Effect API entries.';
 function rejectLegacyEffectModuleShape(options, shape) {
     options.onWarning?.(`${strictEffectApproachMessage} Rejected ${shape}.`);
     return true;
@@ -41,41 +32,21 @@ function createLoadedHttpApiHandler(webHandler) {
         dispose: webHandler.dispose
     };
 }
-function resolveNormalizedEffectBffModuleHandler(normalizedModule, options = {}) {
-    if (isRequestHandler(normalizedModule.handler)) {
-        if (rejectLegacyEffectModuleShape(options, '`handler` export')) return null;
-        return {
-            handler: normalizedModule.handler
-        };
-    }
-    const entry = normalizedModule.default;
-    if (isRequestHandler(entry)) {
-        if (rejectLegacyEffectModuleShape(options, 'default request handler')) return null;
-        return {
-            handler: entry
-        };
-    }
-    if (isRecord(entry)) normalizedModule = {
-        ...normalizedModule,
-        ...entry
-    };
-    if (isRecord(entry) && 'handler' in entry) {
-        const maybeHandler = entry.handler;
-        if (isRequestHandler(maybeHandler)) normalizedModule = {
-            ...normalizedModule,
-            handler: maybeHandler
-        };
-    }
-    if (isRequestHandler(normalizedModule.handler)) {
-        if (rejectLegacyEffectModuleShape(options, '`handler` export')) return null;
-        return {
-            handler: normalizedModule.handler
-        };
+function classifyEffectBffRuntimeEntryShape(module) {
+    return classifyEffectBffEntryModule(module, {
+        isRequestHandler: isRequestHandler,
+        isValidatorAwareHandlerFactory: isValidatorAwareHandlerFactory,
+        isHttpApi: HttpApi.isHttpApi
+    });
+}
+function resolveClassifiedEffectBffModuleHandler(facts, options = {}) {
+    if (!facts) return null;
+    if (facts.legacyShape) {
+        if (rejectLegacyEffectModuleShape(options, facts.legacyShape)) return null;
     }
-    if ('function' == typeof normalizedModule.createHandler) {
-        const factory = normalizedModule.createHandler;
-        const validatorAware = isValidatorAwareHandlerFactory(factory);
-        if (!validatorAware && rejectLegacyEffectModuleShape(options, 'unbranded `createHandler` export')) return null;
+    if ('function' == typeof facts.createHandler) {
+        if (!facts.createHandlerValidatorAware && rejectLegacyEffectModuleShape(options, 'unbranded `createHandler` export')) return null;
+        const factory = facts.createHandler;
         const webHandler = factory({
             openapi: options.openapi,
             dataPlatform: options.dataPlatform,
@@ -83,11 +54,11 @@ function resolveNormalizedEffectBffModuleHandler(normalizedModule, options = {})
         });
         return createLoadedHandler(webHandler);
     }
-    if (isEffectApiDefinition(normalizedModule)) {
+    if (void 0 !== facts.api && facts.hasRuntimeLayer) {
         options.onWarning?.('[BFF][Effect] Detected { api, layer } export without createHandler. Prefer `defineEffectBff(...)` from @modern-js/plugin-bff/server to avoid module instance mismatch.');
         const webHandler = createHttpApiHandler({
-            api: normalizedModule.api,
-            layer: normalizedModule.layer,
+            api: facts.api,
+            layer: facts.layer,
             openapi: options.openapi,
             dataPlatform: options.dataPlatform,
             validateRequest: options.validateRequest
@@ -96,38 +67,10 @@ function resolveNormalizedEffectBffModuleHandler(normalizedModule, options = {})
     }
     return null;
 }
+function resolveNormalizedEffectBffModuleHandler(normalizedModule, options = {}) {
+    return resolveClassifiedEffectBffModuleHandler(classifyEffectBffRuntimeEntryShape(normalizedModule), options);
+}
 function resolveEffectBffModuleHandler(mod, options = {}) {
-    let normalizedModule = mod;
-    const mergeRuntimeExports = (value)=>{
-        if (!isRecord(value) || !includesRuntimeExports(value)) return;
-        normalizedModule = {
-            ...normalizedModule,
-            ...value
-        };
-    };
-    if (isRequestHandler(normalizedModule.handler)) {
-        if (rejectLegacyEffectModuleShape(options, '`handler` export')) return Promise.resolve(null);
-        return Promise.resolve({
-            handler: normalizedModule.handler
-        });
-    }
-    const entry = normalizedModule.default;
-    if (isRequestHandler(entry)) {
-        if (rejectLegacyEffectModuleShape(options, 'default request handler')) return Promise.resolve(null);
-        return Promise.resolve({
-            handler: entry
-        });
-    }
-    if ('function' == typeof entry && 0 === entry.length) return Promise.resolve(entry()).then((out)=>{
-        if (isRequestHandler(out)) {
-            if (rejectLegacyEffectModuleShape(options, 'default factory returning a request handler')) return null;
-            return {
-                handler: out
-            };
-        }
-        mergeRuntimeExports(out);
-        return resolveNormalizedEffectBffModuleHandler(normalizedModule, options);
-    });
-    return Promise.resolve(resolveNormalizedEffectBffModuleHandler(normalizedModule, options));
+    return Promise.resolve(resolveNormalizedEffectBffModuleHandler(mod, options));
 }
 export { resolveEffectBffModuleHandler };

package/dist/types/runtime/effect/backend-federation-manifest.d.ts

@@ -0,0 +1,60 @@
+import type { ModuleFederation, ModuleFederationRuntimePlugin } from '@module-federation/runtime';
+import { type BackendFederatedEffectApiModule, type BackendFederationRemote } from './backend-federation';
+export type BackendFederationManifestAdapterErrorCode = 'manifest_unavailable' | 'manifest_invalid' | 'remote_unavailable' | 'strict_effect_required' | 'timeout' | 'version_mismatch';
+export declare const BACKEND_FEDERATION_MANIFEST_ADAPTER_FAILURE_EVENT: 'modernjs:microvertical-server-fallback';
+export declare class BackendFederationManifestAdapterError extends Error {
+    code: BackendFederationManifestAdapterErrorCode;
+    readonly failureEvent: "modernjs:microvertical-server-fallback";
+    details?: Record<string, unknown>;
+    constructor(code: BackendFederationManifestAdapterErrorCode, message: string, cause?: unknown, details?: Record<string, unknown>);
+}
+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 = {
+    ok: boolean;
+    status: number;
+    statusText?: string;
+    text: () => Promise<string>;
+};
+export type BackendFederationManifestAdapterFallback = (error: BackendFederationManifestAdapterError, context: {
+    manifest?: BackendFederationManifest;
+    remote?: BackendFederationRemote;
+}) => BackendFederatedEffectApiModule | Promise<BackendFederatedEffectApiModule>;
+export type BackendFederationManifestAdapterOptions = {
+    env?: Record<string, string | undefined>;
+    expected?: BackendFederationVersionBoundaryExpectation;
+    fallback?: BackendFederationManifestAdapterFallback;
+    fetch?: (url: string) => Promise<BackendFederationManifestFetchResponse>;
+    hostName: string;
+    manifest?: BackendFederationManifest;
+    manifestEnv?: string;
+    manifestPath?: string;
+    manifestUrl?: string;
+    plugins?: ModuleFederationRuntimePlugin[];
+    remote?: Partial<BackendFederationRemote>;
+    runtime?: ModuleFederation;
+    timeoutMs?: number;
+};
+export declare function loadBackendFederationManifest(options: Pick<BackendFederationManifestAdapterOptions, 'env' | 'fetch' | 'manifest' | 'manifestEnv' | 'manifestPath' | 'manifestUrl' | 'timeoutMs'>): Promise<BackendFederationManifest>;
+export declare function resolveBackendFederationRemoteFromManifest(manifest: BackendFederationManifest, remoteOverride?: Partial<BackendFederationRemote>): BackendFederationRemote;
+export declare function loadBackendFederatedEffectApiFromManifest(options: BackendFederationManifestAdapterOptions): Promise<BackendFederatedEffectApiModule>;