@prosopo/ipinfo 0.3.24 → 0.4.0

package/dist/types.d.ts

@@ -3,6 +3,7 @@ import type { IPInfoResponse } from "@prosopo/types";
 export interface IIpInfoService {
     initialize(): Promise<void>;
     lookup(ip: string): Promise<IPInfoResponse>;
+    country(ip: string): string | undefined;
     isAvailable(): boolean;
 }
 export interface IpInfoServiceConfig {

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,MAAM,WAAW,cAAc;IAC9B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5C,WAAW,IAAI,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IACnC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,MAAM,WAAW,cAAc;IAC9B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAM5C,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACxC,WAAW,IAAI,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IACnC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@prosopo/ipinfo",
-	"version": "0.3.24",
+	"version": "0.4.0",
 	"description": "IP information service with MaxMind and ipapi.is backends",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -29,10 +29,10 @@
 	"dependencies": {
 		"@maxmind/geoip2-node": "7.1.0",
 		"@prosopo/logger": "2.0.9",
-		"@prosopo/types": "5.7.0"
+		"@prosopo/types": "5.8.1"
 	},
 	"devDependencies": {
-		"@prosopo/config": "3.3.14",
+		"@prosopo/config": "3.3.15",
 		"@types/node": "22.10.2",
 		"@vitest/coverage-v8": "4.1.11",
 		"del-cli": "6.0.0",

package/src/IpInfoService.ts

@@ -117,6 +117,27 @@ export class IpInfoService implements IIpInfoService {
 		);
 	}
 
+	/**
+	 * MaxMind-only country fast path: the ISO 3166-1 alpha-2 code for `ip`, or
+	 * undefined when it cannot be determined.
+	 *
+	 * Deliberately NOT `lookup()`. `lookup()` prefers ipapi.is for its threat
+	 * data, which puts a network call to the sidecar on the caller's path; a
+	 * caller that only wants a country does not need that data and must not pay
+	 * for it. The MaxMind database is memory-mapped and read in-process, so this
+	 * is synchronous and cannot fail on a network or a slow sidecar.
+	 *
+	 * Returns undefined rather than throwing for every failure mode — no
+	 * MaxMind backend configured, backend not initialised yet, non-routable
+	 * address, address absent from the database — so callers have exactly one
+	 * "no answer" case to handle.
+	 */
+	country(ip: string): string | undefined {
+		if (isNonRoutable(ip)) return undefined;
+		if (!this.maxmindBackend?.isAvailable()) return undefined;
+		return this.maxmindBackend.countryCode(ip);
+	}
+
 	async lookup(ip: string): Promise<IPInfoResponse> {
 		if (isNonRoutable(ip)) {
 			return {

package/src/backends/maxmind.ts

@@ -109,6 +109,42 @@ export class MaxMindBackend {
 		return this.cityReader !== null || this.asnReader !== null;
 	}
 
+	/**
+	 * ISO 3166-1 alpha-2 country code, or undefined when the reader has no
+	 * answer. Synchronous and allocation-light: the .mmdb is memory-mapped, so
+	 * this is a tree walk with no I/O and no network.
+	 *
+	 * Separate from `lookup()` because callers that only need the country
+	 * should not pay for the ASN read, the threat-field assembly, or the
+	 * `IPInfoResponse` object. The reader-kind latch is shared with `lookup()`
+	 * — `country()` rejects a City database and `city()` rejects a Country one,
+	 * so the accessor has to be chosen from the database's own metadata.
+	 */
+	countryCode(ip: string): string | undefined {
+		if (!this.cityReader) return undefined;
+
+		if (this.geoReaderKind !== "country") {
+			try {
+				const isoCode = this.cityReader.city(ip).country?.isoCode;
+				this.geoReaderKind = "city";
+				return isoCode;
+			} catch (error) {
+				if (!isBadMethodCall(error)) {
+					// Address not in the database, or an invalid address: no
+					// country, and nothing to latch.
+					return undefined;
+				}
+				this.geoReaderKind = "country";
+			}
+		}
+
+		try {
+			return this.cityReader.country(ip).country?.isoCode;
+		} catch {
+			return undefined;
+		}
+	}
+
 	async lookup(ip: string): Promise<IPInfoResponse> {
 		if (!this.isAvailable()) {
 			return {

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

@@ -55,15 +55,18 @@ interface StubBackend {
 	initialize: () => Promise<void>;
 	isAvailable: () => boolean;
 	lookup: (ip: string) => Promise<IPInfoResponse>;
+	countryCode: (ip: string) => string | undefined;
 }
 
 const stub = (
 	available: boolean,
 	answer: IPInfoResponse = result("stub"),
+	countryCode: string | undefined = "US",
 ): StubBackend => ({
 	initialize: vi.fn<() => Promise<void>>(async () => {}),
 	isAvailable: vi.fn<() => boolean>(() => available),
 	lookup: vi.fn<(ip: string) => Promise<IPInfoResponse>>(async () => answer),
+	countryCode: vi.fn<(ip: string) => string | undefined>(() => countryCode),
 });
 
 /**
@@ -410,6 +413,7 @@ describe("IpInfoService.lookup", () => {
 			lookup: vi.fn<(ip: string) => Promise<IPInfoResponse>>(async () =>
 				result("recovered"),
 			),
+			countryCode: vi.fn<(ip: string) => string | undefined>(() => undefined),
 		};
 		const svc = service({ ipapi: flaky });
 
@@ -420,3 +424,58 @@ describe("IpInfoService.lookup", () => {
 		expect(await svc.lookup(IP)).toEqual(result("recovered"));
 	});
 });
+
+describe("IpInfoService.country", () => {
+	it("answers from MaxMind", () => {
+		expect(
+			service({ maxmind: stub(true, result("maxmind"), "GB") }).country(IP),
+		).toBe("GB");
+	});
+
+	it("never consults ipapi, even when ipapi is the preferred backend", () => {
+		// `lookup()` prefers ipapi for its threat data, which costs a call to
+		// the sidecar. A country lookup does not need that data and must not
+		// pay for it.
+		const ipapi = stub(true, result("ipapi"));
+		const maxmind = stub(true, result("maxmind"), "FR");
+
+		expect(service({ maxmind, ipapi }).country(IP)).toBe("FR");
+
+		expect(ipapi.lookup).not.toHaveBeenCalled();
+		expect(ipapi.isAvailable).not.toHaveBeenCalled();
+	});
+
+	it("has no answer for a loopback caller, without reading the database", () => {
+		// Deploy gates and container health checks call over loopback; they
+		// must cost nothing and must never resolve to a country.
+		const maxmind = stub(true, result("maxmind"), "US");
+
+		expect(service({ maxmind }).country("127.0.0.1")).toBeUndefined();
+		expect(service({ maxmind }).country("::1")).toBeUndefined();
+		expect(service({ maxmind }).country("10.1.2.3")).toBeUndefined();
+
+		expect(maxmind.countryCode).not.toHaveBeenCalled();
+	});
+
+	it("has no answer when no MaxMind backend is configured", () => {
+		expect(service({ ipapi: stub(true) }).country(IP)).toBeUndefined();
+	});
+
+	it("has no answer while MaxMind is still unavailable", () => {
+		// Availability is false until the environment finishes becoming ready,
+		// which is exactly when a caller that cannot await readiness asks.
+		const maxmind = stub(false, result("maxmind"), "DE");
+
+		expect(service({ maxmind }).country(IP)).toBeUndefined();
+		expect(maxmind.countryCode).not.toHaveBeenCalled();
+	});
+
+	it("has no answer when the address is absent from the database", () => {
+		const maxmind: StubBackend = {
+			...stub(true, result("maxmind")),
+			countryCode: vi.fn<(ip: string) => string | undefined>(() => undefined),
+		};
+
+		expect(service({ maxmind }).country(IP)).toBeUndefined();
+	});
+});

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

@@ -726,3 +726,76 @@ describe("MaxMindBackend default reader", () => {
 		expect(backend.isAvailable()).toBe(false);
 	});
 });
+
+describe("MaxMindBackend.countryCode", () => {
+	it("reads the country from a City database", async () => {
+		const backend = new MaxMindBackend({
+			cityDbPath: CITY_DB,
+			openReader: opens({ city: reader({ city: () => cityData() }) }),
+		});
+		await backend.initialize();
+
+		expect(backend.countryCode(IP)).toBe("US");
+	});
+
+	it("falls back to country() on a Country database and latches the choice", async () => {
+		const city = vi.fn(badMethodCall);
+		const country = vi.fn((): Country => countryData());
+		const backend = new MaxMindBackend({
+			cityDbPath: CITY_DB,
+			openReader: opens({ city: reader({ city, country }) }),
+		});
+		await backend.initialize();
+
+		expect(backend.countryCode(IP)).toBe("US");
+		expect(backend.countryCode(IP)).toBe("US");
+
+		// The mismatched accessor is tried once, not once per call.
+		expect(city).toHaveBeenCalledTimes(1);
+		expect(country).toHaveBeenCalledTimes(2);
+	});
+
+	it("has no answer when the address is absent from the database", async () => {
+		const backend = new MaxMindBackend({
+			cityDbPath: CITY_DB,
+			openReader: opens({
+				city: reader({
+					city: (): never => {
+						throw new Error("The address 8.8.8.8 is not in the database");
+					},
+				}),
+			}),
+		});
+		await backend.initialize();
+
+		expect(backend.countryCode(IP)).toBeUndefined();
+	});
+
+	it("has no answer when no geo database was opened", async () => {
+		const backend = new MaxMindBackend({
+			asnDbPath: ASN_DB,
+			openReader: opens({ asn: reader({ asn: () => asnData() }) }),
+		});
+		await backend.initialize();
+
+		expect(backend.isAvailable()).toBe(true);
+		expect(backend.countryCode(IP)).toBeUndefined();
+	});
+
+	it("does not read the ASN database", async () => {
+		// The country is the whole answer; nothing else is worth a second read.
+		const asn = vi.fn((): Asn => asnData());
+		const backend = new MaxMindBackend({
+			cityDbPath: CITY_DB,
+			asnDbPath: ASN_DB,
+			openReader: opens({
+				city: reader({ city: () => cityData() }),
+				asn: reader({ asn }),
+			}),
+		});
+		await backend.initialize();
+
+		expect(backend.countryCode(IP)).toBe("US");
+		expect(asn).not.toHaveBeenCalled();
+	});
+});

package/src/types.ts

@@ -18,6 +18,12 @@ import type { IPInfoResponse } from "@prosopo/types";
 export interface IIpInfoService {
 	initialize(): Promise<void>;
 	lookup(ip: string): Promise<IPInfoResponse>;
+	/**
+	 * ISO 3166-1 alpha-2 country code from the local MaxMind database only.
+	 * Synchronous and network-free, unlike `lookup()`. Undefined whenever no
+	 * answer is available.
+	 */
+	country(ip: string): string | undefined;
 	isAvailable(): boolean;
 }