@prosopo/load-balancer 2.9.20 → 2.10.0

package/dist/tests/providers.unit.test.js

@@ -1,224 +1,86 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { loadBalancer } from "../index.js";
-import { getRandomActiveProvider, selectWeightedProvider, } from "../providers.js";
-import { _resetCache } from "../providers.js";
-vi.mock("../index.js", () => ({
-    loadBalancer: vi.fn(),
-}));
-describe("selectWeightedProvider", () => {
-    it("selects provider based on weight distribution", () => {
-        const providers = [
-            {
-                address: "address1",
-                url: "url1",
-                datasetId: "dataset1",
-                weight: 1,
-            },
-            {
-                address: "address2",
-                url: "url2",
-                datasetId: "dataset2",
-                weight: 3,
-            },
-            {
-                address: "address3",
-                url: "url3",
-                datasetId: "dataset3",
-                weight: 1,
-            },
-        ];
-        expect(selectWeightedProvider(providers, 0).address).toBe("address1");
-        expect(selectWeightedProvider(providers, 1).address).toBe("address2");
-        expect(selectWeightedProvider(providers, 2).address).toBe("address2");
-        expect(selectWeightedProvider(providers, 3).address).toBe("address2");
-        expect(selectWeightedProvider(providers, 4).address).toBe("address3");
-        expect(selectWeightedProvider(providers, 5).address).toBe("address1");
-        expect(selectWeightedProvider(providers, 6).address).toBe("address2");
-    });
-    it("handles equal weights correctly", () => {
-        const providers = [
-            {
-                address: "address1",
-                url: "url1",
-                datasetId: "dataset1",
-                weight: 1,
-            },
-            {
-                address: "address2",
-                url: "url2",
-                datasetId: "dataset2",
-                weight: 1,
-            },
-        ];
-        expect(selectWeightedProvider(providers, 0).address).toBe("address1");
-        expect(selectWeightedProvider(providers, 1).address).toBe("address2");
-        expect(selectWeightedProvider(providers, 2).address).toBe("address1");
-        expect(selectWeightedProvider(providers, 3).address).toBe("address2");
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { _resetPinCache, getRandomActiveProvider } from "../providers.js";
+const originalFetch = globalThis.fetch;
+const mockHealthzFetch = (host, ok = true, status = 200) => {
+    const mocked = vi.fn(async () => ({
+        ok,
+        status,
+        json: async () => ({ ok: true, host }),
+    }));
+    globalThis.fetch = mocked;
+    return mocked;
+};
+beforeEach(() => {
+    _resetPinCache();
+});
+afterEach(() => {
+    globalThis.fetch = originalFetch;
+});
+describe("getRandomActiveProvider (dual stack)", () => {
+    it("uses the local URL directly in development (no healthz round-trip)", async () => {
+        const mocked = mockHealthzFetch("ignored");
+        const result = await getRandomActiveProvider("development");
+        expect(result.provider.url).toBe("https://localhost:9229");
+        expect(mocked).not.toHaveBeenCalled();
     });
-    it("handles single provider", () => {
-        const providers = [
-            {
-                address: "address1",
-                url: "url1",
-                datasetId: "dataset1",
-                weight: 10,
-            },
-        ];
-        expect(selectWeightedProvider(providers, 0).address).toBe("address1");
-        expect(selectWeightedProvider(providers, 5).address).toBe("address1");
-        expect(selectWeightedProvider(providers, 100).address).toBe("address1");
+    it("pins to the host returned by /healthz in production", async () => {
+        mockHealthzFetch("pronode7.prosopo.io");
+        const result = await getRandomActiveProvider("production");
+        expect(result.provider.url).toBe("https://pronode7.prosopo.io");
     });
-    it("throws error for empty provider list", () => {
-        expect(() => selectWeightedProvider([], 0)).toThrow("No providers available");
+    it("pins to the host returned by /healthz in staging", async () => {
+        mockHealthzFetch("staging-pronode2.prosopo.io");
+        const result = await getRandomActiveProvider("staging");
+        expect(result.provider.url).toBe("https://staging-pronode2.prosopo.io");
     });
-    it("heavily weighted provider is selected more often", () => {
-        const providers = [
-            {
-                address: "address1",
-                url: "url1",
-                datasetId: "dataset1",
-                weight: 1,
-            },
-            {
-                address: "address2",
-                url: "url2",
-                datasetId: "dataset2",
-                weight: 99,
-            },
-        ];
-        const selections = { address1: 0, address2: 0 };
-        for (let i = 0; i < 100; i++) {
-            const selected = selectWeightedProvider(providers, i);
-            if (selected.address === "address1") {
-                selections.address1++;
-            }
-            else {
-                selections.address2++;
-            }
-        }
-        expect(selections.address1).toBe(1);
-        expect(selections.address2).toBe(99);
+    it("caches the pinned URL for repeat callers in the same env + ipMode", async () => {
+        const mocked = mockHealthzFetch("pronode3.prosopo.io");
+        await getRandomActiveProvider("production");
+        await getRandomActiveProvider("production");
+        await getRandomActiveProvider("production");
+        expect(mocked).toHaveBeenCalledTimes(1);
     });
-    it("handles maximum weight value (100)", () => {
-        const providers = [
-            {
-                address: "address1",
-                url: "url1",
-                datasetId: "dataset1",
-                weight: 100,
-            },
-            {
-                address: "address2",
-                url: "url2",
-                datasetId: "dataset2",
-                weight: 100,
-            },
-        ];
-        const selections = { address1: 0, address2: 0 };
-        for (let i = 0; i < 200; i++) {
-            const selected = selectWeightedProvider(providers, i);
-            if (selected.address === "address1") {
-                selections.address1++;
-            }
-            else {
-                selections.address2++;
-            }
-        }
-        expect(selections.address1).toBe(100);
-        expect(selections.address2).toBe(100);
+    it("falls back to the dual-stack base URL when /healthz responds non-OK", async () => {
+        mockHealthzFetch("ignored", false, 503);
+        const result = await getRandomActiveProvider("production");
+        expect(result.provider.url).toBe("https://pronode.prosopo.io");
     });
-    it("correctly handles providers without values for weight", () => {
-        const providers = [
-            {
-                address: "address1",
-                url: "url1",
-                datasetId: "dataset1",
-            },
-            {
-                address: "address2",
-                url: "url2",
-                datasetId: "dataset2",
-                weight: 3,
-            },
-        ];
-        const providersWithDefaults = [
-            { ...providers[0], weight: 1 },
-            providers[1],
-        ];
-        const selections = { address1: 0, address2: 0 };
-        for (let i = 0; i < 100; i++) {
-            const selected = selectWeightedProvider(providersWithDefaults, i);
-            if (selected.address === "address1") {
-                selections.address1++;
-            }
-            else {
-                selections.address2++;
-            }
-        }
-        expect(selections.address1).toBe(25);
-        expect(selections.address2).toBe(75);
+    it("falls back to the dual-stack base URL when /healthz body is malformed", async () => {
+        const mocked = vi.fn(async () => ({
+            ok: true,
+            status: 200,
+            json: async () => ({ ok: true }),
+        }));
+        globalThis.fetch = mocked;
+        const result = await getRandomActiveProvider("production");
+        expect(result.provider.url).toBe("https://pronode.prosopo.io");
     });
 });
-describe("getRandomActiveProvider", () => {
-    beforeEach(() => {
-        _resetCache();
-        vi.clearAllMocks();
-        vi.resetAllMocks();
-        vi.resetModules();
-    });
-    it("returns a random provider when providers list is populated", async () => {
-        const mockProviders = [
-            { address: "address1", url: "url1", datasetId: "dataset1", weight: 1 },
-            { address: "address2", url: "url2", datasetId: "dataset2", weight: 1 },
-        ];
-        loadBalancer.mockResolvedValue(mockProviders);
-        const result = await getRandomActiveProvider("development", 1);
-        expect(result.providerAccount).toBe("address2");
-        expect(result.provider.url).toBe("url2");
-        expect(result.provider.datasetId).toBe("dataset2");
-    });
-    it("loads providers only once when called multiple times", async () => {
-        const mockProviders = [
-            { address: "address1", url: "url1", datasetId: "dataset1", weight: 1 },
-        ];
-        loadBalancer.mockResolvedValue(mockProviders);
-        await getRandomActiveProvider("development", 123);
-        await getRandomActiveProvider("development", 456);
-        expect(loadBalancer).toHaveBeenCalledTimes(1);
+describe("getRandomActiveProvider (single stack ipMode)", () => {
+    it("hits ipv4.pronode.prosopo.io/healthz and pins to ipv4.pronodeN", async () => {
+        const mocked = mockHealthzFetch("pronode4.prosopo.io");
+        const result = await getRandomActiveProvider("production", "ipv4");
+        expect(result.provider.url).toBe("https://ipv4.pronode4.prosopo.io");
+        expect(mocked).toHaveBeenCalledWith("https://ipv4.pronode.prosopo.io/healthz", expect.any(Object));
     });
-    it("handles empty providers list gracefully", async () => {
-        loadBalancer.mockResolvedValue([]);
-        await expect(getRandomActiveProvider("development", 123)).rejects.toThrow();
+    it("hits ipv6 staging /healthz and pins to ipv6.staging-pronodeN", async () => {
+        const mocked = mockHealthzFetch("staging-pronode2.prosopo.io");
+        const result = await getRandomActiveProvider("staging", "ipv6");
+        expect(result.provider.url).toBe("https://ipv6.staging-pronode2.prosopo.io");
+        expect(mocked).toHaveBeenCalledWith("https://ipv6.staging.pronode.prosopo.io/healthz", expect.any(Object));
     });
-    it("respects provider weights when selecting", async () => {
-        const mockProviders = [
-            { address: "address1", url: "url1", datasetId: "dataset1", weight: 1 },
-            { address: "address2", url: "url2", datasetId: "dataset2", weight: 3 },
-        ];
-        loadBalancer.mockResolvedValue(mockProviders);
-        const result0 = await getRandomActiveProvider("development", 0);
-        expect(result0.providerAccount).toBe("address1");
-        _resetCache();
-        const result1 = await getRandomActiveProvider("development", 1);
-        expect(result1.providerAccount).toBe("address2");
-        _resetCache();
-        const result2 = await getRandomActiveProvider("development", 2);
-        expect(result2.providerAccount).toBe("address2");
-        _resetCache();
-        const result3 = await getRandomActiveProvider("development", 3);
-        expect(result3.providerAccount).toBe("address2");
+    it("falls back to the ipv4-labelled global URL when ipv4 /healthz fails", async () => {
+        mockHealthzFetch("ignored", false, 500);
+        const result = await getRandomActiveProvider("production", "ipv4");
+        expect(result.provider.url).toBe("https://ipv4.pronode.prosopo.io");
     });
-    it("handles providers with missing weight field (defaults to 1)", async () => {
-        const mockProviders = [
-            { address: "address1", url: "url1", datasetId: "dataset1", weight: 1 },
-            { address: "address2", url: "url2", datasetId: "dataset2", weight: 1 },
-        ];
-        loadBalancer.mockResolvedValue(mockProviders);
-        const result0 = await getRandomActiveProvider("development", 0);
-        expect(result0.providerAccount).toBe("address1");
-        _resetCache();
-        const result1 = await getRandomActiveProvider("development", 1);
-        expect(result1.providerAccount).toBe("address2");
+    it("keeps the dual-stack cache and the ipv4 cache separate", async () => {
+        const mocked = mockHealthzFetch("pronode9.prosopo.io");
+        await getRandomActiveProvider("production");
+        await getRandomActiveProvider("production", "ipv4");
+        await getRandomActiveProvider("production");
+        await getRandomActiveProvider("production", "ipv4");
+        expect(mocked).toHaveBeenCalledTimes(2);
     });
 });
 //# sourceMappingURL=providers.unit.test.js.map

package/dist/tests/providers.unit.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"providers.unit.test.js","sourceRoot":"","sources":["../../src/tests/providers.unit.test.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"providers.unit.test.js","sourceRoot":"","sources":["../../src/tests/providers.unit.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@prosopo/load-balancer",
-	"version": "2.9.20",
+	"version": "2.10.0",
 	"description": "Provider load balancer",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -38,11 +38,11 @@
 	"homepage": "https://github.com/prosopo/captcha#readme",
 	"dependencies": {
 		"@prosopo/common": "3.1.40",
-		"@prosopo/types": "4.7.3",
+		"@prosopo/types": "4.8.0",
 		"zod": "3.23.8"
 	},
 	"devDependencies": {
-		"@prosopo/config": "3.3.2",
+		"@prosopo/config": "3.3.3",
 		"@types/node": "22.10.2",
 		"@vitest/coverage-v8": "3.2.4",
 		"concurrently": "9.0.1",

package/src/balancer.ts

@@ -32,17 +32,43 @@ const HardcodedProviderSchema = z.object({
 
 export type HardcodedProvider = z.infer<typeof HardcodedProviderSchema>;
 
+export type IpMode = "ipv4" | "ipv6";
+
+// Top-level keys reserved by providerListJson for the ipv4-only / ipv6-only
+// sub-lists. They appear alongside the dual-stack provider entries in the
+// fetched JSON; the converter skips them so existing dual-stack consumers
+// keep working.
+const IP_MODE_KEYS: ReadonlyArray<IpMode> = ["ipv4", "ipv6"];
+
 type hostedProviders = Record<string, unknown>;
 
+const isProviderRecord = (value: unknown): value is hostedProviders =>
+	typeof value === "object" && value !== null;
+
 export const convertHostedProvider = (
 	provider: hostedProviders,
+	ipMode?: IpMode,
 ): HardcodedProvider[] => {
-	const providers = Object.values(provider).map((p) =>
-		HardcodedProviderSchema.parse(p),
-	);
+	const source =
+		ipMode && isProviderRecord(provider[ipMode])
+			? (provider[ipMode] as hostedProviders)
+			: provider;
+
+	const providers = Object.entries(source)
+		.filter(([key]) => !IP_MODE_KEYS.includes(key as IpMode))
+		.map(([, value]) => HardcodedProviderSchema.parse(value));
 	return providers.sort((a, b) => a.url.localeCompare(b.url));
 };
 
+// Strip the leading `ipv4.` / `ipv6.` label that providerListJson prepends for
+// the single-stack sub-lists so callers can derive a stable identity from the
+// provider URL regardless of which ipMode was requested.
+export const stripIpModeLabel = (hostname: string): string =>
+	hostname.replace(/^ipv[46]\./, "");
+
+export const getProviderHostname = (provider: HardcodedProvider): string =>
+	stripIpModeLabel(new URL(provider.url).hostname);
+
 export const getLoadBalancerUrl = (environment: EnvironmentTypes): string => {
 	if (environment === "production") {
 		return "https://provider-list.prosopo.io/";

package/src/providers.ts

@@ -13,119 +13,114 @@
 // limitations under the License.
 
 import type { EnvironmentTypes, RandomProvider } from "@prosopo/types";
-import { type HardcodedProvider, loadBalancer } from "./index.js";
+import type { IpMode } 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();
-
-/** Optional custom loader for server-side caching (e.g. cacheFile with ETag). */
-let customProviderLoader:
-	| ((env: EnvironmentTypes) => Promise<HardcodedProvider[]>)
-	| null = null;
-
-/**
- * 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;
-}
+// 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",
+};
 
-export function _resetCache() {
-	providerPromiseCache.clear();
-}
+// 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;
 
-/**
- * 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 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;
 	}
+};
 
-	const totalWeight = providers.reduce((sum, p) => sum + p.weight, 0);
-
-	// Use entropy to generate a value between 0 and totalWeight-1
-	const randomValue = entropy % totalWeight;
-
-	// Select provider based on cumulative weight
-	let cumulativeWeight = 0;
-	for (const provider of providers) {
-		cumulativeWeight += provider.weight;
-		if (randomValue < cumulativeWeight) {
-			return provider;
-		}
-	}
+// 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();
 
-	// Fallback (should never reach here)
-	const selectedProvider = providers[providers.length - 1];
-	if (!selectedProvider) {
-		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}`);
 	}
-	return selectedProvider;
-}
-
-/** Load providers using the custom loader if set, otherwise the default fetch. */
-const loadProviders = async (
-	env: EnvironmentTypes,
-): Promise<HardcodedProvider[]> => {
-	if (customProviderLoader) {
-		return customProviderLoader(env);
+	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 loadBalancer(env);
+	return body.host;
 };
 
-// Caches the in-flight Promise (not the resolved array) so concurrent callers
-// share a single network request rather than racing.
-const getProvidersPromise = (
-	env: EnvironmentTypes,
-): Promise<HardcodedProvider[]> => {
-	const existing = providerPromiseCache.get(env);
-	if (existing) return existing;
-	const promise = loadProviders(env).catch((err) => {
-		providerPromiseCache.delete(env);
-		throw err;
-	});
-	providerPromiseCache.set(env, promise);
-	return promise;
-};
+const resolveBaseUrl = (env: EnvironmentTypes): string =>
+	DNS_ENDPOINT[env] ?? DNS_ENDPOINT.development;
 
-/**
- * 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 (
+const resolvePinnedUrl = async (
 	env: EnvironmentTypes,
-): Promise<void> => {
-	await getProvidersPromise(env);
+	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;
+
+	const key = cacheKey(env, ipMode);
+	const cached = pinPromiseCache.get(key);
+	if (cached) return cached;
+
+	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;
+		}
+	})();
+
+	pinPromiseCache.set(key, promise);
+	return promise;
 };
 
 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();
+};