@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
|
@@ -1,33 +1,17 @@
|
|
|
1
|
-
import type { IBlock, Action, ActionType, ActionHandler, BlockId, ITransactor, BlockStore, Transforms, ActionId
|
|
1
|
+
import type { IBlock, Action, ActionType, ActionHandler, BlockId, ITransactor, BlockStore, Transforms, ActionId } from "../index.js";
|
|
2
2
|
import { Tracker } from "../transform/tracker.js";
|
|
3
3
|
import type { BasePins } from "../transform/base-pins.js";
|
|
4
4
|
import { CacheSource } from "../transform/cache-source.js";
|
|
5
|
-
import type { BlockBaseRevs } from "../network/struct.js";
|
|
6
5
|
import { TransactorSource } from "../transactor/transactor-source.js";
|
|
7
6
|
import { BlockFloors } from "../transactor/block-floors.js";
|
|
8
7
|
import type { WriteDurability } from "../network/struct.js";
|
|
9
|
-
import type { CollectionId, CommittedTail, CommittedTailAnswer, CommittedTailQuery, ICollection, SyncOptions } from "./index.js";
|
|
10
|
-
import
|
|
8
|
+
import type { CollectionId, CommittedTail, CommittedTailAnswer, CommittedTailQuery, HeadCommitOptions, ICollection, InFlightAttempt, InFlightCycle, OpenHeadCommitOptions, SyncOptions } from "./index.js";
|
|
9
|
+
import { ActionRefusedError } from "./struct.js";
|
|
10
|
+
import type { EntryId } from "./segments.js";
|
|
11
|
+
import type { ActionContext, ActionRev, AlreadyAppliedTally } from "./action.js";
|
|
12
|
+
import type { WriteIdentity } from "./write-attempts.js";
|
|
13
|
+
import type { HeadCommitHandle } from "./head-commit.js";
|
|
11
14
|
import type { ReadDependency } from "../transaction/transaction.js";
|
|
12
|
-
/** Exactly what one failed write attempt sent to the transactor — enough to send the same thing
|
|
13
|
-
* again. Retained by {@link Collection.retainInFlightAttempt} so that a refresh which then finds
|
|
14
|
-
* this attempt's own log entry can land the blocks the attempt left behind, at the same action id
|
|
15
|
-
* and revision (see {@link Collection.completeOwnEntry}). */
|
|
16
|
-
export type InFlightAttempt = {
|
|
17
|
-
/** The revision the attempt's log entry was stamped with, and pended and committed at. */
|
|
18
|
-
rev: number;
|
|
19
|
-
/** Every transform the attempt pended — the log blocks included. The caller hands over a copy
|
|
20
|
-
* it will not mutate; the collection keeps it as given. */
|
|
21
|
-
transforms: Transforms;
|
|
22
|
-
/** The attempt's log tail block, committed first. */
|
|
23
|
-
tailId: BlockId;
|
|
24
|
-
/** The per-block content declarations the attempt's commit carried, if any. */
|
|
25
|
-
blockDigests?: BlockContentDigests;
|
|
26
|
-
/** The per-block bases the attempt's pend carried, if any (see `PendRequest.baseRevs`). Kept
|
|
27
|
-
* with the transforms because they describe them: a re-send of these operations must name the
|
|
28
|
-
* same bases they were computed against. */
|
|
29
|
-
baseRevs?: BlockBaseRevs;
|
|
30
|
-
};
|
|
31
15
|
/** What one refresh ({@link Collection.refreshInFlight}, and the refresh inside a sync) found out
|
|
32
16
|
* about the write in flight on the instance's behalf. The caller hands in an empty report and the
|
|
33
17
|
* refresh fills it in AS IT GOES, rather than returning it at the end, so a refresh that throws
|
|
@@ -50,7 +34,10 @@ export type RefreshReport = {
|
|
|
50
34
|
};
|
|
51
35
|
};
|
|
52
36
|
export type CollectionInitOptions<TAction> = {
|
|
53
|
-
|
|
37
|
+
/** One handler per action type. A handler may answer what the action accepted as already applied
|
|
38
|
+
* ({@link AlreadyAppliedTally}); one that answers nothing counts as the zero tally, so a collection
|
|
39
|
+
* type with no such notion returns nothing. */
|
|
40
|
+
modules: Record<ActionType, ActionHandler<TAction, AlreadyAppliedTally | void>>;
|
|
54
41
|
createHeaderBlock: (id: BlockId, store: BlockStore<IBlock>) => IBlock;
|
|
55
42
|
/** Called for each local action that is potentially in conflict with a remote action.
|
|
56
43
|
* @param action - The local action to check
|
|
@@ -60,6 +47,14 @@ export type CollectionInitOptions<TAction> = {
|
|
|
60
47
|
* the conflict replay), or undefined to discard this action
|
|
61
48
|
*/
|
|
62
49
|
filterConflict?: (action: Action<TAction>, potential: Action<TAction>[]) => Action<TAction> | undefined;
|
|
50
|
+
/** Called once per refusal of a SEALED segment discovered by a replay (see
|
|
51
|
+
* {@link Collection.replayActions}): the segment's entry id and the handler's refusal. Called
|
|
52
|
+
* synchronously from inside the replay, under the collection latch, so it MUST NOT call a
|
|
53
|
+
* latched method of this collection ({@link Collection.update}, {@link Collection.dropSealed},
|
|
54
|
+
* {@link Collection.sync}, …) synchronously — the latch is non-reentrant and that would
|
|
55
|
+
* deadlock. The queue schedules its reaction instead. A throw out of the callback is caught and
|
|
56
|
+
* logged (`collection:refusal-callback-threw`), never allowed to abort the replay. */
|
|
57
|
+
onSealedRefused?: (entryId: EntryId, error: ActionRefusedError) => void;
|
|
63
58
|
};
|
|
64
59
|
/** Options for building a committed read view (see {@link Collection.createReadTracker}
|
|
65
60
|
* and `Tree.readView`). */
|
|
@@ -92,8 +87,17 @@ export interface CollectionSnapshot<TAction> {
|
|
|
92
87
|
* were not built on. Absent on a snapshot built by hand; such a restore keeps whatever pins
|
|
93
88
|
* the tracker holds for the restored ids. */
|
|
94
89
|
pins?: BasePins;
|
|
95
|
-
/**
|
|
90
|
+
/** The OPEN segment's actions at snapshot time (see {@link SegmentList}). Sealed segments are
|
|
91
|
+
* not captured as actions — their effects are in `transforms`, which is what a committed read
|
|
92
|
+
* view built from this snapshot must include — and a restore never puts one back: whether it
|
|
93
|
+
* reinstates `transforms` verbatim or rebuilds the tracker from the sealed segments as they are
|
|
94
|
+
* then is decided by {@link sealedVersion} (see {@link Collection.restorePending}). */
|
|
96
95
|
pending: Action<TAction>[];
|
|
96
|
+
/** {@link SegmentList.version} at capture: a restore that finds the sealed list changed since —
|
|
97
|
+
* a segment sealed, dropped or refused while the snapshot was outstanding — replays rather than
|
|
98
|
+
* reinstating `transforms`, which would put a dropped segment's effects back. Absent on a
|
|
99
|
+
* snapshot built by hand, which reads as "unchanged". */
|
|
100
|
+
sealedVersion?: number;
|
|
97
101
|
/** The committed boundary (action context) the staged state sat on when captured.
|
|
98
102
|
* `undefined` for a collection with no committed revision yet (an invented
|
|
99
103
|
* collection whose header/root still live in the tracker). A read view built
|
|
@@ -116,12 +120,27 @@ export declare class Collection<TAction> implements ICollection<TAction> {
|
|
|
116
120
|
* {@link BlockFloors}). */
|
|
117
121
|
private readonly floors;
|
|
118
122
|
private readonly filterConflict?;
|
|
123
|
+
/** See {@link CollectionInitOptions.onSealedRefused}. */
|
|
124
|
+
private readonly onSealedRefused?;
|
|
119
125
|
/** Short random tag naming THIS instance (see {@link newInstanceTag}). Open paths generate
|
|
120
126
|
* it BEFORE construction (so pre-construction diagnostics such as attachToLog can carry it);
|
|
121
127
|
* the default covers direct construction in tests. */
|
|
122
128
|
readonly instanceTag: string;
|
|
123
|
-
|
|
129
|
+
/** The staged actions: sealed segments, one per queued entry, ahead of the open segment the
|
|
130
|
+
* current transaction stages into (see {@link SegmentList}). While nothing is sealed this is
|
|
131
|
+
* exactly the one pending list it replaced, and every path behaves as it did then. */
|
|
132
|
+
private readonly segments;
|
|
124
133
|
private readonly latchId;
|
|
134
|
+
/** The transforms an INVENTED collection starts from — its header, its empty log block and (for
|
|
135
|
+
* a tree) its empty root, as {@link createOrOpen}'s create branch staged them. A replay resets
|
|
136
|
+
* the tracker to a copy of this, rather than to empty, for as long as no committed revision has
|
|
137
|
+
* been adopted: those blocks are then nowhere but the tracker, and resetting to empty would drop
|
|
138
|
+
* them and leave the collection unreadable (the hazard {@link mustReplay} and
|
|
139
|
+
* {@link snapshotPending} describe). Never cleared — it is read only while
|
|
140
|
+
* `source.actionContext` is undefined, and once a context is adopted the blocks are in storage
|
|
141
|
+
* and the empty reset is the right one. `undefined` for a collection opened over a committed
|
|
142
|
+
* header, which never replays from a baseline. */
|
|
143
|
+
private inventedBaseline?;
|
|
125
144
|
/** The action id of a write currently in flight ON THIS INSTANCE'S BEHALF, or `undefined`
|
|
126
145
|
* outside a write. Read by {@link updateInternal}: if the committed log now carries an entry
|
|
127
146
|
* under this id, that action's LOG TAIL landed despite the failure answer that sent us back here
|
|
@@ -170,19 +189,46 @@ export declare class Collection<TAction> implements ICollection<TAction> {
|
|
|
170
189
|
* Only the latest attempt is kept. An own entry can only be visible at the revision of an
|
|
171
190
|
* attempt whose tail landed, and a later attempt at a DIFFERENT revision is only made after a
|
|
172
191
|
* refresh adopted somebody else's entry at the earlier one — which is proof the earlier tail did
|
|
173
|
-
* not land. {@link completeOwnEntry} still checks the revision and refuses on a mismatch.
|
|
192
|
+
* not land. {@link completeOwnEntry} still checks the revision and refuses on a mismatch.
|
|
193
|
+
*
|
|
194
|
+
* A head commit may be opened with one already in hand ({@link openHeadCommit}'s `resume`): the
|
|
195
|
+
* attempt an earlier cycle under the same action id recorded through `HeadCommitOptions.recordAttempt`
|
|
196
|
+
* before sending it, which the cycle's opening refresh can then finish from. */
|
|
174
197
|
private inFlightAttempt?;
|
|
175
198
|
/** The log data-block ids the append of the action marked in {@link inFlightActionId} has
|
|
176
199
|
* minted, in the order it minted them, together with the revision they were minted for. Set and
|
|
177
200
|
* read by {@link logAppendBlockIds}, cleared with the rest of the in-flight state by
|
|
178
201
|
* {@link beginInFlightAction} and its disposer. */
|
|
179
202
|
private mintedLogBlockIds?;
|
|
203
|
+
/** What the cycle marked in {@link inFlightActionId} asked of every send it makes
|
|
204
|
+
* ({@link InFlightCycle}) — read by {@link send} and by the re-send {@link completeOwnEntry} makes
|
|
205
|
+
* to finish a torn attempt, so neither needs it threaded through. Set by
|
|
206
|
+
* {@link beginInFlightAction} and cleared by its disposer. */
|
|
207
|
+
private inFlightCycle;
|
|
208
|
+
/** The head commit running on this instance ({@link openHeadCommit}), for the whole cycle — set and
|
|
209
|
+
* cleared beside {@link inFlightActionId}: the sealed segment it is committing, and the hook told
|
|
210
|
+
* what that segment accepted as already applied when it is dropped as committed
|
|
211
|
+
* ({@link HeadCommitOptions.onCommittedHead}). Read by {@link consumeOwnEntry}: the entry a head
|
|
212
|
+
* commit's own refresh finds under the in-flight action id records the HEAD segment's actions, not
|
|
213
|
+
* the open segment's, so consuming it removes that segment — and reports it through the hook, as
|
|
214
|
+
* the handle's `fold` does. */
|
|
215
|
+
private headCommit?;
|
|
216
|
+
/** Set only while a head commit has RELEASED the collection latch for its one network round trip
|
|
217
|
+
* ({@link HeadCommitHandle.release}), and cleared the moment it is retaken, so anything that runs under the
|
|
218
|
+
* latch in that window can tell. Two things must: a refresh ({@link updateInternal}) that walks
|
|
219
|
+
* into the in-flight entry returns without adopting it, since it can neither finish it as the
|
|
220
|
+
* write's own (nothing failed, nothing is retained) nor replay it as a stranger's (that would
|
|
221
|
+
* re-stage the head over state that already contains it); and {@link dropSealed} refuses to drop
|
|
222
|
+
* the segment the commit is carrying. A second {@link commitHead} meets it as its `in-flight`
|
|
223
|
+
* precondition. Gated on THIS field, not on {@link inFlightActionId}: the head commit's own
|
|
224
|
+
* refreshes run with it cleared and must take the own-entry path. */
|
|
225
|
+
private headInFlight?;
|
|
180
226
|
/** The log tail block id the most recent header read named. A refresh asks for this block in the
|
|
181
227
|
* same request as the header ({@link readLogEnds}): the tail id only changes when the tail block
|
|
182
228
|
* fills, so an idle refresh is one request rather than two. A stale value costs one extra request
|
|
183
229
|
* and nothing else. */
|
|
184
230
|
private logTailId?;
|
|
185
|
-
protected constructor(id: CollectionId, transactor: ITransactor, handlers: Record<ActionType, ActionHandler<TAction>>, source: TransactorSource<IBlock>,
|
|
231
|
+
protected constructor(id: CollectionId, transactor: ITransactor, handlers: Record<ActionType, ActionHandler<TAction, AlreadyAppliedTally | void>>, source: TransactorSource<IBlock>,
|
|
186
232
|
/** Cache of unmodified blocks from the source */
|
|
187
233
|
sourceCache: CacheSource<IBlock>,
|
|
188
234
|
/** Tracked Changes */
|
|
@@ -191,6 +237,8 @@ export declare class Collection<TAction> implements ICollection<TAction> {
|
|
|
191
237
|
* {@link updateInternal}, and shared with every read source this handle builds (see
|
|
192
238
|
* {@link BlockFloors}). */
|
|
193
239
|
floors: BlockFloors, filterConflict?: ((action: Action<TAction>, potential: Action<TAction>[]) => Action<TAction> | undefined) | undefined,
|
|
240
|
+
/** See {@link CollectionInitOptions.onSealedRefused}. */
|
|
241
|
+
onSealedRefused?: ((entryId: EntryId, error: ActionRefusedError) => void) | undefined,
|
|
194
242
|
/** Short random tag naming THIS instance (see {@link newInstanceTag}). Open paths generate
|
|
195
243
|
* it BEFORE construction (so pre-construction diagnostics such as attachToLog can carry it);
|
|
196
244
|
* the default covers direct construction in tests. */
|
|
@@ -243,10 +291,12 @@ export declare class Collection<TAction> implements ICollection<TAction> {
|
|
|
243
291
|
* a poll of many collections whose logs stayed on their blocks is one request, however many it
|
|
244
292
|
* names; the per-block judgement is {@link readLogEnds}'s, through the same helpers.
|
|
245
293
|
*
|
|
246
|
-
* A
|
|
247
|
-
*
|
|
248
|
-
*
|
|
249
|
-
*
|
|
294
|
+
* A block no coordinator answered comes back flagged and fails only its own collection, through
|
|
295
|
+
* the per-block judgement. A request that throws as a whole — `NetworkTransactor.get` does when a
|
|
296
|
+
* coordinator's answer leaves a block out — is not every collection's failure either:
|
|
297
|
+
* {@link readAttributed} then reads each block alone and only the collections whose blocks failed
|
|
298
|
+
* report an error. That fallback costs what reading each collection separately costs, and only
|
|
299
|
+
* when a request fails. */
|
|
250
300
|
static readCommittedTails(transactor: ITransactor, queries: ReadonlyArray<CommittedTailQuery>): Promise<Map<CollectionId, CommittedTailAnswer>>;
|
|
251
301
|
/** The per-instance read wiring every open path needs, plus the collection's log ends — the
|
|
252
302
|
* header, then the log tail block it names — read by {@link readLogEnds}, the reader every
|
|
@@ -261,7 +311,8 @@ export declare class Collection<TAction> implements ICollection<TAction> {
|
|
|
261
311
|
* first read of it through the handle's cache now records, at the revision it was served at
|
|
262
312
|
* (see {@link attachToLog}). */
|
|
263
313
|
private static probeHeader;
|
|
264
|
-
/** A new handle's floors: none yet (
|
|
314
|
+
/** A new handle's floors: none yet (an open raises them from its log tail,
|
|
315
|
+
* {@link floorTailEntries}), wired to report every below-floor
|
|
265
316
|
* answer any of the handle's read sources receives. The line is the only trace such an answer
|
|
266
317
|
* leaves — the read itself succeeds (see the accepted-tradeoff NOTE at
|
|
267
318
|
* `TransactorSource.mayRetain`) — so repeated lines for one block with `servedRev` short of
|
|
@@ -274,6 +325,23 @@ export declare class Collection<TAction> implements ICollection<TAction> {
|
|
|
274
325
|
* declines to keep is re-read through the tracker/cache, so it can disagree with the probe when
|
|
275
326
|
* storage is flaky mid-open.) */
|
|
276
327
|
private static attachToLog;
|
|
328
|
+
/** Floor every block an action entry in the opened log's tail block names, at that entry's
|
|
329
|
+
* revision — what a refresh's walk does for the entries it walks ({@link raiseFloors}), for the
|
|
330
|
+
* entries an open has read but does not walk.
|
|
331
|
+
*
|
|
332
|
+
* An open adopts the revision the tail names, then reads each block it needs for the first time.
|
|
333
|
+
* When the answering repo's copy of such a block is older than an entry the tail holds — a node
|
|
334
|
+
* whose crash kept a commit's log tail but lost its other blocks within the store's durability
|
|
335
|
+
* window, or a coordinator that missed the commit — nothing else tells the read so, and the
|
|
336
|
+
* repo serves its held copy (a held block's first read after a restart is answered locally while
|
|
337
|
+
* the consult runs behind it). The handle then shows, say, a table row whose index entry is
|
|
338
|
+
* missing. With the floor, the read carries the revision the tail proves, so the repo consults
|
|
339
|
+
* its cohort before answering and the transactor re-asks another machine for an answer still
|
|
340
|
+
* below it (see {@link BlockFloors}).
|
|
341
|
+
*
|
|
342
|
+
* Only the tail block's entries: they are what the open read, and they hold the newest commits —
|
|
343
|
+
* the ones a durability window can tear. Invalidation entries set no floor, as on a refresh. */
|
|
344
|
+
private static floorTailEntries;
|
|
277
345
|
/** Adopt a freshly-read action context WITHOUT ever lowering the revision already held.
|
|
278
346
|
*
|
|
279
347
|
* The revision a collection last committed at is knowledge it earned; a read that found
|
|
@@ -388,6 +456,13 @@ export declare class Collection<TAction> implements ICollection<TAction> {
|
|
|
388
456
|
act(...actions: Action<TAction>[]): Promise<void>;
|
|
389
457
|
private actInternal;
|
|
390
458
|
private internalTransact;
|
|
459
|
+
/** Run `actions` through their handlers over `tracker` as ONE atomic unit: a throw from any
|
|
460
|
+
* handler leaves none of their writes staged. The live tracker's path ({@link internalTransact})
|
|
461
|
+
* and a head commit's tracker ({@link buildHeadTracker}) share it.
|
|
462
|
+
*
|
|
463
|
+
* @returns the sum of what the handlers accepted as already applied ({@link AlreadyAppliedTally});
|
|
464
|
+
* a handler that answers nothing adds the zero tally. */
|
|
465
|
+
private stageInto;
|
|
391
466
|
/** Load external changes and update our context to the latest log revision - resolve any conflicts with our pending actions. */
|
|
392
467
|
update(): Promise<void>;
|
|
393
468
|
/** The refresh `TransactionCoordinator.commit` runs between attempts: exactly {@link update},
|
|
@@ -493,27 +568,64 @@ export declare class Collection<TAction> implements ICollection<TAction> {
|
|
|
493
568
|
* {@link completeOwnEntry} has returned for this entry — the entry alone is not proof the write
|
|
494
569
|
* is saved.
|
|
495
570
|
*
|
|
496
|
-
* `
|
|
497
|
-
* actions are therefore the LEADING `entry.actions.length` items of
|
|
498
|
-
* staged since is behind them, because {@link actInternal}
|
|
499
|
-
* {@link syncInternal} nothing can even be staged mid-cycle (`act()` shares the
|
|
500
|
-
* latch); under `TransactionCoordinator.commit` the mark spans a latch-free
|
|
501
|
-
* window, so an `act()` there CAN grow
|
|
502
|
-
* right.
|
|
503
|
-
*
|
|
504
|
-
*
|
|
505
|
-
*
|
|
506
|
-
*
|
|
507
|
-
*
|
|
571
|
+
* A whole-collection write (`sync`) wrote exactly the snapshot of the OPEN segment under this
|
|
572
|
+
* action id, and the entry's actions are therefore the LEADING `entry.actions.length` items of
|
|
573
|
+
* the open segment — anything staged since is behind them, because {@link actInternal}
|
|
574
|
+
* appends. Under {@link syncInternal} nothing can even be staged mid-cycle (`act()` shares the
|
|
575
|
+
* collection latch); under `TransactionCoordinator.commit` the mark spans a latch-free
|
|
576
|
+
* inter-attempt window, so an `act()` there CAN grow the open segment — still only at the
|
|
577
|
+
* tail, so the slice stays right. No sealed segment can exist for such a write: every
|
|
578
|
+
* whole-collection path refuses while one does ({@link SealedSegmentsError}).
|
|
579
|
+
*
|
|
580
|
+
* A head commit ({@link commitHead}, which marks {@link headCommit} for its cycle) wrote the
|
|
581
|
+
* HEAD sealed segment's actions, so its entry is consumed by removing that segment — the open
|
|
582
|
+
* segment, which may have grown while the commit was on the network, is untouched. The sealed
|
|
583
|
+
* segments behind the head are never touched by either arm.
|
|
584
|
+
*
|
|
585
|
+
* The guards are the load-bearing part: `slice` fails SILENTLY if the open correspondence ever
|
|
586
|
+
* breaks, dropping actions that were never committed, so an entry longer than the open segment
|
|
587
|
+
* throws instead of losing work, and an entry whose action count is not the head's throws rather
|
|
588
|
+
* than removing a segment the entry does not record. (See the sibling note on `syncInternal`'s
|
|
589
|
+
* post-commit replay, which rests on the same invariant.)
|
|
590
|
+
*
|
|
591
|
+
* @returns whether the staged set changed — always true here: even for a zero-action entry the
|
|
592
|
+
* tracker still holds this action's staged transforms, and only the replay at the end of
|
|
593
|
+
* `updateInternal` — which resets the tracker and re-stages just what remains — drops them.
|
|
594
|
+
* That reset is what turns `hasUnsyncedChanges()` false so the sync loop exits reporting the
|
|
595
|
+
* success the writer is owed (the action IS durable). */
|
|
508
596
|
private consumeOwnEntry;
|
|
509
|
-
/**
|
|
510
|
-
*
|
|
597
|
+
/** Remove the head segment `entryId` because `entry`, its own committed log entry, made it
|
|
598
|
+
* durable — the head arm of {@link consumeOwnEntry}. Bumps the segment version, so an outstanding
|
|
599
|
+
* snapshot restores by replay rather than putting the committed segment back, and reports the
|
|
600
|
+
* dropped segment's tally through the cycle's hook ({@link reportCommittedHead}), as the handle's
|
|
601
|
+
* `fold` does for an attempt that committed. */
|
|
602
|
+
private consumeHead;
|
|
603
|
+
/** Hand the tally recorded on `segment` — the head segment just made durable and dropped — to the
|
|
604
|
+
* cycle's `onCommittedHead` hook ({@link HeadCommitOptions.onCommittedHead}), under the latch, from
|
|
605
|
+
* the two places that drop a head segment as committed: the handle's `fold`, and
|
|
606
|
+
* {@link consumeHead}. A segment with no recorded tally is a defect, answered with the zero tally
|
|
607
|
+
* and logged rather than thrown: every sealed segment is staged by {@link buildHeadTracker} before
|
|
608
|
+
* its first send and by a replay when put back ({@link restoreSealed}), and the resume path that
|
|
609
|
+
* re-sends a recorded attempt verbatim runs after one of those. A throw out of the hook is logged,
|
|
610
|
+
* never raised — the commit is already durable. */
|
|
611
|
+
private reportCommittedHead;
|
|
612
|
+
/** The open segment with the leading actions `entry` made durable dropped off it. */
|
|
613
|
+
private consumedFromOpen;
|
|
614
|
+
/** Maps each OPEN-segment action to its effective form against a remote entry: the original, a
|
|
615
|
+
* replacement, or dropped. A replacement or a discard changes the staged set; the tracker still
|
|
511
616
|
* holds the pre-filter transforms, so report it as mutated to force a replay that re-stages
|
|
512
617
|
* against the effective actions. Identity comparison per the contract: keep => same instance,
|
|
513
618
|
* replace => new instance.
|
|
619
|
+
*
|
|
620
|
+
* A SEALED segment's action list is the queue entry's own and is never rewritten (invariant 3
|
|
621
|
+
* of docs/offline-sync.md §The segment model), so the hook is not offered them. `Tree` and
|
|
622
|
+
* `Diary` install no hook, so nothing observable changes for them either way.
|
|
623
|
+
*
|
|
514
624
|
* NOTE: a filterConflict hook that always allocates a fresh (but equal) instance instead of
|
|
515
625
|
* returning the same one forces a replay on every update — if that ever shows up as a hot path,
|
|
516
|
-
* compare by value/id here instead of by reference.
|
|
626
|
+
* compare by value/id here instead of by reference.
|
|
627
|
+
*
|
|
628
|
+
* @returns whether the open segment changed. */
|
|
517
629
|
private filterAgainstEntry;
|
|
518
630
|
/** Refresh this instance against the stored log: adopt the latest committed revision, resolve
|
|
519
631
|
* pending actions against everything that landed since, and replay them if anything conflicts.
|
|
@@ -678,8 +790,8 @@ export declare class Collection<TAction> implements ICollection<TAction> {
|
|
|
678
790
|
* revision. A revision only one side names is missing evidence, not disagreement — the rule
|
|
679
791
|
* {@link earliestFork} applies too. */
|
|
680
792
|
private static disagreesWithHeld;
|
|
681
|
-
/** Whether {@link updateInternal} must re-stage
|
|
682
|
-
* context it held BEFORE the refresh.
|
|
793
|
+
/** Whether {@link updateInternal} must re-stage the staged actions after adopting `latest`,
|
|
794
|
+
* given the context it held BEFORE the refresh.
|
|
683
795
|
*
|
|
684
796
|
* The answer is deliberately NOT just "a conflict was found". A conflict is detected by an
|
|
685
797
|
* incoming log entry naming a block this tracker already holds a transform for — so an action
|
|
@@ -694,16 +806,17 @@ export declare class Collection<TAction> implements ICollection<TAction> {
|
|
|
694
806
|
* The advance test rests on {@link advanceContext} being monotonic (it refuses to lower), which
|
|
695
807
|
* is what makes "the adopted rev differs from the held one" mean "it went up".
|
|
696
808
|
*
|
|
697
|
-
* The second conjunct
|
|
698
|
-
*
|
|
699
|
-
*
|
|
700
|
-
* {@link
|
|
701
|
-
*
|
|
702
|
-
* {@link
|
|
703
|
-
*
|
|
704
|
-
*
|
|
705
|
-
*
|
|
706
|
-
*
|
|
809
|
+
* The second conjunct counts the REPLAYABLE actions — every non-refused sealed segment's plus
|
|
810
|
+
* the open segment's, since a refresh that adopts a newer revision must re-stage the sealed
|
|
811
|
+
* segments too — and deliberately NOT {@link hasUnsyncedChanges}, which also counts tracker
|
|
812
|
+
* transforms. A collection {@link createOrOpen} just INVENTED holds its staged header/root in
|
|
813
|
+
* the tracker with NO staged action naming them; {@link replayActions} now restores them from
|
|
814
|
+
* {@link inventedBaseline}, but nothing to re-stage still means nothing to replay, and a replay
|
|
815
|
+
* over no actions would be a wasted tracker rebuild.
|
|
816
|
+
*
|
|
817
|
+
* NOTE: this makes a refresh that adopts a newer revision O(staged actions) rather than free,
|
|
818
|
+
* so a read taken mid-transaction while a rival keeps committing re-stages every action staged
|
|
819
|
+
* so far, on each such read. Measured as no change to the storage-op budgets
|
|
707
820
|
* (`index-backfill-cost.spec.ts`, `cold-apply-cost.spec.ts`), because the replay's reads are
|
|
708
821
|
* served from `sourceCache`. If a long transaction's reads ever show up as slow, narrow the
|
|
709
822
|
* replay to the actions whose reads the adopted entries actually invalidated — NOT back to
|
|
@@ -711,17 +824,14 @@ export declare class Collection<TAction> implements ICollection<TAction> {
|
|
|
711
824
|
private mustReplay;
|
|
712
825
|
/** Re-judge every staged update's pinned base against the read cache and re-stage the pending
|
|
713
826
|
* queue if any has moved. Runs immediately before each pend attempt — {@link syncAttempts} and
|
|
714
|
-
* the coordinator's commit span both call it
|
|
715
|
-
*
|
|
716
|
-
*
|
|
827
|
+
* the coordinator's commit span both call it, and {@link headTrackerFor} re-judges a head
|
|
828
|
+
* commit's tracker the same way — because that is the last moment before the base the pend
|
|
829
|
+
* declares is put on the wire, and nothing between a refused attempt and the re-pend reads the
|
|
830
|
+
* block again (the refresh may have moved nothing and so replayed nothing).
|
|
717
831
|
*
|
|
718
|
-
* Two steps. First, one read for each pinned block the cache does NOT retain
|
|
719
|
-
*
|
|
720
|
-
*
|
|
721
|
-
* and only a read can tell. An evicted-but-kept base needs no read: its content met every floor
|
|
722
|
-
* the handle knows, so storage cannot have moved it without a log entry the next refresh will
|
|
723
|
-
* walk (and the pend would be refused as stale on revision alone). Then, one cache probe per
|
|
724
|
-
* pinned block ({@link Tracker.movedBases}) and a replay if any moved.
|
|
832
|
+
* Two steps. First, one read for each pinned block the cache does NOT retain
|
|
833
|
+
* ({@link rereadUnretainedBases}). Then, one cache probe per pinned block
|
|
834
|
+
* ({@link Tracker.movedBases}) and a replay if any moved.
|
|
725
835
|
*
|
|
726
836
|
* Latch-free by contract, like {@link snapshotPending}: the caller holds this instance's latch
|
|
727
837
|
* ({@link replayActions} is always run under it).
|
|
@@ -733,6 +843,13 @@ export declare class Collection<TAction> implements ICollection<TAction> {
|
|
|
733
843
|
*
|
|
734
844
|
* @returns whether the pending queue was re-staged. */
|
|
735
845
|
restageIfBasesMoved(): Promise<boolean>;
|
|
846
|
+
/** One read for each of `tracker`'s pinned blocks the cache does NOT retain — content handed
|
|
847
|
+
* through unkept (a below-floor answer, which the cache re-asks for on every read anyway): the
|
|
848
|
+
* pin names the revision last served, storage may have caught up since without the log moving,
|
|
849
|
+
* and only a read can tell. An evicted-but-kept base needs no read: its content met every floor
|
|
850
|
+
* the handle knows, so storage cannot have moved it without a log entry the next refresh will
|
|
851
|
+
* walk (and the pend would be refused as stale on revision alone). */
|
|
852
|
+
private rereadUnretainedBases;
|
|
736
853
|
/** Report each moved base, naming the revision the operations were computed against and the
|
|
737
854
|
* one the cache describes now, and return how many there were. */
|
|
738
855
|
private logMovedBases;
|
|
@@ -754,29 +871,63 @@ export declare class Collection<TAction> implements ICollection<TAction> {
|
|
|
754
871
|
* mutations staged since. Reads through the collection then observe exactly the
|
|
755
872
|
* snapshot state again; storage is untouched because nothing was ever synced.
|
|
756
873
|
*
|
|
757
|
-
*
|
|
758
|
-
*
|
|
759
|
-
*
|
|
760
|
-
*
|
|
761
|
-
*
|
|
762
|
-
*
|
|
763
|
-
*
|
|
764
|
-
*
|
|
765
|
-
*
|
|
766
|
-
*
|
|
767
|
-
*
|
|
768
|
-
*
|
|
769
|
-
*
|
|
770
|
-
*
|
|
771
|
-
*
|
|
772
|
-
*
|
|
773
|
-
*
|
|
774
|
-
*
|
|
775
|
-
*
|
|
874
|
+
* The snapshot describes the OPEN segment only (docs/offline-sync.md §Rollback and savepoints
|
|
875
|
+
* only touch the open segment): its `pending` is the open segment's actions, while its
|
|
876
|
+
* `transforms` are the whole tracker at capture, the sealed segments' effects included. Which
|
|
877
|
+
* arm a restore takes is decided from three facts — whether the sealed list has changed since
|
|
878
|
+
* the capture ({@link CollectionSnapshot.sealedVersion} against {@link SegmentList.version}),
|
|
879
|
+
* whether the committed boundary has moved (this collection has since ADOPTED a newer
|
|
880
|
+
* revision), and whether any segment is sealed now:
|
|
881
|
+
*
|
|
882
|
+
* - **Verbatim**, when the sealed list is unchanged and the boundary has not moved: the tracker
|
|
883
|
+
* is reset to a copy of the captured transforms, the captured pins are restored, and the open
|
|
884
|
+
* segment is set to the captured actions. This keeps an INVENTED collection's header, log
|
|
885
|
+
* block and root, which live in the tracker until the first sync and would be lost by a
|
|
886
|
+
* reset. It is the arm every restore took before segments existed, so while nothing is ever
|
|
887
|
+
* sealed nothing behaves differently.
|
|
888
|
+
* - **Replay**, when the sealed list has changed — a segment sealed, dropped or refused while
|
|
889
|
+
* the snapshot was outstanding — or when the boundary has moved while a segment is sealed:
|
|
890
|
+
* the open segment is set to the captured actions and the tracker is rebuilt by
|
|
891
|
+
* {@link replayActions}, the sealed segments as they are NOW (refused ones skipped, a newly
|
|
892
|
+
* refused one recorded and reported) and then the restored open actions. Reinstating the
|
|
893
|
+
* captured transforms would put a dropped segment's effects back — the drain removes the
|
|
894
|
+
* head segment after committing it, and the next head commit would commit it a second time
|
|
895
|
+
* — and a reset would drop the sealed segments' effects.
|
|
896
|
+
* - A moved boundary with NOTHING sealed keeps the two arms it had before segments. An empty
|
|
897
|
+
* captured open segment (the transaction-rollback shape: the capture predates the
|
|
898
|
+
* transaction's first stage) resets the tracker empty, because the captured transforms
|
|
899
|
+
* describe block state at the OLD boundary and reinstalling them would shadow committed
|
|
900
|
+
* blocks with stale structure — the observed case being an INVENTED collection's pre-commit
|
|
901
|
+
* header/root restored over a rival's now-committed collection, after the conflict replay
|
|
902
|
+
* that refused a guarded insert (TreeKeyTakenError), making every later read descend an
|
|
903
|
+
* empty tree. A non-empty one restores verbatim (the NOTE below).
|
|
904
|
+
*
|
|
905
|
+
* The staged-base rule (docs/internals.md §Staged Edits Keep Their Base: an update names the
|
|
906
|
+
* base it was computed against, and a rollback never pairs operations with the bases of some
|
|
907
|
+
* later re-stage) is met differently by the two arms. The verbatim arm restores the captured
|
|
908
|
+
* pins beside the captured operations. The replay arm restores none: its reset clears the pin
|
|
909
|
+
* store, and every re-staged update pins its base from the read cache as it is now, which IS
|
|
910
|
+
* the base the re-staged operations were computed against.
|
|
911
|
+
*
|
|
912
|
+
* A refusal of the OPEN segment inside the replay arm propagates, as it would out of a
|
|
913
|
+
* refresh's replay: the caller rolling back is told that its transaction's own actions no
|
|
914
|
+
* longer apply at the boundary the collection is now at. Rare — it needs a sealed change, or a
|
|
915
|
+
* sealed segment across a moved boundary, AND a rival between capture and restore — and the
|
|
916
|
+
* honest answer; the tracker is then as {@link updateInternal}'s note on a throw out of
|
|
917
|
+
* `replayActions` describes.
|
|
918
|
+
*
|
|
919
|
+
* Latch-free by contract, like {@link snapshotPending}: every caller holds this instance's
|
|
920
|
+
* latch or runs on the single call path that excludes a concurrent stage (the coordinator's
|
|
921
|
+
* `rollback` and the bridge's savepoint rollback document that assumption).
|
|
922
|
+
*
|
|
923
|
+
* NOTE: a snapshot that carries PENDING actions across a moved boundary with nothing sealed (a
|
|
924
|
+
* mid-transaction savepoint captured before a mid-transaction refresh adopted a rival's commit)
|
|
925
|
+
* still restores verbatim. That shape predates the moved-boundary guard and keeps its old
|
|
926
|
+
* behaviour; if it is ever observed producing stale reads, route it through the replay arm too.
|
|
776
927
|
* The WRITE side of that shape is closed here: the snapshot's base pins are restored with
|
|
777
928
|
* its transforms, so the restored operations name the bases they were computed on, and the
|
|
778
929
|
* pre-pend re-validation (restageIfBasesMoved) finds those bases moved and re-stages. */
|
|
779
|
-
restorePending(snapshot: CollectionSnapshot<TAction>): void
|
|
930
|
+
restorePending(snapshot: CollectionSnapshot<TAction>): Promise<void>;
|
|
780
931
|
/** A read-only {@link Tracker} pinned to this collection's committed state AS OF the
|
|
781
932
|
* moment of this call, seeded with a (deep-copied) set of pre-transaction transforms.
|
|
782
933
|
* Reads through it observe exactly that revision plus exactly those transforms — NOT
|
|
@@ -819,28 +970,143 @@ export declare class Collection<TAction> implements ICollection<TAction> {
|
|
|
819
970
|
* yield a coherent pre-commit view AFTER that commit folded into the shared cache
|
|
820
971
|
* (a mid-sweep multi-tree commit being the motivating case). */
|
|
821
972
|
createReadTracker(transforms: Transforms, options?: ReadViewOptions): Tracker<IBlock>;
|
|
822
|
-
/** The staged (not-yet-synced) actions queued by {@link act}
|
|
973
|
+
/** The OPEN segment: the staged (not-yet-synced) actions queued by {@link act} that no
|
|
974
|
+
* {@link sealPending} has closed off.
|
|
823
975
|
*
|
|
824
976
|
* Exposed so a {@link TransactionCoordinator} can append them to the log at
|
|
825
977
|
* commit time — mirroring what {@link sync} does internally — when the actions
|
|
826
978
|
* were staged directly into this collection (e.g. through a Tree's stage())
|
|
827
|
-
* rather than applied via the coordinator's own action path.
|
|
979
|
+
* rather than applied via the coordinator's own action path.
|
|
980
|
+
*
|
|
981
|
+
* @throws SealedSegmentsError while any segment is sealed: the coordinator's only use is a
|
|
982
|
+
* whole-collection append, which would merge the sealed segments' effects (they are in the
|
|
983
|
+
* tracker) into one entry under one action id. The throw lands in `commitOnceLatched`'s
|
|
984
|
+
* existing catch, which restores every participant. */
|
|
828
985
|
getPendingActions(): Action<TAction>[];
|
|
829
|
-
/** Drop the
|
|
830
|
-
*
|
|
831
|
-
*
|
|
832
|
-
* externally. */
|
|
986
|
+
/** Drop the OPEN segment after it has been committed through a coordinator. Counterpart to
|
|
987
|
+
* {@link getPendingActions}, which cannot have returned anything while a segment was sealed,
|
|
988
|
+
* so only the open segment is ever cleared here; {@link sync} clears its own inline, so this
|
|
989
|
+
* is only needed when commit was orchestrated externally. */
|
|
833
990
|
clearPendingActions(): void;
|
|
834
|
-
/** Whether {@link sync} has anything to push: staged actions, or tracker
|
|
835
|
-
* that were never committed
|
|
836
|
-
* until its first sync
|
|
991
|
+
/** Whether {@link sync} has anything to push: staged actions in the open segment, or tracker
|
|
992
|
+
* transforms that were never committed — an INVENTED collection's header/root blocks, which
|
|
993
|
+
* live there until its first sync with no staged action to name them, and the effects of
|
|
994
|
+
* every sealed segment.
|
|
837
995
|
*
|
|
838
996
|
* This is the exact predicate {@link syncInternal} loops on, so `false` means a sync
|
|
839
997
|
* would commit nothing. Exposed so a caller that would otherwise flush
|
|
840
998
|
* unconditionally can skip the round trip — note that {@link Tree.sync} routes
|
|
841
999
|
* through {@link updateAndSync}, so an unnecessary flush still pays a full,
|
|
842
|
-
* cache-bypassing {@link update} before discovering it has nothing to do.
|
|
1000
|
+
* cache-bypassing {@link update} before discovering it has nothing to do.
|
|
1001
|
+
*
|
|
1002
|
+
* `true` does not promise that {@link sync} can push it: while any segment is sealed, `sync`
|
|
1003
|
+
* refuses with {@link SealedSegmentsError} rather than committing the sealed effects as one
|
|
1004
|
+
* entry, so a caller that loops on this over a sealed collection gets that typed error, never
|
|
1005
|
+
* a silent no-op. Check {@link sealedEntries} first, or commit the head segment.
|
|
1006
|
+
*
|
|
1007
|
+
* Nor does `false` promise that nothing is sealed. A sealed segment leaves no tracker transform
|
|
1008
|
+
* when every one of its actions is refused, or wrote nothing (a blind delete of a key nobody
|
|
1009
|
+
* holds), so over an otherwise empty tracker this reads `false` while {@link sealedEntries} is
|
|
1010
|
+
* non-empty. The queue drives off {@link sealedEntries}, never off this predicate. */
|
|
843
1011
|
hasUnsyncedChanges(): boolean;
|
|
1012
|
+
/** Close the open segment into a sealed segment owned by `entryId` (see {@link SegmentList}).
|
|
1013
|
+
* Returns `false` and changes nothing when the open segment is empty: an invented collection's
|
|
1014
|
+
* header transforms are not an action and are not sealed, so an entry that staged nothing here
|
|
1015
|
+
* owns no segment here. Throws when `entryId` is already sealed in this collection.
|
|
1016
|
+
*
|
|
1017
|
+
* Synchronous and latch-free by contract, like {@link snapshotPending}: the caller brackets it
|
|
1018
|
+
* (no concurrent act or sync is in flight). */
|
|
1019
|
+
sealPending(entryId: EntryId): boolean;
|
|
1020
|
+
/** The entry ids of the sealed segments, oldest first — refused ones included, until dropped. */
|
|
1021
|
+
sealedEntries(): EntryId[];
|
|
1022
|
+
/** The log tail block id the most recent header read named ({@link logTailId}), for a caller that
|
|
1023
|
+
* resolves this collection's cohorts from routing keys without a read — the offline queue's
|
|
1024
|
+
* reachability gate (docs/offline-sync.md §When to submit). `undefined` before the first header
|
|
1025
|
+
* read of an invented collection; possibly stale by one roll-over, which costs that caller nothing
|
|
1026
|
+
* worse than asking about a block the collection has moved on from. */
|
|
1027
|
+
knownLogTailId(): BlockId | undefined;
|
|
1028
|
+
/** The refusal recorded for `entryId`'s segment by a replay that excluded it (see
|
|
1029
|
+
* {@link replayActions}), or `undefined` when the segment is not refused — or not sealed here. */
|
|
1030
|
+
sealedRefusal(entryId: EntryId): ActionRefusedError | undefined;
|
|
1031
|
+
/** The sealed segment `entryId` owns here: its actions, the array the segment holds (never
|
|
1032
|
+
* mutated by a caller; the offline journal serialises it), or `undefined` when the entry is not
|
|
1033
|
+
* sealed here. Synchronous and latch-free, like {@link sealedEntries}. */
|
|
1034
|
+
sealedActions(entryId: EntryId): readonly Action<TAction>[] | undefined;
|
|
1035
|
+
/** The OPEN segment's actions — what the current transaction has staged since the last seal — as
|
|
1036
|
+
* the array the segment holds (never mutated by a caller). Unlike {@link getPendingActions} it
|
|
1037
|
+
* answers while segments are sealed, for a reader that judges the open transaction beside the
|
|
1038
|
+
* queued ones (the Quereus plugin's `CommitOutlook()`). Synchronous and latch-free, like
|
|
1039
|
+
* {@link sealedActions}. */
|
|
1040
|
+
openActions(): readonly Action<TAction>[];
|
|
1041
|
+
/** The exact inverse of {@link sealPending}, list-only and latch-free by the same contract: move
|
|
1042
|
+
* the segment's actions back into the open segment, for an enqueue whose journal write failed
|
|
1043
|
+
* after sealing (`OfflineQueue.enqueue`, which unseals every collection it sealed, in reverse
|
|
1044
|
+
* order, and rethrows). Requires the segment to be the NEWEST sealed one and the open segment to
|
|
1045
|
+
* be empty — both true at that one call site, which has just sealed and staged nothing since —
|
|
1046
|
+
* and throws otherwise (`SegmentList.unseal`). The tracker is untouched: its transforms are
|
|
1047
|
+
* already what they were before the seal. The segment version moves, so a snapshot taken before
|
|
1048
|
+
* the transaction restores by replay ({@link restorePending}), which ends with the transaction's
|
|
1049
|
+
* actions gone once the caller rolls it back. */
|
|
1050
|
+
unseal(entryId: EntryId): void;
|
|
1051
|
+
/** Whether this collection's committed context names `attempt.actionId` at `attempt.rev`: the
|
|
1052
|
+
* write that attempt sent is committed here, and this handle has adopted it. This is how a restore
|
|
1053
|
+
* after a restart recognises, before re-staging a journaled segment, that the segment's network
|
|
1054
|
+
* commit landed and the crash came after it (docs/offline-sync.md §Restore after a restart):
|
|
1055
|
+
* re-staging such a segment would run its own guards against its own committed rows (`absent`
|
|
1056
|
+
* refuses on a present key) and fail the entry with `constraint`, the opposite of the truth.
|
|
1057
|
+
* `false` for an invented collection, which has no context. Synchronous and latch-free.
|
|
1058
|
+
*
|
|
1059
|
+
* NOTE: `actionIdAt` reaches back only to the most recent checkpoint, and no checkpoint is written
|
|
1060
|
+
* today (backlog `debt-the-collection-log-never-writes-a-checkpoint`); if that changes, read the
|
|
1061
|
+
* log's entry at `attempt.rev` instead, since a committed attempt behind a checkpoint would
|
|
1062
|
+
* otherwise answer `false` and be re-staged against itself. */
|
|
1063
|
+
holdsCommitted(attempt: ActionRev): boolean;
|
|
1064
|
+
/**
|
|
1065
|
+
* Put a sealed segment back, holding `actions` under `entryId`, at `position` in the sealed list —
|
|
1066
|
+
* ahead of the segment `before` names, or last — and rebuild the tracker by replaying every
|
|
1067
|
+
* replayable segment in order ({@link replayActions}), for the offline queue's restore after a
|
|
1068
|
+
* restart (`OfflineQueue.restore`; docs/offline-sync.md §Restore after a restart). A record
|
|
1069
|
+
* restored late belongs ahead of entries queued since, in the queue and in each collection's
|
|
1070
|
+
* sealed list alike, or the head commit's "head is first" rule and the queue's order disagree;
|
|
1071
|
+
* hence insertion rather than appending, at the cost of the one replay every insertion costs.
|
|
1072
|
+
*
|
|
1073
|
+
* The replay records and reports each refusal it meets as a refresh's would — EXCEPT this
|
|
1074
|
+
* segment's own, which is recorded on the segment and RETURNED rather than reported through
|
|
1075
|
+
* `onSealedRefused`: the queue registers the entry and hears the result from its own `stage`
|
|
1076
|
+
* callback, since the collection cannot report it to a queue that does not yet list the entry. A
|
|
1077
|
+
* later segment the replay newly refuses (this segment inserts the key it also inserts, say) is
|
|
1078
|
+
* reported through `onSealedRefused` as any replay's would be.
|
|
1079
|
+
*
|
|
1080
|
+
* Takes the collection latch, like {@link dropSealed}. Throws before anything changes when the
|
|
1081
|
+
* open segment is non-empty (a transaction is open, and its actions were staged over state without
|
|
1082
|
+
* this segment; the only caller refuses to restore mid-transaction), when a head commit is in
|
|
1083
|
+
* flight ({@link SealedSegmentsError}, `in-flight`), when `entryId` is already sealed here, or when
|
|
1084
|
+
* `before` names no segment here. A replay error that is not a refusal (a block the replay could
|
|
1085
|
+
* not read, say) propagates with the segment REMOVED again: the caller's restore rolls back and
|
|
1086
|
+
* may try this entry again later, which would otherwise meet its own segment as "already sealed".
|
|
1087
|
+
* The tracker is then half re-staged, the state a refresh's replay that throws leaves too (backlog
|
|
1088
|
+
* `debt-a-failed-refresh-can-leave-a-collection-half-restaged`); the next replay rebuilds it.
|
|
1089
|
+
*
|
|
1090
|
+
* @returns this segment's own refusal, when the replay refused it; `undefined` when it staged. */
|
|
1091
|
+
restoreSealed(entryId: EntryId, actions: readonly Action<TAction>[], position: {
|
|
1092
|
+
before: EntryId;
|
|
1093
|
+
} | 'last'): Promise<ActionRefusedError | undefined>;
|
|
1094
|
+
/** Remove the sealed segment owned by `entryId`, wherever it sits, and rebuild the tracker by
|
|
1095
|
+
* replaying what remains ({@link replayActions}). A later segment whose guard now refuses — one
|
|
1096
|
+
* that updated a row the dropped segment inserted, say — is recorded and reported through
|
|
1097
|
+
* `onSealedRefused` during that replay; cascading the removal through the queue's other
|
|
1098
|
+
* collections is the queue's job (docs/offline-sync.md §Removing an entry). Throws for an id
|
|
1099
|
+
* that is not sealed here, before anything changes, and {@link SealedSegmentsError} (`in-flight`)
|
|
1100
|
+
* for the segment a {@link commitHead} on this instance is carrying to the network — the only
|
|
1101
|
+
* segment that cannot be dropped while it waits, since the outcome being applied names it.
|
|
1102
|
+
* Another segment can be: the replay here rebuilds the live tracker, which the head commit's own
|
|
1103
|
+
* tracker does not depend on.
|
|
1104
|
+
*
|
|
1105
|
+
* Takes the collection latch, like {@link update}. */
|
|
1106
|
+
dropSealed(entryId: EntryId): Promise<void>;
|
|
1107
|
+
/** The refusal every whole-collection commit path makes while a segment is sealed (see
|
|
1108
|
+
* {@link SealedSegmentsError}). */
|
|
1109
|
+
private assertNoSealedSegments;
|
|
844
1110
|
/** The committed revision this collection currently READS at, or `undefined` for an
|
|
845
1111
|
* INVENTED collection that has never adopted a committed revision
|
|
846
1112
|
* ({@link createOrOpen} found no header and staged a fresh empty one).
|
|
@@ -963,8 +1229,11 @@ export declare class Collection<TAction> implements ICollection<TAction> {
|
|
|
963
1229
|
* path, which is the same assumption the participant selection in
|
|
964
1230
|
* `TransactionCoordinator.commitOnce` and its `rollback` already rest on. If a second writer is
|
|
965
1231
|
* ever allowed to drive the SAME instance concurrently, this must become a per-attempt token (a
|
|
966
|
-
* mark object compared by identity, refusing to replace a live one) rather than a bare id.
|
|
967
|
-
|
|
1232
|
+
* mark object compared by identity, refusing to replace a live one) rather than a bare id.
|
|
1233
|
+
*
|
|
1234
|
+
* `cycle` is what every send of the cycle carries ({@link InFlightCycle}); a re-mark replaces it,
|
|
1235
|
+
* which is harmless because every caller re-marks with what it marked. */
|
|
1236
|
+
beginInFlightAction(actionId: ActionId, cycle?: InFlightCycle): () => void;
|
|
968
1237
|
/** Keep what a FAILED attempt under `actionId` sent, so that if the refresh before its retry
|
|
969
1238
|
* finds that attempt's own log entry it can finish the action rather than assume it finished
|
|
970
1239
|
* (see {@link inFlightAttempt} and {@link completeOwnEntry}). Every write path that marks an
|
|
@@ -972,11 +1241,11 @@ export declare class Collection<TAction> implements ICollection<TAction> {
|
|
|
972
1241
|
* a path that does not still never reports a half-landed write as saved (the refresh then
|
|
973
1242
|
* refuses with a `transforms-not-held` {@link TornActionError}), but it cannot recover from one.
|
|
974
1243
|
*
|
|
975
|
-
* A no-op unless
|
|
976
|
-
* cycle has already ended cannot plant transforms under somebody else's mark. Latch-free and
|
|
1244
|
+
* A no-op unless the attempt's action is the one currently marked, so a late call from an attempt
|
|
1245
|
+
* whose cycle has already ended cannot plant transforms under somebody else's mark. Latch-free and
|
|
977
1246
|
* synchronous, like the mark itself: `TransactionCoordinator` calls it from inside its commit
|
|
978
1247
|
* span, where it already holds this instance's latch. */
|
|
979
|
-
retainInFlightAttempt(
|
|
1248
|
+
retainInFlightAttempt(attempt: InFlightAttempt): void;
|
|
980
1249
|
/** Ids for the log data blocks a write's log append may have to mint, so a RETRY of that write
|
|
981
1250
|
* at the same revision sends the same ids the attempt it is repeating sent. Hand the result to
|
|
982
1251
|
* {@link Log.open} as `newDataBlockId`; it yields remembered ids in order and mints (and
|
|
@@ -1017,22 +1286,142 @@ export declare class Collection<TAction> implements ICollection<TAction> {
|
|
|
1017
1286
|
* class or throws ({@link SyncRetryExhaustedError} for a write that never landed). Present a change
|
|
1018
1287
|
* as saved only via `isFullyDurable`, never by comparing `quorum`. */
|
|
1019
1288
|
sync(options?: SyncOptions): Promise<WriteDurability | undefined>;
|
|
1289
|
+
/** The refresh a write's attempt cycle runs between attempts ({@link AttemptCycle.refreshUntilSettled}):
|
|
1290
|
+
* {@link updateInternal}, under the latch the write already holds and with its action marked in
|
|
1291
|
+
* flight, so the refresh recognises the write's own log entry. */
|
|
1292
|
+
private readonly refreshBetweenAttempts;
|
|
1020
1293
|
/** Mints the one action id this sync reuses across all of its retry attempts, and owns it for
|
|
1021
1294
|
* the WHOLE cycle — including the inter-attempt refresh, which is the only thing that reads it
|
|
1022
1295
|
* (see {@link inFlightActionId}). `sync()`/`updateAndSync()` hold the collection latch across
|
|
1023
1296
|
* all of this, so the mark's lifetime is contained inside the latched span here; the disposer
|
|
1024
1297
|
* runs on every exit, including a throw out of retry exhaustion or an abort. */
|
|
1025
1298
|
private syncInternal;
|
|
1026
|
-
/** The retry loop behind {@link syncInternal}, run with
|
|
1299
|
+
/** The retry loop behind {@link syncInternal}, run with the action already marked in flight: the
|
|
1300
|
+
* attempt machinery of {@link AttemptCycle} and {@link stageAttempt}, aimed at the open segment
|
|
1301
|
+
* over the live tracker. {@link commitHead} drives the same machinery at the head segment.
|
|
1027
1302
|
*
|
|
1028
|
-
* @param timestamp the WRITE's time, stamped on the log entry every attempt appends — see
|
|
1029
|
-
* {@link syncInternal}, which mints it.
|
|
1030
1303
|
* @returns the durability of what this sync committed, or `undefined` when the loop never ran a
|
|
1031
1304
|
* commit (nothing staged). See {@link sync}. */
|
|
1032
1305
|
private syncAttempts;
|
|
1306
|
+
/** Build one attempt at the revision this collection would commit at next ({@link stageAttempt});
|
|
1307
|
+
* the ids its log append may have to mint come from {@link logAppendBlockIds}, so a retry at the
|
|
1308
|
+
* same revision appends the same entry. */
|
|
1309
|
+
private buildAttempt;
|
|
1310
|
+
/** Send one attempt — pend, then commit — under the cycle's aged retry `priority`, carrying what
|
|
1311
|
+
* the cycle asked of every send ({@link inFlightCycle}). */
|
|
1312
|
+
private send;
|
|
1313
|
+
/** Fold a committed attempt's transforms — the log append included — into this instance's read
|
|
1314
|
+
* cache and adopt the revision it committed at. Every caller does this BEFORE replaying what is
|
|
1315
|
+
* still staged (see the note in {@link syncAttempts}). Takes the transforms out of the attempt's
|
|
1316
|
+
* tracker, which is finished with. */
|
|
1317
|
+
private foldOwnCommit;
|
|
1033
1318
|
/** Refresh from the transactor, then push. Same return contract as {@link sync}: the durability of
|
|
1034
1319
|
* what was committed, or `undefined` when nothing was staged and so nothing was written. */
|
|
1035
1320
|
updateAndSync(options?: SyncOptions): Promise<WriteDurability | undefined>;
|
|
1321
|
+
/** Commit exactly the head sealed segment — the oldest, `entryId` — as one log entry under the
|
|
1322
|
+
* action id and timestamp `options` supplies, for the offline-sync queue's drain
|
|
1323
|
+
* (docs/offline-sync.md §One entry, one network transaction): {@link openHeadCommit} followed by
|
|
1324
|
+
* the one-collection driver, `driveHeadCommit` in head-commit.ts, with the handle closed on every
|
|
1325
|
+
* exit. The attempt machinery is {@link syncAttempts}' ({@link AttemptCycle}, {@link stageAttempt});
|
|
1326
|
+
* what differs is the target — a head tracker ({@link headTrackerFor}) — and the latch, released
|
|
1327
|
+
* around the one network `await` ({@link HeadCommitHandle.release}). `options.recordAttempt` is
|
|
1328
|
+
* called with each attempt before it is sent, and `options.resume` hands back an attempt an
|
|
1329
|
+
* earlier cycle under the same action id recorded (see {@link HeadCommitOptions}).
|
|
1330
|
+
*
|
|
1331
|
+
* @returns what {@link sync} returns: who holds the commit, or `undefined` when the refresh
|
|
1332
|
+
* established that the write was already saved under `options.actionId` without re-sending.
|
|
1333
|
+
* @throws SealedSegmentsError before anything is done, when `entryId` is not the head segment
|
|
1334
|
+
* (`not-head`), carries a recorded refusal (`refused`), or a head commit is already in flight on
|
|
1335
|
+
* this instance (`in-flight`); the head segment's recorded refusal, an {@link ActionRefusedError},
|
|
1336
|
+
* when a refresh or the head tracker's staging refused it during the cycle; whatever
|
|
1337
|
+
* `options.recordAttempt` throws, before anything is sent; otherwise what {@link sync} throws. */
|
|
1338
|
+
commitHead(entryId: EntryId, options: HeadCommitOptions): Promise<WriteDurability | undefined>;
|
|
1339
|
+
/** Open a head commit of `entryId` under `identity` and hand back the handle a driver runs it
|
|
1340
|
+
* through, step by step ({@link HeadCommitHandle}): this is {@link commitHead} with the loop left
|
|
1341
|
+
* to the caller, for the coordinator's per-entry commit over several collections, which runs each
|
|
1342
|
+
* step on every collection it wrote in lock-step. Takes the collection latch, which the handle
|
|
1343
|
+
* holds until its `close()` except around the network round trip; checks the three
|
|
1344
|
+
* preconditions; marks the action in flight for the whole cycle ({@link beginInFlightAction}), as
|
|
1345
|
+
* a sync's is, so the refresh between attempts recognises the write's own entry; sets
|
|
1346
|
+
* {@link headCommit}, which tells {@link consumeOwnEntry} that such an entry records the head
|
|
1347
|
+
* segment; and seeds the retained attempt with `options.resume` when one is given, so that the
|
|
1348
|
+
* opening refresh can finish an earlier cycle's torn attempt from it ({@link completeOwnEntry}) —
|
|
1349
|
+
* and `stage()` re-sends it verbatim while the next attempt would request its revision
|
|
1350
|
+
* ({@link resumedAttempt}). The rest of `options` is the cycle's ({@link InFlightCycle}), recorded
|
|
1351
|
+
* with the in-flight mark, so the handle's `send()` and a refresh's re-send of a torn attempt both
|
|
1352
|
+
* carry it.
|
|
1353
|
+
*
|
|
1354
|
+
* **The target.** The live tracker holds every sealed segment and the open one, cumulatively, so
|
|
1355
|
+
* an attempt cannot run on a copy of it the way a sync's does. It runs on a HEAD TRACKER instead
|
|
1356
|
+
* ({@link headTrackerFor}): the head segment's actions alone, staged atomically over the
|
|
1357
|
+
* committed state, with pins of their own — built once per requested revision and reused across
|
|
1358
|
+
* attempts, since a rebuild mints fresh ids for the blocks the actions insert and would send
|
|
1359
|
+
* different content under one `(action id, revision)` (the rule {@link logAppendBlockIds}
|
|
1360
|
+
* closes). Staging runs the actions' guards against the committed state; a refusal there is the
|
|
1361
|
+
* segment's refusal, recorded and reported exactly as a replay's would be, and thrown out of
|
|
1362
|
+
* `stage()`.
|
|
1363
|
+
*
|
|
1364
|
+
* **The latch.** Held for every step EXCEPT the one `await` on the network, so `act`,
|
|
1365
|
+
* `sealPending`, `update` and the rest are not blocked behind a commit that can take seconds
|
|
1366
|
+
* (docs/offline-sync.md §The drain does not hold the collection latch across the network). While
|
|
1367
|
+
* it is released {@link headInFlight} is set: a refresh that walks into this commit's entry defers
|
|
1368
|
+
* to it, and `dropSealed` of the head refuses. A second head commit on this instance waits on the
|
|
1369
|
+
* latch and then meets the `in-flight` precondition.
|
|
1370
|
+
*
|
|
1371
|
+
* **The head's recorded refusal** is re-checked by `stage()` before every attempt and by
|
|
1372
|
+
* `refused()` after every refused send, because a refresh that adopted a rival — a reader's,
|
|
1373
|
+
* while the latch was released, or this cycle's own — may have replayed and refused it; each
|
|
1374
|
+
* throws the recorded refusal in place of another attempt. On success the driver calls `fold()`
|
|
1375
|
+
* (remove the head segment, bump the segment version, fold the attempt's transforms into the
|
|
1376
|
+
* cache and adopt its revision) and only THEN `replay()` (the remaining segments and the open
|
|
1377
|
+
* segment over the committed state that now holds the head) — the fold-before-replay order
|
|
1378
|
+
* {@link syncAttempts} takes, which anything staged while the commit was on the network relies on.
|
|
1379
|
+
*
|
|
1380
|
+
* A driver that opens handles on more than one collection opens them in sorted collection-id
|
|
1381
|
+
* order, the order `TransactionCoordinator.commitOnce` takes the same latches in; see the
|
|
1382
|
+
* interface.
|
|
1383
|
+
*
|
|
1384
|
+
* @throws Error before the latch is taken when `options.resume` was recorded under an action other than
|
|
1385
|
+
* `identity.actionId` — a caller defect, since the attempt would be re-sent under the wrong id;
|
|
1386
|
+
* SealedSegmentsError, with the latch released again, when `entryId` is not the head segment
|
|
1387
|
+
* (`not-head`), carries a recorded refusal (`refused`), or a head commit is already in flight on
|
|
1388
|
+
* this instance (`in-flight`). */
|
|
1389
|
+
openHeadCommit(entryId: EntryId, identity: WriteIdentity, options?: OpenHeadCommitOptions): Promise<HeadCommitHandle>;
|
|
1390
|
+
/** The handle {@link openHeadCommit} returns: closures over this instance's private state, so
|
|
1391
|
+
* nothing private becomes public. `release` is the latch release of the latch the caller took;
|
|
1392
|
+
* `endInFlight` the disposer of the in-flight mark. The head tracker lives here, per handle, so it
|
|
1393
|
+
* is reused across the attempts of one cycle exactly as the in-line loop reused it. `resume` is
|
|
1394
|
+
* the attempt the cycle was opened with, which `stage()` re-sends verbatim while the next attempt
|
|
1395
|
+
* would request its revision ({@link resumedAttempt}). */
|
|
1396
|
+
private headCommitHandle;
|
|
1397
|
+
/** {@link commitHead}'s preconditions, each a {@link SealedSegmentsError} naming its reason. */
|
|
1398
|
+
private assertHeadCommittable;
|
|
1399
|
+
/** The head segment, which a running head commit may still commit: it is `entryId` — anything
|
|
1400
|
+
* else is a defect ({@link headSegment}) — and it has not been refused meanwhile. A refresh that
|
|
1401
|
+
* adopted a rival may have replayed and refused it, and that refusal, not another attempt, is
|
|
1402
|
+
* then the cycle's answer. */
|
|
1403
|
+
private committableHead;
|
|
1404
|
+
/** The head segment, asserted to be `entryId`. Nothing may remove the head while a head commit
|
|
1405
|
+
* of it runs — a refresh that meets it defers, `dropSealed` of it refuses — so anything else here
|
|
1406
|
+
* is a defect, thrown as one. */
|
|
1407
|
+
private headSegment;
|
|
1408
|
+
/** The tracker a head attempt is built from (see {@link commitHead}): `current`, while it was
|
|
1409
|
+
* built for the revision the next attempt requests and no base under it has moved; otherwise a
|
|
1410
|
+
* fresh one ({@link buildHeadTracker}). A revision that moved is a write that is genuinely
|
|
1411
|
+
* different. A base that moved at the same revision is re-judged exactly as
|
|
1412
|
+
* {@link restageIfBasesMoved} re-judges the live queue before an attempt, and rebuilds.
|
|
1413
|
+
* NOTE: that rebuild is the same exception to the byte-identical retry that {@link syncAttempts}
|
|
1414
|
+
* records at its `restageIfBasesMoved` call — fresh ids for the blocks the actions insert under
|
|
1415
|
+
* an unchanged `(action id, revision)` — reached the same narrow way and refused by storage's
|
|
1416
|
+
* base guard on the same machines; the same answer applies if it is ever seen. */
|
|
1417
|
+
private headTrackerFor;
|
|
1418
|
+
/** A tracker over this instance's read cache, with pins of its own, holding `segment`'s actions
|
|
1419
|
+
* staged atomically over the committed state — from the invented baseline while this collection
|
|
1420
|
+
* has no committed revision ({@link replayBaseline}): its header, log block and root then exist
|
|
1421
|
+
* nowhere else, and the head's commit has to carry them. A refusal is the segment's own,
|
|
1422
|
+
* recorded and reported ({@link recordSealedRefusal}) and thrown; a live replay that found it
|
|
1423
|
+
* first has already done the recording, and the caller never gets here. */
|
|
1424
|
+
private buildHeadTracker;
|
|
1036
1425
|
/** Stage `actions` and flush them as one call that either takes effect or leaves NOTHING behind:
|
|
1037
1426
|
* when the flush throws, the actions this call staged are unstaged again before the error escapes.
|
|
1038
1427
|
*
|
|
@@ -1057,14 +1446,42 @@ export declare class Collection<TAction> implements ICollection<TAction> {
|
|
|
1057
1446
|
* revision from before the actions were staged.
|
|
1058
1447
|
*
|
|
1059
1448
|
* While the held revision has not moved, the earlier transforms are reinstated verbatim rather
|
|
1060
|
-
* than rebuilt by replay:
|
|
1061
|
-
* no
|
|
1062
|
-
* the
|
|
1063
|
-
*
|
|
1064
|
-
*
|
|
1449
|
+
* than rebuilt by replay: they are exactly the state before the call, and reinstating them costs
|
|
1450
|
+
* no handler run (a replay would rebuild the same state from {@link inventedBaseline} and the
|
|
1451
|
+
* staged actions). Once the revision has moved those transforms describe blocks at a revision
|
|
1452
|
+
* this handle has left, so what remains is re-staged against the adopted one, exactly as a
|
|
1453
|
+
* refresh would have done. */
|
|
1065
1454
|
private unstage;
|
|
1066
1455
|
selectLog(forward?: boolean): AsyncIterableIterator<Action<TAction>>;
|
|
1456
|
+
/** Rebuild the tracker from the staged actions over the committed state this collection now
|
|
1457
|
+
* reads at (always called under latch): reset to {@link replayBaseline}, then every sealed
|
|
1458
|
+
* segment in order, then the open segment.
|
|
1459
|
+
*
|
|
1460
|
+
* A SEALED segment is staged as ONE atomic unit — one `internalTransact` call over all of its
|
|
1461
|
+
* actions — so a refusal of any action in it leaves none of its writes staged, and a refusal
|
|
1462
|
+
* ({@link ActionRefusedError}, the only class caught) is that segment's own: recorded on it,
|
|
1463
|
+
* reported through `onSealedRefused`, and the replay goes on to the next segment. A segment
|
|
1464
|
+
* already refused is skipped and not reported again; it stays listed until dropped. The OPEN
|
|
1465
|
+
* segment keeps the pre-segment behaviour: one `internalTransact` per action, and a refusal
|
|
1466
|
+
* propagates, since it is the live transaction's own (docs/offline-sync.md §Replay with a
|
|
1467
|
+
* per-segment refusal). Any error that is not a refusal propagates from either.
|
|
1468
|
+
*
|
|
1469
|
+
* Each re-staged update pins its base through `Atomic.commit` → `Tracker.absorb`, the path
|
|
1470
|
+
* {@link act} uses, so the pend declares the bases the re-staged operations were computed on. Each
|
|
1471
|
+
* sealed segment that staged records what its actions accepted as already applied
|
|
1472
|
+
* (`SealedSegment.applied`), the tally the head commit reports when the segment is committed.
|
|
1473
|
+
*
|
|
1474
|
+
* @param unreported - a segment whose refusal is recorded but NOT reported through
|
|
1475
|
+
* `onSealedRefused`: the one {@link restoreSealed} is inserting, whose caller reads the recorded
|
|
1476
|
+
* refusal off the segment itself. */
|
|
1067
1477
|
private replayActions;
|
|
1478
|
+
/** What a replay resets the tracker to: a copy of {@link inventedBaseline} while this collection
|
|
1479
|
+
* holds no committed revision (those blocks exist nowhere else), and nothing otherwise. */
|
|
1480
|
+
private replayBaseline;
|
|
1481
|
+
/** Record a replay's refusal of a sealed segment and, when `report` says so, report it once,
|
|
1482
|
+
* under the latch. The callback's throw is logged rather than raised: the refusal is already
|
|
1483
|
+
* recorded, and the rest of the replay must still run. */
|
|
1484
|
+
private recordSealedRefusal;
|
|
1068
1485
|
getReadDependencies(): ReadDependency[];
|
|
1069
1486
|
clearReadDependencies(): void;
|
|
1070
1487
|
/** Called for each local action that may be in conflict with a remote action (always called under latch).
|
|
@@ -1081,13 +1498,9 @@ export declare class Collection<TAction> implements ICollection<TAction> {
|
|
|
1081
1498
|
* than kept, because nothing proves it is current at the revision the refresh will pin to.
|
|
1082
1499
|
*
|
|
1083
1500
|
* Both answers pass {@link answeredBlock}'s checks as unpinned reads, header first, so a doubted
|
|
1084
|
-
* header or tail throws exactly as it would through {@link TransactorSource.tryGet}.
|
|
1085
|
-
*
|
|
1086
|
-
*
|
|
1087
|
-
* (`NetworkTransactor.get` throws on a missing id), so an unreachable out-of-date tail fails a
|
|
1088
|
-
* refresh that would not have needed it. Harmless today: the log has no checkpoints, so a
|
|
1089
|
-
* refresh that finds a new tail walks back through the old one anyway. If checkpoints start
|
|
1090
|
-
* letting that walk stop short, read the known tail in its own request instead.
|
|
1501
|
+
* header or tail throws exactly as it would through {@link TransactorSource.tryGet}. An
|
|
1502
|
+
* out-of-date tail no coordinator answered comes back flagged (`NetworkTransactor.get` flags that
|
|
1503
|
+
* one block rather than failing the request), and its answer is dropped unjudged.
|
|
1091
1504
|
*
|
|
1092
1505
|
* `tailFloor` (see {@link updateInternal}) goes on whichever request reads the tail — never on
|
|
1093
1506
|
* the header, which is rewritten only when the tail rolls over or the collection changes it
|