@fragno-dev/db 0.2.2 → 0.3.0

package/src/fragments/internal-fragment.ts

@@ -8,45 +8,20 @@ import {
   type FragnoPublicConfigWithDatabase,
   type ImplicitDatabaseDependencies,
 } from "../db-fragment-definition-builder";
-import type { FragnoId } from "../schema/create";
-import { schema, idColumn, column } from "../schema/create";
+import { FragnoId } from "../schema/create";
 import type { RetryPolicy } from "../query/unit-of-work/retry-policy";
+import { dbNow } from "../query/db-now";
+import {
+  internalSchema,
+  SETTINGS_NAMESPACE,
+  SETTINGS_TABLE_NAME,
+} from "./internal-fragment.schema";
 
-// Constants for Fragno's internal settings table
-export const SETTINGS_TABLE_NAME = "fragno_db_settings" as const;
-// FIXME: In some places we simply use empty string "" as namespace, which is not correct.
-export const SETTINGS_NAMESPACE = "fragno-db-settings" as const;
-
-export const internalSchema = schema((s) => {
-  return s
-    .addTable(SETTINGS_TABLE_NAME, (t) => {
-      return t
-        .addColumn("id", idColumn())
-        .addColumn("key", column("string"))
-        .addColumn("value", column("string"))
-        .createIndex("unique_key", ["key"], { unique: true });
-    })
-    .addTable("fragno_hooks", (t) => {
-      return t
-        .addColumn("id", idColumn())
-        .addColumn("namespace", column("string"))
-        .addColumn("hookName", column("string"))
-        .addColumn("payload", column("json"))
-        .addColumn("status", column("string")) // "pending" | "processing" | "completed" | "failed"
-        .addColumn("attempts", column("integer").defaultTo(0))
-        .addColumn("maxAttempts", column("integer").defaultTo(5))
-        .addColumn("lastAttemptAt", column("timestamp").nullable())
-        .addColumn("nextRetryAt", column("timestamp").nullable())
-        .addColumn("error", column("string").nullable())
-        .addColumn(
-          "createdAt",
-          column("timestamp").defaultTo((b) => b.now()),
-        )
-        .addColumn("nonce", column("string"))
-        .createIndex("idx_namespace_status_retry", ["namespace", "status", "nextRetryAt"])
-        .createIndex("idx_nonce", ["nonce"]);
-    });
-});
+export {
+  internalSchema,
+  SETTINGS_NAMESPACE,
+  SETTINGS_TABLE_NAME,
+} from "./internal-fragment.schema";
 
 // This uses DatabaseFragmentDefinitionBuilder directly
 // to avoid circular dependency (it doesn't need to link to itself)
@@ -64,8 +39,15 @@ export const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(
     DatabaseRequestStorage
   >("$fragno-internal-fragment"),
   internalSchema,
-  "", // intentionally blank namespace so there is no prefix
 )
