velocious 1.0.500 → 1.0.501

package/src/sync/sync-client.js

@@ -6,6 +6,7 @@ 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"
 
@@ -87,10 +88,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} */
@@ -265,26 +269,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 +309,78 @@ 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._remoteApplyRecords.add(record)
+
+      return () => this._remoteApplyRecords.delete(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 +548,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 +568,7 @@ function resourceConfigFromSyncDeclaration({declaration, modelClass, resourceTyp
     findRecordForDelete,
     localOnlyAttributes: mergedAttributeNames(derived.localOnlyAttributes, localOnlyAttributes),
     modelClass,
+    realtime,
     syncType,
     track: normalizedTrack(track),
     trackedData

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