@donkeylabs/server 2.0.17 → 2.0.19

package/CLAUDE.md

@@ -139,11 +139,31 @@ throw ctx.errors.BadRequest("Invalid input");    // 400
 throw ctx.errors.Unauthorized("Login required"); // 401
 ```
 
+## Testing
+```ts
+// Unit test plugins (no HTTP)
+import { createTestHarness } from "@donkeylabs/server";
+const { manager } = await createTestHarness(myPlugin);
+
+// Integration test with HTTP (parallel-safe, unique ports)
+import { createIntegrationHarness } from "@donkeylabs/server";
+import { createApiClient } from "../lib/api";
+
+const harness = await createIntegrationHarness({
+  routers: [usersRouter],
+  plugins: [usersPlugin],
+});
+const api = harness.createClient(createApiClient); // Fully typed!
+await api.users.create({ name: "Test" });
+await harness.shutdown();
+```
+
 ## Commands
 ```sh
 bun run dev               # Dev server
 bunx donkeylabs generate  # Regen types after changes
 bun --bun tsc --noEmit    # Type check
+bun test                  # Run tests
 ```
 
 ## MCP Tools
@@ -154,4 +174,5 @@ bun --bun tsc --noEmit    # Type check
 - Core: logger, cache, events, cron, jobs, external-jobs, processes, workflows, sse, rate-limiter, errors
 - API: router, handlers, middleware
 - Server: lifecycle-hooks, services (custom services)
-- Infrastructure: database, plugins, testing, sveltekit-adapter, api-client
+- Testing: `createTestHarness` (unit), `createIntegrationHarness` (HTTP)
+- Infrastructure: database, plugins, sveltekit-adapter, api-client

package/docs/testing.md

@@ -1,25 +1,61 @@
 # Testing
 
-This guide covers testing plugins and routes using the built-in test harness.
+This guide covers testing plugins and routes using the built-in test harnesses.
 
 ## Table of Contents
 
-- [Test Harness](#test-harness)
+- [Quick Start](#quick-start)
+- [Test Harnesses](#test-harnesses)
+  - [createTestHarness](#createtestharness) - Unit testing plugins
+  - [createIntegrationHarness](#createintegrationharness) - Full HTTP API testing
 - [Unit Testing Plugins](#unit-testing-plugins)
-- [Integration Testing](#integration-testing)
+- [Integration Testing with HTTP](#integration-testing-with-http)
 - [Testing Routes](#testing-routes)
+- [Parallel Test Execution](#parallel-test-execution)
 - [Mocking Core Services](#mocking-core-services)
 - [Test Organization](#test-organization)
 - [Running Tests](#running-tests)
 
 ---
 
-## Test Harness
+## Quick Start
 
-The test harness creates a fully functional in-memory testing environment with real SQLite, migrations, and all core services.
+```ts
+// Unit test (no HTTP, fast)
+import { createTestHarness } from "@donkeylabs/server";
+const { manager } = await createTestHarness(myPlugin);
+const result = await manager.getServices().myPlugin.doSomething();
+
+// Integration test (full HTTP server)
+import { createIntegrationHarness } from "@donkeylabs/server";
+import { createApiClient } from "../lib/api"; // Your generated client
+
+const harness = await createIntegrationHarness({
+  routers: [myRouter],
+  plugins: [myPlugin],
+});
+const api = harness.createClient(createApiClient);
+const user = await api.users.create({ name: "Test" }); // Fully typed!
+await harness.shutdown();
+```
+
+---
+
+## Test Harnesses
+
+DonkeyLabs provides two test harnesses for different testing needs:
+
+| Harness | Use Case | HTTP Server | Speed |
+|---------|----------|-------------|-------|
+| `createTestHarness` | Unit testing plugins | No | Fast |
+| `createIntegrationHarness` | Full API testing | Yes | Medium |
+
+### createTestHarness
+
+For unit testing plugin services without HTTP overhead. Creates an in-memory environment with SQLite, migrations, and all core services.
 
 ```ts
