@apifuse/provider-sdk 2.1.0-beta.6 → 2.1.0-beta.8

package/dist/runtime/insights.d.ts

@@ -0,0 +1,9 @@
+import type { Span } from "./trace";
+export type InsightSeverity = "info" | "warning" | "error";
+export type Insight = {
+    id: string;
+    severity: InsightSeverity;
+    message: string;
+    fix?: string;
+};
+export declare function generateInsights(spans: Span[]): Insight[];

package/dist/runtime/insights.js

@@ -0,0 +1,324 @@
+import { computePercentile } from "./perf";
+const LARGE_RESPONSE_BYTES = 100_000;
+const SLOW_TRANSFORM_MS = 10;
+const DNS_WARN_MS = 5;
+const BROWSER_IDLE_MS = 5_000;
+const REFRESH_WARN_RATE = 0.1;
+const TLS_REUSE_FIX = `const session = ctx.stealth.createSession({ profile: 'chrome-146' });
+const resp = await session.fetch(url, opts);`;
+const TRANSFORM_FIX = `transformResponse: (raw) => {
+	return raw.items.map(({ id, name, price }) => ({ id, name, price }));
+}`;
+const LARGE_RESPONSE_FIX = `const resp = await ctx.http.get('/items', {
+	params: { limit: 50, page: 1 },
+});`;
+const DNS_FIX = `// Enable DNS caching or reuse a long-lived session per host.
+const session = ctx.stealth.createSession({ profile: 'chrome-146' });
+await session.fetch(url, opts);`;
+const PROXY_FIX = `// Re-check whether this operation really needs a proxy.
+await ctx.stealth.fetch(url, { ...opts, proxy: undefined });`;
+const BROWSER_FIX = `await page.waitForSelector('[data-ready="true"]', {
+	timeout: 5_000,
+});`;
+const SESSION_FIX = `export default defineProvider({
+	session: {
+		ttl: 60 * 60,
+	},
+});`;
+function isNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function isBoolean(value) {
+    return typeof value === "boolean";
+}
+function isString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function getNumberAttribute(span, key) {
+    const value = span.attributes[key];
+    return isNumber(value) ? value : undefined;
+}
+function getBooleanAttribute(span, key) {
+    const value = span.attributes[key];
+    return isBoolean(value) ? value : undefined;
+}
+function getStringAttribute(span, key) {
+    const value = span.attributes[key];
+    return isString(value) ? value : undefined;
+}
+function formatPercent(value) {
+    return `${Math.round(value)}%`;
+}
+function formatMs(value) {
+    const rounded = Number(value.toFixed(value >= 10 ? 0 : 1));
+    return `${rounded}ms`;
+}
+function formatBytes(value) {
+    if (value >= 1_000_000) {
+        return `${(value / 1_000_000).toFixed(1)}MB`;
+    }
+    if (value >= 1_000) {
+        return `${(value / 1_000).toFixed(1)}KB`;
+    }
+    return `${value}B`;
+}
+function parseHostname(url) {
+    if (!url) {
+        return undefined;
+    }
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return undefined;
+    }
+}
+function makeInsight(id, severity, result) {
+    return {
+        id,
+        severity,
+        message: result.message,
+        ...(result.fix ? { fix: result.fix } : {}),
+    };
+}
+function isStealthSpan(span) {
+    return span.name.startsWith("stealth.");
+}
+function isRequestSpan(span) {
+    return span.name === "stealth.fetch" || span.name.startsWith("http.");
+}
+function isBrowserSpan(span) {
+    return span.name.startsWith("browser.") || span.name.startsWith("page.");
+}
+function hasProxy(span) {
+    const proxy = span.attributes.proxy;
+    return proxy === true || (typeof proxy === "string" && proxy.length > 0);
+}
+function getTlsReuseInsight(spans) {
+    const tlsSpans = spans.filter(isStealthSpan);
+    if (tlsSpans.length === 0) {
+        return {
+            triggered: false,
+            message: "✓ Stealth connection reuse: no stealth spans sampled yet",
+        };
+    }
+    const reusedCount = tlsSpans.filter((span) => getBooleanAttribute(span, "connection_reused") === true).length;
+    const reuseRate = reusedCount / tlsSpans.length;
+    if (1 - reuseRate >= 0.8) {
+        return {
+            triggered: true,
+            message: `⚠ Stealth connection reuse: ${formatPercent(reuseRate * 100)} reused — stealth handshakes are happening on most requests`,
+            fix: TLS_REUSE_FIX,
+        };
+    }
+    return {
+        triggered: false,
+        message: `✓ Stealth connection reuse: ${formatPercent(reuseRate * 100)} (good)`,
+    };
+}
+function getSlowTransformInsight(spans) {
+    const durations = spans
+        .filter((span) => span.name === "transformResponse")
+        .map((span) => span.duration_ms)
+        .filter((value) => Number.isFinite(value));
+    if (durations.length === 0) {
+        return {
+            triggered: false,
+            message: "✓ Transform overhead: no transformResponse spans sampled yet",
+        };
+    }
+    const p95 = computePercentile([...durations].sort((a, b) => a - b), 95);
+    if (p95 > SLOW_TRANSFORM_MS) {
+        return {
+            triggered: true,
+            message: `⚠ Transform overhead: p95 ${formatMs(p95)} — trim array size or transformation complexity`,
+            fix: TRANSFORM_FIX,
+        };
+    }
+    return {
+        triggered: false,
+        message: `✓ Transform overhead: p95 ${formatMs(p95)} (good)`,
+    };
+}
+function getLargeResponseInsight(spans) {
+    const sizes = spans
+        .map((span) => getNumberAttribute(span, "response_size"))
+        .filter((value) => value !== undefined);
+    if (sizes.length === 0) {
+        return {
+            triggered: false,
+            message: "✓ Response size: no response payloads sampled yet",
+        };
+    }
+    const maxSize = Math.max(...sizes);
+    if (maxSize > LARGE_RESPONSE_BYTES) {
+        return {
+            triggered: true,
+            message: `⚠ Response size: ${formatBytes(maxSize)} — consider pagination or a lower limit`,
+            fix: LARGE_RESPONSE_FIX,
+        };
+    }
+    return {
+        triggered: false,
+        message: `✓ Response size: ${formatBytes(maxSize)} max (good)`,
+    };
+}
+function getDnsRepeatedCandidate(spans) {
+    const grouped = new Map();
+    for (const span of spans.filter(isStealthSpan)) {
+        const hostname = parseHostname(getStringAttribute(span, "url"));
+        const dnsMs = getNumberAttribute(span, "dns_ms");
+        if (!hostname || dnsMs === undefined) {
+            continue;
+        }
+        const entry = grouped.get(hostname) ?? {
+            dnsDurations: [],
+            reuseCount: 0,
+            totalCount: 0,
+        };
+        entry.dnsDurations.push(dnsMs);
+        entry.totalCount += 1;
+        if (getBooleanAttribute(span, "connection_reused") === true) {
+            entry.reuseCount += 1;
+        }
+        grouped.set(hostname, entry);
+    }
+    let candidate = null;
+    for (const [hostname, entry] of grouped) {
+        if (entry.totalCount < 2) {
+            continue;
+        }
+        const avgDnsMs = entry.dnsDurations.reduce((sum, value) => sum + value, 0) /
+            entry.dnsDurations.length;
+        const reuseRate = entry.reuseCount / entry.totalCount;
+        if (avgDnsMs > DNS_WARN_MS && reuseRate < 0.2) {
+            if (!candidate || avgDnsMs > candidate.avgDnsMs) {
+                candidate = {
+                    hostname,
+                    avgDnsMs,
+                };
+            }
+        }
+    }
+    return candidate;
+}
+function getDnsRepeatedInsight(spans) {
+    const candidate = getDnsRepeatedCandidate(spans);
+    if (!candidate) {
+        return {
+            triggered: false,
+            message: "✓ DNS resolution: no repeated DNS bottleneck detected",
+        };
+    }
+    return {
+        triggered: true,
+        message: `⚠ DNS resolution: ${formatMs(candidate.avgDnsMs)} avg for ${candidate.hostname} — consider DNS caching`,
+        fix: DNS_FIX,
+    };
+}
+function getProxyOverheadInsight(spans) {
+    const requestSpans = spans.filter(isRequestSpan);
+    const proxiedDurations = requestSpans
+        .filter(hasProxy)
+        .map((span) => span.duration_ms);
+    const directDurations = requestSpans
+        .filter((span) => !hasProxy(span))
+        .map((span) => span.duration_ms);
+    if (proxiedDurations.length === 0 || directDurations.length === 0) {
+        return {
+            triggered: false,
+            message: "✓ Proxy overhead: insufficient proxy/direct samples",
+        };
+    }
+    const proxyAvg = proxiedDurations.reduce((sum, value) => sum + value, 0) /
+        proxiedDurations.length;
+    const directAvg = directDurations.reduce((sum, value) => sum + value, 0) /
+        directDurations.length;
+    if (directAvg > 0 && proxyAvg >= directAvg * 2) {
+        return {
+            triggered: true,
+            message: `⚠ Proxy overhead: ${formatMs(proxyAvg)} avg with proxy vs ${formatMs(directAvg)} direct`,
+            fix: PROXY_FIX,
+        };
+    }
+    return {
+        triggered: false,
+        message: `✓ Proxy overhead: ${formatMs(proxyAvg)} avg with proxy vs ${formatMs(directAvg)} direct (good)`,
+    };
+}
+function getBrowserIdleInsight(spans) {
+    const waits = spans
+        .filter(isBrowserSpan)
+        .map((span) => {
+        const waitMs = getNumberAttribute(span, "wait_ms");
+        if (waitMs !== undefined) {
+            return waitMs;
+        }
+        return span.name.toLowerCase().includes("wait")
+            ? span.duration_ms
+            : undefined;
+    })
+        .filter((value) => value !== undefined);
+    if (waits.length === 0) {
+        return {
+            triggered: false,
+            message: "✓ Browser waits: no idle wait spans sampled yet",
+        };
+    }
+    const maxWait = Math.max(...waits);
+    if (maxWait > BROWSER_IDLE_MS) {
+        return {
+            triggered: true,
+            message: `⚠ Browser idle wait: ${formatMs(maxWait)} — optimize waitFor conditions`,
+            fix: BROWSER_FIX,
+        };
+    }
+    return {
+        triggered: false,
+        message: `✓ Browser waits: ${formatMs(maxWait)} max (good)`,
+    };
+}
+function getSessionExpiryInsight(spans) {
+    const refreshCount = spans.filter((span) => span.name === "credential.refresh").length;
+    const requestCount = spans.filter(isRequestSpan).length;
+    if (requestCount === 0) {
+        return {
+            triggered: false,
+            message: "✓ Session refresh frequency: no request spans sampled yet",
+        };
+    }
+    const refreshRate = refreshCount / requestCount;
+    if (refreshRate > REFRESH_WARN_RATE) {
+        return {
+            triggered: true,
+            message: `⚠ Session refresh frequency: ${formatPercent(refreshRate * 100)} of requests — adjust session TTL`,
+            fix: SESSION_FIX,
+        };
+    }
+    return {
+        triggered: false,
+        message: `✓ Session refresh frequency: ${formatPercent(refreshRate * 100)} of requests (good)`,
+    };
+}
+export function generateInsights(spans) {
+    if (spans.length === 0) {
+        return [];
+    }
+    const tlsReuse = getTlsReuseInsight(spans);
+    const slowTransform = getSlowTransformInsight(spans);
+    const largeResponse = getLargeResponseInsight(spans);
+    const dnsRepeated = getDnsRepeatedInsight(spans);
+    const proxyOverhead = getProxyOverheadInsight(spans);
+    const browserIdle = getBrowserIdleInsight(spans);
+    const sessionExpiry = getSessionExpiryInsight(spans);
+    const rules = [
+        makeInsight("tls_reuse_failure", tlsReuse.triggered ? "warning" : "info", tlsReuse),
+        makeInsight("slow_transform", slowTransform.triggered ? "warning" : "info", slowTransform),
+        makeInsight("large_response", largeResponse.triggered ? "warning" : "info", largeResponse),
+        makeInsight("dns_repeated", dnsRepeated.triggered ? "warning" : "info", dnsRepeated),
+        makeInsight("proxy_overhead", proxyOverhead.triggered ? "warning" : "info", proxyOverhead),
+        makeInsight("browser_idle", browserIdle.triggered ? "warning" : "info", browserIdle),
+        makeInsight("session_expiry_frequent", sessionExpiry.triggered ? "warning" : "info", sessionExpiry),
+    ];
+    return rules;
+}

