velocious 1.0.574 → 1.0.576

package/src/sync/sync-envelope-replay-service.js

@@ -3,7 +3,10 @@
 import {deliverDeclaredBroadcasts, upsertSyncRow} from "./sync-change-fanout.js"
 import {markServerApply} from "./sync-publish-suppression.js"
 import {resolveFrontendModelResourceClass} from "../frontend-models/resource-definition.js"
+import {resolveSyncConflict} from "./conflict-strategy.js"
 import SyncReplayUpsertApplier from "./sync-replay-upsert-applier.js"
+import stableJsonStringify from "./stable-json.js"
+import sha256Hex from "../utils/sha256-hex.js"
 import {ValidationError} from "../database/record/index.js"
 import VelociousError from "../velocious-error.js"
 
@@ -16,6 +19,8 @@ import VelociousError from "../velocious-error.js"
  */
 /**
  * @typedef {object} SyncReplayMutation
+ * @property {string | number | null} [baseVersion] - Base server/client version observed by the client.
+ * @property {string} [clientMutationId] - Original client mutation id from the signed envelope.
  * @property {Date} clientUpdatedAt - Client-side mutation timestamp.
  * @property {Record<string, ?>} data - Parsed mutation payload.
  * @property {?} id - Client sync row id for per-sync responses.
@@ -65,6 +70,7 @@ export default class SyncEnvelopeReplayService {
    * @param {(broadcast: {channel: string, params: Record<string, ?>, body: ?}) => Promise<void>} [args.broadcaster] - Delivers declarative broadcasts. Required when broadcasts are configured.
    * @param {SyncReplayBroadcast[]} [args.broadcasts] - Broadcasts fanned out by the default afterReplayMutation.
    * @param {import("../configuration.js").default} [args.configuration] - Configuration whose frontend-model registry routes mutations to resource classes.
+   * @param {{strategy?: "optimisticVersion" | "serverWins", versionAttribute: string} | null} [args.conflictStrategy] - Optional base-version conflict detection for routed upserts. Only `optimisticVersion` and `serverWins` are supported for backend replay because the server does not have the client's base snapshot. When `strategy` is omitted it defaults to `optimisticVersion`, matching `resolveSyncConflict` and normalized resource config. When configured, a mutation whose baseVersion does not match the current server versionAttribute is rejected with a structured conflict result instead of being applied.
    * @param {Record<string, import("../configuration-types.js").FrontendModelResourceClassType | string>} [args.resourceTypeOverrides] - Per-resourceType routing overrides: a resource class, or a string alias resolved through the registry.
    * @param {import("../authorization/ability.js").default} [args.ability] - Ability scoping routed record lookups and create membership checks.
    * @param {Record<string, ?>} [args.abilityContext] - Ability context passed to routed resources.
@@ -83,6 +89,7 @@ export default class SyncEnvelopeReplayService {
     this.broadcasts = args.broadcasts || null
     this.applyHandlers = args.applyHandlers ? this.builtApplyHandlers(args.applyHandlers) : null
     this.configuration = args.configuration || null
+    this.conflictStrategy = args.conflictStrategy || null
     this.resourceTypeOverrides = args.resourceTypeOverrides || null
     this.ability = args.ability || null
     this.abilityContext = args.abilityContext || null
@@ -96,6 +103,16 @@ export default class SyncEnvelopeReplayService {
     if (this.broadcasts && !this.broadcaster) {
       throw new Error("SyncEnvelopeReplayService broadcasts require a broadcaster option delivering them")
     }
+    if (this.conflictStrategy) {
+      const supportedConflictStrategies = new Set(["optimisticVersion", "serverWins"])
+
+      if (!this.conflictStrategy.versionAttribute || typeof this.conflictStrategy.versionAttribute !== "string") {
+        throw new Error("SyncEnvelopeReplayService conflictStrategy requires a non-blank versionAttribute")
+      }
+      if (this.conflictStrategy.strategy !== undefined && !supportedConflictStrategies.has(this.conflictStrategy.strategy)) {
+        throw new Error(`Unsupported sync conflict strategy for backend replay: ${this.conflictStrategy.strategy}. Only optimisticVersion and serverWins are supported.`)
+      }
+    }
   }
 
   /**
@@ -181,6 +198,15 @@ export default class SyncEnvelopeReplayService {
         throw error
       }
 
+      if (applyResult && applyResult.status === "conflict") {
+        syncResponses.push({
+          conflict: applyResult.conflict,
+          id: mutation.id,
+          syncState: "conflict"
+        })
+        continue
+      }
+
       await this.persistReplayMutation({actor: actorResult.actor, context, existingSync, applyResult, mutation, shouldApply})
       await this.afterReplayMutation({actor: actorResult.actor, context, existingSync, applyResult, mutation, shouldApply})
 
@@ -249,7 +275,7 @@ export default class SyncEnvelopeReplayService {
     }
 
     const sync = /** @type {Record<string, ?>} */ (rawSync)
