velocious 1.0.721 → 1.0.723

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/build/background-jobs/main.js +10 -2
  2. package/build/configuration-types.js +1 -1
  3. package/build/database/advisory-lock-reentrancy-node.js +9 -0
  4. package/build/database/advisory-lock-reentrancy.js +66 -0
  5. package/build/database/advisory-lock-runner.js +9 -12
  6. package/build/database/pool/single-multi-use.js +3 -2
  7. package/build/environment-handlers/node.js +1 -0
  8. package/build/src/background-jobs/main.d.ts.map +1 -1
  9. package/build/src/background-jobs/main.js +11 -4
  10. package/build/src/configuration-types.d.ts +2 -2
  11. package/build/src/configuration-types.js +2 -2
  12. package/build/src/database/advisory-lock-reentrancy-node.d.ts +2 -0
  13. package/build/src/database/advisory-lock-reentrancy-node.d.ts.map +1 -0
  14. package/build/src/database/advisory-lock-reentrancy-node.js +7 -0
  15. package/build/src/database/advisory-lock-reentrancy.d.ts +67 -0
  16. package/build/src/database/advisory-lock-reentrancy.d.ts.map +1 -0
  17. package/build/src/database/advisory-lock-reentrancy.js +60 -0
  18. package/build/src/database/advisory-lock-runner.d.ts +25 -33
  19. package/build/src/database/advisory-lock-runner.d.ts.map +1 -1
  20. package/build/src/database/advisory-lock-runner.js +10 -13
  21. package/build/src/database/pool/single-multi-use.d.ts.map +1 -1
  22. package/build/src/database/pool/single-multi-use.js +4 -3
  23. package/build/src/environment-handlers/node.d.ts +1 -0
  24. package/build/src/environment-handlers/node.d.ts.map +1 -1
  25. package/build/src/environment-handlers/node.js +2 -1
  26. package/build/src/sync/sync-applied-sequence-store.d.ts +27 -8
  27. package/build/src/sync/sync-applied-sequence-store.d.ts.map +1 -1
  28. package/build/src/sync/sync-applied-sequence-store.js +43 -18
  29. package/build/src/sync/sync-client.js +3 -3
  30. package/build/src/sync/sync-cursor.d.ts +30 -0
  31. package/build/src/sync/sync-cursor.d.ts.map +1 -0
  32. package/build/src/sync/sync-cursor.js +54 -0
  33. package/build/src/sync/sync-realtime-bridge.d.ts +127 -24
  34. package/build/src/sync/sync-realtime-bridge.d.ts.map +1 -1
  35. package/build/src/sync/sync-realtime-bridge.js +92 -56
  36. package/build/src/sync/sync-websocket-channel.d.ts +49 -0
  37. package/build/src/sync/sync-websocket-channel.d.ts.map +1 -1
  38. package/build/src/sync/sync-websocket-channel.js +138 -2
  39. package/build/sync/sync-applied-sequence-store.js +46 -17
  40. package/build/sync/sync-client.js +2 -2
  41. package/build/sync/sync-cursor.js +56 -0
  42. package/build/sync/sync-realtime-bridge.js +97 -51
  43. package/build/sync/sync-websocket-channel.js +153 -1
  44. package/package.json +1 -1
  45. package/src/background-jobs/main.js +10 -2
  46. package/src/configuration-types.js +1 -1
  47. package/src/database/advisory-lock-reentrancy-node.js +9 -0
  48. package/src/database/advisory-lock-reentrancy.js +66 -0
  49. package/src/database/advisory-lock-runner.js +9 -12
  50. package/src/database/pool/single-multi-use.js +3 -2
  51. package/src/environment-handlers/node.js +1 -0
  52. package/src/sync/sync-applied-sequence-store.js +46 -17
  53. package/src/sync/sync-client.js +2 -2
  54. package/src/sync/sync-cursor.js +56 -0
  55. package/src/sync/sync-realtime-bridge.js +97 -51
  56. package/src/sync/sync-websocket-channel.js +153 -1
