@apifuse/provider-sdk 2.2.0-beta.2 → 2.2.0-beta.21

package/src/runtime/otlp.ts

@@ -1,4 +1,4 @@
-import type { TraceSpan } from "../types";
+import type { TraceSpan } from "../types.js";
 
 export interface OTLPExportOptions {
 	endpoint: string;
@@ -32,10 +32,7 @@ function createTraceId(signature: string): string {
 	return traceId;
 }
 
-function normalizeHexId(
-	value: string | undefined,
-	length: number,
-): string | undefined {
+function normalizeHexId(value: string | undefined, length: number): string | undefined {
 	if (!value) {
 		return undefined;
 	}
@@ -44,9 +41,7 @@ function normalizeHexId(
 	return normalized.padStart(length, "0").slice(-length);
 }
 
-function toAttributeValue(
-	value: unknown,
-): Record<string, string | number | boolean> {
+function toAttributeValue(value: unknown): Record<string, string | number | boolean> {
 	if (typeof value === "string") {
 		return { stringValue: value };
 	}
@@ -92,20 +87,16 @@ export function spansToOTLP(
 		}>;
 	}>;
 } {
-	const traceId = createTraceId(
-		createBatchSignature(spans, resourceAttributes),
-	);
+	const traceId = createTraceId(createBatchSignature(spans, resourceAttributes));
 
 	return {
 		resourceSpans: [
 			{
 				resource: {
-					attributes: Object.entries(resourceAttributes ?? {}).map(
-						([key, value]) => ({
-							key,
-							value: { stringValue: value },
-						}),
-					),
+					attributes: Object.entries(resourceAttributes ?? {}).map(([key, value]) => ({
+						key,
+						value: { stringValue: value },
+					})),
 				},
 				scopeSpans: [
 					{
@@ -122,12 +113,10 @@ export function spansToOTLP(
 							startTimeUnixNano: String(span.startedAt * 1_000_000),
 							endTimeUnixNano: String(span.endedAt * 1_000_000),
 							status: { code: span.status === "ok" ? 1 : 2 },
-							attributes: Object.entries(span.attributes ?? {}).map(
-								([key, value]) => ({
-									key,
-									value: toAttributeValue(value),
-								}),
-							),
+							attributes: Object.entries(span.attributes ?? {}).map(([key, value]) => ({
+								key,
+								value: toAttributeValue(value),
+							})),
 						})),
 					},
 				],

package/src/runtime/perf.ts

@@ -1,4 +1,4 @@
-import type { Span } from "./trace";
+import type { Span } from "./trace.js";
 
 export type PerfStats = {
 	p50: number;

package/src/runtime/provider.ts

@@ -1,15 +1,10 @@
-import type { ProviderDefinition } from "../types";
+import type { ProviderDefinition } from "../types.js";
 
-export function getProviderBaseUrl(
-	provider: ProviderDefinition,
-): string | undefined {
-	const operations = Object.values(
-		provider.operations as Record<string, unknown>,
-	);
+export function getProviderBaseUrl(provider: ProviderDefinition): string | undefined {
+	const operations = Object.values(provider.operations as Record<string, unknown>);
 
 	for (const operation of operations) {
-		const baseUrl = (operation as { upstream?: { baseUrl?: unknown } }).upstream
-			?.baseUrl;
+		const baseUrl = (operation as { upstream?: { baseUrl?: unknown } }).upstream?.baseUrl;
 
 		if (typeof baseUrl === "string" && baseUrl.length > 0) {
 			return baseUrl;

package/src/runtime/proxy-errors.ts

@@ -1,4 +1,4 @@
-import { TransportError } from "../errors";
+import { TransportError } from "../errors.js";
 
 export const PROXY_AUTH_IP_DENIED_CODE = "PROXY_AUTH_IP_DENIED";
 export const PROXY_AUTH_IP_DENIED_MESSAGE =
@@ -19,10 +19,18 @@ const PROXY_AUTH_IP_DENIED_PATTERN =
 	/\b(?:source|egress|client)\s+ip\b.{0,120}\b(?:deny|denied|unauthori[sz]ed|not\s+authori[sz]ed|white\s*list|allow\s*list)\b|\b(?:white\s*list|allow\s*list)\b.{0,120}\b(?:source|egress|client)\s+ip\b/i;
 const PROXY_EDGE_AUTH_REJECTED_PATTERN =
 	/\bauth\s+ip\s+err\b|\bproxy\b.{0,120}\bauth(?:entication)?\b.{0,120}\b(?:reject(?:ed)?|fail(?:ed)?|invalid|den(?:y|ied)|unauthori[sz]ed)\b|\bauth(?:entication)?\b.{0,120}\b(?:reject(?:ed)?|fail(?:ed)?|invalid|den(?:y|ied)|unauthori[sz]ed)\b.{0,120}\bproxy\b/i;
-const PROXY_POOL_STALE_MESSAGE_PATTERN =
-	/\bproxy\b.{0,120}\b(?:pool|lease|expired|unavailable|exhausted|non[\s-]?200\s+code:\s*(?:509|512))\b|\bnon[\s-]?200\s+code:\s*(?:509|512)\b.{0,120}\bproxy\b|\bsmartproxy\b.{0,120}\b(?:509|512)\b/i;
-const PROXY_EDGE_TLS_REJECTED_MESSAGE_PATTERN =
-	/\b(?:smartproxy|proxy)\b.{0,160}\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\s-]?200)\b|\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\s-]?200)\b.{0,160}\b(?:smartproxy|proxy)\b/i;
+// Vendor host tokens that can appear in upstream error strings. Adding a proxy
+// vendor updates every classifier below in one place. `proxy` is the generic
+// fallback so vendor-agnostic messages still classify.
+const PROXY_VENDOR_ALTERNATION = "smartproxy|nodemaven|proxy";
+const PROXY_POOL_STALE_MESSAGE_PATTERN = new RegExp(
+	`\\bproxy\\b.{0,120}\\b(?:pool|lease|expired|unavailable|exhausted|non[\\s-]?200\\s+code:\\s*(?:509|512))\\b|\\bnon[\\s-]?200\\s+code:\\s*(?:509|512)\\b.{0,120}\\bproxy\\b|\\b(?:${PROXY_VENDOR_ALTERNATION})\\b.{0,120}\\b(?:509|512)\\b`,
+	"i",
+);
+const PROXY_EDGE_TLS_REJECTED_MESSAGE_PATTERN = new RegExp(
+	`\\b(?:${PROXY_VENDOR_ALTERNATION})\\b.{0,160}\\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\\s-]?200)\\b|\\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\\s-]?200)\\b.{0,160}\\b(?:${PROXY_VENDOR_ALTERNATION})\\b`,
+	"i",
+);
 
 export function isProxyAuthIpDeniedMessage(message: string): boolean {
 	return PROXY_AUTH_IP_DENIED_PATTERN.test(message);
@@ -39,9 +47,7 @@ export function isProxyEdgeAuthRejectedMessage(message: string): boolean {
 	return PROXY_EDGE_AUTH_REJECTED_PATTERN.test(message);
 }
 
-export function createProxyEdgeAuthRejectedError(
-	cause?: Error,
-): TransportError {
+export function createProxyEdgeAuthRejectedError(cause?: Error): TransportError {
 	return new TransportError(PROXY_EDGE_AUTH_REJECTED_MESSAGE, {
 		code: PROXY_EDGE_AUTH_REJECTED_CODE,
 		cause,
@@ -52,10 +58,7 @@ export function isProxyPoolStaleStatus(status: number): boolean {
 	return PROXY_POOL_STALE_STATUS_CODES.has(status);
 }
 
-export function isProxyEdgeTlsRejectedResponse(
-	status: number,
-	evidence: string,
-): boolean {
+export function isProxyEdgeTlsRejectedResponse(status: number, evidence: string): boolean {
 	return (
 		PROXY_EDGE_TLS_REJECTED_STATUS_CODES.has(status) &&
 		PROXY_EDGE_TLS_REJECTED_MESSAGE_PATTERN.test(evidence)
@@ -67,10 +70,7 @@ export function isProxyPoolStaleMessage(message: string): boolean {
 }
 
 export function isProxyPoolRefreshableError(error: unknown): boolean {
-	if (
-		error instanceof TransportError &&
-		error.code === PROXY_AUTH_IP_DENIED_CODE
-	) {
+	if (error instanceof TransportError && error.code === PROXY_AUTH_IP_DENIED_CODE) {
 		return false;
 	}
 
@@ -89,39 +89,26 @@ export function isProxyPoolRefreshableError(error: unknown): boolean {
 		cause instanceof Error ? cause.message : "",
 	].join(" ");
 	return (
-		PROXY_POOL_STALE_MESSAGE_PATTERN.test(message) ||
-		PROXY_EDGE_AUTH_REJECTED_PATTERN.test(message)
+		PROXY_POOL_STALE_MESSAGE_PATTERN.test(message) || PROXY_EDGE_AUTH_REJECTED_PATTERN.test(message)
 	);
 }
 
 export const isProxyPoolStaleError = isProxyPoolRefreshableError;
 
-export function createProxyPoolStaleError(
-	status: number,
-	cause?: Error,
-): TransportError {
-	return new TransportError(
-		`Proxy provider pool failed with status ${status}`,
-		{
-			code: PROXY_POOL_STALE_CODE,
-			status,
-			cause,
-		},
-	);
+export function createProxyPoolStaleError(status: number, cause?: Error): TransportError {
+	return new TransportError(`Proxy provider pool failed with status ${status}`, {
+		code: PROXY_POOL_STALE_CODE,
+		status,
+		cause,
+	});
 }
 
-export function createProxyEdgeTlsRejectedError(
-	status: number,
-	cause?: Error,
-): TransportError {
-	return new TransportError(
-		`Proxy edge TLS request was rejected with status ${status}`,
-		{
-			code: PROXY_EDGE_TLS_REJECTED_CODE,
-			status,
-			cause,
-		},
-	);
+export function createProxyEdgeTlsRejectedError(status: number, cause?: Error): TransportError {
+	return new TransportError(`Proxy edge TLS request was rejected with status ${status}`, {
+		code: PROXY_EDGE_TLS_REJECTED_CODE,
+		status,
+		cause,
+	});
 }
 
 export function createProxyPoolExhaustedError(cause?: Error): TransportError {

package/src/runtime/proxy-nodemaven.ts

@@ -0,0 +1,221 @@
+import { createHash, randomBytes } from "node:crypto";
+
+import type { ProviderProxyPolicy } from "../types.js";
+
+export const NODEMAVEN_USERNAME_ENV = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
+export const NODEMAVEN_PASSWORD_ENV = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
+export const NODEMAVEN_FILTER_ENV = "APIFUSE__PROXY__NODEMAVEN_FILTER";
+
+export const NODEMAVEN_GATEWAY_HOST = "gate.nodemaven.com";
+
+export type NodemavenCredentials = {
+	readonly username: string;
+	readonly password: string;
+	readonly filter?: string;
+};
+
+/** Both schemes tunnel bytes end-to-end, preserving the client TLS handshake. */
+export type ProxyProtocol = "http" | "socks5";
+
+/**
+ * NodeMaven's fastest protocol: HTTP CONNECT. Benchmarks (KR, cold + warm)
+ * showed socks5 through the gateway adds ~500ms per request over http, so
+ * NodeMaven never defaults to socks5.
+ */
+export const NODEMAVEN_DEFAULT_PROTOCOL: ProxyProtocol = "http";
+
+/** NodeMaven gateway port ranges per protocol (docs: HTTP 8080-9080, SOCKS5 1080-2080). */
+const NODEMAVEN_PORTS: Record<ProxyProtocol, { min: number; max: number }> = {
+	http: { min: 8080, max: 9080 },
+	socks5: { min: 1080, max: 2080 },
+};
+
+const NODEMAVEN_FILTERS = new Set(["medium", "high"]);
+const DEFAULT_NODEMAVEN_FILTER = "medium";
+const DEFAULT_NODEMAVEN_POOL_SIZE = 20;
+export const NODEMAVEN_MAX_POOL_SIZE = 50;
+/** NodeMaven sticky sessions persist up to 24h server-side, keyed by the sid. */
+const NODEMAVEN_MAX_LIFETIME_MINUTES = 1440;
+const SID_LENGTH = 10;
+
+export function hasNodemavenCredentials(): boolean {
+	return Boolean(readNodemavenUsername() && readNodemavenPassword());
+}
+
+function readNodemavenUsername(): string | undefined {
+	return process.env[NODEMAVEN_USERNAME_ENV]?.trim() || undefined;
+}
+
+function readNodemavenPassword(): string | undefined {
+	return process.env[NODEMAVEN_PASSWORD_ENV]?.trim() || undefined;
+}
+
+function resolveNodemavenFilter(value: string | undefined): string {
+	const raw = value?.trim().toLowerCase();
+	if (!raw) return DEFAULT_NODEMAVEN_FILTER;
+	if (!NODEMAVEN_FILTERS.has(raw)) {
+		throw new Error(`${NODEMAVEN_FILTER_ENV} must be "medium" or "high"`);
+	}
+	return raw;
+}
+
+export function nodemavenPoolSize(policy: ProviderProxyPolicy): number {
+	return Math.min(
+		NODEMAVEN_MAX_POOL_SIZE,
+		Math.max(1, Math.floor(policy.session?.poolSize ?? DEFAULT_NODEMAVEN_POOL_SIZE)),
+	);
+}
+
+export function nodemavenLifetimeMinutes(policy: ProviderProxyPolicy): number {
+	const configured = policy.session?.lifetimeMinutes;
+	if (typeof configured !== "number" || !Number.isFinite(configured) || configured <= 0) {
+		return NODEMAVEN_MAX_LIFETIME_MINUTES;
+	}
+	return Math.min(NODEMAVEN_MAX_LIFETIME_MINUTES, Math.max(1, Math.floor(configured)));
+}
+
+export type NodemavenSessionWindow = {
+	refreshEpoch: number;
+	expiresAt: string;
+};
+
+/** Stable wall-clock window shared by every process deriving the same sticky sid. */
+export function nodemavenSessionWindow(
+	policy: ProviderProxyPolicy,
+	now = Date.now(),
+): NodemavenSessionWindow {
+	const lifetimeMs = nodemavenLifetimeMinutes(policy) * 60_000;
+	const refreshEpoch = Math.floor(now / lifetimeMs);
+	return {
+		refreshEpoch,
+		expiresAt: new Date((refreshEpoch + 1) * lifetimeMs).toISOString(),
+	};
+}
+
+/** NodeMaven username tokens accept `[a-z0-9]`; slugify geo values to that set. */
+function slugifyGeo(value: string | undefined): string | undefined {
+	if (!value) return undefined;
+	const slug = value
+		.trim()
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "");
+	return slug || undefined;
+}
+
+function isStickyAffinity(policy: ProviderProxyPolicy): boolean {
+	return (policy.session?.affinity ?? "request") !== "request";
+}
+
+/**
+ * A sticky sid is deterministic from the affinity key so every process serving
+ * the same connection derives the same egress IP without shared storage. A
+ * rotating sid is random per call (a fresh egress IP per request).
+ */
+function deriveSid(
+	policy: ProviderProxyPolicy,
+	affinityKey: string | undefined,
+	poolIndex: number,
+	refreshEpoch: number,
+): string {
+	if (!isStickyAffinity(policy) || !affinityKey) {
+		return randomBytes(SID_LENGTH).toString("hex").slice(0, SID_LENGTH);
+	}
+	const digest = createHash("sha256")
+		.update(`${affinityKey}:${refreshEpoch}:${poolIndex}`)
+		.digest("hex");
+	// hex digits are a subset of the allowed [a-z0-9] sid charset.
+	return digest.slice(0, SID_LENGTH);
+}
+
+function selectPort(protocol: ProxyProtocol, sid: string, poolIndex: number): number {
+	const { min, max } = NODEMAVEN_PORTS[protocol];
+	const span = max - min + 1;
+	const hashInt = Number.parseInt(
+		createHash("sha256").update(`${sid}:${poolIndex}`).digest("hex").slice(0, 8),
+		16,
+	);
+	return min + (hashInt % span);
+}
+
+export type NodemavenSynthesisInput = {
+	policy: ProviderProxyPolicy;
+	/** Explicit credentials; synthesis never reads process-global state. */
+	credentials: NodemavenCredentials;
+	affinityKey: string | undefined;
+	protocol: ProxyProtocol;
+	poolIndex: number;
+	refreshEpoch: number;
+	/** ISO 3166-1 alpha-2, already resolved by the caller (falls back to env). */
+	country?: string;
+	/** Clock injection used by native sticky-expiry lifecycle tests. */
+	now?: number;
+	/** Stable caller-owned hard expiry when the refresh epoch is wall-clock-derived. */
+	expiresAt?: string;
+};
+
+export type NodemavenSynthesis = {
+	url: string;
+	protocol: ProxyProtocol;
+	sticky: boolean;
+	sessionId: string;
+	expiresAt?: string;
+	diagnostics: Record<string, string | number | boolean>;
+};
+
+/**
+ * Synthesize a NodeMaven gateway proxy URL locally from static credentials.
+ * There is no allocation API — geo/session are encoded in the username.
+ */
+export function synthesizeNodemavenProxy(input: NodemavenSynthesisInput): NodemavenSynthesis {
+	const username = input.credentials.username.trim();
+	const password = input.credentials.password.trim();
+	if (!username || !password) {
+		throw new Error(
+			`NodeMaven credentials missing: set ${NODEMAVEN_USERNAME_ENV} and ${NODEMAVEN_PASSWORD_ENV}.`,
+		);
+	}
+
+	const filter = resolveNodemavenFilter(input.credentials.filter);
+	const sid = deriveSid(input.policy, input.affinityKey, input.poolIndex, input.refreshEpoch);
+	const port = selectPort(input.protocol, sid, input.poolIndex);
+	const lifetimeMinutes = nodemavenLifetimeMinutes(input.policy);
+	const sticky = isStickyAffinity(input.policy);
+
+	const country = slugifyGeo(input.country ?? input.policy.geo?.country);
+	const region = slugifyGeo(input.policy.geo?.subdivision);
+	const city = slugifyGeo(input.policy.geo?.city);
+
+	const tokens = [username];
+	if (country) tokens.push("country", country);
+	if (region) tokens.push("region", region);
+	if (city) tokens.push("city", city);
+	tokens.push("sid", sid);
+	tokens.push("filter", filter);
+	tokens.push("ipv4", "true");
+	const proxyUsername = tokens.join("-");
+
+	// Username tokens are [a-z0-9-] only, which survive URL encoding unchanged.
+	const url = `${input.protocol}://${proxyUsername}:${encodeURIComponent(password)}@${NODEMAVEN_GATEWAY_HOST}:${port}`;
+
+	return {
+		url,
+		protocol: input.protocol,
+		sticky,
+		sessionId: sid,
+		...(sticky
+			? {
+					expiresAt:
+						input.expiresAt ??
+						new Date((input.now ?? Date.now()) + lifetimeMinutes * 60_000).toISOString(),
+				}
+			: {}),
+		diagnostics: {
+			vendor: "nodemaven",
+			protocol: input.protocol,
+			sticky,
+			filter,
+			lifetimeMinutes,
+			...(country ? { country } : {}),
+		},
+	};
+}

package/src/runtime/proxy-retry-policy.ts

@@ -1,12 +1,12 @@
-import { ProviderError, TransportError } from "../errors";
-import type { HttpMethod, HttpRetryOptions, RequestOptions } from "../types";
+import { ProviderError, TransportError } from "../errors.js";
+import type { HttpMethod, HttpRetryOptions, RequestOptions } from "../types.js";
 import {
 	HttpRetryAfterPolicy,
 	HttpRetryDelayStrategy,
 	HttpRetryJitter,
 	HttpRetryPreset,
 	HttpRetryUnsafeMethodPolicy,
-} from "../types";
+} from "../types.js";
 
 export type NormalizedProxyTransportRetryOptions = Required<
 	Pick<