velocious 1.0.475 → 1.0.477

package/src/frontend-models/resource-definition.js

@@ -288,7 +288,7 @@ function normalizeFrontendModelResourceSync(resourceConfiguration) {
   const sync = resourceConfiguration.sync
 
   if (sync === undefined || sync === null) return undefined
-  if (sync === false) return {enabled: false, operations: [], policyHash: syncPolicyHash({enabled: false}), policyVersion: null}
+  if (sync === false) return {conflictStrategy: "optimisticVersion", enabled: false, operations: [], policyHash: syncPolicyHash({conflictStrategy: "optimisticVersion", enabled: false}), policyVersion: null}
   if (sync === true) {
     return normalizeFrontendModelResourceSync({
       ...resourceConfiguration,
@@ -299,18 +299,20 @@ function normalizeFrontendModelResourceSync(resourceConfiguration) {
     throw new Error("Resource sync configuration must be true, false, or an object.")
   }
 
-  const {enabled = true, metadata, operations, policy, policyVersion, ...rest} = /** @type {import("../configuration-types.js").FrontendModelResourceSyncConfiguration} */ (sync)
+  const {conflictStrategy, enabled = true, metadata, operations, policy, policyVersion, ...rest} = /** @type {import("../configuration-types.js").FrontendModelResourceSyncConfiguration} */ (sync)
 
   if (Object.keys(rest).length > 0) {
-    throw new Error(`Unexpected sync keys: ${Object.keys(rest).join(", ")}. Allowed: enabled, metadata, operations, policy, policyVersion`)
+    throw new Error(`Unexpected sync keys: ${Object.keys(rest).join(", ")}. Allowed: conflictStrategy, enabled, metadata, operations, policy, policyVersion`)
   }
   if (enabled !== true && enabled !== false) throw new Error("Resource sync enabled must be true or false when provided.")
 
+  const normalizedConflictStrategy = normalizeSyncConflictStrategy(conflictStrategy)
   const normalizedOperations = normalizeSyncOperations(operations)
   const normalizedMetadata = metadata === undefined ? undefined : deterministicSyncJson({label: "metadata", value: metadata})
   const normalizedPolicy = policy === undefined ? undefined : deterministicSyncJson({label: "policy", value: policy})
   const normalizedPolicyVersion = policyVersion === undefined || policyVersion === null ? null : String(policyVersion)
   const hashInput = {
+    conflictStrategy: normalizedConflictStrategy,
     enabled,
     metadata: normalizedMetadata,
     modelName: resourceConfiguration.modelName || null,
@@ -320,6 +322,7 @@ function normalizeFrontendModelResourceSync(resourceConfiguration) {
   }
   /** @type {import("../configuration-types.js").NormalizedFrontendModelResourceSyncConfiguration} */
   const normalized = {
+    conflictStrategy: normalizedConflictStrategy,
     enabled,
     operations: normalizedOperations,
     policyHash: syncPolicyHash(hashInput),
@@ -331,6 +334,20 @@ function normalizeFrontendModelResourceSync(resourceConfiguration) {
   return normalized
 }
 
+/**
+ * Normalizes the sync conflict strategy for replay clients/servers.
+ * @param {unknown} conflictStrategy - Raw strategy.
+ * @returns {"optimisticVersion" | "serverWins" | "lastWriterWins" | "fieldThreeWay" | "appendOnly"} - Normalized strategy.
+ */
+function normalizeSyncConflictStrategy(conflictStrategy) {
+  if (conflictStrategy === undefined || conflictStrategy === null) return "optimisticVersion"
+  if (["optimisticVersion", "serverWins", "lastWriterWins", "fieldThreeWay", "appendOnly"].includes(String(conflictStrategy))) {
+    return /** @type {"optimisticVersion" | "serverWins" | "lastWriterWins" | "fieldThreeWay" | "appendOnly"} */ (conflictStrategy)
+  }
+
+  throw new Error(`Unknown resource sync conflictStrategy: ${String(conflictStrategy)}`)
+}
+
 /**
  * Normalizes sync operations into a stable, duplicate-free list.
  * @param {unknown} operations - Raw operations value.

package/src/http-server/client/websocket-session.js

@@ -199,6 +199,24 @@ export default class VelociousHttpServerClientWebsocketSession {
     this._fragmentedBytes = 0
 
     this.configuration._websocketSessions.add(this)
+
+    /**
+     * Heartbeat liveness flag. Set true on every inbound frame
+     * (including the client's auto-pong) and cleared each time a ping
+     * is sent; a still-false flag at the next tick means the socket
+     * has gone silent.
+     * @type {boolean}
+     */
+    this._heartbeatAlive = true
+
+    /**
+     * Per-session heartbeat interval handle. Started from
+     * `sendSessionEstablished` once the socket is live, not at
+     * construction, so directly-constructed sessions in tests don't
+     * spin up a background timer.
+     * @type {ReturnType<typeof setInterval> | null}
+     */
+    this._heartbeatTimer = null
   }
 
   /**
@@ -212,6 +230,9 @@ export default class VelociousHttpServerClientWebsocketSession {
       sessionId: this.sessionId,
       graceSeconds: this.configuration.getWebsocketSessionGraceSeconds?.() || 300
     })
+
+    // The socket is live now, so begin reaping it if it goes silent.
+    this._startHeartbeat()
   }
 
   /**
@@ -251,6 +272,7 @@ export default class VelociousHttpServerClientWebsocketSession {
   }
 
   destroy() {
+    this._stopHeartbeat()
     this.configuration._websocketSessions.delete(this)
     this._paused = false
     void this._teardownChannel()
@@ -274,6 +296,11 @@ export default class VelociousHttpServerClientWebsocketSession {
    * @returns {void} - No return value.
    */
   onData(data) {
+    // Any inbound bytes — a data frame, the auto-pong answering our
+    // heartbeat, or a partial frame still being uploaded — prove the
+    // socket is alive. Mark it here, before `_processBuffer` may return
+    // early waiting for the rest of an incomplete frame.
+    this._heartbeatAlive = true
     this.buffer = Buffer.concat([this.buffer, data])
     this._processBuffer()
   }
@@ -611,6 +638,11 @@ export default class VelociousHttpServerClientWebsocketSession {
         continue
       }
 
+      if (opcode === WEBSOCKET_OPCODE_PONG) {
+        // Answer to a heartbeat ping; liveness is recorded in onData.
+        continue
+      }
+
       if (opcode >= 0x8) {
         this.logger.warn(`Unsupported websocket control opcode: ${opcode}`)
         continue
@@ -756,6 +788,60 @@ export default class VelociousHttpServerClientWebsocketSession {
     this._fragmentedBytes = 0
   }
 
+  /**
+   * Starts the per-session heartbeat. Each tick pings the client and
+   * reaps the session if the previous ping went unanswered, so a
+   * half-open socket (client gone without a TCP FIN / close frame)
+   * cannot linger forever holding channel subscriptions. Disabled when
+   * the configured interval is 0.
+   * @returns {void}
+   */
+  _startHeartbeat() {
+    const intervalSeconds = this.configuration.getWebsocketSessionHeartbeatSeconds()
+
+    if (!intervalSeconds || intervalSeconds <= 0) return
+
+    this._heartbeatTimer = setInterval(() => this._heartbeatTick(), intervalSeconds * 1000)
+
+    // Don't let the heartbeat timer keep the process alive.
+    if (typeof this._heartbeatTimer.unref === "function") this._heartbeatTimer.unref()
+  }
+
+  /**
+   * One heartbeat cycle. Reaps the session via the normal close path
+   * when the previous ping was not answered; otherwise marks it
+   * pending and pings again. Browsers and React Native sockets answer
+   * server pings with an automatic pong, which lands in `_processBuffer`
+   * and re-marks the session alive.
+   * @returns {void}
+   */
+  _heartbeatTick() {
+    if (this._paused || !this.client?.events) return
+
+    if (!this._heartbeatAlive) {
+      // No frame arrived since the last ping — the socket is dead.
+      // Route through `_handleClose` so resumable state still pauses
+      // for the grace window and everything else is torn down.
+      this._stopHeartbeat()
+      this._handleClose()
+      return
+    }
+
+    this._heartbeatAlive = false
+    this._sendControlFrame(WEBSOCKET_OPCODE_PING, Buffer.alloc(0))
+  }
+
+  /**
+   * Stops the per-session heartbeat timer, if any.
+   * @returns {void}
+   */
+  _stopHeartbeat() {
+    if (this._heartbeatTimer) {
+      clearInterval(this._heartbeatTimer)
+      this._heartbeatTimer = null
+    }
+  }
+
   /**
    * Runs send control frame.
    * @param {number} opcode - Opcode.
@@ -891,6 +977,9 @@ export default class VelociousHttpServerClientWebsocketSession {
     const hasResumableState = this._connections.size > 0 || this._channelSubscriptions.size > 0
 
     if (hasResumableState && !this._paused) {
+      // Paused sessions have no live socket to ping; the grace timer
+      // owns their eventual teardown from here.
+      this._stopHeartbeat()
       this._paused = true
       this.socket = null
       // Kick off auth-identity capture for resume verification. Runs
@@ -905,6 +994,8 @@ export default class VelociousHttpServerClientWebsocketSession {
       return
     }
 
+    this._stopHeartbeat()
+    this.configuration._websocketSessions.delete(this)
     void this._runMessageHandlerClose()
     void this._teardownChannel()
     void this._teardownConnections("session_destroyed")
@@ -919,6 +1010,8 @@ export default class VelociousHttpServerClientWebsocketSession {
    * @returns {void}
    */
   _finalizeGraceExpiry() {
+    this._stopHeartbeat()
+    this.configuration._websocketSessions.delete(this)
     void this._runMessageHandlerClose()
     void this._teardownChannel()
     void this._teardownConnections("grace_expired")

package/src/routes/hooks/frontend-model-command-route-hook.js

@@ -25,6 +25,30 @@ export default async function frontendModelCommandRouteHook({configuration, curr
     }
   }
 
+  if (normalizedCurrentPath === "/frontend-models/sync/replay") {
+    return {
+      action: "frontend-sync-replay",
+      controller: "velocious/api",
+      controllerPath: FRONTEND_MODEL_CONTROLLER_PATH
+    }
+  }
+
+  if (["/frontend-models/sync/change-feed", "/frontend-models/sync/changes", "/sync/changes"].includes(normalizedCurrentPath)) {
+    return {
+      action: "frontend-sync-change-feed",
+      controller: "velocious/api",
+      controllerPath: FRONTEND_MODEL_CONTROLLER_PATH
+    }
+  }
+
+  if (["/frontend-models/sync/snapshot", "/sync/snapshot"].includes(normalizedCurrentPath)) {
+    return {
+      action: "frontend-sync-snapshot",
+      controller: "velocious/api",
+      controllerPath: FRONTEND_MODEL_CONTROLLER_PATH
+    }
+  }
+
   if (normalizedCurrentPath === SHARED_FRONTEND_MODEL_API_PATH) {
     return {
       action: "frontend-api",

package/src/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)
+}