castrum 0.7.0

package/src/bench/measure.ts

@@ -0,0 +1,177 @@
+import { checksumValue } from "./checksum";
+import { nowMs } from "./now";
+import type {
+  BenchResult,
+  ConcurrentBenchTask,
+  ConcurrentBenchResult,
+  StressBenchResult,
+} from "./types";
+
+const concurrentWorkerUrl = new URL("./concurrent-worker.ts", import.meta.url);
+
+export function bench(
+  name: string,
+  fn: () => unknown,
+  iterations = 100,
+  warmup = 10,
+): BenchResult {
+  const safeIterations = Math.max(1, iterations);
+  const safeWarmup = Math.max(0, warmup);
+
+  let checksum = 0n;
+
+  for (let i = 0; i < safeWarmup; i++) {
+    checksum += checksumValue(fn());
+  }
+
+  const samples: number[] = new Array(safeIterations);
+
+  for (let i = 0; i < safeIterations; i++) {
+    const start = nowMs();
+    checksum += checksumValue(fn());
+    samples[i] = nowMs() - start;
+  }
+
+  samples.sort((a, b) => a - b);
+
+  const total = samples.reduce((a, b) => a + b, 0);
+  const avg = total / safeIterations;
+
+  return {
+    name,
+    iterations: safeIterations,
+    avgMs: avg,
+    p50Ms: samples[Math.floor(safeIterations * 0.5)] ?? 0,
+    p95Ms: samples[Math.floor(safeIterations * 0.95)] ?? 0,
+    opsPerSec: 1000 / Math.max(avg, 1e-9),
+    checksum: checksum.toString(),
+  };
+}
+
+export async function benchConcurrent(
+  task: ConcurrentBenchTask,
+): Promise<ConcurrentBenchResult> {
+  const concurrency = Math.max(1, task.concurrency);
+  const iterations = Math.max(1, task.iterationsPerSlot);
+  const warmup = Math.max(0, task.warmupPerSlot);
+
+  const workers: Worker[] = [];
+
+  try {
+    await Promise.all(
+      Array.from({ length: concurrency }, async () => {
+        const worker = new Worker(concurrentWorkerUrl, { type: "module" });
+        workers.push(worker);
+
+        await new Promise<void>((resolve, reject) => {
+          worker.onmessage = (e: any) => {
+            const msg = e.data;
+            if (msg?.type === "ready") {
+              resolve();
+            } else if (msg?.type === "error") {
+              reject(new Error(msg.message ?? "worker init error"));
+            }
+          };
+
+          worker.onerror = (e: any) => {
+            reject(new Error(e?.message ?? "worker error"));
+          };
+
+          worker.postMessage({
+            type: "init",
+            op: task.op,
+            payload: task.payload,
+            warmup,
+          });
+        });
+      }),
+    );
+
+    const resultPromises = workers.map(
+      (worker) =>
+        new Promise<bigint>((resolve, reject) => {
+          worker.onmessage = (e: any) => {
+            const msg = e.data;
+            if (msg?.type === "result") {
+              resolve(BigInt(msg.checksum ?? "0"));
+            } else if (msg?.type === "error") {
+              reject(new Error(msg.message ?? "worker runtime error"));
+            }
+          };
+
+          worker.onerror = (e: any) => {
+            reject(new Error(e?.message ?? "worker error"));
+          };
+        }),
+    );
+
+    const start = nowMs();
+
+    for (const worker of workers) {
+      worker.postMessage({
+        type: "run",
+        iterations,
+      });
+    }
+
+    const checksums = await Promise.all(resultPromises);
+    const totalMs = nowMs() - start;
+
+    const checksum = checksums.reduce((a, b) => a + b, 0n);
+    const totalOps = concurrency * iterations;
+
+    return {
+      name: task.name,
+      iterations,
+      concurrency,
+      totalOps,
+      totalMs,
+      avgMs: totalMs / Math.max(totalOps, 1),
+      p50Ms: 0,
+      p95Ms: 0,
+      opsPerSec: (totalOps / Math.max(totalMs, 1e-9)) * 1000,
+      checksum: checksum.toString(),
+    };
+  } finally {
+    for (const worker of workers) {
+      worker.terminate();
+    }
+  }
+}
+
+export function benchStress(
+  name: string,
+  fn: () => unknown,
+  durationMs: number,
+  warmupMs = 100,
+): StressBenchResult {
+  const safeDuration = Math.max(100, durationMs);
+  const safeWarmup = Math.max(0, warmupMs);
+
+  const warmupEnd = nowMs() + safeWarmup;
+  while (nowMs() < warmupEnd) {
+    checksumValue(fn());
+  }
+
+  let checksum = 0n;
+  let ops = 0;
+
+  const start = nowMs();
+  const end = start + safeDuration;
+
+  while (nowMs() < end) {
+    checksum += checksumValue(fn());
+    ops++;
+  }
+
+  const elapsed = nowMs() - start;
+
+  return {
+    name,
+    durationMs: elapsed,
+    totalOps: ops,
+    opsPerSec: (ops / Math.max(elapsed, 1e-9)) * 1000,
+    avgMs: elapsed / Math.max(ops, 1),
+    checksum: checksum.toString(),
+  };
+}

