@fragno-dev/db 0.3.0 → 0.4.1

package/src/fragments/internal-fragment.ts

@@ -1,5 +1,6 @@
 import { FragmentDefinitionBuilder } from "@fragno-dev/core";
 import type { InstantiatedFragmentFromDefinition } from "@fragno-dev/core";
+
 import {
   DatabaseFragmentDefinitionBuilder,
   type DatabaseHandlerContext,
@@ -8,26 +9,94 @@ import {
   type FragnoPublicConfigWithDatabase,
   type ImplicitDatabaseDependencies,
 } from "../db-fragment-definition-builder";
-import { FragnoId } from "../schema/create";
+import { isHookStatus, type HookStatus } from "../hooks/hooks";
+import type { Cursor } from "../query/cursor";
+import { dbNow, type DbNow } from "../query/db-now";
 import type { RetryPolicy } from "../query/unit-of-work/retry-policy";
-import { dbNow } from "../query/db-now";
+import { FragnoId } from "../schema/create";
 import {
   internalSchema,
   SETTINGS_NAMESPACE,
   SETTINGS_TABLE_NAME,
 } from "./internal-fragment.schema";
 
-export {
-  internalSchema,
-  SETTINGS_NAMESPACE,
-  SETTINGS_TABLE_NAME,
-} from "./internal-fragment.schema";
+type AdapterRegistry = {
+  listSchemas: () => Array<{
+    name: string;
+    namespace: string | null;
+    version: number;
+    tables: string[];
+  }>;
+  listOutboxFragments: () => Array<{ name: string; mountRoute: string }>;
+  isOutboxEnabled: () => boolean;
+  resolveSyncCommand: (
+    fragmentName: string,
+    schemaName: string,
+    commandName: string,
+  ) => { command: unknown; namespace: string | null } | undefined;
+};
+
+export class SchemaRegistryCollisionError extends Error {
+  readonly code = "SCHEMA_REGISTRY_COLLISION" as const;
+  readonly namespaceKey: string;
+  readonly existing: { name: string; namespace: string | null };
+  readonly attempted: { name: string; namespace: string | null };
+
+  constructor({
+    namespaceKey,
+    existing,
+    attempted,
+  }: {
+    namespaceKey: string;
+    existing: { name: string; namespace: string | null };
+    attempted: { name: string; namespace: string | null };
+  }) {
+    super(
+      `Schema namespace "${namespaceKey}" is already owned by "${existing.name}" (${existing.namespace ?? "null"}).`,
+    );
+    this.name = "SchemaRegistryCollisionError";
+    this.namespaceKey = namespaceKey;
+    this.existing = existing;
+    this.attempted = attempted;
+  }
+}
+
+export type InternalFragmentConfig = {
+  registry?: AdapterRegistry;
+};
+
+export { internalSchema, SETTINGS_NAMESPACE, SETTINGS_TABLE_NAME };
+
+const INTERNAL_SCHEMA_MIN_VERSION = 4;
+if (internalSchema.version < INTERNAL_SCHEMA_MIN_VERSION) {
+  // Keep the internal schema version monotonic after removing fragno_db_schemas.
+  internalSchema.version = INTERNAL_SCHEMA_MIN_VERSION;
+}
+
+const describeHookStatusSource = (event: { id: FragnoId; hookName: string }) =>
+  `fragno_hooks id=${event.id} hook=${event.hookName}`;
+
+const coerceHookStatus = (status: string, context: string): HookStatus => {
+  if (isHookStatus(status)) {
+    return status;
+  }
+  throw new Error(`Invalid hook status from database (${context}): ${status}`);
+};
+
+const DEFAULT_HOOKS_PAGE_SIZE = 50;
+
+const resolveHookPageSize = (pageSize?: number): number => {
+  if (typeof pageSize !== "number" || !Number.isInteger(pageSize) || pageSize <= 0) {
+    return DEFAULT_HOOKS_PAGE_SIZE;
+  }
+  return pageSize;
+};
 
 // This uses DatabaseFragmentDefinitionBuilder directly
 // to avoid circular dependency (it doesn't need to link to itself)
 export const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(
   new FragmentDefinitionBuilder<
-    {},
+    InternalFragmentConfig,
     FragnoPublicConfigWithDatabase,
     ImplicitDatabaseDependencies<typeof internalSchema>,
     {},
@@ -40,14 +109,6 @@ export const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(
   >("$fragno-internal-fragment"),
   internalSchema,
 )
-  .providesBaseService(({ deps }) => ({
-    getDbNow: async () => {
-      if (deps.db.now) {
-        return deps.db.now();
-      }
-      return new Date();
-    },
-  }))
   .providesService("settingsService", ({ defineService }) => {
     return defineService({
       /**
@@ -93,6 +154,30 @@ export const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(
           .build();
       },
 
+      /**
+       * Set a setting value only if it does not already exist.
+       */
+      setIfMissing(namespace: string, key: string, value: string) {
+        const fullKey = `${namespace}.${key}`;
+        return this.serviceTx(internalSchema)
+          .retrieve((uow) =>
+            uow.findFirst(SETTINGS_TABLE_NAME, (b) =>
+              b.whereIndex("unique_key", (eb) => eb("key", "=", fullKey)),
+            ),
+          )
+          .transformRetrieve(([result]) => result)
+          .mutate(({ uow, retrieveResult }) => {
+            if (retrieveResult) {
+              return;
+            }
+            uow.create(SETTINGS_TABLE_NAME, {
+              key: fullKey,
+              value,
+            });
+          })
+          .build();
+      },
+
       /**
        * Delete a setting by ID.
        */
@@ -128,8 +213,12 @@ export const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(
               id: event.id,
               hookName: event.hookName,
               payload: event.payload as unknown,
+              status: coerceHookStatus(event.status, describeHookStatusSource(event)),
               attempts: event.attempts,
               maxAttempts: event.maxAttempts,
+              lastAttemptAt: event.lastAttemptAt,
+              nextRetryAt: event.nextRetryAt,
+              createdAt: event.createdAt,
               idempotencyKey: event.nonce,
             }));
           })
@@ -159,8 +248,12 @@ export const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(
               id: event.id,
               hookName: event.hookName,
               payload: event.payload,
+              status: coerceHookStatus(event.status, describeHookStatusSource(event)),
               attempts: event.attempts,
               maxAttempts: event.maxAttempts,
+              lastAttemptAt: event.lastAttemptAt,
+              nextRetryAt: event.nextRetryAt,
+              createdAt: event.createdAt,
               idempotencyKey: event.nonce,
             }));
           })
