@kubun/store-workflow 0.15.0 → 0.16.0

package/lib/api.d.ts

@@ -91,6 +91,7 @@ export type WorkflowStoreAPI = {
     checkpoint(instanceID: string, input: CheckpointInput, now: number): Promise<void>;
     fail(instanceID: string, input: FailInput, now: number, bootID?: string): Promise<boolean>;
     finish(instanceID: string, input: FinishInput, now: number, bootID?: string): Promise<boolean>;
+    retryFailed(instanceID: string, now: number): Promise<WorkflowInstanceRow | null>;
     listRecoverable(now: number): Promise<Array<WorkflowInstanceRow>>;
     countRunning(queue: string, now: number): Promise<number>;
     listRunnableQueues(now: number): Promise<Array<string>>;

package/lib/api.js

@@ -35,11 +35,10 @@ export function createWorkflowStore(db, adapter) {
             const queue = input.queue ?? input.name;
             const runAfter = input.runAfter ?? input.createdAt;
             const updatedAt = input.updatedAt ?? input.createdAt;
-            // A transaction gives the pre-checks and the insert one snapshot. The
-            // partial unique index is the concurrent-race backstop (a second
-            // in-flight insert for the same active singleton would surface as a
-            // thrown constraint error); the graceful created:false return is the
-            // sequential pre-check path, so no driver error strings are parsed.
+            // The transaction gives the pre-checks and the insert one snapshot. The
+            // partial unique index is the race backstop; the graceful created:false
+            // return is the sequential pre-check path, so no driver error strings are
+            // parsed.
             return await db.transaction().execute(async (tx)=>{
                 if (input.idempotencyKey != null) {
                     const existing = await tx.selectFrom('kubun_workflow_instances').selectAll().where('idempotency_key', '=', input.idempotencyKey).executeTakeFirst();
@@ -64,6 +63,12 @@ export function createWorkflowStore(db, adapter) {
                         };
                     }
                 }
+                // ON CONFLICT DO NOTHING makes the insert atomic against a racer this
+                // snapshot's pre-checks could not yet see: two inserts for the same
+                // idempotency_key (the cross-hub idempotent retry) or the same active
+                // singleton both clear the pre-checks, and the unique indexes arbitrate.
+                // The loser inserts nothing and reads the winner's row below — no
+                // adapter-specific constraint-error parsing.
                 await tx.insertInto('kubun_workflow_instances').values({
                     instance_id: input.instanceID,
                     name: input.name,
@@ -81,12 +86,43 @@ export function createWorkflowStore(db, adapter) {
                     last_error: null,
                     created_at: input.createdAt,
                     updated_at: updatedAt
-                }).execute();
-                const row = await tx.selectFrom('kubun_workflow_instances').selectAll().where('instance_id', '=', input.instanceID).executeTakeFirstOrThrow();
-                return {
-                    row: rowToInstance(row),
-                    created: true
-                };
+                }).onConflict((oc)=>oc.doNothing()).execute();
+                const row = await tx.selectFrom('kubun_workflow_instances').selectAll().where('instance_id', '=', input.instanceID).executeTakeFirst();
+                if (row != null) {
+                    return {
+                        row: rowToInstance(row),
+                        created: true
+                    };
+                }
+                // The insert was a no-op: a concurrent racer holds the conflicting key.
+                // Return its row as the idempotent/singleton hit, mirroring the pre-checks.
+                if (input.idempotencyKey != null) {
+                    const existing = await tx.selectFrom('kubun_workflow_instances').selectAll().where('idempotency_key', '=', input.idempotencyKey).executeTakeFirst();
+                    if (existing != null) {
+                        return {
+                            row: rowToInstance(existing),
+                            created: false,
+                            reason: 'idempotent'
+                        };
+                    }
+                }
+                if (input.singletonKey != null) {
+                    const active = await tx.selectFrom('kubun_workflow_instances').selectAll().where('name', '=', input.name).where('singleton_key', '=', input.singletonKey).where('status', 'in', [
+                        'pending',
+                        'running'
+                    ]).executeTakeFirst();
+                    if (active != null) {
+                        return {
+                            row: rowToInstance(active),
+                            created: false,
+                            reason: 'singleton'
+                        };
+                    }
+                }
+                // A no-op insert with no recoverable conflicting row means the constraint
+                // hit was neither unique index we recover from — surface it, never a
+                // silent empty return.
+                throw new Error(`Workflow instance "${input.instanceID}" insert did nothing but no conflicting row was found`);
             });
         },
         async claim (instanceID, bootID, leaseMs, now) {
@@ -122,11 +158,10 @@ export function createWorkflowStore(db, adapter) {
                         ])
                     ])
                 ]);