package/src/bench/now.ts

@@ -0,0 +1,3 @@
+export function nowMs(): number {
+  return Bun.nanoseconds() / 1_000_000;
+}

package/src/bench/report.ts

@@ -0,0 +1,79 @@
+import type { BenchResult, ComparisonReport, ConcurrentBenchResult, StressBenchResult } from "./types";
+
+export function printResults(results: BenchResult[]): void {
+  console.table(
+    results.map((r) => ({
+      name: r.name,
+      iters: r.iterations,
+      "avg ms": r.avgMs.toFixed(4),
+      "p50 ms": r.p50Ms.toFixed(4),
+      "p95 ms": r.p95Ms.toFixed(4),
+      "ops/s": r.opsPerSec.toFixed(1),
+      checksum:
+        r.checksum.length > 16 ? `${r.checksum.slice(0, 16)}…` : r.checksum,
+    })),
+  );
+}
+
+export function printConcurrentResults(results: ConcurrentBenchResult[]): void {
+  console.table(
+    results.map((r) => ({
+      name: r.name,
+      concurrency: r.concurrency,
+      "ops/slot": r.iterations,
+      "total ops": r.totalOps,
+      "total ms": r.totalMs.toFixed(2),
+      "avg ms/op": r.avgMs.toFixed(6),
+      "ops/s": r.opsPerSec.toFixed(1),
+      checksum: r.checksum.length > 16 ? `${r.checksum.slice(0, 16)}…` : r.checksum,
+    })),
+  );
+}
+
+export function printStressResults(results: StressBenchResult[]): void {
+  console.table(
+    results.map((r) => ({
+      name: r.name,
+      "duration ms": r.durationMs.toFixed(0),
+      "total ops": r.totalOps,
+      "ops/s": r.opsPerSec.toFixed(1),
+      "avg ms": r.avgMs.toFixed(6),
+      checksum: r.checksum.length > 16 ? `${r.checksum.slice(0, 16)}…` : r.checksum,
+    })),
+  );
+}
+
+function printComparison(
+  results: (BenchResult | ConcurrentBenchResult | StressBenchResult)[],
+  report: ComparisonReport,
+): void {
+  const n = results.find((x) => x.name === report.nativeName);
+  const r = results.find((x) => x.name === report.rustName);
+
+  if (!n || !r) {
+    return;
+  }
+
+  const nAvg = n.avgMs;
+  const rAvg = r.avgMs;
+  const ratio = nAvg / Math.max(rAvg, 1e-9);
+
+  if (ratio >= 1) {
+    console.log(
+      `${report.label}: Rust ${rAvg.toFixed(4)}ms vs Native ${nAvg.toFixed(4)}ms → Rust ${ratio.toFixed(2)}x faster`,
+    );
+  } else {
+    console.log(
+      `${report.label}: Rust ${rAvg.toFixed(4)}ms vs Native ${nAvg.toFixed(4)}ms → Native ${(1 / ratio).toFixed(2)}x faster`,
+    );
+  }
+}
+
+export function printSummary(
+  results: (BenchResult | ConcurrentBenchResult | StressBenchResult)[],
+  reports: ComparisonReport[],
+): void {
+  for (const report of reports) {
+    printComparison(results, report);
+  }
+}

package/src/bench/run.ts

