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

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

@@ -0,0 +1,37 @@
+import "node:module";
+import { BACKEND_FEDERATION_EFFECT_EXPOSE, loadBackendFederatedEffectApi } from "../backend-federation.mjs";
+import { BackendFederationManifestAdapterError } from "./errors.mjs";
+import { loadBackendFederationManifest, withTimeout } from "./reference.mjs";
+import { resolveBackendFederationRemoteFromManifest } from "./remote.mjs";
+import { classifyLoadError, validateBackendFederationManifest, validateLoadedBackendFederationContract } from "./validation.mjs";
+async function loadBackendFederatedEffectApiFromManifest(options) {
+    let manifest;
+    let remote;
+    try {
+        manifest = await loadBackendFederationManifest(options);
+        validateBackendFederationManifest(manifest, options.expected);
+        remote = resolveBackendFederationRemoteFromManifest(manifest, options.remote);
+        const loaded = await withTimeout(loadBackendFederatedEffectApi({
+            hostName: options.hostName,
+            remote,
+            ...options.plugins ? {
+                plugins: options.plugins
+            } : {},
+            ...options.runtime ? {
+                runtime: options.runtime
+            } : {}
+        }), options.timeoutMs, `Backend federation remote ${remote.name}`).catch((error)=>{
+            throw new BackendFederationManifestAdapterError(classifyLoadError(error), `[BFF][Effect] Backend federation remote ${remote?.name ?? 'unknown'} could not load ${remote?.expose ?? BACKEND_FEDERATION_EFFECT_EXPOSE}.`, error);
+        });
+        validateLoadedBackendFederationContract(loaded, manifest, remote);
+        return loaded;
+    } catch (error) {
+        const adapterError = error instanceof BackendFederationManifestAdapterError ? error : new BackendFederationManifestAdapterError('remote_unavailable', '[BFF][Effect] Backend federation manifest adapter failed.', error);
+        if (options.fallback) return options.fallback(adapterError, {
+            manifest,
+            remote
+        });
+        throw adapterError;
+    }
+}
+export { loadBackendFederatedEffectApiFromManifest };

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

@@ -0,0 +1,43 @@
+import "node:module";
+import { backendFederationMetadata, backendFederationVersionBoundary } from "@modern-js/utils/universal";
+function stringValue(value) {
+    return 'string' == typeof value && value.length > 0 ? value : void 0;
+}
+function isRecord(value) {
+    return 'object' == typeof value && null !== value;
+}
+function recordField(value, field) {
+    const fieldValue = value?.[field];
+    return isRecord(fieldValue) ? fieldValue : void 0;
+}
+function resolveRemoteEntryFromMetadata(manifest) {
+    const metaData = recordField(manifest, 'metaData');
+    const remoteEntry = recordField(metaData, 'remoteEntry');
+    const publicPath = stringValue(metaData?.publicPath) ?? stringValue(metaData?.ssrPublicPath);
+    const entryName = stringValue(remoteEntry?.name);
+    if (!publicPath || !entryName) return;
+    const entryPath = stringValue(remoteEntry?.path) ?? '';
+    const normalizedBase = publicPath.replace(/\/+$/u, '');
+    const normalizedPath = entryPath.replace(/^\/+|\/+$/gu, '');
+    return [
+        normalizedBase,
+        normalizedPath,
+        entryName
+    ].filter(Boolean).join('/');
+}
+function metadata_backendFederationMetadata(manifest) {
+    return backendFederationMetadata(manifest);
+}
+function versionBoundaryMetadata(manifest) {
+    return backendFederationVersionBoundary(manifest);
+}
+function deliveryUnitMetadata(record) {
+    return recordField(record, 'deliveryUnit');
+}
+function manifestDeliveryUnit(backendFederation, boundary) {
+    return {
+        boundary: deliveryUnitMetadata(boundary),
+        top: deliveryUnitMetadata(backendFederation)
+    };
+}
+export { deliveryUnitMetadata, isRecord, manifestDeliveryUnit, metadata_backendFederationMetadata as backendFederationMetadata, recordField, resolveRemoteEntryFromMetadata, stringValue, versionBoundaryMetadata };

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

