velocious 1.0.476 → 1.0.477

package/build/sync/conflict-strategy.js

@@ -0,0 +1,225 @@
+// @ts-check
+
+const CONFLICT_STRATEGIES = new Set(["optimisticVersion", "serverWins", "lastWriterWins", "fieldThreeWay", "appendOnly"])
+
+/**
+ * @typedef {null | string | number | boolean | unknown[] | Record<string, unknown>} SyncJsonValue
+ */
+
+/**
+ * @typedef {object} SyncConflictRecord
+ * @property {Record<string, SyncJsonValue>} attributes - Record attributes.
+ * @property {string | number | boolean | null} [version] - Record version value.
+ */
+
+/**
+ * @typedef {object} SyncConflictResult
+ * @property {Record<string, SyncJsonValue>} [attributes] - Attributes to apply when replay may continue.
+ * @property {Record<string, SyncJsonValue>} [conflict] - Structured conflict payload for the client/local log.
+ * @property {"applied" | "conflict" | "rejected"} status - Conflict decision.
+ * @property {string} strategy - Strategy that produced the decision.
+ */
+
+/**
+ * Evaluates a replay mutation against server/base state using a sync conflict strategy.
+ * @param {object} args - Arguments.
+ * @param {SyncConflictRecord | null} [args.baseRecord] - Record state observed when the mutation was made.
+ * @param {function(object): (SyncConflictResult | Promise<SyncConflictResult>)} [args.customHandler] - Resource-specific conflict hook.
+ * @param {import("./device-identity.js").SyncMutation} args.mutation - Replayed mutation.
+ * @param {SyncConflictRecord | null} [args.serverRecord] - Current authoritative server record.
+ * @param {string} [args.strategy] - Conflict strategy.
+ * @param {string} [args.versionAttribute] - Attribute used for optimistic version checks.
+ * @returns {Promise<SyncConflictResult>} - Conflict decision.
+ */
+export async function resolveSyncConflict({baseRecord = null, customHandler, mutation, serverRecord = null, strategy = "optimisticVersion", versionAttribute = "updatedAt"}) {
+  if (customHandler) return normalizeConflictResult(await customHandler({baseRecord, mutation, serverRecord, strategy, versionAttribute}), strategy)
+  if (!CONFLICT_STRATEGIES.has(strategy)) throw new Error(`Unknown sync conflict strategy '${strategy}'`)
+
+  const mutationAttributes = mutationAttributesFor(mutation)
+
+  if (strategy === "appendOnly" || strategy === "lastWriterWins") return {attributes: mutationAttributes, status: "applied", strategy}
+  if (strategy === "fieldThreeWay") return fieldThreeWayResult({baseRecord, mutation, serverRecord, strategy, versionAttribute})
+  if (hasVersionConflict({mutation, serverRecord, versionAttribute})) return conflictResult({baseRecord, mutation, serverRecord, strategy, versionAttribute})
+
+  return {attributes: mutationAttributes, status: "applied", strategy}
+}
+
+/**
+ * Applies a server replay result to a local mutation-log record.
+ * @param {object} args - Arguments.
+ * @param {import("./local-mutation-log.js").default} args.mutationLog - Local mutation log.
+ * @param {import("./local-mutation-log.js").LocalMutationLogRecord} args.record - Local mutation-log record.
+ * @param {Record<string, SyncJsonValue>} args.result - Server replay result payload.
+ * @returns {Promise<import("./local-mutation-log.js").LocalMutationLogRecord>} - Updated local record.
+ */
+export async function applySyncReplayResultToLocalMutationLog({mutationLog, record, result}) {
+  return await mutationLog.updateStatus({
+    id: record.id,
+    status: replayResultLocalStatus(result),
+    syncResult: result
+  })
+}
+
+/**
+ * Maps a server replay result to a local mutation-log status.
+ * @param {Record<string, SyncJsonValue>} result - Replay result.
+ * @returns {import("./local-mutation-log.js").LocalMutationStatus} - Local mutation-log status.
+ */
+export function replayResultLocalStatus(result) {
+  if (result.status === "conflict") return "conflict"
+  if (result.status === "error" || result.status === "rejected") return "rejected"
+  if (result.status === "success" && replayResultHasFailedApplication(result)) return "rejected"
+  if (result.status === "success" || result.status === "applied" || result.status === "duplicate") return "synced"
+
+  throw new Error(`Unknown sync replay result status '${String(result.status)}'`)
+}
+
+/**
+ * Checks whether an otherwise successful replay result contains a failed
+ * frontend-model command or change-feed write.
+ * @param {Record<string, SyncJsonValue>} result - Replay result.
+ * @returns {boolean} - Whether the local mutation must stay unsynced.
+ */
+function replayResultHasFailedApplication(result) {
+  if (result.serverSequence === null || result.serverChangeFeedStatus === "error") return true
+  if (!result.response || typeof result.response !== "object" || Array.isArray(result.response)) return false
+
+  return /** @type {Record<string, SyncJsonValue>} */ (result.response).status === "error"
+}
+
+/**
+ * Runs a field-level three-way merge.
+ * @param {object} args - Arguments.
+ * @param {SyncConflictRecord | null} args.baseRecord - Base record.
+ * @param {import("./device-identity.js").SyncMutation} args.mutation - Mutation.
+ * @param {SyncConflictRecord | null} args.serverRecord - Server record.
+ * @param {string} args.strategy - Strategy.
+ * @param {string} args.versionAttribute - Version attribute.
+ * @returns {SyncConflictResult} - Conflict decision.
+ */
+function fieldThreeWayResult({baseRecord, mutation, serverRecord, strategy, versionAttribute}) {
+  if (!baseRecord || !serverRecord) return {attributes: mutationAttributesFor(mutation), status: "applied", strategy}
+
+  const mutationAttributes = mutationAttributesFor(mutation)
+  /** @type {string[]} */
+  const affectedFields = []
+  /** @type {Record<string, SyncJsonValue>} */
+  const mergedAttributes = {}
+
+  for (const [field, localValue] of Object.entries(mutationAttributes)) {
+    const baseValue = baseRecord.attributes[field]
+    const serverValue = serverRecord.attributes[field]
+
+    if (jsonValuesEqual(serverValue, baseValue) || jsonValuesEqual(serverValue, localValue)) {
+      mergedAttributes[field] = localValue
+    } else {
+      affectedFields.push(field)
+    }
+  }
+
+  if (affectedFields.length > 0) return conflictResult({affectedFields, baseRecord, mutation, serverRecord, strategy, versionAttribute})
+
+  return {attributes: mergedAttributes, status: "applied", strategy}
+}
+
+/**
+ * Checks whether current server state conflicts with a mutation base version.
+ * @param {object} args - Arguments.
+ * @param {import("./device-identity.js").SyncMutation} args.mutation - Mutation.
+ * @param {SyncConflictRecord | null} args.serverRecord - Server record.
+ * @param {string} args.versionAttribute - Version attribute.
+ * @returns {boolean} - Whether versions conflict.
+ */
+function hasVersionConflict({mutation, serverRecord, versionAttribute}) {
+  if (!serverRecord) return false
+  if (mutation.baseVersion === undefined || mutation.baseVersion === null) return false
+
+  const serverVersion = serverRecord.version ?? serverRecord.attributes[versionAttribute] ?? null
+
+  return !jsonValuesEqual(serverVersion, mutation.baseVersion)
+}
+
+/**
+ * Builds a structured conflict result.
+ * @param {object} args - Arguments.
+ * @param {string[]} [args.affectedFields] - Explicit affected fields.
+ * @param {SyncConflictRecord | null} args.baseRecord - Base record.
+ * @param {import("./device-identity.js").SyncMutation} args.mutation - Mutation.
+ * @param {SyncConflictRecord | null} args.serverRecord - Server record.
+ * @param {string} args.strategy - Strategy.
+ * @param {string} args.versionAttribute - Version attribute.
+ * @returns {SyncConflictResult} - Conflict result.
+ */
+function conflictResult({affectedFields, baseRecord, mutation, serverRecord, strategy, versionAttribute}) {
+  const mutationAttributes = mutationAttributesFor(mutation)
+
+  return {
+    conflict: {
+      affectedFields: affectedFields || Object.keys(mutationAttributes),
+      baseRecord: baseRecord ? baseRecord.attributes : null,
+      baseVersion: /** @type {SyncJsonValue} */ (mutation.baseVersion ?? null),
+      localMutation: {
+        attributes: mutationAttributes,
+        clientMutationId: mutation.clientMutationId,
+        model: mutation.model,
+        operation: mutation.operation,
+        payload: /** @type {SyncJsonValue} */ (mutation.payload || null)
+      },
+      serverModel: serverRecord ? serverRecord.attributes : null,
+      serverVersion: serverRecord ? /** @type {SyncJsonValue} */ (serverRecord.version ?? serverRecord.attributes[versionAttribute] ?? null) : null,
+      suggestedResolution: strategy === "serverWins" ? "keep_server" : "manual",
+      versionAttribute
+    },
+    status: "conflict",
+    strategy
+  }
+}
+
+/**
+ * Normalizes a custom resource conflict result.
+ * @param {unknown} result - Raw result.
+ * @param {string} strategy - Requested strategy.
+ * @returns {SyncConflictResult} - Normalized result.
+ */
+function normalizeConflictResult(result, strategy) {
+  if (!result || typeof result !== "object" || Array.isArray(result)) throw new Error("Sync conflict handler must return an object")
+  const resultRecord = /** @type {Record<string, unknown>} */ (result)
+  if (!["applied", "conflict", "rejected"].includes(String(resultRecord.status))) throw new Error("Sync conflict handler returned an unknown status")
+
+  return /** @type {SyncConflictResult} */ ({strategy, ...resultRecord})
+}
+
+/**
+ * Returns mutation attributes as a JSON object.
+ * @param {import("./device-identity.js").SyncMutation} mutation - Mutation.
+ * @returns {Record<string, SyncJsonValue>} - Attributes.
+ */
+function mutationAttributesFor(mutation) {
+  if (!mutation.attributes || typeof mutation.attributes !== "object" || Array.isArray(mutation.attributes)) return {}
+
+  return /** @type {Record<string, SyncJsonValue>} */ (JSON.parse(JSON.stringify(mutation.attributes)))
+}
+
+/**
+ * Compares JSON values by stable serialization.
+ * @param {unknown} left - Left value.
+ * @param {unknown} right - Right value.
+ * @returns {boolean} - Whether values match.
+ */
+function jsonValuesEqual(left, right) {
+  return stableJsonStringify(left) === stableJsonStringify(right)
+}
+
+/**
+ * Stable JSON stringify helper.
+ * @param {unknown} value - Value.
+ * @returns {string} - Stable JSON.
+ */
+function stableJsonStringify(value) {
+  if (Array.isArray(value)) return `[${value.map((entry) => stableJsonStringify(entry)).join(",")}]`
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJsonStringify(/** @type {Record<string, unknown>} */ (value)[key])}`).join(",")}}`
+  }
+
+  return JSON.stringify(value)
+}

