velocious 1.0.720 → 1.0.722

package/src/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.