-import { createTestHarness } from "@donkeylabs/server/harness";
+import { createTestHarness } from "@donkeylabs/server";
 import { myPlugin } from "./plugins/myPlugin";
 
 const { manager, db, core } = await createTestHarness(myPlugin);
@@ -35,12 +71,12 @@ core.logger.info("Test log");
 core.cache.set("key", "value");
 ```
 
-### With Dependencies
+#### With Dependencies
 
 If your plugin depends on other plugins, pass them as the second argument:
 
 ```ts
-import { createTestHarness } from "@donkeylabs/server/harness";
+import { createTestHarness } from "@donkeylabs/server";
 import { ordersPlugin } from "./plugins/orders";
 import { usersPlugin } from "./plugins/users";
 
@@ -51,6 +87,65 @@ const orders = manager.getServices().orders;
 const users = manager.getServices().users;
 ```
 
+### createIntegrationHarness
+
+For full HTTP API testing with your generated client. Starts a real HTTP server on a unique port for parallel test execution.
+
+```ts
+import { createIntegrationHarness, type IntegrationHarnessResult } from "@donkeylabs/server";
+import { createApiClient } from "../lib/api"; // Your generated client
+import { usersRouter } from "../server/routes/users";
+import { usersPlugin } from "../server/plugins/users";
+
+describe("Users API", () => {
+  let harness: IntegrationHarnessResult;
+  let api: ReturnType<typeof createApiClient>;
+
+  beforeAll(async () => {
+    harness = await createIntegrationHarness({
+      routers: [usersRouter],
+      plugins: [usersPlugin],
+    });
+    api = harness.createClient(createApiClient);
+  });
+
+  afterAll(async () => {
+    await harness.shutdown();
+  });
+
+  it("should create a user", async () => {
+    const user = await api.users.create({ name: "Test", email: "test@example.com" });
+    expect(user.id).toBeDefined();
+  });
+});
+```
+
+#### Harness Result Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `server` | `AppServer` | The running server instance |
+| `baseUrl` | `string` | Base URL (e.g., `http://localhost:12345`) |
+| `port` | `number` | Actual port the server is running on |
+| `db` | `Kysely<any>` | Database instance for direct queries |
+| `core` | `CoreServices` | Core services (logger, cache, etc.) |
+| `plugins` | `Record<string, any>` | Plugin services |
+| `client` | `TestApiClient` | Untyped client for quick testing |
+| `createClient` | `<T>(factory) => T` | Create typed client from your factory |
+| `shutdown` | `() => Promise<void>` | Cleanup function |
+
+#### Configuration Options
+
+```ts
+interface IntegrationHarnessOptions {
+  routers?: IRouter[];           // Routers to register
+  plugins?: Plugin[];            // Plugins to register
+  port?: number;                 // Starting port (default: random 10000-60000)
+  maxPortAttempts?: number;      // Retry attempts (default: 10)
+  logLevel?: "debug" | "info" | "warn" | "error"; // Default: "error"
+}
+```
+
 ---
 
 ## Unit Testing Plugins
