@durable-streams/server-conformance-tests 0.1.0

package/README.md

@@ -0,0 +1,132 @@
+# @durable-streams/server-conformance-tests
+
+Protocol compliance test suite for Durable Streams server implementations.
+
+This package provides a comprehensive test suite to verify that a server correctly implements the [Durable Streams protocol](../../PROTOCOL.md).
+
+## Installation
+
+```bash
+npm install @durable-streams/server-conformance-tests
+# or
+pnpm add @durable-streams/server-conformance-tests
+```
+
+## CLI Usage
+
+The easiest way to run conformance tests against your server:
+
+### Run Once (CI)
+
+```bash
+npx @durable-streams/server-conformance-tests --run http://localhost:4437
+```
+
+### Watch Mode (Development)
+
+Watch source files and automatically rerun tests when changes are detected:
+
+```bash
+npx @durable-streams/server-conformance-tests --watch src http://localhost:4437
+
+# Watch multiple directories
+npx @durable-streams/server-conformance-tests --watch src lib http://localhost:4437
+```
+
+### CLI Options
+
+```
+Usage:
+  npx @durable-streams/server-conformance-tests --run <url>
+  npx @durable-streams/server-conformance-tests --watch <path> [path...] <url>
+
+Options:
+  --run              Run tests once and exit (for CI)
+  --watch <paths>    Watch source paths and rerun tests on changes (for development)
+  --help, -h         Show help message
+
+Arguments:
+  <url>              Base URL of the Durable Streams server to test against
+```
+
+## Programmatic Usage
+
+You can also run the conformance tests programmatically within your own test suite:
+
+```typescript
+import { runConformanceTests } from "@durable-streams/server-conformance-tests"
+
+// In your test file (e.g., with vitest)
+describe("My Server Implementation", () => {
+  const config = { baseUrl: "" }
+
+  beforeAll(async () => {
+    // Start your server
+    const server = await startMyServer({ port: 0 })
+    config.baseUrl = server.url
+  })
+
+  afterAll(async () => {
+    await server.stop()
+  })
+
+  // Run all conformance tests
+  runConformanceTests(config)
+})
+```
+
+## CI Integration
+
+Add conformance tests to your CI pipeline:
+
+```yaml
+# GitHub Actions example
+jobs:
+  conformance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Start server
+        run: npm run start:server &
+
+      - name: Wait for server
+        run: npx wait-on http://localhost:4437
+
+      - name: Run conformance tests
+        run: npx @durable-streams/server-conformance-tests --run http://localhost:4437
+```
+
+## Test Coverage
+
+The conformance test suite covers:
+
+- **Basic Stream Operations** - Create, delete, idempotent operations
+- **Append Operations** - String data, chunking, sequence ordering
+- **Read Operations** - Empty/full streams, offset reads
+- **Long-Poll Operations** - Data waiting, immediate returns
+- **HTTP Protocol** - Headers, status codes, content negotiation
+- **TTL and Expiry** - TTL/Expires-At handling
+- **Case-Insensitivity** - Content-type, header casing
+- **Content-Type Validation** - Match enforcement
+- **HEAD Metadata** - Metadata-only responses
+- **Offset Validation** - Malformed offsets, resumable reads
+- **Protocol Edge Cases** - Empty bodies, binary data, monotonic progression
+- **Byte-Exactness** - Data integrity guarantees
+- **Caching and ETag** - ETag and 304 responses
+- **Chunking and Large Payloads** - Pagination, large files
+- **Property-Based Fuzzing** - Random append/read sequences
+- **Malformed Input Fuzzing** - Security-focused tests
+- **Read-Your-Writes Consistency** - Immediate visibility after writes
+- **SSE Mode** - Server-sent events streaming
+- **JSON Mode** - JSON serialization and batching
+
+## License
+
+Apache 2.0

