@apifuse/provider-sdk 2.1.0-beta.6 → 2.1.0-beta.8

package/dist/runtime/proxy-errors.js

@@ -0,0 +1,83 @@
+import { TransportError } from "../errors";
+export const PROXY_AUTH_IP_DENIED_CODE = "PROXY_AUTH_IP_DENIED";
+export const PROXY_AUTH_IP_DENIED_MESSAGE = "Proxy source IP is not authorized. Add the runtime egress IP to the proxy provider allowlist.";
+export const PROXY_EDGE_AUTH_REJECTED_CODE = "PROXY_EDGE_AUTH_REJECTED";
+export const PROXY_EDGE_AUTH_REJECTED_MESSAGE = "Proxy provider rejected a candidate endpoint during authentication. The SDK will retry or refresh the proxy pool when safe.";
+export const PROXY_POOL_STALE_CODE = "PROXY_POOL_STALE";
+export const PROXY_EDGE_TLS_REJECTED_CODE = "PROXY_EDGE_TLS_REJECTED";
+export const PROXY_POOL_EXHAUSTED_CODE = "PROXY_POOL_EXHAUSTED";
+export const PROXY_POOL_EXHAUSTED_MESSAGE = "Proxy provider pool was exhausted. The SDK refreshed the proxy allocation, but all candidate endpoints failed.";
+const PROXY_POOL_STALE_STATUS_CODES = new Set([509, 512]);
+const PROXY_EDGE_TLS_REJECTED_STATUS_CODES = new Set([495]);
+const PROXY_AUTH_IP_DENIED_PATTERN = /\b(?:source|egress|client)\s+ip\b.{0,120}\b(?:deny|denied|unauthori[sz]ed|not\s+authori[sz]ed|white\s*list|allow\s*list)\b|\b(?:white\s*list|allow\s*list)\b.{0,120}\b(?:source|egress|client)\s+ip\b/i;
+const PROXY_EDGE_AUTH_REJECTED_PATTERN = /\bauth\s+ip\s+err\b|\bproxy\b.{0,120}\bauth(?:entication)?\b.{0,120}\b(?:reject(?:ed)?|fail(?:ed)?|invalid|den(?:y|ied)|unauthori[sz]ed)\b|\bauth(?:entication)?\b.{0,120}\b(?:reject(?:ed)?|fail(?:ed)?|invalid|den(?:y|ied)|unauthori[sz]ed)\b.{0,120}\bproxy\b/i;
+const PROXY_POOL_STALE_MESSAGE_PATTERN = /\bproxy\b.{0,120}\b(?:pool|lease|expired|unavailable|exhausted|non[\s-]?200\s+code:\s*(?:509|512))\b|\bnon[\s-]?200\s+code:\s*(?:509|512)\b.{0,120}\bproxy\b|\bsmartproxy\b.{0,120}\b(?:509|512)\b/i;
+const PROXY_EDGE_TLS_REJECTED_MESSAGE_PATTERN = /\b(?:smartproxy|proxy)\b.{0,160}\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\s-]?200)\b|\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\s-]?200)\b.{0,160}\b(?:smartproxy|proxy)\b/i;
+export function isProxyAuthIpDeniedMessage(message) {
+    return PROXY_AUTH_IP_DENIED_PATTERN.test(message);
+}
+export function createProxyAuthIpDeniedError(cause) {
+    return new TransportError(PROXY_AUTH_IP_DENIED_MESSAGE, {
+        code: PROXY_AUTH_IP_DENIED_CODE,
+        cause,
+    });
+}
+export function isProxyEdgeAuthRejectedMessage(message) {
+    return PROXY_EDGE_AUTH_REJECTED_PATTERN.test(message);
+}
+export function createProxyEdgeAuthRejectedError(cause) {
+    return new TransportError(PROXY_EDGE_AUTH_REJECTED_MESSAGE, {
+        code: PROXY_EDGE_AUTH_REJECTED_CODE,
+        cause,
+    });
+}
+export function isProxyPoolStaleStatus(status) {
+    return PROXY_POOL_STALE_STATUS_CODES.has(status);
+}
+export function isProxyEdgeTlsRejectedResponse(status, evidence) {
+    return (PROXY_EDGE_TLS_REJECTED_STATUS_CODES.has(status) &&
+        PROXY_EDGE_TLS_REJECTED_MESSAGE_PATTERN.test(evidence));
+}
+export function isProxyPoolStaleMessage(message) {
+    return PROXY_POOL_STALE_MESSAGE_PATTERN.test(message);
+}
+export function isProxyPoolRefreshableError(error) {
+    if (error instanceof TransportError &&
+        error.code === PROXY_AUTH_IP_DENIED_CODE) {
+        return false;
+    }
+    if (error instanceof TransportError &&
+        (error.code === PROXY_POOL_STALE_CODE ||
+            error.code === PROXY_EDGE_AUTH_REJECTED_CODE ||
+            error.code === PROXY_EDGE_TLS_REJECTED_CODE)) {
+        return true;
+    }
+    const cause = error instanceof Error ? error.cause : undefined;
+    const message = [
+        error instanceof Error ? error.message : String(error),
+        cause instanceof Error ? cause.message : "",
+    ].join(" ");
+    return (PROXY_POOL_STALE_MESSAGE_PATTERN.test(message) ||
+        PROXY_EDGE_AUTH_REJECTED_PATTERN.test(message));
+}
+export const isProxyPoolStaleError = isProxyPoolRefreshableError;
+export function createProxyPoolStaleError(status, cause) {
+    return new TransportError(`Proxy provider pool failed with status ${status}`, {
+        code: PROXY_POOL_STALE_CODE,
+        status,
+        cause,
+    });
+}
+export function createProxyEdgeTlsRejectedError(status, cause) {
+    return new TransportError(`Proxy edge TLS request was rejected with status ${status}`, {
+        code: PROXY_EDGE_TLS_REJECTED_CODE,
+        status,
+        cause,
+    });
+}
+export function createProxyPoolExhaustedError(cause) {
+    return new TransportError(PROXY_POOL_EXHAUSTED_MESSAGE, {
+        code: PROXY_POOL_EXHAUSTED_CODE,
+        cause,
+    });
+}

