@apifuse/provider-sdk 2.2.0-beta.5 → 2.2.0-beta.51

package/dist/runtime/otlp.js

@@ -1,3 +1,183 @@
+import { AsyncResource } from "node:async_hooks";
+export const OTEL_EXPORTER_OTLP_TRACES_ENDPOINT = "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT";
+export const OTEL_EXPORTER_OTLP_ENDPOINT = "OTEL_EXPORTER_OTLP_ENDPOINT";
+export const OTEL_EXPORTER_OTLP_TRACES_HEADERS = "OTEL_EXPORTER_OTLP_TRACES_HEADERS";
+export const OTEL_EXPORTER_OTLP_HEADERS = "OTEL_EXPORTER_OTLP_HEADERS";
+export const OTEL_SERVICE_NAME = "OTEL_SERVICE_NAME";
+export const OTEL_RESOURCE_ATTRIBUTES = "OTEL_RESOURCE_ATTRIBUTES";
+const OTLP_HTTP_PROTOCOLS = new Set(["http:", "https:"]);
+const INVALID_ENDPOINT_URL = "is not an absolute http(s) URL";
+const INVALID_ENDPOINT_CREDENTIALS = `embeds credentials in the URL; send them through ${OTEL_EXPORTER_OTLP_HEADERS} instead`;
+const INVALID_HEADERS = "contains an HTTP header name or value that cannot be sent";
+const EXPLICIT_ENDPOINT_SOURCE = "the configured OTLP endpoint";
+const EXPLICIT_HEADERS_SOURCE = "the configured OTLP headers";
+/** Only an unset or empty variable is absent (OTel env rules); whitespace is a value and is validated as one. */
+function presentValue(value) {
+    return value === undefined || value === "" ? undefined : value;
+}
+function parseHttpUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return { reason: INVALID_ENDPOINT_URL };
+    }
+    if (!OTLP_HTTP_PROTOCOLS.has(url.protocol))
+        return { reason: INVALID_ENDPOINT_URL };
+    if (url.username || url.password)
+        return { reason: INVALID_ENDPOINT_CREDENTIALS };
+    return { url };
+}
+/** fetch() rejects malformed header names/values per request; catch that once at resolve time instead. */
+function headersAreSendable(headers) {
+    try {
+        new Headers(headers);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Appends the traces signal path to a base URL, keeping every configured path byte and adding only the separator. */
+function appendTracesPath(base) {
+    const endpoint = new URL(base.toString());
+    const separator = endpoint.pathname.endsWith("/") ? "" : "/";
+    endpoint.pathname = `${endpoint.pathname}${separator}v1/traces`;
+    return endpoint.toString();
+}
+/** HTTP header names are case-insensitive: a later source replaces an earlier one whatever its casing. */
+function mergeHeaders(...sources) {
+    const merged = new Map();
+    for (const source of sources) {
+        for (const [key, value] of Object.entries(source ?? {})) {
+            merged.set(key.toLowerCase(), [key, value]);
+        }
+    }
+    return Object.fromEntries(merged.values());
+}
+function decodeHeaderMember(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        // A literal "%" that is not a valid escape is passed through rather than dropping the header.
+        return value;
+    }
+}
+/** Baggage-style header list: malformed members are skipped and an invalid percent-escape keeps the raw text. */
+function parseHeaderList(value) {
+    const entries = [];
+    for (const member of value?.split(",") ?? []) {
+        const separator = member.indexOf("=");
+        if (separator <= 0)
+            continue;
+        const key = decodeHeaderMember(member.slice(0, separator).trim());
+        if (!key)
+            continue;
+        entries.push([key, decodeHeaderMember(member.slice(separator + 1).trim())]);
+    }
+    return mergeHeaders(Object.fromEntries(entries));
+}
+/**
+ * OTel resource list: a member without `key=value` or with an invalid
+ * percent-escape discards the whole value, as the Resource SDK spec requires,
+ * so a partially malformed variable can never export a wrong identity.
+ */
+function parseResourceAttributeList(value) {
+    const entries = [];
+    for (const member of value.split(",")) {
+        // Every member must be `key=value`; an empty member (`a=b,,c=d`, a trailing comma, a
+        // whitespace-only value) is a parse error and discards the whole variable.
+        const separator = member.indexOf("=");
+        if (separator <= 0)
+            return undefined;
+        try {
+            const key = decodeURIComponent(member.slice(0, separator).trim());
+            if (!key)
+                return undefined;
+            entries.push([key, decodeURIComponent(member.slice(separator + 1).trim())]);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return Object.fromEntries(entries);
+}
+/**
+ * Resolves the OTLP/HTTP export target from explicit configuration and the
+ * standard OpenTelemetry environment contract. Endpoint precedence is explicit
+ * config, then OTEL_EXPORTER_OTLP_TRACES_ENDPOINT verbatim, then
+ * OTEL_EXPORTER_OTLP_ENDPOINT with `/v1/traces` appended. The winning candidate
+ * must be an absolute http(s) URL; an invalid one fails closed instead of
+ * falling through to a lower-precedence destination. Header values are never
+ * surfaced in the result beyond the request options themselves.
+ */
+export function resolveOTLPExportOptions(explicit, env = process.env) {
+    const candidates = [
+        { source: EXPLICIT_ENDPOINT_SOURCE, value: explicit.endpoint, appendPath: false },
+        {
+            source: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
+            value: env[OTEL_EXPORTER_OTLP_TRACES_ENDPOINT],
+            appendPath: false,
+        },
+        {
+            source: OTEL_EXPORTER_OTLP_ENDPOINT,
+            value: env[OTEL_EXPORTER_OTLP_ENDPOINT],
+            appendPath: true,
+        },
+    ];
+    const candidate = candidates
+        .map((entry) => ({ ...entry, value: presentValue(entry.value) }))
+        .find((entry) => entry.value !== undefined);
+    if (!candidate)
+        return { status: "unconfigured" };
+    const parsed = parseHttpUrl(candidate.value);
+    if ("reason" in parsed) {
+        return { status: "invalid", source: candidate.source, reason: parsed.reason };
+    }
+    const endpoint = candidate.appendPath ? appendTracesPath(parsed.url) : candidate.value;
+    const tracesHeaders = presentValue(env[OTEL_EXPORTER_OTLP_TRACES_HEADERS]);
+    const headersSource = tracesHeaders !== undefined ? OTEL_EXPORTER_OTLP_TRACES_HEADERS : OTEL_EXPORTER_OTLP_HEADERS;
+    const envHeaders = parseHeaderList(tracesHeaders ?? presentValue(env[OTEL_EXPORTER_OTLP_HEADERS]));
+    if (!headersAreSendable(envHeaders)) {
+        return { status: "invalid", source: headersSource, reason: INVALID_HEADERS };
+    }
+    const headers = mergeHeaders(envHeaders, explicit.headers);
+    if (!headersAreSendable(headers)) {
+        return { status: "invalid", source: EXPLICIT_HEADERS_SOURCE, reason: INVALID_HEADERS };
+    }
+    return {
+        status: "resolved",
+        options: {
+            endpoint,
+            ...(Object.keys(headers).length > 0 ? { headers } : {}),
+            ...(explicit.timeout !== undefined ? { timeout: explicit.timeout } : {}),
+        },
+    };
+}
+/**
+ * Merges OTEL_RESOURCE_ATTRIBUTES and OTEL_SERVICE_NAME under the caller's
+ * explicit resource attributes: explicit wins per key, OTEL_SERVICE_NAME wins
+ * over a `service.name` inside OTEL_RESOURCE_ATTRIBUTES. An unparseable
+ * OTEL_RESOURCE_ATTRIBUTES value is discarded as a unit and reported in `discarded`.
+ */
+export function resolveOTLPResourceAttributes(explicit, env = process.env) {
+    const discarded = [];
+    const resourceList = presentValue(env[OTEL_RESOURCE_ATTRIBUTES]);
+    const resourceAttributes = resourceList === undefined ? {} : parseResourceAttributeList(resourceList);
+    if (resourceAttributes === undefined)
+        discarded.push(OTEL_RESOURCE_ATTRIBUTES);
+    const serviceName = presentValue(env[OTEL_SERVICE_NAME]);
+    return {
+        attributes: {
+            ...resourceAttributes,
+            ...(serviceName ? { "service.name": serviceName } : {}),
+            ...explicit,
+        },
+        discarded,
+    };
+}
 let nextTraceId = 1n;
 let replayableTraceId = null;
 function createBatchSignature(spans, resourceAttributes) {
@@ -36,8 +216,8 @@ function toAttributeValue(value) {
     }
     return { stringValue: String(value) };
 }
-export function spansToOTLP(spans, resourceAttributes) {
-    const traceId = createTraceId(createBatchSignature(spans, resourceAttributes));
+export function spansToOTLP(spans, resourceAttributes, traceId) {
+    const batchTraceId = traceId ?? createTraceId(createBatchSignature(spans, resourceAttributes));
     return {
         resourceSpans: [
             {
@@ -54,7 +234,7 @@ export function spansToOTLP(spans, resourceAttributes) {
                             version: "0.1.0",
                         },
                         spans: spans.map((span) => ({
-                            traceId,
+                            traceId: batchTraceId,
                             spanId: normalizeHexId(span.id, 16) ?? "0000000000000001",
                             parentSpanId: normalizeHexId(span.parentId, 16),
                             name: span.name,
@@ -73,31 +253,232 @@ export function spansToOTLP(spans, resourceAttributes) {
         ],
     };
 }
-export async function exportSpansOTLP(spans, options, resourceAttributes) {
-    if (spans.length === 0) {
+/**
+ * Binds the transport that carries collector credentials.
+ *
+ * Trust model: in production the provider's own entry file is the process entry, so
+ * provider-controlled code (its earlier imports, a `bun --preload`, or a bunfig preload) can run
+ * before any SDK module evaluates; capture timing alone therefore cannot establish trust. On Bun
+ * the native fetch is also exposed as `Bun.fetch`, and both the `Bun` global and its `fetch`
+ * property are read-only and non-configurable, so no JavaScript in the process can replace that
+ * reference at any point. The engine binds it here and never consults `globalThis.fetch`.
+ *
+ * Residual assumptions: on a runtime without `Bun.fetch` the fallback is `globalThis.fetch` as
+ * seen when this module first evaluates, which code that runs earlier in the same process can
+ * have replaced (or can have forged a `Bun` global). Code with process authority can also patch
+ * other builtins on this path (Map, Object.fromEntries, Headers, AbortController, setTimeout),
+ * install module loader plugins, or reach the internal test seam below by importing this module
+ * by path; an in-process boundary cannot defend against any of that. The CLI flows load provider
+ * modules only after the engine has loaded.
+ */
+function bindEngineTransport() {
+    const bunFetch = typeof Bun !== "undefined" ? Bun.fetch : undefined;
+    return typeof bunFetch === "function" ? bunFetch : globalThis.fetch;
+}
+const engineTransport = bindEngineTransport();
+let transport = engineTransport;
+// Deliveries run inside this engine-owned async scope, created while the module evaluates, so a
+// batch admitted from another batch's completion never inherits that request's async context.
+// (The scope snapshots the async context active at module load: empty under the static imports
+// the engine uses.)
+const exportScope = new AsyncResource("apifuse.otlp.export");
+/** Process-wide bounds so a collector outage can never turn into unbounded sockets, memory, or log volume. */
+export const OTLP_EXPORT_LIMITS = {
+    maxInFlight: 4,
+    maxQueued: 64,
+    maxAttempts: 3,
+    retryBaseDelayMs: 200,
+    retryMaxDelayMs: 2_000,
+    warningCooldownMs: 10_000,
+};
+const RETRYABLE_STATUSES = new Set([408, 429, 502, 503, 504]);
+const TIMEOUT_ERROR_NAMES = new Set(["AbortError", "TimeoutError"]);
+/** Certificate failures do not clear up on retry; they are reported once and the batch dropped. */
+const CERTIFICATE_ERROR_CODES = new Set([
+    "CERT_HAS_EXPIRED",
+    "DEPTH_ZERO_SELF_SIGNED_CERT",
+    "SELF_SIGNED_CERT_IN_CHAIN",
+    "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+    "ERR_TLS_CERT_ALTNAME_INVALID",
+]);
+/** Only these system codes are ever echoed; anything else is reported as a plain network error. */
+const NETWORK_ERROR_CODES = new Set([
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ECONNABORTED",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "ETIMEDOUT",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "EPIPE",
+    "CERT_HAS_EXPIRED",
+    "DEPTH_ZERO_SELF_SIGNED_CERT",
+    "SELF_SIGNED_CERT_IN_CHAIN",
+    "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+    "ERR_TLS_CERT_ALTNAME_INVALID",
+    "ConnectionRefused",
+    "ConnectionClosed",
+    "FailedToOpenSocket",
+]);
+const queue = [];
+let inFlight = 0;
+let lastWarningAt = Number.NEGATIVE_INFINITY;
+let suppressedDrops = 0;
+let suppressedFlush;
+function errorCode(error) {
+    const own = error?.code;
+    if (typeof own === "string")
+        return own;
+    const cause = error?.cause?.code;
+    return typeof cause === "string" ? cause : undefined;
+}
+/** Maps a transport failure onto a fixed vocabulary; nothing from the error object is interpolated. */
+function describeExportFailure(error) {
+    if (error instanceof Error && TIMEOUT_ERROR_NAMES.has(error.name)) {
+        return { reason: "timeout", retryable: true };
+    }
+    const code = errorCode(error);
+    if (code !== undefined && CERTIFICATE_ERROR_CODES.has(code)) {
+        return { reason: `certificate error: ${code}`, retryable: false };
+    }
+    return {
+        reason: code !== undefined && NETWORK_ERROR_CODES.has(code)
+            ? `network error: ${code}`
+            : "network error",
+        retryable: true,
+    };
+}
+function batchesLabel(count) {
+    return `${count} ${count === 1 ? "batch" : "batches"}`;
+}
+/** Emits the count of drops suppressed during a cooldown once it ends, so a burst is never under-reported. */
+function flushSuppressedDrops() {
+    suppressedFlush = undefined;
+    if (suppressedDrops === 0)
+        return;
+    const dropped = suppressedDrops;
+    suppressedDrops = 0;
+    lastWarningAt = Date.now();
+    console.warn(`[apifuse] OTLP export: ${batchesLabel(dropped)} more dropped since the last warning.`);
+}
+function noteDroppedBatch(reason) {
+    const now = Date.now();
+    const sinceLastWarning = now - lastWarningAt;
+    if (sinceLastWarning < OTLP_EXPORT_LIMITS.warningCooldownMs) {
+        suppressedDrops += 1;
+        if (suppressedFlush === undefined) {
+            suppressedFlush = setTimeout(flushSuppressedDrops, OTLP_EXPORT_LIMITS.warningCooldownMs - sinceLastWarning);
+            suppressedFlush.unref?.();
+        }
         return;
     }
+    lastWarningAt = now;
+    console.warn(`[apifuse] OTLP export failed (${reason}); ${batchesLabel(1)} dropped.`);
+}
+async function sendBatch(batch) {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), options.timeout ?? 5_000);
+    const timer = setTimeout(() => controller.abort(), batch.options.timeout ?? 5_000);
     try {
-        const response = await fetch(options.endpoint, {
+        const response = await transport(batch.options.endpoint, {
             method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                ...options.headers,
-            },
-            body: JSON.stringify(spansToOTLP(spans, resourceAttributes)),
+            headers: mergeHeaders(batch.options.headers, { "Content-Type": "application/json" }),
+            body: batch.body,
             signal: controller.signal,
         });
-        if (!response.ok) {
-            throw new Error(`HTTP ${response.status}`);
+        // The reply body is not needed; cancel it while the abort timer still bounds the socket.
+        try {
+            await response.body?.cancel();
+        }
+        catch {
+            // A body that cannot be cancelled does not change the outcome of the export.
         }
+        if (response.ok)
+            return { ok: true };
+        return {
+            ok: false,
+            reason: `HTTP ${response.status}`,
+            retryable: RETRYABLE_STATUSES.has(response.status),
+        };
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        console.warn("[apifuse] OTLP export failed:", message);
+        return { ok: false, ...describeExportFailure(error) };
     }
     finally {
         clearTimeout(timer);
     }
 }
+/** Exponential backoff between attempts: base * 2^(attempt-1), capped at the maximum delay. */
+export function retryDelayMs(attempt) {
+    return Math.min(OTLP_EXPORT_LIMITS.retryBaseDelayMs * 2 ** (attempt - 1), OTLP_EXPORT_LIMITS.retryMaxDelayMs);
+}
+async function deliverBatch(batch) {
+    for (let attempt = 1;; attempt += 1) {
+        const outcome = await sendBatch(batch);
+        if (outcome.ok)
+            return;
+        if (!outcome.retryable || attempt >= OTLP_EXPORT_LIMITS.maxAttempts) {
+            noteDroppedBatch(attempt > 1 ? `${outcome.reason} after ${attempt} attempts` : outcome.reason);
+            return;
+        }
+        await new Promise((resolve) => {
+            setTimeout(resolve, retryDelayMs(attempt)).unref?.();
+        });
+    }
+}
+function pumpQueue() {
+    while (inFlight < OTLP_EXPORT_LIMITS.maxInFlight && queue.length > 0) {
+        const batch = queue.shift();
+        if (!batch)
+            return;
+        inFlight += 1;
+        void exportScope
+            .runInAsyncScope(() => deliverBatch(batch))
+            .finally(() => {
+            inFlight -= 1;
+            batch.settle();
+            pumpQueue();
+        });
+    }
+}
+/**
+ * Queues one export batch behind the process-wide concurrency and queue bounds.
+ * Resolves once the batch has been delivered or dropped; it never rejects, so
+ * callers can fire and forget.
+ */
+export function exportSpansOTLP(spans, options, resourceAttributes, traceId) {
+    if (spans.length === 0) {
+        return Promise.resolve();
+    }
+    if (queue.length >= OTLP_EXPORT_LIMITS.maxQueued) {
+        noteDroppedBatch("export queue is full");
+        return Promise.resolve();
+    }
+    let body;
+    try {
+        body = JSON.stringify(spansToOTLP(spans, resourceAttributes, traceId));
+    }
+    catch {
+        noteDroppedBatch("span serialization failed");
+        return Promise.resolve();
+    }
+    return new Promise((settle) => {
+        queue.push({ body, options, settle });
+        pumpQueue();
+    });
+}
+/** Test seam (not re-exported from any package entry point): substitute the engine transport. */
+export function swapOTLPTransportForTests(next) {
+    transport = next ?? engineTransport;
+}
+/** Test seam: drop queued batches, clear the warning throttle, and restore the engine transport. */
+export function resetOTLPExportForTests() {
+    for (const batch of queue.splice(0))
+        batch.settle();
+    if (suppressedFlush !== undefined)
+        clearTimeout(suppressedFlush);
+    suppressedFlush = undefined;
+    lastWarningAt = Number.NEGATIVE_INFINITY;
+    suppressedDrops = 0;
+    transport = engineTransport;
+}

package/dist/runtime/proxy-errors.js

@@ -11,8 +11,12 @@ const PROXY_POOL_STALE_STATUS_CODES = new Set([509, 512]);
 const PROXY_EDGE_TLS_REJECTED_STATUS_CODES = new Set([495]);
 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) {
     return PROXY_AUTH_IP_DENIED_PATTERN.test(message);
 }

package/dist/runtime/proxy-nodemaven.d.ts

@@ -0,0 +1,56 @@
+import type { ProviderProxyPolicy } from "../types.js";
+export declare const NODEMAVEN_USERNAME_ENV = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
+export declare const NODEMAVEN_PASSWORD_ENV = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
+export declare const NODEMAVEN_FILTER_ENV = "APIFUSE__PROXY__NODEMAVEN_FILTER";
+export declare 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 declare const NODEMAVEN_DEFAULT_PROTOCOL: ProxyProtocol;
+export declare const NODEMAVEN_MAX_POOL_SIZE = 50;
+export declare function hasNodemavenCredentials(): boolean;
+export declare function nodemavenPoolSize(policy: ProviderProxyPolicy): number;
+export declare function nodemavenLifetimeMinutes(policy: ProviderProxyPolicy): number;
+export type NodemavenSessionWindow = {
+    refreshEpoch: number;
+    expiresAt: string;
+};
+/** Stable wall-clock window shared by every process deriving the same sticky sid. */
+export declare function nodemavenSessionWindow(policy: ProviderProxyPolicy, now?: number): NodemavenSessionWindow;
+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 declare function synthesizeNodemavenProxy(input: NodemavenSynthesisInput): NodemavenSynthesis;

package/dist/runtime/proxy-nodemaven.js

@@ -0,0 +1,146 @@
+import { createHash, randomBytes } from "node:crypto";
+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";
+/**
+ * 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 = "http";
+/** NodeMaven gateway port ranges per protocol (docs: HTTP 8080-9080, SOCKS5 1080-2080). */
+const NODEMAVEN_PORTS = {
+    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() {
+    return Boolean(readNodemavenUsername() && readNodemavenPassword());
+}
+function readNodemavenUsername() {
+    return process.env[NODEMAVEN_USERNAME_ENV]?.trim() || undefined;
+}
+function readNodemavenPassword() {
+    return process.env[NODEMAVEN_PASSWORD_ENV]?.trim() || undefined;
+}
+function resolveNodemavenFilter(value) {
+    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) {
+    return Math.min(NODEMAVEN_MAX_POOL_SIZE, Math.max(1, Math.floor(policy.session?.poolSize ?? DEFAULT_NODEMAVEN_POOL_SIZE)));
+}
+export function nodemavenLifetimeMinutes(policy) {
+    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)));
+}
+/** Stable wall-clock window shared by every process deriving the same sticky sid. */
+export function nodemavenSessionWindow(policy, now = Date.now()) {
+    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) {
+    if (!value)
+        return undefined;
+    const slug = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "");
+    return slug || undefined;
+}
+function isStickyAffinity(policy) {
+    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, affinityKey, poolIndex, refreshEpoch) {
+    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, sid, poolIndex) {
+    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);
+}
+/**
+ * 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) {
+    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 } : {}),
+        },
+    };
+}