@fragno-dev/db 0.2.2 → 0.4.1

package/src/sync/submit.ts

@@ -0,0 +1,328 @@
+import type { OutboxEntry } from "../outbox/outbox";
+import { ConcurrencyConflictError } from "../query/unit-of-work/execute-unit-of-work";
+import type { SubmitResponse, SubmitConflictReason, SyncCommandDefinition } from "./types";
+
+export const DEFAULT_MAX_COMMANDS_PER_SUBMIT = 100;
+export const DEFAULT_MAX_UNSEEN_MUTATIONS = 10_000;
+
+export type SyncRequestRecord = {
+  requestId: string;
+  status: "applied" | "conflict";
+  confirmedCommandIds: string[];
+  conflictCommandId?: string;
+  baseVersionstamp?: string;
+  lastVersionstamp?: string;
+};
+
+export type SyncCommandResolution = {
+  command: SyncCommandDefinition;
+  namespace: string | null;
+};
+
+export type SyncSubmitRuntime = {
+  getAdapterIdentity: () => Promise<string>;
+  listOutboxEntries: (afterVersionstamp?: string) => Promise<OutboxEntry[]>;
+  countOutboxMutations: (afterVersionstamp?: string) => Promise<number>;
+  getSyncRequest: (requestId: string) => Promise<SyncRequestRecord | undefined>;
+  storeSyncRequest: (record: SyncRequestRecord) => Promise<void>;
+  resolveCommand: (
+    fragment: string,
+    schema: string,
+    name: string,
+  ) => SyncCommandResolution | undefined;
+  createCommandContext: (command: SyncCommandDefinition) => unknown;
+  executeCommand: (command: SyncCommandDefinition, input: unknown, ctx: unknown) => Promise<void>;
+  maxCommandsPerSubmit?: number;
+  maxUnseenMutations?: number;
+};
+
+export type SyncSubmitError = {
+  status: "error";
+  statusCode: number;
+  body: {
+    error: {
+      code: string;
+      message: string;
+      detail?: string;
+    };
+  };
+};
+
+export type SyncSubmitResult =
+  | {
+      status: "ok";
+      response: SubmitResponse;
+    }
+  | SyncSubmitError;
+
+const VALID_CONFLICT_RESOLUTION = new Set(["server", "disabled"] as const);
+const VERSIONSTAMP_REGEX = /^[0-9a-f]{24}$/i;
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object";
+
+const isNonEmptyString = (value: unknown): value is string =>
+  typeof value === "string" && value.trim().length > 0;
+
+const normalizeVersionstamp = (value: string | undefined): string | undefined =>
+  value ? value.toLowerCase() : undefined;
+
+const isValidVersionstamp = (value: string): boolean => VERSIONSTAMP_REGEX.test(value);
+
+const buildError = (code: string, message: string, statusCode = 400): SyncSubmitError => ({
+  status: "error",
+  statusCode,
+  body: {
+    error: {
+      code,
+      message,
+    },
+  },
+});
+
+const withEntries = async (
+  runtime: SyncSubmitRuntime,
+  baseVersionstamp: string | undefined,
+): Promise<{ entries: OutboxEntry[]; lastVersionstamp?: string }> => {
+  const entries = await runtime.listOutboxEntries(baseVersionstamp);
+  const lastVersionstamp =
+    entries.length > 0 ? entries[entries.length - 1]?.versionstamp : undefined;
+  return { entries, lastVersionstamp };
+};
+
+export const submitSyncRequest = async (
+  raw: unknown,
+  runtime: SyncSubmitRuntime,
+): Promise<SyncSubmitResult> => {
+  if (!isObject(raw)) {
+    return buildError("INVALID_REQUEST", "Request body must be an object.");
+  }
+
+  const requestId = raw["requestId"];
+  if (!isNonEmptyString(requestId)) {
+    return buildError("INVALID_REQUEST", "requestId is required.");
+  }
+
+  const adapterIdentity = raw["adapterIdentity"];
+  if (!isNonEmptyString(adapterIdentity)) {
+    return buildError("INVALID_REQUEST", "adapterIdentity is required.");
+  }
+
+  const conflictResolutionStrategy = raw["conflictResolutionStrategy"];
+  if (
+    !isNonEmptyString(conflictResolutionStrategy) ||
+    !VALID_CONFLICT_RESOLUTION.has(conflictResolutionStrategy as "server" | "disabled")
+  ) {
+    return buildError(
+      "INVALID_REQUEST",
+      'conflictResolutionStrategy must be "server" or "disabled".',
+    );
+  }
+
+  const baseVersionstamp = raw["baseVersionstamp"];
+  if (baseVersionstamp !== undefined && !isNonEmptyString(baseVersionstamp)) {
+    return buildError("INVALID_REQUEST", "baseVersionstamp must be a non-empty string.");
+  }
+
+  const normalizedBaseVersionstamp =
+    baseVersionstamp !== undefined ? normalizeVersionstamp(baseVersionstamp) : undefined;
+  if (normalizedBaseVersionstamp && !isValidVersionstamp(normalizedBaseVersionstamp)) {
+    return buildError("INVALID_VERSIONSTAMP", "baseVersionstamp must be 24 hex characters.");
+  }
+
+  const commands = raw["commands"];
+  if (!Array.isArray(commands)) {
+    return buildError("INVALID_REQUEST", "commands must be an array.");
+  }
+
+  const expectedAdapterIdentity = await runtime.getAdapterIdentity();
+  if (expectedAdapterIdentity !== adapterIdentity) {
+    return buildError(
+      "ADAPTER_IDENTITY_MISMATCH",
+      "adapterIdentity does not match this adapter.",
+      409,
+    );
+  }
+
+  const existing = await runtime.getSyncRequest(requestId);
+  if (existing) {
+    const { entries, lastVersionstamp } = await withEntries(runtime, normalizedBaseVersionstamp);
+    const response: SubmitResponse = {
+      status: "conflict",
+      requestId,
+      confirmedCommandIds: existing.confirmedCommandIds ?? [],
+      conflictCommandId: existing.conflictCommandId ?? undefined,
+      lastVersionstamp: lastVersionstamp ?? existing.lastVersionstamp ?? undefined,
+      entries,
+      reason: "already_handled",
+    };
+    return { status: "ok", response };
+  }
+
+  const maxCommands = runtime.maxCommandsPerSubmit ?? DEFAULT_MAX_COMMANDS_PER_SUBMIT;
+  const maxUnseen = runtime.maxUnseenMutations ?? DEFAULT_MAX_UNSEEN_MUTATIONS;
+
+  if (commands.length === 0) {
+    const { entries, lastVersionstamp } = await withEntries(runtime, normalizedBaseVersionstamp);
+    const response: SubmitResponse = {
+      status: "conflict",
+      requestId,
+      confirmedCommandIds: [],
+      entries,
+      lastVersionstamp,
+      reason: "no_commands",
+    };
+    await runtime.storeSyncRequest({
+      requestId,
+      status: "conflict",
+      confirmedCommandIds: [],
+      baseVersionstamp: normalizedBaseVersionstamp,
+      lastVersionstamp,
+    });
+    return { status: "ok", response };
+  }
+
+  if (commands.length > maxCommands) {
+    const { entries, lastVersionstamp } = await withEntries(runtime, normalizedBaseVersionstamp);
+    const response: SubmitResponse = {
+      status: "conflict",
+      requestId,
+      confirmedCommandIds: [],
+      entries,
+      lastVersionstamp,
+      reason: "limit_exceeded",
+    };
+    await runtime.storeSyncRequest({
+      requestId,
+      status: "conflict",
+      confirmedCommandIds: [],
+      baseVersionstamp: normalizedBaseVersionstamp,
+      lastVersionstamp,
+    });
+    return { status: "ok", response };
+  }
+
+  const unseenCount = await runtime.countOutboxMutations(normalizedBaseVersionstamp);
+  if (unseenCount > maxUnseen) {
+    const { entries, lastVersionstamp } = await withEntries(runtime, normalizedBaseVersionstamp);
+    const response: SubmitResponse = {
+      status: "conflict",
+      requestId,
+      confirmedCommandIds: [],
+      entries,
+      lastVersionstamp,
+      reason: "client_far_behind",
+    };
+    await runtime.storeSyncRequest({
+      requestId,
+      status: "conflict",
+      confirmedCommandIds: [],
+      baseVersionstamp: normalizedBaseVersionstamp,
+      lastVersionstamp,
+    });
+    return { status: "ok", response };
+  }
+
+  const confirmedCommandIds: string[] = [];
+  let conflictCommandId: string | undefined;
+  let conflictReason: SubmitConflictReason | undefined;
+
+  for (const command of commands) {
+    if (!isObject(command)) {
+      return buildError("INVALID_COMMAND", "Command entries must be objects.");
+    }
+
+    const commandId = command["id"];
+    const commandName = command["name"];
+    const target = command["target"];
+
+    if (!isNonEmptyString(commandId) || !isNonEmptyString(commandName) || !isObject(target)) {
+      return buildError("INVALID_COMMAND", "Command entries must include id, name, and target.");
+    }
+
+    const fragmentName = target["fragment"];
+    const schemaName = target["schema"];
+
+    if (!isNonEmptyString(fragmentName) || !isNonEmptyString(schemaName)) {
+      return buildError("INVALID_COMMAND", "Command target must include fragment and schema.");
+    }
+
+    const resolved = runtime.resolveCommand(fragmentName, schemaName, commandName);
+    if (!resolved) {
+      return buildError("UNKNOWN_COMMAND", "Command target or name was not recognized.");
+    }
+
+    const ctx = runtime.createCommandContext(resolved.command);
+
+    try {
+      await runtime.executeCommand(resolved.command, command["input"], ctx);
+      confirmedCommandIds.push(commandId);
+    } catch (error) {
+      if (error instanceof ConcurrencyConflictError) {
+        conflictCommandId = commandId;
+        conflictReason = "write_congestion";
+        break;
+      }
+      await runtime.storeSyncRequest({
+        requestId,
+        status: "conflict",
+        confirmedCommandIds,
+        conflictCommandId: commandId,
+        baseVersionstamp: normalizedBaseVersionstamp,
+      });
+      return {
+        status: "error",
+        statusCode: 500,
+        body: {
+          error: {
+            code: "SYNC_COMMAND_FAILED",
+            message: error instanceof Error ? error.message : "Sync command failed.",
+          },
+        },
+      };
+    }
+  }
+
+  const { entries, lastVersionstamp } = await withEntries(runtime, normalizedBaseVersionstamp);
+
+  if (conflictReason) {
+    const response: SubmitResponse = {
+      status: "conflict",
+      requestId,
+      confirmedCommandIds,
+      conflictCommandId,
+      entries,
+      lastVersionstamp,
+      reason: conflictReason,
+    };
+
+    await runtime.storeSyncRequest({
+      requestId,
+      status: "conflict",
+      confirmedCommandIds,
+      conflictCommandId,
+      baseVersionstamp: normalizedBaseVersionstamp,
+      lastVersionstamp,
+    });
+
+    return { status: "ok", response };
+  }
+
+  const response: SubmitResponse = {
+    status: "applied",
+    requestId,
+    confirmedCommandIds,
+    entries,
+    lastVersionstamp,
+  };
+
+  await runtime.storeSyncRequest({
+    requestId,
+    status: "applied",
+    confirmedCommandIds,
+    baseVersionstamp: normalizedBaseVersionstamp,
+    lastVersionstamp,
+  });
+
+  return { status: "ok", response };
+};

