@sonamu-kit/tasks 0.0.1

package/src/worker.ts

@@ -0,0 +1,281 @@
+import { randomUUID } from "node:crypto";
+import type { Backend } from "./backend";
+import type { WorkflowRun } from "./core/workflow";
+import { executeWorkflow } from "./execution";
+import type { WorkflowRegistry } from "./registry";
+import type { Workflow } from "./workflow";
+
+const DEFAULT_LEASE_DURATION_MS = 30 * 1000; // 30s
+const DEFAULT_POLL_INTERVAL_MS = 100; // 100ms
+const DEFAULT_CONCURRENCY = 1;
+
+/**
+ * Configures how a Worker polls the backend, leases workflow runs, and
+ * registers workflows.
+ */
+export interface WorkerOptions {
+  backend: Backend;
+  registry: WorkflowRegistry;
+  concurrency?: number | undefined;
+  usePubSub?: boolean;
+  listenDelay?: number;
+}
+
+/**
+ * Runs workflows by polling the backend, dispatching runs across a concurrency
+ * pool, and heartbeating/extending leases.
+ */
+export class Worker {
+  private readonly backend: Backend;
+  private readonly workerIds: string[];
+  private readonly registry: WorkflowRegistry;
+  private readonly activeExecutions = new Set<WorkflowExecution>();
+  private running = false;
+  private loopPromise: Promise<void> | null = null;
+
+  private usePubSub: boolean;
+  private listenDelay: number;
+
+  constructor(options: WorkerOptions) {
+    this.backend = options.backend;
+    this.registry = options.registry;
+    this.usePubSub = options.usePubSub ?? true;
+    this.listenDelay = options.listenDelay ?? 500;
+
+    const concurrency = Math.max(DEFAULT_CONCURRENCY, options.concurrency ?? DEFAULT_CONCURRENCY);
+
+    // generate worker IDs for every concurrency slot
+    this.workerIds = Array.from({ length: concurrency }, () => randomUUID());
+  }
+
+  /**
+   * Start the worker. It will begin polling for and executing workflows.
+   * @returns Promise resolved when started
+   */
+  async start(): Promise<void> {
+    if (this.running) return;
+    this.running = true;
+    this.loopPromise = this.runLoop();
+    await Promise.resolve();
+  }
+
+  /**
+   * Stop the worker gracefully. Waits for all active workflow runs to complete
+   * before returning.
+   * @returns Promise resolved when stopped
+   */
+  async stop(): Promise<void> {
+    this.running = false;
+
+    // wait for the poll loop to stop
+    if (this.loopPromise) await this.loopPromise;
+
+    // wait for all active executions to finish
+    while (this.activeExecutions.size > 0) await sleep(100);
+  }
+
+  /**
+   * Processes one round of work claims and execution. Exposed for testing.
+   * Returns the number of workflow runs claimed.
+   * @returns Number of workflow runs claimed
+   */
+  async tick(): Promise<number> {
+    const availableSlots = this.concurrency - this.activeExecutions.size;
+    if (availableSlots <= 0) return 0;
+
+    // claim work for each available slot
+    const claims = Array.from({ length: availableSlots }, (_, i) => {
+      const availableWorkerId = this.workerIds[i % this.workerIds.length];
+      return availableWorkerId
+        ? this.claimAndProcessWorkflowRunInBackground(availableWorkerId)
+        : Promise.resolve(null);
+    });
+
+    const claimed = await Promise.all(claims);
+    return claimed.filter((run) => run !== null).length;
+  }
+
+  /**
+   * Get the configured concurrency limit.
+   * @returns Concurrency limit
+   */
+  private get concurrency(): number {
+    return this.workerIds.length;
+  }
+
+  /*
+   * Main run loop that continuously ticks while the worker is running.
+   * Only sleeps when no work was claimed to avoid busy-waiting.
+   */
+  private async runLoop(): Promise<void> {
+    if (this.usePubSub) {
+      this.backend.subscribe(async (result) => {
+        if (!result.ok) {
+          return;
+        }
+
+        await sleep(this.listenDelay);
+        await this.tick();
+      });
+    }
+
+    while (this.running) {
+      try {
+        const claimedCount = await this.tick();
+        // only sleep if we didn't claim any work
+        if (claimedCount === 0) {
+          await sleep(DEFAULT_POLL_INTERVAL_MS);
+        }
+      } catch (error) {
+        console.error("Worker tick failed:", error);
+        await sleep(DEFAULT_POLL_INTERVAL_MS);
+      }
+    }
+  }
+
+  /*
+   * Cclaim and process a workflow run for the given worker ID. Do not await the
+   * processing here to avoid blocking the caller.
+   * Returns the claimed workflow run, or null if none was available.
+   */
+  private async claimAndProcessWorkflowRunInBackground(
+    workerId: string,
+  ): Promise<WorkflowRun | null> {
+    // claim workflow run
+    const workflowRun = await this.backend.claimWorkflowRun({
+      workerId,
+      leaseDurationMs: DEFAULT_LEASE_DURATION_MS,
+    });
+    if (!workflowRun) return null;
+
+    const workflow = this.registry.get(workflowRun.workflowName, workflowRun.version);
+    if (!workflow) {
+      const versionStr = workflowRun.version ? ` (version: ${workflowRun.version})` : "";
+      await this.backend.failWorkflowRun({
+        workflowRunId: workflowRun.id,
+        workerId,
+        error: {
+          message: `Workflow "${workflowRun.workflowName}"${versionStr} is not registered`,
+        },
+      });
+      return null;
+    }
+
+    // create execution and start processing *async* w/o blocking
+    const execution = new WorkflowExecution({
+      backend: this.backend,
+      workflowRun,
+      workerId,
+    });
+    this.activeExecutions.add(execution);
+
+    this.processExecutionInBackground(execution, workflow)
+      .catch(() => {
+        // errors are already handled in processExecution
+      })
+      .finally(() => {
+        execution.stopHeartbeat();
+        this.activeExecutions.delete(execution);
+      });
+
+    return workflowRun;
+  }
+
+  /**
+   * Process a workflow execution, handling heartbeats, step execution, and
+   * marking success or failure.
+   * @param execution - Workflow execution
+   * @param workflow - Workflow to execute
+   * @returns Promise resolved when processing completes
+   */
+  private async processExecutionInBackground(
+    execution: WorkflowExecution,
+    workflow: Workflow<unknown, unknown, unknown>,
+  ): Promise<void> {
+    // start heartbeating
+    execution.startHeartbeat();
+
+    try {
+      await executeWorkflow({
+        backend: this.backend,
+        workflowRun: execution.workflowRun,
+        workflowFn: workflow.fn,
+        workflowVersion: execution.workflowRun.version,
+        workerId: execution.workerId,
+      });
+    } catch (error) {
+      // specifically for unexpected errors in the execution wrapper itself, not
+      // for business logic errors (those are handled inside executeWorkflow)
+      console.error(
+        `Critical error during workflow execution for run ${execution.workflowRun.id}:`,
+        error,
+      );
+    }
+  }
+}
+
+/**
+ * Configures the options for a WorkflowExecution.
+ */
+interface WorkflowExecutionOptions {
+  backend: Backend;
+  workflowRun: WorkflowRun;
+  workerId: string;
+}
+
+/**
+ * Tracks a claimed workflow run and maintains its heartbeat lease for the
+ * worker.
+ */
+class WorkflowExecution {
+  private backend: Backend;
+  workflowRun: WorkflowRun;
+  workerId: string;
+  private heartbeatTimer: NodeJS.Timeout | null = null;
+
+  constructor(options: WorkflowExecutionOptions) {
+    this.backend = options.backend;
+    this.workflowRun = options.workflowRun;
+    this.workerId = options.workerId;
+  }
+
+  /**
+   * Start the heartbeat loop for this execution, heartbeating at half the lease
+   * duration.
+   */
+  startHeartbeat(): void {
+    const leaseDurationMs = DEFAULT_LEASE_DURATION_MS;
+    const heartbeatIntervalMs = leaseDurationMs / 2;
+
+    this.heartbeatTimer = setInterval(() => {
+      this.backend
+        .extendWorkflowRunLease({
+          workflowRunId: this.workflowRun.id,
+          workerId: this.workerId,
+          leaseDurationMs,
+        })
+        .catch((error: unknown) => {
+          console.error("Heartbeat failed:", error);
+        });
+    }, heartbeatIntervalMs);
+  }
+
+  /**
+   * Stop the heartbeat loop.
+   */
+  stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+}
+
+/**
+ * Sleep for a given duration.
+ * @param ms - Milliseconds to sleep
+ * @returns Promise resolved after sleeping
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/workflow.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "vitest";
+import { defineWorkflow, defineWorkflowSpec } from "./workflow";
+
+describe("defineWorkflowSpec", () => {
+  test("returns spec (passthrough)", () => {
+    const spec = { name: "test-workflow" };
+    const definedSpec = defineWorkflowSpec(spec);
+
+    expect(definedSpec).toStrictEqual(spec);
+  });
+});
+
+describe("defineWorkflow", () => {
+  test("returns workflow with spec and fn", () => {
+    // eslint-disable-next-line unicorn/consistent-function-scoping
+    function fn() {
+      return { result: "done" };
+    }
+
+    const spec = { name: "test-workflow" };
+    const workflow = defineWorkflow(spec, fn);
+
+    expect(workflow).toStrictEqual({
+      spec,
+      fn,
+    });
+  });
+});
+
+// --- type checks below -------------------------------------------------------
+// they're unused but useful to ensure that the types work as expected for both
+// defineWorkflowSpec and defineWorkflow
+
+const inferredTypesSpec = defineWorkflowSpec({
+  name: "inferred-types",
+});
+
+defineWorkflow(inferredTypesSpec, async ({ step }) => {
+  await step.run({ name: "step-1" }, () => {
+    return "success";
+  });
+
+  return { result: "done" };
+});
+
+const explicitInputTypeSpec = defineWorkflowSpec<{ name: string }>({
+  name: "explicit-input-type",
+});
+
+defineWorkflow(explicitInputTypeSpec, async ({ step }) => {
+  await step.run({ name: "step-1" }, () => {
+    return "success";
+  });
+
+  return { result: "done" };
+});
+
+const explicitInputAndOutputTypesSpec = defineWorkflowSpec<{ name: string }, { result: string }>({
+  name: "explicit-input-and-output-types",
+});
+
+defineWorkflow(explicitInputAndOutputTypesSpec, async ({ step }) => {
+  await step.run({ name: "step-1" }, () => {
+    return "success";
+  });
+
+  return { result: "done" };
+});

package/src/workflow.ts

@@ -0,0 +1,84 @@
+import type { StandardSchemaV1 } from "./core/schema";
+import type { WorkflowFunction } from "./execution";
+
+export interface WorkflowSpec<Input, Output, RawInput> {
+  /** The name of the workflow. */
+  readonly name: string;
+  /** The version of the workflow. */
+  readonly version?: string;
+  /** The schema used to validate inputs. */
+  readonly schema?: StandardSchemaV1<RawInput, Input>;
+  /** Phantom type carrier - won't exist at runtime. */
+  readonly __types?: {
+    output: Output;
+  };
+}
+
+/**
+ * Define a workflow spec.
+ * @param spec - The workflow spec
+ * @returns The workflow spec
+ */
+export function defineWorkflowSpec<Input, Output = unknown, RawInput = Input>(
+  spec: WorkflowSpec<Input, Output, RawInput>,
+): WorkflowSpec<Input, Output, RawInput> {
+  return spec;
+}
+
+/**
+ * A workflow spec and implementation.
+ */
+export interface Workflow<Input, Output, RawInput> {
+  /** The workflow spec. */
+  readonly spec: WorkflowSpec<Input, Output, RawInput>;
+  /** The workflow implementation function. */
+  readonly fn: WorkflowFunction<Input, Output>;
+}
+
+/**
+ * Define a workflow.
+ * @param spec - The workflow spec
+ * @param fn - The workflow implementation function
+ * @returns The workflow
+ */
+// Handles:
+// - `defineWorkflow(spec, fn)` (0 generics)
+// - `defineWorkflow<Input, Output>(spec, fn)` (2 generics)
+export function defineWorkflow<Input, Output, RawInput = Input>(
+  spec: WorkflowSpec<Input, Output, RawInput>,
+  fn: WorkflowFunction<Input, Output>,
+): Workflow<Input, Output, RawInput>;
+
+/**
+ * Define a workflow.
+ * @param spec - The workflow spec
+ * @param fn - The workflow implementation function
+ * @returns The workflow
+ */
+// Handles:
+// - `defineWorkflow<Input>(spec, fn)` (1 generic)
+export function defineWorkflow<
+  Input,
+  WorkflowFn extends WorkflowFunction<Input, unknown> = WorkflowFunction<Input, unknown>,
+  RawInput = Input,
+>(
+  spec: WorkflowSpec<Input, Awaited<ReturnType<WorkflowFn>>, RawInput>,
+  fn: WorkflowFn,
+): Workflow<Input, Awaited<ReturnType<WorkflowFn>>, RawInput>;
+
+/**
+ * Define a workflow.
+ * @internal
+ * @param spec - The workflow spec
+ * @param fn - The workflow implementation function
+ * @returns The workflow
+ */
+export function defineWorkflow<Input, Output, RawInput>(
+  spec: WorkflowSpec<Input, Output, RawInput>,
+  fn: WorkflowFunction<Input, Output>,
+): Workflow<Input, Output, RawInput> {
+  return {
+    spec,
+    fn,
+  };
+}

