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

package/src/effect/handler/definition.ts

@@ -0,0 +1,121 @@
+// @effect-diagnostics anyUnknownInErrorContext:off asyncFunction:off globalDate:off globalTimers:off newPromise:off strictBooleanExpressions:off
+import type { HttpApi } from 'effect/unstable/httpapi';
+import type { Rpc } from 'effect/unstable/rpc';
+
+import { registerValidatorAwareHandlerFactory } from '../entry-shape';
+import { mergeDataPlatformOptions } from './envelope';
+import { createHttpApiHandler } from './http';
+import { createRpcApiHandler } from './rpc';
+import type {
+  EffectApiPromiseClientFromApi,
+  EffectBffDefinition,
+  EffectBffHandlerFactory,
+  EffectBffRuntime,
+  EffectDataPlatformValidationOptions,
+  EffectRpcBffDefinition,
+  EffectRpcBffHandlerFactory,
+  EffectRpcRuntimeLayer,
+  EffectRuntimeLayer,
+} from './types';
+
+export function defineEffectBff<
+  TApi extends HttpApi.Constraint,
+  TLayer extends EffectRuntimeLayer,
+  TRpcs extends Rpc.Any = Rpc.Any,
+>(
+  definition: EffectBffDefinition<TApi, TLayer, TRpcs>,
+): EffectBffDefinition<TApi, TLayer, TRpcs> & EffectBffRuntime<TApi, TLayer> {
+  const createHandler = registerValidatorAwareHandlerFactory<
+    EffectBffHandlerFactory<TApi, TLayer>
+  >(options => {
+    const rpcDefinition = definition.rpc;
+    let mergedRpcOptions: EffectRpcBffDefinition<TRpcs> | undefined =
+      rpcDefinition;
+    if (rpcDefinition && options?.rpc) {
+      mergedRpcOptions = {
+        ...rpcDefinition,
+        ...options.rpc,
+      };
+    }
+
+    return createHttpApiHandler<TApi, TRpcs>({
+      api: definition.api,
+      layer: definition.layer,
+      openapi: options?.openapi,
+      rpc: mergedRpcOptions,
+      dataPlatform: mergeDataPlatformOptions(
+        definition.dataPlatform,
+        options?.dataPlatform,
+      ),
+      interceptRequest: definition.interceptRequest,
+      validateRequest: options?.validateRequest,
+    });
+  });
+  const client = createLoaderMaterializedClientPlaceholder<TApi>();
+  return {
+    ...definition,
+    createHandler,
+    client,
+  };
+}
+
+const LOADER_CLIENT_IGNORED_KEYS = new Set<PropertyKey>([
+  'then',
+  'catch',
+  'finally',
+  'toJSON',
+  '$$typeof',
+]);
+
+/**
+ * `defineEffectBff(...).client` is only materialized when the entry module
+ * is imported through the `@api/index` transform (the webpack/rspack
+ * loader swaps the module for generated client code). Importing the entry
+ * directly (server code, scripts, tests) used to return a `client` typed as
+ * fully functional but `undefined` at runtime — a bare TypeError with zero
+ * explanation. This placeholder keeps the type contract while failing with
+ * an actionable error on first property access.
+ */
+function createLoaderMaterializedClientPlaceholder<
+  TApi extends HttpApi.Constraint,
+>(): EffectApiPromiseClientFromApi<TApi> {
+  const explain = (property: PropertyKey): never => {
+    throw new Error(
+      `[BFF][Effect] client.${String(property)} is not available here: the typed client only exists when the API entry is imported through the "@api/index" transformed path (the BFF loader replaces it with generated client code). On the server, use HttpApiClient or call the Effect layer directly.`,
+    );
+  };
+
+  return new Proxy(Object.create(null), {
+    get(_target, property) {
+      // Keep async/inspection protocols (await, console.log, React internals)
+      // from throwing so the placeholder stays inert until really used.
+      if (
+        typeof property === 'symbol' ||
+        LOADER_CLIENT_IGNORED_KEYS.has(property)
+      ) {
+        return undefined;
+      }
+      return explain(property);
+    },
+  }) as EffectApiPromiseClientFromApi<TApi>;
+}
+
+export function defineEffectRpcBff<
+  TRpcs extends Rpc.Any = Rpc.Any,
+  TLayer extends EffectRpcRuntimeLayer<TRpcs> = EffectRpcRuntimeLayer<TRpcs>,
+>(
+  definition: EffectRpcBffDefinition<TRpcs, TLayer>,
+): EffectRpcBffDefinition<TRpcs, TLayer> & {
+  createHandler: EffectRpcBffHandlerFactory<TRpcs>;
+} {
+  const createHandler: EffectRpcBffHandlerFactory<TRpcs> = options =>
+    createRpcApiHandler({
+      ...definition,
+      ...options,
+    });
+
+  return {
+    ...definition,
+    createHandler,
+  };
+}