package/src/sync/types.ts

@@ -0,0 +1,80 @@
+import type { RequestThisContext } from "@fragno-dev/core";
+
+import type { OutboxEntry } from "../outbox/outbox";
+import type {
+  ExecuteTxOptions,
+  HandlerTxBuilder,
+} from "../query/unit-of-work/execute-unit-of-work";
+
+export type SubmitRequest = {
+  baseVersionstamp?: string;
+  requestId: string;
+  conflictResolutionStrategy: "server" | "disabled";
+  adapterIdentity: string;
+  commands: Array<{
+    id: string;
+    name: string;
+    target: {
+      fragment: string;
+      schema: string;
+    };
+    input: unknown;
+  }>;
+};
+
+export type SubmitConflictReason =
+  | "conflict"
+  | "write_congestion"
+  | "client_far_behind"
+  | "no_commands"
+  | "already_handled"
+  | "limit_exceeded";
+
+export type SubmitAppliedResponse = {
+  status: "applied";
+  requestId: string;
+  confirmedCommandIds: string[];
+  lastVersionstamp?: string;
+  entries: OutboxEntry[];
+};
+
+export type SubmitConflictResponse = {
+  status: "conflict";
+  requestId: string;
+  confirmedCommandIds: string[];
+  conflictCommandId?: string;
+  lastVersionstamp?: string;
+  entries: OutboxEntry[];
+  reason: SubmitConflictReason;
+};
+
+export type SubmitResponse = SubmitAppliedResponse | SubmitConflictResponse;
+
+export type SyncCommandTxFactory = (
+  options?: Omit<ExecuteTxOptions, "createUnitOfWork">,
+) => HandlerTxBuilder<readonly [], [], [], unknown, unknown, false, false, false, false, {}>;
+
+export type SyncCommandHandler<TInput = unknown, TContext = unknown> = (args: {
+  input: TInput;
+  tx: SyncCommandTxFactory;
+  ctx: TContext;
+}) => Promise<unknown>;
+
+export type SyncCommandDefinition<TInput = unknown, TContext = unknown> = {
+  name: string;
+  handler: SyncCommandHandler<TInput, TContext>;
+  createServerContext?: (requestContext: RequestThisContext) => TContext;
+};
+
+export type SyncCommandRegistry = {
+  schemaName: string;
+  commands: Map<string, SyncCommandDefinition>;
+  getCommand: (name: string) => SyncCommandDefinition | undefined;
+};
+
+export type SyncCommandTargetRegistration = {
+  fragmentName: string;
+  schemaName: string;
+  namespace: string | null;
+  commands: Map<string, SyncCommandDefinition>;
+};

