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

package/src/effect/edge-dispatcher.ts

@@ -0,0 +1,310 @@
+// @effect-diagnostics anyUnknownInErrorContext:off asyncFunction:off strictBooleanExpressions:off
+import {
+  evaluateCrossProjectPolicy,
+  type NormalizedCrossProjectPolicy,
+  resolveCrossProjectRequestObservation,
+} from '@modern-js/bff-core/security/cross-project-policy';
+import { toHeaderRecord } from '../headers';
+import {
+  type DispatchEffectBffRequestOptions,
+  dispatchEffectBffRequestWithContext,
+} from './dispatch';
+import { runWithEffectContext } from './edge-context';
+import type {
+  EffectBffOpenApiConfig,
+  EffectDataPlatformValidationOptions,
+} from './handler';
+import {
+  type EffectApiModule,
+  type EffectBffRequestHandler,
+  resolveEffectBffModuleHandler,
+} from './module';
+import type { EffectContext } from './operation-context';
+
+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 {
+  Cookies,
+  Etag,
+  FetchHttpClient,
+  FindMyWay,
+  Headers,
+  HttpBody,
+  HttpClient,
+  HttpClientError,
+  HttpClientRequest,
+  HttpClientResponse,
+  HttpEffect,
+  HttpIncomingMessage,
+  HttpMethod,
+  HttpMiddleware,
+  HttpPlatform,
+  HttpRouter,
+  HttpServer,
+  HttpServerError,
+  HttpServerRequest,
+  HttpServerRespondable,
+  HttpServerResponse,
+  HttpStaticServer,
+  HttpStatus,
+  HttpTraceContext,
+  Multipart,
+  MultipartParser,
+  Template,
+  Url,
+  UrlParams,
+} from 'effect/unstable/http';
+export {
+  HttpApi,
+  HttpApiBuilder,
+  HttpApiClient,
+  HttpApiEndpoint,
+  HttpApiError,
+  HttpApiGroup,
+  HttpApiMiddleware,
+  HttpApiSchema,
+  HttpApiSecurity,
+  HttpApiTest,
+  OpenApi,
+} from 'effect/unstable/httpapi';
+export {
+  Rpc,
+  RpcClient,
+  RpcClientError,
+  RpcGroup,
+  RpcMessage,
+  RpcMiddleware,
+  RpcSchema,
+  RpcSerialization,
+  RpcServer,
+  RpcTest,
+  RpcWorker,
+  Utils,
+} from 'effect/unstable/rpc';
+export {
+  runWithEffectContext,
+  useEffectContext,
+  useOperationContext,
+} from './edge-context';
+export type {
+  EffectApiClientFromApi,
+  EffectApiPromiseClientFromApi,
+  EffectBffDefinition,
+  EffectBffHandlerFactory,
+  EffectBffOpenApiConfig,
+  EffectBffRuntime,
+  EffectDataPlatformBatchOptions,
+  EffectDataPlatformSelectionValidationOptions,
+  EffectDataPlatformValidationOptions,
+  EffectRequestValidator,
+  EffectRpcBffDefinition,
+  EffectRpcBffHandlerFactory,
+  EffectRpcBffHandlerOptions,
+  EffectRpcRuntimeLayer,
+  EffectRpcSerialization,
+  EffectRuntimeLayer,
+  EffectRuntimeRequirements,
+} from './handler';
+export {
+  createHttpApiHandler,
+  defineEffectBff,
+  defineEffectRpcBff,
+} from './handler';
+export {
+  type CreateEffectOperationContextOptions,
+  createEffectOperationContext,
+  type EffectContext,
+} from './operation-context';
+
+export type EffectBffEdgeDispatchOptions = Omit<
+  DispatchEffectBffRequestOptions,
+  'runWithEffectContext'
+>;
+
+export type EffectBffEdgeHandlerOptions = {
+  module: EffectApiModule;
+  prefix?: string;
+  openapi?: EffectBffOpenApiConfig;
+  dataPlatform?: EffectDataPlatformValidationOptions;
+  crossProjectPolicy?: NormalizedCrossProjectPolicy;
+  onError?: (
+    error: unknown,
+    context: EffectContext,
+  ) => Promise<Response> | Response;
+  onWarning?: (message: string) => void;
+};
+
+const NORMALIZED_POLICY_BOOLEAN_FIELDS = [
+  'enabled',
+  'requireEnvelope',
+  'requireOperationContext',
+  'requireOperationContextDetails',
+  'requireOperationSchemaHash',
+  'requireOperationVersion',
+  'allowUnknownOperations',
+] as const;
+
+function assertNormalizedCrossProjectPolicy(
+  policy: NormalizedCrossProjectPolicy | undefined,
+) {
+  if (policy === undefined) {
+    return;
+  }
+  if (!policy || typeof policy !== 'object' || Array.isArray(policy)) {
+    throw new Error(
+      '[BFF][Effect] Edge cross-project policy must be a normalized object.',
+    );
+  }
+  for (const field of NORMALIZED_POLICY_BOOLEAN_FIELDS) {
+    if (typeof policy[field] !== 'boolean') {
+      throw new Error(
+        `[BFF][Effect] Edge cross-project policy requires boolean ${field}.`,
+      );
+    }
+  }
+  if (
+    !policy.expectedOperationContracts ||
+    typeof policy.expectedOperationContracts !== 'object' ||
+    Array.isArray(policy.expectedOperationContracts)
+  ) {
+    throw new Error(
+      '[BFF][Effect] Edge cross-project policy requires expectedOperationContracts object.',
+    );
+  }
+}
+
+function restoreEffectBffMountPath(
+  request: Request,
+  prefix: string | undefined,
+) {
+  const pathname = new URL(request.url).pathname;
+  if (!prefix || prefix === '/') {
+    return pathname;
+  }
+  const normalizedPrefix = prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
+  return pathname === '/' ? normalizedPrefix : `${normalizedPrefix}${pathname}`;
+}
+
+export async function dispatchEffectBffRequest(
+  handler: EffectBffRequestHandler,
+  request: Request,
+  options: EffectBffEdgeDispatchOptions = {},
+): Promise<Response> {
+  return dispatchEffectBffRequestWithContext(handler, request, {
+    ...options,
+    runWithEffectContext,
+  });
+}
+
+export async function createEffectBffEdgeDispatcher(
+  options: EffectBffEdgeHandlerOptions,
+) {
+  const crossProjectPolicy = options.crossProjectPolicy;
+  assertNormalizedCrossProjectPolicy(crossProjectPolicy);
+  const loaded = await resolveEffectBffModuleHandler(options.module, {
+    openapi: options.openapi,
+    dataPlatform: options.dataPlatform,
+    validateRequest:
+      crossProjectPolicy?.enabled === true
+        ? request => {
+            const pathname = new URL(request.url).pathname;
+            const observedRequest = resolveCrossProjectRequestObservation(
+              { method: request.method, pathname },
+              crossProjectPolicy,
+            ) ?? {
+              method: request.method,
+              routePath: restoreEffectBffMountPath(request, options.prefix),
+            };
+            const violation = evaluateCrossProjectPolicy(
+              toHeaderRecord(request.headers),
+              crossProjectPolicy,
+              observedRequest,
+            );
+            if (!violation) {
+              return null;
+            }
+            return new Response(
+              JSON.stringify({
+                code: violation.code,
+                reason: violation.reason,
+                message: violation.message,
+              }),
+              {
+                status: violation.status,
+                headers: {
+                  'content-type': 'application/json; charset=utf-8',
+                },
+              },
+            );
+          }
+        : undefined,
+    onWarning: options.onWarning,
+  });
+  if (!loaded) {
+    throw new Error(
+      '[BFF][Effect] Invalid Effect edge module. Export defineEffectBff(...) or a { api, layer } HttpApi module.',
+    );
+  }
+
+  const retiredError = new Error(
+    '[BFF][Effect] Edge dispatcher is disposing or has been disposed.',
+  );
+  let acceptingRequests = true;
+  let activeDispatches = 0;
+  let resolveDrain: (() => void) | undefined;
+  let disposePromise: Promise<void> | undefined;
+
+  return {
+    dispatch: (
+      request: Request,
+      dispatchOptions: Omit<
+        EffectBffEdgeDispatchOptions,
+        'prefix' | 'onError'
+      > = {},
+    ) => {
+      if (!acceptingRequests) {
+        return Promise.reject(retiredError);
+      }
+      activeDispatches += 1;
+      return dispatchEffectBffRequest(loaded.handler, request, {
+        ...dispatchOptions,
+        prefix: options.prefix,
+        onError: options.onError,
+      }).finally(() => {
+        activeDispatches -= 1;
+        if (activeDispatches === 0) {
+          resolveDrain?.();
+          resolveDrain = undefined;
+        }
+      });
+    },
+    dispose: () => {
+      disposePromise ??= (async () => {
+        acceptingRequests = false;
+        if (activeDispatches > 0) {
+          await new Promise<void>(resolve => {
+            resolveDrain = resolve;
+          });
+        }
+        await loaded.dispose?.();
+      })();
+      return disposePromise;
+    },
+  };
+}
+
+export const createEffectBffTestHandler = createEffectBffEdgeHandler;
+
+export async function createEffectBffEdgeHandler(
+  options: EffectBffEdgeHandlerOptions,
+) {
+  const dispatcher = await createEffectBffEdgeDispatcher(options);
+
+  return {
+    handler: dispatcher.dispatch,
+    dispose: dispatcher.dispose,
+  };
+}

