@bleedingdev/modern-js-bff-effect 3.8.3-ultramodern.2

package/src/effect/handler/types.ts

@@ -0,0 +1,255 @@
+// @effect-diagnostics anyUnknownInErrorContext:off asyncFunction:off globalDate:off globalTimers:off newPromise:off strictBooleanExpressions:off
+import type { FileSystem, Path } from 'effect';
+import * as Context from 'effect/Context';
+import type * as EffectType from 'effect/Effect';
+import type * as Layer from 'effect/Layer';
+import type { Etag, HttpPlatform, HttpRouter } from 'effect/unstable/http';
+import type {
+  HttpApi,
+  HttpApiClient,
+  HttpApiGroup,
+} from 'effect/unstable/httpapi';
+import type { Rpc, RpcGroup } from 'effect/unstable/rpc';
+
+import type { createHttpApiHandler } from './http';
+import type { createRpcApiHandler } from './rpc';
+
+export type EffectRuntimeRequirements =
+  | Etag.Generator
+  | FileSystem.FileSystem
+  | HttpPlatform.HttpPlatform
+  | HttpRouter.HttpRouter
+  | HttpRouter.Request<'Error', unknown>
+  | HttpRouter.Request<'GlobalError', unknown>
+  | HttpRouter.Request<'GlobalRequires', unknown>
+  | HttpRouter.Request<'Requires', unknown>
+  | Path.Path;
+export type EffectRuntimeLayer = Layer.Layer<
+  never,
+  never,
+  EffectRuntimeRequirements
+>;
+const emptyEffectServiceContext = Context.empty() as Context.Context<any>;
+
+const isEffectServiceContext = (
+  context: unknown,
+): context is Context.Context<any> =>
+  typeof context === 'object' && context !== null && 'mapUnsafe' in context;
+
+export const toEffectServiceContext = (context: unknown) =>
+  isEffectServiceContext(context) ? context : emptyEffectServiceContext;
+
+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.Constraint = HttpApi.Top,
+> =
+  TApi extends HttpApi.HttpApi<infer _ApiId, infer Groups>
+    ? HttpApiClient.Client<
+        Extract<Groups, HttpApiGroup.Constraint>,
+        never,
+        never
+      >
+    : never;
+
+export type EffectApiPromiseClientFromApi<
+  TApi extends HttpApi.Constraint = HttpApi.Top,
+> = EffectApiPromiseClient<EffectApiClientFromApi<TApi>>;
+
+export type EffectBffDefinition<
+  TApi extends HttpApi.Constraint = HttpApi.Top,
+  TLayer extends EffectRuntimeLayer = EffectRuntimeLayer,
+  TRpcs extends Rpc.Any = Rpc.Any,
+> = {
+  api: TApi;
+  layer: TLayer;
+  rpc?: EffectRpcBffDefinition<TRpcs>;
+  dataPlatform?: EffectDataPlatformValidationOptions;
+  interceptRequest?: EffectRequestInterceptor;
+};
+
+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;
+
+export type EffectRequestInterceptor = (options: {
+  request: Request;
+  next: () => Promise<Response>;
+}) => Response | Promise<Response>;
+
+export type EffectBffHandlerFactory<
+  TApi extends HttpApi.Constraint = HttpApi.Top,
+  TLayer extends EffectRuntimeLayer = EffectRuntimeLayer,
+> = (options?: {
+  openapi?: EffectBffOpenApiConfig;
+  rpc?: Partial<EffectRpcBffHandlerOptions>;
+  dataPlatform?: Partial<EffectDataPlatformValidationOptions>;
+  validateRequest?: EffectRequestValidator;
+}) => ReturnType<typeof createHttpApiHandler>;
+
+export type EffectBffRuntime<
+  TApi extends HttpApi.Constraint = HttpApi.Top,
+  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>>;

package/src/effect/handler.ts

