@fragno-dev/db 0.2.2 → 0.4.1

package/src/dispatchers/cloudflare-do/dispatcher.ts

@@ -0,0 +1,204 @@
+import { DurableHooksLogger } from "../../hooks/durable-hooks-logger";
+import type { DurableHooksProcessor } from "../../hooks/durable-hooks-processor";
+import type { HookNotifyContext, HookNotifySource } from "../../hooks/hooks";
+
+type AlarmStorage = {
+  setAlarm?: (timestamp: number | Date) => Promise<void>;
+  deleteAlarm?: () => Promise<void>;
+};
+
+export type DurableHooksDispatcherDurableObjectState = {
+  readonly storage: AlarmStorage;
+};
+
+export type DurableHooksDispatcherDurableObjectHandler = {
+  fetch?: (request: Request) => Promise<Response>;
+  notify?: (context: HookNotifyContext) => void | Promise<void>;
+  alarm?: () => Promise<void>;
+};
+
+export type DurableHooksDispatcherDurableObjectFactory<TEnv = unknown> = (
+  state: DurableHooksDispatcherDurableObjectState,
+  env: TEnv,
+) => DurableHooksDispatcherDurableObjectHandler;
+
+export type DurableHooksDispatcherDurableObjectOptions<TEnv = unknown> = {
+  createProcessor: (context: {
+    state: DurableHooksDispatcherDurableObjectState;
+    env: TEnv;
+  }) => DurableHooksProcessor;
+  onProcessError?: (error: unknown) => void;
+};
+
+export function createDurableHooksDispatcherDurableObject<TEnv>(
+  options: DurableHooksDispatcherDurableObjectOptions<TEnv>,
+): DurableHooksDispatcherDurableObjectFactory<TEnv> {
+  return (state, env) => {
+    const processor = options.createProcessor({ state, env });
+    const onProcessError =
+      options.onProcessError ??
+      ((error: unknown) => {
+        DurableHooksLogger.error("Durable hooks dispatcher error", {
+          namespace: processor.namespace,
+          fields: { error: DurableHooksLogger.toErrorMessage(error) },
+        });
+      });
+    const safeOnProcessError = (error: unknown) => {
+      void Promise.resolve()
+        .then(() => onProcessError(error))
+        .catch((callbackError) => {
+          DurableHooksLogger.error("Durable hooks dispatcher onProcessError callback failed", {
+            namespace: processor.namespace,
+            fields: { error: DurableHooksLogger.toErrorMessage(callbackError) },
+          });
+        });
+    };
+    const rawSetAlarm = state.storage.setAlarm;
+    const rawDeleteAlarm = state.storage.deleteAlarm;
+
+    if (!rawSetAlarm) {
+      throw new Error(
+        "Durable hooks dispatcher requires state.storage.setAlarm to schedule alarms.",
+      );
+    }
+    const setAlarm = rawSetAlarm.bind(state.storage);
+    const deleteAlarm = rawDeleteAlarm?.bind(state.storage);
+
+    let processing = false;
+    let queued = false;
+    let currentPromise: Promise<void> | undefined;
+    let alarmRefreshQueued = false;
+    let alarmRefreshPromise: Promise<void> | undefined;
+    let latestAlarmRefreshSource: HookNotifySource = "request";
+
+    const runProcess = () => {
+      if (processing) {
+        queued = true;
+        return currentPromise ?? Promise.resolve();
+      }
+
+      processing = true;
+      currentPromise = (async () => {
+        try {
+          do {
+            queued = false;
+            try {
+              const startedAt = Date.now();
+              DurableHooksLogger.debug("Durable hooks alarm start", {
+                namespace: processor.namespace,
+              });
+              const processed = await processor.processDue();
+              DurableHooksLogger.debug("Durable hooks alarm processed", {
+                namespace: processor.namespace,
+                fields: {
+                  processed,
+                  ms: Date.now() - startedAt,
+                },
+              });
+            } catch (error) {
+              DurableHooksLogger.error("Durable hooks alarm failed", {
+                namespace: processor.namespace,
+                fields: { error: DurableHooksLogger.toErrorMessage(error) },
+              });
+              safeOnProcessError(error);
+            }
+          } while (queued);
+        } finally {
+          processing = false;
+          currentPromise = undefined;
+        }
+      })();
+
+      return currentPromise;
+    };
+
+    const scheduleNextAlarm = async (source: HookNotifySource) => {
+      DurableHooksLogger.debug("Durable hooks alarm schedule requested", {
+        namespace: processor.namespace,
+        fields: {
+          source,
+        },
+      });
+      const nextWakeAt = await processor.getNextWakeAt();
+      if (!nextWakeAt) {
+        await deleteAlarm?.();
+        DurableHooksLogger.debug("Durable hooks alarm cleared", {
+          namespace: processor.namespace,
+          fields: {
+            source,
+          },
+        });
+        return;
+      }
+
+      const now = Date.now();
+      const scheduledAt = new Date(Math.max(nextWakeAt.getTime(), now));
+      await setAlarm(scheduledAt);
+      DurableHooksLogger.debug("Durable hooks alarm scheduled", {
+        namespace: processor.namespace,
+        fields: {
+          source,
+          nextWakeAt: nextWakeAt.toISOString(),
+          scheduledAt: scheduledAt.toISOString(),
+        },
+      });
+    };
+
+    const refreshAlarm = (source: HookNotifySource): Promise<void> => {
+      latestAlarmRefreshSource = source;
+      if (alarmRefreshPromise) {
+        alarmRefreshQueued = true;
+        return alarmRefreshPromise;
+      }
+
+      alarmRefreshPromise = (async () => {
+        do {
+          alarmRefreshQueued = false;
+          await scheduleNextAlarm(latestAlarmRefreshSource);
+        } while (alarmRefreshQueued);
+      })().finally(() => {
+        alarmRefreshPromise = undefined;
+      });
+
+      return alarmRefreshPromise;
+    };
+
+    DurableHooksLogger.debug("Durable hooks dispatcher init", {
+      namespace: processor.namespace,
+    });
+    void refreshAlarm("alarm").catch((error) => {
+      DurableHooksLogger.error("Durable hooks alarm schedule failed", {
+        namespace: processor.namespace,
+        fields: { error: DurableHooksLogger.toErrorMessage(error) },
+      });
+      safeOnProcessError(error);
+    });
+
+    return {
+      notify: (context) => {
+        const schedulePromise = refreshAlarm(context.source);
+        const handledPromise = schedulePromise.catch((error) => {
+          DurableHooksLogger.error("Durable hooks alarm schedule failed", {
+            namespace: processor.namespace,
+            fields: { error: DurableHooksLogger.toErrorMessage(error) },
+          });
+          safeOnProcessError(error);
+        });
+        if (context.waitUntil) {
+          context.waitUntil(handledPromise);
+        } else {
+          void handledPromise;
+        }
+        return handledPromise;
+      },
+      alarm: async () => {
+        try {
+          await runProcess();
+          await refreshAlarm("alarm");
+        } catch (error) {
+          safeOnProcessError(error);
+        }
+      },
+    };
+  };
+}