package/src/effect/edge.ts

@@ -0,0 +1 @@
+export * from './edge-dispatcher';

package/src/effect/endpoint-contracts.ts

@@ -0,0 +1,191 @@
+// @effect-diagnostics asyncFunction:off strictBooleanExpressions:off
+/**
+ * Shared Effect HttpApi endpoint reflection used by BOTH sides of the
+ * cross-project contract:
+ *
+ * - the `@modern-js/plugin-bff-extensions/client-generator` package stamps
+ *   each generated operation with a per-endpoint contract hash;
+ * - the `@modern-js/plugin-bff-extensions/effect-adapter` package 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 {
+  createOperationContractHash,
+  type OperationContractSource,
+} from '@modern-js/bff-core';
+import {
+  classifyEffectBffEntryModule,
+  isValidatorAwareHandlerFactory,
+} from './entry-shape';
+
+export type EffectEndpointMeta = {
+  apiId: string;
+  groupName: string;
+  endpointName: string;
+  method: string;
+  routePath: string;
+};
+
+export type HttpApiLike = {
+  identifier?: unknown;
+};
+
+type HttpApiGroupLike = {
+  identifier?: unknown;
+};
+
+type HttpApiEndpointLike = {
+  /**
+   * effect 4.0.0-beta.98 renamed the endpoint `name` property to `identifier`,
+   * matching `HttpApiGroup`. `name` is kept as a fallback so reflection over an
+   * older Effect build does not silently degrade to the class name.
+   */
+  identifier?: unknown;
+  name?: unknown;
+  method?: unknown;
+  path?: unknown;
+};
+
+function resolveEffectEndpointName(endpoint: HttpApiEndpointLike): string {
+  if (typeof endpoint.identifier === 'string' && endpoint.identifier) {
+    return endpoint.identifier;
+  }
+  if (typeof endpoint.name === 'string' && endpoint.name) {
+    return endpoint.name;
+  }
+  return '';
+}
+
+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 function ensureLeadingSlash(pathname: string) {
+  return pathname.startsWith('/') ? pathname : `/${pathname}`;
+}
+
+export function normalizeEffectPrefix(prefix: string) {
+  if (prefix === '/') {
+    return '';
+  }
+  return ensureLeadingSlash(prefix || '/api');
+}
+
+function getEffectRoutePath(prefix: string, endpointPath: string) {
+  const normalizedPrefix = normalizeEffectPrefix(prefix);
+  const normalizedEndpointPath = ensureLeadingSlash(endpointPath);
+  const finalEndpointPath = normalizedEndpointPath === '/' ? '' : endpointPath;
+  if (!normalizedPrefix && !finalEndpointPath) {
+    return '/';
+  }
+  return `${normalizedPrefix}${finalEndpointPath || ''}`;
+}
+
+function resolveEffectApiId(api: HttpApiLike): string {
+  const fallback = 'EffectHttpApi';
+  if (
+    'identifier' in api &&
+    typeof api.identifier === 'string' &&
+    api.identifier
+  ) {
+    return api.identifier;
+  }
+  return fallback;
+}
+
+export function collectEffectEndpoints(
+  reflect: HttpApiReflect,
+  api: HttpApiLike,
+  prefix: string,
+): EffectEndpointMeta[] {
+  const endpoints: EffectEndpointMeta[] = [];
+  const apiId = resolveEffectApiId(api);
+  reflect(api, {
+    onGroup: () => {
+      // no-op
+    },
+    onEndpoint: ({ group, endpoint }) => {
+      endpoints.push({
+        apiId,
+        groupName: String(group.identifier),
+        endpointName: resolveEffectEndpointName(endpoint),
+        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);
+  });
+}
+
+/**
+ * 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 function toOperationContractSources(
+  endpoints: EffectEndpointMeta[],
+): OperationContractSource[] {
+  return endpoints.map(createEffectOperationContractSource);
+}
+
+function createEffectOperationContractSource(
+  endpoint: EffectEndpointMeta,
+): OperationContractSource {
+  return {
+    name: endpoint.endpointName,
+    httpMethod: endpoint.method,
+    routePath: endpoint.routePath,
+  };
+}
+
+/**
+ * Extracts the HttpApi instance from a loaded effect entry module. Mirrors
+ * the shared entry-shape policy accepted by `resolveEffectBffModuleHandler`,
+ * without executing factories during contract extraction.
+ */
+export async function extractHttpApiFromModule(
+  mod: unknown,
+  isHttpApi: (value: unknown) => boolean,
+): Promise<HttpApiLike | null> {
+  const facts = classifyEffectBffEntryModule(mod, {
+    isRequestHandler: value => typeof value === 'function',
+    isValidatorAwareHandlerFactory,
+    isHttpApi,
+  });
+  return facts?.legacyShape ||
+    facts?.api === undefined ||
+    !facts.hasRuntimeLayer ||
+    (facts.createHandler !== undefined && !facts.createHandlerValidatorAware)
+    ? null
+    : (facts.api as HttpApiLike);
+}
+
+/**
+ * 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 function createEffectEndpointContractHash(
+  endpoint: EffectEndpointMeta,
+  requestId: string,
+): string {
+  return createOperationContractHash(
+    createEffectOperationContractSource(endpoint),
+    requestId,
+  );
+}

package/src/effect/entry-shape-registry.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+const validatorAwareHandlerFactories = new WeakSet();
+
+module.exports = {
+  register(factory) {
+    validatorAwareHandlerFactories.add(factory);
+    return factory;
+  },
+  is(factory) {
+    return (
+      typeof factory === 'function' &&
+      validatorAwareHandlerFactories.has(factory)
+    );
+  },
+};

package/src/effect/entry-shape-registry.d.cts

@@ -0,0 +1,6 @@
+declare const registry: {
+  register<TFactory extends Function>(factory: TFactory): TFactory;
+  is(factory: unknown): boolean;
+};
+
+export = registry;

package/src/effect/entry-shape.ts

@@ -0,0 +1,155 @@
+type ValidatorAwareHandlerFactoryRegistry = {
+  register<TFactory extends Function>(factory: TFactory): TFactory;
+  is(factory: unknown): boolean;
+};
+
+function createLocalValidatorAwareHandlerFactoryRegistry(): ValidatorAwareHandlerFactoryRegistry {
+  const factories = new WeakSet<Function>();
+  return {
+    register<TFactory extends Function>(factory: TFactory): TFactory {
+      factories.add(factory);
+      return factory;
+    },
+    is(factory: unknown): boolean {
+      return typeof factory === 'function' && factories.has(factory);
+    },
+  };
+}
+
+function loadNodeValidatorAwareHandlerFactoryRegistry(): ValidatorAwareHandlerFactoryRegistry {
+  const moduleUrl = import.meta.url;
+  if (typeof moduleUrl !== 'string' || !moduleUrl.startsWith('file:')) {
+    return createLocalValidatorAwareHandlerFactoryRegistry();
+  }
+
+  const moduleBuiltin = process.getBuiltinModule(
+    'node:module',
+  ) as typeof import('node:module');
+  try {
+    return moduleBuiltin.createRequire(moduleUrl)(
+      `#effect-entry-shape-${'registry'}`,
+    ) as ValidatorAwareHandlerFactoryRegistry;
+  } catch (error) {
+    if (
+      error !== null &&
+      typeof error === 'object' &&
+      'code' in error &&
+      error.code === 'MODULE_NOT_FOUND'
+    ) {
+      return createLocalValidatorAwareHandlerFactoryRegistry();
+    }
+    throw error;
+  }
+}
+
+const validatorAwareHandlerFactoryRegistry =
+  process.env.MODERN_EFFECT_NODE_RUNTIME === 'true'
+    ? loadNodeValidatorAwareHandlerFactoryRegistry()
+    : createLocalValidatorAwareHandlerFactoryRegistry();
+
+type EffectBffEntryModule = {
+  api?: unknown;
+  layer?: unknown;
+  handler?: unknown;
+  createHandler?: unknown;
+  default?: unknown;
+};
+
+type LegacyEffectBffEntryShape = '`handler` export' | 'default request handler';
+
+export type EffectBffEntryShapeFacts = {
+  module: EffectBffEntryModule;
+  legacyShape?: LegacyEffectBffEntryShape;
+  createHandler?: unknown;
+  createHandlerValidatorAware: boolean;
+  api?: unknown;
+  layer?: unknown;
+  hasRuntimeLayer: boolean;
+};
+
+type EffectBffEntryShapePredicates = {
+  isRequestHandler: (value: unknown) => boolean;
+  isValidatorAwareHandlerFactory: (value: unknown) => boolean;
+  isHttpApi: (value: unknown) => boolean;
+};
+
+/** @internal Registers factories created by `defineEffectBff`. */
+export function registerValidatorAwareHandlerFactory<TFactory extends Function>(
+  factory: TFactory,
+): TFactory {
+  return validatorAwareHandlerFactoryRegistry.register(factory);
+}
+
+/**
+ * True when a custom createHandler factory is produced by defineEffectBff and
+ * therefore forwards strict cross-project validation into createHttpApiHandler.
+ */
+export function isValidatorAwareHandlerFactory(factory: unknown): boolean {
+  return validatorAwareHandlerFactoryRegistry.is(factory);
+}
+
+export 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: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+export function classifyEffectBffEntryModule(
+  value: unknown,
+  predicates: EffectBffEntryShapePredicates,
+): EffectBffEntryShapeFacts | null {
+  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: EffectBffEntryModule,
+  predicates: EffectBffEntryShapePredicates,
+  legacyShape?: LegacyEffectBffEntryShape,
+): EffectBffEntryShapeFacts {
+  const createHandler =
+    typeof module.createHandler === 'function'
+      ? module.createHandler
+      : undefined;
+  const api = predicates.isHttpApi(module.api) ? module.api : undefined;
+  const hasRuntimeLayer = module.layer !== undefined;
+
+  return {
+    module,
+    legacyShape,
+    createHandler,
+    createHandlerValidatorAware:
+      createHandler !== undefined &&
+      predicates.isValidatorAwareHandlerFactory(createHandler),
+    api,
+    layer: module.layer,
+    hasRuntimeLayer,
+  };
+}