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

package/dist/esm/request-policy/client.mjs

@@ -0,0 +1,195 @@
+import { IdentityBindingViolationError, ProducerDomainNotConfiguredError, TRACEPARENT_HEADER, attachOperationContextHeaders, buildEnvelopeHeaderValue, deleteHeader, firstHeaderValue, isEmptyDomain, isSecuredRequestId, parseTraceparentValue, readHeader, resolveConfiguredRequest, toOrigin, writeHeader } from "./policyCore.mjs";
+import { executeWithResilience } from "./transport.mjs";
+import { BFF_DEFAULT_PROTECTED_IDENTITY_HEADERS, BFF_ENVELOPE_HEADER, BFF_OPERATION_CONTEXT_DETAIL_HEADER, BFF_OPERATION_CONTEXT_HEADER } from "./types.mjs";
+const createPolicyClient = (nativeClient, environment)=>{
+    const isServerTarget = 'server' === environment.target;
+    const configuredRequests = new Map();
+    const realResolveHeaders = new Map();
+    const realRequireEnvelope = new Map();
+    const realAllowCrossOriginEnvelope = new Map();
+    const realTransportResilience = new Map();
+    const realIdentityBinding = new Map();
+    const realOperationContract = new Map();
+    const domainMap = new Map();
+    const attachEnvelopeHeaderIfRequired = (headers, requestId, url, incomingHeaders)=>{
+        const shouldRequireEnvelope = realRequireEnvelope.get(requestId) ?? isSecuredRequestId(requestId);
+        if (!shouldRequireEnvelope) return;
+        headers[BFF_ENVELOPE_HEADER] = buildEnvelopeHeaderValue({
+            requestId,
+            target: environment.target,
+            sourceOrigin: environment.resolveSourceOrigin(incomingHeaders),
+            targetOrigin: toOrigin(url),
+            traceContext: parseTraceparentValue(readHeader(headers, TRACEPARENT_HEADER)),
+            allowCrossOriginEnvelope: realAllowCrossOriginEnvelope.get(requestId)
+        });
+    };
+    const attachSecuredOperationHeaders = (headers, requestId, method, path, operationContext)=>{
+        if (!isSecuredRequestId(requestId)) return;
+        attachOperationContextHeaders({
+            headers,
+            requestId,
+            target: environment.target,
+            method,
+            path,
+            operationContext,
+            operationContract: realOperationContract.get(requestId),
+            operationContextHeader: BFF_OPERATION_CONTEXT_HEADER,
+            operationContextDetailHeader: BFF_OPERATION_CONTEXT_DETAIL_HEADER
+        });
+    };
+    const applyIdentityAndForwardedHeaders = ({ headers, requestId, incomingHeaders, forwardedHeaders, allowedHeaders: targetAllowedHeaders })=>{
+        const identityBinding = realIdentityBinding.get(requestId);
+        const identityBindingEnabled = identityBinding?.enabled ?? isSecuredRequestId(requestId);
+        const identityBindingStrict = identityBinding?.strict ?? isSecuredRequestId(requestId);
+        const protectedIdentityHeaders = (identityBinding?.protectedHeaders || BFF_DEFAULT_PROTECTED_IDENTITY_HEADERS).map((header)=>header.toLowerCase());
+        if (identityBindingEnabled) {
+            const derivedIdentityHeaders = {};
+            if (isServerTarget) for (const header of protectedIdentityHeaders){
+                const incomingHeaderValue = readHeader(incomingHeaders, header);
+                if (void 0 !== incomingHeaderValue) writeHeader(derivedIdentityHeaders, header, incomingHeaderValue);
+            }
+            const customDerivedHeaders = identityBinding?.deriveHeaders?.({
+                requestId,
+                target: environment.target,
+                incomingHeaders: isServerTarget ? {
+                    ...incomingHeaders
+                } : {},
+                protectedHeaders: [
+                    ...protectedIdentityHeaders
+                ]
+            });
+            if (customDerivedHeaders && 'object' == typeof customDerivedHeaders) for (const header of protectedIdentityHeaders){
+                const customValue = readHeader(customDerivedHeaders, header);
+                if (void 0 !== customValue) writeHeader(derivedIdentityHeaders, header, customValue);
+            }
+            for (const header of protectedIdentityHeaders){
+                const attemptedValue = readHeader(headers, header);
+                if (void 0 === attemptedValue) continue;
+                const violation = {
+                    requestId,
+                    target: environment.target,
+                    header,
+                    attemptedValue,
+                    derivedValue: readHeader(derivedIdentityHeaders, header),
+                    reason: 'client_override_blocked'
+                };
+                identityBinding?.onViolation?.(violation);
+                if (identityBindingStrict) throw new IdentityBindingViolationError(violation);
+                deleteHeader(headers, header);
+            }
+            Object.keys(derivedIdentityHeaders).forEach((header)=>{
+                isServerTarget ? writeHeader(forwardedHeaders, header, derivedIdentityHeaders[header]) : writeHeader(headers, header, derivedIdentityHeaders[header]);
+            });
+        }
+        if (isServerTarget) {
+            const resolveHeaders = realResolveHeaders.get(requestId);
+            if (resolveHeaders) {
+                const resolvedHeaders = resolveHeaders({
+                    requestId,
+                    allowedHeaders: targetAllowedHeaders,
+                    incomingHeaders: {
+                        ...forwardedHeaders
+                    }
+                });
+                if (resolvedHeaders && 'object' == typeof resolvedHeaders) for (const key of targetAllowedHeaders){
+                    const resolvedValue = readHeader(resolvedHeaders, key);
+                    if (void 0 !== resolvedValue) {
+                        if (identityBindingEnabled && protectedIdentityHeaders.includes(key.toLowerCase())) {
+                            writeHeader(forwardedHeaders, key.toLowerCase(), resolvedValue);
+                            continue;
+                        }
+                        writeHeader(forwardedHeaders, key, resolvedValue);
+                    }
+                }
+            }
+        }
+        return headers;
+    };
+    const configure = (options)=>{
+        const { request, interceptor, allowedHeaders, resolveHeaders, transport, requireEnvelope, allowCrossOriginEnvelope, identityBinding, operationContract, setDomain, requestId = 'default' } = options;
+        const hasExistingDomain = domainMap.has(requestId);
+        if ('default' !== requestId && !setDomain && !hasExistingDomain) throw new ProducerDomainNotConfiguredError(requestId);
+        let resolvedDomain;
+        nativeClient.configure({
+            request,
+            interceptor,
+            allowedHeaders,
+            requestId,
+            setDomain: setDomain ? (options)=>{
+                resolvedDomain = setDomain(options);
+                if ('default' !== requestId && isEmptyDomain(resolvedDomain)) throw new ProducerDomainNotConfiguredError(requestId);
+                return resolvedDomain;
+            } : void 0
+        });
+        realResolveHeaders.delete(requestId);
+        realTransportResilience.delete(requestId);
+        realIdentityBinding.delete(requestId);
+        realOperationContract.delete(requestId);
+        realRequireEnvelope.delete(requestId);
+        realAllowCrossOriginEnvelope.delete(requestId);
+        if (isServerTarget && 'function' == typeof resolveHeaders) realResolveHeaders.set(requestId, resolveHeaders);
+        if (transport && 'object' == typeof transport) realTransportResilience.set(requestId, transport);
+        if (identityBinding && 'object' == typeof identityBinding) realIdentityBinding.set(requestId, identityBinding);
+        if (operationContract && 'object' == typeof operationContract) realOperationContract.set(requestId, operationContract);
+        if ('boolean' == typeof requireEnvelope) realRequireEnvelope.set(requestId, requireEnvelope);
+        if ('boolean' == typeof allowCrossOriginEnvelope || 'function' == typeof allowCrossOriginEnvelope) realAllowCrossOriginEnvelope.set(requestId, allowCrossOriginEnvelope);
+        if ('string' == typeof resolvedDomain) domainMap.set(requestId, resolvedDomain);
+        configuredRequests.set(requestId, true);
+    };
+    const createHooks = (path, method, requestId, operationContext, upload = false)=>({
+            onStart: ({ configuredDomain })=>{
+                resolveConfiguredRequest(configuredRequests, requestId, false);
+                if (!upload && 'default' !== requestId && isEmptyDomain(configuredDomain)) throw new ProducerDomainNotConfiguredError(requestId);
+            },
+            prepareHeaders: applyIdentityAndForwardedHeaders,
+            dispatch: (context)=>{
+                const { incomingHeaders, url, init: { headers } } = context;
+                if (isServerTarget && !upload) {
+                    if (void 0 === readHeader(headers, TRACEPARENT_HEADER)) {
+                        const incomingTraceparent = firstHeaderValue(readHeader(incomingHeaders, TRACEPARENT_HEADER));
+                        if ('string' == typeof incomingTraceparent) writeHeader(headers, TRACEPARENT_HEADER, incomingTraceparent);
+                    }
+                    if (void 0 === readHeader(headers, TRACEPARENT_HEADER) && operationContext?.traceparent) writeHeader(headers, TRACEPARENT_HEADER, operationContext.traceparent);
+                }
+                attachEnvelopeHeaderIfRequired(headers, requestId, url, incomingHeaders);
+                attachSecuredOperationHeaders(headers, requestId, method, path, operationContext);
+                return executeWithResilience({
+                    requestId,
+                    target: environment.target,
+                    method,
+                    url,
+                    init: context.init,
+                    fetcher: context.fetcher,
+                    transport: realTransportResilience.get(requestId)
+                });
+            }
+        });
+    const createRequest = (...args)=>{
+        const options = 'object' == typeof args[0] && null !== args[0] ? args[0] : {
+            path: args[0],
+            method: args[1],
+            port: args[2],
+            httpMethodDecider: args[3],
+            fetch: args[4],
+            requestId: args[5],
+            operationContext: args[6]
+        };
+        const { operationContext, requestId = 'default', ...nativeOptions } = options;
+        return nativeClient.createRequest({
+            ...nativeOptions,
+            requestId,
+            hooks: createHooks(options.path, options.method, requestId, operationContext)
+        });
+    };
+    const createUploader = ({ operationContext, requestId = 'default', ...options })=>nativeClient.createUploader({
+            ...options,
+            requestId,
+            hooks: createHooks(options.path, 'POST', requestId, operationContext, true)
+        });
+    return {
+        configure,
+        createRequest,
+        createUploader
+    };
+};
+export { createPolicyClient };

