@apifuse/provider-sdk 2.1.0-beta.1 → 2.1.0-beta.10

package/bin/apifuse-pack-smoke.ts

@@ -1,13 +1,20 @@
 #!/usr/bin/env bun
 
-import { execFileSync, spawnSync } from "node:child_process";
+import {
+	type ChildProcess,
+	execFileSync,
+	spawn,
+	spawnSync,
+} from "node:child_process";
 import {
 	existsSync,
 	mkdirSync,
 	mkdtempSync,
+	readFileSync,
 	rmSync,
 	writeFileSync,
 } from "node:fs";
+import { createServer } from "node:net";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { z } from "zod";
@@ -17,18 +24,34 @@ const PACK_RESULT_SCHEMA = z.array(
 		filename: z.string(),
 	}),
 );
+const HEALTH_RESPONSE_SCHEMA = z.object({
+	status: z.string(),
+	provider: z.string(),
+	version: z.string().optional(),
+});
+const PING_RESPONSE_SCHEMA = z.object({
+	data: z
+		.object({
+			ok: z.boolean(),
+			message: z.string(),
+		})
+		.optional(),
+	error: z.unknown().optional(),
+});
 
-const KEEP_TEMP = process.env.APIFUSE_PACK_SMOKE_KEEP_TEMP === "1";
+const KEEP_TEMP = process.env.APIFUSE__PACK_SMOKE__KEEP_TEMP === "1";
 
 const tempRoot = mkdtempSync(
 	join(tmpdir(), "apifuse-provider-sdk-pack-smoke-"),
 );
 const packDir = join(tempRoot, "pack");
 const consumerDir = join(tempRoot, "consumer");
