@prosopo/load-balancer 2.9.21 → 2.10.1

package/src/providers.ts

@@ -13,119 +13,153 @@
 // limitations under the License.
 
 import type { EnvironmentTypes, RandomProvider } from "@prosopo/types";
-import { type HardcodedProvider, loadBalancer } from "./index.js";
+import {
+	type HardcodedProvider,
+	type IpMode,
+	loadBalancer,
+} from "./balancer.js";
 
-// Keyed by env so a prefetch and a later call with a different env don't share.
-const providerPromiseCache: Map<
-	EnvironmentTypes,
-	Promise<HardcodedProvider[]>
-> = new Map();
+// Base DNS endpoint per env — the `pronode.prosopo.io` family is latency-routed
+// (A/AAAA records across the pronode fleet). Clients hit this URL's `/healthz`
+// once to discover which specific pronodeN the DNS layer picked, then pin
+// subsequent captcha calls to that pronode so session creation and submission
+// land on the same backend.
+const DNS_ENDPOINT: Record<EnvironmentTypes, string> = {
+	development: "https://localhost:9229",
+	staging: "https://staging.pronode.prosopo.io",
+	production: "https://pronode.prosopo.io",
+};
 
-/** Optional custom loader for server-side caching (e.g. cacheFile with ETag). */
-let customProviderLoader:
-	| ((env: EnvironmentTypes) => Promise<HardcodedProvider[]>)
-	| null = null;
+// Apply the `ipv4.` / `ipv6.` DNS label to a hostname. The single-stack
+// sub-zones only resolve to A or AAAA records respectively, so this pins the
+// network path before TLS negotiation. Ansible provisions the matching certs
+// for both `ipv4.{global}` and `ipv4.pronodeN.{global}`.
+const withIpModeLabel = (hostname: string, ipMode?: IpMode): string =>
+	ipMode ? `${ipMode}.${hostname}` : hostname;
 
-/**
- * Set a custom provider loader that replaces the default HTTP fetch.
- * Use this on the server side to inject cacheFile-based loading with
- * ETag/Last-Modified support for disk persistence across restarts.
- */
-export function setProviderLoader(
-	loader: (env: EnvironmentTypes) => Promise<HardcodedProvider[]>,
-): void {
-	customProviderLoader = loader;
-}
+const applyIpModeToUrl = (url: string, ipMode?: IpMode): string => {
+	if (!ipMode) return url;
+	try {
+		const parsed = new URL(url);
+		parsed.hostname = withIpModeLabel(parsed.hostname, ipMode);
+		return parsed.toString().replace(/\/$/, "");
+	} catch {
+		return url;
+	}
+};
 
-export function _resetCache() {
-	providerPromiseCache.clear();
-}
+// Cached, in-flight pin per (env, ipMode). Keyed so dual-stack and single-stack
+// callers maintain separate stickiness — they hit different /healthz endpoints
+// and shouldn't share each other's resolution.
+type CacheKey = `${EnvironmentTypes}|${IpMode | "dual"}`;
+const cacheKey = (env: EnvironmentTypes, ipMode?: IpMode): CacheKey =>
+	`${env}|${ipMode ?? "dual"}`;
+const pinPromiseCache: Map<CacheKey, Promise<string>> = new Map();
 
