@iworkflow/temporal 0.1.0 → 0.3.0

package/README.md

@@ -2,9 +2,10 @@
 
 Temporal для `@iworkflow/core`. Peer: `@temporalio/{client,worker,workflow,activity}` ^1.24.
 
-- `temporalRuntime(workflowsPath).start(def)` — воркер на task queue `def.app`.
-- `temporalClient()` — старт, сигнал, query по id.
+- `temporalRuntime(workflowsPath, opts?).start(def)` — воркер на task queue `def.app`; `opts.workflowBundlePath` — готовый бандл прод-сборки.
+- `temporalClient(opts?)` — старт, сигнал, query по id.
 - `@iworkflow/temporal/workflow` — только для входа песочницы модуля:
   `export const outreach = temporalFlow(flows.outreach, ["send-twice"])`.
 
-Переменные: `TEMPORAL_URL` (по умолчанию `127.0.0.1:17233`), `TEMPORAL_NAMESPACE`.
+`opts` (`TemporalOptions`): `address`, `namespace`, `tls`, `apiKey` — источник токена, меняется каждые `apiKeyRenewMs`.
+Без них — переменные `TEMPORAL_URL` (по умолчанию `127.0.0.1:17233`), `TEMPORAL_NAMESPACE`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iworkflow/temporal",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Temporal adapter for @iworkflow/core",
   "keywords": [
     "workflow",
@@ -29,17 +29,19 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@iworkflow/core": "^0.1.0"
+    "@iworkflow/core": "^0.3.0"
   },
   "peerDependencies": {
     "@temporalio/activity": "^1.24.0",
     "@temporalio/client": "^1.24.0",
+    "@temporalio/common": "^1.24.0",
     "@temporalio/worker": "^1.24.0",
     "@temporalio/workflow": "^1.24.0"
   },
   "devDependencies": {
     "@temporalio/activity": "^1.24.0",
     "@temporalio/client": "^1.24.0",
+    "@temporalio/common": "^1.24.0",
     "@temporalio/worker": "^1.24.0",
     "@temporalio/workflow": "^1.24.0"
   }

package/src/connection.test.ts

@@ -0,0 +1,34 @@
+import { expect, test } from "bun:test";
+import { connectOptions, renewApiKey } from "./connection";
+
+test("токен берётся при подключении и меняется по таймеру", async () => {
+  let n = 0;
+  const apiKey = async () => `t${++n}`;
+  expect(await connectOptions({ address: "a:1", tls: true, apiKey })).toEqual({ address: "a:1", tls: true, apiKey: "t1" });
+  const got: string[] = [];
+  const stop = renewApiKey({ apiKey, apiKeyRenewMs: 10 }, (t) => got.push(t));
+  while (got.length < 2) await Bun.sleep(5);
+  stop();
+  const seen = got.length;
+  await Bun.sleep(25);
+  expect(seen).toBeGreaterThanOrEqual(2);
+  expect(got.length).toBe(seen);
+});
+
+test("без токена и TLS — только адрес", async () => {
+  expect(await connectOptions({ address: "a:1" })).toEqual({ address: "a:1" });
+});
+
+test("медленный запрос не затирает свежий токен, после остановки токен не ставится", async () => {
+  let release!: (t: string) => void;
+  let calls = 0;
+  const apiKey = () => (++calls === 1 ? new Promise<string>((r) => (release = r)) : Promise.resolve(`t${calls}`));
+  const got: string[] = [];
+  const stop = renewApiKey({ apiKey, apiKeyRenewMs: 5 }, (t) => got.push(t));
+  await Bun.sleep(40);
+  expect(calls).toBe(1);
+  stop();
+  release("old");
+  await Bun.sleep(5);
+  expect(got).toEqual([]);
+});

package/src/connection.ts

