@bleedingdev/modern-js-plugin-bff 3.2.0-ultramodern.12 → 3.2.0-ultramodern.121

package/dist/cjs/utils/pluginGenerator.js

@@ -10,11 +10,15 @@ var __webpack_require__ = {};
     };
 })();
 (()=>{
-    __webpack_require__.d = (exports1, definition)=>{
-        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
-            enumerable: true,
-            get: definition[key]
-        });
+    __webpack_require__.d = (exports1, getters, values)=>{
+        var define = (defs, kind)=>{
+            for(var key in defs)if (__webpack_require__.o(defs, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+                enumerable: true,
+                [kind]: defs[key]
+            });
+        };
+        define(getters, "get");
+        define(values, "value");
     };
 })();
 (()=>{

package/dist/cjs/utils/runtimeGenerator.js

@@ -10,11 +10,15 @@ var __webpack_require__ = {};
     };
 })();
 (()=>{
-    __webpack_require__.d = (exports1, definition)=>{
-        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
-            enumerable: true,
-            get: definition[key]
-        });
+    __webpack_require__.d = (exports1, getters, values)=>{
+        var define = (defs, kind)=>{
+            for(var key in defs)if (__webpack_require__.o(defs, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+                enumerable: true,
+                [kind]: defs[key]
+            });
+        };
+        define(getters, "get");
+        define(values, "value");
     };
 })();
 (()=>{

package/dist/esm/loader.mjs

@@ -2,6 +2,24 @@ import { generateClient } from "@modern-js/bff-core";
 import { logger } from "@modern-js/utils";
 import path from "path";
 import { generateEffectClientCode, resolveEffectEntryFile } from "./utils/effectClientGenerator.mjs";
+async function transformEffectRuntimeSource(source, filename) {
+    const swc = await import("@swc/core");
+    const result = await swc.transform(source, {
+        filename,
+        sourceMaps: false,
+        jsc: {
+            parser: {
+                syntax: "typescript",
+                tsx: filename.endsWith('.tsx') || filename.endsWith('.jsx')
+            },
+            target: 'es2022'
+        },
+        module: {
+            type: 'es6'
+        }
+    });
+    return result.code;
+}
 async function loader(source) {
     this.cacheable();
     const { resourcePath } = this;
@@ -13,6 +31,11 @@ async function loader(source) {
         apiDir: draftOptions.apiDir,
         effectEntry: draftOptions.effectEntry
     });
+    if ('effect' === draftOptions.bffRuntimeFramework && effectEntryFile && path.resolve(effectEntryFile) === path.resolve(resourcePath) && this.resourceQuery.includes('modern-bff-runtime')) {
+        const code = await transformEffectRuntimeSource(source, resourcePath);
+        callback(void 0, code);
+        return;
+    }
     if ('effect' === draftOptions.bffRuntimeFramework && effectEntryFile && path.resolve(effectEntryFile) === path.resolve(resourcePath)) {
         const code = await generateEffectClientCode({
             appDir: draftOptions.appDir,

package/dist/esm/runtime/data-platform/index.mjs

@@ -1,7 +1,29 @@
+import { parseTraceparent } from "@modern-js/create-request";
+import { trace as api_trace } from "@opentelemetry/api";
+const DATA_BATCH_TRANSPORT_OTEL_EVENT = 'modernjs.data.batch';
+function createDataBatchTransportTelemetryAttributes(event) {
+    return {
+        'modernjs.data.batch.type': event.type,
+        'modernjs.data.batch.endpoint': event.endpoint,
+        'modernjs.data.batch.degraded': 'fallback' === event.type || 'disable' === event.type,
+        ...event.batchId ? {
+            'modernjs.data.batch.id': event.batchId
+        } : {},
+        ...'number' == typeof event.size ? {
+            'modernjs.data.batch.size': event.size
+        } : {},
+        ...event.reason ? {
+            'modernjs.data.batch.reason': event.reason
+        } : {}
+    };
+}
+function emitDataBatchTransportEvent(onEvent, event) {
+    onEvent?.(event);
+    api_trace.getActiveSpan()?.addEvent(DATA_BATCH_TRANSPORT_OTEL_EVENT, createDataBatchTransportTelemetryAttributes(event));
+}
 const DEFAULT_DATA_ENVELOPE_HEADER = 'x-modernjs-data-envelope';
 const DEFAULT_DATA_BATCH_ENDPOINT = '/_data/batch';
 const DEFAULT_DATA_BATCH_HEADER = 'x-modernjs-data-batch';
-const TRACEPARENT_REGEX = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/i;
 function isPlainObject(value) {
     if ('object' != typeof value || null === value || Array.isArray(value)) return false;
     const proto = Object.getPrototypeOf(value);
@@ -98,18 +120,7 @@ function isValidHex(value, length) {
     return value.length === length && /^[0-9a-f]+$/.test(value);
 }
 function parseTraceparentHeader(header) {
-    const match = header.trim().match(TRACEPARENT_REGEX);
-    if (!match) return null;
-    const traceId = match[1].toLowerCase();
-    const spanId = match[2].toLowerCase();
-    const flags = match[3].toLowerCase();
-    if (isAllZeroHex(traceId) || isAllZeroHex(spanId)) return null;
-    const sampled = (0x1 & Number.parseInt(flags, 16)) === 1;
-    return {
-        traceId,
-        spanId,
-        sampled
-    };
+    return parseTraceparent(header) ?? null;
 }
 function formatTraceparentHeader(trace) {
     const traceId = trace.traceId.toLowerCase();
@@ -415,7 +426,7 @@ function createDataBatchTransport(options = {}) {
         bucket.items = [];
         bucket.bytes = 0;
         if (1 === items.length || disabledEndpoints.has(endpoint)) {
-            onEvent?.({
+            emitDataBatchTransportEvent(onEvent, {
                 type: disabledEndpoints.has(endpoint) ? 'fallback' : 'flush',
                 endpoint,
                 size: items.length,
@@ -432,7 +443,7 @@ function createDataBatchTransport(options = {}) {
             sentAt: Date.now(),
             items: items.map((item)=>item.item)
         };
-        onEvent?.({
+        emitDataBatchTransportEvent(onEvent, {
             type: 'flush',
             endpoint,
             batchId,
@@ -459,7 +470,7 @@ function createDataBatchTransport(options = {}) {
                 requestInit.signal = controller.signal;
                 timeoutHandle = setTimeout(()=>{
                     controller.abort();
-                    onEvent?.({
+                    emitDataBatchTransportEvent(onEvent, {
                         type: 'fallback',
                         endpoint,
                         batchId,
@@ -472,13 +483,13 @@ function createDataBatchTransport(options = {}) {
             if (!response.ok) {
                 if (404 === response.status || 405 === response.status) {
                     disabledEndpoints.add(endpoint);
-                    onEvent?.({
+                    emitDataBatchTransportEvent(onEvent, {
                         type: 'disable',
                         endpoint,
                         batchId,
                         reason: `batch-endpoint-unavailable-${String(response.status)}`
                     });
-                } else onEvent?.({
+                } else emitDataBatchTransportEvent(onEvent, {
                     type: 'fallback',
                     endpoint,
                     batchId,
@@ -491,7 +502,7 @@ function createDataBatchTransport(options = {}) {
             }
             const result = await response.json();
             if (!isBatchResponsePayload(result)) {
-                onEvent?.({
+                emitDataBatchTransportEvent(onEvent, {
                     type: 'fallback',
                     endpoint,
                     batchId,
@@ -514,7 +525,7 @@ function createDataBatchTransport(options = {}) {
                 return parseResponseLikeCreateRequest(reconstructedResponse);
             });
         } catch (error) {
-            onEvent?.({
+            emitDataBatchTransportEvent(onEvent, {
                 type: 'fallback',
                 endpoint,
                 batchId,
@@ -581,7 +592,7 @@ function createDataBatchTransport(options = {}) {
             };
             bucket.items.push(queued);
             bucket.bytes += size;
-            onEvent?.({
+            emitDataBatchTransportEvent(onEvent, {
                 type: 'enqueue',
                 endpoint,
                 size: bucket.items.length
@@ -596,4 +607,4 @@ function createDataBatchTransport(options = {}) {
         return promise;
     };
 }
-export { DEFAULT_DATA_BATCH_ENDPOINT, DEFAULT_DATA_BATCH_HEADER, DEFAULT_DATA_ENVELOPE_HEADER, buildQueryKey, buildScopeKey, createDataBatchTransport, createHydrationEnvelope, createInvalidationEvent, createOperationId, createRequestEnvelope, decodeRequestEnvelopeHeader, deriveChildTraceContext, encodeRequestEnvelopeHeader, formatTraceparentHeader, normalizeOrigin, parseTraceparentHeader, shouldApplyInvalidation, stableStringify, validateHydrationEnvelope, validateRequestEnvelope, validateSelectionPlan };
+export { DATA_BATCH_TRANSPORT_OTEL_EVENT, DEFAULT_DATA_BATCH_ENDPOINT, DEFAULT_DATA_BATCH_HEADER, DEFAULT_DATA_ENVELOPE_HEADER, buildQueryKey, buildScopeKey, createDataBatchTransport, createDataBatchTransportTelemetryAttributes, createHydrationEnvelope, createInvalidationEvent, createOperationId, createRequestEnvelope, decodeRequestEnvelopeHeader, deriveChildTraceContext, emitDataBatchTransportEvent, encodeRequestEnvelopeHeader, formatTraceparentHeader, normalizeOrigin, parseTraceparentHeader, shouldApplyInvalidation, stableStringify, validateHydrationEnvelope, validateRequestEnvelope, validateSelectionPlan };

package/dist/esm/runtime/effect/adapter.mjs

@@ -1,8 +1,12 @@
+import { ApiRouter } from "@modern-js/bff-core";
 import { API_DIR, compatibleRequire, findExists, fs, isProd, logger } from "@modern-js/utils";
 import { HttpApi } from "effect/unstable/httpapi";
 import path from "path";
-import { runWithEffectContext } from "./context.mjs";
-import { createHttpApiHandler } from "./index.mjs";
+import { checkCrossProjectPolicyForRequest, resolveAdapterCrossProjectPolicy } from "../../utils/crossProjectServerPolicy.mjs";
+import { createSafeFailureResponse } from "../safe-failure.mjs";
+import { createEffectOperationContext, runWithEffectContext } from "./context.mjs";
+import { collectEffectEndpoints, extractHttpApiFromModule, toOperationContractSources } from "./endpoint-contracts.mjs";
+import { resolveEffectBffModuleHandler } from "./module.mjs";
 const before = [
     'custom-server-hook',
     'custom-server-middleware',
@@ -35,24 +39,9 @@ function createRequestForMountedPrefix(req, prefix) {
     url.pathname = nextPath;
     return new Request(url, req);
 }
-function isRequestHandler(value) {
-    return 'function' == typeof value;
-}
 function maybeResponse(value) {
     return value instanceof Response;
 }
-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 isHttpApiWithProps(value) {
-    return HttpApi.isHttpApi(value) && isRecord(value) && 'string' == typeof value.identifier && isRecord(value.groups);
-}
-function isEffectApiDefinition(module) {
-    return isHttpApiWithProps(module.api) && void 0 !== module.layer;
-}
 class EffectAdapter {
     resolveEntryFile() {
         const { appDirectory, apiDirectory } = this.api.getServerContext();
@@ -62,71 +51,77 @@ class EffectAdapter {
         const entryWithoutExt = configuredEntry ? path.isAbsolute(configuredEntry) ? configuredEntry : path.resolve(appDirectory || process.cwd(), configuredEntry) : defaultEntry;
         return findExists(JS_OR_TS_EXTS.map((ext)=>`${entryWithoutExt}${ext}`));
     }
-    async loadEffectHandlerFromModule(mod) {
-        let normalizedModule = mod;
-        const mergeRuntimeExports = (value)=>{
-            if (!isRecord(value) || !includesRuntimeExports(value)) return;
-            normalizedModule = {
-                ...normalizedModule,
-                ...value
-            };
-        };
-        if (isRequestHandler(normalizedModule.handler)) return {
-            handler: normalizedModule.handler
-        };
-        const entry = normalizedModule.default;
-        if (isRequestHandler(entry)) return {
-            handler: entry
-        };
-        if ('function' == typeof entry && 0 === entry.length) {
-            const out = await entry();
-            if (isRequestHandler(out)) return {
-                handler: out
-            };
-            mergeRuntimeExports(out);
-        }
-        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)) return {
-            handler: normalizedModule.handler
-        };
-        if ('function' == typeof normalizedModule.createHandler) {
-            const webHandler = normalizedModule.createHandler({
-                openapi: this.api.getServerConfig()?.bff?.effect?.openapi,
-                dataPlatform: this.api.getServerConfig()?.bff?.effect?.dataPlatform
+    isApiRequestPath(requestPath, prefix, enableHandleWeb) {
+        if (!enableHandleWeb) return true;
+        const normalized = normalizePrefix(prefix);
+        if (!normalized) return true;
+        return requestPath === normalized || requestPath.startsWith(`${normalized}/`);
+    }
+    async collectLambdaContractSources() {
+        try {
+            const serverContext = this.api.getServerContext();
+            const appDir = serverContext.distDirectory || serverContext.appDirectory;
+            if (!appDir) return [];
+            const apiDir = 'string' == typeof serverContext.apiDirectory ? serverContext.apiDirectory : path.resolve(appDir, API_DIR);
+            const lambdaDir = 'string' == typeof serverContext.lambdaDirectory ? serverContext.lambdaDirectory : path.join(apiDir, 'lambda');
+            if (!await fs.pathExists(lambdaDir)) return [];
+            const apiRouter = new ApiRouter({
+                appDir,
+                apiDir,
+                lambdaDir,
+                prefix: this.prefix,
+                httpMethodDecider: this.api.getServerConfig()?.bff?.httpMethodDecider
             });
-            return {
-                handler: async (request)=>webHandler.handler(request),
-                dispose: async ()=>{
-                    await webHandler.dispose();
-                }
-            };
+            const handlerInfos = await apiRouter.getApiHandlers();
+            return handlerInfos.map((info)=>({
+                    name: info.name,
+                    httpMethod: info.httpMethod,
+                    routePath: info.routePath,
+                    filename: info.filename,
+                    handler: info.handler
+                }));
+        } catch (error) {
+            logger.warn(`[BFF][Effect] Failed to derive lambda operation contracts for the cross-project policy: ${String(error)}`);
+            return [];
         }
-        if (isEffectApiDefinition(normalizedModule)) {
-            logger.warn('[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,
-                openapi: this.api.getServerConfig()?.bff?.effect?.openapi,
-                dataPlatform: this.api.getServerConfig()?.bff?.effect?.dataPlatform
-            });
-            return {
-                handler: async (request)=>webHandler.handler(request),
-                dispose: async ()=>{
-                    await webHandler.dispose();
-                }
-            };
+    }
+    async refreshCrossProjectPolicy(mod) {
+        let contractSources = [];
+        if (mod) try {
+            const api = await extractHttpApiFromModule(mod, HttpApi.isHttpApi);
+            if (api) {
+                const reflect = (apiValue, handlers)=>HttpApi.reflect(apiValue, {
+                        onGroup: handlers.onGroup ?? (()=>{}),
+                        onEndpoint: handlers.onEndpoint
+                    });
+                contractSources = toOperationContractSources(collectEffectEndpoints(reflect, api, this.prefix));
+            }
+        } catch (error) {
+            logger.warn(`[BFF][Effect] Failed to reflect HttpApi endpoints for the cross-project policy: ${String(error)}`);
         }
-        return null;
+        let policy = resolveAdapterCrossProjectPolicy(this.api, contractSources);
+        if (policy?.enabled) {
+            const lambdaSources = await this.collectLambdaContractSources();
+            if (lambdaSources.length > 0) {
+                contractSources = [
+                    ...contractSources,
+                    ...lambdaSources
+                ];
+                policy = resolveAdapterCrossProjectPolicy(this.api, contractSources);
+            }
+        }
+        this.crossProjectPolicy = policy;
+        if (this.crossProjectPolicy?.enabled && 0 === contractSources.length) logger.warn('[BFF][Effect] Cross-project policy is enabled but no HttpApi endpoints could be reflected; operation-contract matching is disabled for this server (envelope and operation-context checks still apply).');
+    }
+    async loadEffectHandlerFromModule(mod) {
+        return resolveEffectBffModuleHandler(mod, {
+            openapi: this.api.getServerConfig()?.bff?.effect?.openapi,
+            dataPlatform: this.api.getServerConfig()?.bff?.effect?.dataPlatform,
+            validateRequest: (request)=>checkCrossProjectPolicyForRequest(request, this.crossProjectPolicy),
+            onWarning: (message)=>{
+                logger.warn(message);
+            }
+        });
     }
     async reloadHandler() {
         if (!this.isEffect) return;
@@ -152,6 +147,7 @@ class EffectAdapter {
             this.handler = null;
             return;
         }
+        await this.refreshCrossProjectPolicy(mod);
         const loaded = await this.loadEffectHandlerFromModule(mod);
         if (!loaded) {
             logger.warn(`[BFF][Effect] Invalid Effect entry module: ${entryFile}. Export { api, layer } or handler.`);
@@ -160,6 +156,7 @@ class EffectAdapter {
         }
         this.handler = loaded.handler;
         this.dispose = loaded.dispose || null;
+        this.policyEnforcedInMiddleware = !loaded.appliesRequestValidator;
     }
     async disposeCurrentHandler() {
         if (!this.dispose) return;
@@ -183,15 +180,7 @@ class EffectAdapter {
         } catch (configError) {
             logger.error(`Error in serverConfig.onError handler: ${configError}`);
         }
-        const status = 'object' == typeof error && null !== error && 'status' in error && 'number' == typeof error.status ? error.status : 500;
-        return new Response(JSON.stringify({
-            message: error instanceof Error ? error.message : '[BFF] Internal Server Error'
-        }), {
-            status,
-            headers: {
-                'content-type': 'application/json; charset=utf-8'
-            }
-        });
+        return createSafeFailureResponse(error);
     }
     ensureJsonContext(c) {
         const maybeJsonContext = c;
@@ -218,6 +207,8 @@ class EffectAdapter {
         this.effectMiddleware = null;
         this.handler = null;
         this.dispose = null;
+        this.prefix = '/api';
+        this.policyEnforcedInMiddleware = false;
         this.registerMiddleware = async (options)=>{
             const { prefix, enableHandleWeb } = options;
             const { bffRuntimeFramework, middlewares: globalMiddlewares } = this.api.getServerContext();
@@ -225,6 +216,7 @@ class EffectAdapter {
                 this.isEffect = false;
                 return;
             }
+            this.prefix = prefix || this.prefix;
             await this.reloadHandler();
             this.effectMiddleware = {
                 name: 'effect-bff-handler',
@@ -237,6 +229,10 @@ class EffectAdapter {
                         if (enableHandleWeb) return void await next();
                         return this.handleRuntimeError(new Error('[BFF][Effect] Missing Effect entry. Define api/effect/index or configure bff.effect.entry.'), c);
                     }
+                    if (this.crossProjectPolicy?.enabled && this.policyEnforcedInMiddleware && this.isApiRequestPath(c.req.path, prefix, enableHandleWeb)) {
+                        const denial = checkCrossProjectPolicyForRequest(c.req.raw, this.crossProjectPolicy);
+                        if (denial) return denial;
+                    }
                     let response;
                     try {
                         const effectRequest = createRequestForMountedPrefix(c.req.raw, prefix);
@@ -244,7 +240,13 @@ class EffectAdapter {
                             request: effectRequest,
                             env: c.env,
                             path: c.req.path,
-                            method: c.req.method
+                            method: c.req.method,
+                            operationContext: createEffectOperationContext({
+                                request: effectRequest,
+                                env: c.env,
+                                path: c.req.path,
+                                method: c.req.method
+                            })
                         };
                         response = await runWithEffectContext(effectContext, ()=>this.handler.length > 1 ? this.handler(effectRequest, effectContext) : this.handler(effectRequest));
                     } catch (error) {

package/dist/esm/runtime/effect/context.mjs

@@ -8,4 +8,6 @@ const useEffectContext = ()=>{
     if (!context) throw new Error("Can't call useEffectContext out of Effect runtime scope");
     return context;
 };
-export { runWithEffectContext, useEffectContext };
+const useOperationContext = ()=>useEffectContext().operationContext;
+export { createEffectOperationContext } from "./operation-context.mjs";
+export { runWithEffectContext, useEffectContext, useOperationContext };

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

@@ -0,0 +1,83 @@
+import { createSafeFailureResponse } from "../safe-failure.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
+    });
+    const effectRequest = createRequestForMountedPrefix(request, options.prefix);
+    const effectContext = createEdgeEffectContext(request, effectRequest, options);
+    try {
+        const response = handler.length > 1 ? await handler(effectRequest, effectContext) : await 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);
+    }
+}
+async function createEffectBffEdgeHandler(options) {
+    const loaded = await resolveEffectBffModuleHandler(options.module, {
+        openapi: options.openapi,
+        dataPlatform: options.dataPlatform,
+        onWarning: options.onWarning
+    });
+    if (!loaded) throw new Error('[BFF][Effect] Invalid Effect edge module. Export { api, layer }, createHandler, or handler.');
+    return {
+        handler: (request, dispatchOptions = {})=>dispatchEffectBffRequest(loaded.handler, request, {
+                ...dispatchOptions,
+                prefix: options.prefix,
+                onError: options.onError
+            }),
+        dispose: async ()=>{
+            await loaded.dispose?.();
+        }
+    };
+}
+export { createEffectBffEdgeHandler, createEffectOperationContext, dispatchEffectBffRequest };

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

@@ -0,0 +1,68 @@
+import { createOperationContractHash } from "@modern-js/bff-core";
+function ensureLeadingSlash(pathname) {
+    return pathname.startsWith('/') ? pathname : `/${pathname}`;
+}
+function normalizeEffectPrefix(prefix) {
+    if ('/' === prefix) return '';
+    return ensureLeadingSlash(prefix || '/api');
+}
+function getEffectRoutePath(prefix, endpointPath) {
+    const normalizedPrefix = normalizeEffectPrefix(prefix);
+    const normalizedEndpointPath = ensureLeadingSlash(endpointPath);
+    const finalEndpointPath = '/' === normalizedEndpointPath ? '' : endpointPath;
+    if (!normalizedPrefix && !finalEndpointPath) return '/';
+    return `${normalizedPrefix}${finalEndpointPath || ''}`;
+}
+function resolveEffectApiId(api) {
+    const fallback = 'EffectHttpApi';
+    if ('identifier' in api && 'string' == typeof api.identifier && api.identifier) return api.identifier;
+    return fallback;
+}
+function collectEffectEndpoints(reflect, api, prefix) {
+    const endpoints = [];
+    const apiId = resolveEffectApiId(api);
+    reflect(api, {
+        onGroup: ()=>{},
+        onEndpoint: ({ group, endpoint })=>{
+            endpoints.push({
+                apiId,
+                groupName: String(group.identifier),
+                endpointName: String(endpoint.name),
+                method: String(endpoint.method).toUpperCase(),
+                routePath: getEffectRoutePath(prefix, String(endpoint.path))
+            });
+        }
+    });
+    return endpoints.sort((a, b)=>{
+        if (a.groupName === b.groupName) return a.endpointName.localeCompare(b.endpointName);
+        return a.groupName.localeCompare(b.groupName);
+    });
+}
+function toOperationContractSources(endpoints) {
+    return endpoints.map(createEffectOperationContractSource);
+}
+function createEffectOperationContractSource(endpoint) {
+    return {
+        name: endpoint.endpointName,
+        httpMethod: endpoint.method,
+        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;
+}
+function createEffectEndpointContractHash(endpoint, requestId) {
+    return createOperationContractHash(createEffectOperationContractSource(endpoint), requestId);
+}
+export { collectEffectEndpoints, createEffectEndpointContractHash, createEffectOperationContractSource, ensureLeadingSlash, extractHttpApiFromModule, getEffectRoutePath, normalizeEffectPrefix, resolveEffectApiId, toOperationContractSources };