@apifuse/provider-sdk 2.2.0-beta.4 → 2.2.0-beta.40

package/dist/runtime/proxy-nodemaven.js

@@ -0,0 +1,146 @@
+import { createHash, randomBytes } from "node:crypto";
+export const NODEMAVEN_USERNAME_ENV = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
+export const NODEMAVEN_PASSWORD_ENV = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
+export const NODEMAVEN_FILTER_ENV = "APIFUSE__PROXY__NODEMAVEN_FILTER";
+export const NODEMAVEN_GATEWAY_HOST = "gate.nodemaven.com";
+/**
+ * NodeMaven's fastest protocol: HTTP CONNECT. Benchmarks (KR, cold + warm)
+ * showed socks5 through the gateway adds ~500ms per request over http, so
+ * NodeMaven never defaults to socks5.
+ */
+export const NODEMAVEN_DEFAULT_PROTOCOL = "http";
+/** NodeMaven gateway port ranges per protocol (docs: HTTP 8080-9080, SOCKS5 1080-2080). */
+const NODEMAVEN_PORTS = {
+    http: { min: 8080, max: 9080 },
+    socks5: { min: 1080, max: 2080 },
+};
+const NODEMAVEN_FILTERS = new Set(["medium", "high"]);
+const DEFAULT_NODEMAVEN_FILTER = "medium";
+const DEFAULT_NODEMAVEN_POOL_SIZE = 20;
+export const NODEMAVEN_MAX_POOL_SIZE = 50;
+/** NodeMaven sticky sessions persist up to 24h server-side, keyed by the sid. */
+const NODEMAVEN_MAX_LIFETIME_MINUTES = 1440;
+const SID_LENGTH = 10;
+export function hasNodemavenCredentials() {
+    return Boolean(readNodemavenUsername() && readNodemavenPassword());
+}
+function readNodemavenUsername() {
+    return process.env[NODEMAVEN_USERNAME_ENV]?.trim() || undefined;
+}
+function readNodemavenPassword() {
+    return process.env[NODEMAVEN_PASSWORD_ENV]?.trim() || undefined;
+}
+function resolveNodemavenFilter(value) {
+    const raw = value?.trim().toLowerCase();
+    if (!raw)
+        return DEFAULT_NODEMAVEN_FILTER;
+    if (!NODEMAVEN_FILTERS.has(raw)) {
+        throw new Error(`${NODEMAVEN_FILTER_ENV} must be "medium" or "high"`);
+    }
+    return raw;
+}
+export function nodemavenPoolSize(policy) {
+    return Math.min(NODEMAVEN_MAX_POOL_SIZE, Math.max(1, Math.floor(policy.session?.poolSize ?? DEFAULT_NODEMAVEN_POOL_SIZE)));
+}
+export function nodemavenLifetimeMinutes(policy) {
+    const configured = policy.session?.lifetimeMinutes;
+    if (typeof configured !== "number" || !Number.isFinite(configured) || configured <= 0) {
+        return NODEMAVEN_MAX_LIFETIME_MINUTES;
+    }
+    return Math.min(NODEMAVEN_MAX_LIFETIME_MINUTES, Math.max(1, Math.floor(configured)));
+}
+/** Stable wall-clock window shared by every process deriving the same sticky sid. */
+export function nodemavenSessionWindow(policy, now = Date.now()) {
+    const lifetimeMs = nodemavenLifetimeMinutes(policy) * 60_000;
+    const refreshEpoch = Math.floor(now / lifetimeMs);
+    return {
+        refreshEpoch,
+        expiresAt: new Date((refreshEpoch + 1) * lifetimeMs).toISOString(),
+    };
+}
+/** NodeMaven username tokens accept `[a-z0-9]`; slugify geo values to that set. */
+function slugifyGeo(value) {
+    if (!value)
+        return undefined;
+    const slug = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "");
+    return slug || undefined;
+}
+function isStickyAffinity(policy) {
+    return (policy.session?.affinity ?? "request") !== "request";
+}
+/**
+ * A sticky sid is deterministic from the affinity key so every process serving
+ * the same connection derives the same egress IP without shared storage. A
+ * rotating sid is random per call (a fresh egress IP per request).
+ */
+function deriveSid(policy, affinityKey, poolIndex, refreshEpoch) {
+    if (!isStickyAffinity(policy) || !affinityKey) {
+        return randomBytes(SID_LENGTH).toString("hex").slice(0, SID_LENGTH);
+    }
+    const digest = createHash("sha256")
+        .update(`${affinityKey}:${refreshEpoch}:${poolIndex}`)
+        .digest("hex");
+    // hex digits are a subset of the allowed [a-z0-9] sid charset.
+    return digest.slice(0, SID_LENGTH);
+}
+function selectPort(protocol, sid, poolIndex) {
+    const { min, max } = NODEMAVEN_PORTS[protocol];
+    const span = max - min + 1;
+    const hashInt = Number.parseInt(createHash("sha256").update(`${sid}:${poolIndex}`).digest("hex").slice(0, 8), 16);
+    return min + (hashInt % span);
+}
+/**
+ * Synthesize a NodeMaven gateway proxy URL locally from static credentials.
+ * There is no allocation API — geo/session are encoded in the username.
+ */
+export function synthesizeNodemavenProxy(input) {
+    const username = input.credentials.username.trim();
+    const password = input.credentials.password.trim();
+    if (!username || !password) {
+        throw new Error(`NodeMaven credentials missing: set ${NODEMAVEN_USERNAME_ENV} and ${NODEMAVEN_PASSWORD_ENV}.`);
+    }
+    const filter = resolveNodemavenFilter(input.credentials.filter);
+    const sid = deriveSid(input.policy, input.affinityKey, input.poolIndex, input.refreshEpoch);
+    const port = selectPort(input.protocol, sid, input.poolIndex);
+    const lifetimeMinutes = nodemavenLifetimeMinutes(input.policy);
+    const sticky = isStickyAffinity(input.policy);
+    const country = slugifyGeo(input.country ?? input.policy.geo?.country);
+    const region = slugifyGeo(input.policy.geo?.subdivision);
+    const city = slugifyGeo(input.policy.geo?.city);
+    const tokens = [username];
+    if (country)
+        tokens.push("country", country);
+    if (region)
+        tokens.push("region", region);
+    if (city)
+        tokens.push("city", city);
+    tokens.push("sid", sid);
+    tokens.push("filter", filter);
+    tokens.push("ipv4", "true");
+    const proxyUsername = tokens.join("-");
+    // Username tokens are [a-z0-9-] only, which survive URL encoding unchanged.
+    const url = `${input.protocol}://${proxyUsername}:${encodeURIComponent(password)}@${NODEMAVEN_GATEWAY_HOST}:${port}`;
+    return {
+        url,
+        protocol: input.protocol,
+        sticky,
+        sessionId: sid,
+        ...(sticky
+            ? {
+                expiresAt: input.expiresAt ??
+                    new Date((input.now ?? Date.now()) + lifetimeMinutes * 60_000).toISOString(),
+            }
+            : {}),
+        diagnostics: {
+            vendor: "nodemaven",
+            protocol: input.protocol,
+            sticky,
+            filter,
+            lifetimeMinutes,
+            ...(country ? { country } : {}),
+        },
+    };
+}

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