-/**
- * Selects a weighted random provider using the entropy value.
- * Providers with higher weights are more likely to be selected.
- *
- * @param providers - Array of providers with weights
- * @param entropy - Random seed value for deterministic selection
- * @returns Selected provider
- */
-export function selectWeightedProvider(
-	providers: HardcodedProvider[],
-	entropy: number,
-): HardcodedProvider {
-	if (providers.length === 0) {
-		throw new Error("No providers available");
+const fetchPinnedHost = async (baseUrl: string): Promise<string> => {
+	const res = await fetch(`${baseUrl}/healthz`, {
+		method: "GET",
+		cache: "no-store",
+		credentials: "omit",
+	});
+	if (!res.ok) {
+		throw new Error(`healthz responded with ${res.status}`);
+	}
+	const body = (await res.json()) as { host?: unknown };
+	if (typeof body.host !== "string" || body.host.length === 0) {
+		throw new Error("healthz response missing host field");
 	}
+	return body.host;
+};
 
-	const totalWeight = providers.reduce((sum, p) => sum + p.weight, 0);
+const resolveBaseUrl = (env: EnvironmentTypes): string =>
+	DNS_ENDPOINT[env] ?? DNS_ENDPOINT.development;
 
-	// Use entropy to generate a value between 0 and totalWeight-1
-	const randomValue = entropy % totalWeight;
+const resolvePinnedUrl = async (
+	env: EnvironmentTypes,
+	ipMode?: IpMode,
+): Promise<string> => {
+	// The base for /healthz already carries the ipv4./ipv6. label when one is
+	// requested, so DNS keeps the discovery request on the same single-stack
+	// path as the captcha calls that follow.
+	const base = applyIpModeToUrl(resolveBaseUrl(env), ipMode);
+	// Development has no global hostname to /healthz against; use the
+	// hardcoded local URL.
+	if (env === "development") return base;
 
-	// Select provider based on cumulative weight
-	let cumulativeWeight = 0;
-	for (const provider of providers) {
-		cumulativeWeight += provider.weight;
-		if (randomValue < cumulativeWeight) {
-			return provider;
-		}
-	}
+	const key = cacheKey(env, ipMode);
+	const cached = pinPromiseCache.get(key);
+	if (cached) return cached;
 
-	// Fallback (should never reach here)
-	const selectedProvider = providers[providers.length - 1];
-	if (!selectedProvider) {
-		throw new Error("No providers available");
-	}
-	return selectedProvider;
-}
+	const promise = (async () => {
+		try {
+			const host = await fetchPinnedHost(base);
+			const parsed = new URL(base);
+			// /healthz returns the bare pronodeN.prosopo.io (env.config.host).
+			// Re-apply the ipMode label so the per-pronode URL stays on the same
+			// single-stack sub-zone (`ipv4.pronode4.prosopo.io`).
+			parsed.hostname = withIpModeLabel(host, ipMode);
+			return parsed.toString().replace(/\/$/, "");
+		} catch {
+			// Healthz unreachable / malformed — fall back to the load-balanced
+			// hostname (with the ipMode label still applied). Clients still
+			// work, they just lose per-pronode stickiness.
+			return base;
+		}
+	})();
 
-/** Load providers using the custom loader if set, otherwise the default fetch. */
-const loadProviders = async (
-	env: EnvironmentTypes,
-): Promise<HardcodedProvider[]> => {
-	if (customProviderLoader) {
-		return customProviderLoader(env);
-	}
-	return loadBalancer(env);
+	pinPromiseCache.set(key, promise);
+	return promise;
 };
 
-// Caches the in-flight Promise (not the resolved array) so concurrent callers
-// share a single network request rather than racing.
-const getProvidersPromise = (
+// Cached, in-flight provider-list load per env. The list rarely changes, so a
+// single fetch is shared across callers rather than re-fetching the
+// provider-list JSON on every verify-forward decision.
+const providerListPromiseCache: Map<
+	EnvironmentTypes,
+	Promise<HardcodedProvider[]>
+> = new Map();
+
+/**
+ * Returns the full (cached) list of active providers for an environment.
+ * Used to look up a provider by url/address, e.g. to find the provider that
+ * issued a token before forwarding a verification request to it.
+ */
+export const getProviders = async (
 	env: EnvironmentTypes,
 ): Promise<HardcodedProvider[]> => {
-	const existing = providerPromiseCache.get(env);
-	if (existing) return existing;
-	const promise = loadProviders(env).catch((err) => {
-		providerPromiseCache.delete(env);
+	const cached = providerListPromiseCache.get(env);
+	if (cached) return cached;
+
+	const promise = loadBalancer(env).catch((err) => {
+		// Don't cache failures — a transient fetch error shouldn't poison the
+		// cache for the lifetime of the process.
+		providerListPromiseCache.delete(env);
 		throw err;
 	});
-	providerPromiseCache.set(env, promise);
+	providerListPromiseCache.set(env, promise);
 	return promise;
 };
 
-/**
- * Pre-warms the provider cache for a given environment without requiring entropy.
- * Call this as early as possible to avoid a cold-cache delay when getRandomActiveProvider is first used.
- */
-export const prefetchProviders = async (
-	env: EnvironmentTypes,
-): Promise<void> => {
-	await getProvidersPromise(env);
-};
-
 export const getRandomActiveProvider = async (
 	env: EnvironmentTypes,
-	entropy: number,
+	ipMode?: IpMode,
 ): Promise<RandomProvider> => {
-	const providers = await getProvidersPromise(env);
-	const randomProviderObj = selectWeightedProvider(providers, entropy);
-
+	const url = await resolvePinnedUrl(env, ipMode);
 	return {
-		providerAccount: randomProviderObj.address,
-		provider: {
-			url: randomProviderObj.url,
-			datasetId: randomProviderObj.datasetId,
-		},
+		providerAccount: "dns-routed",
+		provider: { url },
 	};
 };
+
+// Test-only escape hatch so tests can isolate the healthz cache between
+// cases. Not exported from the package index — internal use only.
+export const _resetPinCache = () => {
+	pinPromiseCache.clear();
+};
+
+// Test-only escape hatch to isolate the provider-list cache between cases.
+// Not exported from the package index — internal use only.
+export const _resetProviderListCache = () => {
+	providerListPromiseCache.clear();
+};