@pikku/kysely 0.13.10 → 0.13.12

package/CHANGELOG.md

@@ -1,3 +1,52 @@
+## 0.13.12
+
+### Patch Changes
+
+- e848eb2: Add `relayUndispatchedSteps()`, which re-drives steps whose queue or scheduler
+  dispatch was lost.
+
+  Arming a step is two writes to two systems — the step row lands `pending`, then
+  a job is published — and nothing spans both, so a crash in between leaves a
+  durable row nothing will ever pick up. The run then neither finishes nor fails.
+
+  The step row is the outbox record and this is the relay. It is safe to
+  re-dispatch a step that already has a live job because `executeWorkflowStepInner`
+  claims the step under `withStepLock` before invoking anything: the loser reads
+  `running` and returns. Stores opt in by overriding `findUndispatchedSteps`; the
+  default returns nothing, so a store without an atomic step lock gains no
+  re-dispatches. Opted in: `kysely-postgres` and `kysely-mysql` (real locks) and
+  in-memory (inline, single-process, no queues). Not opted in: `mongodb` and
+  `kysely-sqlite`, whose `withStepLock` is a pass-through.
+
+  Not self-starting — call it from a scheduled task.
+
+- Updated dependencies [e848eb2]
+- Updated dependencies [b170489]
+- Updated dependencies [ae4e898]
+  - @pikku/core@0.12.79
+
+## 0.13.11
+
+### Patch Changes
+
+- f5ce870: Recover workflow runs stalled by a crash mid-dispatch.
+
+  Arming a step is two writes to two systems — the step row, then the queue or
+  scheduler job — so a process that died between them left a run `running` with
+  nothing in flight. It parked on a step that would never complete and never
+  error, so the run neither finished nor failed, and nothing swept it up.
+
+  `workflowService.recoverStalledRuns()` re-drives those runs through
+  `resumeWorkflow`. Replay is memoized per step, so resuming a run that was not
+  actually stuck changes nothing; runs mid-sleep or with a step in flight are
+  excluded outright. It is not self-starting — call it from a scheduled task.
+
+  Stores opt in by overriding `findStalledRunIds`; implemented here for the
+  Kysely and in-memory services, and a no-op elsewhere.
+
+- Updated dependencies [f5ce870]
+  - @pikku/core@0.12.78
+
 ## 0.13.10
 
 ### Patch Changes

package/dist/src/kysely-workflow-service.d.ts

@@ -79,6 +79,21 @@ export declare class KyselyWorkflowService extends PikkuWorkflowService {
      */
     private jsonPathFor;
     protected updateRunStateImpl(runId: string, name: string, value: unknown): Promise<void>;
+    /**
+     * The undispatched-step query, shared by the dialects that can safely relay.
+     *
+     * Deliberately NOT an override of `findUndispatchedSteps`: this class's
+     * `withStepLock` is a pass-through, so a subclass inheriting it (kysely-sqlite)
+     * has no atomic claim, and the relay's redundant dispatches would become
+     * double executions. A dialect opts in by overriding `findUndispatchedSteps`
+     * to call this — which `kysely-postgres` and `kysely-mysql` do, having real
+     * locks.
+     */
+    protected queryUndispatchedSteps(before: Date, limit: number): Promise<Array<{
+        runId: string;
+        stepId: string;
+    }>>;
+    protected findStalledRunIds(before: Date, limit: number): Promise<string[]>;
     getRunState(runId: string): Promise<Record<string, unknown>>;
     protected upsertWorkflowVersionImpl(name: string, graphHash: string, graph: any, source: string, status?: WorkflowVersionStatus): Promise<void>;
     protected updateWorkflowVersionStatusImpl(name: string, graphHash: string, status: WorkflowVersionStatus): Promise<void>;

package/dist/src/kysely-workflow-service.js

@@ -464,6 +464,56 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
             .where('workflowRunId', '=', runId)
             .execute();
     }