@@ -1,8 +1,87 @@
-import type { ProxyAttemptTelemetryEvent, ProxyResolutionTelemetryEvent, ProxyTelemetrySink } from "../config/loader.js";
+import type { ProxyAttemptTelemetryEvent, ProxyCacheStatus, ProxyProtocol, ProxyResolutionTelemetryEvent, ProxyTelemetrySink, ProxyUserAgentSource, ProxyVendorFailoverTelemetryEvent, ProxyVendorName, SmartproxyAllocatorBodyClass } from "../config/loader.js";
 export declare const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
+export type ProxyTelemetryResolvedPayload = {
+    kind: "resolved";
+    provider: ProxyVendorName;
+    userAgentSource?: ProxyUserAgentSource;
+    protocol?: ProxyProtocol;
+    cacheStatus: ProxyCacheStatus;
+    cacheHit: boolean;
+    resolutionMs: number;
+    allocatorMs?: number;
+    allocatorStatus?: number;
+    allocatorBodyClass?: SmartproxyAllocatorBodyClass;
+    allocatorAttempts?: number;
+    lockWaitMs?: number;
+    redisReadMs?: number;
+    redisWriteMs?: number;
+    poolAgeMs?: number;
+    poolExpiresInMs?: number;
+    attempts: number;
+    refreshes?: number;
+    attemptSamples?: {
+        n: number;
+        a: number;
+        i?: number;
+        h?: string;
+        o: ProxyAttemptTelemetryEvent["outcome"];
+        c?: string;
+        s?: number;
+        d?: number;
+    }[];
+    /** Distinct vendors attempted across the resolution chain, in order seen. */
+    vendors?: ProxyVendorName[];
+    /** Cross-vendor failover events (bounded). */
+    failovers?: {
+        v: ProxyVendorName;
+        nx?: ProxyVendorName;
+        p: ProxyVendorFailoverTelemetryEvent["phase"];
+        r: ProxyVendorFailoverTelemetryEvent["reason"];
+        a?: number;
+    }[];
+};
+export type ProxyTelemetryUnresolvedPayload = {
+    kind: "unresolved";
+    /** Distinct vendors that failed resolution or recorded a failover, in order seen. */
+    vendors: ProxyVendorName[];
+    cacheStatus?: ProxyCacheStatus;
+    cacheHit?: boolean;
+    resolutionMs?: number;
+    allocatorMs?: number;
+    allocatorStatus?: number;
+    allocatorBodyClass?: SmartproxyAllocatorBodyClass;
+    allocatorAttempts?: number;
+    lockWaitMs?: number;
+    redisReadMs?: number;
+    redisWriteMs?: number;
+    poolAgeMs?: number;
+    poolExpiresInMs?: number;
+    attempts?: number;
+    refreshes?: number;
+    failovers?: {
+        v: ProxyVendorName;
+        nx?: ProxyVendorName;
+        p: ProxyVendorFailoverTelemetryEvent["phase"];
+        r: ProxyVendorFailoverTelemetryEvent["reason"];
+        a?: number;
+    }[];
+    attemptSamples?: {
+        n: number;
+        a: number;
+        i?: number;
+        h?: string;
+        o: ProxyAttemptTelemetryEvent["outcome"];
+        c?: string;
+        s?: number;
+        d?: number;
+    }[];
+};
+export type ProxyTelemetryLogPayload = ProxyTelemetryResolvedPayload | ProxyTelemetryUnresolvedPayload;
 export declare class ProxyTelemetryCollector implements ProxyTelemetrySink {
     #private;
     recordProxyResolution(event: ProxyResolutionTelemetryEvent): void;
+    recordProxyVendorFailover(event: ProxyVendorFailoverTelemetryEvent): void;
     recordProxyAttempt(event: ProxyAttemptTelemetryEvent): void;
+    toLogPayload(): ProxyTelemetryLogPayload | undefined;
     toHeaderValue(): string | undefined;
 }

