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

package/src/data-platform/types.ts

@@ -0,0 +1,186 @@
+// @effect-diagnostics asyncFunction:off globalDate:off globalRandom:off globalTimers:off newPromise:off strictBooleanExpressions:off
+/**
+ * Data-platform envelope (`x-modernjs-data-envelope`): the TRANSPORT/CACHE
+ * contract of the effect lane — protocol versioning, cache scope keys,
+ * selection plans, batching and hydration checksums.
+ *
+ * Boundary note (one envelope system per concern): cross-project
+ * AUTHORIZATION is the bff-core policy's job (`x-modernjs-bff-envelope` +
+ * operation contracts, evaluated server-side in both the hono and effect
+ * lanes). Nothing in this module is a trust boundary; treat every value
+ * here as client-asserted cache metadata.
+ */
+
+export type DataRequestMode =
+  | 'cache-first'
+  | 'stale-while-revalidate'
+  | 'network-only';
+
+export type DataMutationMode = 'optimistic' | 'pessimistic' | 'fire-and-forget';
+
+export type SelectionPlan = {
+  [field: string]: true | SelectionPlan;
+};
+
+export interface OperationDescriptor {
+  appNamespace: string;
+  apiId: string;
+  group: string;
+  endpoint: string;
+  schemaHash?: string;
+  version?: number;
+}
+
+export interface CacheScope {
+  appNamespace: string;
+  origin: string;
+  tenantId?: string;
+  userId?: string;
+  sessionId?: string;
+}
+
+export interface TraceContext {
+  traceId: string;
+  spanId: string;
+  sampled: boolean;
+  parentSpanId?: string;
+}
+
+export interface RequestEnvelope<Input = unknown> {
+  protocolVersion: 1;
+  operationId: string;
+  appNamespace: string;
+  origin: string;
+  requestMode: DataRequestMode;
+  mutationMode?: DataMutationMode;
+  scopeKey: string;
+  input: Input;
+  inputHash: string;
+  selectionPlan?: SelectionPlan;
+  selectionHash?: string;
+  traceparent?: string;
+  timestamp: number;
+}
+
+export interface HydrationEnvelope<Payload = unknown> {
+  protocolVersion: 1;
+  runtimeVersion: string;
+  appNamespace: string;
+  origin: string;
+  createdAt: number;
+  payload: Payload;
+  checksum: string;
+}
+
+export interface InvalidationEvent {
+  sourceNamespace: string;
+  sourceOperationId: string;
+  scopeKey: string;
+  targetNamespaces?: string[];
+  targetOperationIds?: string[];
+}
+
+export interface InvalidationSubscriber {
+  namespace: string;
+  operationIds?: string[];
+  scopeKey?: string;
+  acceptCrossNamespace?: boolean;
+}
+
+export interface DataBatchRequestItem {
+  id: string;
+  path: string;
+  method: string;
+  headers?: Record<string, string>;
+  body?: DataBatchBody;
+}
+
+export interface DataBatchRequestPayload {
+  protocolVersion: 2;
+  batchId: string;
+  sentAt: number;
+  items: DataBatchRequestItem[];
+}
+
+export interface DataBatchResponseItem {
+  id: string;
+  status: number;
+  headers?: DataBatchHeader[];
+  body?: DataBatchBody;
+}
+
+export interface DataBatchBody {
+  encoding: 'base64';
+  data: string;
+}
+
+export type DataBatchHeader = [name: string, value: string];
+
+export interface DataBatchResponsePayload {
+  protocolVersion: 2;
+  batchId: string;
+  receivedAt: number;
+  items: DataBatchResponseItem[];
+}
+
+export interface DataBatchTransportEvent {
+  type: 'enqueue' | 'flush' | 'fallback' | 'disable';
+  endpoint: string;
+  batchId?: string;
+  size?: number;
+  reason?: string;
+}
+
+export type DataBatchTransportTelemetryAttributes = Record<
+  string,
+  string | number | boolean
+>;
+
+export interface DataBatchTransportOptions {
+  endpoint?: string;
+  fetch?: (
+    input: DataTransportRequestInfo,
+    init?: RequestInit,
+  ) => Promise<Response>;
+  flushIntervalMs?: number;
+  maxBatchSize?: number;
+  maxBatchBytes?: number;
+  requestTimeoutMs?: number;
+  allowedMethods?: string[];
+  onEvent?: (event: DataBatchTransportEvent) => void;
+}
+
+export interface SelectionPlanValidationOptions {
+  maxDepth?: number;
+  maxFields?: number;
+  allowedLeafPaths?: ReadonlyArray<string>;
+}
+
+export interface SelectionPlanValidationResult {
+  ok: boolean;
+  errors: string[];
+  stats: {
+    maxDepth: number;
+    fieldCount: number;
+  };
+}
+
+export interface RequestEnvelopeValidationOptions {
+  expectedProtocolVersion?: number;
+  expectedNamespace?: string;
+  expectedOrigin?: string;
+  requireTraceContext?: boolean;
+}
+
+export interface HydrationEnvelopeValidationOptions {
+  expectedProtocolVersion?: number;
+  expectedNamespace?: string;
+  expectedOrigin?: string;
+  expectedRuntimeVersion?: string;
+}
+
+export const DEFAULT_DATA_ENVELOPE_HEADER = 'x-modernjs-data-envelope';
+export const DEFAULT_DATA_BATCH_ENDPOINT = '/_data/batch';
+export const DEFAULT_DATA_BATCH_HEADER = 'x-modernjs-data-batch';
+
+export type DataTransportRequestInfo = string | URL | Request;