package/build/sync/peer-mutation-bundle.js

@@ -0,0 +1,232 @@
+// @ts-check
+
+import {createSignedMutation, mutationIdempotencyKey, verifySignedMutation} from "./device-identity.js"
+
+const PEER_MUTATION_BUNDLE_FORMAT = "velocious.sync.peer-mutation-bundle.v1"
+const EXPORTABLE_STATUSES = new Set(["pending", "applied-locally", "conflict"])
+
+/**
+ * Peer mutation bundle exported by a device for offline/P2P transfer.
+ * @typedef {object} PeerMutationBundle
+ * @property {string} exportedAt - ISO timestamp when the bundle was exported.
+ * @property {"velocious.sync.peer-mutation-bundle.v1"} format - Bundle format identifier.
+ * @property {PeerMutationBundleEntry[]} mutations - Signed mutations in local sequence order.
+ */
+
+/**
+ * One peer mutation bundle entry.
+ * @typedef {object} PeerMutationBundleEntry
+ * @property {string} [localRecordId] - Exporting device's local mutation record id.
+ * @property {number} [localSequence] - Exporting device's local mutation sequence.
+ * @property {import("./device-identity.js").SignedSyncMutation} signedMutation - Device-signed mutation envelope.
+ */
+
+/**
+ * Exports local non-terminal mutations as a signed peer-transfer bundle.
+ * @param {object} args - Arguments.
+ * @param {import("./device-identity.js").DeviceCertificate} args.deviceCertificate - Device certificate for signing records.
+ * @param {import("./device-identity.js").SyncJsonWebKey} args.devicePrivateKey - Device private key for signing records.
+ * @param {import("./local-mutation-log.js").default} args.mutationLog - Local mutation log.
+ * @param {() => Date} [args.now] - Export clock.
+ * @param {import("./local-mutation-log.js").LocalMutationStatus[]} [args.statuses] - Statuses to export.
+ * @returns {Promise<PeerMutationBundle>} - Signed peer mutation bundle.
+ */
+export async function exportPeerMutationBundle({deviceCertificate, devicePrivateKey, mutationLog, now = () => new Date(), statuses}) {
+  const selectedStatuses = normalizeExportStatuses(statuses)
+  const timestamp = isoTimestamp(now(), "exportedAt")
+  const records = (await mutationLog.records())
+    .filter((record) => selectedStatuses.has(record.status))
+    .sort((left, right) => left.sequence - right.sequence)
+  const mutations = []
+
+  for (const record of records) {
+    mutations.push({
+      localRecordId: record.id,
+      localSequence: record.sequence,
+      signedMutation: await createSignedMutation({
+        deviceCertificate,
+        devicePrivateKey,
+        mutation: record.mutation
+      })
+    })
+  }
+
+  return {
+    exportedAt: timestamp,
+    format: PEER_MUTATION_BUNDLE_FORMAT,
+    mutations
+  }
+}
+
+/**
+ * Imports verified peer mutations into the local mutation log.
+ * @param {object} args - Arguments.
+ * @param {import("./device-identity.js").SyncJsonWebKey} args.backendPublicKey - Backend public key for verifying peer certificates.
+ * @param {PeerMutationBundle} args.bundle - Peer bundle to import.
+ * @param {import("./local-mutation-log.js").default} args.mutationLog - Local mutation log.
+ * @param {Date} [args.now] - Verification time.
+ * @returns {Promise<{imported: {clientMutationId: string, idempotencyKey: string, localRecordId: string}[], rejected: {errorMessage: string, index: number}[], skipped: {clientMutationId: string, idempotencyKey: string, localRecordId: string, reason: "duplicate"}[]}>} - Import result.
+ */
+export async function importPeerMutationBundle({backendPublicKey, bundle, mutationLog, now = new Date()}) {
+  const normalizedBundle = normalizePeerMutationBundle(bundle)
+  const existingRecords = await mutationLog.records()
+  const existingByIdempotencyKey = new Map(existingRecords.map((record) => [mutationIdempotencyKey({mutation: record.mutation}), record]))
+  /** @type {{clientMutationId: string, idempotencyKey: string, localRecordId: string}[]} */
+  const imported = []
+  /** @type {{errorMessage: string, index: number}[]} */
+  const rejected = []
+  /** @type {{clientMutationId: string, idempotencyKey: string, localRecordId: string, reason: "duplicate"}[]} */
+  const skipped = []
+
+  for (const [index, entry] of normalizedBundle.mutations.entries()) {
+    const mutation = await verifiedBundleMutation({backendPublicKey, entry, index, now, rejected})
+
+    if (!mutation) continue
+
+    const idempotencyKey = mutationIdempotencyKey(entry.signedMutation)
+    const duplicateRecord = existingByIdempotencyKey.get(idempotencyKey)
+
+    if (duplicateRecord) {
+      skipped.push({
+        clientMutationId: mutation.clientMutationId,
+        idempotencyKey,
+        localRecordId: duplicateRecord.id,
+        reason: /** @type {"duplicate"} */ ("duplicate")
+      })
+      continue
+    }
+
+    const record = await mutationLog.append({mutation})
+    const updated = await mutationLog.updateStatus({id: record.id, status: "peer-applied"})
+    existingByIdempotencyKey.set(idempotencyKey, updated)
+    imported.push({clientMutationId: mutation.clientMutationId, idempotencyKey, localRecordId: updated.id})
+  }
+
+  return {imported, rejected, skipped}
+}
+
+/**
+ * Verifies a bundle mutation and records normal per-entry verification rejections.
+ * Storage writes intentionally happen outside this helper so storage failures escape import.
+ * @param {object} args - Arguments.
+ * @param {import("./device-identity.js").SyncJsonWebKey} args.backendPublicKey - Backend public key.
+ * @param {PeerMutationBundleEntry} args.entry - Bundle entry.
+ * @param {number} args.index - Entry index.
+ * @param {Date} args.now - Verification time.
+ * @param {{errorMessage: string, index: number}[]} args.rejected - Rejection accumulator.
+ * @returns {Promise<import("./device-identity.js").SyncMutation | null>} - Verified mutation, or null when rejected.
+ */
+async function verifiedBundleMutation({backendPublicKey, entry, index, now, rejected}) {
+  try {
+    return await verifySignedMutation({backendPublicKey, now, signedMutation: entry.signedMutation})
+  } catch (error) {
+    rejected.push({errorMessage: errorMessage(error), index})
+
+    return null
+  }
+}
+
+/**
+ * Normalizes export status filters.
+ * @param {import("./local-mutation-log.js").LocalMutationStatus[] | undefined} statuses - Optional statuses.
+ * @returns {Set<import("./local-mutation-log.js").LocalMutationStatus>} - Status set.
+ */
+function normalizeExportStatuses(statuses) {
+  if (statuses === undefined) return /** @type {Set<import("./local-mutation-log.js").LocalMutationStatus>} */ (new Set(EXPORTABLE_STATUSES))
+  if (!Array.isArray(statuses)) throw new Error("Expected peer mutation export statuses array")
+
+  const normalized = new Set()
+
+  for (const status of statuses) {
+    if (!EXPORTABLE_STATUSES.has(status)) throw new Error(`Unsupported peer mutation export status '${String(status)}'`)
+    normalized.add(status)
+  }
+
+  return /** @type {Set<import("./local-mutation-log.js").LocalMutationStatus>} */ (normalized)
+}
+
+/**
+ * Normalizes a peer mutation bundle.
+ * @param {PeerMutationBundle} bundle - Bundle value.
+ * @returns {PeerMutationBundle} - Normalized bundle.
+ */
+function normalizePeerMutationBundle(bundle) {
+  if (!bundle || typeof bundle !== "object" || Array.isArray(bundle)) throw new Error("Expected peer mutation bundle object")
+  if (bundle.format !== PEER_MUTATION_BUNDLE_FORMAT) throw new Error(`Unsupported peer mutation bundle format '${String(bundle.format)}'`)
+  isoTimestamp(new Date(requiredString(bundle.exportedAt, "exportedAt")), "exportedAt")
+  if (!Array.isArray(bundle.mutations)) throw new Error("Expected peer mutation bundle mutations array")
+
+  return {
+    exportedAt: bundle.exportedAt,
+    format: bundle.format,
+    mutations: bundle.mutations.map((entry, index) => normalizePeerMutationBundleEntry(entry, index))
+  }
+}
+
+/**
+ * Normalizes one peer mutation bundle entry.
+ * @param {PeerMutationBundleEntry} entry - Bundle entry.
+ * @param {number} index - Entry index.
+ * @returns {PeerMutationBundleEntry} - Normalized entry.
+ */
+function normalizePeerMutationBundleEntry(entry, index) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw new Error(`Expected peer mutation bundle entry ${index} object`)
+  if (!entry.signedMutation || typeof entry.signedMutation !== "object" || Array.isArray(entry.signedMutation)) throw new Error(`Expected peer mutation bundle entry ${index} signedMutation object`)
+
+  /** @type {PeerMutationBundleEntry} */
+  const normalized = {
+    signedMutation: entry.signedMutation
+  }
+
+  if (entry.localRecordId !== undefined) normalized.localRecordId = requiredString(entry.localRecordId, `entry ${index} localRecordId`)
+  if (entry.localSequence !== undefined) normalized.localSequence = positiveInteger(entry.localSequence, `entry ${index} localSequence`)
+
+  return normalized
+}
+
+/**
+ * Requires a non-empty string.
+ * @param {unknown} value - Value.
+ * @param {string} label - Label.
+ * @returns {string} - String.
+ */
+function requiredString(value, label) {
+  if (typeof value !== "string" || value.length < 1) throw new Error(`Expected peer mutation bundle ${label}`)
+
+  return value
+}
+
+/**
+ * Requires a positive integer.
+ * @param {unknown} value - Value.
+ * @param {string} label - Label.
+ * @returns {number} - Integer.
+ */
+function positiveInteger(value, label) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) throw new Error(`Expected peer mutation bundle ${label} positive integer`)
+
+  return value
+}
+
+/**
+ * Returns an ISO timestamp from a valid Date.
+ * @param {Date} date - Date.
+ * @param {string} label - Label.
+ * @returns {string} - ISO timestamp.
+ */
+function isoTimestamp(date, label) {
+  if (!(date instanceof Date) || Number.isNaN(date.getTime())) throw new Error(`Invalid peer mutation bundle ${label}`)
+
+  return date.toISOString()
+}
+
+/**
+ * Returns a safe error message.
+ * @param {unknown} error - Error.
+ * @returns {string} - Message.
+ */
+function errorMessage(error) {
+  if (error instanceof Error) return error.message
+
+  return String(error)
+}