velocious 1.0.500 → 1.0.502

package/build/sync/sync-client.js

@@ -2,10 +2,12 @@
 
 import Configuration from "../configuration.js"
 import {isBooleanColumnType} from "../database/column-types.js"
+import Logger from "../logger.js"
 import restArgsError from "../utils/rest-args-error.js"
 
 import {serializedScopeFromQuery} from "./query-scope.js"
 import SyncApiClient from "./sync-api-client.js"
+import SyncRealtimeBridge from "./sync-realtime-bridge.js"
 import SyncScopeStore from "./sync-scope-store.js"
 import {currentSyncClient, setCurrentSyncClient} from "./sync-client-registry.js"
 
@@ -14,6 +16,14 @@ let clientCounter = 0
 /** @type {{create: "afterCreate", update: "afterUpdate", destroy: "afterDestroy"}} */
 const TRACKED_CALLBACK_NAMES = {create: "afterCreate", destroy: "afterDestroy", update: "afterUpdate"}
 
+/**
+ * Operations tracked by default for models declaring `static sync` without a
+ * `track` key: local creates and updates queue automatically. Destroys are not
+ * tracked by default because a local destroy is often cache eviction rather
+ * than a server delete; opt in with `track: true` or an operations list.
+ * @type {Array<"create" | "update" | "destroy">} */
+const DEFAULT_TRACKED_OPERATIONS = ["create", "update"]
+
 /** Attribute names treated as client-local sync bookkeeping when deriving localOnlyAttributes. */
 const LOCAL_BOOKKEEPING_ATTRIBUTE_NAMES = ["createdAt", "updatedAt", "lastSyncChangeAt"]
 
@@ -87,10 +97,13 @@ export default class SyncClient {
       onError: clientConfiguration.onError,
       postChanges: transportPoster({path: `${clientConfiguration.mountPath}/changes`, transport: clientConfiguration.transport}),
       postReplay: transportPoster({path: `${clientConfiguration.mountPath}/replay`, transport: clientConfiguration.transport}),
+      realtime: clientConfiguration.realtime,
       resources,
       syncModel: resolvedSyncModel
     }
     this._clientNumber = ++clientCounter
+    /** @type {SyncRealtimeBridge | null} */
+    this._realtimeBridge = null
     /** @type {import("./sync-scope-store.js").default | null} */
     this._scopeStore = scopeStore || null
     /** @type {Promise<void> | null} */
