@fragno-dev/db 0.2.2 → 0.4.1

package/src/hooks/hooks.test.ts

@@ -1,22 +1,47 @@
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
 import SQLite from "better-sqlite3";
 import { SqliteDialect } from "kysely";
-import { beforeAll, describe, expect, it, vi } from "vitest";
+
 import { instantiate } from "@fragno-dev/core";
-import { prepareHookMutations, processHooks, type HooksMap, type HookContext } from "./hooks";
-import { internalFragmentDef, internalSchema } from "../fragments/internal-fragment";
-import type { FragnoPublicConfigWithDatabase } from "../db-fragment-definition-builder";
-import { DrizzleAdapter } from "../adapters/drizzle/drizzle-adapter";
+
 import { BetterSQLite3DriverConfig } from "../adapters/generic-sql/driver-config";
+import { SqlAdapter } from "../adapters/generic-sql/generic-sql-adapter";
+import type { FragnoPublicConfigWithDatabase } from "../db-fragment-definition-builder";
+import { internalFragmentDef, internalSchema } from "../fragments/internal-fragment";
+import { getRegistryForAdapterSync } from "../internal/adapter-registry";
+import { ConcurrencyConflictError } from "../query/unit-of-work/execute-unit-of-work";
 import { ExponentialBackoffRetryPolicy, NoRetryPolicy } from "../query/unit-of-work/retry-policy";