+    /**
+     * The undispatched-step query, shared by the dialects that can safely relay.
+     *
+     * Deliberately NOT an override of `findUndispatchedSteps`: this class's
+     * `withStepLock` is a pass-through, so a subclass inheriting it (kysely-sqlite)
+     * has no atomic claim, and the relay's redundant dispatches would become
+     * double executions. A dialect opts in by overriding `findUndispatchedSteps`
+     * to call this — which `kysely-postgres` and `kysely-mysql` do, having real
+     * locks.
+     */
+    async queryUndispatchedSteps(before, limit) {
+        const rows = await this.db
+            .selectFrom('workflowStep as s')
+            .innerJoin('workflowRuns as r', 'r.workflowRunId', 's.workflowRunId')
+            .select(['s.workflowStepId', 's.workflowRunId'])
+            .where('s.status', '=', 'pending')
+            .where('s.updatedAt', '<', before)
+            // Leftover `pending` steps on a settled run are not work; only a live run
+            // still has anything to dispatch.
+            .where('r.status', '=', 'running')
+            .orderBy('s.updatedAt', 'asc')
+            .limit(limit)
+            .execute();
+        return rows.map((row) => ({
+            runId: row.workflowRunId,
+            stepId: row.workflowStepId,
+        }));
+    }
+    async findStalledRunIds(before, limit) {
+        const rows = await this.db
+            .selectFrom('workflowRuns as r')
+            .select('r.workflowRunId')
+            .where('r.status', '=', 'running')
+            .where(({ not, exists, selectFrom }) => not(exists(selectFrom('workflowStep as s')
+            .select('s.workflowStepId')
+            .whereRef('s.workflowRunId', '=', 'r.workflowRunId')
+            .where('s.status', 'in', ['running', 'scheduled', 'suspended']))))
+            // The run row only moves on a status change, so idleness has to hold for
+            // the steps too — expressed as "no step touched since `before`" rather
+            // than max(updated_at) so it stays one index-friendly NOT EXISTS.
+            .where('r.updatedAt', '<', before)
+            .where(({ not, exists, selectFrom }) => not(exists(selectFrom('workflowStep as s')
+            .select('s.workflowStepId')
+            .whereRef('s.workflowRunId', '=', 'r.workflowRunId')
+            .where('s.updatedAt', '>=', before))))
+            .orderBy('r.updatedAt', 'asc')
+            .limit(limit)
+            .execute();
+        return rows.map((row) => row.workflowRunId);
+    }
     async getRunState(runId) {
         const row = await this.db
             .selectFrom('workflowRuns')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/kysely",
-  "version": "0.13.10",
+  "version": "0.13.12",
   "description": "Kysely-backed Pikku services — workflow state, secrets, sessions, scopes and audit",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
@@ -21,7 +21,7 @@
     "prepublishOnly": "yarn build"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.77"
+    "@pikku/core": "^0.12.79"
   },
   "dependencies": {
     "kysely": "^0.29.0"

package/src/kysely-workflow-service.ts

@@ -600,6 +600,78 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
       .execute()
   }
 
+  /**
+   * The undispatched-step query, shared by the dialects that can safely relay.
+   *
+   * Deliberately NOT an override of `findUndispatchedSteps`: this class's
+   * `withStepLock` is a pass-through, so a subclass inheriting it (kysely-sqlite)
+   * has no atomic claim, and the relay's redundant dispatches would become
+   * double executions. A dialect opts in by overriding `findUndispatchedSteps`
+   * to call this — which `kysely-postgres` and `kysely-mysql` do, having real
+   * locks.
+   */
+  protected async queryUndispatchedSteps(
+    before: Date,
+    limit: number
+  ): Promise<Array<{ runId: string; stepId: string }>> {
+    const rows = await this.db
+      .selectFrom('workflowStep as s')
+      .innerJoin('workflowRuns as r', 'r.workflowRunId', 's.workflowRunId')
+      .select(['s.workflowStepId', 's.workflowRunId'])
+      .where('s.status', '=', 'pending')
+      .where('s.updatedAt', '<', before)
+      // Leftover `pending` steps on a settled run are not work; only a live run
+      // still has anything to dispatch.
+      .where('r.status', '=', 'running')
+      .orderBy('s.updatedAt', 'asc')
+      .limit(limit)
+      .execute()
+
+    return rows.map((row) => ({
+      runId: row.workflowRunId,
+      stepId: row.workflowStepId,
+    }))
+  }
+
+  protected async findStalledRunIds(
+    before: Date,
+    limit: number
+  ): Promise<string[]> {
+    const rows = await this.db
+      .selectFrom('workflowRuns as r')
+      .select('r.workflowRunId')
+      .where('r.status', '=', 'running')
+      .where(({ not, exists, selectFrom }) =>
+        not(
+          exists(
+            selectFrom('workflowStep as s')
+              .select('s.workflowStepId')
+              .whereRef('s.workflowRunId', '=', 'r.workflowRunId')
+              .where('s.status', 'in', ['running', 'scheduled', 'suspended'])
+          )
+        )
+      )
+      // The run row only moves on a status change, so idleness has to hold for
+      // the steps too — expressed as "no step touched since `before`" rather
+      // than max(updated_at) so it stays one index-friendly NOT EXISTS.
+      .where('r.updatedAt', '<', before)
+      .where(({ not, exists, selectFrom }) =>
+        not(
+          exists(
+            selectFrom('workflowStep as s')
+              .select('s.workflowStepId')
+              .whereRef('s.workflowRunId', '=', 'r.workflowRunId')
+              .where('s.updatedAt', '>=', before)
+          )
+        )
+      )
+      .orderBy('r.updatedAt', 'asc')
+      .limit(limit)
+      .execute()
+
+    return rows.map((row) => row.workflowRunId)
+  }
+
   async getRunState(runId: string): Promise<Record<string, unknown>> {
     const row = await this.db
       .selectFrom('workflowRuns')