@fragno-dev/db 0.2.2 → 0.4.1

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

@@ -0,0 +1,126 @@
+type LogFields = Record<string, unknown>;
+type LogFieldsInput = LogFields | (() => LogFields);
+
+type LogLevel = "debug" | "info" | "warn" | "error";
+const LOG_LEVEL_PRIORITY: Record<DurableHooksLogLevel, number> = {
+  off: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4,
+};
+
+const DEFAULT_SCOPE: Required<DurableHooksLoggerConfig> = {
+  enabled: true,
+  level: "warn",
+};
+
+export type DurableHooksLogLevel = "off" | "error" | "warn" | "info" | "debug";
+
+export type DurableHooksLoggerConfig = {
+  enabled?: boolean;
+  level?: DurableHooksLogLevel;
+};
+
+type LoggerScope = Required<DurableHooksLoggerConfig>;
+
+type LogOptions = {
+  namespace?: string;
+  fields?: LogFieldsInput;
+};
+
+export class DurableHooksLogger {
+  static #defaultScope: LoggerScope = { ...DEFAULT_SCOPE };
+  static #namespaceScopes = new Map<string, LoggerScope>();
+
+  static configure(config?: DurableHooksLoggerConfig, namespace?: string): void {
+    if (!config) {
+      return;
+    }
+
+    const target = namespace
+      ? (DurableHooksLogger.#namespaceScopes.get(namespace) ?? {
+          ...DurableHooksLogger.#defaultScope,
+        })
+      : { ...DurableHooksLogger.#defaultScope };
+
+    if (config.enabled !== undefined) {
+      target.enabled = config.enabled;
+    }
+    if (config.level !== undefined) {
+      target.level = config.level;
+    }
+
+    if (namespace) {
+      DurableHooksLogger.#namespaceScopes.set(namespace, target);
+      return;
+    }
+
+    DurableHooksLogger.#defaultScope = target;
+  }
+
+  static enable(namespace?: string): void {
+    DurableHooksLogger.configure({ enabled: true }, namespace);
+  }
+
+  static disable(namespace?: string): void {
+    DurableHooksLogger.configure({ enabled: false }, namespace);
+  }
+
+  static setLogLevel(level: DurableHooksLogLevel, namespace?: string): void {
+    DurableHooksLogger.configure({ level }, namespace);
+  }
+
+  static debug(message: string, options?: LogOptions): void {
+    DurableHooksLogger.#log("debug", message, options);
+  }
+
+  static info(message: string, options?: LogOptions): void {
+    DurableHooksLogger.#log("info", message, options);
+  }
+
+  static warn(message: string, options?: LogOptions): void {
+    DurableHooksLogger.#log("warn", message, options);
+  }
+
+  static error(message: string, options?: LogOptions): void {
+    DurableHooksLogger.#log("error", message, options);
+  }
+
+  static toErrorMessage(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+  }
+
+  static #log(level: LogLevel, message: string, options?: LogOptions): void {
+    const scope = DurableHooksLogger.#resolveScope(options?.namespace);
+    if (!scope.enabled) {
+      return;
+    }
+    if (LOG_LEVEL_PRIORITY[level] > LOG_LEVEL_PRIORITY[scope.level]) {
+      return;
+    }
+
+    const fields = DurableHooksLogger.#resolveFields(options?.fields);
+    const payload = {
+      at: new Date().toISOString(),
+      ...(options?.namespace ? { namespace: options.namespace } : {}),
+      ...fields,
+    };
+
+    console[level](`[fragno-db] ${message}`, payload);
+  }
+
+  static #resolveScope(namespace?: string): LoggerScope {
+    if (!namespace) {
+      return DurableHooksLogger.#defaultScope;
+    }
+    return DurableHooksLogger.#namespaceScopes.get(namespace) ?? DurableHooksLogger.#defaultScope;
+  }
+
+  static #resolveFields(fields?: LogFieldsInput): LogFields {
+    if (!fields) {
+      return {};
+    }
+    return typeof fields === "function" ? fields() : fields;
+  }
+}

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