@@ -0,0 +1,33 @@
+// @effect-diagnostics anyUnknownInErrorContext:off asyncFunction:off globalDate:off globalTimers:off newPromise:off strictBooleanExpressions:off
+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 { defineEffectBff, defineEffectRpcBff } from './handler/definition';
+export { createHttpApiHandler } from './handler/http';
+export type {
+  EffectApiClientFromApi,
+  EffectApiPromiseClientFromApi,
+  EffectBffDefinition,
+  EffectBffHandlerFactory,
+  EffectBffOpenApiConfig,
+  EffectBffRuntime,
+  EffectDataPlatformBatchOptions,
+  EffectDataPlatformSelectionValidationOptions,
+  EffectDataPlatformValidationOptions,
+  EffectRequestValidator,
+  EffectRpcBffDefinition,
+  EffectRpcBffHandlerFactory,
+  EffectRpcBffHandlerOptions,
+  EffectRpcRuntimeLayer,
+  EffectRpcSerialization,
+  EffectRuntimeLayer,
+  EffectRuntimeRequirements,
+} from './handler/types';

package/src/effect/index.ts

@@ -0,0 +1,22 @@
+export * as OpenTelemetry from '@effect/opentelemetry';
+export {
+  type CreateEffectOperationContextOptions,
+  createEffectOperationContext,
+  type EffectContext,
+  runWithEffectContext,
+  useEffectContext,
+  useOperationContext,
+} from './context';
+export {
+  createEffectBffEdgeHandler,
+  createEffectBffTestHandler,
+  dispatchEffectBffRequest,
+} from './edge';
+export * from './endpoint-contracts';
+export * from './handler';
+export {
+  type EffectApiModule,
+  type EffectBffHandlerFactory,
+  type EffectBffRequestHandler,
+  resolveEffectBffModuleHandler,
+} from './module';

package/src/effect/module.ts

