@apifuse/connector-sdk 2.0.0-beta.1

package/src/__tests__/instrumentation.test.ts

@@ -0,0 +1,290 @@
+import { describe, expect, it, mock } from "bun:test";
+
+import { wrapWithInstrumentation } from "../runtime/instrumentation";
+import { createTraceContext } from "../runtime/trace";
+import type {
+	AuthContext,
+	BrowserClient,
+	ConnectorContext,
+	HttpClient,
+	SessionStore,
+	StateContext,
+	TlsClient,
+} from "../types";
+
+function createMockContext(): ConnectorContext {
+	const mockPage = {
+		pageId: "page-1",
+		goto: mock(async (url: string) => ({ url })),
+		fill: mock(async () => undefined),
+		click: mock(async () => undefined),
+		type: mock(async () => undefined),
+		waitForSelector: mock(async () => undefined),
+	};
+
+	return {
+		http: {
+			request: mock(async () => ({
+				status: 200,
+				ok: true,
+				headers: { "content-type": "application/json" },
+				data: { ok: true },
+				meta: { requestId: "req-0", duration: 10 },
+				json: async <T>() => ({ ok: true }) as T,
+				text: async () => JSON.stringify({ ok: true }),
+			})),
+			get: mock(async () => ({
+				status: 200,
+				ok: true,
+				headers: { "content-type": "application/json" },
+				data: { ok: true },
+				meta: { requestId: "req-1", duration: 15 },
+				json: async <T>() => ({ ok: true }) as T,
+				text: async () => JSON.stringify({ ok: true }),
+			})),
+			post: mock(async () => ({
+				status: 200,
+				ok: true,
+				headers: { "content-type": "application/json" },
+				data: { ok: true },
+				meta: { requestId: "req-2", duration: 20 },
+				json: async <T>() => ({ ok: true }) as T,
+				text: async () => JSON.stringify({ ok: true }),
+			})),
+			put: mock(async () => ({
+				status: 200,
+				ok: true,
+				headers: { "content-type": "application/json" },
+				data: { ok: true },
+				meta: { requestId: "req-3", duration: 25 },
+				json: async <T>() => ({ ok: true }) as T,
+				text: async () => JSON.stringify({ ok: true }),
+			})),
+			delete: mock(async () => ({
+				status: 200,
+				ok: true,
+				headers: { "content-type": "application/json" },
+				data: { ok: true },
+				meta: { requestId: "req-4", duration: 30 },
+				json: async <T>() => ({ ok: true }) as T,
+				text: async () => JSON.stringify({ ok: true }),
+			})),
+		} as HttpClient,
+		tls: {
+			fetch: mock(async () => ({
+				status: 201,
+				ok: true,
+				headers: {},
+				rawHeaders: [] as [string, string][],
+				body: "created",
+				cookies: {
+					get: () => undefined,
+					getAll: () => ({}),
+					toString: () => "",
+				},
+				json: async <T>() => ({}) as T,
+			})),
+			createSession: mock(() => ({
+				fetch: async () => ({
+					status: 200,
+					ok: true,
+					headers: {},
+					rawHeaders: [] as [string, string][],
+					body: "ok",
+					cookies: {
+						get: () => undefined,
+						getAll: () => ({}),
+						toString: () => "",
+					},
+					json: async <T>() => ({}) as T,
+				}),
+				close: () => {},
+			})),
+		} as TlsClient,
+		browser: {
+			engine: "playwright-stealth",
+			newPage: mock(async () => mockPage),
+			goto: mock(async (url: string) => ({ url })),
+		} as unknown as BrowserClient,
+		session: {} as SessionStore,
+		state: {} as StateContext,
+		trace: createTraceContext(),
+		auth: {} as AuthContext,
+	};
+}
+
+describe("createTraceContext", () => {
+	it("collects nested custom spans in start order", async () => {
+		const trace = createTraceContext();
+
+		const result = await trace.span("operation", async () => {
+			return trace.span("parse", async () => "done");
+		});
+
+		const spans = trace.getSpans();
+
+		expect(result).toBe("done");
+		expect(spans).toHaveLength(2);
+		expect(spans[0]?.name).toBe("operation");
+		expect(spans[1]?.name).toBe("parse");
+		expect(spans[1]?.parentId).toBe(spans[0]?.id);
+		expect(spans[0]?.status).toBe("ok");
+		expect(spans[1]?.attributes.duration_ms).toBeNumber();
+	});
+
+	it("enforces maxSpans by trimming the oldest completed spans", async () => {
+		const trace = createTraceContext({ maxSpans: 2 });
+
+		await trace.span("first", async () => undefined);
+		await trace.span("second", async () => undefined);
+		await trace.span("third", async () => undefined);
+
+		expect(trace.getSpans().map((span) => span.name)).toEqual([
+			"second",
+			"third",
+		]);
+	});
+});
+
+describe("wrapWithInstrumentation", () => {
+	it("creates spans for http, tls, and browser method calls", async () => {
+		const onSpan = mock(() => {});
+		const ctx = createMockContext();
+		const instrumented = wrapWithInstrumentation(ctx, { onSpan });
+
+		await instrumented.trace.span("connector.search", async () => {
+			await instrumented.http.get("https://api.example.com/items");
+			await instrumented.tls.fetch("https://secure.example.com/login", {
+				method: "POST",
+			});
+			await (
+				instrumented.browser as BrowserClient & {
+					goto(url: string): Promise<{ url: string }>;
+				}
+			).goto("https://app.example.com/dashboard");
+		});
+
+		const spans = instrumented.trace.getSpans();
+
+		expect(spans.map((span) => span.name)).toEqual([
+			"connector.search",
+			"http.get",
+			"tls.fetch",
+			"browser.goto",
+		]);
+
+		const httpSpan = spans[1];
+		expect(httpSpan).toMatchObject({
+			status: "ok",
+			parentId: spans[0]?.id,
+			attributes: {
+				url: "https://api.example.com/items",
+				method: "GET",
+				status: 200,
+				duration_ms: 15,
+			},
+		});
+
+		const tlsSpan = spans[2];
+		expect(tlsSpan).toMatchObject({
+			status: "ok",
+			parentId: spans[0]?.id,
+			attributes: {
+				url: "https://secure.example.com/login",
+				method: "POST",
+				status: 201,
+			},
+		});
+
+		const browserSpan = spans[3];
+		expect(browserSpan).toMatchObject({
+			status: "ok",
+			parentId: spans[0]?.id,
+			attributes: {
+				url: "https://app.example.com/dashboard",
+			},
+		});
+
+		expect(onSpan).toHaveBeenCalledTimes(4);
+	});
+
+	it("wraps browser newPage and page methods with spans", async () => {
+		const ctx = createMockContext();
+		const instrumented = wrapWithInstrumentation(ctx);
+
+		const page = (await instrumented.browser.newPage()) as {
+			goto(url: string): Promise<{ url: string }>;
+			fill(selector: string, value: string): Promise<void>;
+			click(selector: string): Promise<void>;
+			type(selector: string, text: string): Promise<void>;
+			waitForSelector(selector: string): Promise<void>;
+		};
+
+		await page.goto("https://app.example.com/login");
+		await page.fill("#username", "demo");
+		await page.click("button[type=submit]");
+		await page.type("#otp", "123456");
+		await page.waitForSelector(".dashboard");
+
+		const spans = instrumented.trace.getSpans();
+		expect(spans.map((span) => span.name)).toEqual([
+			"browser.newPage",
+			"browser.page.goto",
+			"browser.page.fill",
+			"browser.page.click",
+			"browser.page.type",
+			"browser.page.waitForSelector",
+		]);
+		expect(spans[0]?.attributes).toMatchObject({
+			allocate_ms: expect.any(Number),
+			page_id: "page-1",
+			engine: "playwright-stealth",
+		});
+		expect(spans[1]?.attributes).toMatchObject({
+			url: "https://app.example.com/login",
+			navigation_ms: expect.any(Number),
+		});
+		expect(spans[2]?.attributes).toMatchObject({
+			selector: "#username",
+			action_ms: expect.any(Number),
+		});
+		expect(spans[3]?.attributes).toMatchObject({
+			selector: "button[type=submit]",
+			action_ms: expect.any(Number),
+		});
+		expect(spans[4]?.attributes).toMatchObject({
+			selector: "#otp",
+			action_ms: expect.any(Number),
+		});
+		expect(spans[5]?.attributes).toMatchObject({
+			selector: ".dashboard",
+			wait_ms: expect.any(Number),
+		});
+	});
+
+	it("records error spans when instrumented methods throw", async () => {
+		const ctx = createMockContext();
+		ctx.tls.fetch = mock(async () => {
+			const error = new Error("boom") as Error & { status: number };
+			error.status = 503;
+			throw error;
+		});
+
+		const instrumented = wrapWithInstrumentation(ctx);
+
+		await expect(
+			instrumented.tls.fetch("https://secure.example.com/fail"),
+		).rejects.toThrow("boom");
+
+		expect(instrumented.trace.getSpans()[0]).toMatchObject({
+			name: "tls.fetch",
+			status: "error",
+			error: "boom",
+			attributes: {
+				url: "https://secure.example.com/fail",
+				method: "GET",
+				status: 503,
+			},
+		});
+	});
+});