@@ -138,9 +233,93 @@ describe("usersPlugin", () => {
 
 ---
 
-## Integration Testing
+## Integration Testing with HTTP
+
+Use `createIntegrationHarness` for full end-to-end API testing with your generated client.
+
+### Basic Example
+
+```ts
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { createIntegrationHarness, type IntegrationHarnessResult } from "@donkeylabs/server";
+import { createApiClient } from "../lib/api";
+import { usersRouter } from "../server/routes/users";
+
+describe("Users API", () => {
+  let harness: IntegrationHarnessResult;
+  let api: ReturnType<typeof createApiClient>;
+
+  beforeAll(async () => {
+    harness = await createIntegrationHarness({
+      routers: [usersRouter],
+    });
+    api = harness.createClient(createApiClient);
+  });
+
+  afterAll(async () => {
+    await harness.shutdown();
+  });
+
+  it("should create and retrieve a user", async () => {
+    // Create
+    const created = await api.users.create({
+      name: "Test User",
+      email: "test@example.com",
+    });
+    expect(created.id).toBeDefined();
+
+    // Retrieve
+    const user = await api.users.get({ id: created.id });
+    expect(user.name).toBe("Test User");
+  });
+
+  it("should list users", async () => {
+    const result = await api.users.list({});
+    expect(result.users.length).toBeGreaterThan(0);
+  });
+});
+```
+
+### With Plugins
+
+```ts
+import { usersPlugin } from "../server/plugins/users";
+import { ordersPlugin } from "../server/plugins/orders";
+import { ordersRouter } from "../server/routes/orders";
+
+const harness = await createIntegrationHarness({
+  routers: [ordersRouter],
+  plugins: [usersPlugin, ordersPlugin],
+});
+```
+
+### Accessing Services Directly
+
+You can access plugin services and core services for test setup:
+
+```ts
+it("should process order for existing user", async () => {
+  // Use plugin service directly to create test data
+  const user = await harness.plugins.users.create({
+    email: "buyer@example.com",
+    name: "Buyer",
+  });
+
+  // Test via API
+  const order = await api.orders.create({
+    userId: user.id,
+    items: [{ productId: 1, quantity: 2 }],
+  });
+
+  expect(order.status).toBe("pending");
+});
+```
+
+---
+
+## Integration Testing (Plugin-Level)
 
-Integration tests verify multiple plugins working together.
+Integration tests verify multiple plugins working together without HTTP.
 
 ```ts
 // tests/checkout.integ.test.ts
@@ -419,12 +598,83 @@ jobs:
 
 ---
 
+## Parallel Test Execution
+
+`createIntegrationHarness` is designed for parallel test execution:
+
+1. **Unique ports** - Each harness gets a random port (10000-60000 range)
+2. **Automatic retry** - If port is in use, tries next port (up to 10 attempts)
+3. **In-memory isolation** - Each test has its own SQLite `:memory:` database
+4. **No file conflicts** - Type generation is disabled during tests
+
+### Example: Parallel Test Suites
+
+```ts
+// users.test.ts
+describe("Users API", () => {
+  let harness: IntegrationHarnessResult;
+
+  beforeAll(async () => {
+    harness = await createIntegrationHarness({ routers: [usersRouter] });
+  });
+  afterAll(() => harness.shutdown());
+
+  it("creates users", async () => {
+    // This test runs on port 12345 (random)
+  });
+});
+
+// orders.test.ts (runs in parallel)
+describe("Orders API", () => {
+  let harness: IntegrationHarnessResult;
+
+  beforeAll(async () => {
+    harness = await createIntegrationHarness({ routers: [ordersRouter] });
+  });
+  afterAll(() => harness.shutdown());
+
+  it("creates orders", async () => {
+    // This test runs on port 54321 (different random port)
+  });
+});
+```
+
+Both test files run simultaneously without conflicts.
+
+### Why Use the Generated Client?
+
+The generated client (`lib/api.ts`) provides:
+- Full TypeScript types for all routes
+- IDE autocomplete while writing tests
+- Compile-time error checking
+
+The client is generated once during development (`bunx donkeylabs generate`) and imported in tests. No regeneration happens at test runtime.
+
+---
+
 ## Best Practices
 
-1. **Use fresh harness per test** - Create a new harness in `beforeEach` to ensure test isolation
-2. **Test the public API** - Focus on testing service methods, not internal implementation
-3. **Use realistic data** - Create test data that resembles production data
-4. **Test edge cases** - Empty inputs, null values, boundary conditions
-5. **Test error cases** - Verify proper error throwing and handling
-6. **Keep tests fast** - In-memory SQLite is fast; avoid unnecessary delays
-7. **Run type checks** - Always run `tsc --noEmit` before committing
+1. **Choose the right harness**:
+   - `createTestHarness` for unit tests (fast, no HTTP)
+   - `createIntegrationHarness` for API tests (full HTTP, typed client)
+
+2. **Use fresh harness per test suite** - Create harness in `beforeAll`, shutdown in `afterAll`
+
+3. **Always call shutdown** - Prevent port leaks and hanging tests:
+   ```ts
+   afterAll(() => harness.shutdown());
+   ```
+
+4. **Use your generated client** - Import from `lib/api.ts` for full type safety
+
+5. **Test the public API** - Focus on testing service methods, not internal implementation
+
+6. **Use realistic data** - Create test data that resembles production data
+
+7. **Test edge cases** - Empty inputs, null values, boundary conditions
+
+8. **Test error cases** - Verify proper error throwing and handling
+
+9. **Keep tests fast** - In-memory SQLite is fast; avoid unnecessary delays
+
+10. **Run type checks** - Always run `tsc --noEmit` before committing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donkeylabs/server",
-  "version": "2.0.17",
+  "version": "2.0.19",
   "type": "module",
   "description": "Type-safe plugin system for building RPC-style APIs with Bun",
   "main": "./src/index.ts",
@@ -30,6 +30,10 @@
       "types": "./src/process-client.ts",
       "import": "./src/process-client.ts"
     },
+    "./testing": {
+      "types": "./src/testing/index.ts",
+      "import": "./src/testing/index.ts"
+    },
     "./context": {
       "types": "./context.d.ts"
     },
@@ -68,7 +72,10 @@
     "kysely": "^0.27.0 || ^0.28.0",
     "zod": "^3.20.0",
     "@aws-sdk/client-s3": "^3.0.0",
-    "@aws-sdk/s3-request-presigner": "^3.0.0"
+    "@aws-sdk/s3-request-presigner": "^3.0.0",
+    "@playwright/test": "^1.40.0",
+    "pg": "^8.0.0",
+    "mysql2": "^3.0.0"
   },
   "peerDependenciesMeta": {
     "@aws-sdk/client-s3": {
@@ -76,6 +83,15 @@
     },
     "@aws-sdk/s3-request-presigner": {
       "optional": true
+    },
+    "@playwright/test": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    },
+    "mysql2": {
+      "optional": true
     }
   },
   "dependencies": {

package/src/core/cron.ts

@@ -109,21 +109,109 @@ class CronExpression {
     );
   }
 
+  /**
+   * Get the next run time using an optimized jump algorithm.
+   * Instead of iterating second-by-second (which could be 31M iterations),
+   * this jumps directly to the next valid value for each field.
+   */
   getNextRun(from: Date = new Date()): Date {
     const next = new Date(from);
     next.setMilliseconds(0);
     next.setSeconds(next.getSeconds() + 1);
 
-    // Search up to 1 year ahead
-    const maxIterations = 366 * 24 * 60 * 60;
-    for (let i = 0; i < maxIterations; i++) {
-      if (this.matches(next)) {
-        return next;
+    const [seconds, minutes, hours, daysOfMonth, months, daysOfWeek] = this.fields;
+
+    // Maximum iterations to prevent infinite loops (covers 4 years to handle leap years)
+    const maxYearIterations = 4;
+    const startYear = next.getFullYear();
+
+    // Iterate through potential dates (worst case: a few hundred iterations)
+    for (let yearOffset = 0; yearOffset <= maxYearIterations; yearOffset++) {
+      // Try each valid month
+      for (const month of months) {
+        const targetMonth = month - 1; // JS months are 0-indexed
+
+        // Skip months in the past
+        if (next.getFullYear() === startYear + yearOffset) {
+          if (targetMonth < next.getMonth()) continue;
+        }
+
+        // Set to this month
+        if (targetMonth !== next.getMonth() || next.getFullYear() !== startYear + yearOffset) {
+          next.setFullYear(startYear + yearOffset, targetMonth, 1);
+          next.setHours(0, 0, 0, 0);
+        }
+
+        // Get days in this month
+        const daysInMonth = new Date(next.getFullYear(), targetMonth + 1, 0).getDate();
+
+        // Try each valid day of month
+        for (const dayOfMonth of daysOfMonth) {
+          if (dayOfMonth > daysInMonth) continue; // Skip invalid days for this month
+
+          // Check if this day matches day-of-week constraint
+          const testDate = new Date(next.getFullYear(), targetMonth, dayOfMonth);
+          const dayOfWeek = testDate.getDay();
+          if (!daysOfWeek.includes(dayOfWeek)) continue;
+
+          // Skip days in the past
+          if (testDate < new Date(from.getFullYear(), from.getMonth(), from.getDate())) continue;
+
+          // Set to this day
+          if (dayOfMonth !== next.getDate()) {
+            next.setDate(dayOfMonth);
+            next.setHours(0, 0, 0, 0);
+          }
+
+          // Try each valid hour
+          for (const hour of hours) {
+            // Skip hours in the past for today
+            if (next.getFullYear() === from.getFullYear() &&
+                next.getMonth() === from.getMonth() &&
+                next.getDate() === from.getDate() &&
+                hour < from.getHours()) continue;
+
+            if (hour !== next.getHours()) {
+              next.setHours(hour, 0, 0, 0);
+            }
+
+            // Try each valid minute
+            for (const minute of minutes) {
+              // Skip minutes in the past for this hour
+              if (next.getFullYear() === from.getFullYear() &&
+                  next.getMonth() === from.getMonth() &&
+                  next.getDate() === from.getDate() &&
+                  next.getHours() === from.getHours() &&
+                  minute < from.getMinutes()) continue;
+
+              if (minute !== next.getMinutes()) {
+                next.setMinutes(minute, 0, 0);
+              }
+
+              // Try each valid second
+              for (const second of seconds) {
+                // Skip seconds in the past for this minute
+                if (next.getFullYear() === from.getFullYear() &&
+                    next.getMonth() === from.getMonth() &&
+                    next.getDate() === from.getDate() &&
+                    next.getHours() === from.getHours() &&
+                    next.getMinutes() === from.getMinutes() &&
+                    second <= from.getSeconds()) continue;
+
+                next.setSeconds(second);
+
+                // Verify the date is still valid (handles edge cases like month rollover)
+                if (next > from && this.matches(next)) {
+                  return next;
+                }
+              }
+            }
+          }
+        }
       }
-      next.setSeconds(next.getSeconds() + 1);
     }
 
-    throw new Error("Could not find next run time within 1 year");
+    throw new Error("Could not find next run time within 4 years");
   }
 }
 

package/src/core/workflows.ts

@@ -195,6 +195,8 @@ export interface WorkflowContext {
   getStepResult<T = any>(stepName: string): T | undefined;
   /** Core services (logger, events, cache, etc.) */
   core: CoreServices;
+  /** Plugin services - available for business logic in workflow handlers */
+  plugins: Record<string, any>;
 }
 
 // ============================================
@@ -558,6 +560,8 @@ export interface Workflows {
   stop(): Promise<void>;
   /** Set core services (called after initialization to resolve circular dependency) */
   setCore(core: CoreServices): void;
+  /** Set plugin services (called after plugins are initialized) */
+  setPlugins(plugins: Record<string, any>): void;
 }
 
 // ============================================
@@ -570,6 +574,7 @@ class WorkflowsImpl implements Workflows {
   private jobs?: Jobs;
   private sse?: SSE;
   private core?: CoreServices;
+  private plugins: Record<string, any> = {};
   private definitions = new Map<string, WorkflowDefinition>();
   private running = new Map<string, { timeout?: ReturnType<typeof setTimeout> }>();
   private pollInterval: number;
@@ -587,6 +592,10 @@ class WorkflowsImpl implements Workflows {
     this.core = core;
   }
 
+  setPlugins(plugins: Record<string, any>): void {
+    this.plugins = plugins;
+  }
+
   register(definition: WorkflowDefinition): void {
     if (this.definitions.has(definition.name)) {
       throw new Error(`Workflow "${definition.name}" is already registered`);
@@ -1150,6 +1159,7 @@ class WorkflowsImpl implements Workflows {
         return steps[stepName] as T | undefined;
       },
       core: this.core!,
+      plugins: this.plugins,
     };
   }
 

package/src/harness.ts

@@ -20,6 +20,9 @@ import {
   KyselyWorkflowAdapter,
   MemoryAuditAdapter,
 } from "./core/index";
+import { AppServer, type ServerConfig } from "./server";
+import type { IRouter, RouteDefinition } from "./router";
+import { ApiClientBase, type ApiClientOptions } from "./client/base";
 
 /**
  * Creates a fully functional (in-memory) testing environment for a plugin.
@@ -104,3 +107,277 @@ export async function createTestHarness(targetPlugin: Plugin, dependencies: Plug
     core
   };
 }
+
+// =============================================================================
+// INTEGRATION TEST HARNESS
+// =============================================================================
+
+/**
+ * Configuration for the integration test harness.
+ */
+export interface IntegrationHarnessOptions {
+  /** Routers to register with the server */
+  routers?: IRouter[];
+  /** Plugins to register with the server */
+  plugins?: Plugin[];
+  /** Starting port range (default: 10000-60000 random) */
+  port?: number;
+  /** Maximum port retry attempts (default: 10) */
+  maxPortAttempts?: number;
+  /** Logger level (default: "error" for quiet tests) */
+  logLevel?: "debug" | "info" | "warn" | "error";
+}
+
+/**
+ * A dynamic API client built from router definitions.
+ * Provides an untyped but convenient way to call routes.
+ */
+export class TestApiClient extends ApiClientBase {
+  private routeMap: Map<string, RouteDefinition>;
+
+  constructor(baseUrl: string, routers: IRouter[]) {
+    super(baseUrl);
+    this.routeMap = new Map();
+    for (const router of routers) {
+      for (const route of router.getRoutes()) {
+        this.routeMap.set(route.name, route);
+      }
+    }
+  }
+
+  /**
+   * Call any route by name with the given input.
+   * Convenient for quick testing without generated types.
+   *
+   * @example
+   * ```ts
+   * const user = await client.call("users.create", { name: "Test", email: "test@example.com" });
+   * ```
+   */
+  async call<TOutput = any>(route: string, input: any = {}): Promise<TOutput> {
+    const routeDef = this.routeMap.get(route);
+    if (!routeDef) {
+      throw new Error(`Route not found: ${route}. Available routes: ${[...this.routeMap.keys()].join(", ")}`);
+    }
+
+    // Handle different handler types
+    if (routeDef.handler === "typed" || routeDef.handler === "formData") {
+      return this.request(route, input);
+    } else if (routeDef.handler === "stream" || routeDef.handler === "html") {
+      const response = await this.rawRequest(route, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(input),
+      });
+      return response as any;
+    } else if (routeDef.handler === "raw") {
+      const response = await this.rawRequest(route);
+      return response as any;
+    }
+
+    return this.request(route, input);
+  }
+
+  /**
+   * Get a raw Response for stream/file routes.
+   */
+  async stream(route: string, input: any = {}): Promise<Response> {
+    return this.rawRequest(route, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input),
+    });
+  }
+
+  /**
+   * List all available routes.
+   */
+  routes(): string[] {
+    return [...this.routeMap.keys()];
+  }
+}
+
+/**
+ * Result from createIntegrationHarness.
+ */
+export interface IntegrationHarnessResult {
+  /** The running AppServer instance */
+  server: AppServer;
+  /** Base URL for API calls (e.g., "http://localhost:12345") */
+  baseUrl: string;
+  /** The actual port the server is running on */
+  port: number;
+  /** Database instance */
+  db: Kysely<any>;
+  /** Core services */
+  core: CoreServices;
+  /** Plugin services (after initialization) */
+  plugins: Record<string, any>;
+  /**
+   * Untyped test client for quick testing.
+   * Use `client.call("route.name", input)` to call any route.
+   *
+   * @example
+   * ```ts
+   * const user = await harness.client.call("users.create", { name: "Test" });
+   * ```
+   */
+  client: TestApiClient;
+  /**
+   * Create a typed client using your generated client factory.
+   * Pass your `createApiClient` function to get full type safety.
+   *
+   * @example
+   * ```ts
+   * import { createApiClient } from "../lib/api";
+   * const api = harness.createClient(createApiClient);
+   * const user = await api.users.create({ name: "Test" }); // Fully typed!
+   * ```
+   */
+  createClient: <T>(factory: (config: { baseUrl: string }) => T) => T;
+  /** Shutdown function - call this in afterAll/afterEach */
+  shutdown: () => Promise<void>;
+}
+
+// Track used ports across test files running in parallel
+const usedPorts = new Set<number>();
+
+/**
+ * Get a unique starting port for parallel test execution.
+ * Uses random port in range 10000-60000 and tracks to avoid collisions.
+ */
+function getUniquePort(): number {
+  const minPort = 10000;
+  const maxPort = 60000;
+  let port: number;
+  let attempts = 0;
+  const maxAttempts = 100;
+
+  do {
+    port = minPort + Math.floor(Math.random() * (maxPort - minPort));
+    attempts++;
+  } while (usedPorts.has(port) && attempts < maxAttempts);
+
+  usedPorts.add(port);
+  return port;
+}
+
+/**
+ * Creates a full integration testing environment with a real HTTP server.
+ *
+ * Use this when you need to test API routes end-to-end with the generated
+ * API client. The server runs in-memory (SQLite :memory:) and uses a random
+ * port for parallel test execution.
+ *
+ * @example
+ * ```ts
+ * import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+ * import { createIntegrationHarness } from "@donkeylabs/server";
+ * import { createApiClient } from "../lib/api"; // Your generated client
+ * import { usersRouter } from "../server/routes/users";
+ * import { usersPlugin } from "../server/plugins/users";
+ *
+ * describe("Users API", () => {
+ *   let harness: Awaited<ReturnType<typeof createIntegrationHarness>>;
+ *   let api: ReturnType<typeof createApiClient>;
+ *
+ *   beforeAll(async () => {
+ *     harness = await createIntegrationHarness({
+ *       routers: [usersRouter],
+ *       plugins: [usersPlugin],
+ *     });
+ *     api = createApiClient({ baseUrl: harness.baseUrl });
+ *   });
+ *
+ *   afterAll(async () => {
+ *     await harness.shutdown();
+ *   });
+ *
+ *   it("should create a user", async () => {
+ *     const user = await api.users.create({ name: "Test", email: "test@example.com" });
+ *     expect(user.id).toBeDefined();
+ *   });
+ *
+ *   it("should list users", async () => {
+ *     const result = await api.users.list({});
+ *     expect(result.users.length).toBeGreaterThan(0);
+ *   });
+ * });
+ * ```
+ */
+export async function createIntegrationHarness(
+  options: IntegrationHarnessOptions = {}
+): Promise<IntegrationHarnessResult> {
+  const {
+    routers = [],
+    plugins = [],
+    port = getUniquePort(),
+    maxPortAttempts = 10,
+    logLevel = "error",
+  } = options;
+
+  // 1. Setup In-Memory DB
+  const db = new Kysely<any>({
+    dialect: new BunSqliteDialect({ database: new Database(":memory:") }),
+  });
+
+  // 2. Create server with test configuration
+  const server = new AppServer({
+    db,
+    port,
+    maxPortAttempts,
+    logger: { level: logLevel },
+    // Disable file generation in tests
+    generateTypes: undefined,
+  });
+
+  // 3. Register plugins
+  for (const plugin of plugins) {
+    server.registerPlugin(plugin);
+  }
+
+  // 4. Register routers
+  for (const router of routers) {
+    server.use(router);
+  }
+
+  // 5. Start the server
+  await server.start();
+
+  // Get the actual port (may have changed if initial was in use)
+  const actualPort = (server as any).port as number;
+  const baseUrl = `http://localhost:${actualPort}`;
+
+  // Track this port as used
+  usedPorts.add(actualPort);
+
+  // Get core services and plugins for direct access in tests
+  const core = (server as any).coreServices as CoreServices;
+  const pluginServices = (server as any).manager.getServices();
+
+  // Create untyped test client
+  const client = new TestApiClient(baseUrl, routers);
+
+  // Factory for typed clients
+  const createClient = <T>(factory: (config: { baseUrl: string }) => T): T => {
+    return factory({ baseUrl });
+  };
+
+  // Shutdown function
+  const shutdown = async () => {
+    await server.shutdown();
+    usedPorts.delete(actualPort);
+  };
+
+  return {
+    server,
+    baseUrl,
+    port: actualPort,
+    db,
+    core,
+    plugins: pluginServices,
+    client,
+    createClient,
+    shutdown,
+  };
+}

package/src/index.ts

@@ -121,5 +121,11 @@ export {
   createAdminRouter,
 } from "./admin";
 
-// Test Harness - for plugin testing
-export { createTestHarness } from "./harness";
+// Test Harness - for plugin and integration testing
+export {
+  createTestHarness,
+  createIntegrationHarness,
+  TestApiClient,
+  type IntegrationHarnessOptions,
+  type IntegrationHarnessResult,
+} from "./harness";

package/src/server.ts

@@ -205,6 +205,8 @@ export class AppServer {
   private shutdownHandlers: OnShutdownHandler[] = [];
   private errorHandlers: OnErrorHandler[] = [];
   private isShuttingDown = false;
+  private isInitialized = false;
+  private initializationPromise: Promise<void> | null = null;
   private generateModeSetup = false;
 
   // Custom services registry
@@ -955,6 +957,27 @@ ${factoryFunction}
       process.exit(0);
     }
 
+    // Guard against multiple initializations using promise-based mutex
+    // This prevents race conditions when multiple requests arrive concurrently
+    if (this.isInitialized) {
+      this.coreServices.logger.debug("Server already initialized, skipping");
+      return;
+    }
+    if (this.initializationPromise) {
+      this.coreServices.logger.debug("Server initialization in progress, waiting...");
+      await this.initializationPromise;
+      return;
+    }
+
+    // Create the initialization promise - all concurrent callers will await this same promise
+    this.initializationPromise = this.doInitialize();
+    await this.initializationPromise;
+  }
+
+  /**
+   * Internal initialization logic - only called once via the promise mutex
+   */
+  private async doInitialize(): Promise<void> {
     const { logger } = this.coreServices;
 
     // Auto-generate types in dev mode if configured
@@ -963,6 +986,11 @@ ${factoryFunction}
     await this.manager.migrate();
     await this.manager.init();
 
+    // Pass plugins to workflows so handlers can access ctx.plugins
+    this.coreServices.workflows.setPlugins(this.manager.getServices());
+
+    this.isInitialized = true;
+
     this.coreServices.cron.start();
     this.coreServices.jobs.start();
     await this.coreServices.workflows.resume();
@@ -1185,34 +1213,20 @@ ${factoryFunction}
       process.exit(0);
     }
 