package/src/dispatchers/cloudflare-do/index.test.ts

@@ -0,0 +1,206 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { DurableHooksLogger } from "../../hooks/durable-hooks-logger";
+import { createDurableHooksDispatcherDurableObject } from "./dispatcher";
+
+describe("createDurableHooksDispatcherDurableObject", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  it("should schedule an initial alarm on creation", async () => {
+    const processDue = vi.fn().mockResolvedValue(0);
+    const getNextWakeAt = vi.fn().mockResolvedValue(new Date());
+    const drain = vi.fn().mockResolvedValue(undefined);
+    const setAlarm = vi.fn().mockResolvedValue(undefined);
+
+    const handlerFactory = createDurableHooksDispatcherDurableObject({
+      createProcessor: () => ({
+        processDue,
+        process: processDue,
+        getNextWakeAt,
+        drain,
+        namespace: "test",
+      }),
+    });
+
+    handlerFactory({ storage: { setAlarm } }, {});
+
+    await Promise.resolve();
+    expect(setAlarm).toHaveBeenCalledTimes(1);
+    expect(processDue).not.toHaveBeenCalled();
+  });
+
+  it("should delete the alarm when no pending hooks exist", async () => {
+    const processDue = vi.fn().mockResolvedValue(0);
+    const getNextWakeAt = vi.fn().mockResolvedValue(null);
+    const drain = vi.fn().mockResolvedValue(undefined);
+    const setAlarm = vi.fn().mockResolvedValue(undefined);
+    const deleteAlarm = vi.fn().mockResolvedValue(undefined);
+
+    const handlerFactory = createDurableHooksDispatcherDurableObject({
+      createProcessor: () => ({
+        processDue,
+        process: processDue,
+        getNextWakeAt,
+        drain,
+        namespace: "test",
+      }),
+    });
+
+    const handler = handlerFactory({ storage: { setAlarm, deleteAlarm } }, {});
+
+    await Promise.resolve();
+    expect(getNextWakeAt).toHaveBeenCalledTimes(1);
+
+    await handler.alarm?.();
+
+    expect(processDue).toHaveBeenCalledTimes(1);
+    expect(deleteAlarm).toHaveBeenCalledTimes(1);
+    expect(setAlarm).not.toHaveBeenCalled();
+  });
+
+  it("should schedule alarm on notify and forward promise to waitUntil", async () => {
+    const processDue = vi.fn().mockResolvedValue(0);
+    const getNextWakeAt = vi.fn().mockResolvedValue(new Date("2024-01-01T00:00:00Z"));
+    const drain = vi.fn().mockResolvedValue(undefined);
+    const setAlarm = vi.fn().mockResolvedValue(undefined);
+
+    const handlerFactory = createDurableHooksDispatcherDurableObject({
+      createProcessor: () => ({
+        processDue,
+        process: processDue,
+        getNextWakeAt,
+        drain,
+        namespace: "test",
+      }),
+    });
+
+    const handler = handlerFactory({ storage: { setAlarm } }, {});
+    await Promise.resolve();
+    expect(setAlarm).toHaveBeenCalledTimes(1);
+
+    const waitUntil = vi.fn();
+    handler.notify?.({ source: "request", waitUntil });
+
+    expect(waitUntil).toHaveBeenCalledTimes(1);
+    const [notifyPromise] = waitUntil.mock.calls[0] as [Promise<void>];
+    await notifyPromise;
+
+    expect(processDue).not.toHaveBeenCalled();
+    expect(setAlarm).toHaveBeenCalledTimes(2);
+  });
+
+  it("should schedule alarm using max(nextWakeAt, now)", async () => {
+    vi.useFakeTimers();
+    const now = new Date("2024-01-01T00:00:00Z");
+    vi.setSystemTime(now);
+
+    const processDue = vi.fn().mockResolvedValue(0);
+    const getNextWakeAt = vi.fn().mockResolvedValue(new Date(now.getTime() - 10000));
+    const drain = vi.fn().mockResolvedValue(undefined);
+    const setAlarm = vi.fn().mockResolvedValue(undefined);
+    const deleteAlarm = vi.fn().mockResolvedValue(undefined);
+
+    const handlerFactory = createDurableHooksDispatcherDurableObject({
+      createProcessor: () => ({
+        processDue,
+        process: processDue,
+        getNextWakeAt,
+        drain,
+        namespace: "test",
+      }),
+    });
+
+    const handler = handlerFactory({ storage: { setAlarm, deleteAlarm } }, {});
+
+    await Promise.resolve();
+    expect(setAlarm).toHaveBeenCalledTimes(1);
+
+    await handler.alarm?.();
+
+    expect(setAlarm.mock.calls.length).toBeGreaterThanOrEqual(1);
+    for (const [scheduledAt] of setAlarm.mock.calls) {
+      expect(scheduledAt.getTime()).toBeGreaterThanOrEqual(now.getTime());
+    }
+    vi.useRealTimers();
+  });
+
+  it("should recover alarm processing when onProcessError throws", async () => {
+    const processFailure = new Error("process failed");
+    const processDue = vi.fn().mockRejectedValueOnce(processFailure).mockResolvedValueOnce(0);
+    const getNextWakeAt = vi.fn().mockResolvedValue(new Date("2024-01-01T00:00:00Z"));
+    const drain = vi.fn().mockResolvedValue(undefined);
+    const setAlarm = vi.fn().mockResolvedValue(undefined);
+    const onProcessError = vi.fn(() => {
+      throw new Error("callback failed");
+    });
+    const errorSpy = vi.spyOn(DurableHooksLogger, "error").mockImplementation(() => {});
+
+    const handlerFactory = createDurableHooksDispatcherDurableObject({
+      createProcessor: () => ({
+        processDue,
+        process: processDue,
+        getNextWakeAt,
+        drain,
+        namespace: "test",
+      }),
+      onProcessError,
+    });
+
+    const handler = handlerFactory({ storage: { setAlarm } }, {});
+    await Promise.resolve();
+
+    await handler.alarm?.();
+    await handler.alarm?.();
+    await Promise.resolve();
+
+    expect(processDue).toHaveBeenCalledTimes(2);
+    expect(onProcessError).toHaveBeenCalledWith(processFailure);
+    expect(
+      errorSpy.mock.calls.some(
+        ([message]) => message === "Durable hooks dispatcher onProcessError callback failed",
+      ),
+    ).toBe(true);
+  });
+
+  it("should resolve notify when onProcessError throws in schedule error path", async () => {
+    const scheduleFailure = new Error("schedule failed");
+    const processDue = vi.fn().mockResolvedValue(0);
+    const getNextWakeAt = vi
+      .fn()
+      .mockResolvedValueOnce(new Date("2024-01-01T00:00:00Z"))
+      .mockRejectedValueOnce(scheduleFailure);
+    const drain = vi.fn().mockResolvedValue(undefined);
+    const setAlarm = vi.fn().mockResolvedValue(undefined);
+    const onProcessError = vi.fn(() => {
+      throw new Error("callback failed");
+    });
+    const errorSpy = vi.spyOn(DurableHooksLogger, "error").mockImplementation(() => {});
+
+    const handlerFactory = createDurableHooksDispatcherDurableObject({
+      createProcessor: () => ({
+        processDue,
+        process: processDue,
+        getNextWakeAt,
+        drain,
+        namespace: "test",
+      }),
+      onProcessError,
+    });
+
+    const handler = handlerFactory({ storage: { setAlarm } }, {});
+    await Promise.resolve();
+
+    await handler.notify?.({ source: "request" });
+    await Promise.resolve();
+
+    expect(onProcessError).toHaveBeenCalledWith(scheduleFailure);
+    expect(
+      errorSpy.mock.calls.some(
+        ([message]) => message === "Durable hooks dispatcher onProcessError callback failed",
+      ),
+    ).toBe(true);
+  });
+});

