@fragno-dev/db 0.3.0 → 0.4.1

package/src/hooks/durable-hooks-runtime.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { DurableHooksLogger } from "./durable-hooks-logger";
+import {
+  getDurableHooksNotifierByNamespace,
+  getDurableHooksRuntimeByConfig,
+  getDurableHooksRuntimeByNamespace,
+  getDurableHooksRuntimeByToken,
+  registerDurableHooksRuntime,
+} from "./durable-hooks-runtime";
+import type { HookNotifier, HookProcessorConfig } from "./hooks";
+
+let namespaceCounter = 0;
+const defaultInternalFragment = {} as HookProcessorConfig["internalFragment"];
+
+function createConfig(
+  namespace: string,
+  notifier?: HookNotifier,
+  internalFragment: HookProcessorConfig["internalFragment"] = defaultInternalFragment,
+): HookProcessorConfig {
+  return {
+    namespace,
+    hooks: {},
+    notifier,
+    internalFragment,
+    handlerTx: (() => {
+      throw new Error("handlerTx should not be called in durable-hooks-runtime tests");
+    }) as HookProcessorConfig["handlerTx"],
+  };
+}
+
+describe("durable hooks runtime registry", () => {
+  it("returns the same token when registering the same config twice", () => {
+    const namespace = `runtime-same-config-${namespaceCounter++}`;
+    const config = createConfig(namespace);
+
+    const tokenA = registerDurableHooksRuntime(config);
+    const tokenB = registerDurableHooksRuntime(config);
+
+    expect(tokenA).toBe(tokenB);
+    expect(getDurableHooksRuntimeByToken(tokenA)?.config).toBe(config);
+    expect(getDurableHooksRuntimeByConfig(config)?.token).toBe(tokenA);
+  });
+
+  it("keeps the latest runtime for scoped namespace lookup and warns on duplicates", () => {
+    const warnSpy = vi.spyOn(DurableHooksLogger, "warn").mockImplementation(() => {});
+    const namespace = `runtime-duplicate-${namespaceCounter++}`;
+    const internalFragment = {} as HookProcessorConfig["internalFragment"];
+    const firstConfig = createConfig(namespace, undefined, internalFragment);
+    const notifier: HookNotifier = {
+      notify: vi.fn(),
+    };
+    const secondConfig = createConfig(namespace, notifier, internalFragment);
+
+    const firstToken = registerDurableHooksRuntime(firstConfig);
+    const secondToken = registerDurableHooksRuntime(secondConfig);
+
+    expect(firstToken).not.toBe(secondToken);
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(getDurableHooksRuntimeByNamespace(namespace, internalFragment)?.token).toBe(secondToken);
+    expect(getDurableHooksNotifierByNamespace(namespace, internalFragment)).toBe(notifier);
+
+    warnSpy.mockRestore();
+  });
+});

package/src/hooks/durable-hooks-runtime.ts