package/src/effect/handler/envelope.ts

@@ -0,0 +1,133 @@
+// @effect-diagnostics anyUnknownInErrorContext:off asyncFunction:off globalDate:off globalTimers:off newPromise:off strictBooleanExpressions:off
+import {
+  DEFAULT_DATA_ENVELOPE_HEADER,
+  decodeRequestEnvelopeHeader,
+  validateRequestEnvelope,
+  validateSelectionPlan,
+} from '../../data-platform';
+
+import { getExpectedEnvelopeOrigin } from './routing';
+import type { EffectDataPlatformValidationOptions } from './types';
+
+function createInvalidEnvelopeResponse(message: string, errors?: string[]) {
+  return new Response(
+    JSON.stringify({
+      message,
+      ...(errors && errors.length > 0 ? { errors } : {}),
+    }),
+    {
+      status: 400,
+      headers: {
+        'content-type': 'application/json; charset=utf-8',
+      },
+    },
+  );
+}
+
+/**
+ * Validates the `x-modernjs-data-envelope` header (the data-platform
+ * transport/cache contract: protocol version, scope, selection plan).
+ *
+ * This is NOT a security boundary: the envelope is client-constructed cache
+ * metadata used for batching, scope keys and hydration. Cross-project
+ * authorization runs through the bff-core policy evaluator wired in via
+ * `validateRequest` (see `EffectRequestValidator`), which both the direct
+ * and batched request paths hit before this check.
+ */
+
+export function validateDataPlatformRequestEnvelope(
+  request: Request,
+  options: EffectDataPlatformValidationOptions | undefined,
+) {
+  const isEnabled = options?.enabled ?? true;
+  if (!isEnabled) {
+    return null;
+  }
+
+  const envelopeHeader =
+    options?.envelopeHeader || DEFAULT_DATA_ENVELOPE_HEADER;
+  const encodedEnvelope = request.headers.get(envelopeHeader);
+
+  if (!encodedEnvelope) {
+    if (options?.requireEnvelope) {
+      return createInvalidEnvelopeResponse(
+        `Missing required data envelope header: ${envelopeHeader}`,
+      );
+    }
+    return null;
+  }
+
+  const envelope = decodeRequestEnvelopeHeader(encodedEnvelope);
+  if (!envelope) {
+    return createInvalidEnvelopeResponse(
+      `Invalid data envelope header format: ${envelopeHeader}`,
+    );
+  }
+
+  const validation = validateRequestEnvelope(envelope, {
+    expectedProtocolVersion: 1,
+    expectedNamespace: options?.expectedNamespace,
+    expectedOrigin:
+      options?.validateOrigin === false
+        ? undefined
+        : getExpectedEnvelopeOrigin(request),
+    requireTraceContext: options?.requireTraceContext,
+  });
+
+  if (!validation.ok) {
+    return createInvalidEnvelopeResponse(
+      'Invalid data envelope',
+      validation.errors,
+    );
+  }
+
+  if (envelope.selectionPlan) {
+    const selectionValidation = validateSelectionPlan(envelope.selectionPlan, {
+      maxDepth: options?.selection?.maxDepth,
+      maxFields: options?.selection?.maxFields,
+      allowedLeafPaths: options?.selection?.allowedLeafPaths,
+    });
+
+    if (!selectionValidation.ok) {
+      return createInvalidEnvelopeResponse(
+        'Invalid data envelope selection plan',
+        selectionValidation.errors,
+      );
+    }
+  }
+
+  return null;
+}
+
+export function mergeDataPlatformOptions(
+  base: EffectDataPlatformValidationOptions | undefined,
+  override: Partial<EffectDataPlatformValidationOptions> | undefined,
+): EffectDataPlatformValidationOptions | undefined {
+  if (!base && !override) {
+    return undefined;
+  }
+
+  const baseSelection = base?.selection;
+  const overrideSelection = override?.selection;
+  const baseBatch = base?.batch;
+  const overrideBatch = override?.batch;
+
+  return {
+    ...base,
+    ...override,
+    selection:
+      baseSelection || overrideSelection
+        ? {
+            ...baseSelection,
+            ...overrideSelection,
+          }
+        : undefined,
+    batch:
+      baseBatch || overrideBatch
+        ? {
+            ...baseBatch,
+            ...overrideBatch,
+          }
+        : undefined,
+  };
+}

