@terreno/api 0.31.0 → 56.0.0-beta.2

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 (232) hide show
  1. package/dist/api.d.ts +10 -0
  2. package/dist/api.js +110 -361
  3. package/dist/auth.d.ts +26 -0
  4. package/dist/auth.js +121 -26
  5. package/dist/betterAuth.d.ts +5 -0
  6. package/dist/betterAuthSetup.js +23 -4
  7. package/dist/docLoader.js +12 -9
  8. package/dist/errors.d.ts +13 -0
  9. package/dist/errors.js +29 -1
  10. package/dist/index.d.ts +17 -1
  11. package/dist/index.js +29 -1
  12. package/dist/middleware.d.ts +7 -0
  13. package/dist/middleware.js +16 -1
  14. package/dist/openApiCompat.d.ts +10 -1
  15. package/dist/openApiCompat.js +115 -47
  16. package/dist/permissions.d.ts +27 -0
  17. package/dist/permissions.js +42 -1
  18. package/dist/plugins.d.ts +13 -0
  19. package/dist/plugins.js +47 -1
  20. package/dist/realtime/changeStreamWatcher.d.ts +100 -3
  21. package/dist/realtime/changeStreamWatcher.js +542 -137
  22. package/dist/realtime/realtimeApp.d.ts +2 -0
  23. package/dist/realtime/realtimeApp.js +83 -27
  24. package/dist/realtime/sessionRevalidation.d.ts +90 -0
  25. package/dist/realtime/sessionRevalidation.js +438 -0
  26. package/dist/realtime/socketAuth.d.ts +97 -0
  27. package/dist/realtime/socketAuth.js +272 -0
  28. package/dist/realtime/socketUser.d.ts +54 -0
  29. package/dist/realtime/socketUser.js +75 -5
  30. package/dist/realtime/types.d.ts +54 -0
  31. package/dist/secretProviders.d.ts +23 -0
  32. package/dist/secretProviders.js +9 -3
  33. package/dist/sync/executors.d.ts +198 -0
  34. package/dist/sync/executors.js +670 -0
  35. package/dist/sync/loadHarness.js +807 -0
  36. package/dist/sync/models.d.ts +216 -0
  37. package/dist/sync/models.js +644 -0
  38. package/dist/sync/mutationHandler.d.ts +97 -0
  39. package/dist/sync/mutationHandler.js +886 -0
  40. package/dist/sync/registry.d.ts +73 -0
  41. package/dist/sync/registry.js +223 -0
  42. package/dist/sync/routes.d.ts +62 -0
  43. package/dist/sync/routes.js +936 -0
  44. package/dist/sync/scripts/compactTombstones.d.ts +47 -0
  45. package/dist/sync/scripts/compactTombstones.js +270 -0
  46. package/dist/sync/serialize.d.ts +20 -0
  47. package/dist/{tests/bunSetup.js → sync/serialize.js} +35 -68
  48. package/dist/sync/socketHandlers.d.ts +54 -0
  49. package/dist/sync/socketHandlers.js +470 -0
  50. package/dist/sync/streams.d.ts +85 -0
  51. package/dist/sync/streams.js +221 -0
  52. package/dist/sync/syncApp.d.ts +29 -0
  53. package/dist/sync/syncApp.js +44 -0
  54. package/dist/sync/syncBatch.d.ts +71 -0
  55. package/dist/sync/syncBatch.js +252 -0
  56. package/dist/sync/syncSeqPlugin.d.ts +8 -0
  57. package/dist/sync/syncSeqPlugin.js +899 -0
  58. package/dist/sync/types.d.ts +254 -0
  59. package/dist/sync/types.js +9 -0
  60. package/dist/terrenoApp.js +90 -27
  61. package/dist/vendor/wesleytodd-openapi/index.d.ts +1 -1
  62. package/dist/vendor/wesleytodd-openapi/lib/ui.d.ts +2 -1
  63. package/package.json +7 -6
  64. package/src/__tests__/openApiCompat.test.ts +20 -0
  65. package/src/api.errors.test.ts +32 -23
  66. package/src/api.test.ts +12 -0
  67. package/src/api.ts +87 -296
  68. package/src/auth.test.ts +202 -0
  69. package/src/auth.ts +134 -23
  70. package/src/betterAuth.ts +6 -0
  71. package/src/betterAuthSetup.test.ts +34 -0
  72. package/src/betterAuthSetup.ts +20 -1
  73. package/src/configuration.test.ts +59 -38
  74. package/src/configurationPlugin.test.ts +72 -42
  75. package/src/docLoader.ts +3 -1
  76. package/src/errors.ts +33 -0
  77. package/src/expressServer.test.ts +7 -1
  78. package/src/index.ts +42 -0
  79. package/src/middleware.test.ts +56 -1
  80. package/src/middleware.ts +15 -0
  81. package/src/openApiCompat.ts +99 -45
  82. package/src/permissions.test.ts +101 -17
  83. package/src/permissions.ts +49 -0
  84. package/src/plugins.test.ts +64 -0
  85. package/src/plugins.ts +56 -0
  86. package/src/realtime/changeStreamWatcher.ts +552 -114
  87. package/src/realtime/realtime.test.ts +157 -0
  88. package/src/realtime/realtimeApp.ts +82 -14
  89. package/src/realtime/realtimeAppSetup.test.ts +25 -27
  90. package/src/realtime/sessionRevalidation.test.ts +423 -0
  91. package/src/realtime/sessionRevalidation.ts +273 -0
  92. package/src/realtime/socketAuth.test.ts +355 -0
  93. package/src/realtime/socketAuth.ts +228 -0
  94. package/src/realtime/socketUser.ts +69 -0
  95. package/src/realtime/types.ts +54 -0
  96. package/src/secretProviders.test.ts +7 -1
  97. package/src/secretProviders.ts +15 -3
  98. package/src/secretProvidersGcpClient.test.ts +66 -0
  99. package/src/sync/ensureSyncIndexes.test.ts +144 -0
  100. package/src/sync/executors.test.ts +882 -0
  101. package/src/sync/executors.ts +705 -0
  102. package/src/sync/integration.test.ts +1160 -0
  103. package/src/sync/loadHarness.ts +618 -0
  104. package/src/sync/models.ts +641 -0
  105. package/src/sync/mutationHandler.test.ts +1252 -0
  106. package/src/sync/mutationHandler.ts +850 -0
  107. package/src/sync/registry.ts +232 -0
  108. package/src/sync/routes.ts +812 -0
  109. package/src/sync/scripts/compactTombstones.test.ts +249 -0
  110. package/src/sync/scripts/compactTombstones.ts +145 -0
  111. package/src/sync/serialize.ts +48 -0
  112. package/src/sync/sessionRevalidationIntegration.test.ts +281 -0
  113. package/src/sync/socketHandlers.ts +320 -0
  114. package/src/sync/streams.ts +188 -0
  115. package/src/sync/sync.test.ts +582 -0
  116. package/src/sync/syncApp.ts +44 -0
  117. package/src/sync/syncBatch.ts +219 -0
  118. package/src/sync/syncFrontier.test.ts +494 -0
  119. package/src/sync/syncPhaseC.test.ts +718 -0
  120. package/src/sync/syncRoutes.test.ts +865 -0
  121. package/src/sync/syncSeqPlugin.ts +730 -0
  122. package/src/sync/syncSocket.test.ts +1440 -0
  123. package/src/sync/types.ts +270 -0
  124. package/src/terrenoApp.ts +37 -17
  125. package/src/tests/bunSetup.ts +8 -0
  126. package/tsconfig.json +4 -4
  127. package/tsconfig.typedoc.json +7 -1
  128. package/dist/__tests__/openApiCompat.test.js +0 -317
  129. package/dist/__tests__/versionCheckPlugin.test.d.ts +0 -1
  130. package/dist/__tests__/versionCheckPlugin.test.js +0 -597
  131. package/dist/actions.openApi.test.d.ts +0 -1
  132. package/dist/actions.openApi.test.js +0 -253
  133. package/dist/actions.test.d.ts +0 -1
  134. package/dist/actions.test.js +0 -1087
  135. package/dist/api.arrayOperations.test.d.ts +0 -1
  136. package/dist/api.arrayOperations.test.js +0 -878
  137. package/dist/api.asyncHandler.test.d.ts +0 -1
  138. package/dist/api.asyncHandler.test.js +0 -236
  139. package/dist/api.coverage.test.d.ts +0 -1
  140. package/dist/api.coverage.test.js +0 -192
  141. package/dist/api.errorPaths.test.d.ts +0 -1
  142. package/dist/api.errorPaths.test.js +0 -887
  143. package/dist/api.errors.test.d.ts +0 -1
  144. package/dist/api.errors.test.js +0 -185
  145. package/dist/api.hooks.test.d.ts +0 -1
  146. package/dist/api.hooks.test.js +0 -950
  147. package/dist/api.query.test.d.ts +0 -1
  148. package/dist/api.query.test.js +0 -948
  149. package/dist/api.test.d.ts +0 -1
  150. package/dist/api.test.js +0 -2820
  151. package/dist/auth.compile.test.d.ts +0 -1
  152. package/dist/auth.compile.test.js +0 -201
  153. package/dist/auth.coverage.test.d.ts +0 -1
  154. package/dist/auth.coverage.test.js +0 -202
  155. package/dist/auth.test.d.ts +0 -1
  156. package/dist/auth.test.js +0 -2286
  157. package/dist/betterAuth.test.d.ts +0 -1
  158. package/dist/betterAuth.test.js +0 -181
  159. package/dist/betterAuthApp.test.d.ts +0 -1
  160. package/dist/betterAuthApp.test.js +0 -242
  161. package/dist/betterAuthSetup.test.d.ts +0 -1
  162. package/dist/betterAuthSetup.test.js +0 -762
  163. package/dist/config.test.d.ts +0 -1
  164. package/dist/config.test.js +0 -353
  165. package/dist/configuration.test.d.ts +0 -1
  166. package/dist/configuration.test.js +0 -980
  167. package/dist/configurationPlugin.test.d.ts +0 -1
  168. package/dist/configurationPlugin.test.js +0 -827
  169. package/dist/consentApp.test.d.ts +0 -1
  170. package/dist/consentApp.test.js +0 -1411
  171. package/dist/docLoader.test.d.ts +0 -1
  172. package/dist/docLoader.test.js +0 -137
  173. package/dist/envConfigurationPlugin.test.d.ts +0 -1
  174. package/dist/envConfigurationPlugin.test.js +0 -369
  175. package/dist/errors.test.d.ts +0 -1
  176. package/dist/errors.test.js +0 -607
  177. package/dist/expressServer.test.d.ts +0 -1
  178. package/dist/expressServer.test.js +0 -1249
  179. package/dist/githubAuth.test.d.ts +0 -1
  180. package/dist/githubAuth.test.js +0 -1142
  181. package/dist/httpClient.test.d.ts +0 -1
  182. package/dist/httpClient.test.js +0 -1471
  183. package/dist/logger.test.d.ts +0 -1
  184. package/dist/logger.test.js +0 -685
  185. package/dist/middleware.test.d.ts +0 -1
  186. package/dist/middleware.test.js +0 -241
  187. package/dist/notifiers/googleChatNotifier.test.d.ts +0 -1
  188. package/dist/notifiers/googleChatNotifier.test.js +0 -298
  189. package/dist/notifiers/slackNotifier.test.d.ts +0 -1
  190. package/dist/notifiers/slackNotifier.test.js +0 -297
  191. package/dist/notifiers/zoomNotifier.test.d.ts +0 -1
  192. package/dist/notifiers/zoomNotifier.test.js +0 -373
  193. package/dist/openApi.test.d.ts +0 -1
  194. package/dist/openApi.test.js +0 -620
  195. package/dist/openApiBuilder.test.d.ts +0 -1
  196. package/dist/openApiBuilder.test.js +0 -599
  197. package/dist/openApiEtag.test.d.ts +0 -1
  198. package/dist/openApiEtag.test.js +0 -86
  199. package/dist/openApiValidator.test.d.ts +0 -1
  200. package/dist/openApiValidator.test.js +0 -795
  201. package/dist/permissions.middleware.test.d.ts +0 -1
  202. package/dist/permissions.middleware.test.js +0 -308
  203. package/dist/permissions.test.d.ts +0 -1
  204. package/dist/permissions.test.js +0 -439
  205. package/dist/plugins.test.d.ts +0 -1
  206. package/dist/plugins.test.js +0 -902
  207. package/dist/populate.test.d.ts +0 -1
  208. package/dist/populate.test.js +0 -370
  209. package/dist/realtime/realtime.test.d.ts +0 -10
  210. package/dist/realtime/realtime.test.js +0 -4213
  211. package/dist/realtime/realtimeAppSetup.test.d.ts +0 -1
  212. package/dist/realtime/realtimeAppSetup.test.js +0 -213
  213. package/dist/requestContext.test.d.ts +0 -1
  214. package/dist/requestContext.test.js +0 -412
  215. package/dist/scriptRunner.test.d.ts +0 -1
  216. package/dist/scriptRunner.test.js +0 -386
  217. package/dist/secretProviders.test.d.ts +0 -1
  218. package/dist/secretProviders.test.js +0 -726
  219. package/dist/syncConsents.test.d.ts +0 -1
  220. package/dist/syncConsents.test.js +0 -522
  221. package/dist/terrenoApp.test.d.ts +0 -1
  222. package/dist/terrenoApp.test.js +0 -489
  223. package/dist/tests/bunSetup.d.ts +0 -1
  224. package/dist/tests/fixtures/compileAuthEntry.d.ts +0 -1
  225. package/dist/tests/fixtures/compileAuthEntry.js +0 -37
  226. package/dist/tests/testEnv.d.ts +0 -0
  227. package/dist/tests/testEnv.js +0 -6
  228. package/dist/transformers.test.d.ts +0 -1
  229. package/dist/transformers.test.js +0 -423
  230. package/dist/utils.test.d.ts +0 -1
  231. package/dist/utils.test.js +0 -242
  232. /package/dist/{__tests__/openApiCompat.test.d.ts → sync/loadHarness.d.ts} +0 -0
