@iworkflow/core 0.1.0 → 0.3.0

package/README.md

@@ -17,4 +17,20 @@ export const outreach: Flow = async (ctx, input: { id: string }) => {
 ```
 
 Шаг с прогрессом: `heartbeat(details)` и `lastHeartbeat()` из этого пакета внутри функции шага.
+
+Отказы одинаковы на обоих движках. Шаг бросает `nonRetryable(message, type, details)` или
+`new Failure(message, { type })`; порт бросает `FlowError` с `reason` (`failed`, `timeout`,
+`terminated`, `already-started`, `not-found`), `type`, `details` и `exhausted`:
+
+```ts
+try {
+  await ctx.step("send", [input], { attempts: 20, retryIntervalMs: 120_000, backoff: 1.5, pool: "paced" });
+} catch (e) {
+  if (e instanceof FlowError && e.type === "QuietHours") await ctx.sleep(e.details as number);
+  else throw e;
+}
+```
+
+Ещё: `ctx.startChild` (без ожидания), `ChildOptions.timeoutMs` и `onExisting`, `ctx.startedAt`,
+`ctx.parentId`, `AppDefinition.pools`, `handle.describe()` и `handle.terminate()`.
 Контракт обоих движков — `lab/test/contract.test.ts` репозитория.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iworkflow/core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Engine-neutral durable workflow port: flows, steps, child workflows, signals, queries, patches, heartbeat",
   "keywords": [
     "workflow",

package/src/errors.ts

@@ -0,0 +1,55 @@
+// Ошибки порта: одинаковые на обоих движках. Без импортов рантайма — их читает песочница Temporal.
+
+/**
+ * Отказ, который бросает код шага или процесса. `type` — код для разбора (`FlowError.type`),
+ * `nonRetryable` — шаг не повторять. Отказ процесса не повторяется никогда.
+ */
+export class Failure extends Error {
+  readonly type: string;
+  readonly details?: unknown;
+  readonly nonRetryable: boolean;
+  constructor(message: string, opts: { type: string; details?: unknown; nonRetryable?: boolean }) {
+    super(message);
+    this.name = "Failure";
+    this.type = opts.type;
+    this.details = opts.details;
+    this.nonRetryable = opts.nonRetryable ?? false;
+  }
+}
+
+/** Отказ без повтора: `throw nonRetryable("нет такой фазы", "UnknownPhase")`. */
+export const nonRetryable = (message: string, type: string, details?: unknown) =>
+  new Failure(message, { type, details, nonRetryable: true });
+
+/**
+ * - failed — шаг или процесс упал; `type` — тип отказа (`Failure.type` или имя класса ошибки).
+ * - timeout — вышел срок: попытки шага (`timeoutMs`), шага целиком (`totalTimeoutMs`) или процесса.
+ * - terminated — процесс прерван снаружи (`EngineClient.terminate`).
+ * - already-started — процесс с этим id уже есть (`startChild`, `onExisting: "reject"`).
+ * - not-found — процесса с этим id нет или он завершён (`signal`, `describe`).
+ */
+export type FlowErrorReason = "failed" | "timeout" | "terminated" | "already-started" | "not-found";
+
+/** Что бросает порт: `ctx.step`, `ctx.child`, `ctx.signal`, `handle.result()`, `client.describe`. */
+export class FlowError extends Error {
+  readonly reason: FlowErrorReason;
+  readonly type?: string;
+  readonly details?: unknown;
+  /** Шаг упал на последней разрешённой попытке, а не остановлен `nonRetryable`. */
+  readonly exhausted: boolean;
+  constructor(
+    message: string,
+    opts: { reason: FlowErrorReason; type?: string; details?: unknown; exhausted?: boolean },
+  ) {
+    super(message);
+    this.name = "FlowError";
+    this.reason = opts.reason;
+    this.type = opts.type;
+    this.details = opts.details;
+    this.exhausted = opts.exhausted ?? false;
+  }
+}
+
+/** FlowError по признакам, а не по классу: класс теряется при сериализации в DBOS. */
+export const isFlowError = (e: unknown): e is FlowError =>
+  e instanceof FlowError || (e instanceof Error && e.name === "FlowError" && typeof (e as FlowError).reason === "string");

package/src/index.ts

@@ -1,2 +1,3 @@
 export * from "./types";
 export { bindStepRuntime, heartbeat, lastHeartbeat, type StepRuntime } from "./heartbeat";
+export * from "./errors";

package/src/types.ts

@@ -4,24 +4,66 @@
 export type Activity = (...args: any[]) => Promise<unknown>;
 
 export interface StepOptions {
-  /** Попыток всего, включая первую. По умолчанию 3. */
+  /** Попыток всего, включая первую. По умолчанию 3; Infinity — до totalTimeoutMs или срока процесса. */
   attempts?: number;
   /** Предел одной попытки. По умолчанию 60 с. DBOS не ограничивает: шаг повторяется после рестарта. */
   timeoutMs?: number;
   /** Шаг без heartbeat дольше этого — попытка мёртвой, повтор. Только Temporal; DBOS ловит смерть рестартом. */
   heartbeatTimeoutMs?: number;
+  /** Пауза перед вторым повтором. По умолчанию 200 мс. */
+  retryIntervalMs?: number;
+  /** Множитель паузы для следующих повторов. По умолчанию 1. */
+  backoff?: number;
+  /** Предел паузы между повторами. */
+  maxRetryIntervalMs?: number;
+  /**
+   * Срок шага со всеми повторами; вышел — FlowError reason "timeout". Temporal режет и идущую
+   * попытку, DBOS только не начинает новую: идущую ограничивает timeoutMs.
+   */
+  totalTimeoutMs?: number;
+  /** Типы отказов (`Failure.type` или имя класса ошибки), которые не повторять. */
+  nonRetryableTypes?: string[];
+  /** Пул шага из AppDefinition.pools — со своим пределом одновременных шагов. */
+  pool?: string;
+}
+
+export interface ChildOptions {
+  id: string;
+  /** Срок процесса; вышел — FlowError reason "timeout". */
+  timeoutMs?: number;
+  /**
+   * Id уже занят (процесс идёт или завершён): "reject" — FlowError reason "already-started".
+   * Без него движки расходятся: Temporal запускает завершённый id заново, DBOS отдаёт его результат.
+   */
+  onExisting?: "reject";
+}
+
+/** Дочерний процесс, запущенный без ожидания. */
+export interface ChildHandle<T> {
+  id: string;
+  result(): Promise<T>;
 }
 
 /** Что видит код процесса. Детерминирован: время, случайность, ввод-вывод — только через step. */
 export interface FlowContext {
   readonly workflowId: string;
+  /** Id родительского процесса; undefined — процесс запущен снаружи. */
+  readonly parentId: string | undefined;
+  /** Время запуска процесса: одно и то же при каждом переигрывании. */
+  readonly startedAt: Date;
+  /** Шаг упал после повторов — FlowError reason "failed" или "timeout". */
   step<T>(name: string, args: unknown[], opts?: StepOptions): Promise<T>;
   /** Дочерний процесс в другом модуле: его очередь, его процесс, ждём результат. */
-  child<T>(target: FlowRef, args: unknown[], opts: { id: string }): Promise<T>;
+  child<T>(target: FlowRef, args: unknown[], opts: ChildOptions): Promise<T>;
+  /**
+   * Дочерний процесс без ожидания: живёт и после завершения родителя. Id уже идёт или занят —
+   * FlowError reason "already-started".
+   */
+  startChild<T>(target: FlowRef, args: unknown[], opts: Omit<ChildOptions, "onExisting">): Promise<ChildHandle<T>>;
   sleep(ms: number): Promise<void>;
   /** Ждать сигнал по теме; null — вышло время. Сигнал, пришедший раньше, не теряется. */
   recv<T>(topic: string, timeoutMs: number): Promise<T | null>;
-  /** Сигнал другому процессу по id — в том числе в другом модуле. */
+  /** Сигнал другому процессу по id — в том числе в другом модуле. Процесса нет или он завершён — FlowError "not-found". */
   signal(workflowId: string, topic: string, value: unknown): Promise<void>;
   /** Опубликовать значение для query снаружи; читается и после завершения процесса. */
   setState(key: string, value: unknown): Promise<void>;
@@ -52,14 +94,29 @@ export interface AppDefinition {
    * DBOS решает ветку по этому списку (см. @iworkflow/dbos), опечатка молча вела бы в старую.
    */
   patches?: string[];
+  /** Пулы шагов: имя → сколько шагов пула идёт одновременно в этом процессе. */
+  pools?: Record<string, number>;
+}
+
+export type FlowStatus = "running" | "completed" | "failed" | "terminated" | "timed-out";
+
+export interface FlowDescription {
+  id: string;
+  status: FlowStatus;
+  startedAt: Date;
 }
 
 export interface FlowHandle<T> {
   id: string;
+  /** Процесс упал — FlowError: "failed", "timeout" или "terminated". */
   result(): Promise<T>;
   signal(topic: string, value: unknown): Promise<void>;
   /** Последнее значение setState по ключу; undefined — ещё не публиковалось. */
   query<V>(key: string): Promise<V | undefined>;
+  /** Нет процесса — FlowError "not-found". */
+  describe(): Promise<FlowDescription>;
+  /** Прервать процесс без отката; result() бросит FlowError "terminated". */
+  terminate(reason?: string): Promise<void>;
 }
 
 /** Сторона модуля: держит воркер своей очереди. */
@@ -70,7 +127,8 @@ export interface EngineRuntime {
 
 /** Сторона вызывающего вне процесса (HTTP, CLI, тест). */
 export interface EngineClient {
-  start<T>(target: FlowRef, args: unknown[], opts: { id: string }): Promise<FlowHandle<T>>;
+  /** Id уже идёт — handle к нему. timeoutMs — срок процесса. */
+  start<T>(target: FlowRef, args: unknown[], opts: { id: string; timeoutMs?: number }): Promise<FlowHandle<T>>;
   /** Уже запущенный процесс по id. */
   handle<T>(id: string): FlowHandle<T>;
   close(): Promise<void>;