@terreno/api 0.31.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 (250) hide show
  1. package/CHANGELOG.md +122 -2
  2. package/LICENSE +202 -21
  3. package/dist/api.d.ts +12 -3
  4. package/dist/api.js +110 -361
  5. package/dist/auth.d.ts +26 -0
  6. package/dist/auth.js +100 -1
  7. package/dist/betterAuth.d.ts +5 -0
  8. package/dist/betterAuthSetup.d.ts +1 -15
  9. package/dist/betterAuthSetup.js +29 -8
  10. package/dist/configurationPlugin.js +2 -2
  11. package/dist/docLoader.js +12 -9
  12. package/dist/errors.d.ts +13 -0
  13. package/dist/errors.js +29 -1
  14. package/dist/expressServer.js +5 -11
  15. package/dist/githubAuth.js +4 -1
  16. package/dist/index.d.ts +17 -1
  17. package/dist/index.js +29 -1
  18. package/dist/middleware.d.ts +7 -0
  19. package/dist/middleware.js +16 -1
  20. package/dist/openApiCompat.d.ts +10 -1
  21. package/dist/openApiCompat.js +115 -47
  22. package/dist/permissions.d.ts +27 -0
  23. package/dist/permissions.js +42 -1
  24. package/dist/plugins.d.ts +15 -3
  25. package/dist/plugins.js +36 -6
  26. package/dist/realtime/changeStreamWatcher.d.ts +100 -3
  27. package/dist/realtime/changeStreamWatcher.js +542 -137
  28. package/dist/realtime/realtimeApp.d.ts +3 -1
  29. package/dist/realtime/realtimeApp.js +75 -27
  30. package/dist/realtime/sessionRevalidation.d.ts +90 -0
  31. package/dist/realtime/sessionRevalidation.js +438 -0
  32. package/dist/realtime/socketAuth.d.ts +97 -0
  33. package/dist/realtime/socketAuth.js +272 -0
  34. package/dist/realtime/socketUser.d.ts +54 -0
  35. package/dist/realtime/socketUser.js +75 -5
  36. package/dist/realtime/types.d.ts +40 -0
  37. package/dist/secretProviders.d.ts +23 -0
  38. package/dist/secretProviders.js +9 -3
  39. package/dist/sync/executors.d.ts +198 -0
  40. package/dist/sync/executors.js +670 -0
  41. package/dist/sync/loadHarness.js +807 -0
  42. package/dist/sync/models.d.ts +216 -0
  43. package/dist/sync/models.js +644 -0
  44. package/dist/sync/mutationHandler.d.ts +97 -0
  45. package/dist/sync/mutationHandler.js +886 -0
  46. package/dist/sync/registry.d.ts +73 -0
  47. package/dist/sync/registry.js +223 -0
  48. package/dist/sync/routes.d.ts +62 -0
  49. package/dist/sync/routes.js +936 -0
  50. package/dist/sync/scripts/compactTombstones.d.ts +47 -0
  51. package/dist/sync/scripts/compactTombstones.js +270 -0
  52. package/dist/sync/serialize.d.ts +20 -0
  53. package/dist/{tests/bunSetup.js → sync/serialize.js} +35 -68
  54. package/dist/sync/socketHandlers.d.ts +54 -0
  55. package/dist/sync/socketHandlers.js +470 -0
  56. package/dist/sync/streams.d.ts +85 -0
  57. package/dist/sync/streams.js +221 -0
  58. package/dist/sync/syncApp.d.ts +29 -0
  59. package/dist/sync/syncApp.js +44 -0
  60. package/dist/sync/syncBatch.d.ts +71 -0
  61. package/dist/sync/syncBatch.js +252 -0
  62. package/dist/sync/syncSeqPlugin.d.ts +8 -0
  63. package/dist/sync/syncSeqPlugin.js +903 -0
  64. package/dist/sync/types.d.ts +254 -0
  65. package/dist/sync/types.js +9 -0
  66. package/dist/terrenoApp.js +90 -27
  67. package/dist/tests/models.d.ts +11 -27
  68. package/dist/tests/models.js +3 -5
  69. package/dist/tests/testHelper.d.ts +3 -9
  70. package/dist/vendor/wesleytodd-openapi/index.d.ts +1 -1
  71. package/dist/vendor/wesleytodd-openapi/lib/ui.d.ts +2 -1
  72. package/package.json +10 -8
  73. package/src/__tests__/openApiCompat.test.ts +20 -0
  74. package/src/actions.test.ts +12 -19
  75. package/src/actions.ts +2 -2
  76. package/src/api.coverage.test.ts +9 -7
  77. package/src/api.errorPaths.test.ts +1 -47
  78. package/src/api.test.ts +12 -0
  79. package/src/api.ts +98 -317
  80. package/src/auth.test.ts +128 -176
  81. package/src/auth.ts +109 -0
  82. package/src/betterAuth.ts +6 -0
  83. package/src/betterAuthSetup.test.ts +34 -0
  84. package/src/betterAuthSetup.ts +27 -8
  85. package/src/configurationPlugin.ts +2 -2
  86. package/src/consentApp.test.ts +12 -12
  87. package/src/docLoader.ts +3 -1
  88. package/src/errors.ts +33 -0
  89. package/src/expressServer.test.ts +7 -1
  90. package/src/expressServer.ts +5 -11
  91. package/src/githubAuth.ts +3 -1
  92. package/src/index.ts +42 -0
  93. package/src/middleware.test.ts +40 -1
  94. package/src/middleware.ts +15 -0
  95. package/src/models/versionConfig.ts +1 -1
  96. package/src/openApiBuilder.test.ts +9 -24
  97. package/src/openApiCompat.ts +99 -45
  98. package/src/openApiValidator.test.ts +0 -41
  99. package/src/permissions.test.ts +75 -1
  100. package/src/permissions.ts +49 -0
  101. package/src/plugins.test.ts +54 -14
  102. package/src/plugins.ts +47 -9
  103. package/src/populate.test.ts +16 -25
  104. package/src/realtime/changeStreamWatcher.ts +552 -114
  105. package/src/realtime/realtime.test.ts +157 -239
  106. package/src/realtime/realtimeApp.ts +80 -19
  107. package/src/realtime/sessionRevalidation.test.ts +423 -0
  108. package/src/realtime/sessionRevalidation.ts +273 -0
  109. package/src/realtime/socketAuth.test.ts +355 -0
  110. package/src/realtime/socketAuth.ts +228 -0
  111. package/src/realtime/socketUser.ts +69 -0
  112. package/src/realtime/types.ts +40 -0
  113. package/src/secretProviders.test.ts +7 -1
  114. package/src/secretProviders.ts +15 -3
  115. package/src/sync/ensureSyncIndexes.test.ts +144 -0
  116. package/src/sync/executors.test.ts +882 -0
  117. package/src/sync/executors.ts +703 -0
  118. package/src/sync/integration.test.ts +1160 -0
  119. package/src/sync/loadHarness.ts +618 -0
  120. package/src/sync/models.ts +640 -0
  121. package/src/sync/mutationHandler.test.ts +1252 -0
  122. package/src/sync/mutationHandler.ts +850 -0
  123. package/src/sync/registry.ts +232 -0
  124. package/src/sync/routes.ts +812 -0
  125. package/src/sync/scripts/compactTombstones.test.ts +249 -0
  126. package/src/sync/scripts/compactTombstones.ts +145 -0
  127. package/src/sync/serialize.ts +48 -0
  128. package/src/sync/sessionRevalidationIntegration.test.ts +281 -0
  129. package/src/sync/socketHandlers.ts +320 -0
  130. package/src/sync/streams.ts +188 -0
  131. package/src/sync/sync.test.ts +582 -0
  132. package/src/sync/syncApp.ts +44 -0
  133. package/src/sync/syncBatch.ts +219 -0
  134. package/src/sync/syncFrontier.test.ts +494 -0
  135. package/src/sync/syncPhaseC.test.ts +718 -0
  136. package/src/sync/syncRoutes.test.ts +865 -0
  137. package/src/sync/syncSeqPlugin.ts +738 -0
  138. package/src/sync/syncSocket.test.ts +1440 -0
  139. package/src/sync/types.ts +270 -0
  140. package/src/terrenoApp.ts +37 -17
  141. package/src/tests/bunSetup.ts +8 -0
  142. package/src/tests/models.ts +6 -8
  143. package/tsconfig.json +4 -4
  144. package/tsconfig.typedoc.json +7 -1
  145. package/dist/__tests__/openApiCompat.test.js +0 -317
  146. package/dist/__tests__/versionCheckPlugin.test.d.ts +0 -1
  147. package/dist/__tests__/versionCheckPlugin.test.js +0 -597
  148. package/dist/actions.openApi.test.d.ts +0 -1
  149. package/dist/actions.openApi.test.js +0 -253
  150. package/dist/actions.test.d.ts +0 -1
  151. package/dist/actions.test.js +0 -1087
  152. package/dist/api.arrayOperations.test.d.ts +0 -1
  153. package/dist/api.arrayOperations.test.js +0 -878
  154. package/dist/api.asyncHandler.test.d.ts +0 -1
  155. package/dist/api.asyncHandler.test.js +0 -236
  156. package/dist/api.coverage.test.d.ts +0 -1
  157. package/dist/api.coverage.test.js +0 -192
  158. package/dist/api.errorPaths.test.d.ts +0 -1
  159. package/dist/api.errorPaths.test.js +0 -887
  160. package/dist/api.errors.test.d.ts +0 -1
  161. package/dist/api.errors.test.js +0 -185
  162. package/dist/api.hooks.test.d.ts +0 -1
  163. package/dist/api.hooks.test.js +0 -950
  164. package/dist/api.query.test.d.ts +0 -1
  165. package/dist/api.query.test.js +0 -948
  166. package/dist/api.test.d.ts +0 -1
  167. package/dist/api.test.js +0 -2820
  168. package/dist/auth.compile.test.d.ts +0 -1
  169. package/dist/auth.compile.test.js +0 -201
  170. package/dist/auth.coverage.test.d.ts +0 -1
  171. package/dist/auth.coverage.test.js +0 -202
  172. package/dist/auth.test.d.ts +0 -1
  173. package/dist/auth.test.js +0 -2286
  174. package/dist/betterAuth.test.d.ts +0 -1
  175. package/dist/betterAuth.test.js +0 -181
  176. package/dist/betterAuthApp.test.d.ts +0 -1
  177. package/dist/betterAuthApp.test.js +0 -242
  178. package/dist/betterAuthSetup.test.d.ts +0 -1
  179. package/dist/betterAuthSetup.test.js +0 -762
  180. package/dist/config.test.d.ts +0 -1
  181. package/dist/config.test.js +0 -353
  182. package/dist/configuration.test.d.ts +0 -1
  183. package/dist/configuration.test.js +0 -980
  184. package/dist/configurationPlugin.test.d.ts +0 -1
  185. package/dist/configurationPlugin.test.js +0 -827
  186. package/dist/consentApp.test.d.ts +0 -1
  187. package/dist/consentApp.test.js +0 -1411
  188. package/dist/docLoader.test.d.ts +0 -1
  189. package/dist/docLoader.test.js +0 -137
  190. package/dist/envConfigurationPlugin.test.d.ts +0 -1
  191. package/dist/envConfigurationPlugin.test.js +0 -369
  192. package/dist/errors.test.d.ts +0 -1
  193. package/dist/errors.test.js +0 -607
  194. package/dist/expressServer.test.d.ts +0 -1
  195. package/dist/expressServer.test.js +0 -1249
  196. package/dist/githubAuth.test.d.ts +0 -1
  197. package/dist/githubAuth.test.js +0 -1142
  198. package/dist/httpClient.test.d.ts +0 -1
  199. package/dist/httpClient.test.js +0 -1471
  200. package/dist/logger.test.d.ts +0 -1
  201. package/dist/logger.test.js +0 -685
  202. package/dist/middleware.test.d.ts +0 -1
  203. package/dist/middleware.test.js +0 -241
  204. package/dist/notifiers/googleChatNotifier.test.d.ts +0 -1
  205. package/dist/notifiers/googleChatNotifier.test.js +0 -298
  206. package/dist/notifiers/slackNotifier.test.d.ts +0 -1
  207. package/dist/notifiers/slackNotifier.test.js +0 -297
  208. package/dist/notifiers/zoomNotifier.test.d.ts +0 -1
  209. package/dist/notifiers/zoomNotifier.test.js +0 -373
  210. package/dist/openApi.test.d.ts +0 -1
  211. package/dist/openApi.test.js +0 -620
  212. package/dist/openApiBuilder.test.d.ts +0 -1
  213. package/dist/openApiBuilder.test.js +0 -599
  214. package/dist/openApiEtag.test.d.ts +0 -1
  215. package/dist/openApiEtag.test.js +0 -86
  216. package/dist/openApiValidator.test.d.ts +0 -1
  217. package/dist/openApiValidator.test.js +0 -795
  218. package/dist/permissions.middleware.test.d.ts +0 -1
  219. package/dist/permissions.middleware.test.js +0 -308
  220. package/dist/permissions.test.d.ts +0 -1
  221. package/dist/permissions.test.js +0 -439
  222. package/dist/plugins.test.d.ts +0 -1
  223. package/dist/plugins.test.js +0 -902
  224. package/dist/populate.test.d.ts +0 -1
  225. package/dist/populate.test.js +0 -370
  226. package/dist/realtime/realtime.test.d.ts +0 -10
  227. package/dist/realtime/realtime.test.js +0 -4213
  228. package/dist/realtime/realtimeAppSetup.test.d.ts +0 -1
  229. package/dist/realtime/realtimeAppSetup.test.js +0 -213
  230. package/dist/requestContext.test.d.ts +0 -1
  231. package/dist/requestContext.test.js +0 -412
  232. package/dist/scriptRunner.test.d.ts +0 -1
  233. package/dist/scriptRunner.test.js +0 -386
  234. package/dist/secretProviders.test.d.ts +0 -1
  235. package/dist/secretProviders.test.js +0 -726
  236. package/dist/syncConsents.test.d.ts +0 -1
  237. package/dist/syncConsents.test.js +0 -522
  238. package/dist/terrenoApp.test.d.ts +0 -1
  239. package/dist/terrenoApp.test.js +0 -489
  240. package/dist/tests/bunSetup.d.ts +0 -1
  241. package/dist/tests/fixtures/compileAuthEntry.d.ts +0 -1
  242. package/dist/tests/fixtures/compileAuthEntry.js +0 -37
  243. package/dist/tests/testEnv.d.ts +0 -0
  244. package/dist/tests/testEnv.js +0 -6
  245. package/dist/transformers.test.d.ts +0 -1
  246. package/dist/transformers.test.js +0 -423
  247. package/dist/utils.test.d.ts +0 -1
  248. package/dist/utils.test.js +0 -242
  249. package/src/realtime/realtimeAppSetup.test.ts +0 -161
  250. /package/dist/{__tests__/openApiCompat.test.d.ts → sync/loadHarness.d.ts} +0 -0
