@apifuse/provider-sdk 2.2.0-beta.61 → 2.2.0-beta.63

package/dist/runtime/state-telemetry.js

@@ -0,0 +1,194 @@
+import { createTelemetryObserver } from "./http-telemetry-guard.js";
+import { closedEnum, } from "./request-telemetry.js";
+import { getStateViolation, isStateRedisNoop } from "./state.js";
+const MAX_SAMPLES = 24;
+const MAX_TEXT = 300;
+const STATE_TELEMETRY_INSTRUMENTED = Symbol.for("@apifuse/provider-sdk/state-telemetry-instrumented");
+function integer(value) {
+    return Number.isFinite(value)
+        ? Math.min(Number.MAX_SAFE_INTEGER, Math.max(0, Math.floor(value)))
+        : Number.MAX_SAFE_INTEGER;
+}
+function add(a, b) {
+    return Math.min(Number.MAX_SAFE_INTEGER, integer(a) + integer(b));
+}
+function keyText(value, redact) {
+    if (value === undefined)
+        return undefined;
+    let result;
+    try {
+        result = redact?.(value) ?? value;
+    }
+    catch {
+        result = "[REDACTION_FAILED]";
+    }
+    const length = Math.min(result.length, MAX_TEXT);
+    const units = new Uint16Array(length);
+    for (let index = 0; index < length; index += 1)
+        units[index] = result.charCodeAt(index);
+    return String.fromCharCode(...units);
+}
+export class StateTelemetryCollector {
+    key = "state";
+    #redact;
+    #telemetryFailed = false;
+    #ops = { list: 0, get: 0, set: 0, patch: 0, delete: 0, cas: 0, increment: 0 };
+    #conflicts = 0;
+    #violations = { quota: 0, ttl: 0, size: 0, unsupported: 0, error: 0 };
+    #backend = "unsupported";
+    #redisFallbacks = 0;
+    #configured = "not_configured";
+    #redisRoundTrips = 0;
+    #ms = 0;
+    #samples = [];
+    #dropped = 0;
+    constructor(options = {}) {
+        this.#redact = options.redact;
+    }
+    markTelemetryFailed() {
+        this.#telemetryFailed = true;
+    }
+    setRedisConfigured(configured) {
+        if (configured && this.#configured === "not_configured")
+            this.#configured = "configured";
+    }
+    record(event) {
+        if (!["list", "get", "set", "patch", "delete", "cas", "increment"].includes(event.op) ||
+            !["redis", "memory", "unsupported"].includes(event.backend) ||
+            (event.violation !== undefined &&
+                !["quota", "ttl", "size", "unsupported", "error"].includes(event.violation))) {
+            this.#telemetryFailed = true;
+            return;
+        }
+        this.#ops[event.op] = add(this.#ops[event.op], 1);
+        this.#backend = event.backend;
+        if (event.backend === "redis" && this.#configured === "not_configured")
+            this.#configured = "configured";
+        if (event.backend === "redis" && event.ok && event.redisTouched !== false)
+            this.#redisRoundTrips = add(this.#redisRoundTrips, 1);
+        if (event.backend === "redis" && !event.ok)
+            this.#configured = "degraded";
+        this.#ms = add(this.#ms, event.ms);
+        if (event.conflict)
+            this.#conflicts = add(this.#conflicts, 1);
+        if (event.violation)
+            this.#violations[event.violation] = add(this.#violations[event.violation], 1);
+        if (this.#samples.length < MAX_SAMPLES)
+            this.#samples.push({
+                key: keyText(event.key, this.#redact) ?? "",
+                op: event.op,
+                ms: integer(event.ms),
+                backend: event.backend,
+            });
+        else
+            this.#dropped = add(this.#dropped, 1);
+    }
+    toLogPayload(_spans) {
+        if (Object.values(this.#ops).every((value) => value === 0) && !this.#telemetryFailed)
+            return undefined;
+        return {
+            ...(this.#telemetryFailed ? { telemetryFailed: true } : {}),
+            ops: { ...this.#ops },
+            casConflicts: this.#conflicts,
+            violations: { ...this.#violations },
+            backend: closedEnum(this.#backend),
+            redisFallbacks: this.#redisFallbacks,
+            redisMode: closedEnum(this.#configured),
+            redisRoundTrips: this.#redisRoundTrips,
+            ms: this.#ms,
+            samples: this.#samples.map((sample) => ({ ...sample })),
+            dropped: this.#dropped,
+        };
+    }
+    toHeaderPayload(log) {
+        return {
+            ops: log.ops,
+            casConflicts: log.casConflicts,
+            violations: log.violations,
+            backend: log.backend,
+            redisFallbacks: log.redisFallbacks,
+            redisMode: log.redisMode,
+            redisRoundTrips: log.redisRoundTrips,
+            ms: log.ms,
+            dropped: log.dropped,
+        };
+    }
+}
+function backendOf(state) {
+    try {
+        const name = state.constructor?.name;
+        return name?.includes("Redis") ? "redis" : name?.includes("Memory") ? "memory" : "unsupported";
+    }
+    catch {
+        return "unsupported";
+    }
+}
+function violationOf(error) {
+    return getStateViolation(error) ?? "error";
+}
+function wrapNamespace(namespace, sink, backend) {
+    // Compare-and-set records one event per attempt; a three-attempt loop therefore
+    // reports cas: 3 and casConflicts: 2 when the first two attempts conflict.
+    const observe = createTelemetryObserver(sink);
+    return new Proxy(namespace, {
+        get(target, property, receiver) {
+            const value = Reflect.get(target, property, receiver);
+            if (typeof value !== "function" || property === "constructor")
+                return value;
+            const op = property === "compareAndSet" ? "cas" : String(property);
+            if (!(op in { list: 1, get: 1, set: 1, patch: 1, delete: 1, cas: 1, increment: 1 }))
+                return value;
+            return async (...args) => {
+                const started = Date.now();
+                const key = typeof args[0] === "string" ? args[0] : undefined;
+                try {
+                    const result = await Reflect.apply(value, target, args);
+                    observe(() => sink.record({
+                        op,
+                        key,
+                        ms: Date.now() - started,
+                        backend,
+                        ok: true,
+                        redisTouched: !isStateRedisNoop(result),
+                        conflict: op === "cas" &&
+                            !!result &&
+                            typeof result === "object" &&
+                            "ok" in result &&
+                            result.ok === false,
+                    }));
+                    return result;
+                }
+                catch (error) {
+                    observe(() => sink.record({
+                        op,
+                        key,
+                        ms: Date.now() - started,
+                        backend,
+                        ok: false,
+                        violation: violationOf(error),
+                    }));
+                    throw error;
+                }
+            };
+        },
+    });
+}
+export function instrumentProviderRuntimeState(state, sink, redact) {
+    if (state[STATE_TELEMETRY_INSTRUMENTED])
+        return state;
+    const backend = backendOf(state);
+    const observe = createTelemetryObserver(sink);
+    observe(() => sink.setRedisConfigured?.(backend === "redis"));
+    return new Proxy(state, {
+        get(target, property, receiver) {
+            if (property === STATE_TELEMETRY_INSTRUMENTED)
+                return true;
+            const value = Reflect.get(target, property, receiver);
+            if (property === "forConnection" && typeof value === "function")
+                return (id) => instrumentProviderRuntimeState(value.call(target, id), sink, redact);
+            if (property === "namespace" && typeof value === "function")
+                return (name, options) => wrapNamespace(value.call(target, name, options), sink, backend);
+            return value;
+        },
+    });
+}

package/dist/runtime/state.d.ts

@@ -10,6 +10,9 @@ type RedisProviderRuntimeStateOptions = {
 export declare class UnsupportedProviderStateError extends ProviderError {
     constructor(message?: string);
 }
+export declare function isStateRedisNoop(result: unknown): boolean;
+type StateViolationKind = "quota" | "ttl" | "size" | "unsupported";
+export declare function getStateViolation(error: unknown): StateViolationKind | undefined;
 export declare function createRedisProviderRuntimeState(options: RedisProviderRuntimeStateOptions): ProviderRuntimeState;
 export declare function createProviderRuntimeStateFromEnv(options?: {
     readonly providerId?: string;

package/dist/runtime/state.js

@@ -247,17 +247,17 @@ class RedisProviderStateNamespace {
     enforceValueSize(value) {
         const bytes = Buffer.byteLength(JSON.stringify(value), "utf8");
         if (bytes > this.options.maxValueBytes) {
-            throw new UnsupportedProviderStateError(`Provider runtime state value exceeds maxValueBytes (${bytes} > ${this.options.maxValueBytes})`);
+            throw stateViolationError(`Provider runtime state value exceeds maxValueBytes (${bytes} > ${this.options.maxValueBytes})`, "size");
         }
     }
     quotaExceeded() {
-        return new UnsupportedProviderStateError(`Provider runtime state namespace quota exceeded (${this.options.maxEntries + 1} > ${this.options.maxEntries})`);
+        return stateViolationError(`Provider runtime state namespace quota exceeded (${this.options.maxEntries + 1} > ${this.options.maxEntries})`, "quota");
     }
     writeTiming(ttl) {
         const ttlMs = parseStateDurationMs(ttl ?? this.options.defaultTtl);
         const maxTtlMs = parseStateDurationMs(this.options.maxTtl);
         if (ttlMs > maxTtlMs) {
-            throw new UnsupportedProviderStateError(`Provider runtime state ttl exceeds maxTtl (${ttlMs} > ${maxTtlMs})`);
+            throw stateViolationError(`Provider runtime state ttl exceeds maxTtl (${ttlMs} > ${maxTtlMs})`, "ttl");
         }
         const expiresAtMs = Date.now() + ttlMs;
         return {
@@ -269,7 +269,7 @@ class RedisProviderStateNamespace {
     async list(options) {
         const requestedLimit = Math.max(0, options?.limit ?? this.options.maxEntries);
         if (requestedLimit === 0)
-            return [];
+            return recordStateRedisNoop([]);
         const keys = await this.indexedKeys(this.options.maxEntries);
         if (keys.length === 0)
             return [];
@@ -376,8 +376,27 @@ export class UnsupportedProviderStateError extends ProviderError {
     constructor(message = "Provider runtime state is not available in this runtime") {
         super(message, { code: "PROVIDER_STATE_UNSUPPORTED" });
         this.name = "UnsupportedProviderStateError";
+        stateViolationKinds.set(this, "unsupported");
     }
 }
+// Keep the exact no-command result out of band, without inspecting caller options twice.
+const stateRedisNoopResults = new WeakSet();
+function recordStateRedisNoop(result) {
+    stateRedisNoopResults.add(result);
+    return result;
+}
+export function isStateRedisNoop(result) {
+    return result !== null && typeof result === "object" && stateRedisNoopResults.has(result);
+}
+const stateViolationKinds = new WeakMap();
+function stateViolationError(message, kind) {
+    const error = new UnsupportedProviderStateError(message);
+    stateViolationKinds.set(error, kind);
+    return error;
+}
+export function getStateViolation(error) {
+    return error !== null && typeof error === "object" ? stateViolationKinds.get(error) : undefined;
+}
 class UnsupportedProviderStateNamespace {
     async list(_options) {
         throw new UnsupportedProviderStateError();
@@ -421,7 +440,7 @@ class MemoryProviderStateNamespace {
     enforceValueSize(value) {
         const bytes = Buffer.byteLength(JSON.stringify(value), "utf8");
         if (bytes > this.options.maxValueBytes) {
-            throw new UnsupportedProviderStateError(`Provider runtime state value exceeds maxValueBytes (${bytes} > ${this.options.maxValueBytes})`);
+            throw stateViolationError(`Provider runtime state value exceeds maxValueBytes (${bytes} > ${this.options.maxValueBytes})`, "size");
         }
     }
     enforceWritePolicy(key, value, ttl) {
@@ -429,10 +448,10 @@ class MemoryProviderStateNamespace {
         const ttlMs = parseStateDurationMs(ttl ?? this.options.defaultTtl);
         const maxTtlMs = parseStateDurationMs(this.options.maxTtl);
         if (ttlMs > maxTtlMs) {
-            throw new UnsupportedProviderStateError(`Provider runtime state ttl exceeds maxTtl (${ttlMs} > ${maxTtlMs})`);
+            throw stateViolationError(`Provider runtime state ttl exceeds maxTtl (${ttlMs} > ${maxTtlMs})`, "ttl");
         }
         if (!this.values.has(key) && this.values.size >= this.options.maxEntries) {
-            throw new UnsupportedProviderStateError(`Provider runtime state namespace quota exceeded (${this.options.maxEntries + 1} > ${this.options.maxEntries})`);
+            throw stateViolationError(`Provider runtime state namespace quota exceeded (${this.options.maxEntries + 1} > ${this.options.maxEntries})`, "quota");
         }
     }
     pruneExpired(nowMs = this.now()) {

package/dist/runtime/stealth-cookies.d.ts

@@ -1,8 +1,11 @@
 import type { CookieJar, StealthCookieStore, StealthCookieStoreV1, StealthSessionCookies } from "../types.js";
+/** Extract cookie values from Set-Cookie/header strings for request-scoped registration. */
+export declare function cookieValuesFromHeaders(headers: string | readonly string[]): string[];
 export declare class StealthCookieJar implements CookieJar, StealthSessionCookies {
     private cookies;
     private readonly defaultUrl;
-    constructor(cookieStrings: readonly string[], defaultUrl?: string);
+    private readonly register;
+    constructor(cookieStrings: readonly string[], defaultUrl?: string, register?: (value: string) => void);
     setFromCookieStrings(cookieStrings: readonly string[], url?: string): void;
     get(name: string, url?: string): string | undefined;
     getAll(url?: string): Record<string, string>;
@@ -15,6 +18,7 @@ export declare class StealthCookieJar implements CookieJar, StealthSessionCookie
     deserialize(state: StealthCookieStore): void;
     clear(): void;
     find(predicate: (cookie: string) => boolean, url?: string): string | undefined;
+    names(url?: string): string[];
     private normalizeUrl;
     private getUniqueCookies;
 }

package/dist/runtime/stealth-cookies.js

@@ -4,15 +4,27 @@ function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
 const LEGACY_COOKIE_ORIGIN = "https://legacy-cookie.invalid/";
+/** Extract cookie values from Set-Cookie/header strings for request-scoped registration. */
+export function cookieValuesFromHeaders(headers) {
+    const values = [];
+    for (const header of typeof headers === "string" ? [headers] : headers) {
+        const cookie = Cookie.parse(header);
+        if (cookie?.value)
+            values.push(cookie.value);
+    }
+    return values;
+}
 export class StealthCookieJar {
     cookies;
     defaultUrl;
-    constructor(cookieStrings, defaultUrl = LEGACY_COOKIE_ORIGIN) {
+    register;
+    constructor(cookieStrings, defaultUrl = LEGACY_COOKIE_ORIGIN, register) {
         this.cookies = new ToughCookieJar(undefined, {
             allowSecureOnLocal: false,
             rejectPublicSuffixes: true,
         });
         this.defaultUrl = this.normalizeUrl(defaultUrl) ?? LEGACY_COOKIE_ORIGIN;
+        this.register = register;
         this.setFromCookieStrings(cookieStrings);
     }
     setFromCookieStrings(cookieStrings, url = this.defaultUrl) {
@@ -20,6 +32,8 @@ export class StealthCookieJar {
         if (!cookieUrl)
             return;
         for (const cookieString of cookieStrings) {
+            for (const value of cookieValuesFromHeaders(cookieString))
+                this.register?.(value);
             this.cookies.setCookieSync(cookieString, cookieUrl, { ignoreError: true });
         }
     }
@@ -54,6 +68,7 @@ export class StealthCookieJar {
         for (const [name, value] of Object.entries(cookies)) {
             if (!name)
                 continue;
+            this.register?.(value);
             this.cookies.setCookieSync(new Cookie({ key: name, path: "/", value }), this.defaultUrl, {
                 ignoreError: true,
             });
@@ -88,6 +103,9 @@ export class StealthCookieJar {
         }
         return undefined;
     }
+    names(url) {
+        return this.getUniqueCookies(url ?? this.defaultUrl).map((cookie) => cookie.key);
+    }
     normalizeUrl(url) {
         try {
             return new URL(url).toString();
@@ -102,6 +120,8 @@ export class StealthCookieJar {
             return [];
         const names = new Set();
         return this.cookies.getCookiesSync(cookieUrl).filter((cookie) => {
+            if (cookie.value)
+                this.register?.(cookie.value);
             if (names.has(cookie.key))
                 return false;
             names.add(cookie.key);

package/dist/runtime/stealth-owned-headers.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Header names the stealth transport owns.
+ *
+ * `ctx.stealth` composes these from the Chrome emulation and the request class,
+ * so a caller value is rejected at request time with `SDKError` code
+ * `STEALTH_HEADER_OVERRIDE_UNSUPPORTED` (`assertCallerHeadersSupported` in
+ * stealth.ts). The `browser-version-literal` lint reports a subset of these
+ * names — the `sec-fetch-*` and `sec-ch-ua*` families — in files that use
+ * `ctx.stealth` (`isReportedOwnedHeaderName` in lint.ts). Both read this
+ * module, so the lint cannot claim a rejection the runtime does not perform;
+ * it reports deliberately less than the runtime rejects (host, connection,
+ * accept-encoding and a non-literal user-agent stay silent — see that
+ * predicate for why), so a green `apifuse check` is not proof that no owned
+ * header is set.
+ *
+ * Leaf module by design: no imports, so the lazily loaded CLI lint path does
+ * not pull the stealth runtime in.
+ */
+export declare const SDK_OWNED_EXACT_CHROME_HEADERS: ReadonlySet<string>;
+export declare const SDK_OWNED_CHROME_HEADER_PREFIX = "sec-fetch-";
+/**
+ * True when `ctx.stealth` rejects a caller value for `name` (case-insensitive):
+ * an exact member of {@link SDK_OWNED_EXACT_CHROME_HEADERS} or any
+ * `sec-fetch-*` name.
+ */
+export declare function isStealthOwnedHeaderName(name: string): boolean;

package/dist/runtime/stealth-owned-headers.js

@@ -0,0 +1,37 @@
+/**
+ * Header names the stealth transport owns.
+ *
+ * `ctx.stealth` composes these from the Chrome emulation and the request class,
+ * so a caller value is rejected at request time with `SDKError` code
+ * `STEALTH_HEADER_OVERRIDE_UNSUPPORTED` (`assertCallerHeadersSupported` in
+ * stealth.ts). The `browser-version-literal` lint reports a subset of these
+ * names — the `sec-fetch-*` and `sec-ch-ua*` families — in files that use
+ * `ctx.stealth` (`isReportedOwnedHeaderName` in lint.ts). Both read this
+ * module, so the lint cannot claim a rejection the runtime does not perform;
+ * it reports deliberately less than the runtime rejects (host, connection,
+ * accept-encoding and a non-literal user-agent stay silent — see that
+ * predicate for why), so a green `apifuse check` is not proof that no owned
+ * header is set.
+ *
+ * Leaf module by design: no imports, so the lazily loaded CLI lint path does
+ * not pull the stealth runtime in.
+ */
+export const SDK_OWNED_EXACT_CHROME_HEADERS = new Set([
+    "host",
+    "connection",
+    "user-agent",
+    "sec-ch-ua",
+    "sec-ch-ua-mobile",
+    "sec-ch-ua-platform",
+    "accept-encoding",
+]);
+export const SDK_OWNED_CHROME_HEADER_PREFIX = "sec-fetch-";
+/**
+ * True when `ctx.stealth` rejects a caller value for `name` (case-insensitive):
+ * an exact member of {@link SDK_OWNED_EXACT_CHROME_HEADERS} or any
+ * `sec-fetch-*` name.
+ */
+export function isStealthOwnedHeaderName(name) {
+    const lower = name.toLowerCase();
+    return (SDK_OWNED_EXACT_CHROME_HEADERS.has(lower) || lower.startsWith(SDK_OWNED_CHROME_HEADER_PREFIX));
+}

package/dist/runtime/stealth-telemetry.d.ts

@@ -0,0 +1,92 @@
+import type { StealthBrowser, StealthChallengeClassification, StealthOS, StealthProfileDescriptor } from "../types.js";
+import { type ClosedEnum, type TelemetryContributor } from "./request-telemetry.js";
+export type StealthTelemetryErrorCode = "transport_network_error" | "transport_timeout" | "transport_cancelled" | "upstream_http_error" | "response_too_large" | "proxy_connect_failed" | "PROXY_POOL_STALE" | "PROXY_EDGE_AUTH_REJECTED" | "PROXY_AUTH_IP_DENIED" | "PROXY_EDGE_TLS_REJECTED" | "PROXY_REQUIRED" | "other";
+export type StealthTelemetryRequestClass = "navigation" | "script_navigation" | "xhr" | "post";
+export type StealthTelemetryAttemptKind = "request" | "resolver" | "proxy_diagnostic";
+export type StealthTelemetrySbsdOutcome = StealthChallengeClassification["outcome"] | "detected" | "refetch_clear";
+export type StealthTelemetryDiagnostics = {
+    readonly name?: string;
+    readonly message?: string;
+    readonly code?: string;
+};
+export type StealthTelemetryAttemptEvent = {
+    readonly ms: number;
+    readonly status?: number;
+    readonly errorCode?: StealthTelemetryErrorCode;
+    readonly diagnostics?: StealthTelemetryDiagnostics;
+    readonly profileId: StealthProfileDescriptor;
+    readonly proxyUsed: boolean;
+    readonly requestClass: StealthTelemetryRequestClass;
+    readonly kind?: StealthTelemetryAttemptKind;
+};
+export type StealthTelemetrySbsdEvent = {
+    readonly detected: boolean;
+    readonly outcome?: StealthTelemetrySbsdOutcome;
+};
+export interface StealthTelemetrySink {
+    recordAttempt(event: StealthTelemetryAttemptEvent): void;
+    recordPoolRefresh(): void;
+    recordRedirectHop(): void;
+    recordSbsd(event?: StealthTelemetrySbsdEvent | StealthTelemetrySbsdOutcome): void;
+    recordSafeRefetch(): void;
+}
+export type StealthTelemetryAttemptSample = {
+    n: number;
+    ms: number;
+    status?: number;
+    e?: StealthTelemetryErrorCode;
+    kind?: StealthTelemetryAttemptKind;
+    diagnostics?: StealthTelemetryDiagnostics;
+};
+export type StealthTelemetryLogPayload = {
+    attempts: number;
+    poolRefreshes: number;
+    redirectHops: number;
+    profileId?: StealthProfileDescriptor;
+    proxyUsed: boolean;
+    requestClass?: StealthTelemetryRequestClass;
+    sbsdDetected?: boolean;
+    sbsdOutcome?: StealthTelemetrySbsdOutcome;
+    safeRefetch: number;
+    lastStatus?: number;
+    ms: number;
+    attemptSamples?: StealthTelemetryAttemptSample[];
+    attemptSamplesDropped?: number;
+};
+export type StealthTelemetryHeaderPayload = {
+    attempts: number;
+    poolRefreshes: number;
+    redirectHops: number;
+    profileId?: {
+        browser: ClosedEnum<StealthBrowser>;
+        os: ClosedEnum<StealthOS>;
+    };
+    proxyUsed: boolean;
+    requestClass?: ClosedEnum<StealthTelemetryRequestClass>;
+    sbsdDetected?: boolean;
+    sbsdOutcome?: ClosedEnum<StealthTelemetrySbsdOutcome>;
+    safeRefetch: number;
+    lastStatus?: number;
+    ms: number;
+    attemptSamples?: {
+        n: number;
+        ms: number;
+        status?: number;
+        e?: ClosedEnum<StealthTelemetryErrorCode>;
+        kind?: ClosedEnum<StealthTelemetryAttemptKind>;
+    }[];
+};
+export declare class StealthTelemetryCollector implements StealthTelemetrySink, TelemetryContributor<StealthTelemetryLogPayload, StealthTelemetryHeaderPayload> {
+    #private;
+    readonly key: "stealth";
+    constructor(options?: {
+        redact?: (text: string) => string;
+    });
+    recordAttempt(event: StealthTelemetryAttemptEvent): void;
+    recordPoolRefresh(): void;
+    recordRedirectHop(): void;
+    recordSbsd(event?: StealthTelemetrySbsdEvent | StealthTelemetrySbsdOutcome): void;
+    recordSafeRefetch(): void;
+    toLogPayload(): StealthTelemetryLogPayload | undefined;
+    toHeaderPayload(log: StealthTelemetryLogPayload): StealthTelemetryHeaderPayload;
+}