@prosopo/load-balancer 2.8.17 → 2.9.10

package/src/balancer.ts

@@ -0,0 +1,81 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import { ProsopoEnvError } from "@prosopo/common";
+import type { EnvironmentTypes } from "@prosopo/types";
+import { z } from "zod";
+
+const HardcodedProviderSchema = z.object({
+	address: z.string(),
+	url: z.string(),
+	datasetId: z.string(),
+	weight: z
+		.number()
+		.optional()
+		.default(1)
+		.transform((val) => {
+			// weight coerced to int 1-100
+			const weight = Math.round(val);
+			return Math.max(1, Math.min(100, weight));
+		}),
+});
+
+export type HardcodedProvider = z.infer<typeof HardcodedProviderSchema>;
+
+type hostedProviders = Record<string, unknown>;
+
+export const convertHostedProvider = (
+	provider: hostedProviders,
+): HardcodedProvider[] => {
+	const providers = Object.values(provider).map((p) =>
+		HardcodedProviderSchema.parse(p),
+	);
+	return providers.sort((a, b) => a.url.localeCompare(b.url));
+};
+
+export const getLoadBalancerUrl = (environment: EnvironmentTypes): string => {
+	if (environment === "production") {
+		return "https://provider-list.prosopo.io/";
+	}
+	if (environment === "staging") {
+		return "https://provider-list.prosopo.io/staging.json";
+	}
+	throw new ProsopoEnvError("CONFIG.UNKNOWN_ENVIRONMENT", {
+		context: { environment },
+	});
+};
+
+export const loadBalancer = async (
+	environment: EnvironmentTypes,
+): Promise<HardcodedProvider[]> => {
+	if (environment === "development") {
+		return [
+			{
+				address: "5EjTA28bKSbFPPyMbUjNtArxyqjwq38r1BapVmLZShaqEedV",
+				url: "https://localhost:9229",
+				datasetId:
+					"0x7984714b92d61fd92fd6a7bc9b56b729481470bcc771c19c382ec679acf02e67",
+				weight: 1,
+			},
+		];
+	}
+
+	const providers: hostedProviders = await fetch(
+		getLoadBalancerUrl(environment),
+		{
+			method: "GET",
+			mode: "cors",
+		},
+	).then((res) => res.json());
+	return convertHostedProvider(providers);
+};

package/src/index.ts

@@ -0,0 +1,15 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+export * from "./providers.js";
+export * from "./balancer.js";

package/src/providers.ts

