@andrewheberle/serverless-ssh-ca-testing 0.0.0-stage → 0.20.1

package/src/log.ts

@@ -0,0 +1,98 @@
+import { appendFileSync } from "node:fs"
+import z from "zod"
+import { formatRequest, formatValue } from "./format.js"
+
+/**
+ * Messages the CA logs at error level when it has failed rather than rejected
+ * a request, see {@link isFault}.
+ */
+export const FAULT_MESSAGES: readonly string[] = ["unhandled error", "unexpected error from router"]
+
+/**
+ * The message of the line written by {@link LogFile.write} after a CA log line
+ * that indicates a fault.
+ */
+export const FAULT_MESSAGE = "harness fault"
+
+// the fields of a CA log line used to detect faults
+const LogLineSchema = z.object({
+	level: z.string(),
+	message: z.string(),
+})
+
+/**
+ * Report whether a line logged by the CA indicates a fault, such as a database
+ * error, rather than an expected rejection of a request. Some faults are only
+ * logged, as the CA still issues a certificate when it cannot record it.
+ *
+ * @param line A line of output from the CA
+ * @returns true if the line is an error logged by the CA for a fault
+ */
+export const isFault = (line: string): boolean => {
+	let json: unknown
+	try {
+		json = JSON.parse(line)
+	} catch {
+		return false
+	}
+
+	const result = LogLineSchema.safeParse(json)
+	if (!result.success || result.data.level.toLowerCase() !== "error") {
+		return false
+	}
+
+	return FAULT_MESSAGES.includes(result.data.message) || result.data.message.includes("database")
+}
+
+/**
+ * The log file of a test server, written as JSON lines.
+ *
+ * Lines from the CA are written as they are logged. The harness adds the
+ * following lines, whose messages all start with "harness":
+ *
+ * - `{"level":"info","message":"harness request",...}` for each request, with
+ *   `method`, `url`, `status` and, when `status` is 400 or more, the response
+ *   `body`.
+ * - `{"level":"error","message":"harness ...",...}` for a fault in the CA or
+ *   harness. A CA log line that indicates a fault (see {@link isFault}) is
+ *   followed by a line with the message {@link FAULT_MESSAGE}.
+ */
+export class LogFile {
+	readonly path: string
+
+	constructor(path: string) {
+		this.path = path
+	}
+
+	/**
+	 * Append a line of output from the CA, followed by a fault line if it
+	 * indicates a fault.
+	 */
+	write(line: string): void {
+		this.append(line)
+		if (isFault(line)) {
+			this.append(formatValue({ level: "error", message: FAULT_MESSAGE, line }))
+		}
+	}
+
+	/**
+	 * Append a request handled by the CA.
+	 */
+	request(method: string, url: string, status: number, body: string): void {
+		this.append(formatRequest(method, url, status, body))
+	}
+
+	/**
+	 * Append a fault in the harness.
+	 *
+	 * @param message A description of the fault, which is prefixed with "harness"
+	 * @param error The error that caused the fault
+	 */
+	fault(message: string, error: unknown): void {
+		this.append(formatValue({ level: "error", message: `harness ${message}`, error }))
+	}
+
+	private append(line: string): void {
+		appendFileSync(this.path, line + "\n")
+	}
+}

package/src/node.ts