+const externalWorkspaceDir = join(tempRoot, "external-workspace");
 
 try {
 	mkdirSync(packDir, { recursive: true });
 	mkdirSync(consumerDir, { recursive: true });
+	mkdirSync(join(externalWorkspaceDir, "providers"), { recursive: true });
 
 	const packed = packSdk(packDir);
 	const tarballPath = resolve(packDir, packed.filename);
@@ -72,7 +95,15 @@ try {
 
 	const generatedProviderDir = join(consumerDir, "dx-smoke");
 	run("bun", ["run", "check"], generatedProviderDir);
+	run("bun", ["run", "submit-check"], generatedProviderDir);
 	run("bun", ["run", "test"], generatedProviderDir);
+	assertGeneratedReadme(generatedProviderDir);
+	await smokeGeneratedDevServer(generatedProviderDir);
+	assertExternalWorkspaceTopology(
+		cliBin,
+		externalWorkspaceDir,
+		tarballSpecifier,
+	);
 
 	console.log(
 		`Provider SDK packed-artifact smoke passed: ${tarballPath} -> ${generatedProviderDir}`,
@@ -85,6 +116,103 @@ try {
 	}
 }
 
+function assertExternalWorkspaceTopology(
+	cliBin: string,
+	externalWorkspaceDir: string,
+	tarballSpecifier: string,
+): void {
+	writeFileSync(
+		join(externalWorkspaceDir, "package.json"),
+		`${JSON.stringify(
+			{
+				private: true,
+				type: "module",
+				workspaces: ["providers/*"],
+			},
+			null,
+			2,
+		)}\n`,
+	);
+
+	run(
+		"bun",
+		[
+			cliBin,
+			"create",
+			"external-workspace-smoke",
+			"--yes",
+			"--json",
+			"--sdk-specifier",
+			tarballSpecifier,
+		],
+		externalWorkspaceDir,
+	);
+
+	const generatedProviderDir = join(
+		externalWorkspaceDir,
+		"external-workspace-smoke",
+	);
+	const forbiddenProviderDir = join(
+		externalWorkspaceDir,
+		"providers",
+		"external-workspace-smoke",
+	);
+	if (!existsSync(generatedProviderDir)) {
+		throw new Error(
+			"Public create must generate a one-provider repository at <name>/ even when providers/ exists.",
+		);
+	}
+	if (existsSync(forbiddenProviderDir)) {
+		throw new Error(
+			"Public create must not generate providers/<name>/ in external bounty workspaces.",
+		);
+	}
+
+	const packageJson = JSON.parse(
+		readFileSync(join(generatedProviderDir, "package.json"), "utf8"),
+	);
+	const sdkDependency = packageJson?.dependencies?.["@apifuse/provider-sdk"];
+	if (sdkDependency !== tarballSpecifier) {
+		throw new Error(
+			`Expected generated provider to depend on packed SDK ${tarballSpecifier}, got ${sdkDependency}`,
+		);
+	}
+	if (JSON.stringify(packageJson).includes("workspace:")) {
+		throw new Error(
+			"External bounty workspace scaffold must not contain workspace: dependencies.",
+		);
+	}
+
+	run("bun", ["install"], generatedProviderDir);
+	run("bun", ["run", "check"], generatedProviderDir);
+	run("bun", ["run", "submit-check"], generatedProviderDir);
+	run("bun", ["run", "test"], generatedProviderDir);
+
+	const monorepoAttempt = spawnSync(
+		"bun",
+		[cliBin, "create", "bad-monorepo-smoke", "--preset", "monorepo", "--yes"],
+		{
+			cwd: externalWorkspaceDir,
+			env: { ...process.env, APIFUSE__SDK__SPECIFIER: tarballSpecifier },
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "pipe"],
+		},
+	);
+	if (monorepoAttempt.status === 0) {
+		throw new Error(
+			"--preset monorepo must reject outside the private APIFuse monorepo.",
+		);
+	}
+	const rejectionOutput = `${monorepoAttempt.stdout}\n${monorepoAttempt.stderr}`;
+	if (
+		!rejectionOutput.includes(
+			"Monorepo preset is internal to the APIFuse repository",
+		)
+	) {
+		throw new Error(`Unexpected monorepo rejection output: ${rejectionOutput}`);
+	}
+}
+
 function packSdk(destination: string): { filename: string } {
 	const raw = execFileSync(
 		"npm",
@@ -120,3 +248,176 @@ function run(command: string, args: string[], cwd: string): void {
 		);
 	}
 }
+
+function assertGeneratedReadme(providerDir: string): void {
+	const readme = readFileSync(join(providerDir, "README.md"), "utf8");
+	if (!readme.includes('"requestId":"req_local_ping"')) {
+		throw new Error(
+			"Generated README is missing requestId in local smoke docs.",
+		);
+	}
+	if (readme.includes('"connection":null')) {
+		throw new Error(
+			"Generated README must not document connection:null for no-auth local smoke.",
+		);
+	}
+	if (!readme.includes("bunx playwright install chromium")) {
+		throw new Error(
+			"Generated README is missing browser runtime troubleshooting guidance.",
+		);
+	}
+	if (!readme.includes("impit")) {
+		throw new Error(
+			"Generated README is missing impit stealth runtime guidance.",
+		);
+	}
+	if (!readme.includes("bun run submit-check")) {
+		throw new Error(
+			"Generated README must document the submit-check pre-submission workflow.",
+		);
+	}
+	if (!readme.includes("bun run record -- --operation <operation>")) {
+		throw new Error(
+			"Generated README must document fixture recording through the generated record script.",
+		);
+	}
+}
+
+async function smokeGeneratedDevServer(providerDir: string): Promise<void> {
+	const port = await getAvailablePort();
+	const server = spawn("bun", ["run", "dev"], {
+		cwd: providerDir,
+		env: { ...process.env, APIFUSE__RUNTIME__PORT: String(port) },
+		detached: process.platform !== "win32",
+		stdio: ["ignore", "pipe", "pipe"],
+	});
+	let output = "";
+	server.stdout?.on("data", (chunk) => {
+		output += chunk.toString();
+	});
+	server.stderr?.on("data", (chunk) => {
+		output += chunk.toString();
+	});
+
+	try {
+		const baseUrl = `http://127.0.0.1:${port}`;
+		await waitForHttp(`${baseUrl}/health`, server, () => output);
+
+		const health = await fetchJson(`${baseUrl}/health`, HEALTH_RESPONSE_SCHEMA);
+		if (health.status !== "ok" || health.provider !== "dx-smoke") {
+			throw new Error(`Unexpected /health payload: ${JSON.stringify(health)}`);
+		}
+
+		const response = await fetch(`${baseUrl}/v1/ping`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({
+				requestId: "req_pack_smoke_ping",
+				input: { value: "hello" },
+				headers: {},
+			}),
+		});
+		const payload = PING_RESPONSE_SCHEMA.parse(await response.json());
+
+		if (!response.ok || payload.data?.ok !== true) {
+			throw new Error(
+				`Unexpected /v1/ping response (${response.status}): ${JSON.stringify(payload)}`,
+			);
+		}
+	} finally {
+		await stopServer(server);
+	}
+}
+
+async function getAvailablePort(): Promise<number> {
+	return await new Promise((resolvePromise, rejectPromise) => {
+		const server = createServer();
+		server.once("error", rejectPromise);
+		server.listen(0, "127.0.0.1", () => {
+			const address = server.address();
+			server.close((error) => {
+				if (error) {
+					rejectPromise(error);
+					return;
+				}
+				if (!address || typeof address === "string") {
+					rejectPromise(new Error("Could not allocate a local TCP port."));
+					return;
+				}
+				resolvePromise(address.port);
+			});
+		});
+	});
+}
+
+async function fetchJson<T>(url: string, schema: z.ZodType<T>): Promise<T> {
+	const response = await fetch(url);
+	if (!response.ok) {
+		throw new Error(`${url} returned ${response.status}`);
+	}
+	return schema.parse(await response.json());
+}
+
+async function waitForHttp(
+	url: string,
+	server: ChildProcess,
+	getOutput: () => string,
+): Promise<void> {
+	const deadline = Date.now() + 10_000;
+	let lastError: unknown;
+
+	while (Date.now() < deadline) {
+		if (server.exitCode !== null) {
+			throw new Error(
+				`Dev server exited early with code ${server.exitCode}\n${getOutput()}`,
+			);
+		}
+
+		try {
+			await fetchJson(url, HEALTH_RESPONSE_SCHEMA);
+			return;
+		} catch (error) {
+			lastError = error;
+			await new Promise((resolve) => setTimeout(resolve, 200));
+		}
+	}
+
+	throw new Error(
+		`Timed out waiting for ${url}: ${lastError instanceof Error ? lastError.message : String(lastError)}\n${getOutput()}`,
+	);
+}
+
+async function stopServer(server: ChildProcess): Promise<void> {
+	if (server.exitCode !== null) {
+		return;
+	}
+	killProcessTree(server, "SIGTERM");
+	await new Promise<void>((resolvePromise) => {
+		const timeout = setTimeout(() => {
+			if (server.exitCode === null) {
+				killProcessTree(server, "SIGKILL");
+			}
+			resolvePromise();
+		}, 2_000);
+		server.once("exit", () => {
+			clearTimeout(timeout);
+			resolvePromise();
+		});
+	});
+}
+
+function killProcessTree(server: ChildProcess, signal: NodeJS.Signals): void {
+	if (server.pid === undefined) {
+		return;
+	}
+
+	try {
+		if (process.platform === "win32") {
+			server.kill(signal);
+			return;
+		}
+		process.kill(-server.pid, signal);
+	} catch {
+		server.kill(signal);
+	}
+}

