Skip to content

A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source and free forever. Try it out today!

35.4 KB
Raw Blame
import type { WebAccessConnection, WebAccessProvider } from "./contracts";
import type { LookupFunction } from "node:net";
import { lookup as socketLookup } from "node:dns";
import { lookup } from "node:dns/promises";
import { EventEmitter } from "node:events";
import { createServer } from "node:http";
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vite-plus/test";
import { searchJobPostings } from "../applications/posting";
import { probeWebAccess, readPage, searchWeb } from "./service";

const fixtures = vi.hoisted(() => ({
	limit: vi.fn(async () => ({ success: true })),
	direct: vi.fn(),
	directHtml: "<h1>Direct posting</h1><p>Work on accessible products.</p>",
	directLocation: "",
	directDelay: 0,
	directContentType: "text/html",
	env: { FLAG_DISABLE_API_RATE_LIMIT: false } as {
		FLAG_DISABLE_API_RATE_LIMIT: boolean;
		WEB_SEARCH_SEARXNG_URL?: string;
	},
}));
vi.mock("../../redis", () => ({
	createRateLimiter: () => ({ limit: fixtures.limit }),
}));
vi.mock("@reactive-resume/env/server", () => ({ env: fixtures.env }));
vi.mock("node:dns/promises", () => ({ lookup: vi.fn() }));
vi.mock("node:dns", () => ({ lookup: vi.fn() }));
vi.mock("node:https", async (original) => ({
	...(await original<typeof import("node:https")>()),
	request: (
		url: URL,
		options: { signal: AbortSignal; agent: { options: { lookup: LookupFunction } } },
		callback: (response: EventEmitter) => void,
	) => {
		fixtures.direct(url.toString());
		const request = new EventEmitter();
		let timer: ReturnType<typeof setTimeout> | undefined;
		const aborted = () => request.emit("error", options.signal.reason);
		const req = Object.assign(request, {
			destroy: (error: Error) => request.emit("error", error),
			end: () => {
				options.signal.addEventListener("abort", aborted, { once: true });
				options.agent.options.lookup(url.hostname, { all: true }, (error) => {
					if (error) return req.destroy(error);
					const send = () => {
						const response = Object.assign(new EventEmitter(), {
							statusCode: fixtures.directLocation ? 302 : 200,
							headers: {
								"content-type": fixtures.directContentType,
								location: fixtures.directLocation || undefined,
							},
							resume: () => {},
						});
						callback(response);
						response.emit("data", Buffer.from(fixtures.directHtml));
						response.emit("end");
						options.signal.removeEventListener("abort", aborted);
					};
					if (fixtures.directDelay) timer = setTimeout(send, fixtures.directDelay);
					else send();
				});
			},
		});
		request.on("error", () => {
			if (timer) clearTimeout(timer);
			options.signal.removeEventListener("abort", aborted);
		});
		return req;
	},
}));

const PROVIDERS = ["firecrawl", "tavily", "exa"] as const;
const URL = "https://jobs.example.com/role";
const nativeFetch = globalThis.fetch;
const nativeTimeout = AbortSignal.timeout;
let endpoint: string;
let status = 200;
let responseOverride: unknown;
let delay = 0;
let searchStatus: number | undefined;
let onRequest: (() => void) | undefined;
let respond:
	| ((request: { provider: string; body: Record<string, unknown> }) => { status?: number; body?: unknown } | undefined)
	| undefined;
const requests: {
	provider: string;
	operation: string;
	method: string | undefined;
	url: string;
	body: Record<string, unknown>;
	raw: string;
	auth: string | undefined;
}[] = [];

const searchResponse = (provider: WebAccessProvider) => {
	const unsafe = [
		{ url: "https://localhost/private", title: "Private" },
		{ url: "javascript:alert(1)", title: "Script" },
		{ url: "http://jobs.example.com/insecure", title: "HTTP" },
		{ url: "https://jobs.example.com/missing-title" },
	];
	if (provider === "firecrawl")
		return {
			success: true,
			data: {
				web: [{ url: `${URL}#apply`, title: "Designer", description: "Berlin" }, ...unsafe],
			},
		};
	if (provider === "tavily")
		return {
			results: [{ url: `${URL}#apply`, title: "Designer", content: "Berlin" }, ...unsafe],
		};
	return { results: [{ url: `${URL}#apply`, title: "Designer" }, ...unsafe] };
};
const readResponse = (provider: WebAccessProvider, content = "# Designer\nAccessible product design") => {
	if (provider === "firecrawl")
		return {
			success: true,
			data: { markdown: content, metadata: { url: URL, cachedAt: "2026-09-29T12:00:00Z" } },
		};
	if (provider === "tavily")
		return {
			results: [{ url: URL, raw_content: content }],
			failed_results: [],
		};
	return {
		results: [{ url: URL, text: content, crawlDate: "2026-09-29T12:00:00Z" }],
		statuses: [{ id: URL, status: "success" }],
	};
};