package/src/__tests__/otlp.test.ts

@@ -0,0 +1,141 @@
+import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test";
+
+import { exportSpansOTLP, spansToOTLP } from "../runtime/otlp";
+import type { TraceSpan } from "../types";
+
+function makeSpan(overrides: Partial<TraceSpan> = {}): TraceSpan {
+	return {
+		id: overrides.id ?? "span-1",
+		name: overrides.name ?? "connector.search",
+		startedAt: overrides.startedAt ?? 1_000,
+		endedAt: overrides.endedAt ?? 1_025,
+		duration_ms: overrides.duration_ms ?? 25,
+		status: overrides.status ?? "ok",
+		attributes: overrides.attributes ?? {
+			method: "GET",
+			status: 200,
+			success: true,
+		},
+		...(overrides.parentId ? { parentId: overrides.parentId } : {}),
+		...(overrides.error ? { error: overrides.error } : {}),
+	};
+}
+
+describe("otlp export", () => {
+	let originalFetch: typeof fetch;
+	let originalWarn: typeof console.warn;
+
+	beforeEach(() => {
+		originalFetch = global.fetch;
+		originalWarn = console.warn;
+	});
+
+	afterEach(() => {
+		global.fetch = originalFetch;
+		console.warn = originalWarn;
+	});
+
+	it("spansToOTLP() returns OTLP resource and scope span payload", () => {
+		const payload = spansToOTLP(
+			[makeSpan({ id: "abc123", parentId: "def456", name: "tls.fetch" })],
+			{ "service.name": "connector-sdk-test" },
+		);
+
+		expect(payload).toEqual({
+			resourceSpans: [
+				{
+					resource: {
+						attributes: [
+							{
+								key: "service.name",
+								value: { stringValue: "connector-sdk-test" },
+							},
+						],
+					},
+					scopeSpans: [
+						{
+							scope: {
+								name: "apifuse-connector-sdk",
+								version: "0.1.0",
+							},
+							spans: [
+								{
+									attributes: [
+										{
+											key: "method",
+											value: { stringValue: "GET" },
+										},
+										{
+											key: "status",
+											value: { doubleValue: 200 },
+										},
+										{
+											key: "success",
+											value: { boolValue: true },
+										},
+									],
+									endTimeUnixNano: "1025000000",
+									kind: 2,
+									name: "tls.fetch",
+									parentSpanId: "0000000000def456",
+									spanId: "0000000000abc123",
+									startTimeUnixNano: "1000000000",
+									status: { code: 1 },
+									traceId: "00000000000000000000000000000001",
+								},
+							],
+						},
+					],
+				},
+			],
+		});
+	});
+
+	it("exportSpansOTLP() posts OTLP JSON with merged headers", async () => {
+		let requestUrl: string | undefined;
+		let requestInit: RequestInit | undefined;
+
+		global.fetch = mock(
+			async (url: string | URL | Request, init?: RequestInit) => {
+				requestUrl = typeof url === "string" ? url : url.toString();
+				requestInit = init;
+				return new Response(null, { status: 200 });
+			},
+		) as unknown as typeof fetch;
+
+		await exportSpansOTLP([makeSpan()], {
+			endpoint: "http://localhost:4318/v1/traces",
+			headers: { Authorization: "Bearer test" },
+			timeout: 100,
+		});
+
+		expect(requestUrl).toBe("http://localhost:4318/v1/traces");
+		expect(requestInit?.method).toBe("POST");
+		expect(requestInit?.headers).toEqual({
+			"Content-Type": "application/json",
+			Authorization: "Bearer test",
+		});
+		expect(JSON.parse(String(requestInit?.body))).toEqual(
+			spansToOTLP([makeSpan()]),
+		);
+	});
+
+	it("exportSpansOTLP() swallows fetch errors and warns", async () => {
+		const warn = mock(() => {});
+		console.warn = warn;
+		global.fetch = mock(async () => {
+			throw new Error("network down");
+		}) as unknown as typeof fetch;
+
+		await expect(
+			exportSpansOTLP([makeSpan()], {
+				endpoint: "http://localhost:4318/v1/traces",
+			}),
+		).resolves.toBeUndefined();
+
+		expect(warn).toHaveBeenCalledWith(
+			"[apifuse] OTLP export failed:",
+			"network down",
+		);
+	});
+});