package/src/dispatchers/cloudflare-do/index.ts

@@ -0,0 +1,63 @@
+import { createDurableHooksProcessorGroup } from "../../hooks/durable-hooks-processor";
+import { getDurableHooksRuntimeByToken } from "../../hooks/durable-hooks-runtime";
+import type { AnyFragnoInstantiatedDatabaseFragment } from "../../mod";
+import {
+  createDurableHooksDispatcherDurableObject,
+  type DurableHooksDispatcherDurableObjectFactory,
+  type DurableHooksDispatcherDurableObjectHandler,
+  type DurableHooksDispatcherDurableObjectState,
+} from "./dispatcher";
+
+export type DurableHooksProcessorOptions = {
+  onProcessError?: (error: unknown) => void;
+};
+
+export type {
+  DurableHooksDispatcherDurableObjectFactory,
+  DurableHooksDispatcherDurableObjectHandler,
+  DurableHooksDispatcherDurableObjectState,
+};
+
+type DurableHooksInternal = {
+  durableHooksToken?: object;
+};
+
+export function createDurableHooksProcessor<TEnv>(
+  fragments: readonly AnyFragnoInstantiatedDatabaseFragment[],
+  options: DurableHooksProcessorOptions = {},
+): DurableHooksDispatcherDurableObjectFactory<TEnv> {
+  const processor = createDurableHooksProcessorGroup(fragments, {
+    onError: options.onProcessError,
+  });
+  const factory = createDurableHooksDispatcherDurableObject<TEnv>({
+    createProcessor: () => processor,
+    onProcessError: options.onProcessError,
+  });
+
+  return (state, env) => {
+    const handler = factory(state, env);
+    const notifier = {
+      notify: (context: Parameters<NonNullable<typeof handler.notify>>[0]) => {
+        if (!handler.notify) {
+          return;
+        }
+        return handler.notify(context);
+      },
+    };
+
+    for (const fragment of fragments) {
+      const internal = fragment.$internal as DurableHooksInternal | undefined;
+      const durableHooksToken = internal?.durableHooksToken;
+      if (!durableHooksToken) {
+        continue;
+      }
+      const runtime = getDurableHooksRuntimeByToken(durableHooksToken);
+      if (!runtime) {
+        continue;
+      }
+      runtime.config.notifier = notifier;
+    }
+
+    return handler;
+  };
+}