package/table_ddl.sql

@@ -0,0 +1,60 @@
+-- TaskNode에서 처리할 Task Item 목록
+CREATE TABLE sonamu_task_items (
+  id BINARY(16) PRIMARY KEY,
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+  -- Task의 Namespace
+  namespace VARCHAR(255) NOT NULL,
+
+  -- pending, pending_for_retry
+  status VARCHAR(32) NOT NULL DEFAULT "pending",
+
+  -- Task의 시도 횟수를 상태로 저장
+  attempt INTEGER NOT NULL DEFAULT 1,
+
+  -- payload는 JSON이든 무엇이든 일단 BLOB으로 저장
+  payload MEDIUMBLOB NOT NULL
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- TaskNode에서 처리가 끝난 Task Item 목록
+CREATE TABLE sonamu_archived_task_items (
+  id BINARY(16) PRIMARY KEY,
+  created_at TIMESTAMP NOT NULL,
+  completed_at TIMESTAMP NOT NULL,
+  namespace VARCHAR(255) NOT NULL,
+  payload MEDIUMBLOB NOT NULL,
+
+  -- Task가 몇번째 시도에 끝났는지 저장
+  attempt INTEGER NOT NULL DEFAULT 1,
+
+  -- error, completed
+  status VARCHAR(32) NOT NULL
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+CREATE TABLE sonamu_task_events (
+  id INT AUTO_INCREMENT PRIMARY KEY,
+  timestamp TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- Event의 종류 네임스페이스
+  -- start | stop | fetch | process:(start|error|complete)
+  event_type VARCHAR(255) NOT NULL,
+
+  -- TaskNode에서 자동 생성된 노드의 UUIDv7
+  node_id BINARY(16) NOT NULL,
+  -- 사용자가 지정한 노드 이름
+  node_name VARCHAR(64),
+
+  -- Task의 id
+  task_item_id BINARY(16),
+  -- Task의 당시 몇번째인지 기록해둠.
+  attempt INTEGER,
+
+  -- event_type이 stop일 때와 process:error:*일 때만 있음
+  -- TaskNode Stop: app_shutdown | process_signal | unknown
+  -- Process Error: no_route | serialization | timeout | max_retries_exceeded | exception
+  reason VARCHAR(32),
+
+  error_message VARCHAR(1000),
+  error_stack TEXT
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

package/templates/openworkflow.config.ts

@@ -0,0 +1,22 @@
+import type { Knex } from "knex";
+import { BackendPostgres, defineConfig } from "../src/index";
+
+const config: Knex.Config = {
+  client: "pg",
+  connection: {
+    host: "localhost",
+    port: 51000,
+    user: "postgres",
+    password: "postgres",
+    database: "postgres",
+  },
+} as const;
+
+// Use Postgres (configured with Knex config)
+const backend = await BackendPostgres.connect(config, {
+  runMigrations: false,
+});
+
+export default defineConfig({
+  backend,
+});

package/tsconfig.json

@@ -0,0 +1,40 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "rootDir": "src",
+    "outDir": "dist",
+    "sourceMap": true,
+    "lib": ["esnext"],
+    "types": ["node"],
+    "declaration": true,
+    "declarationMap": true,
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitThis": true,
+    "alwaysStrict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "noErrorTruncation": true
+  },
+  "exclude": [
+    "node_modules",
+    "dist",
+    "src/**/*.ignore.ts",
+    "**/__mocks__/**",
+    "*.config.ts",
+    "templates/openworkflow.config.ts",
+    "scripts/**/*.ts",
+    "src/database/migrations/**/*.ts"
+  ]
+}

package/tsconfig.test.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["src/**/*.test.ts"]
+}

package/vite.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  plugins: [],
+  test: {
+    include: ["src/**/*.test.ts"],
+    exclude: ["src/**/*.test-hold.ts", "**/node_modules/**", "**/.yarn/**", "**/dist/**"],
+    maxConcurrency: 4,
+  },
+  resolve: {
+    extensions: [".ts", ".tsx", ".js", ".jsx", ".json", ".mjs", ".cjs", ".mts", ".cts"],
+  },
+});