package/dist/runtime/instrumentation.d.ts

@@ -0,0 +1,8 @@
+import type { ProviderContext } from "../types";
+import { type CreateTraceContextOptions, type TraceContext } from "./trace";
+export interface InstrumentationOptions extends CreateTraceContextOptions {
+}
+export type InstrumentedProviderContext<T extends ProviderContext> = Omit<T, "trace"> & {
+    trace: TraceContext;
+};
+export declare function wrapWithInstrumentation<T extends ProviderContext>(ctx: T, options?: InstrumentationOptions): InstrumentedProviderContext<T>;

package/dist/runtime/instrumentation.js

@@ -0,0 +1,269 @@
+import { createTraceContext, getTraceRecorder, } from "./trace";
+const BROWSER_PAGE_METHODS = new Set([
+    "goto",
+    "fill",
+    "click",
+    "type",
+    "waitForSelector",
+]);
+function getErrorStatus(error) {
+    if (typeof error === "object" &&
+        error !== null &&
+        "status" in error &&
+        typeof error.status === "number") {
+        return error.status;
+    }
+    return undefined;
+}
+function getResponseDuration(result) {
+    if (typeof result === "object" &&
+        result !== null &&
+        "meta" in result &&
+        typeof result.meta === "object" &&
+        result.meta !== null &&
+        "duration" in result.meta &&
+        typeof result.meta.duration === "number") {
+        return result.meta.duration;
+    }
+    return undefined;
+}
+function getResponseStatus(namespace, result) {
+    if (typeof result === "object" &&
+        result !== null &&
+        "status" in result &&
+        typeof result.status === "number") {
+        return result.status;
+    }
+    if (namespace === "http") {
+        return 200;
+    }
+    return undefined;
+}
+function getUrl(namespace, args, result) {
+    if (typeof args[0] === "string") {
+        return args[0];
+    }
+    if (namespace === "browser" &&
+        typeof result === "object" &&
+        result !== null &&
+        "url" in result &&
+        typeof result.url === "string") {
+        return result.url;
+    }
+    return undefined;
+}
+function getMethod(namespace, methodName, args) {
+    if (namespace === "http") {
+        return methodName.toUpperCase();
+    }
+    if (namespace === "stealth") {
+        const options = typeof args[1] === "object" && args[1] !== null ? args[1] : undefined;
+        if (options && "method" in options && typeof options.method === "string") {
+            return options.method.toUpperCase();
+        }
+        return "GET";
+    }
+    return undefined;
+}
+function buildSpanAttributes(namespace, methodName, args, result, error) {
+    const attributes = {};
+    const url = getUrl(namespace, args, result);
+    const method = getMethod(namespace, methodName, args);
+    const status = error
+        ? getErrorStatus(error)
+        : getResponseStatus(namespace, result);
+    const duration = error ? undefined : getResponseDuration(result);
+    if (url) {
+        attributes.url = url;
+    }
+    if (method) {
+        attributes.method = method;
+    }
+    if (status !== undefined &&
+        (namespace === "http" || namespace === "stealth")) {
+        attributes.status = status;
+    }
+    if (duration !== undefined) {
+        attributes.duration_ms = duration;
+    }
+    if (namespace === "session" || namespace === "state") {
+        attributes.operation = methodName;
+        const key = typeof args[0] === "string" ? args[0] : undefined;
+        if (key) {
+            attributes.key = key;
+        }
+    }
+    return attributes;
+}
+function getBrowserPageAttributes(methodName, args, elapsedMs, error) {
+    const attributes = {};
+    if (methodName === "goto") {
+        const url = typeof args[0] === "string" ? args[0] : undefined;
+        if (url) {
+            attributes.url = url;
+        }
+        if (error === undefined) {
+            attributes.navigation_ms = elapsedMs ?? 0;
+        }
+        return attributes;
+    }
+    const selector = typeof args[0] === "string" ? args[0] : undefined;
+    if (selector) {
+        attributes.selector = selector;
+    }
+    if (error === undefined) {
+        const key = methodName === "waitForSelector" ? "wait_ms" : "action_ms";
+        attributes[key] = elapsedMs ?? 0;
+    }
+    return attributes;
+}
+function wrapPage(page, trace) {
+    if (page === null || page === undefined) {
+        return page;
+    }
+    const recorder = getTraceRecorder(trace);
+    if (!recorder) {
+        return page;
+    }
+    const wrappedMethods = new Map();
+    return new Proxy(page, {
+        get(pageTarget, property, receiver) {
+            const value = Reflect.get(pageTarget, property, receiver);
+            if (typeof value !== "function" ||
+                property === "constructor" ||
+                !BROWSER_PAGE_METHODS.has(String(property))) {
+                return value;
+            }
+            if (wrappedMethods.has(property)) {
+                return wrappedMethods.get(property);
+            }
+            const methodName = String(property);
+            const wrapped = (...args) => {
+                let elapsedMs = 0;
+                return recorder.runSpan(`browser.page.${methodName}`, async () => {
+                    const startedAt = Date.now();
+                    const result = await Reflect.apply(value, pageTarget, args);
+                    elapsedMs = Date.now() - startedAt;
+                    return result;
+                }, {
+                    onSuccess: () => getBrowserPageAttributes(methodName, args, elapsedMs),
+                    onError: (error) => getBrowserPageAttributes(methodName, args, undefined, error),
+                });
+            };
+            wrappedMethods.set(property, wrapped);
+            return wrapped;
+        },
+    });
+}
+function wrapNamespace(namespace, target, trace) {
+    const recorder = getTraceRecorder(trace);
+    if (!recorder) {
+        return target;
+    }
+    const wrappedMethods = new Map();
+    return new Proxy(target, {
+        get(namespaceTarget, property, receiver) {
+            const value = Reflect.get(namespaceTarget, property, receiver);
+            if (typeof value !== "function" || property === "constructor") {
+                return value;
+            }
+            if (namespace === "browser" && property === "newPage") {
+                if (wrappedMethods.has(property)) {
+                    return wrappedMethods.get(property);
+                }
+                const wrapped = (...args) => {
+                    let allocateMs = 0;
+                    return recorder.runSpan("browser.newPage", async () => {
+                        const startedAt = Date.now();
+                        const page = await Reflect.apply(value, namespaceTarget, args);
+                        allocateMs = Date.now() - startedAt;
+                        return wrapPage(page, trace);
+                    }, {
+                        onSuccess: (result) => {
+                            const attributes = {
+                                allocate_ms: allocateMs,
+                            };
+                            if (result &&
+                                typeof result === "object" &&
+                                "pageId" in result &&
+                                typeof result.pageId === "string") {
+                                attributes.page_id = result.pageId;
+                            }
+                            if (namespaceTarget &&
+                                typeof namespaceTarget === "object" &&
+                                "engine" in namespaceTarget &&
+                                typeof namespaceTarget.engine ===
+                                    "string") {
+                                attributes.engine = namespaceTarget.engine;
+                            }
+                            return attributes;
+                        },
+                        onError: (error) => getBrowserPageAttributes("newPage", args, undefined, error),
+                    });
+                };
+                wrappedMethods.set(property, wrapped);
+                return wrapped;
+            }
+            if (wrappedMethods.has(property)) {
+                return wrappedMethods.get(property);
+            }
+            const methodName = String(property);
+            if (namespace === "browser") {
+                const wrapped = (...args) => {
+                    let elapsedMs = 0;
+                    return recorder.runSpan(`browser.${methodName}`, async () => {
+                        const startedAt = Date.now();
+                        const result = await Reflect.apply(value, namespaceTarget, args);
+                        elapsedMs = Date.now() - startedAt;
+                        return result;
+                    }, {
+                        onSuccess: () => getBrowserPageAttributes(methodName, args, elapsedMs),
+                        onError: (error) => getBrowserPageAttributes(methodName, args, undefined, error),
+                    });
+                };
+                wrappedMethods.set(property, wrapped);
+                return wrapped;
+            }
+            const wrapped = (...args) => recorder.runSpan(`${namespace}.${methodName}`, () => Reflect.apply(value, namespaceTarget, args), {
+                onSuccess: (result) => buildSpanAttributes(namespace, methodName, args, result),
+                onError: (error) => buildSpanAttributes(namespace, methodName, args, undefined, error),
+            });
+            wrappedMethods.set(property, wrapped);
+            return wrapped;
+        },
+    });
+}
+function hasTraceOverrides(options) {
+    return options.maxSpans !== undefined || options.onSpan !== undefined;
+}
+export function wrapWithInstrumentation(ctx, options = {}) {
+    const trace = getTraceRecorder(ctx.trace) && !hasTraceOverrides(options)
+        ? ctx.trace
+        : createTraceContext(options);
+    const wrappedTargets = new Map();
+    return new Proxy(ctx, {
+        get(target, property, receiver) {
+            if (property === "trace") {
+                return trace;
+            }
+            if (property === "http" ||
+                property === "stealth" ||
+                property === "browser" ||
+                property === "session" ||
+                property === "state") {
+                const namespace = property;
+                if (wrappedTargets.has(namespace)) {
+                    return wrappedTargets.get(namespace);
+                }
+                const value = Reflect.get(target, property, receiver);
+                if (!value || typeof value !== "object") {
+                    return value;
+                }
+                const wrapped = wrapNamespace(namespace, value, trace);
+                wrappedTargets.set(namespace, wrapped);
+                return wrapped;
+            }
+            return Reflect.get(target, property, receiver);
+        },
+    });
+}