@@ -0,0 +1,45 @@
+// Подключение к Temporal: адрес, TLS, токен с заменой на месте — общее для воркера и клиента.
+import type { TLSConfig } from "@temporalio/client";
+
+/** Подключение к Temporal; не задано — TEMPORAL_URL и TEMPORAL_NAMESPACE из окружения. */
+export interface TemporalOptions {
+  address?: string;
+  namespace?: string;
+  /** TLSConfig SDK (serverNameOverride, свой CA, mTLS). С apiKey SDK включает TLS сам — без TLS только `false`. */
+  tls?: boolean | TLSConfig;
+  /** Источник токена; соединение берёт свежий каждые apiKeyRenewMs (по умолчанию 60 с). */
+  apiKey?: () => Promise<string>;
+  apiKeyRenewMs?: number;
+}
+
+export const address = (o: TemporalOptions) => o.address ?? process.env.TEMPORAL_URL ?? "127.0.0.1:17233";
+export const namespace = (o: TemporalOptions) => o.namespace ?? process.env.TEMPORAL_NAMESPACE ?? "default";
+
+/** Токен меняется на месте: иначе воркер однажды молча перестанет брать задачи. */
+export function renewApiKey(o: TemporalOptions, set: (token: string) => unknown): () => void {
+  if (!o.apiKey) return () => {};
+  const apiKey = o.apiKey;
+  // По одному запросу за раз: поздний ответ не затрёт свежий токен, после остановки токен не ставится.
+  let busy = false;
+  let stopped = false;
+  const timer = setInterval(() => {
+    if (busy) return;
+    busy = true;
+    apiKey()
+      .then((t) => (stopped ? undefined : set(t)))
+      .catch((e: unknown) => stopped || console.error("токен Temporal не обновлён:", e))
+      .finally(() => (busy = false));
+  }, o.apiKeyRenewMs ?? 60_000);
+  timer.unref?.();
+  return () => {
+    stopped = true;
+    clearInterval(timer);
+  };
+}
+
+export const connectOptions = async (o: TemporalOptions) => ({
+  address: address(o),
+  ...(o.tls !== undefined ? { tls: o.tls } : {}),
+  ...(o.apiKey ? { apiKey: await o.apiKey() } : {}),
+});
+

package/src/failure.ts

@@ -0,0 +1,48 @@
+// Отказы Temporal ↔ ошибки порта. Общее для песочницы и клиента: только @temporalio/common.
+import {
+  ActivityFailure,
+  ApplicationFailure,
+  ChildWorkflowFailure,
+  TerminatedFailure,
+  TimeoutFailure,
+  WorkflowExecutionAlreadyStartedError,
+} from "@temporalio/common";
+import { Failure, FlowError, isFlowError } from "@iworkflow/core";
+
+/** Отказ шага, дочернего процесса или процесса целиком — FlowError; прочее (отмена) — как есть. */
+export function fromTemporal(e: unknown): unknown {
+  if (e instanceof WorkflowExecutionAlreadyStartedError)
+    return new FlowError(`процесс ${e.workflowId} уже есть`, { reason: "already-started" });
+  if (e instanceof ActivityFailure) {
+    const exhausted = e.retryState === "MAXIMUM_ATTEMPTS_REACHED";
+    const f = cause(e.cause, exhausted);
+    // Срок шага целиком (scheduleToClose) Temporal отдаёт последней ошибкой попытки, а не TimeoutFailure.
+    if (f && e.retryState === "TIMEOUT") return new FlowError(f.message, { reason: "timeout", type: f.type, details: f.details });
+    return f ?? e;
+  }
+  if (e instanceof ChildWorkflowFailure) return cause(e.cause, false) ?? e;
+  return e;
+}
+
+/** Причина отказа процесса или шага — FlowError; undefined — причина не наша (отмена и т. п.). */
+export function cause(c: Error | undefined, exhausted = false): FlowError | undefined {
+  if (c instanceof TimeoutFailure) return new FlowError(c.message || "срок вышел", { reason: "timeout", exhausted });
+  if (c instanceof TerminatedFailure) return new FlowError(c.message || "процесс прерван", { reason: "terminated" });
+  if (c instanceof ApplicationFailure)
+    return new FlowError(c.message, { reason: "failed", type: c.type ?? undefined, details: c.details?.[0], exhausted });
+  return undefined;
+}
+
+/** Отказ из кода порта — ApplicationFailure: обычная ошибка в песочнице не роняет процесс, а повторяет задачу. */
+export function toTemporal(e: unknown, nonRetryable: boolean): unknown {
+  if (e instanceof Failure)
+    return ApplicationFailure.create({
+      message: e.message,
+      type: e.type,
+      details: [e.details],
+      nonRetryable: nonRetryable || e.nonRetryable,
+    });
+  if (isFlowError(e))
+    return ApplicationFailure.create({ message: e.message, type: e.type ?? e.reason, details: [e.details], nonRetryable });
+  return e;
+}

package/src/index.ts

@@ -1,55 +1,156 @@
 // Temporal: воркер на очереди модуля (task queue = имя модуля), клиент — по имени процесса.
-import { Client, Connection, type WorkflowHandle } from "@temporalio/client";
+import { Client, Connection, WorkflowFailedError, WorkflowNotFoundError, type WorkflowHandle } from "@temporalio/client";
 import { Context } from "@temporalio/activity";
 import { NativeConnection, Worker } from "@temporalio/worker";