package/src/effect/handler/http.ts

@@ -0,0 +1,133 @@
+// @effect-diagnostics anyUnknownInErrorContext:off asyncFunction:off globalDate:off globalTimers:off newPromise:off strictBooleanExpressions:off
+import * as Layer from 'effect/Layer';
+import { HttpRouter, HttpServer } from 'effect/unstable/http';
+import type { HttpApi } from 'effect/unstable/httpapi';
+import type { Rpc } from 'effect/unstable/rpc';
+
+import { prepareJsonRequestBody } from './batch';
+import { createDataPlatformBatchRequestHandler } from './batch-handler';
+import { validateDataPlatformRequestEnvelope } from './envelope';
+import { createOpenApiLayer } from './openapi';
+import { getRequestPathname, isRpcRequest } from './routing';
+import { createRpcApiHandler, normalizeRpcPath } from './rpc';
+import type {
+  EffectBffOpenApiConfig,
+  EffectDataPlatformValidationOptions,
+  EffectRequestInterceptor,
+  EffectRequestValidator,
+  EffectRpcBffDefinition,
+  EffectRuntimeLayer,
+} from './types';
+import { toEffectServiceContext } from './types';
+
+export function createHttpApiHandler<
+  TApi extends HttpApi.Constraint = HttpApi.Top,
+  TRpcs extends Rpc.Any = Rpc.Any,
+>(options: {
+  api: TApi;
+  layer: EffectRuntimeLayer;
+  openapi?: EffectBffOpenApiConfig;
+  rpc?: EffectRpcBffDefinition<TRpcs>;
+  dataPlatform?: EffectDataPlatformValidationOptions;
+  interceptRequest?: EffectRequestInterceptor;
+  validateRequest?: EffectRequestValidator;
+}) {
+  const apiLayer = options.layer.pipe(Layer.provide(HttpServer.layerServices));
+  const openApiLayer = createOpenApiLayer(options.api, options.openapi);
+  const mergedLayer = openApiLayer
+    ? Layer.mergeAll(apiLayer, openApiLayer)
+    : apiLayer;
+  const httpApiHandler = HttpRouter.toWebHandler(mergedLayer);
+
+  const dispatchHttpApiRequest = async (
+    request: Request,
+    context?: Parameters<typeof httpApiHandler.handler>[1],
+  ) => {
+    const preparedRequest = await prepareJsonRequestBody(request);
+    if (preparedRequest instanceof Response) {
+      return preparedRequest;
+    }
+    const validationError = validateDataPlatformRequestEnvelope(
+      preparedRequest,
+      options.dataPlatform,
+    );
+    if (validationError) {
+      return validationError;
+    }
+    return httpApiHandler.handler(
+      preparedRequest,
+      toEffectServiceContext(context),
+    );
+  };
+
+  const withRequestPolicy = async (
+    request: Request,
+    context?: Parameters<typeof httpApiHandler.handler>[1],
+  ) => {
+    // Policy seam first: every HttpApi request, direct or batched item,
+    // passes through here, so batch fan-out cannot bypass validator. The
+    // interceptor receives the original request and may own malformed or
+    // legacy payloads; delegated requests still pass through body validation.
+    const policyDenial = options.validateRequest?.(request);
+    if (policyDenial) {
+      return policyDenial;
+    }
+    const next = () => dispatchHttpApiRequest(request, context);
+    return options.interceptRequest
+      ? options.interceptRequest({ request, next })
+      : next();
+  };
+
+  const batchHandler = createDataPlatformBatchRequestHandler({
+    dataPlatform: options.dataPlatform,
+    handleItem: withRequestPolicy,
+  });
+
+  const handleHttpApiRequest = async (
+    request: Request,
+    context?: Parameters<typeof httpApiHandler.handler>[1],
+  ) => {
+    const pathname = getRequestPathname(request);
+    if (batchHandler.enabled && pathname === batchHandler.path) {
+      // Outer batch POST transport, not an API operation: each batched item is
+      // dispatched through withDataPlatformValidation and hits policy handling.
+      return batchHandler.handle(request, context);
+    }
+    return withRequestPolicy(request, context);
+  };
+
+  if (!options.rpc) {
+    return {
+      handler: handleHttpApiRequest,
+      dispose: async () => {
+        await httpApiHandler.dispose();
+      },
+    };
+  }
+
+  const rpcPath = normalizeRpcPath(options.rpc.path);
+  const rpcHandler = createRpcApiHandler(options.rpc);
+
+  return {
+    handler: async (
+      request: Request,
+      context?: Parameters<typeof httpApiHandler.handler>[1],
+    ) => {
+      if (isRpcRequest(request, rpcPath)) {
+        const policyDenial = options.validateRequest?.(request);
+        if (policyDenial) {
+          return policyDenial;
+        }
+        const next = () =>
+          rpcHandler.handler(request, toEffectServiceContext(context));
+        return options.interceptRequest
+          ? options.interceptRequest({ request, next })
+          : next();
+      }
+      return handleHttpApiRequest(request, context);
+    },
+    dispose: async () => {
+      await Promise.all([httpApiHandler.dispose(), rpcHandler.dispose()]);
+    },
+  };
+}

