@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,97 @@
1
+ import type express from "express";
2
+ import type { User } from "../auth";
3
+ import { type SyncRegistryEntry } from "./registry";
4
+ import type { SyncAck, SyncMutateBatchResponse, SyncMutateRequest, SyncNack } from "./types";
5
+ export type SyncMutationScopeResolver = (user: User, entry: SyncRegistryEntry) => Promise<string[]> | string[];
6
+ /**
7
+ * Shared mutation handler for the sync channel: `POST /sync/mutate` (HTTP fallback)
8
+ * and `sync:mutate` (socket) both delegate here.
9
+ *
10
+ * Idempotency (atomic claim): the handler inserts a SyncMutation ledger row with status
11
+ * `pending` (unique index on mutationId) *before* applying. A duplicate-key error means
12
+ * another delivery owns or already completed the mutation, so the handler polls the
13
+ * existing row and returns the recorded outcome instead of re-applying — closing the
14
+ * race where a socket retry and the HTTP fallback deliver the same mutation concurrently.
15
+ *
16
+ * Conflict rule: the client's `baseVersion` (the `_syncSeq` it last saw) is passed to
17
+ * executeUpdate as a seq concurrency check; a mismatch yields a `conflict` nack carrying
18
+ * the canonical serialized server document and its current seq.
19
+ *
20
+ * C5 crash resilience (FIX 6):
21
+ * - **Lease/takeover (M4).** A `pending` row carries `claimedAt`. If a server crashes
22
+ * between claiming the row and finalizing it, the mutationId would otherwise be wedged
23
+ * for the full 30-day TTL. A duplicate-claim attempt older than
24
+ * {@link SYNC_MUTATION_LEASE_MS} may take over via an atomic
25
+ * `findOneAndUpdate({_id, status: "pending", claimedAt: {$lt: cutoff}}, {$set: {claimedAt: now}})`
26
+ * and re-run the mutation as the new claimant. Because the original attempt may have
27
+ * already landed the write before crashing, the executor path tolerates that: a create
28
+ * that hits E11000 on the SAME `_id` reads the doc back and reports it as the ack instead
29
+ * of nacking; an update/delete whose current server seq already reflects this mutation's
30
+ * expected post-write seq (`baseVersion + 1`) is treated as already-applied and reported
31
+ * from the current doc rather than re-executed (which would otherwise spuriously conflict
32
+ * against the write it is itself retrying).
33
+ * - **Finalize-before-post-hooks (M5).** The pipeline is: document write → finalize the
34
+ * ledger `applied` (with the ack payload) → THEN run the model's post-hook
35
+ * (`postCreate`/`postUpdate`/`postDelete`). A post-hook throw is `logger.error`'d and
36
+ * reported back as an ack with a `warning` field — never converted into a nack, since the
37
+ * write (and its delta) already committed and rolling the client back would be a lie. If
38
+ * the `applied` finalize itself throws, the request is allowed to fail loudly (500); the
39
+ * client's transport retry lands on the lease-takeover path above, which resolves it from
40
+ * the ledger/doc state rather than double-applying.
41
+ */
42
+ /** Outcome of applying a sync mutation: an ack for the client, or a typed nack. */
43
+ export type SyncMutationOutcome = {
44
+ type: "ack";
45
+ ack: SyncAck;
46
+ } | {
47
+ type: "nack";
48
+ nack: SyncNack;
49
+ };
50
+ /** Maximum mutations accepted in a single `sync:mutateBatch` / `POST /sync/mutate/batch` request. */
51
+ export declare const MAX_SYNC_MUTATIONS_PER_BATCH = 100;
52
+ /**
53
+ * Apply a client mutation through the transport-agnostic executors (permissions,
54
+ * pre/post hooks, validation) with an atomic idempotency claim. Always finalizes the
55
+ * claimed ledger row before returning so duplicate deliveries can read the outcome back.
56
+ */
57
+ export declare const applySyncMutation: ({ user, mutation, req, scopeResolver, }: {
58
+ user: User;
59
+ mutation: SyncMutateRequest;
60
+ /** The real Express request when called over HTTP; hooks receive a `{user}` stub otherwise. */
61
+ req?: express.Request;
62
+ scopeResolver?: SyncMutationScopeResolver;
63
+ }) => Promise<SyncMutationOutcome>;
64
+ /** Outcome of a batch validation pre-check (before any mutation is attempted). */
65
+ export type SyncBatchValidationOutcome = {
66
+ ok: true;
67
+ } | {
68
+ ok: false;
69
+ response: SyncMutateBatchResponse;
70
+ };
71
+ /**
72
+ * Up-front validation shared by both batch transports (HTTP and socket): reject an
73
+ * oversized batch or one with intra-batch duplicate mutationIds before anything is
74
+ * applied. On failure, returns a single-element `results` array carrying a
75
+ * `validation` nack for the offending mutation (or an empty-batch guard) — mirroring
76
+ * the shape callers expect from `applySyncMutationBatch`, but produced without
77
+ * touching the idempotency ledger since nothing was attempted.
78
+ */
79
+ export declare const validateSyncMutationBatch: (mutations: SyncMutateRequest[]) => SyncBatchValidationOutcome;
80
+ /**
81
+ * Apply a batch of mutations strictly serially, in array order, reusing
82
+ * `applySyncMutation` per item — full reuse of the idempotency ledger, executors,
83
+ * permissions, and delta emission. Stops immediately at the first non-ack outcome
84
+ * (the user's hard requirement, INV-1): mutations after it are neither attempted nor
85
+ * ledgered, and are safe for the client to resend later (INV-3).
86
+ *
87
+ * Callers MUST run {@link validateSyncMutationBatch} first (oversized/duplicate
88
+ * rejection happens before any mutation is attempted); this function assumes the
89
+ * batch already passed that check.
90
+ */
91
+ export declare const applySyncMutationBatch: ({ user, mutations, req, scopeResolver, }: {
92
+ user: User;
93
+ mutations: SyncMutateRequest[];
94
+ /** The real Express request when called over HTTP; hooks receive a `{user}` stub otherwise. */
95
+ req?: express.Request;
96
+ scopeResolver?: SyncMutationScopeResolver;
97
+ }) => Promise<SyncMutateBatchResponse>;