@optimystic/db-core 1.19.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/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 +533 -120
- package/dist/src/collection/collection.d.ts.map +1 -1
- package/dist/src/collection/collection.js +974 -500
- 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 +156 -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 +112 -26
- 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/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 +3 -0
- package/dist/src/network/index.d.ts.map +1 -1
- package/dist/src/network/index.js +3 -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 +148 -2
- package/dist/src/network/struct.d.ts.map +1 -1
- package/dist/src/network/struct.js.map +1 -1
- 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/testing/test-transactor.d.ts +29 -0
- package/dist/src/testing/test-transactor.d.ts.map +1 -1
- package/dist/src/testing/test-transactor.js +50 -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 +165 -41
- package/dist/src/transaction/coordinator.d.ts.map +1 -1
- package/dist/src/transaction/coordinator.js +605 -300
- 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/network-transactor.d.ts +1 -0
- package/dist/src/transactor/network-transactor.d.ts.map +1 -1
- package/dist/src/transactor/network-transactor.js +61 -28
- 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/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/cluster/structs.ts +42 -7
- package/src/collection/action.ts +34 -0
- package/src/collection/collection.ts +1048 -543
- 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 +183 -1
- package/src/collection/write-attempts.ts +506 -0
- package/src/collections/tree/struct.ts +97 -17
- package/src/collections/tree/tree.ts +125 -29
- package/src/index.ts +2 -0
- package/src/network/i-repo.ts +3 -0
- package/src/network/index.ts +3 -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 +154 -2
- 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/testing/test-transactor.ts +53 -0
- package/src/transaction/commit-failure-class.ts +133 -0
- package/src/transaction/coordinator.ts +696 -349
- 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/network-transactor.ts +62 -28
- package/src/transactor/transactor-source.ts +29 -13
- package/src/utility/visit-every.ts +25 -0
|
@@ -0,0 +1,439 @@
|
|
|
1
|
+
import { Log } from "../log/log.js";
|
|
2
|
+
import { Tracker } from "../transform/tracker.js";
|
|
3
|
+
import { copyTransforms } from "../transform/helpers.js";
|
|
4
|
+
import { describeTouchedBlocks, baseRevsField } from "../transform/digest.js";
|
|
5
|
+
import { oversizedBlock } from "../network/block-size.js";
|
|
6
|
+
import { mergeDurability } from "../network/durability.js";
|
|
7
|
+
import { highestStaleAt, isExpiryFailure, isRejectedFailure, isShortfallFailure } from "../network/stale-failure.js";
|
|
8
|
+
import { TransactionExpiredError } from "../network/transaction-expired-error.js";
|
|
9
|
+
import { PromiseShortfallError } from "../network/promise-shortfall-error.js";
|
|
10
|
+
import { ValidityRejectedError } from "../network/validity-rejected-error.js";
|
|
11
|
+
import { SyncRetryExhaustedError, SyncRevisionStalledError, TornActionError } from "./struct.js";
|
|
12
|
+
import { clampPriority, SlotHoldAfterLosses } from "../transaction/transaction.js";
|
|
13
|
+
import { jitteredBackoffMs, abortableDelay, makeAbortError } from "../utility/backoff.js";
|
|
14
|
+
import { createLogger } from "../logger.js";
|
|
15
|
+
/**
|
|
16
|
+
* The attempt machinery a collection's two write paths share — `Collection.syncAttempts`, which
|
|
17
|
+
* commits the open segment, and `Collection.commitHead`, which commits the head sealed segment
|
|
18
|
+
* (docs/offline-sync.md §One entry, one network transaction). Each path decides WHAT an attempt
|
|
19
|
+
* sends and what to do with a commit; everything about HOW an attempt is built and accounted for
|
|
20
|
+
* is here, so the two cannot drift: the per-attempt tracker and log append
|
|
21
|
+
* ({@link stageAttempt}), the retained attempt a refresh may finish from
|
|
22
|
+
* ({@link retainedAttempt}), and the retry accounting with its stall check and its
|
|
23
|
+
* refresh-until-settled loop ({@link AttemptCycle}). The rules each step enforces are spelled out
|
|
24
|
+
* in docs/internals.md under *Key Invariants* ("The writer's retry finishes its own half-landed
|
|
25
|
+
* action", "A write's log append is a fixed function of the write and the revision it is
|
|
26
|
+
* requesting", "Monotonicity is also what makes a wedged view detectable").
|
|
27
|
+
*/
|
|
28
|
+
const log = createLogger('collection');
|
|
29
|
+
/** Default base backoff (and historical fixed delay) between write retries, in ms. */
|
|
30
|
+
const PendingRetryDelayMs = 100;
|
|
31
|
+
/** Default max consecutive no-progress stale-failure retries before a write gives up. */
|
|
32
|
+
const DefaultMaxAttempts = 10;
|
|
33
|
+
/** Default ceiling on a single exponential-backoff sleep, in ms. */
|
|
34
|
+
const DefaultMaxBackoffMs = 5000;
|
|
35
|
+
/** Default consecutive stalled refreshes — ones that moved this collection's revision NOWHERE
|
|
36
|
+
* while a responder CONFIRMED a revision at or above the one being requested — before a write
|
|
37
|
+
* gives up. Two, not one, so a single transiently-lagging read is absorbed.
|
|
38
|
+
*
|
|
39
|
+
* NOTE: two is a judgement call, not a measurement — nothing here counts how often a legitimate
|
|
40
|
+
* loser reads a view that moves nowhere for two consecutive rounds. The check only strikes when the
|
|
41
|
+
* refresh made NO progress at all, so a client merely catching up is already excluded; if a
|
|
42
|
+
* spurious `SyncRevisionStalledError` ever shows up under real contention anyway, raise this. */
|
|
43
|
+
const DefaultMaxStalledAttempts = 2;
|
|
44
|
+
/**
|
|
45
|
+
* The sleep before the refresh that follows a write's `failures`-th consecutive loss.
|
|
46
|
+
*
|
|
47
|
+
* The jittered backoff exists to separate a herd of writers that lost the SAME race, so they do not
|
|
48
|
+
* re-collide on the next tick. A loss to a rival that had already committed (the refusal carried a
|
|
49
|
+
* confirmed `staleAt`) is not a herd, and once this write has taken `SlotHoldAfterLosses` such losses
|
|
50
|
+
* (`confirmedLosses`, counted over the whole write as a member counts its stale refusals of one
|
|
51
|
+
* action) the members that refused it hold the next slot for it — so sleeping only spends that hold.
|
|
52
|
+
* Both sides count the same refusals against the same constant, so the writer stops sleeping on the
|
|
53
|
+
* loss after which a member holds, with nothing said over the wire. A loss the latest refusal did not
|
|
54
|
+
* confirm (`latestConfirmed` false — a race against something still in flight) keeps the jitter.
|
|
55
|
+
*
|
|
56
|
+
* NOTE: against members that do not hold (an earlier release, `slotHoldWindowMs: 0`, or a member the
|
|
57
|
+
* refused pends did not reach) this retries without sleeping and so spends the same attempt budget
|
|
58
|
+
* sooner, at about twice one writer's pend rate (measured in the plan stage of
|
|
59
|
+
* `slot-hold-for-an-aged-writer`). Accepted: the backoff bought that writer nothing either, it only
|
|
60
|
+
* delayed the same give-up.
|
|
61
|
+
*/
|
|
62
|
+
function retryBackoffMs(failures, confirmedLosses, latestConfirmed, config, rand) {
|
|
63
|
+
if (latestConfirmed && confirmedLosses >= SlotHoldAfterLosses) {
|
|
64
|
+
return 0;
|
|
65
|
+
}
|
|
66
|
+
return jitteredBackoffMs(failures - 1, config, rand);
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* Build one attempt: a tracker seeded with a COPY of the target's transforms, so the target is
|
|
70
|
+
* untouched whatever becomes of the attempt, with the log entry for `target.actions` appended at
|
|
71
|
+
* `rev` under `identity`, then the content declarations and the size check.
|
|
72
|
+
*
|
|
73
|
+
* The per-attempt tracker SHARES the target's pin store: it inherits the transforms by copy and
|
|
74
|
+
* never stages the data-block updates itself, so without the shared pins the digest pass could only
|
|
75
|
+
* describe bases still resident in the read cache. NOTE: an attempt that ends in a stale failure is
|
|
76
|
+
* abandoned WITHOUT reset(), so the log tail/header bases its append pinned stay in the shared
|
|
77
|
+
* store until the target tracker's next reset. Bounded and harmless — a few log blocks per
|
|
78
|
+
* attempt, capped by `maxAttempts`, each re-validated against the source generation before any use
|
|
79
|
+
* — but if an attempt ever grows a per-attempt footprint beyond the log blocks, reset the abandoned
|
|
80
|
+
* tracker on the stale-failure branch instead of letting the residue ride to the end of the write.
|
|
81
|
+
*
|
|
82
|
+
* The append is a fixed function of the write and `rev`: the timestamp is the identity's, and any
|
|
83
|
+
* data block the append has to mint takes the id `newDataBlockId` hands out — the caller's
|
|
84
|
+
* `Collection.logAppendBlockIds`, which replays the ids an earlier attempt at this revision minted.
|
|
85
|
+
*
|
|
86
|
+
* The declarations are computed AFTER the append so the log tail and header transforms the attempt
|
|
87
|
+
* just staged are digested too, and purely locally — an id whose base is not cached is omitted and
|
|
88
|
+
* falls back to corroboration on the member side. NOTE: recomputed from scratch on every attempt,
|
|
89
|
+
* so a write that loses N races pays N full hashing passes over its touched blocks. Unmeasured and
|
|
90
|
+
* cheap relative to the round trips it is retrying; if a high-contention write ever shows digest
|
|
91
|
+
* hashing in a profile, memoize per (id, staged ops).
|
|
92
|
+
*
|
|
93
|
+
* @throws BlockTooLargeError when a touched block would be left larger than one message can carry —
|
|
94
|
+
* before anything is sent, judged apart from the declaration (which never throws), and unretried by
|
|
95
|
+
* either write path, since a later attempt would leave the same block. */
|
|
96
|
+
export async function stageAttempt(collectionId, cache, target, identity, rev, newDataBlockId) {
|
|
97
|
+
const tracker = new Tracker(cache, copyTransforms(target.transforms), target.pins);
|
|
98
|
+
const collectionLog = await Log.open(tracker, collectionId, { newDataBlockId: newDataBlockId(tracker) });
|
|
99
|
+
if (!collectionLog) {
|
|
100
|
+
throw new Error(`Log not found for collection ${collectionId}`);
|
|
101
|
+
}
|
|
102
|
+
const added = await collectionLog.addActions([...target.actions], identity.actionId, rev, () => tracker.transformedBlockIds(), { timestamp: identity.timestamp });
|
|
103
|
+
const touched = await describeTouchedBlocks(tracker, tracker.transformedBlockIds());
|
|
104
|
+
const tooLarge = oversizedBlock(touched.bytes);
|
|
105
|
+
if (tooLarge)
|
|
106
|
+
throw tooLarge;
|
|
107
|
+
return {
|
|
108
|
+
tracker,
|
|
109
|
+
rev,
|
|
110
|
+
tailId: added.tailPath.block.header.id,
|
|
111
|
+
blockDigests: touched.digests,
|
|
112
|
+
// The base each update-only block's operations were computed against, for the pend (see
|
|
113
|
+
// `PendRequest.baseRevs`): the pinned revisions, which the caller re-judged before staging.
|
|
114
|
+
baseRevs: tracker.stagedBaseRevs(tracker.transformedBlockIds()),
|
|
115
|
+
};
|
|
116
|
+
}
|
|
117
|
+
/** Exactly what an attempt sends under `actionId`, for `Collection.retainInFlightAttempt` and for
|
|
118
|
+
* the write-ahead hook (`HeadCommitOptions.recordAttempt`): a refused commit is not proof nothing
|
|
119
|
+
* landed, and if the refresh that follows finds the attempt's own log entry these are the
|
|
120
|
+
* transforms that finish the action. The attempt's tracker is abandoned once this is taken, so its
|
|
121
|
+
* transforms are handed over as they are, uncopied.
|
|
122
|
+
* NOTE: the same object reaches the write-ahead hook and is retained for the re-send; nothing in
|
|
123
|
+
* the tree mutates it (a fold clones the inserts and applies the updates to the cache's own blocks),
|
|
124
|
+
* but a hook that mutated its argument would corrupt the re-send. If a hook ever needs to, copy
|
|
125
|
+
* here (`copyTransforms`) rather than at the hook. */
|
|
126
|
+
export function retainedAttempt(staged, actionId) {
|
|
127
|
+
return {
|
|
128
|
+
actionId,
|
|
129
|
+
rev: staged.rev,
|
|
130
|
+
transforms: staged.tracker.transforms,
|
|
131
|
+
tailId: staged.tailId,
|
|
132
|
+
...(staged.blockDigests === undefined ? {} : { blockDigests: staged.blockDigests }),
|
|
133
|
+
...baseRevsField(staged.baseRevs),
|
|
134
|
+
};
|
|
135
|
+
}
|
|
136
|
+
/**
|
|
137
|
+
* The inverse of {@link retainedAttempt}, for a head commit opened with `resume`
|
|
138
|
+
* (`HeadCommitOptions.resume`): the attempt an earlier cycle recorded, as a {@link StagedAttempt}
|
|
139
|
+
* that sends exactly what that cycle sent, while `rev` — the revision the next attempt would
|
|
140
|
+
* request — equals the recorded one; `undefined` otherwise, and the attempt is built as usual.
|
|
141
|
+
* The tracker is over the handle's read cache, with a COPY of the recorded transforms (a fold
|
|
142
|
+
* resets it and folds what it holds, and the record stays the caller's) and pins of its own, since
|
|
143
|
+
* it stages nothing.
|
|
144
|
+
*
|
|
145
|
+
* The recorded attempt IS the attempt that may have landed: it can sit on a minority of its cohort,
|
|
146
|
+
* hidden from the refresh by a coordinator lagging that cohort, and storage accepts a retry of one
|
|
147
|
+
* `(action id, revision)` as the same write, so anything but these transforms under that pair forks
|
|
148
|
+
* the block on the machines that hold the first (docs/offline-sync.md §Identity across attempts).
|
|
149
|
+
* Three departures from how an attempt is otherwise built are deliberate:
|
|
150
|
+
* - **Keyed on `resume`, not on the retained attempt.** Within one cycle a retry at an unchanged
|
|
151
|
+
* revision reuses the head tracker and the minted log block ids, so it is byte-identical already,
|
|
152
|
+
* and keeps the re-judging of its base pins before each attempt (`Collection.headTrackerFor`).
|
|
153
|
+
* The recorded attempt is re-sent as it was, unjudged: a base that moved under it is judged by
|
|
154
|
+
* storage's own base guard, which refuses it on every machine whose base moved — the exception
|
|
155
|
+
* `Collection.completeOwnEntry`'s re-send of a retained attempt already takes.
|
|
156
|
+
* - **No invented baseline.** A head tracker over a collection with no committed revision starts
|
|
157
|
+
* from the invented baseline so the header, log block and root ride in the head's commit; the
|
|
158
|
+
* recorded transforms already carry those inserts.
|
|
159
|
+
* - **Only equality switches it on.** A refresh that moves the revision past `attempt.rev` adopted a
|
|
160
|
+
* rival's entry there, which proves the recorded attempt lost at that revision, and the write is
|
|
161
|
+
* rebuilt at the higher one. A revision BELOW it is not reachable inside one process (the held
|
|
162
|
+
* revision never lowers); a new handle after a restart that reaches one has read a view behind the
|
|
163
|
+
* attempt, and the ordinary build handles it as it would without `resume` — the recorded revision
|
|
164
|
+
* is not adopted to get there.
|
|
165
|
+
*/
|
|
166
|
+
export function resumedAttempt(cache, attempt, rev) {
|
|
167
|
+
if (attempt === undefined || attempt.rev !== rev) {
|
|
168
|
+
return undefined;
|
|
169
|
+
}
|
|
170
|
+
return {
|
|
171
|
+
tracker: new Tracker(cache, copyTransforms(attempt.transforms)),
|
|
172
|
+
rev: attempt.rev,
|
|
173
|
+
tailId: attempt.tailId,
|
|
174
|
+
blockDigests: attempt.blockDigests,
|
|
175
|
+
baseRevs: attempt.baseRevs ?? {},
|
|
176
|
+
};
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* The retry accounting of one write's attempt cycle: how many consecutive attempts have been
|
|
180
|
+
* refused, what the responders confirmed, whether the refresh in between moved the collection, and
|
|
181
|
+
* who holds what the write has committed so far. One instance per write; the write path drives it
|
|
182
|
+
* in order — {@link beforeAttempt}, then either {@link recordRefusal} followed by
|
|
183
|
+
* {@link refreshUntilSettled}, or {@link recordCommit}.
|
|
184
|
+
*/
|
|
185
|
+
export class AttemptCycle {
|
|
186
|
+
collectionId;
|
|
187
|
+
instanceTag;
|
|
188
|
+
maxAttempts;
|
|
189
|
+
maxStalledAttempts;
|
|
190
|
+
backoff;
|
|
191
|
+
deadlineMs;
|
|
192
|
+
signal;
|
|
193
|
+
rand;
|
|
194
|
+
startedAt = Date.now();
|
|
195
|
+
// Count of consecutive stale failures that made no forward progress. Reset to 0 on every
|
|
196
|
+
// commit, so the cap bounds only a persistently-failing write — a legitimate large multi-batch
|
|
197
|
+
// sync (which iterates many times committing progress) never trips it.
|
|
198
|
+
consecutiveFailures = 0;
|
|
199
|
+
lastReason;
|
|
200
|
+
// Highest confirmed revision any responder has reported holding, accumulated with the
|
|
201
|
+
// codebase's single rule for picking among several candidates. Reported on the error, and
|
|
202
|
+
// the evidence the stall check reasons from.
|
|
203
|
+
lastStaleAt;
|
|
204
|
+
// Whether the failure most recently handled carried its OWN staleAt. A strike needs the
|
|
205
|
+
// responder to have re-confirmed the number this round, not merely an older observation
|
|
206
|
+
// left standing in `lastStaleAt`.
|
|
207
|
+
lastFailureConfirmedStaleAt = false;
|
|
208
|
+
// Refused attempts of this write that carried their own staleAt. Never reset: a member counts
|
|
209
|
+
// its stale refusals per action for the action's whole life, and this is the writer's view of
|
|
210
|
+
// that count (see retryBackoffMs).
|
|
211
|
+
confirmedLosses = 0;
|
|
212
|
+
// Consecutive refreshes that moved the requested revision nowhere at all while a confirmed
|
|
213
|
+
// revision stood at or above it.
|
|
214
|
+
consecutiveStalls = 0;
|
|
215
|
+
// The revision the PREVIOUS attempt would have requested, so the stall check can tell a
|
|
216
|
+
// refresh that moved nowhere from one that is still climbing toward the confirmed number.
|
|
217
|
+
previousRequestedRev;
|
|
218
|
+
/** Who holds what the write has committed so far. Stays `undefined` while nothing has been
|
|
219
|
+
* committed, which is also the answer when no attempt runs at all — a write with nothing staged
|
|
220
|
+
* writes nothing, and there is no durability to fabricate for it. Refused attempts never
|
|
221
|
+
* contribute: a refused attempt left nothing behind, so the answer is the committing one's. A
|
|
222
|
+
* write that commits more than once folds them with `mergeDurability`, whose scalar answer is
|
|
223
|
+
* the WEAKEST: one batch that only reached the writer makes the whole write only-on-the-writer,
|
|
224
|
+
* and reporting the last batch's class instead would show such a write as saved. */
|
|
225
|
+
durability;
|
|
226
|
+
constructor(collectionId, instanceTag, options) {
|
|
227
|
+
this.collectionId = collectionId;
|
|
228
|
+
this.instanceTag = instanceTag;
|
|
229
|
+
this.maxAttempts = options?.maxAttempts ?? DefaultMaxAttempts;
|
|
230
|
+
this.maxStalledAttempts = options?.maxStalledAttempts ?? DefaultMaxStalledAttempts;
|
|
231
|
+
this.backoff = {
|
|
232
|
+
baseMs: options?.baseBackoffMs ?? PendingRetryDelayMs,
|
|
233
|
+
capMs: options?.maxBackoffMs ?? DefaultMaxBackoffMs,
|
|
234
|
+
};
|
|
235
|
+
this.deadlineMs = options?.deadlineMs;
|
|
236
|
+
this.signal = options?.signal;
|
|
237
|
+
this.rand = options?.rand;
|
|
238
|
+
}
|
|
239
|
+
/** The aged retry priority for the next attempt, from the consecutive-failure count: a write
|
|
240
|
+
* that keeps losing concurrent races out-ranks fresh (priority-0) rivals in the cluster's
|
|
241
|
+
* `resolveRace` (fairness-only, capped at `MaxPriority`). A first attempt is priority 0, so the
|
|
242
|
+
* common pend is unchanged. */
|
|
243
|
+
priority() {
|
|
244
|
+
return clampPriority(this.consecutiveFailures);
|
|
245
|
+
}
|
|
246
|
+
/**
|
|
247
|
+
* The checks that run before an attempt is built: the abort signal, the wall-clock deadline, and
|
|
248
|
+
* the stall check. The deadline comes before the stall check deliberately: it is the documented
|
|
249
|
+
* outer bound, so a write that is both past it and stalled reports the deadline.
|
|
250
|
+
*
|
|
251
|
+
* The stall check asks: can the attempt about to run possibly differ from the one that just
|
|
252
|
+
* failed? Only when BOTH of these hold is the answer provably no:
|
|
253
|
+
*
|
|
254
|
+
* - `requestedRev` is at or below one a responder CONFIRMED is taken. A producer sets `staleAt`
|
|
255
|
+
* only after reading that revision as durably held by someone else out of its own storage,
|
|
256
|
+
* revisions are one per-collection counter that every commit touches, and a confirmed
|
|
257
|
+
* revision never becomes un-taken (invalidation takes a NEW slot). So the request is already
|
|
258
|
+
* lost before it is sent.
|
|
259
|
+
* - The refresh in between moved the collection nowhere. `advanceContext` never lowers the
|
|
260
|
+
* held revision, so "nowhere" is exactly `requestedRev` unchanged since the last attempt. A
|
|
261
|
+
* refresh that moved forward WITHOUT clearing the confirmed number is a collection still
|
|
262
|
+
* climbing (it read a replica that lags the holder — the same partial catch-up
|
|
263
|
+
* `reportShortfall` exists to report), and its next attempt is a genuinely different request
|
|
264
|
+
* that may yet win.
|
|
265
|
+
*
|
|
266
|
+
* This is NOT a second answer to "is this failure retryable?" — `isConflictFailure` remains the
|
|
267
|
+
* sole rule for that, untouched. It only ever stops a loop that rule had already decided to
|
|
268
|
+
* continue.
|
|
269
|
+
*
|
|
270
|
+
* @param requestedRev the revision the attempt would request (`Collection.getNextRev`).
|
|
271
|
+
* @param heldRev the revision the collection holds, for the stall report.
|
|
272
|
+
* @throws AbortError, {@link SyncRetryExhaustedError} (deadline), {@link SyncRevisionStalledError}. */
|
|
273
|
+
beforeAttempt(requestedRev, heldRev) {
|
|
274
|
+
if (this.signal?.aborted) {
|
|
275
|
+
throw makeAbortError(this.signal);
|
|
276
|
+
}
|
|
277
|
+
if (this.pastDeadline()) {
|
|
278
|
+
throw new SyncRetryExhaustedError(this.collectionId, this.consecutiveFailures, this.lastReason ?? 'deadline exceeded', this.lastStaleAt);
|
|
279
|
+
}
|
|
280
|
+
const refreshMoved = this.previousRequestedRev !== undefined && requestedRev > this.previousRequestedRev;
|
|
281
|
+
this.previousRequestedRev = requestedRev;
|
|
282
|
+
if (this.lastStaleAt === undefined) {
|
|
283
|
+
return;
|
|
284
|
+
}
|
|
285
|
+
if (requestedRev > this.lastStaleAt.rev || refreshMoved) {
|
|
286
|
+
// Either the refresh adopted a revision above the confirmed one — ordinary contention,
|
|
287
|
+
// where the rival's commit is exactly what we just read — or it made partial forward
|
|
288
|
+
// progress. Both mean the next attempt differs. Not a stall.
|
|
289
|
+
this.consecutiveStalls = 0;
|
|
290
|
+
}
|
|
291
|
+
else if (this.lastFailureConfirmedStaleAt) {
|
|
292
|
+
this.consecutiveStalls++;
|
|
293
|
+
if (log.enabled) {
|
|
294
|
+
log('collection:sync-stalled id=%s tag=%s heldRev=%s requestedRev=%d staleBlock=%s staleRev=%d strike=%d of=%d', this.collectionId, this.instanceTag, heldRev ?? 'none', requestedRev, this.lastStaleAt.blockId, this.lastStaleAt.rev, this.consecutiveStalls, this.maxStalledAttempts);
|
|
295
|
+
}
|
|
296
|
+
// Two strikes, not one: a legitimate loser can transiently read a view that has not yet
|
|
297
|
+
// caught up with the rival's commit, which looks identical for one round.
|
|
298
|
+
if (this.consecutiveStalls >= this.maxStalledAttempts) {
|
|
299
|
+
throw new SyncRevisionStalledError(this.collectionId, this.consecutiveFailures, this.lastStaleAt, requestedRev, heldRev, this.lastReason);
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
// Else: the responder told us nothing new this round. No strike, and no reset either — the
|
|
303
|
+
// budget stays bounded by maxAttempts.
|
|
304
|
+
}
|
|
305
|
+
/**
|
|
306
|
+
* Account for a refused attempt. The three refusals a retry can never get past are thrown by
|
|
307
|
+
* name, with nothing on the collection touched (the attempt ran on its own tracker), so the
|
|
308
|
+
* staged actions are still staged for a later write: an expiry, because the next attempt's
|
|
309
|
+
* expiration comes from the same clock; a promise shortfall, because every coordinator of the
|
|
310
|
+
* cohort meets the same silent members (only a pend answers this way, so nothing of the attempt
|
|
311
|
+
* was stored); a validity rejection, because the next attempt sends the same content to the same
|
|
312
|
+
* checks. Everything else is a stale failure counted against the no-progress budget, so a
|
|
313
|
+
* transactor that persistently rejects can no longer hold the collection latch forever.
|
|
314
|
+
*
|
|
315
|
+
* NOTE: an expiry refusing a commit SWEEP (`NetworkTransactor.commitTailThenSweep`) arrives after
|
|
316
|
+
* the log tail was stored, and no refresh follows this throw, so that attempt's log entry stays
|
|
317
|
+
* behind with none of its data — the state the budget-exhausted exit leaves too. Needs a sweep
|
|
318
|
+
* cohort whose clocks disagree while the tail's agree; tracked with the other leftover-entry
|
|
319
|
+
* exits in tickets/backlog/bug-a-refused-write-can-leave-its-log-entry-behind.
|
|
320
|
+
*
|
|
321
|
+
* NOTE: the budget also bounds the legitimate `pending`-wait case (retrying the same action while
|
|
322
|
+
* another commit is in flight), which used to retry indefinitely. Default 10 attempts ≈ 21s of
|
|
323
|
+
* exponential backoff. If a high-contention workload legitimately needs to wait longer for a
|
|
324
|
+
* pending commit to clear, raise maxAttempts for that caller.
|
|
325
|
+
*
|
|
326
|
+
* NOTE: no refresh follows the LAST budgeted attempt, so if that attempt's log tail landed nobody
|
|
327
|
+
* finds out: the caller gets plain exhaustion over a log that holds an entry for this write. The
|
|
328
|
+
* write is still never reported saved, which is the rule; what is lost is the more specific name
|
|
329
|
+
* (TornActionError). The leftover entry itself is tracked in
|
|
330
|
+
* tickets/backlog/bug-a-refused-write-can-leave-its-log-entry-behind.
|
|
331
|
+
*
|
|
332
|
+
* @throws TransactionExpiredError, PromiseShortfallError, ValidityRejectedError, SyncRetryExhaustedError */
|
|
333
|
+
recordRefusal(refusal) {
|
|
334
|
+
if (isExpiryFailure(refusal)) {
|
|
335
|
+
throw new TransactionExpiredError(refusal.expired);
|
|
336
|
+
}
|
|
337
|
+
if (isShortfallFailure(refusal)) {
|
|
338
|
+
throw new PromiseShortfallError(refusal.shortfall);
|
|
339
|
+
}
|
|
340
|
+
if (isRejectedFailure(refusal)) {
|
|
341
|
+
throw new ValidityRejectedError(refusal.rejected);
|
|
342
|
+
}
|
|
343
|
+
this.consecutiveFailures++;
|
|
344
|
+
this.lastReason = refusal.reason ?? this.lastReason;
|
|
345
|
+
// Highest-wins, not last-wins: the next request has to clear EVERY holder, so a later
|
|
346
|
+
// responder reporting a LOWER number understates the binding constraint. Same rule the
|
|
347
|
+
// producers and the transactor's aggregation already use.
|
|
348
|
+
this.lastStaleAt = highestStaleAt([this.lastStaleAt, refusal.staleAt]);
|
|
349
|
+
this.lastFailureConfirmedStaleAt = refusal.staleAt !== undefined;
|
|
350
|
+
if (this.lastFailureConfirmedStaleAt)
|
|
351
|
+
this.confirmedLosses++;
|
|
352
|
+
if (this.consecutiveFailures >= this.maxAttempts) {
|
|
353
|
+
throw new SyncRetryExhaustedError(this.collectionId, this.consecutiveFailures, this.lastReason, this.lastStaleAt);
|
|
354
|
+
}
|
|
355
|
+
}
|
|
356
|
+
/** Account for a commit — by an attempt, or by a refresh that finished the write's own entry,
|
|
357
|
+
* which is a commit too and is reported and counted exactly like one (see {@link durability}).
|
|
358
|
+
* Forward progress: the no-progress budget and the stall evidence start over. */
|
|
359
|
+
recordCommit(durability) {
|
|
360
|
+
this.durability = this.durability === undefined ? durability : mergeDurability([this.durability, durability]);
|
|
361
|
+
this.consecutiveFailures = 0;
|
|
362
|
+
this.lastReason = undefined;
|
|
363
|
+
this.lastStaleAt = undefined;
|
|
364
|
+
this.lastFailureConfirmedStaleAt = false;
|
|
365
|
+
this.consecutiveStalls = 0;
|
|
366
|
+
}
|
|
367
|
+
/**
|
|
368
|
+
* Back off, refresh, and keep refreshing while the refresh reports that this write's own
|
|
369
|
+
* half-landed action could not be finished YET. The write path must not fall through to a new
|
|
370
|
+
* attempt in that state: the action's log entry is already durable, and as soon as a refresh
|
|
371
|
+
* adopts a newer revision a new attempt appends a SECOND entry under the same action id — the
|
|
372
|
+
* duplicate `Collection.consumeOwnEntry` exists to prevent. (At an unchanged revision the rebuild
|
|
373
|
+
* is byte-identical — see `Collection.logAppendBlockIds` — so what is at stake is the second
|
|
374
|
+
* entry, not two versions of one tail block.) Each round is a failure against the same
|
|
375
|
+
* no-progress budget as a refused attempt, and the round that would spend the last of it is told
|
|
376
|
+
* so (`lastChance`), so it settles a half-landed write instead of asking for another round and
|
|
377
|
+
* the error that escapes says whether the write can still land. (A deadline cannot be foreseen
|
|
378
|
+
* the same way; a write given up on it escapes unsettled, as `final: false`.)
|
|
379
|
+
*
|
|
380
|
+
* The backoff before each round grows exponentially from the base delay up to the cap, with
|
|
381
|
+
* proportional random jitter so a herd of clients that lost the same race does not re-collide on
|
|
382
|
+
* the next tick (see utility/backoff.ts) — except once this write has lost to committed rivals
|
|
383
|
+
* often enough that a member holds the next slot for it ({@link retryBackoffMs}). The abortable
|
|
384
|
+
* sleep lets an aborted write reject promptly instead of finishing the sleep. A refresh that
|
|
385
|
+
* follows NO refused attempt — the one `Collection.commitHead` opens its cycle with — sleeps not
|
|
386
|
+
* at all: there is no race to space out.
|
|
387
|
+
* NOTE: the `missing`/`reason` conflict paths pay this backoff too (they used to retry with zero
|
|
388
|
+
* delay); that is what stops the persistent-`reason` hot spin. If a high-contention workload ever
|
|
389
|
+
* shows this base delay as recovery latency, lower baseBackoffMs for that caller rather than
|
|
390
|
+
* reintroducing the zero-delay retry.
|
|
391
|
+
*
|
|
392
|
+
* The highest revision a responder confirmed is taken rides out as the floor of the refresh's
|
|
393
|
+
* tail read, so a machine that has not caught up to it is not the last one asked (see
|
|
394
|
+
* `Collection.updateInternal`).
|
|
395
|
+
*
|
|
396
|
+
* @returns whether the refresh FINISHED the write's own log entry (`RefreshReport.ownEntryFinished`)
|
|
397
|
+
* — the write is saved and the entry consumed, whether or not the refresh learned who holds it.
|
|
398
|
+
* @throws TornActionError with any reason but an unsettled `completion-refused`, and that one too
|
|
399
|
+
* once the budget or the deadline is spent; whatever else the refresh throws. */
|
|
400
|
+
async refreshUntilSettled(refresh) {
|
|
401
|
+
// Whether the failure just handled was a loss to a rival already durably committed. Only the
|
|
402
|
+
// attempt's own refusal can say so; a refresh refused for a cause that can clear (below) is a
|
|
403
|
+
// race against something still in flight, and clears it.
|
|
404
|
+
let latestConfirmed = this.lastFailureConfirmedStaleAt;
|
|
405
|
+
for (;;) {
|
|
406
|
+
const delay = this.consecutiveFailures === 0
|
|
407
|
+
? 0
|
|
408
|
+
: retryBackoffMs(this.consecutiveFailures, this.confirmedLosses, latestConfirmed, this.backoff, this.rand);
|
|
409
|
+
await abortableDelay(delay, this.signal);
|
|
410
|
+
try {
|
|
411
|
+
const report = {};
|
|
412
|
+
await refresh(report, this.consecutiveFailures + 1 >= this.maxAttempts, this.lastStaleAt?.rev);
|
|
413
|
+
const completed = report.ownEntryFinished?.durability;
|
|
414
|
+
if (completed !== undefined) {
|
|
415
|
+
this.recordCommit(completed);
|
|
416
|
+
}
|
|
417
|
+
return report.ownEntryFinished !== undefined;
|
|
418
|
+
}
|
|
419
|
+
catch (err) {
|
|
420
|
+
if (!(err instanceof TornActionError) || err.reason !== 'completion-refused') {
|
|
421
|
+
throw err;
|
|
422
|
+
}
|
|
423
|
+
// Refused for a cause that can clear. The error already names the write as torn, which
|
|
424
|
+
// is the truth if the budget ends here — so it, not a plain exhaustion, is what escapes:
|
|
425
|
+
// the log holds an entry for a write that was not saved.
|
|
426
|
+
this.consecutiveFailures++;
|
|
427
|
+
this.lastReason = err.detail;
|
|
428
|
+
latestConfirmed = false;
|
|
429
|
+
if (this.consecutiveFailures >= this.maxAttempts || this.pastDeadline()) {
|
|
430
|
+
throw err;
|
|
431
|
+
}
|
|
432
|
+
}
|
|
433
|
+
}
|
|
434
|
+
}
|
|
435
|
+
pastDeadline() {
|
|
436
|
+
return this.deadlineMs !== undefined && Date.now() - this.startedAt >= this.deadlineMs;
|
|
437
|
+
}
|
|
438
|
+
}
|
|
439
|
+
//# sourceMappingURL=write-attempts.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"write-attempts.js","sourceRoot":"","sources":["../../../src/collection/write-attempts.ts"],"names":[],"mappings":"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"}
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { BlockId, CollectionHeaderBlock, CollectionId } from "../../index.js";
|
|
2
2
|
import type { KeyRange } from "../../btree/index.js";
|
|
3
|
+
import { ActionRefusedError } from "../../collection/struct.js";
|
|
3
4
|
export declare const TreeHeaderBlockType: string;
|
|
4
5
|
export type TreeCollectionHeaderBlock = CollectionHeaderBlock & {
|
|
5
6
|
rootId: BlockId;
|
|
@@ -27,6 +28,9 @@ export declare const rootId$: string;
|
|
|
27
28
|
* re-stage of a present key (a replay after a clean refresh) would refuse itself.
|
|
28
29
|
* - `unchanged` — see {@link TreeUnchangedGuard}: the only kind that says something must
|
|
29
30
|
* still BE here, rather than that nothing may be.
|
|
31
|
+
* - `absentOrEqual`, `unchangedOrEqual`, `unchangedOrAbsent` — the three ALREADY-APPLIED variants
|
|
32
|
+
* (see {@link TreeAlreadyAppliedGuard}): each accepts, and SKIPS the element, where a rival has
|
|
33
|
+
* already made exactly the change this element makes, instead of refusing it.
|
|
30
34
|
*
|
|
31
35
|
* MIXED VERSIONS: a peer running a build that predates guards destructures `[key, entry]`
|
|
32
36
|
* and ignores the third slot — its replays revert to today's silent overwrite. No version
|
|
@@ -39,7 +43,57 @@ export type TreeEntryGuard<TKey, TEntry = unknown> = {
|
|
|
39
43
|
} | {
|
|
40
44
|
kind: 'absentRange';
|
|
41
45
|
range: KeyRange<TKey>;
|
|
42
|
-
} | TreeUnchangedGuard<TEntry>;
|
|
46
|
+
} | TreeUnchangedGuard<TEntry> | TreeAlreadyAppliedGuard<TEntry>;
|
|
47
|
+
/**
|
|
48
|
+
* The three guard kinds that accept a row another writer already changed the same way, for the
|
|
49
|
+
* offline-sync queue's rebase of a queued entry (docs/offline-sync.md §Guards that make idempotent
|
|
50
|
+
* writes assured). Every guard above refuses when the row is not as the staged write found it, which
|
|
51
|
+
* includes the rival that made exactly the change this write makes: two machines marking one task
|
|
52
|
+
* done, two machines deleting one row. Each variant below has three outcomes, where its base kind has
|
|
53
|
+
* two — it ACCEPTS AND WRITES as the base kind does, it ACCEPTS AS ALREADY APPLIED and skips the
|
|
54
|
+
* element (the final state is the one the write intended), or it REFUSES with the base kind's error:
|
|
55
|
+
*
|
|
56
|
+
* | Kind | Element | Writes when | Skips as already applied when | Refuses with |
|
|
57
|
+
* |---|---|---|---|---|
|
|
58
|
+
* | `absentOrEqual` | upsert | the key is absent | the present entry equals the element's own `entry` | {@link TreeKeyTakenError}, as `absent` does |
|
|
59
|
+
* | `unchangedOrEqual` | upsert | the present entry equals `expected` | the present entry equals the element's own `entry` (checked second, so a no-op update whose `expected` equals its `entry` writes) | {@link TreeEntryChangedError} on absent or any other entry |
|
|
60
|
+
* | `unchangedOrAbsent` | delete | the present entry equals `expected` | the key is absent | {@link TreeEntryChangedError} on any other entry |
|
|
61
|
+
*
|
|
62
|
+
* "Equals" is `structuralEquals` in `packages/db-core/src/utility/structural-equals.ts`, the
|
|
63
|
+
* comparison `unchanged` uses, with the same JSON caveats {@link TreeUnchangedGuard} states. The
|
|
64
|
+
* post-image an upsert variant compares against is the element's own `entry`, not a second copy on
|
|
65
|
+
* the guard: the element already carries it, so the guard stays the size its base kind is.
|
|
66
|
+
*
|
|
67
|
+
* Kinds and elements: `unchangedOrAbsent` is meaningful only on a delete (on an upsert it would mean
|
|
68
|
+
* "resurrect the row"), and the two `…OrEqual` kinds only on an upsert (a delete has no `entry` to
|
|
69
|
+
* compare, and would be a no-op by construction). The handler narrows both ways at runtime: a delete
|
|
70
|
+
* carrying an upsert-only kind throws {@link TreeDeleteGuardKindError}, an upsert carrying the
|
|
71
|
+
* delete-only kind {@link TreeUpsertGuardKindError} — malformed actions, outside the refusal
|
|
72
|
+
* hierarchy, never ignored.
|
|
73
|
+
*
|
|
74
|
+
* Whether an element accepted as already applied changed anything is reported out of the handler
|
|
75
|
+
* as an `AlreadyAppliedTally` (`packages/db-core/src/collection/action.ts`), which the offline queue
|
|
76
|
+
* folds into the `effect` of its `committed` status.
|
|
77
|
+
*/
|
|
78
|
+
export type TreeAlreadyAppliedGuard<TEntry = unknown> = {
|
|
79
|
+
kind: 'absentOrEqual';
|
|
80
|
+
} | {
|
|
81
|
+
kind: 'unchangedOrEqual'; /** The entry image the staged write read, as stored. */
|
|
82
|
+
expected: TEntry;
|
|
83
|
+
} | {
|
|
84
|
+
kind: 'unchangedOrAbsent'; /** The entry image the staged delete read, as stored. */
|
|
85
|
+
expected: TEntry;
|
|
86
|
+
};
|
|
87
|
+
/** The kinds a {@link TreeUpsertElement} may carry: every kind but the delete-only
|
|
88
|
+
* `unchangedOrAbsent`. */
|
|
89
|
+
export type TreeUpsertGuard<TKey, TEntry = unknown> = Exclude<TreeEntryGuard<TKey, TEntry>, {
|
|
90
|
+
kind: 'unchangedOrAbsent';
|
|
91
|
+
}>;
|
|
92
|
+
/** The kinds a {@link TreeDeleteElement} may carry: the two that say something must still BE at the
|
|
93
|
+
* key — `unchanged`, and `unchangedOrAbsent`, which also accepts the key already gone. */
|
|
94
|
+
export type TreeDeleteGuard<TEntry = unknown> = TreeUnchangedGuard<TEntry> | Extract<TreeAlreadyAppliedGuard<TEntry>, {
|
|
95
|
+
kind: 'unchangedOrAbsent';
|
|
96
|
+
}>;
|
|
43
97
|
/**
|
|
44
98
|
* "The entry I am replacing must still be exactly the one I read" — the optimistic-concurrency
|
|
45
99
|
* (lost-update) guard, and the only {@link TreeEntryGuard} kind that also applies to a DELETE.
|
|
@@ -51,8 +105,9 @@ export type TreeEntryGuard<TKey, TEntry = unknown> = {
|
|
|
51
105
|
* exists, so re-applying it is never right: an upsert would resurrect a row a rival deleted, and
|
|
52
106
|
* a delete would be the second of two racing deletes. Refusing both is the optimistic answer —
|
|
53
107
|
* the writer read a row that is now gone, and an application-level retry then affects zero rows
|
|
54
|
-
* sequentially.
|
|
55
|
-
*
|
|
108
|
+
* sequentially. A delete that means "gone either way" carries `unchangedOrAbsent` instead, and an
|
|
109
|
+
* upsert that means "equal either way" carries `unchangedOrEqual` ({@link TreeAlreadyAppliedGuard});
|
|
110
|
+
* this kind's contract is not weakened for them.
|
|
56
111
|
*
|
|
57
112
|
* `expected` is the entry AS STORED, not a digest: a guard rides in the log beside its action
|
|
58
113
|
* under the same encoding entries already use, so a full copy round-trips by construction and no
|
|
@@ -69,21 +124,22 @@ export type TreeUnchangedGuard<TEntry = unknown> = {
|
|
|
69
124
|
/** The entry image the staged write read, as stored. */
|
|
70
125
|
expected: TEntry;
|
|
71
126
|
};
|
|
72
|
-
/** An element that writes (inserts or replaces) an entry.
|
|
73
|
-
* meaningful here. */
|
|
127
|
+
/** An element that writes (inserts or replaces) an entry. Every {@link TreeEntryGuard} kind but the
|
|
128
|
+
* delete-only `unchangedOrAbsent` is meaningful here ({@link TreeUpsertGuard}). */
|
|
74
129
|
export type TreeUpsertElement<TKey, TEntry> = [
|
|
75
130
|
key: TKey,
|
|
76
131
|
entry: TEntry,
|
|
77
|
-
guard?:
|
|
132
|
+
guard?: TreeUpsertGuard<TKey, TEntry>
|
|
78
133
|
];
|
|
79
|
-
/** An element that deletes the entry at a key. Only
|
|
80
|
-
* delete can act on — the other kinds all assert
|
|
81
|
-
* delete a no-op by construction. The handler rejects
|
|
82
|
-
* replayed log entry is deserialized data that this type
|
|
134
|
+
/** An element that deletes the entry at a key. Only the two kinds that say something must still BE
|
|
135
|
+
* at the key say anything a delete can act on ({@link TreeDeleteGuard}) — the other kinds all assert
|
|
136
|
+
* that nothing is present, which would make the delete a no-op by construction. The handler rejects
|
|
137
|
+
* any other kind at runtime too, since a replayed log entry is deserialized data that this type
|
|
138
|
+
* never policed. */
|
|
83
139
|
export type TreeDeleteElement<TKey, TEntry> = [
|
|
84
140
|
key: TKey,
|
|
85
141
|
entry?: undefined,
|
|
86
|
-
guard?:
|
|
142
|
+
guard?: TreeDeleteGuard<TEntry>
|
|
87
143
|
];
|
|
88
144
|
/** Represents a unit of change to a tree collection. */
|
|
89
145
|
export type TreeReplaceAction<TKey, TEntry> = (TreeUpsertElement<TKey, TEntry> | TreeDeleteElement<TKey, TEntry>)[];
|
|
@@ -104,10 +160,13 @@ export type TreeReplaceAction<TKey, TEntry> = (TreeUpsertElement<TKey, TEntry> |
|
|
|
104
160
|
* {@link TreeEntryChangedError} is a lost update (the bridge raises its
|
|
105
161
|
* `ConcurrentModificationError`, status code BUSY, which is not a constraint error). Catch
|
|
106
162
|
* this base to treat any guard refusal uniformly; catch a subclass to say which happened.
|
|
163
|
+
*
|
|
164
|
+
* It is the tree's {@link ActionRefusedError}, which is what the collection's segment-aware
|
|
165
|
+
* replay recognises (a refusal from a sealed segment is recorded against that segment rather
|
|
166
|
+
* than thrown — see `Collection.replayActions`); the classifier and the bridge keep matching
|
|
167
|
+
* this class, which the subclass relation leaves unchanged.
|
|
107
168
|
*/
|
|
108
|
-
export declare class TreeGuardRefusedError<TKey = unknown> extends
|
|
109
|
-
/** The collection whose tree refused the entry. */
|
|
110
|
-
readonly collectionId: CollectionId;
|
|
169
|
+
export declare class TreeGuardRefusedError<TKey = unknown> extends ActionRefusedError {
|
|
111
170
|
/** The key whose staged entry was refused. */
|
|
112
171
|
readonly key: TKey;
|
|
113
172
|
constructor(
|
|
@@ -184,21 +243,45 @@ export declare class TreeEntryChangedError<TKey = unknown, TEntry = unknown> ext
|
|
|
184
243
|
* present, which would make the delete a no-op by construction, so this is a malformed action —
|
|
185
244
|
* a caller bug, or a log entry written by a build whose element types disagree with this one.
|
|
186
245
|
* The handler raises it rather than ignoring the guard (the pre-guard behaviour) so a writer
|
|
187
|
-
* never believes an unenforceable guard is being enforced.
|
|
246
|
+
* never believes an unenforceable guard is being enforced. {@link TreeUpsertGuardKindError} is the
|
|
247
|
+
* upsert side of the same check.
|
|
188
248
|
*/
|
|
189
249
|
export declare class TreeDeleteGuardKindError<TKey = unknown> extends Error {
|
|
190
250
|
/** The collection whose tree rejected the element. */
|
|
191
251
|
readonly collectionId: CollectionId;
|
|
192
252
|
/** The key the malformed delete named. */
|
|
193
253
|
readonly key: TKey;
|
|
194
|
-
/** The `kind` that was carried; only `'unchanged'`
|
|
254
|
+
/** The `kind` that was carried; only `'unchanged'` and `'unchangedOrAbsent'` are meaningful on
|
|
255
|
+
* a delete. */
|
|
195
256
|
readonly guardKind: string;
|
|
196
257
|
constructor(
|
|
197
258
|
/** The collection whose tree rejected the element. */
|
|
198
259
|
collectionId: CollectionId,
|
|
199
260
|
/** The key the malformed delete named. */
|
|
200
261
|
key: TKey,
|
|
201
|
-
/** The `kind` that was carried; only `'unchanged'`
|
|
262
|
+
/** The `kind` that was carried; only `'unchanged'` and `'unchangedOrAbsent'` are meaningful on
|
|
263
|
+
* a delete. */
|
|
264
|
+
guardKind: string);
|
|
265
|
+
}
|
|
266
|
+
/**
|
|
267
|
+
* An UPSERT element carries the delete-only guard kind, `unchangedOrAbsent`: on an upsert it would
|
|
268
|
+
* mean "write the row whether or not a rival deleted it", which resurrects a row the staged write
|
|
269
|
+
* never meant to and so is a malformed action, not a concurrency refusal — the mirror of
|
|
270
|
+
* {@link TreeDeleteGuardKindError}, and like it deliberately not a {@link TreeGuardRefusedError}.
|
|
271
|
+
*/
|
|
272
|
+
export declare class TreeUpsertGuardKindError<TKey = unknown> extends Error {
|
|
273
|
+
/** The collection whose tree rejected the element. */
|
|
274
|
+
readonly collectionId: CollectionId;
|
|
275
|
+
/** The key the malformed upsert named. */
|
|
276
|
+
readonly key: TKey;
|
|
277
|
+
/** The `kind` that was carried. */
|
|
278
|
+
readonly guardKind: string;
|
|
279
|
+
constructor(
|
|
280
|
+
/** The collection whose tree rejected the element. */
|
|
281
|
+
collectionId: CollectionId,
|
|
282
|
+
/** The key the malformed upsert named. */
|
|
283
|
+
key: TKey,
|
|
284
|
+
/** The `kind` that was carried. */
|
|
202
285
|
guardKind: string);
|
|
203
286
|
}
|
|
204
287
|
//# sourceMappingURL=struct.d.ts.map
|