@iworkflow/dbos 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @iworkflow/dbos
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DBOS для `@iworkflow/core`. Peer: `@dbos-inc/dbos-sdk` ^5.3; зависимость `pg`.
+
+- `dbosRuntime().start(def)` — приложение `def.app`, очередь `def.app`, версия `<app>-patching`.
+- `dbosClient()` — старт, сигнал, query по id.
+- Модули, зовущие друг друга, делят одну системную базу (`DBOS_SYSTEM_DATABASE_URL`).
+- Своё в схеме `iwf`: `heartbeat` (прогресс шага), `birth` (патчи кода, начавшего процесс).
+- Запуск модулей — под advisory-замком: миграции DBOS на пустой базе иначе ловят deadlock.
+
+Переменные: `DBOS_SYSTEM_DATABASE_URL`, `DBOS_QUEUE_POLL_MS`, `DBOS_RESULT_POLL_MS`, `DBOS_APPLICATION_VERSION`.

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@iworkflow/dbos",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "DBOS adapter for @iworkflow/core",
+  "keywords": [
+    "workflow",
+    "dbos",
+    "postgres"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iconicompany/iworkflow.git",
+    "directory": "packages/dbos"
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@iworkflow/core": "^0.2.0",
+    "pg": "^8.0.0"
+  },
+  "peerDependencies": {
+    "@dbos-inc/dbos-sdk": "^5.3.0"
+  },
+  "devDependencies": {
+    "@dbos-inc/dbos-sdk": "^5.3.0",
+    "@types/pg": "^8.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,372 @@
+// DBOS: общая системная база Postgres, у модуля своё приложение (name) и своя очередь.
+// Дочерний процесс в чужом модуле — enqueueWorkflowWithOptions по имени, без ссылки на функцию.
+import { DBOS, DBOSClient, Error as DBOSErrors, type WorkflowStatus } from "@dbos-inc/dbos-sdk";
+import {
+  bindStepRuntime,
+  Failure,
+  FlowError,
+  isFlowError,
+  type Activity,
+  type AppDefinition,
+  type ChildOptions,
+  type EngineClient,
+  type EngineRuntime,
+  type FlowContext,
+  type FlowHandle,
+  type FlowStatus,
+  type StepOptions,
+} from "@iworkflow/core";
+import { Pool } from "pg";
+
+// Ожидание результата дочернего процесса — опрос базы, по умолчанию раз в секунду: это и есть
+// задержка каждого перехода между модулями. DBOS_RESULT_POLL_MS уменьшает её ценой запросов к базе.
+const resultPoll = () => ({ pollingIntervalMs: Number(process.env.DBOS_RESULT_POLL_MS) || undefined });
+
+const sysDb = () =>
+  process.env.DBOS_SYSTEM_DATABASE_URL ?? "postgres://iworkflow:iworkflow@localhost:55432/iworkflow";
+
+// У DBOS нет heartbeat: прогресс шага — строка в системной базе по (workflow, номер шага).
+// Номер шага детерминирован, поэтому повтор после рестарта читает прогресс своей прошлой попытки.
+const HEARTBEAT_DDL = [
+  "CREATE SCHEMA IF NOT EXISTS iwf",
+  `CREATE TABLE IF NOT EXISTS iwf.birth (
+    workflow_id text PRIMARY KEY, app text NOT NULL, patches text[] NOT NULL, at timestamptz NOT NULL DEFAULT now())`,
+  `CREATE TABLE IF NOT EXISTS iwf.heartbeat (
+    workflow_id text NOT NULL, step_id integer NOT NULL, details jsonb, at timestamptz NOT NULL DEFAULT now(),
+    PRIMARY KEY (workflow_id, step_id))`,
+];
+
+// Модули стартуют разом на одной системной базе: миграции DBOS на пустой базе ловят deadlock и
+// "tuple concurrently updated", IF NOT EXISTS — гонку. Запуск целиком — под общим advisory-замком.
+// Ждать замок — опросом pg_try_advisory_lock: висящий pg_advisory_lock держит транзакцию, и
+// CREATE INDEX CONCURRENTLY из миграций DBOS ждёт его вечно.
+const LAUNCH_LOCK = "hashtext('iworkflow/dbos launch')";
+
+async function underLaunchLock<T>(pool: Pool, fn: () => Promise<T>): Promise<T> {
+  const c = await pool.connect();
+  try {
+    while (!(await c.query(`SELECT pg_try_advisory_lock(${LAUNCH_LOCK}) AS ok`)).rows[0].ok) await Bun.sleep(200);
+    for (const sql of HEARTBEAT_DDL) await c.query(sql);
+    return await fn();
+  } finally {
+    await c.query(`SELECT pg_advisory_unlock(${LAUNCH_LOCK})`).catch(() => {});
+    c.release();
+  }
+}
+
+// patched без DBOS.patch: тот смотрит слот текущей операции, а у процесса, ждущего в recv, слот ещё
+// пуст — старый процесс уходит в новую ветку и ломает детерминизм на следующем шаге.
+// Здесь при первом исполнении процесса записывается список патчей кода, который его начал
+// (iwf.birth), и patched отвечает по нему: ответ одинаков при каждом переигрывании, номер операции
+// не тратится, откат и повторная выкатка версии не путают ветки.
+function patchBook(db: Pool, app: string, declared: string[]) {
+  const births = new Map<string, Set<string>>();
+  return {
+    async patched(workflowId: string, id: string) {
+      if (!declared.includes(id)) throw new Error(`патч "${id}" не объявлен в AppDefinition.patches модуля ${app}`);
+      let set = births.get(workflowId);
+      if (!set) {
+        await db.query(
+          "INSERT INTO iwf.birth (workflow_id, app, patches) VALUES ($1, $2, $3) ON CONFLICT (workflow_id) DO NOTHING",
+          [workflowId, app, declared],
+        );
+        const r = await db.query("SELECT patches FROM iwf.birth WHERE workflow_id = $1", [workflowId]);
+        set = new Set(r.rows[0].patches as string[]);
+        births.set(workflowId, set);
+      }
+      return set.has(id);
+    },
+    /** Первое исполнение — запомнить патчи кода. Вызывается до первой операции процесса. */
+    async born(workflowId: string) {
+      if (births.has(workflowId)) return;
+      await db.query(
+        "INSERT INTO iwf.birth (workflow_id, app, patches) VALUES ($1, $2, $3) ON CONFLICT (workflow_id) DO NOTHING",
+        [workflowId, app, declared],
+      );
+    },
+  };
+}
+
+function stepKey(): [string, number] {
+  const wf = DBOS.workflowID;
+  const step = DBOS.stepID;
+  if (!wf || step === undefined) throw new Error("heartbeat вне шага DBOS");
+  return [wf, step];
+}
+
+// --- Отказы ---------------------------------------------------------------------------------------
+// Ошибку шага и процесса DBOS сериализует: при переигрывании класс теряется, остаются name и поля.
+
+const typeOf = (e: unknown) => (e instanceof Failure ? e.type : e instanceof Error ? e.name : "Error");
+
+/** FlowError после сериализации — снова FlowError: модуль проверяет instanceof. */
+function revive(e: unknown): unknown {
+  if (e instanceof FlowError || !isFlowError(e)) return e;
+  return new FlowError(e.message, { reason: e.reason, type: e.type, details: e.details, exhausted: e.exhausted });
+}
+
+const CANCELLED = new DBOSErrors.DBOSAwaitedWorkflowCancelledError("").dbosErrorCode;
+const isCancelled = (e: unknown) => e instanceof Error && DBOSErrors.getDBOSErrorCode(e) === CANCELLED;
+
+/** Прерван процесс сроком или снаружи: по статусу, неизменному после конца, — ответ одинаков при переигрывании. */
+const cancelReason = (st: WorkflowStatus | undefined): "timeout" | "terminated" =>
+  st?.deadlineEpochMS !== undefined && (st.updatedAt ?? 0) >= st.deadlineEpochMS ? "timeout" : "terminated";
+
+/** Отказ процесса глазами ожидающего: родителя или клиента. Как у Temporal — "failed" с типом отказа. */
+async function flowFailure(e: unknown, status: () => Promise<WorkflowStatus | undefined>): Promise<unknown> {
+  if (isCancelled(e)) {
+    const reason = cancelReason(await status());
+    return new FlowError(reason === "timeout" ? "срок процесса вышел" : "процесс прерван", { reason });
+  }
+  if (isFlowError(e))
+    return new FlowError(e.message, { reason: "failed", type: e.type ?? e.reason, details: e.details });
+  if (e instanceof Error)
+    return new FlowError(e.message, { reason: "failed", type: (e as Failure).type ?? e.name, details: (e as Failure).details });
+  return e;
+}
+
+const alreadyStarted = (id: string) => (e: unknown): never => {
+  if (DBOSErrors.isWorkflowIDInUseError(e)) throw new FlowError(`процесс ${id} уже есть`, { reason: "already-started" });
+  throw e;
+};
+
+// --- Шаг ------------------------------------------------------------------------------------------
+// Повторы — свои, внутри одного шага DBOS: в историю пишется уже FlowError с причиной, как у Temporal.
+// Цена: отмена процесса не прерывает повторы шага, а ждёт его конца.
+
+class Semaphore {
+  private queue: (() => void)[] = [];
+  constructor(private free: number) {}
+  async run<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.free > 0) this.free--;
+    else await new Promise<void>((r) => this.queue.push(r));
+    try {
+      return await fn();
+    } finally {
+      const next = this.queue.shift();
+      if (next) next();
+      else this.free++;
+    }
+  }
+}
+
+class AttemptTimeout extends Error {}
+
+const sleepMs = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/** Попытка, урезанная по сроку: брошенная продолжает идти в фоне, её итог отбрасывается. */
+async function withTimeout<T>(p: Promise<T>, ms: number): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      p,
+      new Promise<never>((_, reject) => (timer = setTimeout(() => reject(new AttemptTimeout(`попытка дольше ${ms} мс`)), ms))),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function attempts(fn: Activity, args: unknown[], opts: StepOptions, pool: Semaphore | undefined) {
+  const max = opts.attempts ?? 3;
+  const started = Date.now();
+  let interval = opts.retryIntervalMs ?? 200;
+  for (let n = 1; ; n++) {
+    try {
+      const attempt = () => withTimeout(fn(...args), opts.timeoutMs ?? 60_000);
+      return await (pool ? pool.run(attempt) : attempt());
+    } catch (e) {
+      const stop = (e instanceof Failure && e.nonRetryable) || (opts.nonRetryableTypes ?? []).includes(typeOf(e));
+      if (stop || n >= max) {
+        const exhausted = !stop;
+        if (e instanceof AttemptTimeout) throw new FlowError(e.message, { reason: "timeout", exhausted });
+        throw new FlowError(e instanceof Error ? e.message : String(e), {
+          reason: "failed",
+          type: typeOf(e),
+          details: e instanceof Failure ? e.details : undefined,
+          exhausted,
+        });
+      }
+      if (opts.totalTimeoutMs !== undefined && Date.now() - started + interval >= opts.totalTimeoutMs)
+        throw new FlowError(e instanceof Error ? e.message : String(e), {
+          reason: "timeout",
+          type: typeOf(e),
+          details: e instanceof Failure ? e.details : undefined,
+        });
+      await sleepMs(interval);
+      interval = Math.min(interval * (opts.backoff ?? 1), opts.maxRetryIntervalMs ?? Infinity);
+    }
+  }
+}
+
+const FINISHED = new Set(["SUCCESS", "ERROR", "CANCELLED", "MAX_RECOVERY_ATTEMPTS_EXCEEDED"]);
+
+const STATUS: Record<string, FlowStatus> = {
+  SUCCESS: "completed",
+  ERROR: "failed",
+  MAX_RECOVERY_ATTEMPTS_EXCEEDED: "failed",
+};
+
+const describeStatus = (st: WorkflowStatus): FlowStatus =>
+  st.status === "CANCELLED" ? (cancelReason(st) === "timeout" ? "timed-out" : "terminated") : (STATUS[st.status] ?? "running");
+
+export function dbosRuntime(): EngineRuntime {
+  let pool: Pool | undefined;
+  return {
+    async start(def: AppDefinition) {
+      pool = new Pool({ connectionString: sysDb(), max: 2 });
+      const db = pool;
+      const patches = patchBook(db, def.app, def.patches ?? []);
+      bindStepRuntime({
+        async heartbeat(details) {
+          await db.query(
+            `INSERT INTO iwf.heartbeat (workflow_id, step_id, details) VALUES ($1, $2, $3)
+             ON CONFLICT (workflow_id, step_id) DO UPDATE SET details = EXCLUDED.details, at = now()`,
+            [...stepKey(), JSON.stringify(details ?? null)],
+          );
+        },
+        async lastHeartbeat() {
+          const r = await db.query("SELECT details FROM iwf.heartbeat WHERE workflow_id = $1 AND step_id = $2", stepKey());
+          return r.rows[0]?.details ?? undefined;
+        },
+      });
+      const pools = Object.fromEntries(Object.entries(def.pools ?? {}).map(([p, n]) => [p, new Semaphore(n)]));
+      const enqueue = (target: { app: string; flow: string }, args: unknown[], opts: ChildOptions, reject: boolean) =>
+        DBOS.enqueueWorkflowWithOptions(
+          {
+            queueName: target.app,
+            workflowName: target.flow,
+            workflowID: opts.id,
+            applicationName: target.app,
+            ...(opts.timeoutMs ? { workflowTimeoutMS: opts.timeoutMs } : {}),
+            ...(reject ? { workflowIDReusePolicy: "reject" as const } : {}),
+          },
+          ...args,
+        ).catch(alreadyStarted(opts.id));
+      const waitChild = async <T>(h: { getResult(o?: object): Promise<unknown> }, id: string): Promise<T> => {
+        try {
+          return (await h.getResult(resultPoll())) as T;
+        } catch (e) {
+          throw await flowFailure(e, () => DBOS.getWorkflowStatus(id).then((st) => st ?? undefined));
+        }
+      };
+      for (const [name, flow] of Object.entries(def.flows)) {
+        const run = async (...args: unknown[]) => {
+          const workflowId = DBOS.workflowID!;
+          await patches.born(workflowId);
+          // Строка статуса не меняется после создания: чтение вне шага детерминировано.
+          const row = (
+            await db.query("SELECT created_at, parent_workflow_id FROM dbos.workflow_status WHERE workflow_uuid = $1", [
+              workflowId,
+            ])
+          ).rows[0];
+          const ctx: FlowContext = {
+            workflowId,
+            parentId: row?.parent_workflow_id ?? undefined,
+            startedAt: new Date(Number(row?.created_at)),
+            step: (step, stepArgs, opts = {}) => {
+              const pool = opts.pool ? pools[opts.pool] : undefined;
+              if (opts.pool && !pool) throw new Error(`пул "${opts.pool}" не объявлен в AppDefinition.pools модуля ${def.app}`);
+              // heartbeatTimeoutMs у DBOS не действует: умерший процесс ловится рестартом, шаг повторяется.
+              return DBOS.runStep(() => attempts(def.activities[step]!, stepArgs, opts, pool), {
+                name: step,
+                retriesAllowed: false,
+              }).catch((e) => {
+                throw revive(e);
+              }) as Promise<never>;
+            },
+            child: async (target, childArgs, opts) =>
+              waitChild(await enqueue(target, childArgs, opts, opts.onExisting === "reject"), opts.id),
+            async startChild(target, childArgs, opts) {
+              // Процесс DBOS не привязан к родителю: живёт сам, как ABANDON у Temporal.
+              const h = await enqueue(target, childArgs, opts, true);
+              return { id: opts.id, result: () => waitChild(h, opts.id) };
+            },
+            sleep: (ms) => DBOS.sleep(ms),
+            recv: (topic, timeoutMs) => DBOS.recv(topic, { timeoutSeconds: timeoutMs / 1000, ...resultPoll() }),
+            async signal(target, topic, value) {
+              // Отправка завершённому процессу у DBOS проходит молча; Temporal отказывает — проверяем сами.
+              const status = await DBOS.runStep(
+                async () =>
+                  ((await db.query("SELECT status FROM dbos.workflow_status WHERE workflow_uuid = $1", [target])).rows[0]
+                    ?.status as string | undefined) ?? null,
+                { name: "iwf.signalTarget" },
+              );
+              if (status === null || FINISHED.has(status))
+                throw new FlowError(`процесса ${target} нет или он завершён`, { reason: "not-found" });
+              await DBOS.send(target, value, topic);
+            },
+            setState: (key, value) => DBOS.setEvent(key, value),
+            patched: (id) => patches.patched(workflowId, id),
+            // Старых процессов нет — ветка всегда новая; вызов можно удалять.
+            deprecatePatch: async () => {},
+          };
+          return flow(ctx, ...args);
+        };
+        DBOS.registerWorkflow(run, { name });
+      }
+      // Версия постоянна, ветки кода — patched. Без этого версия — хэш кода, и после выкатки новый
+      // процесс не подхватывает незавершённые процессы старого. Своя на модуль: в общей системной
+      // базе DBOS требует уникальных имён версий.
+      DBOS.setConfig({
+        name: def.app,
+        systemDatabaseUrl: sysDb(),
+        logLevel: "warn",
+        applicationVersion: process.env.DBOS_APPLICATION_VERSION ?? `${def.app}-patching`,
+      });
+      await underLaunchLock(db, () => DBOS.launch());
+      // Опрос очереди — главный вклад в задержку перехода между модулями (по умолчанию ~1 с).
+      const poll = Number(process.env.DBOS_QUEUE_POLL_MS) || undefined;
+      await DBOS.registerQueue(def.app, { minPollingIntervalMs: poll, onConflict: "always_update" });
+    },
+    async stop() {
+      await DBOS.shutdown();
+      await pool?.end();
+    },
+  };
+}
+
+export async function dbosClient(): Promise<EngineClient> {
+  const client = await DBOSClient.create({ systemDatabaseUrl: sysDb() });
+  const status = (id: string) => client.getWorkflow(id);
+  const exists = async (id: string) => {
+    const st = await status(id);
+    if (!st) throw new FlowError(`процесса ${id} нет`, { reason: "not-found" });
+    return st;
+  };
+  const wrap = <T>(id: string): FlowHandle<T> => ({
+    id,
+    result: () =>
+      (client.retrieveWorkflow<T>(id).getResult(resultPoll()) as Promise<T>).catch(async (e) => {
+        throw await flowFailure(e, () => status(id));
+      }),
+    signal: (topic, value) => client.send(id, value, topic),
+    // Нет ожидания: query читает текущее значение, как у Temporal.
+    query: async <V>(key: string) => ((await client.getEvent<V>(id, key, { timeoutSeconds: 0 })) ?? undefined),
+    async describe() {
+      const st = await exists(id);
+      return { id, status: describeStatus(st), startedAt: new Date(st.createdAt) };
+    },
+    async terminate() {
+      await exists(id);
+      await client.cancelWorkflow(id);
+    },
+  });
+  return {
+    async start(target, args, opts) {
+      const h = await client.enqueue(
+        {
+          queueName: target.app,
+          workflowName: target.flow,
+          workflowID: opts.id,
+          applicationName: target.app,
+          ...(opts.timeoutMs ? { workflowTimeoutMS: opts.timeoutMs } : {}),
+        },
+        ...args,
+      );
+      return wrap(h.workflowID);
+    },
+    handle: (id) => wrap(id),
+    close: () => client.destroy(),
+  };
+}