const server = createServer(async (request, result) => {
	const chunks: Buffer[] = [];
	for await (const chunk of request) chunks.push(chunk);
	const parts = (request.url ?? "").split("?", 1)[0]?.split("/") ?? [];
	const provider = (parts[1] === "v2" ? "firecrawl" : parts[1]) as WebAccessProvider;
	const operation = parts[2] === "search" ? "search" : "read";
	const raw = Buffer.concat(chunks).toString();
	const body = (raw ? JSON.parse(raw) : {}) as Record<string, unknown>;
	requests.push({
		provider,
		operation,
		method: request.method,
		url: request.url ?? "",
		body,
		raw,
		auth: request.headers.authorization ?? (request.headers["x-api-key"] as string | undefined),
	});
	onRequest?.();
	if (delay) await new Promise((resolve) => setTimeout(resolve, delay));
	if (result.destroyed) return;
	const custom = respond?.({ provider, body });
	result.writeHead(custom?.status ?? (operation === "search" && searchStatus !== undefined ? searchStatus : status), {
		"content-type": "application/json",
	});
	result.end(
		JSON.stringify(
			custom?.body ?? responseOverride ?? (operation === "search" ? searchResponse(provider) : readResponse(provider)),
		),
	);
});

/** Today's search body for "designer", which a search with no regions must send byte for byte. */
const plainSearchBody = (provider: WebAccessProvider) =>
	provider === "firecrawl"
		? { query: "designer", sources: ["web"], limit: 5, timeout: 14_000, integration: "_reactive-resume" }
		: provider === "tavily"
			? {
					query: "designer",
					max_results: 5,
					search_depth: "basic",
					include_answer: false,
					include_raw_content: false,
				}
			: { query: "designer", numResults: 5, type: "auto" };
const TAVILY_COUNTRIES: Record<string, string> = { AU: "australia", DE: "germany", FR: "france" };
/** The provider's location field and the value it carries for a country code. */
const regionField = (provider: WebAccessProvider, code: string): [string, string] =>
	provider === "exa"
		? ["userLocation", code]
		: ["country", provider === "tavily" ? (TAVILY_COUNTRIES[code] ?? "") : code];
const regionOf = (provider: WebAccessProvider, body: Record<string, unknown>) =>
	Object.keys(TAVILY_COUNTRIES).find((code) => {
		const [field, value] = regionField(provider, code);
		return body[field] === value;
	});
const resultsFor = (provider: WebAccessProvider, items: { url: string; title: string }[]) =>
	provider === "firecrawl" ? { success: true, data: { web: items } } : { results: items };
const job = (path: string) => ({ url: `https://jobs.example.com/${path}`, title: path });

const connection = (provider: WebAccessProvider): WebAccessConnection => ({
	provider,
	apiKey: "test-provider-key",
	...(provider === "firecrawl" ? { apiUrl: endpoint } : {}),
});
const context = (provider: WebAccessProvider) => ({
	userId: "user",
	connection: connection(provider),
});

beforeAll(async () => {
	await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
	const address = server.address();
	if (!address || typeof address === "string") throw new Error("Missing fixture server");
	endpoint = `http://127.0.0.1:${address.port}`;
});
afterAll(async () => {
	server.closeAllConnections();
	await new Promise<void>((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())));
});
beforeEach(() => {
	vi.stubEnv("NODE_ENV", "test");
	vi.stubGlobal("fetch", (input: string | URL | Request, options?: RequestInit) => {
		const url = new globalThis.URL(input instanceof Request ? input.url : input.toString());
		if (url.origin === endpoint) return nativeFetch(input, options);
		const provider = url.hostname === "api.tavily.com" ? "tavily" : "exa";
		return nativeFetch(`${endpoint}/${provider}${url.pathname}`, options);
	});
	vi.mocked(lookup).mockResolvedValue([{ address: "93.184.216.34", family: 4 }] as never);
	vi.mocked(socketLookup).mockImplementation(((
		_hostname: string,
		_options: unknown,
		callback: (error: Error | null, addresses: unknown) => void,
	) => callback(null, [{ address: "93.184.216.34", family: 4 }])) as never);
	vi.spyOn(console, "info").mockImplementation(() => {});
	requests.length = 0;
	status = 200;
	searchStatus = undefined;
	onRequest = undefined;
	respond = undefined;
	responseOverride = undefined;
	delay = 0;
	fixtures.limit.mockClear();
	fixtures.limit.mockResolvedValue({ success: true });
	fixtures.direct.mockClear();
	fixtures.directHtml = "<h1>Direct posting</h1><p>Work on accessible products.</p>";
	fixtures.directLocation = "";
	fixtures.directDelay = 0;
	fixtures.directContentType = "text/html";
	delete fixtures.env.WEB_SEARCH_SEARXNG_URL;
});
afterEach(() => {
	vi.restoreAllMocks();
	vi.unstubAllGlobals();
	vi.unstubAllEnvs();
});

