@nanobpm/urban 0.10.0 → 0.11.1

package/src/runtime/core/modules/triggers.ts

@@ -3,35 +3,77 @@
 // message to the engine for correlation. HMAC verification uses Web Crypto (global in both
 // Node 18+ and Deno), so this stays runtime-agnostic.
 
-import type { AppApi, RuntimeContext } from "../context.ts";
+import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
 import type { HttpRequest } from "../host.ts";
 import { json, normalizeRoutePath, type Route } from "../router.ts";
 import type { TriggerDecl } from "../manifest.ts";
+import { nextCronFire, parseCron } from "./cron.ts";
 
-export interface TriggersHandle {
-  readonly name: string;
+export interface TriggersHandle extends Mounted {
   routes: Route[];
-  describe(): Record<string, unknown>;
 }
 
-/** Evaluate a tiny correlation expression: `= body.a.b`, or a literal string. */
-export function evalCorrelation(
-  expr: string | undefined,
-  scope: { body: unknown; headers: Record<string, string>; query: Record<string, string> },
-): string | undefined {
-  if (!expr) return undefined;
+/** Injectable timer + clock seam so cron scheduling is deterministic under test. */
+export interface SchedulerDeps {
+  setTimer: (fn: () => void, delayMs: number) => unknown;
+  clearTimer: (handle: unknown) => void;
+  /** Current wall-clock time in ms since epoch. */
+  now: () => number;
+}
+
+type Scope = { body: unknown; headers: Record<string, string>; query: Record<string, string> };
+
+/**
+ * Resolve a tiny FEEL-ish expression against the event scope: a `= body.a.b` path walk
+ * returns the raw value at that path (or `undefined` if any segment is missing); a literal
+ * (non-`=`) string is returned verbatim.
+ */
+export function resolveExpr(expr: string, scope: Scope): unknown {
   const trimmed = expr.trim();
   if (!trimmed.startsWith("=")) return trimmed; // literal
   const pathExpr = trimmed.slice(1).trim(); // e.g. "body.taskId"
   let cur: unknown = scope;
   for (const seg of pathExpr.split(".")) {
-    if (cur && typeof cur === "object" && seg in (cur as Record<string, unknown>)) {
+    if (cur && typeof cur === "object" && Object.prototype.hasOwnProperty.call(cur, seg)) {
       cur = (cur as Record<string, unknown>)[seg];
     } else {
       return undefined;
     }
   }
-  return cur == null ? undefined : String(cur);
+  return cur;
+}
+
+/** Evaluate a correlation expression to a string key: `= body.a.b`, or a literal string. */
+export function evalCorrelation(expr: string | undefined, scope: Scope): string | undefined {
+  if (!expr) return undefined;
+  const cur = resolveExpr(expr, scope);
+  // A correlation key must be scalar; a non-scalar (object/array) is not a usable key —
+  // return undefined rather than forcing a "[object Object]" string.
+  if (typeof cur === "string" || typeof cur === "number" || typeof cur === "boolean") {
+    return String(cur);
+  }
+  return undefined;
+}
+
+/**
+ * Resolve `action.variables` to the record handed to the engine (schema: a FEEL string over
+ * the event body — `#/$defs/triggerAction.variables`). A `= body.<path>` expression must
+ * resolve to an object; a plain object literal is accepted for convenience; anything else
+ * (missing, or a non-object result) falls back to the raw event body when that is an object,
+ * else `{}`.
+ */
+export function resolveActionVariables(
+  expr: unknown,
+  scope: Scope,
+): Record<string, unknown> {
+  const asRecord = (v: unknown): Record<string, unknown> | undefined =>
+    v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined;
+
+  if (typeof expr === "string") {
+    return asRecord(resolveExpr(expr, scope)) ?? asRecord(scope.body) ?? {};
+  }
+  // Back-compat: an inline object literal used directly as the variables.
+  return asRecord(expr) ?? asRecord(scope.body) ?? {};
 }
 
 async function verifyHmac(secret: string, body: string, signature: string): Promise<boolean> {
@@ -64,13 +106,146 @@ function headerRecord(req: HttpRequest): Record<string, string> {
   return out;
 }
 
-/** Mount webhook triggers and return their routes. */
-export function mountTriggers(ctx: RuntimeContext, app: AppApi): TriggersHandle {
+/**
+ * Fire a trigger's action against the engine: start a process or publish a message
+ * (ADR 0025 §1). `scope` supplies the event body/headers/query for FEEL-ish resolution
+ * of `correlationKey`/`variables`; cron passes a minimal `{ firedAt }` body. Returns what
+ * was done.
+ */
+export async function runTriggerAction(
+  app: AppApi,
+  action: TriggerDecl["action"],
+  scope: Scope,
+): Promise<{ kind: "start" | "message" | "none"; target?: string; correlationKey?: string }> {
+  if (!action) return { kind: "none" };
+  const variables = resolveActionVariables(action.variables, scope);
+
+  if (action.start) {
+    await app.engine.createInstance({ processDefinitionId: action.start, variables });
+    return { kind: "start", target: action.start };
+  }
+  if (action.message) {
+    const correlationKey = evalCorrelation(action.correlationKey, scope);
+    await app.engine.publishMessage({ name: action.message, correlationKey, variables });
+    return { kind: "message", target: action.message, correlationKey };
+  }
+  return { kind: "none" };
+}
+
+const emptyScope = { body: {}, headers: {} as Record<string, string>, query: {} as Record<string, string> };
+
+/** Max delay a single `setTimeout` honours before its 32-bit signed overflow (~24.8 days). */
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
+/** Default (live) scheduler seam, backed by the global timer functions. */
+function defaultScheduler(): SchedulerDeps {
+  return {
+    setTimer: (fn, ms) => globalThis.setTimeout(fn, ms),
+    clearTimer: (h) => globalThis.clearTimeout(h as ReturnType<typeof setTimeout>),
+    now: () => Date.now(),
+  };
+}
+
+/** Mount webhook + cron triggers. Webhooks contribute HTTP routes; cron triggers arm
+ *  background timers that fire their action on schedule. `stop()` clears every timer. */
+export function mountTriggers(
+  ctx: RuntimeContext,
+  app: AppApi,
+  sched: SchedulerDeps = defaultScheduler(),
+): TriggersHandle {
   const routes: Route[] = [];
   const mounted: string[] = [];
+  const scheduled: string[] = [];
   const seenDeliveries = new Set<string>();
+  const timers = new Set<unknown>();
+  let stopped = false;
+
+  // Arm a cron trigger: compute the next UTC fire, sleep until it, fire the action, repeat.
+  const armCron = (trig: TriggerDecl): void => {
+    const spec = trig.spec;
+    if (!spec) {
+      ctx.host.log("warn", `trigger "${trig.id}": cron trigger has no spec, skipped`);
+      return;
+    }
+    let schedule;
+    try {
+      schedule = parseCron(spec);
+    } catch (e) {
+      app.log("error", `trigger "${trig.id}": invalid cron spec "${spec}": ${String(e)}`);
+      return;
+    }
+    if (!trig.action?.start && !trig.action?.message) {
+      // A timer that can never do anything is pure waste — don't arm it (unlike a webhook,
+      // which is request-driven and costs nothing while idle).
+      app.log("warn", `trigger "${trig.id}": cron trigger has no action.start/message; not scheduled`);
+      return;
+    }
+    if (trig.onMissed && trig.onMissed !== "skip") {
+      // once/all catch-up needs a durable last-fire timestamp the runtime does not persist;
+      // without it, honour the safe default (skip) and say so rather than silently dropping.
+      app.log("warn", `trigger "${trig.id}": onMissed="${trig.onMissed}" not supported without ` +
+        `durable trigger state; scheduling forward as "skip"`);
+    }
+    // Probe the first fire before recording the trigger as scheduled, so an impossible spec
+    // (e.g. Feb 30) is reported honestly and never shows up in describe()/startup logs.
+    if (!nextCronFire(schedule, new Date(sched.now()))) {
+      app.log("warn", `trigger "${trig.id}": cron spec "${spec}" never fires; not scheduled`);
+      return;
+    }
+    scheduled.push(`${trig.id}@${spec}`);
+
+    const arm = (): void => {
+      if (stopped) return;
+      // Capture the clock once so `next` and `delay` are derived from the same instant.
+      const nowMs = sched.now();
+      const next = nextCronFire(schedule, new Date(nowMs));
+      if (!next) return; // spec became unsatisfiable (defensive; the probe above already vetted it)
+      const remaining = Math.max(0, next.getTime() - nowMs);
+
+      // setTimeout delays are clamped to a 32-bit signed int (~24.8 days); a larger delay
+      // overflows and fires immediately. For far-future fires (monthly/annual specs), sleep in
+      // bounded chunks and re-arm — without firing — until the real deadline is within range.
+      if (remaining > MAX_TIMER_DELAY_MS) {
+        let chunk: unknown;
+        chunk = sched.setTimer(() => {
+          timers.delete(chunk);
+          if (stopped) return;
+          arm();
+        }, MAX_TIMER_DELAY_MS);
+        timers.add(chunk);
+        return;
+      }
+
+      // Declare `handle` before arming so the callback can reference it even if a scheduler
+      // double invokes it synchronously (avoids a TDZ ReferenceError on `timers.delete`).
+      let handle: unknown;
+      handle = sched.setTimer(() => {
+        timers.delete(handle);
+        if (stopped) return;
+        void (async () => {
+          try {
+            const res = await runTriggerAction(app, trig.action, {
+              ...emptyScope,
+              body: { firedAt: next.toISOString() },
+            });
+            app.log("info", `trigger "${trig.id}" fired`, { firedAt: next.toISOString(), ...res });
+          } catch (err) {
+            app.log("error", `trigger "${trig.id}": action failed`, { error: String(err) });
+          } finally {
+            arm(); // reschedule regardless of success (at-least-once, idempotent handlers)
+          }
+        })();
+      }, remaining);
+      timers.add(handle);
+    };
+    arm();
+  };
 
   for (const trig of (ctx.manifest.triggers ?? []) as TriggerDecl[]) {
+    if (trig.type === "cron") {
+      armCron(trig);
+      continue;
+    }
     if (trig.type !== "webhook") {
       ctx.host.log("warn", `trigger "${trig.id}": type "${trig.type}" not implemented, skipped`);
       continue;
@@ -117,27 +292,31 @@ export function mountTriggers(ctx: RuntimeContext, app: AppApi): TriggersHandle
           return json({ error: "body must be JSON" }, 400);
         }
 
-        const message = trig.action?.message;
-        if (!message) {
-          app.log("warn", `trigger "${trig.id}": no action.message; nothing published`);
-          return json({ ok: true, published: false });
+        if (!trig.action?.message && !trig.action?.start) {
+          app.log("warn", `trigger "${trig.id}": no action.message/start; nothing to do`);
+          return json({ ok: true, fired: false });
         }
-        const correlationKey = evalCorrelation(trig.action?.correlationKey, {
+        const res = await runTriggerAction(app, trig.action, {
           body,
           headers,
           query: Object.fromEntries(req.query),
         });
-        await app.engine.publishMessage({
-          name: message,
-          correlationKey,
-          variables: (body && typeof body === "object" ? (body as Record<string, unknown>) : {}),
-        });
-        app.log("info", `trigger "${trig.id}" published`, { message, correlationKey });
-        return json({ ok: true, published: true, message, correlationKey });
+        // `res.kind` is the honest verb (start | message); don't hard-code "published".
+        app.log("info", `trigger "${trig.id}" fired`, { ...res });
+        return json({ ok: true, fired: true, ...res });
       },
     });
   }
 
-  ctx.host.log("info", "triggers mounted", { mounted });
-  return { name: "triggers", routes, describe: () => ({ mounted }) };
+  ctx.host.log("info", "triggers mounted", { mounted, scheduled });
+  return {
+    name: "triggers",
+    routes,
+    describe: () => ({ mounted, scheduled }),
+    async stop() {
+      stopped = true;
+      for (const h of timers) sched.clearTimer(h);
+      timers.clear();
+    },
+  };
 }

package/src/runtime/core/runtime.ts

@@ -180,7 +180,8 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
         if (flags.triggers) {
           const t = mountTriggers(ctx, api);
           routes.push(...t.routes);
-          describe.triggers = t.describe();
+          mounted.push(t);
+          describe.triggers = t.describe?.();
         }
         if (security) describe.security = security.describe();
         if (data) describe.data = data.describe();

package/src/runtime/engine/nanosdk.test.ts

@@ -81,6 +81,9 @@ function fakeSdkClient(overrides: Partial<NanoSdkClient> = {}): NanoSdkClient &
           rec.stopped++;
         },
       };
+      // The real nano-sdk starts the worker itself after async transport detection
+      // (autoStart defaults on). Model that here so the adapter must NOT call start().
+      if (cfg.autoStart !== false) worker.start();
       return worker;
     },
     close() {
@@ -198,7 +201,7 @@ test("completeUserTask routes through the SDK", async () => {
   assert.deepEqual(seen, { userTaskKey: "utk", variables: { done: true } });
 });
 
-test("registerWorker creates a worker (autoStart false), starts it, and dispatches + completes", async () => {
+test("registerWorker creates a worker the SDK auto-starts, and dispatches + completes", async () => {
   const client = fakeSdkClient();
   const engine = new SdkEngineClient(client);
   const handled: Record<string, unknown>[] = [];
@@ -212,7 +215,9 @@ test("registerWorker creates a worker (autoStart false), starts it, and dispatch
   );
   assert.equal(sub.jobType, "svc");
   const rec = client.workers[0];
-  assert.equal(rec.cfg.autoStart, false);
+  // The adapter must not force autoStart off or call start() itself (that races the
+  // SDK's async transport detection); the SDK owns the start lifecycle.
+  assert.equal(rec.cfg.autoStart, undefined);
   assert.equal(rec.cfg.workerName, "urban:svc");
   assert.equal(rec.cfg.maxParallelJobs, 4);
   assert.equal(rec.started, 1);
@@ -272,6 +277,31 @@ test("close stops every worker and closes the SDK client", async () => {
   assert.equal(client.closed, 1);
 });
 
+test("close drains the REST-fallback worker via the SDK's stopAllWorkers", async () => {
+  let stopAllCalls = 0;
+  const client = fakeSdkClient({
+    async stopAllWorkers() {
+      stopAllCalls++;
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  await engine.registerWorker("a", async () => ({}));
+  await engine.close();
+  // The SDK may start a REST-fallback worker whose handle we never receive;
+  // close() must reach it through the client's stopAllWorkers().
+  assert.equal(stopAllCalls, 1, "close awaits client.stopAllWorkers exactly once");
+  assert.equal(client.closed, 1);
+});
+
+test("close tolerates a client without stopAllWorkers", async () => {
+  const client = fakeSdkClient();
+  delete (client as { stopAllWorkers?: unknown }).stopAllWorkers;
+  const engine = new SdkEngineClient(client);
+  await engine.registerWorker("a", async () => ({}));
+  await engine.close();
+  assert.equal(client.closed, 1);
+});
+
 test("exposes the underlying nano-sdk client as .sdk", () => {
   const client = fakeSdkClient();
   const engine = new SdkEngineClient(client);

package/src/runtime/engine/nanosdk.ts

@@ -49,7 +49,8 @@ export interface NanoSdkJobWorkerConfig {
   jobTimeoutMs?: number;
   pollTimeoutMs?: number;
   fetchVariables?: string[];
-  /** Start polling immediately. This adapter sets it false and starts explicitly. */
+  /** Start polling immediately (the SDK default). The adapter leaves this unset so the
+   * SDK owns the start lifecycle after its async Nano/Falcon transport detection. */
   autoStart?: boolean;
 }
 
@@ -97,6 +98,10 @@ export interface NanoSdkClient {
     options?: unknown,
   ): Promise<unknown>;
   createJobWorker(cfg: NanoSdkJobWorkerConfig): NanoSdkJobWorker;
+  /** Stop every worker created on this client. Used on teardown to also drain a
+   * REST-fallback worker, whose handle the `createJobWorker` proxy starts internally
+   * and does not hand back. Optional: not every injected client implements it. */
+  stopAllWorkers?(): void | Promise<void>;
   close?(): void | Promise<void>;
 }
 
@@ -210,9 +215,6 @@ export class SdkEngineClient implements EngineClient {
       workerName: options?.workerName ?? `urban:${jobType}`,
       maxParallelJobs: options?.maxParallelJobs ?? 8,
       fetchVariables: options?.fetchVariables,
-      // Own the poll lifecycle here rather than leaving it to the SDK's auto-start
-      // default, so nothing polls until `start()` is called below.
-      autoStart: false,
       jobHandler: async (job) => {
         const rawKey = job.jobKey;
         if (rawKey == null || rawKey === "") {
@@ -244,7 +246,11 @@ export class SdkEngineClient implements EngineClient {
         }
       },
     });
-    await worker.start();
+    // The nano-sdk job worker owns its own start lifecycle: `createJobWorker` runs
+    // async Nano/Falcon detection and, once the transport is bound, starts polling
+    // itself (Falcon) or hands off to an auto-started REST worker. Calling `start()`
+    // here would race that detection and dereference a still-null transport, so we
+    // don't — the worker autostarts.
     this.workers.add(worker);
 
     return {
@@ -269,6 +275,13 @@ export class SdkEngineClient implements EngineClient {
   async close(): Promise<void> {
     for (const w of this.workers) await this.stopWorker(w);
     this.workers.clear();
+    try {
+      // Also drain any REST-fallback worker the SDK started internally (its handle is
+      // not the one we hold), which `stopWorker` above cannot reach.
+      await this.client.stopAllWorkers?.();
+    } catch {
+      /* no workers running / already stopped */
+    }
     try {
       await this.client.close?.();
     } catch {