@terreno/api 0.30.0 → 56.0.0-beta.0

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 (226) 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 +100 -1
  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 +35 -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 +73 -21
  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 +40 -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 +903 -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/actions.openApi.test.ts +7 -10
  66. package/src/api.test.ts +12 -0
  67. package/src/api.ts +87 -295
  68. package/src/auth.test.ts +128 -176
  69. package/src/auth.ts +109 -0
  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/docLoader.ts +3 -1
  74. package/src/errors.ts +33 -0
  75. package/src/expressServer.test.ts +7 -1
  76. package/src/index.ts +42 -0
  77. package/src/middleware.test.ts +40 -1
  78. package/src/middleware.ts +15 -0
  79. package/src/openApiCompat.ts +99 -45
  80. package/src/permissions.test.ts +75 -1
  81. package/src/permissions.ts +49 -0
  82. package/src/plugins.test.ts +54 -0
  83. package/src/plugins.ts +43 -0
  84. package/src/realtime/changeStreamWatcher.ts +552 -114
  85. package/src/realtime/realtime.test.ts +157 -0
  86. package/src/realtime/realtimeApp.ts +75 -11
  87. package/src/realtime/sessionRevalidation.test.ts +423 -0
  88. package/src/realtime/sessionRevalidation.ts +273 -0
  89. package/src/realtime/socketAuth.test.ts +355 -0
  90. package/src/realtime/socketAuth.ts +228 -0
  91. package/src/realtime/socketUser.ts +69 -0
  92. package/src/realtime/types.ts +40 -0
  93. package/src/secretProviders.test.ts +7 -1
  94. package/src/secretProviders.ts +15 -3
  95. package/src/sync/ensureSyncIndexes.test.ts +144 -0
  96. package/src/sync/executors.test.ts +882 -0
  97. package/src/sync/executors.ts +703 -0
  98. package/src/sync/integration.test.ts +1160 -0
  99. package/src/sync/loadHarness.ts +618 -0
  100. package/src/sync/models.ts +640 -0
  101. package/src/sync/mutationHandler.test.ts +1252 -0
  102. package/src/sync/mutationHandler.ts +850 -0
  103. package/src/sync/registry.ts +232 -0
  104. package/src/sync/routes.ts +812 -0
  105. package/src/sync/scripts/compactTombstones.test.ts +249 -0
  106. package/src/sync/scripts/compactTombstones.ts +145 -0
  107. package/src/sync/serialize.ts +48 -0
  108. package/src/sync/sessionRevalidationIntegration.test.ts +281 -0
  109. package/src/sync/socketHandlers.ts +320 -0
  110. package/src/sync/streams.ts +188 -0
  111. package/src/sync/sync.test.ts +582 -0
  112. package/src/sync/syncApp.ts +44 -0
  113. package/src/sync/syncBatch.ts +219 -0
  114. package/src/sync/syncFrontier.test.ts +494 -0
  115. package/src/sync/syncPhaseC.test.ts +718 -0
  116. package/src/sync/syncRoutes.test.ts +865 -0
  117. package/src/sync/syncSeqPlugin.ts +738 -0
  118. package/src/sync/syncSocket.test.ts +1440 -0
  119. package/src/sync/types.ts +270 -0
  120. package/src/terrenoApp.ts +37 -17
  121. package/src/tests/bunSetup.ts +8 -0
  122. package/tsconfig.json +4 -4
  123. package/tsconfig.typedoc.json +7 -1
  124. package/dist/__tests__/openApiCompat.test.js +0 -317
  125. package/dist/__tests__/versionCheckPlugin.test.d.ts +0 -1
  126. package/dist/__tests__/versionCheckPlugin.test.js +0 -597
  127. package/dist/actions.openApi.test.d.ts +0 -1
  128. package/dist/actions.openApi.test.js +0 -255
  129. package/dist/actions.test.d.ts +0 -1
  130. package/dist/actions.test.js +0 -1089
  131. package/dist/api.arrayOperations.test.d.ts +0 -1
  132. package/dist/api.arrayOperations.test.js +0 -878
  133. package/dist/api.asyncHandler.test.d.ts +0 -1
  134. package/dist/api.asyncHandler.test.js +0 -236
  135. package/dist/api.coverage.test.d.ts +0 -1
  136. package/dist/api.coverage.test.js +0 -194
  137. package/dist/api.errorPaths.test.d.ts +0 -1
  138. package/dist/api.errorPaths.test.js +0 -801
  139. package/dist/api.errors.test.d.ts +0 -1
  140. package/dist/api.errors.test.js +0 -185
  141. package/dist/api.hooks.test.d.ts +0 -1
  142. package/dist/api.hooks.test.js +0 -950
  143. package/dist/api.query.test.d.ts +0 -1
  144. package/dist/api.query.test.js +0 -948
  145. package/dist/api.test.d.ts +0 -1
  146. package/dist/api.test.js +0 -2820
  147. package/dist/auth.compile.test.d.ts +0 -1
  148. package/dist/auth.compile.test.js +0 -201
  149. package/dist/auth.coverage.test.d.ts +0 -1
  150. package/dist/auth.coverage.test.js +0 -202
  151. package/dist/auth.test.d.ts +0 -1
  152. package/dist/auth.test.js +0 -2286
  153. package/dist/betterAuth.test.d.ts +0 -1
  154. package/dist/betterAuth.test.js +0 -181
  155. package/dist/betterAuthApp.test.d.ts +0 -1
  156. package/dist/betterAuthApp.test.js +0 -242
  157. package/dist/betterAuthSetup.test.d.ts +0 -1
  158. package/dist/betterAuthSetup.test.js +0 -762
  159. package/dist/config.test.d.ts +0 -1
  160. package/dist/config.test.js +0 -353
  161. package/dist/configuration.test.d.ts +0 -1
  162. package/dist/configuration.test.js +0 -980
  163. package/dist/configurationPlugin.test.d.ts +0 -1
  164. package/dist/configurationPlugin.test.js +0 -827
  165. package/dist/consentApp.test.d.ts +0 -1
  166. package/dist/consentApp.test.js +0 -1415
  167. package/dist/docLoader.test.d.ts +0 -1
  168. package/dist/docLoader.test.js +0 -137
  169. package/dist/envConfigurationPlugin.test.d.ts +0 -1
  170. package/dist/envConfigurationPlugin.test.js +0 -369
  171. package/dist/errors.test.d.ts +0 -1
  172. package/dist/errors.test.js +0 -607
  173. package/dist/expressServer.test.d.ts +0 -1
  174. package/dist/expressServer.test.js +0 -1249
  175. package/dist/githubAuth.test.d.ts +0 -1
  176. package/dist/githubAuth.test.js +0 -1142
  177. package/dist/httpClient.test.d.ts +0 -1
  178. package/dist/httpClient.test.js +0 -1471
  179. package/dist/logger.test.d.ts +0 -1
  180. package/dist/logger.test.js +0 -685
  181. package/dist/middleware.test.d.ts +0 -1
  182. package/dist/middleware.test.js +0 -241
  183. package/dist/notifiers/googleChatNotifier.test.d.ts +0 -1
  184. package/dist/notifiers/googleChatNotifier.test.js +0 -298
  185. package/dist/notifiers/slackNotifier.test.d.ts +0 -1
  186. package/dist/notifiers/slackNotifier.test.js +0 -297
  187. package/dist/notifiers/zoomNotifier.test.d.ts +0 -1
  188. package/dist/notifiers/zoomNotifier.test.js +0 -373
  189. package/dist/openApi.test.d.ts +0 -1
  190. package/dist/openApi.test.js +0 -620
  191. package/dist/openApiBuilder.test.d.ts +0 -1
  192. package/dist/openApiBuilder.test.js +0 -601
  193. package/dist/openApiEtag.test.d.ts +0 -1
  194. package/dist/openApiEtag.test.js +0 -86
  195. package/dist/openApiValidator.test.d.ts +0 -1
  196. package/dist/openApiValidator.test.js +0 -761
  197. package/dist/permissions.middleware.test.d.ts +0 -1
  198. package/dist/permissions.middleware.test.js +0 -308
  199. package/dist/permissions.test.d.ts +0 -1
  200. package/dist/permissions.test.js +0 -439
  201. package/dist/plugins.test.d.ts +0 -1
  202. package/dist/plugins.test.js +0 -890
  203. package/dist/populate.test.d.ts +0 -1
  204. package/dist/populate.test.js +0 -373
  205. package/dist/realtime/realtime.test.d.ts +0 -10
  206. package/dist/realtime/realtime.test.js +0 -3982
  207. package/dist/requestContext.test.d.ts +0 -1
  208. package/dist/requestContext.test.js +0 -412
  209. package/dist/scriptRunner.test.d.ts +0 -1
  210. package/dist/scriptRunner.test.js +0 -386
  211. package/dist/secretProviders.test.d.ts +0 -1
  212. package/dist/secretProviders.test.js +0 -726
  213. package/dist/syncConsents.test.d.ts +0 -1
  214. package/dist/syncConsents.test.js +0 -522
  215. package/dist/terrenoApp.test.d.ts +0 -1
  216. package/dist/terrenoApp.test.js +0 -489
  217. package/dist/tests/bunSetup.d.ts +0 -1
  218. package/dist/tests/fixtures/compileAuthEntry.d.ts +0 -1
  219. package/dist/tests/fixtures/compileAuthEntry.js +0 -37
  220. package/dist/tests/testEnv.d.ts +0 -0
  221. package/dist/tests/testEnv.js +0 -6
  222. package/dist/transformers.test.d.ts +0 -1
  223. package/dist/transformers.test.js +0 -423
  224. package/dist/utils.test.d.ts +0 -1
  225. package/dist/utils.test.js +0 -242
  226. /package/dist/{__tests__/openApiCompat.test.d.ts → sync/loadHarness.d.ts} +0 -0
