@fragno-dev/db 0.2.2 → 0.4.1

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

@@ -0,0 +1,334 @@
+import { defineRoutes } from "@fragno-dev/core";
+
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+import type { DatabaseHandlerContext } from "../db-fragment-definition-builder";
+import type { OutboxEntry } from "../outbox/outbox";
+import { submitSyncRequest, type SyncRequestRecord } from "../sync/submit";
+import type { SubmitRequest, SyncCommandDefinition } from "../sync/types";
+import {
+  SETTINGS_NAMESPACE,
+  internalFragmentDef,
+  internalSchema,
+  type InternalFragmentInstance,
+} from "./internal-fragment";
+
+type InternalDescribeResponse = {
+  adapterIdentity: string;
+  fragments: Array<{ name: string; mountRoute: string }>;
+  schemas: Array<{
+    name: string;
+    namespace: string | null;
+    version: number;
+    tables: string[];
+  }>;
+  routes: {
+    internal: "/_internal";
+    outbox?: "/_internal/outbox";
+  };
+};
+
+type InternalDescribeError = {
+  error: {
+    code: string;
+    message: string;
+    detail?: string;
+  };
+};
+
+const ADAPTER_IDENTITY_KEY = "adapter_identity" as const;
+
+const passthroughInputSchema: StandardSchemaV1 = {
+  "~standard": {
+    version: 1,
+    vendor: "fragno",
+    validate: async (value: unknown) => ({ value }),
+  },
+};
+
+type AdapterIdentityResult =
+  | { ok: true; value: string }
+  | { ok: false; error: InternalDescribeError };
+
+const getOrCreateAdapterIdentity = async (
+  handlerTx: () => ReturnType<DatabaseHandlerContext["handlerTx"]>,
+  services: Pick<InternalFragmentInstance["services"], "settingsService">,
+): Promise<AdapterIdentityResult> => {
+  const readIdentity = async () =>
+    handlerTx()
+      .withServiceCalls(
+        () => [services.settingsService.get(SETTINGS_NAMESPACE, ADAPTER_IDENTITY_KEY)] as const,
+      )
+      .transform(({ serviceResult: [result] }) => result?.value as string | undefined)
+      .execute();
+
+  try {
+    const existingIdentity = await readIdentity();
+    if (existingIdentity) {
+      return { ok: true, value: existingIdentity };
+    }
+
+    const adapterIdentity = crypto.randomUUID();
+    try {
+      await handlerTx()
+        .withServiceCalls(
+          () =>
+            [
+              services.settingsService.setIfMissing(
+                SETTINGS_NAMESPACE,
+                ADAPTER_IDENTITY_KEY,
+                adapterIdentity,
+              ),
+            ] as const,
+        )
+        .execute();
+    } catch (error) {
+      const recoveredIdentity = await readIdentity();
+      if (recoveredIdentity) {
+        return { ok: true, value: recoveredIdentity };
+      }
+      throw error;
+    }
+
+    const persistedIdentity = await readIdentity();
+    return { ok: true, value: persistedIdentity ?? adapterIdentity };
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        error: {
+          code: "SETTINGS_UNAVAILABLE",
+          message: "Internal settings table is not available.",
+          detail: error instanceof Error ? error.message : undefined,
+        },
+      },
+    };
+  }
+};
+
+export const createInternalFragmentDescribeRoutes = () =>
+  defineRoutes(internalFragmentDef).create(({ defineRoute, config, services }) => [
+    defineRoute({
+      method: "GET",
+      path: "/",
+      handler: async function (_input, { json }) {
+        const registry = config.registry;
+        if (!registry) {
+          return json(
+            {
+              error: {
+                code: "REGISTRY_UNAVAILABLE",
+                message: "Adapter registry is not configured.",
+              },
+            } satisfies InternalDescribeError,
+            { status: 500 },
+          );
+        }
+
+        const adapterIdentityResult = await getOrCreateAdapterIdentity(
+          () => this.handlerTx(),
+          services,
+        );
+        if (!adapterIdentityResult.ok) {
+          return json(adapterIdentityResult.error, { status: 500 });
+        }
+
+        const outboxEnabled = registry.isOutboxEnabled();
+        const response: InternalDescribeResponse = {
+          adapterIdentity: adapterIdentityResult.value,
+          fragments: outboxEnabled ? registry.listOutboxFragments() : [],
+          schemas: registry.listSchemas(),
+          routes: {
+            internal: "/_internal",
+            outbox: outboxEnabled ? "/_internal/outbox" : undefined,
+          },
+        };
+
+        return json(response);
+      },
+    }),
+  ]);
+
+export const createInternalFragmentOutboxRoutes = () =>
+  defineRoutes(internalFragmentDef).create(({ defineRoute, services, config }) => [
+    defineRoute({
+      method: "GET",
+      path: "/outbox",
+      handler: async function (input, { json }) {
+        const registry = config.registry;
+        if (!registry || !registry.isOutboxEnabled()) {
+          return json(
+            {
+              error: {
+                code: "OUTBOX_UNAVAILABLE",
+                message: "Outbox is not enabled for this adapter.",
+              },
+            },
+            { status: 404 },
+          );
+        }
+
+        // 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);
+      },
+    }),
+  ]);
+
+type InternalSyncError = {
+  error: {
+    code: string;
+    message: string;
+    detail?: string;
+  };
+};
+
+export const createInternalFragmentSyncRoutes = () =>
+  defineRoutes(internalFragmentDef).create(({ defineRoute, services, config }) => [
+    defineRoute({
+      method: "POST",
+      path: "/sync",
+      inputSchema: passthroughInputSchema,
+      handler: async function (input, { json }) {
+        const registry = config.registry;
+        if (!registry || !registry.isOutboxEnabled()) {
+          return json(
+            {
+              error: {
+                code: "SYNC_UNAVAILABLE",
+                message: "Sync is not enabled for this adapter.",
+              },
+            } satisfies InternalSyncError,
+            { status: 404 },
+          );
+        }
+
+        const adapterIdentityResult = await getOrCreateAdapterIdentity(
+          () => this.handlerTx(),
+          services,
+        );
+        if (!adapterIdentityResult.ok) {
+          return json(adapterIdentityResult.error, { status: 500 });
+        }
+
+        const body = (await input.input?.valid()) as SubmitRequest | undefined;
+
+        const result = await submitSyncRequest(body, {
+          getAdapterIdentity: async () => adapterIdentityResult.value,
+          listOutboxEntries: async (afterVersionstamp) =>
+            await this.handlerTx()
+              .withServiceCalls(
+                () =>
+                  [services.outboxService.list({ afterVersionstamp, limit: undefined })] as const,
+              )
+              .transform(({ serviceResult: [entries] }) => entries as OutboxEntry[])
+              .execute(),
+          countOutboxMutations: async (afterVersionstamp) => {
+            const count = await this.handlerTx()
+              .retrieve(({ forSchema }) => {
+                const builder = afterVersionstamp
+                  ? forSchema(internalSchema).find("fragno_db_outbox_mutations", (b) =>
+                      b
+                        .whereIndex("idx_outbox_mutations_entry", (eb) =>
+                          eb("entryVersionstamp", ">", afterVersionstamp),
+                        )
+                        .selectCount(),
+                    )
+                  : forSchema(internalSchema).find("fragno_db_outbox_mutations", (b) =>
+                      b.whereIndex("idx_outbox_mutations_entry").selectCount(),
+                    );
+                return builder;
+              })
+              .transformRetrieve(([result]) => (typeof result === "number" ? result : 0))
+              .execute();
+            return count;
+          },
+          getSyncRequest: async (requestId) =>
+            await this.handlerTx()
+              .retrieve(({ forSchema }) =>
+                forSchema(internalSchema).findFirst("fragno_db_sync_requests", (b) =>
+                  b.whereIndex("idx_sync_request_id", (eb) => eb("requestId", "=", requestId)),
+                ),
+              )
+              .transformRetrieve(([result]) => {
+                if (!result) {
+                  return undefined;
+                }
+                const confirmed = Array.isArray(result.confirmedCommandIds)
+                  ? (result.confirmedCommandIds as string[])
+                  : [];
+                const status = result.status === "applied" ? "applied" : "conflict";
+                return {
+                  requestId: result.requestId,
+                  status,
+                  confirmedCommandIds: confirmed,
+                  conflictCommandId: result.conflictCommandId ?? undefined,
+                  baseVersionstamp: result.baseVersionstamp ?? undefined,
+                  lastVersionstamp: result.lastVersionstamp ?? undefined,
+                } satisfies SyncRequestRecord;
+              })
+              .execute(),
+          storeSyncRequest: async (record) => {
+            await this.handlerTx()
+              .mutate(({ forSchema }) => {
+                forSchema(internalSchema).create("fragno_db_sync_requests", {
+                  requestId: record.requestId,
+                  status: record.status,
+                  confirmedCommandIds: record.confirmedCommandIds,
+                  conflictCommandId: record.conflictCommandId ?? null,
+                  baseVersionstamp: record.baseVersionstamp ?? null,
+                  lastVersionstamp: record.lastVersionstamp ?? null,
+                });
+              })
+              .execute();
+          },
+          resolveCommand: (fragment, schema, name) =>
+            registry.resolveSyncCommand(fragment, schema, name) as
+              | { command: SyncCommandDefinition; namespace: string | null }
+              | undefined,
+          createCommandContext: (command) =>
+            command.createServerContext?.(this) ?? { mode: "server" },
+          executeCommand: async (command, inputPayload, ctx) => {
+            await command.handler({
+              input: inputPayload,
+              ctx,
+              tx: (options) => this.handlerTx(options),
+            });
+          },
+        });
+
+        if (result.status === "error") {
+          const statusCode = result.statusCode as 400 | 409 | 500;
+          return json(result.body, { status: statusCode });
+        }
+
+        return json(result.response);
+      },
+    }),
+  ]);

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

