@apifuse/provider-sdk 2.2.0-beta.1 → 2.2.0-beta.2

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.2
+
+- Release candidate for main commit ceefad020a1038eade542fd3b128667b39625f6f.
+
 ## 2.2.0-beta.1
 
 - Release candidate for main commit 5056b8c89fe0fa8f10bafcd30f83bcc421d4b5c5.
@@ -35,6 +39,7 @@
 ## Unreleased
 
 - Add `arrayBuffer()` and `bytes()` to `HttpResponse` so `ctx.http` consumers can read binary-safe upstream bodies; internal response handling is now byte-first.
+- Preserve identity-only operation `connectionId` values in `ProviderContext` without requiring credential material.
 
 ## 2.1.0-beta.15
 

package/dist/runtime/http.js

@@ -1,317 +1,12 @@
 import { resolveProxyConfigAsync } from "../config/loader";
 import { ProviderError, TransportError } from "../errors";
-import { parseSseStream, readableBytes, readableLines, readableTextChunks, } from "../stream";
-import { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "../types";
+import { parseSseStream, readableBytes, readableLines, readableTextChunks } from "../stream";
+import { computeProxyAttemptIndex, computeProxyTransportRetryDelayMs, createDefaultProxyTransportRetryOptions, isProxyTransportRetryMethod, normalizeProxyTransportRetryOptions, proxyTransportRetryErrorCode, proxyTransportRetryErrorStatus, shouldRetryProxyTransportAttempt, validateUnsafeProxyTransportRetryMethods, } from "./proxy-retry-policy";
 import { appendQueryParams, normalizeHttpRequestBody } from "./request-options";
 const DEFAULT_HTTP_BASE_URL = "http://localhost";
 function isHttpStatusOutcome(outcome) {
     return "kind" in outcome && outcome.kind === "http-status";
 }
-const DEFAULT_RETRY_METHODS = ["GET", "HEAD", "OPTIONS"];
-const DEFAULT_RETRY_ERROR_CODES = [
-    "transport_network_error",
-    "transport_timeout",
-];
-const SAFE_RETRY_STATUS_CODES = [408, 429, 500, 502, 503, 504];
-const RATE_LIMIT_RETRY_STATUS_CODES = [429, 503];
-const KNOWN_RETRY_METHODS = new Set([
-    "GET",
-    "HEAD",
-    "POST",
-    "PUT",
-    "DELETE",
-    "OPTIONS",
-    "TRACE",
-    "PATCH",
-]);
-const UNSAFE_RETRY_METHODS = new Set([
-    "POST",
-    "PUT",
-    "PATCH",
-    "DELETE",
-    "TRACE",
-]);
-const MAX_RETRY_ATTEMPTS = 8;
-const MAX_RETRY_DELAY_MS = 30_000;
-function hasOwnValue(values, value) {
-    if (typeof value !== "string")
-        return false;
-    return Object.values(values).some((candidate) => candidate === value);
-}
-function createInvalidRetryPolicyError(message) {
-    return new ProviderError(message, { code: "retry_invalid_policy" });
-}
-function createRetryOptions(preset) {
-    switch (preset) {
-        case HttpRetryPreset.Off:
-            return {
-                preset,
-                attempts: 1,
-                methods: DEFAULT_RETRY_METHODS,
-                statusCodes: [],
-                errorCodes: DEFAULT_RETRY_ERROR_CODES,
-                delayStrategy: HttpRetryDelayStrategy.Exponential,
-                baseDelayMs: 100,
-                maxDelayMs: 1_000,
-                jitter: HttpRetryJitter.Full,
-                retryAfter: HttpRetryAfterPolicy.Ignore,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-        case HttpRetryPreset.SafeRead:
-            return {
-                preset,
-                attempts: 3,
-                methods: DEFAULT_RETRY_METHODS,
-                statusCodes: SAFE_RETRY_STATUS_CODES,
-                errorCodes: DEFAULT_RETRY_ERROR_CODES,
-                delayStrategy: HttpRetryDelayStrategy.Exponential,
-                baseDelayMs: 100,
-                maxDelayMs: 2_000,
-                jitter: HttpRetryJitter.Full,
-                retryAfter: HttpRetryAfterPolicy.Cap,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-        case HttpRetryPreset.AggressiveRead:
-            return {
-                preset,
-                attempts: 4,
-                methods: DEFAULT_RETRY_METHODS,
-                statusCodes: SAFE_RETRY_STATUS_CODES,
-                errorCodes: DEFAULT_RETRY_ERROR_CODES,
-                delayStrategy: HttpRetryDelayStrategy.Exponential,
-                baseDelayMs: 150,
-                maxDelayMs: 5_000,
-                jitter: HttpRetryJitter.Full,
-                retryAfter: HttpRetryAfterPolicy.Cap,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-        case HttpRetryPreset.RateLimitAware:
-            return {
-                preset,
-                attempts: 3,
-                methods: DEFAULT_RETRY_METHODS,
-                statusCodes: RATE_LIMIT_RETRY_STATUS_CODES,
-                errorCodes: ["transport_timeout"],
-                delayStrategy: HttpRetryDelayStrategy.Exponential,
-                baseDelayMs: 250,
-                maxDelayMs: 5_000,
-                jitter: HttpRetryJitter.Equal,
-                retryAfter: HttpRetryAfterPolicy.Respect,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-        case HttpRetryPreset.TransportTransient:
-            return {
-                preset,
-                attempts: 3,
-                methods: DEFAULT_RETRY_METHODS,
-                statusCodes: [],
-                errorCodes: DEFAULT_RETRY_ERROR_CODES,
-                delayStrategy: HttpRetryDelayStrategy.Exponential,
-                baseDelayMs: 100,
-                maxDelayMs: 1_000,
-                jitter: HttpRetryJitter.Full,
-                retryAfter: HttpRetryAfterPolicy.Ignore,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-    }
-    throw createInvalidRetryPolicyError(`Unknown HTTP retry preset: ${preset}`);
-}
-function clampPositiveInteger(value, fallback, max) {
-    if (value === undefined)
-        return fallback;
-    if (!Number.isFinite(value) || value < 1)
-        return fallback;
-    return Math.min(Math.floor(value), max);
-}
-function clampDelay(value, fallback) {
-    if (value === undefined)
-        return fallback;
-    if (!Number.isFinite(value) || value < 0)
-        return fallback;
-    return Math.min(Math.floor(value), MAX_RETRY_DELAY_MS);
-}
-function normalizeRetryOptions(retry) {
-    if (retry === undefined || retry === false) {
-        return undefined;
-    }
-    if (retry === true) {
-        return createRetryOptions(HttpRetryPreset.TransportTransient);
-    }
-    if (typeof retry === "string") {
-        if (!hasOwnValue(HttpRetryPreset, retry)) {
-            throw createInvalidRetryPolicyError(`Unknown HTTP retry preset: ${retry}`);
-        }
-        return createRetryOptions(retry);
-    }
-    if (typeof retry !== "object" || retry === null) {
-        throw createInvalidRetryPolicyError("HTTP retry policy must be an object");
-    }
-    if (Array.isArray(retry)) {
-        throw createInvalidRetryPolicyError("HTTP retry policy must be a plain object");
-    }
-    validateRetryOptionsShape(retry);
-    const base = createRetryOptions(retry.preset ?? HttpRetryPreset.TransportTransient);
-    const maxDelayMs = clampDelay(retry.maxDelayMs, base.maxDelayMs);
-    const normalized = {
-        preset: retry.preset ?? base.preset,
-        attempts: clampPositiveInteger(retry.attempts, base.attempts, MAX_RETRY_ATTEMPTS),
-        methods: retry.methods?.map((method) => method.toUpperCase()) ?? base.methods,
-        statusCodes: retry.statusCodes?.filter((status) => Number.isInteger(status)) ??
-            base.statusCodes,
-        errorCodes: retry.errorCodes ?? base.errorCodes,
-        delayStrategy: retry.delayStrategy ?? base.delayStrategy,
-        baseDelayMs: clampDelay(retry.baseDelayMs, base.baseDelayMs),
-        maxDelayMs,
-        jitter: retry.jitter ?? base.jitter,
-        retryAfter: retry.retryAfter ?? base.retryAfter,
-        unsafeMethodPolicy: retry.unsafeMethodPolicy ?? base.unsafeMethodPolicy,
-    };
-    return normalized;
-}
-function validateRetryOptionsShape(retry) {
-    if (retry.preset !== undefined &&
-        !hasOwnValue(HttpRetryPreset, retry.preset)) {
-        throw createInvalidRetryPolicyError(`Unknown HTTP retry preset: ${String(retry.preset)}`);
-    }
-    if (retry.delayStrategy !== undefined &&
-        !hasOwnValue(HttpRetryDelayStrategy, retry.delayStrategy)) {
-        throw createInvalidRetryPolicyError(`Unknown HTTP retry delay strategy: ${String(retry.delayStrategy)}`);
-    }
-    if (retry.jitter !== undefined &&
-        !hasOwnValue(HttpRetryJitter, retry.jitter)) {
-        throw createInvalidRetryPolicyError(`Unknown HTTP retry jitter policy: ${String(retry.jitter)}`);
-    }
-    if (retry.retryAfter !== undefined &&
-        !hasOwnValue(HttpRetryAfterPolicy, retry.retryAfter)) {
-        throw createInvalidRetryPolicyError(`Unknown HTTP retry-after policy: ${String(retry.retryAfter)}`);
-    }
-    if (retry.unsafeMethodPolicy !== undefined &&
-        !hasOwnValue(HttpRetryUnsafeMethodPolicy, retry.unsafeMethodPolicy)) {
-        throw createInvalidRetryPolicyError(`Unknown HTTP retry unsafe method policy: ${String(retry.unsafeMethodPolicy)}`);
-    }
-    if (retry.methods !== undefined) {
-        if (!Array.isArray(retry.methods)) {
-            throw createInvalidRetryPolicyError("HTTP retry methods must be an array");
-        }
-        const nonStringMethods = retry.methods.filter((method) => typeof method !== "string");
-        if (nonStringMethods.length > 0) {
-            throw createInvalidRetryPolicyError("HTTP retry methods must contain only strings");
-        }
-        const unknownMethods = retry.methods
-            .map((method) => method.toUpperCase())
-            .filter((method) => !KNOWN_RETRY_METHODS.has(method));
-        if (unknownMethods.length > 0) {
-            throw createInvalidRetryPolicyError(`Unknown HTTP retry method(s): ${unknownMethods.join(", ")}`);
-        }
-    }
-    if (retry.statusCodes !== undefined) {
-        if (!Array.isArray(retry.statusCodes)) {
-            throw createInvalidRetryPolicyError("HTTP retry statusCodes must be an array");
-        }
-        const invalidStatusCodes = retry.statusCodes.filter((status) => !Number.isInteger(status) ||
-            Number(status) < 100 ||
-            Number(status) > 599);
-        if (invalidStatusCodes.length > 0) {
-            throw createInvalidRetryPolicyError("HTTP retry statusCodes must contain HTTP status integers in [100, 599]");
-        }
-    }
-    if (retry.errorCodes !== undefined) {
-        if (!Array.isArray(retry.errorCodes)) {
-            throw createInvalidRetryPolicyError("HTTP retry errorCodes must be an array");
-        }
-        const nonStringErrorCodes = retry.errorCodes.filter((errorCode) => typeof errorCode !== "string");
-        if (nonStringErrorCodes.length > 0) {
-            throw createInvalidRetryPolicyError("HTTP retry errorCodes must contain only strings");
-        }
-    }
-    if (retry.preset === HttpRetryPreset.Off &&
-        ((retry.attempts !== undefined && retry.attempts > 1) ||
-            (retry.statusCodes !== undefined && retry.statusCodes.length > 0))) {
-        throw createInvalidRetryPolicyError("HTTP retry preset off cannot be combined with retry-enabling overrides");
-    }
-}
-function validateUnsafeRetryMethods(options) {
-    if (options.unsafeMethodPolicy ===
-        HttpRetryUnsafeMethodPolicy.AllowExplicitUnsafe) {
-        return;
-    }
-    const unsafeMethods = options.methods.filter((method) => UNSAFE_RETRY_METHODS.has(method.toUpperCase()));
-    if (unsafeMethods.length === 0)
-        return;
-    throw new ProviderError(`HTTP retry methods include unsafe method(s): ${unsafeMethods.join(", ")}`, { code: "retry_unsafe_method" });
-}
-function isMethodRetryable(method, options) {
-    return options.methods
-        .map((allowedMethod) => allowedMethod.toUpperCase())
-        .includes(method.toUpperCase());
-}
-function retryErrorCode(error) {
-    if (error instanceof TransportError) {
-        return error.code;
-    }
-    if (error && typeof error === "object" && "code" in error) {
-        const code = Reflect.get(error, "code");
-        return typeof code === "string" ? code : undefined;
-    }
-    return undefined;
-}
-function retryErrorStatus(error) {
-    if (error instanceof TransportError) {
-        return error.status ?? error.upstreamStatus;
-    }
-    return undefined;
-}
-function shouldRetryTransportError(error, options) {
-    const code = retryErrorCode(error);
-    return Boolean(code && options.errorCodes.includes(code));
-}
-function retryAfterHeader(headers) {
-    for (const [name, value] of Object.entries(headers)) {
-        if (name.toLowerCase() === "retry-after")
-            return value;
-    }
-    return undefined;
-}
-function parseRetryAfterMs(headers, now = Date.now()) {
-    const value = retryAfterHeader(headers);
-    if (!value)
-        return undefined;
-    const seconds = Number(value);
-    if (Number.isFinite(seconds)) {
-        return Math.max(0, Math.floor(seconds * 1_000));
-    }
-    const dateMs = Date.parse(value);
-    if (!Number.isNaN(dateMs)) {
-        return Math.max(0, dateMs - now);
-    }
-    return undefined;
-}
-function computeRetryDelayMs(options, attemptIndex, headers) {
-    const multiplier = options.delayStrategy === HttpRetryDelayStrategy.Exponential
-        ? 2 ** Math.max(0, attemptIndex - 1)
-        : 1;
-    const configuredDelay = Math.min(options.baseDelayMs * multiplier, options.maxDelayMs);
-    const retryAfterMs = options.retryAfter === HttpRetryAfterPolicy.Ignore
-        ? undefined
-        : headers
-            ? parseRetryAfterMs(headers)
-            : undefined;
-    if (retryAfterMs !== undefined) {
-        const boundedRetryAfterMs = Math.min(retryAfterMs, options.maxDelayMs);
-        if (options.retryAfter === HttpRetryAfterPolicy.Cap) {
-            return Math.min(boundedRetryAfterMs, configuredDelay);
-        }
-        return boundedRetryAfterMs;
-    }
-    switch (options.jitter) {
-        case HttpRetryJitter.None:
-            return configuredDelay;
-        case HttpRetryJitter.Equal:
-            return Math.floor(configuredDelay / 2 + Math.random() * (configuredDelay / 2));
-        case HttpRetryJitter.Full:
-            return Math.floor(Math.random() * configuredDelay);
-    }
-}
 async function sleep(ms) {
     if (ms <= 0)
         return;
@@ -330,9 +25,7 @@ function hasHeader(headers, name) {
 }
 function withClientHeaders(options, clientOptions, body) {
     const headers = {
-        ...(clientOptions.userAgent
-            ? { "User-Agent": clientOptions.userAgent }
-            : {}),
+        ...(clientOptions.userAgent ? { "User-Agent": clientOptions.userAgent } : {}),
         ...options?.headers,
     };
     if (body !== undefined && !hasHeader(headers, "Content-Type")) {
@@ -344,9 +37,7 @@ function withClientHeaders(options, clientOptions, body) {
     };
 }
 function parseHttpData(body, headers) {
-    const contentType = headers["content-type"] ??
-        headers["Content-Type"] ??
-        headers["CONTENT-TYPE"];
+    const contentType = headers["content-type"] ?? headers["Content-Type"] ?? headers["CONTENT-TYPE"];
     if (contentType?.includes("application/json")) {
         return body ? JSON.parse(body) : null;
     }
@@ -403,12 +94,8 @@ async function toNativeHttpResponse(response) {
         data,
         headers,
         json: async () => {
-            const contentType = headers["content-type"] ??
-                headers["Content-Type"] ??
-                headers["CONTENT-TYPE"];
-            return parseJson(contentType?.includes("application/json") && !rawText
-                ? "null"
-                : rawText);
+            const contentType = headers["content-type"] ?? headers["Content-Type"] ?? headers["CONTENT-TYPE"];
+            return parseJson(contentType?.includes("application/json") && !rawText ? "null" : rawText);
         },
         ok: response.status >= 200 && response.status < 300,
         status: response.status,
@@ -478,17 +165,16 @@ function resolveHttpUrl(baseUrl, url) {
     return new URL(url, baseUrl ?? DEFAULT_HTTP_BASE_URL).toString();
 }
 async function resolveNativeProxy(options, clientOptions, warn, proxyAttemptOffset = 0) {
-    const baseProxyAttempt = clientOptions.proxyAttempt === undefined ||
-        !Number.isFinite(clientOptions.proxyAttempt)
-        ? 0
-        : Math.max(0, Math.floor(clientOptions.proxyAttempt));
     const resolvedProxy = await resolveProxyConfigAsync({
         proxy: options.proxy ?? clientOptions.proxy,
         upstream: clientOptions.upstream,
         apifuseConfig: clientOptions.apifuseConfig,
         proxyPolicy: clientOptions.proxyPolicy,
         affinityKey: clientOptions.affinityKey,
-        proxyAttempt: baseProxyAttempt + proxyAttemptOffset,
+        proxyAttempt: computeProxyAttemptIndex({
+            baseProxyAttempt: clientOptions.proxyAttempt,
+            retryAttemptOffset: proxyAttemptOffset,
+        }),
         telemetry: clientOptions.telemetry,
     });
     if (resolvedProxy.shouldWarn) {
@@ -622,15 +308,15 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
         const headersOptions = withClientHeaders(options, clientOptions, options.body);
         const methodName = normalizeHttpMethod(method);
         const explicitRetry = headersOptions.retry !== undefined;
-        const retryOptions = normalizeRetryOptions(headersOptions.retry) ??
-            (explicitRetry
-                ? undefined
-                : createRetryOptions(HttpRetryPreset.TransportTransient));
+        const retryOptions = normalizeProxyTransportRetryOptions(headersOptions.retry, {
+            label: "HTTP",
+        }) ??
+            (explicitRetry ? undefined : createDefaultProxyTransportRetryOptions({ label: "HTTP" }));
         if (retryOptions)
-            validateUnsafeRetryMethods(retryOptions);
+            validateUnsafeProxyTransportRetryMethods(retryOptions, "HTTP");
         const retryEnabled = Boolean(retryOptions &&
             retryOptions.attempts > 1 &&
-            isMethodRetryable(methodName, retryOptions));
+            isProxyTransportRetryMethod(methodName, retryOptions));
         const statusRetryEnabled = Boolean(retryEnabled &&
             explicitRetry &&
             retryOptions &&
@@ -655,14 +341,13 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
                 if (isHttpStatusOutcome(outcome)) {
                     lastStatus = outcome.status;
                     if (outcome.retryable && attempt < retryOptions.attempts) {
-                        await sleep(computeRetryDelayMs(retryOptions, attempt, outcome.headers));
+                        await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt, outcome.headers));
                         continue;
                     }
                     throw toUpstreamHttpError(outcome.status);
                 }
                 const response = outcome;
-                if (response.status >= 400 &&
-                    headersOptions.throwOnHttpError !== false) {
+                if (response.status >= 400 && headersOptions.throwOnHttpError !== false) {
                     throw toUpstreamHttpError(response.status);
                 }
                 if (attempt > 1) {
@@ -679,13 +364,18 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
                 return response;
             }
             catch (error) {
-                lastErrorCode = retryErrorCode(error);
-                lastStatus = retryErrorStatus(error);
+                lastErrorCode = proxyTransportRetryErrorCode(error);
+                lastStatus = proxyTransportRetryErrorStatus(error);
                 const proxyUsed = Boolean(error.proxyUsed);
                 if (attempt < retryOptions.attempts &&
-                    (explicitRetry || proxyUsed) &&
-                    shouldRetryTransportError(error, retryOptions)) {
-                    await sleep(computeRetryDelayMs(retryOptions, attempt));
+                    shouldRetryProxyTransportAttempt({
+                        error,
+                        explicitRetry,
+                        method: methodName,
+                        options: retryOptions,
+                        proxyUsed,
+                    })) {
+                    await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt));
                     continue;
                 }
                 throw error;

package/dist/runtime/proxy-retry-policy.d.ts

@@ -0,0 +1,40 @@
+import type { HttpMethod, HttpRetryOptions, RequestOptions } from "../types";
+import { HttpRetryPreset } from "../types";
+export type NormalizedProxyTransportRetryOptions = Required<Pick<HttpRetryOptions, "attempts" | "delayStrategy" | "baseDelayMs" | "maxDelayMs" | "jitter" | "retryAfter" | "unsafeMethodPolicy">> & {
+    preset?: HttpRetryPreset;
+    methods: readonly string[];
+    statusCodes: readonly number[];
+    errorCodes: readonly string[];
+};
+export declare const DEFAULT_PROXY_TRANSPORT_RETRY_METHODS: readonly ["GET", "HEAD", "OPTIONS"];
+export declare const DEFAULT_PROXY_TRANSPORT_RETRY_ERROR_CODES: readonly ["transport_network_error", "transport_timeout"];
+export declare const MAX_PROXY_TRANSPORT_RETRY_ATTEMPTS = 8;
+type RetryPolicyLabel = "HTTP" | "Stealth" | "Proxy transport";
+export declare function proxyTransportRetryErrorCode(error: unknown): string | undefined;
+export declare function proxyTransportRetryErrorStatus(error: unknown): number | undefined;
+export declare function createDefaultProxyTransportRetryOptions(options?: {
+    extraErrorCodes?: readonly string[];
+    label?: RetryPolicyLabel;
+}): NormalizedProxyTransportRetryOptions;
+export declare function normalizeProxyTransportRetryOptions(retry: RequestOptions["retry"], options?: {
+    extraErrorCodes?: readonly string[];
+    label?: RetryPolicyLabel;
+}): NormalizedProxyTransportRetryOptions | undefined;
+export declare function validateUnsafeProxyTransportRetryMethods(options: NormalizedProxyTransportRetryOptions, label?: RetryPolicyLabel): void;
+export declare function isProxyTransportRetryMethod(method: HttpMethod | string, options: NormalizedProxyTransportRetryOptions): boolean;
+export declare function shouldRetryProxyTransportError(error: unknown, options: NormalizedProxyTransportRetryOptions): boolean;
+export declare function shouldRetryProxyTransportAttempt(input: {
+    error: unknown;
+    explicitRetry: boolean;
+    method: HttpMethod | string;
+    options: NormalizedProxyTransportRetryOptions | undefined;
+    proxyUsed: boolean;
+}): boolean;
+export declare function computeProxyTransportRetryDelayMs(options: NormalizedProxyTransportRetryOptions, attemptIndex: number, headers?: Record<string, string>): number;
+export declare function normalizeProxyAttemptIndex(value: number | undefined): number;
+export declare function computeProxyAttemptIndex(options: {
+    baseProxyAttempt?: number;
+    proxyAttemptOffset?: number;
+    retryAttemptOffset?: number;
+}): number;
+export {};