@terreno/api 57.2.0 → 57.3.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 (277) hide show
  1. package/README.md +17 -7
  2. package/dist/actions.js +19 -7
  3. package/dist/api.d.ts +4 -0
  4. package/dist/api.js +12 -24
  5. package/dist/auth.d.ts +23 -10
  6. package/dist/auth.js +97 -32
  7. package/dist/authRecovery.d.ts +5 -0
  8. package/dist/authRecovery.js +350 -0
  9. package/dist/authTokens.d.ts +8 -0
  10. package/dist/authTokens.js +162 -0
  11. package/dist/betterAuth.d.ts +33 -0
  12. package/dist/betterAuthApp.d.ts +4 -0
  13. package/dist/betterAuthApp.js +26 -8
  14. package/dist/betterAuthSetup.d.ts +44 -2
  15. package/dist/betterAuthSetup.js +288 -18
  16. package/dist/collectionRegistry.d.ts +38 -0
  17. package/dist/collectionRegistry.js +72 -0
  18. package/dist/configurationApp.d.ts +11 -2
  19. package/dist/configurationApp.js +2 -4
  20. package/dist/docLoader.js +35 -6
  21. package/dist/expressServer.d.ts +26 -3
  22. package/dist/expressServer.js +79 -11
  23. package/dist/index.d.ts +16 -0
  24. package/dist/index.js +38 -2
  25. package/dist/mcp/auth.d.ts +1 -0
  26. package/dist/mcp/auth.js +47 -25
  27. package/dist/mcp/handlers.d.ts +1 -1
  28. package/dist/mcp/handlers.js +67 -233
  29. package/dist/mcp/query.d.ts +2 -2
  30. package/dist/mcp/registry.d.ts +1 -5
  31. package/dist/mcp/registry.js +31 -20
  32. package/dist/mcp/schemaGenerator.d.ts +2 -7
  33. package/dist/mcp/schemaGenerator.js +41 -116
  34. package/dist/mcp/server.d.ts +1 -0
  35. package/dist/mcp/server.js +1 -0
  36. package/dist/mcp/serviceTokens.d.ts +16 -0
  37. package/dist/mcp/serviceTokens.js +345 -0
  38. package/dist/mcp/types.d.ts +2 -2
  39. package/dist/models/mcpServiceToken.d.ts +3 -0
  40. package/dist/models/mcpServiceToken.js +208 -0
  41. package/dist/openApiBuilder.d.ts +5 -4
  42. package/dist/openApiBuilder.js +61 -8
  43. package/dist/openApiCompat.js +1 -1
  44. package/dist/openApiValidator.js +0 -2
  45. package/dist/plugins.d.ts +14 -1
  46. package/dist/plugins.js +17 -6
  47. package/dist/populate.d.ts +2 -2
  48. package/dist/populate.js +47 -42
  49. package/dist/rateLimit/applyTrustProxy.d.ts +3 -0
  50. package/dist/rateLimit/applyTrustProxy.js +17 -0
  51. package/dist/rateLimit/createStore.d.ts +2 -0
  52. package/dist/rateLimit/createStore.js +28 -0
  53. package/dist/rateLimit/memoryStore.d.ts +2 -0
  54. package/dist/rateLimit/memoryStore.js +108 -0
  55. package/dist/rateLimit/middleware.d.ts +11 -0
  56. package/dist/rateLimit/middleware.js +110 -0
  57. package/dist/rateLimit/mongoStore.d.ts +3 -0
  58. package/dist/rateLimit/mongoStore.js +122 -0
  59. package/dist/rateLimit/policies.d.ts +14 -0
  60. package/dist/rateLimit/policies.js +151 -0
  61. package/dist/rateLimit/redisStore.d.ts +3 -0
  62. package/dist/rateLimit/redisStore.js +155 -0
  63. package/dist/rateLimit/types.d.ts +54 -0
  64. package/dist/rateLimit/types.js +9 -0
  65. package/dist/rbac/access.js +5 -1
  66. package/dist/rbac/assertAllowed.d.ts +9 -0
  67. package/dist/rbac/assertAllowed.js +182 -0
  68. package/dist/rbac/modelRouterAccess.d.ts +1 -0
  69. package/dist/rbac/modelRouterAccess.js +8 -4
  70. package/dist/rbac/permissionUtils.js +3 -2
  71. package/dist/rbac/resolve.js +5 -4
  72. package/dist/rbac/routes.js +15 -6
  73. package/dist/realtime/deprecation.d.ts +12 -0
  74. package/dist/realtime/deprecation.js +32 -0
  75. package/dist/realtime/realtimeApp.d.ts +1 -1
  76. package/dist/realtime/realtimeApp.js +10 -11
  77. package/dist/realtime/registry.d.ts +0 -31
  78. package/dist/realtime/registry.js +44 -31
  79. package/dist/realtime/socketAuth.d.ts +5 -5
  80. package/dist/realtime/socketAuth.js +11 -1
  81. package/dist/realtime/socketUser.d.ts +5 -1
  82. package/dist/realtime/types.d.ts +14 -4
  83. package/dist/schemaMetadata.d.ts +56 -0
  84. package/dist/schemaMetadata.js +513 -0
  85. package/dist/seedRunner.d.ts +88 -0
  86. package/dist/seedRunner.js +627 -0
  87. package/dist/sync/executors.d.ts +12 -2
  88. package/dist/sync/executors.js +8 -10
  89. package/dist/sync/loadHarness.js +28 -19
  90. package/dist/sync/models.js +26 -24
  91. package/dist/sync/mutationHandler.d.ts +9 -0
  92. package/dist/sync/mutationHandler.js +11 -6
  93. package/dist/sync/registrationSideEffects.d.ts +35 -0
  94. package/dist/sync/registrationSideEffects.js +151 -0
  95. package/dist/sync/registry.d.ts +2 -52
  96. package/dist/sync/registry.js +38 -187
  97. package/dist/sync/routes.js +3 -2
  98. package/dist/sync/scripts/compactTombstones.js +0 -2
  99. package/dist/sync/syncApp.d.ts +3 -3
  100. package/dist/sync/syncApp.js +4 -4
  101. package/dist/sync/syncBatch.js +3 -2
  102. package/dist/sync/syncSeqPlugin.d.ts +1 -1
  103. package/dist/sync/syncSeqPlugin.js +20 -16
  104. package/dist/terrenoApp.d.ts +19 -5
  105. package/dist/terrenoApp.js +66 -18
  106. package/dist/tests/models.d.ts +2 -0
  107. package/dist/tests/models.js +6 -0
  108. package/dist/types/authToken.d.ts +33 -0
  109. package/dist/types/authToken.js +2 -0
  110. package/dist/types/mcpServiceToken.d.ts +41 -0
  111. package/dist/types/mcpServiceToken.js +2 -0
  112. package/dist/webhooks/headerValue.d.ts +2 -0
  113. package/dist/webhooks/headerValue.js +14 -0
  114. package/dist/webhooks/idempotency/memoryStore.d.ts +10 -0
  115. package/dist/webhooks/idempotency/memoryStore.js +65 -0
  116. package/dist/webhooks/idempotency/mongoStore.d.ts +4 -0
  117. package/dist/webhooks/idempotency/mongoStore.js +150 -0
  118. package/dist/webhooks/idempotency/webhookReceipt.d.ts +62 -0
  119. package/dist/webhooks/idempotency/webhookReceipt.js +39 -0
  120. package/dist/webhooks/rawBody.d.ts +14 -0
  121. package/dist/webhooks/rawBody.js +22 -0
  122. package/dist/webhooks/timingSafeEqual.d.ts +4 -0
  123. package/dist/webhooks/timingSafeEqual.js +17 -0
  124. package/dist/webhooks/verifiers/hmac.d.ts +15 -0
  125. package/dist/webhooks/verifiers/hmac.js +49 -0
  126. package/dist/webhooks/verifiers/sendgrid.d.ts +10 -0
  127. package/dist/webhooks/verifiers/sendgrid.js +56 -0
  128. package/dist/webhooks/verifiers/stripe.d.ts +9 -0
  129. package/dist/webhooks/verifiers/stripe.js +99 -0
  130. package/dist/webhooks/verifiers/twilio.d.ts +9 -0
  131. package/dist/webhooks/verifiers/twilio.js +112 -0
  132. package/dist/webhooks/webhooksApp.d.ts +33 -0
  133. package/dist/webhooks/webhooksApp.js +195 -0
  134. package/package.json +4 -5
  135. package/src/__snapshots__/openApi.test.ts.snap +270 -0
  136. package/src/__snapshots__/openApiBuilder.test.ts.snap +30 -12
  137. package/src/__snapshots__/schemaMetadata.test.ts.snap +197 -0
  138. package/src/actions.ts +20 -13
  139. package/src/adminModelRouter.test.ts +133 -0
  140. package/src/api.arrayOperations.test.ts +43 -31
  141. package/src/api.hooks.test.ts +38 -29
  142. package/src/api.query.test.ts +31 -31
  143. package/src/api.test.ts +95 -96
  144. package/src/api.ts +16 -27
  145. package/src/auth.test.ts +107 -51
  146. package/src/auth.ts +98 -29
  147. package/src/authRecovery.test.ts +281 -0
  148. package/src/authRecovery.ts +279 -0
  149. package/src/authTokens.test.ts +94 -0
  150. package/src/authTokens.ts +118 -0
  151. package/src/authVerification.test.ts +293 -0
  152. package/src/betterAuth.ts +24 -0
  153. package/src/betterAuthApp.test.ts +1 -0
  154. package/src/betterAuthApp.ts +27 -9
  155. package/src/betterAuthSetup.test.ts +568 -38
  156. package/src/betterAuthSetup.ts +260 -5
  157. package/src/collectionRegistry.test.ts +165 -0
  158. package/src/collectionRegistry.ts +115 -0
  159. package/src/configurationApp.ts +13 -7
  160. package/src/docLoader.test.ts +45 -1
  161. package/src/docLoader.ts +37 -6
  162. package/src/express.d.ts +1 -0
  163. package/src/expressServer.test.ts +130 -66
  164. package/src/expressServer.ts +75 -19
  165. package/src/githubAuth.test.ts +60 -55
  166. package/src/index.ts +58 -0
  167. package/src/mcp/auth.test.ts +47 -0
  168. package/src/mcp/auth.ts +32 -11
  169. package/src/mcp/handlers.ts +45 -172
  170. package/src/mcp/integration.test.ts +59 -9
  171. package/src/mcp/query.ts +2 -4
  172. package/src/mcp/registry.ts +29 -20
  173. package/src/mcp/schemaGenerator.test.ts +8 -0
  174. package/src/mcp/schemaGenerator.ts +49 -131
  175. package/src/mcp/server.ts +2 -0
  176. package/src/mcp/serviceTokens.test.ts +330 -0
  177. package/src/mcp/serviceTokens.ts +307 -0
  178. package/src/mcp/toolGenerator.test.ts +1 -1
  179. package/src/mcp/types.ts +2 -6
  180. package/src/models/mcpServiceToken.test.ts +129 -0
  181. package/src/models/mcpServiceToken.ts +158 -0
  182. package/src/openApi.test.ts +80 -64
  183. package/src/openApiBuilder.test.ts +95 -7
  184. package/src/openApiBuilder.ts +46 -9
  185. package/src/openApiCompat.ts +1 -1
  186. package/src/openApiValidator.test.ts +49 -54
  187. package/src/openApiValidator.ts +1 -3
  188. package/src/plugins.test.ts +14 -0
  189. package/src/plugins.ts +34 -9
  190. package/src/populate.test.ts +34 -0
  191. package/src/populate.ts +40 -29
  192. package/src/rateLimit/applyTrustProxy.ts +17 -0
  193. package/src/rateLimit/createStore.ts +25 -0
  194. package/src/rateLimit/memoryStore.ts +40 -0
  195. package/src/rateLimit/middleware.ts +79 -0
  196. package/src/rateLimit/mongoStore.test.ts +80 -0
  197. package/src/rateLimit/mongoStore.ts +76 -0
  198. package/src/rateLimit/policies.ts +130 -0
  199. package/src/rateLimit/rateLimit.test.ts +328 -0
  200. package/src/rateLimit/redisStore.ioredis.test.ts +29 -0
  201. package/src/rateLimit/redisStore.test.ts +114 -0
  202. package/src/rateLimit/redisStore.ts +85 -0
  203. package/src/rateLimit/types.ts +64 -0
  204. package/src/rbac/access.ts +5 -1
  205. package/src/rbac/assertAllowed.test.ts +325 -0
  206. package/src/rbac/assertAllowed.ts +157 -0
  207. package/src/rbac/backfillAdmins.test.ts +124 -0
  208. package/src/rbac/fieldViews.test.ts +89 -0
  209. package/src/rbac/modelRouterAccess.test.ts +126 -0
  210. package/src/rbac/modelRouterAccess.ts +5 -2
  211. package/src/rbac/permissionUtils.ts +3 -2
  212. package/src/rbac/realtimeAccess.test.ts +109 -1
  213. package/src/rbac/resolve.ts +5 -4
  214. package/src/rbac/roleManager.test.ts +169 -0
  215. package/src/rbac/routes.test.ts +233 -0
  216. package/src/rbac/routes.ts +16 -6
  217. package/src/realtime/deprecation.test.ts +60 -0
  218. package/src/realtime/deprecation.ts +32 -0
  219. package/src/realtime/realtime.test.ts +8 -4
  220. package/src/realtime/realtimeApp.ts +10 -11
  221. package/src/realtime/realtimeAppSetup.test.ts +32 -5
  222. package/src/realtime/registry.ts +48 -42
  223. package/src/realtime/sessionRevalidation.test.ts +57 -44
  224. package/src/realtime/socketAuth.test.ts +75 -23
  225. package/src/realtime/socketAuth.ts +17 -6
  226. package/src/realtime/socketUser.ts +5 -3
  227. package/src/realtime/types.ts +14 -4
  228. package/src/schemaMetadata.test.ts +405 -0
  229. package/src/schemaMetadata.ts +593 -0
  230. package/src/scrubAdminFields.test.ts +105 -0
  231. package/src/seedRunner.test.ts +591 -0
  232. package/src/seedRunner.ts +464 -0
  233. package/src/sync/docMatchesMutationData.test.ts +16 -0
  234. package/src/sync/ensureSyncIndexes.test.ts +54 -15
  235. package/src/sync/executors.test.ts +40 -0
  236. package/src/sync/executors.ts +24 -12
  237. package/src/sync/integration.test.ts +15 -7
  238. package/src/sync/loadHarness.ts +28 -19
  239. package/src/sync/models.ts +32 -18
  240. package/src/sync/mutationHandler.test.ts +16 -16
  241. package/src/sync/mutationHandler.ts +9 -7
  242. package/src/sync/registrationSideEffects.test.ts +126 -0
  243. package/src/sync/registrationSideEffects.ts +131 -0
  244. package/src/sync/registry.ts +45 -171
  245. package/src/sync/routes.ts +3 -2
  246. package/src/sync/scripts/compactTombstones.ts +0 -2
  247. package/src/sync/sessionRevalidationIntegration.test.ts +12 -11
  248. package/src/sync/sync.test.ts +25 -23
  249. package/src/sync/syncApp.ts +4 -4
  250. package/src/sync/syncBatch.ts +3 -2
  251. package/src/sync/syncFrontier.test.ts +17 -15
  252. package/src/sync/syncPhaseC.test.ts +54 -43
  253. package/src/sync/syncRoutes.test.ts +51 -36
  254. package/src/sync/syncSeqPlugin.ts +66 -44
  255. package/src/sync/syncSocket.test.ts +112 -81
  256. package/src/terrenoApp.mcpServiceTokens.test.ts +173 -0
  257. package/src/terrenoApp.ts +87 -15
  258. package/src/tests/models.ts +14 -1
  259. package/src/types/authToken.ts +43 -0
  260. package/src/types/mcpServiceToken.ts +54 -0
  261. package/src/webhooks/headerValue.test.ts +22 -0
  262. package/src/webhooks/headerValue.ts +12 -0
  263. package/src/webhooks/idempotency/memoryStore.ts +34 -0
  264. package/src/webhooks/idempotency/mongoStore.test.ts +274 -0
  265. package/src/webhooks/idempotency/mongoStore.ts +83 -0
  266. package/src/webhooks/idempotency/webhookReceipt.ts +70 -0
  267. package/src/webhooks/rawBody.test.ts +74 -0
  268. package/src/webhooks/rawBody.ts +23 -0
  269. package/src/webhooks/timingSafeEqual.ts +16 -0
  270. package/src/webhooks/verifiers/hmac.test.ts +110 -0
  271. package/src/webhooks/verifiers/hmac.ts +54 -0
  272. package/src/webhooks/verifiers/providerVerifiers.test.ts +388 -0
  273. package/src/webhooks/verifiers/sendgrid.ts +59 -0
  274. package/src/webhooks/verifiers/stripe.ts +67 -0
  275. package/src/webhooks/verifiers/twilio.ts +69 -0
  276. package/src/webhooks/webhooksApp.test.ts +221 -0
  277. package/src/webhooks/webhooksApp.ts +144 -0
