@fragno-dev/db 0.2.2 → 0.4.1

package/src/hooks/hooks.ts

@@ -1,8 +1,14 @@
+import type { InternalFragmentInstance } from "../fragments/internal-fragment";
+import { dbNow, isDbNow, type DbNow } from "../query/db-now";
+import type {
+  ExecuteTxOptions,
+  HandlerTxBuilder,
+} from "../query/unit-of-work/execute-unit-of-work";
 import type { RetryPolicy } from "../query/unit-of-work/retry-policy";
 import { ExponentialBackoffRetryPolicy } from "../query/unit-of-work/retry-policy";
 import type { IUnitOfWork } from "../query/unit-of-work/unit-of-work";
-import type { InternalFragmentInstance } from "../fragments/internal-fragment";
-import type { TxResult } from "../query/unit-of-work/execute-unit-of-work";
+import type { FragnoId } from "../schema/create";
+import { DurableHooksLogger, type DurableHooksLoggerConfig } from "./durable-hooks-logger";
 
 /**
  * Context available in hook functions via `this`.
@@ -14,8 +20,58 @@ export interface HookContext {
    * Use this for idempotency checks in your hook implementation.
    */
   idempotencyKey: string;
+  /**
+   * Hook event identifier (versioned FragnoId).
+   */
+  hookId: FragnoId;
+  /**
+   * Hook name for this event.
+   */
+  hookName: string;
+  /**
+   * Current status of the hook event.
+   */
+  status: HookStatus;
+  /**
+   * Attempt count for this hook event.
+   */
+  attempts: number;
+  /**
+   * Maximum attempts configured for this hook event.
+   */
+  maxAttempts: number;
+  /**
+   * Timestamp of the last attempt (if any).
+   */
+  lastAttemptAt: Date | null;
+  /**
+   * Next scheduled retry timestamp (if any).
+   */
+  nextRetryAt: Date | null;
+  /**
+   * When the hook event was created.
+   */
+  createdAt: Date;
+  /**
+   * Create a handler transaction builder to run atomic operations.
+   */
+  handlerTx: HookHandlerTx;
 }
 
+export const hookStatusValues = ["pending", "processing", "completed", "failed"] as const;
+
+export type HookStatus = (typeof hookStatusValues)[number];
+
+export const isHookStatus = (value: unknown): value is HookStatus =>
+  typeof value === "string" && hookStatusValues.includes(value as HookStatus);
+
+const assertHookStatus = (value: unknown): HookStatus => {
+  if (isHookStatus(value)) {
+    return value;
+  }
+  throw new Error(`Invalid hook status: ${String(value)}`);
+};
+
 /**
  * A hook function signature.
  * Hooks receive a typed payload and access context via `this`.
@@ -43,6 +99,16 @@ export interface TriggerHookOptions {
    * If not provided, uses the default retry policy.
    */
   retryPolicy?: RetryPolicy;
+  /**
+   * Optional hook event ID. When provided, the hook insert will fail if a hook
+   * with the same ID already exists.
+   */
+  id?: string | FragnoId;
+  /**
+   * Absolute time for the first attempt. If in the future, the hook is
+   * scheduled for that time; if in the past, it runs immediately.
+   */
+  processAt?: Date | DbNow;
 }
 
 /**
@@ -50,28 +116,153 @@ export interface TriggerHookOptions {
  * Stored in the Unit of Work before execution.
  */
 export interface TriggeredHook {
+  namespace: string;
   hookName: string;
   payload: unknown;
   options?: TriggerHookOptions;
 }
 
