@terreno/api 0.31.0 → 56.0.0-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (232) hide show
  1. package/dist/api.d.ts +10 -0
  2. package/dist/api.js +110 -361
  3. package/dist/auth.d.ts +26 -0
  4. package/dist/auth.js +121 -26
  5. package/dist/betterAuth.d.ts +5 -0
  6. package/dist/betterAuthSetup.js +23 -4
  7. package/dist/docLoader.js +12 -9
  8. package/dist/errors.d.ts +13 -0
  9. package/dist/errors.js +29 -1
  10. package/dist/index.d.ts +17 -1
  11. package/dist/index.js +29 -1
  12. package/dist/middleware.d.ts +7 -0
  13. package/dist/middleware.js +16 -1
  14. package/dist/openApiCompat.d.ts +10 -1
  15. package/dist/openApiCompat.js +115 -47
  16. package/dist/permissions.d.ts +27 -0
  17. package/dist/permissions.js +42 -1
  18. package/dist/plugins.d.ts +13 -0
  19. package/dist/plugins.js +47 -1
  20. package/dist/realtime/changeStreamWatcher.d.ts +100 -3
  21. package/dist/realtime/changeStreamWatcher.js +542 -137
  22. package/dist/realtime/realtimeApp.d.ts +2 -0
  23. package/dist/realtime/realtimeApp.js +83 -27
  24. package/dist/realtime/sessionRevalidation.d.ts +90 -0
  25. package/dist/realtime/sessionRevalidation.js +438 -0
  26. package/dist/realtime/socketAuth.d.ts +97 -0
  27. package/dist/realtime/socketAuth.js +272 -0
  28. package/dist/realtime/socketUser.d.ts +54 -0
  29. package/dist/realtime/socketUser.js +75 -5
  30. package/dist/realtime/types.d.ts +54 -0
  31. package/dist/secretProviders.d.ts +23 -0
  32. package/dist/secretProviders.js +9 -3
  33. package/dist/sync/executors.d.ts +198 -0
  34. package/dist/sync/executors.js +670 -0
  35. package/dist/sync/loadHarness.js +807 -0
  36. package/dist/sync/models.d.ts +216 -0
  37. package/dist/sync/models.js +644 -0
  38. package/dist/sync/mutationHandler.d.ts +97 -0
  39. package/dist/sync/mutationHandler.js +886 -0
  40. package/dist/sync/registry.d.ts +73 -0
  41. package/dist/sync/registry.js +223 -0
  42. package/dist/sync/routes.d.ts +62 -0
  43. package/dist/sync/routes.js +936 -0
  44. package/dist/sync/scripts/compactTombstones.d.ts +47 -0
  45. package/dist/sync/scripts/compactTombstones.js +270 -0
  46. package/dist/sync/serialize.d.ts +20 -0
  47. package/dist/{tests/bunSetup.js → sync/serialize.js} +35 -68
  48. package/dist/sync/socketHandlers.d.ts +54 -0
  49. package/dist/sync/socketHandlers.js +470 -0
  50. package/dist/sync/streams.d.ts +85 -0
  51. package/dist/sync/streams.js +221 -0
  52. package/dist/sync/syncApp.d.ts +29 -0
  53. package/dist/sync/syncApp.js +44 -0
  54. package/dist/sync/syncBatch.d.ts +71 -0
  55. package/dist/sync/syncBatch.js +252 -0
  56. package/dist/sync/syncSeqPlugin.d.ts +8 -0
  57. package/dist/sync/syncSeqPlugin.js +899 -0
  58. package/dist/sync/types.d.ts +254 -0
  59. package/dist/sync/types.js +9 -0
  60. package/dist/terrenoApp.js +90 -27
  61. package/dist/vendor/wesleytodd-openapi/index.d.ts +1 -1
  62. package/dist/vendor/wesleytodd-openapi/lib/ui.d.ts +2 -1
  63. package/package.json +7 -6
  64. package/src/__tests__/openApiCompat.test.ts +20 -0
  65. package/src/api.errors.test.ts +32 -23
  66. package/src/api.test.ts +12 -0
  67. package/src/api.ts +87 -296
  68. package/src/auth.test.ts +202 -0
  69. package/src/auth.ts +134 -23
  70. package/src/betterAuth.ts +6 -0
  71. package/src/betterAuthSetup.test.ts +34 -0
  72. package/src/betterAuthSetup.ts +20 -1
  73. package/src/configuration.test.ts +59 -38
  74. package/src/configurationPlugin.test.ts +72 -42
  75. package/src/docLoader.ts +3 -1
  76. package/src/errors.ts +33 -0
  77. package/src/expressServer.test.ts +7 -1
  78. package/src/index.ts +42 -0
  79. package/src/middleware.test.ts +56 -1
  80. package/src/middleware.ts +15 -0
  81. package/src/openApiCompat.ts +99 -45
  82. package/src/permissions.test.ts +101 -17
  83. package/src/permissions.ts +49 -0
  84. package/src/plugins.test.ts +64 -0
  85. package/src/plugins.ts +56 -0
  86. package/src/realtime/changeStreamWatcher.ts +552 -114
  87. package/src/realtime/realtime.test.ts +157 -0
  88. package/src/realtime/realtimeApp.ts +82 -14
  89. package/src/realtime/realtimeAppSetup.test.ts +25 -27
  90. package/src/realtime/sessionRevalidation.test.ts +423 -0
  91. package/src/realtime/sessionRevalidation.ts +273 -0
  92. package/src/realtime/socketAuth.test.ts +355 -0
  93. package/src/realtime/socketAuth.ts +228 -0
  94. package/src/realtime/socketUser.ts +69 -0
  95. package/src/realtime/types.ts +54 -0
  96. package/src/secretProviders.test.ts +7 -1
  97. package/src/secretProviders.ts +15 -3
  98. package/src/secretProvidersGcpClient.test.ts +66 -0
  99. package/src/sync/ensureSyncIndexes.test.ts +144 -0
  100. package/src/sync/executors.test.ts +882 -0
  101. package/src/sync/executors.ts +705 -0
  102. package/src/sync/integration.test.ts +1160 -0
  103. package/src/sync/loadHarness.ts +618 -0
  104. package/src/sync/models.ts +641 -0
  105. package/src/sync/mutationHandler.test.ts +1252 -0
  106. package/src/sync/mutationHandler.ts +850 -0
  107. package/src/sync/registry.ts +232 -0
  108. package/src/sync/routes.ts +812 -0
  109. package/src/sync/scripts/compactTombstones.test.ts +249 -0
  110. package/src/sync/scripts/compactTombstones.ts +145 -0
  111. package/src/sync/serialize.ts +48 -0
  112. package/src/sync/sessionRevalidationIntegration.test.ts +281 -0
  113. package/src/sync/socketHandlers.ts +320 -0
  114. package/src/sync/streams.ts +188 -0
  115. package/src/sync/sync.test.ts +582 -0
  116. package/src/sync/syncApp.ts +44 -0
  117. package/src/sync/syncBatch.ts +219 -0
  118. package/src/sync/syncFrontier.test.ts +494 -0
  119. package/src/sync/syncPhaseC.test.ts +718 -0
  120. package/src/sync/syncRoutes.test.ts +865 -0
  121. package/src/sync/syncSeqPlugin.ts +730 -0
  122. package/src/sync/syncSocket.test.ts +1440 -0
  123. package/src/sync/types.ts +270 -0
  124. package/src/terrenoApp.ts +37 -17
  125. package/src/tests/bunSetup.ts +8 -0
  126. package/tsconfig.json +4 -4
  127. package/tsconfig.typedoc.json +7 -1
  128. package/dist/__tests__/openApiCompat.test.js +0 -317
  129. package/dist/__tests__/versionCheckPlugin.test.d.ts +0 -1
  130. package/dist/__tests__/versionCheckPlugin.test.js +0 -597
  131. package/dist/actions.openApi.test.d.ts +0 -1
  132. package/dist/actions.openApi.test.js +0 -253
  133. package/dist/actions.test.d.ts +0 -1
  134. package/dist/actions.test.js +0 -1087
  135. package/dist/api.arrayOperations.test.d.ts +0 -1
  136. package/dist/api.arrayOperations.test.js +0 -878
  137. package/dist/api.asyncHandler.test.d.ts +0 -1
  138. package/dist/api.asyncHandler.test.js +0 -236
  139. package/dist/api.coverage.test.d.ts +0 -1
  140. package/dist/api.coverage.test.js +0 -192
  141. package/dist/api.errorPaths.test.d.ts +0 -1
  142. package/dist/api.errorPaths.test.js +0 -887
  143. package/dist/api.errors.test.d.ts +0 -1
  144. package/dist/api.errors.test.js +0 -185
  145. package/dist/api.hooks.test.d.ts +0 -1
  146. package/dist/api.hooks.test.js +0 -950
  147. package/dist/api.query.test.d.ts +0 -1
  148. package/dist/api.query.test.js +0 -948
  149. package/dist/api.test.d.ts +0 -1
  150. package/dist/api.test.js +0 -2820
  151. package/dist/auth.compile.test.d.ts +0 -1
  152. package/dist/auth.compile.test.js +0 -201
  153. package/dist/auth.coverage.test.d.ts +0 -1
  154. package/dist/auth.coverage.test.js +0 -202
  155. package/dist/auth.test.d.ts +0 -1
  156. package/dist/auth.test.js +0 -2286
  157. package/dist/betterAuth.test.d.ts +0 -1
  158. package/dist/betterAuth.test.js +0 -181
  159. package/dist/betterAuthApp.test.d.ts +0 -1
  160. package/dist/betterAuthApp.test.js +0 -242
  161. package/dist/betterAuthSetup.test.d.ts +0 -1
  162. package/dist/betterAuthSetup.test.js +0 -762
  163. package/dist/config.test.d.ts +0 -1
  164. package/dist/config.test.js +0 -353
  165. package/dist/configuration.test.d.ts +0 -1
  166. package/dist/configuration.test.js +0 -980
  167. package/dist/configurationPlugin.test.d.ts +0 -1
  168. package/dist/configurationPlugin.test.js +0 -827
  169. package/dist/consentApp.test.d.ts +0 -1
  170. package/dist/consentApp.test.js +0 -1411
  171. package/dist/docLoader.test.d.ts +0 -1
  172. package/dist/docLoader.test.js +0 -137
  173. package/dist/envConfigurationPlugin.test.d.ts +0 -1
  174. package/dist/envConfigurationPlugin.test.js +0 -369
  175. package/dist/errors.test.d.ts +0 -1
  176. package/dist/errors.test.js +0 -607
  177. package/dist/expressServer.test.d.ts +0 -1
  178. package/dist/expressServer.test.js +0 -1249
  179. package/dist/githubAuth.test.d.ts +0 -1
  180. package/dist/githubAuth.test.js +0 -1142
  181. package/dist/httpClient.test.d.ts +0 -1
  182. package/dist/httpClient.test.js +0 -1471
  183. package/dist/logger.test.d.ts +0 -1
  184. package/dist/logger.test.js +0 -685
  185. package/dist/middleware.test.d.ts +0 -1
  186. package/dist/middleware.test.js +0 -241
  187. package/dist/notifiers/googleChatNotifier.test.d.ts +0 -1
  188. package/dist/notifiers/googleChatNotifier.test.js +0 -298
  189. package/dist/notifiers/slackNotifier.test.d.ts +0 -1
  190. package/dist/notifiers/slackNotifier.test.js +0 -297
  191. package/dist/notifiers/zoomNotifier.test.d.ts +0 -1
  192. package/dist/notifiers/zoomNotifier.test.js +0 -373
  193. package/dist/openApi.test.d.ts +0 -1
  194. package/dist/openApi.test.js +0 -620
  195. package/dist/openApiBuilder.test.d.ts +0 -1
  196. package/dist/openApiBuilder.test.js +0 -599
  197. package/dist/openApiEtag.test.d.ts +0 -1
  198. package/dist/openApiEtag.test.js +0 -86
  199. package/dist/openApiValidator.test.d.ts +0 -1
  200. package/dist/openApiValidator.test.js +0 -795
  201. package/dist/permissions.middleware.test.d.ts +0 -1
  202. package/dist/permissions.middleware.test.js +0 -308
  203. package/dist/permissions.test.d.ts +0 -1
  204. package/dist/permissions.test.js +0 -439
  205. package/dist/plugins.test.d.ts +0 -1
  206. package/dist/plugins.test.js +0 -902
  207. package/dist/populate.test.d.ts +0 -1
  208. package/dist/populate.test.js +0 -370
  209. package/dist/realtime/realtime.test.d.ts +0 -10
  210. package/dist/realtime/realtime.test.js +0 -4213
  211. package/dist/realtime/realtimeAppSetup.test.d.ts +0 -1
  212. package/dist/realtime/realtimeAppSetup.test.js +0 -213
  213. package/dist/requestContext.test.d.ts +0 -1
  214. package/dist/requestContext.test.js +0 -412
  215. package/dist/scriptRunner.test.d.ts +0 -1
  216. package/dist/scriptRunner.test.js +0 -386
  217. package/dist/secretProviders.test.d.ts +0 -1
  218. package/dist/secretProviders.test.js +0 -726
  219. package/dist/syncConsents.test.d.ts +0 -1
  220. package/dist/syncConsents.test.js +0 -522
  221. package/dist/terrenoApp.test.d.ts +0 -1
  222. package/dist/terrenoApp.test.js +0 -489
  223. package/dist/tests/bunSetup.d.ts +0 -1
  224. package/dist/tests/fixtures/compileAuthEntry.d.ts +0 -1
  225. package/dist/tests/fixtures/compileAuthEntry.js +0 -37
  226. package/dist/tests/testEnv.d.ts +0 -0
  227. package/dist/tests/testEnv.js +0 -6
  228. package/dist/transformers.test.d.ts +0 -1
  229. package/dist/transformers.test.js +0 -423
  230. package/dist/utils.test.d.ts +0 -1
  231. package/dist/utils.test.js +0 -242
  232. /package/dist/{__tests__/openApiCompat.test.d.ts → sync/loadHarness.d.ts} +0 -0
@@ -0,0 +1,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
+ };