@apifuse/connector-sdk 2.0.0-beta.1

package/src/__tests__/waterfall.test.ts

@@ -0,0 +1,270 @@
+import { describe, expect, it } from "bun:test";
+
+import type { Span } from "../runtime/trace";
+import { renderWaterfall, type WaterfallRequest } from "../runtime/waterfall";
+
+function assertDefined<T>(value: T | null | undefined, message?: string): T {
+	if (value === null || value === undefined) {
+		throw new Error(message ?? "Expected value to be defined");
+	}
+
+	return value;
+}
+
+function makeSpan(overrides: Partial<Span> & { name: string }): Span {
+	return {
+		id: crypto.randomUUID(),
+		name: overrides.name,
+		startedAt: overrides.startedAt ?? 1000,
+		endedAt: overrides.endedAt ?? 1100,
+		duration_ms: overrides.duration_ms ?? 100,
+		status: overrides.status ?? "ok",
+		attributes: overrides.attributes ?? {},
+		...(overrides.parentId ? { parentId: overrides.parentId } : {}),
+		...(overrides.error ? { error: overrides.error } : {}),
+		...(overrides.id ? { id: overrides.id } : {}),
+	};
+}
+
+const defaultRequest: WaterfallRequest = {
+	method: "GET",
+	path: "/v1/coingecko/prices",
+	status: 200,
+	totalMs: 289,
+};
+
+describe("renderWaterfall", () => {
+	it("renders span name and duration", () => {
+		const rootSpan = makeSpan({
+			id: "root-1",
+			name: "prices",
+			startedAt: 1000,
+			endedAt: 1289,
+			duration_ms: 289,
+		});
+
+		const child = makeSpan({
+			name: "normalizeRequest",
+			parentId: "root-1",
+			startedAt: 1000,
+			endedAt: 1001,
+			duration_ms: 0.1,
+		});
+
+		const output = renderWaterfall([rootSpan, child], defaultRequest);
+
+		expect(output).toContain("prices");
+		expect(output).toContain("289ms");
+		expect(output).toContain("normalizeRequest");
+		expect(output).toContain("0.1ms");
+	});
+
+	it("indents child spans", () => {
+		const root = makeSpan({
+			id: "root-1",
+			name: "prices",
+			startedAt: 1000,
+			endedAt: 1289,
+			duration_ms: 289,
+		});
+
+		const parent = makeSpan({
+			id: "parent-1",
+			name: "tls.fetch",
+			parentId: "root-1",
+			startedAt: 1001,
+			endedAt: 1286,
+			duration_ms: 285,
+		});
+
+		const child = makeSpan({
+			name: "dns",
+			parentId: "parent-1",
+			startedAt: 1001,
+			endedAt: 1012,
+			duration_ms: 11.3,
+		});
+
+		const output = renderWaterfall([root, parent, child], defaultRequest);
+
+		const lines = output.split("\n");
+
+		const tlsFetchLine = lines.find((l) => l.includes("tls.fetch"));
+		const dnsLine = lines.find((l) => l.includes("dns"));
+
+		expect(tlsFetchLine).toBeDefined();
+		expect(dnsLine).toBeDefined();
+
+		const stripAnsi = (s: string) =>
+			s.replace(new RegExp("\\u001b\\[[0-9;]*m", "g"), "");
+		const tlsFetchPos = stripAnsi(assertDefined(tlsFetchLine)).indexOf("├─");
+		const dnsPos = stripAnsi(assertDefined(dnsLine)).indexOf("└─");
+
+		expect(dnsPos).toBeGreaterThan(tlsFetchPos);
+	});
+
+	it("marks slow spans yellow", () => {
+		const root = makeSpan({
+			id: "root-1",
+			name: "prices",
+			startedAt: 1000,
+			endedAt: 1600,
+			duration_ms: 600,
+		});
+
+		const slowChild = makeSpan({
+			name: "tls.fetch",
+			parentId: "root-1",
+			startedAt: 1000,
+			endedAt: 1600,
+			duration_ms: 600,
+		});
+
+		const output = renderWaterfall(
+			[root, slowChild],
+			{
+				...defaultRequest,
+				totalMs: 600,
+			},
+			{ slowThresholdMs: 500 },
+		);
+
+		expect(output).toContain("\x1b[33m");
+	});
+
+	it("marks error spans red", () => {
+		const root = makeSpan({
+			id: "root-1",
+			name: "prices",
+			startedAt: 1000,
+			endedAt: 1100,
+			duration_ms: 100,
+			status: "error",
+			error: "Network failure",
+		});
+
+		const output = renderWaterfall([root], {
+			...defaultRequest,
+			status: 500,
+			totalMs: 100,
+		});
+
+		expect(output).toContain("\x1b[31m");
+	});
+
+	it("marks bottleneck with star", () => {
+		const root = makeSpan({
+			id: "root-1",
+			name: "prices",
+			startedAt: 1000,
+			endedAt: 1289,
+			duration_ms: 289,
+		});
+
+		const fast = makeSpan({
+			name: "normalizeRequest",
+			parentId: "root-1",
+			startedAt: 1000,
+			endedAt: 1001,
+			duration_ms: 0.1,
+		});
+
+		const slow = makeSpan({
+			name: "tls.fetch",
+			parentId: "root-1",
+			startedAt: 1001,
+			endedAt: 1286,
+			duration_ms: 285,
+		});
+
+		const transform = makeSpan({
+			name: "transformResponse",
+			parentId: "root-1",
+			startedAt: 1286,
+			endedAt: 1289,
+			duration_ms: 3.2,
+		});
+
+		const output = renderWaterfall(
+			[root, fast, slow, transform],
+			defaultRequest,
+		);
+
+		const lines = output.split("\n");
+		const tlsFetchLine = lines.find((l) => l.includes("tls.fetch"));
+		expect(tlsFetchLine).toContain("★");
+
+		const normalizeLine = lines.find((l) => l.includes("normalizeRequest"));
+		expect(normalizeLine).not.toContain("★");
+	});
+
+	it("returns empty string for no spans", () => {
+		const output = renderWaterfall([], defaultRequest);
+		expect(output).toBe("");
+	});
+
+	it("renders status line with method and path", () => {
+		const root = makeSpan({
+			id: "root-1",
+			name: "prices",
+			duration_ms: 100,
+		});
+
+		const output = renderWaterfall([root], defaultRequest);
+
+		expect(output).toContain("GET");
+		expect(output).toContain("/v1/coingecko/prices");
+		expect(output).toContain("200");
+		expect(output).toContain("OK");
+	});
+
+	it("renders timing bars proportional to total duration", () => {
+		const root = makeSpan({
+			id: "root-1",
+			name: "op",
+			startedAt: 1000,
+			endedAt: 1200,
+			duration_ms: 200,
+		});
+
+		const half = makeSpan({
+			name: "half",
+			parentId: "root-1",
+			startedAt: 1000,
+			endedAt: 1100,
+			duration_ms: 100,
+		});
+
+		const full = makeSpan({
+			name: "full",
+			parentId: "root-1",
+			startedAt: 1100,
+			endedAt: 1200,
+			duration_ms: 200,
+		});
+
+		const output = renderWaterfall(
+			[root, half, full],
+			{
+				...defaultRequest,
+				totalMs: 200,
+			},
+			{ maxBarWidth: 20 },
+		);
+
+		const stripAnsi = (s: string) =>
+			s.replace(new RegExp("\\u001b\\[[0-9;]*m", "g"), "");
+		const lines = output.split("\n").map(stripAnsi);
+
+		const halfLine = lines.find(
+			(l) => l.includes("half") && !l.includes("full"),
+		);
+		const fullLine = lines.find((l) => l.includes("full"));
+
+		const countBars = (s: string) => (s.match(/━/g) ?? []).length;
+		const halfBars = countBars(halfLine ?? "");
+		const fullBars = countBars(fullLine ?? "");
+
+		expect(fullBars).toBeGreaterThan(halfBars);
+	});
+});