+  .providesBaseService(({ deps }) => ({
+    getDbNow: async () => {
+      if (deps.db.now) {
+        return deps.db.now();
+      }
+      return new Date();
+    },
+  }))
   .providesService("settingsService", ({ defineService }) => {
     return defineService({
       /**
@@ -128,33 +110,240 @@ export const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(
        * Returns all pending events for the given namespace that are ready to be processed.
        */
       getPendingHookEvents(namespace: string) {
+        const now = dbNow();
         return this.serviceTx(internalSchema)
           .retrieve((uow) =>
             uow.find("fragno_hooks", (b) =>
               b.whereIndex("idx_namespace_status_retry", (eb) =>
-                eb.and(eb("namespace", "=", namespace), eb("status", "=", "pending")),
+                eb.and(
+                  eb("namespace", "=", namespace),
+                  eb("status", "=", "pending"),
+                  eb.or(eb.isNull("nextRetryAt"), eb("nextRetryAt", "<=", now)),
+                ),
               ),
             ),
           )
           .transformRetrieve(([events]) => {
-            const now = new Date();
-            // FIXME(Wilco): this should be handled by the database query, but there seems to be an issue.
-            const ready = events.filter((event) => {
-              if (!event.nextRetryAt) {
-                return true; // Newly created events (nextRetryAt = null) are ready
+            return events.map((event) => ({
+              id: event.id,
+              hookName: event.hookName,
+              payload: event.payload as unknown,
+              attempts: event.attempts,
+              maxAttempts: event.maxAttempts,
+              idempotencyKey: event.nonce,
+            }));
+          })
+          .build();
+      },
+
+      /**
+       * Claim pending hook events for processing.
+       * Returns ready events and marks them as processing in the same transaction.
+       */
+      claimPendingHookEvents(namespace: string) {
+        const now = dbNow();
+        return this.serviceTx(internalSchema)
+          .retrieve((uow) =>
+            uow.find("fragno_hooks", (b) =>
+              b.whereIndex("idx_namespace_status_retry", (eb) =>
+                eb.and(
+                  eb("namespace", "=", namespace),
+                  eb("status", "=", "pending"),
+                  eb.or(eb.isNull("nextRetryAt"), eb("nextRetryAt", "<=", now)),
+                ),
+              ),
+            ),
+          )
+          .transformRetrieve(([events]) => {
+            return events.map((event) => ({
+              id: event.id,
+              hookName: event.hookName,
+              payload: event.payload,
+              attempts: event.attempts,
+              maxAttempts: event.maxAttempts,
+              idempotencyKey: event.nonce,
+            }));
+          })
+          .mutate(({ uow, retrieveResult }) => {
+            if (retrieveResult.length === 0) {
+              return;
+            }
+            for (const event of retrieveResult) {
+              uow.update("fragno_hooks", event.id, (b) =>
+                b.set({ status: "processing", lastAttemptAt: now }).check(),
+              );
+            }
+          })
+          .transform(({ retrieveResult }) =>
+            retrieveResult.map((event) => ({
+              ...event,
+              id: new FragnoId({
+                externalId: event.id.externalId,
+                internalId: event.id.internalId,
+                version: event.id.version + 1,
+              }),
+            })),
+          )
+          .build();
+      },
+
+      /**
+       * Re-queue hook events that have been stuck in processing for too long.
+       */
+      requeueStuckProcessingHooks(namespace: string, staleBefore: Date) {
+        return this.serviceTx(internalSchema)
+          .retrieve((uow) =>
+            uow.find("fragno_hooks", (b) =>
+              b.whereIndex("idx_namespace_status_retry", (eb) =>
+                eb.and(eb("namespace", "=", namespace), eb("status", "=", "processing")),
+              ),
+            ),
+          )
+          .transformRetrieve(([events]) => {
+            const stuck = events.filter((event) => {
+              if (!event.lastAttemptAt) {
+                return true;
               }
-              return event.nextRetryAt <= now; // Only include if retry time has passed
+              return event.lastAttemptAt <= staleBefore;
             });
 
-            return ready.map((event) => ({
+            return stuck.map((event) => ({
               id: event.id,
               hookName: event.hookName,
-              payload: event.payload as unknown,
               attempts: event.attempts,
               maxAttempts: event.maxAttempts,
-              idempotencyKey: event.nonce,
+              lastAttemptAt: event.lastAttemptAt,
+              nextRetryAt: event.nextRetryAt,
             }));
           })
+          .mutate(({ uow, retrieveResult }) => {
+            for (const event of retrieveResult) {
+              uow.update("fragno_hooks", event.id, (b) =>
+                b.set({ status: "pending", nextRetryAt: null }).check(),
+              );
+            }
+          })
+          .transform(({ retrieveResult }) => retrieveResult)
+          .build();
+      },
+
+      /**
+       * Get the next time a processing hook becomes stale.
+       */
+      getNextProcessingStaleAt(namespace: string, timeoutMinutes: number, now?: Date) {
+        return this.serviceTx(internalSchema)
+          .retrieve((uow) =>
+            uow.find("fragno_hooks", (b) =>
+              b.whereIndex("idx_namespace_status_retry", (eb) =>
+                eb.and(eb("namespace", "=", namespace), eb("status", "=", "processing")),
+              ),
+            ),
+          )
+          .transformRetrieve(([events]) => {
+            if (events.length === 0) {
+              return null;
+            }
+
+            const baseNow = now ?? new Date();
+            const nowMs = baseNow.getTime();
+            const timeoutMs = timeoutMinutes * 60_000;
+            let earliestStaleAt: Date | null = null;
+
+            for (const event of events) {
+              if (!event.lastAttemptAt) {
+                return baseNow;
+              }
+
+              const staleAtMs = event.lastAttemptAt.getTime() + timeoutMs;
+              if (staleAtMs <= nowMs) {
+                return baseNow;
+              }
+
+              const staleAt = new Date(staleAtMs);
+              if (!earliestStaleAt || staleAt < earliestStaleAt) {
+                earliestStaleAt = staleAt;
+              }
+            }
+
+            return earliestStaleAt;
+          })
+          .build();
+      },
+
+      /**
+       * Get the earliest pending hook wake time for a namespace.
+       * Optionally considers processing hooks becoming stale when timeoutMinutes is provided.
+       */
+      getNextHookWakeAt(namespace: string, timeoutMinutes?: number | false, now?: Date) {
+        const baseNow = now ?? new Date();
+        const includeProcessing = typeof timeoutMinutes === "number" && timeoutMinutes > 0;
+        const timeoutMs = includeProcessing ? timeoutMinutes * 60_000 : 0;
+
+        return this.serviceTx(internalSchema)
+          .retrieve((uow) =>
+            uow.find("fragno_hooks", (b) =>
+              b
+                .whereIndex("idx_namespace_status_retry", (eb) => {
+                  if (includeProcessing) {
+                    return eb.and(
+                      eb("namespace", "=", namespace),
+                      eb.or(eb("status", "=", "pending"), eb("status", "=", "processing")),
+                    );
+                  }
+                  return eb.and(eb("namespace", "=", namespace), eb("status", "=", "pending"));
+                })
+                .select(["status", "nextRetryAt", "lastAttemptAt"]),
+            ),
+          )
+          .transformRetrieve(([events]) => {
+            if (events.length === 0) {
+              return null;
+            }
+
+            const nowMs = baseNow.getTime();
+            let earliestPendingAt: Date | null = null;
+            let earliestStaleAt: Date | null = null;
+
+            for (const event of events) {
+              if (event.status === "pending") {
+                const nextRetryAt = event.nextRetryAt;
+                if (!nextRetryAt || nextRetryAt.getTime() <= nowMs) {
+                  return baseNow;
+                }
+                if (!earliestPendingAt || nextRetryAt < earliestPendingAt) {
+                  earliestPendingAt = nextRetryAt;
+                }
+                continue;
+              }
+
+              if (!includeProcessing || event.status !== "processing") {
+                continue;
+              }
+
+              const lastAttemptAt = event.lastAttemptAt;
+              if (!lastAttemptAt) {
+                return baseNow;
+              }
+
+              const staleAtMs = lastAttemptAt.getTime() + timeoutMs;
+              if (staleAtMs <= nowMs) {
+                return baseNow;
+              }
+
+              const staleAt = new Date(staleAtMs);
+              if (!earliestStaleAt || staleAt < earliestStaleAt) {
+                earliestStaleAt = staleAt;
+              }
+            }
+
+            if (!earliestPendingAt) {
+              return earliestStaleAt ?? null;
+            }
+            if (!earliestStaleAt) {
+              return earliestPendingAt;
+            }
+            return earliestPendingAt <= earliestStaleAt ? earliestPendingAt : earliestStaleAt;
+          })
           .build();
       },
 
@@ -165,7 +354,7 @@ export const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(
         return this.serviceTx(internalSchema)
           .mutate(({ uow }) =>
             uow.update("fragno_hooks", eventId, (b) =>
-              b.set({ status: "completed", lastAttemptAt: new Date() }).check(),
+              b.set({ status: "completed", lastAttemptAt: dbNow() }).check(),
             ),
           )
           .build();
@@ -174,7 +363,13 @@ export const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(
       /**
        * Mark a hook event as failed and schedule next retry.
        */
-      markHookFailed(eventId: FragnoId, error: string, attempts: number, retryPolicy: RetryPolicy) {
+      markHookFailed(
+        eventId: FragnoId,
+        error: string,
+        attempts: number,
+        retryPolicy: RetryPolicy,
+        now?: Date,
+      ) {
         const newAttempts = attempts + 1;
         const shouldRetry = retryPolicy.shouldRetry(newAttempts - 1);
 
@@ -182,13 +377,14 @@ export const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(
           .mutate(({ uow }) => {
             if (shouldRetry) {
               const delayMs = retryPolicy.getDelayMs(newAttempts - 1);
-              const nextRetryAt = new Date(Date.now() + delayMs);
+              const baseNow = now ?? new Date();
+              const nextRetryAt = new Date(baseNow.getTime() + delayMs);
               uow.update("fragno_hooks", eventId, (b) =>
                 b
                   .set({
                     status: "pending",
                     attempts: newAttempts,
-                    lastAttemptAt: new Date(),
+                    lastAttemptAt: dbNow(),
                     nextRetryAt,
                     error,
                   })
@@ -200,7 +396,7 @@ export const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(
                   .set({
                     status: "failed",
                     attempts: newAttempts,
-                    lastAttemptAt: new Date(),
+                    lastAttemptAt: dbNow(),
                     error,
                   })
                   .check(),
@@ -217,7 +413,7 @@ export const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(
         return this.serviceTx(internalSchema)
           .mutate(({ uow }) =>
             uow.update("fragno_hooks", eventId, (b) =>
-              b.set({ status: "processing", lastAttemptAt: new Date() }).check(),
+              b.set({ status: "processing", lastAttemptAt: dbNow() }).check(),
             ),
           )
           .build();
@@ -252,6 +448,44 @@ export const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(
       },
     });
   })
+  .providesService("outboxService", ({ defineService }) => {
+    return defineService({
+      /**
+       * List outbox entries ordered by versionstamp (ascending).
+       */
+      list({ afterVersionstamp, limit }: { afterVersionstamp?: string; limit?: number } = {}) {
+        const afterValue = afterVersionstamp?.toLowerCase();
+
+        return this.serviceTx(internalSchema)
+          .retrieve((uow) =>
+            uow.find("fragno_db_outbox", (b) => {
+              let builder = afterValue
+                ? b.whereIndex("idx_outbox_versionstamp", (eb) =>
+                    eb("versionstamp", ">", afterValue),
+                  )
+                : b.whereIndex("idx_outbox_versionstamp");
+
+              builder = builder.orderByIndex("idx_outbox_versionstamp", "asc");
+              if (limit !== undefined) {
+                builder = builder.pageSize(limit);
+              }
+              return builder;
+            }),
+          )
+          .transformRetrieve(([entries]) =>
+            entries.map((entry) => ({
+              id: entry.id,
+              versionstamp: entry.versionstamp,
+              uowId: entry.uowId,
+              payload: entry.payload,
+              refMap: entry.refMap ?? undefined,
+              createdAt: entry.createdAt,
+            })),
+          )
+          .build();
+      },
+    });
+  })
   .build();
 
 /**
@@ -267,15 +501,40 @@ export async function getSchemaVersionFromDatabase(
   namespace: string,
 ): Promise<number> {
   try {
-    const setting = await fragment.inContext(async function () {
-      return await this.handlerTx()
-        .withServiceCalls(
-          () => [fragment.services.settingsService.get(namespace, "schema_version")] as const,
-        )
-        .transform(({ serviceResult: [result] }) => result)
-        .execute();
-    });
-    return setting ? parseInt(setting.value, 10) : 0;
+    const readSchemaVersion = async (targetNamespace: string): Promise<number | undefined> => {
+      const setting = await fragment.inContext(async function () {
+        return await this.handlerTx()
+          .withServiceCalls(
+            () =>
+              [fragment.services.settingsService.get(targetNamespace, "schema_version")] as const,
+          )
+          .transform(({ serviceResult: [result] }) => result)
+          .execute();
+      });
+      if (!setting) {
+        return undefined;
+      }
+      const parsed = parseInt(setting.value, 10);
+      return Number.isNaN(parsed) ? undefined : parsed;
+    };
+
+    const primary = await readSchemaVersion(namespace);
+    if (primary !== undefined) {
+      return primary;
+    }
+
+    // Back-compat: some installs stored internal schema version under a different namespace.
+    // Check the alternate key (empty string ↔ schema name) so we find the version either way.
+    const legacyNamespace =
+      namespace === "" ? internalSchema.name : namespace === internalSchema.name ? "" : null;
+    if (legacyNamespace !== null) {
+      const legacy = await readSchemaVersion(legacyNamespace);
+      if (legacy !== undefined) {
+        return legacy;
+      }
+    }
+
+    return 0;
   } catch {
     return 0;
   }

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

@@ -0,0 +1,117 @@
+import SQLite from "better-sqlite3";
+import { SqliteDialect } from "kysely";
+import { beforeAll, describe, expect, it } from "vitest";
+import { defineFragment, instantiate } from "@fragno-dev/core";
+import { withDatabase } from "../with-database";
+import { schema, column, idColumn } from "../schema/create";
+import { SqlAdapter } from "../adapters/generic-sql/generic-sql-adapter";
+import { BetterSQLite3DriverConfig } from "../adapters/generic-sql/driver-config";
+import { internalSchema } from "../fragments/internal-fragment";
+import { createDurableHooksProcessor } from "./durable-hooks-processor";
+
+const testSchema = schema("test", (s) =>
+  s.addTable("items", (t) => t.addColumn("id", idColumn()).addColumn("name", column("string"))),
+);
+
+const testFragmentDefinition = defineFragment("test")
+  .extend(withDatabase(testSchema))
+  .provideHooks(({ defineHook }) => ({
+    onTest: defineHook(async function () {}),
+  }))
+  .build();
+
+describe("createDurableHooksProcessor", () => {
+  let adapter: SqlAdapter;
+  let fragment: ReturnType<typeof instantiateFragment>;
+
+  function instantiateFragment(options: { databaseAdapter: SqlAdapter }) {
+    return instantiate(testFragmentDefinition).withConfig({}).withOptions(options).build();
+  }
+
+  beforeAll(async () => {
+    const sqliteDatabase = new SQLite(":memory:");
+    const dialect = new SqliteDialect({ database: sqliteDatabase });
+
+    adapter = new SqlAdapter({
+      dialect,
+      driverConfig: new BetterSQLite3DriverConfig(),
+    });
+
+    const internalMigrations = adapter.prepareMigrations(internalSchema, null);
+    await internalMigrations.executeWithDriver(adapter.driver, 0);
+
+    const testMigrations = adapter.prepareMigrations(testSchema, "test");
+    await testMigrations.executeWithDriver(adapter.driver, 0);
+
+    fragment = instantiateFragment({ databaseAdapter: adapter });
+
+    return async () => {
+      await adapter.close();
+    };
+  }, 12000);
+
+  it("should process pending hooks and return counts", async () => {
+    const processor = createDurableHooksProcessor(fragment);
+    expect(processor).not.toBeNull();
+
+    const internalFragment = fragment.$internal.linkedFragments._fragno_internal;
+    await internalFragment.inContext(async function () {
+      await this.handlerTx()
+        .mutate(({ forSchema }) => {
+          const uow = forSchema(internalSchema);
+          uow.create("fragno_hooks", {
+            namespace: "test",
+            hookName: "onTest",
+            payload: { ok: true },
+            status: "pending",
+            attempts: 0,
+            maxAttempts: 1,
+            lastAttemptAt: null,
+            nextRetryAt: null,
+            error: null,
+            nonce: "test-nonce",
+          });
+        })
+        .execute();
+    });
+
+    const wakeAt = await processor!.getNextWakeAt();
+    expect(wakeAt).toBeInstanceOf(Date);
+
+    const processed = await processor!.process();
+    expect(processed).toBe(1);
+  });
+
+  it("should wake for stale processing hooks", async () => {
+    const processor = createDurableHooksProcessor(fragment);
+    expect(processor).not.toBeNull();
+
+    const internalFragment = fragment.$internal.linkedFragments._fragno_internal;
+    const services = internalFragment.services as { getDbNow?: () => Promise<Date> };
+    const baseNow = services.getDbNow ? await services.getDbNow() : new Date();
+
+    await internalFragment.inContext(async function () {
+      await this.handlerTx()
+        .mutate(({ forSchema }) => {
+          const uow = forSchema(internalSchema);
+          uow.create("fragno_hooks", {
+            namespace: "test",
+            hookName: "onTest",
+            payload: { ok: true },
+            status: "processing",
+            attempts: 0,
+            maxAttempts: 1,
+            lastAttemptAt: new Date(baseNow.getTime() - 20 * 60_000),
+            nextRetryAt: null,
+            error: null,
+            nonce: "test-nonce-stuck",
+          });
+        })
+        .execute();
+    });
+
+    const wakeAt = await processor!.getNextWakeAt();
+    expect(wakeAt).toBeInstanceOf(Date);
+    expect(wakeAt!.getTime()).toBeLessThanOrEqual(baseNow.getTime());
+  });
+});

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

@@ -0,0 +1,67 @@
+import type { AnySchema } from "../schema/create";
+import type { AnyFragnoInstantiatedDatabaseFragment } from "../mod";
+import { createHookScheduler, type HookProcessorConfig } from "./hooks";
+
+export type DurableHooksProcessor = {
+  process: () => Promise<number>;
+  getNextWakeAt: () => Promise<Date | null>;
+  drain: () => Promise<void>;
+  namespace: string;
+};
+
+type DurableHooksInternal = {
+  durableHooks?: HookProcessorConfig;
+};
+
+const DEFAULT_STUCK_PROCESSING_TIMEOUT_MINUTES = 10;
+
+function resolveStuckProcessingTimeoutMinutes(value: number | false | undefined): number | false {
+  if (value === false) {
+    return false;
+  }
+  if (typeof value === "number") {
+    return value > 0 ? value : false;
+  }
+  return DEFAULT_STUCK_PROCESSING_TIMEOUT_MINUTES;
+}
+
+export function createDurableHooksProcessor<TSchema extends AnySchema>(
+  fragment: AnyFragnoInstantiatedDatabaseFragment<TSchema>,
+): DurableHooksProcessor | null {
+  const durableHooks = (fragment.$internal as DurableHooksInternal).durableHooks;
+  if (!durableHooks) {
+    return null;
+  }
+
+  const { namespace, internalFragment } = durableHooks;
+  const stuckProcessingTimeoutMinutes = resolveStuckProcessingTimeoutMinutes(
+    durableHooks.stuckProcessingTimeoutMinutes,
+  );
+  const scheduler =
+    durableHooks.scheduler ?? (durableHooks.scheduler = createHookScheduler(durableHooks));
+
+  return {
+    namespace,
+    process: async () => scheduler.schedule(),
+    drain: async () => scheduler.drain(),
+    getNextWakeAt: async () => {
+      const services = internalFragment.services as { getDbNow?: () => Promise<Date> };
+      const now = services.getDbNow ? await services.getDbNow() : new Date();
+      return await internalFragment.inContext(async function () {
+        return await this.handlerTx()
+          .withServiceCalls(
+            () =>
+              [
+                internalFragment.services.hookService.getNextHookWakeAt(
+                  namespace,
+                  stuckProcessingTimeoutMinutes,
+                  now,
+                ),
+              ] as const,
+          )
+          .transform(({ serviceResult: [result] }) => result)
+          .execute();
+      });
+    },
+  };
+}