@@ -0,0 +1,81 @@
+import { DurableHooksLogger } from "./durable-hooks-logger";
+import type { HookProcessorConfig } from "./hooks";
+
+type DurableHooksRuntimeState = {
+  token: object;
+  config: HookProcessorConfig;
+  dispatcherRegistered: boolean;
+  dispatcherWarningEmitted: boolean;
+};
+
+const runtimeByToken = new WeakMap<object, DurableHooksRuntimeState>();
+const runtimeByConfig = new WeakMap<HookProcessorConfig, DurableHooksRuntimeState>();
+const runtimesByInternalFragment = new WeakMap<
+  HookProcessorConfig["internalFragment"],
+  Map<string, DurableHooksRuntimeState>
+>();
+
+function getNamespaceRuntimeMap(
+  internalFragment: HookProcessorConfig["internalFragment"],
+  createIfMissing = false,
+) {
+  const existing = runtimesByInternalFragment.get(internalFragment);
+  if (existing || !createIfMissing) {
+    return existing;
+  }
+  const created = new Map<string, DurableHooksRuntimeState>();
+  runtimesByInternalFragment.set(internalFragment, created);
+  return created;
+}
+
+export function registerDurableHooksRuntime(config: HookProcessorConfig): object {
+  const existing = runtimeByConfig.get(config);
+  if (existing) {
+    return existing.token;
+  }
+
+  const token = {};
+  const runtime: DurableHooksRuntimeState = {
+    token,
+    config,
+    dispatcherRegistered: false,
+    dispatcherWarningEmitted: false,
+  };
+
+  runtimeByToken.set(token, runtime);
+  runtimeByConfig.set(config, runtime);
+  const runtimeByNamespace = getNamespaceRuntimeMap(config.internalFragment, true);
+  const existingForNamespace = runtimeByNamespace?.get(config.namespace);
+  if (existingForNamespace && existingForNamespace.config !== config) {
+    DurableHooksLogger.warn("Durable hooks runtime already registered for namespace", {
+      namespace: config.namespace,
+    });
+  }
+  runtimeByNamespace?.set(config.namespace, runtime);
+
+  return token;
+}
+
+export function getDurableHooksRuntimeByToken(token: object): DurableHooksRuntimeState | undefined {
+  return runtimeByToken.get(token);
+}
+
+export function getDurableHooksRuntimeByConfig(
+  config: HookProcessorConfig,
+): DurableHooksRuntimeState | undefined {
+  return runtimeByConfig.get(config);
+}
+
+export function getDurableHooksRuntimeByNamespace(
+  namespace: string,
+  internalFragment: HookProcessorConfig["internalFragment"],
+): DurableHooksRuntimeState | undefined {
+  return getNamespaceRuntimeMap(internalFragment)?.get(namespace);
+}
+
+export function getDurableHooksNotifierByNamespace(
+  namespace: string,
+  internalFragment: HookProcessorConfig["internalFragment"],
+) {
+  return getNamespaceRuntimeMap(internalFragment)?.get(namespace)?.config.notifier;
+}

package/src/hooks/hooks.test.ts

@@ -1,20 +1,33 @@
+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 { 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 { FragnoId } from "../schema/create";
+import { DurableHooksLogger } from "./durable-hooks-logger";
 import {
   prepareHookMutations,
   processHooks,
+  createDurableHooksRunner,
   type HooksMap,
   type HookContext,
   type HookHandlerTx,
 } from "./hooks";
-import { internalFragmentDef, internalSchema } from "../fragments/internal-fragment";
-import type { FragnoPublicConfigWithDatabase } from "../db-fragment-definition-builder";
-import { SqlAdapter } from "../adapters/generic-sql/generic-sql-adapter";
-import { BetterSQLite3DriverConfig } from "../adapters/generic-sql/driver-config";
-import { ExponentialBackoffRetryPolicy, NoRetryPolicy } from "../query/unit-of-work/retry-policy";
-import type { FragnoId } from "../schema/create";
+
+const TEST_NS = "test";
+
+type OptionsWithAdapter = FragnoPublicConfigWithDatabase & {
+  databaseAdapter: SqlAdapter;
+};
 
 describe("Hook System", () => {
   const handlerTx = (() => {
@@ -24,8 +37,11 @@ describe("Hook System", () => {
   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 () => {
@@ -41,13 +57,13 @@ describe("Hook System", () => {
     });
 
     {
-      const migrations = adapter.prepareMigrations(internalSchema, null);
+      const migrations = adapter.prepareMigrations(internalSchema, TEST_NS);
       await migrations.executeWithDriver(adapter.driver, 0);
     }
 
-    const options: FragnoPublicConfigWithDatabase = {
+    const options: OptionsWithAdapter = {
       databaseAdapter: adapter,
-      databaseNamespace: null,
+      databaseNamespace: TEST_NS,
     };
 
     internalFragment = instantiateFragment(options);
@@ -58,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(),
       };
@@ -78,13 +97,11 @@ describe("Hook System", () => {
             uow.triggerHook("onTest", { data: "test" });
 
             // Prepare hook mutations
-            prepareHookMutations(uow, {
-              hooks,
-              namespace,
+            prepareHookMutations(
+              uow,
               internalFragment,
-              handlerTx,
-              defaultRetryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 5 }),
-            });
+              new ExponentialBackoffRetryPolicy({ maxRetries: 5 }),
+            );
           })
           .execute();
       });
@@ -97,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();
@@ -112,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(),
       };
@@ -125,13 +231,7 @@ describe("Hook System", () => {
 
             uow.triggerHook("onNoRetry", { data: "test" });
 
-            prepareHookMutations(uow, {
-              hooks,
-              namespace,
-              internalFragment,
-              handlerTx,
-              defaultRetryPolicy: new NoRetryPolicy(),
-            });
+            prepareHookMutations(uow, internalFragment, new NoRetryPolicy());
           })
           .execute();
       });
@@ -139,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();
@@ -150,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(),
       };