@@ -0,0 +1,57 @@
+import { runCorrectnessChecks, runComplexCorrectnessChecks } from "./checks";
+import { comparisonReports } from "./comparisons";
+import { createFixtures, createComplexFixtures } from "./fixtures";
+import { bench, benchConcurrent, benchStress } from "./measure";
+import { printResults, printConcurrentResults, printStressResults, printSummary } from "./report";
+import { createAllTasks, createComplexTasks, createConcurrentTasks, createStressTasks } from "./tasks";
+
+export async function runBenchmark(): Promise<void> {
+  const fixtures = createFixtures();
+  const complexFixtures = createComplexFixtures();
+
+  runCorrectnessChecks(fixtures);
+  runComplexCorrectnessChecks(fixtures, complexFixtures);
+
+  // ── Standard sequential benchmarks ──
+  console.log("\n═══ Standard Benchmarks ═══");
+  const tasks = createAllTasks(fixtures);
+  const results = tasks.map((task) =>
+    bench(task.name, task.run, task.iterations, task.warmup),
+  );
+  printResults(results);
+
+  // ── Complex payload benchmarks ──
+  console.log("\n═══ Complex Payload Benchmarks ═══");
+  const complexTasks = createComplexTasks(complexFixtures);
+  const complexResults = complexTasks.map((task) =>
+    bench(task.name, task.run, task.iterations, task.warmup),
+  );
+  printResults(complexResults);
+
+  // ── Concurrent burst benchmarks ──
+  console.log("\n═══ Concurrent Burst Benchmarks ═══");
+  const concurrentTasks = createConcurrentTasks(fixtures, complexFixtures);
+  const concurrentResults: import("./types").ConcurrentBenchResult[] = [];
+  for (const task of concurrentTasks) {
+    concurrentResults.push(await benchConcurrent(task));
+  }
+  printConcurrentResults(concurrentResults);
+
+  // ── Stress benchmarks (fixed duration) ──
+  console.log("\n═══ Stress Benchmarks (2s each) ═══");
+  const stressTasksList = createStressTasks(fixtures, complexFixtures);
+  const stressResults: import("./types").StressBenchResult[] = [];
+  for (const task of stressTasksList) {
+    stressResults.push(
+      benchStress(task.name, task.run, task.durationMs, task.warmupMs),
+    );
+  }
+  printStressResults(stressResults);
+
+  // ── Combined summary ──
+  console.log("\n═══ Practical Summary ═══");
+  printSummary(
+    [...results, ...complexResults, ...concurrentResults, ...stressResults],
+    comparisonReports,
+  );
+}

package/src/bench/tasks/complex.ts