+export type HookNotifySource = "request" | "hook" | "alarm";
+
+export type HookNotifyContext = {
+  source: HookNotifySource;
+  route?: string | null;
+  waitUntil?: (promise: Promise<unknown>) => void;
+};
+
+export type HookNotifier = {
+  notify: (context: HookNotifyContext) => void | Promise<void>;
+};
+
+export type DurableHooksRunner = {
+  processDue: () => Promise<number>;
+  drain: () => Promise<void>;
+};
+
+/**
+ * @deprecated Use DurableHooksRunner.
+ */
+export type HookScheduler = {
+  schedule: () => Promise<number>;
+  drain: () => Promise<void>;
+};
+
 /**
  * Configuration for hook processing.
  */
-export interface HookProcessorConfig {
-  hooks: HooksMap;
+export interface HookProcessorConfig<THooks extends HooksMap = HooksMap> {
+  hooks?: THooks;
   namespace: string;
   internalFragment: InternalFragmentInstance;
+  handlerTx: HookHandlerTx;
+  /**
+   * Whether post-mutate notifications should auto-schedule processing.
+   * Defaults to true.
+   */
+  autoSchedule?: boolean;
+  /**
+   * Internal hook runner used to coordinate processing/drain.
+   */
+  runner?: DurableHooksRunner;
+  /**
+   * Post-commit durable hooks notifier.
+   */
+  notifier?: HookNotifier;
+  /**
+   * @deprecated Use `runner`.
+   */
+  scheduler?: HookScheduler;
   defaultRetryPolicy?: RetryPolicy;
+  /**
+   * Re-queue hooks that have been in `processing` for at least this many minutes.
+   * Use `false` to disable stuck-processing recovery entirely.
+   * Values <= 0 are treated as `false`.
+   *
+   * Default: 10 minutes.
+   */
+  stuckProcessingTimeoutMinutes?: StuckHookProcessingTimeoutMinutes;
+  /**
+   * Called when stuck processing hooks are detected and re-queued.
+   * Invoked after the hooks are moved back to `pending`.
+   */
+  onStuckProcessingHooks?: (info: StuckHookProcessingInfo) => void;
+}
+
+export type StuckHookProcessingTimeoutMinutes = number | false;
+
+export type StuckHookProcessingEvent = {
+  id: FragnoId;
+  hookName: string;
+  attempts: number;
+  maxAttempts: number;
+  lastAttemptAt: Date | null;
+  nextRetryAt: Date | null;
+};
+
+export type StuckHookProcessingInfo = {
+  namespace: string;
+  timeoutMinutes: number;
+  events: StuckHookProcessingEvent[];
+};
+
+export type DurableHooksProcessingOptions = {
+  /**
+   * Re-queue hooks that have been in `processing` for at least this many minutes.
+   * Use `false` to disable stuck-processing recovery entirely.
+   * Values <= 0 are treated as `false`.
+   *
+   * Default: 10 minutes.
+   */
+  stuckProcessingTimeoutMinutes?: StuckHookProcessingTimeoutMinutes;
+  /**
+   * Automatically schedule hook processing after successful mutations.
+   * Defaults to true. Set false to disable auto scheduling (manual drain only).
+   */
+  autoSchedule?: boolean;
+  /**
+   * Called when stuck processing hooks are detected and re-queued.
+   * Invoked after the hooks are moved back to `pending`.
+   */
+  onStuckProcessingHooks?: (info: StuckHookProcessingInfo) => void;
+  /**
+   * Durable hooks logging controls.
+   * Defaults: enabled=true, level="warn".
+   */
+  logging?: DurableHooksLoggerConfig;
+};
+
+export type HookHandlerTx = (
+  execOptions?: Omit<ExecuteTxOptions, "createUnitOfWork">,
+) => HandlerTxBuilder<readonly [], [], [], unknown, unknown, false, false, false, false, HooksMap>;
+
+const DEFAULT_STUCK_PROCESSING_TIMEOUT_MINUTES = 10;
+
+function resolveStuckProcessingTimeoutMinutes(
+  value: StuckHookProcessingTimeoutMinutes | undefined,
+): number | false {
+  if (value === false) {
+    return false;
+  }
+  if (typeof value === "number") {
+    return value > 0 ? value : false;
+  }
+  return DEFAULT_STUCK_PROCESSING_TIMEOUT_MINUTES;
 }
 
 /**
  * Add hook events as mutation operations to the UOW.
  * This should be called before executeMutations() so hook records are created
  * in the same transaction as the user's mutations.
+ *
+ * Each triggered hook carries its own namespace (set at trigger-time), so this
+ * function works regardless of which fragment's handler is executing. When a
+ * `config` is provided its `defaultRetryPolicy` is used as fallback.
  */
-export function prepareHookMutations(uow: IUnitOfWork, config: HookProcessorConfig): void {
-  const { namespace, internalFragment, defaultRetryPolicy } = config;
+export function prepareHookMutations(
+  uow: Pick<IUnitOfWork, "getTriggeredHooks" | "forSchema" | "idempotencyKey">,
+  internalFragment: InternalFragmentInstance,
+  defaultRetryPolicy?: RetryPolicy,
+): void {
   const retryPolicy = defaultRetryPolicy ?? new ExponentialBackoffRetryPolicy({ maxRetries: 5 });
 
   const triggeredHooks = uow.getTriggeredHooks();
@@ -80,24 +271,57 @@ export function prepareHookMutations(uow: IUnitOfWork, config: HookProcessorConf
     return;
   }
 
+  const primaryNamespace = triggeredHooks[0]?.namespace;
+  DurableHooksLogger.debug("Durable hooks queued", {
+    namespace: primaryNamespace,
+    fields: () => {
+      const hookSummary = new Map<string, { namespace: string; hookName: string; count: number }>();
+      for (const hook of triggeredHooks) {
+        const key = `${hook.namespace}:${hook.hookName}`;
+        const summary = hookSummary.get(key);
+        if (summary) {
+          summary.count += 1;
+          continue;
+        }
+        hookSummary.set(key, {
+          namespace: hook.namespace,
+          hookName: hook.hookName,
+          count: 1,
+        });
+      }
+      const hooks = Array.from(hookSummary.values());
+      return {
+        hooks,
+        total: triggeredHooks.length,
+      };
+    },
+  });
+
   const internalSchema = internalFragment.$internal.deps.schema;
   const internalUow = uow.forSchema(internalSchema);
 
   for (const hook of triggeredHooks) {
     const hookRetryPolicy = hook.options?.retryPolicy ?? retryPolicy;
     const maxAttempts = hookRetryPolicy.shouldRetry(4) ? 5 : 1;
-    internalUow.create("fragno_hooks", {
-      namespace,
+    const rawProcessAt = hook.options?.processAt ?? null;
+    const processAt: Date | DbNow | null =
+      rawProcessAt === null ? null : isDbNow(rawProcessAt) ? rawProcessAt : new Date(rawProcessAt);
+    const nextRetryAt = processAt ?? null;
+    const hookValues = {
+      ...(hook.options?.id !== undefined ? { id: hook.options.id } : {}),
+      namespace: hook.namespace,
       hookName: hook.hookName,
       payload: hook.payload,
       status: "pending",
       attempts: 0,
       maxAttempts,
       lastAttemptAt: null,
-      nextRetryAt: null,
+      nextRetryAt,
       error: null,
       nonce: uow.idempotencyKey,
-    });
+    };
+
+    internalUow.create("fragno_hooks", hookValues);
   }
 }
 
@@ -105,29 +329,117 @@ export function prepareHookMutations(uow: IUnitOfWork, config: HookProcessorConf
  * Process pending hook events after the transaction has committed.
  * This should be called in the onSuccess callback after executeMutations().
  */
-export async function processHooks(config: HookProcessorConfig): Promise<void> {
+export async function processHooks<THooks extends HooksMap>(
+  config: HookProcessorConfig<THooks>,
+): Promise<number> {
   const { hooks, namespace, internalFragment, defaultRetryPolicy } = config;
+  if (!hooks) {
+    throw new Error("Hook processor hooks not initialized.");
+  }
   const retryPolicy = defaultRetryPolicy ?? new ExponentialBackoffRetryPolicy({ maxRetries: 5 });
+  const stuckProcessingTimeoutMinutes = resolveStuckProcessingTimeoutMinutes(
+    config.stuckProcessingTimeoutMinutes,
+  );
+  const internalSchema = internalFragment.$internal.deps.schema;
+  const includeStuckProcessing = stuckProcessingTimeoutMinutes !== false;
+  const staleBefore = includeStuckProcessing
+    ? dbNow().plus({ minutes: -stuckProcessingTimeoutMinutes })
+    : null;
+  let claimedEvents: Array<{
+    id: FragnoId;
+    hookName: string;
+    payload: unknown;
+    status: HookStatus;
+    attempts: number;
+    maxAttempts: number;
+    idempotencyKey: string;
+    lastAttemptAt: Date | null;
+    nextRetryAt: Date | null;
+    createdAt: Date;
+  }> = [];
+  let stuckEvents: StuckHookProcessingEvent[] = [];
 
-  // Get pending events
-  const pendingEvents = await internalFragment.inContext(async function () {
+  const result = await internalFragment.inContext(async function () {
     return await this.handlerTx()
-      .withServiceCalls(
-        () => [internalFragment.services.hookService.getPendingHookEvents(namespace)] as const,
-      )
-      .transform(({ serviceResult: [events] }) => events)
+      .withServiceCalls(() => {
+        const pending = internalFragment.services.hookService.claimPendingHookEvents(namespace);
+        const stuck = includeStuckProcessing
+          ? internalFragment.services.hookService.claimStuckProcessingHookEvents(
+              namespace,
+              staleBefore!,
+            )
+          : undefined;
+        return [pending, stuck] as const;
+      })
+      .transform(({ serviceResult: [pendingEvents, stuckResult] }) => ({
+        pendingEvents,
+        stuckResult,
+      }))
       .execute();
   });
 
-  if (pendingEvents.length === 0) {
-    return;
+  const pendingCount = result.pendingEvents.length;
+  const stuckClaimedCount = result.stuckResult?.events.length ?? 0;
+  const stuckRequeuedCount = result.stuckResult?.stuckEvents.length ?? 0;
+  const staleBeforeApprox = includeStuckProcessing
+    ? new Date(Date.now() - stuckProcessingTimeoutMinutes * 60_000).toISOString()
+    : null;
+  DurableHooksLogger.debug("Durable hooks claimed", {
+    namespace,
+    fields: {
+      pending: pendingCount,
+      stuck: stuckClaimedCount,
+      requeued: stuckRequeuedCount,
+      includeStuckProcessing,
+      staleBeforeApprox,
+    },
+  });
+
+  claimedEvents = [...result.pendingEvents, ...(result.stuckResult?.events ?? [])].map((event) => ({
+    ...event,
+    status: assertHookStatus(event.status),
+  }));
+  stuckEvents = result.stuckResult?.stuckEvents ?? [];
+
+  if (includeStuckProcessing && stuckEvents.length > 0) {
+    try {
+      config.onStuckProcessingHooks?.({
+        namespace,
+        timeoutMinutes: stuckProcessingTimeoutMinutes,
+        events: stuckEvents,
+      });
+    } catch (error) {
+      DurableHooksLogger.error("Error calling onStuckProcessingHooks", {
+        namespace,
+        fields: {
+          error: DurableHooksLogger.toErrorMessage(error),
+        },
+      });
+    }
+  }
+
+  if (claimedEvents.length === 0) {
+    DurableHooksLogger.debug("Durable hooks idle", {
+      namespace,
+    });
+    return 0;
   }
 
   // Process events (async work outside transaction)
   const processedEvents = await Promise.allSettled(
-    pendingEvents.map(async (event) => {
+    claimedEvents.map(async (event) => {
       const hookFn = hooks[event.hookName];
       if (!hookFn) {
+        DurableHooksLogger.error("Hook missing", {
+          namespace,
+          fields: {
+            eventId: event.id,
+            hookName: event.hookName,
+            attempts: event.attempts,
+            maxAttempts: event.maxAttempts,
+            createdAt: event.createdAt.toISOString(),
+          },
+        });
         return {
           eventId: event.id,
           status: "failed" as const,
@@ -138,14 +450,56 @@ export async function processHooks(config: HookProcessorConfig): Promise<void> {
       }
 
       try {
-        const hookContext: HookContext = { idempotencyKey: event.idempotencyKey };
+        const startedAt = Date.now();
+        DurableHooksLogger.debug("Hook start", {
+          namespace,
+          fields: {
+            eventId: event.id,
+            hookName: event.hookName,
+            status: event.status,
+            attempts: event.attempts,
+            maxAttempts: event.maxAttempts,
+            createdAt: event.createdAt.toISOString(),
+            nextRetryAt: event.nextRetryAt ? event.nextRetryAt.toISOString() : null,
+            lastAttemptAt: event.lastAttemptAt ? event.lastAttemptAt.toISOString() : null,
+          },
+        });
+        const hookContext: HookContext = {
+          idempotencyKey: event.idempotencyKey,
+          hookId: event.id,
+          hookName: event.hookName,
+          status: event.status,
+          attempts: event.attempts,
+          maxAttempts: event.maxAttempts,
+          lastAttemptAt: event.lastAttemptAt,
+          nextRetryAt: event.nextRetryAt,
+          createdAt: event.createdAt,
+          handlerTx: config.handlerTx,
+        };
         await hookFn.call(hookContext, event.payload);
+        DurableHooksLogger.debug("Hook completed", {
+          namespace,
+          fields: {
+            eventId: event.id,
+            hookName: event.hookName,
+            ms: Date.now() - startedAt,
+          },
+        });
         return {
           eventId: event.id,
           status: "completed" as const,
         };
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
+        DurableHooksLogger.error("Hook failed", {
+          namespace,
+          fields: {
+            eventId: event.id.toJSON(),
+            hookName: event.hookName,
+            error: errorMessage,
+            idempotencyKey: event.idempotencyKey,
+          },
+        });
         return {
           eventId: event.id,
           status: "failed" as const,
@@ -160,31 +514,144 @@ export async function processHooks(config: HookProcessorConfig): Promise<void> {
   // Mark events as completed/failed
   await internalFragment.inContext(async function () {
     await this.handlerTx()
-      .withServiceCalls(() => {
-        const txResults: TxResult<void>[] = [];
+      .mutate(({ forSchema }) => {
+        const uow = forSchema(internalSchema);
+        const now = dbNow();
+
         for (const processedEvent of processedEvents) {
           if (processedEvent.status === "rejected") {
+            DurableHooksLogger.error("Hook processing promise rejected", {
+              namespace,
+              fields: {
+                error: DurableHooksLogger.toErrorMessage(processedEvent.reason),
+              },
+            });
             continue;
           }
 
           const { eventId, status } = processedEvent.value;
 
           if (status === "completed") {
-            txResults.push(internalFragment.services.hookService.markHookCompleted(eventId));
-          } else if (status === "failed") {
-            const { error, attempts } = processedEvent.value;
-            txResults.push(
-              internalFragment.services.hookService.markHookFailed(
-                eventId,
-                error,
-                attempts,
-                retryPolicy,
-              ),
+            uow.update("fragno_hooks", eventId, (b) =>
+              b.set({ status: "completed", lastAttemptAt: now }).check(),
+            );
+            continue;
+          }
+
+          const { error, attempts } = processedEvent.value;
+          const newAttempts = attempts + 1;
+          const shouldRetry = retryPolicy.shouldRetry(newAttempts - 1);
+
+          if (shouldRetry) {
+            const delayMs = retryPolicy.getDelayMs(newAttempts - 1);
+            const nextRetryAt = now.plus({ ms: delayMs });
+            uow.update("fragno_hooks", eventId, (b) =>
+              b
+                .set({
+                  status: "pending",
+                  attempts: newAttempts,
+                  lastAttemptAt: now,
+                  nextRetryAt,
+                  error,
+                })
+                .check(),
+            );
+          } else {
+            uow.update("fragno_hooks", eventId, (b) =>
+              b
+                .set({
+                  status: "failed",
+                  attempts: newAttempts,
+                  lastAttemptAt: now,
+                  error,
+                })
+                .check(),
             );
           }
         }
-        return txResults;
       })
       .execute();
   });
+
+  const processedCount = processedEvents.reduce(
+    (count, result) => count + (result.status === "fulfilled" ? 1 : 0),
+    0,
+  );
+
+  const failed = processedEvents
+    .filter((result) => result.status === "fulfilled" && result.value.status === "failed")
+    .map((result) => {
+      if (result.status !== "fulfilled") {
+        return null;
+      }
+      return {
+        eventId: result.value.eventId,
+        error: result.value.error ?? null,
+      };
+    })
+    .filter(Boolean);
+
+  DurableHooksLogger.debug("Durable hooks processed", {
+    namespace,
+    fields: {
+      processed: processedCount,
+      failed: failed.length,
+      failures: failed.length > 0 ? failed : null,
+    },
+  });
+
+  return processedCount;
+}
+
+export function createDurableHooksRunner(config: HookProcessorConfig): DurableHooksRunner {
+  let processing = false;
+  let queued = false;
+  let currentPromise: Promise<number> | null = null;
+
+  const processDue = async () => {
+    if (processing) {
+      queued = true;
+      return currentPromise ?? Promise.resolve(0);
+    }
+
+    processing = true;
+    currentPromise = (async () => {
+      let totalProcessed = 0;
+      try {
+        do {
+          queued = false;
+          totalProcessed += await processHooks(config);
+        } while (queued);
+        return totalProcessed;
+      } finally {
+        processing = false;
+        queued = false;
+        currentPromise = null;
+      }
+    })();
+
+    return currentPromise;
+  };
+
+  const drain = async () => {
+    while (true) {
+      const processed = await processDue();
+      if (processed === 0) {
+        return;
+      }
+    }
+  };
+
+  return { processDue, drain };
+}
+
+/**
+ * @deprecated Use createDurableHooksRunner.
+ */
+export function createHookScheduler(config: HookProcessorConfig): HookScheduler {
+  const runner = createDurableHooksRunner(config);
+  return {
+    schedule: () => runner.processDue(),
+    drain: () => runner.drain(),
+  };
 }

package/src/id.test.ts

@@ -0,0 +1,34 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createId, init } from "./id";
+
+const idPattern = /^[a-z][0-9a-z]*$/;
+
+const createCounter = (start = 0) => {
+  let value = start;
+  return () => value++;
+};
+
+describe("db id", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("re-exports the shared createId implementation", () => {
+    const id = createId();
+
+    expect(id).toHaveLength(24);
+    expect(id).toMatch(idPattern);
+  });
+
+  it("re-exports init for deterministic generators", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2020-01-01T00:00:00.000Z"));
+
+    const first = init({ random: () => 0, counter: createCounter(0), fingerprint: "fingerprint" });
+    const second = init({ random: () => 0, counter: createCounter(0), fingerprint: "fingerprint" });
+
+    expect(first()).toBe(second());
+  });
+});

package/src/id.ts

@@ -1,3 +1 @@
-import { createId } from "@paralleldrive/cuid2";
-
-export { createId };
+export { createId, init } from "@fragno-dev/core";