@@ -0,0 +1,112 @@
+import { createServer, type IncomingMessage } from "node:http"
+import { DatabaseSync } from "node:sqlite"
+import { createSshCa } from "@andrewheberle/serverless-ssh-ca"
+import { bindingsFromEnv, fromNodeSqlite, secretFromString } from "@andrewheberle/serverless-ssh-ca/node"
+import type { TestServerConfig } from "./config.js"
+import { formatArgs } from "./format.js"
+import type { LogFile } from "./log.js"
+import type { TestServer } from "./server.js"
+
+const consoleMethods = ["debug", "info", "log", "warn", "error"] as const
+
+// convert a request received by the HTTP server into a Fetch API request
+const toRequest = async (req: IncomingMessage): Promise<Request> => {
+	const chunks: Buffer[] = []
+	for await (const chunk of req) {
+		chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)))
+	}
+
+	const headers = new Headers()
+	for (const [name, values] of Object.entries(req.headersDistinct)) {
+		for (const value of values ?? []) {
+			headers.append(name, value)
+		}
+	}
+
+	const method = req.method ?? "GET"
+
+	return new Request(`http://${req.headers.host ?? "localhost"}${req.url ?? "/"}`, {
+		method,
+		headers,
+		body: method === "GET" || method === "HEAD" ? undefined : Buffer.concat(chunks),
+	})
+}
+
+/**
+ * Run the CA on Node.js, created with the package's Node.js helpers and an
+ * in-memory `node:sqlite` database, behind an HTTP server on a random port.
+ *
+ * Output the CA writes with `console` is written to `log` until the server is
+ * closed.
+ *
+ * @param config The test server configuration
+ * @param log The log file for the CA and harness
+ * @returns The running server
+ * @throws InvalidConfigurationError if `config.bindings` is not a valid CA configuration
+ */
+export const startNode = async (config: TestServerConfig, log: LogFile): Promise<TestServer> => {
+	const db = new DatabaseSync(":memory:")
+
+	// bindingsFromEnv validates the configuration so a mistake fails at start up
+	const ca = createSshCa(bindingsFromEnv({
+		DB: fromNodeSqlite(db),
+		PRIVATE_KEY: secretFromString(config.private_key),
+	}, config.bindings))
+
+	// the CA logs JSON lines via console, so send them to the log file
+	const original = consoleMethods.map(level => [level, console[level]] as const)
+	for (const level of consoleMethods) {
+		console[level] = (...args: unknown[]): void => log.write(formatArgs(args))
+	}
+	const restoreConsole = (): void => {
+		for (const [level, method] of original) {
+			console[level] = method
+		}
+	}
+
+	const server = createServer(async (req, res) => {
+		try {
+			const request = await toRequest(req)
+			const response = await ca.fetch(request)
+			const body = Buffer.from(await response.arrayBuffer())
+
+			log.request(request.method, req.url ?? "/", response.status, body.toString())
+
+			res.writeHead(response.status, Object.fromEntries(response.headers))
+			res.end(body)
+		} catch (err) {
+			log.fault("request failed", err)
+			res.writeHead(502)
+			res.end()
+		}
+	})
+
+	try {
+		await new Promise<void>((resolve, reject) => {
+			server.once("error", reject)
+			server.listen(0, "127.0.0.1", () => resolve())
+		})
+	} catch (err) {
+		restoreConsole()
+		db.close()
+		throw err
+	}
+
+	const address = server.address()
+	if (address === null || typeof address === "string") {
+		restoreConsole()
+		server.close()
+		db.close()
+		throw new Error(`unexpected server address: ${String(address)}`)
+	}
+
+	return {
+		port: address.port,
+		close: async (): Promise<void> => {
+			server.closeAllConnections()
+			await new Promise<void>(resolve => server.close(() => resolve()))
+			restoreConsole()
+			db.close()
+		},
+	}
+}

package/src/server.ts

@@ -0,0 +1,9 @@
+/**
+ * A running test server, returned by {@link startTestServer}.
+ */
+export type TestServer = {
+	/** The port the CA is listening on at 127.0.0.1 */
+	port: number
+	/** Stop the CA and release its resources */
+	close(): Promise<void>
+}

package/src/worker.ts

@@ -0,0 +1,30 @@
+// Worker entry point used by startWorkerd, bundled by Wrangler when the test
+// server starts.
+//
+// The CA's default export is used as on Cloudflare Workers, wrapped only to
+// log each request and to write console output as JSON lines, as the Node.js
+// runtime does.
+import ca from "@andrewheberle/serverless-ssh-ca"
+import { formatArgs, formatRequest } from "./format.js"
+
+type FetchParameters = Parameters<typeof ca.fetch>
+
+// workerd formats objects passed to console for display rather than as JSON,
+// so format them here
+for (const level of ["debug", "info", "log", "warn", "error"] as const) {
+	const write = console[level].bind(console)
+	console[level] = (...args: unknown[]): void => write(formatArgs(args))
+}
+
+export default {
+	...ca,
+	async fetch(request: FetchParameters[0], env: FetchParameters[1], ctx: FetchParameters[2]): Promise<Response> {
+		const response = await ca.fetch(request, env, ctx)
+		const url = new URL(request.url)
+		const body = response.status >= 400 ? await response.clone().text() : ""
+
+		console.log(formatRequest(request.method, url.pathname + url.search, response.status, body))
+
+		return response
+	},
+}

