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

package/src/effect/handler/batch-handler.ts

@@ -0,0 +1,475 @@
+// @effect-diagnostics anyUnknownInErrorContext:off asyncFunction:off globalDate:off globalTimers:off newPromise:off strictBooleanExpressions:off
+import {
+  type DataBatchResponsePayload,
+  DEFAULT_DATA_BATCH_HEADER,
+  DEFAULT_DATA_ENVELOPE_HEADER,
+  decodeRequestEnvelopeHeader,
+  isPlainObject,
+  normalizeMethod as normalizeItemMethod,
+} from '../../data-platform';
+import {
+  decodeBatchBody,
+  isBatchBody,
+  toBatchResponseItem,
+} from '../../data-platform/batch/protocol';
+import {
+  BatchItemTimeoutError,
+  createBatchValidationResponse,
+  isBatchRequestPayload,
+  mapWithConcurrency,
+  normalizeBatchAllowedMethods,
+  normalizeBatchPath,
+  promiseWithTimeout,
+  toBatchItemError,
+} from './batch';
+import {
+  getMountedPrefixFromContext,
+  removeMountedPrefixFromBatchPath,
+} from './routing';
+import type { EffectDataPlatformValidationOptions } from './types';
+
+type DataPlatformBatchItemHandler<TContext> = (
+  request: Request,
+  context?: TContext,
+) => Promise<unknown>;
+
+const HOP_BY_HOP_BATCH_ITEM_HEADERS = new Set([
+  'connection',
+  'keep-alive',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'proxy-connection',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+]);
+
+const OUTER_BOUND_BATCH_ITEM_HEADERS = new Set([
+  'authorization',
+  'cookie',
+  'forwarded',
+  'origin',
+  'referer',
+  'sec-fetch-dest',
+  'sec-fetch-mode',
+  'sec-fetch-site',
+  'sec-fetch-user',
+  'x-forwarded-client-cert',
+  'x-forwarded-for',
+  'x-forwarded-host',
+  'x-forwarded-port',
+  'x-forwarded-proto',
+  'x-real-ip',
+  'x-subject-id',
+  'x-tenant-id',
+  'x-user-id',
+  'x-verified-producer',
+]);
+
+const TRANSPORT_CONTROLLED_BATCH_ITEM_HEADERS = new Set([
+  'content-length',
+  'host',
+  ...HOP_BY_HOP_BATCH_ITEM_HEADERS,
+]);
+
+type BoundedRequestBodyResult =
+  | { status: 'ok'; text: string }
+  | { status: 'invalid-content-length' }
+  | { status: 'read-error' }
+  | { status: 'too-large' };
+
+async function readRequestTextWithinLimit(
+  request: Request,
+  maxBytes: number,
+): Promise<BoundedRequestBodyResult> {
+  const contentLength = request.headers.get('content-length');
+  if (contentLength !== null) {
+    if (!/^\d+$/.test(contentLength)) {
+      return { status: 'invalid-content-length' };
+    }
+    if (BigInt(contentLength) > BigInt(maxBytes)) {
+      return { status: 'too-large' };
+    }
+  }
+  if (request.body === null) {
+    return { status: 'ok', text: '' };
+  }
+
+  const reader = request.body.getReader();
+  const decoder = new TextDecoder();
+  const text: string[] = [];
+  let bytesRead = 0;
+  try {
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done) {
+        text.push(decoder.decode());
+        return { status: 'ok', text: text.join('') };
+      }
+      bytesRead += chunk.value.byteLength;
+      if (bytesRead > maxBytes) {
+        await reader.cancel('batch-payload-too-large');
+        return { status: 'too-large' };
+      }
+      text.push(decoder.decode(chunk.value, { stream: true }));
+    }
+  } catch {
+    return { status: 'read-error' };
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+export function createDataPlatformBatchRequestHandler<TContext>(options: {
+  dataPlatform?: EffectDataPlatformValidationOptions;
+  handleItem: DataPlatformBatchItemHandler<TContext>;
+}) {
+  const dataPlatformBatchOptions = options.dataPlatform?.batch;
+  const batchEnabled = dataPlatformBatchOptions?.enabled !== false;
+  const batchPath = normalizeBatchPath(dataPlatformBatchOptions?.endpoint);
+  const batchMaxSize = Math.max(
+    1,
+    dataPlatformBatchOptions?.maxBatchSize ?? 16,
+  );
+  const batchMaxBytes = Math.max(
+    1024,
+    dataPlatformBatchOptions?.maxBatchBytes ?? 64 * 1024,
+  );
+  const batchConcurrency = Math.max(
+    1,
+    dataPlatformBatchOptions?.maxConcurrency ?? 4,
+  );
+  const batchItemTimeoutMs = Math.max(
+    0,
+    dataPlatformBatchOptions?.requestTimeoutMs ?? 10_000,
+  );
+  const batchAllowedMethods = normalizeBatchAllowedMethods(
+    dataPlatformBatchOptions?.allowedMethods,
+  );
+  const envelopeHeader =
+    options.dataPlatform?.envelopeHeader || DEFAULT_DATA_ENVELOPE_HEADER;
+  const normalizedEnvelopeHeader = envelopeHeader.toLowerCase();
+
+  const handle = async (request: Request, context?: TContext) => {
+    const mountedPrefix = getMountedPrefixFromContext(request, context);
+    const method = normalizeItemMethod(request.method);
+    if (method !== 'POST') {
+      return createBatchValidationResponse(
+        'Batch endpoint only supports POST requests',
+        405,
+      );
+    }
+
+    const contentType = request.headers.get('content-type') || '';
+    if (!contentType.includes('application/json')) {
+      return createBatchValidationResponse(
+        'Batch endpoint requires application/json content-type',
+        415,
+      );
+    }
+
+    const bodyResult = await readRequestTextWithinLimit(request, batchMaxBytes);
+    if (bodyResult.status === 'too-large') {
+      return createBatchValidationResponse(
+        `Batch payload exceeds max size (${String(batchMaxBytes)} bytes)`,
+        413,
+      );
+    }
+    if (bodyResult.status === 'invalid-content-length') {
+      return createBatchValidationResponse(
+        'Batch payload has invalid content-length',
+      );
+    }
+    if (bodyResult.status === 'read-error') {
+      return createBatchValidationResponse('Unable to read batch payload');
+    }
+    const payloadText = bodyResult.text;
+
+    let payload: unknown;
+    try {
+      payload = JSON.parse(payloadText);
+    } catch {
+      return createBatchValidationResponse('Invalid batch payload JSON');
+    }
+
+    if (!isBatchRequestPayload(payload)) {
+      return createBatchValidationResponse('Invalid batch payload shape');
+    }
+
+    if (payload.items.length === 0) {
+      return createBatchValidationResponse(
+        'Batch payload items cannot be empty',
+      );
+    }
+
+    if (payload.items.length > batchMaxSize) {
+      return createBatchValidationResponse(
+        `Batch item count exceeds max size (${String(batchMaxSize)})`,
+        413,
+      );
+    }
+
+    const batchRequestOrigin = new URL(request.url).origin;
+    const responseItems = await mapWithConcurrency(
+      payload.items,
+      batchConcurrency,
+      async (rawItem, index) => {
+        const fallbackId = `item_${String(index)}`;
+        const itemId =
+          isPlainObject(rawItem) && typeof rawItem.id === 'string'
+            ? rawItem.id
+            : fallbackId;
+
+        if (!isPlainObject(rawItem)) {
+          return toBatchItemError(
+            itemId,
+            400,
+            'Invalid batch item; expected object',
+          );
+        }
+
+        if (typeof rawItem.path !== 'string' || rawItem.path.length === 0) {
+          return toBatchItemError(itemId, 400, 'Invalid batch item path');
+        }
+
+        if (!rawItem.path.startsWith('/')) {
+          return toBatchItemError(
+            itemId,
+            400,
+            'Batch item path must start with "/"',
+          );
+        }
+
+        const normalizedItemPath = removeMountedPrefixFromBatchPath(
+          rawItem.path,
+          mountedPrefix,
+        );
+        const itemPathname =
+          normalizedItemPath.split('?')[0] || normalizedItemPath;
+        if (
+          itemPathname === batchPath ||
+          itemPathname.startsWith(`${batchPath}/`)
+        ) {
+          return toBatchItemError(
+            itemId,
+            400,
+            'Batch item path cannot target batch endpoint',
+          );
+        }
+
+        const itemMethod = normalizeItemMethod(
+          typeof rawItem.method === 'string' ? rawItem.method : undefined,
+        );
+        if (!batchAllowedMethods.has(itemMethod)) {
+          return toBatchItemError(
+            itemId,
+            405,
+            `Batch item method ${itemMethod} is not allowed`,
+          );
+        }
+
+        if (typeof rawItem.body !== 'undefined' && !isBatchBody(rawItem.body)) {
+          return toBatchItemError(
+            itemId,
+            400,
+            'Batch item body must use the base64 body protocol',
+          );
+        }
+
+        if (
+          (itemMethod === 'GET' || itemMethod === 'HEAD') &&
+          typeof rawItem.body !== 'undefined'
+        ) {
+          return toBatchItemError(
+            itemId,
+            400,
+            `${itemMethod} batch item cannot include body`,
+          );
+        }
+
+        const normalizedHeaders: Record<string, string> = {};
+        if (typeof rawItem.headers !== 'undefined') {
+          if (!isPlainObject(rawItem.headers)) {
+            return toBatchItemError(
+              itemId,
+              400,
+              'Batch item headers must be an object',
+            );
+          }
+
+          for (const [key, value] of Object.entries(rawItem.headers)) {
+            if (typeof value !== 'string') {
+              return toBatchItemError(
+                itemId,
+                400,
+                `Invalid header "${key}" for batch item`,
+              );
+            }
+            normalizedHeaders[key.toLowerCase()] = value;
+          }
+        }
+
+        const connectionScopedHeaders = new Set(
+          (normalizedHeaders.connection || '')
+            .split(',')
+            .map(header => header.trim().toLowerCase())
+            .filter(Boolean),
+        );
+        for (const header of Object.keys(normalizedHeaders)) {
+          if (
+            TRANSPORT_CONTROLLED_BATCH_ITEM_HEADERS.has(header) ||
+            OUTER_BOUND_BATCH_ITEM_HEADERS.has(header) ||
+            connectionScopedHeaders.has(header)
+          ) {
+            delete normalizedHeaders[header];
+          }
+        }
+
+        if (!normalizedHeaders.traceparent) {
+          const encodedEnvelope = normalizedHeaders[normalizedEnvelopeHeader];
+          if (typeof encodedEnvelope === 'string') {
+            const envelope = decodeRequestEnvelopeHeader(encodedEnvelope);
+            if (envelope?.traceparent) {
+              normalizedHeaders.traceparent = envelope.traceparent;
+            }
+          }
+        }
+
+        // Authentication, verified identity, and network-origin context belong
+        // to the authenticated outer request. Batch items may carry application
+        // and operation metadata, but cannot manufacture or replace this context.
+        for (const header of OUTER_BOUND_BATCH_ITEM_HEADERS) {
+          const value = request.headers.get(header);
+          if (value !== null) {
+            normalizedHeaders[header] = value;
+          }
+        }
+
+        if (!normalizedHeaders.traceparent) {
+          const requestTraceparent = request.headers.get('traceparent');
+          if (requestTraceparent) {
+            normalizedHeaders.traceparent = requestTraceparent;
+          }
+        }
+
+        const targetUrl = new URL(normalizedItemPath, request.url);
+        if (targetUrl.origin !== batchRequestOrigin) {
+          return toBatchItemError(
+            itemId,
+            400,
+            'Batch item path must stay on the same origin',
+          );
+        }
+        let requestHeaders: Headers;
+        try {
+          requestHeaders = new Headers(normalizedHeaders);
+        } catch {
+          return toBatchItemError(itemId, 400, 'Invalid batch item headers');
+        }
+        const body =
+          itemMethod === 'GET' || itemMethod === 'HEAD'
+            ? undefined
+            : typeof rawItem.body === 'undefined'
+              ? undefined
+              : decodeBatchBody(rawItem.body);
+
+        if (typeof body === 'undefined') {
+          requestHeaders.delete('content-type');
+        }
+
+        const itemAbortController = new AbortController();
+        const abortFromBatchRequest = () =>
+          itemAbortController.abort(request.signal.reason);
+        if (request.signal.aborted) {
+          abortFromBatchRequest();
+        } else {
+          request.signal.addEventListener('abort', abortFromBatchRequest, {
+            once: true,
+          });
+        }
+        const itemRequest = new Request(targetUrl.toString(), {
+          method: itemMethod,
+          headers: requestHeaders,
+          body,
+          signal: itemAbortController.signal,
+        });
+
+        try {
+          const itemResponse = await promiseWithTimeout(
+            options.handleItem(itemRequest, context),
+            batchItemTimeoutMs,
+            error => itemAbortController.abort(error),
+          );
+
+          if (!(itemResponse instanceof Response)) {
+            return toBatchItemError(
+              itemId,
+              500,
+              'Invalid response returned by batch item handler',
+            );
+          }
+
+          return toBatchResponseItem(
+            itemId,
+            itemResponse,
+            itemMethod === 'HEAD',
+          );
+        } catch (error) {
+          if (error instanceof BatchItemTimeoutError) {
+            console.error({
+              event: 'bff.batch.item.timeout',
+              batchId: payload.batchId,
+              itemId,
+              method: itemMethod,
+              path: itemPathname,
+              errorName: error.name,
+            });
+            return toBatchItemError(
+              itemId,
+              504,
+              'Batch item request timed out',
+            );
+          }
+          if (error instanceof Response) {
+            return toBatchResponseItem(itemId, error, itemMethod === 'HEAD');
+          }
+
+          console.error({
+            event: 'bff.batch.item.failure',
+            batchId: payload.batchId,
+            itemId,
+            method: itemMethod,
+            path: itemPathname,
+            errorName: error instanceof Error ? error.name : 'UnknownError',
+          });
+          return toBatchItemError(itemId, 500, 'Internal Server Error');
+        } finally {
+          request.signal.removeEventListener('abort', abortFromBatchRequest);
+        }
+      },
+    );
+
+    const responsePayload: DataBatchResponsePayload = {
+      protocolVersion: 2,
+      batchId: payload.batchId,
+      receivedAt: Date.now(),
+      items: responseItems,
+    };
+
+    return new Response(JSON.stringify(responsePayload), {
+      status: 200,
+      headers: {
+        'content-type': 'application/json; charset=utf-8',
+        [DEFAULT_DATA_BATCH_HEADER]: '2',
+        'x-modernjs-data-batch-id': payload.batchId,
+      },
+    });
+  };
+
+  return {
+    enabled: batchEnabled,
+    path: batchPath,
+    handle,
+  };
+}

package/src/effect/handler/batch.ts

@@ -0,0 +1,182 @@
+// @effect-diagnostics anyUnknownInErrorContext:off asyncFunction:off globalDate:off globalTimers:off newPromise:off strictBooleanExpressions:off
+
+import {
+  type DataBatchRequestPayload,
+  type DataBatchResponseItem,
+  DEFAULT_DATA_BATCH_ENDPOINT,
+  isPlainObject,
+  measureTextBytes,
+  normalizeMethod as normalizeItemMethod,
+} from '../../data-platform';
+import { encodeBatchText } from '../../data-platform/batch/protocol';
+import { toHeaderRecord } from '../../headers';
+
+export { toHeaderRecord } from '../../headers';
+
+export function normalizeBatchPath(pathname: string | undefined) {
+  if (!pathname || pathname === '/') {
+    return DEFAULT_DATA_BATCH_ENDPOINT as `/${string}`;
+  }
+  if (!pathname.startsWith('/')) {
+    return `/${pathname}` as `/${string}`;
+  }
+  return pathname as `/${string}`;
+}
+
+export function normalizeBatchAllowedMethods(
+  allowedMethods: string[] | undefined,
+) {
+  const source =
+    Array.isArray(allowedMethods) && allowedMethods.length > 0
+      ? allowedMethods
+      : ['GET'];
+  return new Set(source.map(method => method.toUpperCase()));
+}
+
+type ParsedBatchRequestPayload = Omit<DataBatchRequestPayload, 'items'> & {
+  items: unknown[];
+};
+
+export function isBatchRequestPayload(
+  value: unknown,
+): value is ParsedBatchRequestPayload {
+  return (
+    isPlainObject(value) &&
+    value.protocolVersion === 2 &&
+    typeof value.batchId === 'string' &&
+    typeof value.sentAt === 'number' &&
+    Array.isArray(value.items)
+  );
+}
+
+export function createBatchValidationResponse(message: string, status = 400) {
+  return new Response(
+    JSON.stringify({
+      message,
+    }),
+    {
+      status,
+      headers: {
+        'content-type': 'application/json; charset=utf-8',
+      },
+    },
+  );
+}
+
+function cloneWithoutJsonBodyHeaders(request: Request) {
+  const headers = new Headers(request.headers);
+  headers.delete('content-type');
+  headers.delete('content-length');
+
+  return new Request(request.url, {
+    method: request.method,
+    headers,
+    signal: request.signal,
+  });
+}
+
+export async function prepareJsonRequestBody(request: Request) {
+  const method = normalizeItemMethod(request.method);
+  if (method === 'GET' || method === 'HEAD') {
+    return request;
+  }
+
+  const contentType = (request.headers.get('content-type') || '').toLowerCase();
+  if (!contentType.includes('application/json')) {
+    return request;
+  }
+
+  if (request.body === null) {
+    return cloneWithoutJsonBodyHeaders(request);
+  }
+
+  try {
+    const bodyText = await request.clone().text();
+    if (bodyText === '') {
+      return cloneWithoutJsonBodyHeaders(request);
+    }
+
+    JSON.parse(bodyText);
+  } catch {
+    return createBatchValidationResponse('Invalid JSON request body');
+  }
+
+  return request;
+}
+
+export function toBatchItemError(
+  id: string,
+  status: number,
+  message: string,
+): DataBatchResponseItem {
+  return {
+    id,
+    status,
+    headers: [['content-type', 'application/json; charset=utf-8']],
+    body: encodeBatchText(JSON.stringify({ message })),
+  };
+}
+
+export class BatchItemTimeoutError extends Error {}
+
+export function promiseWithTimeout<T>(
+  effect: Promise<T>,
+  timeoutMs: number,
+  onTimeout?: (error: BatchItemTimeoutError) => void,
+) {
+  if (timeoutMs <= 0) {
+    return effect;
+  }
+
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      const error = new BatchItemTimeoutError(
+        `Batch item timeout after ${String(timeoutMs)}ms`,
+      );
+      onTimeout?.(error);
+      reject(error);
+    }, timeoutMs);
+
+    effect.then(
+      value => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      error => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}
+
+export async function mapWithConcurrency<TItem, TResult>(
+  items: readonly TItem[],
+  concurrency: number,
+  mapper: (item: TItem, index: number) => Promise<TResult>,
+) {
+  if (items.length === 0) {
+    return [] as TResult[];
+  }
+
+  const normalizedConcurrency = Math.max(1, concurrency);
+  const output = new Array<TResult>(items.length);
+  let index = 0;
+
+  const workers = Array.from(
+    { length: Math.min(normalizedConcurrency, items.length) },
+    async () => {
+      while (true) {
+        const currentIndex = index;
+        index += 1;
+        if (currentIndex >= items.length) {
+          return;
+        }
+        output[currentIndex] = await mapper(items[currentIndex]!, currentIndex);
+      }
+    },
+  );
+
+  await Promise.all(workers);
+  return output;
+}