@@ -168,13 +267,11 @@ describe("Hook System", () => {
               },
             );
 
-            prepareHookMutations(uow, {
-              hooks,
-              namespace,
+            prepareHookMutations(
+              uow,
               internalFragment,
-              handlerTx,
-              defaultRetryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 10 }),
-            });
+              new ExponentialBackoffRetryPolicy({ maxRetries: 10 }),
+            );
           })
           .execute();
       });
@@ -182,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();
@@ -192,7 +289,6 @@ describe("Hook System", () => {
     });
 
     it("should set nextRetryAt when processAt is in the future", async () => {
-      const namespace = "test-process-at-future";
       const hooks: HooksMap = {
         onScheduled: vi.fn(),
       };
@@ -205,13 +301,11 @@ describe("Hook System", () => {
 
             uow.triggerHook("onScheduled", { data: "test" }, { processAt: futureTime });
 
-            prepareHookMutations(uow, {
-              hooks,
-              namespace,
+            prepareHookMutations(
+              uow,
               internalFragment,
-              handlerTx,
-              defaultRetryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 5 }),
-            });
+              new ExponentialBackoffRetryPolicy({ maxRetries: 5 }),
+            );
           })
           .execute();
       });
@@ -219,7 +313,7 @@ describe("Hook System", () => {
       const events = await internalFragment.inContext(async function () {
         return await this.handlerTx()
           .withServiceCalls(
-            () => [internalFragment.services.hookService.getHooksByNamespace(namespace)] as const,
+            () => [internalFragment.services.hookService.getHooksByNamespace(TEST_NS)] as const,
           )
           .transform(({ serviceResult: [result] }) => result)
           .execute();
@@ -231,7 +325,6 @@ describe("Hook System", () => {
     });
 
     it("should keep processAt in the past while remaining immediately eligible", async () => {
-      const namespace = "test-process-at-past";
       const hooks: HooksMap = {
         onImmediate: vi.fn(),
       };
@@ -244,13 +337,11 @@ describe("Hook System", () => {
 
             uow.triggerHook("onImmediate", { data: "test" }, { processAt: pastTime });
 
-            prepareHookMutations(uow, {
-              hooks,
-              namespace,
+            prepareHookMutations(
+              uow,
               internalFragment,
-              handlerTx,
-              defaultRetryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 5 }),
-            });
+              new ExponentialBackoffRetryPolicy({ maxRetries: 5 }),
+            );
           })
           .execute();
       });
@@ -258,7 +349,7 @@ describe("Hook System", () => {
       const events = await internalFragment.inContext(async function () {
         return await this.handlerTx()
           .withServiceCalls(
-            () => [internalFragment.services.hookService.getHooksByNamespace(namespace)] as const,
+            () => [internalFragment.services.hookService.getHooksByNamespace(TEST_NS)] as const,
           )
           .transform(({ serviceResult: [result] }) => result)
           .execute();
@@ -268,6 +359,54 @@ describe("Hook System", () => {
       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", () => {
@@ -333,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"));
@@ -736,4 +948,53 @@ describe("Hook System", () => {
       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);
+    });
+  });
 });