@prosopo/provider 5.9.0 → 5.10.1

package/dist/cjs/api/healthzGeo.cjs

@@ -0,0 +1,209 @@
+let _prosopo_types = require("@prosopo/types");
+let zod = require("zod");
+//#region src/api/healthzGeo.ts
+/**
+* Geo steering for `/healthz`.
+*
+* `/healthz` tells a client which node to pin its captcha calls to. By default
+* a node answers with its own name, so the pin is whatever the DNS layer
+* picked. With steering enabled the node instead answers with the node the
+* caller's country is mapped to, when that node is known to be up.
+*
+* Off by default. With the flag off nothing here runs: no lookup, no poller,
+* no response header, no counter.
+*
+* Configuration (all read once, at first use):
+*
+*   PROSOPO_HEALTHZ_GEO_STEERING
+*     "true" enables steering. Anything else, including unset, disables it.
+*
+*   PROSOPO_HEALTHZ_GEO_ROUTES
+*     JSON object mapping ISO 3166-1 alpha-2 country code to hostname, e.g.
+*     `{"XX":"node1.example.com","YY":"node2.example.com"}`. Keys are
+*     case-insensitive. Countries absent from the map are not steered.
+*
+*     The map is the candidate set: a host that must not receive traffic
+*     simply does not appear in it. Nothing here derives candidates from
+*     anywhere else, so the deployment that generates the map is the single
+*     place that decides which nodes are in rotation.
+*
+*   PROSOPO_HEALTHZ_GEO_PROBE_INTERVAL_MS   (default 30000)
+*   PROSOPO_HEALTHZ_GEO_PROBE_TIMEOUT_MS    (default 2000)
+*     Background health-probe period and per-probe timeout.
+*
+* An invalid or unparseable route map disables steering rather than failing
+* startup — the fallback is the node's own name, which is the default
+* behaviour.
+*/
+var DEFAULT_PROBE_INTERVAL_MS = 3e4;
+var DEFAULT_PROBE_TIMEOUT_MS = 2e3;
+var MIN_PROBE_INTERVAL_MS = 1e3;
+/** Hostname, not a URL: no scheme, no path, no port. */
+var hostnameSchema = zod.z.string().min(1).max(253).regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/i);
+var routesSchema = zod.z.record(zod.z.string().regex(/^[a-z]{2}$/i), hostnameSchema);
+var parsePositiveInt = (raw, fallback) => {
+	if (raw === void 0) return fallback;
+	const parsed = Number.parseInt(raw, 10);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+var parseRoutes = (raw, logger) => {
+	if (!raw || raw.trim().length === 0) return /* @__PURE__ */ new Map();
+	try {
+		const parsed = routesSchema.parse(JSON.parse(raw));
+		return new Map(Object.entries(parsed).map(([country, host]) => [country.toUpperCase(), host]));
+	} catch (err) {
+		logger?.warn(() => ({
+			msg: "PROSOPO_HEALTHZ_GEO_ROUTES is not a valid country->host map; healthz geo steering stays off",
+			err
+		}));
+		return /* @__PURE__ */ new Map();
+	}
+};
+var readHealthzGeoConfig = (envVars = process.env, logger) => {
+	const routes = parseRoutes(envVars.PROSOPO_HEALTHZ_GEO_ROUTES, logger);
+	return {
+		enabled: envVars.PROSOPO_HEALTHZ_GEO_STEERING === "true" && routes.size > 0,
+		routes,
+		probeIntervalMs: Math.max(MIN_PROBE_INTERVAL_MS, parsePositiveInt(envVars.PROSOPO_HEALTHZ_GEO_PROBE_INTERVAL_MS, DEFAULT_PROBE_INTERVAL_MS)),
+		probeTimeoutMs: parsePositiveInt(envVars.PROSOPO_HEALTHZ_GEO_PROBE_TIMEOUT_MS, DEFAULT_PROBE_TIMEOUT_MS)
+	};
+};
+var fetchHealthzProbe = async (host, timeoutMs) => {
+	try {
+		return (await fetch(`https://${host}${_prosopo_types.PublicApiPaths.Healthz}`, {
+			method: "GET",
+			signal: AbortSignal.timeout(timeoutMs)
+		})).ok;
+	} catch {
+		return false;
+	}
+};
+/**
+* Tracks whether each candidate host is answering, in the background.
+*
+* `/healthz` is served before the request pipeline that would otherwise
+* observe a node's health, so nothing else here knows whether a candidate is
+* reachable. Every host starts `false` and only becomes `true` on a successful
+* probe, so a poller that has not run, cannot run, or is failing leaves every
+* candidate down and steering off — degrading to the default behaviour by
+* construction rather than by a fallback branch.
+*
+* The probe never touches the request path: `isUp()` reads a boolean.
+*/
+var TargetHealthMonitor = class {
+	constructor(options) {
+		this.up = /* @__PURE__ */ new Map();
+		this.hosts = [...new Set(options.hosts)];
+		this.intervalMs = options.intervalMs;
+		this.timeoutMs = options.timeoutMs;
+		this.probe = options.probe ?? fetchHealthzProbe;
+		this.logger = options.logger;
+	}
+	isUp(host) {
+		return this.up.get(host) === true;
+	}
+	start() {
+		if (this.timer !== void 0 || this.hosts.length === 0) return;
+		this.pollAll();
+		this.timer = setInterval(() => {
+			this.pollAll();
+		}, this.intervalMs);
+		this.timer.unref?.();
+	}
+	stop() {
+		if (this.timer !== void 0) {
+			clearInterval(this.timer);
+			this.timer = void 0;
+		}
+	}
+	/** One probe round over every candidate. Exposed so tests can await it. */
+	async pollAll() {
+		await Promise.all(this.hosts.map(async (host) => {
+			let healthy = false;
+			try {
+				healthy = await this.probe(host, this.timeoutMs);
+			} catch {
+				healthy = false;
+			}
+			const previous = this.up.get(host);
+			this.up.set(host, healthy);
+			if (previous !== healthy) this.logger?.info(() => ({
+				msg: "healthz geo target health changed",
+				data: {
+					host,
+					healthy
+				}
+			}));
+		}));
+	}
+};
+/**
+* Picks the host `/healthz` should answer with. Pure apart from reading the
+* monitor's booleans and the memory-mapped country lookup — it never awaits
+* anything, so it cannot delay or fail a health check.
+*/
+var HealthzGeoRouter = class {
+	constructor(config, env, monitor) {
+		this.enabled = config.enabled;
+		this.routes = config.routes;
+		this.ipInfoService = env.ipInfoService;
+		this.monitor = monitor ?? new TargetHealthMonitor({
+			hosts: [...new Set(config.routes.values())],
+			intervalMs: config.probeIntervalMs,
+			timeoutMs: config.probeTimeoutMs,
+			logger: env.logger
+		});
+	}
+	start() {
+		if (this.enabled) this.monitor.start();
+	}
+	stop() {
+		this.monitor.stop();
+	}
+	resolveHost(clientIp, ownHost) {
+		if (!this.enabled) return {
+			host: ownHost,
+			outcome: "not_steered"
+		};
+		if (!clientIp) return {
+			host: ownHost,
+			outcome: "geo_unavailable"
+		};
+		if (!this.ipInfoService.isAvailable()) return {
+			host: ownHost,
+			outcome: "geo_unavailable"
+		};
+		const country = this.ipInfoService.country(clientIp);
+		if (!country) return {
+			host: ownHost,
+			outcome: "geo_unavailable"
+		};
+		const target = this.routes.get(country.toUpperCase());
+		if (target === void 0 || target === ownHost) return {
+			host: ownHost,
+			outcome: "not_steered"
+		};
+		if (!this.monitor.isUp(target)) return {
+			host: ownHost,
+			outcome: "target_down"
+		};
+		return {
+			host: target,
+			outcome: "steered"
+		};
+	}
+};
+var cachedRouter;
+var getHealthzGeoRouter = (env) => {
+	if (!cachedRouter) {
+		cachedRouter = new HealthzGeoRouter(readHealthzGeoConfig(process.env, env.logger), env);
+		cachedRouter.start();
+	}
+	return cachedRouter;
+};
+//#endregion
+exports.HealthzGeoRouter = HealthzGeoRouter;
+exports.TargetHealthMonitor = TargetHealthMonitor;
+exports.fetchHealthzProbe = fetchHealthzProbe;
+exports.getHealthzGeoRouter = getHealthzGeoRouter;
+exports.readHealthzGeoConfig = readHealthzGeoConfig;

package/dist/cjs/api/metrics.cjs

@@ -154,6 +154,12 @@ var buildMetrics = () => {
 			help: "1 when the given redis connection is ready, else 0",
 			labelNames: ["actor"],
 			registers: [registry]
+		}),
+		healthzGeoOutcomesTotal: new prom_client.Counter({
+			name: `${PREFIX}healthz_geo_outcomes_total`,
+			help: "Healthz geo steering outcomes (steered/not_steered/target_down/geo_unavailable)",
+			labelNames: ["outcome"],
+			registers: [registry]
 		})
 	};
 };