package/src/__tests__/perf.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+	computePercentile,
+	computeStats,
+	groupSpansByName,
+} from "../runtime/perf";
+import type { Span } from "../runtime/trace";
+
+function makeSpan(name: string, duration_ms: number): Span {
+	return {
+		id: crypto.randomUUID(),
+		name,
+		startedAt: 1000,
+		endedAt: 1000 + duration_ms,
+		duration_ms,
+		status: "ok",
+		attributes: {},
+	};
+}
+
+describe("computePercentile", () => {
+	it("computes p50 correctly", () => {
+		expect(computePercentile([10, 20, 30, 40, 50], 50)).toBe(30);
+	});
+
+	it("computes p95 correctly", () => {
+		expect(computePercentile([10, 20, 30, 40, 50], 95)).toBe(48);
+	});
+
+	it("handles single element", () => {
+		expect(computePercentile([42], 99)).toBe(42);
+	});
+});
+
+describe("computeStats", () => {
+	it("returns p50/p95/p99/avg for sample data", () => {
+		expect(computeStats([10, 20, 30, 40, 50])).toEqual({
+			p50: 30,
+			p95: 48,
+			p99: 49.6,
+			avg: 30,
+			min: 10,
+			max: 50,
+		});
+	});
+});
+
+describe("groupSpansByName", () => {
+	it("groups spans across multiple runs", () => {
+		const grouped = groupSpansByName([
+			[makeSpan("tls.fetch", 100), makeSpan("transformResponse", 5)],
+			[makeSpan("tls.fetch", 120), makeSpan("normalizeRequest", 1)],
+		]);
+
+		expect(grouped.get("tls.fetch")).toEqual([100, 120]);
+		expect(grouped.get("transformResponse")).toEqual([5]);
+		expect(grouped.get("normalizeRequest")).toEqual([1]);
+	});
+});