package/dist/runtime/proxy-telemetry.d.ts

@@ -0,0 +1,8 @@
+import type { ProxyAttemptTelemetryEvent, ProxyResolutionTelemetryEvent, ProxyTelemetrySink } from "../config/loader";
+export declare const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
+export declare class ProxyTelemetryCollector implements ProxyTelemetrySink {
+    #private;
+    recordProxyResolution(event: ProxyResolutionTelemetryEvent): void;
+    recordProxyAttempt(event: ProxyAttemptTelemetryEvent): void;
+    toHeaderValue(): string | undefined;
+}

package/dist/runtime/proxy-telemetry.js

@@ -0,0 +1,174 @@
+export const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
+const MAX_HEADER_BYTES = 4_096;
+const MAX_PROXY_ATTEMPT_SAMPLES = 24;
+const CACHE_STATUS_SEVERITY = {
+    disabled: 0,
+    memory_hit: 1,
+    redis_hit: 2,
+    soft_stale_refresh: 3,
+    redis_corrupt: 4,
+    redis_error: 5,
+    lock_wait: 6,
+    allocator: 7,
+};
+function sumOptional(left, right) {
+    const total = (left ?? 0) + (right ?? 0);
+    return total > 0 ? total : undefined;
+}
+function maxOptional(left, right) {
+    const values = [left, right].filter((value) => typeof value === "number");
+    return values.length > 0 ? Math.max(...values) : undefined;
+}
+function worseStatus(left, right) {
+    return CACHE_STATUS_SEVERITY[right] > CACHE_STATUS_SEVERITY[left]
+        ? right
+        : left;
+}
+function encodeBase64Url(value) {
+    return Buffer.from(value, "utf8").toString("base64url");
+}
+export class ProxyTelemetryCollector {
+    #events = [];
+    #attempts = [];
+    recordProxyResolution(event) {
+        this.#events.push({
+            provider: "smartproxy",
+            cacheStatus: event.cacheStatus,
+            cacheHit: event.cacheHit,
+            resolutionMs: Math.max(0, Math.floor(event.resolutionMs)),
+            allocatorMs: event.allocatorMs === undefined
+                ? undefined
+                : Math.max(0, Math.floor(event.allocatorMs)),
+            allocatorStatus: event.allocatorStatus === undefined
+                ? undefined
+                : Math.max(0, Math.floor(event.allocatorStatus)),
+            allocatorBodyClass: event.allocatorBodyClass,
+            allocatorAttempts: event.allocatorAttempts === undefined
+                ? undefined
+                : Math.max(1, Math.floor(event.allocatorAttempts)),
+            lockWaitMs: event.lockWaitMs === undefined
+                ? undefined
+                : Math.max(0, Math.floor(event.lockWaitMs)),
+            redisReadMs: event.redisReadMs === undefined
+                ? undefined
+                : Math.max(0, Math.floor(event.redisReadMs)),
+            redisWriteMs: event.redisWriteMs === undefined
+                ? undefined
+                : Math.max(0, Math.floor(event.redisWriteMs)),
+            poolAgeMs: event.poolAgeMs === undefined
+                ? undefined
+                : Math.max(0, Math.floor(event.poolAgeMs)),
+            poolExpiresInMs: event.poolExpiresInMs === undefined
+                ? undefined
+                : Math.max(0, Math.floor(event.poolExpiresInMs)),
+            attempts: Math.max(1, Math.floor(event.attempts || 1)),
+            refreshes: event.refreshes === undefined
+                ? undefined
+                : Math.max(0, Math.floor(event.refreshes)),
+        });
+    }
+    recordProxyAttempt(event) {
+        if (this.#attempts.length >= MAX_PROXY_ATTEMPT_SAMPLES)
+            return;
+        this.#attempts.push({
+            provider: "smartproxy",
+            attempt: Math.max(1, Math.floor(event.attempt || 1)),
+            ...(event.poolIndex === undefined
+                ? {}
+                : { poolIndex: Math.max(0, Math.floor(event.poolIndex)) }),
+            ...(event.proxyHash ? { proxyHash: event.proxyHash.slice(0, 16) } : {}),
+            outcome: event.outcome === "ok" ? "ok" : "error",
+            ...(event.errorCode ? { errorCode: event.errorCode.slice(0, 80) } : {}),
+            ...(event.status === undefined
+                ? {}
+                : { status: Math.max(0, Math.floor(event.status)) }),
+            ...(event.durationMs === undefined
+                ? {}
+                : { durationMs: Math.max(0, Math.floor(event.durationMs)) }),
+        });
+    }
+    toHeaderValue() {
+        const [first, ...rest] = this.#events;
+        if (!first)
+            return undefined;
+        const aggregate = rest.reduce((acc, event) => ({
+            provider: "smartproxy",
+            cacheStatus: worseStatus(acc.cacheStatus, event.cacheStatus),
+            cacheHit: acc.cacheHit && event.cacheHit,
+            resolutionMs: acc.resolutionMs + event.resolutionMs,
+            allocatorMs: sumOptional(acc.allocatorMs, event.allocatorMs),
+            allocatorStatus: event.allocatorStatus ?? acc.allocatorStatus,
+            allocatorBodyClass: event.allocatorBodyClass ?? acc.allocatorBodyClass,
+            allocatorAttempts: sumOptional(acc.allocatorAttempts, event.allocatorAttempts),
+            lockWaitMs: sumOptional(acc.lockWaitMs, event.lockWaitMs),
+            redisReadMs: sumOptional(acc.redisReadMs, event.redisReadMs),
+            redisWriteMs: sumOptional(acc.redisWriteMs, event.redisWriteMs),
+            poolAgeMs: maxOptional(acc.poolAgeMs, event.poolAgeMs),
+            poolExpiresInMs: maxOptional(acc.poolExpiresInMs, event.poolExpiresInMs),
+            attempts: acc.attempts + event.attempts,
+            refreshes: sumOptional(acc.refreshes, event.refreshes),
+        }), first);
+        const payload = {
+            v: 1,
+            proxy: {
+                provider: "smartproxy",
+                cacheStatus: aggregate.cacheStatus,
+                cacheHit: aggregate.cacheHit,
+                resolutionMs: aggregate.resolutionMs,
+                ...(aggregate.allocatorMs !== undefined
+                    ? { allocatorMs: aggregate.allocatorMs }
+                    : {}),
+                ...(aggregate.allocatorStatus !== undefined
+                    ? { allocatorStatus: aggregate.allocatorStatus }
+                    : {}),
+                ...(aggregate.allocatorBodyClass !== undefined
+                    ? { allocatorBodyClass: aggregate.allocatorBodyClass }
+                    : {}),
+                ...(aggregate.allocatorAttempts !== undefined
+                    ? { allocatorAttempts: aggregate.allocatorAttempts }
+                    : {}),
+                ...(aggregate.lockWaitMs !== undefined
+                    ? { lockWaitMs: aggregate.lockWaitMs }
+                    : {}),
+                ...(aggregate.redisReadMs !== undefined
+                    ? { redisReadMs: aggregate.redisReadMs }
+                    : {}),
+                ...(aggregate.redisWriteMs !== undefined
+                    ? { redisWriteMs: aggregate.redisWriteMs }
+                    : {}),
+                ...(aggregate.poolAgeMs !== undefined
+                    ? { poolAgeMs: aggregate.poolAgeMs }
+                    : {}),
+                ...(aggregate.poolExpiresInMs !== undefined
+                    ? { poolExpiresInMs: aggregate.poolExpiresInMs }
+                    : {}),
+                attempts: aggregate.attempts,
+                ...(aggregate.refreshes !== undefined
+                    ? { refreshes: aggregate.refreshes }
+                    : {}),
+                ...(this.#attempts.length > 0
+                    ? {
+                        attemptSamples: this.#attempts.map((attempt, index) => ({
+                            n: index + 1,
+                            a: attempt.attempt,
+                            ...(attempt.poolIndex === undefined
+                                ? {}
+                                : { i: attempt.poolIndex }),
+                            ...(attempt.proxyHash ? { h: attempt.proxyHash } : {}),
+                            o: attempt.outcome,
+                            ...(attempt.errorCode ? { c: attempt.errorCode } : {}),
+                            ...(attempt.status === undefined ? {} : { s: attempt.status }),
+                            ...(attempt.durationMs === undefined
+                                ? {}
+                                : { d: attempt.durationMs }),
+                        })),
+                    }
+                    : {}),
+            },
+        };
+        const encoded = encodeBase64Url(JSON.stringify(payload));
+        if (encoded.length > MAX_HEADER_BYTES)
+            return undefined;
+        return encoded;
+    }
+}