package/dist/esm/request-policy/policyCore.mjs

@@ -0,0 +1,171 @@
+import { parseTraceparent } from "./traceparent.mjs";
+const TRACEPARENT_HEADER = 'traceparent';
+const readProcessEnv = (key)=>{
+    if ("u" < typeof process || void 0 === process.env || 'string' != typeof process.env[key]) return;
+    return process.env[key];
+};
+const isStrictDefaultRequestIdEnabled = ()=>'true' === readProcessEnv('MODERN_BFF_STRICT_DEFAULT_REQUEST_ID');
+const isSecuredRequestId = (requestId)=>'default' !== requestId || isStrictDefaultRequestIdEnabled();
+const isEmptyDomain = (domain)=>'string' != typeof domain || '' === domain.trim();
+const firstHeaderValue = (value)=>Array.isArray(value) ? value[0] : value;
+const findHeaderKey = (headers, header)=>{
+    const normalized = header.toLowerCase();
+    return Object.keys(headers).find((key)=>key.toLowerCase() === normalized);
+};
+const readHeader = (headers, header)=>{
+    const key = findHeaderKey(headers, header);
+    return 'string' == typeof key ? headers[key] : void 0;
+};
+const writeHeader = (headers, header, value)=>{
+    if (void 0 === value) return;
+    const key = findHeaderKey(headers, header);
+    if ('string' == typeof key && key !== header) delete headers[key];
+    headers[header] = value;
+};
+const deleteHeader = (headers, header)=>{
+    const key = findHeaderKey(headers, header);
+    if ('string' == typeof key) delete headers[key];
+};
+const toOrigin = (value)=>{
+    if (!value) return;
+    try {
+        return new URL(value).origin;
+    } catch (error) {
+        return;
+    }
+};
+const parseTraceparentValue = (value)=>parseTraceparent(firstHeaderValue(value));
+const buildOperationContext = ({ requestId, method, path, operationContext, traceparent })=>{
+    const routePath = operationContext?.routePath || path;
+    const operationMethod = (operationContext?.method || method || 'GET').toUpperCase();
+    const rawOperationId = operationContext?.operationId || `${operationMethod}:${routePath}`;
+    const operationId = rawOperationId.startsWith(`${requestId}:`) ? rawOperationId : `${requestId}:${rawOperationId}`;
+    const traceparentValue = operationContext?.traceparent || ('string' == typeof firstHeaderValue(traceparent) ? String(firstHeaderValue(traceparent)) : void 0);
+    const parsedTraceContext = operationContext?.traceId && operationContext?.spanId ? {
+        traceId: operationContext.traceId,
+        spanId: operationContext.spanId
+    } : parseTraceparentValue(traceparentValue);
+    return {
+        requestId,
+        operationId,
+        routePath,
+        method: operationMethod,
+        ...operationContext?.schemaHash ? {
+            schemaHash: operationContext.schemaHash
+        } : {},
+        ...'number' == typeof operationContext?.operationVersion ? {
+            operationVersion: operationContext.operationVersion
+        } : {},
+        ...traceparentValue ? {
+            traceparent: traceparentValue
+        } : {},
+        ...parsedTraceContext ? {
+            traceId: parsedTraceContext.traceId,
+            spanId: parsedTraceContext.spanId
+        } : {}
+    };
+};
+class ProducerClientNotInitializedError extends Error {
+    constructor(requestId){
+        super(`Producer client "${requestId}" is not initialized. Call initProducerClient() (or configure()) before using generated APIs for this requestId.`), this.code = 'BFF_PRODUCER_CLIENT_NOT_INITIALIZED';
+        this.name = 'ProducerClientNotInitializedError';
+    }
+}
+class ProducerDomainNotConfiguredError extends Error {
+    constructor(requestId){
+        super(`Producer client "${requestId}" must provide setDomain() during configure().`), this.code = 'BFF_PRODUCER_DOMAIN_NOT_CONFIGURED';
+        this.name = 'ProducerDomainNotConfiguredError';
+    }
+}
+class CrossOriginEnvelopePolicyError extends Error {
+    constructor(requestId, sourceOrigin, targetOrigin){
+        super(`Cross-origin envelope is not allowed for producer "${requestId}" (${sourceOrigin || 'unknown-origin'} -> ${targetOrigin || 'unknown-origin'}). Configure allowCrossOriginEnvelope to explicitly allow this flow.`), this.code = 'BFF_CROSS_ORIGIN_ENVELOPE_NOT_ALLOWED';
+        this.name = 'CrossOriginEnvelopePolicyError';
+    }
+}
+class IdentityBindingViolationError extends Error {
+    constructor(violation){
+        super(`Identity header "${violation.header}" for producer "${violation.requestId}" was rejected by server-derived identity binding.`), this.code = 'BFF_IDENTITY_BINDING_VIOLATION';
+        this.name = 'IdentityBindingViolationError';
+        this.violation = violation;
+    }
+}
+class OperationContractViolationError extends Error {
+    constructor(violation){
+        super(`Operation contract violation "${violation.reason}" for producer "${violation.requestId}" operation "${violation.operationId}".`), this.code = 'BFF_OPERATION_CONTRACT_VIOLATION';
+        this.name = 'OperationContractViolationError';
+        this.violation = violation;
+    }
+}
+const validateOperationContract = ({ requestId, target, contextPayload, operationContract })=>{
+    const operationContractEnabled = operationContract?.enabled ?? isSecuredRequestId(requestId);
+    if (!operationContractEnabled) return;
+    const strict = operationContract?.strict ?? true;
+    const requireSchemaHash = operationContract?.requireSchemaHash ?? true;
+    const requireOperationVersion = operationContract?.requireOperationVersion ?? true;
+    const maybeReportViolation = (reason)=>{
+        const violation = {
+            requestId,
+            target,
+            operationId: contextPayload.operationId,
+            routePath: contextPayload.routePath,
+            method: contextPayload.method,
+            schemaHash: 'string' == typeof contextPayload.schemaHash ? contextPayload.schemaHash : void 0,
+            operationVersion: 'number' == typeof contextPayload.operationVersion ? contextPayload.operationVersion : void 0,
+            reason
+        };
+        operationContract?.onViolation?.(violation);
+        if (strict) throw new OperationContractViolationError(violation);
+    };
+    if (requireSchemaHash && 'string' != typeof contextPayload.schemaHash) maybeReportViolation('missing_schema_hash');
+    if (requireOperationVersion && 'number' != typeof contextPayload.operationVersion) maybeReportViolation('missing_operation_version');
+};
+const resolveConfiguredRequest = (configuredRequests, requestId, fallback)=>{
+    const configuredRequest = configuredRequests.get(requestId);
+    if (configuredRequest) return configuredRequest;
+    if ('default' !== requestId) throw new ProducerClientNotInitializedError(requestId);
+    return fallback;
+};
+const buildEnvelopeHeaderValue = ({ requestId, target, sourceOrigin, targetOrigin, traceContext, allowCrossOriginEnvelope })=>{
+    const isCrossOrigin = Boolean(sourceOrigin) && Boolean(targetOrigin) && sourceOrigin !== targetOrigin;
+    if (isCrossOrigin) {
+        const isAllowed = 'function' == typeof allowCrossOriginEnvelope ? true === allowCrossOriginEnvelope({
+            requestId,
+            sourceOrigin,
+            targetOrigin,
+            target
+        }) : true === allowCrossOriginEnvelope;
+        if (!isAllowed) throw new CrossOriginEnvelopePolicyError(requestId, sourceOrigin, targetOrigin);
+    }
+    return JSON.stringify({
+        requestId,
+        target,
+        timestamp: Date.now(),
+        sourceOrigin,
+        targetOrigin,
+        ...traceContext ? {
+            traceId: traceContext.traceId,
+            spanId: traceContext.spanId
+        } : {}
+    });
+};
+const attachOperationContextHeaders = ({ headers, requestId, target, method, path, operationContext, operationContract, operationContextHeader, operationContextDetailHeader })=>{
+    if (void 0 === readHeader(headers, TRACEPARENT_HEADER) && operationContext?.traceparent) writeHeader(headers, TRACEPARENT_HEADER, operationContext.traceparent);
+    const contextPayload = buildOperationContext({
+        requestId,
+        method,
+        path,
+        operationContext,
+        traceparent: readHeader(headers, TRACEPARENT_HEADER)
+    });
+    validateOperationContract({
+        requestId,
+        target,
+        contextPayload,
+        operationContract
+    });
+    if (void 0 === readHeader(headers, operationContextHeader)) writeHeader(headers, operationContextHeader, contextPayload.operationId);
+    writeHeader(headers, operationContextDetailHeader, JSON.stringify(contextPayload));
+    return contextPayload;
+};
+export { CrossOriginEnvelopePolicyError, IdentityBindingViolationError, OperationContractViolationError, ProducerClientNotInitializedError, ProducerDomainNotConfiguredError, TRACEPARENT_HEADER, attachOperationContextHeaders, buildEnvelopeHeaderValue, buildOperationContext, deleteHeader, findHeaderKey, firstHeaderValue, isEmptyDomain, isSecuredRequestId, parseTraceparentValue, readHeader, resolveConfiguredRequest, toOrigin, validateOperationContract, writeHeader };