@@ -0,0 +1,126 @@
1
+ import {beforeEach, describe, expect, it} from "bun:test";
2
+ import {model, Schema} from "mongoose";
3
+
4
+ import type {ModelRouterOptions} from "../api";
5
+ import {registerCollection} from "../collectionRegistry";
6
+ import {Permissions} from "../permissions";
7
+ import {createdUpdatedPlugin, type IsDeleted, isDeletedPlugin} from "../plugins";
8
+ import {
9
+ applySyncRegistrationSideEffects,
10
+ clearSyncIndexCreationTasks,
11
+ ensureSyncIndexes,
12
+ trackSyncIndexCreation,
13
+ } from "./registrationSideEffects";
14
+ import {clearSyncRegistry, registerSync} from "./registry";
15
+ import {syncPlugin} from "./syncSeqPlugin";
16
+
17
+ interface SideEffectTodo extends IsDeleted {
18
+ _id: string;
19
+ ownerId: string;
20
+ title: string;
21
+ _syncSeq?: number;
22
+ }
23
+
24
+ const buildModel = (name: string, extraFields: Record<string, unknown> = {}) => {
25
+ const schema = new Schema<SideEffectTodo>({
26
+ ownerId: {description: "The owner", type: String},
27
+ title: {description: "The title", required: true, type: String},
28
+ ...extraFields,
29
+ });
30
+ schema.plugin(isDeletedPlugin);
31
+ schema.plugin(createdUpdatedPlugin);
32
+ schema.plugin(syncPlugin);
33
+ return model<SideEffectTodo>(name, schema);
34
+ };
35
+
36
+ const authedOptions = {
37
+ permissions: {
38
+ create: [Permissions.IsAuthenticated],
39
+ delete: [Permissions.IsAuthenticated],
40
+ list: [Permissions.IsAuthenticated],
41
+ read: [Permissions.IsAuthenticated],
42
+ update: [Permissions.IsAuthenticated],
43
+ },
44
+ } as unknown as ModelRouterOptions<SideEffectTodo>;
45
+
46
+ describe("applySyncRegistrationSideEffects", () => {
47
+ beforeEach(() => {
48
+ clearSyncRegistry();
49
+ });
50
+
51
+ it("requires snapshotFilter when scope is a custom resolver function", () => {
52
+ const SideEffectTodoModel = buildModel("SideEffectCustomScope");
53
+ expect(() =>
54
+ applySyncRegistrationSideEffects({
55
+ config: {scope: () => "owner:abc"},
56
+ existingSyncEntries: [],
57
+ model: SideEffectTodoModel,
58
+ options: authedOptions,
59
+ routePath: "/sideEffectCustomScope",
60
+ })
61
+ ).toThrow(/snapshotFilter/);
62
+ });
63
+
64
+ it("rejects registering the same model name on a second route path", () => {
65
+ const SideEffectTodoModel = buildModel("SideEffectDupModel");
66
+ registerSync({
67
+ config: {scope: {type: "owner"}},
68
+ model: SideEffectTodoModel,
69
+ options: authedOptions,
70
+ routePath: "/sideEffectDupA",
71
+ });
72
+
73
+ expect(() =>
74
+ registerSync({
75
+ config: {scope: {type: "owner"}},
76
+ model: SideEffectTodoModel,
77
+ options: authedOptions,
78
+ routePath: "/sideEffectDupB",
79
+ })
80
+ ).toThrow(/already registered/);
81
+ });
82
+
83
+ it("rejects a duplicate collection tag across route path spellings", () => {
84
+ const FirstModel = buildModel("SideEffectDupTagA");
85
+ registerCollection({
86
+ model: FirstModel,
87
+ options: {...authedOptions, sync: {scope: {type: "owner"}}},
88
+ routePath: "/sideEffectDupTag",
89
+ });
90
+
91
+ const SecondModel = buildModel("SideEffectDupTagB");
92
+ expect(() =>
93
+ applySyncRegistrationSideEffects({
94
+ config: {scope: {type: "owner"}},
95
+ existingSyncEntries: [{collectionTag: "sideEffectDupTag", modelName: "SideEffectDupTagA"}],
96
+ model: SecondModel,
97
+ options: authedOptions,
98
+ routePath: "sideEffectDupTag",
99
+ })
100
+ ).toThrow(/already registered/);
101
+ });
102
+
103
+ it("wraps createIndex failures in an actionable APIError at startup", async () => {
104
+ const SideEffectTodoModel = buildModel("SideEffectIndexFail");
105
+ SideEffectTodoModel.collection.createIndex = async (): Promise<string> => {
106
+ throw new Error("boom: index build failed");
107
+ };
108
+ applySyncRegistrationSideEffects({
109
+ config: {scope: {type: "owner"}},
110
+ existingSyncEntries: [],
111
+ model: SideEffectTodoModel,
112
+ options: authedOptions,
113
+ routePath: "/sideEffectIndexFail",
114
+ });
115
+
116
+ await expect(ensureSyncIndexes()).rejects.toThrow(/Failed to create sync snapshot index/);
117
+ });
118
+
119
+ it("clearSyncIndexCreationTasks drops deferred index work", async () => {
120
+ trackSyncIndexCreation(async () => {
121
+ throw new Error("should not run");
122
+ });
123
+ clearSyncIndexCreationTasks();
124
+ await expect(ensureSyncIndexes()).resolves.toBeUndefined();
125
+ });
126
+ });
@@ -0,0 +1,131 @@
1
+ /**
2
+ * Schema and Mongo work that must happen when a collection first becomes
3
+ * sync-enabled — kept out of CollectionRegistry so catalog writes stay a
4
+ * Map update, while models can still register before Mongo is connected.
5
+ *
6
+ * Registration only validates the schema and queues index creation.
7
+ * TerrenoApp.start() (or a host that builds Express without it) must later
8
+ * await ensureSyncIndexes() so snapshot/catch-up queries have their indexes.
9
+ */
10
+ import type {Model} from "mongoose";
11
+
12
+ import type {ModelRouterOptions} from "../api";
13
+ import {APIError, errorDetail} from "../errors";
14
+ import {logger} from "../logger";
15
+ import {getScopeField} from "./streams";
16
+ import type {SyncConfig} from "./types";
17
+
18
+ type IndexCreationTask = () => Promise<void>;
19
+ const indexCreationTasks: IndexCreationTask[] = [];
20
+
21
+ export interface SyncRegistrationSnapshot {
22
+ collectionTag: string;
23
+ modelName: string;
24
+ }
25
+
26
+ /** Queue extra index work (tests and SyncApp bookkeeping models). */
27
+ export const trackSyncIndexCreation = (task: IndexCreationTask): void => {
28
+ indexCreationTasks.push(task);
29
+ };
30
+
31
+ /**
32
+ * Fail loud if the model cannot participate in sync, then queue the
33
+ * snapshot index. Call only on the first sync enable for a routePath.
34
+ */
35
+ export const applySyncRegistrationSideEffects = <T>({
36
+ config,
37
+ existingSyncEntries,
38
+ model,
39
+ routePath,
40
+ }: {
41
+ config: SyncConfig;
42
+ existingSyncEntries: SyncRegistrationSnapshot[];
43
+ model: Model<T>;
44
+ options: ModelRouterOptions<T>;
45
+ routePath: string;
46
+ }): void => {
47
+ const name = model.modelName;
48
+ const deletedPath = model.schema.path("deleted");
49
+ if (deletedPath?.instance !== "Boolean") {
50
+ throw new APIError({
51
+ status: 500,
52
+ title:
53
+ `Model ${name} has a sync config but no soft delete support. ` +
54
+ "Apply isDeletedPlugin to the schema — sync catch-up requires delete tombstones.",
55
+ });
56
+ }
57
+ if (!model.schema.path("_syncSeq")) {
58
+ throw new APIError({
59
+ status: 500,
60
+ title:
61
+ `Model ${name} has a sync config but syncPlugin is not applied to its schema. ` +
62
+ "Apply syncPlugin so every write stamps a per-stream _syncSeq.",
63
+ });
64
+ }
65
+ const scopeField = getScopeField(config.scope);
66
+ if (scopeField && !model.schema.path(scopeField)) {
67
+ throw new APIError({
68
+ status: 500,
69
+ title: `Model ${name} has a sync scope on field "${scopeField}" but the schema has no such path.`,
70
+ });
71
+ }
72
+ if (typeof config.scope === "function" && !config.snapshotFilter) {
73
+ throw new APIError({
74
+ status: 500,
75
+ title:
76
+ `Model ${name} uses a custom sync scope resolver, which requires a snapshotFilter ` +
77
+ "so the snapshot endpoint can restrict queries to the caller's documents.",
78
+ });
79
+ }
80
+ if (existingSyncEntries.some((entry) => entry.modelName === name)) {
81
+ throw new APIError({
82
+ status: 500,
83
+ title: `Model ${name} is already registered for sync.`,
84
+ });
85
+ }
86
+ const collectionTag = routePath.replace(/^\//, "");
87
+ if (existingSyncEntries.some((entry) => entry.collectionTag === collectionTag)) {
88
+ throw new APIError({
89
+ status: 500,
90
+ title:
91
+ `Sync collection tag "${collectionTag}" is already registered (routePath ${routePath}). ` +
92
+ "Each synced model must have a unique route path.",
93
+ });
94
+ }
95
+
96
+ (model as unknown as {bulkWrite: () => never}).bulkWrite = (): never => {
97
+ throw new APIError({
98
+ status: 500,
99
+ title:
100
+ `bulkWrite is not supported on sync-enabled model ${name}: it bypasses Mongoose ` +
101
+ "middleware, so writes are never stamped with a per-stream _syncSeq and become " +
102
+ "invisible to sync delta emission and snapshot catch-up. Loop per document instead.",
103
+ });
104
+ };
105
+
106
+ const indexSpec: Record<string, 1> = scopeField ? {[scopeField]: 1, _syncSeq: 1} : {_syncSeq: 1};
107
+ indexCreationTasks.push(async () => {
108
+ try {
109
+ await model.collection.createIndex(indexSpec);
110
+ } catch (error: unknown) {
111
+ logger.error(`[sync] Failed to create sync index for ${name}`, {error: String(error)});
112
+ throw new APIError({
113
+ cause: error,
114
+ code: "sync-snapshot-index-failed",
115
+ detail: `${errorDetail(error)}. The snapshot/catch-up query requires this index; fix the schema/DB and restart.`,
116
+ status: 500,
117
+ title: `Failed to create sync snapshot index for ${name}`,
118
+ });
119
+ }
120
+ });
121
+ };
122
+
123
+ /** Create every queued sync index after Mongo is connected. */
124
+ export const ensureSyncIndexes = async (): Promise<void> => {
125
+ await Promise.all(indexCreationTasks.map((task) => task()));
126
+ };
127
+
128
+ /** Drop queued index work when the collection catalog is wiped (tests). */
129
+ export const clearSyncIndexCreationTasks = (): void => {
130
+ indexCreationTasks.length = 0;
131
+ };
@@ -1,60 +1,49 @@
1
1
  import type {Model} from "mongoose";
2
+
2
3
  import type {ModelRouterOptions} from "../api";
4
+ import {
5
+ clearCollectionRegistry,
6
+ listCollections,
7
+ registerCollection,
8
+ replaceCollectionOptions,
9
+ } from "../collectionRegistry";
3
10
  import {logger} from "../logger";
4
- import {getScopeField} from "./streams";
11
+ import {
12
+ clearSyncIndexCreationTasks,
13
+ ensureSyncIndexes,
14
+ trackSyncIndexCreation,
15
+ } from "./registrationSideEffects";
5
16
  import type {SyncConfig} from "./types";
6
17
 
7
- /**
8
- * A registered model with SyncDB local-first sync configuration.
9
- */
10
18
  export interface SyncRegistryEntry {
11
- /** Mongoose model name (e.g. "Todo") */
12
19
  modelName: string;
13
- /** Route path (e.g. "/todos") */
14
20
  routePath: string;
15
- /** Collection tag used in the sync protocol (route path without the leading slash) */
16
21
  collectionTag: string;
17
- /** MongoDB collection name (e.g. "todos") */
18
22
  collectionName: string;
19
- /** Sync configuration from modelRouter options */
20
23
  config: SyncConfig;
21
- /** Full modelRouter options (for responseHandler, permissions, etc.) */
22
24
  options: ModelRouterOptions<unknown>;
23
25
  }
24
26
 
25
- const syncRegistry: SyncRegistryEntry[] = [];
26
-
27
- /**
28
- * C8: index creation is kicked off (fire-and-forget) at registration, but its failure must
29
- * be a STARTUP error, not a swallowed warning (a missing index table-scans the snapshot
30
- * query under load, and a missing unique index breaks mutation idempotency). Each
31
- * registration records its index promise here; `ensureSyncIndexes()` awaits them and
32
- * throws on any failure so server startup can fail loudly. A detached failure is also
33
- * logged so it is never silent even if startup never calls `ensureSyncIndexes`.
34
- */
35
- const indexCreationPromises: Promise<void>[] = [];
36
-
37
- /**
38
- * Enqueue an index-creation promise for `ensureSyncIndexes()` to await at startup. Used by
39
- * `SyncApp.register` for the bookkeeping-model indexes (`SyncCounter`, `SyncMutation`,
40
- * `SyncScopeMove`, `SyncKey`), which are correctness-critical and must not depend on
41
- * Mongoose `autoIndex` being enabled.
42
- */
43
- export const trackSyncIndexCreation = (promise: Promise<void>): void => {
44
- indexCreationPromises.push(promise);
45
- // Swallow the detached rejection (the failure is logged where it happens and rethrown
46
- // by `ensureSyncIndexes()` via the retained promise above).
47
- promise.catch(() => {});
48
- };
27
+ const toSyncEntry = (record: {
28
+ model: Model<unknown>;
29
+ options: ModelRouterOptions<unknown>;
30
+ routePath: string;
31
+ }): SyncRegistryEntry => ({
32
+ collectionName: record.model.collection.collectionName,
33
+ collectionTag: record.routePath.replace(/^\//, ""),
34
+ config: record.options.sync as SyncConfig,
35
+ modelName: record.model.modelName,
36
+ options: record.options,
37
+ routePath: record.routePath,
38
+ });
39
+
40
+ const syncCollections = () =>
41
+ listCollections()
42
+ .filter((record) => record.surfaces.sync)
43
+ .map(toSyncEntry);
44
+
45
+ export {ensureSyncIndexes, trackSyncIndexCreation};
49
46
 
50
- /**
51
- * Register a model for local-first sync. Called automatically by modelRouter when the
52
- * `sync` option is provided. Validates the schema contract at startup and throws with
53
- * an actionable message when it is not met:
54
- * - soft delete (`isDeletedPlugin`) is required so deletes remain queryable tombstones;
55
- * - `syncPlugin` is required so every write stamps a per-stream `_syncSeq`;
56
- * - owner/tenant scope fields must exist on the schema.
57
- */
58
47
  export const registerSync = <T>({
59
48
  model,
60
49
  routePath,
@@ -66,143 +55,32 @@ export const registerSync = <T>({
66
55
  config: SyncConfig;
67
56
  options: ModelRouterOptions<T>;
68
57
  }): void => {
69
- const name = model.modelName;
70
- const deletedPath = model.schema.path("deleted");
71
- if (deletedPath?.instance !== "Boolean") {
72
- throw new Error(
73
- `Model ${name} has a sync config but no soft delete support. ` +
74
- "Apply isDeletedPlugin to the schema — sync catch-up requires delete tombstones."
75
- );
76
- }
77
- if (!model.schema.path("_syncSeq")) {
78
- throw new Error(
79
- `Model ${name} has a sync config but syncPlugin is not applied to its schema. ` +
80
- "Apply syncPlugin so every write stamps a per-stream _syncSeq."
81
- );
82
- }
83
- const scopeField = getScopeField(config.scope);
84
- if (scopeField && !model.schema.path(scopeField)) {
85
- throw new Error(
86
- `Model ${name} has a sync scope on field "${scopeField}" but the schema has no such path.`
87
- );
88
- }
89
- if (typeof config.scope === "function" && !config.snapshotFilter) {
90
- throw new Error(
91
- `Model ${name} uses a custom sync scope resolver, which requires a snapshotFilter ` +
92
- "so the snapshot endpoint can restrict queries to the caller's documents."
93
- );
94
- }
95
- if (syncRegistry.some((entry) => entry.modelName === name)) {
96
- throw new Error(`Model ${name} is already registered for sync.`);
97
- }
98
- // C8: a duplicate collectionTag would make two models share sync streams and route
99
- // snapshots/deltas ambiguously — reject it loudly at registration.
100
- const collectionTag = routePath.replace(/^\//, "");
101
- if (syncRegistry.some((entry) => entry.collectionTag === collectionTag)) {
102
- throw new Error(
103
- `Sync collection tag "${collectionTag}" is already registered (routePath ${routePath}). ` +
104
- "Each synced model must have a unique route path."
105
- );
106
- }
107
-
108
- syncRegistry.push({
109
- collectionName: model.collection.collectionName,
110
- collectionTag,
111
- config,
112
- modelName: name,
113
- options: options as unknown as ModelRouterOptions<unknown>,
58
+ registerCollection({
59
+ model,
60
+ options: {
61
+ ...options,
62
+ sync: config,
63
+ } as ModelRouterOptions<T>,
114
64
  routePath,
115
65
  });
116
-
117
- // `Model.bulkWrite` bypasses Mongoose middleware entirely, so `syncPlugin`'s query
118
- // guards never see it: writes land with no `_syncSeq`, invisible to both delta emission
119
- // and snapshot catch-up, and clients silently never learn about them. The restriction
120
- // used to be documentation only — replace the static so it throws the same way the
121
- // guarded multi-document paths do. Idempotent: the replacement never delegates, so a
122
- // re-registration (tests clearing the registry) re-patching it is harmless.
123
- (model as unknown as {bulkWrite: () => never}).bulkWrite = (): never => {
124
- throw new Error(
125
- `bulkWrite is not supported on sync-enabled model ${name}: it bypasses Mongoose ` +
126
- "middleware, so writes are never stamped with a per-stream _syncSeq and become " +
127
- "invisible to sync delta emission and snapshot catch-up. Loop per document instead."
128
- );
129
- };
130
-
131
- // Compound index for snapshot/catch-up queries: {scopeField, _syncSeq}. Created
132
- // directly on the collection because the model is already compiled at registration.
133
- // C8: track the promise so `ensureSyncIndexes()` (server startup) can fail loudly on a
134
- // createIndex error — a missing index table-scans the snapshot query under load. The
135
- // detached path only logs (never throws into an orphaned promise).
136
- const indexSpec: Record<string, 1> = scopeField ? {[scopeField]: 1, _syncSeq: 1} : {_syncSeq: 1};
137
- const indexPromise = model.collection
138
- .createIndex(indexSpec)
139
- .then(() => {})
140
- .catch((error: unknown) => {
141
- logger.error(`[sync] Failed to create sync index for ${name}`, {error: String(error)});
142
- throw new Error(
143
- `Failed to create sync snapshot index for ${name}: ${String(error)}. ` +
144
- "The snapshot/catch-up query requires this index; fix the schema/DB and restart."
145
- );
146
- });
147
- indexCreationPromises.push(indexPromise);
148
- // Swallow the detached rejection (already logged) so it is not an unhandled rejection;
149
- // `ensureSyncIndexes()` still observes it via the retained promise above.
150
- indexPromise.catch(() => {});
151
66
  };
152
67
 
153
- /**
154
- * Replace options on an existing sync registry entry after TerrenoApp injects
155
- * accessControl and modelRouter resolves RBAC permissions.
156
- */
157
68
  export const updateSyncRegistryOptions = (
158
69
  routePath: string,
159
70
  options: ModelRouterOptions<unknown>
160
71
  ): void => {
161
- const existing = syncRegistry.find((entry) => entry.routePath === routePath);
162
- if (!existing) {
163
- return;
164
- }
165
- existing.options = options;
166
- };
167
-
168
- /**
169
- * C8: await every enqueued sync index creation — per-model snapshot indexes from
170
- * `registerSync` plus the bookkeeping-model indexes from `SyncApp.register` — throwing on
171
- * the first failure. Called at server startup by `TerrenoApp.start()` (after all models
172
- * and plugins register) so a missing index fails the boot loudly rather than silently
173
- * degrading the snapshot query to a table scan or breaking mutation idempotency.
174
- */
175
- export const ensureSyncIndexes = async (): Promise<void> => {
176
- await Promise.all(indexCreationPromises);
72
+ replaceCollectionOptions(routePath, options);
177
73
  };
178
74
 
179
- /** Get all registered sync models. */
180
- export const getSyncRegistry = (): SyncRegistryEntry[] => syncRegistry;
75
+ export const getSyncRegistry = (): SyncRegistryEntry[] => syncCollections();
181
76
 
182
- /**
183
- * Collection tags whose scope can only be resolved from the FULL user document —
184
- * tenant scopes read `organizationIds` (or whatever `getUserScopes` looks at) and custom
185
- * resolvers may read anything. The synthetic `{_id, admin, id}` user built from JWT claims
186
- * carries none of that.
187
- */
188
77
  const scopesRequiringFullUser = (): string[] =>
189
- syncRegistry
78
+ syncCollections()
190
79
  .filter(
191
80
  (entry) => typeof entry.config.scope === "function" || entry.config.scope.type === "tenant"
192
81
  )
193
82
  .map((entry) => entry.collectionTag);
194
83
 
195
- /**
196
- * Task 9.21: warn loudly at startup when a tenant/custom-scoped collection is registered
197
- * but no `userModel` is configured for socket handshakes.
198
- *
199
- * Without one, `getSocketUser` falls back to the synthetic decoded-token user: `admin`
200
- * comes from a JWT claim rather than the database, and `getUserScopes` sees no
201
- * `organizationIds`, so tenant subscriptions silently resolve to no streams (a client that
202
- * appears connected but never receives data). This warns rather than throws so an existing
203
- * deployment cannot be bricked by an upgrade; the message names the collections and the
204
- * fix. Returns the offending collection tags for tests and callers that want to escalate.
205
- */
206
84
  export const warnOnSyncScopesWithoutUserModel = ({userModel}: {userModel?: unknown}): string[] => {
207
85
  if (userModel) {
208
86
  return [];
@@ -222,24 +100,20 @@ export const warnOnSyncScopesWithoutUserModel = ({userModel}: {userModel?: unkno
222
100
  return collections;
223
101
  };
224
102
 
225
- /** Find a sync registry entry by Mongoose model name. */
226
103
  export const findSyncEntryByModelName = (modelName: string): SyncRegistryEntry | undefined =>
227
- syncRegistry.find((entry) => entry.modelName === modelName);
104
+ syncCollections().find((entry) => entry.modelName === modelName);
228
105
 
229
- /** Find a sync registry entry by collection tag (e.g. "todos"). */
230
106
  export const findSyncEntryByCollectionTag = (
231
107
  collectionTag: string
232
108
  ): SyncRegistryEntry | undefined =>
233
- syncRegistry.find((entry) => entry.collectionTag === collectionTag);
109
+ syncCollections().find((entry) => entry.collectionTag === collectionTag);
234
110
 
235
- /** Find a sync registry entry by MongoDB collection name. */
236
111
  export const findSyncEntryByCollectionName = (
237
112
  collectionName: string
238
113
  ): SyncRegistryEntry | undefined =>
239
- syncRegistry.find((entry) => entry.collectionName === collectionName);
114
+ syncCollections().find((entry) => entry.collectionName === collectionName);
240
115
 
241
- /** Clear the registry (for testing). */
242
116
  export const clearSyncRegistry = (): void => {
243
- syncRegistry.length = 0;
244
- indexCreationPromises.length = 0;
117
+ clearCollectionRegistry();
118
+ clearSyncIndexCreationTasks();
245
119
  };
@@ -5,6 +5,7 @@ import {authenticateMiddleware, type User} from "../auth";
5
5
  import {APIError, apiErrorMiddleware, apiUnauthorizedMiddleware} from "../errors";
6
6
  import {logger} from "../logger";
7
7
  import {checkPermissions} from "../permissions";
8
+ import {findOneOrNoneFor} from "../plugins";
8
9
  import {
9
10
  computeStableFrontier,
10
11
  getCompactedThroughSeq,
@@ -316,8 +317,8 @@ const frontierBelowStreamHead = async (
316
317
  streamKey: string,
317
318
  frontierSeq: number
318
319
  ): Promise<boolean> => {
319
- const counter = await SyncCounter.findOne({stream: streamKey}).select({seq: 1}).lean();
320
- const head = counter ? ((counter as {seq?: number}).seq ?? 0) : 0;
320
+ const counter = await findOneOrNoneFor(SyncCounter, {stream: streamKey});
321
+ const head = counter?.seq ?? 0;
321
322
  return head > frontierSeq;
322
323
  };
323
324
 
@@ -1,5 +1,3 @@
1
- // noExplicitAny: operates generically across registered sync models
2
- // biome-ignore-all lint/suspicious/noExplicitAny: operates generically across registered sync models
3
1
  import {DateTime} from "luxon";
4
2
  import mongoose from "mongoose";
5
3
  import {logger} from "../../logger";
@@ -1,5 +1,3 @@
1
- // noExplicitAny: the rig bridges generic model/router/test types
2
- // biome-ignore-all lint/suspicious/noExplicitAny: the rig bridges generic model/router/test types
3
1
  /**
4
2
  * Integration coverage for D1 (socket session re-validation sweep) and D4
5
3
  * (membership revocation vs socket rooms), using a REAL @terreno/syncdb client
@@ -32,7 +30,7 @@ import {
32
30
  import mongoose, {model, Schema} from "mongoose";
33
31
 
34
32
  import {modelRouter} from "../api";
35
- import {addAuthRoutes, generateTokens, setupAuth} from "../auth";
33
+ import {type UserModel as AuthUserModel, addAuthRoutes, generateTokens, setupAuth} from "../auth";
36
34
  import {createdUpdatedPlugin, findOneOrNoneFor, type IsDeleted, isDeletedPlugin} from "../plugins";
37
35
  import {RealtimeApp} from "../realtime/realtimeApp";
38
36
  import {getBaseServer, setupDb, UserModel} from "../tests";
@@ -155,8 +153,8 @@ describe("session re-validation sweep integration (D1/D4)", () => {
155
153
  });
156
154
 
157
155
  const app = getBaseServer();
158
- setupAuth(app as any, UserModel as any);
159
- addAuthRoutes(app as any, UserModel as any);
156
+ setupAuth(app, UserModel as unknown as AuthUserModel);
157
+ addAuthRoutes(app, UserModel as unknown as AuthUserModel);
160
158
  new SyncApp({
161
159
  getUserScopes: (user) => memberships.get(String(user.id)) ?? [],
162
160
  }).register(app);
@@ -165,7 +163,7 @@ describe("session re-validation sweep integration (D1/D4)", () => {
165
163
  realtimeApp = new RealtimeApp({
166
164
  // D1: a short sweep interval so the tests don't wait a full 60s default.
167
165
  sessionRevalidationIntervalMs: SESSION_REVALIDATION_INTERVAL_MS,
168
- userModel: UserModel as any,
166
+ userModel: UserModel as unknown as AuthUserModel,
169
167
  });
170
168
  realtimeApp.register(app);
171
169
 
@@ -208,9 +206,12 @@ describe("session re-validation sweep integration (D1/D4)", () => {
208
206
  // for the socket-specific signal (isOnline flipping false) first — the only
209
207
  // thing that can disconnect this socket mid-test is the sweep, since nothing
210
208
  // else in this scenario touches the transport.
211
- const fullUser = await findOneOrNoneFor(UserModel as any, {_id: userDoc._id});
212
- (fullUser as any).disabled = true;
213
- await (fullUser as any).save();
209
+ const fullUser = await findOneOrNoneFor(UserModel, {_id: userDoc._id});
210
+ if (!fullUser) {
211
+ throw new Error("the seeded test user is missing");
212
+ }
213
+ fullUser.disabled = true;
214
+ await fullUser.save();
214
215
 
215
216
  await waitFor(() => !client.getSyncStatus().isOnline, {
216
217
  label: "socket disconnected by the sweep after being disabled",
@@ -234,8 +235,8 @@ describe("session re-validation sweep integration (D1/D4)", () => {
234
235
 
235
236
  // Re-enable so afterAll's client.stop() and any later scenario aren't left
236
237
  // fighting a disabled user; also proves recovery is possible.
237
- (fullUser as any).disabled = false;
238
- await (fullUser as any).save();
238
+ fullUser.disabled = false;
239
+ await fullUser.save();
239
240
  }, 15_000);
240
241
 
241
242
  it("D4: revoking the user's only organization membership stops further deltas for that tenant on the live socket", async () => {