package/bin/apifuse-perf.ts

@@ -8,8 +8,11 @@ import { pathToFileURL } from "node:url";
 
 import {
 	type ApiFuseConfig,
+	createBypassProviderCache,
 	createHttpClient,
-	createTlsClient,
+	createProviderChoiceContext,
+	createStealthClient,
+	createSttClientFromEnv,
 	executeOperation,
 	getProviderBaseUrl,
 	type HttpClient,
@@ -18,8 +21,8 @@ import {
 	type ProviderDefinition,
 	ProviderError,
 	type Span,
-	type TlsClient,
-	type TlsResponse,
+	type StealthClient,
+	type StealthResponse,
 	wrapWithInstrumentation,
 } from "../src";
 import {
@@ -27,6 +30,7 @@ import {
 	groupSpansByName,
 	type PerfStats,
 } from "../src/runtime/perf";
+import { createMemoryProviderRuntimeState } from "../src/runtime/state";
 import {
 	createTraceContext,
 	resolveTraceContextOptions,
@@ -41,6 +45,7 @@ type CliArgs = {
 	exportPath?: string;
 	flame: boolean;
 	operation: string;
+	params?: string;
 	runs: number;
 	warmup: number;
 };
@@ -79,6 +84,21 @@ const DEFAULT_RUNS = 10;
 const DEFAULT_WARMUP = 2;
 const DEFAULT_CONCURRENCY = 1;
 const BAR_WIDTH = 20;
+const HELP_TEXT = `Usage: apifuse perf <provider-path> --operation <operation> [options]
+
+Options:
+  --operation, -o <name>   operation to profile (required)
+  --params, -p <json>      JSON input template; falls back to fixtures.request or {}
+  --runs, -n <number>      number of runs (default: 10)
+  --warmup <number>        warmup runs (default: 2)
+  --concurrency, -c <n>    concurrent requests (default: 1)
+  --compare-proxy          run with proxy on/off and compare
+  --export <path>          export results to JSON file
+  --flame                  generate flamegraph SVG
+  --help, -h               show this help
+
+Example:
+  apifuse perf providers/korea-air-quality --operation realtime --params '{"stationName":"jongno"}' --runs 5`;
 
 export async function main() {
 	try {
@@ -92,7 +112,11 @@ export async function main() {
 		const inputSchema = getOperationSchema(provider, operation, "input");
 		const outputSchema = getOperationSchema(provider, operation, "output");
 		const fixtureReplay = await loadFixtureReplay(providerDirectory);
-		const inputTemplate = resolveInputTemplate(provider, inputSchema);
+		const inputTemplate = resolveInputTemplate(
+			provider,
+			inputSchema,
+			args.params,
+		);
 
 		const directSuite = await runProfileSuite({
 			args,
@@ -182,6 +206,7 @@ function parseArgs(argv: string[]): CliArgs {
 	let compareProxy = false;
 	let exportPath: string | undefined;
 	let flame = false;
+	let params: string | undefined;
 
 	for (let index = 0; index < argv.length; index += 1) {
 		const arg = argv[index];
@@ -199,6 +224,11 @@ function parseArgs(argv: string[]): CliArgs {
 			continue;
 		}
 
+		if (arg === "--help" || arg === "-h") {
+			console.log(HELP_TEXT);
+			process.exit(0);
+		}
+
 		if (arg === "--compare-proxy") {
 			compareProxy = true;
 			continue;
@@ -220,6 +250,22 @@ function parseArgs(argv: string[]): CliArgs {
 			continue;
 		}
 
+		if (arg === "--params" || arg === "-p") {
+			params = requireArgValue(argv, index, arg);
+			index += 1;
+			continue;
+		}
+
+		if (arg.startsWith("--params=")) {
+			params = arg.slice("--params=".length);
+			continue;
+		}
+
+		if (arg.startsWith("-p=")) {
+			params = arg.slice("-p=".length);
+			continue;
+		}
+
 		if (arg.startsWith("-o=")) {
 			operation = arg.slice("-o=".length);
 			continue;
@@ -292,20 +338,7 @@ function parseArgs(argv: string[]): CliArgs {
 	}
 
 	if (!providerPath || !operation) {
-		throw new Error(
-			[
-				"Usage: apifuse perf <provider-path> [options]",
-				"",
-				"Options:",
-				"  --operation, -o <name>   operation to profile (required)",
-				"  --runs, -n <number>      number of runs (default: 10)",
-				"  --warmup <number>        warmup runs (default: 2)",
-				"  --concurrency, -c <n>    concurrent requests (default: 1)",
-				"  --compare-proxy          run with proxy on/off and compare",
-				"  --export <path>          export results to JSON file",
-				"  --flame                  generate flamegraph SVG",
-			].join("\n"),
-		);
+		throw new Error(HELP_TEXT);
 	}
 
 	return {
@@ -315,6 +348,7 @@ function parseArgs(argv: string[]): CliArgs {
 		exportPath,
 		flame,
 		operation,
+		params,
 		runs,
 		warmup,
 	};
@@ -409,7 +443,18 @@ function isSchema(value: unknown): value is { parse(input: unknown): unknown } {
 function resolveInputTemplate(
 	provider: ProviderDefinition,
 	inputSchema: { parse(input: unknown): unknown },
+	params: string | undefined,
 ): unknown {
+	if (params !== undefined) {
+		try {
+			return inputSchema.parse(JSON.parse(params));
+		} catch (error) {
+			throw new Error(
+				`Failed to parse --params JSON or validate input: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
+	}
+
 	const firstOp = Object.values(provider.operations)[0];
 	if (firstOp?.fixtures?.request !== undefined) {
 		return firstOp.fixtures.request;
@@ -440,12 +485,12 @@ async function loadFixtureReplay(
 }
 
 function assertProxyConfigured(config: ApiFuseConfig): void {
-	if (config.proxy?.url || process.env.APIFUSE_PROXY_URL) {
+	if (config.proxy?.url || process.env.APIFUSE__PROXY__URL) {
 		return;
 	}
 
 	throw new Error(
-		"--compare-proxy requires a proxy URL in apifuse.config.ts or APIFUSE_PROXY_URL.",
+		"--compare-proxy requires a proxy URL in apifuse.config.ts or APIFUSE__PROXY__URL.",
 	);
 }
 
@@ -637,30 +682,44 @@ function createBaseContext(options: {
 					apifuseConfig,
 					upstream,
 				});
-	const tls =
+	const stealth =
 		options.forceFixtureReplay && options.fixtureReplay
-			? createFixtureTlsClient(options.fixtureReplay.rawText)
-			: createTlsClient(getProviderBaseUrl(options.provider), {
+			? createFixtureStealthClient(options.fixtureReplay.rawText)
+			: createStealthClient(getProviderBaseUrl(options.provider), {
 					apifuseConfig,
 					upstream,
 				});
 
+	const env = {
+		get: (key: string) => process.env[key],
+	};
+	const credential = {
+		mode: "none" as const,
+		get: () => undefined,
+		getAll: () => ({}),
+		getAccessToken: () => undefined,
+		getScopes: () => [],
+	};
+	const state = createMemoryProviderRuntimeState();
 	return {
-		env: {
-			get: (key: string) => process.env[key],
-		},
-		credential: {
-			mode: "none",
-			get: () => undefined,
-			getAll: () => ({}),
-			getAccessToken: () => undefined,
-			getScopes: () => [],
-		},
+		env,
+		credential,
+		request: { headers: {} },
 		http,
-		tls,
+		cache: createBypassProviderCache({ providerId: options.provider.id }),
+		state,
+		stealth,
 		browser: createBrowserStub(),
 		trace: options.traceContext,
 		auth: createAuthStub(),
+		stt: createSttClientFromEnv(options.provider.stt),
+		choice: createProviderChoiceContext({
+			providerId: options.provider.id,
+			env,
+			request: { headers: {} },
+			credential,
+			state,
+		}),
 	};
 }
 
@@ -695,16 +754,25 @@ function createFixtureResponse(raw: unknown) {
 	};
 }
 
-function createFixtureTlsClient(rawText: string): TlsClient {
-	const createResponse = async (): Promise<TlsResponse> => ({
-		status: 200,
-		ok: true,
-		headers: { "content-type": "application/json" },
-		rawHeaders: [["content-type", "application/json"]],
-		body: rawText,
-		cookies: { get: () => undefined, getAll: () => ({}), toString: () => "" },
-		json: async <T>() => JSON.parse(rawText) as T,
-	});
+function createFixtureStealthClient(rawText: string): StealthClient {
+	const createResponse = async (): Promise<StealthResponse> => {
+		const bodyBytes = new TextEncoder().encode(rawText);
+		return {
+			status: 200,
+			ok: true,
+			headers: { "content-type": "application/json" },
+			rawHeaders: [["content-type", "application/json"]],
+			body: rawText,
+			cookies: { get: () => undefined, getAll: () => ({}), toString: () => "" },
+			json: async <T>() => JSON.parse(rawText) as T,
+			arrayBuffer: async () =>
+				bodyBytes.buffer.slice(
+					bodyBytes.byteOffset,
+					bodyBytes.byteOffset + bodyBytes.byteLength,
+				) as ArrayBuffer,
+			bytes: async () => new Uint8Array(bodyBytes),
+		};
+	};
 
 	return {
 		fetch: async () => createResponse(),
@@ -720,6 +788,7 @@ function createFixtureTlsClient(rawText: string): TlsClient {
 function createBrowserStub(): BrowserClient {
 	return {
 		engine: "playwright-stealth",
+		async close() {},
 		async newPage() {
 			throw new ProviderError(
 				"Browser runtime is not supported by apifuse perf yet.",
@@ -728,6 +797,30 @@ function createBrowserStub(): BrowserClient {
 				},
 			);
 		},
+		async rawPage() {
+			throw new ProviderError(
+				"Browser runtime is not supported by apifuse perf yet.",
+				{
+					code: "BROWSER_RUNTIME_UNSUPPORTED",
+				},
+			);
+		},
+		async withIsolatedContext() {
+			throw new ProviderError(
+				"Browser runtime is not supported by apifuse perf yet.",
+				{
+					code: "BROWSER_RUNTIME_UNSUPPORTED",
+				},
+			);
+		},
+		async solveChallenge() {
+			throw new ProviderError(
+				"Browser runtime is not supported by apifuse perf yet.",
+				{
+					code: "BROWSER_RUNTIME_UNSUPPORTED",
+				},
+			);
+		},
 	};
 }
 
@@ -738,7 +831,7 @@ function buildInsights(
 ): string[] {
 	const insights: string[] = [];
 	const allSpans = runs.flatMap((run) => run.spans);
-	const tlsSpans = allSpans.filter((span) => span.name === "tls.fetch");
+	const stealthSpans = allSpans.filter((span) => span.name === "stealth.fetch");
 	const dnsSpans = allSpans.filter((span) => span.name === "dns");
 	const transform = breakdown.find(
 		(entry) => entry.name === "transformResponse",
@@ -746,7 +839,7 @@ function buildInsights(
 	const responseSizes = allSpans
 		.map((span) => span.attributes.response_size)
 		.filter((value): value is number => typeof value === "number");
-	const reuseFlags = tlsSpans
+	const reuseFlags = stealthSpans
 		.map((span) => span.attributes.connection_reused)
 		.filter((value): value is boolean => typeof value === "boolean");
 
@@ -756,8 +849,8 @@ function buildInsights(
 		);
 		insights.push(
 			reusePercent >= 80
-				? `✓ TLS connection reuse: ${reusePercent}% (good)`
-				: `⚠ TLS connection reuse: ${reusePercent}% — consider session reuse`,
+				? `✓ Stealth connection reuse: ${reusePercent}% (good)`
+				: `⚠ Stealth connection reuse: ${reusePercent}% — consider session reuse`,
 		);
 	}
 
@@ -1091,7 +1184,7 @@ function cloneValue<T>(value: T): T {
 
 function handleCliError(error: unknown): never {
 	const message = error instanceof Error ? error.message : String(error);
-	console.error(message);
+	console.error(`[apifuse perf] ${message}`);
 	process.exit(1);
 }