package/dist/esm/request-policy/requestContext.mjs

@@ -0,0 +1,75 @@
+import { parseTraceparent } from "./traceparent.mjs";
+const BFF_LOCALE_HEADER = 'accept-language';
+const BFF_TRACEPARENT_HEADER = 'traceparent';
+const readHeader = (headers, header)=>{
+    if (!headers) return;
+    const normalized = header.toLowerCase();
+    const key = Object.keys(headers).find((current)=>current.toLowerCase() === normalized);
+    if (!key) return;
+    const value = headers[key];
+    return Array.isArray(value) ? value[0] : value;
+};
+const readString = (value)=>'string' == typeof value && value.length > 0 ? value : void 0;
+function createOperationContextSnapshot(operationContext, safeContext) {
+    if (!operationContext) return;
+    const snapshot = {
+        ...operationContext,
+        ...safeContext.locale || operationContext?.locale ? {
+            locale: safeContext.locale || operationContext?.locale
+        } : {},
+        ...safeContext.traceparent || operationContext?.traceparent ? {
+            traceparent: safeContext.traceparent || operationContext?.traceparent
+        } : {},
+        ...safeContext.traceId || operationContext?.traceId ? {
+            traceId: safeContext.traceId || operationContext?.traceId
+        } : {},
+        ...safeContext.spanId || operationContext?.spanId ? {
+            spanId: safeContext.spanId || operationContext?.spanId
+        } : {}
+    };
+    return Object.keys(snapshot).some((key)=>void 0 !== snapshot[key]) ? snapshot : void 0;
+}
+function createRequestContextSnapshot(input = {}) {
+    const locale = readString(input.locale) || readString(readHeader(input.headers, BFF_LOCALE_HEADER));
+    const traceparent = readString(input.traceparent) || readString(input.operationContext?.traceparent) || readString(readHeader(input.headers, BFF_TRACEPARENT_HEADER));
+    const parsedTraceparent = input.operationContext?.traceId && input.operationContext?.spanId ? {
+        traceId: input.operationContext.traceId,
+        spanId: input.operationContext.spanId
+    } : parseTraceparent(traceparent);
+    const headers = {};
+    if (locale) headers[BFF_LOCALE_HEADER] = locale;
+    if (traceparent) headers[BFF_TRACEPARENT_HEADER] = traceparent;
+    const operationContext = createOperationContextSnapshot(input.operationContext, {
+        ...locale ? {
+            locale
+        } : {},
+        ...traceparent ? {
+            traceparent
+        } : {},
+        ...parsedTraceparent ? {
+            traceId: parsedTraceparent.traceId,
+            spanId: parsedTraceparent.spanId
+        } : {}
+    });
+    return {
+        headers,
+        ...locale ? {
+            locale
+        } : {},
+        ...traceparent ? {
+            traceparent
+        } : {},
+        ...parsedTraceparent ? {
+            traceId: parsedTraceparent.traceId,
+            spanId: parsedTraceparent.spanId
+        } : {},
+        ...operationContext ? {
+            operationContext
+        } : {}
+    };
+}
+function createRequestContextHeaders(input = {}) {
+    return createRequestContextSnapshot(input).headers;
+}
+export { BFF_DEFAULT_PROTECTED_IDENTITY_HEADERS, BFF_ENVELOPE_HEADER, BFF_OPERATION_CONTEXT_DETAIL_HEADER, BFF_OPERATION_CONTEXT_HEADER } from "./types.mjs";
+export { BFF_LOCALE_HEADER, BFF_TRACEPARENT_HEADER, createRequestContextHeaders, createRequestContextSnapshot, parseTraceparent };