@@ -202,6 +208,10 @@ var recordSpamEmail = (result) => {
 	if (!metricsEnabled()) return;
 	getMetrics().spamEmailTotal.inc({ result });
 };
+var recordHealthzGeoOutcome = (outcome) => {
+	if (!metricsEnabled()) return;
+	getMetrics().healthzGeoOutcomesTotal.inc({ outcome });
+};
 var setMaintenanceModeGauge = (on) => {
 	if (!metricsEnabled()) return;
 	getMetrics().maintenanceMode.set(on ? 1 : 0);
@@ -257,5 +267,6 @@ exports.recordCaptchaVerify = recordCaptchaVerify;
 exports.recordDetectorTriggered = recordDetectorTriggered;
 exports.recordDomainValidation = recordDomainValidation;
 exports.recordFrictionlessDecision = recordFrictionlessDecision;
+exports.recordHealthzGeoOutcome = recordHealthzGeoOutcome;
 exports.recordSpamEmail = recordSpamEmail;
 exports.setMaintenanceModeGauge = setMaintenanceModeGauge;

package/dist/cjs/api/public.cjs

@@ -1,5 +1,6 @@
 const require_runtime = require("../_virtual/_rolldown/runtime.cjs");
 const require_metrics = require("./metrics.cjs");
+const require_healthzGeo = require("./healthzGeo.cjs");
 let _prosopo_common = require("@prosopo/common");
 let _prosopo_types = require("@prosopo/types");
 let _prosopo_util = require("@prosopo/util");
@@ -14,11 +15,19 @@ express = require_runtime.__toESM(express, 1);
 */
 function publicRouter(env) {
 	const router = express.default.Router();
+	const geo = require_healthzGeo.getHealthzGeoRouter(env);
 	router.get(_prosopo_types.PublicApiPaths.Healthz, (req, res) => {
-		const host = env.config.host && env.config.host.length > 0 ? env.config.host : req.hostname;
+		const ownHost = env.config.host && env.config.host.length > 0 ? env.config.host : req.hostname;
+		if (!geo.enabled) return res.status(200).json({
+			ok: true,
+			host: ownHost
+		});
+		res.set("Cache-Control", "no-store, private");
+		const decision = geo.resolveHost(req.ip, ownHost);
+		require_metrics.recordHealthzGeoOutcome(decision.outcome);
 		return res.status(200).json({
 			ok: true,
-			host
+			host: decision.host
 		});
 	});
 	if (require_metrics.metricsEnabled()) router.get(_prosopo_types.PublicApiPaths.Metrics, require_metrics.metricsHandler(env));
@@ -30,9 +39,11 @@ function publicRouter(env) {
 			const db = env.getDb();
 			const redisConnection = db.getRedisConnection();
 			const redisAccessRulesConnection = db.getRedisAccessRulesConnection();
+			const host = env.config.host && env.config.host.length > 0 ? env.config.host : req.hostname;
 			const response = {
 				version: _prosopo_util.version,
 				message: "Provider online",
+				host,
 				redis: [{
 					actor: "General",
 					isReady: redisConnection.isReady(),

package/dist/cjs/services/ipComparison.cjs

@@ -100,7 +100,8 @@ async function compareIPs(ip1, ip2, ipInfoService) {
 					country: ip1Info.country,
 					countryCode: ip1Info.countryCode,
 					city: ip1Info.city,
-					coordinates: ip1Coordinates
+					coordinates: ip1Coordinates,
+					abuserScore: ip1Info.abuserScore
 				},
 				ip2Details: {
 					provider: ip2Provider,
@@ -109,7 +110,8 @@ async function compareIPs(ip1, ip2, ipInfoService) {
 					country: ip2Info.country,
 					countryCode: ip2Info.countryCode,
 					city: ip2Info.city,
-					coordinates: ip2Coordinates
+					coordinates: ip2Coordinates,
+					abuserScore: ip2Info.abuserScore
 				}
 			}
 		};