velocious 1.0.721 → 1.0.722

package/build/sync/sync-websocket-channel.js

@@ -2,10 +2,53 @@
 
 import VelociousWebsocketChannel from "../http-server/websocket-channel.js"
 import {VELOCIOUS_SYNC_CHANNEL} from "./sync-channel-name.js"
+import {cursorFromSyncEntry, isCursorAfter} from "./sync-cursor.js"
+import SyncModelChangeFeedService from "./sync-model-change-feed-service.js"
 
 /** Configurations whose framework sync channel has already been registered. */
 const registeredConfigurations = new WeakSet()
 
+/** Default catch-up replay page size when the subscriber sends no `limit` param. */
+const DEFAULT_REPLAY_LIMIT = 1000
+
+/**
+ * Serializes a cursor into the change-feed request params under the given prefix.
+ * @param {"after" | "upTo"} prefix - Request field prefix.
+ * @param {import("./sync-api-client-types.js").SyncCursor} cursor - Cursor to serialize.
+ * @returns {Record<string, string | number | null>} Serialized cursor params.
+ */
+function cursorParams(prefix, cursor) {
+  if (!cursor) return {}
+
+  return {
+    [`${prefix}Id`]: cursor.id,
+    ...(cursor.serverSequence !== null ? {[`${prefix}ServerSequence`]: cursor.serverSequence} : {}),
+    [`${prefix}UpdatedAt`]: cursor.updatedAt
+  }
+}
+
+/**
+ * Reads the after-cursor the subscriber declared in its subscribe params, or null
+ * when it sent none (a fresh subscription replays the whole scope).
+ * @param {Record<string, ReturnType<typeof JSON.parse>>} params - Subscribe params.
+ * @returns {import("./sync-api-client-types.js").SyncCursor} Declared after-cursor, or null.
+ */
+function cursorFromParams(params) {
+  const updatedAt = typeof params.afterUpdatedAt === "string" ? params.afterUpdatedAt : null
+
+  if (!updatedAt) return null
+
+  const serverSequence = params.afterServerSequence === null || params.afterServerSequence === undefined
+    ? null
+    : Number(params.afterServerSequence)
+
+  return {
+    id: params.afterId === null || params.afterId === undefined ? null : String(params.afterId),
+    serverSequence,
+    updatedAt
+  }
+}
+
 /**
  * Framework-owned websocket channel for synced resources
  * ({@link VELOCIOUS_SYNC_CHANNEL}).
@@ -25,6 +68,14 @@ export default class SyncWebsocketChannel extends VelociousWebsocketChannel {
    */
   _scope = null
 