package/src/dispatchers/node/dispatcher.ts

@@ -0,0 +1,112 @@
+import { DurableHooksLogger } from "../../hooks/durable-hooks-logger";
+import type { DurableHooksProcessor } from "../../hooks/durable-hooks-processor";
+import type { HookNotifyContext } from "../../hooks/hooks";
+
+export type DurableHooksDispatcher = {
+  notify: (context: HookNotifyContext) => void;
+  wake: () => Promise<void>;
+  drain: () => Promise<void>;
+  startPolling: () => void;
+  stopPolling: () => void;
+};
+
+export type DurableHooksDispatcherOptions = {
+  processor: DurableHooksProcessor;
+  pollIntervalMs?: number;
+  onError?: (error: unknown) => void;
+};
+
+export function createDurableHooksDispatcher(
+  options: DurableHooksDispatcherOptions,
+): DurableHooksDispatcher {
+  const pollIntervalMs = options.pollIntervalMs ?? 5000;
+  const onError =
+    options.onError ??
+    ((error: unknown) => {
+      DurableHooksLogger.error("Durable hooks dispatcher error", {
+        namespace: options.processor.namespace,
+        fields: { error: DurableHooksLogger.toErrorMessage(error) },
+      });
+    });
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let processing = false;
+  let queued = false;
+  let notifyQueued = false;
+  let currentPromise: Promise<void> | undefined;
+
+  const runProcess = () => {
+    if (processing) {
+      queued = true;
+      return currentPromise ?? Promise.resolve();
+    }
+
+    processing = true;
+    currentPromise = (async () => {
+      do {
+        queued = false;
+        try {
+          await options.processor.processDue();
+        } catch (error) {
+          onError(error);
+        }
+      } while (queued);
+      processing = false;
+    })();
+
+    return currentPromise;
+  };
+
+  const poll = async () => {
+    try {
+      const nextWakeAt = await options.processor.getNextWakeAt();
+      if (!nextWakeAt) {
+        return;
+      }
+      if (Date.now() >= nextWakeAt.getTime()) {
+        await runProcess();
+      }
+    } catch (error) {
+      onError(error);
+    }
+  };
+
+  return {
+    notify: (_context) => {
+      if (notifyQueued) {
+        return;
+      }
+      notifyQueued = true;
+      setTimeout(() => {
+        notifyQueued = false;
+        void runProcess();
+      }, 0);
+    },
+    wake: async () => {
+      await runProcess();
+    },
+    drain: async () => {
+      try {
+        await options.processor.drain();
+      } catch (error) {
+        onError(error);
+      }
+    },
+    startPolling: () => {
+      if (timer) {
+        return;
+      }
+
+      timer = setInterval(() => {
+        void poll();
+      }, pollIntervalMs);
+    },
+    stopPolling: () => {
+      if (!timer) {
+        return;
+      }
+
+      clearInterval(timer);
+      timer = undefined;
+    },
+  };
+}