package/dist/esm/request-policy/traceparent.mjs

@@ -0,0 +1,18 @@
+const TRACEPARENT_REGEX = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/i;
+const isAllZeroHex = (value)=>/^0+$/.test(value);
+function parseTraceparent(traceparent) {
+    if (!traceparent) return;
+    const match = traceparent.trim().match(TRACEPARENT_REGEX);
+    if (!match) return;
+    const [, rawTraceId, rawSpanId, rawFlags] = match;
+    if (!rawTraceId || !rawSpanId || !rawFlags) return;
+    const traceId = rawTraceId.toLowerCase();
+    const spanId = rawSpanId.toLowerCase();
+    if (isAllZeroHex(traceId) || isAllZeroHex(spanId)) return;
+    return {
+        traceId,
+        spanId,
+        sampled: (0x1 & Number.parseInt(rawFlags, 16)) === 1
+    };
+}
+export { parseTraceparent };

package/dist/esm/request-policy/transport.mjs

@@ -0,0 +1,196 @@
+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'
+]);
+const createTimeoutError = (timeoutMs)=>{
+    const error = new Error(`Request timed out after ${timeoutMs}ms`);
+    error.name = 'TimeoutError';
+    return error;
+};
+const unrefTimer = (timer)=>{
+    if ('object' == typeof timer && null !== timer && 'unref' in timer && 'function' == typeof timer.unref) timer.unref();
+};
+const wait = (ms)=>new Promise((resolve)=>{
+        const timer = setTimeout(()=>resolve(), ms);
+        unrefTimer(timer);
+    });
+const toStatusCode = (error)=>{
+    if (!error || 'object' != typeof error) return;
+    const status = error.status;
+    if ('number' == typeof status) return status;
+    const responseStatus = error.response?.status;
+    if ('number' == typeof responseStatus) return responseStatus;
+};
+const isRetryableNetworkError = (error)=>{
+    if (!error || 'object' != typeof error) return false;
+    const name = error.name;
+    if ('FetchError' === name || 'TimeoutError' === name || 'TypeError' === name) return true;
+    const code = error.code;
+    return 'ECONNRESET' === code || 'ETIMEDOUT' === code || 'ECONNREFUSED' === code || 'EPIPE' === code;
+};
+const normalizePositiveNumber = (value, fallback)=>'number' == typeof value && Number.isFinite(value) && value > 0 ? value : fallback;
+const normalizeNonNegativeInt = (value, fallback)=>'number' == typeof value && Number.isFinite(value) && value >= 0 ? Math.floor(value) : fallback;
+const normalizeJitterRatio = (value)=>{
+    if ('number' != typeof value || !Number.isFinite(value)) return DEFAULT_JITTER_RATIO;
+    return Math.max(0, Math.min(1, value));
+};
+const shouldRetryWithDefaults = (method, statusCode, error, retryableStatusCodes)=>{
+    if (!DEFAULT_RETRYABLE_METHODS.has(method.toUpperCase())) return false;
+    if ('number' == typeof statusCode) return retryableStatusCodes.includes(statusCode);
+    return isRetryableNetworkError(error);
+};
+const shouldRetry = (retryOptions, context, retryableStatusCodes)=>{
+    if ('function' == typeof retryOptions?.shouldRetry) try {
+        return retryOptions.shouldRetry(context);
+    } catch (error) {
+        return false;
+    }
+    return shouldRetryWithDefaults(context.method, context.statusCode, context.error, retryableStatusCodes);
+};
+const getBackoffMs = (retryOptions, attempt)=>{
+    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 = 0 === jitterRatio ? 1 : 1 + (2 * Math.random() - 1) * jitterRatio;
+    return Math.max(0, Math.floor(exponentialDelay * jitterFactor));
+};
+const emitDegradedEvent = (transport, event)=>{
+    if ('function' != typeof transport?.onDegraded) return;
+    try {
+        transport.onDegraded(event);
+    } catch (error) {}
+};
+const withTimeout = async (promise, timeoutMs, signalBuilder)=>{
+    if (!timeoutMs || timeoutMs <= 0) {
+        const result = await promise;
+        return {
+            result
+        };
+    }
+    const controller = signalBuilder?.();
+    let timeoutTriggered = false;
+    let rejectTimeout;
+    const timeoutPromise = new Promise((_, 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?.name === 'AbortError') throw createTimeoutError(timeoutMs);
+        throw error;
+    } finally{
+        clearTimeout(timer);
+    }
+};
+const executeWithResilience = async ({ requestId, target, method, url, init, fetcher, transport })=>{
+    const retries = normalizeNonNegativeInt(transport?.retry?.retries, 0);
+    const timeoutMs = 'number' == typeof transport?.timeoutMs && transport.timeoutMs > 0 ? transport.timeoutMs : void 0;
+    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 = "u" > typeof AbortController;
+        let controller;
+        if (timeoutMs && canUseAbortController) controller = new AbortController();
+        const callerSignal = init.signal;
+        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 = {
+                requestId,
+                target,
+                method,
+                url,
+                attempt,
+                maxAttempts,
+                error,
+                statusCode
+            };
+            if (error?.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?.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);
+        }
+    }
+};
+export { executeWithResilience };

package/dist/esm/request-policy/types.mjs

@@ -0,0 +1,10 @@
+const BFF_ENVELOPE_HEADER = 'x-modernjs-bff-envelope';
+const BFF_OPERATION_CONTEXT_HEADER = 'x-operation-id';
+const BFF_OPERATION_CONTEXT_DETAIL_HEADER = 'x-modernjs-bff-operation-context';
+const BFF_DEFAULT_PROTECTED_IDENTITY_HEADERS = [
+    'x-tenant-id',
+    'x-subject-id',
+    'x-user-id',
+    BFF_OPERATION_CONTEXT_HEADER
+];
+export { BFF_DEFAULT_PROTECTED_IDENTITY_HEADERS, BFF_ENVELOPE_HEADER, BFF_OPERATION_CONTEXT_DETAIL_HEADER, BFF_OPERATION_CONTEXT_HEADER };