package/dist/runtime/proxy-telemetry.js

@@ -1,6 +1,7 @@
 export const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
 const MAX_HEADER_BYTES = 4_096;
 const MAX_PROXY_ATTEMPT_SAMPLES = 24;
+const MAX_PROXY_FAILOVER_SAMPLES = 12;
 const CACHE_STATUS_SEVERITY = {
     disabled: 0,
     memory_hit: 1,
@@ -28,9 +29,15 @@ function encodeBase64Url(value) {
 export class ProxyTelemetryCollector {
     #events = [];
     #attempts = [];
+    #failovers = [];
+    #unresolvedVendors = [];
     recordProxyResolution(event) {
+        const outcome = event.outcome === "error" ? "error" : "ok";
         this.#events.push({
-            provider: "smartproxy",
+            provider: event.provider,
+            outcome,
+            ...(event.userAgentSource ? { userAgentSource: event.userAgentSource } : {}),
+            ...(event.protocol ? { protocol: event.protocol } : {}),
             cacheStatus: event.cacheStatus,
             cacheHit: event.cacheHit,
             resolutionMs: Math.max(0, Math.floor(event.resolutionMs)),
@@ -52,12 +59,29 @@ export class ProxyTelemetryCollector {
             attempts: Math.max(1, Math.floor(event.attempts || 1)),
             refreshes: event.refreshes === undefined ? undefined : Math.max(0, Math.floor(event.refreshes)),
         });
+        if (outcome === "error" && !this.#unresolvedVendors.includes(event.provider)) {
+            this.#unresolvedVendors.push(event.provider);
+        }
+    }
+    recordProxyVendorFailover(event) {
+        if (this.#failovers.length >= MAX_PROXY_FAILOVER_SAMPLES)
+            return;
+        this.#failovers.push({
+            vendor: event.vendor,
+            ...(event.nextVendor ? { nextVendor: event.nextVendor } : {}),
+            phase: event.phase,
+            reason: event.reason,
+            ...(event.attempt === undefined ? {} : { attempt: Math.max(0, Math.floor(event.attempt)) }),
+        });
+        if (!this.#unresolvedVendors.includes(event.vendor)) {
+            this.#unresolvedVendors.push(event.vendor);
+        }
     }
     recordProxyAttempt(event) {
         if (this.#attempts.length >= MAX_PROXY_ATTEMPT_SAMPLES)
             return;
         this.#attempts.push({
-            provider: "smartproxy",
+            provider: event.provider,
             attempt: Math.max(1, Math.floor(event.attempt || 1)),
             ...(event.poolIndex === undefined
                 ? {}
@@ -71,12 +95,100 @@ export class ProxyTelemetryCollector {
                 : { durationMs: Math.max(0, Math.floor(event.durationMs)) }),
         });
     }
-    toHeaderValue() {
+    toLogPayload() {
         const [first, ...rest] = this.#events;
-        if (!first)
-            return undefined;
+        const okEvents = this.#events.filter((event) => event.outcome !== "error");
+        const 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 failovers = this.#failovers.map((failover) => ({
+            v: failover.vendor,
+            ...(failover.nextVendor ? { nx: failover.nextVendor } : {}),
+            p: failover.phase,
+            r: failover.reason,
+            ...(failover.attempt === undefined ? {} : { a: failover.attempt }),
+        }));
+        if (okEvents.length === 0) {
+            if (!first && failovers.length === 0)
+                return undefined;
+            const failureEvents = this.#events.filter((event) => event.outcome === "error");
+            const [firstFailure, ...remainingFailures] = failureEvents;
+            const aggregate = firstFailure
+                ? remainingFailures.reduce((acc, event) => ({
+                    provider: event.provider,
+                    outcome: "error",
+                    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),
+                }), firstFailure)
+                : undefined;
+            return {
+                kind: "unresolved",
+                vendors: [...this.#unresolvedVendors],
+                ...(aggregate
+                    ? {
+                        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 } : {}),
+                    }
+                    : {}),
+                ...(failovers.length > 0 ? { failovers } : {}),
+                ...(attemptSamples.length > 0 ? { attemptSamples } : {}),
+            };
+        }
+        // The serving vendor/protocol is the last successful resolution.
+        const serving = okEvents[okEvents.length - 1] ?? first;
+        const vendors = [];
+        for (const event of this.#events) {
+            if (!vendors.includes(event.provider))
+                vendors.push(event.provider);
+        }
         const aggregate = rest.reduce((acc, event) => ({
-            provider: "smartproxy",
+            provider: event.provider,
+            userAgentSource: event.userAgentSource ?? acc.userAgentSource,
             cacheStatus: worseStatus(acc.cacheStatus, event.cacheStatus),
             cacheHit: acc.cacheHit && event.cacheHit,
             resolutionMs: acc.resolutionMs + event.resolutionMs,
@@ -92,48 +204,43 @@ export class ProxyTelemetryCollector {
             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 }),
-                        })),
-                    }
-                    : {}),
-            },
+        return {
+            kind: "resolved",
+            provider: serving.provider,
+            ...(aggregate.userAgentSource ? { userAgentSource: aggregate.userAgentSource } : {}),
+            ...(serving.protocol ? { protocol: serving.protocol } : {}),
+            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 } : {}),
+            ...(attemptSamples.length > 0 ? { attemptSamples } : {}),
+            ...(vendors.length > 1 ? { vendors } : {}),
+            ...(failovers.length > 0 ? { failovers } : {}),
         };
