@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.
- package/dist/api.d.ts +10 -0
- package/dist/api.js +110 -361
- package/dist/auth.d.ts +26 -0
- package/dist/auth.js +100 -1
- package/dist/betterAuth.d.ts +5 -0
- package/dist/betterAuthSetup.js +23 -4
- package/dist/docLoader.js +12 -9
- package/dist/errors.d.ts +13 -0
- package/dist/errors.js +29 -1
- package/dist/index.d.ts +17 -1
- package/dist/index.js +29 -1
- package/dist/middleware.d.ts +7 -0
- package/dist/middleware.js +16 -1
- package/dist/openApiCompat.d.ts +10 -1
- package/dist/openApiCompat.js +115 -47
- package/dist/permissions.d.ts +27 -0
- package/dist/permissions.js +42 -1
- package/dist/plugins.d.ts +13 -0
- package/dist/plugins.js +35 -1
- package/dist/realtime/changeStreamWatcher.d.ts +100 -3
- package/dist/realtime/changeStreamWatcher.js +542 -137
- package/dist/realtime/realtimeApp.d.ts +2 -0
- package/dist/realtime/realtimeApp.js +73 -21
- package/dist/realtime/sessionRevalidation.d.ts +90 -0
- package/dist/realtime/sessionRevalidation.js +438 -0
- package/dist/realtime/socketAuth.d.ts +97 -0
- package/dist/realtime/socketAuth.js +272 -0
- package/dist/realtime/socketUser.d.ts +54 -0
- package/dist/realtime/socketUser.js +75 -5
- package/dist/realtime/types.d.ts +40 -0
- package/dist/secretProviders.d.ts +23 -0
- package/dist/secretProviders.js +9 -3
- package/dist/sync/executors.d.ts +198 -0
- package/dist/sync/executors.js +670 -0
- package/dist/sync/loadHarness.js +807 -0
- package/dist/sync/models.d.ts +216 -0
- package/dist/sync/models.js +644 -0
- package/dist/sync/mutationHandler.d.ts +97 -0
- package/dist/sync/mutationHandler.js +886 -0
- package/dist/sync/registry.d.ts +73 -0
- package/dist/sync/registry.js +223 -0
- package/dist/sync/routes.d.ts +62 -0
- package/dist/sync/routes.js +936 -0
- package/dist/sync/scripts/compactTombstones.d.ts +47 -0
- package/dist/sync/scripts/compactTombstones.js +270 -0
- package/dist/sync/serialize.d.ts +20 -0
- package/dist/{tests/bunSetup.js → sync/serialize.js} +35 -68
- package/dist/sync/socketHandlers.d.ts +54 -0
- package/dist/sync/socketHandlers.js +470 -0
- package/dist/sync/streams.d.ts +85 -0
- package/dist/sync/streams.js +221 -0
- package/dist/sync/syncApp.d.ts +29 -0
- package/dist/sync/syncApp.js +44 -0
- package/dist/sync/syncBatch.d.ts +71 -0
- package/dist/sync/syncBatch.js +252 -0
- package/dist/sync/syncSeqPlugin.d.ts +8 -0
- package/dist/sync/syncSeqPlugin.js +903 -0
- package/dist/sync/types.d.ts +254 -0
- package/dist/sync/types.js +9 -0
- package/dist/terrenoApp.js +90 -27
- package/dist/vendor/wesleytodd-openapi/index.d.ts +1 -1
- package/dist/vendor/wesleytodd-openapi/lib/ui.d.ts +2 -1
- package/package.json +7 -6
- package/src/__tests__/openApiCompat.test.ts +20 -0
- package/src/actions.openApi.test.ts +7 -10
- package/src/api.test.ts +12 -0
- package/src/api.ts +87 -295
- package/src/auth.test.ts +128 -176
- package/src/auth.ts +109 -0
- package/src/betterAuth.ts +6 -0
- package/src/betterAuthSetup.test.ts +34 -0
- package/src/betterAuthSetup.ts +20 -1
- package/src/docLoader.ts +3 -1
- package/src/errors.ts +33 -0
- package/src/expressServer.test.ts +7 -1
- package/src/index.ts +42 -0
- package/src/middleware.test.ts +40 -1
- package/src/middleware.ts +15 -0
- package/src/openApiCompat.ts +99 -45
- package/src/permissions.test.ts +75 -1
- package/src/permissions.ts +49 -0
- package/src/plugins.test.ts +54 -0
- package/src/plugins.ts +43 -0
- package/src/realtime/changeStreamWatcher.ts +552 -114
- package/src/realtime/realtime.test.ts +157 -0
- package/src/realtime/realtimeApp.ts +75 -11
- package/src/realtime/sessionRevalidation.test.ts +423 -0
- package/src/realtime/sessionRevalidation.ts +273 -0
- package/src/realtime/socketAuth.test.ts +355 -0
- package/src/realtime/socketAuth.ts +228 -0
- package/src/realtime/socketUser.ts +69 -0
- package/src/realtime/types.ts +40 -0
- package/src/secretProviders.test.ts +7 -1
- package/src/secretProviders.ts +15 -3
- package/src/sync/ensureSyncIndexes.test.ts +144 -0
- package/src/sync/executors.test.ts +882 -0
- package/src/sync/executors.ts +703 -0
- package/src/sync/integration.test.ts +1160 -0
- package/src/sync/loadHarness.ts +618 -0
- package/src/sync/models.ts +640 -0
- package/src/sync/mutationHandler.test.ts +1252 -0
- package/src/sync/mutationHandler.ts +850 -0
- package/src/sync/registry.ts +232 -0
- package/src/sync/routes.ts +812 -0
- package/src/sync/scripts/compactTombstones.test.ts +249 -0
- package/src/sync/scripts/compactTombstones.ts +145 -0
- package/src/sync/serialize.ts +48 -0
- package/src/sync/sessionRevalidationIntegration.test.ts +281 -0
- package/src/sync/socketHandlers.ts +320 -0
- package/src/sync/streams.ts +188 -0
- package/src/sync/sync.test.ts +582 -0
- package/src/sync/syncApp.ts +44 -0
- package/src/sync/syncBatch.ts +219 -0
- package/src/sync/syncFrontier.test.ts +494 -0
- package/src/sync/syncPhaseC.test.ts +718 -0
- package/src/sync/syncRoutes.test.ts +865 -0
- package/src/sync/syncSeqPlugin.ts +738 -0
- package/src/sync/syncSocket.test.ts +1440 -0
- package/src/sync/types.ts +270 -0
- package/src/terrenoApp.ts +37 -17
- package/src/tests/bunSetup.ts +8 -0
- package/tsconfig.json +4 -4
- package/tsconfig.typedoc.json +7 -1
- package/dist/__tests__/openApiCompat.test.js +0 -317
- package/dist/__tests__/versionCheckPlugin.test.d.ts +0 -1
- package/dist/__tests__/versionCheckPlugin.test.js +0 -597
- package/dist/actions.openApi.test.d.ts +0 -1
- package/dist/actions.openApi.test.js +0 -255
- package/dist/actions.test.d.ts +0 -1
- package/dist/actions.test.js +0 -1089
- package/dist/api.arrayOperations.test.d.ts +0 -1
- package/dist/api.arrayOperations.test.js +0 -878
- package/dist/api.asyncHandler.test.d.ts +0 -1
- package/dist/api.asyncHandler.test.js +0 -236
- package/dist/api.coverage.test.d.ts +0 -1
- package/dist/api.coverage.test.js +0 -194
- package/dist/api.errorPaths.test.d.ts +0 -1
- package/dist/api.errorPaths.test.js +0 -801
- package/dist/api.errors.test.d.ts +0 -1
- package/dist/api.errors.test.js +0 -185
- package/dist/api.hooks.test.d.ts +0 -1
- package/dist/api.hooks.test.js +0 -950
- package/dist/api.query.test.d.ts +0 -1
- package/dist/api.query.test.js +0 -948
- package/dist/api.test.d.ts +0 -1
- package/dist/api.test.js +0 -2820
- package/dist/auth.compile.test.d.ts +0 -1
- package/dist/auth.compile.test.js +0 -201
- package/dist/auth.coverage.test.d.ts +0 -1
- package/dist/auth.coverage.test.js +0 -202
- package/dist/auth.test.d.ts +0 -1
- package/dist/auth.test.js +0 -2286
- package/dist/betterAuth.test.d.ts +0 -1
- package/dist/betterAuth.test.js +0 -181
- package/dist/betterAuthApp.test.d.ts +0 -1
- package/dist/betterAuthApp.test.js +0 -242
- package/dist/betterAuthSetup.test.d.ts +0 -1
- package/dist/betterAuthSetup.test.js +0 -762
- package/dist/config.test.d.ts +0 -1
- package/dist/config.test.js +0 -353
- package/dist/configuration.test.d.ts +0 -1
- package/dist/configuration.test.js +0 -980
- package/dist/configurationPlugin.test.d.ts +0 -1
- package/dist/configurationPlugin.test.js +0 -827
- package/dist/consentApp.test.d.ts +0 -1
- package/dist/consentApp.test.js +0 -1415
- package/dist/docLoader.test.d.ts +0 -1
- package/dist/docLoader.test.js +0 -137
- package/dist/envConfigurationPlugin.test.d.ts +0 -1
- package/dist/envConfigurationPlugin.test.js +0 -369
- package/dist/errors.test.d.ts +0 -1
- package/dist/errors.test.js +0 -607
- package/dist/expressServer.test.d.ts +0 -1
- package/dist/expressServer.test.js +0 -1249
- package/dist/githubAuth.test.d.ts +0 -1
- package/dist/githubAuth.test.js +0 -1142
- package/dist/httpClient.test.d.ts +0 -1
- package/dist/httpClient.test.js +0 -1471
- package/dist/logger.test.d.ts +0 -1
- package/dist/logger.test.js +0 -685
- package/dist/middleware.test.d.ts +0 -1
- package/dist/middleware.test.js +0 -241
- package/dist/notifiers/googleChatNotifier.test.d.ts +0 -1
- package/dist/notifiers/googleChatNotifier.test.js +0 -298
- package/dist/notifiers/slackNotifier.test.d.ts +0 -1
- package/dist/notifiers/slackNotifier.test.js +0 -297
- package/dist/notifiers/zoomNotifier.test.d.ts +0 -1
- package/dist/notifiers/zoomNotifier.test.js +0 -373
- package/dist/openApi.test.d.ts +0 -1
- package/dist/openApi.test.js +0 -620
- package/dist/openApiBuilder.test.d.ts +0 -1
- package/dist/openApiBuilder.test.js +0 -601
- package/dist/openApiEtag.test.d.ts +0 -1
- package/dist/openApiEtag.test.js +0 -86
- package/dist/openApiValidator.test.d.ts +0 -1
- package/dist/openApiValidator.test.js +0 -761
- package/dist/permissions.middleware.test.d.ts +0 -1
- package/dist/permissions.middleware.test.js +0 -308
- package/dist/permissions.test.d.ts +0 -1
- package/dist/permissions.test.js +0 -439
- package/dist/plugins.test.d.ts +0 -1
- package/dist/plugins.test.js +0 -890
- package/dist/populate.test.d.ts +0 -1
- package/dist/populate.test.js +0 -373
- package/dist/realtime/realtime.test.d.ts +0 -10
- package/dist/realtime/realtime.test.js +0 -3982
- package/dist/requestContext.test.d.ts +0 -1
- package/dist/requestContext.test.js +0 -412
- package/dist/scriptRunner.test.d.ts +0 -1
- package/dist/scriptRunner.test.js +0 -386
- package/dist/secretProviders.test.d.ts +0 -1
- package/dist/secretProviders.test.js +0 -726
- package/dist/syncConsents.test.d.ts +0 -1
- package/dist/syncConsents.test.js +0 -522
- package/dist/terrenoApp.test.d.ts +0 -1
- package/dist/terrenoApp.test.js +0 -489
- package/dist/tests/bunSetup.d.ts +0 -1
- package/dist/tests/fixtures/compileAuthEntry.d.ts +0 -1
- package/dist/tests/fixtures/compileAuthEntry.js +0 -37
- package/dist/tests/testEnv.d.ts +0 -0
- package/dist/tests/testEnv.js +0 -6
- package/dist/transformers.test.d.ts +0 -1
- package/dist/transformers.test.js +0 -423
- package/dist/utils.test.d.ts +0 -1
- package/dist/utils.test.js +0 -242
- /package/dist/{__tests__/openApiCompat.test.d.ts → sync/loadHarness.d.ts} +0 -0
|
@@ -0,0 +1,850 @@
|
|
|
1
|
+
// noExplicitAny: the mutation handler operates generically across registered models
|
|
2
|
+
// biome-ignore-all lint/suspicious/noExplicitAny: the mutation handler operates generically across registered models
|
|
3
|
+
import type express from "express";
|
|
4
|
+
import {DateTime} from "luxon";
|
|
5
|
+
import mongoose from "mongoose";
|
|
6
|
+
import type {User} from "../auth";
|
|
7
|
+
import {APIError, isAPIError} from "../errors";
|
|
8
|
+
import {createFeatureFlaggedLogger, logger} from "../logger";
|
|
9
|
+
import {findOneOrNoneFor} from "../plugins";
|
|
10
|
+
import {
|
|
11
|
+
executeCreate,
|
|
12
|
+
executeDelete,
|
|
13
|
+
executeUpdate,
|
|
14
|
+
isExecutorConflictError,
|
|
15
|
+
runPostCreate,
|
|
16
|
+
runPostDelete,
|
|
17
|
+
runPostUpdate,
|
|
18
|
+
} from "./executors";
|
|
19
|
+
import {SYNC_MUTATION_LEASE_MS, SyncMutation, type SyncMutationDocument} from "./models";
|
|
20
|
+
import {findSyncEntryByCollectionTag, type SyncRegistryEntry} from "./registry";
|
|
21
|
+
import {serializeSyncDoc} from "./routes";
|
|
22
|
+
import {getScopeField} from "./streams";
|
|
23
|
+
import type {
|
|
24
|
+
SyncAck,
|
|
25
|
+
SyncMutateBatchResponse,
|
|
26
|
+
SyncMutateRequest,
|
|
27
|
+
SyncNack,
|
|
28
|
+
SyncNackCode,
|
|
29
|
+
} from "./types";
|
|
30
|
+
|
|
31
|
+
export type SyncMutationScopeResolver = (
|
|
32
|
+
user: User,
|
|
33
|
+
entry: SyncRegistryEntry
|
|
34
|
+
) => Promise<string[]> | string[];
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Per-mutation success traces (`Mutation applied`) are high-volume. Gate them behind
|
|
38
|
+
* `SYNC_DEBUG=true` so they stay silent by default even when Winston's console level is
|
|
39
|
+
* `debug`.
|
|
40
|
+
*/
|
|
41
|
+
const syncDebugLog = createFeatureFlaggedLogger({
|
|
42
|
+
isEnabled: () => process.env.SYNC_DEBUG === "true",
|
|
43
|
+
});
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* C6 (M6): enforce write scope at the sync boundary regardless of consumer `preCreate`
|
|
47
|
+
* quality. For `owner` strategy, force/verify the owner field equals the authenticated
|
|
48
|
+
* user id; for `tenant` strategy, verify the incoming tenant value is in the user's
|
|
49
|
+
* memberships. Throws a 403 APIError (mapped to `unauthorized`) otherwise. A no-op for
|
|
50
|
+
* broadcast/custom scopes and for update data that does not touch the scope field.
|
|
51
|
+
*/
|
|
52
|
+
const enforceWriteScope = async ({
|
|
53
|
+
entry,
|
|
54
|
+
user,
|
|
55
|
+
operation,
|
|
56
|
+
data,
|
|
57
|
+
scopeResolver,
|
|
58
|
+
}: {
|
|
59
|
+
entry: SyncRegistryEntry;
|
|
60
|
+
user: User;
|
|
61
|
+
operation: "create" | "update" | "delete";
|
|
62
|
+
data: Record<string, unknown> | undefined;
|
|
63
|
+
scopeResolver?: SyncMutationScopeResolver;
|
|
64
|
+
}): Promise<void> => {
|
|
65
|
+
if (operation === "delete") {
|
|
66
|
+
return;
|
|
67
|
+
}
|
|
68
|
+
const {scope} = entry.config;
|
|
69
|
+
if (typeof scope === "function" || scope.type === "broadcast") {
|
|
70
|
+
return;
|
|
71
|
+
}
|
|
72
|
+
const field = getScopeField(scope) as string;
|
|
73
|
+
const incoming = data?.[field];
|
|
74
|
+
if (scope.type === "owner") {
|
|
75
|
+
// Create must belong to the caller; an update may not move ownership to someone else.
|
|
76
|
+
if (operation === "create" && (incoming === undefined || incoming === null)) {
|
|
77
|
+
// preCreate typically injects ownerId; nothing to verify if absent here.
|
|
78
|
+
return;
|
|
79
|
+
}
|
|
80
|
+
if (incoming !== undefined && incoming !== null && String(incoming) !== String(user.id)) {
|
|
81
|
+
throw new APIError({
|
|
82
|
+
status: 403,
|
|
83
|
+
title: `Write scope violation on ${entry.collectionTag}: ${field} must be the caller`,
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
return;
|
|
87
|
+
}
|
|
88
|
+
// Tenant: the incoming value (create) or the changed value (update) must be a membership.
|
|
89
|
+
if (incoming === undefined || incoming === null) {
|
|
90
|
+
// Nothing to check against memberships yet. A create may legitimately omit the tenant
|
|
91
|
+
// field for `preCreate` to inject from the authenticated user (see the example
|
|
92
|
+
// projects router), and an update that does not touch the scope field leaves it
|
|
93
|
+
// alone. Task 9.21's "never file a document under `tenant:undefined`" guarantee is
|
|
94
|
+
// enforced by resolveStreamForDoc on the write path instead, which sees the value
|
|
95
|
+
// AFTER preCreate has run — inferring intent from the mere presence of a preCreate
|
|
96
|
+
// hook would let an unrelated one (logging, timestamps) silently reopen that hole.
|
|
97
|
+
return;
|
|
98
|
+
}
|
|
99
|
+
if (!scopeResolver) {
|
|
100
|
+
throw new APIError({
|
|
101
|
+
status: 500,
|
|
102
|
+
title: `Sync collection ${entry.collectionTag} is tenant-scoped but SyncApp has no getUserScopes resolver`,
|
|
103
|
+
});
|
|
104
|
+
}
|
|
105
|
+
const memberships = await scopeResolver(user, entry);
|
|
106
|
+
if (!memberships.map(String).includes(String(incoming))) {
|
|
107
|
+
throw new APIError({
|
|
108
|
+
status: 403,
|
|
109
|
+
title: `Write scope violation on ${entry.collectionTag}: ${field} ${String(incoming)} is not a membership`,
|
|
110
|
+
});
|
|
111
|
+
}
|
|
112
|
+
};
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* Shared mutation handler for the sync channel: `POST /sync/mutate` (HTTP fallback)
|
|
116
|
+
* and `sync:mutate` (socket) both delegate here.
|
|
117
|
+
*
|
|
118
|
+
* Idempotency (atomic claim): the handler inserts a SyncMutation ledger row with status
|
|
119
|
+
* `pending` (unique index on mutationId) *before* applying. A duplicate-key error means
|
|
120
|
+
* another delivery owns or already completed the mutation, so the handler polls the
|
|
121
|
+
* existing row and returns the recorded outcome instead of re-applying — closing the
|
|
122
|
+
* race where a socket retry and the HTTP fallback deliver the same mutation concurrently.
|
|
123
|
+
*
|
|
124
|
+
* Conflict rule: the client's `baseVersion` (the `_syncSeq` it last saw) is passed to
|
|
125
|
+
* executeUpdate as a seq concurrency check; a mismatch yields a `conflict` nack carrying
|
|
126
|
+
* the canonical serialized server document and its current seq.
|
|
127
|
+
*
|
|
128
|
+
* C5 crash resilience (FIX 6):
|
|
129
|
+
* - **Lease/takeover (M4).** A `pending` row carries `claimedAt`. If a server crashes
|
|
130
|
+
* between claiming the row and finalizing it, the mutationId would otherwise be wedged
|
|
131
|
+
* for the full 30-day TTL. A duplicate-claim attempt older than
|
|
132
|
+
* {@link SYNC_MUTATION_LEASE_MS} may take over via an atomic
|
|
133
|
+
* `findOneAndUpdate({_id, status: "pending", claimedAt: {$lt: cutoff}}, {$set: {claimedAt: now}})`
|
|
134
|
+
* and re-run the mutation as the new claimant. Because the original attempt may have
|
|
135
|
+
* already landed the write before crashing, the executor path tolerates that: a create
|
|
136
|
+
* that hits E11000 on the SAME `_id` reads the doc back and reports it as the ack instead
|
|
137
|
+
* of nacking; an update/delete whose current server seq already reflects this mutation's
|
|
138
|
+
* expected post-write seq (`baseVersion + 1`) is treated as already-applied and reported
|
|
139
|
+
* from the current doc rather than re-executed (which would otherwise spuriously conflict
|
|
140
|
+
* against the write it is itself retrying).
|
|
141
|
+
* - **Finalize-before-post-hooks (M5).** The pipeline is: document write → finalize the
|
|
142
|
+
* ledger `applied` (with the ack payload) → THEN run the model's post-hook
|
|
143
|
+
* (`postCreate`/`postUpdate`/`postDelete`). A post-hook throw is `logger.error`'d and
|
|
144
|
+
* reported back as an ack with a `warning` field — never converted into a nack, since the
|
|
145
|
+
* write (and its delta) already committed and rolling the client back would be a lie. If
|
|
146
|
+
* the `applied` finalize itself throws, the request is allowed to fail loudly (500); the
|
|
147
|
+
* client's transport retry lands on the lease-takeover path above, which resolves it from
|
|
148
|
+
* the ledger/doc state rather than double-applying.
|
|
149
|
+
*/
|
|
150
|
+
|
|
151
|
+
/** Outcome of applying a sync mutation: an ack for the client, or a typed nack. */
|
|
152
|
+
export type SyncMutationOutcome = {type: "ack"; ack: SyncAck} | {type: "nack"; nack: SyncNack};
|
|
153
|
+
|
|
154
|
+
const PENDING_POLL_ATTEMPTS = 10;
|
|
155
|
+
const PENDING_POLL_INTERVAL_MS = 100;
|
|
156
|
+
const VALID_OPERATIONS = new Set(["create", "update", "delete"]);
|
|
157
|
+
|
|
158
|
+
/** Maximum mutations accepted in a single `sync:mutateBatch` / `POST /sync/mutate/batch` request. */
|
|
159
|
+
export const MAX_SYNC_MUTATIONS_PER_BATCH = 100;
|
|
160
|
+
|
|
161
|
+
const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
|
|
162
|
+
|
|
163
|
+
const makeNack = (nack: SyncNack): SyncMutationOutcome => {
|
|
164
|
+
logger.info("[sync] Mutation nacked", {code: nack.code, mutationId: nack.mutationId});
|
|
165
|
+
return {nack, type: "nack"};
|
|
166
|
+
};
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* Load a document by id INCLUDING tombstones (`isDeletedPlugin` would otherwise filter a
|
|
170
|
+
* soft-deleted doc out) and serialize it for a sync payload. Returns undefined when the
|
|
171
|
+
* document is gone, the id does not cast, or the consumer's serializer throws — callers
|
|
172
|
+
* treat a missing `serverDoc` as "seq only", which is what the client needs to re-base.
|
|
173
|
+
*/
|
|
174
|
+
const serializeLiveDoc = async ({
|
|
175
|
+
entry,
|
|
176
|
+
id,
|
|
177
|
+
request,
|
|
178
|
+
}: {
|
|
179
|
+
entry: SyncRegistryEntry;
|
|
180
|
+
id: string | undefined;
|
|
181
|
+
request: express.Request;
|
|
182
|
+
}): Promise<unknown> => {
|
|
183
|
+
if (!id) {
|
|
184
|
+
return undefined;
|
|
185
|
+
}
|
|
186
|
+
try {
|
|
187
|
+
const model = mongoose.model(entry.modelName);
|
|
188
|
+
const found = await model.find({_id: id, deleted: {$in: [true, false]}}).limit(1);
|
|
189
|
+
const doc = found[0] as mongoose.Document | undefined;
|
|
190
|
+
if (!doc) {
|
|
191
|
+
return undefined;
|
|
192
|
+
}
|
|
193
|
+
return await serializeSyncDoc({doc, entry, req: request});
|
|
194
|
+
} catch (error: unknown) {
|
|
195
|
+
logger.warn("[sync] Failed to serialize the server doc for a recorded conflict", {
|
|
196
|
+
collection: entry.collectionTag,
|
|
197
|
+
error: String(error),
|
|
198
|
+
id,
|
|
199
|
+
});
|
|
200
|
+
return undefined;
|
|
201
|
+
}
|
|
202
|
+
};
|
|
203
|
+
|
|
204
|
+
/**
|
|
205
|
+
* Reconstruct the outcome recorded on a finalized ledger row; undefined while pending.
|
|
206
|
+
*
|
|
207
|
+
* Task 9.21: the row stores no document data, so a recorded `conflicted` outcome
|
|
208
|
+
* re-serializes the LIVE document from `resultId`. Besides keeping PHI out of
|
|
209
|
+
* `syncmutations` for the ledger's 30-day TTL, this hands the client current server
|
|
210
|
+
* state rather than a snapshot frozen at first-conflict time.
|
|
211
|
+
*/
|
|
212
|
+
const outcomeFromLedgerRow = async ({
|
|
213
|
+
entry,
|
|
214
|
+
request,
|
|
215
|
+
row,
|
|
216
|
+
}: {
|
|
217
|
+
entry: SyncRegistryEntry;
|
|
218
|
+
request: express.Request;
|
|
219
|
+
row: SyncMutationDocument;
|
|
220
|
+
}): Promise<SyncMutationOutcome | undefined> => {
|
|
221
|
+
if (row.status === "applied") {
|
|
222
|
+
return {
|
|
223
|
+
ack: {id: row.resultId ?? "", mutationId: row.mutationId, seq: row.resultSeq ?? 0},
|
|
224
|
+
type: "ack",
|
|
225
|
+
};
|
|
226
|
+
}
|
|
227
|
+
if (row.status === "conflicted") {
|
|
228
|
+
return makeNack({
|
|
229
|
+
code: "conflict",
|
|
230
|
+
message: row.error,
|
|
231
|
+
mutationId: row.mutationId,
|
|
232
|
+
serverDoc: await serializeLiveDoc({entry, id: row.resultId, request}),
|
|
233
|
+
serverSeq: row.resultSeq,
|
|
234
|
+
});
|
|
235
|
+
}
|
|
236
|
+
if (row.status === "failed") {
|
|
237
|
+
return makeNack({
|
|
238
|
+
code: (row.nackCode as SyncNackCode) ?? "error",
|
|
239
|
+
message: row.error,
|
|
240
|
+
mutationId: row.mutationId,
|
|
241
|
+
});
|
|
242
|
+
}
|
|
243
|
+
return undefined;
|
|
244
|
+
};
|
|
245
|
+
|
|
246
|
+
/**
|
|
247
|
+
* C5 (FIX 6) lease takeover: a `pending` row older than {@link SYNC_MUTATION_LEASE_MS}
|
|
248
|
+
* is assumed abandoned (the original claimant crashed between claiming the row and
|
|
249
|
+
* finalizing it) — atomically re-claim it via `findOneAndUpdate` so exactly one
|
|
250
|
+
* concurrent delivery wins the takeover. Returns the re-claimed row (with a bumped
|
|
251
|
+
* `claimedAt`) on success, or `undefined` if the row is not stale/pending (someone else
|
|
252
|
+
* is actively working it, or it already finalized).
|
|
253
|
+
*/
|
|
254
|
+
const takeoverStaleLease = async (
|
|
255
|
+
mutationId: string
|
|
256
|
+
): Promise<SyncMutationDocument | undefined> => {
|
|
257
|
+
const cutoff = DateTime.now().minus({milliseconds: SYNC_MUTATION_LEASE_MS}).toJSDate();
|
|
258
|
+
const claimed = await SyncMutation.findOneAndUpdate(
|
|
259
|
+
{claimedAt: {$lt: cutoff}, mutationId, status: "pending"},
|
|
260
|
+
{$set: {claimedAt: new Date()}},
|
|
261
|
+
{new: true}
|
|
262
|
+
);
|
|
263
|
+
return claimed ?? undefined;
|
|
264
|
+
};
|
|
265
|
+
|
|
266
|
+
/**
|
|
267
|
+
* Another delivery claimed this mutationId: poll the ledger row until its status leaves
|
|
268
|
+
* `pending` and return the recorded outcome. Before each poll, attempt a lease takeover
|
|
269
|
+
* (C5/FIX 6) — a `pending` row older than {@link SYNC_MUTATION_LEASE_MS} is assumed
|
|
270
|
+
* abandoned by a crashed claimant, so this delivery re-claims and re-applies it instead
|
|
271
|
+
* of waiting out the full poll budget (or worse, the 30-day TTL). If the row stays
|
|
272
|
+
* pending and un-stale past the timeout, nack `error` without modifying the row — the
|
|
273
|
+
* owning delivery will still finalize it.
|
|
274
|
+
*/
|
|
275
|
+
const waitForRecordedOutcome = async ({
|
|
276
|
+
entry,
|
|
277
|
+
mutationId,
|
|
278
|
+
request,
|
|
279
|
+
user,
|
|
280
|
+
onTakeover,
|
|
281
|
+
}: {
|
|
282
|
+
entry: SyncRegistryEntry;
|
|
283
|
+
mutationId: string;
|
|
284
|
+
request: express.Request;
|
|
285
|
+
user: User;
|
|
286
|
+
/** Invoked with the re-claimed row when a stale lease is taken over. */
|
|
287
|
+
onTakeover: (row: SyncMutationDocument) => Promise<SyncMutationOutcome>;
|
|
288
|
+
}): Promise<SyncMutationOutcome> => {
|
|
289
|
+
for (let attempt = 0; attempt < PENDING_POLL_ATTEMPTS; attempt++) {
|
|
290
|
+
const row = await findOneOrNoneFor(SyncMutation, {mutationId});
|
|
291
|
+
if (row) {
|
|
292
|
+
if (String(row.userId) !== String(user.id)) {
|
|
293
|
+
return makeNack({
|
|
294
|
+
code: "unauthorized",
|
|
295
|
+
message: `Mutation ${mutationId} was submitted by another user`,
|
|
296
|
+
mutationId,
|
|
297
|
+
});
|
|
298
|
+
}
|
|
299
|
+
const outcome = await outcomeFromLedgerRow({entry, request, row});
|
|
300
|
+
if (outcome) {
|
|
301
|
+
return outcome;
|
|
302
|
+
}
|
|
303
|
+
if (row.status === "pending") {
|
|
304
|
+
const takenOver = await takeoverStaleLease(mutationId);
|
|
305
|
+
if (takenOver) {
|
|
306
|
+
logger.warn("[sync] Took over a stale mutation lease", {
|
|
307
|
+
mutationId,
|
|
308
|
+
staleForMs: Date.now() - new Date(row.claimedAt).getTime(),
|
|
309
|
+
});
|
|
310
|
+
return onTakeover(takenOver);
|
|
311
|
+
}
|
|
312
|
+
}
|
|
313
|
+
}
|
|
314
|
+
await sleep(PENDING_POLL_INTERVAL_MS);
|
|
315
|
+
}
|
|
316
|
+
return makeNack({
|
|
317
|
+
code: "error",
|
|
318
|
+
message: `Mutation ${mutationId} is still in flight`,
|
|
319
|
+
mutationId,
|
|
320
|
+
});
|
|
321
|
+
};
|
|
322
|
+
|
|
323
|
+
/**
|
|
324
|
+
* C5 (FIX 6): true when `error` is (or wraps, via `APIError.error` — see
|
|
325
|
+
* `executeCreate`'s `model.create()` catch, which wraps the raw Mongo driver
|
|
326
|
+
* error in an APIError before it ever reaches the caller) a MongoDB E11000
|
|
327
|
+
* duplicate-key error.
|
|
328
|
+
*/
|
|
329
|
+
const isE11000Error = (error: unknown): boolean => {
|
|
330
|
+
const candidate = error as {code?: number; error?: unknown};
|
|
331
|
+
if (candidate?.code === 11000) {
|
|
332
|
+
return true;
|
|
333
|
+
}
|
|
334
|
+
const wrapped = candidate?.error as {code?: number} | undefined;
|
|
335
|
+
return wrapped?.code === 11000;
|
|
336
|
+
};
|
|
337
|
+
|
|
338
|
+
/**
|
|
339
|
+
* C5 (FIX 6): true when every key/value in `data` (the mutation's own
|
|
340
|
+
* intended write) is already present on `doc` — used alongside the
|
|
341
|
+
* expected-post-write-seq check to distinguish "this mutation's own write
|
|
342
|
+
* already landed" (safe to report as already-applied) from "a genuinely
|
|
343
|
+
* different write landed and happens to have advanced the seq by exactly
|
|
344
|
+
* one" (a real conflict; a seq match alone cannot tell these apart).
|
|
345
|
+
*/
|
|
346
|
+
const docMatchesMutationData = (
|
|
347
|
+
doc: unknown,
|
|
348
|
+
data: Record<string, unknown> | undefined
|
|
349
|
+
): boolean => {
|
|
350
|
+
if (!data) {
|
|
351
|
+
return true;
|
|
352
|
+
}
|
|
353
|
+
const asDocument = doc as {toObject?: () => Record<string, unknown>} | undefined;
|
|
354
|
+
const plain =
|
|
355
|
+
typeof asDocument?.toObject === "function"
|
|
356
|
+
? asDocument.toObject()
|
|
357
|
+
: (doc as Record<string, unknown>);
|
|
358
|
+
return Object.entries(data).every(([key, value]) => {
|
|
359
|
+
const current = plain?.[key];
|
|
360
|
+
if (current instanceof Date && typeof value === "string") {
|
|
361
|
+
return current.toISOString() === new Date(value).toISOString();
|
|
362
|
+
}
|
|
363
|
+
return JSON.stringify(current) === JSON.stringify(value);
|
|
364
|
+
});
|
|
365
|
+
};
|
|
366
|
+
|
|
367
|
+
const nackCodeForError = (error: unknown): SyncNackCode => {
|
|
368
|
+
if (!isAPIError(error)) {
|
|
369
|
+
return "error";
|
|
370
|
+
}
|
|
371
|
+
if (error.status === 403 || error.status === 405) {
|
|
372
|
+
return "unauthorized";
|
|
373
|
+
}
|
|
374
|
+
if (error.status === 400 || error.status === 404 || error.status === 422) {
|
|
375
|
+
return "validation";
|
|
376
|
+
}
|
|
377
|
+
return "error";
|
|
378
|
+
};
|
|
379
|
+
|
|
380
|
+
/** Record a failed/conflicted outcome on the claimed ledger row and build the nack. */
|
|
381
|
+
const finalizeNack = async ({
|
|
382
|
+
claimedId,
|
|
383
|
+
entry,
|
|
384
|
+
error,
|
|
385
|
+
mutation,
|
|
386
|
+
request,
|
|
387
|
+
}: {
|
|
388
|
+
claimedId: mongoose.Types.ObjectId;
|
|
389
|
+
entry: SyncRegistryEntry;
|
|
390
|
+
error: unknown;
|
|
391
|
+
mutation: SyncMutateRequest;
|
|
392
|
+
request: express.Request;
|
|
393
|
+
}): Promise<SyncMutationOutcome> => {
|
|
394
|
+
// Duck-typed: `instanceof` breaks for Error subclasses in the compiled ES5 dist.
|
|
395
|
+
if (isExecutorConflictError(error)) {
|
|
396
|
+
let serverDoc: unknown;
|
|
397
|
+
try {
|
|
398
|
+
serverDoc = await serializeSyncDoc({
|
|
399
|
+
doc: error.doc as mongoose.Document,
|
|
400
|
+
entry,
|
|
401
|
+
req: request,
|
|
402
|
+
});
|
|
403
|
+
} catch (serializeError: unknown) {
|
|
404
|
+
logger.warn("[sync] Failed to serialize conflict server doc", {
|
|
405
|
+
error: String(serializeError),
|
|
406
|
+
mutationId: mutation.mutationId,
|
|
407
|
+
});
|
|
408
|
+
}
|
|
409
|
+
// Task 9.21: record only the pointer ({resultId, resultSeq}), never `serverDoc` —
|
|
410
|
+
// a duplicate delivery re-serializes the live document from `resultId`.
|
|
411
|
+
const resultId =
|
|
412
|
+
(error.doc as {_id?: unknown} | undefined)?._id !== undefined
|
|
413
|
+
? String((error.doc as {_id: unknown})._id)
|
|
414
|
+
: mutation.id;
|
|
415
|
+
await SyncMutation.updateOne(
|
|
416
|
+
{_id: claimedId},
|
|
417
|
+
{
|
|
418
|
+
$set: {
|
|
419
|
+
error: error.title,
|
|
420
|
+
nackCode: "conflict",
|
|
421
|
+
resultId,
|
|
422
|
+
resultSeq: error.serverSeq,
|
|
423
|
+
status: "conflicted",
|
|
424
|
+
},
|
|
425
|
+
}
|
|
426
|
+
);
|
|
427
|
+
return makeNack({
|
|
428
|
+
code: "conflict",
|
|
429
|
+
message: error.title,
|
|
430
|
+
mutationId: mutation.mutationId,
|
|
431
|
+
serverDoc,
|
|
432
|
+
serverSeq: error.serverSeq,
|
|
433
|
+
});
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
const code = nackCodeForError(error);
|
|
437
|
+
const message = isAPIError(error) ? error.title : String(error);
|
|
438
|
+
if (code === "error") {
|
|
439
|
+
logger.warn("[sync] Mutation failed unexpectedly", {
|
|
440
|
+
collection: mutation.collection,
|
|
441
|
+
error: message,
|
|
442
|
+
mutationId: mutation.mutationId,
|
|
443
|
+
});
|
|
444
|
+
// Task 9.18: an `error`-class failure is non-deterministic (DB hiccup, replica
|
|
445
|
+
// step-down) — it is not a verdict on the mutation. Recording it `failed` would make
|
|
446
|
+
// it sticky for the ledger's 30-day TTL, so every replay of the same mutationId reads
|
|
447
|
+
// the nack back and the client's durable outbox retries forever without the mutation
|
|
448
|
+
// ever re-executing. Release the claim instead: the next delivery re-claims the
|
|
449
|
+
// mutationId and genuinely re-runs the write. Deterministic outcomes
|
|
450
|
+
// (validation/unauthorized/conflict) stay recorded — replaying those must not re-run.
|
|
451
|
+
await SyncMutation.deleteOne({_id: claimedId});
|
|
452
|
+
return makeNack({code, message, mutationId: mutation.mutationId});
|
|
453
|
+
}
|
|
454
|
+
await SyncMutation.updateOne(
|
|
455
|
+
{_id: claimedId},
|
|
456
|
+
{$set: {error: message, nackCode: code, status: "failed"}}
|
|
457
|
+
);
|
|
458
|
+
return makeNack({code, message, mutationId: mutation.mutationId});
|
|
459
|
+
};
|
|
460
|
+
|
|
461
|
+
/**
|
|
462
|
+
* C5 (FIX 6): read the doc back and report it as the ack for an ALREADY-APPLIED write —
|
|
463
|
+
* used both by the create-E11000 tolerance and the update/delete already-applied check.
|
|
464
|
+
* Finalizes the ledger `applied` from the doc's actual state (not assumed) before
|
|
465
|
+
* returning, exactly like the normal apply path, so a subsequent duplicate delivery
|
|
466
|
+
* reads back the same outcome.
|
|
467
|
+
*/
|
|
468
|
+
const finalizeAlreadyApplied = async ({
|
|
469
|
+
claimedId,
|
|
470
|
+
doc,
|
|
471
|
+
mutation,
|
|
472
|
+
}: {
|
|
473
|
+
claimedId: mongoose.Types.ObjectId;
|
|
474
|
+
doc: mongoose.Document;
|
|
475
|
+
mutation: SyncMutateRequest;
|
|
476
|
+
}): Promise<{resultId: string; resultSeq: number}> => {
|
|
477
|
+
const resultId = String(doc._id);
|
|
478
|
+
const resultSeq = (doc as unknown as {_syncSeq?: number})._syncSeq ?? 0;
|
|
479
|
+
await SyncMutation.updateOne({_id: claimedId}, {$set: {resultId, resultSeq, status: "applied"}});
|
|
480
|
+
logger.info("[sync] Mutation already applied (lease-takeover tolerance)", {
|
|
481
|
+
collection: mutation.collection,
|
|
482
|
+
mutationId: mutation.mutationId,
|
|
483
|
+
seq: resultSeq,
|
|
484
|
+
});
|
|
485
|
+
return {resultId, resultSeq};
|
|
486
|
+
};
|
|
487
|
+
|
|
488
|
+
/**
|
|
489
|
+
* Apply a client mutation through the transport-agnostic executors (permissions,
|
|
490
|
+
* pre/post hooks, validation) against an ALREADY-CLAIMED ledger row (either a fresh claim
|
|
491
|
+
* or a lease takeover of an abandoned one — C5/FIX 6). Always finalizes the claimed row
|
|
492
|
+
* before returning so duplicate deliveries can read the outcome back.
|
|
493
|
+
*
|
|
494
|
+
* Reorder (M5): the document write finalizes the ledger `applied` BEFORE the model's
|
|
495
|
+
* post-hook runs. A post-hook throw is logged and reported as a `warning` on the ack —
|
|
496
|
+
* never converted into a nack, since the write already committed.
|
|
497
|
+
*
|
|
498
|
+
* Already-applied tolerance (M4, `isLeaseTakeover` only — a normal first attempt reports
|
|
499
|
+
* genuine conflicts/errors as usual): a lease takeover re-runs a mutation whose FIRST
|
|
500
|
+
* attempt may have already landed the write before crashing.
|
|
501
|
+
* - create: an E11000 on the same target `_id` is treated as success — the doc is read
|
|
502
|
+
* back and reported as the ack (a genuine `_id` collision from a DIFFERENT mutation is
|
|
503
|
+
* not expected for client-minted ids and is out of scope here).
|
|
504
|
+
* - update: re-checked reactively — if the executor's seq concurrency check throws a
|
|
505
|
+
* conflict whose `serverSeq` is EXACTLY `baseVersion + 1` (what this mutation's own
|
|
506
|
+
* write would have produced) while retrying via a lease takeover, that is treated as
|
|
507
|
+
* "this exact write already landed" rather than a genuine external conflict, and the
|
|
508
|
+
* current doc is reported as the ack instead of nacking.
|
|
509
|
+
* - delete: idempotent already (executeDelete on an already-deleted tombstone is a no-op
|
|
510
|
+
* success in this codebase's soft-delete model), so no special tolerance is needed.
|
|
511
|
+
*/
|
|
512
|
+
const applyClaimedMutation = async ({
|
|
513
|
+
claimed,
|
|
514
|
+
entry,
|
|
515
|
+
mutation,
|
|
516
|
+
request,
|
|
517
|
+
user,
|
|
518
|
+
scopeResolver,
|
|
519
|
+
isLeaseTakeover = false,
|
|
520
|
+
}: {
|
|
521
|
+
claimed: SyncMutationDocument;
|
|
522
|
+
entry: SyncRegistryEntry;
|
|
523
|
+
mutation: SyncMutateRequest;
|
|
524
|
+
request: express.Request;
|
|
525
|
+
user: User;
|
|
526
|
+
scopeResolver?: SyncMutationScopeResolver;
|
|
527
|
+
/** True when `claimed` was re-claimed from a stale lease rather than freshly inserted. */
|
|
528
|
+
isLeaseTakeover?: boolean;
|
|
529
|
+
}): Promise<SyncMutationOutcome> => {
|
|
530
|
+
const mutationId = mutation.mutationId;
|
|
531
|
+
|
|
532
|
+
try {
|
|
533
|
+
// Task 9.18: resolving the model must be INSIDE the try — a MissingSchemaError thrown
|
|
534
|
+
// here would escape without finalizing the claimed row, wedging the mutationId
|
|
535
|
+
// `pending` for the whole lease window instead of nacking it.
|
|
536
|
+
const model = mongoose.model(entry.modelName);
|
|
537
|
+
// C6 (M6): sync-boundary write-scope backstop before any write pipeline runs.
|
|
538
|
+
await enforceWriteScope({
|
|
539
|
+
data: mutation.data,
|
|
540
|
+
entry,
|
|
541
|
+
operation: mutation.operation,
|
|
542
|
+
scopeResolver,
|
|
543
|
+
user,
|
|
544
|
+
});
|
|
545
|
+
|
|
546
|
+
let doc: mongoose.Document;
|
|
547
|
+
let postHook: (() => Promise<void>) | undefined;
|
|
548
|
+
if (mutation.operation === "create") {
|
|
549
|
+
const body: Record<string, unknown> = {...(mutation.data ?? {})};
|
|
550
|
+
if (mutation.id) {
|
|
551
|
+
body._id = mutation.id;
|
|
552
|
+
}
|
|
553
|
+
try {
|
|
554
|
+
const result = await executeCreate({
|
|
555
|
+
body,
|
|
556
|
+
model,
|
|
557
|
+
options: entry.options,
|
|
558
|
+
req: request,
|
|
559
|
+
skipPostHooks: true,
|
|
560
|
+
user,
|
|
561
|
+
});
|
|
562
|
+
doc = result.doc;
|
|
563
|
+
postHook = (): Promise<void> =>
|
|
564
|
+
runPostCreate({doc: result.doc, options: entry.options, request});
|
|
565
|
+
} catch (createError: unknown) {
|
|
566
|
+
// M4 (lease takeover only): an E11000 on the exact target _id is
|
|
567
|
+
// tolerated as "already applied" — a prior (crashed) attempt at
|
|
568
|
+
// THIS mutation landed the write before finalizing the ledger. A
|
|
569
|
+
// normal (non-takeover) first attempt reports the error as usual —
|
|
570
|
+
// client-minted UUIDs make a genuine unrelated _id collision
|
|
571
|
+
// vanishingly unlikely, so gating this on isLeaseTakeover keeps the
|
|
572
|
+
// tolerance scoped to its actual crash-recovery purpose.
|
|
573
|
+
if (isLeaseTakeover && isE11000Error(createError) && typeof mutation.id === "string") {
|
|
574
|
+
const existing = await findOneOrNoneFor(model, {_id: mutation.id});
|
|
575
|
+
if (existing) {
|
|
576
|
+
const {resultId, resultSeq} = await finalizeAlreadyApplied({
|
|
577
|
+
claimedId: claimed._id,
|
|
578
|
+
doc: existing as unknown as mongoose.Document,
|
|
579
|
+
mutation,
|
|
580
|
+
});
|
|
581
|
+
return {ack: {id: resultId, mutationId, seq: resultSeq}, type: "ack"};
|
|
582
|
+
}
|
|
583
|
+
}
|
|
584
|
+
throw createError;
|
|
585
|
+
}
|
|
586
|
+
} else if (mutation.operation === "update") {
|
|
587
|
+
try {
|
|
588
|
+
const result = await executeUpdate({
|
|
589
|
+
body: mutation.data ?? {},
|
|
590
|
+
concurrencyCheck: {baseSeq: mutation.baseVersion ?? 0, type: "seq"},
|
|
591
|
+
id: mutation.id as string,
|
|
592
|
+
model,
|
|
593
|
+
options: entry.options,
|
|
594
|
+
req: request,
|
|
595
|
+
skipPostHooks: true,
|
|
596
|
+
user,
|
|
597
|
+
});
|
|
598
|
+
doc = result.doc;
|
|
599
|
+
// biome-ignore lint/style/noNonNullAssertion: executeUpdate with skipPostHooks always returns cleanedBody/prevDoc.
|
|
600
|
+
const cleanedBody = result.cleanedBody!;
|
|
601
|
+
// biome-ignore lint/style/noNonNullAssertion: executeUpdate with skipPostHooks always returns cleanedBody/prevDoc.
|
|
602
|
+
const prevDoc = result.prevDoc!;
|
|
603
|
+
postHook = (): Promise<void> =>
|
|
604
|
+
runPostUpdate({cleanedBody, doc: result.doc, options: entry.options, prevDoc, request});
|
|
605
|
+
} catch (updateError: unknown) {
|
|
606
|
+
// M4 (lease takeover only): a conflict whose serverSeq is EXACTLY
|
|
607
|
+
// this mutation's own expected post-write seq COULD mean the write
|
|
608
|
+
// this very mutation intended already landed on a prior (crashed)
|
|
609
|
+
// attempt — but a seq match alone is ambiguous (any other write
|
|
610
|
+
// landing between the claim and the retry would also bump the seq
|
|
611
|
+
// by exactly one). Additionally require the current doc's fields to
|
|
612
|
+
// already contain every value this mutation's own `data` would have
|
|
613
|
+
// written — only THEN is it safe to treat as already-applied and
|
|
614
|
+
// report success; otherwise it is a genuine external conflict and
|
|
615
|
+
// must nack as usual, exactly like a normal (non-takeover) apply.
|
|
616
|
+
if (
|
|
617
|
+
isLeaseTakeover &&
|
|
618
|
+
isExecutorConflictError(updateError) &&
|
|
619
|
+
updateError.conflictType === "seq" &&
|
|
620
|
+
updateError.serverSeq === (mutation.baseVersion ?? 0) + 1 &&
|
|
621
|
+
docMatchesMutationData(updateError.doc, mutation.data)
|
|
622
|
+
) {
|
|
623
|
+
const {resultId, resultSeq} = await finalizeAlreadyApplied({
|
|
624
|
+
claimedId: claimed._id,
|
|
625
|
+
doc: updateError.doc as mongoose.Document,
|
|
626
|
+
mutation,
|
|
627
|
+
});
|
|
628
|
+
return {ack: {id: resultId, mutationId, seq: resultSeq}, type: "ack"};
|
|
629
|
+
}
|
|
630
|
+
throw updateError;
|
|
631
|
+
}
|
|
632
|
+
} else {
|
|
633
|
+
const result = await executeDelete({
|
|
634
|
+
id: mutation.id as string,
|
|
635
|
+
model,
|
|
636
|
+
options: entry.options,
|
|
637
|
+
req: request,
|
|
638
|
+
skipPostHooks: true,
|
|
639
|
+
user,
|
|
640
|
+
});
|
|
641
|
+
doc = result.doc;
|
|
642
|
+
postHook = (): Promise<void> =>
|
|
643
|
+
runPostDelete({doc: result.doc, options: entry.options, request});
|
|
644
|
+
}
|
|
645
|
+
|
|
646
|
+
const resultId = String(doc._id);
|
|
647
|
+
const resultSeq = (doc as unknown as {_syncSeq?: number})._syncSeq ?? 0;
|
|
648
|
+
// M5: finalize the ledger BEFORE the post-hook runs — a post-hook throw
|
|
649
|
+
// must never make a committed write look like a failure.
|
|
650
|
+
await SyncMutation.updateOne(
|
|
651
|
+
{_id: claimed._id},
|
|
652
|
+
{$set: {resultId, resultSeq, status: "applied"}}
|
|
653
|
+
);
|
|
654
|
+
syncDebugLog.debug("[sync] Mutation applied", {
|
|
655
|
+
collection: mutation.collection,
|
|
656
|
+
mutationId,
|
|
657
|
+
seq: resultSeq,
|
|
658
|
+
});
|
|
659
|
+
|
|
660
|
+
let warning: string | undefined;
|
|
661
|
+
try {
|
|
662
|
+
await postHook();
|
|
663
|
+
} catch (postHookError: unknown) {
|
|
664
|
+
warning = errorMessageOf(postHookError);
|
|
665
|
+
logger.error("[sync] Post-hook failed after a committed mutation", {
|
|
666
|
+
collection: mutation.collection,
|
|
667
|
+
error: warning,
|
|
668
|
+
mutationId,
|
|
669
|
+
});
|
|
670
|
+
}
|
|
671
|
+
return {
|
|
672
|
+
ack: {id: resultId, mutationId, seq: resultSeq, ...(warning ? {warning} : {})},
|
|
673
|
+
type: "ack",
|
|
674
|
+
};
|
|
675
|
+
} catch (error: unknown) {
|
|
676
|
+
return finalizeNack({claimedId: claimed._id, entry, error, mutation, request});
|
|
677
|
+
}
|
|
678
|
+
};
|
|
679
|
+
|
|
680
|
+
const errorMessageOf = (error: unknown): string =>
|
|
681
|
+
isAPIError(error) ? error.title : error instanceof Error ? error.message : String(error);
|
|
682
|
+
|
|
683
|
+
/**
|
|
684
|
+
* Apply a client mutation through the transport-agnostic executors (permissions,
|
|
685
|
+
* pre/post hooks, validation) with an atomic idempotency claim. Always finalizes the
|
|
686
|
+
* claimed ledger row before returning so duplicate deliveries can read the outcome back.
|
|
687
|
+
*/
|
|
688
|
+
export const applySyncMutation = async ({
|
|
689
|
+
user,
|
|
690
|
+
mutation,
|
|
691
|
+
req,
|
|
692
|
+
scopeResolver,
|
|
693
|
+
}: {
|
|
694
|
+
user: User;
|
|
695
|
+
mutation: SyncMutateRequest;
|
|
696
|
+
/** The real Express request when called over HTTP; hooks receive a `{user}` stub otherwise. */
|
|
697
|
+
req?: express.Request;
|
|
698
|
+
scopeResolver?: SyncMutationScopeResolver;
|
|
699
|
+
}): Promise<SyncMutationOutcome> => {
|
|
700
|
+
const mutationId = typeof mutation?.mutationId === "string" ? mutation.mutationId : "";
|
|
701
|
+
const validationNack = (message: string): SyncMutationOutcome =>
|
|
702
|
+
makeNack({code: "validation", message, mutationId});
|
|
703
|
+
|
|
704
|
+
if (!mutationId) {
|
|
705
|
+
return validationNack("mutationId is required");
|
|
706
|
+
}
|
|
707
|
+
if (!mutation.collection || typeof mutation.collection !== "string") {
|
|
708
|
+
return validationNack("collection is required");
|
|
709
|
+
}
|
|
710
|
+
if (!VALID_OPERATIONS.has(mutation.operation)) {
|
|
711
|
+
return validationNack(`Unknown operation: ${String(mutation.operation)}`);
|
|
712
|
+
}
|
|
713
|
+
if ((mutation.operation === "update" || mutation.operation === "delete") && !mutation.id) {
|
|
714
|
+
return validationNack(`id is required for ${mutation.operation} mutations`);
|
|
715
|
+
}
|
|
716
|
+
// C8: an update MUST carry an explicit baseVersion — omitting it would silently become
|
|
717
|
+
// a `baseSeq: 0` check (an accidental conflict against every non-fresh doc, or an
|
|
718
|
+
// accidental success against a seq-0 doc). Reject it as a client bug up front.
|
|
719
|
+
if (mutation.operation === "update" && typeof mutation.baseVersion !== "number") {
|
|
720
|
+
return validationNack("baseVersion is required for update mutations");
|
|
721
|
+
}
|
|
722
|
+
|
|
723
|
+
const entry = findSyncEntryByCollectionTag(mutation.collection);
|
|
724
|
+
if (!entry) {
|
|
725
|
+
return validationNack(`Unknown sync collection: ${mutation.collection}`);
|
|
726
|
+
}
|
|
727
|
+
|
|
728
|
+
const request = req ?? ({user} as unknown as express.Request);
|
|
729
|
+
|
|
730
|
+
// Atomic claim: inserting the pending row first means exactly one delivery applies.
|
|
731
|
+
let claimed: SyncMutationDocument;
|
|
732
|
+
try {
|
|
733
|
+
claimed = await SyncMutation.create({
|
|
734
|
+
claimedAt: new Date(),
|
|
735
|
+
mutationId,
|
|
736
|
+
status: "pending",
|
|
737
|
+
userId: String(user.id),
|
|
738
|
+
});
|
|
739
|
+
} catch (error: unknown) {
|
|
740
|
+
if ((error as {code?: number}).code !== 11000) {
|
|
741
|
+
throw error;
|
|
742
|
+
}
|
|
743
|
+
return waitForRecordedOutcome({
|
|
744
|
+
entry,
|
|
745
|
+
mutationId,
|
|
746
|
+
onTakeover: (takenOver) =>
|
|
747
|
+
applyClaimedMutation({
|
|
748
|
+
claimed: takenOver,
|
|
749
|
+
entry,
|
|
750
|
+
isLeaseTakeover: true,
|
|
751
|
+
mutation,
|
|
752
|
+
request,
|
|
753
|
+
scopeResolver,
|
|
754
|
+
user,
|
|
755
|
+
}),
|
|
756
|
+
request,
|
|
757
|
+
user,
|
|
758
|
+
});
|
|
759
|
+
}
|
|
760
|
+
|
|
761
|
+
return applyClaimedMutation({claimed, entry, mutation, request, scopeResolver, user});
|
|
762
|
+
};
|
|
763
|
+
|
|
764
|
+
/** Outcome of a batch validation pre-check (before any mutation is attempted). */
|
|
765
|
+
export type SyncBatchValidationOutcome =
|
|
766
|
+
| {ok: true}
|
|
767
|
+
| {ok: false; response: SyncMutateBatchResponse};
|
|
768
|
+
|
|
769
|
+
/**
|
|
770
|
+
* Up-front validation shared by both batch transports (HTTP and socket): reject an
|
|
771
|
+
* oversized batch or one with intra-batch duplicate mutationIds before anything is
|
|
772
|
+
* applied. On failure, returns a single-element `results` array carrying a
|
|
773
|
+
* `validation` nack for the offending mutation (or an empty-batch guard) — mirroring
|
|
774
|
+
* the shape callers expect from `applySyncMutationBatch`, but produced without
|
|
775
|
+
* touching the idempotency ledger since nothing was attempted.
|
|
776
|
+
*/
|
|
777
|
+
export const validateSyncMutationBatch = (
|
|
778
|
+
mutations: SyncMutateRequest[]
|
|
779
|
+
): SyncBatchValidationOutcome => {
|
|
780
|
+
if (mutations.length > MAX_SYNC_MUTATIONS_PER_BATCH) {
|
|
781
|
+
return {
|
|
782
|
+
ok: false,
|
|
783
|
+
response: {
|
|
784
|
+
results: [
|
|
785
|
+
makeNack({
|
|
786
|
+
code: "validation",
|
|
787
|
+
message: `Batch of ${mutations.length} exceeds the maximum of ${MAX_SYNC_MUTATIONS_PER_BATCH} mutations`,
|
|
788
|
+
mutationId: "",
|
|
789
|
+
}) as {type: "nack"; nack: SyncNack},
|
|
790
|
+
],
|
|
791
|
+
},
|
|
792
|
+
};
|
|
793
|
+
}
|
|
794
|
+
const seen = new Set<string>();
|
|
795
|
+
for (const mutation of mutations) {
|
|
796
|
+
const mutationId = typeof mutation?.mutationId === "string" ? mutation.mutationId : "";
|
|
797
|
+
if (mutationId && seen.has(mutationId)) {
|
|
798
|
+
return {
|
|
799
|
+
ok: false,
|
|
800
|
+
response: {
|
|
801
|
+
results: [
|
|
802
|
+
makeNack({
|
|
803
|
+
code: "validation",
|
|
804
|
+
message: `Duplicate mutationId within batch: ${mutationId}`,
|
|
805
|
+
mutationId,
|
|
806
|
+
}) as {type: "nack"; nack: SyncNack},
|
|
807
|
+
],
|
|
808
|
+
},
|
|
809
|
+
};
|
|
810
|
+
}
|
|
811
|
+
seen.add(mutationId);
|
|
812
|
+
}
|
|
813
|
+
return {ok: true};
|
|
814
|
+
};
|
|
815
|
+
|
|
816
|
+
/**
|
|
817
|
+
* Apply a batch of mutations strictly serially, in array order, reusing
|
|
818
|
+
* `applySyncMutation` per item — full reuse of the idempotency ledger, executors,
|
|
819
|
+
* permissions, and delta emission. Stops immediately at the first non-ack outcome
|
|
820
|
+
* (the user's hard requirement, INV-1): mutations after it are neither attempted nor
|
|
821
|
+
* ledgered, and are safe for the client to resend later (INV-3).
|
|
822
|
+
*
|
|
823
|
+
* Callers MUST run {@link validateSyncMutationBatch} first (oversized/duplicate
|
|
824
|
+
* rejection happens before any mutation is attempted); this function assumes the
|
|
825
|
+
* batch already passed that check.
|
|
826
|
+
*/
|
|
827
|
+
export const applySyncMutationBatch = async ({
|
|
828
|
+
user,
|
|
829
|
+
mutations,
|
|
830
|
+
req,
|
|
831
|
+
scopeResolver,
|
|
832
|
+
}: {
|
|
833
|
+
user: User;
|
|
834
|
+
mutations: SyncMutateRequest[];
|
|
835
|
+
/** The real Express request when called over HTTP; hooks receive a `{user}` stub otherwise. */
|
|
836
|
+
req?: express.Request;
|
|
837
|
+
scopeResolver?: SyncMutationScopeResolver;
|
|
838
|
+
}): Promise<SyncMutateBatchResponse> => {
|
|
839
|
+
const results: SyncMutateBatchResponse["results"] = [];
|
|
840
|
+
for (const mutation of mutations) {
|
|
841
|
+
const outcome = await applySyncMutation({mutation, req, scopeResolver, user});
|
|
842
|
+
results.push(outcome);
|
|
843
|
+
if (outcome.type === "nack") {
|
|
844
|
+
// Stop-on-error: the client re-sends everything after this point, and
|
|
845
|
+
// INV-3's idempotency ledger makes that overlap safe.
|
|
846
|
+
break;
|
|
847
|
+
}
|
|
848
|
+
}
|
|
849
|
+
return {results};
|
|
850
|
+
};
|