@@ -0,0 +1,87 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { KyselyPGlite } from "kysely-pglite";
+
+import { defineFragment, instantiate } from "@fragno-dev/core";
+
+import { PGlite } from "@electric-sql/pglite";
+
+import { PGLiteDriverConfig } from "../adapters/generic-sql/driver-config";
+import { SqlAdapter } from "../adapters/generic-sql/generic-sql-adapter";
+import { internalSchema } from "../fragments/internal-fragment.schema";
+import { column, idColumn, schema } from "../schema/create";
+import { withDatabase } from "../with-database";
+import { createDurableHooksProcessor } from "./durable-hooks-processor";
+
+const testSchema = schema("hook_test", (s) =>
+  s.addTable("items", (t) => t.addColumn("id", idColumn()).addColumn("name", column("string"))),
+);
+
+async function createPgliteAdapter() {
+  const pglite = new PGlite();
+  const { dialect } = new KyselyPGlite(pglite);
+  const adapter = new SqlAdapter({
+    dialect,
+    driverConfig: new PGLiteDriverConfig(),
+  });
+
+  const internalMigrations = adapter.prepareMigrations(internalSchema, null);
+  await internalMigrations.executeWithDriver(adapter.driver, 0);
+
+  const testMigrations = adapter.prepareMigrations(testSchema, testSchema.name);
+  await testMigrations.executeWithDriver(adapter.driver, 0);
+
+  return {
+    adapter,
+    cleanup: async () => {
+      await adapter.close();
+    },
+  };
+}
+
+describe("durable hooks with pglite", () => {
+  it("keeps durable hooks processing after duplicate hook ids", async () => {
+    const hookFn = vi.fn();
+    const fragmentDefinition = defineFragment("hook-test")
+      .extend(withDatabase(testSchema))
+      .provideHooks(({ defineHook }) => ({
+        onTest: defineHook(async function (payload: { ok: boolean }) {
+          hookFn(payload.ok);
+        }),
+      }))
+      .build();
+
+    const { adapter, cleanup } = await createPgliteAdapter();
+
+    try {
+      const fragment = instantiate(fragmentDefinition)
+        .withConfig({})
+        .withRoutes([])
+        .withOptions({ databaseAdapter: adapter, durableHooks: { autoSchedule: false } })
+        .build();
+
+      const processor = createDurableHooksProcessor(fragment);
+      const hookId = "hook-id-duplicate";
+
+      const triggerHook = async () => {
+        await fragment.inContext(async function () {
+          await this.handlerTx()
+            .mutate(({ forSchema }) => {
+              const uow = forSchema(testSchema);
+              uow.triggerHook("onTest", { ok: true }, { id: hookId });
+            })
+            .execute();
+        });
+      };
+
+      await triggerHook();
+      await expect(triggerHook()).rejects.toThrow();
+
+      await processor.drain();
+
+      expect(hookFn).toHaveBeenCalledTimes(1);
+    } finally {
+      await cleanup();
+    }
+  }, 15000);
+});

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

