@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,618 @@
1
+ // noExplicitAny: the harness bridges generic model/router/client types, mirroring integration.test.ts
2
+ // biome-ignore-all lint/suspicious/noExplicitAny: the harness bridges generic model/router/client types, mirroring integration.test.ts
3
+ /**
4
+ * This is a manual load-generation script — NOT run by `bun test`. Invoke via
5
+ * `bun run api:load` (see root package.json) or directly:
6
+ * `bun run api/src/sync/loadHarness.ts [--clients=20] [--seedDocs=5000] [--targetRate=200] [--durationSec=30] [--mongoUri=...] [--port=0]`
7
+ * Requires a real MongoDB replica set (change streams power live delta fan-out).
8
+ *
9
+ * Stands up one in-process Express + Socket.io server with a synced Mongoose model
10
+ * (mirroring `IntTodo` from `sync/integration.test.ts`), then drives N real
11
+ * `@terreno/syncdb` clients (each a distinct owner) against it over real HTTP/socket
12
+ * transports: seeds documents, bootstraps all clients, then issues a mixed
13
+ * create/update/delete mutation load — including deliberate duplicate mutationIds
14
+ * and deliberate update/update conflicts — while measuring:
15
+ * - mutate round-trip latency (p50/p95/p99)
16
+ * - change-stream -> sync:delta fan-out lag across all connected sockets
17
+ * - bootstrap wall time at the seeded doc count
18
+ * - final-state convergence (each client's local store vs. what Mongo holds)
19
+ *
20
+ * This is a load/perf tool, not a correctness test suite — assertions are logged as
21
+ * pass/fail lines rather than thrown, so a single divergent client doesn't abort the
22
+ * report. The process exits non-zero if any client fails to converge.
23
+ */
24
+ import {createServer, type Server as HttpServer} from "node:http";
25
+ import type {AddressInfo} from "node:net";
26
+ import {
27
+ type AuthProvider,
28
+ clearMemoryPersisterData,
29
+ createHttpChannel,
30
+ createSocketTransport,
31
+ createSyncDb,
32
+ type FetchLike,
33
+ type HttpChannel,
34
+ listConflicts,
35
+ memoryPersisterFactory,
36
+ type SyncDb,
37
+ type SyncMutateRequest,
38
+ type SyncTransport,
39
+ } from "@terreno/syncdb";
40
+ import express from "express";
41
+ import mongoose, {model, Schema} from "mongoose";
42
+ import passportLocalMongoose from "passport-local-mongoose";
43
+
44
+ import {modelRouter} from "../api";
45
+ import {addAuthRoutes, generateTokens, setupAuth} from "../auth";
46
+ import {logger} from "../logger";
47
+ import {Permissions} from "../permissions";
48
+ import {createdUpdatedPlugin, type IsDeleted, isDeletedPlugin} from "../plugins";
49
+ import {RealtimeApp} from "../realtime/realtimeApp";
50
+ import {clearSyncRegistry} from "./registry";
51
+ import {SyncApp} from "./syncApp";
52
+ import {syncPlugin} from "./syncSeqPlugin";
53
+
54
+ // ─────────────────────────────────────────────────────────────────────────────
55
+ // CLI flags
56
+ // ─────────────────────────────────────────────────────────────────────────────
57
+
58
+ interface HarnessConfig {
59
+ clients: number;
60
+ seedDocs: number;
61
+ targetRate: number;
62
+ durationSec: number;
63
+ mongoUri: string;
64
+ port: number;
65
+ }
66
+
67
+ /** Simple `--flag=value` argv parser; no CLI framework needed for a one-off script. */
68
+ const parseFlags = (argv: string[]): HarnessConfig => {
69
+ const flags = new Map<string, string>();
70
+ for (const arg of argv) {
71
+ const match = /^--([^=]+)=(.*)$/.exec(arg);
72
+ if (match) {
73
+ flags.set(match[1], match[2]);
74
+ }
75
+ }
76
+ const num = (key: string, fallback: number): number => {
77
+ const raw = flags.get(key);
78
+ if (raw === undefined) {
79
+ return fallback;
80
+ }
81
+ const parsed = Number(raw);
82
+ return Number.isFinite(parsed) ? parsed : fallback;
83
+ };
84
+ return {
85
+ clients: num("clients", 20),
86
+ durationSec: num("durationSec", 30),
87
+ mongoUri:
88
+ flags.get("mongoUri") ??
89
+ process.env.MONGO_URI ??
90
+ "mongodb://127.0.0.1:27017/terreno-sync-load?replicaSet=rs0",
91
+ port: num("port", 0),
92
+ seedDocs: num("seedDocs", 5_000),
93
+ targetRate: num("targetRate", 200),
94
+ };
95
+ };
96
+
97
+ // ─────────────────────────────────────────────────────────────────────────────
98
+ // Synced load-test model (mirrors IntTodo from integration.test.ts)
99
+ // ─────────────────────────────────────────────────────────────────────────────
100
+
101
+ interface LoadTodo extends IsDeleted {
102
+ _id: string;
103
+ title: string;
104
+ completed: boolean;
105
+ ownerId: string;
106
+ created: Date;
107
+ _syncSeq?: number;
108
+ }
109
+
110
+ const loadTodoSchema = new Schema<LoadTodo>({
111
+ _id: {
112
+ default: (): string => new mongoose.Types.ObjectId().toHexString(),
113
+ description: "The document id (string so offline clients can mint ids)",
114
+ type: String,
115
+ },
116
+ completed: {
117
+ default: false,
118
+ description: "Whether the load-test todo has been completed",
119
+ type: Boolean,
120
+ },
121
+ ownerId: {description: "The user who owns this load-test todo", type: String},
122
+ title: {description: "The title of the load-test todo", required: true, type: String},
123
+ });
124
+ loadTodoSchema.plugin(isDeletedPlugin);
125
+ loadTodoSchema.plugin(createdUpdatedPlugin);
126
+ loadTodoSchema.plugin(syncPlugin);
127
+ const LoadTodoModel = model<LoadTodo>("LoadHarnessTodo", loadTodoSchema);
128
+
129
+ const COLLECTION = "loadHarnessTodos";
130
+
131
+ // ─────────────────────────────────────────────────────────────────────────────
132
+ // Percentile helper
133
+ // ─────────────────────────────────────────────────────────────────────────────
134
+
135
+ const percentile = (samples: number[], p: number): number => {
136
+ if (samples.length === 0) {
137
+ return 0;
138
+ }
139
+ const sorted = [...samples].sort((a, b) => a - b);
140
+ const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1));
141
+ return sorted[index];
142
+ };
143
+
144
+ // ─────────────────────────────────────────────────────────────────────────────
145
+ // Rig helpers
146
+ // ─────────────────────────────────────────────────────────────────────────────
147
+
148
+ /** Poll until the predicate holds, or throw naming the failed wait. */
149
+ const waitFor = async (
150
+ predicate: () => boolean | Promise<boolean>,
151
+ {
152
+ label = "condition",
153
+ timeoutMs = 30_000,
154
+ intervalMs = 25,
155
+ }: {
156
+ label?: string;
157
+ timeoutMs?: number;
158
+ intervalMs?: number;
159
+ } = {}
160
+ ): Promise<void> => {
161
+ const start = Date.now();
162
+ while (Date.now() - start < timeoutMs) {
163
+ if (await predicate()) {
164
+ return;
165
+ }
166
+ await new Promise((resolve) => setTimeout(resolve, intervalMs));
167
+ }
168
+ throw new Error(`Timed out after ${timeoutMs}ms waiting for ${label}`);
169
+ };
170
+
171
+ interface HarnessClient {
172
+ name: string;
173
+ user: {_id: unknown};
174
+ ownerId: string;
175
+ client: SyncDb;
176
+ httpChannel: HttpChannel;
177
+ transport: SyncTransport;
178
+ }
179
+
180
+ const makeAuthProvider = (user: {_id: unknown}): AuthProvider => ({
181
+ getToken: async () => (await generateTokens(user)).token ?? null,
182
+ getUserId: async () => String(user._id),
183
+ onAuthChange: () => () => {},
184
+ });
185
+
186
+ const makeHarnessClient = ({
187
+ name,
188
+ user,
189
+ baseUrl,
190
+ }: {
191
+ name: string;
192
+ user: {_id: unknown};
193
+ baseUrl: string;
194
+ }): HarnessClient => {
195
+ const authProvider = makeAuthProvider(user);
196
+ const fetchImpl: FetchLike = (input, init) => fetch(input, init);
197
+ const httpChannel = createHttpChannel({authProvider, baseUrl, fetchImpl});
198
+ const transport = createSocketTransport({authProvider, baseUrl, timeoutMs: 8_000});
199
+ clearMemoryPersisterData({databaseName: name});
200
+ const client = createSyncDb({
201
+ authProvider,
202
+ collections: [COLLECTION],
203
+ httpChannel,
204
+ name,
205
+ persisterFactory: memoryPersisterFactory,
206
+ reconcileIntervalMs: 0,
207
+ transport,
208
+ });
209
+ return {client, httpChannel, name, ownerId: String(user._id), transport, user};
210
+ };
211
+
212
+ /** Build the Express + Socket.io rig: synced model, SyncApp, RealtimeApp, listening server. */
213
+ const buildRig = async (
214
+ config: HarnessConfig
215
+ ): Promise<{httpServer: HttpServer; realtimeApp: RealtimeApp; baseUrl: string}> => {
216
+ process.env.TOKEN_SECRET = process.env.TOKEN_SECRET ?? "load-harness-token-secret";
217
+ process.env.TOKEN_ISSUER = process.env.TOKEN_ISSUER ?? "terreno-load-harness";
218
+ process.env.REFRESH_TOKEN_SECRET =
219
+ process.env.REFRESH_TOKEN_SECRET ?? "load-harness-refresh-secret";
220
+ process.env.SESSION_SECRET = process.env.SESSION_SECRET ?? "load-harness-session-secret";
221
+
222
+ clearSyncRegistry();
223
+
224
+ // Fresh User model bound to this script's own mongoose connection. setupAuth requires
225
+ // a passport-local-mongoose-backed model (createStrategy/serializeUser/deserializeUser),
226
+ // even though the harness only ever mints JWTs directly via generateTokens and never
227
+ // exercises the password login route.
228
+ const userSchema = new Schema<{email: string; admin: boolean}>({
229
+ admin: {default: false, description: "Whether the user has admin privileges", type: Boolean},
230
+ email: {description: "The user's email", type: String},
231
+ });
232
+ userSchema.plugin(
233
+ passportLocalMongoose as unknown as (schema: Schema, options?: Record<string, unknown>) => void,
234
+ {usernameField: "email"}
235
+ );
236
+ const UserModel = mongoose.models.LoadHarnessUser ?? model("LoadHarnessUser", userSchema);
237
+
238
+ // modelRouter's 3-argument form both registers the sync entry AND returns the
239
+ // Express router to mount, so a single call does both — no need to call it twice.
240
+ const registration = modelRouter<LoadTodo>("/loadHarnessTodos", LoadTodoModel, {
241
+ permissions: {
242
+ create: [Permissions.IsAuthenticated],
243
+ delete: [Permissions.IsOwner],
244
+ list: [Permissions.IsAuthenticated],
245
+ read: [Permissions.IsOwner],
246
+ update: [Permissions.IsOwner],
247
+ },
248
+ preCreate: (body, req) => {
249
+ const user = req.user as unknown as {_id?: unknown; id?: unknown} | undefined;
250
+ return {...body, ownerId: String(user?._id ?? user?.id ?? "")} as LoadTodo;
251
+ },
252
+ sync: {scope: {type: "owner"}},
253
+ });
254
+
255
+ const app = express();
256
+ app.use(express.json());
257
+ setupAuth(app as any, UserModel as any);
258
+ addAuthRoutes(app as any, UserModel as any);
259
+ new SyncApp({}).register(app as any);
260
+ app.use(registration.path, registration.router);
261
+
262
+ const realtimeApp = new RealtimeApp({});
263
+ realtimeApp.register(app as any);
264
+
265
+ const httpServer = createServer(app);
266
+ await new Promise<void>((resolve) => {
267
+ httpServer.listen(config.port, () => resolve());
268
+ });
269
+ const {port} = httpServer.address() as AddressInfo;
270
+ const baseUrl = `http://127.0.0.1:${port}`;
271
+
272
+ realtimeApp.onServerCreated(httpServer);
273
+ // Give the change-stream cursor a moment to open before any writes happen.
274
+ await new Promise((resolve) => setTimeout(resolve, 300));
275
+
276
+ return {baseUrl, httpServer, realtimeApp};
277
+ };
278
+
279
+ // ─────────────────────────────────────────────────────────────────────────────
280
+ // Main
281
+ // ─────────────────────────────────────────────────────────────────────────────
282
+
283
+ const main = async (): Promise<void> => {
284
+ const config = parseFlags(process.argv.slice(2));
285
+ logger.info("[loadHarness] starting", config as unknown as Record<string, unknown>);
286
+
287
+ await mongoose.connect(config.mongoUri);
288
+
289
+ await Promise.all([
290
+ LoadTodoModel.collection.deleteMany({}),
291
+ mongoose.connection.db?.collection("syncmutations").deleteMany({}),
292
+ mongoose.connection.db?.collection("synccounters").deleteMany({}),
293
+ ]);
294
+
295
+ const {httpServer, realtimeApp, baseUrl} = await buildRig(config);
296
+
297
+ let exitCode = 0;
298
+ const harnessClients: HarnessClient[] = [];
299
+
300
+ try {
301
+ // ── N users, one owner stream each ──────────────────────────────────────
302
+ const UserModel = mongoose.models.LoadHarnessUser;
303
+ const users: {_id: unknown}[] = [];
304
+ for (let i = 0; i < config.clients; i++) {
305
+ const user = await UserModel.create({admin: false, email: `load-client-${i}@example.com`});
306
+ users.push(user as unknown as {_id: unknown});
307
+ }
308
+
309
+ for (let i = 0; i < config.clients; i++) {
310
+ harnessClients.push(makeHarnessClient({baseUrl, name: `load-client-${i}`, user: users[i]}));
311
+ }
312
+
313
+ // ── Start all clients, wait for online ──────────────────────────────────
314
+ await Promise.all(harnessClients.map((hc) => hc.client.start()));
315
+ await waitFor(() => harnessClients.every((hc) => hc.client.getSyncStatus().isOnline), {
316
+ label: "all clients online",
317
+ timeoutMs: 30_000,
318
+ });
319
+ logger.info(`[loadHarness] ${harnessClients.length} clients online`);
320
+
321
+ // ── Seed docs round-robin across owners; measure bootstrap wall time ────
322
+ const perOwnerCount = new Map<string, number>();
323
+ const seeds = Array.from({length: config.seedDocs}, (_, i) => {
324
+ const owner = harnessClients[i % harnessClients.length];
325
+ perOwnerCount.set(owner.ownerId, (perOwnerCount.get(owner.ownerId) ?? 0) + 1);
326
+ return {ownerId: owner.ownerId, title: `seed-${i}`};
327
+ });
328
+
329
+ const bootstrapStart = Date.now();
330
+ if (seeds.length > 0) {
331
+ await LoadTodoModel.insertMany(seeds);
332
+ }
333
+
334
+ await waitFor(
335
+ () =>
336
+ harnessClients.every((hc) => {
337
+ const expected = perOwnerCount.get(hc.ownerId) ?? 0;
338
+ return hc.client.store.listEntities({collection: COLLECTION}).length >= expected;
339
+ }),
340
+ {label: `bootstrap convergence at ${config.seedDocs} docs`, timeoutMs: 120_000}
341
+ );
342
+ const bootstrapWallMs = Date.now() - bootstrapStart;
343
+ logger.info(`[loadHarness] bootstrap converged in ${bootstrapWallMs}ms`);
344
+
345
+ // ── Driven mutation load ─────────────────────────────────────────────────
346
+ const mutateLatenciesMs: number[] = [];
347
+ const fanoutLagsMs: number[] = [];
348
+ let conflictCount = 0;
349
+ let ackCount = 0;
350
+ let nackCount = 0;
351
+ let duplicateCount = 0;
352
+
353
+ /** Poll the outbox for a mutation to reach a terminal status, recording latency. */
354
+ const trackMutation = async (
355
+ hc: HarnessClient,
356
+ mutationId: string,
357
+ startedAt: number
358
+ ): Promise<void> => {
359
+ try {
360
+ await waitFor(
361
+ () => {
362
+ const mutation = hc.client.outbox.getMutation({mutationId});
363
+ return (
364
+ mutation === undefined ||
365
+ mutation.status === "acked" ||
366
+ mutation.status === "conflicted" ||
367
+ mutation.status === "failed"
368
+ );
369
+ },
370
+ {intervalMs: 8, label: `mutation ${mutationId} terminal`, timeoutMs: 15_000}
371
+ );
372
+ mutateLatenciesMs.push(Date.now() - startedAt);
373
+ const mutation = hc.client.outbox.getMutation({mutationId});
374
+ if (mutation?.status === "conflicted") {
375
+ conflictCount += 1;
376
+ } else if (mutation?.status === "failed") {
377
+ nackCount += 1;
378
+ } else {
379
+ ackCount += 1;
380
+ }
381
+ } catch {
382
+ // Timed out waiting; still record whatever elapsed so the report reflects it.
383
+ mutateLatenciesMs.push(Date.now() - startedAt);
384
+ }
385
+ };
386
+
387
+ const randomClient = (): HarnessClient =>
388
+ harnessClients[Math.floor(Math.random() * harnessClients.length)];
389
+
390
+ const knownEntityIds: {clientIndex: number; id: string}[] = [];
391
+ for (const [i, hc] of harnessClients.entries()) {
392
+ for (const entity of hc.client.store.listEntities({collection: COLLECTION})) {
393
+ knownEntityIds.push({clientIndex: i, id: entity.id});
394
+ }
395
+ }
396
+
397
+ const loadPromises: Promise<void>[] = [];
398
+ const intervalMs = 1000 / config.targetRate;
399
+ const loadEnd = Date.now() + config.durationSec * 1000;
400
+
401
+ while (Date.now() < loadEnd) {
402
+ const hc = randomClient();
403
+ const opRoll = Math.random();
404
+
405
+ if (opRoll < 0.5 || knownEntityIds.length === 0) {
406
+ // Create.
407
+ const startedAt = Date.now();
408
+ const {mutationId} = hc.client.mutate({
409
+ collection: COLLECTION,
410
+ data: {title: `load-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`},
411
+ operation: "create",
412
+ });
413
+ loadPromises.push(trackMutation(hc, mutationId, startedAt));
414
+ } else if (opRoll < 0.85) {
415
+ // Update.
416
+ const target = knownEntityIds[Math.floor(Math.random() * knownEntityIds.length)];
417
+ const owner = harnessClients[target.clientIndex];
418
+ const startedAt = Date.now();
419
+ const {mutationId} = owner.client.mutate({
420
+ collection: COLLECTION,
421
+ data: {title: `updated-${Date.now()}`},
422
+ id: target.id,
423
+ operation: "update",
424
+ });
425
+ loadPromises.push(trackMutation(owner, mutationId, startedAt));
426
+
427
+ // Deliberate mid-batch conflict: race a second, server-side write against the
428
+ // SAME entity underneath this client's just-queued optimistic edit, mirroring
429
+ // integration.test.ts's 4a/4b conflict scenarios (server moves on while the
430
+ // client's mutation is still in flight/queued).
431
+ if (Math.random() < 0.1) {
432
+ void LoadTodoModel.findById(target.id)
433
+ .then((doc) => {
434
+ if (!doc) {
435
+ return;
436
+ }
437
+ doc.title = `server-race-${Date.now()}`;
438
+ return doc.save();
439
+ })
440
+ .catch(() => {});
441
+ }
442
+
443
+ // Deliberate duplicate mutationId resend: replay the exact same request via the
444
+ // lower-level httpChannel.sendMutation (mutate() always mints a fresh id, so a
445
+ // real duplicate delivery must go through the transport-level API directly, per
446
+ // integration.test.ts test "5.").
447
+ if (Math.random() < 0.05) {
448
+ const dupRequest: SyncMutateRequest = {
449
+ collection: COLLECTION,
450
+ data: {title: `dup-${Date.now()}`},
451
+ mutationId: `load-dup-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
452
+ operation: "create",
453
+ };
454
+ loadPromises.push(
455
+ owner.httpChannel
456
+ .sendMutation(dupRequest)
457
+ .then(() => owner.httpChannel.sendMutation(dupRequest))
458
+ .then(() => {
459
+ duplicateCount += 1;
460
+ })
461
+ .catch(() => {})
462
+ );
463
+ }
464
+ } else {
465
+ // Delete.
466
+ const idx = Math.floor(Math.random() * knownEntityIds.length);
467
+ const target = knownEntityIds[idx];
468
+ const owner = harnessClients[target.clientIndex];
469
+ const startedAt = Date.now();
470
+ const {mutationId} = owner.client.mutate({
471
+ collection: COLLECTION,
472
+ id: target.id,
473
+ operation: "delete",
474
+ });
475
+ loadPromises.push(trackMutation(owner, mutationId, startedAt));
476
+ knownEntityIds.splice(idx, 1);
477
+ }
478
+
479
+ // ── Fan-out lag sample: an out-of-band server write, measured against every
480
+ // connected client's local store reflecting it ─────────────────────────────
481
+ if (Math.random() < 0.02) {
482
+ const anyOwner = randomClient();
483
+ const writeStart = Date.now();
484
+ const doc = await LoadTodoModel.create({
485
+ ownerId: anyOwner.ownerId,
486
+ title: `fanout-${writeStart}`,
487
+ });
488
+ const id = String(doc._id);
489
+ knownEntityIds.push({clientIndex: harnessClients.indexOf(anyOwner), id});
490
+ loadPromises.push(
491
+ waitFor(
492
+ () =>
493
+ harnessClients.every(
494
+ (hc2) => hc2.client.store.getEntity({collection: COLLECTION, id}) !== undefined
495
+ ),
496
+ {
497
+ intervalMs: 8,
498
+ label: `fanout delta for ${id}`,
499
+ timeoutMs: 15_000,
500
+ }
501
+ )
502
+ .then(() => {
503
+ fanoutLagsMs.push(Date.now() - writeStart);
504
+ })
505
+ .catch(() => {})
506
+ );
507
+ }
508
+
509
+ await new Promise((resolve) => setTimeout(resolve, intervalMs));
510
+ }
511
+
512
+ await Promise.all(loadPromises);
513
+
514
+ // Resolve any conflicts left over from the deliberate server-race scenario the load
515
+ // phase injects (useServer: the canonical server doc wins) — exactly what a real
516
+ // client eventually does, either via user action or an auto-resolve policy. Without
517
+ // this, a conflicted mutation sits in the outbox forever and both `queuedCount` and
518
+ // the final convergence check would spuriously never settle.
519
+ for (const hc of harnessClients) {
520
+ for (const conflict of listConflicts({store: hc.client.store})) {
521
+ hc.client.resolveConflict({mutationId: conflict.mutationId, strategy: "useServer"});
522
+ }
523
+ }
524
+
525
+ // Drain any outstanding queued mutations before checking convergence.
526
+ await waitFor(() => harnessClients.every((hc) => hc.client.getSyncStatus().queuedCount === 0), {
527
+ label: "all clients drained",
528
+ timeoutMs: 60_000,
529
+ }).catch((error: unknown) => {
530
+ logger.warn(`[loadHarness] drain wait: ${String(error)}`);
531
+ });
532
+
533
+ // ── Final-state convergence check ───────────────────────────────────────
534
+ let convergenceFailures = 0;
535
+ for (const hc of harnessClients) {
536
+ const localEntities = new Map(
537
+ hc.client.store
538
+ .listEntities<{title?: string}>({collection: COLLECTION})
539
+ .map((entity) => [entity.id, {data: entity.data, seq: entity.seq}])
540
+ );
541
+ const serverDocs = await LoadTodoModel.find({deleted: {$ne: true}, ownerId: hc.ownerId});
542
+ const serverMap = new Map(
543
+ serverDocs.map((doc) => [
544
+ String(doc._id),
545
+ {seq: (doc as unknown as {_syncSeq?: number})._syncSeq ?? 0, title: doc.title},
546
+ ])
547
+ );
548
+
549
+ let matches = localEntities.size === serverMap.size;
550
+ if (matches) {
551
+ for (const [id, local] of localEntities) {
552
+ const server = serverMap.get(id);
553
+ const localData = local.data as {title?: string} | undefined;
554
+ if (!server || server.seq !== local.seq || server.title !== localData?.title) {
555
+ matches = false;
556
+ break;
557
+ }
558
+ }
559
+ }
560
+ if (!matches) {
561
+ convergenceFailures += 1;
562
+ }
563
+ logger.info(
564
+ `[loadHarness] convergence ${matches ? "PASS" : "FAIL"} for ${hc.name} (local=${localEntities.size}, server=${serverMap.size})`
565
+ );
566
+ }
567
+
568
+ // ── Report ───────────────────────────────────────────────────────────────
569
+ const report = [
570
+ "",
571
+ "==================== SyncDB Load Harness Report ====================",
572
+ `clients=${config.clients} seedDocs=${config.seedDocs} targetRate=${config.targetRate}/s durationSec=${config.durationSec}`,
573
+ "",
574
+ `Bootstrap wall time @ ${config.seedDocs} docs: ${bootstrapWallMs}ms`,
575
+ "",
576
+ "Mutate round-trip latency (ms):",
577
+ ` p50=${percentile(mutateLatenciesMs, 50).toFixed(1)} p95=${percentile(mutateLatenciesMs, 95).toFixed(1)} p99=${percentile(mutateLatenciesMs, 99).toFixed(1)} (n=${mutateLatenciesMs.length})`,
578
+ ` acked=${ackCount} conflicted=${conflictCount} failed=${nackCount} duplicateResends=${duplicateCount}`,
579
+ "",
580
+ "Change-stream -> sync:delta fan-out lag across all sockets (ms):",
581
+ fanoutLagsMs.length > 0
582
+ ? ` min=${Math.min(...fanoutLagsMs).toFixed(1)} p50=${percentile(fanoutLagsMs, 50).toFixed(1)} p95=${percentile(fanoutLagsMs, 95).toFixed(1)} max=${Math.max(...fanoutLagsMs).toFixed(1)} (n=${fanoutLagsMs.length})`
583
+ : " (no samples collected)",
584
+ "",
585
+ `Final-state convergence: ${harnessClients.length - convergenceFailures}/${harnessClients.length} clients PASS`,
586
+ "======================================================================",
587
+ "",
588
+ ].join("\n");
589
+ // Deliberately plain stdout output for a load report — not a structured log line.
590
+ process.stdout.write(report);
591
+
592
+ if (convergenceFailures > 0) {
593
+ exitCode = 1;
594
+ }
595
+ } catch (error: unknown) {
596
+ logger.error(`[loadHarness] fatal error: ${String(error)}`);
597
+ exitCode = 1;
598
+ } finally {
599
+ for (const hc of harnessClients) {
600
+ await hc.client.stop().catch(() => {});
601
+ }
602
+ realtimeApp.getIo()?.disconnectSockets(true);
603
+ httpServer.closeAllConnections?.();
604
+ await realtimeApp.close().catch(() => {});
605
+ await new Promise<void>((resolve) => {
606
+ httpServer.close(() => resolve());
607
+ });
608
+ clearSyncRegistry();
609
+ await mongoose.disconnect();
610
+ }
611
+
612
+ process.exit(exitCode);
613
+ };
614
+
615
+ main().catch((error: unknown) => {
616
+ logger.error(`[loadHarness] unhandled error: ${String(error)}`);
617
+ process.exit(1);
618
+ });