@@ -177,6 +270,7 @@ export const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(
           .transform(({ retrieveResult }) =>
             retrieveResult.map((event) => ({
               ...event,
+              status: "processing" as const,
               id: new FragnoId({
                 externalId: event.id.externalId,
                 internalId: event.id.internalId,
@@ -188,84 +282,68 @@ export const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(
       },
 
       /**
-       * Re-queue hook events that have been stuck in processing for too long.
+       * Claim stale processing hook events for processing.
+       * Returns ready events and marks them as processing in the same transaction.
        */
-      requeueStuckProcessingHooks(namespace: string, staleBefore: Date) {
+      claimStuckProcessingHookEvents(namespace: string, staleBefore: DbNow) {
+        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", "=", "processing")),
+              b.whereIndex("idx_namespace_status_last_attempt", (eb) =>
+                eb.and(
+                  eb("namespace", "=", namespace),
+                  eb("status", "=", "processing"),
+                  eb.or(eb.isNull("lastAttemptAt"), eb("lastAttemptAt", "<=", staleBefore)),
+                ),
               ),
             ),
           )
           .transformRetrieve(([events]) => {
-            const stuck = events.filter((event) => {
-              if (!event.lastAttemptAt) {
-                return true;
-              }
-              return event.lastAttemptAt <= staleBefore;
-            });
-
-            return stuck.map((event) => ({
+            return events.map((event) => ({
               id: event.id,
               hookName: event.hookName,
+              payload: event.payload as unknown,
+              status: coerceHookStatus(event.status, describeHookStatusSource(event)),
               attempts: event.attempts,
               maxAttempts: event.maxAttempts,
+              idempotencyKey: event.nonce,
               lastAttemptAt: event.lastAttemptAt,
               nextRetryAt: event.nextRetryAt,
+              createdAt: event.createdAt,
             }));
           })
           .mutate(({ uow, retrieveResult }) => {
+            if (retrieveResult.length === 0) {
+              return;
+            }
+
             for (const event of retrieveResult) {
               uow.update("fragno_hooks", event.id, (b) =>
-                b.set({ status: "pending", nextRetryAt: null }).check(),
+                b.set({ status: "processing", lastAttemptAt: now, 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;
+          .transform(({ retrieveResult }) => {
+            return {
+              events: retrieveResult.map((event) => ({
+                ...event,
+                id: new FragnoId({
+                  externalId: event.id.externalId,
+                  internalId: event.id.internalId,
+                  version: event.id.version + 1,
+                }),
+              })),
+              stuckEvents: retrieveResult.map((event) => ({
+                id: event.id,
+                hookName: event.hookName,
+                attempts: event.attempts,
+                maxAttempts: event.maxAttempts,
+                lastAttemptAt: event.lastAttemptAt,
+                nextRetryAt: event.nextRetryAt,
+              })),
+            };
           })
           .build();
       },
@@ -274,88 +352,97 @@ export const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(
        * 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;
+      getNextHookWakeAt(namespace: string, timeoutMinutes?: number | false) {
+        const timeoutMinutesValue =
+          typeof timeoutMinutes === "number" && timeoutMinutes > 0 ? timeoutMinutes : 0;
+        const includeProcessing = timeoutMinutesValue > 0;
+        const now = dbNow();
+        const timeoutMs = timeoutMinutesValue * 60_000;
+        // Sentinel to keep query shape stable when processing checks are disabled.
+        const processingStatus = includeProcessing ? "processing" : "__disabled__";
+        const staleBefore = now.plus({ minutes: -timeoutMinutesValue });
 
         return this.serviceTx(internalSchema)
           .retrieve((uow) =>
-            uow.find("fragno_hooks", (b) =>
-              b
-                .whereIndex("idx_namespace_status_retry", (eb) => {
-                  if (includeProcessing) {
-                    return eb.and(
+            uow
+              .forSchema(internalSchema)
+              .find("fragno_hooks", (b) =>
+                b
+                  .whereIndex("idx_namespace_status_retry", (eb) =>
+                    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"]),
-            ),
+                      eb("status", "=", "pending"),
+                      eb.or(eb.isNull("nextRetryAt"), eb("nextRetryAt", "<=", now)),
+                    ),
+                  )
+                  .pageSize(1),
+              )
+              .find("fragno_hooks", (b) =>
+                b
+                  .whereIndex("idx_namespace_status_retry", (eb) =>
+                    eb.and(
+                      eb("namespace", "=", namespace),
+                      eb("status", "=", "pending"),
+                      eb.isNotNull("nextRetryAt"),
+                      eb("nextRetryAt", ">", now),
+                    ),
+                  )
+                  .orderByIndex("idx_namespace_status_retry", "asc")
+                  .pageSize(1)
+                  .select(["nextRetryAt"]),
+              )
+              .find("fragno_hooks", (b) =>
+                b
+                  .whereIndex("idx_namespace_status_last_attempt", (eb) =>
+                    eb.and(
+                      eb("namespace", "=", namespace),
+                      eb("status", "=", processingStatus),
+                      eb.or(eb.isNull("lastAttemptAt"), eb("lastAttemptAt", "<=", staleBefore)),
+                    ),
+                  )
+                  .pageSize(1),
+              )
+              .find("fragno_hooks", (b) =>
+                b
+                  .whereIndex("idx_namespace_status_last_attempt", (eb) =>
+                    eb.and(
+                      eb("namespace", "=", namespace),
+                      eb("status", "=", processingStatus),
+                      eb.isNotNull("lastAttemptAt"),
+                      eb("lastAttemptAt", ">", staleBefore),
+                    ),
+                  )
+                  .orderByIndex("idx_namespace_status_last_attempt", "asc")
+                  .pageSize(1)
+                  .select(["lastAttemptAt"]),
+              ),
           )
-          .transformRetrieve(([events]) => {
-            if (events.length === 0) {
-              return null;
-            }
-
-            const nowMs = baseNow.getTime();
-            let earliestPendingAt: Date | null = null;
-            let earliestStaleAt: Date | null = null;
+          .transformRetrieve(
+            ([pendingImmediate, pendingNext, processingImmediate, processingNext]) => {
+              const hasProcessingImmediate = includeProcessing && processingImmediate.length > 0;
 
-            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 (pendingImmediate.length > 0 || hasProcessingImmediate) {
+                return new Date();
               }
 
-              if (!includeProcessing || event.status !== "processing") {
-                continue;
-              }
+              const pendingNextAt = pendingNext[0]?.nextRetryAt ?? null;
+              let processingNextAt: Date | null = null;
 
-              const lastAttemptAt = event.lastAttemptAt;
-              if (!lastAttemptAt) {
-                return baseNow;
+              if (includeProcessing) {
+                const lastAttemptAt = processingNext[0]?.lastAttemptAt;
+                if (lastAttemptAt) {
+                  processingNextAt = new Date(lastAttemptAt.getTime() + timeoutMs);
+                }
               }
 
-              const staleAtMs = lastAttemptAt.getTime() + timeoutMs;
-              if (staleAtMs <= nowMs) {
-                return baseNow;
+              if (!pendingNextAt) {
+                return processingNextAt ?? null;
               }
-
-              const staleAt = new Date(staleAtMs);
-              if (!earliestStaleAt || staleAt < earliestStaleAt) {
-                earliestStaleAt = staleAt;
+              if (!processingNextAt) {
+                return pendingNextAt;
               }
-            }
-
-            if (!earliestPendingAt) {
-              return earliestStaleAt ?? null;
-            }
-            if (!earliestStaleAt) {
-              return earliestPendingAt;
-            }
-            return earliestPendingAt <= earliestStaleAt ? earliestPendingAt : earliestStaleAt;
-          })
-          .build();
-      },
-
-      /**
-       * Mark a hook event as completed.
-       */
-      markHookCompleted(eventId: FragnoId) {
-        return this.serviceTx(internalSchema)
-          .mutate(({ uow }) =>
-            uow.update("fragno_hooks", eventId, (b) =>
-              b.set({ status: "completed", lastAttemptAt: dbNow() }).check(),
-            ),
+              return pendingNextAt <= processingNextAt ? pendingNextAt : processingNextAt;
+            },
           )
           .build();
       },
@@ -363,28 +450,22 @@ export const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(
       /**
        * Mark a hook event as failed and schedule next retry.
        */
-      markHookFailed(
-        eventId: FragnoId,
-        error: string,
-        attempts: number,
-        retryPolicy: RetryPolicy,
-        now?: Date,
-      ) {
+      markHookFailed(eventId: FragnoId, error: string, attempts: number, retryPolicy: RetryPolicy) {
         const newAttempts = attempts + 1;
         const shouldRetry = retryPolicy.shouldRetry(newAttempts - 1);
+        const now = dbNow();
 
         return this.serviceTx(internalSchema)
           .mutate(({ uow }) => {
             if (shouldRetry) {
               const delayMs = retryPolicy.getDelayMs(newAttempts - 1);
-              const baseNow = now ?? new Date();
-              const nextRetryAt = new Date(baseNow.getTime() + delayMs);
+              const nextRetryAt = now.plus({ ms: delayMs });
               uow.update("fragno_hooks", eventId, (b) =>
                 b
                   .set({
                     status: "pending",
                     attempts: newAttempts,
-                    lastAttemptAt: dbNow(),
+                    lastAttemptAt: now,
                     nextRetryAt,
                     error,
                   })
@@ -396,7 +477,7 @@ export const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(
                   .set({
                     status: "failed",
                     attempts: newAttempts,
-                    lastAttemptAt: dbNow(),
+                    lastAttemptAt: now,
                     error,
                   })
                   .check(),
@@ -429,7 +510,45 @@ export const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(
               b.whereIndex("primary", (eb) => eb("id", "=", eventId)),
             ),
           )
-          .transformRetrieve(([result]) => result ?? undefined)
+          .transformRetrieve(([result]) =>
+            result
+              ? {
+                  ...result,
+                  status: coerceHookStatus(result.status, describeHookStatusSource(result)),
+                }
+              : undefined,
+          )
+          .build();
+      },
+
+      /**
+       * Get hook events for a namespace in newest-first order with pagination.
+       */
+      getHooksByNamespacePage(
+        namespace: string,
+        options: { cursor?: Cursor | string; pageSize?: number } = {},
+      ) {
+        const pageSize = resolveHookPageSize(options.pageSize);
+
+        return this.serviceTx(internalSchema)
+          .retrieve((uow) =>
+            uow.findWithCursor("fragno_hooks", (b) => {
+              const query = b
+                .whereIndex("idx_namespace_created_at", (eb) => eb("namespace", "=", namespace))
+                .orderByIndex("idx_namespace_created_at", "desc")
+                .pageSize(pageSize);
+
+              return options.cursor ? query.after(options.cursor) : query;
+            }),
+          )
+          .transformRetrieve(([page]) => ({
+            items: page.items.map((event) => ({
+              ...event,
+              status: coerceHookStatus(event.status, describeHookStatusSource(event)),
+            })),
+            cursor: page.cursor,
+            hasNextPage: page.hasNextPage,
+          }))
           .build();
       },
 
@@ -443,7 +562,12 @@ export const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(
               b.whereIndex("idx_namespace_status_retry", (eb) => eb("namespace", "=", namespace)),
             ),
           )
-          .transformRetrieve(([events]) => events)
+          .transformRetrieve(([events]) =>
+            events.map((event) => ({
+              ...event,
+              status: coerceHookStatus(event.status, describeHookStatusSource(event)),
+            })),
+          )
           .build();
       },
     });