@@ -0,0 +1,282 @@
+import { beforeAll, describe, expect, it, vi } from "vitest";
+
+import SQLite from "better-sqlite3";
+import { SqliteDialect } from "kysely";
+
+import { defineFragment, instantiate } from "@fragno-dev/core";
+
+import { BetterSQLite3DriverConfig } from "../adapters/generic-sql/driver-config";
+import { SqlAdapter } from "../adapters/generic-sql/generic-sql-adapter";
+import { internalSchema } from "../fragments/internal-fragment";
+import { getInternalFragment } from "../internal/adapter-registry";
+import type { TxResult } from "../query/unit-of-work/execute-unit-of-work";
+import { schema, column, idColumn } from "../schema/create";
+import { withDatabase } from "../with-database";
+import {
+  createDurableHooksProcessor,
+  createDurableHooksProcessorGroup,
+  createDurableHooksProcessorGroupFromProcessors,
+} from "./durable-hooks-processor";
+
+const testSchema = schema("test", (s) =>
+  s.addTable("items", (t) => t.addColumn("id", idColumn()).addColumn("name", column("string"))),
+);
+
+const boundServiceHookSpy = vi.fn<(count: number) => void>();
+let getItemCountService: (() => TxResult<number>) | undefined;
+
+const testFragmentDefinition = defineFragment("test")
+  .extend(withDatabase(testSchema))
+  .providesBaseService(({ defineService }) =>
+    defineService({
+      getItemCount() {
+        return this.serviceTx(testSchema)
+          .retrieve((uow) => uow.find("items", (b) => b.whereIndex("primary")))
+          .transformRetrieve(([items]) => items.length)
+          .build();
+      },
+    }),
+  )
+  .provideHooks(({ defineHook }) => ({
+    onTest: defineHook(async function () {}),
+    onTestUsesBoundService: defineHook(async function () {
+      const itemCount = await this.handlerTx()
+        .withServiceCalls(() => [getItemCountService!()] as const)
+        .transform(({ serviceResult: [count] }) => count)
+        .execute();
+
+      boundServiceHookSpy(itemCount);
+    }),
+  }))
+  .build();
+
+const noHooksFragmentDefinition = defineFragment("no-hooks")
+  .extend(withDatabase(testSchema))
+  .build();
+
+describe("createDurableHooksProcessor", () => {
+  let adapter: SqlAdapter;
+
+  function instantiateFragment(options: { databaseAdapter: SqlAdapter }) {
+    return instantiate(testFragmentDefinition).withConfig({}).withOptions(options).build();
+  }
+
+  let fragment: ReturnType<typeof instantiateFragment>;
+
+  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 });
+    getItemCountService = fragment.services.getItemCount;
+
+    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 = getInternalFragment(adapter);
+    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.processDue();
+    expect(processed).toBe(1);
+  });
+
+  it("should wake for stale processing hooks", async () => {
+    const processor = createDurableHooksProcessor(fragment);
+    expect(processor).not.toBeNull();
+
+    const internalFragment = getInternalFragment(adapter);
+    const baseNow = 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(Date.now());
+  });
+
+  it("allows bound fragment services to run inside durable hooks", async () => {
+    boundServiceHookSpy.mockReset();
+
+    await fragment.inContext(async function () {
+      await this.handlerTx()
+        .mutate(({ forSchema }) => {
+          const uow = forSchema(testSchema);
+          uow.create("items", {
+            name: "bound-service-item",
+          });
+          uow.triggerHook("onTestUsesBoundService", {});
+        })
+        .execute();
+    });
+
+    const processor = createDurableHooksProcessor(fragment);
+    await processor.drain();
+
+    expect(boundServiceHookSpy).toHaveBeenCalledOnce();
+    expect(boundServiceHookSpy).toHaveBeenCalledWith(1);
+  });
+
+  it("throws when fragment has no hooks configured", () => {
+    const noHooksFragment = instantiate(noHooksFragmentDefinition)
+      .withConfig({})
+      .withOptions({ databaseAdapter: adapter })
+      .build();
+
+    expect(() => createDurableHooksProcessor(noHooksFragment)).toThrow(
+      '[fragno-db] Durable hooks not configured for fragment "no-hooks".',
+    );
+  });
+
+  it("skips fragments without hooks when creating a group", () => {
+    const noHooksFragment = instantiate(noHooksFragmentDefinition)
+      .withConfig({})
+      .withOptions({ databaseAdapter: adapter })
+      .build();
+
+    const processor = createDurableHooksProcessorGroup([noHooksFragment, fragment]);
+    expect(processor).not.toBeNull();
+    expect(processor.namespace).toBe("test");
+  });
+});
+
+describe("createDurableHooksProcessorGroupFromProcessors", () => {
+  const makeProcessor = (overrides: Partial<ReturnType<typeof createProcessorStub>> = {}) => ({
+    ...createProcessorStub(),
+    ...overrides,
+  });
+
+  function createProcessorStub() {
+    const processDue = vi.fn().mockResolvedValue(0);
+    return {
+      namespace: "test",
+      processDue,
+      process: processDue,
+      getNextWakeAt: vi.fn().mockResolvedValue(null),
+      drain: vi.fn().mockResolvedValue(undefined),
+    };
+  }
+
+  it("returns null when there are no processors", () => {
+    expect(() => createDurableHooksProcessorGroupFromProcessors([])).toThrow(
+      "No processors provided for durable hooks processing.",
+    );
+  });
+
+  it("returns the same processor when only one is provided", () => {
+    const processor = makeProcessor({ namespace: "solo" });
+    const group = createDurableHooksProcessorGroupFromProcessors([processor]);
+    expect(group).toBe(processor);
+  });
+
+  it("aggregates processing results and reports errors", async () => {
+    const error = new Error("processor failed");
+    const onError = vi.fn();
+    const processorA = makeProcessor({
+      namespace: "a",
+      processDue: vi.fn().mockResolvedValue(2),
+      drain: vi.fn().mockResolvedValue(undefined),
+    });
+    const processorB = makeProcessor({
+      namespace: "b",
+      processDue: vi.fn().mockRejectedValue(error),
+      drain: vi.fn().mockRejectedValue(error),
+    });
+
+    const group = createDurableHooksProcessorGroupFromProcessors([processorA, processorB], {
+      onError,
+    });
+    expect(group).not.toBeNull();
+
+    const processed = await group.processDue();
+    expect(processed).toBe(2);
+    expect(onError).toHaveBeenCalledWith(error);
+
+    await group.drain();
+    expect(onError).toHaveBeenCalledTimes(2);
+  });
+
+  it("returns the earliest wake time and ignores failures", async () => {
+    const error = new Error("wake failed");
+    const onError = vi.fn();
+    const early = new Date("2024-01-01T00:00:00Z");
+    const late = new Date("2024-01-01T00:00:10Z");
+
+    const processorA = makeProcessor({
+      namespace: "a",
+      getNextWakeAt: vi.fn().mockResolvedValue(late),
+    });
+    const processorB = makeProcessor({
+      namespace: "b",
+      getNextWakeAt: vi.fn().mockResolvedValue(early),
+    });
+    const processorC = makeProcessor({
+      namespace: "c",
+      getNextWakeAt: vi.fn().mockRejectedValue(error),
+    });
+
+    const group = createDurableHooksProcessorGroupFromProcessors(
+      [processorA, processorB, processorC],
+      { onError },
+    );
+
+    const wakeAt = await group.getNextWakeAt();
+    expect(wakeAt).toEqual(early);
+    expect(onError).toHaveBeenCalledWith(error);
+  });
+});

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