package/dist/runtime/redis.d.ts

@@ -0,0 +1,17 @@
+import Redis from "ioredis";
+export type ProviderRedisClient = Redis;
+export type ProviderRedisClientOptions = {
+    readonly redisUrl: string;
+    readonly timeoutMs: number;
+    readonly onError: () => void;
+};
+type RedisTimeoutOptions<T> = {
+    readonly timeoutMs: number;
+    readonly onTimeout: () => T;
+    readonly onError?: (error: unknown) => T;
+};
+export declare function createProviderRedisClient(options: ProviderRedisClientOptions): ProviderRedisClient;
+export declare function withRedisTimeout<T>(operation: () => Promise<T>, options: RedisTimeoutOptions<T>): Promise<T>;
+export declare function redisStatus(redis: ProviderRedisClient): string;
+export declare function ensureRedisReady(redis: ProviderRedisClient, timeoutMs: number): Promise<boolean>;
+export {};

package/dist/runtime/redis.js

@@ -0,0 +1,82 @@
+import Redis from "ioredis";
+export function createProviderRedisClient(options) {
+    const redis = new Redis(options.redisUrl, {
+        connectTimeout: options.timeoutMs,
+        enableOfflineQueue: false,
+        lazyConnect: true,
+        maxRetriesPerRequest: 0,
+        retryStrategy: () => null,
+    });
+    redis.on("error", options.onError);
+    return redis;
+}
+export async function withRedisTimeout(operation, options) {
+    let timeoutId;
+    try {
+        const timeout = new Promise((resolve, reject) => {
+            timeoutId = setTimeout(() => {
+                try {
+                    resolve(options.onTimeout());
+                }
+                catch (error) {
+                    reject(error);
+                }
+            }, options.timeoutMs);
+        });
+        const operationResult = options.onError
+            ? operation().catch(options.onError)
+            : operation();
+        return await Promise.race([operationResult, timeout]);
+    }
+    finally {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+    }
+}
+export function redisStatus(redis) {
+    return redis.status;
+}
+async function waitForRedisReady(redis, timeoutMs) {
+    let timeoutId;
+    let settled = false;
+    return await new Promise((resolve) => {
+        const cleanup = () => {
+            if (timeoutId)
+                clearTimeout(timeoutId);
+            redis.off("ready", onReady);
+            redis.off("close", onUnavailable);
+            redis.off("end", onUnavailable);
+            redis.off("error", onUnavailable);
+        };
+        const finish = (ready) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(ready);
+        };
+        const onReady = () => finish(true);
+        const onUnavailable = () => finish(false);
+        timeoutId = setTimeout(() => finish(redisStatus(redis) === "ready"), timeoutMs);
+        redis.once("ready", onReady);
+        redis.once("close", onUnavailable);
+        redis.once("end", onUnavailable);
+        redis.once("error", onUnavailable);
+    });
+}
+export async function ensureRedisReady(redis, timeoutMs) {
+    if (redisStatus(redis) === "ready")
+        return true;
+    if (redisStatus(redis) === "wait" || redisStatus(redis) === "end") {
+        const connected = await withRedisTimeout(async () => {
+            await redis.connect();
+            return true;
+        }, {
+            timeoutMs,
+            onTimeout: () => false,
+            onError: () => false,
+        });
+        return connected && redisStatus(redis) === "ready";
+    }
+    return await waitForRedisReady(redis, timeoutMs);
+}

