@fragno-dev/db 0.2.1 → 0.3.0

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

@@ -0,0 +1,104 @@
+import type { DurableHooksProcessor } from "../../hooks/durable-hooks-processor";
+
+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>;
+  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) => {
+        console.error("Durable hooks dispatcher error", error);
+      });
+    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;
+
+    const runProcess = () => {
+      if (processing) {
+        queued = true;
+        return currentPromise ?? Promise.resolve();
+      }
+
+      processing = true;
+      currentPromise = (async () => {
+        do {
+          queued = false;
+          try {
+            await processor.process();
+          } catch (error) {
+            onProcessError(error);
+          }
+        } while (queued);
+        processing = false;
+      })();
+
+      return currentPromise;
+    };
+
+    const scheduleNextAlarm = async () => {
+      const nextWakeAt = await processor.getNextWakeAt();
+      if (!nextWakeAt) {
+        await deleteAlarm?.();
+        return;
+      }
+
+      const now = Date.now();
+      const scheduledAt = new Date(Math.max(nextWakeAt.getTime(), now));
+      await setAlarm(scheduledAt);
+    };
+
+    void scheduleNextAlarm().catch((error) => {
+      onProcessError(error);
+    });
+
+    return {
+      alarm: async () => {
+        try {
+          await runProcess();
+          await scheduleNextAlarm();
+        } catch (error) {
+          onProcessError(error);
+        }
+      },
+    };
+  };
+}

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

@@ -0,0 +1,91 @@
+import { describe, expect, it, vi } from "vitest";
+import { createDurableHooksDispatcher } from "./index";
+
+describe("createDurableHooksDispatcher", () => {
+  it("should wake and process hooks", async () => {
+    const process = vi.fn().mockResolvedValue(0);
+    const getNextWakeAt = vi.fn().mockResolvedValue(null);
+    const drain = vi.fn().mockResolvedValue(undefined);
+
+    const dispatcher = createDurableHooksDispatcher({
+      processor: { process, getNextWakeAt, drain, namespace: "test" },
+    });
+
+    await dispatcher.wake();
+
+    expect(process).toHaveBeenCalledTimes(1);
+  });
+
+  it("should coalesce overlapping wake calls", async () => {
+    let resolveFirst!: (value: number) => void;
+    const firstPromise = new Promise<number>((resolve) => {
+      resolveFirst = resolve;
+    });
+    const process = vi.fn().mockReturnValueOnce(firstPromise).mockResolvedValue(0);
+    const drain = vi.fn().mockResolvedValue(undefined);
+
+    const dispatcher = createDurableHooksDispatcher({
+      processor: {
+        process,
+        getNextWakeAt: vi.fn().mockResolvedValue(null),
+        drain,
+        namespace: "test",
+      },
+    });
+
+    const first = dispatcher.wake();
+    const second = dispatcher.wake();
+
+    expect(process).toHaveBeenCalledTimes(1);
+
+    resolveFirst(0);
+    await first;
+    await second;
+
+    expect(process).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 process = vi.fn().mockResolvedValue(0);
+    const getNextWakeAt = vi.fn().mockResolvedValue(new Date(now.getTime() - 1000));
+    const drain = vi.fn().mockResolvedValue(undefined);
+
+    const dispatcher = createDurableHooksDispatcher({
+      processor: { process, getNextWakeAt, drain, namespace: "test" },
+      pollIntervalMs: 1000,
+    });
+
+    dispatcher.startPolling();
+    await vi.advanceTimersByTimeAsync(1000);
+    dispatcher.stopPolling();
+
+    expect(process).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 process = vi.fn().mockResolvedValue(0);
+    const getNextWakeAt = vi.fn().mockResolvedValue(new Date(now.getTime() + 60000));
+    const drain = vi.fn().mockResolvedValue(undefined);
+
+    const dispatcher = createDurableHooksDispatcher({
+      processor: { process, getNextWakeAt, drain, namespace: "test" },
+      pollIntervalMs: 1000,
+    });
+
+    dispatcher.startPolling();
+    await vi.advanceTimersByTimeAsync(1000);
+    dispatcher.stopPolling();
+
+    expect(process).not.toHaveBeenCalled();
+    vi.useRealTimers();
+  });
+});

package/src/dispatchers/node/index.ts

@@ -0,0 +1,87 @@
+import type { DurableHooksProcessor } from "../../hooks/durable-hooks-processor";
+
+export type DurableHooksDispatcher = {
+  wake: () => 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) => {
+      console.error("Durable hooks dispatcher error", error);
+    });
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let processing = false;
+  let queued = 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.process();
+        } 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 {
+    wake: async () => {
+      await runProcess();
+    },
+    startPolling: () => {
+      if (timer) {
+        return;
+      }
+
+      timer = setInterval(() => {
+        void poll();
+      }, pollIntervalMs);
+    },
+    stopPolling: () => {
+      if (!timer) {
+        return;
+      }
+
+      clearInterval(timer);
+      timer = undefined;
+    },
+  };
+}

package/src/fragments/internal-fragment.routes.ts

@@ -0,0 +1,42 @@
+import { defineRoutes } from "@fragno-dev/core";
+import { internalFragmentDef } from "./internal-fragment";
+
+export const internalFragmentRoutes = defineRoutes(internalFragmentDef).create(
+  ({ defineRoute, services }) => [
+    defineRoute({
+      method: "GET",
+      path: "/outbox",
+      handler: async function (input, { json }) {
+        // We intentionally skip input/output schemas here to keep the internal route lightweight.
+        // Query params are validated manually and the response shape is stable (OutboxEntry[]),
+        // while the public API surface is still gated behind adapter config.
+        const afterVersionstamp = input.query.get("afterVersionstamp") ?? undefined;
+        const limitValue = input.query.get("limit");
+        let limit: number | undefined;
+
+        if (limitValue !== null) {
+          const parsed = Number.parseInt(limitValue, 10);
+          if (!Number.isFinite(parsed) || parsed < 1) {
+            return json(
+              {
+                error: "Invalid limit query parameter.",
+                code: "INVALID_LIMIT",
+              },
+              { status: 400 },
+            );
+          }
+          limit = parsed;
+        }
+
+        const entries = await this.handlerTx()
+          .withServiceCalls(
+            () => [services.outboxService.list({ afterVersionstamp, limit })] as const,
+          )
+          .transform(({ serviceResult: [result] }) => result)
+          .execute();
+
+        return json(entries);
+      },
+    }),
+  ],
+);

package/src/fragments/internal-fragment.schema.ts

@@ -0,0 +1,51 @@
+import { schema, idColumn, column } from "../schema/create";
+
+// 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("fragno_internal", (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"]);
+    })
+    .addTable("fragno_db_outbox", (t) => {
+      return t
+        .addColumn("id", idColumn())
+        .addColumn("versionstamp", column("string"))
+        .addColumn("uowId", column("string"))
+        .addColumn("payload", column("json"))
+        .addColumn("refMap", column("json").nullable())
+        .addColumn(
+          "createdAt",
+          column("timestamp").defaultTo((b) => b.now()),
+        )
+        .createIndex("idx_outbox_versionstamp", ["versionstamp"], { unique: true })
+        .createIndex("idx_outbox_uow", ["uowId"]);
+    });
+});