@@ -0,0 +1,582 @@
1
+ // noExplicitAny: test model typing
2
+ // biome-ignore-all lint/suspicious/noExplicitAny: test model typing
3
+ import {beforeAll, beforeEach, describe, expect, it} from "bun:test";
4
+ import {model, Schema} from "mongoose";
5
+ import {type ModelRouterOptions, modelRouter} from "../api";
6
+ import {createdUpdatedPlugin, type IsDeleted, isDeletedPlugin} from "../plugins";
7
+ import {setupDb} from "../tests";
8
+ import {
9
+ claimSyncSeqs,
10
+ getOrCreateSyncKeyMaterial,
11
+ SyncCounter,
12
+ SyncKey,
13
+ SyncMutation,
14
+ } from "./models";
15
+ import {
16
+ clearSyncRegistry,
17
+ findSyncEntryByCollectionTag,
18
+ findSyncEntryByModelName,
19
+ getSyncRegistry,
20
+ registerSync,
21
+ warnOnSyncScopesWithoutUserModel,
22
+ } from "./registry";
23
+ import {
24
+ assertWritableStream,
25
+ getScopeField,
26
+ resolveStreamForDoc,
27
+ streamForScopeValue,
28
+ } from "./streams";
29
+ import {syncPlugin} from "./syncSeqPlugin";
30
+ import type {SyncConfig} from "./types";
31
+
32
+ interface SyncStuff extends IsDeleted {
33
+ _id: string;
34
+ name: string;
35
+ ownerId: string;
36
+ orgId?: string;
37
+ created: Date;
38
+ updated?: Date;
39
+ _syncSeq?: number;
40
+ _syncPrevStream?: string | null;
41
+ }
42
+
43
+ const syncStuffSchema = new Schema<SyncStuff>({
44
+ name: {description: "The name of the item", required: true, type: String},
45
+ orgId: {description: "The organization this item belongs to", type: String},
46
+ ownerId: {description: "The user who owns this item", type: String},
47
+ });
48
+ syncStuffSchema.plugin(isDeletedPlugin);
49
+ syncStuffSchema.plugin(createdUpdatedPlugin);
50
+ syncStuffSchema.plugin(syncPlugin);
51
+ const SyncStuffModel = model<SyncStuff>("SyncStuff", syncStuffSchema);
52
+
53
+ // The shared test database can be dropped by another test file mid-suite
54
+ // (configurationPlugin.test.ts drops it in an afterAll), destroying the unique indexes
55
+ // the concurrency/idempotency tests below depend on. Rebuild them before this file runs.
56
+ beforeAll(async () => {
57
+ await Promise.all([
58
+ SyncCounter.ensureIndexes(),
59
+ SyncKey.ensureIndexes(),
60
+ SyncMutation.ensureIndexes(),
61
+ ]);
62
+ });
63
+
64
+ // Has syncPlugin but is never registered — hooks must no-op.
65
+ const unregisteredSchema = new Schema<SyncStuff>({
66
+ name: {description: "The name of the item", type: String},
67
+ ownerId: {description: "The user who owns this item", type: String},
68
+ });
69
+ unregisteredSchema.plugin(isDeletedPlugin);
70
+ unregisteredSchema.plugin(syncPlugin);
71
+ const UnregisteredModel = model<SyncStuff>("SyncUnregistered", unregisteredSchema);
72
+
73
+ // Missing isDeletedPlugin — registration must throw.
74
+ const noDeleteSchema = new Schema({
75
+ name: {description: "The name of the item", type: String},
76
+ ownerId: {description: "The user who owns this item", type: String},
77
+ });
78
+ noDeleteSchema.plugin(syncPlugin);
79
+ const NoDeleteModel = model("SyncNoDelete", noDeleteSchema);
80
+
81
+ // Missing syncPlugin — registration must throw.
82
+ const noPluginSchema = new Schema({
83
+ name: {description: "The name of the item", type: String},
84
+ ownerId: {description: "The user who owns this item", type: String},
85
+ });
86
+ noPluginSchema.plugin(isDeletedPlugin);
87
+ const NoPluginModel = model("SyncNoPlugin", noPluginSchema);
88
+
89
+ const stubOptions = {
90
+ permissions: {create: [], delete: [], list: [], read: [], update: []},
91
+ } as unknown as ModelRouterOptions<any>;
92
+
93
+ const ownerConfig: SyncConfig = {scope: {type: "owner"}};
94
+
95
+ const registerStuff = (config: SyncConfig = ownerConfig): void => {
96
+ registerSync({
97
+ config,
98
+ model: SyncStuffModel as any,
99
+ options: stubOptions,
100
+ routePath: "/syncStuff",
101
+ });
102
+ };
103
+
104
+ describe("sync streams", () => {
105
+ it("resolves owner scope with the default field", () => {
106
+ expect(getScopeField({type: "owner"})).toBe("ownerId");
107
+ expect(
108
+ resolveStreamForDoc({collectionTag: "todos", doc: {ownerId: "u1"}, scope: {type: "owner"}})
109
+ ).toBe("todos|owner:u1");
110
+ });
111
+
112
+ it("resolves owner scope with a custom field", () => {
113
+ expect(getScopeField({field: "userId", type: "owner"})).toBe("userId");
114
+ expect(
115
+ resolveStreamForDoc({
116
+ collectionTag: "todos",
117
+ doc: {userId: "u2"},
118
+ scope: {field: "userId", type: "owner"},
119
+ })
120
+ ).toBe("todos|owner:u2");
121
+ });
122
+
123
+ it("resolves tenant scope", () => {
124
+ expect(getScopeField({field: "orgId", type: "tenant"})).toBe("orgId");
125
+ expect(
126
+ resolveStreamForDoc({
127
+ collectionTag: "projects",
128
+ doc: {orgId: "org9"},
129
+ scope: {field: "orgId", type: "tenant"},
130
+ })
131
+ ).toBe("projects|tenant:org9");
132
+ });
133
+
134
+ it("resolves broadcast scope", () => {
135
+ expect(getScopeField({type: "broadcast"})).toBeNull();
136
+ expect(
137
+ resolveStreamForDoc({collectionTag: "banners", doc: {}, scope: {type: "broadcast"}})
138
+ ).toBe("banners|all");
139
+ });
140
+
141
+ // Task 9.21: readers must stay total so the change-stream watcher and the tombstone
142
+ // compactor can still name a stream for legacy rows, while the write path refuses to
143
+ // create new unroutable ones.
144
+ it("still resolves a stream for a tenant doc missing its scope value (readers are total)", () => {
145
+ expect(
146
+ resolveStreamForDoc({
147
+ collectionTag: "projects",
148
+ doc: {},
149
+ scope: {field: "orgId", type: "tenant"},
150
+ })
151
+ ).toBe("projects|tenant:undefined");
152
+ });
153
+
154
+ it("rejects WRITING a tenant doc with no scope value, whatever the model's hooks do", () => {
155
+ const scope = {field: "orgId", type: "tenant"} as const;
156
+ // The guard reads the effective document, so it holds regardless of whether the model
157
+ // happens to configure a preCreate hook (which may exist for unrelated reasons and
158
+ // never inject the tenant field).
159
+ for (const doc of [{}, {orgId: null}, {orgId: undefined}]) {
160
+ expect(() => assertWritableStream({collectionTag: "projects", doc, scope})).toThrow(
161
+ /missing tenant scope field "orgId"/
162
+ );
163
+ }
164
+ expect(() =>
165
+ assertWritableStream({collectionTag: "projects", doc: {orgId: "org9"}, scope})
166
+ ).not.toThrow();
167
+ });
168
+
169
+ it("leaves owner, broadcast, and custom scopes unguarded on write", () => {
170
+ expect(() =>
171
+ assertWritableStream({collectionTag: "todos", doc: {}, scope: {type: "owner"}})
172
+ ).not.toThrow();
173
+ expect(() =>
174
+ assertWritableStream({collectionTag: "banners", doc: {}, scope: {type: "broadcast"}})
175
+ ).not.toThrow();
176
+ expect(() =>
177
+ assertWritableStream({collectionTag: "shops", doc: {}, scope: () => "eu"})
178
+ ).not.toThrow();
179
+ });
180
+
181
+ it("resolves custom scope via resolver function", () => {
182
+ const scope = (doc: Record<string, unknown>): string => `${doc.region}`;
183
+ expect(getScopeField(scope)).toBeNull();
184
+ expect(resolveStreamForDoc({collectionTag: "shops", doc: {region: "eu"}, scope})).toBe(
185
+ "shops|custom:eu"
186
+ );
187
+ expect(streamForScopeValue({collectionTag: "shops", scope, scopeValue: "us"})).toBe(
188
+ "shops|custom:us"
189
+ );
190
+ });
191
+ });
192
+
193
+ describe("registerSync validation", () => {
194
+ beforeAll(async () => {
195
+ await setupDb();
196
+ });
197
+
198
+ beforeEach(() => {
199
+ clearSyncRegistry();
200
+ });
201
+
202
+ it("throws when the model lacks soft delete", () => {
203
+ expect(() =>
204
+ registerSync({
205
+ config: ownerConfig,
206
+ model: NoDeleteModel as any,
207
+ options: stubOptions,
208
+ routePath: "/noDelete",
209
+ })
210
+ ).toThrow(/soft delete/);
211
+ });
212
+
213
+ it("throws when the model lacks syncPlugin", () => {
214
+ expect(() =>
215
+ registerSync({
216
+ config: ownerConfig,
217
+ model: NoPluginModel as any,
218
+ options: stubOptions,
219
+ routePath: "/noPlugin",
220
+ })
221
+ ).toThrow(/syncPlugin/);
222
+ });
223
+
224
+ it("throws when the scope field does not exist on the schema", () => {
225
+ expect(() =>
226
+ registerSync({
227
+ config: {scope: {field: "workspaceId", type: "tenant"}},
228
+ model: SyncStuffModel as any,
229
+ options: stubOptions,
230
+ routePath: "/syncStuff",
231
+ })
232
+ ).toThrow(/workspaceId/);
233
+ });
234
+
235
+ it("throws on duplicate registration", () => {
236
+ registerStuff();
237
+ expect(() => registerStuff()).toThrow(/already registered/);
238
+ });
239
+
240
+ it("registers a compliant model and exposes lookup helpers", () => {
241
+ registerStuff();
242
+ expect(getSyncRegistry()).toHaveLength(1);
243
+ expect(findSyncEntryByModelName("SyncStuff")?.collectionTag).toBe("syncStuff");
244
+ expect(findSyncEntryByCollectionTag("syncStuff")?.modelName).toBe("SyncStuff");
245
+ });
246
+
247
+ it("makes bulkWrite throw on the registered model (it bypasses every plugin guard)", () => {
248
+ registerStuff();
249
+ expect(() =>
250
+ (SyncStuffModel as any).bulkWrite([
251
+ {updateOne: {filter: {_id: "any"}, update: {$set: {name: "nope"}}}},
252
+ ])
253
+ ).toThrow(/bulkWrite is not supported on sync-enabled model SyncStuff/);
254
+ });
255
+
256
+ // Task 9.21: tenant/custom scopes can only be resolved from the full user document, so a
257
+ // socket layer without a userModel silently serves empty tenant streams.
258
+ describe("warnOnSyncScopesWithoutUserModel", () => {
259
+ it("names tenant-scoped collections when no userModel is configured", () => {
260
+ registerStuff({scope: {field: "orgId", type: "tenant"}});
261
+ expect(warnOnSyncScopesWithoutUserModel({})).toEqual(["syncStuff"]);
262
+ });
263
+
264
+ it("stays quiet once a userModel is configured", () => {
265
+ registerStuff({scope: {field: "orgId", type: "tenant"}});
266
+ expect(warnOnSyncScopesWithoutUserModel({userModel: {} as never})).toEqual([]);
267
+ });
268
+
269
+ it("stays quiet for owner-scoped collections, which need no membership fields", () => {
270
+ registerStuff();
271
+ expect(warnOnSyncScopesWithoutUserModel({})).toEqual([]);
272
+ });
273
+ });
274
+ });
275
+
276
+ describe("modelRouter sync option", () => {
277
+ beforeAll(async () => {
278
+ await setupDb();
279
+ });
280
+
281
+ beforeEach(() => {
282
+ clearSyncRegistry();
283
+ });
284
+
285
+ it("registers the model for sync in the three-argument form", () => {
286
+ const registration = modelRouter("/syncStuff", SyncStuffModel as any, {
287
+ ...stubOptions,
288
+ sync: ownerConfig,
289
+ });
290
+ expect((registration as {__type: string}).__type).toBe("modelRouter");
291
+ expect(findSyncEntryByCollectionTag("syncStuff")).toBeDefined();
292
+ });
293
+
294
+ it("does not register in the two-argument form", () => {
295
+ modelRouter(SyncStuffModel as any, {...stubOptions, sync: ownerConfig});
296
+ expect(findSyncEntryByCollectionTag("syncStuff")).toBeUndefined();
297
+ });
298
+ });
299
+
300
+ describe("syncPlugin seq stamping", () => {
301
+ beforeAll(async () => {
302
+ await setupDb();
303
+ });
304
+
305
+ beforeEach(async () => {
306
+ clearSyncRegistry();
307
+ registerStuff();
308
+ await Promise.all([
309
+ SyncStuffModel.deleteMany({}).catch(() => undefined),
310
+ UnregisteredModel.collection.deleteMany({}),
311
+ SyncCounter.deleteMany({}),
312
+ ]);
313
+ });
314
+
315
+ it("stamps monotonic seqs per stream across create and update", async () => {
316
+ const doc = await SyncStuffModel.create({name: "one", ownerId: "u1"});
317
+ expect(doc._syncSeq).toBe(1);
318
+ expect(doc._syncPrevStream).toBeNull();
319
+
320
+ doc.name = "one updated";
321
+ await doc.save();
322
+ expect(doc._syncSeq).toBe(2);
323
+ expect(doc._syncPrevStream).toBeNull();
324
+ });
325
+
326
+ it("keeps independent streams per owner", async () => {
327
+ const a = await SyncStuffModel.create({name: "a", ownerId: "userA"});
328
+ const b = await SyncStuffModel.create({name: "b", ownerId: "userB"});
329
+ expect(a._syncSeq).toBe(1);
330
+ expect(b._syncSeq).toBe(1);
331
+ const counters = await SyncCounter.find({}).sort({stream: 1});
332
+ expect(counters.map((c) => c.stream)).toEqual([
333
+ "syncStuff|owner:userA",
334
+ "syncStuff|owner:userB",
335
+ ]);
336
+ });
337
+
338
+ it("assigns unique seqs under concurrent writes to one stream", async () => {
339
+ const docs = await Promise.all(
340
+ Array.from({length: 10}, (_, i) =>
341
+ SyncStuffModel.create({name: `item ${i}`, ownerId: "concurrent"})
342
+ )
343
+ );
344
+ const seqs = docs.map((d) => d._syncSeq).sort((x, y) => (x ?? 0) - (y ?? 0));
345
+ expect(seqs).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
346
+ });
347
+
348
+ it("does not consume a seq when validation fails", async () => {
349
+ await expect(SyncStuffModel.create({ownerId: "u1"} as any)).rejects.toThrow();
350
+ const doc = await SyncStuffModel.create({name: "valid", ownerId: "u1"});
351
+ expect(doc._syncSeq).toBe(1);
352
+ });
353
+
354
+ it("stamps on Model.updateOne", async () => {
355
+ const doc = await SyncStuffModel.create({name: "q", ownerId: "u1"});
356
+ await SyncStuffModel.updateOne({_id: doc._id}, {$set: {name: "q2"}});
357
+ const updated = await SyncStuffModel.findById(doc._id);
358
+ expect(updated?._syncSeq).toBe(2);
359
+ expect(updated?.name).toBe("q2");
360
+ });
361
+
362
+ it("stamps on findOneAndUpdate", async () => {
363
+ const doc = await SyncStuffModel.create({name: "f", ownerId: "u1"});
364
+ const updated = await SyncStuffModel.findOneAndUpdate(
365
+ {_id: doc._id},
366
+ {$set: {name: "f2"}},
367
+ {new: true}
368
+ );
369
+ expect(updated?._syncSeq).toBe(2);
370
+ });
371
+
372
+ it("stamps plain-object updates (implicit $set) on the correct stream", async () => {
373
+ // Regression: a plain object passed to findOneAndUpdate is an implicit $set, not a
374
+ // replacement — the scope value must come from the existing doc, not read as
375
+ // undefined from the update body (which claimed a bogus "owner:undefined" stream).
376
+ const doc = await SyncStuffModel.create({name: "p", ownerId: "u1"});
377
+ const updated = await SyncStuffModel.findOneAndUpdate(
378
+ {_id: doc._id},
379
+ {name: "p2"},
380
+ {new: true}
381
+ );
382
+ expect(updated?._syncSeq).toBe(2);
383
+ expect(updated?._syncPrevStream).toBeNull();
384
+ expect(updated?.ownerId).toBe("u1");
385
+ const counters = await SyncCounter.find({}).sort({stream: 1});
386
+ expect(counters.map((c) => c.stream)).toEqual(["syncStuff|owner:u1"]);
387
+ });
388
+
389
+ it("stamps plain-object updateOne (implicit $set) without a bogus scope move", async () => {
390
+ const doc = await SyncStuffModel.create({name: "q1", ownerId: "u1"});
391
+ await SyncStuffModel.updateOne({_id: doc._id}, {name: "q2"});
392
+ const updated = await SyncStuffModel.find({_id: doc._id});
393
+ expect(updated[0]?._syncSeq).toBe(2);
394
+ expect(updated[0]?._syncPrevStream).toBeNull();
395
+ const counters = await SyncCounter.find({});
396
+ expect(counters).toHaveLength(1);
397
+ });
398
+
399
+ it("stamps on replaceOne", async () => {
400
+ const doc = await SyncStuffModel.create({name: "r", ownerId: "u1"});
401
+ await SyncStuffModel.replaceOne({_id: doc._id}, {name: "r2", ownerId: "u1"});
402
+ const replaced = await SyncStuffModel.findById(doc._id);
403
+ expect(replaced?._syncSeq).toBe(2);
404
+ expect(replaced?.name).toBe("r2");
405
+ });
406
+
407
+ it("stamps ascending seqs on insertMany, grouped by stream", async () => {
408
+ const docs = await SyncStuffModel.insertMany([
409
+ {name: "m1", ownerId: "bulkA"},
410
+ {name: "m2", ownerId: "bulkA"},
411
+ {name: "m3", ownerId: "bulkB"},
412
+ ]);
413
+ const bulkA = docs.filter((d) => d.ownerId === "bulkA").map((d) => d._syncSeq);
414
+ const bulkB = docs.filter((d) => d.ownerId === "bulkB").map((d) => d._syncSeq);
415
+ expect(bulkA).toEqual([1, 2]);
416
+ expect(bulkB).toEqual([1]);
417
+ });
418
+
419
+ it("no-ops for models with the plugin that are not registered", async () => {
420
+ const doc = await UnregisteredModel.create({name: "free", ownerId: "u1"});
421
+ expect(doc._syncSeq).toBeUndefined();
422
+ });
423
+
424
+ it("records _syncPrevStream when a save moves the doc between owners", async () => {
425
+ const doc = await SyncStuffModel.create({name: "mover", ownerId: "oldOwner"});
426
+ const loaded = await SyncStuffModel.findById(doc._id);
427
+ expect(loaded).toBeDefined();
428
+ if (!loaded) {
429
+ throw new Error("doc not found");
430
+ }
431
+ loaded.ownerId = "newOwner";
432
+ await loaded.save();
433
+ expect(loaded._syncPrevStream).toBe("syncStuff|owner:oldOwner");
434
+ expect(loaded._syncSeq).toBe(1); // first write on the newOwner stream
435
+
436
+ loaded.name = "no move this time";
437
+ await loaded.save();
438
+ expect(loaded._syncPrevStream).toBeNull();
439
+ });
440
+
441
+ it("records _syncPrevStream when findOneAndUpdate moves the doc between owners", async () => {
442
+ const doc = await SyncStuffModel.create({name: "qmover", ownerId: "oldOwner"});
443
+ const updated = await SyncStuffModel.findOneAndUpdate(
444
+ {_id: doc._id},
445
+ {$set: {ownerId: "newOwner"}},
446
+ {new: true}
447
+ );
448
+ expect(updated?._syncPrevStream).toBe("syncStuff|owner:oldOwner");
449
+ expect(updated?._syncSeq).toBe(1);
450
+ });
451
+
452
+ it("sequences soft deletes as tombstones", async () => {
453
+ const doc = await SyncStuffModel.create({name: "bye", ownerId: "u1"});
454
+ doc.deleted = true;
455
+ await doc.save();
456
+ expect(doc._syncSeq).toBe(2);
457
+ });
458
+
459
+ it("stamps updates to existing tombstones (the internal lookup sees deleted docs)", async () => {
460
+ const doc = await SyncStuffModel.create({name: "ghost", ownerId: "u1"});
461
+ doc.deleted = true;
462
+ await doc.save();
463
+ await SyncStuffModel.updateOne({_id: doc._id}, {$set: {name: "ghost2"}});
464
+ const revived = await SyncStuffModel.find({_id: doc._id, deleted: true});
465
+ expect(revived[0]?._syncSeq).toBe(3);
466
+ expect(revived[0]?.name).toBe("ghost2");
467
+ });
468
+
469
+ it("leaves updates that match nothing unstamped and unclaimed", async () => {
470
+ await SyncStuffModel.updateOne({_id: "000000000000000000000000"}, {$set: {name: "nobody"}});
471
+ const counters = await SyncCounter.find({});
472
+ expect(counters).toHaveLength(0);
473
+ });
474
+ });
475
+
476
+ describe("syncPlugin unsupported write guards", () => {
477
+ beforeAll(async () => {
478
+ await setupDb();
479
+ });
480
+
481
+ beforeEach(async () => {
482
+ clearSyncRegistry();
483
+ registerStuff();
484
+ await SyncCounter.deleteMany({});
485
+ });
486
+
487
+ it("throws on updateMany", async () => {
488
+ await expect(
489
+ SyncStuffModel.updateMany({ownerId: "u1"}, {$set: {name: "x"}}).exec()
490
+ ).rejects.toThrow(/updateMany is not supported/);
491
+ });
492
+
493
+ it("throws on deleteMany", async () => {
494
+ await expect(SyncStuffModel.deleteMany({ownerId: "u1"}).exec()).rejects.toThrow(
495
+ /deleteMany is not supported/
496
+ );
497
+ });
498
+
499
+ it("throws on query deleteOne", async () => {
500
+ await expect(SyncStuffModel.deleteOne({ownerId: "u1"}).exec()).rejects.toThrow(
501
+ /deleteOne is not supported/
502
+ );
503
+ });
504
+
505
+ it("throws on findOneAndDelete", async () => {
506
+ await expect(SyncStuffModel.findOneAndDelete({ownerId: "u1"}).exec()).rejects.toThrow(
507
+ /findOneAndDelete is not supported/
508
+ );
509
+ });
510
+
511
+ it("throws on document deleteOne (hard delete)", async () => {
512
+ const doc = await SyncStuffModel.create({name: "hard", ownerId: "u1"});
513
+ await expect(doc.deleteOne().exec()).rejects.toThrow(/hard delete/);
514
+ });
515
+
516
+ it("allows all of these on unregistered models", async () => {
517
+ await UnregisteredModel.create({name: "temp", ownerId: "u1"});
518
+ await expect(
519
+ UnregisteredModel.updateMany({ownerId: "u1"}, {$set: {name: "y"}}).exec()
520
+ ).resolves.toBeDefined();
521
+ await expect(UnregisteredModel.deleteMany({ownerId: "u1"}).exec()).resolves.toBeDefined();
522
+ });
523
+ });
524
+
525
+ describe("claimSyncSeqs", () => {
526
+ beforeAll(async () => {
527
+ await setupDb();
528
+ });
529
+
530
+ beforeEach(async () => {
531
+ await SyncCounter.deleteMany({});
532
+ });
533
+
534
+ it("claims monotonic seqs and batch ranges", async () => {
535
+ expect((await claimSyncSeqs({stream: "s|a"})).lastSeq).toBe(1);
536
+ const batch = await claimSyncSeqs({count: 5, stream: "s|a"});
537
+ expect(batch.lastSeq).toBe(6);
538
+ expect(batch.seqs).toEqual([2, 3, 4, 5, 6]);
539
+ expect((await claimSyncSeqs({stream: "s|a"})).lastSeq).toBe(7);
540
+ expect((await claimSyncSeqs({stream: "s|b"})).lastSeq).toBe(1);
541
+ });
542
+
543
+ it("survives concurrent first claims for a new stream", async () => {
544
+ const results = await Promise.all(
545
+ Array.from({length: 5}, () => claimSyncSeqs({stream: "s|fresh"}))
546
+ );
547
+ expect(results.map((r) => r.lastSeq).sort((a, b) => a - b)).toEqual([1, 2, 3, 4, 5]);
548
+ });
549
+ });
550
+
551
+ describe("getOrCreateSyncKeyMaterial", () => {
552
+ beforeAll(async () => {
553
+ await setupDb();
554
+ });
555
+
556
+ beforeEach(async () => {
557
+ await SyncKey.deleteMany({});
558
+ });
559
+
560
+ it("creates on first call and returns the same material afterwards", async () => {
561
+ const first = await getOrCreateSyncKeyMaterial({userId: "user1"});
562
+ const second = await getOrCreateSyncKeyMaterial({userId: "user1"});
563
+ expect(first).toBe(second);
564
+ expect(Buffer.from(first, "base64")).toHaveLength(32);
565
+ });
566
+
567
+ it("gives distinct users distinct material", async () => {
568
+ const a = await getOrCreateSyncKeyMaterial({userId: "userA"});
569
+ const b = await getOrCreateSyncKeyMaterial({userId: "userB"});
570
+ expect(a).not.toBe(b);
571
+ });
572
+
573
+ it("converges concurrent first calls on one persisted value", async () => {
574
+ const results = await Promise.all(
575
+ Array.from({length: 5}, () => getOrCreateSyncKeyMaterial({userId: "racer"}))
576
+ );
577
+ expect(new Set(results).size).toBe(1);
578
+ const docs = await SyncKey.find({userId: "racer"});
579
+ expect(docs).toHaveLength(1);
580
+ expect(docs[0].keyMaterial).toBe(results[0]);
581
+ });
582
+ });
@@ -0,0 +1,44 @@
1
+ import type express from "express";
2
+ import type {TerrenoPlugin} from "../terrenoPlugin";
3
+ import {ensureSyncModelIndexes} from "./models";
4
+ import {trackSyncIndexCreation} from "./registry";
5
+ import {addSyncRoutes, type SyncAppOptions} from "./routes";
6
+
7
+ const SYNC_APP_OPTIONS_LOCAL_KEY = "terrenoSyncAppOptions";
8
+
9
+ /** Resolve the SyncApp configuration attached to one Express application. */
10
+ export const getSyncAppOptions = (app: express.Application): SyncAppOptions | undefined =>
11
+ app.locals[SYNC_APP_OPTIONS_LOCAL_KEY] as SyncAppOptions | undefined;
12
+
13
+ /**
14
+ * TerrenoPlugin mounting the SyncDB local-first sync HTTP routes
15
+ * (`GET /sync/snapshot`, `POST /sync/mutate`, `GET /sync/key`). Models opt in via
16
+ * modelRouter's `sync` option; this plugin serves the registered collections.
17
+ *
18
+ * Registration attaches the plugin's options (notably `getUserScopes`) to this Express
19
+ * application so RealtimeApp's connection handler can install the socket
20
+ * mutation/subscription channel (`sync:subscribe`, `sync:mutate`) with the same
21
+ * configuration — the socket layer requires both plugins: SyncApp for config/routes and
22
+ * RealtimeApp for the Socket.io server and `sync:delta` emission.
23
+ *
24
+ * Registration also kicks off the bookkeeping-model index builds (`SyncCounter`,
25
+ * `SyncMutation`, `SyncScopeMove`, `SyncKey`) and enqueues them for `ensureSyncIndexes()`,
26
+ * which `TerrenoApp.start()` awaits before listening. Those indexes are correctness
27
+ * requirements — the unique `mutationId` index is what makes duplicate mutation deliveries
28
+ * idempotent, and the unique `stream` index is what keeps the counter upsert race from
29
+ * minting duplicate seqs — so an index-build failure fails startup loudly. Apps that build
30
+ * the Express app without `TerrenoApp.start()` should await `ensureSyncIndexes()` themselves.
31
+ */
32
+ export class SyncApp implements TerrenoPlugin {
33
+ private readonly options: SyncAppOptions;
34
+
35
+ constructor(options: SyncAppOptions = {}) {
36
+ this.options = options;
37
+ }
38
+
39
+ register(app: express.Application): void {
40
+ app.locals[SYNC_APP_OPTIONS_LOCAL_KEY] = this.options;
41
+ trackSyncIndexCreation(ensureSyncModelIndexes());
42
+ addSyncRoutes(app, this.options);
43
+ }
44
+ }