package/src/effect/handler/openapi.ts

@@ -0,0 +1,45 @@
+// @effect-diagnostics anyUnknownInErrorContext:off asyncFunction:off globalDate:off globalTimers:off newPromise:off strictBooleanExpressions:off
+import { HttpRouter, HttpServerResponse } from 'effect/unstable/http';
+import { type HttpApi, OpenApi } from 'effect/unstable/httpapi';
+
+import type { EffectBffOpenApiConfig } from './types';
+
+const DEFAULT_OPENAPI_PATH = '/openapi.json';
+
+function normalizeOpenApiPath(pathname: string) {
+  if (!pathname.startsWith('/')) {
+    return `/${pathname}` as `/${string}`;
+  }
+  return pathname as `/${string}`;
+}
+
+function getOpenApiOptions(openapi: EffectBffOpenApiConfig | undefined) {
+  if (openapi === false || openapi === undefined) {
+    return undefined;
+  }
+
+  const path = openapi === true ? DEFAULT_OPENAPI_PATH : openapi.path;
+  return {
+    path: normalizeOpenApiPath(path ?? DEFAULT_OPENAPI_PATH),
+  };
+}
+
+export function createOpenApiLayer(
+  api: HttpApi.Constraint,
+  openapi: EffectBffOpenApiConfig | undefined,
+) {
+  const openApiOptions = getOpenApiOptions(openapi);
+  if (!openApiOptions) {
+    return null;
+  }
+
+  // effect 4.0.0-beta.98 made `HttpApi`'s `Groups` parameter invariant, so no
+  // concrete api is assignable to the widened `HttpApi.Top` instance type.
+  // `HttpApi.Constraint` is the erased bound every api satisfies; `fromApi`
+  // only reads runtime properties, which `Top` preserves.
+  return HttpRouter.add(
+    'GET',
+    openApiOptions.path,
+    HttpServerResponse.jsonUnsafe(OpenApi.fromApi(api as HttpApi.Top)),
+  );
+}

package/src/effect/handler/routing.ts

