@apifuse/provider-sdk 2.2.0-beta.22 → 2.2.0-beta.24

package/dist/runtime/resolver.js

@@ -0,0 +1,414 @@
+import { createHash } from "node:crypto";
+import { ProviderError } from "../errors.js";
+import { resolverChallengeIsIdentityScoped, resolverChallengeIssuingIdentity, } from "./resolver-vendors/bindings.js";
+import { createBrowserResolverVendorAdapter } from "./resolver-vendors/browser.js";
+import { RESOLVER_VENDOR_CAPABILITIES, ResolverVendorUnavailableError, resolverVendorSupports, } from "./resolver-vendors/types.js";
+export const APIFUSE__RESOLVER__2CAPTCHA__API_KEY = "APIFUSE__RESOLVER__2CAPTCHA__API_KEY";
+export const APIFUSE__RESOLVER__CAPSOLVER__API_KEY = "APIFUSE__RESOLVER__CAPSOLVER__API_KEY";
+export const APIFUSE__RESOLVER__CAPMONSTER__API_KEY = "APIFUSE__RESOLVER__CAPMONSTER__API_KEY";
+export const APIFUSE__RESOLVER__TIMEOUT_MS = "APIFUSE__RESOLVER__TIMEOUT_MS";
+export const APIFUSE__CDP_POOL__URL = "APIFUSE__CDP_POOL__URL";
+export const DEFAULT_RESOLVER_TIMEOUT_MS = 180_000;
+const RESOLVER_SOLUTION_CACHE_NAMESPACE = "resolver-solution";
+const RESOLVER_SOLUTION_INDEX_CACHE_NAMESPACE = "resolver-solution-index";
+const MIN_RESOLVER_CACHE_TTL_MS = 1_000;
+const resolverCaches = new WeakMap();
+const solutionIssuerDigests = new WeakMap();
+export const RESOLVER_INSTRUMENTATION_METADATA = Symbol.for("@apifuse/provider-sdk/runtime/resolver-instrumentation-metadata");
+export const RESOLVER_ADAPTER_REGISTRY = {
+    browser(configuration, timeoutMs, allowedHosts) {
+        return createBrowserResolverVendorAdapter({
+            allowedHosts,
+            cdpUrl: configuration,
+            timeoutMs,
+        });
+    },
+};
+// This is the sole allowlist for declared vendors whose registry entry may be absent.
+// Remove a vendor here when its adapter is registered.
+const KNOWN_UNIMPLEMENTED_RESOLVER_VENDORS = new Set([
+    "2captcha",
+    "capsolver",
+    "capmonster",
+    "custom",
+]);
+function normalizedEnvValue(env, key) {
+    const value = env[key]?.trim();
+    return value ? value : undefined;
+}
+function readPositiveIntegerEnv(env, name) {
+    const raw = env[name]?.trim();
+    if (!raw)
+        return undefined;
+    if (!/^[1-9]\d*$/.test(raw)) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+    return raw;
+}
+function assertDeclaredKind(requestedKind, declaredKinds) {
+    if (declaredKinds.includes(requestedKind))
+        return;
+    const declared = declaredKinds.length > 0 ? declaredKinds.join(", ") : "none";
+    throw new ProviderError(`Resolver kind "${requestedKind}" is not declared; declared kinds: ${declared}`, {
+        code: "RESOLVER_KIND_NOT_DECLARED",
+        fix: `Add "${requestedKind}" to the provider's resolver.kinds declaration.`,
+    });
+}
+function createUnavailableAdapter(vendor, reason) {
+    return {
+        id: vendor,
+        supports(kind) {
+            return resolverVendorSupports(vendor, kind);
+        },
+        async solve() {
+            throw new ResolverVendorUnavailableError(vendor, reason);
+        },
+    };
+}
+function createAdapter(vendor, timeoutMs, allowedHosts) {
+    const factory = RESOLVER_ADAPTER_REGISTRY[vendor.vendor];
+    if (!factory && !KNOWN_UNIMPLEMENTED_RESOLVER_VENDORS.has(vendor.vendor)) {
+        throw new Error(`Resolver adapter factory is missing for implemented vendor "${vendor.vendor}"`);
+    }
+    if (!vendor.available) {
+        return createUnavailableAdapter(vendor.vendor, vendor.reason);
+    }
+    if (factory) {
+        return factory(vendor.configuration, timeoutMs, allowedHosts);
+    }
+    return createUnavailableAdapter(vendor.vendor, "not_implemented");
+}
+function assertKnownResolverVendor(vendor) {
+    if (Object.hasOwn(RESOLVER_VENDOR_CAPABILITIES, vendor))
+        return;
+    throw new Error(`Unknown resolver vendor "${vendor}" in resolver configuration`);
+}
+function throwUnsupportedKind(kind) {
+    throw new ProviderError(`Resolver vendor chain does not support kind "${kind}"`, {
+        code: "RESOLVER_KIND_UNSUPPORTED_BY_CHAIN",
+        fix: `Add a resolver vendor that supports "${kind}" to the provider's resolver.vendors declaration.`,
+    });
+}
+function throwExhausted(attempts) {
+    const summary = attempts.map(({ vendor, reason }) => `${vendor}: ${reason}`).join(", ");
+    throw new ProviderError(`Resolver vendor chain exhausted: ${summary}`, {
+        code: "RESOLVER_CHAIN_EXHAUSTED",
+        fix: "Configure another supporting resolver vendor or restore an unavailable vendor.",
+        details: attempts,
+    });
+}
+function challengeOrigin(challenge) {
+    return new URL(challenge.pageUrl).origin;
+}
+function resolverIdentityDigest(identity) {
+    return createHash("sha256")
+        .update(JSON.stringify({
+        proxyUrl: identity.proxyUrl ?? null,
+        userAgent: identity.userAgent,
+    }))
+        .digest("hex");
+}
+function resolverIdentityScopeDigest(identityScope) {
+    return createHash("sha256").update(JSON.stringify({ identityScope })).digest("hex");
+}
+function resolverSolutionCacheKey(cache, challenge, issuerDigest) {
+    return cache.key(RESOLVER_SOLUTION_CACHE_NAMESPACE, {
+        kind: challenge.kind,
+        origin: challengeOrigin(challenge),
+        issuerDigest,
+    });
+}
+function resolverSolutionIndexCacheKey(cache, challenge) {
+    return cache.key(RESOLVER_SOLUTION_INDEX_CACHE_NAMESPACE, {
+        kind: challenge.kind,
+        origin: challengeOrigin(challenge),
+    });
+}
+function isCachedResolverSolution(value) {
+    try {
+        if (value === null || typeof value !== "object")
+            return false;
+        const candidate = value;
+        if (typeof candidate.expiresAtMs !== "number" ||
+            typeof candidate.issuerDigest !== "string" ||
+            candidate.solution === null ||
+            typeof candidate.solution !== "object" ||
+            candidate.solution.form !== "cookies" ||
+            typeof candidate.solution.userAgent !== "string") {
+            return false;
+        }
+        const cookies = candidate.solution.cookies;
+        return (cookies !== null &&
+            typeof cookies === "object" &&
+            !Array.isArray(cookies) &&
+            Object.values(cookies).every((cookie) => typeof cookie === "string"));
+    }
+    catch {
+        return false;
+    }
+}
+function isResolverCacheIndex(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const entries = value.entries;
+    return (Array.isArray(entries) &&
+        entries.every((entry) => entry !== null &&
+            typeof entry === "object" &&
+            entry.direct === true &&
+            typeof entry.expiresAtMs === "number" &&
+            typeof entry.issuerDigest === "string"));
+}
+function solutionExpiryMs(solution) {
+    if (solution.form !== "cookies")
+        return undefined;
+    const expires = solution.expires;
+    if (typeof expires !== "number" || !Number.isFinite(expires))
+        return undefined;
+    return expires * 1_000;
+}
+function rememberSolutionIssuer(solution, issuerDigest) {
+    if (typeof solution === "object" && solution !== null) {
+        solutionIssuerDigests.set(solution, issuerDigest);
+    }
+}
+async function readCachedSolution(cache, challenge, issuerDigest, now) {
+    const cached = await cache.get(resolverSolutionCacheKey(cache, challenge, issuerDigest));
+    if (!cached || !isCachedResolverSolution(cached.value))
+        return undefined;
+    if (cached.value.issuerDigest !== issuerDigest || cached.value.expiresAtMs <= now)
+        return undefined;
+    rememberSolutionIssuer(cached.value.solution, issuerDigest);
+    return cached.value.solution;
+}
+async function findCachedSolution(cache, challenge, identity, identityScope) {
+    const now = Date.now();
+    if (identityScope !== undefined && resolverChallengeIsIdentityScoped(challenge)) {
+        return await readCachedSolution(cache, challenge, resolverIdentityScopeDigest(identityScope), now);
+    }
+    if (identity) {
+        const lookupIdentity = resolverChallengeIssuingIdentity(challenge, identity);
+        return await readCachedSolution(cache, challenge, resolverIdentityDigest(lookupIdentity), now);
+    }
+    const index = await cache.get(resolverSolutionIndexCacheKey(cache, challenge));
+    if (!index || !isResolverCacheIndex(index.value))
+        return undefined;
+    for (const entry of index.value.entries) {
+        if (entry.expiresAtMs <= now)
+            continue;
+        const solution = await readCachedSolution(cache, challenge, entry.issuerDigest, now);
+        if (solution)
+            return solution;
+    }
+    return undefined;
+}
+async function writeResolverCacheIndex(cache, challenge, entries, now) {
+    const indexKey = resolverSolutionIndexCacheKey(cache, challenge);
+    const liveEntries = entries.filter((entry) => entry.expiresAtMs > now);
+    if (liveEntries.length === 0) {
+        await cache.delete(indexKey);
+        return;
+    }
+    const ttlMs = Math.max(1, Math.floor(Math.max(...liveEntries.map((entry) => entry.expiresAtMs)) - now));
+    await cache.set(indexKey, { entries: liveEntries }, { ttlMs });
+}
+async function cacheBrowserSolution(cache, challenge, solution, identity, identityScope) {
+    const expiresAtMs = solutionExpiryMs(solution);
+    const now = Date.now();
+    if (expiresAtMs === undefined)
+        return;
+    const ttlMs = Math.floor(expiresAtMs - now);
+    if (ttlMs <= MIN_RESOLVER_CACHE_TTL_MS)
+        return;
+    const scopedDigest = identityScope !== undefined && resolverChallengeIsIdentityScoped(challenge)
+        ? resolverIdentityScopeDigest(identityScope)
+        : undefined;
+    const issuerDigest = scopedDigest ?? resolverIdentityDigest(identity);
+    await cache.set(resolverSolutionCacheKey(cache, challenge, issuerDigest), { expiresAtMs, issuerDigest, solution }, { ttlMs });
+    rememberSolutionIssuer(solution, issuerDigest);
+    if (scopedDigest !== undefined || identity.proxyUrl !== undefined)
+        return;
+    const indexKey = resolverSolutionIndexCacheKey(cache, challenge);
+    const current = await cache.get(indexKey);
+    const currentEntries = isResolverCacheIndex(current?.value) ? current.value.entries : [];
+    await writeResolverCacheIndex(cache, challenge, [
+        ...currentEntries.filter((entry) => entry.issuerDigest !== issuerDigest),
+        { direct: true, expiresAtMs, issuerDigest },
+    ], now);
+}
+/** Remove the cached entry for the exact solution object returned by this resolver. */
+export async function invalidateResolverSolution(resolver, challenge, solution) {
+    const metadata = resolver[RESOLVER_INSTRUMENTATION_METADATA];
+    const cacheOwner = metadata?.target ?? resolver;
+    const invalidate = async () => {
+        if (solution.form !== "cookies")
+            return "not_cookie_solution";
+        if (!resolverCaches.has(cacheOwner)) {
+            throw new Error("Resolver cache registration lookup failed during solution invalidation");
+        }
+        const cache = resolverCaches.get(cacheOwner);
+        if (cache === null || cache === undefined)
+            return "cache_disabled";
+        const issuerDigest = solutionIssuerDigests.get(solution);
+        if (!issuerDigest)
+            return "solution_not_cached";
+        await cache.delete(resolverSolutionCacheKey(cache, challenge, issuerDigest));
+        const index = await cache.get(resolverSolutionIndexCacheKey(cache, challenge));
+        if (!index)
+            return "entry_deleted";
+        if (!isResolverCacheIndex(index.value)) {
+            throw new Error("Resolver solution cache index is malformed during invalidation");
+        }
+        await writeResolverCacheIndex(cache, challenge, index.value.entries.filter((entry) => entry.issuerDigest !== issuerDigest), Date.now());
+        return "index_entry_deleted";
+    };
+    if (!metadata) {
+        await invalidate();
+        return;
+    }
+    await metadata.traceRecorder.runSpan("resolver.cache.invalidate", invalidate, {
+        attributes: { challenge_kind: challenge.kind },
+        onSuccess: (outcome) => ({ outcome }),
+    });
+}
+function createResolverChainClient(options) {
+    const client = {
+        async solve(challenge, signal = new AbortController().signal, traceRecorder) {
+            assertDeclaredKind(challenge.kind, options.kinds);
+            if (options.unavailableReason) {
+                throw new ProviderError(options.unavailableReason, {
+                    code: "RESOLVER_UNAVAILABLE",
+                    fix: "Configure at least one declared resolver vendor or provide a test ResolverContext override.",
+                });
+            }
+            const supportingEntries = options.entries.filter((entry) => entry.supports(challenge.kind));
+            if (supportingEntries.length === 0)
+                throwUnsupportedKind(challenge.kind);
+            signal.throwIfAborted();
+            if (options.cache && supportingEntries.some((entry) => entry.id === "browser")) {
+                const cached = await findCachedSolution(options.cache, challenge, options.identity, options.identityScope);
+                if (cached)
+                    return cached;
+            }
+            const attempts = [];
+            for (const entry of supportingEntries) {
+                const adapter = entry.createAdapter();
+                try {
+                    const solveAttempt = () => adapter.solve(challenge, options.identity, signal, traceRecorder);
+                    const solution = traceRecorder
+                        ? await traceRecorder.runSpan("resolver.vendor.attempt", solveAttempt, {
+                            attributes: {
+                                vendor: adapter.id,
+                                challenge_kind: challenge.kind,
+                            },
+                            onError(error) {
+                                return error instanceof ResolverVendorUnavailableError
+                                    ? { unavailability_reason: error.reason }
+                                    : undefined;
+                            },
+                        })
+                        : await solveAttempt();
+                    if (options.cache && entry.id === "browser" && solution.form === "cookies") {
+                        const issuingIdentity = adapter.getIssuingIdentity?.(solution, options.identity, challenge);
+                        if (issuingIdentity) {
+                            await cacheBrowserSolution(options.cache, challenge, solution, issuingIdentity, options.identityScope);
+                        }
+                    }
+                    return solution;
+                }
+                catch (error) {
+                    signal.throwIfAborted();
+                    if (!(error instanceof ResolverVendorUnavailableError))
+                        throw error;
+                    attempts.push({ vendor: adapter.id, reason: error.reason });
+                }
+            }
+            throwExhausted(attempts);
+        },
+    };
+    resolverCaches.set(client, options.cache ?? null);
+    return client;
+}
+export function createResolverClient(options) {
+    return createResolverChainClient({
+        kinds: options.kinds,
+        entries: options.adapters.map((adapter) => ({
+            id: adapter.id,
+            supports: (kind) => adapter.supports(kind),
+            createAdapter: () => adapter,
+        })),
+        unavailableReason: options.unavailableReason,
+        cache: options.cache,
+        identity: options.identity,
+    });
+}
+function resolveVendorAvailability(vendor, env) {
+    if (vendor === "custom") {
+        return {
+            vendor,
+            available: false,
+            reason: "missing_transport",
+        };
+    }
+    const envKey = vendor === "2captcha"
+        ? APIFUSE__RESOLVER__2CAPTCHA__API_KEY
+        : vendor === "capsolver"
+            ? APIFUSE__RESOLVER__CAPSOLVER__API_KEY
+            : vendor === "capmonster"
+                ? APIFUSE__RESOLVER__CAPMONSTER__API_KEY
+                : APIFUSE__CDP_POOL__URL;
+    const configuration = normalizedEnvValue(env, envKey);
+    return configuration
+        ? { vendor, available: true, configuration }
+        : { vendor, available: false, reason: "missing_credentials" };
+}
+export function createUnsupportedResolverClient(reason) {
+    return {
+        async solve() {
+            throw new ProviderError(reason ?? "Resolver runtime is not configured", {
+                code: "RESOLVER_UNAVAILABLE",
+                fix: "Declare resolver on the provider definition and configure vendor credentials.",
+            });
+        },
+    };
+}
+export function bindResolverSignal(resolver, defaultSignal) {
+    if (!defaultSignal)
+        return resolver;
+    const boundResolver = {
+        solve(challenge, signal = defaultSignal) {
+            return resolver.solve(challenge, signal);
+        },
+    };
+    if (resolverCaches.has(resolver)) {
+        resolverCaches.set(boundResolver, resolverCaches.get(resolver) ?? null);
+    }
+    return boundResolver;
+}
+export function createResolverClientFromEnv(config, env = process.env, options = {}) {
+    if (!config) {
+        return createUnsupportedResolverClient("Provider does not declare resolver capability");
+    }
+    if (config.vendors.length === 0) {
+        return createResolverChainClient({
+            kinds: config.kinds,
+            entries: [],
+            unavailableReason: "Provider resolver vendor chain is empty",
+        });
+    }
+    const timeoutValue = readPositiveIntegerEnv(env, APIFUSE__RESOLVER__TIMEOUT_MS);
+    const timeoutMs = timeoutValue === undefined ? DEFAULT_RESOLVER_TIMEOUT_MS : Number(timeoutValue);
+    return createResolverChainClient({
+        kinds: config.kinds,
+        entries: config.vendors.map((configuredVendor) => {
+            assertKnownResolverVendor(configuredVendor);
+            const vendor = configuredVendor;
+            return {
+                id: vendor,
+                supports: (kind) => resolverVendorSupports(vendor, kind),
+                createAdapter: () => createAdapter(resolveVendorAvailability(vendor, env), timeoutMs, options.allowedHosts ?? []),
+            };
+        }),
+        cache: options.cache,
+        identityScope: options.identityScope,
+    });
+}

package/dist/runtime/state.d.ts

@@ -1,8 +1,11 @@
 import { ProviderError } from "../errors.js";
 import type { ProviderRuntimeState } from "../types.js";
+import { type ProviderRedisClient } from "./redis.js";
 type RedisProviderRuntimeStateOptions = {
     readonly redisUrl: string;
     readonly providerId?: string;
+    /** Test seam; production callers use redisUrl-backed client sharing. */
+    readonly __redisClient?: ProviderRedisClient;
 };
 export declare class UnsupportedProviderStateError extends ProviderError {
     constructor(message?: string);