@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,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
+ });