@@ -0,0 +1,730 @@
1
+ // noExplicitAny: Schema/Query generics must be loose to accept arbitrary consumer schemas
2
+ // biome-ignore-all lint/suspicious/noExplicitAny: Schema/Query generics must be loose to accept arbitrary consumer schemas
3
+ import type {ClientSession, Model, Query, Schema} from "mongoose";
4
+ import {logger} from "../logger";
5
+ import {claimSyncSeqs, confirmSyncSeqs, releaseSyncSeqs, SyncScopeMove} from "./models";
6
+ import {findSyncEntryByModelName, type SyncRegistryEntry} from "./registry";
7
+ import {
8
+ assertWritableStream,
9
+ getScopeField,
10
+ resolveStreamForDoc,
11
+ streamForScopeValue,
12
+ } from "./streams";
13
+
14
+ /**
15
+ * Schema plugin for sync-enabled models. Stamps a monotonic per-stream `_syncSeq` on
16
+ * every single-document write and records `_syncPrevStream` when a write moves the
17
+ * document between scopes (owner/tenant change).
18
+ *
19
+ * Apply to the schema alongside `isDeletedPlugin`; activation is keyed off the sync
20
+ * registry, so models that are not registered via modelRouter's `sync` option no-op.
21
+ *
22
+ * Sequencing guarantees (C1 — stable frontier):
23
+ * - Validation failures never consume a seq: Mongoose runs validation before user
24
+ * pre('save') hooks, so the claim happens post-validation.
25
+ * - Each claim registers the claimed seq on the counter's in-flight `pending` registry;
26
+ * the matching post-write hook (`confirmSyncSeqs`) clears it. Until confirmed, the
27
+ * stream's stable frontier holds below the claimed seq, so a snapshot/delta cursor
28
+ * never advances past a seq whose owning write has not yet committed. A crash between
29
+ * claim and confirm leaves a stale pending entry that ages out via the lease.
30
+ * - The claim joins the caller's session when one is present; that path gets true
31
+ * counter+write atomicity and skips the pending registry entirely (no confirm due).
32
+ * - Every write path claims in its pre hook and confirms in its POST hook — single saves,
33
+ * `insertMany` batches, and query-writes alike. Confirming before the documents commit
34
+ * would let a cursor advance past seqs that have not landed, permanently stranding those
35
+ * documents below every catch-up cursor.
36
+ *
37
+ * Scope moves (C4): when a write moves the document between streams, a durable
38
+ * `SyncScopeMove` marker is written AFTER the move commits, carrying a seq claimed from
39
+ * the OLD stream's counter. The change-stream watcher and old-stream snapshot catch-up
40
+ * tombstone the document from the marker (not the racy `_syncPrevStream` post-image),
41
+ * so a racing second write can no longer erase the tombstone. `_syncPrevStream` is still
42
+ * stamped (harmless), but the marker is the source of truth. Writing the marker
43
+ * post-commit keeps a failed write from leaving a phantom tombstone; the insert is
44
+ * retried ({@link SCOPE_MOVE_MARKER_ATTEMPTS}) because a committed move whose marker is
45
+ * lost can never be tombstoned on the old stream.
46
+ *
47
+ * Lost-update protection (Task 9.13): the plugin turns on Mongoose
48
+ * `optimisticConcurrency`, so `doc.save()` on an existing document filters by the loaded
49
+ * `__v` and throws a `VersionError` when another write landed in between. This closes the
50
+ * read-compare-save TOCTOU window in `executeUpdate`'s `baseVersion` check — two clients
51
+ * sending the same `baseVersion` concurrently now produce exactly one ack and one conflict
52
+ * instead of two acks with one edit silently lost. The loser's already-claimed seq is
53
+ * released (never stamped on anything), so the stream's frontier does not stall for the
54
+ * pending-claim lease.
55
+ *
56
+ * Write restrictions:
57
+ * - `updateMany`, `deleteMany`, hard deletes, and `bulkWrite` are unsupported on synced
58
+ * models and all throw. The first three are guarded here; `bulkWrite` bypasses
59
+ * middleware entirely, so `registerSync` replaces that static on the model instead.
60
+ * - Query-writes MUST target a single document by `_id` (m9): a non-`_id` filter could
61
+ * match a different document than intended and stamp the wrong stream's seq.
62
+ * - `upsert: true` is rejected on query-writes (m8/C6): an upsert can create a document
63
+ * the pre-write lookup never saw, escaping seq stamping.
64
+ */
65
+
66
+ const INITIAL_STREAM_KEY = "_syncInitialStream";
67
+
68
+ /**
69
+ * Resolve the stream for a plain object under an entry's scope. Total by design: this also
70
+ * runs on documents already in the database (hydration, post-commit seq confirmation, and
71
+ * the previous-stream lookup for a scope move), where a legacy row with no scope value
72
+ * must still be nameable rather than unreadable.
73
+ */
74
+ const streamForObject = (entry: SyncRegistryEntry, obj: Record<string, unknown>): string =>
75
+ resolveStreamForDoc({collectionTag: entry.collectionTag, doc: obj, scope: entry.config.scope});
76
+
77
+ /**
78
+ * Same, for the document a write is about to persist: refuses a tenant-scoped write with
79
+ * no scope value rather than filing it under an unsubscribable `tenant:undefined` stream
80
+ * (Task 9.21). Only the seq-stamping write paths use this — reads stay total.
81
+ */
82
+ const writableStreamForObject = (
83
+ entry: SyncRegistryEntry,
84
+ obj: Record<string, unknown>
85
+ ): string => {
86
+ assertWritableStream({collectionTag: entry.collectionTag, doc: obj, scope: entry.config.scope});
87
+ return streamForObject(entry, obj);
88
+ };
89
+
90
+ const unsupportedWrite = (modelName: string, operation: string): Error =>
91
+ new Error(
92
+ `${operation} is not supported on sync-enabled model ${modelName}: per-document seq ` +
93
+ "stamping requires single-document writes (and deletes must be soft). " +
94
+ "Loop per document instead."
95
+ );
96
+
97
+ /**
98
+ * m9: a query-write on a synced model must target exactly one document by `_id`, so the
99
+ * pre-write lookup resolves the stream of the SAME document the update mutates. A non-`_id`
100
+ * filter can match a different document and stamp the wrong stream's seq (duplicate seqs
101
+ * within a stream). Accept `{_id: value}` and `{_id: {$eq: value}}`.
102
+ */
103
+ const filterTargetsSingleId = (filter: Record<string, unknown>): boolean => {
104
+ const idClause = filter._id;
105
+ if (idClause === undefined || idClause === null) {
106
+ return false;
107
+ }
108
+ // A plain string/number id, or an ObjectId (or any BSON value — has a `_bsontype`),
109
+ // is a direct single-document match.
110
+ if (typeof idClause !== "object" || (idClause as {_bsontype?: unknown})._bsontype) {
111
+ return true;
112
+ }
113
+ // A query-operator object is only single-document when it is exactly `{$eq: value}`.
114
+ const keys = Object.keys(idClause as Record<string, unknown>);
115
+ return keys.length === 1 && keys[0] === "$eq";
116
+ };
117
+
118
+ const nonIdFilterError = (modelName: string, operation: string): Error =>
119
+ new Error(
120
+ `${operation} on sync-enabled model ${modelName} must target a single document by _id ` +
121
+ "(use findByIdAndUpdate or loop per document): a non-_id filter can stamp the wrong " +
122
+ "stream's seq."
123
+ );
124
+
125
+ const upsertError = (modelName: string, operation: string): Error =>
126
+ new Error(
127
+ `${operation} with upsert:true is not supported on sync-enabled model ${modelName}: an ` +
128
+ "upsert can create a document the pre-write lookup never saw, escaping seq stamping."
129
+ );
130
+
131
+ /**
132
+ * C4: how many times a scope-move marker insert is attempted before giving up. Losing the
133
+ * marker loses the old stream's tombstone forever (the exact race C4 exists to eliminate),
134
+ * so a transient failure (replica step-down, transient network error) is retried.
135
+ */
136
+ export const SCOPE_MOVE_MARKER_ATTEMPTS = 3;
137
+
138
+ /** Backoff between marker-write attempts. */
139
+ const SCOPE_MOVE_MARKER_RETRY_MS = 25;
140
+
141
+ const delay = (ms: number): Promise<void> =>
142
+ new Promise((resolve) => {
143
+ setTimeout(resolve, ms);
144
+ });
145
+
146
+ /**
147
+ * C4: write the scope-move marker (claim a seq from the OLD stream so it orders in that
148
+ * stream's frontier). Runs AFTER the move commits, so it never leaves a phantom tombstone
149
+ * for a write that failed; the insert is retried up to {@link SCOPE_MOVE_MARKER_ATTEMPTS}
150
+ * times because the already-committed move cannot be undone if the marker is lost.
151
+ *
152
+ * Never throws: the owning write has already committed, so a marker failure is logged
153
+ * rather than surfaced to the caller.
154
+ */
155
+ const writeScopeMoveMarker = async ({
156
+ entry,
157
+ entityId,
158
+ fromStream,
159
+ toStream,
160
+ session,
161
+ }: {
162
+ entry: SyncRegistryEntry;
163
+ entityId: string;
164
+ fromStream: string;
165
+ toStream: string;
166
+ session: ClientSession | null;
167
+ }): Promise<void> => {
168
+ let claim: Awaited<ReturnType<typeof claimSyncSeqs>>;
169
+ try {
170
+ claim = await claimSyncSeqs({session, stream: fromStream});
171
+ } catch (error: unknown) {
172
+ logger.error("[sync] Failed to claim scope-move marker seq", {
173
+ entityId,
174
+ error: String(error),
175
+ fromStream,
176
+ });
177
+ return;
178
+ }
179
+ // Retry the insert with the SAME claimed seq so a retry cannot mint a second marker
180
+ // ordered at a different point in the old stream.
181
+ for (let attempt = 1; attempt <= SCOPE_MOVE_MARKER_ATTEMPTS; attempt++) {
182
+ try {
183
+ await SyncScopeMove.create(
184
+ [
185
+ {
186
+ collectionTag: entry.collectionTag,
187
+ entityId,
188
+ fromStream,
189
+ seq: claim.lastSeq,
190
+ toStream,
191
+ },
192
+ ],
193
+ session ? {session} : {}
194
+ );
195
+ // The marker's own seq on the old stream is confirmed once the insert lands: that
196
+ // insert is the committing write for the claim.
197
+ if (claim.registered) {
198
+ await confirmSyncSeqs({seqs: claim.seqs, stream: fromStream}).catch((error: unknown) => {
199
+ logger.error("[sync] Failed to confirm scope-move marker seq", {
200
+ error: String(error),
201
+ stream: fromStream,
202
+ });
203
+ });
204
+ }
205
+ return;
206
+ } catch (error: unknown) {
207
+ const exhausted = attempt === SCOPE_MOVE_MARKER_ATTEMPTS;
208
+ logger.error("[sync] Failed to write scope-move marker", {
209
+ attempt,
210
+ entityId,
211
+ error: String(error),
212
+ exhausted,
213
+ fromStream,
214
+ });
215
+ if (exhausted) {
216
+ // The claim is left pending: the old stream's frontier holds below the missing
217
+ // tombstone until the lease ages it out, rather than skipping it silently.
218
+ return;
219
+ }
220
+ await delay(SCOPE_MOVE_MARKER_RETRY_MS);
221
+ }
222
+ }
223
+ };
224
+
225
+ /**
226
+ * Task 9.17: the confirm found no pending entry, meaning this writer's claim was reaped as
227
+ * abandoned (it stalled past {@link PENDING_CLAIM_LEASE_MS} without crashing) and the
228
+ * frontier has already advanced past `reapedSeq`. The document just committed BELOW every
229
+ * catch-up cursor, so re-stamp it with a freshly claimed seq: the raw-collection write
230
+ * bypasses this plugin's hooks (no recursion, no second claim) while still producing a
231
+ * change event, so online clients get a delta and offline ones see it on catch-up.
232
+ *
233
+ * Returns the new seq, or undefined when re-stamping failed (logged; the document stays
234
+ * below the frontier and only a full re-bootstrap recovers it).
235
+ */
236
+ const restampReapedSeq = async ({
237
+ model,
238
+ id,
239
+ stream,
240
+ reapedSeq,
241
+ }: {
242
+ model: Model<any>;
243
+ /** The document's RAW `_id` — the native driver does no casting, so a stringified
244
+ * ObjectId would match nothing and silently leave the doc below the frontier. */
245
+ id: unknown;
246
+ stream: string;
247
+ reapedSeq: number;
248
+ }): Promise<number | undefined> => {
249
+ logger.error(
250
+ "[sync] Seq claim was reaped before its write committed; re-stamping the document above " +
251
+ "the frontier",
252
+ {entityId: String(id), model: model.modelName, reapedSeq, stream}
253
+ );
254
+ try {
255
+ const claim = await claimSyncSeqs({stream});
256
+ const result = await model.collection.updateOne(
257
+ {_id: id as any},
258
+ {$set: {_syncSeq: claim.lastSeq}}
259
+ );
260
+ if ((result.matchedCount ?? 0) === 0) {
261
+ logger.error("[sync] Re-stamp matched no document; releasing the re-stamp claim", {
262
+ entityId: String(id),
263
+ seq: claim.lastSeq,
264
+ stream,
265
+ });
266
+ await releaseSyncSeqs({seqs: claim.seqs, stream});
267
+ return undefined;
268
+ }
269
+ const confirmed = await confirmSyncSeqs({seqs: claim.seqs, stream});
270
+ if (!confirmed.cleared) {
271
+ // Two reaps in a row means the process is pathologically slow; stop recursing.
272
+ logger.error("[sync] Re-stamped seq was itself reaped; document remains below the frontier", {
273
+ entityId: String(id),
274
+ seq: claim.lastSeq,
275
+ stream,
276
+ });
277
+ }
278
+ return claim.lastSeq;
279
+ } catch (error: unknown) {
280
+ logger.error("[sync] Failed to re-stamp a reaped seq", {
281
+ entityId: String(id),
282
+ error: String(error),
283
+ reapedSeq,
284
+ stream,
285
+ });
286
+ return undefined;
287
+ }
288
+ };
289
+
290
+ export const syncPlugin = (schema: Schema<any, any, any, any>): void => {
291
+ // Task 9.13: `doc.save()` must be conditional on the version the document was loaded at,
292
+ // so the `baseVersion` comparison in executeUpdate cannot be defeated by a concurrent
293
+ // save landing between the read and the write.
294
+ if (!schema.options.versionKey) {
295
+ throw new Error(
296
+ "syncPlugin requires a versionKey on the schema: sync relies on Mongoose " +
297
+ "optimisticConcurrency to make the baseVersion conflict check atomic. " +
298
+ "Remove `versionKey: false` from the schema options."
299
+ );
300
+ }
301
+ schema.set("optimisticConcurrency", true);
302
+
303
+ schema.add({
304
+ _syncPrevStream: {
305
+ default: null,
306
+ description:
307
+ "The document's previous sync stream, set when a write moved it between scopes; " +
308
+ "null when the last write did not move it",
309
+ type: String,
310
+ },
311
+ _syncSeq: {
312
+ description: "Monotonic per-stream sequence stamped on every synced write",
313
+ index: true,
314
+ type: Number,
315
+ },
316
+ });
317
+
318
+ // Capture the stream the document belonged to when it was loaded, so scope moves can
319
+ // be detected at save time without re-querying.
320
+ schema.post("init", function () {
321
+ const entry = findSyncEntryByModelName((this.constructor as Model<any>).modelName);
322
+ if (!entry) {
323
+ return;
324
+ }
325
+ this.$locals[INITIAL_STREAM_KEY] = streamForObject(entry, this.toObject());
326
+ });
327
+
328
+ const PENDING_COMMIT_KEY = "_syncPendingCommit";
329
+
330
+ /** What `post("save")` must finish once the document write commits. */
331
+ interface PendingSaveCommit {
332
+ claim: {registered: boolean; seqs: number[]};
333
+ currentStream: string;
334
+ entityId: string;
335
+ entry: SyncRegistryEntry;
336
+ prevStream: string | null;
337
+ session: ClientSession | null;
338
+ }
339
+
340
+ schema.pre("save", async function () {
341
+ const entry = findSyncEntryByModelName((this.constructor as Model<any>).modelName);
342
+ if (!entry) {
343
+ return;
344
+ }
345
+ // A previous save on this instance that failed after this hook leaves its pending work
346
+ // behind; drop it so this save's post hook never acts on the earlier attempt's claim.
347
+ this.$locals[PENDING_COMMIT_KEY] = undefined;
348
+ // m10: a save that changes nothing meaningful must not burn a seq or emit a delta.
349
+ // Excluded from the "meaningful" set: the sync stamps this hook writes (`_syncSeq`,
350
+ // `_syncPrevStream`) and auto-managed timestamp metadata (`updated`, which
351
+ // createdUpdatedPlugin bumps on EVERY save — otherwise no save would ever be a
352
+ // no-op). A save whose only modified paths are these is a no-op: skip the claim.
353
+ if (!this.isNew) {
354
+ const ignored = new Set(["_syncSeq", "_syncPrevStream", "updated"]);
355
+ const meaningful = this.modifiedPaths().filter((p) => !ignored.has(p));
356
+ if (meaningful.length === 0) {
357
+ return;
358
+ }
359
+ }
360
+ const session = this.$session() ?? null;
361
+ const currentStream = writableStreamForObject(entry, this.toObject());
362
+ let prevStream: string | null = null;
363
+ if (!this.isNew) {
364
+ const initialStream = this.$locals[INITIAL_STREAM_KEY] as string | undefined;
365
+ if (initialStream && initialStream !== currentStream) {
366
+ prevStream = initialStream;
367
+ }
368
+ }
369
+ const claim = await claimSyncSeqs({session, stream: currentStream});
370
+ this.set({_syncPrevStream: prevStream, _syncSeq: claim.lastSeq});
371
+ // Stash everything post-commit work needs: the seq confirm (C1) and the scope-move
372
+ // marker (C4). Both MUST wait for the commit — a save that fails after this hook
373
+ // (E11000, VersionError, a later user hook) must leave neither a confirmed seq nor a
374
+ // phantom tombstone that old-stream clients would apply to a still-live document.
375
+ const pending: PendingSaveCommit = {
376
+ claim,
377
+ currentStream,
378
+ entityId: String(this._id),
379
+ entry,
380
+ prevStream,
381
+ session,
382
+ };
383
+ this.$locals[PENDING_COMMIT_KEY] = pending;
384
+ });
385
+
386
+ // C1/C4: once the document write commits, confirm the claimed seq (so the stable
387
+ // frontier can advance past it) and record the durable scope-move marker. Document
388
+ // post('save') `this` is the saved document.
389
+ schema.post("save", async function () {
390
+ const pending = this.$locals[PENDING_COMMIT_KEY] as PendingSaveCommit | undefined;
391
+ if (!pending) {
392
+ return;
393
+ }
394
+ this.$locals[PENDING_COMMIT_KEY] = undefined;
395
+ if (pending.claim.registered) {
396
+ const confirmed = await confirmSyncSeqs({
397
+ seqs: pending.claim.seqs,
398
+ stream: pending.currentStream,
399
+ }).catch((error: unknown) => {
400
+ // Never fail the user write for a confirm error: the entry ages out via the lease.
401
+ logger.error("[sync] Failed to confirm seq after save", {
402
+ error: String(error),
403
+ stream: pending.currentStream,
404
+ });
405
+ return {cleared: true};
406
+ });
407
+ if (!confirmed.cleared) {
408
+ // Task 9.17: this writer's claim was reaped as abandoned while it was still
409
+ // running, so the frontier already passed the seq we just committed.
410
+ const restamped = await restampReapedSeq({
411
+ id: this._id,
412
+ model: this.constructor as Model<any>,
413
+ reapedSeq: pending.claim.seqs[pending.claim.seqs.length - 1],
414
+ stream: pending.currentStream,
415
+ });
416
+ if (restamped !== undefined) {
417
+ // Reflect the durable seq on the in-memory document so the caller's ack (and
418
+ // any serialization of this instance) reports the seq clients will actually see.
419
+ this.$set("_syncSeq", restamped);
420
+ this.unmarkModified("_syncSeq");
421
+ }
422
+ }
423
+ }
424
+ if (pending.prevStream) {
425
+ await writeScopeMoveMarker({
426
+ entityId: pending.entityId,
427
+ entry: pending.entry,
428
+ fromStream: pending.prevStream,
429
+ session: pending.session,
430
+ toStream: pending.currentStream,
431
+ });
432
+ }
433
+ // The committed stream becomes the baseline for the next save on this instance; a
434
+ // FAILED save keeps the old baseline so a retry still detects the move.
435
+ this.$locals[INITIAL_STREAM_KEY] = pending.currentStream;
436
+ });
437
+
438
+ // Any save that claimed a seq in pre('save') but then failed (VersionError, E11000,
439
+ // simulated/hook failure, etc.) never stamped that seq. Release it so the stable
440
+ // frontier is not held for the full pending-claim lease.
441
+ //
442
+ // Mongoose 9 / Kareem 3: async error middleware must `throw error` (or return a
443
+ // rejected promise). Calling `next(error)` after an async hook returns a Promise
444
+ // leaves an orphaned rejection that Bun reports as an unhandled error between tests,
445
+ // even when the caller correctly awaited `save().catch(...)`.
446
+ // Keep arity ≥ 3 so Kareem still classifies this as error middleware.
447
+ schema.post(
448
+ "save",
449
+ async function (error: any, doc: any, _next: (err?: Error) => void): Promise<void> {
450
+ const locals = (this?.$locals ?? doc?.$locals) as Record<string, unknown> | undefined;
451
+ const pending = locals?.[PENDING_COMMIT_KEY] as PendingSaveCommit | undefined;
452
+ if (locals) {
453
+ locals[PENDING_COMMIT_KEY] = undefined;
454
+ }
455
+ if (pending?.claim.registered) {
456
+ await releaseSyncSeqs({seqs: pending.claim.seqs, stream: pending.currentStream}).catch(
457
+ (releaseError: unknown) => {
458
+ logger.error("[sync] Failed to release seq claim after failed save", {
459
+ error: String(releaseError),
460
+ stream: pending.currentStream,
461
+ });
462
+ }
463
+ );
464
+ }
465
+ throw error;
466
+ }
467
+ );
468
+
469
+ // Mongoose 9 insertMany pre hooks are async (no `next` callback) and receive docs + options.
470
+ schema.pre(
471
+ "insertMany",
472
+ async function (docs: any | Array<any>, options?: {session?: ClientSession | null}) {
473
+ const docsArray = Array.isArray(docs)
474
+ ? (docs as Record<string, unknown>[])
475
+ : [docs as Record<string, unknown>];
476
+ const model = this as unknown as Model<any>;
477
+ const entry = findSyncEntryByModelName(model.modelName);
478
+ if (!entry || docsArray.length === 0) {
479
+ return;
480
+ }
481
+ const session = options?.session ?? null;
482
+ const byStream = new Map<string, Record<string, unknown>[]>();
483
+ for (const doc of docsArray) {
484
+ const stream = writableStreamForObject(entry, doc);
485
+ const group = byStream.get(stream) ?? [];
486
+ group.push(doc);
487
+ byStream.set(stream, group);
488
+ }
489
+ for (const [stream, group] of byStream) {
490
+ // The claim joins the caller's session so a transactional insertMany gets true
491
+ // counter+write atomicity (and registers no pending entry to confirm).
492
+ const claim = await claimSyncSeqs({count: group.length, session, stream});
493
+ group.forEach((doc, index) => {
494
+ doc._syncPrevStream = null;
495
+ doc._syncSeq = claim.seqs[index];
496
+ });
497
+ }
498
+ // C1: the confirm belongs in post('insertMany') — confirming here would let the
499
+ // stable frontier (and therefore a snapshot cursor) advance past seqs whose
500
+ // documents have not committed yet, stranding them below every catch-up cursor.
501
+ }
502
+ );
503
+
504
+ // C1: the batch has committed — confirm the claimed seqs so the frontier advances past
505
+ // them. Post insertMany middleware receives the inserted (hydrated) documents, which
506
+ // carry the seqs stamped in the pre hook.
507
+ schema.post("insertMany", async function (docs: unknown) {
508
+ if (!Array.isArray(docs) || docs.length === 0) {
509
+ return;
510
+ }
511
+ const modelName = ((docs[0] as {constructor?: {modelName?: string}})?.constructor?.modelName ??
512
+ (this as unknown as Model<any>).modelName) as string | undefined;
513
+ const entry = modelName ? findSyncEntryByModelName(modelName) : undefined;
514
+ if (!entry) {
515
+ return;
516
+ }
517
+ const seqsByStream = new Map<string, number[]>();
518
+ for (const doc of docs as Record<string, any>[]) {
519
+ // A session-backed claim registered nothing to confirm, and a `$pull` issued outside
520
+ // the caller's still-open transaction would conflict with its counter write.
521
+ if (typeof doc?.$session === "function" && doc.$session()) {
522
+ continue;
523
+ }
524
+ const obj = (typeof doc?.toObject === "function" ? doc.toObject() : doc) as Record<
525
+ string,
526
+ unknown
527
+ >;
528
+ const seq = obj._syncSeq;
529
+ if (typeof seq !== "number") {
530
+ continue;
531
+ }
532
+ const stream = streamForObject(entry, obj);
533
+ const seqs = seqsByStream.get(stream) ?? [];
534
+ seqs.push(seq);
535
+ seqsByStream.set(stream, seqs);
536
+ }
537
+ for (const [stream, seqs] of seqsByStream) {
538
+ await confirmSyncSeqs({seqs, stream}).catch((error: unknown) => {
539
+ // Never fail the user write for a confirm error: the entries age out via the lease.
540
+ logger.error("[sync] Failed to confirm insertMany seqs", {
541
+ error: String(error),
542
+ stream,
543
+ });
544
+ });
545
+ }
546
+ });
547
+
548
+ // Single-document query writes: fetch the target to resolve its stream (and detect
549
+ // scope moves), claim a seq, and merge the stamp into the update.
550
+ const preQueryWrite = async function (this: Query<any, any>): Promise<void> {
551
+ const model = this.model as Model<any>;
552
+ const entry = findSyncEntryByModelName(model.modelName);
553
+ if (!entry) {
554
+ return;
555
+ }
556
+ const operation = (this as unknown as {op?: string}).op ?? "query-write";
557
+ // m8/C6: reject upserts — an upsert can create a doc the lookup never saw.
558
+ if (this.getOptions().upsert) {
559
+ throw upsertError(model.modelName, operation);
560
+ }
561
+ const rawFilter = this.getFilter();
562
+ // m9: refuse a non-single-_id filter — it could match a different doc than intended.
563
+ if (!filterTargetsSingleId(rawFilter as Record<string, unknown>)) {
564
+ throw nonIdFilterError(model.modelName, operation);
565
+ }
566
+ const session = this.getOptions().session ?? null;
567
+ // Mirror update semantics: query updates are NOT auto-filtered by isDeletedPlugin
568
+ // (it only hooks find/findOne), so the lookup must see tombstones too.
569
+ const filter: Record<string, unknown> = {...rawFilter};
570
+ if (filter.deleted === undefined) {
571
+ filter.deleted = {$in: [true, false]};
572
+ }
573
+ const matches = await model
574
+ .find(filter)
575
+ .setOptions(session ? {session} : {})
576
+ .limit(1);
577
+ const target = matches[0];
578
+ if (!target) {
579
+ // The update matches nothing; let it proceed as a no-op.
580
+ return;
581
+ }
582
+ const targetObj = target.toObject() as Record<string, unknown>;
583
+ const previousStream = streamForObject(entry, targetObj);
584
+
585
+ const rawUpdate = (this.getUpdate() ?? {}) as Record<string, any>;
586
+ // Only replaceOne/findOneAndReplace replace the document. A plain object passed to
587
+ // updateOne/findOneAndUpdate is an IMPLICIT $set in Mongoose — treating it as a
588
+ // replacement would resolve the scope value as undefined and claim the wrong stream.
589
+ const op = (this as unknown as {op?: string}).op ?? "";
590
+ const isTrueReplacement = op === "replaceOne" || op === "findOneAndReplace";
591
+ const hasOperators = Object.keys(rawUpdate).some((key) => key.startsWith("$"));
592
+ // The fields the update effectively $sets (empty for true replacements).
593
+ const setFields: Record<string, unknown> = isTrueReplacement
594
+ ? {}
595
+ : hasOperators
596
+ ? ((rawUpdate.$set as Record<string, unknown>) ?? {})
597
+ : rawUpdate;
598
+ const scopeField = getScopeField(entry.config.scope);
599
+
600
+ let currentStream: string;
601
+ if (typeof entry.config.scope === "function") {
602
+ const effectiveDoc = isTrueReplacement ? rawUpdate : {...targetObj, ...setFields};
603
+ currentStream = streamForObject(entry, effectiveDoc);
604
+ } else if (scopeField) {
605
+ // Distinguish "the update clears the scope field" from "the update leaves it
606
+ // alone": `??` cannot, because it treats an explicit `$set: {field: null}` as
607
+ // absent and falls back to the document's current value — which both hides the
608
+ // clear from the guard below and stamps the OLD stream's seq onto a document that
609
+ // no longer belongs to it.
610
+ const unsetFields: Record<string, unknown> = hasOperators
611
+ ? ((rawUpdate.$unset as Record<string, unknown>) ?? {})
612
+ : {};
613
+ let newScopeValue: unknown;
614
+ if (isTrueReplacement) {
615
+ newScopeValue = rawUpdate[scopeField];
616
+ } else if (scopeField in unsetFields) {
617
+ newScopeValue = undefined;
618
+ } else if (scopeField in setFields) {
619
+ newScopeValue = setFields[scopeField];
620
+ } else {
621
+ newScopeValue = targetObj[scopeField];
622
+ }
623
+ // A replacement, a `$set` to null, or an `$unset` can strip the tenant field off an
624
+ // existing document, which would move it into an unsubscribable stream just as
625
+ // surely as creating it without one.
626
+ assertWritableStream({
627
+ collectionTag: entry.collectionTag,
628
+ doc: {[scopeField]: newScopeValue},
629
+ scope: entry.config.scope,
630
+ });
631
+ currentStream = streamForScopeValue({
632
+ collectionTag: entry.collectionTag,
633
+ scope: entry.config.scope,
634
+ scopeValue: newScopeValue,
635
+ });
636
+ } else {
637
+ currentStream = previousStream;
638
+ }
639
+
640
+ const prevStream = previousStream !== currentStream ? previousStream : null;
641
+ const claim = await claimSyncSeqs({session, stream: currentStream});
642
+
643
+ if (isTrueReplacement || !hasOperators) {
644
+ // True replacements and implicit-$set plain objects both take plain keys.
645
+ rawUpdate._syncPrevStream = prevStream;
646
+ rawUpdate._syncSeq = claim.lastSeq;
647
+ } else {
648
+ rawUpdate.$set = {
649
+ ...(rawUpdate.$set ?? {}),
650
+ _syncPrevStream: prevStream,
651
+ _syncSeq: claim.lastSeq,
652
+ };
653
+ }
654
+ this.setUpdate(rawUpdate);
655
+ // Stash the claim + move info so the query post hook confirms/records after commit.
656
+ (this as unknown as {_syncPendingConfirm?: unknown})._syncPendingConfirm = {
657
+ claim,
658
+ currentStream,
659
+ entityId: String(target._id),
660
+ entry,
661
+ prevStream,
662
+ session,
663
+ };
664
+ };
665
+
666
+ // C1/C4: after the query write commits, confirm the claimed seq and record the
667
+ // scope-move marker. Query post middleware `this` is the Query (not a document).
668
+ const postQueryWrite = async function (this: Query<any, any>): Promise<void> {
669
+ const pending = (this as unknown as {_syncPendingConfirm?: any})._syncPendingConfirm;
670
+ if (!pending) {
671
+ return;
672
+ }
673
+ (this as unknown as {_syncPendingConfirm?: unknown})._syncPendingConfirm = undefined;
674
+ const {claim, currentStream, entityId, entry, prevStream, session} = pending as {
675
+ claim: {registered: boolean; seqs: number[]};
676
+ currentStream: string;
677
+ entityId: string;
678
+ entry: SyncRegistryEntry;
679
+ prevStream: string | null;
680
+ session: ClientSession | null;
681
+ };
682
+ if (claim.registered) {
683
+ await confirmSyncSeqs({seqs: claim.seqs, stream: currentStream}).catch((error: unknown) => {
684
+ logger.error("[sync] Failed to confirm seq after query write", {
685
+ error: String(error),
686
+ stream: currentStream,
687
+ });
688
+ });
689
+ }
690
+ if (prevStream) {
691
+ // Retries internally and never throws: the move already committed, so the marker
692
+ // must not be dropped on the first transient failure nor fail the user's write.
693
+ await writeScopeMoveMarker({
694
+ entityId,
695
+ entry,
696
+ fromStream: prevStream,
697
+ session,
698
+ toStream: currentStream,
699
+ });
700
+ }
701
+ };
702
+
703
+ schema.pre("updateOne", {document: false, query: true}, preQueryWrite);
704
+ schema.pre("findOneAndUpdate", preQueryWrite);
705
+ schema.pre("replaceOne", preQueryWrite);
706
+ schema.pre("findOneAndReplace", preQueryWrite);
707
+ schema.post("updateOne", {document: false, query: true}, postQueryWrite);
708
+ schema.post("findOneAndUpdate", postQueryWrite);
709
+ schema.post("replaceOne", postQueryWrite);
710
+ schema.post("findOneAndReplace", postQueryWrite);
711
+
712
+ // Unsupported multi-document / hard-delete paths throw for registered models.
713
+ const guardQuery = (operation: string) =>
714
+ function (this: Query<any, any>): void {
715
+ const model = this.model as Model<any>;
716
+ if (findSyncEntryByModelName(model.modelName)) {
717
+ throw unsupportedWrite(model.modelName, operation);
718
+ }
719
+ };
720
+ schema.pre("updateMany", guardQuery("updateMany"));
721
+ schema.pre("deleteMany", guardQuery("deleteMany"));
722
+ schema.pre("deleteOne", {document: false, query: true}, guardQuery("deleteOne"));
723
+ schema.pre("findOneAndDelete", guardQuery("findOneAndDelete"));
724
+ schema.pre("deleteOne", {document: true, query: false}, function () {
725
+ const entry = findSyncEntryByModelName((this.constructor as Model<any>).modelName);
726
+ if (entry) {
727
+ throw unsupportedWrite(entry.modelName, "document deleteOne (hard delete)");
728
+ }
729
+ });
730
+ };