@aikirun/worker 0.7.0 → 0.8.0

package/README.md

@@ -20,7 +20,7 @@ import { onboardingWorkflowV1 } from "./workflows.ts";
 
 // Define worker
 const aikiWorker = worker({
-	id: "worker-1",
+	name: "worker-1",
 	workflows: [onboardingWorkflowV1],
 	subscriber: { type: "redis_streams" },
 	opts: {
@@ -30,7 +30,7 @@ const aikiWorker = worker({
 
 // Initialize client
 const aikiClient = await client({
-	url: "http://localhost:9090",
+	url: "http://localhost:9876",
 	redis: { host: "localhost", port: 6379 },
 });
 
@@ -68,8 +68,8 @@ Scale workers by creating separate definitions to isolate workflows or shard by
 
 ```typescript
 // Separate workers by workflow type
-const orderWorker = worker({ id: "orders", workflows: [orderWorkflowV1] });
-const emailWorker = worker({ id: "emails", workflows: [emailWorkflowV1] });
+const orderWorker = worker({ name: "orders", workflows: [orderWorkflowV1] });
+const emailWorker = worker({ name: "emails", workflows: [emailWorkflowV1] });
 
 await orderWorker.spawn(client);
 await emailWorker.spawn(client);
@@ -77,10 +77,10 @@ await emailWorker.spawn(client);
 
 ```typescript
 // Shard workers by key (reuse base definition with different shards)
-const orderWorker = worker({ id: "order-processor", workflows: [orderWorkflowV1] });
+const orderWorker = worker({ name: "order-processor", workflows: [orderWorkflowV1] });
 
-await orderWorker.with().opt("shardKeys", ["us-east", "us-west"]).spawn(client);
-await orderWorker.with().opt("shardKeys", ["eu-west"]).spawn(client);
+await orderWorker.with().opt("shards", ["us-east", "us-west"]).spawn(client);
+await orderWorker.with().opt("shards", ["eu-west"]).spawn(client);
 ```
 
 ## Worker Configuration
@@ -89,7 +89,7 @@ await orderWorker.with().opt("shardKeys", ["eu-west"]).spawn(client);
 
 ```typescript
 interface WorkerParams {
-	id: string; // Unique worker ID
+	name: string; // Unique worker name
 	workflows: WorkflowVersion[]; // Workflow versions to execute
 	subscriber?: SubscriberStrategy; // Message subscriber (default: redis_streams)
 }
@@ -104,7 +104,7 @@ interface WorkerOptions {
 		heartbeatIntervalMs?: number; // Heartbeat interval (default: 30s)
 	};
 	gracefulShutdownTimeoutMs?: number; // Shutdown timeout (default: 5s)
-	shardKeys?: string[]; // Optional shard keys for distributed work
+	shards?: string[]; // Optional shards for distributed work
 }
 ```
 
@@ -114,7 +114,7 @@ Workers receive workflow versions through the `workflows` param:
 
 ```typescript
 const aikiWorker = worker({
-	id: "worker-1",
+	name: "worker-1",
 	workflows: [workflowV1, workflowV2, anotherWorkflowV1],
 	subscriber: { type: "redis_streams" },
 });

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { Client, SubscriberStrategy } from '@aikirun/client';
+import { WorkerName, WorkerId } from '@aikirun/types/worker';
 import { WorkflowVersion } from '@aikirun/workflow';
 
 type NonEmptyArray<T> = [T, ...T[]];
@@ -27,7 +28,7 @@ type TypeOfValueAtPath<T extends object, Path extends PathFromObject<T>> = Path
  * execution, which returns a handle for controlling the running worker.
  *
  * @param params - Worker configuration parameters
- * @param params.id - Unique worker ID for identification and monitoring
+ * @param params.name - Unique worker name for identification and monitoring
  * @param params.workflows - Array of workflow versions this worker can execute
  * @param params.subscriber - Message subscriber strategy (default: redis_streams)
  * @returns Worker definition, call spawn(client) to begin execution
@@ -35,7 +36,7 @@ type TypeOfValueAtPath<T extends object, Path extends PathFromObject<T>> = Path
  * @example
  * ```typescript
  * export const myWorker = worker({
- *   id: "order-worker",
+ *   name: "order-worker",
  *   workflows: [orderWorkflowV1, paymentWorkflowV1],
  *   opts: {
  *     maxConcurrentWorkflowRuns: 10,
@@ -52,44 +53,53 @@ type TypeOfValueAtPath<T extends object, Path extends PathFromObject<T>> = Path
  */
 declare function worker(params: WorkerParams): Worker;
 interface WorkerParams {
-    id: string;
+    name: string;
     workflows: WorkflowVersion<any, any, any, any>[];
     subscriber?: SubscriberStrategy;
     opts?: WorkerOptions;
 }
 interface WorkerOptions {
     maxConcurrentWorkflowRuns?: number;
-    workflowRun?: {
-        heartbeatIntervalMs?: number;
-        /**
-         * Threshold for spinning vs persisting delays (default: 10ms).
-         *
-         * Delays <= threshold: In-memory wait (fast, no history, not durable)
-         * Delays > threshold: Server state transition (history recorded, durable)
-         *
-         * Set to 0 to record all delays in transition history.
-         */
-        spinThresholdMs?: number;
-    };
+    workflowRun?: WorkflowRunOptions;
     gracefulShutdownTimeoutMs?: number;
     /**
-     * Optional array of shardKeys this worker should process.
+     * Optional array of shards this worker should process.
      * When provided, the worker will only subscribe to sharded streams.
      * When omitted, the worker subscribes to default streams.
      */
-    shardKeys?: string[];
+    shards?: string[];
+    /**
+     * Optional reference for external correlation.
+     * Use this to associate the worker with external identifiers.
+     */
+    reference?: {
+        id: string;
+    };
+}
+interface WorkflowRunOptions {
+    heartbeatIntervalMs?: number;
+    /**
+     * Threshold for spinning vs persisting delays (default: 10ms).
+     *
+     * Delays <= threshold: In-memory wait (fast, no history, not durable)
+     * Delays > threshold: Server state transition (history recorded, durable)
+     *
+     * Set to 0 to record all delays in transition history.
+     */
+    spinThresholdMs?: number;
 }
 interface WorkerBuilder {
     opt<Path extends PathFromObject<WorkerOptions>>(path: Path, value: TypeOfValueAtPath<WorkerOptions, Path>): WorkerBuilder;
     spawn: Worker["spawn"];
 }
 interface Worker {
-    id: string;
+    name: WorkerName;
     with(): WorkerBuilder;
     spawn: <AppContext>(client: Client<AppContext>) => Promise<WorkerHandle>;
 }
 interface WorkerHandle {
-    id: string;
+    id: WorkerId;
+    name: WorkerName;
     stop: () => Promise<void>;
 }
 

package/dist/index.js

@@ -29,26 +29,6 @@ function fireAndForget(promise, onError) {
   });
 }
 
-// ../../lib/error/conflict.ts
-function isServerConflictError(error) {
-  if (error === null || typeof error !== "object") {
-    return false;
-  }
-  if ("code" in error && error.code === "CONFLICT") {
-    return true;
-  }
-  if ("status" in error && error.status === 409) {
-    return true;
-  }
-  if (error instanceof Error && error.name === "ConflictError") {
-    return true;
-  }
-  if ("data" in error && error.data !== null && typeof error.data === "object" && "status" in error.data && error.data.status === 409) {
-    return true;
-  }
-  return false;
-}
-
 // ../../lib/object/overrider.ts
 function set(obj, path, value) {
   const keys = path.split(".");
@@ -80,7 +60,6 @@ var objectOverrider = (defaultObj) => (obj) => {
 
 // worker.ts
 import { INTERNAL } from "@aikirun/types/symbols";
-import { TaskFailedError } from "@aikirun/types/task";
 import {
   WorkflowRunFailedError,
   WorkflowRunNotExecutableError,
@@ -98,9 +77,9 @@ function worker(params) {
 var WorkerImpl = class _WorkerImpl {
   constructor(params) {
     this.params = params;
-    this.id = params.id;
+    this.name = params.name;
   }
-  id;
+  name;
   with() {
     const optsOverrider = objectOverrider(this.params.opts ?? {});
     const createBuilder = (optsBuilder) => ({
@@ -119,14 +98,24 @@ var WorkerHandleImpl = class {
   constructor(client, params) {
     this.client = client;
     this.params = params;
-    this.id = params.id;
+    this.id = crypto.randomUUID();
+    this.name = params.name;
+    this.workflowRunOpts = {
+      heartbeatIntervalMs: this.params.opts?.workflowRun?.heartbeatIntervalMs ?? 3e4,
+      spinThresholdMs: this.params.opts?.workflowRun?.spinThresholdMs ?? 10
+    };
     this.registry = workflowRegistry().addMany(this.params.workflows);
+    const reference = this.params.opts?.reference;
     this.logger = client.logger.child({
       "aiki.component": "worker",
-      "aiki.workerId": this.id
+      "aiki.workerId": this.id,
+      "aiki.workerName": this.name,
+      ...reference && { "aiki.workerReferenceId": reference.id }
     });
   }
   id;
+  name;
+  workflowRunOpts;
   registry;
   logger;
   abortController;
@@ -136,10 +125,10 @@ var WorkerHandleImpl = class {
     const subscriberStrategyBuilder = this.client[INTERNAL].subscriber.create(
       this.params.subscriber ?? { type: "redis_streams" },
       this.registry.getAll(),
-      this.params.opts?.shardKeys
+      this.params.opts?.shards
     );
     this.subscriberStrategy = await subscriberStrategyBuilder.init(this.id, {
-      onError: (error) => this.handleNotificationError(error),
+      onError: (error) => this.handleSubscriberError(error),
       onStop: () => this.stop()
     });
     this.abortController = new AbortController();
@@ -156,7 +145,9 @@ var WorkerHandleImpl = class {
     this.logger.info("Worker stopping");
     this.abortController?.abort();
     const activeWorkflowRuns = Array.from(this.activeWorkflowRunsById.values());
-    if (activeWorkflowRuns.length === 0) return;
+    if (activeWorkflowRuns.length === 0) {
+      return;
+    }
     const timeoutMs = this.params.opts?.gracefulShutdownTimeoutMs ?? 5e3;
     if (timeoutMs > 0) {
       await Promise.race([Promise.allSettled(activeWorkflowRuns.map((w) => w.executionPromise)), delay(timeoutMs)]);
@@ -171,15 +162,16 @@ var WorkerHandleImpl = class {
     this.activeWorkflowRunsById.clear();
   }
   async poll(abortSignal) {
-    this.logger.info("Worker started");
     if (!this.subscriberStrategy) {
       throw new Error("Subscriber strategy not initialized");
     }
+    this.logger.info("Worker started");
+    const maxConcurrentWorkflowRuns = this.params.opts?.maxConcurrentWorkflowRuns ?? 1;
     let nextDelayMs = this.subscriberStrategy.getNextDelay({ type: "polled", foundWork: false });
     let subscriberFailedAttempts = 0;
     while (!abortSignal.aborted) {
       await delay(nextDelayMs, { abortSignal });
-      const availableCapacity = (this.params.opts?.maxConcurrentWorkflowRuns ?? 1) - this.activeWorkflowRunsById.size;
+      const availableCapacity = maxConcurrentWorkflowRuns - this.activeWorkflowRunsById.size;
       if (availableCapacity <= 0) {
         nextDelayMs = this.subscriberStrategy.getNextDelay({ type: "at_capacity" });
         continue;
@@ -243,13 +235,13 @@ var WorkerHandleImpl = class {
         continue;
       }
       const workflowVersion = this.registry.get(
-        workflowRun.workflowId,
-        workflowRun.workflowVersionId
+        workflowRun.name,
+        workflowRun.versionId
       );
       if (!workflowVersion) {
         this.logger.warn("Workflow version not found", {
-          "aiki.workflowId": workflowRun.workflowId,
-          "aiki.workflowVersionId": workflowRun.workflowVersionId,
+          "aiki.workflowName": workflowRun.name,
+          "aiki.workflowVersionId": workflowRun.versionId,
           "aiki.workflowRunId": workflowRun.id
         });
         if (meta && this.subscriberStrategy?.acknowledge) {
@@ -258,7 +250,9 @@ var WorkerHandleImpl = class {
         }
         continue;
       }
-      if (abortSignal.aborted) break;
+      if (abortSignal.aborted) {
+        break;
+      }
       const workflowExecutionPromise = this.executeWorkflow(workflowRun, workflowVersion, meta);
       this.activeWorkflowRunsById.set(workflowRun.id, {
         run: workflowRun,
@@ -270,8 +264,8 @@ var WorkerHandleImpl = class {
   async executeWorkflow(workflowRun, workflowVersion, meta) {
     const logger = this.logger.child({
       "aiki.component": "workflow-execution",
-      "aiki.workflowId": workflowRun.workflowId,
-      "aiki.workflowVersionId": workflowRun.workflowVersionId,
+      "aiki.workflowName": workflowRun.name,
+      "aiki.workflowVersionId": workflowRun.versionId,
       "aiki.workflowRunId": workflowRun.id
     });
     let heartbeatInterval;
@@ -287,29 +281,28 @@ var WorkerHandleImpl = class {
               "aiki.error": error instanceof Error ? error.message : String(error)
             });
           }
-        }, this.params.opts?.workflowRun?.heartbeatIntervalMs ?? 3e4);
+        }, this.workflowRunOpts.heartbeatIntervalMs);
       }
       const eventsDefinition = workflowVersion[INTERNAL].eventsDefinition;
       const handle = await workflowRunHandle(this.client, workflowRun, eventsDefinition, logger);
-      const spinThresholdMs = this.params.opts?.workflowRun?.spinThresholdMs ?? 10;
       const appContext = this.client[INTERNAL].contextFactory ? await this.client[INTERNAL].contextFactory(workflowRun) : null;
       await workflowVersion[INTERNAL].handler(
-        workflowRun.input,
         {
           id: workflowRun.id,
-          workflowId: workflowRun.workflowId,
-          workflowVersionId: workflowRun.workflowVersionId,
+          name: workflowRun.name,
+          versionId: workflowRun.versionId,
           options: workflowRun.options,
           logger,
-          sleep: createSleeper(handle, logger, { spinThresholdMs }),
+          sleep: createSleeper(handle, logger),
           events: createEventWaiters(handle, eventsDefinition, logger),
-          [INTERNAL]: { handle, options: { spinThresholdMs } }
+          [INTERNAL]: { handle, options: { spinThresholdMs: this.workflowRunOpts.spinThresholdMs } }
         },
+        workflowRun.input,
         appContext
       );
       shouldAcknowledge = true;
     } catch (error) {
-      if (error instanceof WorkflowRunNotExecutableError || error instanceof WorkflowRunSuspendedError || error instanceof WorkflowRunFailedError || error instanceof TaskFailedError || isServerConflictError(error)) {
+      if (error instanceof WorkflowRunNotExecutableError || error instanceof WorkflowRunSuspendedError || error instanceof WorkflowRunFailedError) {
         shouldAcknowledge = true;
       } else {
         logger.error("Unexpected error during workflow execution", {
@@ -337,8 +330,8 @@ var WorkerHandleImpl = class {
       this.activeWorkflowRunsById.delete(workflowRun.id);
     }
   }
-  handleNotificationError(error) {
-    this.logger.warn("Notification error, falling back to polling", {
+  handleSubscriberError(error) {
+    this.logger.warn("Subscriber error", {
       "aiki.error": error.message,
       "aiki.stack": error.stack
     });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aikirun/worker",
-	"version": "0.7.0",
+	"version": "0.8.0",
 	"description": "Worker SDK for Aiki - execute workflows and tasks with durable state management and automatic recovery",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -18,9 +18,9 @@
 		"build": "tsup"
 	},
 	"dependencies": {
-		"@aikirun/types": "0.7.0",
-		"@aikirun/client": "0.7.0",
-		"@aikirun/workflow": "0.7.0"
+		"@aikirun/types": "0.8.0",
+		"@aikirun/client": "0.8.0",
+		"@aikirun/workflow": "0.8.0"
 	},
 	"publishConfig": {
 		"access": "public"