@fragno-dev/db 0.2.2 → 0.4.1

package/src/sync/read-tracking.ts

@@ -0,0 +1,287 @@
+import type { Condition } from "../query/condition-builder";
+import { buildCondition } from "../query/condition-builder";
+import type { CursorResult } from "../query/cursor";
+import type { CompiledJoin } from "../query/orm/orm";
+import type { AnySelectClause } from "../query/simple-query-interface";
+import type { MutationOperation, RetrievalOperation } from "../query/unit-of-work/unit-of-work";
+import type { AnySchema, AnyTable } from "../schema/create";
+import { FragnoId } from "../schema/create";
+
+export type ReadKey = {
+  schema: string;
+  table: string;
+  externalId: string;
+};
+
+export type ReadScope = {
+  schema: string;
+  table: AnyTable;
+  indexName: string;
+  condition?: Condition;
+  joins?: CompiledJoin[];
+};
+
+const isCursorResult = (value: unknown): value is CursorResult<unknown> => {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+
+  return Array.isArray((value as CursorResult<unknown>).items);
+};
+
+const getExternalId = (value: unknown): string | undefined => {
+  if (typeof value === "string") {
+    return value;
+  }
+
+  if (value instanceof FragnoId) {
+    return value.externalId;
+  }
+
+  if (value && typeof value === "object") {
+    const candidate = (value as { externalId?: unknown }).externalId;
+    if (typeof candidate === "string") {
+      return candidate;
+    }
+  }
+
+  return undefined;
+};
+
+const collectKeysFromRecord = (
+  record: unknown,
+  table: AnyTable,
+  joins: CompiledJoin[] | undefined,
+  schemaName: string,
+  output: ReadKey[],
+): void => {
+  if (!record || typeof record !== "object") {
+    return;
+  }
+
+  const idKey = table.getIdColumn().name;
+  const externalId = getExternalId((record as Record<string, unknown>)[idKey]);
+  if (externalId !== undefined) {
+    output.push({ schema: schemaName, table: table.name, externalId });
+  }
+
+  if (!joins || joins.length === 0) {
+    return;
+  }
+
+  for (const join of joins) {
+    const { relation, options } = join;
+    if (options === false) {
+      continue;
+    }
+
+    const relationValue = (record as Record<string, unknown>)[relation.name];
+    if (relationValue === null || relationValue === undefined) {
+      continue;
+    }
+
+    if (Array.isArray(relationValue)) {
+      for (const item of relationValue) {
+        collectKeysFromRecord(item, relation.table, options.join, schemaName, output);
+      }
+      continue;
+    }
+
+    collectKeysFromRecord(relationValue, relation.table, options.join, schemaName, output);
+  }
+};
+
+const shouldStripId = (select: AnySelectClause | undefined, table: AnyTable): boolean => {
+  if (!select || select === true) {
+    return false;
+  }
+
+  const idKey = table.getIdColumn().name;
+  return !select.includes(idKey);
+};
+
+const stripKeysFromRecord = (
+  record: unknown,
+  table: AnyTable,
+  joins: CompiledJoin[] | undefined,
+  stripId: boolean,
+): void => {
+  if (!record || typeof record !== "object") {
+    return;
+  }
+
+  if (stripId) {
+    const idKey = table.getIdColumn().name;
+    delete (record as Record<string, unknown>)[idKey];
+  }
+
+  if (!joins || joins.length === 0) {
+    return;
+  }
+
+  for (const join of joins) {
+    const { relation, options } = join;
+    if (options === false) {
+      continue;
+    }
+
+    const relationValue = (record as Record<string, unknown>)[relation.name];
+    if (relationValue === null || relationValue === undefined) {
+      continue;
+    }
+
+    const stripRelationId = shouldStripId(options.select, relation.table);
+
+    if (Array.isArray(relationValue)) {
+      for (const item of relationValue) {
+        stripKeysFromRecord(item, relation.table, options.join, stripRelationId);
+      }
+      continue;
+    }
+
+    stripKeysFromRecord(relationValue, relation.table, options.join, stripRelationId);
+  }
+};
+
+export const collectReadScopes = (
+  operations: ReadonlyArray<RetrievalOperation<AnySchema>>,
+): ReadScope[] => {
+  const scopes: ReadScope[] = [];
+
+  for (const op of operations) {
+    const schemaName = op.namespace ?? "";
+
+    if (op.type === "count") {
+      const condition = op.options.where
+        ? buildCondition(op.table.columns, op.options.where)
+        : undefined;
+
+      if (condition === false) {
+        continue;
+      }
+
+      scopes.push({
+        schema: schemaName,
+        table: op.table,
+        indexName: op.indexName,
+        condition: condition === true ? undefined : condition,
+      });
+      continue;
+    }
+
+    if (op.type === "find") {
+      const condition = op.options.where
+        ? buildCondition(op.table.columns, op.options.where)
+        : undefined;
+
+      if (condition === false) {
+        continue;
+      }
+
+      scopes.push({
+        schema: schemaName,
+        table: op.table,
+        indexName: op.indexName,
+        condition: condition === true ? undefined : condition,
+        joins: op.options.joins,
+      });
+    }
+  }
+
+  return scopes;
+};
+
+export const collectReadKeys = (
+  operations: ReadonlyArray<RetrievalOperation<AnySchema>>,
+  results: unknown[],
+): ReadKey[] => {
+  const keys: ReadKey[] = [];
+
+  for (const [index, op] of operations.entries()) {
+    if (op.type !== "find") {
+      continue;
+    }
+
+    const schemaName = op.namespace ?? "";
+    const result = results[index];
+
+    let records: unknown[] = [];
+    if (op.withCursor && isCursorResult(result)) {
+      records = result.items;
+    } else if (Array.isArray(result)) {
+      records = result;
+    } else if (result !== null && result !== undefined) {
+      records = [result];
+    }
+
+    for (const record of records) {
+      collectKeysFromRecord(record, op.table, op.options.joins, schemaName, keys);
+    }
+  }
+
+  return keys;
+};
+
+export const collectWriteKeys = (
+  operations: ReadonlyArray<MutationOperation<AnySchema>>,
+): ReadKey[] => {
+  const keys: ReadKey[] = [];
+
+  for (const op of operations) {
+    if (op.type === "check") {
+      continue;
+    }
+
+    const schemaName = op.namespace ?? "";
+
+    if (op.type === "create") {
+      keys.push({
+        schema: schemaName,
+        table: op.table,
+        externalId: op.generatedExternalId,
+      });
+      continue;
+    }
+
+    const externalId = getExternalId(op.id);
+    if (externalId !== undefined) {
+      keys.push({
+        schema: schemaName,
+        table: op.table,
+        externalId,
+      });
+    }
+  }
+
+  return keys;
+};
+
+export const stripReadTrackingResults = (
+  operations: ReadonlyArray<RetrievalOperation<AnySchema>>,
+  results: unknown[],
+): void => {
+  for (const [index, op] of operations.entries()) {
+    if (op.type !== "find" || !op.readTracking) {
+      continue;
+    }
+
+    const result = results[index];
+    const stripId = shouldStripId(op.options.select, op.table);
+
+    if (op.withCursor && isCursorResult(result)) {
+      for (const record of result.items) {
+        stripKeysFromRecord(record, op.table, op.options.joins, stripId);
+      }
+      continue;
+    }
+
+    if (Array.isArray(result)) {
+      for (const record of result) {
+        stripKeysFromRecord(record, op.table, op.options.joins, stripId);
+      }
+      continue;
+    }
+
+    stripKeysFromRecord(result, op.table, op.options.joins, stripId);
+  }
+};

