@apifuse/provider-sdk 2.2.0-beta.47 → 2.2.0-beta.49

package/src/runtime/resolver.ts

@@ -51,7 +51,7 @@ import {
 	APIFUSE__RESOLVER__TIMEOUT_MS,
 	DEFAULT_RESOLVER_TIMEOUT_MS,
 } from "./resolver-config.js";
-import { DEFAULT_PROFILE } from "./stealth.js";
+import { DEFAULT_STEALTH_PROFILE } from "./stealth.js";
 import type { TraceRecorder } from "./trace.js";
 
 export {
@@ -143,11 +143,21 @@ type ResolverCacheIndex = {
 	}[];
 };
 
+export type ResolverSolutionSource = "cache" | "vendor";
+
+type ResolverSolutionInvalidationOutcome =
+	| "cache_disabled"
+	| "entry_deleted"
+	| "index_entry_deleted"
+	| "not_cookie_solution"
+	| "solution_not_cached";
+
 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<object, ProviderCache | null>();
 const solutionIssuerDigests = new WeakMap<object, string>();
+const resolverSolutionSources = new WeakMap<object, ResolverSolutionSource>();
 const SAFE_CAUSE_MESSAGE_WORDS: ReadonlySet<string> = new Set([
 	"abort",
 	"aborted",
@@ -244,7 +254,7 @@ export function swapResolverAdapterFactoryForTests(
 }
 
 let resolveDefaultResolverUserAgent: () => string | undefined = () =>
-	getStealthProfile(DEFAULT_PROFILE).userAgent;
+	getStealthProfile(DEFAULT_STEALTH_PROFILE).userAgent;
 
 /** Internal test seam; deliberately not re-exported from the package root. */
 export function swapResolverDefaultUserAgentForTests(
@@ -252,7 +262,7 @@ export function swapResolverDefaultUserAgentForTests(
 ): () => void {
 	const original = resolveDefaultResolverUserAgent;
 	resolveDefaultResolverUserAgent =
-		resolver ?? (() => getStealthProfile(DEFAULT_PROFILE).userAgent);
+		resolver ?? (() => getStealthProfile(DEFAULT_STEALTH_PROFILE).userAgent);
 	let restored = false;
 	return () => {
 		if (restored) return;
@@ -597,7 +607,7 @@ function isResolverCacheIndex(value: unknown): value is ResolverCacheIndex {
 
 function solutionExpiryMs(solution: ChallengeSolution): number | undefined {
 	if (solution.form !== "cookies") return undefined;
-	const expires = solution.expires;
+	const expires = solution.expires ?? solution.sdkEstimatedExpires;
 	if (typeof expires !== "number" || !Number.isFinite(expires)) return undefined;
 	return expires * 1_000;
 }
@@ -608,6 +618,22 @@ function rememberSolutionIssuer(solution: ChallengeSolution, issuerDigest: strin
 	}
 }
 
+function rememberSolutionSource(solution: ChallengeSolution, source: ResolverSolutionSource): void {
+	if (typeof solution === "object" && solution !== null) {
+		resolverSolutionSources.set(solution, source);
+	}
+}
+
+/**
+ * Identify whether this exact SDK-returned solution object came from the cache
+ * or a vendor solve. Returns undefined for copied or caller-created objects.
+ */
+export function getResolverSolutionSource(
+	solution: ChallengeSolution,
+): ResolverSolutionSource | undefined {
+	return resolverSolutionSources.get(solution);
+}
+
 async function readCachedSolution(
 	cache: ProviderCache,
 	challenge: ProviderChallenge,
@@ -618,8 +644,14 @@ async function readCachedSolution(
 	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;
+	if (cached.value.solution.form !== "cookies") return undefined;
+	const solution = {
+		...cached.value.solution,
+		cookies: { ...cached.value.solution.cookies },
+	};
+	rememberSolutionIssuer(solution, issuerDigest);
+	rememberSolutionSource(solution, "cache");
+	return solution;
 }
 
 async function findCachedSolution(
@@ -720,25 +752,18 @@ async function cacheResolverSolution(
 	);
 }
 
-/** Remove the cached entry for the exact solution object returned by this resolver. */
-export async function invalidateResolverSolution(
+async function invalidateResolverSolutionWithOutcome(
 	resolver: ResolverContext,
 	challenge: ProviderChallenge,
 	solution: ChallengeSolution,
-): Promise<void> {
+): Promise<ResolverSolutionInvalidationOutcome> {
 	const metadata = (
 		resolver as ResolverContext & {
 			readonly [RESOLVER_INSTRUMENTATION_METADATA]?: ResolverInstrumentationMetadata;
 		}
 	)[RESOLVER_INSTRUMENTATION_METADATA];
 	const cacheOwner = metadata?.target ?? resolver;
-	const invalidate = async (): Promise<
-		| "cache_disabled"
-		| "entry_deleted"
-		| "index_entry_deleted"
-		| "not_cookie_solution"
-		| "solution_not_cached"
-	> => {
+	const invalidate = async (): Promise<ResolverSolutionInvalidationOutcome> => {
 		if (solution.form !== "cookies") return "not_cookie_solution";
 		if (!resolverCaches.has(cacheOwner)) {
 			throw new Error("Resolver cache registration lookup failed during solution invalidation");
@@ -764,15 +789,38 @@ export async function invalidateResolverSolution(
 	};
 
 	if (!metadata) {
-		await invalidate();
-		return;
+		return await invalidate();
 	}
-	await metadata.traceRecorder.runSpan("resolver.cache.invalidate", invalidate, {
+	return await metadata.traceRecorder.runSpan("resolver.cache.invalidate", invalidate, {
 		attributes: { challenge_kind: challenge.kind },
 		onSuccess: (outcome) => ({ outcome }),
 	});
 }
 
+/** Remove the cached entry for the exact solution object returned by this resolver. */
+export async function invalidateResolverSolution(
+	resolver: ResolverContext,
+	challenge: ProviderChallenge,
+	solution: ChallengeSolution,
+): Promise<void> {
+	await invalidateResolverSolutionWithOutcome(resolver, challenge, solution);
+}
+
+/**
+ * Remove a solution only when it was returned from the resolver cache. Providers
+ * should call this when an upstream serves the same challenge after a cached
+ * solution was applied, so the next `solve()` mints a fresh solution.
+ */
+export async function invalidateCachedResolverSolution(
+	resolver: ResolverContext,
+	challenge: ProviderChallenge,
+	solution: ChallengeSolution,
+): Promise<boolean> {
+	if (getResolverSolutionSource(solution) !== "cache") return false;
+	const outcome = await invalidateResolverSolutionWithOutcome(resolver, challenge, solution);
+	return outcome === "entry_deleted" || outcome === "index_entry_deleted";
+}
+
 async function resolveResolverIdentity(
 	proxyIntent: NonNullable<ResolverRuntimeOptions["proxyIntent"]>,
 ): Promise<{
@@ -938,6 +986,7 @@ function createResolverChainClient(options: {
 							);
 						}
 					}
+					rememberSolutionSource(solution, "vendor");
 					return solution;
 				} catch (error) {
 					signal.throwIfAborted();