@iworkflow/dbos 0.0.0-stage → 0.1.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.1.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.1.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,186 @@
+// DBOS: общая системная база Postgres, у модуля своё приложение (name) и своя очередь.
+// Дочерний процесс в чужом модуле — enqueueWorkflowWithOptions по имени, без ссылки на функцию.
+import { DBOS, DBOSClient } from "@dbos-inc/dbos-sdk";
+import {
+  bindStepRuntime,
+  type AppDefinition,
+  type EngineClient,
+  type EngineRuntime,
+  type FlowContext,
+  type FlowHandle,
+} 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];
+}
+
+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;
+        },
+      });
+      for (const [name, flow] of Object.entries(def.flows)) {
+        const run = async (...args: unknown[]) => {
+          await patches.born(DBOS.workflowID!);
+          const ctx: FlowContext = {
+            workflowId: DBOS.workflowID!,
+            step: (step, stepArgs, opts) => {
+              // timeoutMs и heartbeatTimeoutMs у DBOS не действуют: шаг повторяется после рестарта процесса.
+              const attempts = opts?.attempts ?? 3;
+              return DBOS.runStep(() => def.activities[step]!(...stepArgs), {
+                name: step,
+                retriesAllowed: attempts > 1,
+                maxAttempts: attempts,
+                intervalSeconds: 0.2,
+                backoffRate: 1,
+              }) as Promise<never>;
+            },
+            child: async (target, childArgs, opts) => {
+              const h = await DBOS.enqueueWorkflowWithOptions(
+                { queueName: target.app, workflowName: target.flow, workflowID: opts.id, applicationName: target.app },
+                ...childArgs,
+              );
+              return (await h.getResult(resultPoll())) as never;
+            },
+            sleep: (ms) => DBOS.sleep(ms),
+            recv: (topic, timeoutMs) => DBOS.recv(topic, { timeoutSeconds: timeoutMs / 1000, ...resultPoll() }),
+            signal: (workflowId, topic, value) => DBOS.send(workflowId, value, topic),
+            setState: (key, value) => DBOS.setEvent(key, value),
+            patched: (id) => patches.patched(DBOS.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 wrap = <T>(id: string): FlowHandle<T> => ({
+    id,
+    result: () => client.retrieveWorkflow<T>(id).getResult(resultPoll()) as Promise<T>,
+    signal: (topic, value) => client.send(id, value, topic),
+    // Нет ожидания: query читает текущее значение, как у Temporal.
+    query: async <V>(key: string) => ((await client.getEvent<V>(id, key, { timeoutSeconds: 0 })) ?? undefined),
+  });
+  return {
+    async start(target, args, opts) {
+      const h = await client.enqueue(
+        { queueName: target.app, workflowName: target.flow, workflowID: opts.id, applicationName: target.app },
+        ...args,
+      );
+      return wrap(h.workflowID);
+    },
+    handle: (id) => wrap(id),
+    close: () => client.destroy(),
+  };
+}