@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,188 @@
1
+ import type {User} from "../auth";
2
+ import {APIError} from "../errors";
3
+ import type {SyncRegistryEntry} from "./registry";
4
+ import type {SyncScope} from "./types";
5
+
6
+ /**
7
+ * Stream key resolution for SyncDB.
8
+ *
9
+ * A stream is the unit of ordered delivery and cursor resumption:
10
+ * `{collectionTag}|owner:{ownerId}`, `{collectionTag}|tenant:{tenantId}`,
11
+ * `{collectionTag}|all` (broadcast), or `{collectionTag}|custom:{value}`.
12
+ */
13
+
14
+ /** The document field a scope reads, or null for broadcast/custom scopes. */
15
+ export const getScopeField = (scope: SyncScope): string | null => {
16
+ if (typeof scope === "function") {
17
+ return null;
18
+ }
19
+ if (scope.type === "owner") {
20
+ return scope.field ?? "ownerId";
21
+ }
22
+ if (scope.type === "tenant") {
23
+ return scope.field;
24
+ }
25
+ return null;
26
+ };
27
+
28
+ /** Build a stream key from a collection tag and a raw scope value. */
29
+ export const streamForScopeValue = ({
30
+ collectionTag,
31
+ scope,
32
+ scopeValue,
33
+ }: {
34
+ collectionTag: string;
35
+ scope: SyncScope;
36
+ scopeValue: unknown;
37
+ }): string => {
38
+ if (typeof scope === "function") {
39
+ return `${collectionTag}|custom:${String(scopeValue)}`;
40
+ }
41
+ if (scope.type === "owner") {
42
+ return `${collectionTag}|owner:${String(scopeValue)}`;
43
+ }
44
+ if (scope.type === "tenant") {
45
+ return `${collectionTag}|tenant:${String(scopeValue)}`;
46
+ }
47
+ return `${collectionTag}|all`;
48
+ };
49
+
50
+ /**
51
+ * Parse a stream key into its collection tag and scope value. The value is everything
52
+ * after the first `:` following the `|`-delimited collection tag, so custom values
53
+ * containing `:` survive intact. Broadcast streams (`{tag}|all`) yield `scopeValue: null`.
54
+ * Returns null when the key is not a valid stream key.
55
+ */
56
+ export const parseStreamKey = (
57
+ stream: string
58
+ ): {collectionTag: string; scopeKind: string; scopeValue: string | null} | null => {
59
+ const pipe = stream.indexOf("|");
60
+ if (pipe <= 0) {
61
+ return null;
62
+ }
63
+ const collectionTag = stream.slice(0, pipe);
64
+ const rest = stream.slice(pipe + 1);
65
+ if (rest === "all") {
66
+ return {collectionTag, scopeKind: "all", scopeValue: null};
67
+ }
68
+ const colon = rest.indexOf(":");
69
+ if (colon < 0) {
70
+ return null;
71
+ }
72
+ return {
73
+ collectionTag,
74
+ scopeKind: rest.slice(0, colon),
75
+ scopeValue: rest.slice(colon + 1),
76
+ };
77
+ };
78
+
79
+ /**
80
+ * Resolve the stream a document belongs to under the given scope.
81
+ *
82
+ * Deliberately total: readers (the change-stream watcher, the tombstone compactor) must
83
+ * be able to name a stream for any document already in the database, including legacy
84
+ * rows written before a scope field existed. Rejecting an unroutable document is the
85
+ * write path's job — see {@link assertWritableStream}.
86
+ */
87
+ export const resolveStreamForDoc = ({
88
+ collectionTag,
89
+ scope,
90
+ doc,
91
+ }: {
92
+ collectionTag: string;
93
+ scope: SyncScope;
94
+ doc: Record<string, unknown>;
95
+ }): string => {
96
+ if (typeof scope === "function") {
97
+ return streamForScopeValue({collectionTag, scope, scopeValue: scope(doc)});
98
+ }
99
+ if (scope.type === "broadcast") {
100
+ return streamForScopeValue({collectionTag, scope, scopeValue: null});
101
+ }
102
+ const field = getScopeField(scope) as string;
103
+ return streamForScopeValue({collectionTag, scope, scopeValue: doc[field]});
104
+ };
105
+
106
+ /**
107
+ * Write-path guard: refuse to file a tenant-scoped document under `tenant:undefined`, a
108
+ * stream no client can ever subscribe to, which would leave the document written,
109
+ * invisible, and never synced (Task 9.21).
110
+ *
111
+ * Called from the `_syncSeq` plugin's write hooks, so it sees the EFFECTIVE scope value —
112
+ * after any `preCreate` has injected it and before the write commits — on every write
113
+ * path, sync mutations and plain REST/model writes alike. That is why the sync mutation
114
+ * handler does not try to infer the same thing from the raw request body: a create may
115
+ * legitimately omit the field for `preCreate` to supply.
116
+ *
117
+ * Owner scopes are intentionally not guarded: `ownerId` is conventionally stamped by
118
+ * `preCreate`/`IsOwner` plumbing, and an unowned document is still admin-reachable, so
119
+ * tightening that is a separate behavioral change.
120
+ */
121
+ export const assertWritableStream = ({
122
+ collectionTag,
123
+ scope,
124
+ doc,
125
+ }: {
126
+ collectionTag: string;
127
+ scope: SyncScope;
128
+ doc: Record<string, unknown>;
129
+ }): void => {
130
+ if (typeof scope === "function" || scope.type !== "tenant") {
131
+ return;
132
+ }
133
+ const field = getScopeField(scope) as string;
134
+ const scopeValue = doc[field];
135
+ if (scopeValue === undefined || scopeValue === null) {
136
+ throw new APIError({
137
+ status: 400,
138
+ title: `Sync write on ${collectionTag} is missing tenant scope field "${field}"`,
139
+ });
140
+ }
141
+ };
142
+
143
+ /**
144
+ * Resolve the streams a user currently belongs to for one registered entry — the
145
+ * authoritative membership set, shared by the socket `sync:subscribe` handler,
146
+ * `GET /sync/streams`, and the snapshot stream-membership check.
147
+ *
148
+ * - broadcast → the single `{collection}|all` stream.
149
+ * - owner → the single stream keyed by the authenticated user's own id (a client-supplied
150
+ * id must never select the stream).
151
+ * - tenant / custom → one stream per value from `getUserScopes`. Requires the resolver;
152
+ * throws {@link MissingScopeResolverError} when it is absent.
153
+ *
154
+ * Runs against the FULL user (D2) so tenant memberships resolve from current
155
+ * `organizationIds`.
156
+ */
157
+ export class MissingScopeResolverError extends Error {
158
+ constructor(public collection: string) {
159
+ super(`Sync collection ${collection} requires a getUserScopes resolver on SyncApp`);
160
+ this.name = "MissingScopeResolverError";
161
+ }
162
+ }
163
+
164
+ export const resolveUserStreamsForEntry = async ({
165
+ entry,
166
+ user,
167
+ getUserScopes,
168
+ }: {
169
+ entry: SyncRegistryEntry;
170
+ user: User;
171
+ getUserScopes?: (user: User, entry: SyncRegistryEntry) => Promise<string[]> | string[];
172
+ }): Promise<string[]> => {
173
+ const {scope} = entry.config;
174
+ const collection = entry.collectionTag;
175
+ if (typeof scope !== "function" && scope.type === "broadcast") {
176
+ return [streamForScopeValue({collectionTag: collection, scope, scopeValue: null})];
177
+ }
178
+ if (typeof scope !== "function" && scope.type === "owner") {
179
+ return [streamForScopeValue({collectionTag: collection, scope, scopeValue: user.id})];
180
+ }
181
+ if (!getUserScopes) {
182
+ throw new MissingScopeResolverError(collection);
183
+ }
184
+ const scopeValues = await getUserScopes(user, entry);
185
+ return scopeValues.map((scopeValue) =>
186
+ streamForScopeValue({collectionTag: collection, scope, scopeValue})
187
+ );
188
+ };