package/src/sync/submit.test.ts

@@ -0,0 +1,205 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { OutboxEntry } from "../outbox/outbox";
+import { FragnoId } from "../schema/create";
+import { submitSyncRequest, type SyncRequestRecord, type SyncSubmitRuntime } from "./submit";
+import type { SyncCommandDefinition } from "./types";
+
+const createEntry = (versionstamp: string): OutboxEntry => ({
+  id: FragnoId.fromExternal(`entry-${versionstamp}`, 1),
+  versionstamp,
+  uowId: `uow-${versionstamp}`,
+  payload: { json: { version: 1, mutations: [] } },
+  createdAt: new Date(),
+});
+
+const createRuntime = (
+  overrides: Partial<SyncSubmitRuntime> = {},
+): {
+  runtime: SyncSubmitRuntime;
+  stored: SyncRequestRecord[];
+  executed: string[];
+} => {
+  const stored: SyncRequestRecord[] = [];
+  const executed: string[] = [];
+
+  const runtime: SyncSubmitRuntime = {
+    getAdapterIdentity: async () => "adapter-1",
+    listOutboxEntries: async () => [],
+    countOutboxMutations: async () => 0,
+    getSyncRequest: async () => undefined,
+    storeSyncRequest: async (record) => {
+      stored.push(record);
+    },
+    resolveCommand: () => ({
+      command: { name: "noop", handler: async () => undefined },
+      namespace: "app",
+    }),
+    createCommandContext: () => ({}),
+    executeCommand: async (command) => {
+      executed.push(command.name);
+    },
+    ...overrides,
+  };
+
+  return { runtime, stored, executed };
+};
+
+describe("submitSyncRequest", () => {
+  it("rejects adapter identity mismatches", async () => {
+    const { runtime } = createRuntime({
+      getAdapterIdentity: async () => "expected",
+    });
+
+    const result = await submitSyncRequest(
+      {
+        requestId: "req-1",
+        adapterIdentity: "other",
+        conflictResolutionStrategy: "server",
+        commands: [
+          {
+            id: "cmd-1",
+            name: "noop",
+            target: { fragment: "alpha", schema: "alpha" },
+            input: {},
+          },
+        ],
+      },
+      runtime,
+    );
+
+    expect(result.status).toBe("error");
+    if (result.status === "error") {
+      expect(result.statusCode).toBe(409);
+      expect(result.body.error.code).toBe("ADAPTER_IDENTITY_MISMATCH");
+    }
+  });
+
+  it("returns limit_exceeded when too many commands are submitted", async () => {
+    const { runtime, stored } = createRuntime({
+      maxCommandsPerSubmit: 1,
+      listOutboxEntries: async () => [createEntry("000000000000000000000001")],
+    });
+
+    const result = await submitSyncRequest(
+      {
+        requestId: "req-2",
+        adapterIdentity: "adapter-1",
+        conflictResolutionStrategy: "server",
+        commands: [
+          {
+            id: "cmd-1",
+            name: "noop",
+            target: { fragment: "alpha", schema: "alpha" },
+            input: {},
+          },
+          {
+            id: "cmd-2",
+            name: "noop",
+            target: { fragment: "alpha", schema: "alpha" },
+            input: {},
+          },
+        ],
+      },
+      runtime,
+    );
+
+    expect(result.status).toBe("ok");
+    if (result.status === "ok") {
+      expect(result.response.status).toBe("conflict");
+      if (result.response.status === "conflict") {
+        expect(result.response.reason).toBe("limit_exceeded");
+        expect(result.response.confirmedCommandIds).toEqual([]);
+        expect(result.response.lastVersionstamp).toBe("000000000000000000000001");
+      }
+    }
+    expect(stored).toHaveLength(1);
+    expect(stored[0]?.status).toBe("conflict");
+  });
+
+  it("returns client_far_behind when unseen mutations exceed the limit", async () => {
+    const { runtime, stored } = createRuntime({
+      maxUnseenMutations: 1,
+      countOutboxMutations: async () => 2,
+      listOutboxEntries: async () => [createEntry("000000000000000000000002")],
+    });
+
+    const result = await submitSyncRequest(
+      {
+        requestId: "req-3",
+        adapterIdentity: "adapter-1",
+        conflictResolutionStrategy: "server",
+        commands: [
+          {
+            id: "cmd-1",
+            name: "noop",
+            target: { fragment: "alpha", schema: "alpha" },
+            input: {},
+          },
+        ],
+      },
+      runtime,
+    );
+
+    expect(result.status).toBe("ok");
+    if (result.status === "ok") {
+      expect(result.response.status).toBe("conflict");
+      if (result.response.status === "conflict") {
+        expect(result.response.reason).toBe("client_far_behind");
+        expect(result.response.lastVersionstamp).toBe("000000000000000000000002");
+      }
+    }
+    expect(stored).toHaveLength(1);
+    expect(stored[0]?.status).toBe("conflict");
+  });
+
+  it("tracks confirmed command ids on applied requests", async () => {
+    const commandDefs = new Map<string, SyncCommandDefinition>([
+      ["create", { name: "create", handler: async () => undefined }],
+      ["update", { name: "update", handler: async () => undefined }],
+    ]);
+
+    const executeCommand = vi.fn(async () => undefined);
+    const { runtime, stored } = createRuntime({
+      resolveCommand: (_fragment, _schema, name) => {
+        const command = commandDefs.get(name);
+        return command ? { command, namespace: "app" } : undefined;
+      },
+      executeCommand,
+    });
+
+    const result = await submitSyncRequest(
+      {
+        requestId: "req-4",
+        adapterIdentity: "adapter-1",
+        conflictResolutionStrategy: "server",
+        commands: [
+          {
+            id: "cmd-1",
+            name: "create",
+            target: { fragment: "alpha", schema: "alpha" },
+            input: { name: "First" },
+          },
+          {
+            id: "cmd-2",
+            name: "update",
+            target: { fragment: "alpha", schema: "alpha" },
+            input: { name: "Second" },
+          },
+        ],
+      },
+      runtime,
+    );
+
+    expect(result.status).toBe("ok");
+    if (result.status === "ok") {
+      expect(result.response.status).toBe("applied");
+      if (result.response.status === "applied") {
+        expect(result.response.confirmedCommandIds).toEqual(["cmd-1", "cmd-2"]);
+      }
+    }
+    expect(executeCommand).toHaveBeenCalledTimes(2);
+    expect(stored).toHaveLength(1);
+    expect(stored[0]?.status).toBe("applied");
+  });
+});