-import { bindStepRuntime, type AppDefinition, type EngineClient, type EngineRuntime, type FlowHandle } from "@iworkflow/core";
+import {
+  bindStepRuntime,
+  FlowError,
+  type Activity,
+  type AppDefinition,
+  type EngineClient,
+  type EngineRuntime,
+  type FlowHandle,
+  type FlowStatus,
+} from "@iworkflow/core";
+import { address, connectOptions, namespace, renewApiKey, type TemporalOptions } from "./connection";
+import { cause, toTemporal } from "./failure";
+
+export type { TemporalOptions };
 
 // Те же имена, что в workflow.ts: его нельзя импортировать вне песочницы.
 const SIGNAL = "iwf.signal";
 const QUERY = "iwf.query";
+const poolQueue = (app: string, pool: string) => `${app}@${pool}`;
+
+const STATUS: Record<string, FlowStatus> = {
+  RUNNING: "running",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  CANCELLED: "terminated",
+  TERMINATED: "terminated",
+  TIMED_OUT: "timed-out",
+  CONTINUED_AS_NEW: "running",
+};
+
+const notFound = (id: string) => (e: unknown): never => {
+  if (e instanceof WorkflowNotFoundError) throw new FlowError(`процесса ${id} нет`, { reason: "not-found" });
+  throw e;
+};
 
 const wrap = <T>(h: WorkflowHandle): FlowHandle<T> => ({
   id: h.workflowId,
-  result: () => h.result(),
+  result: () =>
+    h.result().catch((e) => {
+      throw (e instanceof WorkflowFailedError && cause(e.cause)) || e;
+    }),
   signal: (topic, value) => h.signal(SIGNAL, { topic, value }),
   query: async <V>(key: string) => ((await h.query(QUERY, key)) ?? undefined) as V | undefined,
+  async describe() {
+    const d = await h.describe().catch(notFound(h.workflowId));
+    return { id: h.workflowId, status: STATUS[d.status.name] ?? "running", startedAt: d.startTime };
+  },
+  terminate: async (reason) => void (await h.terminate(reason).catch(notFound(h.workflowId))),
 });
 
-const address = () => process.env.TEMPORAL_URL ?? "127.0.0.1:17233";
-const namespace = () => process.env.TEMPORAL_NAMESPACE ?? "default";
+/** Шаги отдают Failure как ApplicationFailure: тип, детали и nonRetryable доезжают до процесса. */
+const withFailures = (activities: Record<string, Activity>) =>
+  Object.fromEntries(
+    Object.entries(activities).map(([name, fn]) => [
+      name,
+      async (...args: unknown[]) => {
+        try {
+          return await fn(...args);
+        } catch (e) {
+          throw toTemporal(e, false);
+        }
+      },
+    ]),
+  );
 