package/src/dispatchers/node/index.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createDurableHooksDispatcher } from "./dispatcher";
+
+describe("createDurableHooksDispatcher", () => {
+  it("should notify via macrotask wake hint", async () => {
+    vi.useFakeTimers();
+    try {
+      const processDue = vi.fn().mockResolvedValue(0);
+      const dispatcher = createDurableHooksDispatcher({
+        processor: {
+          processDue,
+          process: processDue,
+          getNextWakeAt: vi.fn().mockResolvedValue(null),
+          drain: vi.fn().mockResolvedValue(undefined),
+          namespace: "test",
+        },
+      });
+
+      dispatcher.notify({ source: "request" });
+      dispatcher.notify({ source: "request" });
+
+      expect(processDue).toHaveBeenCalledTimes(0);
+      await Promise.resolve();
+      expect(processDue).toHaveBeenCalledTimes(0);
+      await vi.advanceTimersByTimeAsync(0);
+      expect(processDue).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("should wake and process hooks", async () => {
+    const processDue = vi.fn().mockResolvedValue(0);
+    const getNextWakeAt = vi.fn().mockResolvedValue(null);
+    const drain = vi.fn().mockResolvedValue(undefined);
+
+    const dispatcher = createDurableHooksDispatcher({
+      processor: { processDue, process: processDue, getNextWakeAt, drain, namespace: "test" },
+    });
+
+    await dispatcher.wake();
+
+    expect(processDue).toHaveBeenCalledTimes(1);
+  });
+
+  it("should coalesce overlapping wake calls", async () => {
+    let resolveFirst!: (value: number) => void;
+    const firstPromise = new Promise<number>((resolve) => {
+      resolveFirst = resolve;
+    });
+    const processDue = vi.fn().mockReturnValueOnce(firstPromise).mockResolvedValue(0);
+    const drain = vi.fn().mockResolvedValue(undefined);
+
+    const dispatcher = createDurableHooksDispatcher({
+      processor: {
+        processDue,
+        process: processDue,
+        getNextWakeAt: vi.fn().mockResolvedValue(null),
+        drain,
+        namespace: "test",
+      },
+    });
+
+    const first = dispatcher.wake();
+    const second = dispatcher.wake();
+
+    expect(processDue).toHaveBeenCalledTimes(1);
+
+    resolveFirst(0);
+    await first;
+    await second;
+
+    expect(processDue).toHaveBeenCalledTimes(2);
+  });
+
+  it("should poll and process when due", async () => {
+    vi.useFakeTimers();
+    const now = new Date("2024-01-01T00:00:00Z");
+    vi.setSystemTime(now);
+
+    const processDue = vi.fn().mockResolvedValue(0);
+    const getNextWakeAt = vi.fn().mockResolvedValue(new Date(now.getTime() - 1000));
+    const drain = vi.fn().mockResolvedValue(undefined);
+
+    const dispatcher = createDurableHooksDispatcher({
+      processor: { processDue, process: processDue, getNextWakeAt, drain, namespace: "test" },
+      pollIntervalMs: 1000,
+    });
+
+    dispatcher.startPolling();
+    await vi.advanceTimersByTimeAsync(1000);
+    dispatcher.stopPolling();
+
+    expect(processDue).toHaveBeenCalledTimes(1);
+    vi.useRealTimers();
+  });
+
+  it("should skip polling when next wake is in the future", async () => {
+    vi.useFakeTimers();
+    const now = new Date("2024-01-01T00:00:00Z");
+    vi.setSystemTime(now);
+
+    const processDue = vi.fn().mockResolvedValue(0);
+    const getNextWakeAt = vi.fn().mockResolvedValue(new Date(now.getTime() + 60000));
+    const drain = vi.fn().mockResolvedValue(undefined);
+
+    const dispatcher = createDurableHooksDispatcher({
+      processor: { processDue, process: processDue, getNextWakeAt, drain, namespace: "test" },
+      pollIntervalMs: 1000,
+    });
+
+    dispatcher.startPolling();
+    await vi.advanceTimersByTimeAsync(1000);
+    dispatcher.stopPolling();
+
+    expect(processDue).not.toHaveBeenCalled();
+    vi.useRealTimers();
+  });
+});