package/dist/runtime/request-options.d.ts

@@ -0,0 +1,3 @@
+import type { RequestParams } from "../types";
+export declare function appendQueryParams(url: string, params?: RequestParams): string;
+export declare function normalizeHttpRequestBody(body: unknown): string | Buffer | undefined;

package/dist/runtime/request-options.js

@@ -0,0 +1,42 @@
+function isParamArray(value) {
+    return Array.isArray(value);
+}
+function appendQueryValue(searchParams, key, value) {
+    if (value === null || value === undefined) {
+        return;
+    }
+    searchParams.append(key, String(value));
+}
+export function appendQueryParams(url, params) {
+    if (!params || Object.keys(params).length === 0) {
+        return url;
+    }
+    const parsed = new URL(url);
+    for (const [key, value] of Object.entries(params)) {
+        if (isParamArray(value)) {
+            for (const item of value)
+                appendQueryValue(parsed.searchParams, key, item);
+            continue;
+        }
+        appendQueryValue(parsed.searchParams, key, value);
+    }
+    return parsed.toString();
+}
+export function normalizeHttpRequestBody(body) {
+    if (body === undefined) {
+        return undefined;
+    }
+    if (typeof body === "string" || Buffer.isBuffer(body)) {
+        return body;
+    }
+    if (body instanceof URLSearchParams) {
+        return body.toString();
+    }
+    if (body instanceof ArrayBuffer) {
+        return Buffer.from(body);
+    }
+    if (ArrayBuffer.isView(body)) {
+        return Buffer.from(body.buffer, body.byteOffset, body.byteLength);
+    }
+    return JSON.stringify(body);
+}

package/dist/runtime/state.d.ts

@@ -0,0 +1,17 @@
+import { ProviderError } from "../errors";
+import type { ProviderRuntimeState } from "../types";
+type RedisProviderRuntimeStateOptions = {
+    readonly redisUrl: string;
+    readonly providerId?: string;
+};
+export declare class UnsupportedProviderStateError extends ProviderError {
+    constructor(message?: string);
+}
+export declare function createRedisProviderRuntimeState(options: RedisProviderRuntimeStateOptions): ProviderRuntimeState;
+export declare function createProviderRuntimeStateFromEnv(options?: {
+    readonly providerId?: string;
+    readonly allowMemoryFallback?: boolean;
+}): ProviderRuntimeState;
+export declare function createMemoryProviderRuntimeState(): ProviderRuntimeState;
+export declare function createUnsupportedProviderRuntimeState(): ProviderRuntimeState;
+export {};