@@ -101,13 +114,18 @@ export default class SyncClient {
     this._trackedCallbacks = []
     /** @type {WeakSet<object>} */
     this._remoteApplyRecords = new WeakSet()
+    this._withoutTrackingDepth = 0
+    /** @type {Logger | {error: (...messages: Array<?>) => Promise<void>} | null} */
+    this._logger = null
     this._started = false
   }
 
   /**
-   * Registers automatic mutation tracking for every resource with `track` enabled:
-   * local model creates/updates/destroys queue pending sync rows and schedule an
-   * immediate replay attempt, without app-side queue calls.
+   * Registers automatic mutation tracking for every declared resource (on by
+   * default: local creates and updates queue pending sync rows once their
+   * transaction commits and schedule an immediate replay attempt, without
+   * app-side queue calls). `track: false` resources are skipped; `track: true`
+   * adds destroys; an operations list narrows the tracked operations.
    * @returns {Promise<void>}
    */
   async start() {
@@ -143,13 +161,17 @@ export default class SyncClient {
 
   /**
    * Resolves and validates the tracked operations for a resource config.
+   * Tracking is on by default: models declaring `static sync` without a `track`
+   * key queue local creates and updates automatically; `track: false` opts a
+   * model out (for models written by non-user flows).
    * @param {{resourceConfig: import("./sync-client-types.js").SyncClientResourceConfig, resourceType: string}} args - Resource config and name.
    * @returns {Array<"create" | "update" | "destroy">} Tracked operations.
    */
   trackedOperations({resourceConfig, resourceType}) {
     const track = resourceConfig.track
 
-    if (track === undefined || track === false) return []
+    if (track === false) return []
+    if (track === undefined) return DEFAULT_TRACKED_OPERATIONS
     if (track === true) return ["create", "update", "destroy"]
 
     if (!track || typeof track !== "object" || !Array.isArray(track.operations) || track.operations.length === 0) {
@@ -166,27 +188,78 @@ export default class SyncClient {
   }
 
   /**
-   * Builds the lifecycle callback queueing one tracked mutation.
+   * Builds the lifecycle callback queueing one tracked mutation. The queued
+   * payload and sync type are snapshotted at mutation-callback time, so
+   * afterSave hooks assigning unsaved attributes (or any later drift on the
+   * record) cannot change what gets queued vs what was committed. Queueing is
+   * deferred through the model connection's afterCommit hook so it only runs
+   * once the mutation's transaction has committed (immediately when no
+   * transaction is open) - queued syncs never reference rolled-back rows.
+   * Post-commit queue failures are reported without rethrowing into the
+   * driver's afterCommit chain (see reportAfterCommitError).
    * @param {{operation: "create" | "update" | "destroy", resourceConfig: import("./sync-client-types.js").SyncClientResourceConfig}} args - Operation and resource config.
    * @returns {(record: ?) => Promise<void>} Lifecycle callback.
    */
   trackedMutationCallback({operation, resourceConfig}) {
     return async (record) => {
-      if (this.isRemoteApply(record)) return
+      if (this.isTrackingSuppressed(record)) return
 
-      await SyncApiClient.queueLocalSync({
+      const data = SyncApiClient.queuedSyncData({
         booleanAttributes: resourceConfig.booleanAttributes || [],
         data: resourceConfig.trackedData ? resourceConfig.trackedData({operation, record}) : undefined,
         localOnlyAttributes: resourceConfig.localOnlyAttributes || [],
-        resource: record,
-        syncModel: this.config.syncModel,
-        syncType: this.defaultSyncType({operation, record, resourceConfig})
+        resource: record
       })
+      const syncType = this.defaultSyncType({operation, record, resourceConfig})
+
+      await resourceConfig.modelClass.connection().afterCommit(async () => {
+        try {
+          await SyncApiClient.queueLocalSync({
+            data,
+            resource: record,
+            syncModel: this.config.syncModel,
+            syncType
+          })
+        } catch (error) {
+          await this.reportAfterCommitError(/** @type {Error} */ (error))
+
+          return
+        }
 
-      this.scheduleReplay()
+        this.scheduleReplay()
+      })
     }
   }
 
+  /**
+   * Reports a post-commit tracked-queueing failure. The transaction has already
+   * committed when afterCommit callbacks run, so rethrowing here would poison
+   * the driver's awaited afterCommit chain (breaking unrelated callbacks) -
+   * instead the failure goes to the configured sync.client.onError hook, or is
+   * logged loudly through the client's logger when none is configured.
+   * @param {Error} error - Post-commit queueing failure.
+   * @returns {Promise<void>}
+   */
+  async reportAfterCommitError(error) {
+    if (this.config.onError) {
+      this.config.onError(error)
+
+      return
+    }
+
+    await this.logger().error("SyncClient failed to queue a tracked mutation after commit", error)
+  }
+
+  /**
+   * Returns the lazily built client logger.
+   * @returns {Logger | {error: (...messages: Array<?>) => Promise<void>}} Client logger.
+   */
+  logger() {
+    this._logger ||= new Logger("SyncClient", {configuration: this.config.configuration})
+
+    return this._logger
+  }
+
   /**
    * Whether a record is currently being written by pull-apply (echo suppression).
    * @param {?} record - Local model record.
@@ -196,6 +269,54 @@ export default class SyncClient {
     return this._remoteApplyRecords.has(record)
   }
 
+  /**
+   * Whether tracked mutation queueing is currently suppressed for a record:
+   * either the record was marked as a remote apply (`markRemoteApply`, used by
+   * pull and realtime applies) or a `withoutTracking` callback is running on
+   * this client.
+   * @param {?} record - Local model record.
+   * @returns {boolean} Whether tracked queueing is suppressed for the record.
+   */
+  isTrackingSuppressed(record) {
+    return this._withoutTrackingDepth > 0 || this.isRemoteApply(record)
+  }
+
+  /**
+   * Runs a callback with tracked mutation queueing suppressed on this client -
+   * for code applying server-originated data outside the derived pull/realtime
+   * appliers (legacy pull paths, importers, sign-in backfills), so their writes
+   * are not echoed back to the server as device changes. Suppression covers the
+   * whole async duration of the callback (nested calls stack) and is
+   * client-wide while it runs: mutations from concurrently running tasks are
+   * also suppressed for that window, so prefer `markRemoteApply(record)` when
+   * writes from other flows can interleave.
+   * @template T
+   * @param {() => Promise<T> | T} callback - Work whose model writes should not queue tracked syncs.
+   * @returns {Promise<T>} The callback result.
+   */
+  async withoutTracking(callback) {
+    this._withoutTrackingDepth++
+
+    try {
+      return await callback()
+    } finally {
+      this._withoutTrackingDepth--
+    }
+  }
+
+  /**
+   * Marks one record as being written from server-originated data so tracked
+   * mutation queueing skips it (record-precise suppression). The derived pull
+   * and realtime appliers use this internally around every applied write.
+   * @param {?} record - Local model record about to be written.
+   * @returns {() => void} Release callback re-enabling tracking for the record.
+   */
+  markRemoteApply(record) {
+    this._remoteApplyRecords.add(record)
+
+    return () => this._remoteApplyRecords.delete(record)
+  }
+
   /**
    * Registers this client as the app's current sync client.
    * @returns {void}
@@ -265,26 +386,7 @@ export default class SyncClient {
     await SyncApiClient.singleFlight(`velocious-sync-client-pull-${this._clientNumber}`, async () => {
       const authenticationToken = await this.config.authenticationToken()
       const scopeStore = this.scopeStore()
-      const pullResourceConfigs = this.pullResourceConfigs()
-      const applier = SyncApiClient.resourceApplier(pullResourceConfigs, (record) => {
-        this._remoteApplyRecords.add(record)
-
-        return () => this._remoteApplyRecords.delete(record)
-      })
-      /**
-       * Applies one pulled change, failing loudly instead of silently skipping unconfigured resources.
-       * @param {import("./sync-api-client-types.js").SyncChangeEnvelope} sync - Pulled change.
-       * @returns {Promise<import("./sync-api-client-types.js").SyncChangeApplyResult>} Apply result.
-       */
-      const applySync = async (sync) => {
-        const resourceType = sync.resourceType()
-
-        if (!resourceType || !pullResourceConfigs[resourceType]) {
-          throw new Error(`No sync resource with pull attributes configured for pulled change: ${String(resourceType)}`)
-        }
-
-        return await applier(sync)
-      }
+      const applySync = this.remoteApplySync()
       const result = {
         changed: false,
         pages: 0,
@@ -324,6 +426,74 @@ export default class SyncClient {
     return combinedResult
   }
 
+  /**
+   * Builds the derived remote-change applier shared by pulls and realtime pushes:
+   * applies through the declared resource configs, registers each written record
+   * for echo suppression (tracked resources do not re-queue applied changes), and
+   * fails loudly instead of silently skipping unconfigured resources.
+   * @param {{source?: string}} [args] - Error context describing where the change came from.
+   * @returns {(sync: import("./sync-api-client-types.js").SyncChangeEnvelope) => Promise<import("./sync-api-client-types.js").SyncChangeApplyResult>} Loud remote-change applier.
+   */
+  remoteApplySync({source = "pulled change"} = {}) {
+    const pullResourceConfigs = this.pullResourceConfigs()
+    const applier = SyncApiClient.resourceApplier(pullResourceConfigs, (record) => this.markRemoteApply(record))
+
+    return async (sync) => {
+      const resourceType = sync.resourceType()
+
+      if (!resourceType || !pullResourceConfigs[resourceType]) {
+        throw new Error(`No sync resource with pull attributes configured for ${source}: ${String(resourceType)}`)
+      }
+
+      return await applier(sync)
+    }
+  }
+
+  /**
+   * Subscribes the derived realtime channels so pushed websocket changes apply
+   * through the same derived applier as pulls (idempotent, single-flighted).
+   * @param {?} [context] - App context passed to the `sync.client.realtime.channels` callback (runtime values like eventId).
+   * @returns {Promise<void>}
+   */
+  async subscribeRealtime(context) {
+    await this.realtimeBridge().subscribe(context)
+  }
+
+  /**
+   * Unsubscribes the realtime channels and disconnects the websocket client (idempotent).
+   * @returns {Promise<void>}
+   */
+  async unsubscribeRealtime() {
+    await this.realtimeBridge().unsubscribe()
+  }
+
+  /**
+   * Reports the realtime subscription state and per-channel readiness.
+   * @returns {ReturnType<SyncRealtimeBridge["status"]>} Realtime status.
+   */
+  realtimeStatus() {
+    return this.realtimeBridge().status()
+  }
+
+  /**
+   * Awaits all pending realtime message applies and any scheduled
+   * pull-on-reconnect (useful in tests and shutdown flows).
+   * @returns {Promise<void>}
+   */
+  async waitForRealtimeApplied() {
+    await this.realtimeBridge().waitForApplied()
+  }
+
+  /**
+   * Returns the lazily built realtime bridge.
+   * @returns {SyncRealtimeBridge} Realtime bridge.
+   */
+  realtimeBridge() {
+    this._realtimeBridge ||= new SyncRealtimeBridge({syncClient: this})
+
+    return this._realtimeBridge
+  }
+
   /**
    * Queues a local model change as a pending sync row and schedules an immediate
    * replay attempt (kept pending while offline or when the backend rejects it).
@@ -491,11 +661,11 @@ function resourceConfigFromSyncDeclaration({declaration, modelClass, resourceTyp
     throw new Error(`${resourceType} static sync must be true or a sync declaration object, got: ${String(declaration)}`)
   }
 
-  const {afterApply, attributes, booleanAttributes, findRecord, findRecordForDelete, localOnlyAttributes, syncType, track, trackedData, ...restDeclaration} = normalizedDeclaration
+  const {afterApply, attributes, booleanAttributes, findRecord, findRecordForDelete, localOnlyAttributes, realtime, syncType, track, trackedData, ...restDeclaration} = normalizedDeclaration
   const unknownKeys = Object.keys(restDeclaration)
 
   if (unknownKeys.length > 0) {
-    throw new Error(`${resourceType} static sync received unknown keys: ${unknownKeys.join(", ")} (supported: afterApply, attributes, booleanAttributes, findRecord, findRecordForDelete, localOnlyAttributes, syncType, track, trackedData)`)
+    throw new Error(`${resourceType} static sync received unknown keys: ${unknownKeys.join(", ")} (supported: afterApply, attributes, booleanAttributes, findRecord, findRecordForDelete, localOnlyAttributes, realtime, syncType, track, trackedData)`)
   }
   if (syncType !== undefined && typeof syncType !== "function" && syncType !== "upsert") {
     throw new Error(`${resourceType} static sync syncType must be a function or the string "upsert", got: ${String(syncType)}`)
@@ -511,6 +681,7 @@ function resourceConfigFromSyncDeclaration({declaration, modelClass, resourceTyp
     findRecordForDelete,
     localOnlyAttributes: mergedAttributeNames(derived.localOnlyAttributes, localOnlyAttributes),
     modelClass,
+    realtime,
     syncType,
     track: normalizedTrack(track),
     trackedData

package/build/sync/sync-realtime-bridge.js

@@ -0,0 +1,299 @@
+// @ts-check
+
+import SyncApiClient from "./sync-api-client.js"
+
+/** @typedef {import("../configuration-types.js").VelociousSyncRealtimeChannelDescriptor} VelociousSyncRealtimeChannelDescriptor */
+/** @typedef {import("../configuration-types.js").VelociousSyncRealtimeWebsocketClient} VelociousSyncRealtimeWebsocketClient */
+
+/**
+ * Derived realtime push bridge for the sync client. Subscribes the declared
+ * websocket channels (config `sync.client.realtime.channels` callback plus
+ * model-level `static sync = {realtime: {channel}}` declarations), applies
+ * pushed changes through the same derived resource applier as pulls (with echo
+ * suppression against tracked re-queueing), drops own-device messages by echo
+ * origin, and fires a coalesced `pull()` when subscriptions become ready or
+ * resume so offline gaps close.
+ */
+export default class SyncRealtimeBridge {
+  /**
+   * Builds the bridge for a sync client.
+   * @param {{syncClient: import("./sync-client.js").default}} args - Bridge args.
+   */
+  constructor({syncClient}) {
+    this.syncClient = syncClient
+    /** @type {Array<{channel: string, resourceType: string | null, subscription: import("../configuration-types.js").VelociousSyncRealtimeSubscription}>} */
+    this._channels = []
+    /** @type {VelociousSyncRealtimeWebsocketClient | null} */
+    this._client = null
+    /** @type {Promise<void>} */
+    this._applyPromise = Promise.resolve()
+    /** @type {number} Subscription generation - bumped by unsubscribe so in-flight subscribes detect they became stale. */
+    this._generation = 0
+    /** @type {Promise<void> | null} */
+    this._scheduledPull = null
+    /** @type {Promise<void> | null} */
+    this._subscribePromise = null
+    /** @type {"subscribed" | "subscribing" | "unsubscribed"} */
+    this._state = "unsubscribed"
+  }
+
+  /**
+   * Subscribes the derived realtime channels (idempotent and single-flighted):
+   * an active subscription is kept as-is and a concurrent subscribe awaits the
+   * in-flight attempt. Call `unsubscribe()` first to change the context.
+   * @param {?} [context] - App context passed to the `sync.client.realtime.channels` callback (runtime values like eventId).
+   * @returns {Promise<void>}
+   */
+  async subscribe(context) {
+    if (this._state === "subscribed") return
+
+    if (!this._subscribePromise) {
+      this._subscribePromise = this._subscribe(context).finally(() => {
+        this._subscribePromise = null
+      })
+    }
+
+    await this._subscribePromise
+  }
+
+  /**
+   * Connects the websocket client, subscribes every derived channel, and waits
+   * for each subscription's server acknowledgement before the gap-closing pull,
+   * so no change can land between the pull and the subscriptions going live.
+   * Locally created resources are only promoted to the bridge once everything
+   * is live; an unsubscribe arriving during any await marks this attempt stale
+   * and it tears its own resources down instead of resubscribing.
+   * @param {?} context - App context passed to the channels callback.
+   * @returns {Promise<void>}
+   */
+  async _subscribe(context) {
+    const generation = this._generation
+
+    this._state = "subscribing"
+
+    /** @type {Array<{channel: string, resourceType: string | null, subscription: import("../configuration-types.js").VelociousSyncRealtimeSubscription}>} */
+    const channels = []
+    /** @type {VelociousSyncRealtimeWebsocketClient | null} */
+    let client = null
+    /**
+     * Tears down everything this stale/failed subscribe attempt created itself.
+     * @returns {Promise<void>}
+     */
+    const teardown = async () => {
+      for (const {subscription} of channels) {
+        subscription.close()
+      }
+
+      if (client) await client.disconnectAndStopReconnect()
+    }
+
+    try {
+      const realtime = this.realtimeConfiguration()
+      const channelDescriptors = await this.channelDescriptors(context)
+
+      if (generation !== this._generation) return
+
+      client = await realtime.createClient()
+
+      if (generation !== this._generation) return
+
+      await client.connect()
+
+      if (generation !== this._generation) {
+        await teardown()
+        return
+      }
+
+      const authenticationToken = await this.syncClient.config.authenticationToken()
+
+      if (generation !== this._generation) {
+        await teardown()
+        return
+      }
+
+      for (const channelDescriptor of channelDescriptors) {
+        if (channelDescriptor.params && "authenticationToken" in channelDescriptor.params) {
+          throw new Error(`Realtime channel "${channelDescriptor.channel}" params must not include authenticationToken - the framework injects the sync.client authenticationToken automatically`)
+        }
+
+        const resourceType = channelDescriptor.resourceType ?? null
+        const subscription = client.subscribeChannel(channelDescriptor.channel, {
+          onMessage: (body) => this.enqueueApply({body, resourceType}),
+          onResume: () => this.schedulePull(),
+          params: {...channelDescriptor.params, authenticationToken}
+        })
+
+        channels.push({channel: channelDescriptor.channel, resourceType, subscription})
+      }
+
+      await Promise.all(channels.map(({subscription}) => subscription.waitForReady()))
+
+      if (generation !== this._generation) {
+        await teardown()
+        return
+      }
+
+      this._channels = channels
+      this._client = client
+      this._state = "subscribed"
+      this.schedulePull()
+    } catch (error) {
+      await teardown()
+
+      if (generation === this._generation) this._state = "unsubscribed"
+
+      throw error
+    }
+  }
+
+  /**
+   * Closes every channel subscription and disconnects the websocket client
+   * (idempotent). Also marks any in-flight subscribe attempt stale so it tears
+   * itself down instead of finishing the subscription afterwards.
+   * @returns {Promise<void>}
+   */
+  async unsubscribe() {
+    this._generation += 1
+
+    const channels = this._channels
+    const client = this._client
+
+    this._channels = []
+    this._client = null
+    this._state = "unsubscribed"
+
+    for (const {subscription} of channels) {
+      subscription.close()
+    }
+
+    if (client) await client.disconnectAndStopReconnect()
+  }
+
+  /**
+   * Reports the bridge subscription state and per-channel readiness.
+   * @returns {{channels: Array<{channel: string, ready: boolean, resourceType: string | null}>, state: "subscribed" | "subscribing" | "unsubscribed"}} Realtime status.
+   */
+  status() {
+    return {
+      channels: this._channels.map(({channel, resourceType, subscription}) => ({channel, ready: subscription.isReady(), resourceType})),
+      state: this._state
+    }
+  }
+
+  /**
+   * Awaits all enqueued message applies and any scheduled pull (tests, shutdown flows).
+   * @returns {Promise<void>}
+   */
+  async waitForApplied() {
+    await this._applyPromise
+    if (this._scheduledPull) await this._scheduledPull
+  }
+
+  /**
+   * Resolves the realtime configuration, failing loudly when it is missing.
+   * @returns {import("../configuration-types.js").VelociousSyncClientRealtimeConfiguration} Realtime configuration.
+   */
+  realtimeConfiguration() {
+    const realtime = this.syncClient.config.realtime
+
+    if (!realtime) {
+      throw new Error("subscribeRealtime requires a sync.client.realtime configuration block with a createClient callback")
+    }
+
+    return realtime
+  }
+
+  /**
+   * Derives the channel descriptors to subscribe: model-level static realtime
+   * declarations plus the config channels callback, failing loudly when none exist.
+   * @param {?} context - App context passed to the channels callback.
+   * @returns {Promise<Array<VelociousSyncRealtimeChannelDescriptor>>} Channel descriptors.
+   */
+  async channelDescriptors(context) {
+    const realtime = this.realtimeConfiguration()
+    /** @type {Array<VelociousSyncRealtimeChannelDescriptor>} */
+    const channelDescriptors = []
+
+    for (const [resourceType, resourceConfig] of Object.entries(this.syncClient.config.resources)) {
+      if (!resourceConfig.realtime) continue
+
+      channelDescriptors.push({channel: resourceConfig.realtime.channel, params: resourceConfig.realtime.params, resourceType})
+    }
+
+    if (realtime.channels) {
+      channelDescriptors.push(...await realtime.channels(context))
+    }
+
+    if (channelDescriptors.length === 0) {
+      throw new Error("subscribeRealtime found no realtime channels - declare sync.client.realtime.channels or static sync = {realtime: {channel}} on a model")
+    }
+
+    return channelDescriptors
+  }
+
+  /**
+   * Chains one pushed message onto the serialized apply queue so changes apply
+   * in arrival order; failures go to the sync client's error reporting.
+   * @param {{body: ?, resourceType: string | null}} args - Message args.
+   * @returns {void}
+   */
+  enqueueApply({body, resourceType}) {
+    this._applyPromise = this._applyPromise.then(async () => {
+      try {
+        await this.applyMessage({body, resourceType})
+      } catch (error) {
+        this.syncClient.reportError(/** @type {Error} */ (error))
+      }
+    })
+  }
+
+  /**
+   * Applies one pushed message through the derived resource applier: drops
+   * own-device messages by echo origin, defaults the channel's resourceType onto
+   * envelopes without one, and fails loudly on unknown resource types.
+   * @param {{body: ?, resourceType: string | null}} args - Message args.
+   * @returns {Promise<void>}
+   */
+  async applyMessage({body, resourceType}) {
+    if (!body || typeof body !== "object" || Array.isArray(body)) {
+      throw new Error(`Realtime sync messages must be envelope objects, got: ${JSON.stringify(body)}`)
+    }
+
+    const realtime = this.realtimeConfiguration()
+
+    if (realtime.localOrigin && body.echoOrigin !== undefined && body.echoOrigin !== null) {
+      const localOrigin = String(await realtime.localOrigin())
+
+      if (String(body.echoOrigin) === localOrigin) return
+    }
+
+    const syncPayloads = Array.isArray(body.syncs) ? body.syncs : [body]
+    const applySync = this.syncClient.remoteApplySync({source: "remote change"})
+
+    for (const syncPayload of syncPayloads) {
+      const sync = SyncApiClient.syncEnvelopeFromPayload({resourceType, ...syncPayload})
+
+      await applySync(sync)
+    }
+  }
+
+  /**
+   * Schedules a coalesced background pull closing offline gaps after
+   * (re)subscription readiness. Resumes arriving while a pull is already
+   * scheduled or in flight coalesce into that pull instead of stacking.
+   * @returns {void}
+   */
+  schedulePull() {
+    if (this.realtimeConfiguration().pullOnReconnect === false) return
+
+    this._scheduledPull ||= (async () => {
+      try {
+        await this.syncClient.pull()
+      } catch (error) {
+        this.syncClient.reportError(/** @type {Error} */ (error))
+      } finally {
+        this._scheduledPull = null
+      }
+    })()
+  }
+}