-import type { FragnoId } from "../schema/create";
+import { FragnoId } from "../schema/create";
+import { DurableHooksLogger } from "./durable-hooks-logger";
+import {
+  prepareHookMutations,
+  processHooks,
+  createDurableHooksRunner,
+  type HooksMap,
+  type HookContext,
+  type HookHandlerTx,
+} from "./hooks";
+
+const TEST_NS = "test";
+
+type OptionsWithAdapter = FragnoPublicConfigWithDatabase & {
+  databaseAdapter: SqlAdapter;
+};
 
 describe("Hook System", () => {
+  const handlerTx = (() => {
+    throw new Error("handlerTx not configured for hooks test");
+  }) as HookHandlerTx;
   let sqliteDatabase: SQLite.Database;
-  let adapter: DrizzleAdapter;
+  let adapter: SqlAdapter;
   let internalFragment: ReturnType<typeof instantiateFragment>;
 
-  function instantiateFragment(options: FragnoPublicConfigWithDatabase) {
-    return instantiate(internalFragmentDef).withConfig({}).withOptions(options).build();
+  function instantiateFragment(options: OptionsWithAdapter) {
+    return instantiate(internalFragmentDef)
+      .withConfig({ registry: getRegistryForAdapterSync(options.databaseAdapter) })
+      .withOptions(options)
+      .build();
   }
 
   beforeAll(async () => {
@@ -26,18 +51,19 @@ describe("Hook System", () => {
       database: sqliteDatabase,
     });
 
-    adapter = new DrizzleAdapter({
+    adapter = new SqlAdapter({
       dialect,
       driverConfig: new BetterSQLite3DriverConfig(),
     });
 
     {
-      const migrations = adapter.prepareMigrations(internalSchema, "");
+      const migrations = adapter.prepareMigrations(internalSchema, TEST_NS);
       await migrations.executeWithDriver(adapter.driver, 0);
     }
 
-    const options: FragnoPublicConfigWithDatabase = {
+    const options: OptionsWithAdapter = {
       databaseAdapter: adapter,
+      databaseNamespace: TEST_NS,
     };
 
     internalFragment = instantiateFragment(options);
@@ -48,8 +74,11 @@ describe("Hook System", () => {
   }, 12000);
 
   describe("prepareHookMutations", () => {
+    beforeEach(() => {
+      sqliteDatabase.exec("DELETE FROM fragno_hooks_test");
+    });
+
     it("should create hook records for triggered hooks", async () => {
-      const namespace = "test-namespace";
       const hooks: HooksMap = {
         onTest: vi.fn(),
       };
@@ -68,12 +97,11 @@ describe("Hook System", () => {
             uow.triggerHook("onTest", { data: "test" });
 
             // Prepare hook mutations
-            prepareHookMutations(uow, {
-              hooks,
-              namespace,
+            prepareHookMutations(
+              uow,
               internalFragment,
-              defaultRetryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 5 }),
-            });
+              new ExponentialBackoffRetryPolicy({ maxRetries: 5 }),
+            );
           })
           .execute();
       });
@@ -86,7 +114,7 @@ describe("Hook System", () => {
       const events = await internalFragment.inContext(async function () {
         return await this.handlerTx()
           .withServiceCalls(
-            () => [internalFragment.services.hookService.getPendingHookEvents(namespace)] as const,
+            () => [internalFragment.services.hookService.getHooksByNamespace(TEST_NS)] as const,
           )
           .transform(({ serviceResult: [result] }) => result)
           .execute();
@@ -101,8 +129,97 @@ describe("Hook System", () => {
       });
     });
 
+    it("should store a provided hook id", async () => {
+      const namespace = internalFragment.$internal.deps.namespace ?? internalSchema.name;
+      const hookId = "hook-id-1";
+      const hooks: HooksMap = {
+        onId: vi.fn(),
+      };
+
+      await internalFragment.inContext(async function () {
+        await this.handlerTx()
+          .mutate(({ forSchema }) => {
+            const uow = forSchema(internalSchema, hooks);
+
+            uow.triggerHook("onId", { data: "test" }, { id: hookId });
+
+            prepareHookMutations(
+              uow,
+              internalFragment,
+              new ExponentialBackoffRetryPolicy({ maxRetries: 5 }),
+            );
+          })
+          .execute();
+      });
+
+      const events = await internalFragment.inContext(async function () {
+        return await this.handlerTx()
+          .withServiceCalls(
+            () => [internalFragment.services.hookService.getHooksByNamespace(namespace)] as const,
+          )
+          .transform(({ serviceResult: [result] }) => result)
+          .execute();
+      });
+
+      expect(events).toHaveLength(1);
+      expect(events[0]?.id.externalId).toBe(hookId);
+    });
+
+    it("should fail when a hook id already exists", async () => {
+      const namespace = internalFragment.$internal.deps.namespace ?? internalSchema.name;
+      const hookId = "hook-id-conflict";
+      const hooks: HooksMap = {
+        onIdConflict: vi.fn(),
+      };
+
+      await internalFragment.inContext(async function () {
+        await this.handlerTx()
+          .mutate(({ forSchema }) => {
+            const uow = forSchema(internalSchema, hooks);
+
+            uow.triggerHook("onIdConflict", { data: "first" }, { id: hookId });
+
+            prepareHookMutations(
+              uow,
+              internalFragment,
+              new ExponentialBackoffRetryPolicy({ maxRetries: 5 }),
+            );
+          })
+          .execute();
+      });
+
+      await expect(
+        internalFragment.inContext(async function () {
+          await this.handlerTx()
+            .mutate(({ forSchema }) => {
+              const uow = forSchema(internalSchema, hooks);
+
+              uow.triggerHook("onIdConflict", { data: "second" }, { id: hookId });
+
+              prepareHookMutations(
+                uow,
+                internalFragment,
+                new ExponentialBackoffRetryPolicy({ maxRetries: 5 }),
+              );
+            })
+            .execute();
+        }),
+      ).rejects.toThrow();
+
+      const events = await internalFragment.inContext(async function () {
+        return await this.handlerTx()
+          .withServiceCalls(
+            () => [internalFragment.services.hookService.getHooksByNamespace(namespace)] as const,
+          )
+          .transform(({ serviceResult: [result] }) => result)
+          .execute();
+      });
+
+      expect(events).toHaveLength(1);
+      expect(events[0]?.id.externalId).toBe(hookId);
+    });
+
     it("should set maxAttempts to 1 when retry policy does not retry", async () => {
-      const namespace = "test-no-retry";
       const hooks: HooksMap = {
         onNoRetry: vi.fn(),
       };
@@ -114,12 +231,7 @@ describe("Hook System", () => {
 
             uow.triggerHook("onNoRetry", { data: "test" });
 
-            prepareHookMutations(uow, {
-              hooks,
-              namespace,
-              internalFragment,
-              defaultRetryPolicy: new NoRetryPolicy(),
-            });
+            prepareHookMutations(uow, internalFragment, new NoRetryPolicy());
           })
           .execute();
       });
@@ -127,7 +239,7 @@ describe("Hook System", () => {
       const events = await internalFragment.inContext(async function () {
         return await this.handlerTx()
           .withServiceCalls(
-            () => [internalFragment.services.hookService.getPendingHookEvents(namespace)] as const,
+            () => [internalFragment.services.hookService.getHooksByNamespace(TEST_NS)] as const,
           )
           .transform(({ serviceResult: [result] }) => result)
           .execute();
@@ -138,7 +250,6 @@ describe("Hook System", () => {
     });
 
     it("should use custom retry policy from trigger options", async () => {
-      const namespace = "test-custom-retry";
       const hooks: HooksMap = {
         onCustomRetry: vi.fn(),
       };
@@ -156,12 +267,11 @@ describe("Hook System", () => {
               },
             );
 
-            prepareHookMutations(uow, {
-              hooks,
-              namespace,
+            prepareHookMutations(
+              uow,
               internalFragment,
-              defaultRetryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 10 }),
-            });
+              new ExponentialBackoffRetryPolicy({ maxRetries: 10 }),
+            );
           })
           .execute();
       });
@@ -169,7 +279,7 @@ describe("Hook System", () => {
       const events = await internalFragment.inContext(async function () {
         return await this.handlerTx()
           .withServiceCalls(
-            () => [internalFragment.services.hookService.getPendingHookEvents(namespace)] as const,
+            () => [internalFragment.services.hookService.getHooksByNamespace(TEST_NS)] as const,
           )
           .transform(({ serviceResult: [result] }) => result)
           .execute();
@@ -177,6 +287,126 @@ describe("Hook System", () => {
 
       expect(events[0]?.maxAttempts).toBe(1);
     });
+
+    it("should set nextRetryAt when processAt is in the future", async () => {
+      const hooks: HooksMap = {
+        onScheduled: vi.fn(),
+      };
+      const futureTime = new Date(Date.now() + 60000);
+
+      await internalFragment.inContext(async function () {
+        await this.handlerTx()
+          .mutate(({ forSchema }) => {
+            const uow = forSchema(internalSchema, hooks);
+
+            uow.triggerHook("onScheduled", { data: "test" }, { processAt: futureTime });
+
+            prepareHookMutations(
+              uow,
+              internalFragment,
+              new ExponentialBackoffRetryPolicy({ maxRetries: 5 }),
+            );
+          })
+          .execute();
+      });
+
+      const events = await internalFragment.inContext(async function () {
+        return await this.handlerTx()
+          .withServiceCalls(
+            () => [internalFragment.services.hookService.getHooksByNamespace(TEST_NS)] as const,
+          )
+          .transform(({ serviceResult: [result] }) => result)
+          .execute();
+      });
+
+      expect(events).toHaveLength(1);
+      expect(events[0]?.nextRetryAt).toBeInstanceOf(Date);
+      expect(events[0]?.nextRetryAt?.getTime()).toBe(futureTime.getTime());
+    });
+
+    it("should keep processAt in the past while remaining immediately eligible", async () => {
+      const hooks: HooksMap = {
+        onImmediate: vi.fn(),
+      };
+      const pastTime = new Date(Date.now() - 60000);
+
+      await internalFragment.inContext(async function () {
+        await this.handlerTx()
+          .mutate(({ forSchema }) => {
+            const uow = forSchema(internalSchema, hooks);
+
+            uow.triggerHook("onImmediate", { data: "test" }, { processAt: pastTime });
+
+            prepareHookMutations(
+              uow,
+              internalFragment,
+              new ExponentialBackoffRetryPolicy({ maxRetries: 5 }),
+            );
+          })
+          .execute();
+      });
+
+      const events = await internalFragment.inContext(async function () {
+        return await this.handlerTx()
+          .withServiceCalls(
+            () => [internalFragment.services.hookService.getHooksByNamespace(TEST_NS)] as const,
+          )
+          .transform(({ serviceResult: [result] }) => result)
+          .execute();
+      });
+
+      expect(events).toHaveLength(1);
+      expect(events[0]?.nextRetryAt).toBeInstanceOf(Date);
+      expect(events[0]?.nextRetryAt?.getTime()).toBe(pastTime.getTime());
+    });
+
+    it("should preserve full hookName in queued hooks log summary when it contains colons", async () => {
+      const hookName = "on:segment:created";
+      const hooks: HooksMap = {
+        [hookName]: vi.fn(),
+      };
+      const debugSpy = vi.spyOn(DurableHooksLogger, "debug").mockImplementation(() => {});
+
+      try {
+        await internalFragment.inContext(async function () {
+          await this.handlerTx()
+            .mutate(({ forSchema }) => {
+              const uow = forSchema(internalSchema, hooks);
+              uow.triggerHook(hookName, { data: "test" });
+              prepareHookMutations(
+                uow,
+                internalFragment,
+                new ExponentialBackoffRetryPolicy({ maxRetries: 5 }),
+              );
+            })
+            .execute();
+        });
+
+        const queuedCall = debugSpy.mock.calls.find(
+          ([message]) => message === "Durable hooks queued",
+        );
+        expect(queuedCall).toBeDefined();
+
+        const fields = queuedCall?.[1]?.fields;
+        expect(typeof fields).toBe("function");
+
+        const summary = (
+          fields as () => {
+            hooks: Array<{ namespace: string; hookName: string; count: number }>;
+            total: number;
+          }
+        )();
+
+        expect(summary.hooks).toContainEqual({
+          namespace: TEST_NS,
+          hookName,
+          count: 1,
+        });
+        expect(summary.total).toBe(1);
+      } finally {
+        debugSpy.mockRestore();
+      }
+    });
   });
 
   describe("processHooks", () => {
@@ -216,6 +446,7 @@ describe("Hook System", () => {
         hooks,
         namespace,
         internalFragment,
+        handlerTx,
         defaultRetryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 3 }),
       });
 
@@ -241,6 +472,79 @@ describe("Hook System", () => {
       expect(result?.lastAttemptAt).toBeInstanceOf(Date);
     });
 
+    it("should surface conflicts when a hook mutates its own record", async () => {
+      const namespace = "test-claim-conflict";
+      let eventId!: FragnoId;
+
+      const hookFn = vi.fn(async (payload: { externalId: string; version: number }) => {
+        const conflictId = new FragnoId({
+          externalId: payload.externalId,
+          version: payload.version,
+        });
+        await internalFragment.inContext(async function () {
+          await this.handlerTx()
+            .mutate(({ forSchema }) => {
+              const uow = forSchema(internalSchema);
+              uow.update("fragno_hooks", conflictId, (b) => b.set({ status: "processing" }));
+            })
+            .execute();
+        });
+      });
+
+      const hooks: HooksMap = {
+        onConflict: hookFn,
+      };
+
+      await internalFragment.inContext(async function () {
+        const createdId = await this.handlerTx()
+          .mutate(({ forSchema }) => {
+            const uow = forSchema(internalSchema);
+            return uow.create("fragno_hooks", {
+              id: "hook-conflict-id",
+              namespace,
+              hookName: "onConflict",
+              payload: { externalId: "hook-conflict-id", version: 0 },
+              status: "pending",
+              attempts: 0,
+              maxAttempts: 5,
+              lastAttemptAt: null,
+              nextRetryAt: null,
+              error: null,
+              nonce: "test-nonce-conflict",
+            });
+          })
+          .execute();
+        eventId = createdId;
+      });
+
+      await expect(
+        processHooks({
+          hooks,
+          namespace,
+          internalFragment,
+          handlerTx,
+          defaultRetryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 3 }),
+        }),
+      ).rejects.toThrow(ConcurrencyConflictError);
+
+      expect(hookFn).toHaveBeenCalledOnce();
+      expect(hookFn).toHaveBeenCalledWith({
+        externalId: eventId.externalId,
+        version: eventId.version,
+      });
+
+      const event = await internalFragment.inContext(async function () {
+        return await this.handlerTx()
+          .withServiceCalls(
+            () => [internalFragment.services.hookService.getHookById(eventId)] as const,
+          )
+          .transform(({ serviceResult: [result] }) => result)
+          .execute();
+      });
+
+      expect(event?.status).toBe("processing");
+    });
+
     it("should mark failed hooks for retry", async () => {
       const namespace = "test-failure";
       const hookFn = vi.fn().mockRejectedValue(new Error("Hook failed"));
@@ -275,6 +579,7 @@ describe("Hook System", () => {
         hooks,
         namespace,
         internalFragment,
+        handlerTx,
         defaultRetryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 3 }),
       });
 
@@ -329,6 +634,7 @@ describe("Hook System", () => {
         hooks,
         namespace,
         internalFragment,
+        handlerTx,
         defaultRetryPolicy: new NoRetryPolicy(),
       });
 
@@ -379,6 +685,7 @@ describe("Hook System", () => {
         hooks,
         namespace,
         internalFragment,
+        handlerTx,
         defaultRetryPolicy: new NoRetryPolicy(),
       });
 
@@ -395,6 +702,68 @@ describe("Hook System", () => {
       expect(result?.error).toBe("Hook 'onMissing' not found in hooks map");
     });
 
+    it("should re-queue stuck processing hooks and call the handler", async () => {
+      const namespace = "test-stuck-processing";
+      const hookFn = vi.fn();
+      const hooks: HooksMap = {
+        onStuck: hookFn,
+      };
+      const onStuckProcessingHooks = vi.fn();
+
+      let eventId: FragnoId;
+
+      await internalFragment.inContext(async function () {
+        const createdId = await this.handlerTx()
+          .mutate(({ forSchema }) => {
+            const uow = forSchema(internalSchema);
+            return uow.create("fragno_hooks", {
+              namespace,
+              hookName: "onStuck",
+              payload: { ok: true },
+              status: "processing",
+              attempts: 0,
+              maxAttempts: 5,
+              lastAttemptAt: new Date(Date.now() - 20 * 60_000),
+              nextRetryAt: null,
+              error: null,
+              nonce: "test-nonce",
+            });
+          })
+          .execute();
+        eventId = createdId;
+      });
+
+      await processHooks({
+        hooks,
+        namespace,
+        internalFragment,
+        handlerTx,
+        stuckProcessingTimeoutMinutes: 1,
+        onStuckProcessingHooks,
+      });
+
+      expect(hookFn).toHaveBeenCalledOnce();
+      expect(onStuckProcessingHooks).toHaveBeenCalledOnce();
+      expect(onStuckProcessingHooks).toHaveBeenCalledWith(
+        expect.objectContaining({
+          namespace,
+          timeoutMinutes: 1,
+          events: [expect.objectContaining({ hookName: "onStuck" })],
+        }),
+      );
+
+      const result = await internalFragment.inContext(async function () {
+        return await this.handlerTx()
+          .withServiceCalls(
+            () => [internalFragment.services.hookService.getHookById(eventId)] as const,
+          )
+          .transform(({ serviceResult: [event] }) => event)
+          .execute();
+      });
+
+      expect(result?.status).toBe("completed");
+    });
+
     it("should process multiple hooks in parallel", async () => {
       const namespace = "test-parallel";
       const hook1 = vi.fn();
@@ -454,6 +823,7 @@ describe("Hook System", () => {
         hooks,
         namespace,
         internalFragment,
+        handlerTx,
         defaultRetryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 3 }),
       });
 
@@ -534,6 +904,7 @@ describe("Hook System", () => {
         hooks,
         namespace,
         internalFragment,
+        handlerTx,
         defaultRetryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 3 }),
       });
 
@@ -570,10 +941,60 @@ describe("Hook System", () => {
         hooks,
         namespace,
         internalFragment,
+        handlerTx,
         defaultRetryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 3 }),
       });
 
       expect(hookFn).not.toHaveBeenCalled();
     });
   });
+
+  describe("createDurableHooksRunner", () => {
+    it("should return the total processed count across queued reruns", async () => {
+      const namespace = "test-runner-queued";
+      let resolveHook!: () => void;
+      const hookDone = new Promise<void>((resolve) => {
+        resolveHook = resolve;
+      });
+      const hookFn = vi.fn(async () => {
+        await hookDone;
+      });
+
+      await internalFragment.inContext(async function () {
+        await this.handlerTx()
+          .mutate(({ forSchema }) => {
+            const uow = forSchema(internalSchema);
+            uow.create("fragno_hooks", {
+              namespace,
+              hookName: "onQueued",
+              payload: { ok: true },
+              status: "pending",
+              attempts: 0,
+              maxAttempts: 1,
+              lastAttemptAt: null,
+              nextRetryAt: null,
+              error: null,
+              nonce: "runner-queued-nonce",
+            });
+          })
+          .execute();
+      });
+
+      const runner = createDurableHooksRunner({
+        hooks: { onQueued: hookFn },
+        namespace,
+        internalFragment,
+        handlerTx,
+        defaultRetryPolicy: new NoRetryPolicy(),
+      });
+
+      const firstRun = runner.processDue();
+      const queuedRun = runner.processDue();
+      resolveHook();
+
+      await expect(firstRun).resolves.toBe(1);
+      await expect(queuedRun).resolves.toBe(1);
+      expect(hookFn).toHaveBeenCalledTimes(1);
+    });
+  });
 });