@donkeylabs/server 2.0.30 → 2.0.32

package/docs/workflows.md

@@ -89,6 +89,26 @@ const instanceId = await ctx.core.workflows.start("process-order", {
 });
 ```
 
+### Concurrency Guard
+
+Limit concurrent instances per workflow name:
+
+```ts
+const server = new AppServer({
+  db,
+  workflows: {
+    concurrentWorkflows: 1, // default for all workflows (0 = unlimited)
+    concurrentWorkflowsByName: {
+      testWorkflow: 1,
+      ingestionWorkflow: 1,
+    },
+  },
+});
+
+// Or per-register override
+ctx.core.workflows.register(orderWorkflow, { maxConcurrent: 1 });
+```
+
 ### 3. Track Progress
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donkeylabs/server",
-  "version": "2.0.30",
+  "version": "2.0.32",
   "type": "module",
   "description": "Type-safe plugin system for building RPC-style APIs with Bun",
   "main": "./src/index.ts",

package/src/core/workflows.ts

@@ -766,6 +766,10 @@ export interface WorkflowsConfig {
   sqlitePragmas?: SqlitePragmaConfig;
   /** Disable in-process watchdog timers (use external watchdog instead) */
   useWatchdog?: boolean;
+  /** Default max concurrent instances per workflow name (0 = unlimited, default: 0) */
+  concurrentWorkflows?: number;
+  /** Per-workflow concurrency overrides */
+  concurrentWorkflowsByName?: Record<string, number>;
   /** Resume strategy for orphaned workflows (default: "blocking") */
   resumeStrategy?: WorkflowResumeStrategy;
 }
@@ -794,6 +798,8 @@ export interface WorkflowRegisterOptions {
    * workflows.register(myWorkflow, { modulePath: import.meta.url });
    */
   modulePath?: string;
+  /** Max concurrent instances for this workflow (overrides defaults) */
+  maxConcurrent?: number;
 }
 
 export interface Workflows {
@@ -871,6 +877,9 @@ class WorkflowsImpl implements Workflows {
   private killGraceMs: number;
   private sqlitePragmas?: SqlitePragmaConfig;
   private useWatchdog: boolean;
+  private concurrentWorkflows: number;
+  private concurrentWorkflowsByName: Record<string, number>;
+  private workflowConcurrencyOverrides = new Map<string, number>();
   private resumeStrategy!: WorkflowResumeStrategy;
   private workflowModulePaths = new Map<string, string>();
   private isolatedProcesses = new Map<string, IsolatedProcessInfo>();
@@ -908,6 +917,8 @@ class WorkflowsImpl implements Workflows {
     this.killGraceMs = config.killGraceMs ?? 5000;
     this.sqlitePragmas = config.sqlitePragmas;
     this.useWatchdog = config.useWatchdog ?? false;
+    this.concurrentWorkflows = config.concurrentWorkflows ?? 0;
+    this.concurrentWorkflowsByName = config.concurrentWorkflowsByName ?? {};
     this.resumeStrategy = config.resumeStrategy ?? "blocking";
   }
 
@@ -998,6 +1009,10 @@ class WorkflowsImpl implements Workflows {
     }
 
     this.definitions.set(definition.name, definition);
+
+    if (options?.maxConcurrent !== undefined) {
+      this.workflowConcurrencyOverrides.set(definition.name, options.maxConcurrent);
+    }
   }
 
   async start<T = any>(workflowName: string, input: T): Promise<string> {
@@ -1006,6 +1021,17 @@ class WorkflowsImpl implements Workflows {
       throw new Error(`Workflow "${workflowName}" is not registered`);
     }
 
+    const limit = this.getConcurrencyLimit(workflowName);
+    if (limit > 0) {
+      const running = await this.adapter.getInstancesByWorkflow(workflowName, "running");
+      const pending = await this.adapter.getInstancesByWorkflow(workflowName, "pending");
+      if (running.length + pending.length >= limit) {
+        throw new Error(
+          `Workflow "${workflowName}" has reached its concurrency limit (${limit})`
+        );
+      }
+    }
+
     const instance = await this.adapter.createInstance({
       workflowName,
       status: "pending",
@@ -1991,6 +2017,16 @@ class WorkflowsImpl implements Workflows {
     await this.adapter.updateInstance(instanceId, { metadata });
   }
 
+  private getConcurrencyLimit(workflowName: string): number {
+    if (this.workflowConcurrencyOverrides.has(workflowName)) {
+      return this.workflowConcurrencyOverrides.get(workflowName) ?? 0;
+    }
+    if (this.concurrentWorkflowsByName[workflowName] !== undefined) {
+      return this.concurrentWorkflowsByName[workflowName] ?? 0;
+    }
+    return this.concurrentWorkflows;
+  }
+
   private async markOrphanedAsFailed(
     instances: WorkflowInstance[],
     reason: string