@@ -0,0 +1,186 @@
+// @effect-diagnostics strictBooleanExpressions:off
+import type * as EffectServiceContext from 'effect/Context';
+import { HttpApi } from 'effect/unstable/httpapi';
+import {
+  classifyEffectBffEntryModule,
+  type EffectBffEntryShapeFacts,
+  isValidatorAwareHandlerFactory,
+  strictEffectApproachMessage,
+} from './entry-shape';
+import {
+  createHttpApiHandler,
+  type EffectBffOpenApiConfig,
+  type EffectDataPlatformValidationOptions,
+  type EffectRequestValidator,
+  type EffectRuntimeLayer,
+} 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;
+};
+
+type LoadedEffectBffHandler = {
+  handler: EffectBffRequestHandler;
+  dispose?: () => Promise<void>;
+};
+
+type ResolveEffectBffModuleHandlerOptions = {
+  openapi?: EffectBffOpenApiConfig;
+  dataPlatform?: EffectDataPlatformValidationOptions;
+  /**
+   * Server-seam request validator (cross-project policy). Strict Effect
+   * entries forward it into `createHttpApiHandler`, where it applies to
+   * direct, batched and rpc requests.
+   */
+  validateRequest?: EffectRequestValidator;
+  onWarning?: (message: string) => void;
+};
+
+function isRequestHandler(value: unknown): value is EffectBffRequestHandler {
+  return typeof value === 'function';
+}
+
+function shareDispose(dispose: () => Promise<void>) {
+  let disposePromise: Promise<void> | undefined;
+  return () => {
+    disposePromise ??= Promise.resolve().then(dispose);
+    return disposePromise;
+  };
+}
+
+function rejectLegacyEffectModuleShape(
+  options: ResolveEffectBffModuleHandlerOptions,
+  shape: string,
+) {
+  options.onWarning?.(`${strictEffectApproachMessage} Rejected ${shape}.`);
+  return true;
+}
+
+function callEffectBffRequestHandler(
+  handler: EffectBffRequestHandler,
+  request: Request,
+  context: Parameters<EffectBffRequestHandler>[1],
+) {
+  return context === undefined ? handler(request) : handler(request, context);
+}
+
+function createLoadedHandler(webHandler: {
+  handler: EffectBffRequestHandler;
+  dispose: () => Promise<void>;
+}): LoadedEffectBffHandler {
+  return {
+    handler: (request, context) =>
+      callEffectBffRequestHandler(webHandler.handler, request, context),
+    dispose: shareDispose(webHandler.dispose),
+  };
+}
+
+function createLoadedHttpApiHandler(
+  webHandler: ReturnType<typeof createHttpApiHandler>,
+): LoadedEffectBffHandler {
+  return createLoadedHandler({
+    handler: webHandler.handler as EffectBffRequestHandler,
+    dispose: webHandler.dispose,
+  });
+}
+
+function classifyEffectBffRuntimeEntryShape(module: EffectApiModule) {
+  return classifyEffectBffEntryModule(module, {
+    isRequestHandler,
+    isValidatorAwareHandlerFactory,
+    isHttpApi: HttpApi.isHttpApi,
+  });
+}
+
+function resolveClassifiedEffectBffModuleHandler(
+  facts: EffectBffEntryShapeFacts | null,
+  options: ResolveEffectBffModuleHandlerOptions = {},
+): LoadedEffectBffHandler | null {
+  if (!facts) {
+    return null;
+  }
+
+  if (facts.legacyShape) {
+    if (rejectLegacyEffectModuleShape(options, facts.legacyShape)) {
+      return null;
+    }
+  }
+
+  if (typeof facts.createHandler === 'function') {
+    if (facts.createHandlerValidatorAware) {
+      const factory = facts.createHandler as EffectBffHandlerFactory;
+      const webHandler = factory({
+        openapi: options.openapi,
+        dataPlatform: options.dataPlatform,
+        validateRequest: options.validateRequest,
+      });
+      return createLoadedHandler(webHandler);
+    }
+
+    if (facts.api === undefined || !facts.hasRuntimeLayer) {
+      rejectLegacyEffectModuleShape(
+        options,
+        'unbranded `createHandler` export',
+      );
+      return null;
+    }
+
+    options.onWarning?.(
+      `${strictEffectApproachMessage} Ignored unbranded \`createHandler\` export and rebuilt the handler from its { api, layer } exports.`,
+    );
+  }
+
+  if (facts.api !== undefined && facts.hasRuntimeLayer) {
+    if (facts.createHandler === undefined) {
+      options.onWarning?.(
+        '[BFF][Effect] Detected { api, layer } export without createHandler. Prefer `defineEffectBff(...)` from @modern-js/bff-effect/effect to avoid module instance mismatch.',
+      );
+    }
+    const webHandler = createHttpApiHandler({
+      api: facts.api as HttpApi.Top,
+      layer: facts.layer as EffectRuntimeLayer,
+      openapi: options.openapi,
+      dataPlatform: options.dataPlatform,
+      validateRequest: options.validateRequest,
+    });
+    return createLoadedHttpApiHandler(webHandler);
+  }
+
+  return null;
+}
+
+function resolveNormalizedEffectBffModuleHandler(
+  normalizedModule: EffectApiModule,
+  options: ResolveEffectBffModuleHandlerOptions = {},
+): LoadedEffectBffHandler | null {
+  return resolveClassifiedEffectBffModuleHandler(
+    classifyEffectBffRuntimeEntryShape(normalizedModule),
+    options,
+  );
+}
+
+export function resolveEffectBffModuleHandler(
+  mod: EffectApiModule,
+  options: ResolveEffectBffModuleHandlerOptions = {},
+): Promise<LoadedEffectBffHandler | null> {
+  return Promise.resolve(resolveNormalizedEffectBffModuleHandler(mod, options));
+}

package/src/effect/operation-context.ts