package/src/workerd.ts

@@ -0,0 +1,111 @@
+import { fileURLToPath } from "node:url"
+import { createTestHarness } from "wrangler"
+import type { TestServerConfig } from "./config.js"
+import type { LogFile } from "./log.js"
+import type { TestServer } from "./server.js"
+
+// the Secrets Store binding exposes an admin API in local development, used
+// to create the CA private key secret
+type SecretsStoreAdmin = {
+	create(value: string): Promise<string>
+}
+
+type WorkerEnv = {
+	PRIVATE_KEY: {
+		"SecretsStoreSecret::admin_api": () => Promise<SecretsStoreAdmin>
+	}
+}
+
+/**
+ * The Workers compatibility date the CA is run with, which matches the
+ * configuration the CA is tested with on Workers.
+ */
+export const COMPATIBILITY_DATE = "2026-03-13"
+
+/**
+ * Run the CA under workerd, the Cloudflare Workers runtime, using the Wrangler
+ * test harness as "wrangler dev" would, with a local D1 database and Secrets
+ * Store that are not persisted.
+ *
+ * The CA's output is copied to `log` every 100ms and when the server is
+ * closed. Errors from workerd itself, such as an uncaught exception, are
+ * logged as harness faults.
+ *
+ * @param config The test server configuration
+ * @param log The log file for the CA and harness
+ * @param root The directory Wrangler's working files are written to
+ * @returns The running server
+ */
+export const startWorkerd = async (config: TestServerConfig, log: LogFile, root: string): Promise<TestServer> => {
+	// use placeholder request.cf data rather than downloading it from
+	// Cloudflare and caching it in the working directory
+	process.env.CLOUDFLARE_CF_FETCH_ENABLED = "false"
+
+	const server = createTestHarness({
+		root,
+		workers: [{
+			config: {
+				name: "serverless-ssh-ca",
+				main: fileURLToPath(new URL("./worker.js", import.meta.url)),
+				compatibility_date: COMPATIBILITY_DATE,
+				compatibility_flags: ["nodejs_compat"],
+				vars: config.bindings,
+				d1_databases: [{
+					binding: "DB",
+					database_name: "ssh-ca-database",
+					database_id: "00000000-0000-0000-0000-000000000000",
+				}],
+				secrets_store_secrets: [{
+					binding: "PRIVATE_KEY",
+					store_id: "test",
+					secret_name: "ssh-ca-private-key",
+				}],
+			},
+		}],
+	})
+
+	// copy the runtime logs to the log file. Errors that are not JSON lines
+	// from the CA are from workerd, such as an uncaught exception, so are
+	// logged as a harness fault.
+	const flushLogs = (): void => {
+		for (const entry of server.getLogs()) {
+			let json = true
+			try {
+				JSON.parse(entry.message)
+			} catch {
+				json = false
+			}
+
+			if (json || entry.level !== "error") {
+				log.write(entry.message)
+			} else {
+				log.fault("runtime error", entry.message)
+			}
+		}
+		server.clearLogs()
+	}
+
+	try {
+		const { url } = await server.listen()
+
+		// the secret must exist before the port is reported and requests are made
+		const env = await server.getWorker<WorkerEnv>().getEnv()
+		const secrets = await env.PRIVATE_KEY["SecretsStoreSecret::admin_api"]()
+		await secrets.create(config.private_key)
+
+		const timer = setInterval(flushLogs, 100)
+
+		return {
+			port: Number(url.port),
+			close: async (): Promise<void> => {
+				clearInterval(timer)
+				flushLogs()
+				await server.close()
+			},
+		}
+	} catch (err) {
+		flushLogs()
+		await server.close()
+		throw err
+	}
+}