@optimystic/db-core 1.18.0 → 1.20.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/README.md +2 -1
- package/dist/src/blocks/helpers.d.ts +7 -0
- package/dist/src/blocks/helpers.d.ts.map +1 -1
- package/dist/src/blocks/helpers.js +7 -1
- package/dist/src/blocks/helpers.js.map +1 -1
- package/dist/src/btree/btree.d.ts +100 -4
- package/dist/src/btree/btree.d.ts.map +1 -1
- package/dist/src/btree/btree.js +252 -90
- package/dist/src/btree/btree.js.map +1 -1
- package/dist/src/btree/node-division.d.ts +37 -0
- package/dist/src/btree/node-division.d.ts.map +1 -0
- package/dist/src/btree/node-division.js +133 -0
- package/dist/src/btree/node-division.js.map +1 -0
- package/dist/src/chain/chain.d.ts +23 -0
- package/dist/src/chain/chain.d.ts.map +1 -1
- package/dist/src/chain/chain.js +43 -6
- package/dist/src/chain/chain.js.map +1 -1
- package/dist/src/cluster/structs.d.ts +41 -8
- package/dist/src/cluster/structs.d.ts.map +1 -1
- package/dist/src/cluster/structs.js +18 -7
- package/dist/src/cluster/structs.js.map +1 -1
- package/dist/src/collection/action.d.ts +29 -0
- package/dist/src/collection/action.d.ts.map +1 -1
- package/dist/src/collection/action.js +6 -0
- package/dist/src/collection/action.js.map +1 -1
- package/dist/src/collection/collection.d.ts +566 -120
- package/dist/src/collection/collection.d.ts.map +1 -1
- package/dist/src/collection/collection.js +1084 -495
- package/dist/src/collection/collection.js.map +1 -1
- package/dist/src/collection/head-commit.d.ts +110 -0
- package/dist/src/collection/head-commit.d.ts.map +1 -0
- package/dist/src/collection/head-commit.js +65 -0
- package/dist/src/collection/head-commit.js.map +1 -0
- package/dist/src/collection/index.d.ts +2 -0
- package/dist/src/collection/index.d.ts.map +1 -1
- package/dist/src/collection/index.js +2 -0
- package/dist/src/collection/index.js.map +1 -1
- package/dist/src/collection/segments.d.ts +77 -0
- package/dist/src/collection/segments.d.ts.map +1 -0
- package/dist/src/collection/segments.js +110 -0
- package/dist/src/collection/segments.js.map +1 -0
- package/dist/src/collection/struct.d.ts +176 -1
- package/dist/src/collection/struct.d.ts.map +1 -1
- package/dist/src/collection/struct.js +70 -0
- package/dist/src/collection/struct.js.map +1 -1
- package/dist/src/collection/write-attempts.d.ts +245 -0
- package/dist/src/collection/write-attempts.d.ts.map +1 -0
- package/dist/src/collection/write-attempts.js +439 -0
- package/dist/src/collection/write-attempts.js.map +1 -0
- package/dist/src/collections/tree/struct.d.ts +100 -17
- package/dist/src/collections/tree/struct.d.ts.map +1 -1
- package/dist/src/collections/tree/struct.js +38 -7
- package/dist/src/collections/tree/struct.js.map +1 -1
- package/dist/src/collections/tree/tree.d.ts +17 -5
- package/dist/src/collections/tree/tree.d.ts.map +1 -1
- package/dist/src/collections/tree/tree.js +117 -29
- package/dist/src/collections/tree/tree.js.map +1 -1
- package/dist/src/index.d.ts +2 -0
- package/dist/src/index.d.ts.map +1 -1
- package/dist/src/index.js +2 -0
- package/dist/src/index.js.map +1 -1
- package/dist/src/log/log.d.ts +5 -1
- package/dist/src/log/log.d.ts.map +1 -1
- package/dist/src/log/log.js +7 -1
- package/dist/src/log/log.js.map +1 -1
- package/dist/src/network/block-size.d.ts +67 -0
- package/dist/src/network/block-size.d.ts.map +1 -0
- package/dist/src/network/block-size.js +82 -0
- package/dist/src/network/block-size.js.map +1 -0
- package/dist/src/network/i-repo.d.ts +3 -0
- package/dist/src/network/i-repo.d.ts.map +1 -1
- package/dist/src/network/index.d.ts +5 -0
- package/dist/src/network/index.d.ts.map +1 -1
- package/dist/src/network/index.js +5 -0
- package/dist/src/network/index.js.map +1 -1
- package/dist/src/network/promise-shortfall-error.d.ts +40 -0
- package/dist/src/network/promise-shortfall-error.d.ts.map +1 -0
- package/dist/src/network/promise-shortfall-error.js +67 -0
- package/dist/src/network/promise-shortfall-error.js.map +1 -0
- package/dist/src/network/refuse-solo.d.ts +8 -0
- package/dist/src/network/refuse-solo.d.ts.map +1 -0
- package/dist/src/network/refuse-solo.js +8 -0
- package/dist/src/network/refuse-solo.js.map +1 -0
- package/dist/src/network/stale-failure.d.ts +20 -3
- package/dist/src/network/stale-failure.d.ts.map +1 -1
- package/dist/src/network/stale-failure.js +24 -3
- package/dist/src/network/stale-failure.js.map +1 -1
- package/dist/src/network/struct.d.ts +161 -13
- package/dist/src/network/struct.d.ts.map +1 -1
- package/dist/src/network/struct.js.map +1 -1
- package/dist/src/network/transaction-size.d.ts +59 -0
- package/dist/src/network/transaction-size.d.ts.map +1 -0
- package/dist/src/network/transaction-size.js +74 -0
- package/dist/src/network/transaction-size.js.map +1 -0
- package/dist/src/network/validity-rejected-error.d.ts +28 -0
- package/dist/src/network/validity-rejected-error.d.ts.map +1 -0
- package/dist/src/network/validity-rejected-error.js +51 -0
- package/dist/src/network/validity-rejected-error.js.map +1 -0
- package/dist/src/offline/entry.d.ts +72 -0
- package/dist/src/offline/entry.d.ts.map +1 -0
- package/dist/src/offline/entry.js +73 -0
- package/dist/src/offline/entry.js.map +1 -0
- package/dist/src/offline/index.d.ts +5 -0
- package/dist/src/offline/index.d.ts.map +1 -0
- package/dist/src/offline/index.js +5 -0
- package/dist/src/offline/index.js.map +1 -0
- package/dist/src/offline/journal.d.ts +61 -0
- package/dist/src/offline/journal.d.ts.map +1 -0
- package/dist/src/offline/journal.js +2 -0
- package/dist/src/offline/journal.js.map +1 -0
- package/dist/src/offline/queue.d.ts +484 -0
- package/dist/src/offline/queue.d.ts.map +1 -0
- package/dist/src/offline/queue.js +1236 -0
- package/dist/src/offline/queue.js.map +1 -0
- package/dist/src/offline/reachability.d.ts +25 -0
- package/dist/src/offline/reachability.d.ts.map +1 -0
- package/dist/src/offline/reachability.js +13 -0
- package/dist/src/offline/reachability.js.map +1 -0
- package/dist/src/offline/status.d.ts +148 -0
- package/dist/src/offline/status.d.ts.map +1 -0
- package/dist/src/offline/status.js +63 -0
- package/dist/src/offline/status.js.map +1 -0
- package/dist/src/offline/wake.d.ts +30 -0
- package/dist/src/offline/wake.d.ts.map +1 -0
- package/dist/src/offline/wake.js +68 -0
- package/dist/src/offline/wake.js.map +1 -0
- package/dist/src/reactivity/config.d.ts +8 -4
- package/dist/src/reactivity/config.d.ts.map +1 -1
- package/dist/src/reactivity/config.js +7 -3
- package/dist/src/reactivity/config.js.map +1 -1
- package/dist/src/reactivity/rotation.d.ts +9 -3
- package/dist/src/reactivity/rotation.d.ts.map +1 -1
- package/dist/src/reactivity/rotation.js +8 -2
- package/dist/src/reactivity/rotation.js.map +1 -1
- package/dist/src/testing/test-transactor.d.ts +31 -0
- package/dist/src/testing/test-transactor.d.ts.map +1 -1
- package/dist/src/testing/test-transactor.js +60 -0
- package/dist/src/testing/test-transactor.js.map +1 -1
- package/dist/src/transaction/commit-failure-class.d.ts +103 -0
- package/dist/src/transaction/commit-failure-class.d.ts.map +1 -0
- package/dist/src/transaction/commit-failure-class.js +96 -0
- package/dist/src/transaction/commit-failure-class.js.map +1 -0
- package/dist/src/transaction/coordinator.d.ts +224 -31
- package/dist/src/transaction/coordinator.d.ts.map +1 -1
- package/dist/src/transaction/coordinator.js +841 -362
- package/dist/src/transaction/coordinator.js.map +1 -1
- package/dist/src/transaction/entry-commit.d.ts +139 -0
- package/dist/src/transaction/entry-commit.d.ts.map +1 -0
- package/dist/src/transaction/entry-commit.js +199 -0
- package/dist/src/transaction/entry-commit.js.map +1 -0
- package/dist/src/transaction/index.d.ts +4 -1
- package/dist/src/transaction/index.d.ts.map +1 -1
- package/dist/src/transaction/index.js +1 -0
- package/dist/src/transaction/index.js.map +1 -1
- package/dist/src/transaction/transaction.d.ts +20 -0
- package/dist/src/transaction/transaction.d.ts.map +1 -1
- package/dist/src/transaction/validator.d.ts +7 -0
- package/dist/src/transaction/validator.d.ts.map +1 -1
- package/dist/src/transaction/validator.js +21 -12
- package/dist/src/transaction/validator.js.map +1 -1
- package/dist/src/transactor/change-notifier.d.ts +13 -4
- package/dist/src/transactor/change-notifier.d.ts.map +1 -1
- package/dist/src/transactor/change-notifier.js.map +1 -1
- package/dist/src/transactor/network-transactor.d.ts +58 -8
- package/dist/src/transactor/network-transactor.d.ts.map +1 -1
- package/dist/src/transactor/network-transactor.js +244 -50
- package/dist/src/transactor/network-transactor.js.map +1 -1
- package/dist/src/transactor/transactor-source.d.ts +22 -11
- package/dist/src/transactor/transactor-source.d.ts.map +1 -1
- package/dist/src/transactor/transactor-source.js +9 -13
- package/dist/src/transactor/transactor-source.js.map +1 -1
- package/dist/src/transactor/transactor.d.ts +14 -0
- package/dist/src/transactor/transactor.d.ts.map +1 -1
- package/dist/src/transform/digest.d.ts +20 -0
- package/dist/src/transform/digest.d.ts.map +1 -1
- package/dist/src/transform/digest.js +23 -3
- package/dist/src/transform/digest.js.map +1 -1
- package/dist/src/utility/visit-every.d.ts +14 -0
- package/dist/src/utility/visit-every.d.ts.map +1 -0
- package/dist/src/utility/visit-every.js +27 -0
- package/dist/src/utility/visit-every.js.map +1 -0
- package/package.json +1 -1
- package/src/blocks/helpers.ts +8 -1
- package/src/btree/btree.ts +266 -88
- package/src/btree/node-division.ts +155 -0
- package/src/chain/chain.ts +55 -6
- package/src/cluster/structs.ts +42 -7
- package/src/collection/action.ts +34 -0
- package/src/collection/collection.ts +1167 -540
- package/src/collection/head-commit.ts +148 -0
- package/src/collection/index.ts +2 -0
- package/src/collection/segments.ts +149 -0
- package/src/collection/struct.ts +201 -1
- package/src/collection/write-attempts.ts +506 -0
- package/src/collections/tree/struct.ts +97 -17
- package/src/collections/tree/tree.ts +129 -31
- package/src/index.ts +2 -0
- package/src/log/log.ts +7 -1
- package/src/network/block-size.ts +81 -0
- package/src/network/i-repo.ts +3 -0
- package/src/network/index.ts +5 -0
- package/src/network/promise-shortfall-error.ts +69 -0
- package/src/network/refuse-solo.ts +7 -0
- package/src/network/stale-failure.ts +27 -4
- package/src/network/struct.ts +169 -15
- package/src/network/transaction-size.ts +73 -0
- package/src/network/validity-rejected-error.ts +55 -0
- package/src/offline/entry.ts +127 -0
- package/src/offline/index.ts +4 -0
- package/src/offline/journal.ts +60 -0
- package/src/offline/queue.ts +1342 -0
- package/src/offline/reachability.ts +32 -0
- package/src/offline/status.ts +183 -0
- package/src/offline/wake.ts +67 -0
- package/src/reactivity/config.ts +8 -4
- package/src/reactivity/rotation.ts +9 -3
- package/src/testing/test-transactor.ts +65 -0
- package/src/transaction/commit-failure-class.ts +133 -0
- package/src/transaction/coordinator.ts +969 -393
- package/src/transaction/entry-commit.ts +285 -0
- package/src/transaction/index.ts +4 -0
- package/src/transaction/transaction.ts +21 -0
- package/src/transaction/validator.ts +22 -12
- package/src/transactor/change-notifier.ts +13 -4
- package/src/transactor/network-transactor.ts +252 -55
- package/src/transactor/transactor-source.ts +29 -13
- package/src/transactor/transactor.ts +16 -0
- package/src/transform/digest.ts +36 -3
- package/src/utility/visit-every.ts +25 -0
|
@@ -2,6 +2,7 @@ import type { ITransactor, CollectionId, Transforms } from "../index.js";
|
|
|
2
2
|
import type { Transaction, ExecutionResult, ITransactionEngine, CollectionActions, ReadDependency } from "./transaction.js";
|
|
3
3
|
import type { Collection } from "../collection/collection.js";
|
|
4
4
|
import type { SyncOptions } from "../collection/index.js";
|
|
5
|
+
import type { EntryCommit } from "./entry-commit.js";
|
|
5
6
|
import { type TransactionDurability } from "./durability.js";
|
|
6
7
|
/**
|
|
7
8
|
* What a pend this coordinator sends carries for the receiving cluster members to re-check.
|
|
@@ -161,7 +162,9 @@ export declare class TransactionCoordinator {
|
|
|
161
162
|
* unavailable transactor, unreachable cluster) also propagates without retry — including a pend
|
|
162
163
|
* or commit the cohort refused because the transaction had expired by its members' clocks, which
|
|
163
164
|
* surfaces as {@link TransactionExpiredError} (inside a partial commit's `reason` once a sibling
|
|
164
|
-
* has landed)
|
|
165
|
+
* has landed), a pend too few of the cohort's members answered, which surfaces as
|
|
166
|
+
* {@link PromiseShortfallError}, and a pend the members that sank it judged invalid, which surfaces
|
|
167
|
+
* as {@link ValidityRejectedError}.
|
|
165
168
|
*
|
|
166
169
|
* A participant can also be SAVED between attempts: an attempt that reported a loss may still
|
|
167
170
|
* have stored that participant's log tail, and the refresh before the next attempt then finishes
|
|
@@ -185,35 +188,73 @@ export declare class TransactionCoordinator {
|
|
|
185
188
|
* committed half's on {@link CoordinatorPartialCommitError.durability}.
|
|
186
189
|
*/
|
|
187
190
|
commit(transaction: Transaction, options?: SyncOptions): Promise<TransactionDurability | undefined>;
|
|
188
|
-
/**
|
|
189
|
-
*
|
|
190
|
-
*
|
|
191
|
-
*
|
|
191
|
+
/**
|
|
192
|
+
* The retry loop behind {@link commit} and {@link commitEntry}: every attempt, and the refresh
|
|
193
|
+
* rounds between them, over the `driver`'s steps and the budget `options` sets
|
|
194
|
+
* ({@link RetryBudget}). Records what it learns in `cycle`; the caller owns turning a failure into
|
|
195
|
+
* the right report. On success, reports every participant the cycle saved together with what the
|
|
196
|
+
* final attempt committed (see {@link commit}'s return).
|
|
197
|
+
*
|
|
198
|
+
* Only a CLEAN stale loss is retried. A partial landing on a hard failure, an expired transaction,
|
|
199
|
+
* an unavailable transactor, etc. all propagate unchanged. Once a refresh round has saved a
|
|
200
|
+
* participant and the driver has nothing left to commit, the write is finished and the loop
|
|
201
|
+
* returns at once rather than going round again, where an abort, the deadline or an expiry check
|
|
202
|
+
* could still report failure for a write that is entirely saved.
|
|
203
|
+
*/
|
|
192
204
|
private commitAttempts;
|
|
193
205
|
/**
|
|
194
|
-
*
|
|
195
|
-
*
|
|
196
|
-
*
|
|
206
|
+
* Back off, refresh, and keep refreshing while a round reports that a participant's half-landed
|
|
207
|
+
* write could not be finished YET. Re-reading fresh state before re-attempting is what lets the
|
|
208
|
+
* next attempt pend against current revisions (mirrors how Collection.sync calls updateInternal()
|
|
209
|
+
* before retrying), and a participant whose log tail landed despite the reported loss finds its
|
|
210
|
+
* own entry here and FINISHES that action before consuming it (Collection.completeOwnEntry, from
|
|
211
|
+
* the attempt the previous one retained).
|
|
212
|
+
*
|
|
213
|
+
* When finishing is refused for a cause that can clear, the refresh — not the commit — is what
|
|
214
|
+
* gets retried: the participant's log entry is already durable, and once a refresh adopts a newer
|
|
215
|
+
* revision the next attempt appends a SECOND entry under the write's id. (At an unchanged
|
|
216
|
+
* revision the re-append is byte-identical — see Collection.logAppendBlockIds — so what is at
|
|
217
|
+
* stake is the duplicate entry, not two versions of one tail block.) Each such round counts
|
|
218
|
+
* against the same budget as a stale loss; a permanent refusal (a rival holds the revision)
|
|
219
|
+
* escapes as the named TornActionError at once. Re-refreshing a collection an earlier round
|
|
220
|
+
* already refreshed is a no-op. The round that would spend the last of the budget is told so,
|
|
221
|
+
* which makes each participant SETTLE a half-landed write rather than ask for another round: the
|
|
222
|
+
* error thrown then says whether the write can still land (`final`). A deadline cannot be
|
|
223
|
+
* foreseen the same way; a write given up on it stays unsettled.
|
|
224
|
+
*/
|
|
225
|
+
private refreshRounds;
|
|
226
|
+
/** Every registered collection as a refresh-round participant of a transaction's commit.
|
|
227
|
+
*
|
|
228
|
+
* NOTE: EVERY registered collection, not only the participants of the transaction. Not free: a
|
|
229
|
+
* non-participant's refresh throws CollectionHeaderVanishedError if its header momentarily reads
|
|
230
|
+
* absent while it holds a committed revision, aborting this retry. And because a throw does not
|
|
231
|
+
* stop the round, an unreachable cluster costs one failed read per registered collection rather
|
|
232
|
+
* than one. The registered set is small today; if that (or retry latency) ever bites, narrow this
|
|
233
|
+
* to the transaction's participants. (The per-entry commit already refreshes its participants
|
|
234
|
+
* only, through their handles — see `EntryParticipants.refreshers`.) */
|
|
235
|
+
private registeredRefreshers;
|
|
236
|
+
/**
|
|
237
|
+
* One refresh round between attempts: refresh every participant, recording in `cycle.saved` each
|
|
238
|
+
* one whose refresh finished the write's own log entry (see {@link Collection.refreshInFlight}),
|
|
239
|
+
* with who holds it — `undefined` when the refresh could not say, which still records it as
|
|
240
|
+
* saved — and telling the participant so (`RefreshParticipant.saved`).
|
|
197
241
|
*
|
|
198
|
-
* Visits EVERY
|
|
199
|
-
* participant later in the
|
|
242
|
+
* Visits EVERY participant even after one throws. Stopping at the first throw would leave a
|
|
243
|
+
* participant later in the round unfinished whenever an earlier one is torn — its log tail stored
|
|
200
244
|
* and its other blocks never landed, the silent loss `Collection.completeOwnEntry` exists to
|
|
201
245
|
* prevent — and unreported. Each refresh is independent (its own latch, its own instance state),
|
|
202
246
|
* so one failing says nothing about the next.
|
|
203
247
|
*
|
|
204
|
-
* NOTE:
|
|
205
|
-
*
|
|
206
|
-
*
|
|
207
|
-
* a throw no longer stops the round, an unreachable cluster costs one failed read per registered
|
|
208
|
-
* collection rather than one. The registered set is small today; if that (or retry latency) ever
|
|
209
|
-
* bites, narrow this to the transaction's participants.
|
|
248
|
+
* NOTE: no `tailFloor` is passed to any refresh — the coordinator's loop loses the confirmed
|
|
249
|
+
* revision before the round runs (backlog `debt-multi-collection-retry-cannot-see-the-taken-revision`);
|
|
250
|
+
* the per-entry commit has the same gap, through the same round.
|
|
210
251
|
*
|
|
211
252
|
* @param lastChance - this is the round that spends the last of the retry budget, so a
|
|
212
253
|
* participant whose half-landed write is refused again settles it (`Collection.completeOwnEntry`)
|
|
213
254
|
* rather than asking for a round it will not get; the error returned then carries `final`.
|
|
214
255
|
* @returns the first `completion-refused` {@link TornActionError} when that is the only way any
|
|
215
256
|
* refresh failed — the round is worth retrying; `undefined` when every refresh succeeded.
|
|
216
|
-
* @throws the first other error, once every
|
|
257
|
+
* @throws the first other error, once every participant has been visited.
|
|
217
258
|
*/
|
|
218
259
|
private refreshBetweenAttempts;
|
|
219
260
|
/** Every registered collection with something to push — the participants an attempt starting
|
|
@@ -243,8 +284,9 @@ export declare class TransactionCoordinator {
|
|
|
243
284
|
*
|
|
244
285
|
* Local state already matches that report: a saved participant was consumed by its refresh, and
|
|
245
286
|
* an unsaved one kept its staged actions (a failed finish throws before touching anything, and
|
|
246
|
-
* commitOnceLatched restores every participant it did not commit
|
|
247
|
-
*
|
|
287
|
+
* commitOnceLatched restores every participant it did not commit; the per-entry commit leaves a
|
|
288
|
+
* refused participant's segment sealed and first). Releasing a transaction's stamp on the partial
|
|
289
|
+
* report is {@link commit}'s, which reads the class of what this returns.
|
|
248
290
|
*/
|
|
249
291
|
private reportSaved;
|
|
250
292
|
/**
|
|
@@ -289,6 +331,76 @@ export declare class TransactionCoordinator {
|
|
|
289
331
|
* @returns on success, every participant with who holds it (see {@link commitOnce}).
|
|
290
332
|
*/
|
|
291
333
|
private commitOnceLatched;
|
|
334
|
+
/**
|
|
335
|
+
* Commit one queued entry's slice of every collection it wrote, as ONE all-or-nothing round
|
|
336
|
+
* (docs/offline-sync.md §One entry, one network transaction): for each collection in
|
|
337
|
+
* `entry.collectionIds`, exactly its HEAD sealed segment, which must be `entry.entryId`, as one
|
|
338
|
+
* log entry under `entry.actionId` and `entry.timestamp`. The offline-sync queue is the caller,
|
|
339
|
+
* for an entry that wrote more than one collection; an entry that wrote one commits through
|
|
340
|
+
* `Collection.commitHead`, whose steps this drives in lock-step across the participants
|
|
341
|
+
* (`HeadCommitHandle` in collection/head-commit.ts): open a handle per participant, in sorted
|
|
342
|
+
* collection-id order; the opening refresh, which finishes and consumes an entry an earlier
|
|
343
|
+
* `commitEntry` under this action id left in a participant's log; then per attempt, build every
|
|
344
|
+
* participant's attempt on its head tracker, record them through `entry.recordAttempt`, release
|
|
345
|
+
* every latch, run the phases ({@link coordinateAttempts}: pend every participant, then commit),
|
|
346
|
+
* retake every latch, and apply the outcome — fold then replay on a commit, the recorded refusal
|
|
347
|
+
* re-checked and the attempt retained on a refusal — with the retry loop of {@link commit}
|
|
348
|
+
* ({@link commitAttempts}) between attempts.
|
|
349
|
+
*
|
|
350
|
+
* What the slice deliberately does NOT do, where {@link commit} does: no pre-commit snapshots or
|
|
351
|
+
* `restorePending` (an attempt never touches the live tracker; a failed one leaves it as it was
|
|
352
|
+
* by construction); no `getPendingActions`, `clearPendingActions` or `tracker.reset` (the head
|
|
353
|
+
* segment is dropped and folded through the handle); no stamp (the one-open-stamp rule is about
|
|
354
|
+
* staged state, which a slice does not stage — a slice may run while a stamp is open on another
|
|
355
|
+
* coordinator over the same collections, which is the plugin's open SQL transaction; the
|
|
356
|
+
* collection latch is what serialises them); no expiry check (an entry has no stamp to expire).
|
|
357
|
+
* Its refresh rounds refresh the entry's participants only, through their handles, never the
|
|
358
|
+
* coordinator's whole map.
|
|
359
|
+
*
|
|
360
|
+
* Requires a coordinator built with `pendValidation: 'none'`, and throws before touching
|
|
361
|
+
* anything otherwise: a queued entry has no statements for a member to re-execute, and the pend
|
|
362
|
+
* carries bare transforms exactly as the plugin's `commitBatchLegacy` sends them. The queue builds
|
|
363
|
+
* one coordinator per submission over exactly the entry's collections; running `commitEntry`
|
|
364
|
+
* while a {@link commit} of the same coordinator is open is not a supported combination, and
|
|
365
|
+
* nothing but the collection latches guards it.
|
|
366
|
+
*
|
|
367
|
+
* @returns who holds each collection the entry wrote, across every attempt, as {@link commit}
|
|
368
|
+
* answers it — a participant the refresh saved included, listed with an `undefined` class (and
|
|
369
|
+
* `overall` then absent) when the refresh established it was saved under `entry.actionId` without
|
|
370
|
+
* re-sending (the status-read fallback of `Collection.completeOwnEntry`, where
|
|
371
|
+
* `Collection.commitHead` answers `undefined`). Never `undefined`: a slice always writes at least
|
|
372
|
+
* one collection, so the "nothing was written" answer `commit` has is unrepresentable here.
|
|
373
|
+
* @throws what {@link commit} throws — a {@link CoordinatorStaleLossError} once the retry budget
|
|
374
|
+
* is spent, a {@link CoordinatorPartialCommitError} for a partial landing (every participant it
|
|
375
|
+
* names as committed has had its head consumed; every failed one's head is still sealed and
|
|
376
|
+
* first, its attempt retained), the named refusals, `TornActionError` out of a refresh — plus the
|
|
377
|
+
* recorded refusal of any participant's head (an `ActionRefusedError`), thrown with every other
|
|
378
|
+
* participant's segment intact since nothing was sent or the send was refused, and
|
|
379
|
+
* `SealedSegmentsError` from `Collection.openHeadCommit`'s preconditions, before anything is done.
|
|
380
|
+
*/
|
|
381
|
+
commitEntry(entry: EntryCommit, options?: SyncOptions): Promise<TransactionDurability>;
|
|
382
|
+
/**
|
|
383
|
+
* One attempt of {@link commitEntry}, under the latches `participants` hold: every remaining
|
|
384
|
+
* participant's attempt is built (`HeadCommitHandle.stage`, which re-checks the head's recorded
|
|
385
|
+
* refusal and throws it), recorded through the write-ahead hook — a throw there aborts with
|
|
386
|
+
* nothing sent and nothing changed — then sent as one round with every latch released, and the
|
|
387
|
+
* outcome applied under the retaken latches:
|
|
388
|
+
*
|
|
389
|
+
* - a commit: fold every participant in one await-free pass, then replay each
|
|
390
|
+
* (`EntryParticipants.landed`); the attempt's durability per collection is the answer;
|
|
391
|
+
* - a partial landing: the committed participants folded, replayed and recorded in `cycle.saved`
|
|
392
|
+
* — before their local treatment, so a throw in it is still reported over the right committed
|
|
393
|
+
* set — and the rest refused (their recorded refusal re-checked, their attempt retained); then
|
|
394
|
+
* {@link CoordinatorStaleLossError} when every refusal was a returned one, so the retry loop
|
|
395
|
+
* finishes the refused participants forward over what is left (as `commitOnceLatched`'s
|
|
396
|
+
* partial-retry branch does), or {@link CoordinatorPartialCommitError} on a hard failure;
|
|
397
|
+
* - nothing committed: every participant refused, then the failure thrown by its class
|
|
398
|
+
* ({@link cleanFailureError}).
|
|
399
|
+
*
|
|
400
|
+
* The refusal re-check runs after the committed participants are folded, never before: a
|
|
401
|
+
* sibling's recorded refusal must not keep a durable commit from being applied locally.
|
|
402
|
+
*/
|
|
403
|
+
private commitEntryOnce;
|
|
292
404
|
/**
|
|
293
405
|
* Rollback a transaction (undo only the given stampId's applied actions).
|
|
294
406
|
*
|
|
@@ -346,13 +458,16 @@ export declare class TransactionCoordinator {
|
|
|
346
458
|
/**
|
|
347
459
|
* Apply actions to a collection.
|
|
348
460
|
*
|
|
349
|
-
* This runs the action handlers, writes to the log, and collects transforms.
|
|
461
|
+
* This runs the action handlers, writes to the log, and collects transforms. The log entry is
|
|
462
|
+
* written under `context`: its action id, its timestamp and its reads.
|
|
350
463
|
*/
|
|
351
464
|
private applyActionsToCollection;
|
|
352
465
|
/**
|
|
353
|
-
* Coordinate a transaction across multiple collections
|
|
466
|
+
* Coordinate a transaction's attempt across multiple collections: describe what each collection's
|
|
467
|
+
* staged transforms send ({@link declareTouchedBlocks}), then run the phases
|
|
468
|
+
* ({@link coordinateAttempts}).
|
|
354
469
|
*
|
|
355
|
-
* @param
|
|
470
|
+
* @param context - The write being coordinated (its action id and aged priority)
|
|
356
471
|
* @param validation - What every pend carries for members to re-check, or undefined for an
|
|
357
472
|
* unvalidated pend (see {@link pendValidationFor})
|
|
358
473
|
* @param collectionTransforms - Map of collectionId to its transforms
|
|
@@ -362,6 +477,13 @@ export declare class TransactionCoordinator {
|
|
|
362
477
|
* and the local record name the same number.
|
|
363
478
|
*/
|
|
364
479
|
private coordinateTransaction;
|
|
480
|
+
/**
|
|
481
|
+
* The distributed phases of one attempt — GATHER, PEND, COMMIT, and the CANCEL of what a failed
|
|
482
|
+
* commit left pending — over every collection's share of it, already described
|
|
483
|
+
* (`CollectionAttempt`). Run by {@link coordinateTransaction} for a transaction's attempt and by
|
|
484
|
+
* {@link commitEntryOnce} for a queued entry's, whose attempts the head commit described.
|
|
485
|
+
*/
|
|
486
|
+
private coordinateAttempts;
|
|
365
487
|
/**
|
|
366
488
|
* GATHER phase: Collect nominees from critical clusters.
|
|
367
489
|
*
|
|
@@ -371,41 +493,112 @@ export declare class TransactionCoordinator {
|
|
|
371
493
|
* @returns Set of peer IDs to use for consensus, or null for single-collection
|
|
372
494
|
*/
|
|
373
495
|
private gatherPhase;
|
|
496
|
+
/**
|
|
497
|
+
* What each collection's staged transforms send, described from its live tracker after the log
|
|
498
|
+
* append: one local materialization of every block the transforms touch
|
|
499
|
+
* ({@link describeTouchedBlocks}), taken before anything is sent. A block the write would leave
|
|
500
|
+
* over `MAX_BLOCK_BYTES` refuses the transaction here, as a pend-phase failure carrying the
|
|
501
|
+
* {@link BlockTooLargeError} — the same shape as a pend too large to send, so `commit` throws it by
|
|
502
|
+
* name and `execute` reports it as a failure. Otherwise each collection's digests are kept as its
|
|
503
|
+
* commit's declaration ({@link commitRequestFor}), so the commit does not materialize again, and
|
|
504
|
+
* the base each update-only block's operations were computed against is read from the same
|
|
505
|
+
* tracker's pins for its pend (`PendRequest.baseRevs`; storage keeps it with the pending record so
|
|
506
|
+
* the record is never applied to a different version of the block).
|
|
507
|
+
*
|
|
508
|
+
* Purely local: each collection's tracker holds this transaction's staged transforms until the commit
|
|
509
|
+
* succeeds, under the instance latch the commit span holds. A collection missing from the registry
|
|
510
|
+
* is a defect here: {@link applyActionsToCollection} has already refused it.
|
|
511
|
+
*/
|
|
512
|
+
private declareTouchedBlocks;
|
|
374
513
|
/**
|
|
375
514
|
* PEND phase: Distribute transaction to all affected block clusters.
|
|
376
515
|
*
|
|
377
|
-
*
|
|
378
|
-
*
|
|
516
|
+
* Two or more collections go as ONE request when the transactor can send them so
|
|
517
|
+
* ({@link pendTogether}); otherwise, and for one collection, each collection is pended on its own.
|
|
518
|
+
*
|
|
519
|
+
* @param context - The write being pended (its action id names the action; its aged priority
|
|
520
|
+
* rides on an unvalidated pend)
|
|
379
521
|
* @param validation - What every pend carries for members to re-check, or undefined for an
|
|
380
522
|
* unvalidated pend (see {@link pendValidationFor})
|
|
381
|
-
* @param
|
|
382
|
-
*
|
|
383
|
-
*
|
|
384
|
-
*
|
|
523
|
+
* @param attempts - Per collection, its share of the attempt: its transforms, and the revision
|
|
524
|
+
* its log entry was stamped with — the pend request repeats it verbatim rather than recomputing
|
|
525
|
+
* from the collection (a recompute after the append could name a different number if the
|
|
526
|
+
* collection refreshed in between).
|
|
385
527
|
* @param superclusterNominees - Nominees for multi-collection consensus (null for single-collection)
|
|
386
528
|
*/
|
|
387
529
|
private pendPhase;
|
|
530
|
+
/**
|
|
531
|
+
* Pends every collection as ONE request ({@link ITransactor.pendMany}): one consensus record,
|
|
532
|
+
* answered together. Every request is marked the action's only reservation
|
|
533
|
+
* (`PendRequest.soleReservation`) — together they are, and their commit goes as one request to the
|
|
534
|
+
* same coordinator ({@link commitTogether}) — so a coordinator may hold the pend's decision back for
|
|
535
|
+
* the commit to carry, and a member that refuses any collection's pend late refuses the action's one
|
|
536
|
+
* commit record before anything of it is durable.
|
|
537
|
+
*
|
|
538
|
+
* - **Success**: every collection is pended, with its own blocks.
|
|
539
|
+
* - **Refusal**: classified as one collection's refusal is ({@link pendRefusalError}), once for the
|
|
540
|
+
* batch. `pendMany` cancelled every block, so nothing is left pended.
|
|
541
|
+
* - **Throw** (a transactor other than `NetworkTransactor`, which answers a throw with `undefined`):
|
|
542
|
+
* a hard failure, as a thrown pend is. What was pended is unknown, so every collection's blocks are
|
|
543
|
+
* cancelled.
|
|
544
|
+
* - **`undefined`**: they could not go as one, and nothing of them is pended. {@link pendPhase} then
|
|
545
|
+
* pends each collection on its own with requests rebuilt WITHOUT the mark. The marked requests are
|
|
546
|
+
* never re-sent one by one: each carries every block of its collection, so `NetworkTransactor.pend`
|
|
547
|
+
* would keep the mark, and one collection's late refusal could then surface after a sibling's commit
|
|
548
|
+
* landed — the tear the mark exists to prevent.
|
|
549
|
+
*/
|
|
550
|
+
private pendTogether;
|
|
388
551
|
/**
|
|
389
552
|
* Pend a single collection's transforms. Resolves with the collection id and its
|
|
390
553
|
* pended block ids on success; throws with a per-collection reason on failure so the
|
|
391
554
|
* fan-out in {@link pendPhase} can settle it as a rejection.
|
|
392
555
|
*/
|
|
393
556
|
private pendCollection;
|
|
557
|
+
/**
|
|
558
|
+
* The pend request for one collection's share of an attempt — the one place a pend request is built,
|
|
559
|
+
* whether it goes on its own ({@link pendCollection}) or with its siblings ({@link pendTogether}).
|
|
560
|
+
*/
|
|
561
|
+
private pendRequestFor;
|
|
394
562
|
/**
|
|
395
563
|
* COMMIT phase: Commit to all critical blocks with retry for transient failures.
|
|
396
564
|
*
|
|
397
565
|
* Once all collections are pended (Phase 1 passes), the coordinator has decided
|
|
398
|
-
* to commit.
|
|
399
|
-
*
|
|
566
|
+
* to commit. Two or more collections go as ONE request when the transactor can send them so
|
|
567
|
+
* ({@link commitTogether}); otherwise each collection commits on its own, its transient failures
|
|
568
|
+
* retried (forward recovery) before giving up. Returns which collections committed vs failed so
|
|
569
|
+
* the caller can do targeted cancel.
|
|
400
570
|
*/
|
|
401
571
|
private commitPhase;
|
|
572
|
+
/**
|
|
573
|
+
* Commits every collection as ONE request ({@link ITransactor.commitMany}): one consensus record,
|
|
574
|
+
* decided together — the commit half of {@link pendTogether}. Every collection gets the batch's one
|
|
575
|
+
* answer ({@link collectionCommitOutcome}): committed, each stamped with its own blocks and revision;
|
|
576
|
+
* or refused, every collection alike. A refused collection's attempt is then retained by
|
|
577
|
+
* `commitOnceLatched`, and the refresh between attempts finishes any collection whose log entry did
|
|
578
|
+
* land (`Collection.completeOwnEntry`) — the path a refused one-collection commit already takes.
|
|
579
|
+
*
|
|
580
|
+
* `undefined` when they could not go as one, when the request threw, or when a collection's request
|
|
581
|
+
* could not be built (no log tail among its pended blocks): {@link commitPhase} then commits each
|
|
582
|
+
* collection on its own, which re-sends everything and reports a request it cannot build as it
|
|
583
|
+
* always has. The batch is never retried here: a returned refusal cannot be won by the identical
|
|
584
|
+
* request, and a throw is the per-collection path's to retry.
|
|
585
|
+
*/
|
|
586
|
+
private commitTogether;
|
|
587
|
+
/** Commits each collection on its own, concurrently ({@link commitCollection}), one outcome per collection. */
|
|
588
|
+
private commitEach;
|
|
402
589
|
/**
|
|
403
590
|
* Commit a single collection's pended blocks, retrying transient failures up to three
|
|
404
591
|
* times (forward recovery). Always resolves — success is carried in the returned
|
|
405
592
|
* `committed` flag, with the commit's `durability` beside it — so the fan-out in
|
|
406
|
-
* {@link
|
|
593
|
+
* {@link commitEach} can aggregate every result.
|
|
407
594
|
*/
|
|
408
595
|
private commitCollection;
|
|
596
|
+
/**
|
|
597
|
+
* The commit request for one collection's pended blocks — the one place a commit request is built,
|
|
598
|
+
* whether it goes on its own ({@link commitCollection}) or with its siblings ({@link commitTogether})
|
|
599
|
+
* — or, as a string, why there is none.
|
|
600
|
+
*/
|
|
601
|
+
private commitRequestFor;
|
|
409
602
|
/**
|
|
410
603
|
* CANCEL phase: Cancel pending actions on affected blocks.
|
|
411
604
|
*
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../../../src/transaction/coordinator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAW,YAAY,EAAE,UAAU,
|
|
1
|
+
{"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../../../src/transaction/coordinator.ts"],"names":[],"mappings":"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"}
|