-            // One statement: pick the next `limit` candidates in the inner select, but
-            // repeat `claimable` in the OUTER update's WHERE so IT is the atomic guard.
-            // Under a concurrent claimDue the loser blocks on the row lock, then
-            // re-evaluates the outer WHERE against the now-running row (its own
-            // columns, not the snapshot subquery) and skips it — no double-claim,
+            // One statement: the inner select picks the next `limit` candidates, but
+            // `claimable` is repeated in the OUTER update's WHERE so IT is the atomic
+            // guard. A concurrent loser blocks on the row lock, re-evaluates the outer
+            // WHERE against the now-running row, and skips it — no double-claim,
             // without SKIP LOCKED (which SQLite lacks).
             const rows = await db.updateTable('kubun_workflow_instances').set({
                 status: 'running',
@@ -183,6 +218,31 @@ export function createWorkflowStore(db, adapter) {
             const row = await query.returning('instance_id').executeTakeFirst();
             return row != null;
         },
+        async retryFailed (instanceID, now) {
+            // One conditional UPDATE. `status = 'failed'` is the atomic guard: two
+            // concurrent retries leave one winner, the loser matching nothing. The
+            // singleton guard is a correlated NOT EXISTS re-checked in the same
+            // statement; the partial-unique singleton index is the true race backstop
+            // (a live singleton slipping past NOT EXISTS violates it on the write to
+            // `pending`, surfacing as a thrown singleton refusal). next_action IS NOT
+            // NULL keeps an unresumable row from re-arming into a fabricated action.
+            const row = await db.updateTable('kubun_workflow_instances').set({
+                status: 'pending',
+                lease_owner: null,
+                lease_expires: null,
+                last_error: null,
+                attempts: 0,
+                run_after: now,
+                updated_at: now
+            }).where('instance_id', '=', instanceID).where('status', '=', 'failed').where('next_action', 'is not', null).where((eb)=>eb.or([
+                    eb('singleton_key', 'is', null),
+                    eb.not(eb.exists(eb.selectFrom('kubun_workflow_instances as o').select('o.instance_id').whereRef('o.name', '=', 'kubun_workflow_instances.name').whereRef('o.singleton_key', '=', 'kubun_workflow_instances.singleton_key').whereRef('o.instance_id', '<>', 'kubun_workflow_instances.instance_id').where('o.status', 'in', [
+                        'pending',
+                        'running'
+                    ])))
+                ])).returningAll().executeTakeFirst();
+            return row != null ? rowToInstance(row) : null;
+        },
         async listRecoverable (now) {
             const rows = await db.selectFrom('kubun_workflow_instances').selectAll().where('status', '=', 'running').where('lease_expires', '<', now).execute();
             return rows.map(rowToInstance);
@@ -234,14 +294,13 @@ export function createWorkflowStore(db, adapter) {
         async upsertAdaptiveSchedule (input, now) {
             const reactivate = input.reactivate ?? true;
             // One statement, no preceding read: ON CONFLICT DO UPDATE lets two
-            // concurrent enables of the same id both commit — one inserts, the other
-            // updates — instead of the loser hitting the PK constraint. RETURNING
-            // hands back the row as committed by this statement. The update touches
-            // only next_run + enabled, so an existing row's params/policy and its
-            // last_outcome/consecutive_count streak survive a re-arm. Under
-            // reactivate:false the update keeps the stored `enabled` flag (a
-            // qualified self-reference, portable across SQLite and Postgres) so a
-            // user-paused row is not silently re-enabled; next_run still advances.
+            // concurrent enables of the same id both commit — one inserts, one updates
+            // — instead of the loser hitting the PK constraint. RETURNING hands back
+            // the committed row. The update touches only next_run + enabled, so an
+            // existing row's params/policy and its outcome streak survive a re-arm.
+            // Under reactivate:false it keeps the stored `enabled` flag (a qualified
+            // self-reference, portable across SQLite and Postgres) so a user-paused row
+            // is not silently re-enabled; next_run still advances.
             const row = await db.insertInto('kubun_workflow_schedules').values({
                 id: input.id,
                 workflow_name: input.workflowName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/store-workflow",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,13 +15,13 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kubun/db": "^0.15.0",
-    "@kubun/db-adapter": "^0.15.0",
+    "@kubun/db": "^0.16.0",
+    "@kubun/db-adapter": "^0.16.0",
     "kysely": "^0.29.5"
   },
   "devDependencies": {
-    "@kubun/db-better-sqlite": "^0.15.0",
-    "@kubun/db-postgres": "^0.15.0",
+    "@kubun/db-better-sqlite": "^0.16.0",
+    "@kubun/db-postgres": "^0.16.0",
     "@testcontainers/postgresql": "^12.1.0"
   },
   "publishConfig": {