@@ -0,0 +1,131 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type { EnvironmentTypes, RandomProvider } from "@prosopo/types";
+import { type HardcodedProvider, loadBalancer } from "./index.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;
+}
+
+export function _resetCache() {
+	providerPromiseCache.clear();
+}
+
+/**
+ * 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 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;
+		}
+	}
+
+	// Fallback (should never reach here)
+	const selectedProvider = providers[providers.length - 1];
+	if (!selectedProvider) {
+		throw new Error("No providers available");
+	}
+	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);
+	}
+	return loadBalancer(env);
+};
+
+// 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;
+};
+
+/**
+ * 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,
+): Promise<RandomProvider> => {
+	const providers = await getProvidersPromise(env);
+	const randomProviderObj = selectWeightedProvider(providers, entropy);
+
+	return {
+		providerAccount: randomProviderObj.address,
+		provider: {
+			url: randomProviderObj.url,
+			datasetId: randomProviderObj.datasetId,
+		},
+	};
+};

package/src/tests/providers.unit.test.ts

@@ -0,0 +1,320 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { type HardcodedProvider, 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,
+			},
+		];
+
+		// Total weight = 5
+		// Provider 1: weight 1 (covers entropy 0-0)
+		// Provider 2: weight 3 (covers entropy 1-3)
+		// Provider 3: weight 1 (covers entropy 4-4)
+
+		// Entropy 0 should select provider1
+		expect(selectWeightedProvider(providers, 0).address).toBe("address1");
+
+		// Entropy 1-3 should select provider2
+		expect(selectWeightedProvider(providers, 1).address).toBe("address2");
+		expect(selectWeightedProvider(providers, 2).address).toBe("address2");
+		expect(selectWeightedProvider(providers, 3).address).toBe("address2");
+
+		// Entropy 4 should select provider3
+		expect(selectWeightedProvider(providers, 4).address).toBe("address3");
+
+		// Entropy wraps around with modulo
+		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,
+			},
+		];
+
+		// Total weight = 2
+		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");
+	});
+
+	it("handles single provider", () => {
+		const providers = [
+			{
+				address: "address1",
+				url: "url1",
+				datasetId: "dataset1",
+				weight: 10,
+			},
+		];
+
+		// All entropy values should select the only provider
+		expect(selectWeightedProvider(providers, 0).address).toBe("address1");
+		expect(selectWeightedProvider(providers, 5).address).toBe("address1");
+		expect(selectWeightedProvider(providers, 100).address).toBe("address1");
+	});
+
+	it("throws error for empty provider list", () => {
+		expect(() => selectWeightedProvider([], 0)).toThrow(
+			"No providers available",
+		);
+	});
+
+	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,
+			},
+		];
+
+		// Total weight = 100
+		// Provider 1: entropy 0 (1% of the time)
+		// Provider 2: entropy 1-99 (99% of the time)
+
+		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("handles maximum weight value (100)", () => {
+		const providers = [
+			{
+				address: "address1",
+				url: "url1",
+				datasetId: "dataset1",
+				weight: 100,
+			},
+			{
+				address: "address2",
+				url: "url2",
+				datasetId: "dataset2",
+				weight: 100,
+			},
+		];
+
+		// Total weight = 200
+		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++;
+			}
+		}
+
+		// Each should get selected 100 times (50%)
+		expect(selections.address1).toBe(100);
+		expect(selections.address2).toBe(100);
+	});
+
+	it("correctly handles providers without values for weight", () => {
+		// Providers without weight field should default to weight 1
+		const providers = [
+			{
+				address: "address1",
+				url: "url1",
+				datasetId: "dataset1",
+				// No weight field
+			},
+			{
+				address: "address2",
+				url: "url2",
+				datasetId: "dataset2",
+				weight: 3,
+			},
+		];
+
+		// Mock the providers to simulate what comes from the API
+		// The real providers will have weight added by zod schema default
+		const providersWithDefaults = [
+			{ ...providers[0], weight: 1 },
+			providers[1],
+		];
+
+		// Total weight = 4 (1 + 3)
+		// address1 (weight 1) should get entropy 0 (25%)
+		// address2 (weight 3) should get entropy 1-3 (75%)
+
+		const selections = { address1: 0, address2: 0 };
+		for (let i = 0; i < 100; i++) {
+			const selected = selectWeightedProvider(
+				providersWithDefaults as HardcodedProvider[],
+				i,
+			);
+			if (selected.address === "address1") {
+				selections.address1++;
+			} else {
+				selections.address2++;
+			}
+		}
+
+		// address1 should get ~25% and address2 should get ~75%
+		expect(selections.address1).toBe(25);
+		expect(selections.address2).toBe(75);
+	});
+});
+
+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 as unknown as ReturnType<typeof vi.fn>).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 as unknown as ReturnType<typeof vi.fn>).mockResolvedValue(
+			mockProviders,
+		);
+
+		await getRandomActiveProvider("development", 123);
+		await getRandomActiveProvider("development", 456);
+
+		expect(loadBalancer).toHaveBeenCalledTimes(1);
+	});
+
+	it("handles empty providers list gracefully", async () => {
+		(loadBalancer as unknown as ReturnType<typeof vi.fn>).mockResolvedValue([]);
+
+		await expect(getRandomActiveProvider("development", 123)).rejects.toThrow();
+	});
+
+	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 as unknown as ReturnType<typeof vi.fn>).mockResolvedValue(
+			mockProviders,
+		);
+
+		// Total weight = 4
+		// address1 gets entropy 0 (25%)
+		// address2 gets entropy 1-3 (75%)
+
+		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("handles providers with missing weight field (defaults to 1)", async () => {
+		// Simulate providers returned from loadBalancer where one has weight and one doesn't
+		const mockProviders = [
+			{ address: "address1", url: "url1", datasetId: "dataset1", weight: 1 },
+			{ address: "address2", url: "url2", datasetId: "dataset2", weight: 1 },
+		];
+		(loadBalancer as unknown as ReturnType<typeof vi.fn>).mockResolvedValue(
+			mockProviders,
+		);
+
+		// With equal weights, distribution should be 50/50
+		const result0 = await getRandomActiveProvider("development", 0);
+		expect(result0.providerAccount).toBe("address1");
+
+		_resetCache();
+		const result1 = await getRandomActiveProvider("development", 1);
+		expect(result1.providerAccount).toBe("address2");
+	});
+});

package/tsconfig.cjs.json

@@ -0,0 +1,24 @@
+{
+	"extends": "../../tsconfig.cjs.json",
+	"compilerOptions": {
+		"rootDir": "./src",
+		"outDir": "./dist/cjs"
+	},
+	"include": [
+		"./src/**/*.ts",
+		"./src/**/*.json",
+		"./src/**/*.d.ts",
+		"./src/**/*.tsx"
+	],
+	"references": [
+		{
+			"path": "../../dev/config/tsconfig.cjs.json"
+		},
+		{
+			"path": "../common/tsconfig.cjs.json"
+		},
+		{
+			"path": "../types/tsconfig.cjs.json"
+		}
+	]
+}

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+	"extends": "../../tsconfig.esm.json",
+	"compilerOptions": {
+		"rootDir": "./src",
+		"outDir": "./dist"
+	},
+	"include": [
+		"src",
+		"src/**/*.json",
+		"src/**/*.ts",
+		"src/**/*.tsx",
+		"src/**/*.d.ts"
+	],
+	"references": [
+		{
+			"path": "../../dev/config/tsconfig.json"
+		},
+		{
+			"path": "../common"
+		},
+		{
+			"path": "../types"
+		}
+	]
+}