-/** workflowsPath — вход песочницы модуля: temporalFlow(...) на каждый процесс, имя экспорта = имя процесса. */
-export function temporalRuntime(workflowsPath: string): EngineRuntime {
-  let worker: Worker | undefined;
-  let running: Promise<void> | undefined;
+/**
+ * workflowsPath — вход песочницы модуля: temporalFlow(...) на каждый процесс, имя экспорта = имя процесса.
+ * workflowBundlePath — готовый бандл того же входа (прод-сборка); с ним воркер не собирает код сам.
+ */
+export function temporalRuntime(
+  workflowsPath: string,
+  opts: TemporalOptions & { workflowBundlePath?: string } = {},
+): EngineRuntime {
+  let workers: Worker[] = [];
+  let running: Promise<void>[] = [];
   let conn: NativeConnection | undefined;
+  let starting = false;
+  let stopRenew = () => {};
   return {
     async start(def: AppDefinition) {
+      if (starting) throw new Error("воркер уже запущен");
+      starting = true;
       bindStepRuntime({
         heartbeat: async (details) => Context.current().heartbeat(details),
         lastHeartbeat: async () => Context.current().info.heartbeatDetails,
       });
-      conn = await NativeConnection.connect({ address: address() });
-      worker = await Worker.create({
-        connection: conn,
-        namespace: namespace(),
-        taskQueue: def.app,
-        workflowsPath,
-        activities: def.activities,
-      });
-      running = worker.run();
+      let c: NativeConnection;
+      try {
+        c = conn = await NativeConnection.connect(await connectOptions(opts));
+      } catch (e) {
+        starting = false;
+        throw e;
+      }
+      stopRenew = renewApiKey(opts, (t) => c.setApiKey(t));
+      // Воркер не создался (нет бандла, namespace) — соединение и таймер токена закрываются.
+      try {
+        const activities = withFailures(def.activities);
+        const base = { connection: c, namespace: namespace(opts) };
+        const code = opts.workflowBundlePath ? { workflowBundle: { codePath: opts.workflowBundlePath } } : { workflowsPath };
+        workers = [await Worker.create({ ...base, taskQueue: def.app, ...code, activities })];
+        // Пул — своя очередь с пределом одновременных шагов в этом процессе.
+        for (const [pool, limit] of Object.entries(def.pools ?? {}))
+          workers.push(
+            await Worker.create({
+              ...base,
+              taskQueue: poolQueue(def.app, pool),
+              activities,
+              maxConcurrentActivityTaskExecutions: limit,
+            }),
+          );
+      } catch (e) {
+        // Созданный, но не запущенный воркер держит соединение: запустить и сразу погасить.
+        await Promise.allSettled(workers.map(async (w) => {
+          const r = w.run();
+          w.shutdown();
+          await r;
+        }));
+        stopRenew();
+        await c.close().catch(() => {});
+        conn = undefined;
+        workers = [];
+        starting = false;
+        throw e;
+      }
+      running = workers.map((w) => w.run());
     },
     async stop() {
-      worker?.shutdown();
-      await running;
-      await conn?.close();
+      for (const w of workers) if (w.getState() === "RUNNING") w.shutdown();
+      // Упавший воркер не мешает закрыть соединение и таймер токена.
+      const done = await Promise.allSettled(running);
+      stopRenew();
+      try {
+        await conn?.close();
+      } finally {
+        conn = undefined;
+        workers = [];
+        running = [];
+        starting = false;
+      }
+      const failed = done.find((r) => r.status === "rejected");
+      if (failed) throw (failed as PromiseRejectedResult).reason;
     },
   };
 }
 
-export async function temporalClient(): Promise<EngineClient> {
-  const connection = await Connection.connect({ address: address() });
-  const client = new Client({ connection, namespace: namespace() });
+export async function temporalClient(opts: TemporalOptions = {}): Promise<EngineClient> {
+  const connection = await Connection.connect(await connectOptions(opts));
+  const stopRenew = renewApiKey(opts, (t) => connection.setApiKey(t));
+  const client = new Client({ connection, namespace: namespace(opts) });
   return {
     async start(target, args, opts) {
       const h = await client.workflow.start(target.flow, {
@@ -57,10 +158,11 @@ export async function temporalClient(): Promise<EngineClient> {
         workflowId: opts.id,
         args,
         workflowIdConflictPolicy: "USE_EXISTING",
+        ...(opts.timeoutMs ? { workflowExecutionTimeout: opts.timeoutMs } : {}),
       });
       return wrap(h);
     },
     handle: (id) => wrap(client.workflow.getHandle(id)),
-    close: () => connection.close(),
+    close: () => (stopRenew(), connection.close()),
   };
 }

package/src/workflow.ts

@@ -8,36 +8,63 @@ import {
   deprecatePatch,
   executeChild,
   getExternalWorkflowHandle,
+  ParentClosePolicy,
   patched,
   proxyActivities,
   setHandler,
   sleep,
+  startChild,
+  TemporalFailure,
   workflowInfo,
 } from "@temporalio/workflow";
 
-import type { Flow, FlowContext, StepOptions } from "@iworkflow/core";
+import { FlowError, type ChildOptions, type Flow, type FlowContext, type StepOptions } from "@iworkflow/core";
+import { fromTemporal, toTemporal } from "./failure";
 
 export const SIGNAL = "iwf.signal";
 export const QUERY = "iwf.query";
 const signalDef = defineSignal<[{ topic: string; value: unknown }]>(SIGNAL);
 const queryDef = defineQuery<unknown, [string]>(QUERY);
 
+/** Очередь пула шагов модуля; воркер пула поднимает temporalRuntime. */
+export const poolQueue = (app: string, pool: string) => `${app}@${pool}`;
+
 const proxies = new Map<string, Record<string, (...a: unknown[]) => Promise<unknown>>>();
 
 function activitiesWith(opts: StepOptions = {}) {
-  const key = `${opts.attempts ?? 3}/${opts.timeoutMs ?? 60_000}/${opts.heartbeatTimeoutMs ?? 0}`;
+  const key = JSON.stringify(opts);
   let p = proxies.get(key);
   if (!p) {
     p = proxyActivities({
+      ...(opts.pool ? { taskQueue: poolQueue(workflowInfo().taskQueue, opts.pool) } : {}),
       startToCloseTimeout: opts.timeoutMs ?? 60_000,
+      ...(opts.totalTimeoutMs ? { scheduleToCloseTimeout: opts.totalTimeoutMs } : {}),
       ...(opts.heartbeatTimeoutMs ? { heartbeatTimeout: opts.heartbeatTimeoutMs } : {}),
-      retry: { maximumAttempts: opts.attempts ?? 3, initialInterval: "200 ms", backoffCoefficient: 1 },
+      retry: {
+        maximumAttempts: opts.attempts ?? 3,
+        initialInterval: opts.retryIntervalMs ?? 200,
+        backoffCoefficient: opts.backoff ?? 1,
+        ...(opts.maxRetryIntervalMs ? { maximumInterval: opts.maxRetryIntervalMs } : {}),
+        ...(opts.nonRetryableTypes ? { nonRetryableErrorTypes: opts.nonRetryableTypes } : {}),
+      },
     });
     proxies.set(key, p);
   }
   return p;
 }
 
+const childOptions = (app: string, args: unknown[], opts: ChildOptions) => ({
+  taskQueue: app,
+  workflowId: opts.id,
+  args,
+  ...(opts.timeoutMs ? { workflowExecutionTimeout: opts.timeoutMs } : {}),
+  ...(opts.onExisting === "reject" ? { workflowIdReusePolicy: "REJECT_DUPLICATE" as const } : {}),
+});
+
+const rethrow = (e: unknown): never => {
+  throw fromTemporal(e);
+};
+
 /** patches — как AppDefinition.patches: необъявленный id — ошибка, как у DBOS. */
 export function temporalFlow(flow: Flow, patches: string[] = []) {
   return async (...args: unknown[]) => {
@@ -51,17 +78,34 @@ export function temporalFlow(flow: Flow, patches: string[] = []) {
     });
     setHandler(queryDef, (key) => state.get(key));
 
+    const info = workflowInfo();
     const ctx: FlowContext = {
-      workflowId: workflowInfo().workflowId,
-      step: (name, stepArgs, opts) => activitiesWith(opts)[name]!(...stepArgs) as Promise<never>,
+      workflowId: info.workflowId,
+      parentId: info.parent?.workflowId,
+      startedAt: info.startTime,
+      step: (name, stepArgs, opts) => activitiesWith(opts)[name]!(...stepArgs).catch(rethrow) as Promise<never>,
       child: (target, childArgs, opts) =>
-        executeChild(target.flow, { taskQueue: target.app, workflowId: opts.id, args: childArgs }),
+        executeChild(target.flow, childOptions(target.app, childArgs, opts)).catch(rethrow) as Promise<never>,
+      async startChild(target, childArgs, opts) {
+        // REJECT_DUPLICATE: завершённый id тоже занят — как у DBOS, где id не переиспользуется.
+        const h = await startChild(target.flow, {
+          ...childOptions(target.app, childArgs, { ...opts, onExisting: "reject" }),
+          parentClosePolicy: ParentClosePolicy.ABANDON,
+        }).catch(rethrow);
+        return { id: opts.id, result: () => h.result().catch(rethrow) as Promise<never> };
+      },
       sleep: (ms) => sleep(ms),
       async recv<T>(topic: string, timeoutMs: number) {
         const ready = await condition(() => (inbox.get(topic)?.length ?? 0) > 0, timeoutMs);
         return ready ? (inbox.get(topic)!.shift() as T) : null;
       },
-      signal: (workflowId, topic, value) => getExternalWorkflowHandle(workflowId).signal(signalDef, { topic, value }),
+      signal: (workflowId, topic, value) =>
+        getExternalWorkflowHandle(workflowId)
+          .signal(signalDef, { topic, value })
+          .catch((e) => {
+            if (!(e instanceof TemporalFailure)) throw e;
+            throw new FlowError(`процесса ${workflowId} нет или он завершён`, { reason: "not-found" });
+          }),
       async setState(key, value) {
         state.set(key, value);
       },
@@ -71,6 +115,10 @@ export function temporalFlow(flow: Flow, patches: string[] = []) {
       },
       deprecatePatch: async (id) => deprecatePatch(id),
     };
-    return flow(ctx, ...args);
+    try {
+      return await flow(ctx, ...args);
+    } catch (e) {
+      throw toTemporal(e, true);
+    }
   };
 }