@@ -0,0 +1,144 @@
+// @effect-diagnostics strictBooleanExpressions:off
+import {
+  BFF_LOCALE_HEADER,
+  BFF_OPERATION_CONTEXT_DETAIL_HEADER,
+  BFF_OPERATION_CONTEXT_HEADER,
+  BFF_TRACEPARENT_HEADER,
+  type OperationContext,
+  parseTraceparent,
+} from '@modern-js/create-request';
+
+export type EffectContext = {
+  request: Request;
+  env: Record<string, unknown>;
+  path: string;
+  method: string;
+  operationContext: OperationContext;
+};
+
+export type EffectContextStorage = {
+  getStore: () => EffectContext | undefined;
+  run: <TResult>(value: EffectContext, cb: () => TResult) => TResult;
+};
+
+export const kEffectContextStorage = Symbol.for(
+  'modernjs.plugin-bff.effectContextStorage',
+);
+
+export type CreateEffectOperationContextOptions = Omit<
+  EffectContext,
+  'operationContext'
+>;
+
+type OperationContextStringField =
+  | 'requestId'
+  | 'operationId'
+  | 'schemaHash'
+  | 'traceparent'
+  | 'traceId'
+  | 'spanId';
+
+const readHeader = (headers: Headers, header: string) => {
+  const value = headers.get(header);
+  return value && value.length > 0 ? value : undefined;
+};
+
+const copyStringField = (
+  target: Partial<OperationContext>,
+  details: Record<string, unknown>,
+  key: OperationContextStringField,
+) => {
+  const value = details[key];
+  if (typeof value === 'string' && value.length > 0) {
+    target[key] = value;
+  }
+};
+
+const readOperationContextDetails = (
+  request: Request,
+): Partial<OperationContext> => {
+  const rawDetails = readHeader(
+    request.headers,
+    BFF_OPERATION_CONTEXT_DETAIL_HEADER,
+  );
+  if (!rawDetails) {
+    return {};
+  }
+
+  try {
+    const parsed = JSON.parse(rawDetails);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return {};
+    }
+    const details = parsed as Record<string, unknown>;
+    const safeDetails: Partial<OperationContext> = {};
+    copyStringField(safeDetails, details, 'requestId');
+    copyStringField(safeDetails, details, 'operationId');
+    copyStringField(safeDetails, details, 'schemaHash');
+    copyStringField(safeDetails, details, 'traceparent');
+    copyStringField(safeDetails, details, 'traceId');
+    copyStringField(safeDetails, details, 'spanId');
+    if (typeof details.operationVersion === 'number') {
+      safeDetails.operationVersion = details.operationVersion;
+    }
+    return safeDetails;
+  } catch {
+    return {};
+  }
+};
+
+export const createEffectOperationContext = ({
+  request,
+  path,
+  method,
+}: CreateEffectOperationContextOptions): OperationContext => {
+  const details = readOperationContextDetails(request);
+  const operationDetails = { ...details };
+  delete operationDetails.traceparent;
+  delete operationDetails.traceId;
+  delete operationDetails.spanId;
+  const servicePath = new URL(request.url).pathname;
+  const headerTraceparent = readHeader(request.headers, BFF_TRACEPARENT_HEADER);
+  const headerTraceContext = parseTraceparent(headerTraceparent);
+  const detailTraceContext = parseTraceparent(details.traceparent);
+  const traceparent = headerTraceContext
+    ? headerTraceparent
+    : detailTraceContext
+      ? details.traceparent
+      : undefined;
+  const parsedTraceparent =
+    headerTraceContext ||
+    detailTraceContext ||
+    (details.traceId && details.spanId
+      ? {
+          traceId: details.traceId,
+          spanId: details.spanId,
+        }
+      : undefined);
+  const locale = readHeader(request.headers, BFF_LOCALE_HEADER);
+  const headerOperationId = readHeader(
+    request.headers,
+    BFF_OPERATION_CONTEXT_HEADER,
+  );
+
+  return {
+    ...operationDetails,
+    ...(headerOperationId || details.operationId
+      ? { operationId: headerOperationId || details.operationId }
+      : {}),
+    routePath: servicePath,
+    method: (method || request.method || 'GET').toUpperCase(),
+    source: 'effect-adapter',
+    ...(path && path !== servicePath
+      ? { attributes: { mountedPath: path } }
+      : {}),
+    ...(locale ? { locale } : {}),
+    ...(traceparent ? { traceparent } : {}),
+    ...(parsedTraceparent
+      ? {
+          traceId: parsedTraceparent.traceId,
+          spanId: parsedTraceparent.spanId,
+        }
+      : {}),
+  };
+};

package/src/effect/rpcSerialization.ts

@@ -0,0 +1,20 @@
+import { RpcSerialization } from 'effect/unstable/rpc';
+
+import type { EffectRpcSerialization } from './handler/types';
+
+export function getRpcSerializationLayer(
+  serialization: EffectRpcSerialization | undefined,
+) {
+  switch (serialization) {
+    case 'ndjson':
+      return RpcSerialization.layerNdjson;
+    case 'jsonRpc':
+      return RpcSerialization.layerJsonRpc();
+    case 'ndJsonRpc':
+      return RpcSerialization.layerNdJsonRpc();
+    case 'msgPack':
+      return RpcSerialization.layerMsgPack;
+    default:
+      return RpcSerialization.layerJsonRpc();
+  }
+}