@@ -0,0 +1,232 @@
+import * as native from "../../baseline";
+import { rust, rustBatch } from "../../rust-ffi";
+import type { ComplexFixtures } from "../fixtures";
+import type { BenchTask } from "../types";
+
+export function complexTasks(c: ComplexFixtures): BenchTask[] {
+  return [
+    // ── Large JSON payloads ──
+    {
+      name: "native:json_valid_large",
+      run: () => native.nativeJsonValid(c.jsonLarge),
+      iterations: 20,
+      warmup: 5,
+    },
+    {
+      name: "rust:json_valid_large",
+      run: () => rust.jsonValid(c.jsonLarge),
+      iterations: 20,
+      warmup: 5,
+    },
+    {
+      name: "native:json_sum_large",
+      run: () => native.nativeJsonSum(c.jsonLarge),
+      iterations: 20,
+      warmup: 5,
+    },
+    {
+      name: "rust:json_sum_large",
+      run: () => rust.jsonSumIds(c.jsonLarge),
+      iterations: 20,
+      warmup: 5,
+    },
+
+    // ── Huge JSON payloads ──
+    {
+      name: "native:json_valid_huge",
+      run: () => native.nativeJsonValid(c.jsonHuge),
+      iterations: 10,
+      warmup: 3,
+    },
+    {
+      name: "rust:json_valid_huge",
+      run: () => rust.jsonValid(c.jsonHuge),
+      iterations: 10,
+      warmup: 3,
+    },
+
+    // ── Deep nested JSON ──
+    {
+      name: "native:json_valid_deep",
+      run: () => native.nativeJsonValid(c.jsonNestedDeep),
+      iterations: 100,
+      warmup: 20,
+    },
+    {
+      name: "rust:json_valid_deep",
+      run: () => rust.jsonValid(c.jsonNestedDeep),
+      iterations: 100,
+      warmup: 20,
+    },
+
+    // ── Complex HTTP ──
+    {
+      name: "native:http_parse_complex",
+      run: () => native.nativeHttpParseRequestPacked(c.httpComplex).byteLength,
+      iterations: 200,
+      warmup: 50,
+    },
+    {
+      name: "rust:http_parse_complex",
+      run: () => rust.httpParseRequestPacked(c.httpComplex).byteLength,
+      iterations: 200,
+      warmup: 50,
+    },
+
+    // ── Huge HTTP ──
+    {
+      name: "native:http_parse_huge",
+      run: () => native.nativeHttpParseRequestPacked(c.httpHuge).byteLength,
+      iterations: 100,
+      warmup: 20,
+    },
+    {
+      name: "rust:http_parse_huge",
+      run: () => rust.httpParseRequestPacked(c.httpHuge).byteLength,
+      iterations: 100,
+      warmup: 20,
+    },
+
+    // ── Large cookie string ──
+    {
+      name: "native:cookie_parse_large",
+      run: () => native.nativeCookieParsePacked(c.cookieLarge).byteLength,
+      iterations: 200,
+      warmup: 50,
+    },
+    {
+      name: "rust:cookie_parse_large",
+      run: () => rust.cookieParsePacked(c.cookieLarge).byteLength,
+      iterations: 200,
+      warmup: 50,
+    },
+
+    // ── Complex query string ──
+    {
+      name: "native:query_parse_complex",
+      run: () => native.nativeQueryParsePacked(c.queryComplex).byteLength,
+      iterations: 100,
+      warmup: 20,
+    },
+    {
+      name: "rust:query_parse_complex",
+      run: () => rust.queryParsePacked(c.queryComplex).byteLength,
+      iterations: 100,
+      warmup: 20,
+    },
+
+    // ── Large URL encode/decode ──
+    {
+      name: "native:url_encode_large",
+      run: () => native.nativeUrlEncode(c.urlLarge).length,
+      iterations: 100,
+      warmup: 20,
+    },
+    {
+      name: "rust:url_encode_large",
+      run: () => rust.urlEncode(c.urlLarge).byteLength,
+      iterations: 100,
+      warmup: 20,
+    },
+    {
+      name: "native:url_decode_large",
+      run: () => native.nativeUrlDecode(c.urlLarge).length,
+      iterations: 100,
+      warmup: 20,
+    },
+    {
+      name: "rust:url_decode_large",
+      run: () => rust.urlDecode(c.urlLarge).byteLength,
+      iterations: 100,
+      warmup: 20,
+    },
+
+    // ── Batch operations ──
+    {
+      name: "native:json_valid_batch",
+      run: () =>
+        c.batchJsonDocs.reduce(
+          (acc, doc) => acc + (native.nativeJsonValid(doc) ? 1 : 0),
+          0,
+        ),
+      iterations: 50,
+      warmup: 10,
+    },
+    {
+      name: "rust:json_valid_batch",
+      run: () => rustBatch.jsonValid(c.batchJsonDocs).reduce((acc, b) => acc + b, 0),
+      iterations: 50,
+      warmup: 10,
+    },
+    {
+      name: "native:validate_email_batch",
+      run: () =>
+        c.batchEmails.reduce(
+          (acc, e) => acc + (native.nativeValidateEmail(e) ? 1 : 0),
+          0,
+        ),
+      iterations: 50,
+      warmup: 10,
+    },
+    {
+      name: "rust:validate_email_batch",
+      run: () =>
+        rustBatch.validateEmail(c.batchEmails).reduce((acc, b) => acc + b, 0),
+      iterations: 50,
+      warmup: 10,
+    },
+    {
+      name: "native:validate_uuid_batch",
+      run: () =>
+        c.batchUuids.reduce(
+          (acc, u) => acc + (native.nativeValidateUuid(u) ? 1 : 0),
+          0,
+        ),
+      iterations: 50,
+      warmup: 10,
+    },
+    {
+      name: "rust:validate_uuid_batch",
+      run: () =>
+        rustBatch.validateUuid(c.batchUuids).reduce((acc, b) => acc + b, 0),
+      iterations: 50,
+      warmup: 10,
+    },
+    {
+      name: "native:validate_ipv4_batch",
+      run: () =>
+        c.batchIpv4s.reduce(
+          (acc, ip) => acc + (native.nativeValidateIpv4(ip) ? 1 : 0),
+          0,
+        ),
+      iterations: 50,
+      warmup: 10,
+    },
+    {
+      name: "rust:validate_ipv4_batch",
+      run: () =>
+        rustBatch.validateIpv4(c.batchIpv4s).reduce((acc, b) => acc + b, 0),
+      iterations: 50,
+      warmup: 10,
+    },
+    {
+      name: "native:query_parse_batch",
+      run: () =>
+        c.batchQueries.reduce(
+          (acc, q) => acc + native.nativeQueryParsePacked(q).byteLength,
+          0,
+        ),
+      iterations: 30,
+      warmup: 5,
+    },
+    {
+      name: "rust:query_parse_batch",
+      run: () =>
+        rustBatch
+          .queryParse(c.batchQueries)
+          .reduce((acc, bytes) => acc + bytes.byteLength, 0),
+      iterations: 30,
+      warmup: 5,
+    },
+  ];
+}