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

package/dist/types/runtime/data-platform/index.d.ts

@@ -93,6 +93,7 @@ export interface DataBatchTransportEvent {
     size?: number;
     reason?: string;
 }
+export type DataBatchTransportTelemetryAttributes = Record<string, string | number | boolean>;
 export interface DataBatchTransportOptions {
     endpoint?: string;
     fetch?: (input: DataTransportRequestInfo, init?: RequestInit) => Promise<Response>;
@@ -103,6 +104,9 @@ export interface DataBatchTransportOptions {
     allowedMethods?: string[];
     onEvent?: (event: DataBatchTransportEvent) => void;
 }
+export declare const DATA_BATCH_TRANSPORT_OTEL_EVENT = "modernjs.data.batch";
+export declare function createDataBatchTransportTelemetryAttributes(event: DataBatchTransportEvent): DataBatchTransportTelemetryAttributes;
+export declare function emitDataBatchTransportEvent(onEvent: ((event: DataBatchTransportEvent) => void) | undefined, event: DataBatchTransportEvent): void;
 export interface SelectionPlanValidationOptions {
     maxDepth?: number;
     maxFields?: number;

package/dist/types/runtime/effect/adapter.d.ts

@@ -1,4 +1,5 @@
 import type { ServerMiddleware, ServerPluginAPI } from '@modern-js/server-core';
+import { type ResolvedCrossProjectPolicy } from '../../utils/crossProjectServerPolicy';
 interface MiddlewareOptions {
     prefix: string;
     enableHandleWeb?: boolean;
@@ -7,12 +8,36 @@ export declare class EffectAdapter {
     api: ServerPluginAPI;
     isEffect: boolean;
     effectMiddleware: ServerMiddleware | null;
+    crossProjectPolicy: ResolvedCrossProjectPolicy | undefined;
     private handler;
     private dispose;
+    private prefix;
+    /**
+     * True when the loaded handler does NOT run the policy seam internally
+     * (plain `handler` exports); the adapter middleware enforces it instead.
+     */
+    private policyEnforcedInMiddleware;
     constructor(api: ServerPluginAPI);
     registerMiddleware: (options: MiddlewareOptions) => Promise<void>;
     onApiHandlersUpdated: () => Promise<void>;
     private resolveEntryFile;
+    private isApiRequestPath;
+    /**
+     * Contract sources for the lambda-lane handlers hosted alongside the
+     * effect entry. Cross-project SDKs generate per-operation contracts for
+     * `api/lambda` handlers with the exact same `ApiRouter` derivation used
+     * here, so the server-side expected-contract map must include them —
+     * otherwise every lambda-lane operation of a hosted producer SDK would be
+     * denied as `unknown_operation_contract`.
+     */
+    private collectLambdaContractSources;
+    /**
+     * Resolves the cross-project policy from the reflected HttpApi endpoints
+     * (plus any hosted lambda-lane handlers) so the expected operation
+     * contracts match the hashes the client generators stamp into generated
+     * SDKs.
+     */
+    private refreshCrossProjectPolicy;
     private loadEffectHandlerFromModule;
     private reloadHandler;
     private disposeCurrentHandler;

package/dist/types/runtime/effect/context.d.ts

@@ -1,8 +1,5 @@
-export type EffectContext = {
-    request: Request;
-    env: Record<string, unknown>;
-    path: string;
-    method: string;
-};
+import type { EffectContext } from './operation-context';
+export { type CreateEffectOperationContextOptions, createEffectOperationContext, type EffectContext, } from './operation-context';
 export declare const runWithEffectContext: <T>(context: EffectContext, cb: () => T) => T;
 export declare const useEffectContext: () => EffectContext;
+export declare const useOperationContext: () => import("@modern-js/create-request").OperationContext;

package/dist/types/runtime/effect/edge.d.ts

@@ -0,0 +1,25 @@
+import type { EffectBffOpenApiConfig, EffectDataPlatformValidationOptions } from './handler';
+import { type EffectApiModule, type EffectBffRequestHandler } from './module';
+import { type EffectContext } from './operation-context';
+export * from './handler';
+export { type CreateEffectOperationContextOptions, createEffectOperationContext, type EffectContext, } from './operation-context';
+export type EffectBffEdgeDispatchOptions = {
+    prefix?: string;
+    env?: Record<string, unknown>;
+    path?: string;
+    method?: string;
+    onError?: (error: unknown, context: EffectContext) => Promise<Response> | Response;
+};
+export type EffectBffEdgeHandlerOptions = {
+    module: EffectApiModule;
+    prefix?: string;
+    openapi?: EffectBffOpenApiConfig;
+    dataPlatform?: EffectDataPlatformValidationOptions;
+    onError?: (error: unknown, context: EffectContext) => Promise<Response> | Response;
+    onWarning?: (message: string) => void;
+};
+export declare function dispatchEffectBffRequest(handler: EffectBffRequestHandler, request: Request, options?: EffectBffEdgeDispatchOptions): Promise<Response>;
+export declare function createEffectBffEdgeHandler(options: EffectBffEdgeHandlerOptions): Promise<{
+    handler: (request: Request, dispatchOptions?: Omit<EffectBffEdgeDispatchOptions, 'prefix' | 'onError'>) => Promise<Response>;
+    dispose: () => Promise<void>;
+}>;

package/dist/types/runtime/effect/endpoint-contracts.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared Effect HttpApi endpoint reflection used by BOTH sides of the
+ * cross-project contract:
+ *
+ * - the client generator (`utils/effectClientGenerator`) stamps each
+ *   generated operation with a per-endpoint contract hash;
+ * - the effect server adapter derives the expected operation-contract map
+ *   for the cross-project policy from the same endpoints.
+ *
+ * Keeping route-path normalization and the endpoint -> contract mapping in
+ * one module is what guarantees the two hashes agree.
+ */
+import { type OperationContractSource } from '@modern-js/bff-core';
+export type EffectEndpointMeta = {
+    apiId: string;
+    groupName: string;
+    endpointName: string;
+    method: string;
+    routePath: string;
+};
+export type HttpApiLike = {
+    identifier?: unknown;
+};
+export type HttpApiGroupLike = {
+    identifier?: unknown;
+};
+export type HttpApiEndpointLike = {
+    name?: unknown;
+    method?: unknown;
+    path?: unknown;
+};
+export type HttpApiReflect = (api: unknown, handlers: {
+    /** Group metadata is unused by contract collection; kept as a no-op. */
+    onGroup?: () => void;
+    onEndpoint: (input: {
+        group: HttpApiGroupLike;
+        endpoint: HttpApiEndpointLike;
+    }) => void;
+}) => void;
+export declare function ensureLeadingSlash(pathname: string): string;
+export declare function normalizeEffectPrefix(prefix: string): string;
+export declare function getEffectRoutePath(prefix: string, endpointPath: string): string;
+export declare function resolveEffectApiId(api: HttpApiLike): string;
+export declare function collectEffectEndpoints(reflect: HttpApiReflect, api: HttpApiLike, prefix: string): EffectEndpointMeta[];
+/**
+ * Maps reflected endpoints onto operation-contract sources for
+ * `buildOperationContractMap`/`resolveCrossProjectPolicy`. Effect endpoints
+ * carry no zod metadata, so the contract hash covers the endpoint identity.
+ */
+export declare function toOperationContractSources(endpoints: EffectEndpointMeta[]): OperationContractSource[];
+export declare function createEffectOperationContractSource(endpoint: EffectEndpointMeta): OperationContractSource;
+/**
+ * Extracts the HttpApi instance from a loaded effect entry module. Mirrors
+ * the module shapes accepted by `resolveEffectBffModuleHandler`:
+ * `{ api }`, `{ default: { api } }` and zero-arg default factories.
+ */
+export declare function extractHttpApiFromModule(mod: unknown, isHttpApi: (value: unknown) => boolean): Promise<HttpApiLike | null>;
+/**
+ * Per-endpoint contract hash; MUST stay in sync with the server-side
+ * contract map (it is the same bff-core hash over the same inputs).
+ */
+export declare function createEffectEndpointContractHash(endpoint: EffectEndpointMeta, requestId: string): string;

package/dist/types/runtime/effect/handler.d.ts

@@ -0,0 +1,203 @@
+import type { FileSystem, Path } from 'effect';
+import * as Context from 'effect/Context';
+import type * as EffectType from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { Etag, HttpPlatform, HttpRouter } from 'effect/unstable/http';
+import { type HttpApi, type HttpApiClient, type HttpApiGroup } from 'effect/unstable/httpapi';
+import { type Rpc, type RpcGroup } from 'effect/unstable/rpc';
+export * as Config from 'effect/Config';
+export * as Effect from 'effect/Effect';
+export * as Layer from 'effect/Layer';
+export * as Option from 'effect/Option';
+export * as Schema from 'effect/Schema';
+export * from 'effect/unstable/http';
+export { HttpTraceContext } from 'effect/unstable/http';
+export * from 'effect/unstable/httpapi';
+export { HttpApiBuilder } from 'effect/unstable/httpapi';
+export * from 'effect/unstable/rpc';
+export type EffectRuntimeRequirements = Etag.Generator | FileSystem.FileSystem | HttpPlatform.HttpPlatform | HttpRouter.HttpRouter | HttpRouter.Request<'Error', any> | HttpRouter.Request<'GlobalError', any> | HttpRouter.Request<'GlobalRequires', any> | HttpRouter.Request<'Requires', any> | Path.Path;
+export type EffectRuntimeLayer = Layer.Layer<never, never, EffectRuntimeRequirements>;
+export type EffectRpcSerialization = 'json' | 'ndjson' | 'jsonRpc' | 'ndJsonRpc' | 'msgPack';
+export type EffectRpcRuntimeLayer<TRpcs extends Rpc.Any = Rpc.Any> = Layer.Layer<Rpc.ToHandler<TRpcs> | Rpc.Middleware<TRpcs> | Rpc.ServicesServer<TRpcs>, unknown, never>;
+export type EffectRpcBffDefinition<TRpcs extends Rpc.Any = Rpc.Any, TRpcLayer extends EffectRpcRuntimeLayer<TRpcs> = EffectRpcRuntimeLayer<TRpcs>> = {
+    group: RpcGroup.RpcGroup<TRpcs>;
+    layer: TRpcLayer;
+    path?: `/${string}`;
+    serialization?: EffectRpcSerialization;
+    disableTracing?: boolean;
+    spanPrefix?: string;
+    spanAttributes?: Record<string, unknown>;
+    disableFatalDefects?: boolean;
+};
+export type EffectRpcBffHandlerOptions = Pick<EffectRpcBffDefinition, 'path' | 'serialization' | 'disableTracing' | 'spanPrefix' | 'spanAttributes' | 'disableFatalDefects'>;
+type EffectApiPromiseClient<TClient> = {
+    [GroupName in keyof TClient]: {
+        [EndpointName in keyof TClient[GroupName]]: TClient[GroupName][EndpointName] extends (...args: infer TArgs) => infer TResult ? TResult extends EffectType.Effect<unknown, unknown, unknown> ? (...args: TArgs) => Promise<Exclude<EffectType.Success<TResult>, readonly [unknown, unknown]>> : never : never;
+    };
+};
+export type EffectApiClientFromApi<TApi extends HttpApi.AnyWithProps = HttpApi.AnyWithProps> = TApi extends HttpApi.HttpApi<infer _ApiId, infer Groups> ? HttpApiClient.Client<Extract<Groups, HttpApiGroup.Any>, unknown, never> : never;
+export type EffectApiPromiseClientFromApi<TApi extends HttpApi.AnyWithProps = HttpApi.AnyWithProps> = EffectApiPromiseClient<EffectApiClientFromApi<TApi>>;
+export type EffectBffDefinition<TApi extends HttpApi.AnyWithProps = HttpApi.AnyWithProps, TLayer extends EffectRuntimeLayer = EffectRuntimeLayer, TRpcs extends Rpc.Any = Rpc.Any> = {
+    api: TApi;
+    layer: TLayer;
+    rpc?: EffectRpcBffDefinition<TRpcs>;
+    dataPlatform?: EffectDataPlatformValidationOptions;
+};
+export type EffectDataPlatformSelectionValidationOptions = {
+    maxDepth?: number;
+    maxFields?: number;
+    allowedLeafPaths?: string[];
+};
+export type EffectDataPlatformBatchOptions = {
+    /**
+     * Enable network batching endpoint for Effect HttpApi requests.
+     * Defaults to `true`.
+     */
+    enabled?: boolean;
+    /**
+     * Batch endpoint path mounted under BFF prefix.
+     * Defaults to `/_data/batch`.
+     */
+    endpoint?: `/${string}`;
+    /**
+     * Maximum request items accepted per batch call.
+     * Defaults to `16`.
+     */
+    maxBatchSize?: number;
+    /**
+     * Maximum serialized request payload size in bytes.
+     * Defaults to `65536` (64KiB).
+     */
+    maxBatchBytes?: number;
+    /**
+     * Client-side micro-batch flush window in milliseconds.
+     * Server runtime ignores this value and passes it through for codegen.
+     * Defaults to `8`.
+     */
+    flushIntervalMs?: number;
+    /**
+     * Maximum per-batch internal request concurrency.
+     * Defaults to `4`.
+     */
+    maxConcurrency?: number;
+    /**
+     * Optional timeout per internal request in milliseconds.
+     * Defaults to `10000`.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Allowed HTTP methods for internal batched dispatch.
+     * Defaults to `['GET']`.
+     */
+    allowedMethods?: string[];
+};
+export type EffectDataPlatformValidationOptions = {
+    /**
+     * Enable envelope validation for HttpApi requests.
+     * Defaults to `true`.
+     */
+    enabled?: boolean;
+    /**
+     * Require every HttpApi request to include an envelope header.
+     * Defaults to `false`.
+     */
+    requireEnvelope?: boolean;
+    /**
+     * Header name used by client/server for the serialized request envelope.
+     * Defaults to `x-modernjs-data-envelope`.
+     */
+    envelopeHeader?: string;
+    /**
+     * Optional namespace assertion for envelope validation.
+     */
+    expectedNamespace?: string;
+    /**
+     * Validate envelope origin against incoming request origin.
+     * Defaults to `true`.
+     */
+    validateOrigin?: boolean;
+    /**
+     * Require trace context inside request envelope.
+     * Defaults to `false`.
+     */
+    requireTraceContext?: boolean;
+    /**
+     * Selection plan guardrails for server-side validation.
+     */
+    selection?: EffectDataPlatformSelectionValidationOptions;
+    /**
+     * Network batching gateway configuration.
+     */
+    batch?: EffectDataPlatformBatchOptions;
+};
+/**
+ * Server-seam request validator applied to every HttpApi request — direct,
+ * batched (per item) and rpc. Returning a Response short-circuits the
+ * request; returning `null`/`undefined` lets it through. Used by the effect
+ * adapter to enforce the cross-project policy at one seam so batched items
+ * cannot bypass it.
+ */
+export type EffectRequestValidator = (request: Request) => Response | null | undefined;
+/**
+ * Brand stamped on `createHandler` factories that are guaranteed to forward
+ * `options.validateRequest` into `createHttpApiHandler` — i.e. the policy
+ * seam runs inside the produced handler, including per batched item.
+ *
+ * `defineEffectBff` brands its factory automatically. Hand-written factories
+ * are NOT assumed to honor `validateRequest` (the option is newer than the
+ * factory shape), so the effect adapter falls back to middleware enforcement
+ * for unbranded factories instead of silently skipping the policy. Custom
+ * factories that do forward `validateRequest` into `createHttpApiHandler`
+ * may opt in by setting this symbol property to `true`.
+ *
+ * Registered via `Symbol.for` so independently loaded runtime copies agree.
+ */
+export declare const EFFECT_VALIDATOR_AWARE_FACTORY: symbol;
+/**
+ * True when `factory` is branded as validator-aware (see
+ * {@link EFFECT_VALIDATOR_AWARE_FACTORY}).
+ */
+export declare function isValidatorAwareHandlerFactory(factory: unknown): boolean;
+export type EffectBffHandlerFactory<TApi extends HttpApi.AnyWithProps = HttpApi.AnyWithProps, TLayer extends EffectRuntimeLayer = EffectRuntimeLayer> = (options?: {
+    openapi?: EffectBffOpenApiConfig;
+    rpc?: Partial<EffectRpcBffHandlerOptions>;
+    dataPlatform?: Partial<EffectDataPlatformValidationOptions>;
+    validateRequest?: EffectRequestValidator;
+}) => ReturnType<typeof createHttpApiHandler>;
+export type EffectBffRuntime<TApi extends HttpApi.AnyWithProps = HttpApi.AnyWithProps, TLayer extends EffectRuntimeLayer = EffectRuntimeLayer> = {
+    createHandler: EffectBffHandlerFactory<TApi, TLayer>;
+    client: EffectApiPromiseClientFromApi<TApi>;
+};
+export type EffectBffOpenApiConfig = boolean | {
+    path?: string;
+};
+export type EffectRpcBffHandlerFactory<TRpcs extends Rpc.Any = Rpc.Any> = (options?: Partial<EffectRpcBffHandlerOptions>) => ReturnType<typeof createRpcApiHandler<TRpcs>>;
+declare function createRpcApiHandler<TRpcs extends Rpc.Any = Rpc.Any>(options: EffectRpcBffDefinition<TRpcs>): {
+    readonly handler: (request: globalThis.Request, context?: Context.Context<never> | undefined) => Promise<Response>;
+    readonly dispose: () => Promise<void>;
+};
+export declare function defineEffectBff<TApi extends HttpApi.AnyWithProps, TLayer extends EffectRuntimeLayer, TRpcs extends Rpc.Any = Rpc.Any>(definition: {
+    api: TApi;
+    layer: TLayer;
+    rpc?: EffectRpcBffDefinition<TRpcs>;
+    dataPlatform?: EffectDataPlatformValidationOptions;
+}): {
+    api: TApi;
+    layer: TLayer;
+    rpc?: EffectRpcBffDefinition<TRpcs>;
+    dataPlatform?: EffectDataPlatformValidationOptions;
+} & EffectBffRuntime<TApi, TLayer>;
+export declare function defineEffectRpcBff<TRpcs extends Rpc.Any = Rpc.Any, TLayer extends EffectRpcRuntimeLayer<TRpcs> = EffectRpcRuntimeLayer<TRpcs>>(definition: EffectRpcBffDefinition<TRpcs, TLayer>): EffectRpcBffDefinition<TRpcs, TLayer> & {
+    createHandler: EffectRpcBffHandlerFactory<TRpcs>;
+};
+export declare function createHttpApiHandler<TApi extends HttpApi.AnyWithProps = HttpApi.AnyWithProps, TRpcs extends Rpc.Any = Rpc.Any>(options: {
+    api: TApi;
+    layer: EffectRuntimeLayer;
+    openapi?: EffectBffOpenApiConfig;
+    rpc?: EffectRpcBffDefinition<TRpcs>;
+    dataPlatform?: EffectDataPlatformValidationOptions;
+    validateRequest?: EffectRequestValidator;
+}): {
+    handler: (request: Request, context?: Parameters<(request: globalThis.Request, context: Context.Context<any>) => Promise<Response>>[1]) => Promise<Response>;
+    dispose: () => Promise<void>;
+};

package/dist/types/runtime/effect/index.d.ts

@@ -1,171 +1,3 @@
-import type * as EffectType from 'effect/Effect';
-import * as Layer from 'effect/Layer';
-import { type HttpApi, type HttpApiClient, type HttpApiGroup } from 'effect/unstable/httpapi';
-import { type Rpc, type RpcGroup } from 'effect/unstable/rpc';
 export * as OpenTelemetry from '@effect/opentelemetry';
-export * as Config from 'effect/Config';
-export * as Effect from 'effect/Effect';
-export * as Layer from 'effect/Layer';
-export * as Option from 'effect/Option';
-export * as Schema from 'effect/Schema';
-export * from 'effect/unstable/http';
-export { HttpTraceContext } from 'effect/unstable/http';
-export * from 'effect/unstable/httpapi';
-export { HttpApiBuilder } from 'effect/unstable/httpapi';
-export * from 'effect/unstable/rpc';
-export { type EffectContext, useEffectContext } from './context';
-export type EffectRuntimeLayer = Layer.Layer<never, unknown, unknown>;
-export type EffectRpcSerialization = 'json' | 'ndjson' | 'jsonRpc' | 'ndJsonRpc' | 'msgPack';
-export type EffectRpcRuntimeLayer<TRpcs extends Rpc.Any = Rpc.Any> = Layer.Layer<Rpc.ToHandler<TRpcs> | Rpc.Middleware<TRpcs> | Rpc.ServicesServer<TRpcs>, unknown, never>;
-export type EffectRpcBffDefinition<TRpcs extends Rpc.Any = Rpc.Any, TRpcLayer extends EffectRpcRuntimeLayer<TRpcs> = EffectRpcRuntimeLayer<TRpcs>> = {
-    group: RpcGroup.RpcGroup<TRpcs>;
-    layer: TRpcLayer;
-    path?: `/${string}`;
-    serialization?: EffectRpcSerialization;
-    disableTracing?: boolean;
-    spanPrefix?: string;
-    spanAttributes?: Record<string, unknown>;
-    disableFatalDefects?: boolean;
-};
-export type EffectRpcBffHandlerOptions = Pick<EffectRpcBffDefinition, 'path' | 'serialization' | 'disableTracing' | 'spanPrefix' | 'spanAttributes' | 'disableFatalDefects'>;
-type EffectApiPromiseClient<TClient> = {
-    [GroupName in keyof TClient]: {
-        [EndpointName in keyof TClient[GroupName]]: TClient[GroupName][EndpointName] extends (...args: infer TArgs) => infer TResult ? TResult extends EffectType.Effect<unknown, unknown, unknown> ? (...args: TArgs) => Promise<Exclude<EffectType.Success<TResult>, readonly [unknown, unknown]>> : never : never;
-    };
-};
-export type EffectApiClientFromApi<TApi extends HttpApi.AnyWithProps = HttpApi.AnyWithProps> = TApi extends HttpApi.HttpApi<infer _ApiId, infer Groups> ? HttpApiClient.Client<Extract<Groups, HttpApiGroup.Any>, unknown, never> : never;
-export type EffectApiPromiseClientFromApi<TApi extends HttpApi.AnyWithProps = HttpApi.AnyWithProps> = EffectApiPromiseClient<EffectApiClientFromApi<TApi>>;
-export type EffectBffDefinition<TApi extends HttpApi.AnyWithProps = HttpApi.AnyWithProps, TLayer extends EffectRuntimeLayer = EffectRuntimeLayer, TRpcs extends Rpc.Any = Rpc.Any> = {
-    api: TApi;
-    layer: TLayer;
-    rpc?: EffectRpcBffDefinition<TRpcs>;
-    dataPlatform?: EffectDataPlatformValidationOptions;
-};
-export type EffectDataPlatformSelectionValidationOptions = {
-    maxDepth?: number;
-    maxFields?: number;
-    allowedLeafPaths?: string[];
-};
-export type EffectDataPlatformBatchOptions = {
-    /**
-     * Enable network batching endpoint for Effect HttpApi requests.
-     * Defaults to `true`.
-     */
-    enabled?: boolean;
-    /**
-     * Batch endpoint path mounted under BFF prefix.
-     * Defaults to `/_data/batch`.
-     */
-    endpoint?: `/${string}`;
-    /**
-     * Maximum request items accepted per batch call.
-     * Defaults to `16`.
-     */
-    maxBatchSize?: number;
-    /**
-     * Maximum serialized request payload size in bytes.
-     * Defaults to `65536` (64KiB).
-     */
-    maxBatchBytes?: number;
-    /**
-     * Client-side micro-batch flush window in milliseconds.
-     * Server runtime ignores this value and passes it through for codegen.
-     * Defaults to `8`.
-     */
-    flushIntervalMs?: number;
-    /**
-     * Maximum per-batch internal request concurrency.
-     * Defaults to `4`.
-     */
-    maxConcurrency?: number;
-    /**
-     * Optional timeout per internal request in milliseconds.
-     * Defaults to `10000`.
-     */
-    requestTimeoutMs?: number;
-    /**
-     * Allowed HTTP methods for internal batched dispatch.
-     * Defaults to `['GET']`.
-     */
-    allowedMethods?: string[];
-};
-export type EffectDataPlatformValidationOptions = {
-    /**
-     * Enable envelope validation for HttpApi requests.
-     * Defaults to `true`.
-     */
-    enabled?: boolean;
-    /**
-     * Require every HttpApi request to include an envelope header.
-     * Defaults to `false`.
-     */
-    requireEnvelope?: boolean;
-    /**
-     * Header name used by client/server for the serialized request envelope.
-     * Defaults to `x-modernjs-data-envelope`.
-     */
-    envelopeHeader?: string;
-    /**
-     * Optional namespace assertion for envelope validation.
-     */
-    expectedNamespace?: string;
-    /**
-     * Validate envelope origin against incoming request origin.
-     * Defaults to `true`.
-     */
-    validateOrigin?: boolean;
-    /**
-     * Require trace context inside request envelope.
-     * Defaults to `false`.
-     */
-    requireTraceContext?: boolean;
-    /**
-     * Selection plan guardrails for server-side validation.
-     */
-    selection?: EffectDataPlatformSelectionValidationOptions;
-    /**
-     * Network batching gateway configuration.
-     */
-    batch?: EffectDataPlatformBatchOptions;
-};
-export type EffectBffHandlerFactory<TApi extends HttpApi.AnyWithProps = HttpApi.AnyWithProps, TLayer extends EffectRuntimeLayer = EffectRuntimeLayer> = (options?: {
-    openapi?: EffectBffOpenApiConfig;
-    rpc?: Partial<EffectRpcBffHandlerOptions>;
-    dataPlatform?: Partial<EffectDataPlatformValidationOptions>;
-}) => ReturnType<typeof createHttpApiHandler>;
-export type EffectBffRuntime<TApi extends HttpApi.AnyWithProps = HttpApi.AnyWithProps, TLayer extends EffectRuntimeLayer = EffectRuntimeLayer> = {
-    createHandler: EffectBffHandlerFactory<TApi, TLayer>;
-    client: EffectApiPromiseClientFromApi<TApi>;
-};
-export type EffectBffOpenApiConfig = boolean | {
-    path?: string;
-};
-export type EffectRpcBffHandlerFactory<TRpcs extends Rpc.Any = Rpc.Any> = (options?: Partial<EffectRpcBffHandlerOptions>) => ReturnType<typeof createRpcApiHandler<TRpcs>>;
-declare function createRpcApiHandler<TRpcs extends Rpc.Any = Rpc.Any>(options: EffectRpcBffDefinition<TRpcs>): {
-    readonly handler: (request: globalThis.Request, context?: import("effect/Context").Context<never> | undefined) => Promise<Response>;
-    readonly dispose: () => Promise<void>;
-};
-export declare function defineEffectBff<TApi extends HttpApi.AnyWithProps, TLayer extends EffectRuntimeLayer, TRpcs extends Rpc.Any = Rpc.Any>(definition: {
-    api: TApi;
-    layer: TLayer;
-    rpc?: EffectRpcBffDefinition<TRpcs>;
-    dataPlatform?: EffectDataPlatformValidationOptions;
-}): {
-    api: TApi;
-    layer: TLayer;
-    rpc?: EffectRpcBffDefinition<TRpcs>;
-    dataPlatform?: EffectDataPlatformValidationOptions;
-} & EffectBffRuntime<TApi, TLayer>;
-export declare function defineEffectRpcBff<TRpcs extends Rpc.Any = Rpc.Any, TLayer extends EffectRpcRuntimeLayer<TRpcs> = EffectRpcRuntimeLayer<TRpcs>>(definition: EffectRpcBffDefinition<TRpcs, TLayer>): EffectRpcBffDefinition<TRpcs, TLayer> & {
-    createHandler: EffectRpcBffHandlerFactory<TRpcs>;
-};
-export declare function createHttpApiHandler<TApi extends HttpApi.AnyWithProps = HttpApi.AnyWithProps, TRpcs extends Rpc.Any = Rpc.Any>(options: {
-    api: TApi;
-    layer: EffectRuntimeLayer;
-    openapi?: EffectBffOpenApiConfig;
-    rpc?: EffectRpcBffDefinition<TRpcs>;
-    dataPlatform?: EffectDataPlatformValidationOptions;
-}): {
-    handler: (request: Request, context?: Parameters<(request: globalThis.Request, context: import("effect/Context").Context<any>) => Promise<Response>>[1]) => Promise<Response>;
-    dispose: () => Promise<void>;
-};
+export { type CreateEffectOperationContextOptions, createEffectOperationContext, type EffectContext, useEffectContext, useOperationContext, } from './context';
+export * from './handler';

package/dist/types/runtime/effect/module.d.ts

@@ -0,0 +1,48 @@
+import type * as EffectServiceContext from 'effect/Context';
+import { type EffectBffOpenApiConfig, type EffectDataPlatformValidationOptions, type EffectRequestValidator } from './handler';
+import type { EffectContext } from './operation-context';
+export type EffectBffRequestHandler = (request: Request, context?: EffectServiceContext.Context<any> | EffectContext) => Promise<Response> | Response;
+export type EffectBffHandlerFactory = (options?: {
+    openapi?: EffectBffOpenApiConfig;
+    dataPlatform?: EffectDataPlatformValidationOptions;
+    validateRequest?: EffectRequestValidator;
+}) => {
+    handler: EffectBffRequestHandler;
+    dispose: () => Promise<void>;
+};
+export type EffectApiModule = {
+    api?: unknown;
+    layer?: unknown;
+    handler?: EffectBffRequestHandler;
+    createHandler?: EffectBffHandlerFactory;
+    default?: unknown;
+};
+export type LoadedEffectBffHandler = {
+    handler: EffectBffRequestHandler;
+    dispose?: () => Promise<void>;
+    /**
+     * True when the handler is known to apply `validateRequest` internally
+     * (including per batched item): `{ api, layer }` modules resolved through
+     * `createHttpApiHandler`, and `createHandler` factories branded by
+     * `defineEffectBff` (see `EFFECT_VALIDATOR_AWARE_FACTORY`). Plain
+     * `handler` exports and unbranded custom factories leave this unset; the
+     * adapter middleware must enforce the policy itself for those.
+     */
+    appliesRequestValidator?: boolean;
+};
+export type ResolveEffectBffModuleHandlerOptions = {
+    openapi?: EffectBffOpenApiConfig;
+    dataPlatform?: EffectDataPlatformValidationOptions;
+    /**
+     * Server-seam request validator (cross-project policy). Applied by
+     * `createHttpApiHandler` to direct, batched and rpc requests.
+     *
+     * Note: plain `handler` exports and unbranded custom `createHandler`
+     * factories bypass this seam — the effect adapter enforces the policy in
+     * its middleware for those shapes instead (see
+     * `LoadedEffectBffHandler.appliesRequestValidator`).
+     */
+    validateRequest?: EffectRequestValidator;
+    onWarning?: (message: string) => void;
+};
+export declare function resolveEffectBffModuleHandler(mod: EffectApiModule, options?: ResolveEffectBffModuleHandlerOptions): Promise<LoadedEffectBffHandler | null>;

package/dist/types/runtime/effect/operation-context.d.ts

@@ -0,0 +1,10 @@
+import { type OperationContext } from '@modern-js/create-request';
+export type EffectContext = {
+    request: Request;
+    env: Record<string, unknown>;
+    path: string;
+    method: string;
+    operationContext: OperationContext;
+};
+export type CreateEffectOperationContextOptions = Omit<EffectContext, 'operationContext'>;
+export declare const createEffectOperationContext: ({ request, path, method, }: CreateEffectOperationContextOptions) => OperationContext;

package/dist/types/runtime/effect-client/index.d.ts

@@ -1,5 +1,7 @@
+import { type RequestContextInput } from '@modern-js/create-request';
 import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
+import { HttpClient } from 'effect/unstable/http';
 import { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from 'effect/unstable/httpapi';
 import { Rpc, RpcClient, RpcGroup, RpcSchema, RpcSerialization } from 'effect/unstable/rpc';
 export * as Effect from 'effect/Effect';
@@ -8,6 +10,9 @@ export * as Schema from 'effect/Schema';
 export { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup, HttpApiSchema, Rpc, RpcClient, RpcGroup, RpcSchema, RpcSerialization, };
 export type EffectHttpApiClientOptions = {
     baseUrl?: URL | string;
+    requestContext?: RequestContextInput;
+    transformClient?: (client: HttpClient.HttpClient) => HttpClient.HttpClient;
+    transformResponse?: ((effect: Effect.Effect<unknown, unknown, unknown>) => Effect.Effect<unknown, unknown, unknown>) | undefined;
 };
 type Nullish = null | undefined;
 type NonNullish<T> = Exclude<T, Nullish>;
@@ -49,6 +54,6 @@ export declare function mask<T, const Selection extends EffectViewSelection<T>>(
 export declare function runEffectView<T, const Selection extends EffectViewSelection<T>>(request: PromiseLike<T>, selection: Selection): Promise<EffectViewData<T, Selection>>;
 export declare function makeEffectHttpApiClient<ApiId extends string, Groups extends HttpApiGroup.Any>(api: HttpApi.HttpApi<ApiId, Groups>, options?: EffectHttpApiClientOptions): Effect.Effect<import("effect/Types").Simplify<{ readonly [Group in Extract<Groups, {
     readonly topLevel: false;
-}> as HttpApiGroup.Name<Group>]: HttpApiClient.Client.Group<Group, Group["identifier"], never, never>; } & { readonly [Method in HttpApiClient.Client.TopLevelMethods<Groups, never, never> as Method[0]]: Method[1]; }>, never, Exclude<import("effect/unstable/httpapi/HttpApiMiddleware").MiddlewareClient<HttpApiEndpoint.Middleware<HttpApiGroup.Endpoints<Groups>>>, import("effect/unstable/http/HttpClient").HttpClient>>;
+}> as HttpApiGroup.Name<Group>]: HttpApiClient.Client.Group<Group, Group["identifier"], never, never>; } & { readonly [Method in HttpApiClient.Client.TopLevelMethods<Groups, never, never> as Method[0]]: Method[1]; }>, never, Exclude<import("effect/unstable/httpapi/HttpApiMiddleware").MiddlewareClient<HttpApiEndpoint.Middleware<HttpApiGroup.Endpoints<Groups>>>, HttpClient.HttpClient>>;
 export declare function makeEffectRpcClient<Rpcs extends Rpc.Any, const Flatten extends boolean = false>(group: RpcGroup.RpcGroup<Rpcs>, options: EffectRpcClientOptions<Rpcs, Flatten>): Effect.Effect<EffectRpcClientHandle<Rpcs, Flatten>, EffectRpcClientError, never>;
 export declare const runEffectRequest: <A, E>(effect: Effect.Effect<A, E>, options?: Effect.RunOptions | undefined) => Promise<A>;