@@ -0,0 +1,95 @@
+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"]);
+    })
+    .addTable("fragno_db_outbox_mutations", (t) => {
+      return t
+        .addColumn("id", idColumn())
+        .addColumn("entryVersionstamp", column("string"))
+        .addColumn("mutationVersionstamp", column("string"))
+        .addColumn("uowId", column("string"))
+        .addColumn("schema", column("string"))
+        .addColumn("table", column("string"))
+        .addColumn("externalId", column("string"))
+        .addColumn("op", column("string"))
+        .addColumn(
+          "createdAt",
+          column("timestamp").defaultTo((b) => b.now()),
+        )
+        .createIndex("idx_outbox_mutations_entry", ["entryVersionstamp"])
+        .createIndex("idx_outbox_mutations_key", [
+          "schema",
+          "table",
+          "externalId",
+          "entryVersionstamp",
+        ])
+        .createIndex("idx_outbox_mutations_uow", ["uowId"]);
+    })
+    .addTable("fragno_db_sync_requests", (t) => {
+      return t
+        .addColumn("id", idColumn())
+        .addColumn("requestId", column("string"))
+        .addColumn("status", column("string"))
+        .addColumn("confirmedCommandIds", column("json"))
+        .addColumn("conflictCommandId", column("string").nullable())
+        .addColumn("baseVersionstamp", column("string").nullable())
+        .addColumn("lastVersionstamp", column("string").nullable())
+        .addColumn(
+          "createdAt",
+          column("timestamp").defaultTo((b) => b.now()),
+        )
+        .createIndex("idx_sync_request_id", ["requestId"], { unique: true });
+    })
+    .alterTable("fragno_hooks", (t) =>
+      t.createIndex("idx_namespace_status_last_attempt", ["namespace", "status", "lastAttemptAt"]),
+    )
+    .alterTable("fragno_hooks", (t) =>
+      t.createIndex("idx_namespace_created_at", ["namespace", "createdAt", "id"]),
+    );
+});