@@ -1,6 +1,7 @@
1
1
  // @ts-check
2
2
 
3
3
  import BasePool from "./base.js"
4
+ import DatabasePoolCheckoutTimeoutError from "./checkout-timeout-error.js"
4
5
  import OperationLease from "../operation-lease.js"
5
6
  import {coordinateSharedTransactionConnection} from "../../testing/shared-transaction-connection-coordinator.js"
6
7
 
@@ -274,7 +275,7 @@ export default class VelociousDatabasePoolSingleMultiUser extends BasePool {
274
275
 
275
276
  if (timeoutMillis !== null) {
276
277
  timer = setTimeout(() => {
277
- pending.reject(new Error(`Timed out waiting for database connection checkout after ${timeoutMillis}ms.`))
278
+ pending.reject(new DatabasePoolCheckoutTimeoutError(`Timed out waiting for database connection checkout after ${timeoutMillis}ms.`))
278
279
  }, timeoutMillis)
279
280
  }
280
281
  })
@@ -452,7 +453,7 @@ export default class VelociousDatabasePoolSingleMultiUser extends BasePool {
452
453
  const timeoutMillis = pending.timeoutMillis
453
454
 
454
455
  await new Promise((resolve, reject) => {
455
- const timer = setTimeout(() => reject(new Error(`Timed out waiting for database connection checkout after ${timeoutMillis}ms.`)), timeoutMillis)
456
+ const timer = setTimeout(() => reject(new DatabasePoolCheckoutTimeoutError(`Timed out waiting for database connection checkout after ${timeoutMillis}ms.`)), timeoutMillis)
456
457
 
457
458
  previousTurn.then(() => {
458
459
  clearTimeout(timer)
@@ -1,6 +1,7 @@
1
1
  // @ts-check
2
2
 
3
3
  import "../database/annotations-async-hooks.js"
4
+ import "../database/advisory-lock-reentrancy-node.js"
4
5
  import AdvisoryLockFileBackend from "../database/advisory-lock-file-backend.js"
5
6
  import AdvisoryLockLockServerBackend from "../database/advisory-lock-lock-server-backend.js"
6
7
  import Base from "./base.js"
@@ -69,9 +69,10 @@ export default class SyncAppliedSequenceStore {
69
69
 
70
70
  /**
71
71
  * Ensures the backing table exists.
72
+ * @param {{operation?: import("../database/operation.js").default | null}} [args] - Optional caller-owned operation.
72
73
  * @returns {Promise<void>} Resolves when ready.
73
74
  */
74
- async ensureReady() {
75
+ async ensureReady({operation} = {}) {
75
76
  if (this._isReady) return
76
77
 
77
78
  if (this._usesMemoryStorage()) {
@@ -79,43 +80,43 @@ export default class SyncAppliedSequenceStore {
79
80
  return
80
81
  }
81
82
 
82
- await this._withDb(async (db) => await this._ensureReadyWithDb(db))
83
+ await this._withDb(async (db) => await this._ensureReadyWithDb(db), operation)
83
84
  }
84
85
 
85
86
  /**
86
87
  * Returns the highest server sequence already applied to a record.
87
- * @param {{resourceType: string, resourceId: string}} identity - Resource identity.
88
+ * @param {{resourceType: string, resourceId: string, operation?: import("../database/operation.js").default | null}} identity - Resource identity and optional caller-owned operation.
88
89
  * @returns {Promise<number | null>} Applied sequence, or null when none is recorded.
89
90
  */
90
- async lastAppliedSequence(identity) {
91
- await this.ensureReady()
91
+ async lastAppliedSequence({resourceId, resourceType, operation}) {
92
+ await this.ensureReady({operation})
92
93
 
93
94
  if (this._usesMemoryStorage()) {
94
- return this._memorySequences.get(memoryKey(identity)) ?? null
95
+ return this._memorySequences.get(memoryKey({resourceId, resourceType})) ?? null
95
96
  }
96
97
 
97
98
  return await this._withDb(async (db) => {
98
- const row = await this._rowByResource(db, identity)
99
+ const row = await this._rowByResource(db, {resourceId, resourceType})
99
100
 
100
101
  return row ? row.serverSequence : null
101
- })
102
+ }, operation)
102
103
  }
103
104
 
104
105
  /**
105
106
  * Records a successfully applied server sequence for a record, keeping only
106
107
  * the highest value. Writes for the same record are serialized in-process so
107
108
  * concurrent pull/realtime applies cannot move the watermark backwards.
108
- * @param {{resourceType: string, resourceId: string, serverSequence: number}} args - Applied change identity and sequence.
109
+ * @param {{resourceType: string, resourceId: string, serverSequence: number, operation?: import("../database/operation.js").default | null}} args - Applied change identity, sequence and optional caller-owned operation.
109
110
  * @returns {Promise<void>} Resolves when recorded.
110
111
  */
111
- async recordAppliedSequence({resourceId, resourceType, serverSequence}) {
112
- await this.ensureReady()
112
+ async recordAppliedSequence({resourceId, resourceType, serverSequence, operation}) {
113
+ await this.ensureReady({operation})
113
114
 
114
115
  const identity = {resourceId, resourceType}
115
116
  const key = memoryKey(identity)
116
117
  const previousWrite = this._writeQueues.get(key) || Promise.resolve()
117
118
  const write = previousWrite
118
- .then(async () => await this._recordSequential({identity, key, serverSequence}))
119
+ .then(async () => await this._recordSequential({identity, key, operation, serverSequence}))
119
120
  .finally(() => {
120
121
  if (this._writeQueues.get(key) === write) this._writeQueues.delete(key)
121
122
  })
@@ -126,11 +127,11 @@ export default class SyncAppliedSequenceStore {
126
127
 
127
128
  /**
128
129
  * Applies one serialized watermark write.
129
- * @param {{identity: {resourceType: string, resourceId: string}, key: string, serverSequence: number}} args - Write args.
130
+ * @param {{identity: {resourceType: string, resourceId: string}, key: string, serverSequence: number, operation?: import("../database/operation.js").default | null}} args - Write args.
130
131
  * @returns {Promise<void>} Resolves when written.
131
132
  */
132
- async _recordSequential({identity, key, serverSequence}) {
133
- const currentSequence = await this.lastAppliedSequence(identity)
133
+ async _recordSequential({identity, key, serverSequence, operation}) {
134
+ const currentSequence = await this.lastAppliedSequence({resourceType: identity.resourceType, resourceId: identity.resourceId, operation})
134
135
 
135
136
  if (currentSequence !== null && currentSequence >= serverSequence) return
136
137
 
@@ -153,7 +154,7 @@ export default class SyncAppliedSequenceStore {
153
154
  tableName: TABLE_NAME,
154
155
  updateColumns: ["server_sequence", "updated_at"]
155
156
  })
156
- })
157
+ }, operation)
157
158
  }
158
159
 
159
160
  /**
@@ -227,11 +228,23 @@ export default class SyncAppliedSequenceStore {
227
228
 
228
229
  /**
229
230
  * Runs a callback with a database connection.
231
+ *
232
+ * A caller that already owns an operation on this store's physical database
233
+ * must hand it in: taking a second checkout from the same physical database
234
+ * would queue behind the operation the caller is running inside and wait
235
+ * behind itself.
230
236
  * @template Result
231
237
  * @param {(db: import("../database/drivers/base.js").default) => Promise<Result>} callback - Database callback.
238
+ * @param {import("../database/operation.js").default | null} [operation] - Caller-owned operation to run on.
232
239
  * @returns {Promise<Result>} Callback result.
233
240
  */
234
- async _withDb(callback) {
241
+ async _withDb(callback, operation) {
242
+ if (operation) {
243
+ this.assertOperationOwnership(operation)
244
+
245
+ return await callback(operation.connection())
246
+ }
247
+
235
248
  if (this.tenantHandle) {
236
249
  return await this.tenantHandle.databaseOperation({databaseIdentifier: this.databaseIdentifier, name: "Tenant sync applied-sequence store"}, async (operation) => {
237
250
  return await callback(operation.connection())
@@ -247,6 +260,22 @@ export default class SyncAppliedSequenceStore {
247
260
  })
248
261
  }
249
262
 
263
+ /**
264
+ * Fails closed when a caller hands in an operation that does not belong to this store's database.
265
+ * @param {import("../database/operation.js").default} operation - Caller-owned operation.
266
+ * @returns {void} Nothing when the operation matches the store.
267
+ * @throws {Error} When the operation belongs to another database or another physical tenant database.
268
+ */
269
+ assertOperationOwnership(operation) {
270
+ if (operation.databaseIdentifier() !== this.databaseIdentifier) {
271
+ throw new Error(`Sync applied-sequence store operation belongs to another database: ${operation.databaseIdentifier()}`)
272
+ }
273
+
274
+ if (this.tenantHandle && operation.databaseIdentity() !== this.storeIdentity) {
275
+ throw new Error(`Sync applied-sequence store operation belongs to another physical database: ${operation.databaseIdentity()}`)
276
+ }
277
+ }
278
+
250
279
  /**
251
280
  * Ensures the applied-sequences table exists.
252
281
  * @param {import("../database/drivers/base.js").default} db - Database connection.
@@ -861,7 +861,7 @@ export default class SyncClient {
861
861
  const appliedSequences = this.appliedSequenceStore()
862
862
 
863
863
  if (serverSequence !== null) {
864
- const lastAppliedSequence = await appliedSequences.lastAppliedSequence({resourceId, resourceType})
864
+ const lastAppliedSequence = await appliedSequences.lastAppliedSequence({resourceId, resourceType, operation})
865
865
 
866
866
  if (lastAppliedSequence !== null && serverSequence <= lastAppliedSequence) {
867
867
  return {changed: false, resourceType}
@@ -888,7 +888,7 @@ export default class SyncClient {
888
888
  const result = await applier(sync)
889
889
 
890
890
  if (serverSequence !== null) {
891
- await appliedSequences.recordAppliedSequence({resourceId, resourceType, serverSequence})
891
+ await appliedSequences.recordAppliedSequence({resourceId, resourceType, serverSequence, operation})
892
892
  }
893
893
 
894
894
  return result
@@ -0,0 +1,56 @@
1
+ // @ts-check
2
+
3
+ /**
4
+ * @module sync-cursor
5
+ *
6
+ * Shared cursor helpers for the sync change feed: building a cursor from a
7
+ * serialized sync entry and ordering two cursors under the feed's stable order
8
+ * (server sequence when present, else updated-at then id). The server channel
9
+ * advances its per-subscription replay watermark with these across out-of-order
10
+ * live broadcasts, and the realtime bridge advances the persisted scope cursor
11
+ * monotonically on pushed changes.
12
+ */
13
+
14
+ /** @typedef {import("./sync-api-client-types.js").SyncCursor} SyncCursor */
15
+
16
+ /**
17
+ * Builds a cursor from a serialized sync entry, or null when the entry carries
18
+ * no cursor identity (no updated-at).
19
+ * @param {Record<string, ReturnType<typeof JSON.parse>>} entry - Serialized sync entry.
20
+ * @returns {SyncCursor} Cursor for the entry, or null.
21
+ */
22
+ export function cursorFromSyncEntry(entry) {
23
+ const updatedAt = entry.updatedAt
24
+
25
+ if (typeof updatedAt !== "string" || updatedAt === "") return null
26
+
27
+ return {
28
+ id: entry.id === null || entry.id === undefined ? null : String(entry.id),
29
+ serverSequence: typeof entry.serverSequence === "number" ? entry.serverSequence : null,
30
+ updatedAt
31
+ }
32
+ }
33
+
34
+ /**
35
+ * Whether one cursor is strictly later than another under the change-feed order.
36
+ * A sequenced cursor is always later than an unsequenced one; both sequenced
37
+ * cursors order by server sequence; both unsequenced cursors order by updated-at
38
+ * then id.
39
+ * @param {SyncCursor} candidate - Candidate cursor.
40
+ * @param {SyncCursor} current - Current cursor.
41
+ * @returns {boolean} Whether the candidate is later.
42
+ */
43
+ export function isCursorAfter(candidate, current) {
44
+ if (!candidate) return false
45
+ if (!current) return true
46
+
47
+ if (candidate.serverSequence !== null && current.serverSequence !== null) {
48
+ return candidate.serverSequence > current.serverSequence
49
+ }
50
+ if (candidate.serverSequence !== null) return true
51
+ if (current.serverSequence !== null) return false
52
+
53
+ if (candidate.updatedAt !== current.updatedAt) return candidate.updatedAt > current.updatedAt
54
+
55
+ return (candidate.id ?? "") > (current.id ?? "")
56
+ }
@@ -5,10 +5,46 @@ import {mergeRemoteRequestContext} from "../remote-request-context.js"
5
5
 
6
6
  import SyncApiClient from "./sync-api-client.js"
7
7
  import {VELOCIOUS_SYNC_CHANNEL} from "./sync-channel-name.js"
8
+ import {cursorFromSyncEntry, isCursorAfter} from "./sync-cursor.js"
8
9
 
9
10
  /** @typedef {import("../configuration-types.js").VelociousSyncRealtimeChannelDescriptor} VelociousSyncRealtimeChannelDescriptor */
10
11
  /** @typedef {import("../configuration-types.js").VelociousSyncRealtimeWebsocketClient} VelociousSyncRealtimeWebsocketClient */
11
12
 
13
+ /**
14
+ * The persisted scope row the bridge carries so it can advance the scope's cursor
15
+ * on applied pushes. Mirrors the framework-owned scope store row shape.
16
+ * @typedef {object} SyncRealtimeScopeRow
17
+ * @property {Record<string, ReturnType<typeof JSON.parse>>} conditions - Scope attribute conditions.
18
+ * @property {string | null} cursorPayload - Persisted cursor JSON payload.
19
+ * @property {string} id - Scope row id.
20
+ * @property {string | null} resourceType - Scope resource type.
21
+ * @property {string} scopeDigest - Fixed-size scope digest.
22
+ * @property {string} state - Scope state.
23
+ * @property {string} storeIdentity - Physical store identity.
24
+ */
25
+
26
+ /**
27
+ * One derived channel subscription carrying its owning scope row (null for legacy
28
+ * app channels) and the in-memory cursor watermark advanced by applied pushes.
29
+ * @typedef {object} DerivedSyncChannel
30
+ * @property {string} channel - Channel name.
31
+ * @property {import("./sync-api-client-types.js").SyncCursor} cursor - In-memory cursor watermark.
32
+ * @property {string | null} resourceType - Default resource type for pushed changes.
33
+ * @property {SyncRealtimeScopeRow | null} scopeRow - Owning scope row, or null for legacy channels.
34
+ * @property {import("../configuration-types.js").VelociousSyncRealtimeSubscription} subscription - Subscription handle.
35
+ */
36
+
37
+ /**
38
+ * One derived channel to subscribe, carrying its owning scope row and cursor for
39
+ * framework sync channel subscriptions (null scope row for legacy app channels).
40
+ * @typedef {object} DerivedSyncChannelDescriptor
41
+ * @property {string} channel - Channel name.
42
+ * @property {import("./sync-api-client-types.js").SyncCursor} cursor - In-memory cursor watermark (null for legacy channels).
43
+ * @property {Record<string, ReturnType<typeof JSON.parse>>} params - Subscribe params (without the framework-injected auth token).
44
+ * @property {string | null} resourceType - Default resource type for pushed changes.
45
+ * @property {SyncRealtimeScopeRow | null} scopeRow - Owning scope row, or null for legacy channels.
46
+ */
47
+
12
48
  /**
13
49
  * Derived realtime push bridge for the sync client. Subscribes every declared
14
50
  * pull scope to the framework sync channel ({@link VELOCIOUS_SYNC_CHANNEL})
@@ -29,7 +65,7 @@ export default class SyncRealtimeBridge {
29
65
  */
30
66
  constructor({syncClient}) {
31
67
  this.syncClient = syncClient
32
- /** @type {Array<{channel: string, resourceType: string | null, subscription: import("../configuration-types.js").VelociousSyncRealtimeSubscription}>} */
68
+ /** @type {Array<DerivedSyncChannel>} */
33
69
  this._channels = []
34
70
  /** @type {VelociousSyncRealtimeWebsocketClient | null} */
35
71
  this._client = null
@@ -40,8 +76,6 @@ export default class SyncRealtimeBridge {
40
76
  /** @type {number} Subscription generation - bumped by unsubscribe so in-flight subscribes detect they became stale. */
41
77
  this._generation = 0
42
78
  /** @type {Promise<void> | null} */
43
- this._scheduledPull = null
44
- /** @type {Promise<void> | null} */
45
79
  this._subscribePromise = null
46
80
  /** @type {"subscribed" | "subscribing" | "unsubscribed"} */
47
81
  this._state = "unsubscribed"
@@ -83,7 +117,7 @@ export default class SyncRealtimeBridge {
83
117
 
84
118
  this._state = "subscribing"
85
119
 
86
- /** @type {Array<{channel: string, resourceType: string | null, subscription: import("../configuration-types.js").VelociousSyncRealtimeSubscription}>} */
120
+ /** @type {Array<DerivedSyncChannel>} */
87
121
  const channels = []
88
122
  /** @type {VelociousSyncRealtimeWebsocketClient | null} */
89
123
  let client = null
@@ -154,13 +188,19 @@ export default class SyncRealtimeBridge {
154
188
  label: "Sync client request context",
155
189
  params: {...channelDescriptor.params, authenticationToken}
156
190
  })
157
- const subscription = client.subscribeChannel(channelDescriptor.channel, {
158
- onMessage: (body) => this.enqueueApply({body, generation, resourceType}),
159
- onResume: () => this.schedulePull(generation),
160
- params
161
- })
191
+ /** @type {DerivedSyncChannel} */
192
+ const channel = {
193
+ channel: channelDescriptor.channel,
194
+ cursor: channelDescriptor.cursor,
195
+ resourceType,
196
+ scopeRow: channelDescriptor.scopeRow,
197
+ subscription: client.subscribeChannel(channelDescriptor.channel, {
198
+ onMessage: (body) => this.enqueueApply({body, channel, generation}),
199
+ params
200
+ })
201
+ }
162
202
 
163
- channels.push({channel: channelDescriptor.channel, resourceType, subscription})
203
+ channels.push(channel)
164
204
  }
165
205
 
166
206
  await Promise.all(channels.map(({subscription}) => subscription.waitForReady({signal})))
@@ -175,7 +215,6 @@ export default class SyncRealtimeBridge {
175
215
  this._client = client
176
216
  this._ownsClient = ownsClient
177
217
  this._state = "subscribed"
178
- this.schedulePull(generation)
179
218
  } catch (error) {
180
219
  await teardown()
181
220
 
@@ -225,12 +264,11 @@ export default class SyncRealtimeBridge {
225
264
  }
226
265
 
227
266
  /**
228
- * Awaits all enqueued message applies and any scheduled pull (tests, shutdown flows).
267
+ * Awaits all enqueued message applies (tests, shutdown flows).
229
268
  * @returns {Promise<void>}
230
269
  */
231
270
  async waitForApplied() {
232
271
  await this._applyPromise
233
- if (this._scheduledPull) await this._scheduledPull
234
272
  }
235
273
 
236
274
  /**
@@ -266,33 +304,44 @@ export default class SyncRealtimeBridge {
266
304
  * model-level static realtime declarations and the config channels callback.
267
305
  * Fails loudly when nothing is subscribable.
268
306
  * @param {ReturnType<typeof JSON.parse>} context - App context passed to the deprecated channels callback.
269
- * @returns {Promise<Array<VelociousSyncRealtimeChannelDescriptor>>} Channel descriptors.
307
+ * @returns {Promise<Array<DerivedSyncChannelDescriptor>>} Channel descriptors.
270
308
  */
271
309
  async channelDescriptors(context) {
272
310
  const realtime = this.realtimeConfiguration()
273
- /** @type {Array<VelociousSyncRealtimeChannelDescriptor>} */
311
+ /** @type {Array<DerivedSyncChannelDescriptor>} */
274
312
  const channelDescriptors = []
275
313
 
276
314
  for (const scopeRow of await this.syncClient.scopeStore().activeScopes()) {
315
+ const cursorPayload = await this.syncClient.scopeStore().loadCursor(scopeRow)
316
+ const cursor = SyncApiClient.syncCursorFromPayload(cursorPayload)
317
+
277
318
  channelDescriptors.push({
278
319
  channel: VELOCIOUS_SYNC_CHANNEL,
320
+ cursor,
279
321
  params: {
280
322
  conditions: this.attributeNamedConditions(scopeRow),
281
323
  resourceType: scopeRow.resourceType,
282
324
  // Only the all-types scope carries the type list; a type-declared scope needs none.
283
- ...(scopeRow.resourceType === null ? {resourceTypes: this.syncClient.userScopeResourceTypes()} : {})
284
- }
325
+ ...(scopeRow.resourceType === null ? {resourceTypes: this.syncClient.userScopeResourceTypes()} : {}),
326
+ // Reuse the changes-endpoint cursor fields so the server replays the
327
+ // catch-up backlog from the scope's persisted cursor on subscribe.
328
+ ...SyncApiClient.cursorPayload("after", cursor)
329
+ },
330
+ resourceType: scopeRow.resourceType,
331
+ scopeRow
285
332
  })
286
333
  }
287
334
 
288
335
  for (const [resourceType, resourceConfig] of Object.entries(this.syncClient.config.resources)) {
289
336
  if (!resourceConfig.realtime) continue
290
337
 
291
- channelDescriptors.push({channel: resourceConfig.realtime.channel, params: resourceConfig.realtime.params, resourceType})
338
+ channelDescriptors.push({channel: resourceConfig.realtime.channel, cursor: null, params: resourceConfig.realtime.params ?? {}, resourceType, scopeRow: null})
292
339
  }
293
340
 
294
341
  if (realtime?.channels) {
295
- channelDescriptors.push(...await realtime.channels(context))
342
+ const legacyChannels = await realtime.channels(context)
343
+
344
+ channelDescriptors.push(...legacyChannels.map((descriptor) => ({channel: descriptor.channel, cursor: null, params: descriptor.params ?? {}, resourceType: descriptor.resourceType ?? null, scopeRow: null})))
296
345
  }
297
346
 
298
347
  if (channelDescriptors.length === 0) {
@@ -341,15 +390,15 @@ export default class SyncRealtimeBridge {
341
390
  /**
342
391
  * Chains one pushed message onto the serialized apply queue so changes apply
343
392
  * in arrival order; failures go to the sync client's error reporting.
344
- * @param {{body: ReturnType<typeof JSON.parse>, generation?: number, resourceType: string | null}} args - Message args.
393
+ * @param {{body: ReturnType<typeof JSON.parse>, channel: DerivedSyncChannel, generation?: number}} args - Message args.
345
394
  * @returns {void}
346
395
  */
347
- enqueueApply({body, generation = this._generation, resourceType}) {
396
+ enqueueApply({body, channel, generation = this._generation}) {
348
397
  this._applyPromise = this._applyPromise.then(async () => {
349
398
  if (generation !== this._generation) return
350
399
 
351
400
  try {
352
- await this.applyMessage({body, resourceType})
401
+ await this.applyMessage({body, channel})
353
402
  } catch (error) {
354
403
  this.syncClient.reportError(/** @type {Error} */ (error))
355
404
  }
@@ -359,11 +408,12 @@ export default class SyncRealtimeBridge {
359
408
  /**
360
409
  * Applies one pushed message through the derived resource applier: drops
361
410
  * own-device messages by echo origin, defaults the channel's resourceType onto
362
- * envelopes without one, and fails loudly on unknown resource types.
363
- * @param {{body: ReturnType<typeof JSON.parse>, resourceType: string | null}} args - Message args.
411
+ * envelopes without one, fails loudly on unknown resource types, and advances
412
+ * the owning scope's cursor so a later replay resumes after the applied rows.
413
+ * @param {{body: ReturnType<typeof JSON.parse>, channel: DerivedSyncChannel}} args - Message args.
364
414
  * @returns {Promise<void>}
365
415
  */
366
- async applyMessage({body, resourceType}) {
416
+ async applyMessage({body, channel}) {
367
417
  if (!body || typeof body !== "object" || Array.isArray(body)) {
368
418
  throw new Error(`Realtime sync messages must be envelope objects, got: ${JSON.stringify(body)}`)
369
419
  }
@@ -382,44 +432,40 @@ export default class SyncRealtimeBridge {
382
432
  // Coalesce record-change events across the pushed batch so it triggers one live-query re-run.
383
433
  await recordChanges.batch(async () => {
384
434
  for (const syncPayload of syncPayloads) {
385
- const sync = SyncApiClient.syncEnvelopeFromPayload({resourceType, ...syncPayload})
435
+ const sync = SyncApiClient.syncEnvelopeFromPayload({resourceType: channel.resourceType, ...syncPayload})
386
436
 
387
437
  await applySync(sync)
388
438
  }
389
439
  })
440
+
441
+ await this.advanceScopeCursor(channel, syncPayloads)
390
442
  }
391
443
 
392
444
  /**
393
- * Schedules a coalesced background pull closing offline gaps after
394
- * (re)subscription readiness. Resumes arriving while a pull is already
395
- * scheduled or in flight coalesce into that pull instead of stacking.
396
- * @param {number} [generation] - Subscription generation owning the resume/readiness callback.
397
- * @returns {void}
445
+ * Advances the owning scope's persisted cursor to the newest applied row,
446
+ * monotonically (never backwards) so an out-of-order or duplicate push cannot
447
+ * regress the cursor and re-deliver already-applied rows on a later replay.
448
+ * Legacy channels with no owning scope are skipped.
449
+ * @param {DerivedSyncChannel} channel - Channel owning the scope.
450
+ * @param {Array<ReturnType<typeof JSON.parse>>} syncPayloads - Applied sync entries.
451
+ * @returns {Promise<void>}
398
452
  */
399
- schedulePull(generation = this._generation) {
400
- if (generation !== this._generation) return
401
- if (this.realtimeConfiguration()?.pullOnReconnect === false) return
453
+ async advanceScopeCursor(channel, syncPayloads) {
454
+ if (!channel.scopeRow) return
402
455
 
403
- const coordinatorRun = this.syncClient.requestCoordinatorSync("realtime")
456
+ let latestCursor = channel.cursor
404
457
 
405
- if (coordinatorRun) {
406
- this._scheduledPull ||= coordinatorRun.finally(() => {
407
- this._scheduledPull = null
408
- })
409
- return
458
+ for (const syncPayload of syncPayloads) {
459
+ const entry = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (syncPayload)
460
+ const cursor = cursorFromSyncEntry(entry)
461
+
462
+ if (cursor && isCursorAfter(cursor, latestCursor)) latestCursor = cursor
410
463
  }
411
464
 
412
- this._scheduledPull ||= (async () => {
413
- try {
414
- await this.syncClient.pull()
415
- } catch (error) {
416
- if (!this.syncClient.isLifecycleAbort(error)) {
417
- this.syncClient.reportError(/** @type {Error} */ (error))
418
- }
419
- } finally {
420
- this._scheduledPull = null
421
- }
422
- })()
465
+ if (latestCursor && latestCursor !== channel.cursor) {
466
+ channel.cursor = latestCursor
467
+ await this.syncClient.scopeStore().saveCursor(channel.scopeRow, latestCursor)
468
+ }
423
469
  }
424
470
  }
425
471