@bleedingdev/modern-js-runtime-extensions 3.9.0-ultramodern.4 → 3.9.0-ultramodern.6

package/src/request-policy/transport.ts

@@ -0,0 +1,349 @@
+import type {
+  DegradedModeEvent,
+  RetryBackoffOptions,
+  RetryDecisionContext,
+  TransportResilienceOptions,
+  TransportTarget,
+} from './types';
+
+const DEFAULT_RETRYABLE_STATUS_CODES = [408, 425, 429, 500, 502, 503, 504];
+const DEFAULT_BASE_DELAY_MS = 100;
+const DEFAULT_MAX_DELAY_MS = 1000;
+const DEFAULT_JITTER_RATIO = 0.1;
+const DEFAULT_RETRYABLE_METHODS = new Set([
+  'DELETE',
+  'GET',
+  'HEAD',
+  'OPTIONS',
+  'PUT',
+  'TRACE',
+]);
+
+type ErrorLike = {
+  name?: unknown;
+  code?: unknown;
+  status?: unknown;
+  response?: { status?: unknown };
+};
+
+const createTimeoutError = (timeoutMs: number) => {
+  const error = new Error(`Request timed out after ${timeoutMs}ms`);
+  error.name = 'TimeoutError';
+  return error;
+};
+
+const unrefTimer = (timer: unknown) => {
+  if (
+    typeof timer === 'object' &&
+    timer !== null &&
+    'unref' in timer &&
+    typeof timer.unref === 'function'
+  ) {
+    timer.unref();
+  }
+};
+
+const wait = (ms: number) =>
+  new Promise<void>(resolve => {
+    const timer = setTimeout(() => resolve(), ms);
+    unrefTimer(timer);
+  });
+
+const toStatusCode = (error: unknown): number | undefined => {
+  if (!error || typeof error !== 'object') {
+    return undefined;
+  }
+
+  const status = (error as ErrorLike).status;
+  if (typeof status === 'number') {
+    return status;
+  }
+
+  const responseStatus = (error as ErrorLike).response?.status;
+  if (typeof responseStatus === 'number') {
+    return responseStatus;
+  }
+
+  return undefined;
+};
+
+const isRetryableNetworkError = (error: unknown) => {
+  if (!error || typeof error !== 'object') {
+    return false;
+  }
+
+  const name = (error as ErrorLike).name;
+  if (
+    name === 'FetchError' ||
+    name === 'TimeoutError' ||
+    name === 'TypeError'
+  ) {
+    return true;
+  }
+
+  const code = (error as ErrorLike).code;
+  return (
+    code === 'ECONNRESET' ||
+    code === 'ETIMEDOUT' ||
+    code === 'ECONNREFUSED' ||
+    code === 'EPIPE'
+  );
+};
+
+const normalizePositiveNumber = (value: unknown, fallback: number) =>
+  typeof value === 'number' && Number.isFinite(value) && value > 0
+    ? value
+    : fallback;
+
+const normalizeNonNegativeInt = (value: unknown, fallback: number) =>
+  typeof value === 'number' && Number.isFinite(value) && value >= 0
+    ? Math.floor(value)
+    : fallback;
+
+const normalizeJitterRatio = (value: unknown) => {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return DEFAULT_JITTER_RATIO;
+  }
+  return Math.max(0, Math.min(1, value));
+};
+
+const shouldRetryWithDefaults = (
+  method: string,
+  statusCode: number | undefined,
+  error: unknown,
+  retryableStatusCodes: number[],
+) => {
+  if (!DEFAULT_RETRYABLE_METHODS.has(method.toUpperCase())) {
+    return false;
+  }
+
+  if (typeof statusCode === 'number') {
+    return retryableStatusCodes.includes(statusCode);
+  }
+  return isRetryableNetworkError(error);
+};
+
+const shouldRetry = (
+  retryOptions: RetryBackoffOptions | undefined,
+  context: RetryDecisionContext,
+  retryableStatusCodes: number[],
+) => {
+  if (typeof retryOptions?.shouldRetry === 'function') {
+    try {
+      return retryOptions.shouldRetry(context);
+    } catch (error) {
+      return false;
+    }
+  }
+
+  return shouldRetryWithDefaults(
+    context.method,
+    context.statusCode,
+    context.error,
+    retryableStatusCodes,
+  );
+};
+
+const getBackoffMs = (
+  retryOptions: RetryBackoffOptions | undefined,
+  attempt: number,
+) => {
+  const baseDelayMs = normalizePositiveNumber(
+    retryOptions?.baseDelayMs,
+    DEFAULT_BASE_DELAY_MS,
+  );
+  const maxDelayMs = normalizePositiveNumber(
+    retryOptions?.maxDelayMs,
+    DEFAULT_MAX_DELAY_MS,
+  );
+  const jitterRatio = normalizeJitterRatio(retryOptions?.jitterRatio);
+  const exponentialDelay = Math.min(
+    maxDelayMs,
+    baseDelayMs * 2 ** Math.max(0, attempt - 1),
+  );
+  const jitterFactor =
+    jitterRatio === 0 ? 1 : 1 + (Math.random() * 2 - 1) * jitterRatio;
+  return Math.max(0, Math.floor(exponentialDelay * jitterFactor));
+};
+
+const emitDegradedEvent = (
+  transport: TransportResilienceOptions | undefined,
+  event: DegradedModeEvent,
+) => {
+  if (typeof transport?.onDegraded !== 'function') {
+    return;
+  }
+
+  try {
+    transport.onDegraded(event);
+  } catch (error) {
+    // best-effort telemetry only
+  }
+};
+
+const withTimeout = async <T>(
+  promise: Promise<T>,
+  timeoutMs: number | undefined,
+  signalBuilder?: () => AbortController | undefined,
+) => {
+  if (!timeoutMs || timeoutMs <= 0) {
+    const result = await promise;
+    return { result };
+  }
+
+  const controller = signalBuilder?.();
+
+  let timeoutTriggered = false;
+  let rejectTimeout: ((error: Error) => void) | undefined;
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    rejectTimeout = reject;
+  });
+
+  const timer = setTimeout(() => {
+    timeoutTriggered = true;
+    if (controller) {
+      controller.abort();
+    }
+    rejectTimeout?.(createTimeoutError(timeoutMs));
+  }, timeoutMs);
+  unrefTimer(timer);
+
+  try {
+    const result = await Promise.race([promise, timeoutPromise]);
+    return { result, timeoutTriggered };
+  } catch (error) {
+    if (timeoutTriggered && (error as ErrorLike)?.name === 'AbortError') {
+      throw createTimeoutError(timeoutMs);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+type ExecuteWithResilienceOptions = {
+  requestId: string;
+  target: TransportTarget;
+  method: string;
+  url: string;
+  init: Record<string, any>;
+  fetcher: (...args: any[]) => Promise<any>;
+  transport?: TransportResilienceOptions;
+};
+
+export const executeWithResilience = async ({
+  requestId,
+  target,
+  method,
+  url,
+  init,
+  fetcher,
+  transport,
+}: ExecuteWithResilienceOptions) => {
+  const retries = normalizeNonNegativeInt(transport?.retry?.retries, 0);
+  const timeoutMs =
+    typeof transport?.timeoutMs === 'number' && transport.timeoutMs > 0
+      ? transport.timeoutMs
+      : undefined;
+  const maxAttempts = retries + 1;
+  const retryableStatusCodes =
+    transport?.retry?.retryableStatusCodes &&
+    transport.retry.retryableStatusCodes.length > 0
+      ? transport.retry.retryableStatusCodes
+      : DEFAULT_RETRYABLE_STATUS_CODES;
+
+  let attempt = 0;
+
+  while (attempt < maxAttempts) {
+    attempt += 1;
+    const canUseAbortController = typeof AbortController !== 'undefined';
+    let controller: AbortController | undefined;
+    if (timeoutMs && canUseAbortController) {
+      controller = new AbortController();
+    }
+
+    const callerSignal = init.signal as AbortSignal | undefined;
+    const requestSignal = controller
+      ? callerSignal && !callerSignal.aborted
+        ? AbortSignal.any([callerSignal, controller.signal])
+        : callerSignal || controller.signal
+      : callerSignal;
+    const nextInit = requestSignal ? { ...init, signal: requestSignal } : init;
+
+    try {
+      const { result } = await withTimeout(
+        fetcher(url, nextInit),
+        timeoutMs,
+        () => controller,
+      );
+      return result;
+    } catch (error) {
+      const statusCode = toStatusCode(error);
+      const decisionContext: RetryDecisionContext = {
+        requestId,
+        target,
+        method,
+        url,
+        attempt,
+        maxAttempts,
+        error,
+        statusCode,
+      };
+
+      if ((error as ErrorLike)?.name === 'TimeoutError') {
+        emitDegradedEvent(transport, {
+          requestId,
+          target,
+          method,
+          url,
+          reason: 'timeout',
+          attempt,
+          maxAttempts,
+          timeoutMs,
+          statusCode,
+          error,
+        });
+      }
+
+      const canRetry =
+        attempt < maxAttempts &&
+        shouldRetry(transport?.retry, decisionContext, retryableStatusCodes);
+      if (!canRetry) {
+        if (retries > 0 || (error as ErrorLike)?.name === 'TimeoutError') {
+          emitDegradedEvent(transport, {
+            requestId,
+            target,
+            method,
+            url,
+            reason: 'retry_exhausted',
+            attempt,
+            maxAttempts,
+            timeoutMs,
+            statusCode,
+            error,
+          });
+        }
+        throw error;
+      }
+
+      const backoffMs = getBackoffMs(transport?.retry, attempt);
+      emitDegradedEvent(transport, {
+        requestId,
+        target,
+        method,
+        url,
+        reason: 'retry',
+        attempt,
+        maxAttempts,
+        timeoutMs,
+        backoffMs,
+        statusCode,
+        error,
+      });
+
+      if (backoffMs > 0) {
+        await wait(backoffMs);
+      }
+    }
+  }
+};

package/src/request-policy/types.ts

@@ -0,0 +1,229 @@
+import type {
+  HttpMethodDecider,
+  IOptions as NativeOptions,
+  RequestCreatorOptions as NativeRequestCreatorOptions,
+  UploadCreatorOptions as NativeUploadCreatorOptions,
+  Sender,
+} from '@modern-js/create-request/client';
+
+export type {
+  BFFRequestPayload,
+  HttpMethodDecider,
+  Sender,
+} from '@modern-js/create-request/client';
+
+export const BFF_ENVELOPE_HEADER = 'x-modernjs-bff-envelope';
+export const BFF_OPERATION_CONTEXT_HEADER = 'x-operation-id';
+export const BFF_OPERATION_CONTEXT_DETAIL_HEADER =
+  'x-modernjs-bff-operation-context';
+export const BFF_DEFAULT_PROTECTED_IDENTITY_HEADERS = [
+  'x-tenant-id',
+  'x-subject-id',
+  'x-user-id',
+  BFF_OPERATION_CONTEXT_HEADER,
+] as const;
+
+export type ResolveHeadersOptions = {
+  requestId: string;
+  allowedHeaders: string[];
+  incomingHeaders: Record<string, any>;
+};
+
+export type ResolveHeaders = (
+  options: ResolveHeadersOptions,
+) => Record<string, any> | void;
+
+export type AllowCrossOriginEnvelopeOptions = {
+  requestId: string;
+  sourceOrigin?: string;
+  targetOrigin?: string;
+  target: 'server' | 'browser';
+};
+
+export type AllowCrossOriginEnvelope =
+  | boolean
+  | ((options: AllowCrossOriginEnvelopeOptions) => boolean);
+
+export type TransportTarget = 'server' | 'browser';
+
+export type RetryDecisionContext = {
+  requestId: string;
+  target: TransportTarget;
+  method: string;
+  url: string;
+  attempt: number;
+  maxAttempts: number;
+  error: unknown;
+  statusCode?: number;
+};
+
+export type RetryBackoffOptions = {
+  retries?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  jitterRatio?: number;
+  retryableStatusCodes?: number[];
+  shouldRetry?: (context: RetryDecisionContext) => boolean;
+};
+
+export type DegradedModeReason = 'timeout' | 'retry' | 'retry_exhausted';
+
+export type DegradedModeEvent = {
+  requestId: string;
+  target: TransportTarget;
+  method: string;
+  url: string;
+  reason: DegradedModeReason;
+  attempt: number;
+  maxAttempts: number;
+  timeoutMs?: number;
+  backoffMs?: number;
+  statusCode?: number;
+  error?: unknown;
+};
+
+export type TransportResilienceOptions = {
+  timeoutMs?: number;
+  retry?: RetryBackoffOptions;
+  onDegraded?: (event: DegradedModeEvent) => void;
+};
+
+export type IdentityBindingViolationReason =
+  | 'client_override_blocked'
+  | 'client_override_rejected';
+
+export type IdentityBindingViolation = {
+  requestId: string;
+  target: TransportTarget;
+  header: string;
+  reason: IdentityBindingViolationReason;
+  attemptedValue?: unknown;
+  derivedValue?: unknown;
+};
+
+export type DeriveIdentityHeadersOptions = {
+  requestId: string;
+  target: TransportTarget;
+  incomingHeaders: Record<string, any>;
+  protectedHeaders: string[];
+};
+
+export type IdentityBindingOptions = {
+  enabled?: boolean;
+  strict?: boolean;
+  protectedHeaders?: string[];
+  deriveHeaders?: (
+    options: DeriveIdentityHeadersOptions,
+  ) => Record<string, any> | void;
+  onViolation?: (violation: IdentityBindingViolation) => void;
+};
+
+export type OperationContractViolationReason =
+  | 'missing_schema_hash'
+  | 'missing_operation_version';
+
+export type OperationContractViolation = {
+  requestId: string;
+  target: TransportTarget;
+  operationId: string;
+  reason: OperationContractViolationReason;
+  routePath?: string;
+  method?: string;
+  schemaHash?: string;
+  operationVersion?: number;
+};
+
+export type CrossProjectOperationContract = {
+  schemaHash?: string;
+  operationVersion?: number;
+};
+
+export type CrossProjectPolicyViolationReason =
+  | 'missing_envelope'
+  | 'invalid_envelope'
+  | 'missing_request_id'
+  | 'namespace_not_allowed'
+  | 'missing_operation_context'
+  | 'operation_context_mismatch'
+  | 'missing_operation_context_details'
+  | 'invalid_operation_context_details'
+  | 'operation_context_details_request_id_mismatch'
+  | 'missing_operation_schema_hash'
+  | 'missing_operation_version'
+  | 'unknown_operation_contract'
+  | 'operation_schema_hash_mismatch'
+  | 'operation_version_mismatch'
+  | 'producer_identity_mismatch';
+
+export type CrossProjectPolicyViolation = {
+  code: 'BFF_CROSS_PROJECT_POLICY_DENIED';
+  reason: CrossProjectPolicyViolationReason;
+  message: string;
+  status: number;
+};
+
+export type OperationContractOptions = {
+  enabled?: boolean;
+  strict?: boolean;
+  requireSchemaHash?: boolean;
+  requireOperationVersion?: boolean;
+  onViolation?: (violation: OperationContractViolation) => void;
+};
+
+export type OperationContextSource =
+  | 'client'
+  | 'server'
+  | 'generated-client'
+  | 'effect-adapter'
+  | 'data-platform'
+  | 'unknown';
+
+export type OperationContext = {
+  requestId?: string;
+  operationId?: string;
+  routePath?: string;
+  method?: string;
+  schemaHash?: string;
+  operationVersion?: number;
+  locale?: string;
+  traceparent?: string;
+  traceId?: string;
+  spanId?: string;
+  source?: OperationContextSource;
+  scope?: Record<string, unknown>;
+  sessionClaims?: Record<string, unknown>;
+  attributes?: Record<string, unknown>;
+};
+
+export type RequestCreatorOptions<F = typeof fetch> = Omit<
+  NativeRequestCreatorOptions<F>,
+  'hooks'
+> & { operationContext?: OperationContext };
+
+export type RequestCreator<F = typeof fetch> = {
+  (options: RequestCreatorOptions<F>): Sender;
+  (
+    path: string,
+    method: string,
+    port: number,
+    httpMethodDecider?: HttpMethodDecider,
+    fetch?: F,
+    requestId?: string,
+    operationContext?: OperationContext,
+  ): Sender;
+};
+
+export type UploadCreatorOptions = Omit<NativeUploadCreatorOptions, 'hooks'> & {
+  operationContext?: OperationContext;
+};
+
+export type UploadCreator = (options: UploadCreatorOptions) => Sender;
+
+export type IOptions<F = typeof fetch> = NativeOptions<F> & {
+  resolveHeaders?: ResolveHeaders;
+  transport?: TransportResilienceOptions;
+  requireEnvelope?: boolean;
+  allowCrossOriginEnvelope?: AllowCrossOriginEnvelope;
+  identityBinding?: IdentityBindingOptions;
+  operationContract?: OperationContractOptions;
+};