Add API benchmark suite

Author: Roy

.env.benchmark.example

@@ -0,0 +1,16 @@
+# Target an already-running API. Leave empty to start the local Express app in-process.
+BENCHMARK_TARGET_URL=
+
+# Optional auth token override for protected routes. Leave empty to generate a local admin JWT.
+BENCHMARK_AUTH_TOKEN=
+
+# Request load settings. Defaults are intentionally under the app rate-limit ceiling.
+BENCHMARK_REQUESTS_PER_ENDPOINT=8
+BENCHMARK_CONCURRENCY=4
+
+# Smoke mode uses lower defaults unless these are set.
+BENCHMARK_SMOKE_REQUESTS_PER_ENDPOINT=2
+BENCHMARK_SMOKE_CONCURRENCY=1
+
+# Output location for JSON and Markdown reports.
+BENCHMARK_RESULTS_DIR=benchmarks/results

.github/workflows/api-benchmark-smoke.yml

@@ -0,0 +1,23 @@
+name: API benchmark smoke
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  api-benchmark-smoke:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          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/*.js"
   },
   "dependencies": {
     "cors": "^2.8.5",

apps/api/src/tests/benchmark-endpoints.test.js

@@ -0,0 +1,36 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { benchmarkEndpoints } from "../../../../benchmarks/endpoints.mjs";
+
+test("benchmark suite covers every mounted API route", () => {
+  const expectedRoutes = new Set([
+    "POST /api/auth/register",
+    "POST /api/auth/login",
+    "GET /api/auth/oauth/github/callback",
+    "POST /api/auth/refresh",
+    "GET /api/users",
+    "POST /api/users",
+    "GET /api/jobs",
+    "POST /api/jobs",
+    "GET /api/proposals",
+    "POST /api/proposals",
+    "POST /api/payments",
+    "GET /api/reviews",
+    "POST /api/reviews",
+    "GET /api/messages",
+    "POST /api/messages",
+    "GET /api/notifications",
+    "POST /api/notifications",
+    "POST /api/uploads",
+    "GET /api/search?q=react%20payments%20benchmark",
+    "GET /api/admin/metrics"
+  ]);
+
+  const benchmarkRoutes = new Set(
+    benchmarkEndpoints
+      .filter((endpoint) => endpoint.path.startsWith("/api/"))
+      .map((endpoint) => `${endpoint.method} ${endpoint.path}`)
+  );
+
+  assert.deepEqual(benchmarkRoutes, expectedRoutes);
+});

benchmarks/README.md

@@ -0,0 +1,33 @@
+# API Benchmark Suite
+
+This suite benchmarks the Express API routes mounted by `apps/api/src/app.js`.
+It can start the local app in-process or target a running API with
+`BENCHMARK_TARGET_URL`.
+
+## Commands
+
+```bash
+npm run benchmark
+npm run benchmark:smoke
+```
+
+`benchmark:smoke` is meant for CI. It uses low concurrency and the same
+threshold checks as the full benchmark.
+
+## Configuration
+
+Copy `.env.benchmark.example` to `.env.benchmark` and adjust values as needed.
+Environment variables already exported in the shell take precedence.
+
+Protected routes use `BENCHMARK_AUTH_TOKEN` when provided. If the benchmark
+starts the local app, it generates a dedicated admin-scoped benchmark JWT.
+
+## Outputs
+
+Every run writes timestamped JSON and Markdown reports under
+`benchmarks/results/`, plus `latest.json` and `latest.md` convenience copies.
+Each report includes p50, p95, p99 latency, p95 TTFB, sustained and peak RPS,
+error rate, and non-2xx rate per endpoint.
+
+Thresholds live in `benchmarks/thresholds.json` so reviewers can tune the smoke
+gate without editing benchmark code.

benchmarks/endpoints.mjs

@@ -0,0 +1,215 @@
+const longJobDescription =
+  "Build a responsive marketplace dashboard with saved filters, proposal review, milestone tracking, and client messaging. Include accessibility checks and realistic empty states.";
+
+function jsonBody(payload) {
+  return {
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(payload)
+  };
+}
+
+function uploadBody() {
+  const form = new FormData();
+  const content = "benchmark upload payload\n".repeat(64);
+  form.append("file", new Blob([content], { type: "text/plain" }), "benchmark-notes.txt");
+  return { body: form };
+}
+
+export const benchmarkEndpoints = [
+  {
+    name: "health",
+    method: "GET",
+    path: "/health",
+    description: "Service health probe"
+  },
+  {
+    name: "auth_register",
+    method: "POST",
+    path: "/api/auth/register",
+    description: "Register a benchmark client user",
+    request: ({ iteration }) =>
+      jsonBody({
+        email: `benchmark.client.${iteration}@example.com`,
+        password: "benchmark-password",
+        role: "client"
+      })
+  },
+  {
+    name: "auth_login",
+    method: "POST",
+    path: "/api/auth/login",
+    description: "Login with realistic credentials",
+    request: () =>
+      jsonBody({
+        email: "existing.client@example.com",
+        password: "benchmark-password"
+      })
+  },
+  {
+    name: "auth_oauth_callback",
+    method: "GET",
+    path: "/api/auth/oauth/github/callback",
+    description: "OAuth provider callback stub"
+  },
+  {
+    name: "auth_refresh",
+    method: "POST",
+    path: "/api/auth/refresh",
+    description: "Refresh an access token"
+  },
+  {
+    name: "users_list",
+    method: "GET",
+    path: "/api/users",
+    description: "List users"
+  },
+  {
+    name: "users_create",
+    method: "POST",
+    path: "/api/users",
+    description: "Create a freelancer profile-sized user record",
+    request: ({ iteration }) =>
+      jsonBody({
+        email: `benchmark.freelancer.${iteration}@example.com`,
+        name: "Benchmark Freelancer",
+        role: "freelancer",
+        hourlyRate: 85,
+        skills: ["node", "react", "api-performance", "payments"],
+        bio: "Senior full-stack freelancer with marketplace and payments experience."
+      })
+  },
+  {
+    name: "jobs_list",
+    method: "GET",
+    path: "/api/jobs",
+    description: "List jobs"
+  },
+  {
+    name: "jobs_create",
+    method: "POST",
+    path: "/api/jobs",
+    description: "Create a realistic marketplace job",
+    request: ({ iteration }) =>
+      jsonBody({
+        title: `Benchmark dashboard build ${iteration}`,
+        description: longJobDescription,
+        budgetMin: 1500,
+        budgetMax: 4500,
+        categoryId: "web-apps",
+        skills: ["node", "react", "postgres", "payments"]
+      })
+  },
+  {
+    name: "proposals_list",
+    method: "GET",
+    path: "/api/proposals",
+    description: "List proposals"
+  },
+  {
+    name: "proposals_create",
+    method: "POST",
+    path: "/api/proposals",
+    description: "Create a proposal payload",
+    request: ({ iteration }) =>
+      jsonBody({
+        jobId: `job_benchmark_${iteration}`,
+        freelancerId: "usr_benchmark_freelancer",
+        coverLetter:
+          "I can deliver the API benchmark dashboard in two milestones with automated validation and weekly demos.",
+        proposedBudget: 3200,
+        estimatedDays: 14
+      })
+  },
+  {
+    name: "payments_create",
+    method: "POST",
+    path: "/api/payments",
+    description: "Create a payment intent-sized payload",
+    request: ({ iteration }) =>
+      jsonBody({
+        jobId: `job_benchmark_${iteration}`,
+        clientId: "usr_benchmark_client",
+        freelancerId: "usr_benchmark_freelancer",
+        amount: 3200,
+        currency: "usd"
+      })
+  },
+  {
+    name: "reviews_list",
+    method: "GET",
+    path: "/api/reviews",
+    description: "List reviews"
+  },
+  {
+    name: "reviews_create",
+    method: "POST",
+    path: "/api/reviews",
+    description: "Create a post-project review",
+    request: ({ iteration }) =>
+      jsonBody({
+        jobId: `job_benchmark_${iteration}`,
+        reviewerId: "usr_benchmark_client",
+        revieweeId: "usr_benchmark_freelancer",
+        rating: 5,
+        comment: "Delivered quickly, communicated clearly, and kept the API stable under load."
+      })
+  },
+  {
+    name: "messages_list",
+    method: "GET",
+    path: "/api/messages",
+    description: "List messages"
+  },
+  {
+    name: "messages_create",
+    method: "POST",
+    path: "/api/messages",
+    description: "Send a project message",
+    request: ({ iteration }) =>
+      jsonBody({
+        threadId: `thread_benchmark_${iteration % 3}`,
+        senderId: "usr_benchmark_client",
+        recipientId: "usr_benchmark_freelancer",
+        body: "Can you share the latest milestone status and benchmark report before the review call?"
+      })
+  },
+  {
+    name: "notifications_list",
+    method: "GET",
+    path: "/api/notifications",
+    description: "List notifications"
+  },
+  {
+    name: "notifications_create",
+    method: "POST",
+    path: "/api/notifications",
+    description: "Create a notification",
+    request: ({ iteration }) =>
+      jsonBody({
+        userId: "usr_benchmark_freelancer",
+        type: "proposal_update",
+        title: "Proposal shortlisted",
+        message: `Benchmark notification ${iteration}: your proposal moved to review.`
+      })
+  },
+  {
+    name: "uploads_create",
+    method: "POST",
+    path: "/api/uploads",
+    description: "Upload a representative text attachment",
+    request: uploadBody
+  },
+  {
+    name: "search",
+    method: "GET",
+    path: "/api/search?q=react%20payments%20benchmark",
+    description: "Search with realistic keywords"
+  },
+  {
+    name: "admin_metrics",
+    method: "GET",
+    path: "/api/admin/metrics",
+    description: "Protected admin metrics route",
+    auth: true
+  }
+];