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