-    const { logger } = this.coreServices;
-
-    // Auto-generate types in dev mode if configured
-    await this.generateTypes();
-
-    // 1. Run migrations
-    await this.manager.migrate();
-
-    // 2. Initialize plugins
-    await this.manager.init();
-
-    // 3. Start background services
-    this.coreServices.cron.start();
-    this.coreServices.jobs.start();
-    await this.coreServices.workflows.resume();
-    this.coreServices.processes.start();
-    logger.info("Background services started (cron, jobs, workflows, processes)");
-
-    // 4. Build route map
-    for (const router of this.routers) {
-      for (const route of router.getRoutes()) {
-        if (this.routeMap.has(route.name)) {
-          logger.warn(`Duplicate route detected`, { route: route.name });
-        }
-        this.routeMap.set(route.name, route);
+    // Guard against multiple initializations using promise-based mutex
+    // This prevents race conditions when multiple requests arrive concurrently
+    if (!this.isInitialized) {
+      if (this.initializationPromise) {
+        this.coreServices.logger.debug("Server initialization in progress, waiting...");
+        await this.initializationPromise;
+      } else {
+        // Create the initialization promise - all concurrent callers will await this same promise
+        this.initializationPromise = this.doInitialize();
+        await this.initializationPromise;
       }
     }
-    logger.info(`Loaded ${this.routeMap.size} RPC routes`);
+
+    const { logger } = this.coreServices;
 
     // 5. Start HTTP server with port retry logic
     const fetchHandler = async (req: Request, server: ReturnType<typeof Bun.serve>) => {