package/src/util/default-database-adapter.ts

@@ -0,0 +1,119 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+import { SqliteDialect } from "kysely";
+
+import type { DatabaseAdapter } from "../adapters/adapters";
+import { BetterSQLite3DriverConfig } from "../adapters/generic-sql/driver-config";
+import { SqlAdapter } from "../adapters/generic-sql/generic-sql-adapter";
+import type { AnySchema } from "../schema/create";
+type DatabaseAdapterConfig = {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  databaseAdapter?: DatabaseAdapter<any>;
+  databaseNamespace?: string | null;
+};
+
+type BetterSqlite3Constructor = typeof import("better-sqlite3");
+
+const isCloudflareWorkers = (): boolean => {
+  if (typeof globalThis === "undefined") {
+    return false;
+  }
+  const navigatorRef = (globalThis as { navigator?: { userAgent?: string } }).navigator;
+  return navigatorRef?.userAgent === "Cloudflare-Workers";
+};
+
+const createNodeRequire = (): NodeRequire | null => {
+  try {
+    const metaUrl = typeof import.meta !== "undefined" ? import.meta.url : undefined;
+    if (!metaUrl || typeof metaUrl !== "string") {
+      return null;
+    }
+    return createRequire(metaUrl);
+  } catch {
+    return null;
+  }
+};
+
+const loadBetterSqlite3 = (): BetterSqlite3Constructor | null => {
+  if (isCloudflareWorkers()) {
+    return null;
+  }
+  const requireFn = createNodeRequire();
+  if (!requireFn) {
+    return null;
+  }
+  try {
+    const module = requireFn("better-sqlite3");
+    return (module.default ?? module) as BetterSqlite3Constructor;
+  } catch {
+    return null;
+  }
+};
+
+const betterSqlite3Constructor = loadBetterSqlite3();
+
+const defaultDataDir = (): string => {
+  const configured = process.env["FRAGNO_DATA_DIR"];
+  if (configured && configured.trim().length > 0) {
+    return configured;
+  }
+  return path.join(process.env["HOME"] ?? process.cwd(), ".fragno");
+};
+
+const sanitizeFileSegment = (name: string): string => {
+  const sanitized = name.replace(/[^a-z0-9-]/gi, "_");
+  return sanitized.length > 0 ? sanitized : "fragno";
+};
+
+const resolveSqliteDatabasePath = <TSchema extends AnySchema>(
+  options: DatabaseAdapterConfig,
+  schema: TSchema,
+): string => {
+  const baseName =
+    typeof options.databaseNamespace === "string" && options.databaseNamespace.length > 0
+      ? options.databaseNamespace
+      : schema.name;
+  const fileName = `${sanitizeFileSegment(baseName)}.sqlite`;
+  return path.join(defaultDataDir(), fileName);
+};
+
+const createDefaultSqliteAdapter = <TSchema extends AnySchema>(
+  options: DatabaseAdapterConfig,
+  schema: TSchema,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): DatabaseAdapter<any> | null => {
+  if (!betterSqlite3Constructor) {
+    return null;
+  }
+
+  const dbPath = resolveSqliteDatabasePath(options, schema);
+  fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+
+  const dialect = new SqliteDialect({
+    database: new betterSqlite3Constructor(dbPath),
+  });
+  const driverConfig = new BetterSQLite3DriverConfig();
+  return new SqlAdapter({ dialect, driverConfig });
+};
+
+export const resolveDatabaseAdapter = <TSchema extends AnySchema>(
+  options: DatabaseAdapterConfig,
+  schema: TSchema,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): DatabaseAdapter<any> => {
+  if (options.databaseAdapter) {
+    return options.databaseAdapter;
+  }
+
+  const defaultAdapter = createDefaultSqliteAdapter(options, schema);
+  if (!defaultAdapter) {
+    throw new Error(
+      "Database fragment requires options.databaseAdapter, or install better-sqlite3 to use the default SQLite adapter.",
+    );
+  }
+
+  options.databaseAdapter = defaultAdapter;
+  return defaultAdapter;
+};