package/bin/conformance-dev.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+/* eslint-disable stylistic/quotes */
+
+/**
+ * Development wrapper that uses tsx to run the TypeScript source directly.
+ * This allows you to use `pnpm link --global` and see changes immediately
+ * without rebuilding.
+ */
+
+import { spawn } from "node:child_process"
+import { fileURLToPath } from "node:url"
+import { dirname, join } from "node:path"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+const srcPath = join(__dirname, "..", "src", "cli.ts")
+
+// Run tsx with the source file
+const child = spawn("tsx", [srcPath, ...process.argv.slice(2)], {
+  stdio: "inherit",
+})
+
+child.on("exit", (code) => {
+  process.exit(code ?? 0)
+})

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/cli.js

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { existsSync, watch } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+//#region src/cli.ts
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function printUsage() {
+	console.log(`
+Durable Streams Conformance Test Runner
+
+Usage:
+  npx @durable-streams/server-conformance-tests --run <url>
+  npx @durable-streams/server-conformance-tests --watch <path> [path...] <url>
+
+Options:
+  --run              Run tests once and exit (for CI)
+  --watch <paths>    Watch source paths and rerun tests on changes (for development)
+  --help, -h         Show this help message
+
+Arguments:
+  <url>              Base URL of the Durable Streams server to test against
+
+Examples:
+  # Run tests once in CI
+  npx @durable-streams/server-conformance-tests --run http://localhost:4473
+
+  # Watch src directory and rerun tests on changes
+  npx @durable-streams/server-conformance-tests --watch src http://localhost:4473
+
+  # Watch multiple directories
+  npx @durable-streams/server-conformance-tests --watch src lib http://localhost:4473
+`);
+}
+function parseArgs(args) {
+	const result = {
+		mode: `run`,
+		watchPaths: [],
+		baseUrl: ``,
+		help: false
+	};
+	let i = 0;
+	while (i < args.length) {
+		const arg = args[i];
+		if (arg === `--help` || arg === `-h`) {
+			result.help = true;
+			return result;
+		}
+		if (arg === `--run`) {
+			result.mode = `run`;
+			i++;
+			continue;
+		}
+		if (arg === `--watch`) {
+			result.mode = `watch`;
+			i++;
+			while (i < args.length - 1) {
+				const next = args[i];
+				if (next.startsWith(`--`) || next.startsWith(`-`)) break;
+				result.watchPaths.push(next);
+				i++;
+			}
+			continue;
+		}
+		if (!arg.startsWith(`-`)) result.baseUrl = arg;
+		i++;
+	}
+	return result;
+}
+function validateArgs(args) {
+	if (!args.baseUrl) return `Error: Base URL is required`;
+	try {
+		new URL(args.baseUrl);
+	} catch {
+		return `Error: Invalid URL "${args.baseUrl}"`;
+	}
+	if (args.mode === `watch` && args.watchPaths.length === 0) return `Error: --watch requires at least one path to watch`;
+	return null;
+}
+function getTestRunnerPath() {
+	const runnerInDist = join(__dirname, `test-runner.js`);
+	const runnerInSrc = join(__dirname, `test-runner.ts`);
+	if (existsSync(runnerInDist)) return runnerInDist;
+	return runnerInSrc;
+}
+function runTests(baseUrl) {
+	return new Promise((resolvePromise) => {
+		const runnerPath = getTestRunnerPath();
+		const vitestBin = join(__dirname, `..`, `node_modules`, `.bin`, `vitest`);
+		const vitestBinAlt = join(__dirname, `..`, `..`, `..`, `node_modules`, `.bin`, `vitest`);
+		let vitestPath = `vitest`;
+		if (existsSync(vitestBin)) vitestPath = vitestBin;
+		else if (existsSync(vitestBinAlt)) vitestPath = vitestBinAlt;
+		const args = [
+			`run`,
+			runnerPath,
+			`--no-coverage`,
+			`--reporter=default`,
+			`--passWithNoTests=false`
+		];
+		const child = spawn(vitestPath, args, {
+			stdio: `inherit`,
+			env: {
+				...process.env,
+				CONFORMANCE_TEST_URL: baseUrl,
+				FORCE_COLOR: `1`
+			},
+			shell: true
+		});
+		child.on(`close`, (code) => {
+			resolvePromise(code ?? 1);
+		});
+		child.on(`error`, (err) => {
+			console.error(`Failed to run tests: ${err.message}`);
+			resolvePromise(1);
+		});
+	});
+}
+async function runOnce(baseUrl) {
+	console.log(`Running conformance tests against ${baseUrl}\n`);
+	const exitCode = await runTests(baseUrl);
+	process.exit(exitCode);
+}
+async function runWatch(baseUrl, watchPaths) {
+	let runningProcess = null;
+	let debounceTimer = null;
+	const DEBOUNCE_MS = 300;
+	const spawnTests = () => {
+		const runnerPath = getTestRunnerPath();
+		const vitestBin = join(__dirname, `..`, `node_modules`, `.bin`, `vitest`);
+		const vitestBinAlt = join(__dirname, `..`, `..`, `..`, `node_modules`, `.bin`, `vitest`);
+		let vitestPath = `vitest`;
+		if (existsSync(vitestBin)) vitestPath = vitestBin;
+		else if (existsSync(vitestBinAlt)) vitestPath = vitestBinAlt;
+		const args = [
+			`run`,
+			runnerPath,
+			`--no-coverage`,
+			`--reporter=default`,
+			`--passWithNoTests=false`
+		];
+		return spawn(vitestPath, args, {
+			stdio: `inherit`,
+			env: {
+				...process.env,
+				CONFORMANCE_TEST_URL: baseUrl,
+				FORCE_COLOR: `1`
+			},
+			shell: true
+		});
+	};
+	const runTestsDebounced = () => {
+		if (debounceTimer) clearTimeout(debounceTimer);
+		debounceTimer = setTimeout(() => {
+			if (runningProcess) {
+				runningProcess.kill(`SIGTERM`);
+				runningProcess = null;
+			}
+			console.clear();
+			console.log(`Running conformance tests against ${baseUrl}\n`);
+			runningProcess = spawnTests();
+			runningProcess.on(`close`, (code) => {
+				if (code === 0) console.log(`\nAll tests passed`);
+				else console.log(`\nTests failed (exit code: ${code})`);
+				console.log(`\nWatching for changes in: ${watchPaths.join(`, `)}`);
+				console.log(`Press Ctrl+C to exit\n`);
+				runningProcess = null;
+			});
+		}, DEBOUNCE_MS);
+	};
+	const watchers = [];
+	for (const watchPath of watchPaths) {
+		const absPath = resolve(process.cwd(), watchPath);
+		try {
+			const watcher = watch(absPath, { recursive: true }, (eventType, filename) => {
+				if (filename && !filename.includes(`node_modules`)) {
+					console.log(`\nChange detected: ${filename}`);
+					runTestsDebounced();
+				}
+			});
+			watchers.push(watcher);
+			console.log(`Watching: ${absPath}`);
+		} catch (err) {
+			console.error(`Warning: Could not watch "${watchPath}": ${err.message}`);
+		}
+	}
+	if (watchers.length === 0) {
+		console.error(`Error: No valid paths to watch`);
+		process.exit(1);
+	}
+	process.on(`SIGINT`, () => {
+		console.log(`\n\nStopping watch mode...`);
+		watchers.forEach((w) => w.close());
+		if (runningProcess) runningProcess.kill(`SIGTERM`);
+		process.exit(0);
+	});
+	runTestsDebounced();
+	await new Promise(() => {});
+}
+async function main() {
+	const args = parseArgs(process.argv.slice(2));
+	if (args.help) {
+		printUsage();
+		process.exit(0);
+	}
+	const error = validateArgs(args);
+	if (error) {
+		console.error(error);
+		console.error(`\nRun with --help for usage information`);
+		process.exit(1);
+	}
+	if (args.mode === `watch`) await runWatch(args.baseUrl, args.watchPaths);
+	else await runOnce(args.baseUrl);
+}
+main().catch((err) => {
+	console.error(`Fatal error: ${err.message}`);
+	process.exit(1);
+});
+
+//#endregion

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+//#region src/index.d.ts
+interface ConformanceTestOptions {
+  /** Base URL of the server to test */
+  baseUrl: string;
+}
+/**
+* Run the full conformance test suite against a server
+*/
+declare function runConformanceTests(options: ConformanceTestOptions): void; //#endregion
+export { ConformanceTestOptions, runConformanceTests };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { runConformanceTests } from "./src-DRIMnUPk.js";
+
+export { runConformanceTests };