add benchmark suite (#867)

Author: guybedford

.github/workflows/codspeed.yml

@@ -0,0 +1,56 @@
+name: CodSpeed Benchmarks
+
+on:
+  push:
+    branches:
+      - "main"
+  pull_request:
+  # `workflow_dispatch` allows CodSpeed to trigger backtest
+  # performance analysis in order to generate initial data.
+  workflow_dispatch:
+
+env:
+  BENCH_RESULT: /tmp/benchmark_results.json
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  benchmarks:
+    name: Run benchmarks
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - uses: dtolnay/rust-toolchain@1.87.0
+        with:
+          targets: wasm32-unknown-unknown
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          key: cargo-bench-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Build wasm-bindgen and worker-build
+        run: npm run build
+
+      - name: Install benchmark dependencies
+        working-directory: benchmark
+        run: npm install
+
+      - name: Build benchmark
+        working-directory: benchmark
+        run: node --run build
+
+      - name: Run benchmarks
+        uses: CodSpeedHQ/action@v4
+        with:
+          mode: walltime
+          run: cd benchmark && node run.js && node codspeed-convert.js $BENCH_RESULT

Cargo.lock

@@ -7,6 +7,7 @@ members = [
     "worker-sys",
     "examples/*",
     "test/container-echo",
+    "benchmark",
 ]
 exclude = [
     "examples/coredump",
@@ -55,6 +56,7 @@ web-sys = { version = "0.3.90", features = [
     "FormData",
     "Headers",
     "MessageEvent",
+    "Performance",
     "ProgressEvent",
     "ReadableStream",
     "ReadableStreamDefaultReader",

Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "workers-rs-benchmark"
+version = "0.1.0"
+edition = "2021"
+license = "MIT OR Apache-2.0"
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+worker.workspace = true
+web-sys.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+futures-util.workspace = true

benchmark/Cargo.toml

@@ -0,0 +1,59 @@
+# workers-rs Benchmark Suite
+
+Performance benchmark for workers-rs that measures streaming and parallel sub-request performance.
+
+## How to run
+
+First, make sure to clone workers-rs with all submodules.
+
+Then from the root of workers-rs:
+
+```bash
+npm run build
+```
+
+to build the local `worker-build`.
+
+Then run the benchmark:
+
+```bash
+cd benchmark
+npm install
+npm run bench
+```
+
+## What it does
+
+- Streams 1MB of data from `/stream` endpoint in 8KB chunks
+- Makes 10 parallel sub-requests to `/stream` from `/benchmark` endpoint
+- All requests are internal (no network I/O) to isolate workers-rs performance
+- Runs 20 iterations with 3 warmup requests
+
+## Output
+
+The benchmark provides:
+
+- Per-iteration timing for Node.js end-to-end and Worker internal execution
+- Summary statistics: average, min, and max times
+- Data transfer statistics (10MB per iteration = 10 parallel 1MB streams)
+- Average throughput in Mbps
+
+## Configuration
+
+Adjust parameters in `run.mjs`:
+- `iterations` - Number of benchmark runs (default: 20)
+- Warmup count (default: 3)
+
+Adjust workload in `src/lib.rs`:
+- Number of parallel requests (default: 10)
+- Data size per request (default: 1MB)
+- Chunk size for streaming (default: 8KB)
+
+## Rust Toolchain
+
+`rust-toolchain.toml` in the root of workers-rs sets the Rust toolchain. Changing this can be used to
+benchmark against different toolchain versions.
+
+## Compatibility Date
+
+The current compaitibility date is set to `2025-11-01` in the `wrangler.toml`. Finalization registry was enabled as of `2025-05-05`, so is included.

benchmark/README.md

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+
+/**
+ * Converts workers-rs benchmark results into CodSpeed walltime format.
+ * Based on the codspeed-rust 4.1.0 result schema.
+ *
+ * Usage: node codspeed-convert.js <input.json>
+ *
+ * Writes results to $CODSPEED_PROFILE_FOLDER/results/<pid>.json
+ * or ./codspeed-results/<pid>.json as fallback.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const IQR_OUTLIER_FACTOR = 1.5;
+const STDEV_OUTLIER_FACTOR = 3.0;
+
+function quantile(sorted, q) {
+  const pos = (sorted.length - 1) * q;
+  const base = Math.floor(pos);
+  const rest = pos - base;
+  if (sorted[base + 1] !== undefined) {
+    return sorted[base] + rest * (sorted[base + 1] - sorted[base]);
+  }
+  return sorted[base];
+}
+
+function computeStats(name, uri, timesMs) {
+  // Convert ms to ns
+  const timesNs = timesMs.map(t => t * 1_000_000);
+  const sorted = [...timesNs].sort((a, b) => a - b);
+  const rounds = timesNs.length;
+
+  const mean = timesNs.reduce((a, b) => a + b, 0) / rounds;
+  const stdev = rounds < 2 ? 0 : Math.sqrt(
+    timesNs.reduce((sum, t) => sum + (t - mean) ** 2, 0) / (rounds - 1)
+  );
+
+  const q1 = quantile(sorted, 0.25);
+  const median = quantile(sorted, 0.5);
+  const q3 = quantile(sorted, 0.75);
+  const iqr = q3 - q1;
+
+  const iqrOutliers = timesNs.filter(
+    t => t < q1 - IQR_OUTLIER_FACTOR * iqr || t > q3 + IQR_OUTLIER_FACTOR * iqr
+  ).length;
+  const stdevOutliers = timesNs.filter(
+    t => t < mean - STDEV_OUTLIER_FACTOR * stdev || t > mean + STDEV_OUTLIER_FACTOR * stdev
+  ).length;
+
+  return {
+    name,
+    uri,
+    config: {},
+    stats: {
+      min_ns: sorted[0],
+      max_ns: sorted[sorted.length - 1],
+      mean_ns: mean,
+      stdev_ns: stdev,
+      q1_ns: q1,
+      median_ns: median,
+      q3_ns: q3,
+      rounds,
+      total_time: timesNs.reduce((a, b) => a + b, 0) / 1_000_000_000,
+      iqr_outlier_rounds: iqrOutliers,
+      stdev_outlier_rounds: stdevOutliers,
+      iter_per_round: 1,
+      warmup_iters: 3,
+    },
+  };
+}
+
+const inputPath = process.argv[2];
+if (!inputPath) {
+  console.error('Usage: node codspeed-convert.js <input.json>');
+  process.exit(1);
+}
+
+const results = JSON.parse(readFileSync(inputPath, 'utf-8'));
+
+const benchmarks = [
+  computeStats(
+    'worker_internal_time',
+    'benchmark/src/lib.rs::handle_benchmark::worker_internal_time',
+    results.map(r => r.workerDuration)
+  ),
+  computeStats(
+    'e2e_time',
+    'benchmark/run.js::runBenchmark::e2e_time',
+    results.map(r => r.nodeJsDuration)
+  ),
+];
+
+const output = {
+  creator: {
+    name: 'codspeed-node',
+    version: '4.1.0',
+    pid: process.pid,
+  },
+  instrument: { type: 'walltime' },
+  benchmarks,
+};
+
+const profileFolder = process.env.CODSPEED_PROFILE_FOLDER || 'codspeed-results';
+const resultsDir = join(profileFolder, 'results');
+mkdirSync(resultsDir, { recursive: true });
+
+const outputPath = join(resultsDir, `${process.pid}.json`);
+writeFileSync(outputPath, JSON.stringify(output, null, 2));
+console.log(`CodSpeed results written to ${outputPath}`);

benchmark/codspeed-convert.js

@@ -0,0 +1,14 @@
+{
+  "name": "workers-rs-benchmark",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Performance benchmark suite for workers-rs",
+  "private": true,
+  "scripts": {
+    "build": "WASM_BINDGEN_BIN=../wasm-bindgen/target/debug/wasm-bindgen ../target/debug/worker-build --release",
+    "bench": "node --run build && node run.js"
+  },
+  "dependencies": {
+    "miniflare": "^4.20260302.0"
+  }
+}