package/src/with-database.ts

@@ -1,10 +1,6 @@
-import type { AnySchema } from "./schema/create";
-import type {
-  RequestThisContext,
-  FragnoPublicConfig,
-  AnyFragnoInstantiatedFragment,
-} from "@fragno-dev/core";
-import { FragmentDefinitionBuilder, instantiate } from "@fragno-dev/core";
+import type { RequestThisContext, FragnoPublicConfig, AnyRouteOrFactory } from "@fragno-dev/core";
+import { FragmentDefinitionBuilder } from "@fragno-dev/core";
+
 import {
   DatabaseFragmentDefinitionBuilder,
   type DatabaseServiceContext,
@@ -13,12 +9,13 @@ import {
   type FragnoPublicConfigWithDatabase,
   type DatabaseRequestStorage,
 } from "./db-fragment-definition-builder";
-import { internalFragmentDef, type InternalFragmentInstance } from "./fragments/internal-fragment";
 import type { HooksMap } from "./hooks/hooks";
+import { getInternalFragment, getRegistryForAdapterSync } from "./internal/adapter-registry";
+import type { AnySchema } from "./schema/create";
 
 /**
  * Helper to add database support to a fragment builder.
- * Automatically links the internal fragment and adds ImplicitDatabaseDependencies to the TDeps type.
+ * Registers the schema with the adapter registry and adds ImplicitDatabaseDependencies to the TDeps type.
  *
  * @example
  * ```typescript
@@ -36,7 +33,6 @@ import type { HooksMap } from "./hooks/hooks";
  */
 export function withDatabase<TSchema extends AnySchema>(
   schema: TSchema,
-  namespace?: string,
 ): <
   TConfig,
   TDeps,
@@ -47,7 +43,7 @@ export function withDatabase<TSchema extends AnySchema>(
   TServiceThisContext extends RequestThisContext,
   THandlerThisContext extends RequestThisContext,
   TRequestStorage,
-  TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment>,
+  TInternalRoutes extends readonly AnyRouteOrFactory[],
 >(
   builder: FragmentDefinitionBuilder<
     TConfig,
@@ -60,7 +56,7 @@ export function withDatabase<TSchema extends AnySchema>(
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   >,
 ) => DatabaseFragmentDefinitionBuilder<
   TSchema,
@@ -73,7 +69,7 @@ export function withDatabase<TSchema extends AnySchema>(
   HooksMap,
   DatabaseServiceContext<HooksMap>,
   DatabaseHandlerContext,
-  TLinkedFragments & { _fragno_internal: InternalFragmentInstance }
+  TInternalRoutes
 > {
   return <
     TConfig,
@@ -85,7 +81,7 @@ export function withDatabase<TSchema extends AnySchema>(
     TServiceThisContext extends RequestThisContext,
     THandlerThisContext extends RequestThisContext,
     TRequestStorage,
-    TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment>,
+    TInternalRoutes extends readonly AnyRouteOrFactory[],
   >(
     builder: FragmentDefinitionBuilder<
       TConfig,
@@ -98,21 +94,9 @@ export function withDatabase<TSchema extends AnySchema>(
       TServiceThisContext,
       THandlerThisContext,
       TRequestStorage,
-      TLinkedFragments
+      TInternalRoutes
     >,
   ) => {
-    const builderWithInternal = builder.withLinkedFragment(
-      "_fragno_internal",
-      ({ config, options }) => {
-        // Cast is safe: by the time this callback is invoked during fragment instantiation,
-        // the options will be FragnoPublicConfigWithDatabase (enforced by DatabaseFragmentDefinitionBuilder)
-        return instantiate(internalFragmentDef)
-          .withConfig(config as {})
-          .withOptions(options as FragnoPublicConfigWithDatabase)
-          .build();
-      },
-    );
-
     // Cast is safe: we're creating a DatabaseFragmentDefinitionBuilder which internally uses
     // FragnoPublicConfigWithDatabase, but the input builder uses FragnoPublicConfig.
     // The database builder's build() method will enforce FragnoPublicConfigWithDatabase at the end.
@@ -130,9 +114,9 @@ export function withDatabase<TSchema extends AnySchema>(
       {}, // Start with empty hooks, provideHooks() will update this
       DatabaseServiceContext<{}>,
       DatabaseHandlerContext,
-      TLinkedFragments & { _fragno_internal: InternalFragmentInstance }
+      TInternalRoutes
     >(
-      builderWithInternal as unknown as FragmentDefinitionBuilder<
+      builder as unknown as FragmentDefinitionBuilder<
         TConfig,
         FragnoPublicConfigWithDatabase,
         TDeps & ImplicitDatabaseDependencies<TSchema>,
@@ -143,10 +127,15 @@ export function withDatabase<TSchema extends AnySchema>(
         DatabaseServiceContext<{}>,
         DatabaseHandlerContext,
         DatabaseRequestStorage,
-        TLinkedFragments & { _fragno_internal: InternalFragmentInstance }
+        TInternalRoutes
       >,
       schema,
-      namespace,
+      undefined,
+      undefined,
+      {
+        getRegistryForAdapterSync,
+        getInternalFragment,
+      },
     );
   };
 }

package/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "@fragno-private/typescript-config/tsconfig.base.json",
+  "extends": "@fragno-private/typescript-config/tsconfig.node.json",
   "compilerOptions": {
     "outDir": "./dist",
     "rootDir": ".",