+  /**
+   * Cursor of the last sync entry delivered to this subscription, advanced by
+   * live broadcasts and catch-up replay so a resume replays only the rows missed
+   * while the socket was down.
+   * @type {import("./sync-api-client-types.js").SyncCursor}
+   */
+  _deliveredCursor = null
+
   /**
    * Registers the framework sync channel on a configuration declaring a
    * `sync.api` block (guarded so repeated server boots with the same
@@ -169,13 +220,17 @@ export default class SyncWebsocketChannel extends VelociousWebsocketChannel {
   async deliverBroadcast(body, meta) {
     if (!this._isUserScope()) {
       this.sendMessage(body, meta)
+      this._trackDeliveredCursor(body)
 
       return
     }
 
     const deliverableBody = await this._userScopeDeliverableBody(body)
 
-    if (deliverableBody !== null) this.sendMessage(deliverableBody, meta)
+    if (deliverableBody !== null) {
+      this.sendMessage(deliverableBody, meta)
+      this._trackDeliveredCursor(deliverableBody)
+    }
   }
 
   /**
@@ -245,6 +300,103 @@ export default class SyncWebsocketChannel extends VelociousWebsocketChannel {
     return deliverableSyncs[0]
   }
 
+  /**
+   * Replays the catch-up backlog to this subscriber once its subscription is
+   * authorized: pages the scoped change feed from the cursor the client declared
+   * in its subscribe params and sends each page as a standard sync envelope, then
+   * live broadcasts continue from there. A fresh subscription with no cursor
+   * replays the whole authorized scope.
+   * @returns {Promise<void>}
+   */
+  async subscribed() {
+    if (!this._scope) return
+
+    await this._replayFrom(cursorFromParams(this.params))
+  }
+
+  /**
+   * Replays rows missed while the socket was down, resuming from the cursor of
+   * the last entry this subscription delivered instead of re-reading the whole
+   * scope from the subscribe-time cursor.
+   * @returns {Promise<void>}
+   */
+  async onResume() {
+    if (!this._scope) return
+
+    await this._replayFrom(this._deliveredCursor ?? cursorFromParams(this.params))
+  }
+
+  /**
+   * Pages the scoped change feed from a cursor and delivers each page to this
+   * subscriber as a `{echoOrigin, syncs}` envelope. The snapshot high-water is
+   * resolved once and pinned across pages so rows arriving mid-replay are left to
+   * the live broadcast path instead of looping the replay. The delivered cursor
+   * advances so a later resume resumes from here.
+   * @param {import("./sync-api-client-types.js").SyncCursor} afterCursor - Cursor to replay after.
+   * @returns {Promise<void>}
+   */
+  async _replayFrom(afterCursor) {
+    const configuration = this.session.configuration
+    const scope = this._scope
+
+    await configuration.ensureConnections({name: `${VELOCIOUS_SYNC_CHANNEL} catch-up replay`}, async () => {
+      const resource = await this.buildSyncResource()
+      const limit = this._replayLimit(resource)
+      /** @type {import("./sync-api-client-types.js").SyncCursor} */
+      let upToCursor = null
+
+      while (true) {
+        const page = await resource.changeFeedService({
+          params: {...this.params, ...cursorParams("after", afterCursor), ...(upToCursor ? cursorParams("upTo", upToCursor) : {})},
+          scope
+        }).changes()
+
+        if (!upToCursor) upToCursor = page.upToCursor
+
+        if (page.syncs.length === 0) break
+
+        await this.deliverBroadcast({echoOrigin: null, syncs: page.syncs})
+
+        afterCursor = page.nextCursor
+        if (afterCursor) this._deliveredCursor = afterCursor
+
+        if (page.syncs.length < limit) break
+      }
+    })
+  }
+
+  /**
+   * Resolves the catch-up replay page size from the subscriber's `limit` param
+   * (defaulting to {@link DEFAULT_REPLAY_LIMIT}).
+   * @param {import("./sync-resource-base.js").default} resource - Authorizing sync resource.
+   * @returns {number} Replay page size.
+   */
+  _replayLimit(resource) {
+    return new SyncModelChangeFeedService({modelClass: resource.syncModelClass(), params: this.params}).normalizedLimit(this.params.limit)
+  }
+
+  /**
+   * Advances the delivered-cursor watermark from a delivered envelope so a resume
+   * resumes after the newest row actually sent to this subscriber. Broadcasts may
+   * arrive out of order across resources, so each entry only advances the
+   * watermark when it is later than the current one.
+   * @param {import("../http-server/websocket-channel.js").WebsocketJsonValue} body - Delivered envelope.
+   * @returns {void}
+   */
+  _trackDeliveredCursor(body) {
+    if (!body || typeof body !== "object" || Array.isArray(body)) return
+
+    const envelope = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (body)
+    const syncs = Array.isArray(envelope.syncs) ? envelope.syncs : [envelope]
+
+    for (const entry of syncs) {
+      const syncEntry = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (entry)
+      const cursor = cursorFromSyncEntry(syncEntry)
+
+      if (cursor && isCursorAfter(cursor, this._deliveredCursor)) this._deliveredCursor = cursor
+    }
+  }
+
   /**
    * Returns the authorized scope for debug snapshots.
    * @returns {Record<string, ReturnType<typeof JSON.parse>>} Debug-safe subscription details.

package/package.json

@@ -3,7 +3,7 @@
     "velocious": "build/bin/velocious.js"
   },
   "name": "velocious",
-  "version": "1.0.721",
+  "version": "1.0.722",
   "main": "build/index.js",
   "types": "build/index.d.ts",
   "files": [

package/src/background-jobs/main.js

@@ -1317,12 +1317,20 @@ export default class BackgroundJobsMain {
    */
   async _handleClientSocketMessage({jsonSocket, message}) {
     if (this.generationId && (this.lifecycleState === "retiring" || this.lifecycleState === "retired")) {
-      if (message?.type === "enqueue" && !message.producerProof) jsonSocket.send({type: "enqueue-error", error: "Background jobs generation is retired"})
+      // A retiring generation stays a durable enqueue target. Queued rows are
+      // generation-neutral in the shared store and a retiring main never
+      // dispatches them (`_handleEnqueue` only drains while active), so accepted
+      // work stays queued for the active generation - the release lifecycle
+      // contract holds that returned/retried queue work is eligible for the
+      // active generation. Refusing these enqueues strands producers with no
+      // successor endpoint to retry against, such as this main's own recovery
+      // listeners. Schedule ownership is not generation-neutral, so those
+      // operations stay fenced here.
       if (message?.type === "replace-scheduled") jsonSocket.send({type: "replace-scheduled-error", error: "Background jobs generation is retired"})
       if (message?.type === "cancel-scheduled") jsonSocket.send({type: "cancel-scheduled-error", error: "Background jobs generation is retired"})
       if (message?.type === "get-scheduled-job") jsonSocket.send({type: "get-scheduled-job-error", error: "Background jobs generation is retired"})
       if (message?.type === "wake-scheduled") jsonSocket.send({type: "wake-scheduled-error", error: "Background jobs generation is retired"})
-      if (message?.type !== "enqueue" || !message.producerProof) return
+      if (message?.type !== "enqueue") return
     }
 
     if (message?.type === "enqueue") {

package/src/configuration-types.js

@@ -602,7 +602,7 @@
  * @property {() => VelociousSyncRealtimeWebsocketClient | Promise<VelociousSyncRealtimeWebsocketClient>} createClient - Builds the (unconnected) websocket client; the framework owns connect/disconnect.
  * @property {(context: ReturnType<typeof JSON.parse>) => Array<VelociousSyncRealtimeChannelDescriptor> | Promise<Array<VelociousSyncRealtimeChannelDescriptor>>} [channels] - Deprecated legacy escape hatch: resolves extra app-channel descriptors from the `subscribeRealtime(context)` context. Declared pull scopes subscribe the framework sync channel automatically.
  * @property {() => string | Promise<string>} [localOrigin] - Resolves this device's echo origin; pushed messages with a matching `echoOrigin` are dropped.
- * @property {boolean} [pullOnReconnect] - Fire a coalesced `pull()` when subscriptions become ready or resume after a drop, closing offline gaps. Defaults to true.
+ * @property {boolean} [pullOnReconnect] - Deprecated no-op: realtime catch-up now replays the server-side sync cursor on subscribe and resume, so the former pull-on-reconnect no longer fires. Kept so existing app configs still typecheck.
  */
 
 /**

package/src/database/advisory-lock-reentrancy-node.js

@@ -0,0 +1,9 @@
+// @ts-check
+
+import {AsyncLocalStorage} from "node:async_hooks"
+
+import {installAdvisoryLockReentrancyStorage} from "./advisory-lock-reentrancy.js"
+
+// Imported for its side effect by the Node environment handler: only Node has
+// async-context storage, and browser/Expo bundles must never reach this module.
+installAdvisoryLockReentrancyStorage(new AsyncLocalStorage())

package/src/database/advisory-lock-reentrancy.js

@@ -0,0 +1,66 @@
+// @ts-check
+
+/**
+ * Backend provenance of one advisory-lock hold (STC-210 design §3).
+ * @typedef {object} AdvisoryLockBackendProvenance
+ * @property {import("./advisory-lock-backend-policy.js").AdvisoryLockTier} backend - Tier that served the acquisition.
+ * @property {string} [driverType] - Database driver type when the driver tier served it.
+ * @property {number} [epoch] - Fencing epoch when the serving tier issues one.
+ * @property {boolean} fencingSupported - Whether this tier carries fencing tokens (design §8); the file tier reports false rather than pretending.
+ * @property {string} [holderId] - Backend holder id for the file tier.
+ * @property {string} [lockName] - Lock name this provenance belongs to.
+ */
+
+/**
+ * One advisory-lock hold tracked in the current async context.
+ * @typedef {object} HeldAdvisoryLock
+ * @property {number} depth - Nesting depth of the hold.
+ * @property {AdvisoryLockBackendProvenance} lockBackend - Backend that served the outer hold.
+ */
+
+/**
+ * Async-context storage contract for advisory-lock re-entrancy.
+ * @typedef {object} AdvisoryLockReentrancyStorage
+ * @property {() => Map<string, HeldAdvisoryLock> | undefined} getStore - Store for the current async context.
+ * @property {(store: Map<string, HeldAdvisoryLock>, callback: () => ReturnType<typeof JSON.parse>) => ReturnType<typeof JSON.parse>} run - Runs the callback with the store installed.
+ */
+
+/**
+ * This module is imported by browser and Expo bundles, so it must stay free of
+ * Node-only imports. The Node handler installs the real AsyncLocalStorage through
+ * `advisory-lock-reentrancy-node.js`; other runtimes leave it uninstalled and
+ * holds then run without re-entry tracking.
+ * @type {AdvisoryLockReentrancyStorage | undefined}
+ */
+let installedStorage
+
+/**
+ * Installs the runtime's async-context storage. Called once by the Node handler.
+ * @param {AdvisoryLockReentrancyStorage} storage - Storage owned by the runtime.
+ * @returns {void}
+ */
+export function installAdvisoryLockReentrancyStorage(storage) {
+  installedStorage = storage
+}
+
+/**
+ * Returns the locks the current async context holds, when this runtime has
+ * async-context storage.
+ * @returns {Map<string, HeldAdvisoryLock> | undefined} - Current context store.
+ */
+export function advisoryLockReentrancyStore() {
+  return installedStorage?.getStore()
+}
+
+/**
+ * Runs a callback with the store installed as the current context. Runtimes
+ * without async-context storage run the callback directly.
+ * @param {Map<string, HeldAdvisoryLock>} store - Store for the hold being executed.
+ * @param {() => ReturnType<typeof JSON.parse>} callback - Hold work.
+ * @returns {ReturnType<typeof JSON.parse>} - Callback result.
+ */
+export function runWithAdvisoryLockReentrancyStore(store, callback) {
+  if (!installedStorage) return callback()
+
+  return installedStorage.run(store, callback)
+}

package/src/database/advisory-lock-runner.js

@@ -1,6 +1,5 @@
 // @ts-check
 
-import {AsyncLocalStorage} from "node:async_hooks"
 import timeout, {TimeoutError} from "awaitery/build/timeout.js"
 import {DEFAULT_ADVISORY_LOCK_ACQUIRE_TIMEOUT_MS} from "./advisory-lock-bound.js"
 import {
@@ -13,19 +12,14 @@ import {
   AdvisoryLockServiceUnavailableError,
   advisoryLockBackendUnavailable
 } from "./advisory-lock-errors.js"
+import {advisoryLockReentrancyStore, runWithAdvisoryLockReentrancyStore} from "./advisory-lock-reentrancy.js"
 import {emitAdvisoryLockFallbackReport} from "./advisory-lock-telemetry.js"
 
 /**
  * Provenance of one advisory-lock acquisition (STC-210 design §3): every
  * held lock reports the tier that actually served it, so a fallback is
  * visible to the callback, in logs, and in `getAdvisoryLockBackendStatus()`.
- * @typedef {object} AdvisoryLockBackendProvenance
- * @property {import("./advisory-lock-backend-policy.js").AdvisoryLockTier} backend - Tier that served the acquisition.
- * @property {string} [driverType] - Database driver type when the driver tier served it.
- * @property {number} [epoch] - Fencing epoch when the serving tier issues one.
- * @property {boolean} fencingSupported - Whether this tier carries fencing tokens (design §8); the file tier reports false rather than pretending.
- * @property {string} [holderId] - Backend holder id for the file tier.
- * @property {string} [lockName] - Lock name this provenance belongs to.
+ * @typedef {import("./advisory-lock-reentrancy.js").AdvisoryLockBackendProvenance} AdvisoryLockBackendProvenance
  */
 
 /**
@@ -78,8 +72,11 @@ class AdvisoryLockBusyError extends Error {
  * `already-held` and treated it as contention. Applications worked around it
  * with hand-passed `*LockHeld` booleans, which is exactly the parameter a
  * monitor makes redundant.
+ *
+ * The storage itself belongs to the environment handler: Node owns async-context
+ * storage, while browser and Expo runtimes have none and therefore hold without
+ * re-entry tracking instead of pulling `node:async_hooks` into their bundles.
  */
-const heldAdvisoryLocks = new AsyncLocalStorage()
 
 /**
  * Thrown when a callback holds an advisory lock longer than `holdTimeoutMs`.
@@ -300,7 +297,7 @@ export default class AdvisoryLockRunner {
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async runLockedCallback({callback, holdTimeoutMs, lockBackend, name, release}) {
-    const store = new Map(heldAdvisoryLocks.getStore() ?? [])
+    const store = new Map(advisoryLockReentrancyStore() ?? [])
 
     store.set(this.lockStorageKey(name), {depth: 1, lockBackend})
 
@@ -308,7 +305,7 @@ export default class AdvisoryLockRunner {
       // The lock is released outside the context scope: a release path that
       // touches the same name (a cleanup hook, an error reporter) must not look
       // like a re-entry of a hold that is already over.
-      return await heldAdvisoryLocks.run(store, async () => await AdvisoryLockRunner.runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs, lockBackend))
+      return await runWithAdvisoryLockReentrancyStore(store, async () => await AdvisoryLockRunner.runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs, lockBackend))
     } finally {
       await release()
     }
@@ -320,7 +317,7 @@ export default class AdvisoryLockRunner {
    * @returns {{depth: number, lockBackend: AdvisoryLockBackendProvenance} | null} - The held entry, or null when this context does not hold the lock.
    */
   heldEntryFor(name) {
-    const store = heldAdvisoryLocks.getStore()
+    const store = advisoryLockReentrancyStore()
 
     if (!store) return null
 

package/src/environment-handlers/node.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import "../database/annotations-async-hooks.js"
+import "../database/advisory-lock-reentrancy-node.js"
 import AdvisoryLockFileBackend from "../database/advisory-lock-file-backend.js"
 import AdvisoryLockLockServerBackend from "../database/advisory-lock-lock-server-backend.js"
 import Base from "./base.js"

package/src/sync/sync-cursor.js

@@ -0,0 +1,56 @@
+// @ts-check
+
+/**
+ * @module sync-cursor
+ *
+ * Shared cursor helpers for the sync change feed: building a cursor from a
+ * serialized sync entry and ordering two cursors under the feed's stable order
+ * (server sequence when present, else updated-at then id). The server channel
+ * advances its per-subscription replay watermark with these across out-of-order
+ * live broadcasts, and the realtime bridge advances the persisted scope cursor
+ * monotonically on pushed changes.
+ */
+
+/** @typedef {import("./sync-api-client-types.js").SyncCursor} SyncCursor */
+
+/**
+ * Builds a cursor from a serialized sync entry, or null when the entry carries
+ * no cursor identity (no updated-at).
+ * @param {Record<string, ReturnType<typeof JSON.parse>>} entry - Serialized sync entry.
+ * @returns {SyncCursor} Cursor for the entry, or null.
+ */
+export function cursorFromSyncEntry(entry) {
+  const updatedAt = entry.updatedAt
+
+  if (typeof updatedAt !== "string" || updatedAt === "") return null
+
+  return {
+    id: entry.id === null || entry.id === undefined ? null : String(entry.id),
+    serverSequence: typeof entry.serverSequence === "number" ? entry.serverSequence : null,
+    updatedAt
+  }
+}
+
+/**
+ * Whether one cursor is strictly later than another under the change-feed order.
+ * A sequenced cursor is always later than an unsequenced one; both sequenced
+ * cursors order by server sequence; both unsequenced cursors order by updated-at
+ * then id.
+ * @param {SyncCursor} candidate - Candidate cursor.
+ * @param {SyncCursor} current - Current cursor.
+ * @returns {boolean} Whether the candidate is later.
+ */
+export function isCursorAfter(candidate, current) {
+  if (!candidate) return false
+  if (!current) return true
+
+  if (candidate.serverSequence !== null && current.serverSequence !== null) {
+    return candidate.serverSequence > current.serverSequence
+  }
+  if (candidate.serverSequence !== null) return true
+  if (current.serverSequence !== null) return false
+
+  if (candidate.updatedAt !== current.updatedAt) return candidate.updatedAt > current.updatedAt
+
+  return (candidate.id ?? "") > (current.id ?? "")
+}