@optimystic/db-core 1.19.0 → 1.20.1
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,245 @@
|
|
|
1
|
+
import type { IBlock, BlockId, Action, ActionId, BlockContentDigests, BlockStore, Transforms, WriteDurability, WriteFailure } from "../index.js";
|
|
2
|
+
import type { BlockBaseRevs } from "../network/struct.js";
|
|
3
|
+
import { Tracker } from "../transform/tracker.js";
|
|
4
|
+
import type { BasePins } from "../transform/base-pins.js";
|
|
5
|
+
import type { CacheSource } from "../transform/cache-source.js";
|
|
6
|
+
import type { CollectionId, InFlightAttempt, SyncOptions } from "./struct.js";
|
|
7
|
+
import type { RefreshReport } from "./collection.js";
|
|
8
|
+
/** What a write is identified as on the wire: the action id every attempt of it reuses, and the
|
|
9
|
+
* log entry's timestamp. Both are minted once per WRITE, never per attempt, so a retry at the same
|
|
10
|
+
* revision appends the same entry (docs/internals.md, "A write's log append is a fixed function of
|
|
11
|
+
* the write and the revision it is requesting"). */
|
|
12
|
+
export type WriteIdentity = {
|
|
13
|
+
readonly actionId: ActionId;
|
|
14
|
+
readonly timestamp: number;
|
|
15
|
+
};
|
|
16
|
+
/** What one attempt is built from: the actions its log entry records, the transforms they produced
|
|
17
|
+
* over the committed state, and the bases those transforms were computed against. For a sync these
|
|
18
|
+
* are the open segment and the live tracker's; for a head commit the head segment and the head
|
|
19
|
+
* tracker's (see `Collection.commitHead`). */
|
|
20
|
+
export type AttemptTarget<TAction> = {
|
|
21
|
+
readonly actions: readonly Action<TAction>[];
|
|
22
|
+
readonly transforms: Transforms;
|
|
23
|
+
readonly pins: BasePins;
|
|
24
|
+
};
|
|
25
|
+
/** One attempt as it goes on the wire: a per-attempt tracker holding the target's transforms plus
|
|
26
|
+
* the log append, the revision it requests, and the declarations the pend and commit carry. */
|
|
27
|
+
export type StagedAttempt = {
|
|
28
|
+
readonly tracker: Tracker<IBlock>;
|
|
29
|
+
readonly rev: number;
|
|
30
|
+
/** The log tail block the entry was appended to, committed first. */
|
|
31
|
+
readonly tailId: BlockId;
|
|
32
|
+
readonly blockDigests: BlockContentDigests | undefined;
|
|
33
|
+
readonly baseRevs: BlockBaseRevs;
|
|
34
|
+
};
|
|
35
|
+
/**
|
|
36
|
+
* Build one attempt: a tracker seeded with a COPY of the target's transforms, so the target is
|
|
37
|
+
* untouched whatever becomes of the attempt, with the log entry for `target.actions` appended at
|
|
38
|
+
* `rev` under `identity`, then the content declarations and the size check.
|
|
39
|
+
*
|
|
40
|
+
* The per-attempt tracker SHARES the target's pin store: it inherits the transforms by copy and
|
|
41
|
+
* never stages the data-block updates itself, so without the shared pins the digest pass could only
|
|
42
|
+
* describe bases still resident in the read cache. NOTE: an attempt that ends in a stale failure is
|
|
43
|
+
* abandoned WITHOUT reset(), so the log tail/header bases its append pinned stay in the shared
|
|
44
|
+
* store until the target tracker's next reset. Bounded and harmless — a few log blocks per
|
|
45
|
+
* attempt, capped by `maxAttempts`, each re-validated against the source generation before any use
|
|
46
|
+
* — but if an attempt ever grows a per-attempt footprint beyond the log blocks, reset the abandoned
|
|
47
|
+
* tracker on the stale-failure branch instead of letting the residue ride to the end of the write.
|
|
48
|
+
*
|
|
49
|
+
* The append is a fixed function of the write and `rev`: the timestamp is the identity's, and any
|
|
50
|
+
* data block the append has to mint takes the id `newDataBlockId` hands out — the caller's
|
|
51
|
+
* `Collection.logAppendBlockIds`, which replays the ids an earlier attempt at this revision minted.
|
|
52
|
+
*
|
|
53
|
+
* The declarations are computed AFTER the append so the log tail and header transforms the attempt
|
|
54
|
+
* just staged are digested too, and purely locally — an id whose base is not cached is omitted and
|
|
55
|
+
* falls back to corroboration on the member side. NOTE: recomputed from scratch on every attempt,
|
|
56
|
+
* so a write that loses N races pays N full hashing passes over its touched blocks. Unmeasured and
|
|
57
|
+
* cheap relative to the round trips it is retrying; if a high-contention write ever shows digest
|
|
58
|
+
* hashing in a profile, memoize per (id, staged ops).
|
|
59
|
+
*
|
|
60
|
+
* @throws BlockTooLargeError when a touched block would be left larger than one message can carry —
|
|
61
|
+
* before anything is sent, judged apart from the declaration (which never throws), and unretried by
|
|
62
|
+
* either write path, since a later attempt would leave the same block. */
|
|
63
|
+
export declare function stageAttempt<TAction>(collectionId: CollectionId, cache: CacheSource<IBlock>, target: AttemptTarget<TAction>, identity: WriteIdentity, rev: number, newDataBlockId: (store: BlockStore<IBlock>) => () => BlockId): Promise<StagedAttempt>;
|
|
64
|
+
/** Exactly what an attempt sends under `actionId`, for `Collection.retainInFlightAttempt` and for
|
|
65
|
+
* the write-ahead hook (`HeadCommitOptions.recordAttempt`): a refused commit is not proof nothing
|
|
66
|
+
* landed, and if the refresh that follows finds the attempt's own log entry these are the
|
|
67
|
+
* transforms that finish the action. The attempt's tracker is abandoned once this is taken, so its
|
|
68
|
+
* transforms are handed over as they are, uncopied.
|
|
69
|
+
* NOTE: the same object reaches the write-ahead hook and is retained for the re-send; nothing in
|
|
70
|
+
* the tree mutates it (a fold clones the inserts and applies the updates to the cache's own blocks),
|
|
71
|
+
* but a hook that mutated its argument would corrupt the re-send. If a hook ever needs to, copy
|
|
72
|
+
* here (`copyTransforms`) rather than at the hook. */
|
|
73
|
+
export declare function retainedAttempt(staged: StagedAttempt, actionId: ActionId): InFlightAttempt;
|
|
74
|
+
/**
|
|
75
|
+
* The inverse of {@link retainedAttempt}, for a head commit opened with `resume`
|
|
76
|
+
* (`HeadCommitOptions.resume`): the attempt an earlier cycle recorded, as a {@link StagedAttempt}
|
|
77
|
+
* that sends exactly what that cycle sent, while `rev` — the revision the next attempt would
|
|
78
|
+
* request — equals the recorded one; `undefined` otherwise, and the attempt is built as usual.
|
|
79
|
+
* The tracker is over the handle's read cache, with a COPY of the recorded transforms (a fold
|
|
80
|
+
* resets it and folds what it holds, and the record stays the caller's) and pins of its own, since
|
|
81
|
+
* it stages nothing.
|
|
82
|
+
*
|
|
83
|
+
* The recorded attempt IS the attempt that may have landed: it can sit on a minority of its cohort,
|
|
84
|
+
* hidden from the refresh by a coordinator lagging that cohort, and storage accepts a retry of one
|
|
85
|
+
* `(action id, revision)` as the same write, so anything but these transforms under that pair forks
|
|
86
|
+
* the block on the machines that hold the first (docs/offline-sync.md §Identity across attempts).
|
|
87
|
+
* Three departures from how an attempt is otherwise built are deliberate:
|
|
88
|
+
* - **Keyed on `resume`, not on the retained attempt.** Within one cycle a retry at an unchanged
|
|
89
|
+
* revision reuses the head tracker and the minted log block ids, so it is byte-identical already,
|
|
90
|
+
* and keeps the re-judging of its base pins before each attempt (`Collection.headTrackerFor`).
|
|
91
|
+
* The recorded attempt is re-sent as it was, unjudged: a base that moved under it is judged by
|
|
92
|
+
* storage's own base guard, which refuses it on every machine whose base moved — the exception
|
|
93
|
+
* `Collection.completeOwnEntry`'s re-send of a retained attempt already takes.
|
|
94
|
+
* - **No invented baseline.** A head tracker over a collection with no committed revision starts
|
|
95
|
+
* from the invented baseline so the header, log block and root ride in the head's commit; the
|
|
96
|
+
* recorded transforms already carry those inserts.
|
|
97
|
+
* - **Only equality switches it on.** A refresh that moves the revision past `attempt.rev` adopted a
|
|
98
|
+
* rival's entry there, which proves the recorded attempt lost at that revision, and the write is
|
|
99
|
+
* rebuilt at the higher one. A revision BELOW it is not reachable inside one process (the held
|
|
100
|
+
* revision never lowers); a new handle after a restart that reaches one has read a view behind the
|
|
101
|
+
* attempt, and the ordinary build handles it as it would without `resume` — the recorded revision
|
|
102
|
+
* is not adopted to get there.
|
|
103
|
+
*/
|
|
104
|
+
export declare function resumedAttempt(cache: CacheSource<IBlock>, attempt: InFlightAttempt | undefined, rev: number): StagedAttempt | undefined;
|
|
105
|
+
/** The refresh a write path runs between attempts — `Collection.updateInternal`, under the
|
|
106
|
+
* collection latch, with the write's action marked in flight so the refresh recognises the write's
|
|
107
|
+
* own log entry. `lastChance` says the budget ends with this round; `tailFloor` is the highest
|
|
108
|
+
* revision a responder confirmed is taken, for the tail read. */
|
|
109
|
+
export type Refresh = (report: RefreshReport, lastChance: boolean, tailFloor: number | undefined) => Promise<void>;
|
|
110
|
+
/**
|
|
111
|
+
* The retry accounting of one write's attempt cycle: how many consecutive attempts have been
|
|
112
|
+
* refused, what the responders confirmed, whether the refresh in between moved the collection, and
|
|
113
|
+
* who holds what the write has committed so far. One instance per write; the write path drives it
|
|
114
|
+
* in order — {@link beforeAttempt}, then either {@link recordRefusal} followed by
|
|
115
|
+
* {@link refreshUntilSettled}, or {@link recordCommit}.
|
|
116
|
+
*/
|
|
117
|
+
export declare class AttemptCycle {
|
|
118
|
+
private readonly collectionId;
|
|
119
|
+
private readonly instanceTag;
|
|
120
|
+
private readonly maxAttempts;
|
|
121
|
+
private readonly maxStalledAttempts;
|
|
122
|
+
private readonly backoff;
|
|
123
|
+
private readonly deadlineMs;
|
|
124
|
+
private readonly signal;
|
|
125
|
+
private readonly rand;
|
|
126
|
+
private readonly startedAt;
|
|
127
|
+
private consecutiveFailures;
|
|
128
|
+
private lastReason;
|
|
129
|
+
private lastStaleAt;
|
|
130
|
+
private lastFailureConfirmedStaleAt;
|
|
131
|
+
private confirmedLosses;
|
|
132
|
+
private consecutiveStalls;
|
|
133
|
+
private previousRequestedRev;
|
|
134
|
+
/** Who holds what the write has committed so far. Stays `undefined` while nothing has been
|
|
135
|
+
* committed, which is also the answer when no attempt runs at all — a write with nothing staged
|
|
136
|
+
* writes nothing, and there is no durability to fabricate for it. Refused attempts never
|
|
137
|
+
* contribute: a refused attempt left nothing behind, so the answer is the committing one's. A
|
|
138
|
+
* write that commits more than once folds them with `mergeDurability`, whose scalar answer is
|
|
139
|
+
* the WEAKEST: one batch that only reached the writer makes the whole write only-on-the-writer,
|
|
140
|
+
* and reporting the last batch's class instead would show such a write as saved. */
|
|
141
|
+
durability: WriteDurability | undefined;
|
|
142
|
+
constructor(collectionId: CollectionId, instanceTag: string, options?: SyncOptions);
|
|
143
|
+
/** The aged retry priority for the next attempt, from the consecutive-failure count: a write
|
|
144
|
+
* that keeps losing concurrent races out-ranks fresh (priority-0) rivals in the cluster's
|
|
145
|
+
* `resolveRace` (fairness-only, capped at `MaxPriority`). A first attempt is priority 0, so the
|
|
146
|
+
* common pend is unchanged. */
|
|
147
|
+
priority(): number;
|
|
148
|
+
/**
|
|
149
|
+
* The checks that run before an attempt is built: the abort signal, the wall-clock deadline, and
|
|
150
|
+
* the stall check. The deadline comes before the stall check deliberately: it is the documented
|
|
151
|
+
* outer bound, so a write that is both past it and stalled reports the deadline.
|
|
152
|
+
*
|
|
153
|
+
* The stall check asks: can the attempt about to run possibly differ from the one that just
|
|
154
|
+
* failed? Only when BOTH of these hold is the answer provably no:
|
|
155
|
+
*
|
|
156
|
+
* - `requestedRev` is at or below one a responder CONFIRMED is taken. A producer sets `staleAt`
|
|
157
|
+
* only after reading that revision as durably held by someone else out of its own storage,
|
|
158
|
+
* revisions are one per-collection counter that every commit touches, and a confirmed
|
|
159
|
+
* revision never becomes un-taken (invalidation takes a NEW slot). So the request is already
|
|
160
|
+
* lost before it is sent.
|
|
161
|
+
* - The refresh in between moved the collection nowhere. `advanceContext` never lowers the
|
|
162
|
+
* held revision, so "nowhere" is exactly `requestedRev` unchanged since the last attempt. A
|
|
163
|
+
* refresh that moved forward WITHOUT clearing the confirmed number is a collection still
|
|
164
|
+
* climbing (it read a replica that lags the holder — the same partial catch-up
|
|
165
|
+
* `reportShortfall` exists to report), and its next attempt is a genuinely different request
|
|
166
|
+
* that may yet win.
|
|
167
|
+
*
|
|
168
|
+
* This is NOT a second answer to "is this failure retryable?" — `isConflictFailure` remains the
|
|
169
|
+
* sole rule for that, untouched. It only ever stops a loop that rule had already decided to
|
|
170
|
+
* continue.
|
|
171
|
+
*
|
|
172
|
+
* @param requestedRev the revision the attempt would request (`Collection.getNextRev`).
|
|
173
|
+
* @param heldRev the revision the collection holds, for the stall report.
|
|
174
|
+
* @throws AbortError, {@link SyncRetryExhaustedError} (deadline), {@link SyncRevisionStalledError}. */
|
|
175
|
+
beforeAttempt(requestedRev: number, heldRev: number | undefined): void;
|
|
176
|
+
/**
|
|
177
|
+
* Account for a refused attempt. The three refusals a retry can never get past are thrown by
|
|
178
|
+
* name, with nothing on the collection touched (the attempt ran on its own tracker), so the
|
|
179
|
+
* staged actions are still staged for a later write: an expiry, because the next attempt's
|
|
180
|
+
* expiration comes from the same clock; a promise shortfall, because every coordinator of the
|
|
181
|
+
* cohort meets the same silent members (only a pend answers this way, so nothing of the attempt
|
|
182
|
+
* was stored); a validity rejection, because the next attempt sends the same content to the same
|
|
183
|
+
* checks. Everything else is a stale failure counted against the no-progress budget, so a
|
|
184
|
+
* transactor that persistently rejects can no longer hold the collection latch forever.
|
|
185
|
+
*
|
|
186
|
+
* NOTE: an expiry refusing a commit SWEEP (`NetworkTransactor.commitTailThenSweep`) arrives after
|
|
187
|
+
* the log tail was stored, and no refresh follows this throw, so that attempt's log entry stays
|
|
188
|
+
* behind with none of its data — the state the budget-exhausted exit leaves too. Needs a sweep
|
|
189
|
+
* cohort whose clocks disagree while the tail's agree; tracked with the other leftover-entry
|
|
190
|
+
* exits in tickets/backlog/bug-a-refused-write-can-leave-its-log-entry-behind.
|
|
191
|
+
*
|
|
192
|
+
* NOTE: the budget also bounds the legitimate `pending`-wait case (retrying the same action while
|
|
193
|
+
* another commit is in flight), which used to retry indefinitely. Default 10 attempts ≈ 21s of
|
|
194
|
+
* exponential backoff. If a high-contention workload legitimately needs to wait longer for a
|
|
195
|
+
* pending commit to clear, raise maxAttempts for that caller.
|
|
196
|
+
*
|
|
197
|
+
* NOTE: no refresh follows the LAST budgeted attempt, so if that attempt's log tail landed nobody
|
|
198
|
+
* finds out: the caller gets plain exhaustion over a log that holds an entry for this write. The
|
|
199
|
+
* write is still never reported saved, which is the rule; what is lost is the more specific name
|
|
200
|
+
* (TornActionError). The leftover entry itself is tracked in
|
|
201
|
+
* tickets/backlog/bug-a-refused-write-can-leave-its-log-entry-behind.
|
|
202
|
+
*
|
|
203
|
+
* @throws TransactionExpiredError, PromiseShortfallError, ValidityRejectedError, SyncRetryExhaustedError */
|
|
204
|
+
recordRefusal(refusal: WriteFailure): void;
|
|
205
|
+
/** Account for a commit — by an attempt, or by a refresh that finished the write's own entry,
|
|
206
|
+
* which is a commit too and is reported and counted exactly like one (see {@link durability}).
|
|
207
|
+
* Forward progress: the no-progress budget and the stall evidence start over. */
|
|
208
|
+
recordCommit(durability: WriteDurability): void;
|
|
209
|
+
/**
|
|
210
|
+
* Back off, refresh, and keep refreshing while the refresh reports that this write's own
|
|
211
|
+
* half-landed action could not be finished YET. The write path must not fall through to a new
|
|
212
|
+
* attempt in that state: the action's log entry is already durable, and as soon as a refresh
|
|
213
|
+
* adopts a newer revision a new attempt appends a SECOND entry under the same action id — the
|
|
214
|
+
* duplicate `Collection.consumeOwnEntry` exists to prevent. (At an unchanged revision the rebuild
|
|
215
|
+
* is byte-identical — see `Collection.logAppendBlockIds` — so what is at stake is the second
|
|
216
|
+
* entry, not two versions of one tail block.) Each round is a failure against the same
|
|
217
|
+
* no-progress budget as a refused attempt, and the round that would spend the last of it is told
|
|
218
|
+
* so (`lastChance`), so it settles a half-landed write instead of asking for another round and
|
|
219
|
+
* the error that escapes says whether the write can still land. (A deadline cannot be foreseen
|
|
220
|
+
* the same way; a write given up on it escapes unsettled, as `final: false`.)
|
|
221
|
+
*
|
|
222
|
+
* The backoff before each round grows exponentially from the base delay up to the cap, with
|
|
223
|
+
* proportional random jitter so a herd of clients that lost the same race does not re-collide on
|
|
224
|
+
* the next tick (see utility/backoff.ts) — except once this write has lost to committed rivals
|
|
225
|
+
* often enough that a member holds the next slot for it ({@link retryBackoffMs}). The abortable
|
|
226
|
+
* sleep lets an aborted write reject promptly instead of finishing the sleep. A refresh that
|
|
227
|
+
* follows NO refused attempt — the one `Collection.commitHead` opens its cycle with — sleeps not
|
|
228
|
+
* at all: there is no race to space out.
|
|
229
|
+
* NOTE: the `missing`/`reason` conflict paths pay this backoff too (they used to retry with zero
|
|
230
|
+
* delay); that is what stops the persistent-`reason` hot spin. If a high-contention workload ever
|
|
231
|
+
* shows this base delay as recovery latency, lower baseBackoffMs for that caller rather than
|
|
232
|
+
* reintroducing the zero-delay retry.
|
|
233
|
+
*
|
|
234
|
+
* The highest revision a responder confirmed is taken rides out as the floor of the refresh's
|
|
235
|
+
* tail read, so a machine that has not caught up to it is not the last one asked (see
|
|
236
|
+
* `Collection.updateInternal`).
|
|
237
|
+
*
|
|
238
|
+
* @returns whether the refresh FINISHED the write's own log entry (`RefreshReport.ownEntryFinished`)
|
|
239
|
+
* — the write is saved and the entry consumed, whether or not the refresh learned who holds it.
|
|
240
|
+
* @throws TornActionError with any reason but an unsettled `completion-refused`, and that one too
|
|
241
|
+
* once the budget or the deadline is spent; whatever else the refresh throws. */
|
|
242
|
+
refreshUntilSettled(refresh: Refresh): Promise<boolean>;
|
|
243
|
+
private pastDeadline;
|
|
244
|
+
}
|
|
245
|
+
//# sourceMappingURL=write-attempts.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"write-attempts.d.ts","sourceRoot":"","sources":["../../../src/collection/write-attempts.ts"],"names":[],"mappings":"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"}
|