package/dist/runtime/key-derivation.d.ts

@@ -0,0 +1,24 @@
+/**
+ * HKDF purpose enum. Closed set; adding a purpose requires a spec amendment in
+ * `provider-isolation-hardening`. Each purpose uses a distinct salt so a leak
+ * of one subkey cannot reveal another for the same provider.
+ *
+ * Tenant-scoped columns (`connections.external_ref`, `connections.metadata`)
+ * are plaintext with RLS + log redaction + audit log; no HKDF purpose exists
+ * for them.
+ */
+export type KeyPurpose = "credential-encryption" | "context-namespace" | "token-signing";
+/** @internal Trusted loaders only; not re-exported to provider-importable paths. */
+export declare function decodeMasterKey(encoded: string): Buffer;
+export declare class ConfigurationError extends Error {
+    constructor(message: string);
+}
+/** @internal Trusted loaders only; not re-exported to provider-importable paths. */
+export declare function deriveSubkey(masterSecret: Buffer, providerId: string, purpose: KeyPurpose, keyVersion: number): Buffer;
+/**
+ * Invalidate the subkey cache. Used by the master-key rotation worker after a
+ * writer version change, and by tests to assert determinism.
+ *
+ * @internal
+ */
+export declare function invalidateSubkeyCache(): void;