package/src/config/connectors-yaml.ts

@@ -0,0 +1,373 @@
+import { readFile } from "node:fs/promises";
+
+import { z } from "zod";
+
+import { SDKError, ValidationError } from "../errors";
+
+type YamlObject = Record<string, unknown>;
+
+function stripInlineComment(line: string): string {
+	let inSingleQuote = false;
+	let inDoubleQuote = false;
+
+	for (let index = 0; index < line.length; index += 1) {
+		const char = line[index];
+
+		if (char === "'" && !inDoubleQuote) {
+			inSingleQuote = !inSingleQuote;
+			continue;
+		}
+
+		if (char === '"' && !inSingleQuote) {
+			inDoubleQuote = !inDoubleQuote;
+			continue;
+		}
+
+		if (char === "#" && !inSingleQuote && !inDoubleQuote) {
+			return line.slice(0, index).trimEnd();
+		}
+	}
+
+	return line;
+}
+
+function parseQuotedString(value: string): string {
+	if (
+		(value.startsWith('"') && value.endsWith('"')) ||
+		(value.startsWith("'") && value.endsWith("'"))
+	) {
+		return value.slice(1, -1);
+	}
+
+	return value;
+}
+
+function splitFlowArrayItems(value: string): string[] {
+	const items: string[] = [];
+	let current = "";
+	let inSingleQuote = false;
+	let inDoubleQuote = false;
+
+	for (let index = 0; index < value.length; index += 1) {
+		const char = value[index];
+
+		if (char === "'" && !inDoubleQuote) {
+			inSingleQuote = !inSingleQuote;
+			current += char;
+			continue;
+		}
+
+		if (char === '"' && !inSingleQuote) {
+			inDoubleQuote = !inDoubleQuote;
+			current += char;
+			continue;
+		}
+
+		if (char === "," && !inSingleQuote && !inDoubleQuote) {
+			items.push(current.trim());
+			current = "";
+			continue;
+		}
+
+		current += char;
+	}
+
+	if (current.trim()) {
+		items.push(current.trim());
+	}
+
+	return items;
+}
+
+function parseYamlScalar(value: string): unknown {
+	if (value === "{}") {
+		return {};
+	}
+
+	if (value === "[]") {
+		return [];
+	}
+
+	if (value.startsWith("[") && value.endsWith("]")) {
+		const inner = value.slice(1, -1).trim();
+		if (!inner) {
+			return [];
+		}
+
+		return splitFlowArrayItems(inner).map((item) => parseYamlScalar(item));
+	}
+
+	if (value === "true") {
+		return true;
+	}
+
+	if (value === "false") {
+		return false;
+	}
+
+	if (/^-?\d+$/.test(value)) {
+		return Number.parseInt(value, 10);
+	}
+
+	return parseQuotedString(value);
+}
+
+function parseYamlObject(yamlContent: string): YamlObject {
+	const root: YamlObject = {};
+	const stack: Array<{ container: YamlObject; indent: number }> = [
+		{ container: root, indent: -1 },
+	];
+
+	for (const rawLine of yamlContent.split(/\r?\n/u)) {
+		const withoutComment = stripInlineComment(rawLine);
+		if (!withoutComment.trim()) {
+			continue;
+		}
+
+		const indent = withoutComment.match(/^\s*/u)?.[0].length ?? 0;
+		const line = withoutComment.trim();
+		const separatorIndex = line.indexOf(":");
+
+		if (separatorIndex === -1) {
+			throw new Error(`Invalid YAML line: ${rawLine}`);
+		}
+
+		const key = line.slice(0, separatorIndex).trim();
+		const rawValue = line.slice(separatorIndex + 1).trim();
+
+		while (stack.length > 1 && indent <= stack[stack.length - 1]?.indent) {
+			stack.pop();
+		}
+
+		const parent = stack[stack.length - 1]?.container;
+		if (!parent) {
+			throw new Error(`Could not resolve YAML parent for line: ${rawLine}`);
+		}
+
+		if (!rawValue) {
+			const child: YamlObject = {};
+			parent[key] = child;
+			stack.push({ container: child, indent });
+			continue;
+		}
+
+		parent[key] = parseYamlScalar(rawValue);
+	}
+
+	return root;
+}
+
+const PoolSizeRangeInputSchema = z
+	.string()
+	.regex(/^\d+\.\.\d+$/, "pool-size must use min..max format")
+	.transform((value, ctx) => {
+		const [minRaw, maxRaw] = value.split("..");
+		const min = Number.parseInt(minRaw, 10);
+		const max = Number.parseInt(maxRaw, 10);
+
+		if (min > max) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				message: "pool-size min must be less than or equal to max",
+			});
+			return z.NEVER;
+		}
+
+		return { max, min };
+	});
+
+const PoolSizeRangeSchema = z.object({
+	max: z.number().int(),
+	min: z.number().int(),
+});
+
+const SecurityOverrideSchema = z
+	.object({
+		"read-only-rootfs": z.boolean().optional(),
+		"no-new-privileges": z.boolean().optional(),
+		egress: z.array(z.string()).optional(),
+		env: z.array(z.string()).optional(),
+	})
+	.passthrough();
+
+const ContainerOverrideSchema = z
+	.object({
+		image: z.string().optional(),
+		memory: z.string().optional(),
+		cpu: z.string().optional(),
+		timeout: z.string().optional(),
+		"restart-policy": z.enum(["on-failure", "always", "never"]).optional(),
+		"max-restarts": z.number().int().optional(),
+	})
+	.passthrough();
+
+const CdpOverrideSchema = z
+	.object({
+		"pool-size": PoolSizeRangeInputSchema,
+		"page-timeout": z.string().optional(),
+		"pages-per-instance": z.number().int().optional(),
+		"idle-timeout": z.string().optional(),
+		"chrome-flags": z.array(z.string()).optional(),
+	})
+	.passthrough();
+
+const DefaultsSchema = z
+	.object({
+		container: ContainerOverrideSchema.optional(),
+		security: SecurityOverrideSchema.optional(),
+	})
+	.passthrough();
+
+const ConnectorConfigOverrideSchema = z
+	.object({
+		container: ContainerOverrideSchema.optional(),
+		runtime: z.enum(["standard", "browser"]).optional(),
+		replicas: z.number().int().optional(),
+		security: SecurityOverrideSchema.optional(),
+		cdp: CdpOverrideSchema.optional(),
+	})
+	.passthrough();
+
+export const SecuritySchema = z
+	.object({
+		"read-only-rootfs": z.boolean().default(true),
+		"no-new-privileges": z.boolean().default(true),
+		egress: z.array(z.string()).optional(),
+		env: z.array(z.string()).optional(),
+	})
+	.passthrough();
+
+export const ContainerSchema = z
+	.object({
+		image: z.string().default("auto"),
+		memory: z.string().default("256Mi"),
+		cpu: z.string().default("250m"),
+		timeout: z.string().default("30s"),
+		"restart-policy": z
+			.enum(["on-failure", "always", "never"])
+			.default("on-failure"),
+		"max-restarts": z.number().int().default(3),
+	})
+	.passthrough();
+
+export const CdpSchema = z
+	.object({
+		"pool-size": PoolSizeRangeSchema,
+		"page-timeout": z.string().default("120s"),
+		"pages-per-instance": z.number().int().default(4),
+		"idle-timeout": z.string().default("5m"),
+		"chrome-flags": z.array(z.string()).optional(),
+	})
+	.passthrough();
+
+export const ConnectorConfigSchema = z
+	.object({
+		container: ContainerSchema,
+		runtime: z.enum(["standard", "browser"]).default("standard"),
+		replicas: z.number().int().default(1),
+		security: SecuritySchema,
+		cdp: CdpSchema.optional(),
+	})
+	.passthrough();
+
+export const ConnectorsYamlSchema = z
+	.object({
+		defaults: DefaultsSchema.optional(),
+		connectors: z.record(z.string(), ConnectorConfigOverrideSchema),
+	})
+	.passthrough();
+
+export type PoolSizeRange = z.infer<typeof PoolSizeRangeSchema>;
+export type ConnectorsYaml = z.infer<typeof ConnectorsYamlSchema>;
+export type ConnectorConfig = z.infer<typeof ConnectorConfigSchema>;
+
+function toValidationError(error: unknown): ValidationError {
+	if (error instanceof z.ZodError) {
+		return new ValidationError("Invalid connectors.yaml configuration", {
+			code: "INVALID_CONNECTORS_YAML",
+			fix: "Match the connectors.yaml schema from openspec/connector-sdk/08-infrastructure.md §8.2.",
+			zodError: error,
+		});
+	}
+
+	return new ValidationError("Invalid connectors.yaml configuration", {
+		code: "INVALID_CONNECTORS_YAML",
+		cause: error instanceof Error ? error : undefined,
+		fix: "Check connectors.yaml syntax and field values.",
+	});
+}
+
+export function parseConnectorsYaml(yamlContent: string): ConnectorsYaml {
+	try {
+		const parsed = parseYamlObject(yamlContent);
+		return ConnectorsYamlSchema.parse(parsed);
+	} catch (error) {
+		if (error instanceof z.ZodError) {
+			throw toValidationError(error);
+		}
+
+		throw new SDKError("Failed to parse connectors.yaml", {
+			code: "CONNECTORS_YAML_PARSE_FAILED",
+			cause: error instanceof Error ? error : undefined,
+			fix: "Ensure connectors.yaml contains valid YAML.",
+		});
+	}
+}
+
+export async function loadConnectorsYaml(
+	filePath: string,
+): Promise<ConnectorsYaml> {
+	try {
+		const yamlContent = await readFile(filePath, "utf8");
+		return parseConnectorsYaml(yamlContent);
+	} catch (error) {
+		if (error instanceof SDKError || error instanceof ValidationError) {
+			throw error;
+		}
+
+		throw new SDKError(`Failed to load connectors.yaml from ${filePath}`, {
+			code: "CONNECTORS_YAML_LOAD_FAILED",
+			cause: error instanceof Error ? error : undefined,
+			fix: "Verify the file exists and is readable.",
+		});
+	}
+}
+
+export function resolveConnectorConfig(
+	yaml: ConnectorsYaml,
+	connectorId: string,
+): ConnectorConfig {
+	const connectorOverride = yaml.connectors[connectorId];
+
+	if (!connectorOverride) {
+		throw new SDKError(
+			`Connector "${connectorId}" not found in connectors.yaml`,
+			{
+				code: "CONNECTOR_NOT_FOUND",
+				fix: `Add ${connectorId} under connectors: in connectors.yaml.`,
+			},
+		);
+	}
+
+	const container = ContainerSchema.parse({
+		...yaml.defaults?.container,
+		...connectorOverride.container,
+	});
+
+	const security = SecuritySchema.parse({
+		...yaml.defaults?.security,
+		...connectorOverride.security,
+	});
+
+	const resolved = {
+		container,
+		security,
+		runtime: connectorOverride.runtime ?? "standard",
+		replicas: connectorOverride.replicas ?? 1,
+		cdp: connectorOverride.cdp
+			? CdpSchema.parse(connectorOverride.cdp)
+			: undefined,
+	};
+
+	return ConnectorConfigSchema.parse(resolved);
+}