describe.each(PROVIDERS)("%s adapter at shared boundary", (provider) => {
	it("retains a legitimate security posting mentioning access challenges", async () => {
		const content = "# Security engineer\nDesign access denied screens and captcha challenge flows.";
		responseOverride = readResponse(provider, content);
		expect(await readPage(URL, context(provider))).toMatchObject({
			content,
			method: provider,
			completeness: "unknown",
		});
		expect(fixtures.direct).not.toHaveBeenCalled();
	});
	it("maps bounded search results, filters unsafe links, and retains the original generic query", async () => {
		const results = await searchWeb("Lumen Health company", context(provider));
		expect(results).toEqual([
			{
				url: URL,
				title: "Designer",
				...(provider !== "exa" ? { snippet: "Berlin" } : {}),
			},
		]);
		expect(requests[0]?.body.query).toBe("Lumen Health company");
		expect(requests[0]?.auth).toContain("test-provider-key");
		expect(requests[0]?.body).not.toHaveProperty("scrapeOptions");
		expect(requests[0]?.body).not.toHaveProperty("contents");
		if (provider === "tavily")
			expect(requests[0]?.body).toMatchObject({
				include_raw_content: false,
				include_answer: false,
			});
	});

	it("reads page content with truthful source metadata and explicit truncation", async () => {
		responseOverride = readResponse(provider, "x".repeat(20_001));
		const result = await readPage(`${URL}#apply`, context(provider));
		expect(result).toMatchObject({
			requestedUrl: URL,
			resolvedUrl: URL,
			method: provider,
			truncated: true,
			completeness: "incomplete",
		});
		expect(result.content).toHaveLength(20_000);
		expect(result.retrievedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
		if (provider === "firecrawl") {
			expect(result.providerFetchedAt).toBe("2026-09-29T12:00:00Z");
			expect(requests[0]?.body).toMatchObject({ integration: "_reactive-resume" });
		} else if (provider === "exa") {
			expect(result.providerFetchedAt).toBe("2026-09-29T12:00:00Z");
			expect(requests[0]?.body).toMatchObject({
				text: { maxCharacters: 20_001 },
				maxAgeHours: 0,
			});
			expect(requests[0]?.body).not.toHaveProperty("livecrawl");
		} else expect(result.providerFetchedAt).toBeUndefined();
		if (provider === "tavily") {
			expect(requests[0]?.body).toMatchObject({ format: "markdown" });
			expect(requests[0]?.body).not.toHaveProperty("query");
			expect(requests[0]?.body).not.toHaveProperty("chunks_per_source");
		}
	});

	it.each([
		[401, "auth"],
		[402, "quota"],
		[429, "rate-limit"],
		[503, "unreachable"],
	] as const)("returns safe search failure for HTTP %i", async (httpStatus, reason) => {
		status = httpStatus;
		responseOverride = {
			error: "test-provider-key should never appear in public errors",
		};
		const failure = await searchWeb("designer", context(provider)).catch((error: Error) => error);
		expect(failure).toMatchObject({ reason });
		expect(failure).toHaveProperty("message", expect.not.stringContaining("test-provider-key"));
		expect(fixtures.direct).not.toHaveBeenCalled();
	});

	it.each(["auth", "quota", "rate-limit", "malformed", "empty", "challenge", "too-large", "per-url"])(
		"falls back once after %s read failure",
		async (failure) => {
			if (failure === "auth") status = 401;
			if (failure === "quota") status = 402;
			if (failure === "rate-limit") status = 429;
			if (failure === "malformed") responseOverride = { unexpected: true };
			if (failure === "empty") responseOverride = readResponse(provider, " ");
			if (failure === "challenge") responseOverride = readResponse(provider, "Just a moment. Verify you are human");
			if (failure === "too-large") responseOverride = readResponse(provider, "x".repeat(2_000_001));
			if (failure === "per-url") {
				if (provider === "firecrawl")
					responseOverride = {
						success: true,
						data: {
							markdown: "Bad cached response",
							metadata: { statusCode: 403 },
						},
					};
				if (provider === "tavily")
					responseOverride = {
						...(readResponse(provider) as object),
						failed_results: [{ url: URL, error: "Not available" }],
					};
				if (provider === "exa")
					responseOverride = {
						...(readResponse(provider) as object),
						statuses: [{ id: URL, status: "error", error: { tag: "CRAWL_TIMEOUT" } }],
					};
			}
			expect(await readPage(URL, context(provider))).toMatchObject({
				method: "builtin",
				content: "Direct posting\nWork on accessible products.",
				fallbackReason: expect.any(String),
				completeness: "unknown",
			});
			expect(fixtures.direct).toHaveBeenCalledTimes(1);
			expect(requests.every((request) => request.provider === provider)).toBe(true);
		},
	);

	it("bounds provider responses before parsing", async () => {
		responseOverride = { unexpected: "x".repeat(2_000_001) };
		await expect(searchWeb("designer", context(provider))).rejects.toMatchObject({ reason: "too-large" });
	});

	it("rejects malformed search responses but accepts a valid empty result list", async () => {
		responseOverride = { unexpected: true };
		await expect(searchWeb("designer", context(provider))).rejects.toMatchObject({ reason: "malformed" });
		responseOverride = provider === "firecrawl" ? { success: true, data: { web: [] } } : { results: [] };
		expect(await searchWeb("designer", context(provider))).toEqual([]);
	});

	it.each(["search", "read"] as const)(
		"cancels an outstanding %s request and never starts a fallback",
		async (operation) => {
			delay = 150;
			const controller = new AbortController();
			const started = new Promise<void>((resolve) => {
				onRequest = resolve;
			});
			const call =
				operation === "search"
					? searchWeb("designer", {
							...context(provider),
							signal: controller.signal,
						})
					: readPage(URL, { ...context(provider), signal: controller.signal });
			const assertion = expect(call).rejects.toMatchObject({
				name: "AbortError",
			});
			await started;
			controller.abort();
			await assertion;
			expect(fixtures.direct).not.toHaveBeenCalled();
		},
	);

	it("reports timeout safely without extending the overall deadline", async () => {
		delay = 150;
		await expect(
			searchWeb("designer", {
				...context(provider),
				signal: nativeTimeout(25),
			}),
		).rejects.toMatchObject({
			reason: "timeout",
		});
		expect(fixtures.direct).not.toHaveBeenCalled();
	});

	it("sends the region in the provider's location field", async () => {
		await searchWeb("designer", { ...context(provider), regions: ["AU"] });
		expect(requests).toHaveLength(1);
		const [field, value] = regionField(provider, "AU");
		expect(requests[0]?.body).toEqual({ ...plainSearchBody(provider), [field]: value });
	});

	it.each<[string[] | undefined]>([[[]], [undefined]])("sends today's exact body with regions %j", async (regions) => {
		await searchWeb(
			"designer",
			{
				...context(provider),
				...(regions ? { regions } : {}),
			},
			(region) => `designer in ${region}`,
		);
		expect(requests).toHaveLength(1);
		expect(requests[0]?.raw).toBe(JSON.stringify(plainSearchBody(provider)));
	});

	it("searches each region and interleaves deduplicated results in region order, capped at five", async () => {
		respond = ({ body }) => {
			const region = regionOf(provider, body);
			if (region === "DE") return { body: resultsFor(provider, [job("DE1"), job("DE2"), job("shared"), job("DE3")]) };
			if (region === "FR") return { body: resultsFor(provider, [job("FR1"), job("shared"), job("FR2"), job("FR3")]) };
			return { status: 400 };
		};
		const results = await searchWeb("designer", { ...context(provider), regions: ["DE", "FR"] });
		expect(requests).toHaveLength(2);
		expect(results.map((result) => result.title)).toEqual(["DE1", "FR1", "DE2", "shared", "FR2"]);
		expect(console.info).toHaveBeenCalledWith("[web-access]", {
			provider,
			operation: "search",
			durationMs: expect.any(Number),
			outcome: "success",
		});
	});

	it.each<[string[], string]>([
		[["DE", "FR"], "1/2-regions-failed"],
		[["DE", "FR", "AU"], "2/3-regions-failed"],
	])("keeps available results and logs regional failures for %j", async (regions, fallback) => {
		respond = ({ body }) =>
			regionOf(provider, body) === "FR" ? { body: resultsFor(provider, [job("FR1"), job("FR2")]) } : { status: 500 };
		const results = await searchWeb("designer", { ...context(provider), regions });
		expect(requests).toHaveLength(regions.length);
		expect(results.map((result) => result.title)).toEqual(["FR1", "FR2"]);
		expect(console.info).toHaveBeenCalledWith("[web-access]", {
			provider,
			operation: "search",
			durationMs: expect.any(Number),
			outcome: "success",
			fallback,
		});
	});

	it("throws the existing failure when every region's request fails", async () => {
		status = 429;
		await expect(searchWeb("designer", { ...context(provider), regions: ["DE", "FR"] })).rejects.toMatchObject({
			reason: "rate-limit",
		});
		expect(requests).toHaveLength(2);
	});

	it("rate-limits a multi-region search once", async () => {
		vi.stubEnv("NODE_ENV", "production");
		await searchWeb("designer", { ...context(provider), regions: ["DE", "FR", "AU"] });
		expect(requests).toHaveLength(3);
		expect(fixtures.limit).toHaveBeenCalledTimes(1);
	});

	it("sends each region the query built for it", async () => {
		await searchWeb("designer", { ...context(provider), regions: ["DE", "FR"] }, (region) => `designer in ${region}`);
		expect(
			Object.fromEntries(requests.map((request) => [regionOf(provider, request.body), request.body.query])),
		).toEqual({ DE: "designer in DE", FR: "designer in FR" });
	});

	it("probes provider operations independently and never validates through fallback", async () => {
		searchStatus = 429;
		const result = await probeWebAccess(connection(provider), {
			userId: "user",
		});
		expect(result).toEqual({
			search: { success: false, error: "rate-limit" },
			read: { success: true },
		});
		expect(fixtures.direct).not.toHaveBeenCalled();
	});
});

describe("Tavily country names", () => {
	it.each([
		["CZ", "czech republic"],
		["SG", "singapore"],
		["HK", undefined],
	])("sends %s as Tavily's listed name %j, or no country when Tavily lists none", async (code, country) => {
		await searchWeb("designer", { ...context("tavily"), regions: [code] });
		expect(requests[0]?.body.country).toBe(country);
		if (!country) expect(requests[0]?.body).not.toHaveProperty("country");
	});
});

describe("posting search names the user's country", () => {
	const postingQuery = async (
		query: string,
		scope: { regions: string[]; locale?: string; locations?: string[] },
	): Promise<unknown> => {
		await searchJobPostings(query, { ...context("tavily"), ...scope });
		expect(requests).toHaveLength(Math.max(scope.regions.length, 1));
		return requests[0]?.body.query;
	};

	it("adds the region's country in the user's locale", async () => {
		expect(await postingQuery("designer", { regions: ["AU"], locale: "en-US", locations: [] })).toBe(
			"designer in Australia job posting",
		);
	});
	it("writes the country in the user's UI language", async () => {
		expect(await postingQuery("designer", { regions: ["FR"], locale: "de-DE" })).toBe(
			"designer in Frankreich job posting",
		);
	});
	it("names the country in English when there is no locale", async () => {
		expect(await postingQuery("designer", { regions: ["DE"] })).toBe("designer in Germany job posting");
	});
	it("names each region's own country", async () => {
		await searchJobPostings("designer", { ...context("tavily"), regions: ["DE", "FR"], locale: "en" });
		expect(
			Object.fromEntries(requests.map((request) => [regionOf("tavily", request.body), request.body.query])),
		).toEqual({ DE: "designer in Germany job posting", FR: "designer in France job posting" });
	});
	it.each<[string, { regions: string[]; locale?: string; locations?: string[] }]>([
		["designer berlin", { regions: ["DE"], locations: ["Berlin"] }],
		["designer Frankreich", { regions: ["FR"], locale: "de-DE" }],
		["designer in france", { regions: ["FR"], locale: "de-DE" }],
		["remote designer", { regions: ["AU"] }],
		["designer REMOTE", { regions: ["AU"] }],
		["designer", { regions: ["AU"], locations: ["Remote"] }],
	])("adds nothing to %j when it names a place or remote work", async (query, scope) => {
		expect(await postingQuery(query, scope)).toBe(`${query} job posting`);
	});
	it("sends the query unchanged when the country would pass the length limit", async () => {
		const query = "x".repeat(500);
		expect(await postingQuery(query, { regions: ["AU"], locale: "en" })).toBe(`${query} job posting`);
	});
	it("keeps today's query with no regions", async () => {
		expect(await postingQuery("designer", { regions: [], locale: "en", locations: ["Berlin"] })).toBe(
			"designer job posting",
		);
		expect(requests[0]?.body).not.toHaveProperty("country");
	});
});

describe("connection test region", () => {
	it("probes search in the given region", async () => {
		await probeWebAccess(connection("tavily"), { userId: "user", region: "AU" });
		const search = requests.find((request) => request.operation === "search");
		expect(search?.body.country).toBe("australia");
	});
	it("probes search with no region when none is given", async () => {
		await probeWebAccess(connection("tavily"), { userId: "user" });
		const search = requests.find((request) => request.operation === "search");
		expect(search?.body).not.toHaveProperty("country");
	});
});

describe("search through a self-hosted SearXNG", () => {
	const searxngResults = { results: [{ url: `${URL}#apply`, title: "Designer", content: "Berlin" }], answers: [] };
	const searxng = () => requests.filter((request) => request.provider === ("searxng" as WebAccessProvider));
	const language = (request: { url: string }) => new globalThis.URL(request.url, endpoint).searchParams.get("language");
	beforeEach(() => {
		fixtures.env.WEB_SEARCH_SEARXNG_URL = `${endpoint}/searxng`;
		respond = ({ provider }) => (provider === ("searxng" as WebAccessProvider) ? { body: searxngResults } : undefined);
	});

	it("searches SearXNG without a web connection", async () => {
		expect(await searchWeb("designer", { userId: "user", connection: null })).toEqual([
			{ url: URL, title: "Designer", snippet: "Berlin" },
		]);
		expect(requests).toHaveLength(1);
		expect(requests[0]).toMatchObject({ provider: "searxng", operation: "search", method: "GET" });
		expect(requests[0]?.url).toBe("/searxng/search?q=designer&format=json");
	});

	it.each(PROVIDERS)("searches SearXNG instead of a saved %s connection", async (provider) => {
		await searchWeb("designer", context(provider));
		expect(requests.map((request) => request.provider)).toEqual(["searxng"]);
		expect(requests[0]?.auth).toBeUndefined();
	});

	it("keeps country targeting independent of the UI language through the same fan-out", async () => {
		respond = ({ provider }) =>
			provider === ("searxng" as WebAccessProvider) ? { body: searxngResults } : { status: 500 };
		const results = await searchWeb(
			"designer",
			{ userId: "user", connection: null, regions: ["AU", "SG"], locale: "de-DE" },
			(region) => `designer in ${region}`,
		);
		expect(results).toEqual([{ url: URL, title: "Designer", snippet: "Berlin" }]);
		expect(Object.fromEntries(searxng().map((request) => [language(request), request.url]))).toEqual({
			"en-AU": "/searxng/search?q=designer+in+AU&format=json&language=en-AU",
			"en-SG": "/searxng/search?q=designer+in+SG&format=json&language=en-SG",
		});
	});

	it("reports a failed search probe when SearXNG's engines all fail", async () => {
		respond = () => ({ body: { results: [], unresponsive_engines: [["google", "timeout"]] } });
		expect(await probeWebAccess(null, { userId: "user", region: "AU" })).toEqual({
			search: { success: false, error: "unreachable" },
			read: { success: false, error: "unavailable" },
		});
	});

	it("reports an unreachable SearXNG safely", async () => {
		respond = () => ({ status: 502 });
		await expect(searchWeb("designer", { userId: "user", connection: null })).rejects.toMatchObject({
			reason: "unreachable",
		});
	});

	it("rate-limits a SearXNG search once", async () => {
		vi.stubEnv("NODE_ENV", "production");
		await searchWeb("designer", { userId: "user", connection: null, regions: ["DE", "FR", "AU"] });
		expect(searxng()).toHaveLength(3);
		expect(fixtures.limit).toHaveBeenCalledTimes(1);
	});

	it("still reads through the saved connection, then the built-in reader", async () => {
		expect(await readPage(URL, context("exa"))).toMatchObject({ method: "exa" });
		expect(requests.map((request) => [request.provider, request.operation])).toEqual([["exa", "read"]]);
		expect(fixtures.direct).not.toHaveBeenCalled();

		requests.length = 0;
		respond = () => ({ status: 500 });
		expect(await readPage(URL, context("exa"))).toMatchObject({ method: "builtin", fallbackReason: "unreachable" });
		expect(requests.map((request) => request.provider)).toEqual(["exa"]);
		expect(fixtures.direct).toHaveBeenCalledTimes(1);
	});

	it("reads with the built-in reader when there is no connection", async () => {
		expect(await readPage(URL, { userId: "user", connection: null })).toMatchObject({ method: "builtin" });
		expect(requests).toHaveLength(0);
	});

	it("tests search against SearXNG and reading against the connection", async () => {
		respond = ({ provider }) => (provider === ("searxng" as WebAccessProvider) ? { status: 503 } : undefined);
		const result = await probeWebAccess(connection("exa"), { userId: "user", region: "AU" });
		expect(result).toEqual({ search: { success: false, error: "unreachable" }, read: { success: true } });
		expect(requests.map((request) => [request.provider, request.operation]).sort()).toEqual([
			["exa", "read"],
			["searxng", "search"],
		]);
		expect(language(searxng()[0] ?? { url: "" })).toBe("en-AU");
		expect(console.info).toHaveBeenCalledWith(
			"[web-access]",
			expect.objectContaining({ provider: "searxng", operation: "search", outcome: "unreachable" }),
		);
		expect(console.info).toHaveBeenCalledWith(
			"[web-access]",
			expect.objectContaining({ provider: "exa", operation: "read", outcome: "success" }),
		);
	});

	it("tests SearXNG search and reports reading as built-in only without a connection", async () => {
		const result = await probeWebAccess(null, { userId: "user", region: "AU" });
		expect(result).toEqual({ search: { success: true }, read: { success: false, error: "unavailable" } });
		expect(requests.map((request) => [request.provider, request.operation])).toEqual([["searxng", "search"]]);
		expect(fixtures.direct).not.toHaveBeenCalled();
	});
});

describe("public targets and bounded fallback", () => {
	it("accepts a maximum-length Applications query including its job intent suffix", async () => {
		const query = "x".repeat(500);
		const results = await searchJobPostings(query, context("tavily"));
		expect(results).toMatchObject([{ url: URL, title: "Designer", description: "Berlin" }]);
		expect(requests[0]?.body.query).toBe(`${query} job posting`);
	});
	it.each([
		"http://jobs.example.com/role",
		"https://user:[email protected]/role",
		"https://localhost/role",
		"https://127.0.0.1/role",
		"https://10.0.0.8/role",
		"https://[::1]/role",
		"ftp://jobs.example.com/role",
	])("refuses unsafe input %s before retrieval", async (url) => {
		await expect(readPage(url, context("firecrawl"))).rejects.toMatchObject({
			reason: "unsafe-url",
		});
		expect(requests).toHaveLength(0);
		expect(fixtures.direct).not.toHaveBeenCalled();
	});

	it("refuses mixed private DNS answers before delegating to any remote service", async () => {
		vi.mocked(lookup).mockResolvedValue([
			{ address: "93.184.216.34", family: 4 },
			{ address: "192.168.1.4", family: 4 },
		] as never);
		await expect(readPage(URL, context("exa"))).rejects.toMatchObject({
			reason: "unsafe-url",
		});
		expect(requests).toHaveLength(0);
		expect(fixtures.direct).not.toHaveBeenCalled();
	});

	it("protects the direct socket against DNS rebinding after preflight", async () => {
		vi.mocked(socketLookup).mockImplementation(((
			_hostname: string,
			_options: unknown,
			callback: (error: Error | null, addresses: unknown) => void,
		) => callback(null, [{ address: "10.0.0.1", family: 4 }])) as never);
		await expect(readPage(URL, { userId: "user", connection: null })).rejects.toMatchObject({ reason: "unsafe-url" });
	});

	it.each(["https://127.0.0.1/private", "http://jobs.example.com/role"])(
		"refuses direct redirects to %s",
		async (location) => {
			fixtures.directLocation = location;
			await expect(readPage(URL, { userId: "user", connection: null })).rejects.toMatchObject({ reason: "unsafe-url" });
			expect(fixtures.direct).toHaveBeenCalledTimes(1);
		},
	);

	it.each(["Readable content", " ", "Just a moment. Verify you are human"])(
		"refuses an unsafe provider resolved URL before accepting %j or starting fallback",
		async (content) => {
			responseOverride = {
				results: [{ url: "https://127.0.0.1/private", raw_content: content }],
			};
			await expect(readPage(URL, context("tavily"))).rejects.toMatchObject({
				reason: "unsafe-url",
			});
			expect(fixtures.direct).not.toHaveBeenCalled();
		},
	);

	it("shares the remaining deadline across a timed-out provider and direct fallback", async () => {
		vi.spyOn(AbortSignal, "timeout").mockImplementation((ms) => nativeTimeout(ms <= 15_000 ? 20 : 75));
		delay = 150;
		fixtures.directDelay = 100;
		await expect(readPage(URL, context("tavily"))).rejects.toMatchObject({
			reason: "timeout",
		});
		expect(fixtures.direct).toHaveBeenCalledTimes(1);
	});

	it.each(["media-type", "response-size", "redirect-loop", "challenge"])(
		"bounds the built-in reader's %s failure",
		async (failure) => {
			if (failure === "media-type") fixtures.directContentType = "application/pdf";
			if (failure === "response-size") fixtures.directHtml = "x".repeat(2_000_001);
			if (failure === "redirect-loop") fixtures.directLocation = URL;
			if (failure === "challenge") fixtures.directHtml = "<p>Just a moment. Verify you are human.</p>";
			await expect(readPage(URL, { userId: "user", connection: null })).rejects.toMatchObject({
				reason:
					failure === "media-type"
						? "not-a-page"
						: failure === "response-size"
							? "too-large"
							: failure === "challenge"
								? "challenge"
								: "unreachable",
			});
			expect(fixtures.direct).toHaveBeenCalledTimes(failure === "redirect-loop" ? 4 : 1);
		},
	);

	it("never sends a provider request after cancellation while DNS is still pending", async () => {
		vi.mocked(lookup).mockImplementation(() => new Promise(() => {}) as never);
		const controller = new AbortController();
		const result = readPage(URL, {
			...context("firecrawl"),
			signal: controller.signal,
		});
		const assertion = expect(result).rejects.toMatchObject({
			name: "AbortError",
		});
		controller.abort();
		await assertion;
		expect(requests).toHaveLength(0);
		expect(fixtures.direct).not.toHaveBeenCalled();
	});

	it("retains the Firecrawl keyless self-hosted reader", async () => {
		expect(
			await readPage(URL, {
				userId: "user",
				connection: { provider: "firecrawl", apiUrl: endpoint, apiKey: "" },
			}),
		).toMatchObject({ method: "firecrawl", completeness: "unknown" });
		expect(requests[0]?.auth).toBeUndefined();
	});

	it("limits the shared boundary once per operation and keeps fallback under the same allowance", async () => {
		vi.stubEnv("NODE_ENV", "production");
		status = 429;
		await readPage(URL, context("exa"));
		expect(fixtures.limit).toHaveBeenCalledTimes(1);
		expect(fixtures.limit).toHaveBeenCalledWith("user");
		fixtures.limit.mockResolvedValue({ success: false });
		await expect(searchWeb("designer", context("exa"))).rejects.toMatchObject({
			reason: "rate-limit",
		});
		expect(requests).toHaveLength(1);
	});
});

describe("explicit alternate search", () => {
	it.each(PROVIDERS.flatMap((provider) => [401, 402].map((status) => ({ provider, status }))))(
		"uses the approved alternate after $provider returns $status",
		async ({ provider, status: failure }) => {
			searchStatus = failure;
			const alternate = [{ url: URL, title: "Retrieved alternate source" }];
			const fallbackSearch = vi.fn(async (_query: string, _region: string | undefined, signal: AbortSignal) => {
				signal.throwIfAborted();
				return alternate;
			});
			expect(await searchWeb("designer", { ...context(provider), fallbackSearch })).toEqual(alternate);
			expect(requests).toHaveLength(1);
			expect(fallbackSearch).toHaveBeenCalledExactlyOnceWith("designer", undefined, expect.any(AbortSignal));
		},
	);

	it.each([200, 429, 500])("does not reroute success, throttling or outage (%s)", async (failure) => {
		searchStatus = failure;
		const fallbackSearch = vi.fn(async () => [{ url: URL, title: "Must not be used" }]);
		const request = searchWeb("designer", { ...context("firecrawl"), fallbackSearch });
		if (failure === 200) await expect(request).resolves.toHaveLength(1);
		else await expect(request).rejects.toMatchObject({ reason: failure === 429 ? "rate-limit" : "unreachable" });
		expect(fallbackSearch).not.toHaveBeenCalled();
	});

	it("retains regional queries, ordering and the shared deadline for the failed region", async () => {
		respond = ({ body }) =>
			body.country === "germany" ? { status: 401 } : { body: resultsFor("tavily", [job("France")]) };
		const fallbackSearch = vi.fn(async (query: string, region: string | undefined, signal: AbortSignal) => {
			signal.throwIfAborted();
			expect(query).toBe("designer DE");
			expect(region).toBe("DE");
			return [job("Germany")];
		});
		expect(
			await searchWeb(
				"designer",
				{ ...context("tavily"), regions: ["DE", "FR"], fallbackSearch },
				(region) => `designer ${region}`,
			),
		).toEqual([job("Germany"), job("France")]);
		expect(fallbackSearch).toHaveBeenCalledTimes(1);
	});

	it("an abort after the failed response prevents the alternate", async () => {
		const controller = new AbortController();
		searchStatus = 401;
		onRequest = () => controller.abort(new DOMException("Stopped", "AbortError"));
		const fallbackSearch = vi.fn(async () => [job("Must not be used")]);
		await expect(
			searchWeb("designer", { ...context("firecrawl"), signal: controller.signal, fallbackSearch }),
		).rejects.toMatchObject({ name: "AbortError" });
		expect(fallbackSearch).not.toHaveBeenCalled();
	});

	it("does not bypass the request rate budget", async () => {
		vi.stubEnv("NODE_ENV", "production");
		fixtures.limit.mockResolvedValue({ success: false });
		const fallbackSearch = vi.fn(async () => [job("Must not be used")]);
		await expect(searchWeb("designer", { ...context("firecrawl"), fallbackSearch })).rejects.toMatchObject({
			reason: "rate-limit",
		});
		expect(requests).toHaveLength(0);
		expect(fallbackSearch).not.toHaveBeenCalled();
	});
});