-    const {clientUpdatedAt, data, id, resourceId, resourceType, syncType} = sync
+    const {clientMutationId, clientUpdatedAt, data, id, resourceId, resourceType, syncType} = sync
 
     if (typeof resourceType !== "string" || resourceType.length < 1 || resourceId === undefined || resourceId === null || typeof syncType !== "string" || syncType.length < 1) {
       return {ok: false, response: {id, syncState: "failed", reason: "invalid-resource-id"}}
@@ -267,6 +293,8 @@ export default class SyncEnvelopeReplayService {
     return {
       ok: true,
       mutation: {
+        baseVersion: sync.baseVersion,
+        clientMutationId,
         clientUpdatedAt: clientUpdatedAtDate,
         data: normalizedDataResult.data,
         id,
@@ -644,29 +672,160 @@ export default class SyncEnvelopeReplayService {
    */
   async applyRoutedReplayUpsert({context, mutation, resource}) {
     const attributes = this.permittedRoutedAttributes({mutation, resource})
-    const existingRecord = await resource.findSyncRecord({mutation})
+    const ModelClass = resource.modelClass()
+    const runUpsert = async () => {
+      const existingRecord = await resource.findSyncRecord({mutation})
+      const conflictResult = await this.routedReplayConflictResult({attributes, existingRecord, mutation, resource})
 
-    /** @type {import("../database/record/index.js").default | null} */
-    let record = existingRecord
-    let created = false
+      if (conflictResult) return conflictResult
 
-    if (existingRecord) {
-      const releaseServerApply = markServerApply(existingRecord)
+      /** @type {import("../database/record/index.js").default | null} */
+      let record = existingRecord
+      let created = false
 
-      try {
-        existingRecord.assign(attributes)
-        await this.saveRoutedReplayRecord(existingRecord)
-      } finally {
-        releaseServerApply()
+      if (existingRecord) {
+        const releaseServerApply = markServerApply(existingRecord)
+
+        try {
+          existingRecord.assign(attributes)
+          await this.saveRoutedReplayRecord(existingRecord)
+        } finally {
+          releaseServerApply()
+        }
+      } else {
+        record = await this.createRoutedReplayRecord({attributes, mutation, resource})
+        created = true
+      }
+
+      const extras = await resource.afterSyncApply({context, created, mutation, record})
+
+      return {created, deleted: false, record, ...extras}
+    }
+
+    if (!this.conflictStrategy) return await runUpsert()
+
+    return await ModelClass.withAdvisoryLock(syncReplayConflictLockName({resourceId: mutation.resourceId, resourceType: mutation.resourceType}), runUpsert, {dedicatedConnection: true})
+  }
+
+  /**
+   * Checks whether a routed upsert mutation conflicts with the current server
+   * state when the service is configured with a conflict strategy. A mutation
+   * whose baseVersion does not match the server's current versionAttribute is
+   * rejected with a structured conflict payload instead of being applied.
+   * @param {object} args - Conflict-check args.
+   * @param {Record<string, ?>} args.attributes - Permitted mutation attributes.
+   * @param {import("../database/record/index.js").default | null} args.existingRecord - Existing server record.
+   * @param {import("./sync-envelope-replay-service.js").SyncReplayMutation} args.mutation - Normalized replay mutation.
+   * @param {import("../frontend-model-resource/base-resource.js").default} args.resource - Routed resource instance.
+   * @returns {Promise<Record<string, ?> | null>} - Conflict apply result, or null when no conflict.
+   */
+  async routedReplayConflictResult({attributes, existingRecord, mutation, resource}) {
+    if (!this.conflictStrategy) return null
+    if (!existingRecord || mutation.syncType === "create") return null
+    if (mutation.baseVersion === undefined || mutation.baseVersion === null) return null
+
+    const versionAttribute = this.conflictStrategy.versionAttribute
+    const serverVersion = normalizeConflictValue(existingRecord.readAttribute(versionAttribute))
+
+    if (stableJsonStringify(serverVersion) === stableJsonStringify(mutation.baseVersion)) return null
+
+    const ModelClass = resource.modelClass()
+    const primaryKey = ModelClass.primaryKey()
+    const serializedAffectedAttributes = await this.serializedRoutedConflictAttributes({attributes, existingRecord, resource})
+    const serverAttributes = {
+      ...serializedAffectedAttributes,
+      [primaryKey]: existingRecord.readAttribute(primaryKey),
+      [versionAttribute]: serverVersion
+    }
+
+    const serverRecord = {
+      attributes: serverAttributes,
+      version: serverVersion
+    }
+    const conflictMutation = /** @type {import("./device-identity.js").SyncMutation} */ (/** @type {unknown} */ ({
+      attributes,
+      baseVersion: mutation.baseVersion,
+      clientMutationId: mutation.clientMutationId || mutation.id,
+      model: mutation.resourceType,
+      operation: mutation.syncType,
+      payload: {id: mutation.resourceId}
+    }))
+    const result = await resolveSyncConflict({
+      baseRecord: null,
+      mutation: conflictMutation,
+      serverRecord,
+      strategy: this.conflictStrategy.strategy || "optimisticVersion",
+      versionAttribute
+    })
+
+    if (result.status !== "conflict") return null
+
+    return {conflict: result.conflict, created: false, deleted: false, record: existingRecord, status: "conflict"}
+  }
+
+  /**
+   * Projects affected mutation fields through the resource's readable
+   * attribute contract. Writable-but-hidden fields are omitted, while custom
+   * `<attribute>Attribute(model)` serializers and model accessors remain the
+   * source of frontend-visible values. The full model attribute hash is never
+   * exposed.
+   * @param {object} args - Projection args.
+   * @param {Record<string, ?>} args.attributes - Permitted affected mutation attributes.
+   * @param {import("../database/record/index.js").default} args.existingRecord - Authorized server record.
+   * @param {import("../frontend-model-resource/base-resource.js").default} args.resource - Routed resource instance.
+   * @returns {Promise<Record<string, ?>>} Serialized readable affected attributes.
+   */
+  async serializedRoutedConflictAttributes({attributes, existingRecord, resource}) {
+    const ModelClass = resource.modelClass()
+    const ResourceClass = /** @type {import("../configuration-types.js").FrontendModelResourceClassType} */ (resource.constructor)
+    const readableAttributes = new Set()
+    const configuredAttributes = ResourceClass.resourceConfig().attributes
+    const configuredEntries = Array.isArray(configuredAttributes) ? configuredAttributes : Object.keys(configuredAttributes)
+
+    if (configuredEntries.length === 0) {
+      const attributeNameToColumnName = ModelClass.getAttributeNameToColumnNameMap()
+
+      for (const attributeName of Object.keys(attributeNameToColumnName)) {
+        readableAttributes.add(attributeName)
       }
-    } else {
-      record = await this.createRoutedReplayRecord({attributes, mutation, resource})
-      created = true
     }
 
-    const extras = await resource.afterSyncApply({context, created, mutation, record})
+    for (const configuredAttribute of configuredEntries) {
+      const configuredName = typeof configuredAttribute === "string" ? configuredAttribute : configuredAttribute.name
+
+      if (!configuredName) continue
+
+      const canonicalName = ModelClass.resolveAttributeName(configuredName)
+
+      readableAttributes.add(canonicalName || configuredName)
+    }
+
+    /** @type {Record<string, ?>} */
+    const serializedAttributes = {}
+
+    for (const affectedField of Object.keys(attributes)) {
+      const attributeName = ModelClass.resolveAttributeName(affectedField)
+
+      if (!attributeName || !readableAttributes.has(attributeName)) continue
 
-    return {created, deleted: false, record, ...extras}
+      const resourceAttribute = resource.resourceMethod(`${attributeName}Attribute`)
+
+      if (resourceAttribute) {
+        serializedAttributes[affectedField] = normalizeConflictValue(await resourceAttribute.method.call(resourceAttribute.resource, existingRecord))
+        continue
+      }
+
+      const recordMethods = /** @type {Record<string, ?>} */ (/** @type {unknown} */ (existingRecord))
+      const attributeMethod = recordMethods[attributeName]
+
+      if (typeof attributeMethod === "function") {
+        serializedAttributes[affectedField] = normalizeConflictValue(await attributeMethod.call(existingRecord))
+      } else {
+        serializedAttributes[affectedField] = normalizeConflictValue(existingRecord.readAttribute(attributeName))
+      }
+    }
+
+    return serializedAttributes
   }
 
   /**
@@ -890,3 +1049,32 @@ export default class SyncEnvelopeReplayService {
     await deliverDeclaredBroadcasts({args, broadcaster: this.broadcaster, broadcasts: this.broadcasts})
   }
 }
+
+/**
+ * Returns a deterministic, MySQL-safe advisory-lock name for a routed replay
+ * resource identity. The full `{resourceType, resourceId}` identity is hashed
+ * with SHA-256 and truncated to 32 hex characters so the final name stays well
+ * under MySQL/MariaDB's 64-character `GET_LOCK` limit while remaining
+ * collision-resistant.
+ * @param {object} args - Lock identity args.
+ * @param {string} args.resourceId - Resource id.
+ * @param {string} args.resourceType - Resource type.
+ * @returns {string} - Advisory lock name.
+ */
+export function syncReplayConflictLockName({resourceId, resourceType}) {
+  const identity = stableJsonStringify({resourceId, resourceType})
+  const hash = sha256Hex(identity).slice(0, 32)
+
+  return `vsr:${hash}`
+}
+
+/**
+ * Normalizes an authoritative conflict value for JSON transport and deterministic comparison.
+ * @param {?} value - Raw value from a database record.
+ * @returns {?} - Normalized value (Date values become ISO strings).
+ */
+function normalizeConflictValue(value) {
+  if (value instanceof Date) return value.toISOString()
+
+  return value
+}

package/src/testing/test-runner.js

@@ -828,24 +828,22 @@ export default class TestRunner {
     process.on("uncaughtException", onUncaughtException)
 
     try {
-      await this.getConfiguration().ensureConnections({name: "Test runner suite"}, async () => {
-        await this.runTests({
-          afterEaches: [],
-          beforeEaches: [],
-          tests,
-          descriptions: [],
-          indentLevel: 0
-        })
-
-        // A rejection scheduled by the final test (a detached rejected promise,
-        // or an afterCommit callback rejecting as the suite drains) is reported
-        // by Node on a LATER turn. Drain a few turns while the handler is still
-        // attached — and connections still open — so those late rejections are
-        // recorded instead of escaping to the default crash path after cleanup.
-        for (let drainTurn = 0; drainTurn < 3; drainTurn++) {
-          await new Promise((resolve) => setImmediate(resolve))
-        }
+      await this.runTests({
+        afterEaches: [],
+        beforeEaches: [],
+        tests,
+        descriptions: [],
+        indentLevel: 0
       })
+
+      // A rejection scheduled by the final test (a detached rejected promise,
+      // or an afterCommit callback rejecting as the suite drains) is reported
+      // by Node on a LATER turn. Drain a few turns while the handler is still
+      // attached so those late rejections are recorded instead of escaping to
+      // the default crash path after cleanup.
+      for (let drainTurn = 0; drainTurn < 3; drainTurn++) {
+        await new Promise((resolve) => setImmediate(resolve))
+      }
     } finally {
       process.off("unhandledRejection", onUnhandledRejection)
       process.off("uncaughtException", onUncaughtException)
@@ -1005,11 +1003,8 @@ export default class TestRunner {
               // Pin one connection per test so beforeEach, the test body and afterEach
               // all run on the SAME connection. This is required for transaction-based
               // database cleaning (beforeEach starts a transaction, afterEach rolls it
-              // back). ensureConnections reuses the suite-level pinned connection while
-              // it is healthy and transparently re-establishes a per-test pin if an
-              // earlier spec closed the suite connection (which would otherwise leave a
-              // stale async-context pin and force every later test onto a fresh checkout,
-              // breaking isolation).
+              // back). Releasing the lease after each lifecycle also runs the pool's
+              // session cleanup before another test can reuse the connection.
               await this.getConfiguration().ensureConnections({name: `Test: ${testDescription}`}, async () => {
                 // Register dynamic candidates before application hooks so transaction
                 // state changes made during a hook are visible to a request dispatched

package/src/utils/sha256-hex.js

@@ -0,0 +1,141 @@
+/**
+ * Computes SHA-256 without importing Node-only crypto modules, keeping this
+ * module safe for Expo/browser bundles. Implementation is a straightforward
+ * pure-JavaScript SHA-256 derived from FIPS 180-4, using only 32-bit unsigned
+ * integer arithmetic.
+ * @param {string} message - UTF-8 message.
+ * @returns {string} - Hex digest.
+ */
+export default function sha256Hex(message) {
+  const bytes = utf8Bytes(message)
+  const padded = [...bytes]
+  const bitLength = bytes.length * 8
+  const hash = [...SHA256_INITIAL_HASH]
+  /** @type {number[]} */
+  const words = new Array(64)
+
+  padded.push(0x80)
+  while (padded.length % 64 !== 56) padded.push(0)
+
+  const highLength = Math.floor(bitLength / 0x100000000)
+  const lowLength = bitLength >>> 0
+
+  for (const value of [highLength, lowLength]) {
+    padded.push((value >>> 24) & 0xff, (value >>> 16) & 0xff, (value >>> 8) & 0xff, value & 0xff)
+  }
+
+  for (let offset = 0; offset < padded.length; offset += 64) {
+    for (let i = 0; i < 16; i++) {
+      const index = offset + (i * 4)
+
+      words[i] = (((padded[index] || 0) << 24) | ((padded[index + 1] || 0) << 16) | ((padded[index + 2] || 0) << 8) | (padded[index + 3] || 0)) >>> 0
+    }
+
+    for (let i = 16; i < 64; i++) {
+      const s0 = rotateRight(words[i - 15], 7) ^ rotateRight(words[i - 15], 18) ^ (words[i - 15] >>> 3)
+      const s1 = rotateRight(words[i - 2], 17) ^ rotateRight(words[i - 2], 19) ^ (words[i - 2] >>> 10)
+
+      words[i] = add32(words[i - 16], s0, words[i - 7], s1)
+    }
+
+    let [a, b, c, d, e, f, g, h] = hash
+
+    for (let i = 0; i < 64; i++) {
+      const s1 = rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25)
+      const ch = (e & f) ^ ((~e) & g)
+      const temp1 = add32(h, s1, ch, SHA256_K[i], words[i])
+      const s0 = rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22)
+      const maj = (a & b) ^ (a & c) ^ (b & c)
+      const temp2 = add32(s0, maj)
+
+      h = g
+      g = f
+      f = e
+      e = add32(d, temp1)
+      d = c
+      c = b
+      b = a
+      a = add32(temp1, temp2)
+    }
+
+    hash[0] = add32(hash[0], a)
+    hash[1] = add32(hash[1], b)
+    hash[2] = add32(hash[2], c)
+    hash[3] = add32(hash[3], d)
+    hash[4] = add32(hash[4], e)
+    hash[5] = add32(hash[5], f)
+    hash[6] = add32(hash[6], g)
+    hash[7] = add32(hash[7], h)
+  }
+
+  return hash.map((value) => value.toString(16).padStart(8, "0")).join("")
+}
+
+const SHA256_INITIAL_HASH = [
+  0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a,
+  0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19
+]
+
+const SHA256_K = [
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5,
+  0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+  0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc,
+  0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7,
+  0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+  0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3,
+  0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5,
+  0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+  0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2
+]
+
+/**
+ * Converts a string to UTF-8 bytes.
+ * @param {string} value - String value.
+ * @returns {number[]} - UTF-8 bytes.
+ */
+function utf8Bytes(value) {
+  /** @type {number[]} */
+  const bytes = []
+
+  for (const character of value) {
+    const codePoint = /** @type {number} */ (character.codePointAt(0))
+
+    if (codePoint <= 0x7f) {
+      bytes.push(codePoint)
+    } else if (codePoint <= 0x7ff) {
+      bytes.push(0xc0 | (codePoint >>> 6), 0x80 | (codePoint & 0x3f))
+    } else if (codePoint <= 0xffff) {
+      bytes.push(0xe0 | (codePoint >>> 12), 0x80 | ((codePoint >>> 6) & 0x3f), 0x80 | (codePoint & 0x3f))
+    } else {
+      bytes.push(0xf0 | (codePoint >>> 18), 0x80 | ((codePoint >>> 12) & 0x3f), 0x80 | ((codePoint >>> 6) & 0x3f), 0x80 | (codePoint & 0x3f))
+    }
+  }
+
+  return bytes
+}
+
+/**
+ * Adds unsigned 32-bit integers.
+ * @param {...number} values - Values to add.
+ * @returns {number} - Unsigned 32-bit result.
+ */
+function add32(...values) {
+  return values.reduce((sum, value) => (sum + value) >>> 0, 0)
+}
+
+/**
+ * Rotates a 32-bit integer right.
+ * @param {number} value - Value to rotate.
+ * @param {number} bits - Bit count.
+ * @returns {number} - Rotated value.
+ */
+function rotateRight(value, bits) {
+  return (value >>> bits) | (value << (32 - bits))
+}