@@ -0,0 +1,91 @@
+// @effect-diagnostics anyUnknownInErrorContext:off asyncFunction:off globalDate:off globalTimers:off newPromise:off strictBooleanExpressions:off
+import { isPlainObject } from '../../data-platform';
+
+export function getRequestPathname(request: Request) {
+  try {
+    return new URL(request.url).pathname;
+  } catch {
+    return new URL(request.url, 'http://localhost').pathname;
+  }
+}
+
+function normalizeMountPrefix(prefix: string) {
+  if (!prefix || prefix === '/') {
+    return '';
+  }
+  return prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
+}
+
+export function getMountedPrefixFromContext(
+  request: Request,
+  context: unknown,
+): string {
+  if (!isPlainObject(context) || typeof context.path !== 'string') {
+    return '';
+  }
+
+  const contextPath = normalizeMountPrefix(context.path);
+  const requestPath = normalizeMountPrefix(getRequestPathname(request));
+
+  if (
+    !contextPath ||
+    !requestPath ||
+    contextPath === requestPath ||
+    !contextPath.endsWith(requestPath)
+  ) {
+    return '';
+  }
+
+  return normalizeMountPrefix(
+    contextPath.slice(0, contextPath.length - requestPath.length),
+  );
+}
+
+export function removeMountedPrefixFromBatchPath(
+  pathWithQuery: string,
+  prefix: string,
+) {
+  const normalizedPrefix = normalizeMountPrefix(prefix);
+  if (!normalizedPrefix) {
+    return pathWithQuery;
+  }
+
+  const [pathname, ...queryParts] = pathWithQuery.split('?');
+  if (!pathname) {
+    return pathWithQuery;
+  }
+
+  let nextPathname = pathname;
+  if (pathname === normalizedPrefix) {
+    nextPathname = '/';
+  } else if (pathname.startsWith(`${normalizedPrefix}/`)) {
+    const sliced = pathname.slice(normalizedPrefix.length);
+    nextPathname = sliced.startsWith('/') ? sliced : `/${sliced}`;
+  }
+
+  if (queryParts.length === 0) {
+    return nextPathname;
+  }
+  return `${nextPathname}?${queryParts.join('?')}`;
+}
+
+function getRequestOrigin(request: Request) {
+  try {
+    return new URL(request.url).origin;
+  } catch {
+    return new URL(request.url, 'http://localhost').origin;
+  }
+}
+
+export function getExpectedEnvelopeOrigin(request: Request) {
+  const origin = request.headers.get('origin');
+  if (origin && origin !== 'null') {
+    return origin;
+  }
+  return getRequestOrigin(request);
+}
+
+export function isRpcRequest(request: Request, rpcPath: `/${string}`) {
+  const pathname = getRequestPathname(request);
+  return pathname === rpcPath || pathname.startsWith(`${rpcPath}/`);
+}

package/src/effect/handler/rpc.ts

@@ -0,0 +1,45 @@
+// @effect-diagnostics anyUnknownInErrorContext:off asyncFunction:off globalDate:off globalTimers:off newPromise:off strictBooleanExpressions:off
+import * as Layer from 'effect/Layer';
+import { HttpRouter } from 'effect/unstable/http';
+import { type Rpc, RpcServer } from 'effect/unstable/rpc';
+
+import { getRpcSerializationLayer } from '../rpcSerialization';
+import type { EffectRpcBffDefinition } from './types';
+
+export function normalizeRpcPath(pathname: string | undefined) {
+  if (!pathname || pathname === '/') {
+    return '/rpc' as `/${string}`;
+  }
+  if (!pathname.startsWith('/')) {
+    return `/${pathname}` as `/${string}`;
+  }
+  return pathname as `/${string}`;
+}
+
+export function createRpcApiHandler<TRpcs extends Rpc.Any = Rpc.Any>(
+  options: EffectRpcBffDefinition<TRpcs>,
+) {
+  const rpcPath = normalizeRpcPath(options.path);
+  const rpcLayer = Layer.provide(
+    RpcServer.layerHttp({
+      group: options.group,
+      path: rpcPath,
+      protocol: 'http',
+      disableTracing: options.disableTracing,
+      spanPrefix: options.spanPrefix,
+      spanAttributes: options.spanAttributes,
+    }),
+    Layer.mergeAll(
+      options.layer,
+      getRpcSerializationLayer(options.serialization),
+    ),
+  );
+
+  return HttpRouter.toWebHandler<
+    never,
+    unknown,
+    HttpRouter.HttpRouter,
+    never,
+    never
+  >(rpcLayer);
+}