@@ -0,0 +1,173 @@
+import type { AnyFragnoInstantiatedDatabaseFragment } from "../mod";
+import type { AnySchema } from "../schema/create";
+import { getDurableHooksRuntimeByToken } from "./durable-hooks-runtime";
+import { createDurableHooksRunner } from "./hooks";
+
+export type DurableHooksProcessor = {
+  processDue: () => Promise<number>;
+  /**
+   * @deprecated Use processDue().
+   */
+  process: () => Promise<number>;
+  getNextWakeAt: () => Promise<Date | null>;
+  drain: () => Promise<void>;
+  namespace: string;
+};
+
+export type DurableHooksProcessorGroupOptions = {
+  onError?: (error: unknown) => void;
+};
+
+type DurableHooksInternal = {
+  durableHooksToken?: object;
+};
+
+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;
+}
+
+function hasDurableHooksConfigured(
+  fragment: AnyFragnoInstantiatedDatabaseFragment,
+): fragment is AnyFragnoInstantiatedDatabaseFragment {
+  const internal = fragment.$internal as DurableHooksInternal | undefined;
+  return Boolean(internal?.durableHooksToken);
+}
+
+export function createDurableHooksProcessor<TSchema extends AnySchema>(
+  fragment: AnyFragnoInstantiatedDatabaseFragment<TSchema>,
+): DurableHooksProcessor {
+  const durableHooksToken = (fragment.$internal as DurableHooksInternal).durableHooksToken;
+  if (!durableHooksToken) {
+    throw new Error(`[fragno-db] Durable hooks not configured for fragment "${fragment.name}".`);
+  }
+  const runtime = getDurableHooksRuntimeByToken(durableHooksToken);
+  if (!runtime) {
+    throw new Error(`[fragno-db] Durable hooks runtime missing for fragment "${fragment.name}".`);
+  }
+  runtime.dispatcherRegistered = true;
+
+  const durableHooks = runtime.config;
+
+  const { namespace, internalFragment } = durableHooks;
+  const stuckProcessingTimeoutMinutes = resolveStuckProcessingTimeoutMinutes(
+    durableHooks.stuckProcessingTimeoutMinutes,
+  );
+  const runner =
+    durableHooks.runner ??
+    (durableHooks.runner = durableHooks.scheduler
+      ? {
+          processDue: () => durableHooks.scheduler!.schedule(),
+          drain: () => durableHooks.scheduler!.drain(),
+        }
+      : createDurableHooksRunner(durableHooks));
+
+  return {
+    namespace,
+    processDue: async () => runner.processDue(),
+    process: async () => runner.processDue(),
+    drain: async () => runner.drain(),
+    getNextWakeAt: async () => {
+      return await internalFragment.inContext(async function () {
+        return await this.handlerTx()
+          .withServiceCalls(
+            () =>
+              [
+                internalFragment.services.hookService.getNextHookWakeAt(
+                  namespace,
+                  stuckProcessingTimeoutMinutes,
+                ),
+              ] as const,
+          )
+          .transform(({ serviceResult: [result] }) => result)
+          .execute();
+      });
+    },
+  };
+}
+
+export function createDurableHooksProcessorGroup(
+  fragments: readonly AnyFragnoInstantiatedDatabaseFragment[],
+  options: DurableHooksProcessorGroupOptions = {},
+): DurableHooksProcessor {
+  const configuredFragments = fragments.filter(hasDurableHooksConfigured);
+  if (configuredFragments.length === 0) {
+    throw new Error("[fragno-db] No fragments provided for durable hooks processing.");
+  }
+  const processors = configuredFragments.map((fragment) => createDurableHooksProcessor(fragment));
+
+  return createDurableHooksProcessorGroupFromProcessors(processors, options);
+}
+
+export function createDurableHooksProcessorGroupFromProcessors(
+  processors: readonly DurableHooksProcessor[],
+  options: DurableHooksProcessorGroupOptions = {},
+): DurableHooksProcessor {
+  if (processors.length === 0) {
+    throw new Error("[fragno-db] No processors provided for durable hooks processing.");
+  }
+  if (processors.length === 1) {
+    return processors[0];
+  }
+
+  const onError = options.onError ?? (() => {});
+  const namespace = processors.map((processor) => processor.namespace).join(",");
+
+  const processDue = async () => {
+    const results = await Promise.allSettled(
+      processors.map(async (processor) => await processor.processDue()),
+    );
+    let processed = 0;
+    for (const result of results) {
+      if (result.status === "fulfilled") {
+        processed += result.value;
+      } else {
+        onError(result.reason);
+      }
+    }
+    return processed;
+  };
+
+  return {
+    namespace,
+    processDue,
+    process: processDue,
+    drain: async () => {
+      const results = await Promise.allSettled(
+        processors.map(async (processor) => await processor.drain()),
+      );
+      for (const result of results) {
+        if (result.status === "rejected") {
+          onError(result.reason);
+        }
+      }
+    },
+    getNextWakeAt: async () => {
+      const results = await Promise.allSettled(
+        processors.map(async (processor) => await processor.getNextWakeAt()),
+      );
+      let nextWakeAt: Date | null = null;
+      for (const result of results) {
+        if (result.status === "fulfilled") {
+          const wakeAt = result.value;
+          if (!wakeAt) {
+            continue;
+          }
+          if (!nextWakeAt || wakeAt.getTime() < nextWakeAt.getTime()) {
+            nextWakeAt = wakeAt;
+          }
+        } else {
+          onError(result.reason);
+        }
+      }
+      return nextWakeAt;
+    },
+  };
+}