+    }
+    toHeaderValue() {
+        const proxy = this.toLogPayload();
+        if (!proxy)
+            return undefined;
+        const payload = { v: 1, proxy };
         const encoded = encodeBase64Url(JSON.stringify(payload));
         if (encoded.length > MAX_HEADER_BYTES)
             return undefined;

package/dist/runtime/redirects.d.ts

@@ -0,0 +1,29 @@
+import type { HttpRedirectFailureReason } from "../types.js";
+export type RedirectHopDecision<TMethod extends string> = {
+    kind: "follow";
+    nextMethod: TMethod | "GET";
+    nextUrl: string;
+} | {
+    kind: "stop";
+    reason: HttpRedirectFailureReason;
+    nextUrl?: string;
+};
+export declare function isRedirectStatus(status: number): boolean;
+/** Shared fetch-compatible redirect method rewriting for stealth and ctx.http. */
+export declare function nextRedirectMethod<TMethod extends string>(status: number, method: TMethod): TMethod | "GET";
+/** Resolves a Location value against the response URL without issuing a request. */
+export declare function resolveRedirectUrl(location: string | undefined, responseUrl: string): string | undefined;
+/**
+ * Shared post-response decision ordering for both redirect walkers. The
+ * caller-owned stop hook is checked first, matching stealth's pre-follow
+ * contract, then structural termination and loop checks run before follow.
+ */
+export declare function evaluateRedirectHop<TMethod extends string>(input: {
+    status: number;
+    method: TMethod;
+    nextUrl: string | undefined;
+    shouldStop: boolean;
+    redirectCount: number;
+    maxHops: number;
+    visitedRequests: ReadonlySet<string>;
+}): RedirectHopDecision<TMethod>;

package/dist/runtime/redirects.js

@@ -0,0 +1,36 @@
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+export function isRedirectStatus(status) {
+    return REDIRECT_STATUSES.has(status);
+}
+/** Shared fetch-compatible redirect method rewriting for stealth and ctx.http. */
+export function nextRedirectMethod(status, method) {
+    if (status === 303 && method !== "HEAD")
+        return "GET";
+    if ((status === 301 || status === 302) && method === "POST")
+        return "GET";
+    return method;
+}
+/** Resolves a Location value against the response URL without issuing a request. */
+export function resolveRedirectUrl(location, responseUrl) {
+    return location ? new URL(location, responseUrl).toString() : undefined;
+}
+/**
+ * Shared post-response decision ordering for both redirect walkers. The
+ * caller-owned stop hook is checked first, matching stealth's pre-follow
+ * contract, then structural termination and loop checks run before follow.
+ */
+export function evaluateRedirectHop(input) {
+    if (input.shouldStop) {
+        return { kind: "stop", reason: "stopped", ...(input.nextUrl ? { nextUrl: input.nextUrl } : {}) };
+    }
+    if (!input.nextUrl)
+        return { kind: "stop", reason: "missing_location" };
+    if (input.redirectCount > input.maxHops) {
+        return { kind: "stop", reason: "max_hops", nextUrl: input.nextUrl };
+    }
+    const nextMethod = nextRedirectMethod(input.status, input.method);
+    if (input.visitedRequests.has(`${nextMethod} ${input.nextUrl}`)) {
+        return { kind: "stop", reason: "loop", nextUrl: input.nextUrl };
+    }
+    return { kind: "follow", nextMethod, nextUrl: input.nextUrl };
+}

package/dist/runtime/redis.d.ts

@@ -1,4 +1,4 @@
-import { Redis } from "ioredis";
+import type { Redis } from "ioredis";
 export type ProviderRedisClient = Redis;
 export type ProviderRedisClientOptions = {
     readonly redisUrl: string;

package/dist/runtime/redis.js

@@ -1,6 +1,8 @@
-import { Redis } from "ioredis";
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
 export function createProviderRedisClient(options) {
-    const redis = new Redis(options.redisUrl, {
+    const { Redis: RedisClient } = require("ioredis");
+    const redis = new RedisClient(options.redisUrl, {
         connectTimeout: options.timeoutMs,
         enableOfflineQueue: false,
         lazyConnect: true,

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

@@ -1,3 +1,70 @@
-import type { RequestParams } from "../types.js";
+import type { HttpClient, RequestOptions, RequestParams } from "../types.js";
+export declare const REDACTED_QUERY_VALUE = "[REDACTED]";
+/** Internal heuristic shared by diagnostic and fixture structural redaction. */
+export declare function isSensitiveKey(key: string): boolean;
+declare const HTTP_REQUEST_METHOD_CONFIG: {
+    readonly request: {
+        readonly optionsIndex: 1;
+    };
+    readonly get: {
+        readonly optionsIndex: 1;
+    };
+    readonly post: {
+        readonly optionsIndex: 2;
+    };
+    readonly put: {
+        readonly optionsIndex: 2;
+    };
+    readonly delete: {
+        readonly optionsIndex: 1;
+    };
+    readonly stream: {
+        readonly optionsIndex: 1;
+    };
+    readonly sse: {
+        readonly optionsIndex: 1;
+    };
+};
+export type HttpRequestMethod = keyof typeof HTTP_REQUEST_METHOD_CONFIG;
+export type HttpRequestInvocation = {
+    [M in HttpRequestMethod]: {
+        method: M;
+        args: Parameters<HttpClient[M]>;
+    };
+}[HttpRequestMethod];
+export declare const HTTP_REQUEST_METHOD_NAMES: HttpRequestMethod[];
+export declare function isHttpRequestMethod(method: PropertyKey): method is HttpRequestMethod;
+export type SerializedRequestUrl = {
+    requestUrl: string;
+    redactedUrl: string;
+    sensitiveValues: readonly string[];
+};
+export declare function normalizeSensitiveParams(sensitiveParams?: Record<string, string>): Record<string, string> | undefined;
 export declare function appendQueryParams(url: string, params?: RequestParams): string;
+/** Redacts matching query keys without reserializing any other URL bytes. */
+export declare function redactUrlQueryParams(url: string, sensitiveParamNames: readonly string[]): {
+    redactedUrl: string;
+    sensitiveValues: readonly string[];
+};
+/**
+ * Serializes public and secret query parameters together while constructing a
+ * separate, structurally redacted URL for diagnostics and observability.
+ */
+export declare function serializeRequestUrl(url: string, params?: RequestParams, sensitiveParams?: Record<string, string>): SerializedRequestUrl;
+/** Scrubs raw and URL-encoded secret values from diagnostic text. */
+export declare function redactSensitiveText(text: string, sensitiveValues: readonly string[], requestUrl?: string, redactedUrl?: string): string;
+/**
+ * Redacts error text and recursively serializable diagnostic metadata.
+ * Mutable errors retain identity; readonly/frozen errors may be replaced, so
+ * callers must use the returned value.
+ */
+export declare function redactSensitiveError<T>(error: T, sensitiveValues: readonly string[], requestUrl?: string, redactedUrl?: string): T;
+/** Redacts failures that occur before a request URL can be fully serialized. */
+export declare function redactSensitiveRequestError<T>(error: T, url: string, sensitiveParams?: Record<string, string>): T;
+/** Validates an untyped proxy invocation before narrowing it to the HttpClient contract. */
+export declare function parseHttpRequestInvocation(method: PropertyKey, args: unknown[]): HttpRequestInvocation | undefined;
+/** Internal typed registry for the request-options position of HttpClient calls. */
+export declare function requestOptionsFromHttpInvocation(invocation: HttpRequestInvocation): RequestOptions | undefined;
+export declare function replaceRequestOptionsInHttpInvocation(invocation: HttpRequestInvocation, options: RequestOptions): void;
 export declare function normalizeHttpRequestBody(body: unknown): string | Buffer | undefined;
+export {};