package/src/data-platform/validation.ts

@@ -0,0 +1,303 @@
+// @effect-diagnostics asyncFunction:off globalDate:off globalRandom:off globalTimers:off newPromise:off strictBooleanExpressions:off
+import {
+  buildScopeKey,
+  createOperationId,
+  hashString,
+  isPlainObject,
+  normalizeOrigin,
+  sanitizeSegment,
+  stableStringify,
+} from './codec';
+import { formatTraceparentHeader, parseTraceparentHeader } from './trace';
+import type {
+  CacheScope,
+  DataMutationMode,
+  DataRequestMode,
+  HydrationEnvelope,
+  HydrationEnvelopeValidationOptions,
+  OperationDescriptor,
+  RequestEnvelope,
+  RequestEnvelopeValidationOptions,
+  SelectionPlan,
+  SelectionPlanValidationOptions,
+  SelectionPlanValidationResult,
+  TraceContext,
+} from './types';
+
+export function validateSelectionPlan(
+  plan: SelectionPlan,
+  options: SelectionPlanValidationOptions = {},
+): SelectionPlanValidationResult {
+  const maxDepthLimit = options.maxDepth ?? 8;
+  const maxFieldsLimit = options.maxFields ?? 256;
+  const allowedLeafPaths = options.allowedLeafPaths
+    ? new Set(options.allowedLeafPaths)
+    : null;
+
+  const errors: string[] = [];
+  let maxDepth = 0;
+  let fieldCount = 0;
+
+  const walk = (node: unknown, path: string[]) => {
+    if (!isPlainObject(node)) {
+      errors.push(
+        `Selection node at "${path.join('.') || '<root>'}" must be an object`,
+      );
+      return;
+    }
+
+    const keys = Object.keys(node);
+    if (keys.length === 0) {
+      errors.push(
+        `Selection node at "${path.join('.') || '<root>'}" cannot be empty`,
+      );
+      return;
+    }
+
+    for (const key of keys) {
+      fieldCount += 1;
+      if (fieldCount > maxFieldsLimit) {
+        errors.push(
+          `Selection has too many fields: ${String(fieldCount)} > ${String(maxFieldsLimit)}`,
+        );
+        return;
+      }
+
+      const nextPath = [...path, key];
+      const depth = nextPath.length;
+      if (depth > maxDepth) {
+        maxDepth = depth;
+      }
+      if (depth > maxDepthLimit) {
+        errors.push(
+          `Selection exceeds maxDepth at "${nextPath.join('.')}" (${String(depth)} > ${String(maxDepthLimit)})`,
+        );
+        return;
+      }
+
+      const value = (node as Record<string, unknown>)[key];
+      if (value === true) {
+        if (allowedLeafPaths && !allowedLeafPaths.has(nextPath.join('.'))) {
+          errors.push(`Unknown selected field "${nextPath.join('.')}"`);
+        }
+        continue;
+      }
+
+      if (!isPlainObject(value)) {
+        errors.push(
+          `Invalid selection value at "${nextPath.join('.')}"; expected true or nested object`,
+        );
+        continue;
+      }
+
+      walk(value, nextPath);
+    }
+  };
+
+  walk(plan, []);
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    stats: {
+      maxDepth,
+      fieldCount,
+    },
+  };
+}
+
+export function createRequestEnvelope<Input>(input: {
+  operation: OperationDescriptor;
+  scope: CacheScope;
+  requestInput: Input;
+  selectionPlan?: SelectionPlan;
+  requestMode?: DataRequestMode;
+  mutationMode?: DataMutationMode;
+  traceContext?: TraceContext;
+  requireTraceContext?: boolean;
+  timestamp?: number;
+  protocolVersion?: 1;
+}): RequestEnvelope<Input> {
+  if (input.requireTraceContext && !input.traceContext) {
+    throw new Error('Trace context is required for this request envelope');
+  }
+
+  const traceparent = input.traceContext
+    ? formatTraceparentHeader(input.traceContext)
+    : undefined;
+
+  const envelope: RequestEnvelope<Input> = {
+    protocolVersion: input.protocolVersion ?? 1,
+    operationId: createOperationId(input.operation),
+    appNamespace: sanitizeSegment(input.scope.appNamespace),
+    origin: normalizeOrigin(input.scope.origin),
+    requestMode: input.requestMode ?? 'cache-first',
+    mutationMode: input.mutationMode,
+    scopeKey: buildScopeKey(input.scope),
+    input: input.requestInput,
+    inputHash: hashString(stableStringify(input.requestInput ?? null)),
+    selectionPlan: input.selectionPlan,
+    selectionHash: input.selectionPlan
+      ? hashString(stableStringify(input.selectionPlan))
+      : undefined,
+    traceparent,
+    timestamp: input.timestamp ?? Date.now(),
+  };
+
+  return envelope;
+}
+
+export function validateRequestEnvelope(
+  envelope: RequestEnvelope,
+  options: RequestEnvelopeValidationOptions = {},
+): { ok: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  if (
+    options.expectedProtocolVersion !== undefined &&
+    envelope.protocolVersion !== options.expectedProtocolVersion
+  ) {
+    errors.push(
+      `Protocol mismatch: expected ${String(options.expectedProtocolVersion)} but received ${String(envelope.protocolVersion)}`,
+    );
+  }
+
+  if (
+    options.expectedNamespace &&
+    envelope.appNamespace !== options.expectedNamespace
+  ) {
+    errors.push(
+      `Namespace mismatch: expected ${options.expectedNamespace} but received ${envelope.appNamespace}`,
+    );
+  }
+
+  if (options.expectedOrigin) {
+    const expectedOrigin = normalizeOrigin(options.expectedOrigin);
+    if (envelope.origin !== expectedOrigin) {
+      errors.push(
+        `Origin mismatch: expected ${expectedOrigin} but received ${envelope.origin}`,
+      );
+    }
+  }
+
+  if (!envelope.operationId) {
+    errors.push('Missing operationId');
+  }
+
+  if (!envelope.scopeKey) {
+    errors.push('Missing scopeKey');
+  }
+
+  if (options.requireTraceContext && !envelope.traceparent) {
+    errors.push('Missing trace context');
+  }
+
+  if (envelope.traceparent && !parseTraceparentHeader(envelope.traceparent)) {
+    errors.push('Invalid traceparent header');
+  }
+
+  const computedInputHash = hashString(stableStringify(envelope.input ?? null));
+  if (computedInputHash !== envelope.inputHash) {
+    errors.push('Input hash mismatch');
+  }
+
+  if (envelope.selectionPlan) {
+    const computedSelectionHash = hashString(
+      stableStringify(envelope.selectionPlan),
+    );
+    if (computedSelectionHash !== envelope.selectionHash) {
+      errors.push('Selection hash mismatch');
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+  };
+}
+
+export function createHydrationEnvelope<Payload>(input: {
+  runtimeVersion: string;
+  scope: Pick<CacheScope, 'appNamespace' | 'origin'>;
+  payload: Payload;
+  createdAt?: number;
+  protocolVersion?: 1;
+}): HydrationEnvelope<Payload> {
+  const envelopeWithoutChecksum = {
+    protocolVersion: input.protocolVersion ?? 1,
+    runtimeVersion: input.runtimeVersion,
+    appNamespace: sanitizeSegment(input.scope.appNamespace),
+    origin: normalizeOrigin(input.scope.origin),
+    createdAt: input.createdAt ?? Date.now(),
+    payload: input.payload,
+  };
+
+  const checksum = hashString(stableStringify(envelopeWithoutChecksum));
+
+  return {
+    ...envelopeWithoutChecksum,
+    checksum,
+  };
+}
+
+export function validateHydrationEnvelope(
+  envelope: HydrationEnvelope,
+  options: HydrationEnvelopeValidationOptions = {},
+): { ok: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  if (
+    options.expectedProtocolVersion !== undefined &&
+    envelope.protocolVersion !== options.expectedProtocolVersion
+  ) {
+    errors.push(
+      `Protocol mismatch: expected ${String(options.expectedProtocolVersion)} but received ${String(envelope.protocolVersion)}`,
+    );
+  }
+
+  if (
+    options.expectedNamespace &&
+    envelope.appNamespace !== options.expectedNamespace
+  ) {
+    errors.push(
+      `Namespace mismatch: expected ${options.expectedNamespace} but received ${envelope.appNamespace}`,
+    );
+  }
+
+  if (options.expectedOrigin) {
+    const expectedOrigin = normalizeOrigin(options.expectedOrigin);
+    if (envelope.origin !== expectedOrigin) {
+      errors.push(
+        `Origin mismatch: expected ${expectedOrigin} but received ${envelope.origin}`,
+      );
+    }
+  }
+
+  if (
+    options.expectedRuntimeVersion &&
+    envelope.runtimeVersion !== options.expectedRuntimeVersion
+  ) {
+    errors.push(
+      `Runtime version mismatch: expected ${options.expectedRuntimeVersion} but received ${envelope.runtimeVersion}`,
+    );
+  }
+
+  const checksumBase = {
+    protocolVersion: envelope.protocolVersion,
+    runtimeVersion: envelope.runtimeVersion,
+    appNamespace: envelope.appNamespace,
+    origin: envelope.origin,
+    createdAt: envelope.createdAt,
+    payload: envelope.payload,
+  };
+
+  const checksum = hashString(stableStringify(checksumBase));
+  if (checksum !== envelope.checksum) {
+    errors.push('Hydration checksum mismatch');
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+  };
+}

package/src/effect/context.ts

@@ -0,0 +1,37 @@
+// @effect-diagnostics strictBooleanExpressions:off
+import { AsyncLocalStorage } from 'node:async_hooks';
+import {
+  type EffectContext,
+  type EffectContextStorage,
+  kEffectContextStorage,
+} from './operation-context';
+
+export {
+  type CreateEffectOperationContextOptions,
+  createEffectOperationContext,
+  type EffectContext,
+} from './operation-context';
+
+const globalStore = globalThis as typeof globalThis & {
+  [kEffectContextStorage]?: EffectContextStorage;
+};
+
+const effectContextStorage =
+  globalStore[kEffectContextStorage] ??
+  (globalStore[kEffectContextStorage] = new AsyncLocalStorage<EffectContext>());
+
+export const runWithEffectContext = <T>(
+  context: EffectContext,
+  cb: () => T,
+): T => effectContextStorage.run(context, cb);
+
+export const useEffectContext = (): EffectContext => {
+  const context = effectContextStorage.getStore();
+  if (!context) {
+    throw new Error(`Can't call useEffectContext out of Effect runtime scope`);
+  }
+
+  return context;
+};
+
+export const useOperationContext = () => useEffectContext().operationContext;

package/src/effect/dispatch.ts

@@ -0,0 +1,132 @@
+// @effect-diagnostics anyUnknownInErrorContext:off asyncFunction:off strictBooleanExpressions:off
+import { createSafeFailureResponse } from '@modern-js/runtime-extensions/safe-failure';
+import type { EffectBffRequestHandler } from './module';
+import {
+  createEffectOperationContext,
+  type EffectContext,
+} from './operation-context';
+
+type EffectDispatchContextRunner = <T>(
+  context: EffectContext,
+  cb: () => T,
+) => T;
+
+export type DispatchEffectBffRequestOptions = {
+  prefix?: string;
+  env?: Record<string, unknown>;
+  path?: string;
+  method?: string;
+  runWithEffectContext: EffectDispatchContextRunner;
+  onError?: (
+    error: unknown,
+    context: EffectContext,
+  ) => Promise<Response> | Response;
+};
+
+function normalizeEffectBffPrefix(prefix: string | undefined) {
+  if (!prefix || prefix === '/') {
+    return '';
+  }
+  return prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
+}
+
+function removeEffectBffPrefixFromPath(
+  pathname: string,
+  prefix: string | undefined,
+) {
+  const normalized = normalizeEffectBffPrefix(prefix);
+  if (
+    !normalized ||
+    (pathname !== normalized && !pathname.startsWith(`${normalized}/`))
+  ) {
+    return pathname;
+  }
+  const sliced = pathname.slice(normalized.length);
+  return sliced.startsWith('/') ? sliced : `/${sliced}`;
+}
+
+function matchesEffectBffPrefix(pathname: string, prefix: string | undefined) {
+  const normalized = normalizeEffectBffPrefix(prefix);
+  return (
+    !normalized ||
+    pathname === normalized ||
+    pathname.startsWith(`${normalized}/`)
+  );
+}
+
+function createEffectBffMountedRequest(
+  req: Request,
+  prefix: string | undefined,
+) {
+  const url = new URL(req.url);
+  const nextPath = removeEffectBffPrefixFromPath(url.pathname, prefix);
+  if (nextPath !== url.pathname) {
+    url.pathname = nextPath;
+    return new Request(url, req);
+  }
+  return req;
+}
+
+function createEffectBffDispatchContext(
+  originalRequest: Request,
+  mountedRequest: Request,
+  options: Omit<DispatchEffectBffRequestOptions, 'runWithEffectContext'>,
+): EffectContext {
+  const path = options.path ?? new URL(originalRequest.url).pathname;
+  const method = options.method ?? originalRequest.method;
+  const env = options.env ?? {};
+
+  return {
+    request: mountedRequest,
+    env,
+    path,
+    method,
+    operationContext: createEffectOperationContext({
+      request: mountedRequest,
+      env,
+      path,
+      method,
+    }),
+  };
+}
+
+export async function dispatchEffectBffRequestWithContext(
+  handler: EffectBffRequestHandler,
+  request: Request,
+  options: DispatchEffectBffRequestOptions,
+): Promise<Response> {
+  const requestPath = new URL(request.url).pathname;
+  if (!matchesEffectBffPrefix(requestPath, options.prefix)) {
+    return new Response('', { status: 404 });
+  }
+
+  const mountedRequest = createEffectBffMountedRequest(request, options.prefix);
+  const effectContext = createEffectBffDispatchContext(
+    request,
+    mountedRequest,
+    options,
+  );
+
+  try {
+    const response = await options.runWithEffectContext(effectContext, () =>
+      handler(mountedRequest, effectContext),
+    );
+    if (!(response instanceof Response)) {
+      throw new Error(
+        '[BFF][Effect] Effect handler must return Response instance.',
+      );
+    }
+    return new Response(response.body, response);
+  } catch (error) {
+    if (error instanceof Response) {
+      return new Response(error.body, error);
+    }
+    if (options.onError) {
+      const errorResponse = await options.onError(error, effectContext);
+      if (errorResponse instanceof Response) {
+        return errorResponse;
+      }
+    }
+    return createSafeFailureResponse(error);
+  }
+}

package/src/effect/edge-context.ts

@@ -0,0 +1,51 @@
+// @effect-diagnostics strictBooleanExpressions:off
+import {
+  type EffectContext,
+  type EffectContextStorage,
+  kEffectContextStorage,
+} from './operation-context';
+
+export {
+  type CreateEffectOperationContextOptions,
+  createEffectOperationContext,
+  type EffectContext,
+} from './operation-context';
+
+type EffectContextStorageConstructor = new () => EffectContextStorage;
+
+const globalStore = globalThis as typeof globalThis & {
+  [kEffectContextStorage]?: EffectContextStorage;
+  process?: {
+    getBuiltinModule?: (id: string) => unknown;
+  };
+};
+
+const asyncHooks = globalStore.process?.getBuiltinModule?.(
+  'node:async_hooks',
+) as { AsyncLocalStorage?: EffectContextStorageConstructor } | undefined;
+const AsyncLocalStorage = asyncHooks?.AsyncLocalStorage;
+if (typeof AsyncLocalStorage !== 'function') {
+  throw new Error(
+    '[BFF][Effect] The edge runtime must provide AsyncLocalStorage. Enable Node.js compatibility or the nodejs_als compatibility flag.',
+  );
+}
+
+const effectContextStorage =
+  globalStore[kEffectContextStorage] ??
+  (globalStore[kEffectContextStorage] = new AsyncLocalStorage());
+
+export const runWithEffectContext = <T>(
+  context: EffectContext,
+  cb: () => T,
+): T => effectContextStorage.run(context, cb);
+
+export const useEffectContext = (): EffectContext => {
+  const context = effectContextStorage.getStore();
+  if (!context) {
+    throw new Error(`Can't call useEffectContext out of Effect runtime scope`);
+  }
+
+  return context;
+};
+
+export const useOperationContext = () => useEffectContext().operationContext;