Add API benchmark harness

.env.benchmark.example

@@ -0,0 +1,18 @@
+NODE_ENV=benchmark
+JWT_SECRET=benchmark-secret
+
+# Optional: benchmark an already-running API instead of starting apps/api locally.
+# BENCHMARK_BASE_URL=http://127.0.0.1:4000
+
+# Optional: use a pre-issued bearer token for protected endpoints.
+# BENCHMARK_AUTH_TOKEN=
+
+# Defaults are intentionally modest so local and CI runs are repeatable.
+BENCHMARK_ITERATIONS=30
+BENCHMARK_CONCURRENCY=4
+BENCHMARK_WARMUP=2
+BENCHMARK_RESULTS_DIR=benchmarks/results
+
+# Local benchmark runs disable the global rate limiter by default so route metrics
+# are not dominated by 429 responses from a single loopback IP.
+BENCHMARK_DISABLE_RATE_LIMIT=true

.github/workflows/benchmark.yml

@@ -0,0 +1,24 @@
+name: API benchmark smoke
+
+on:
+  pull_request:
+    paths:
+      - "apps/api/**"
+      - "benchmarks/**"
+      - "package*.json"
+      - ".github/workflows/benchmark.yml"
+  push:
+    branches:
+      - main
+
+jobs:
+  benchmark-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npm run benchmark:smoke

.gitignore

@@ -3,5 +3,6 @@ node_modules
 dist
 .env
 .env.*
+!.env.benchmark.example
 coverage
 *.log

apps/api/package.json

@@ -5,7 +5,7 @@
   "scripts": {
     "dev": "node src/server.js",
     "start": "node src/server.js",
-    "test": "node --test src/tests"
+    "test": "node --test \"src/tests/**/*.test.js\""
   },
   "dependencies": {
     "cors": "^2.8.5",

apps/api/src/middleware/rateLimit.js

@@ -3,6 +3,7 @@ import rateLimit from "express-rate-limit";
 export const apiLimiter = rateLimit({
   windowMs: 15 * 60 * 1000,
   limit: 200,
+  skip: () => process.env.BENCHMARK_DISABLE_RATE_LIMIT === "true",
   standardHeaders: "draft-7",
   legacyHeaders: false
 });

benchmarks/README.md

@@ -0,0 +1,22 @@
+# API Benchmarks
+
+Run the full local API benchmark from the repository root:
+
+```sh
+npm run benchmark
+```
+
+Run the CI-sized smoke benchmark:
+
+```sh
+npm run benchmark:smoke
+```
+
+The runner starts `apps/api` on an ephemeral local port unless `BENCHMARK_BASE_URL`
+is set. Copy `.env.benchmark.example` to `.env.benchmark` to override iteration
+counts, concurrency, auth token, results directory, or a remote target URL.
+
+Each run writes both JSON and Markdown reports to `benchmarks/results`. The
+threshold gate is configured in `benchmarks/thresholds.json` and fails the
+process when aggregate p95 latency, aggregate error rate, aggregate RPS, or an
+endpoint-specific threshold falls outside the configured limits.

benchmarks/results/.gitignore

@@ -0,0 +1,4 @@
+benchmark-*.json
+benchmark-*.md
+!.gitkeep
+!.gitignore

benchmarks/results/.gitkeep

@@ -0,0 +1 @@
+