@@ -0,0 +1,77 @@
+import "node:module";
+import { BACKEND_FEDERATION_MANIFEST_FILE } from "../backend-federation.mjs";
+import { BackendFederationManifestAdapterError, assertManifestAdapter } from "./errors.mjs";
+import { isRecord } from "./metadata.mjs";
+function getProcessEnv() {
+    return "u" > typeof process ? process.env : void 0;
+}
+function resolveManifestReferenceSource(options) {
+    if (options.manifestPath) return 'path';
+    if (options.manifestUrl) return 'url';
+    if (options.manifestEnv) return 'env';
+}
+function resolveManifestReference(options) {
+    if (options.manifestPath) return options.manifestPath;
+    if (options.manifestUrl) return options.manifestUrl;
+    if (!options.manifestEnv) return;
+    return options.env?.[options.manifestEnv] ?? getProcessEnv()?.[options.manifestEnv];
+}
+function assertExpectedIdentityForReference(options, source) {
+    if (void 0 === source || 'path' === source || options.allowLegacyManifest) 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. Pass allowLegacyManifest: true to load legacy manifest references.`, void 0, {
+        label: 'expected.deliveryUnit',
+        expected: 'unitId + buildMarker',
+        received: options.expected,
+        referenceSource: source
+    });
+}
+function isHttpUrl(value) {
+    return /^https?:\/\//iu.test(value);
+}
+async function readFileReference(reference) {
+    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');
+}
+async function withTimeout(promise, timeoutMs, label) {
+    if (!timeoutMs || timeoutMs <= 0) return promise;
+    let timeout;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject)=>{
+                timeout = setTimeout(()=>{
+                    reject(new BackendFederationManifestAdapterError('timeout', `[BFF][Effect] ${label} timed out after ${timeoutMs}ms.`));
+                }, timeoutMs);
+            })
+        ]);
+    } finally{
+        if (timeout) clearTimeout(timeout);
+    }
+}
+async function loadBackendFederationManifest(options) {
+    if (options.manifest) return options.manifest;
+    const reference = resolveManifestReference(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));
+    try {
+        const source = isHttpUrl(reference) ? await (async ()=>{
+            const fetchManifest = options.fetch ?? globalThis.fetch;
+            if (!fetchManifest) throw new BackendFederationManifestAdapterError('manifest_unavailable', `[BFF][Effect] Backend federation manifest ${reference} requires a fetch implementation.`);
+            const response = await withTimeout(fetchManifest(reference), options.timeoutMs, `Backend federation manifest ${reference}`);
+            if (!response.ok) throw new BackendFederationManifestAdapterError('manifest_unavailable', `[BFF][Effect] Backend federation manifest ${reference} returned HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ''}.`);
+            return response.text();
+        })() : await withTimeout(readFileReference(reference), options.timeoutMs, `Backend federation manifest ${reference}`);
+        const manifest = JSON.parse(source);
+        assertManifestAdapter(isRecord(manifest), 'manifest_invalid', `[BFF][Effect] Backend federation manifest ${reference} must be a JSON object.`);
+        return manifest;
+    } catch (error) {
+        if (error instanceof BackendFederationManifestAdapterError) throw error;
+        throw new BackendFederationManifestAdapterError('manifest_unavailable', `[BFF][Effect] Backend federation manifest ${reference} could not be loaded.`, error);
+    }
+}
+export { loadBackendFederationManifest, withTimeout };

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

@@ -0,0 +1,31 @@
+import "node:module";
+import { backendFederationExposeNames } from "@modern-js/utils/universal";
+import { BACKEND_FEDERATION_EFFECT_EXPOSE } from "../backend-federation.mjs";
+import { assertManifestAdapter } from "./errors.mjs";
+import { backendFederationMetadata, recordField, resolveRemoteEntryFromMetadata, stringValue } from "./metadata.mjs";
+function resolveBackendFederationRemoteFromManifest(manifest, remoteOverride = {}) {
+    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 remoteEntryUrl = remoteOverride.entry ?? stringValue(backendFederation?.containerEntry) ?? stringValue(entry?.url) ?? resolveRemoteEntryFromMetadata(manifest);
+    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;
+    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,
+        ...remoteOverride.entryGlobalName ? {
+            entryGlobalName: remoteOverride.entryGlobalName
+        } : {},
+        expose,
+        ...remoteOverride.shareScope ? {
+            shareScope: remoteOverride.shareScope
+        } : {}
+    };
+}
+export { resolveBackendFederationRemoteFromManifest };

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

@@ -0,0 +1 @@
+import "node:module";

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

@@ -0,0 +1,65 @@
+import "node:module";
+import { formatBackendFederationValidationErrors, validateBackendFederationManifest } from "@modern-js/utils/universal";
+import { BACKEND_FEDERATION_CONTRACT_VERSION, BACKEND_FEDERATION_NODE_ADAPTER_VERSION } from "../backend-federation.mjs";
+import { BackendFederationManifestAdapterError, assertConsistentValue, assertManifestAdapter, assertVersionValue } from "./errors.mjs";
+import { backendFederationMetadata, manifestDeliveryUnit, recordField, stringValue, versionBoundaryMetadata } from "./metadata.mjs";
+function resolveExpectedBuildMarker(expected) {
+    if (void 0 !== expected.buildVersion && void 0 !== expected.buildMarker && expected.buildVersion !== expected.buildMarker) throw new BackendFederationManifestAdapterError('version_mismatch', `[BFF][Effect] Backend federation expected buildVersion/buildMarker mismatch: buildVersion ${expected.buildVersion}, buildMarker ${expected.buildMarker}.`, void 0, {
+        label: 'expected.buildVersion/buildMarker',
+        expected: expected.buildVersion,
+        received: expected.buildMarker
+    });
+    return expected.buildMarker;
+}
+function validation_validateBackendFederationManifest(manifest, expected = {}) {
+    const expectedBuildMarker = resolveExpectedBuildMarker(expected);
+    const backendFederation = backendFederationMetadata(manifest);
+    assertManifestAdapter(backendFederation, 'manifest_invalid', '[BFF][Effect] Backend federation manifest must declare backendFederation metadata.');
+    const manifestShape = validateBackendFederationManifest(manifest, {
+        expectedContractVersion: false,
+        expectedNodeAdapterVersion: false,
+        validateDeliveryUnit: false
+    });
+    assertManifestAdapter(manifestShape.ok, 'manifest_invalid', `[BFF][Effect] Backend federation manifest schema invalid: ${formatBackendFederationValidationErrors(manifestShape.errors)}.`);
+    assertManifestAdapter('effect' === backendFederation.runtimeFramework, 'strict_effect_required', '[BFF][Effect] Backend federation manifest must declare runtimeFramework: "effect".');
+    assertManifestAdapter(true === backendFederation.strictEffectApproach, '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');
+}
+function validateLoadedBackendFederationContract(loaded, manifest, remote) {
+    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);
+    assertConsistentValue(manifestUnitId, stringValue(compatibility.unitId), 'deliveryUnit.unitId vs expose compatibility.unitId');
+    assertConsistentValue(manifestBuildMarker, stringValue(compatibility.build), 'deliveryUnit.buildMarker vs expose compatibility.build');
+}
+function classifyLoadError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes('strictEffectApproach') || message.includes('runtimeFramework')) return 'strict_effect_required';
+    return 'remote_unavailable';
+}
+export { classifyLoadError, validateLoadedBackendFederationContract, validation_validateBackendFederationManifest as validateBackendFederationManifest };

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

@@ -0,0 +1,2 @@
+import "node:module";
+export * from "./backend-federation-manifest/index.mjs";

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

@@ -0,0 +1,5 @@
+import "node:module";
+export { BACKEND_FEDERATION_CONTRACT_VERSION, BACKEND_FEDERATION_EFFECT_EXPOSE, BACKEND_FEDERATION_MANIFEST_FILE, BACKEND_FEDERATION_NODE_ADAPTER_VERSION } from "@modern-js/utils/universal";
+export { loadBackendFederatedEffectApi } from "./backend-federation/load.mjs";
+export { createBackendFederationLoadEntryPlugin } from "./backend-federation/plugin.mjs";
+export { createBackendFederationRuntime } from "./backend-federation/runtime.mjs";

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/batch-handler.mjs

@@ -0,0 +1,124 @@
+import "node:module";
+import { DEFAULT_DATA_BATCH_HEADER, DEFAULT_DATA_ENVELOPE_HEADER, decodeRequestEnvelopeHeader } from "../../data-platform/index.mjs";
+import { createBatchValidationResponse, isBatchRequestPayload, isPlainObject, mapWithConcurrency, normalizeBatchAllowedMethods, normalizeBatchPath, normalizeItemMethod, promiseWithTimeout, toBatchItemError, toHeaderRecord, toTextLength } from "./batch.mjs";
+import { getMountedPrefixFromContext, removeMountedPrefixFromBatchPath } from "./routing.mjs";
+function createDataPlatformBatchRequestHandler(options) {
+    const dataPlatformBatchOptions = options.dataPlatform?.batch;
+    const batchEnabled = dataPlatformBatchOptions?.enabled !== false;
+    const batchPath = normalizeBatchPath(dataPlatformBatchOptions?.endpoint);
+    const batchMaxSize = Math.max(1, dataPlatformBatchOptions?.maxBatchSize ?? 16);
+    const batchMaxBytes = Math.max(1024, dataPlatformBatchOptions?.maxBatchBytes ?? 65536);
+    const batchConcurrency = Math.max(1, dataPlatformBatchOptions?.maxConcurrency ?? 4);
+    const batchItemTimeoutMs = Math.max(0, dataPlatformBatchOptions?.requestTimeoutMs ?? 10000);
+    const batchAllowedMethods = normalizeBatchAllowedMethods(dataPlatformBatchOptions?.allowedMethods);
+    const envelopeHeader = options.dataPlatform?.envelopeHeader || DEFAULT_DATA_ENVELOPE_HEADER;
+    const normalizedEnvelopeHeader = envelopeHeader.toLowerCase();
+    const handle = async (request, context)=>{
+        const mountedPrefix = getMountedPrefixFromContext(request, context);
+        const method = normalizeItemMethod(request.method);
+        if ('POST' !== method) return createBatchValidationResponse('Batch endpoint only supports POST requests', 405);
+        const contentType = request.headers.get('content-type') || '';
+        if (!contentType.includes('application/json')) return createBatchValidationResponse('Batch endpoint requires application/json content-type', 415);
+        const payloadText = await request.text();
+        if (toTextLength(payloadText) > batchMaxBytes) return createBatchValidationResponse(`Batch payload exceeds max size (${String(batchMaxBytes)} bytes)`, 413);
+        let payload;
+        try {
+            payload = JSON.parse(payloadText);
+        } catch  {
+            return createBatchValidationResponse('Invalid batch payload JSON');
+        }
+        if (!isBatchRequestPayload(payload)) return createBatchValidationResponse('Invalid batch payload shape');
+        if (0 === payload.items.length) return createBatchValidationResponse('Batch payload items cannot be empty');
+        if (payload.items.length > batchMaxSize) return createBatchValidationResponse(`Batch item count exceeds max size (${String(batchMaxSize)})`, 413);
+        const responseItems = await mapWithConcurrency(payload.items, batchConcurrency, async (rawItem, index)=>{
+            const fallbackId = `item_${String(index)}`;
+            const itemId = isPlainObject(rawItem) && 'string' == typeof rawItem.id ? rawItem.id : fallbackId;
+            if (!isPlainObject(rawItem)) return toBatchItemError(itemId, 400, 'Invalid batch item; expected object');
+            if ('string' != typeof rawItem.path || 0 === rawItem.path.length) return toBatchItemError(itemId, 400, 'Invalid batch item path');
+            if (!rawItem.path.startsWith('/')) return toBatchItemError(itemId, 400, 'Batch item path must start with "/"');
+            const normalizedItemPath = removeMountedPrefixFromBatchPath(rawItem.path, mountedPrefix);
+            const itemPathname = normalizedItemPath.split('?')[0] || normalizedItemPath;
+            if (itemPathname === batchPath || itemPathname.startsWith(`${batchPath}/`)) return toBatchItemError(itemId, 400, 'Batch item path cannot target batch endpoint');
+            const itemMethod = normalizeItemMethod('string' == typeof rawItem.method ? rawItem.method : void 0);
+            if (!batchAllowedMethods.has(itemMethod)) return toBatchItemError(itemId, 405, `Batch item method ${itemMethod} is not allowed`);
+            if (void 0 !== rawItem.body && null !== rawItem.body && 'string' != typeof rawItem.body) return toBatchItemError(itemId, 400, 'Batch item body must be a string when provided');
+            if (('GET' === itemMethod || 'HEAD' === itemMethod) && 'string' == typeof rawItem.body) return toBatchItemError(itemId, 400, `${itemMethod} batch item cannot include body`);
+            const normalizedHeaders = {};
+            if (void 0 !== rawItem.headers) {
+                if (!isPlainObject(rawItem.headers)) return toBatchItemError(itemId, 400, 'Batch item headers must be an object');
+                for (const [key, value] of Object.entries(rawItem.headers)){
+                    if ('string' != typeof value) return toBatchItemError(itemId, 400, `Invalid header "${key}" for batch item`);
+                    normalizedHeaders[key.toLowerCase()] = value;
+                }
+            }
+            if (!normalizedHeaders.traceparent) {
+                const encodedEnvelope = normalizedHeaders[normalizedEnvelopeHeader];
+                if ('string' == typeof encodedEnvelope) {
+                    const envelope = decodeRequestEnvelopeHeader(encodedEnvelope);
+                    if (envelope?.traceparent) normalizedHeaders.traceparent = envelope.traceparent;
+                }
+            }
+            if (!normalizedHeaders.traceparent) {
+                const requestTraceparent = request.headers.get('traceparent');
+                if (requestTraceparent) normalizedHeaders.traceparent = requestTraceparent;
+            }
+            const targetUrl = new URL(normalizedItemPath, request.url);
+            const requestHeaders = new Headers(normalizedHeaders);
+            const body = 'GET' === itemMethod || 'HEAD' === itemMethod ? void 0 : rawItem.body;
+            if (void 0 === body) requestHeaders.delete('content-type');
+            const itemRequest = new Request(targetUrl.toString(), {
+                method: itemMethod,
+                headers: requestHeaders,
+                body
+            });
+            try {
+                const itemResponse = await promiseWithTimeout(options.handleItem(itemRequest, context), batchItemTimeoutMs);
+                if (!(itemResponse instanceof Response)) return toBatchItemError(itemId, 500, 'Invalid response returned by batch item handler');
+                const bodyText = await itemResponse.text();
+                const responseItem = {
+                    id: itemId,
+                    status: itemResponse.status,
+                    headers: toHeaderRecord(itemResponse.headers),
+                    ...bodyText ? {
+                        body: bodyText
+                    } : {}
+                };
+                return responseItem;
+            } catch (error) {
+                if (error instanceof Response) {
+                    const bodyText = await error.text();
+                    return {
+                        id: itemId,
+                        status: error.status,
+                        headers: toHeaderRecord(error.headers),
+                        ...bodyText ? {
+                            body: bodyText
+                        } : {}
+                    };
+                }
+                const message = error instanceof Error ? error.message : String(error);
+                return toBatchItemError(itemId, 500, message);
+            }
+        });
+        const responsePayload = {
+            protocolVersion: 1,
+            batchId: payload.batchId,
+            receivedAt: Date.now(),
+            items: responseItems
+        };
+        return new Response(JSON.stringify(responsePayload), {
+            status: 200,
+            headers: {
+                'content-type': 'application/json; charset=utf-8',
+                [DEFAULT_DATA_BATCH_HEADER]: '1',
+                'x-modernjs-data-batch-id': payload.batchId
+            }
+        });
+    };
+    return {
+        enabled: batchEnabled,
+        path: batchPath,
+        handle
+    };
+}
+export { createDataPlatformBatchRequestHandler };