@@ -0,0 +1,219 @@
1
+ import type express from "express";
2
+ import type {User} from "../auth";
3
+ import {logger} from "../logger";
4
+ import {
5
+ applySyncMutation,
6
+ applySyncMutationBatch,
7
+ type SyncMutationOutcome,
8
+ type SyncMutationScopeResolver,
9
+ validateSyncMutationBatch,
10
+ } from "./mutationHandler";
11
+ import type {SyncMutateBatchResponse, SyncMutateRequest, SyncNack} from "./types";
12
+
13
+ /**
14
+ * Task 9.20: the single orchestration both mutation transports run.
15
+ *
16
+ * `POST /sync/mutate{,/batch}` and `sync:mutate{,Batch}` used to each carry their own copy
17
+ * of the size-cap -> rate-limit -> validate -> apply sequence, and the socket budget lived
18
+ * in a per-connection closure — so one user on N sockets got N times the budget, while the
19
+ * HTTP window map was per-user but never evicted. Everything now funnels through
20
+ * {@link runSyncMutation} / {@link runSyncBatch} against ONE per-user window map, so a
21
+ * user's budget is theirs no matter how many sockets or HTTP requests they spread it over.
22
+ *
23
+ * Multi-instance semantics: the window map is per PROCESS, so a deployment running N API
24
+ * instances behind a load balancer grants up to N times this budget per user in the worst
25
+ * case. That is intentional — this limiter exists to stop a runaway client from saturating
26
+ * one process, not to meter fair use across a cluster. A cluster-wide limit needs shared
27
+ * state (Redis) and belongs in front of the app, not here.
28
+ */
29
+ export const MAX_SYNC_MUTATIONS_PER_SECOND = 100;
30
+
31
+ /** Width of the rolling per-user mutation budget window. */
32
+ const RATE_LIMIT_WINDOW_MS = 1000;
33
+
34
+ /**
35
+ * How often expired windows are swept out of the map. Windows are only 1s wide, so an
36
+ * unswept map would otherwise retain one entry per user seen since process start.
37
+ */
38
+ const WINDOW_EVICTION_INTERVAL_MS = 60_000;
39
+
40
+ interface MutationWindow {
41
+ /** Epoch ms the current window opened. */
42
+ windowStart: number;
43
+ /** Mutations charged to the current window. */
44
+ count: number;
45
+ }
46
+
47
+ /** userId -> rolling one-second mutation window, shared by every transport. */
48
+ const mutationWindows = new Map<string, MutationWindow>();
49
+
50
+ let lastEvictionAt = 0;
51
+
52
+ /**
53
+ * Drop windows that have expired, so the map does not grow with every user ever seen.
54
+ * Runs automatically (throttled to {@link WINDOW_EVICTION_INTERVAL_MS}) whenever budget is
55
+ * charged; `now` is injectable so the sweep can be exercised without waiting a minute.
56
+ * Returns the number of windows still retained.
57
+ */
58
+ export const evictExpiredSyncMutationWindows = ({
59
+ now = Date.now(),
60
+ }: {
61
+ now?: number;
62
+ } = {}): number => {
63
+ lastEvictionAt = now;
64
+ for (const [userId, window] of mutationWindows) {
65
+ if (now - window.windowStart >= RATE_LIMIT_WINDOW_MS) {
66
+ mutationWindows.delete(userId);
67
+ }
68
+ }
69
+ return mutationWindows.size;
70
+ };
71
+
72
+ /** Sweep expired windows at most once per {@link WINDOW_EVICTION_INTERVAL_MS}. */
73
+ const maybeEvictExpiredWindows = (now: number): void => {
74
+ if (now - lastEvictionAt < WINDOW_EVICTION_INTERVAL_MS) {
75
+ return;
76
+ }
77
+ evictExpiredSyncMutationWindows({now});
78
+ };
79
+
80
+ /**
81
+ * Charge `weight` mutations to `userId`'s rolling window. Returns `undefined` when the
82
+ * budget allowed it (and the weight was consumed), or the ms remaining in the window when
83
+ * it did not — the caller nacks `rate_limited` with that as `retryAfterMs` rather than
84
+ * burning any retry budget (rate limiting must never look like a durable-data error).
85
+ *
86
+ * A rejected request consumes nothing: a client held over budget would otherwise keep its
87
+ * own window pinned full and never recover within the second.
88
+ */
89
+ const consumeMutationBudget = ({
90
+ userId,
91
+ weight,
92
+ }: {
93
+ userId: string;
94
+ weight: number;
95
+ }): number | undefined => {
96
+ const now = Date.now();
97
+ maybeEvictExpiredWindows(now);
98
+ const existing = mutationWindows.get(userId);
99
+ const window =
100
+ !existing || now - existing.windowStart >= RATE_LIMIT_WINDOW_MS
101
+ ? {count: 0, windowStart: now}
102
+ : existing;
103
+ if (window.count + weight > MAX_SYNC_MUTATIONS_PER_SECOND) {
104
+ // Keep the window as-is (a fresh one is not stored) so the caller's retryAfterMs
105
+ // reflects the window that is actually full.
106
+ return Math.max(0, RATE_LIMIT_WINDOW_MS - (now - window.windowStart));
107
+ }
108
+ window.count += weight;
109
+ mutationWindows.set(userId, window);
110
+ return undefined;
111
+ };
112
+
113
+ /** Clear every per-user window. Test-only: windows are module state shared across suites. */
114
+ export const resetSyncMutationRateLimits = (): void => {
115
+ mutationWindows.clear();
116
+ lastEvictionAt = 0;
117
+ };
118
+
119
+ /** Number of retained per-user windows — lets tests assert eviction actually happens. */
120
+ export const syncMutationRateLimitWindowCount = (): number => mutationWindows.size;
121
+
122
+ /** The `rate_limited` nack both transports return, minus the mutationId the caller knows. */
123
+ const rateLimitNack = (retryAfterMs: number): Omit<SyncNack, "mutationId"> => ({
124
+ code: "rate_limited",
125
+ message: `Rate limit of ${MAX_SYNC_MUTATIONS_PER_SECOND} mutations per second exceeded`,
126
+ retryAfterMs,
127
+ });
128
+
129
+ /**
130
+ * Which stage produced the result. The HTTP routes map this to a status code
131
+ * (`rate_limited` -> 429, `validation` -> 422, `applied` -> 200); the socket handlers
132
+ * ignore it and just return the payload.
133
+ */
134
+ export type SyncRunStage = "applied" | "rate_limited" | "validation";
135
+
136
+ export interface SyncMutationRunResult {
137
+ stage: Exclude<SyncRunStage, "validation">;
138
+ outcome: SyncMutationOutcome;
139
+ }
140
+
141
+ export interface SyncBatchRunResult {
142
+ stage: SyncRunStage;
143
+ response: SyncMutateBatchResponse;
144
+ }
145
+
146
+ /** Shared orchestration for a SINGLE mutation: rate limit, then apply. */
147
+ export const runSyncMutation = async ({
148
+ mutation,
149
+ req,
150
+ scopeResolver,
151
+ user,
152
+ }: {
153
+ mutation: SyncMutateRequest;
154
+ /** The real Express request when called over HTTP; hooks receive a `{user}` stub otherwise. */
155
+ req?: express.Request;
156
+ scopeResolver?: SyncMutationScopeResolver;
157
+ user: User;
158
+ }): Promise<SyncMutationRunResult> => {
159
+ const userId = String(user.id);
160
+ const mutationId = typeof mutation?.mutationId === "string" ? mutation.mutationId : "";
161
+ const retryAfterMs = consumeMutationBudget({userId, weight: 1});
162
+ if (retryAfterMs !== undefined) {
163
+ logger.info("[sync] User hit the sync mutation rate limit", {mutationId, userId});
164
+ return {
165
+ outcome: {nack: {mutationId, ...rateLimitNack(retryAfterMs)}, type: "nack"},
166
+ stage: "rate_limited",
167
+ };
168
+ }
169
+ return {
170
+ outcome: await applySyncMutation({mutation, req, scopeResolver, user}),
171
+ stage: "applied",
172
+ };
173
+ };
174
+
175
+ /**
176
+ * Shared orchestration for a BATCH: validate (size cap + intra-batch duplicate ids),
177
+ * then rate limit, then apply.
178
+ *
179
+ * Validation runs FIRST so a malformed batch consumes no budget — it was never going to
180
+ * be applied, and charging for it let a buggy client rate-limit itself out of the
181
+ * mutations that would have succeeded. The budget is then charged per MUTATION (not per
182
+ * batch), so batching cannot buy extra throughput over single sends.
183
+ */
184
+ export const runSyncBatch = async ({
185
+ mutations,
186
+ req,
187
+ scopeResolver,
188
+ user,
189
+ }: {
190
+ mutations: SyncMutateRequest[];
191
+ req?: express.Request;
192
+ scopeResolver?: SyncMutationScopeResolver;
193
+ user: User;
194
+ }): Promise<SyncBatchRunResult> => {
195
+ const validation = validateSyncMutationBatch(mutations);
196
+ if (!validation.ok) {
197
+ return {response: validation.response, stage: "validation"};
198
+ }
199
+
200
+ const userId = String(user.id);
201
+ const retryAfterMs = consumeMutationBudget({userId, weight: mutations.length});
202
+ if (retryAfterMs !== undefined) {
203
+ logger.info("[sync] User hit the sync batch mutation rate limit", {
204
+ batchSize: mutations.length,
205
+ userId,
206
+ });
207
+ return {
208
+ response: {
209
+ results: [{nack: {mutationId: "", ...rateLimitNack(retryAfterMs)}, type: "nack"}],
210
+ },
211
+ stage: "rate_limited",
212
+ };
213
+ }
214
+
215
+ return {
216
+ response: await applySyncMutationBatch({mutations, req, scopeResolver, user}),
217
+ stage: "applied",
218
+ };
219
+ };