@iworkflow/dbos 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iworkflow/dbos",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "DBOS adapter for @iworkflow/core",
   "keywords": [
     "workflow",
@@ -29,7 +29,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@iworkflow/core": "^0.1.0",
+    "@iworkflow/core": "^0.2.0",
     "pg": "^8.0.0"
   },
   "peerDependencies": {

package/src/index.ts

@@ -1,13 +1,20 @@
 // DBOS: общая системная база Postgres, у модуля своё приложение (name) и своя очередь.
 // Дочерний процесс в чужом модуле — enqueueWorkflowWithOptions по имени, без ссылки на функцию.
-import { DBOS, DBOSClient } from "@dbos-inc/dbos-sdk";
+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";
 
@@ -87,6 +94,122 @@ function stepKey(): [string, number] {
   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 {
@@ -107,34 +230,74 @@ export function dbosRuntime(): EngineRuntime {
           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[]) => {
-          await patches.born(DBOS.workflowID!);
+          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: DBOS.workflowID!,
-            step: (step, stepArgs, opts) => {
-              // timeoutMs и heartbeatTimeoutMs у DBOS не действуют: шаг повторяется после рестарта процесса.
-              const attempts = opts?.attempts ?? 3;
-              return DBOS.runStep(() => def.activities[step]!(...stepArgs), {
+            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: attempts > 1,
-                maxAttempts: attempts,
-                intervalSeconds: 0.2,
-                backoffRate: 1,
+                retriesAllowed: false,
+              }).catch((e) => {
+                throw revive(e);
               }) 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;
+            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() }),
-            signal: (workflowId, topic, value) => DBOS.send(workflowId, value, topic),
+            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(DBOS.workflowID!, id),
+            patched: (id) => patches.patched(workflowId, id),
             // Старых процессов нет — ветка всегда новая; вызов можно удалять.
             deprecatePatch: async () => {},
           };
@@ -165,17 +328,40 @@ export function dbosRuntime(): EngineRuntime {
 
 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>,
+    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 },
+        {
+          queueName: target.app,
+          workflowName: target.flow,
+          workflowID: opts.id,
+          applicationName: target.app,
+          ...(opts.timeoutMs ? { workflowTimeoutMS: opts.timeoutMs } : {}),
+        },
         ...args,
       );
       return wrap(h.workflowID);