@optimystic/db-core 1.18.0 → 1.20.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -1
- package/dist/src/blocks/helpers.d.ts +7 -0
- package/dist/src/blocks/helpers.d.ts.map +1 -1
- package/dist/src/blocks/helpers.js +7 -1
- package/dist/src/blocks/helpers.js.map +1 -1
- package/dist/src/btree/btree.d.ts +100 -4
- package/dist/src/btree/btree.d.ts.map +1 -1
- package/dist/src/btree/btree.js +252 -90
- package/dist/src/btree/btree.js.map +1 -1
- package/dist/src/btree/node-division.d.ts +37 -0
- package/dist/src/btree/node-division.d.ts.map +1 -0
- package/dist/src/btree/node-division.js +133 -0
- package/dist/src/btree/node-division.js.map +1 -0
- package/dist/src/chain/chain.d.ts +23 -0
- package/dist/src/chain/chain.d.ts.map +1 -1
- package/dist/src/chain/chain.js +43 -6
- package/dist/src/chain/chain.js.map +1 -1
- package/dist/src/cluster/structs.d.ts +41 -8
- package/dist/src/cluster/structs.d.ts.map +1 -1
- package/dist/src/cluster/structs.js +18 -7
- package/dist/src/cluster/structs.js.map +1 -1
- package/dist/src/collection/action.d.ts +29 -0
- package/dist/src/collection/action.d.ts.map +1 -1
- package/dist/src/collection/action.js +6 -0
- package/dist/src/collection/action.js.map +1 -1
- package/dist/src/collection/collection.d.ts +566 -120
- package/dist/src/collection/collection.d.ts.map +1 -1
- package/dist/src/collection/collection.js +1084 -495
- package/dist/src/collection/collection.js.map +1 -1
- package/dist/src/collection/head-commit.d.ts +110 -0
- package/dist/src/collection/head-commit.d.ts.map +1 -0
- package/dist/src/collection/head-commit.js +65 -0
- package/dist/src/collection/head-commit.js.map +1 -0
- package/dist/src/collection/index.d.ts +2 -0
- package/dist/src/collection/index.d.ts.map +1 -1
- package/dist/src/collection/index.js +2 -0
- package/dist/src/collection/index.js.map +1 -1
- package/dist/src/collection/segments.d.ts +77 -0
- package/dist/src/collection/segments.d.ts.map +1 -0
- package/dist/src/collection/segments.js +110 -0
- package/dist/src/collection/segments.js.map +1 -0
- package/dist/src/collection/struct.d.ts +176 -1
- package/dist/src/collection/struct.d.ts.map +1 -1
- package/dist/src/collection/struct.js +70 -0
- package/dist/src/collection/struct.js.map +1 -1
- package/dist/src/collection/write-attempts.d.ts +245 -0
- package/dist/src/collection/write-attempts.d.ts.map +1 -0
- package/dist/src/collection/write-attempts.js +439 -0
- package/dist/src/collection/write-attempts.js.map +1 -0
- package/dist/src/collections/tree/struct.d.ts +100 -17
- package/dist/src/collections/tree/struct.d.ts.map +1 -1
- package/dist/src/collections/tree/struct.js +38 -7
- package/dist/src/collections/tree/struct.js.map +1 -1
- package/dist/src/collections/tree/tree.d.ts +17 -5
- package/dist/src/collections/tree/tree.d.ts.map +1 -1
- package/dist/src/collections/tree/tree.js +117 -29
- package/dist/src/collections/tree/tree.js.map +1 -1
- package/dist/src/index.d.ts +2 -0
- package/dist/src/index.d.ts.map +1 -1
- package/dist/src/index.js +2 -0
- package/dist/src/index.js.map +1 -1
- package/dist/src/log/log.d.ts +5 -1
- package/dist/src/log/log.d.ts.map +1 -1
- package/dist/src/log/log.js +7 -1
- package/dist/src/log/log.js.map +1 -1
- package/dist/src/network/block-size.d.ts +67 -0
- package/dist/src/network/block-size.d.ts.map +1 -0
- package/dist/src/network/block-size.js +82 -0
- package/dist/src/network/block-size.js.map +1 -0
- package/dist/src/network/i-repo.d.ts +3 -0
- package/dist/src/network/i-repo.d.ts.map +1 -1
- package/dist/src/network/index.d.ts +5 -0
- package/dist/src/network/index.d.ts.map +1 -1
- package/dist/src/network/index.js +5 -0
- package/dist/src/network/index.js.map +1 -1
- package/dist/src/network/promise-shortfall-error.d.ts +40 -0
- package/dist/src/network/promise-shortfall-error.d.ts.map +1 -0
- package/dist/src/network/promise-shortfall-error.js +67 -0
- package/dist/src/network/promise-shortfall-error.js.map +1 -0
- package/dist/src/network/refuse-solo.d.ts +8 -0
- package/dist/src/network/refuse-solo.d.ts.map +1 -0
- package/dist/src/network/refuse-solo.js +8 -0
- package/dist/src/network/refuse-solo.js.map +1 -0
- package/dist/src/network/stale-failure.d.ts +20 -3
- package/dist/src/network/stale-failure.d.ts.map +1 -1
- package/dist/src/network/stale-failure.js +24 -3
- package/dist/src/network/stale-failure.js.map +1 -1
- package/dist/src/network/struct.d.ts +161 -13
- package/dist/src/network/struct.d.ts.map +1 -1
- package/dist/src/network/struct.js.map +1 -1
- package/dist/src/network/transaction-size.d.ts +59 -0
- package/dist/src/network/transaction-size.d.ts.map +1 -0
- package/dist/src/network/transaction-size.js +74 -0
- package/dist/src/network/transaction-size.js.map +1 -0
- package/dist/src/network/validity-rejected-error.d.ts +28 -0
- package/dist/src/network/validity-rejected-error.d.ts.map +1 -0
- package/dist/src/network/validity-rejected-error.js +51 -0
- package/dist/src/network/validity-rejected-error.js.map +1 -0
- package/dist/src/offline/entry.d.ts +72 -0
- package/dist/src/offline/entry.d.ts.map +1 -0
- package/dist/src/offline/entry.js +73 -0
- package/dist/src/offline/entry.js.map +1 -0
- package/dist/src/offline/index.d.ts +5 -0
- package/dist/src/offline/index.d.ts.map +1 -0
- package/dist/src/offline/index.js +5 -0
- package/dist/src/offline/index.js.map +1 -0
- package/dist/src/offline/journal.d.ts +61 -0
- package/dist/src/offline/journal.d.ts.map +1 -0
- package/dist/src/offline/journal.js +2 -0
- package/dist/src/offline/journal.js.map +1 -0
- package/dist/src/offline/queue.d.ts +484 -0
- package/dist/src/offline/queue.d.ts.map +1 -0
- package/dist/src/offline/queue.js +1236 -0
- package/dist/src/offline/queue.js.map +1 -0
- package/dist/src/offline/reachability.d.ts +25 -0
- package/dist/src/offline/reachability.d.ts.map +1 -0
- package/dist/src/offline/reachability.js +13 -0
- package/dist/src/offline/reachability.js.map +1 -0
- package/dist/src/offline/status.d.ts +148 -0
- package/dist/src/offline/status.d.ts.map +1 -0
- package/dist/src/offline/status.js +63 -0
- package/dist/src/offline/status.js.map +1 -0
- package/dist/src/offline/wake.d.ts +30 -0
- package/dist/src/offline/wake.d.ts.map +1 -0
- package/dist/src/offline/wake.js +68 -0
- package/dist/src/offline/wake.js.map +1 -0
- package/dist/src/reactivity/config.d.ts +8 -4
- package/dist/src/reactivity/config.d.ts.map +1 -1
- package/dist/src/reactivity/config.js +7 -3
- package/dist/src/reactivity/config.js.map +1 -1
- package/dist/src/reactivity/rotation.d.ts +9 -3
- package/dist/src/reactivity/rotation.d.ts.map +1 -1
- package/dist/src/reactivity/rotation.js +8 -2
- package/dist/src/reactivity/rotation.js.map +1 -1
- package/dist/src/testing/test-transactor.d.ts +31 -0
- package/dist/src/testing/test-transactor.d.ts.map +1 -1
- package/dist/src/testing/test-transactor.js +60 -0
- package/dist/src/testing/test-transactor.js.map +1 -1
- package/dist/src/transaction/commit-failure-class.d.ts +103 -0
- package/dist/src/transaction/commit-failure-class.d.ts.map +1 -0
- package/dist/src/transaction/commit-failure-class.js +96 -0
- package/dist/src/transaction/commit-failure-class.js.map +1 -0
- package/dist/src/transaction/coordinator.d.ts +224 -31
- package/dist/src/transaction/coordinator.d.ts.map +1 -1
- package/dist/src/transaction/coordinator.js +841 -362
- package/dist/src/transaction/coordinator.js.map +1 -1
- package/dist/src/transaction/entry-commit.d.ts +139 -0
- package/dist/src/transaction/entry-commit.d.ts.map +1 -0
- package/dist/src/transaction/entry-commit.js +199 -0
- package/dist/src/transaction/entry-commit.js.map +1 -0
- package/dist/src/transaction/index.d.ts +4 -1
- package/dist/src/transaction/index.d.ts.map +1 -1
- package/dist/src/transaction/index.js +1 -0
- package/dist/src/transaction/index.js.map +1 -1
- package/dist/src/transaction/transaction.d.ts +20 -0
- package/dist/src/transaction/transaction.d.ts.map +1 -1
- package/dist/src/transaction/validator.d.ts +7 -0
- package/dist/src/transaction/validator.d.ts.map +1 -1
- package/dist/src/transaction/validator.js +21 -12
- package/dist/src/transaction/validator.js.map +1 -1
- package/dist/src/transactor/change-notifier.d.ts +13 -4
- package/dist/src/transactor/change-notifier.d.ts.map +1 -1
- package/dist/src/transactor/change-notifier.js.map +1 -1
- package/dist/src/transactor/network-transactor.d.ts +58 -8
- package/dist/src/transactor/network-transactor.d.ts.map +1 -1
- package/dist/src/transactor/network-transactor.js +244 -50
- package/dist/src/transactor/network-transactor.js.map +1 -1
- package/dist/src/transactor/transactor-source.d.ts +22 -11
- package/dist/src/transactor/transactor-source.d.ts.map +1 -1
- package/dist/src/transactor/transactor-source.js +9 -13
- package/dist/src/transactor/transactor-source.js.map +1 -1
- package/dist/src/transactor/transactor.d.ts +14 -0
- package/dist/src/transactor/transactor.d.ts.map +1 -1
- package/dist/src/transform/digest.d.ts +20 -0
- package/dist/src/transform/digest.d.ts.map +1 -1
- package/dist/src/transform/digest.js +23 -3
- package/dist/src/transform/digest.js.map +1 -1
- package/dist/src/utility/visit-every.d.ts +14 -0
- package/dist/src/utility/visit-every.d.ts.map +1 -0
- package/dist/src/utility/visit-every.js +27 -0
- package/dist/src/utility/visit-every.js.map +1 -0
- package/package.json +1 -1
- package/src/blocks/helpers.ts +8 -1
- package/src/btree/btree.ts +266 -88
- package/src/btree/node-division.ts +155 -0
- package/src/chain/chain.ts +55 -6
- package/src/cluster/structs.ts +42 -7
- package/src/collection/action.ts +34 -0
- package/src/collection/collection.ts +1167 -540
- package/src/collection/head-commit.ts +148 -0
- package/src/collection/index.ts +2 -0
- package/src/collection/segments.ts +149 -0
- package/src/collection/struct.ts +201 -1
- package/src/collection/write-attempts.ts +506 -0
- package/src/collections/tree/struct.ts +97 -17
- package/src/collections/tree/tree.ts +129 -31
- package/src/index.ts +2 -0
- package/src/log/log.ts +7 -1
- package/src/network/block-size.ts +81 -0
- package/src/network/i-repo.ts +3 -0
- package/src/network/index.ts +5 -0
- package/src/network/promise-shortfall-error.ts +69 -0
- package/src/network/refuse-solo.ts +7 -0
- package/src/network/stale-failure.ts +27 -4
- package/src/network/struct.ts +169 -15
- package/src/network/transaction-size.ts +73 -0
- package/src/network/validity-rejected-error.ts +55 -0
- package/src/offline/entry.ts +127 -0
- package/src/offline/index.ts +4 -0
- package/src/offline/journal.ts +60 -0
- package/src/offline/queue.ts +1342 -0
- package/src/offline/reachability.ts +32 -0
- package/src/offline/status.ts +183 -0
- package/src/offline/wake.ts +67 -0
- package/src/reactivity/config.ts +8 -4
- package/src/reactivity/rotation.ts +9 -3
- package/src/testing/test-transactor.ts +65 -0
- package/src/transaction/commit-failure-class.ts +133 -0
- package/src/transaction/coordinator.ts +969 -393
- package/src/transaction/entry-commit.ts +285 -0
- package/src/transaction/index.ts +4 -0
- package/src/transaction/transaction.ts +21 -0
- package/src/transaction/validator.ts +22 -12
- package/src/transactor/change-notifier.ts +13 -4
- package/src/transactor/network-transactor.ts +252 -55
- package/src/transactor/transactor-source.ts +29 -13
- package/src/transactor/transactor.ts +16 -0
- package/src/transform/digest.ts +36 -3
- package/src/utility/visit-every.ts +25 -0
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { IBlock, Action, ActionType, ActionHandler, BlockId, ITransactor, BlockStore, Transforms, ActionId, ActionLineage,
|
|
1
|
+
import type { IBlock, Action, ActionType, ActionHandler, BlockId, ITransactor, BlockStore, Transforms, ActionId, ActionLineage, GetBlockResult, CommitResult } from "../index.js";
|
|
2
2
|
import { Log } from "../log/log.js";
|
|
3
3
|
import type { LogBlock } from "../log/log.js";
|
|
4
4
|
import type { ActionEntry, GetFromResult, LogEntry } from "../log/struct.js";
|
|
@@ -6,27 +6,27 @@ import { Atomic } from "../transform/atomic.js";
|
|
|
6
6
|
import { Tracker } from "../transform/tracker.js";
|
|
7
7
|
import type { BasePins } from "../transform/base-pins.js";
|
|
8
8
|
import { CacheSource } from "../transform/cache-source.js";
|
|
9
|
-
import {
|
|
10
|
-
import
|
|
11
|
-
import { copyTransforms, isTransformsEmpty } from "../transform/helpers.js";
|
|
9
|
+
import type { BlockGets } from "../network/struct.js";
|
|
10
|
+
import { copyTransforms, emptyTransforms, isTransformsEmpty } from "../transform/helpers.js";
|
|
12
11
|
import { TransactorSource, answeredBlock, servedRevision } from "../transactor/transactor-source.js";
|
|
13
12
|
import { BlockFloors } from "../transactor/block-floors.js";
|
|
14
13
|
import type { WriteDurability } from "../network/struct.js";
|
|
15
|
-
import {
|
|
16
|
-
import {
|
|
17
|
-
import {
|
|
18
|
-
import
|
|
19
|
-
import {
|
|
20
|
-
import type { ActionContext } from "./action.js";
|
|
21
|
-
import { actionIdAt } from "./action.js";
|
|
14
|
+
import { withBlockRevs } from "../network/durability.js";
|
|
15
|
+
import type { CollectionHeaderBlock, CollectionId, CommittedTail, CommittedTailAnswer, CommittedTailQuery, HeadCommitOptions, ICollection, InFlightAttempt, InFlightCycle, OpenHeadCommitOptions, SyncOptions, TornActionReason } from "./index.js";
|
|
16
|
+
import { ActionRefusedError, CollectionHeaderVanishedError, SealedSegmentsError, TornActionError } from "./struct.js";
|
|
17
|
+
import { SegmentList } from "./segments.js";
|
|
18
|
+
import type { EntryId, SealedSegment } from "./segments.js";
|
|
19
|
+
import type { ActionContext, ActionRev, AlreadyAppliedTally } from "./action.js";
|
|
20
|
+
import { actionIdAt, addTallies, ZeroTally } from "./action.js";
|
|
21
|
+
import { AttemptCycle, resumedAttempt, retainedAttempt, stageAttempt } from "./write-attempts.js";
|
|
22
|
+
import type { AttemptTarget, Refresh, StagedAttempt, WriteIdentity } from "./write-attempts.js";
|
|
23
|
+
import { driveHeadCommit } from "./head-commit.js";
|
|
24
|
+
import type { HeadCommitHandle } from "./head-commit.js";
|
|
22
25
|
import type { ReadDependency } from "../transaction/transaction.js";
|
|
23
|
-
import { clampPriority, SlotHoldAfterLosses } from "../transaction/transaction.js";
|
|
24
26
|
import { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
|
|
25
27
|
import { randomBytes } from '@noble/hashes/utils.js';
|
|
26
28
|
import { toString as uint8ArrayToString } from 'uint8arrays/to-string';
|
|
27
29
|
import { Latches } from "../utility/latches.js";
|
|
28
|
-
import { jitteredBackoffMs, abortableDelay, makeAbortError } from "../utility/backoff.js";
|
|
29
|
-
import type { JitteredBackoffConfig, RandFn } from "../utility/backoff.js";
|
|
30
30
|
import { createLogger } from "../logger.js";
|
|
31
31
|
|
|
32
32
|
const log = createLogger('collection');
|
|
@@ -52,26 +52,6 @@ type DivergenceSite = 'refresh' | 'attach';
|
|
|
52
52
|
* as `forkRev=` / `heldAction=` / `readAction=`. */
|
|
53
53
|
type LineageFork = { rev: number, heldAction: ActionId, readAction: ActionId };
|
|
54
54
|
|
|
55
|
-
/** Exactly what one failed write attempt sent to the transactor — enough to send the same thing
|
|
56
|
-
* again. Retained by {@link Collection.retainInFlightAttempt} so that a refresh which then finds
|
|
57
|
-
* this attempt's own log entry can land the blocks the attempt left behind, at the same action id
|
|
58
|
-
* and revision (see {@link Collection.completeOwnEntry}). */
|
|
59
|
-
export type InFlightAttempt = {
|
|
60
|
-
/** The revision the attempt's log entry was stamped with, and pended and committed at. */
|
|
61
|
-
rev: number;
|
|
62
|
-
/** Every transform the attempt pended — the log blocks included. The caller hands over a copy
|
|
63
|
-
* it will not mutate; the collection keeps it as given. */
|
|
64
|
-
transforms: Transforms;
|
|
65
|
-
/** The attempt's log tail block, committed first. */
|
|
66
|
-
tailId: BlockId;
|
|
67
|
-
/** The per-block content declarations the attempt's commit carried, if any. */
|
|
68
|
-
blockDigests?: BlockContentDigests;
|
|
69
|
-
/** The per-block bases the attempt's pend carried, if any (see `PendRequest.baseRevs`). Kept
|
|
70
|
-
* with the transforms because they describe them: a re-send of these operations must name the
|
|
71
|
-
* same bases they were computed against. */
|
|
72
|
-
baseRevs?: BlockBaseRevs;
|
|
73
|
-
};
|
|
74
|
-
|
|
75
55
|
/** What one refresh ({@link Collection.refreshInFlight}, and the refresh inside a sync) found out
|
|
76
56
|
* about the write in flight on the instance's behalf. The caller hands in an empty report and the
|
|
77
57
|
* refresh fills it in AS IT GOES, rather than returning it at the end, so a refresh that throws
|
|
@@ -102,50 +82,24 @@ type LogEnds = {
|
|
|
102
82
|
served: Array<[BlockId, IBlock, number]>;
|
|
103
83
|
};
|
|
104
84
|
|
|
105
|
-
/**
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
*
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
* refresh made NO progress at all, so a client merely catching up is already excluded; if a
|
|
118
|
-
* spurious `SyncRevisionStalledError` ever shows up under real contention anyway, raise this. */
|
|
119
|
-
const DefaultMaxStalledAttempts = 2;
|
|
120
|
-
|
|
121
|
-
/**
|
|
122
|
-
* The sleep before the refresh that follows a write's `failures`-th consecutive loss.
|
|
123
|
-
*
|
|
124
|
-
* The jittered backoff exists to separate a herd of writers that lost the SAME race, so they do not
|
|
125
|
-
* re-collide on the next tick. A loss to a rival that had already committed (the refusal carried a
|
|
126
|
-
* confirmed `staleAt`) is not a herd, and once this write has taken `SlotHoldAfterLosses` such losses
|
|
127
|
-
* (`confirmedLosses`, counted over the whole write as a member counts its stale refusals of one
|
|
128
|
-
* action) the members that refused it hold the next slot for it — so sleeping only spends that hold.
|
|
129
|
-
* Both sides count the same refusals against the same constant, so the writer stops sleeping on the
|
|
130
|
-
* loss after which a member holds, with nothing said over the wire. A loss the latest refusal did not
|
|
131
|
-
* confirm (`latestConfirmed` false — a race against something still in flight) keeps the jitter.
|
|
132
|
-
*
|
|
133
|
-
* NOTE: against members that do not hold (an earlier release, `slotHoldWindowMs: 0`, or a member the
|
|
134
|
-
* refused pends did not reach) this retries without sleeping and so spends the same attempt budget
|
|
135
|
-
* sooner, at about twice one writer's pend rate (measured in the plan stage of
|
|
136
|
-
* `slot-hold-for-an-aged-writer`). Accepted: the backoff bought that writer nothing either, it only
|
|
137
|
-
* delayed the same give-up.
|
|
138
|
-
*/
|
|
139
|
-
function retryBackoffMs(failures: number, confirmedLosses: number, latestConfirmed: boolean,
|
|
140
|
-
config: JitteredBackoffConfig, rand?: RandFn): number {
|
|
141
|
-
if (latestConfirmed && confirmedLosses >= SlotHoldAfterLosses) {
|
|
142
|
-
return 0;
|
|
143
|
-
}
|
|
144
|
-
return jitteredBackoffMs(failures - 1, config, rand);
|
|
145
|
-
}
|
|
85
|
+
/** One block's answer in a {@link Collection.readCommittedTails} round: the repo's entry, or why
|
|
86
|
+
* reading the block failed. */
|
|
87
|
+
type AttributedRead = { entry: GetBlockResult | undefined } | { error: unknown };
|
|
88
|
+
type AttributedReads = Map<BlockId, AttributedRead>;
|
|
89
|
+
|
|
90
|
+
/** The tracker a head commit's attempts are built from: the head segment's actions staged over the
|
|
91
|
+
* committed state, and the revision the attempt built from it requests (see
|
|
92
|
+
* {@link Collection.headTrackerFor}). */
|
|
93
|
+
type HeadTracker = {
|
|
94
|
+
rev: number;
|
|
95
|
+
tracker: Tracker<IBlock>;
|
|
96
|
+
};
|
|
146
97
|
|
|
147
98
|
export type CollectionInitOptions<TAction> = {
|
|
148
|
-
|
|
99
|
+
/** One handler per action type. A handler may answer what the action accepted as already applied
|
|
100
|
+
* ({@link AlreadyAppliedTally}); one that answers nothing counts as the zero tally, so a collection
|
|
101
|
+
* type with no such notion returns nothing. */
|
|
102
|
+
modules: Record<ActionType, ActionHandler<TAction, AlreadyAppliedTally | void>>;
|
|
149
103
|
createHeaderBlock: (id: BlockId, store: BlockStore<IBlock>) => IBlock;
|
|
150
104
|
/** Called for each local action that is potentially in conflict with a remote action.
|
|
151
105
|
* @param action - The local action to check
|
|
@@ -154,7 +108,15 @@ export type CollectionInitOptions<TAction> = {
|
|
|
154
108
|
* action (return a new instance to apply instead of the original — it is re-staged via
|
|
155
109
|
* the conflict replay), or undefined to discard this action
|
|
156
110
|
*/
|
|
157
|
-
filterConflict?: (action: Action<TAction>, potential: Action<TAction>[]) => Action<TAction> | undefined
|
|
111
|
+
filterConflict?: (action: Action<TAction>, potential: Action<TAction>[]) => Action<TAction> | undefined;
|
|
112
|
+
/** Called once per refusal of a SEALED segment discovered by a replay (see
|
|
113
|
+
* {@link Collection.replayActions}): the segment's entry id and the handler's refusal. Called
|
|
114
|
+
* synchronously from inside the replay, under the collection latch, so it MUST NOT call a
|
|
115
|
+
* latched method of this collection ({@link Collection.update}, {@link Collection.dropSealed},
|
|
116
|
+
* {@link Collection.sync}, …) synchronously — the latch is non-reentrant and that would
|
|
117
|
+
* deadlock. The queue schedules its reaction instead. A throw out of the callback is caught and
|
|
118
|
+
* logged (`collection:refusal-callback-threw`), never allowed to abort the replay. */
|
|
119
|
+
onSealedRefused?: (entryId: EntryId, error: ActionRefusedError) => void;
|
|
158
120
|
}
|
|
159
121
|
|
|
160
122
|
/** Options for building a committed read view (see {@link Collection.createReadTracker}
|
|
@@ -189,8 +151,17 @@ export interface CollectionSnapshot<TAction> {
|
|
|
189
151
|
* were not built on. Absent on a snapshot built by hand; such a restore keeps whatever pins
|
|
190
152
|
* the tracker holds for the restored ids. */
|
|
191
153
|
pins?: BasePins;
|
|
192
|
-
/**
|
|
154
|
+
/** The OPEN segment's actions at snapshot time (see {@link SegmentList}). Sealed segments are
|
|
155
|
+
* not captured as actions — their effects are in `transforms`, which is what a committed read
|
|
156
|
+
* view built from this snapshot must include — and a restore never puts one back: whether it
|
|
157
|
+
* reinstates `transforms` verbatim or rebuilds the tracker from the sealed segments as they are
|
|
158
|
+
* then is decided by {@link sealedVersion} (see {@link Collection.restorePending}). */
|
|
193
159
|
pending: Action<TAction>[];
|
|
160
|
+
/** {@link SegmentList.version} at capture: a restore that finds the sealed list changed since —
|
|
161
|
+
* a segment sealed, dropped or refused while the snapshot was outstanding — replays rather than
|
|
162
|
+
* reinstating `transforms`, which would put a dropped segment's effects back. Absent on a
|
|
163
|
+
* snapshot built by hand, which reads as "unchanged". */
|
|
164
|
+
sealedVersion?: number;
|
|
194
165
|
/** The committed boundary (action context) the staged state sat on when captured.
|
|
195
166
|
* `undefined` for a collection with no committed revision yet (an invented
|
|
196
167
|
* collection whose header/root still live in the tracker). A read view built
|
|
@@ -201,9 +172,23 @@ export interface CollectionSnapshot<TAction> {
|
|
|
201
172
|
}
|
|
202
173
|
|
|
203
174
|
export class Collection<TAction> implements ICollection<TAction> {
|
|
204
|
-
|
|
175
|
+
/** The staged actions: sealed segments, one per queued entry, ahead of the open segment the
|
|
176
|
+
* current transaction stages into (see {@link SegmentList}). While nothing is sealed this is
|
|
177
|
+
* exactly the one pending list it replaced, and every path behaves as it did then. */
|
|
178
|
+
private readonly segments = new SegmentList<TAction>();
|
|
205
179
|
private readonly latchId: string;
|
|
206
180
|
|
|
181
|
+
/** The transforms an INVENTED collection starts from — its header, its empty log block and (for
|
|
182
|
+
* a tree) its empty root, as {@link createOrOpen}'s create branch staged them. A replay resets
|
|
183
|
+
* the tracker to a copy of this, rather than to empty, for as long as no committed revision has
|
|
184
|
+
* been adopted: those blocks are then nowhere but the tracker, and resetting to empty would drop
|
|
185
|
+
* them and leave the collection unreadable (the hazard {@link mustReplay} and
|
|
186
|
+
* {@link snapshotPending} describe). Never cleared — it is read only while
|
|
187
|
+
* `source.actionContext` is undefined, and once a context is adopted the blocks are in storage
|
|
188
|
+
* and the empty reset is the right one. `undefined` for a collection opened over a committed
|
|
189
|
+
* header, which never replays from a baseline. */
|
|
190
|
+
private inventedBaseline?: Transforms;
|
|
191
|
+
|
|
207
192
|
/** The action id of a write currently in flight ON THIS INSTANCE'S BEHALF, or `undefined`
|
|
208
193
|
* outside a write. Read by {@link updateInternal}: if the committed log now carries an entry
|
|
209
194
|
* under this id, that action's LOG TAIL landed despite the failure answer that sent us back here
|
|
@@ -253,7 +238,11 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
253
238
|
* Only the latest attempt is kept. An own entry can only be visible at the revision of an
|
|
254
239
|
* attempt whose tail landed, and a later attempt at a DIFFERENT revision is only made after a
|
|
255
240
|
* refresh adopted somebody else's entry at the earlier one — which is proof the earlier tail did
|
|
256
|
-
* not land. {@link completeOwnEntry} still checks the revision and refuses on a mismatch.
|
|
241
|
+
* not land. {@link completeOwnEntry} still checks the revision and refuses on a mismatch.
|
|
242
|
+
*
|
|
243
|
+
* A head commit may be opened with one already in hand ({@link openHeadCommit}'s `resume`): the
|
|
244
|
+
* attempt an earlier cycle under the same action id recorded through `HeadCommitOptions.recordAttempt`
|
|
245
|
+
* before sending it, which the cycle's opening refresh can then finish from. */
|
|
257
246
|
private inFlightAttempt?: InFlightAttempt;
|
|
258
247
|
|
|
259
248
|
/** The log data-block ids the append of the action marked in {@link inFlightActionId} has
|
|
@@ -262,6 +251,32 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
262
251
|
* {@link beginInFlightAction} and its disposer. */
|
|
263
252
|
private mintedLogBlockIds?: { rev: number; ids: BlockId[] };
|
|
264
253
|
|
|
254
|
+
/** What the cycle marked in {@link inFlightActionId} asked of every send it makes
|
|
255
|
+
* ({@link InFlightCycle}) — read by {@link send} and by the re-send {@link completeOwnEntry} makes
|
|
256
|
+
* to finish a torn attempt, so neither needs it threaded through. Set by
|
|
257
|
+
* {@link beginInFlightAction} and cleared by its disposer. */
|
|
258
|
+
private inFlightCycle: InFlightCycle = {};
|
|
259
|
+
|
|
260
|
+
/** The head commit running on this instance ({@link openHeadCommit}), for the whole cycle — set and
|
|
261
|
+
* cleared beside {@link inFlightActionId}: the sealed segment it is committing, and the hook told
|
|
262
|
+
* what that segment accepted as already applied when it is dropped as committed
|
|
263
|
+
* ({@link HeadCommitOptions.onCommittedHead}). Read by {@link consumeOwnEntry}: the entry a head
|
|
264
|
+
* commit's own refresh finds under the in-flight action id records the HEAD segment's actions, not
|
|
265
|
+
* the open segment's, so consuming it removes that segment — and reports it through the hook, as
|
|
266
|
+
* the handle's `fold` does. */
|
|
267
|
+
private headCommit?: { readonly entryId: EntryId; readonly onCommitted?: (applied: AlreadyAppliedTally) => void };
|
|
268
|
+
|
|
269
|
+
/** Set only while a head commit has RELEASED the collection latch for its one network round trip
|
|
270
|
+
* ({@link HeadCommitHandle.release}), and cleared the moment it is retaken, so anything that runs under the
|
|
271
|
+
* latch in that window can tell. Two things must: a refresh ({@link updateInternal}) that walks
|
|
272
|
+
* into the in-flight entry returns without adopting it, since it can neither finish it as the
|
|
273
|
+
* write's own (nothing failed, nothing is retained) nor replay it as a stranger's (that would
|
|
274
|
+
* re-stage the head over state that already contains it); and {@link dropSealed} refuses to drop
|
|
275
|
+
* the segment the commit is carrying. A second {@link commitHead} meets it as its `in-flight`
|
|
276
|
+
* precondition. Gated on THIS field, not on {@link inFlightActionId}: the head commit's own
|
|
277
|
+
* refreshes run with it cleared and must take the own-entry path. */
|
|
278
|
+
private headInFlight?: { entryId: EntryId; actionId: ActionId };
|
|
279
|
+
|
|
265
280
|
/** The log tail block id the most recent header read named. A refresh asks for this block in the
|
|
266
281
|
* same request as the header ({@link readLogEnds}): the tail id only changes when the tail block
|
|
267
282
|
* fills, so an idle refresh is one request rather than two. A stale value costs one extra request
|
|
@@ -271,7 +286,7 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
271
286
|
protected constructor(
|
|
272
287
|
public readonly id: CollectionId,
|
|
273
288
|
public readonly transactor: ITransactor,
|
|
274
|
-
private readonly handlers: Record<ActionType, ActionHandler<TAction>>,
|
|
289
|
+
private readonly handlers: Record<ActionType, ActionHandler<TAction, AlreadyAppliedTally | void>>,
|
|
275
290
|
private readonly source: TransactorSource<IBlock>,
|
|
276
291
|
/** Cache of unmodified blocks from the source */
|
|
277
292
|
private readonly sourceCache: CacheSource<IBlock>,
|
|
@@ -282,6 +297,8 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
282
297
|
* {@link BlockFloors}). */
|
|
283
298
|
private readonly floors: BlockFloors,
|
|
284
299
|
private readonly filterConflict?: (action: Action<TAction>, potential: Action<TAction>[]) => Action<TAction> | undefined,
|
|
300
|
+
/** See {@link CollectionInitOptions.onSealedRefused}. */
|
|
301
|
+
private readonly onSealedRefused?: (entryId: EntryId, error: ActionRefusedError) => void,
|
|
285
302
|
/** Short random tag naming THIS instance (see {@link newInstanceTag}). Open paths generate
|
|
286
303
|
* it BEFORE construction (so pre-construction diagnostics such as attachToLog can carry it);
|
|
287
304
|
* the default covers direct construction in tests. */
|
|
@@ -332,7 +349,7 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
332
349
|
return undefined;
|
|
333
350
|
}
|
|
334
351
|
await Collection.attachToLog<TAction>(source, sourceCache, tracker, floors, id, instanceTag, ends);
|
|
335
|
-
const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.filterConflict, instanceTag);
|
|
352
|
+
const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.filterConflict, init.onSealedRefused, instanceTag);
|
|
336
353
|
collection.logTailId = ends.header.tailId;
|
|
337
354
|
return collection;
|
|
338
355
|
}
|
|
@@ -348,6 +365,7 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
348
365
|
const instanceTag = Collection.newInstanceTag();
|
|
349
366
|
const { source, sourceCache, tracker, floors, ends } = await Collection.probeHeader(transactor, id, instanceTag);
|
|
350
367
|
|
|
368
|
+
let inventedBaseline: Transforms | undefined;
|
|
351
369
|
if (ends) { // Collection already exists
|
|
352
370
|
await Collection.attachToLog<TAction>(source, sourceCache, tracker, floors, id, instanceTag, ends);
|
|
353
371
|
} else { // Collection does not exist
|
|
@@ -356,10 +374,15 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
356
374
|
tracker.insert(headerBlock);
|
|
357
375
|
source.actionContext = undefined;
|
|
358
376
|
await Log.open<Action<TAction>>(tracker, id);
|
|
377
|
+
// Everything staged so far — the header (with the tail id Log.open wrote into it), the
|
|
378
|
+
// empty log block, and whatever createHeaderBlock staged beside the header — is what a
|
|
379
|
+
// replay has to put back while this collection has no committed revision.
|
|
380
|
+
inventedBaseline = copyTransforms(tracker.transforms);
|
|
359
381
|
}
|
|
360
382
|
|
|
361
|
-
const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.filterConflict, instanceTag);
|
|
383
|
+
const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.filterConflict, init.onSealedRefused, instanceTag);
|
|
362
384
|
collection.logTailId = ends?.header.tailId;
|
|
385
|
+
collection.inventedBaseline = inventedBaseline;
|
|
363
386
|
return collection;
|
|
364
387
|
}
|
|
365
388
|
|
|
@@ -376,11 +399,57 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
376
399
|
* Throws what a refresh's first read throws: `BlockUnavailableError` for a header or tail the
|
|
377
400
|
* storage layer could not retrieve, `BlockPossiblyStaleError` for one it could not confirm
|
|
378
401
|
* current. Neither is an absence. */
|
|
379
|
-
static async readCommittedTail(transactor: ITransactor, id: CollectionId, knownTailId?: BlockId): Promise<
|
|
402
|
+
static async readCommittedTail(transactor: ITransactor, id: CollectionId, knownTailId?: BlockId): Promise<CommittedTail | undefined> {
|
|
380
403
|
const ends = await Collection.readLogEnds(transactor, id, knownTailId);
|
|
381
404
|
const tailId = ends?.header.tailId;
|
|
382
|
-
|
|
383
|
-
|
|
405
|
+
return tailId === undefined ? undefined : Collection.committedTailOf(tailId, ends?.tail);
|
|
406
|
+
}
|
|
407
|
+
|
|
408
|
+
/** {@link readCommittedTail} for several collections at once, answered per collection: what
|
|
409
|
+
* the single read would have resolved, as `tail`, or what it would have thrown, as `error`. A
|
|
410
|
+
* collection named twice is read once.
|
|
411
|
+
*
|
|
412
|
+
* One request names every header and every known tail id. A collection whose header names a
|
|
413
|
+
* different tail than its known one costs a second request, shared by every such collection. So
|
|
414
|
+
* a poll of many collections whose logs stayed on their blocks is one request, however many it
|
|
415
|
+
* names; the per-block judgement is {@link readLogEnds}'s, through the same helpers.
|
|
416
|
+
*
|
|
417
|
+
* A block no coordinator answered comes back flagged and fails only its own collection, through
|
|
418
|
+
* the per-block judgement. A request that throws as a whole — `NetworkTransactor.get` does when a
|
|
419
|
+
* coordinator's answer leaves a block out — is not every collection's failure either:
|
|
420
|
+
* {@link readAttributed} then reads each block alone and only the collections whose blocks failed
|
|
421
|
+
* report an error. That fallback costs what reading each collection separately costs, and only
|
|
422
|
+
* when a request fails. */
|
|
423
|
+
static async readCommittedTails(transactor: ITransactor, queries: ReadonlyArray<CommittedTailQuery>): Promise<Map<CollectionId, CommittedTailAnswer>> {
|
|
424
|
+
const knownTails = new Map(queries.map(query => [query.id, query.knownTailId]));
|
|
425
|
+
const ends = await Collection.readAttributed(transactor,
|
|
426
|
+
[...knownTails].flatMap(([id, knownTailId]) => knownTailId === undefined ? [id] : [id, knownTailId]));
|
|
427
|
+
const answers = new Map<CollectionId, CommittedTailAnswer>();
|
|
428
|
+
/** Collections whose header names a tail other than the known one, with the tail it names. */
|
|
429
|
+
const moved = new Map<CollectionId, BlockId>();
|
|
430
|
+
for (const [id, knownTailId] of knownTails) {
|
|
431
|
+
try {
|
|
432
|
+
const tailId = Collection.answeredHeader(id, Collection.entryIn(ends, id))?.header.tailId;
|
|
433
|
+
if (tailId === undefined || tailId === knownTailId) {
|
|
434
|
+
answers.set(id, { tail: Collection.judgedTail(tailId, ends) });
|
|
435
|
+
} else {
|
|
436
|
+
moved.set(id, tailId);
|
|
437
|
+
}
|
|
438
|
+
} catch (error) {
|
|
439
|
+
answers.set(id, { error });
|
|
440
|
+
}
|
|
441
|
+
}
|
|
442
|
+
if (moved.size > 0) {
|
|
443
|
+
const tails = await Collection.readAttributed(transactor, [...new Set(moved.values())]);
|
|
444
|
+
for (const [id, tailId] of moved) {
|
|
445
|
+
try {
|
|
446
|
+
answers.set(id, { tail: Collection.judgedTail(tailId, tails) });
|
|
447
|
+
} catch (error) {
|
|
448
|
+
answers.set(id, { error });
|
|
449
|
+
}
|
|
450
|
+
}
|
|
451
|
+
}
|
|
452
|
+
return answers;
|
|
384
453
|
}
|
|
385
454
|
|
|
386
455
|
/** The per-instance read wiring every open path needs, plus the collection's log ends — the
|
|
@@ -414,7 +483,8 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
414
483
|
return { source, sourceCache, tracker, floors, ends };
|
|
415
484
|
}
|
|
416
485
|
|
|
417
|
-
/** A new handle's floors: none yet (
|
|
486
|
+
/** A new handle's floors: none yet (an open raises them from its log tail,
|
|
487
|
+
* {@link floorTailEntries}), wired to report every below-floor
|
|
418
488
|
* answer any of the handle's read sources receives. The line is the only trace such an answer
|
|
419
489
|
* leaves — the read itself succeeds (see the accepted-tradeoff NOTE at
|
|
420
490
|
* `TransactorSource.mayRetain`) — so repeated lines for one block with `servedRev` short of
|
|
@@ -446,6 +516,7 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
446
516
|
// Bootstrap ActionContext from the committed tail before walking the chain.
|
|
447
517
|
// This allows the transactor to serve pending non-tail blocks during Log.open.
|
|
448
518
|
Collection.bootstrapContext(source, ends.tail);
|
|
519
|
+
Collection.floorTailEntries(floors, ends);
|
|
449
520
|
// The walk starts from the header and the tail, which the probe just read: keep them, so the
|
|
450
521
|
// walk reads neither again. Its first read of each through the cache then records the read
|
|
451
522
|
// dependency the probe's own read of the header used to.
|
|
@@ -461,6 +532,31 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
461
532
|
Collection.advanceContext(source, id, instanceTag, 'attach', await collectionLog.getActionContext());
|
|
462
533
|
}
|
|
463
534
|
|
|
535
|
+
/** Floor every block an action entry in the opened log's tail block names, at that entry's
|
|
536
|
+
* revision — what a refresh's walk does for the entries it walks ({@link raiseFloors}), for the
|
|
537
|
+
* entries an open has read but does not walk.
|
|
538
|
+
*
|
|
539
|
+
* An open adopts the revision the tail names, then reads each block it needs for the first time.
|
|
540
|
+
* When the answering repo's copy of such a block is older than an entry the tail holds — a node
|
|
541
|
+
* whose crash kept a commit's log tail but lost its other blocks within the store's durability
|
|
542
|
+
* window, or a coordinator that missed the commit — nothing else tells the read so, and the
|
|
543
|
+
* repo serves its held copy (a held block's first read after a restart is answered locally while
|
|
544
|
+
* the consult runs behind it). The handle then shows, say, a table row whose index entry is
|
|
545
|
+
* missing. With the floor, the read carries the revision the tail proves, so the repo consults
|
|
546
|
+
* its cohort before answering and the transactor re-asks another machine for an answer still
|
|
547
|
+
* below it (see {@link BlockFloors}).
|
|
548
|
+
*
|
|
549
|
+
* Only the tail block's entries: they are what the open read, and they hold the newest commits —
|
|
550
|
+
* the ones a durability window can tear. Invalidation entries set no floor, as on a refresh. */
|
|
551
|
+
private static floorTailEntries(floors: BlockFloors, ends: LogEnds): void {
|
|
552
|
+
const tail = ends.tail?.block as LogBlock<unknown> | undefined;
|
|
553
|
+
for (const entry of tail?.entries ?? []) {
|
|
554
|
+
if (entry.action !== undefined) {
|
|
555
|
+
floors.raise(entry.action.blockIds, { rev: entry.rev, actionId: entry.action.actionId });
|
|
556
|
+
}
|
|
557
|
+
}
|
|
558
|
+
}
|
|
559
|
+
|
|
464
560
|
/** Adopt a freshly-read action context WITHOUT ever lowering the revision already held.
|
|
465
561
|
*
|
|
466
562
|
* The revision a collection last committed at is knowledge it earned; a read that found
|
|
@@ -637,21 +733,37 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
637
733
|
|
|
638
734
|
private async actInternal(...actions: Action<TAction>[]) {
|
|
639
735
|
await this.internalTransact(...actions);
|
|
640
|
-
|
|
736
|
+
// Staging appends to the OPEN segment: a sealed segment is closed to further staging.
|
|
737
|
+
this.segments.open.push(...actions);
|
|
641
738
|
}
|
|
642
739
|
|
|
643
|
-
private
|
|
644
|
-
|
|
740
|
+
private internalTransact(...actions: Action<TAction>[]): Promise<AlreadyAppliedTally> {
|
|
741
|
+
return this.stageInto(this.tracker, ...actions);
|
|
742
|
+
}
|
|
743
|
+
|
|
744
|
+
/** Run `actions` through their handlers over `tracker` as ONE atomic unit: a throw from any
|
|
745
|
+
* handler leaves none of their writes staged. The live tracker's path ({@link internalTransact})
|
|
746
|
+
* and a head commit's tracker ({@link buildHeadTracker}) share it.
|
|
747
|
+
*
|
|
748
|
+
* @returns the sum of what the handlers accepted as already applied ({@link AlreadyAppliedTally});
|
|
749
|
+
* a handler that answers nothing adds the zero tally. */
|
|
750
|
+
private async stageInto(tracker: Tracker<IBlock>, ...actions: Action<TAction>[]): Promise<AlreadyAppliedTally> {
|
|
751
|
+
const atomic = new Atomic(tracker);
|
|
752
|
+
let applied = ZeroTally;
|
|
645
753
|
|
|
646
754
|
for (const action of actions) {
|
|
647
755
|
const handler = this.handlers[action.type];
|
|
648
756
|
if (!handler) {
|
|
649
757
|
throw new Error(`No handler for action type ${action.type}`);
|
|
650
758
|
}
|
|
651
|
-
await handler(action, atomic);
|
|
759
|
+
const tally = await handler(action, atomic);
|
|
760
|
+
if (tally !== undefined) {
|
|
761
|
+
applied = addTallies(applied, tally);
|
|
762
|
+
}
|
|
652
763
|
}
|
|
653
764
|
|
|
654
765
|
atomic.commit();
|
|
766
|
+
return applied;
|
|
655
767
|
}
|
|
656
768
|
|
|
657
769
|
/** Load external changes and update our context to the latest log revision - resolve any conflicts with our pending actions. */
|
|
@@ -741,18 +853,23 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
741
853
|
// finish. `getStatus` is the cheap first question; it judges a block by who holds its
|
|
742
854
|
// LATEST revision, so a block this action landed and a later action has since built on
|
|
743
855
|
// reads there as not committed — those are asked again, properly, by settleUnfinished.
|
|
744
|
-
//
|
|
745
|
-
//
|
|
746
|
-
// made at — a forked lineage.
|
|
856
|
+
// A write's own cycle retains an attempt before any refresh can run, so from inside a cycle
|
|
857
|
+
// this branch is reached only when the entry sits at a revision the retained attempt was
|
|
858
|
+
// not made at — a forked lineage. The ordinary way here is a NEW cycle under an old id:
|
|
859
|
+
// the queue re-driving an entry whose earlier head commit ended in doubt without handing
|
|
860
|
+
// back the attempt it recorded ({@link openHeadCommit}, whose opening refresh runs with
|
|
861
|
+
// nothing retained unless `resume` seeds it).
|
|
747
862
|
const [status] = await this.transactor.getStatus([{ actionId: entry.actionId, blockIds: entry.blockIds }]);
|
|
748
863
|
if (entry.blockIds.every((_, i) => status?.statuses[i] === 'committed')) {
|
|
749
864
|
// Whole, and saved: the refresh reports it as finished (see RefreshReport), so the
|
|
750
865
|
// coordinator counts this participant as committed. Only WHO holds it is unknown.
|
|
751
|
-
// NOTE: a
|
|
752
|
-
//
|
|
753
|
-
//
|
|
754
|
-
// path above;
|
|
755
|
-
//
|
|
866
|
+
// NOTE: a write whose only commit was recognised here therefore answers `undefined` for
|
|
867
|
+
// a write that is saved, because both write paths read the report's durability, not the
|
|
868
|
+
// finished flag. For a sync that is the "nothing was written" answer, reachable only on
|
|
869
|
+
// the forked-lineage path above; for a head commit it is unambiguous (a head segment is
|
|
870
|
+
// never empty) and is how a re-driven entry is answered. If the queue ever needs a
|
|
871
|
+
// durability class for a re-driven entry, take it from `getLineage` (as
|
|
872
|
+
// settleUnfinished does) instead of stopping at the status read.
|
|
756
873
|
return undefined;
|
|
757
874
|
}
|
|
758
875
|
return await this.settleUnfinished(entry, rev, undefined, 'transforms-not-held',
|
|
@@ -773,7 +890,11 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
773
890
|
// pair is not obviously right either: a member re-executing the transaction after a sibling
|
|
774
891
|
// participant has landed no longer sees the state it was staged against. Tracked as an arm
|
|
775
892
|
// of tickets/backlog/feat-no-deployment-validates-transactions-at-pend.
|
|
776
|
-
const result = await this.source.transact(attempt.transforms, entry.actionId, rev, this.id, attempt.tailId,
|
|
893
|
+
const result = await this.source.transact(attempt.transforms, entry.actionId, rev, this.id, attempt.tailId, {
|
|
894
|
+
blockDigests: attempt.blockDigests,
|
|
895
|
+
baseRevs: attempt.baseRevs,
|
|
896
|
+
refuseSolo: this.inFlightCycle.refuseSolo
|
|
897
|
+
});
|
|
777
898
|
if (result.success) {
|
|
778
899
|
return result.durability;
|
|
779
900
|
}
|
|
@@ -791,6 +912,13 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
791
912
|
// needs the clocks to start disagreeing between a write's attempts, since an expiry on the
|
|
792
913
|
// attempt itself ends the write before any refresh. If it is ever seen burning a budget,
|
|
793
914
|
// settle it at once beside the confirmed rival.
|
|
915
|
+
// NOTE: a promise shortfall of the re-send (`isShortfallFailure`) lands in the same arm, and
|
|
916
|
+
// there it can genuinely clear (the silent members come back), so the write is re-sent each
|
|
917
|
+
// round until the budget's last round settles it — unlike a fresh attempt's shortfall, which
|
|
918
|
+
// ends the write at once. If a silent cohort is ever seen holding torn writes for the whole
|
|
919
|
+
// budget, settle it at once here too.
|
|
920
|
+
// A validity rejection (`isRejectedFailure`) cannot answer the re-send: it carries no
|
|
921
|
+
// `validation` pair (above), so no checker judges it.
|
|
794
922
|
// NOTE: a confirmed rival settles at once, even with retry budget left: re-sending is
|
|
795
923
|
// pointless, but the lineage question is asked only this once, so a member that is silent
|
|
796
924
|
// just now makes the answer `final: false`. If unsettled outcomes ever show up often under
|
|
@@ -907,47 +1035,122 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
907
1035
|
* {@link completeOwnEntry} has returned for this entry — the entry alone is not proof the write
|
|
908
1036
|
* is saved.
|
|
909
1037
|
*
|
|
910
|
-
* `
|
|
911
|
-
* actions are therefore the LEADING `entry.actions.length` items of
|
|
912
|
-
* staged since is behind them, because {@link actInternal}
|
|
913
|
-
* {@link syncInternal} nothing can even be staged mid-cycle (`act()` shares the
|
|
914
|
-
* latch); under `TransactionCoordinator.commit` the mark spans a latch-free
|
|
915
|
-
* window, so an `act()` there CAN grow
|
|
916
|
-
* right.
|
|
917
|
-
*
|
|
918
|
-
*
|
|
919
|
-
*
|
|
920
|
-
*
|
|
921
|
-
*
|
|
922
|
-
|
|
923
|
-
|
|
1038
|
+
* A whole-collection write (`sync`) wrote exactly the snapshot of the OPEN segment under this
|
|
1039
|
+
* action id, and the entry's actions are therefore the LEADING `entry.actions.length` items of
|
|
1040
|
+
* the open segment — anything staged since is behind them, because {@link actInternal}
|
|
1041
|
+
* appends. Under {@link syncInternal} nothing can even be staged mid-cycle (`act()` shares the
|
|
1042
|
+
* collection latch); under `TransactionCoordinator.commit` the mark spans a latch-free
|
|
1043
|
+
* inter-attempt window, so an `act()` there CAN grow the open segment — still only at the
|
|
1044
|
+
* tail, so the slice stays right. No sealed segment can exist for such a write: every
|
|
1045
|
+
* whole-collection path refuses while one does ({@link SealedSegmentsError}).
|
|
1046
|
+
*
|
|
1047
|
+
* A head commit ({@link commitHead}, which marks {@link headCommit} for its cycle) wrote the
|
|
1048
|
+
* HEAD sealed segment's actions, so its entry is consumed by removing that segment — the open
|
|
1049
|
+
* segment, which may have grown while the commit was on the network, is untouched. The sealed
|
|
1050
|
+
* segments behind the head are never touched by either arm.
|
|
1051
|
+
*
|
|
1052
|
+
* The guards are the load-bearing part: `slice` fails SILENTLY if the open correspondence ever
|
|
1053
|
+
* breaks, dropping actions that were never committed, so an entry longer than the open segment
|
|
1054
|
+
* throws instead of losing work, and an entry whose action count is not the head's throws rather
|
|
1055
|
+
* than removing a segment the entry does not record. (See the sibling note on `syncInternal`'s
|
|
1056
|
+
* post-commit replay, which rests on the same invariant.)
|
|
1057
|
+
*
|
|
1058
|
+
* @returns whether the staged set changed — always true here: even for a zero-action entry the
|
|
1059
|
+
* tracker still holds this action's staged transforms, and only the replay at the end of
|
|
1060
|
+
* `updateInternal` — which resets the tracker and re-stages just what remains — drops them.
|
|
1061
|
+
* That reset is what turns `hasUnsyncedChanges()` false so the sync loop exits reporting the
|
|
1062
|
+
* success the writer is owed (the action IS durable). */
|
|
1063
|
+
private consumeOwnEntry(entry: ActionEntry<Action<TAction>>): boolean {
|
|
1064
|
+
if (this.headCommit !== undefined) {
|
|
1065
|
+
this.consumeHead(entry, this.headCommit.entryId);
|
|
1066
|
+
} else {
|
|
1067
|
+
this.segments.open = this.consumedFromOpen(entry);
|
|
1068
|
+
}
|
|
1069
|
+
return true;
|
|
1070
|
+
}
|
|
1071
|
+
|
|
1072
|
+
/** Remove the head segment `entryId` because `entry`, its own committed log entry, made it
|
|
1073
|
+
* durable — the head arm of {@link consumeOwnEntry}. Bumps the segment version, so an outstanding
|
|
1074
|
+
* snapshot restores by replay rather than putting the committed segment back, and reports the
|
|
1075
|
+
* dropped segment's tally through the cycle's hook ({@link reportCommittedHead}), as the handle's
|
|
1076
|
+
* `fold` does for an attempt that committed. */
|
|
1077
|
+
private consumeHead(entry: ActionEntry<Action<TAction>>, entryId: EntryId): void {
|
|
1078
|
+
const head = this.segments.head();
|
|
1079
|
+
if (head === undefined || head.entryId !== entryId) {
|
|
1080
|
+
throw new Error(
|
|
1081
|
+
`Collection ${this.id}: own committed entry for action ${entry.actionId} records head segment `
|
|
1082
|
+
+ `${entryId}, but the head is ${head?.entryId ?? 'nothing'}`);
|
|
1083
|
+
}
|
|
1084
|
+
if (entry.actions.length !== head.actions.length) {
|
|
1085
|
+
throw new Error(
|
|
1086
|
+
`Collection ${this.id}: own committed entry for action ${entry.actionId} holds `
|
|
1087
|
+
+ `${entry.actions.length} actions but head segment ${entryId} holds ${head.actions.length}; `
|
|
1088
|
+
+ `consuming it would drop actions that were never committed`);
|
|
1089
|
+
}
|
|
1090
|
+
this.reportCommittedHead(this.segments.drop(entryId));
|
|
1091
|
+
}
|
|
1092
|
+
|
|
1093
|
+
/** Hand the tally recorded on `segment` — the head segment just made durable and dropped — to the
|
|
1094
|
+
* cycle's `onCommittedHead` hook ({@link HeadCommitOptions.onCommittedHead}), under the latch, from
|
|
1095
|
+
* the two places that drop a head segment as committed: the handle's `fold`, and
|
|
1096
|
+
* {@link consumeHead}. A segment with no recorded tally is a defect, answered with the zero tally
|
|
1097
|
+
* and logged rather than thrown: every sealed segment is staged by {@link buildHeadTracker} before
|
|
1098
|
+
* its first send and by a replay when put back ({@link restoreSealed}), and the resume path that
|
|
1099
|
+
* re-sends a recorded attempt verbatim runs after one of those. A throw out of the hook is logged,
|
|
1100
|
+
* never raised — the commit is already durable. */
|
|
1101
|
+
private reportCommittedHead(segment: SealedSegment<TAction>): void {
|
|
1102
|
+
let applied = segment.applied;
|
|
1103
|
+
if (applied === undefined) {
|
|
1104
|
+
log('collection:committed-head-tally-missing id=%s tag=%s entry=%s: the head segment was committed without a recorded staging',
|
|
1105
|
+
this.id, this.instanceTag, segment.entryId);
|
|
1106
|
+
applied = ZeroTally;
|
|
1107
|
+
}
|
|
1108
|
+
const hook = this.headCommit?.onCommitted;
|
|
1109
|
+
if (hook === undefined) {
|
|
1110
|
+
return;
|
|
1111
|
+
}
|
|
1112
|
+
try {
|
|
1113
|
+
hook(applied);
|
|
1114
|
+
} catch (err) {
|
|
1115
|
+
log('collection:committed-head-callback-threw id=%s tag=%s entry=%s error=%s',
|
|
1116
|
+
this.id, this.instanceTag, segment.entryId, err instanceof Error ? err.message : String(err));
|
|
1117
|
+
}
|
|
1118
|
+
}
|
|
1119
|
+
|
|
1120
|
+
/** The open segment with the leading actions `entry` made durable dropped off it. */
|
|
1121
|
+
private consumedFromOpen(entry: ActionEntry<Action<TAction>>): Action<TAction>[] {
|
|
1122
|
+
const open = this.segments.open;
|
|
1123
|
+
if (entry.actions.length > open.length) {
|
|
924
1124
|
throw new Error(
|
|
925
1125
|
`Collection ${this.id}: own committed entry for action ${entry.actionId} holds `
|
|
926
|
-
+ `${entry.actions.length} actions but only ${
|
|
1126
|
+
+ `${entry.actions.length} actions but only ${open.length} are pending; `
|
|
927
1127
|
+ `consuming it would drop actions that were never committed`);
|
|
928
1128
|
}
|
|
929
|
-
|
|
930
|
-
// action's staged transforms, and only the replay at the end of `updateInternal` — which
|
|
931
|
-
// resets the tracker and re-stages just what remains — drops them. That reset is what turns
|
|
932
|
-
// `hasUnsyncedChanges()` false so the sync loop exits reporting the success the writer is
|
|
933
|
-
// owed (the action IS durable).
|
|
934
|
-
return { after: this.pending.slice(entry.actions.length), mutated: true };
|
|
1129
|
+
return open.slice(entry.actions.length);
|
|
935
1130
|
}
|
|
936
1131
|
|
|
937
|
-
/** Maps each
|
|
938
|
-
* replacement, or dropped. A replacement or a discard changes the
|
|
1132
|
+
/** Maps each OPEN-segment action to its effective form against a remote entry: the original, a
|
|
1133
|
+
* replacement, or dropped. A replacement or a discard changes the staged set; the tracker still
|
|
939
1134
|
* holds the pre-filter transforms, so report it as mutated to force a replay that re-stages
|
|
940
1135
|
* against the effective actions. Identity comparison per the contract: keep => same instance,
|
|
941
1136
|
* replace => new instance.
|
|
1137
|
+
*
|
|
1138
|
+
* A SEALED segment's action list is the queue entry's own and is never rewritten (invariant 3
|
|
1139
|
+
* of docs/offline-sync.md §The segment model), so the hook is not offered them. `Tree` and
|
|
1140
|
+
* `Diary` install no hook, so nothing observable changes for them either way.
|
|
1141
|
+
*
|
|
942
1142
|
* NOTE: a filterConflict hook that always allocates a fresh (but equal) instance instead of
|
|
943
1143
|
* returning the same one forces a replay on every update — if that ever shows up as a hot path,
|
|
944
|
-
* compare by value/id here instead of by reference.
|
|
945
|
-
|
|
946
|
-
|
|
1144
|
+
* compare by value/id here instead of by reference.
|
|
1145
|
+
*
|
|
1146
|
+
* @returns whether the open segment changed. */
|
|
1147
|
+
private filterAgainstEntry(entry: ActionEntry<Action<TAction>>): boolean {
|
|
1148
|
+
const before = this.segments.open;
|
|
947
1149
|
const after = before
|
|
948
1150
|
.map(p => this.doFilterConflict(p, entry.actions))
|
|
949
1151
|
.filter((a): a is Action<TAction> => a !== undefined);
|
|
950
|
-
|
|
1152
|
+
this.segments.open = after;
|
|
1153
|
+
return after.length !== before.length || after.some((a, i) => a !== before[i]);
|
|
951
1154
|
}
|
|
952
1155
|
|
|
953
1156
|
/** Refresh this instance against the stored log: adopt the latest committed revision, resolve
|
|
@@ -1039,6 +1242,21 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1039
1242
|
const collectionLog = await Log.open<Action<TAction>>(tracker, this.id);
|
|
1040
1243
|
const latest = collectionLog ? await collectionLog.getFrom(actionContext?.rev ?? 0) : undefined;
|
|
1041
1244
|
|
|
1245
|
+
// A refresh that runs while this instance's own head commit is on the network — a reader's,
|
|
1246
|
+
// the latch being released for that round trip — and walks into that commit's entry adopts
|
|
1247
|
+
// NOTHING (see {@link headInFlight}): the entry is not failed, so it is not finished and consumed
|
|
1248
|
+
// as the write's own below, and it is not a stranger's, so it is not filtered and replayed. The
|
|
1249
|
+
// head commit applies its own outcome when it retakes the latch, after which the next refresh
|
|
1250
|
+
// finds nothing new. The reader is served the state before this collection's own write, which it
|
|
1251
|
+
// sees staged anyway. Entries behind it in the same walk wait with it — an own entry is always
|
|
1252
|
+
// the first above the held revision, since the attempt requested exactly that revision.
|
|
1253
|
+
const headInFlight = this.headInFlight;
|
|
1254
|
+
if (headInFlight !== undefined && latest?.entries.some(entry => entry.actionId === headInFlight.actionId)) {
|
|
1255
|
+
log('collection:refresh-deferred-to-head-commit id=%s tag=%s entry=%s action=%s',
|
|
1256
|
+
this.id, this.instanceTag, headInFlight.entryId, headInFlight.actionId);
|
|
1257
|
+
return;
|
|
1258
|
+
}
|
|
1259
|
+
|
|
1042
1260
|
// This write's own entry, if its log tail landed despite the failure that sent us here.
|
|
1043
1261
|
// Decided ONCE, here: the mark can be cleared latch-free while the completion below is
|
|
1044
1262
|
// awaiting (see {@link inFlightActionId}), and an entry that was finished as our own must
|
|
@@ -1062,11 +1280,9 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1062
1280
|
// Process the entries and track the blocks they affect
|
|
1063
1281
|
let anyConflicts = false;
|
|
1064
1282
|
for (const entry of latest?.entries ?? []) {
|
|
1065
|
-
const
|
|
1066
|
-
const { after, mutated } = isOwnEntry
|
|
1283
|
+
const mutated = entry === ownEntry
|
|
1067
1284
|
? this.consumeOwnEntry(entry)
|
|
1068
1285
|
: this.filterAgainstEntry(entry);
|
|
1069
|
-
this.pending = after;
|
|
1070
1286
|
anyConflicts = anyConflicts || mutated || this.tracker.conflicts(new Set(entry.blockIds)).length > 0;
|
|
1071
1287
|
}
|
|
1072
1288
|
|
|
@@ -1078,7 +1294,7 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1078
1294
|
// block; over-inclusive by design (over-invalidation just resubmits — it never wrongly retains).
|
|
1079
1295
|
const invalidations = collectionLog ? await collectionLog.getInvalidationsFrom(actionContext?.rev ?? 0) : [];
|
|
1080
1296
|
const revertedBlockIds = [...new Set(invalidations.flatMap(inv => inv.reverted.map(r => r.blockId)))];
|
|
1081
|
-
if (invalidations.length > 0 && this.
|
|
1297
|
+
if (invalidations.length > 0 && this.segments.replayableCount() > 0) {
|
|
1082
1298
|
anyConflicts = true;
|
|
1083
1299
|
}
|
|
1084
1300
|
|
|
@@ -1086,15 +1302,17 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1086
1302
|
|
|
1087
1303
|
Collection.reportShortfall(this.id, this.instanceTag, tailRev, actionContext?.rev, this.source.actionContext?.rev);
|
|
1088
1304
|
|
|
1089
|
-
// Re-stage the
|
|
1305
|
+
// Re-stage the staged actions against the adopted revision. The affected
|
|
1090
1306
|
// blocks were already dropped from sourceCache above (per log entry / per invalidation),
|
|
1091
1307
|
// so the replay's reads re-materialize from the transactor.
|
|
1092
|
-
// NOTE: a throw out of replayActions
|
|
1093
|
-
//
|
|
1094
|
-
//
|
|
1095
|
-
//
|
|
1096
|
-
//
|
|
1097
|
-
//
|
|
1308
|
+
// NOTE: a throw out of replayActions — a refusal of the OPEN segment, or any non-refusal
|
|
1309
|
+
// error — leaves the tracker holding only the transforms replayed so far while the open
|
|
1310
|
+
// segment still lists all of its actions; the caller's error handling is expected to
|
|
1311
|
+
// abort/reset the collection rather than keep staging. The coordinator's partial report
|
|
1312
|
+
// after a refresh-saved sibling does not (backlog: debt-a-failed-refresh-can-leave-a-
|
|
1313
|
+
// collection-half-restaged). A SEALED segment is not left half-replayed: it is staged
|
|
1314
|
+
// atomically, and a refusal of one is recorded and skipped rather than thrown. If replay ever
|
|
1315
|
+
// gains a routinely-throwing read path, rebuild into a scratch tracker and swap on success.
|
|
1098
1316
|
if (this.mustReplay(anyConflicts, actionContext)) {
|
|
1099
1317
|
await this.replayActions();
|
|
1100
1318
|
}
|
|
@@ -1313,8 +1531,8 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1313
1531
|
});
|
|
1314
1532
|
}
|
|
1315
1533
|
|
|
1316
|
-
/** Whether {@link updateInternal} must re-stage
|
|
1317
|
-
* context it held BEFORE the refresh.
|
|
1534
|
+
/** Whether {@link updateInternal} must re-stage the staged actions after adopting `latest`,
|
|
1535
|
+
* given the context it held BEFORE the refresh.
|
|
1318
1536
|
*
|
|
1319
1537
|
* The answer is deliberately NOT just "a conflict was found". A conflict is detected by an
|
|
1320
1538
|
* incoming log entry naming a block this tracker already holds a transform for — so an action
|
|
@@ -1329,16 +1547,17 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1329
1547
|
* The advance test rests on {@link advanceContext} being monotonic (it refuses to lower), which
|
|
1330
1548
|
* is what makes "the adopted rev differs from the held one" mean "it went up".
|
|
1331
1549
|
*
|
|
1332
|
-
* The second conjunct
|
|
1333
|
-
*
|
|
1334
|
-
*
|
|
1335
|
-
* {@link
|
|
1336
|
-
*
|
|
1337
|
-
* {@link
|
|
1338
|
-
*
|
|
1339
|
-
*
|
|
1340
|
-
*
|
|
1341
|
-
*
|
|
1550
|
+
* The second conjunct counts the REPLAYABLE actions — every non-refused sealed segment's plus
|
|
1551
|
+
* the open segment's, since a refresh that adopts a newer revision must re-stage the sealed
|
|
1552
|
+
* segments too — and deliberately NOT {@link hasUnsyncedChanges}, which also counts tracker
|
|
1553
|
+
* transforms. A collection {@link createOrOpen} just INVENTED holds its staged header/root in
|
|
1554
|
+
* the tracker with NO staged action naming them; {@link replayActions} now restores them from
|
|
1555
|
+
* {@link inventedBaseline}, but nothing to re-stage still means nothing to replay, and a replay
|
|
1556
|
+
* over no actions would be a wasted tracker rebuild.
|
|
1557
|
+
*
|
|
1558
|
+
* NOTE: this makes a refresh that adopts a newer revision O(staged actions) rather than free,
|
|
1559
|
+
* so a read taken mid-transaction while a rival keeps committing re-stages every action staged
|
|
1560
|
+
* so far, on each such read. Measured as no change to the storage-op budgets
|
|
1342
1561
|
* (`index-backfill-cost.spec.ts`, `cold-apply-cost.spec.ts`), because the replay's reads are
|
|
1343
1562
|
* served from `sourceCache`. If a long transaction's reads ever show up as slow, narrow the
|
|
1344
1563
|
* replay to the actions whose reads the adopted entries actually invalidated — NOT back to
|
|
@@ -1348,7 +1567,8 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1348
1567
|
return true;
|
|
1349
1568
|
}
|
|
1350
1569
|
const adoptedRev = this.source.actionContext?.rev;
|
|
1351
|
-
|
|
1570
|
+
const replayable = this.segments.replayableCount();
|
|
1571
|
+
if (adoptedRev !== undefined && adoptedRev !== priorContext?.rev && replayable > 0) {
|
|
1352
1572
|
return true;
|
|
1353
1573
|
}
|
|
1354
1574
|
// Third reason: a staged block's base has MOVED — the read cache no longer describes it at
|
|
@@ -1356,22 +1576,19 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1356
1576
|
// that adopted nothing and found no conflict can still be standing over such a block: a
|
|
1357
1577
|
// concurrent read served content the cache then kept at a newer revision, say. Re-staging
|
|
1358
1578
|
// is the only repair; declaring the pinned revision on the pend would merely get it refused.
|
|
1359
|
-
return
|
|
1579
|
+
return replayable > 0 && this.logMovedBases(this.tracker.movedBases()) > 0;
|
|
1360
1580
|
}
|
|
1361
1581
|
|
|
1362
1582
|
/** Re-judge every staged update's pinned base against the read cache and re-stage the pending
|
|
1363
1583
|
* queue if any has moved. Runs immediately before each pend attempt — {@link syncAttempts} and
|
|
1364
|
-
* the coordinator's commit span both call it
|
|
1365
|
-
*
|
|
1366
|
-
*
|
|
1584
|
+
* the coordinator's commit span both call it, and {@link headTrackerFor} re-judges a head
|
|
1585
|
+
* commit's tracker the same way — because that is the last moment before the base the pend
|
|
1586
|
+
* declares is put on the wire, and nothing between a refused attempt and the re-pend reads the
|
|
1587
|
+
* block again (the refresh may have moved nothing and so replayed nothing).
|
|
1367
1588
|
*
|
|
1368
|
-
* Two steps. First, one read for each pinned block the cache does NOT retain
|
|
1369
|
-
*
|
|
1370
|
-
*
|
|
1371
|
-
* and only a read can tell. An evicted-but-kept base needs no read: its content met every floor
|
|
1372
|
-
* the handle knows, so storage cannot have moved it without a log entry the next refresh will
|
|
1373
|
-
* walk (and the pend would be refused as stale on revision alone). Then, one cache probe per
|
|
1374
|
-
* pinned block ({@link Tracker.movedBases}) and a replay if any moved.
|
|
1589
|
+
* Two steps. First, one read for each pinned block the cache does NOT retain
|
|
1590
|
+
* ({@link rereadUnretainedBases}). Then, one cache probe per pinned block
|
|
1591
|
+
* ({@link Tracker.movedBases}) and a replay if any moved.
|
|
1375
1592
|
*
|
|
1376
1593
|
* Latch-free by contract, like {@link snapshotPending}: the caller holds this instance's latch
|
|
1377
1594
|
* ({@link replayActions} is always run under it).
|
|
@@ -1383,18 +1600,30 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1383
1600
|
*
|
|
1384
1601
|
* @returns whether the pending queue was re-staged. */
|
|
1385
1602
|
async restageIfBasesMoved(): Promise<boolean> {
|
|
1386
|
-
|
|
1387
|
-
|
|
1388
|
-
|
|
1389
|
-
|
|
1390
|
-
}
|
|
1391
|
-
if (this.pending.length === 0 || this.logMovedBases(this.tracker.movedBases()) === 0) {
|
|
1603
|
+
await this.rereadUnretainedBases(this.tracker);
|
|
1604
|
+
// Every replayable action counts, sealed segments included: a moved base under a sealed
|
|
1605
|
+
// segment's operations is re-staged the same way.
|
|
1606
|
+
if (this.segments.replayableCount() === 0 || this.logMovedBases(this.tracker.movedBases()) === 0) {
|
|
1392
1607
|
return false;
|
|
1393
1608
|
}
|
|
1394
1609
|
await this.replayActions();
|
|
1395
1610
|
return true;
|
|
1396
1611
|
}
|
|
1397
1612
|
|
|
1613
|
+
/** One read for each of `tracker`'s pinned blocks the cache does NOT retain — content handed
|
|
1614
|
+
* through unkept (a below-floor answer, which the cache re-asks for on every read anyway): the
|
|
1615
|
+
* pin names the revision last served, storage may have caught up since without the log moving,
|
|
1616
|
+
* and only a read can tell. An evicted-but-kept base needs no read: its content met every floor
|
|
1617
|
+
* the handle knows, so storage cannot have moved it without a log entry the next refresh will
|
|
1618
|
+
* walk (and the pend would be refused as stale on revision alone). */
|
|
1619
|
+
private async rereadUnretainedBases(tracker: Tracker<IBlock>): Promise<void> {
|
|
1620
|
+
for (const id of tracker.unretainedBases()) {
|
|
1621
|
+
// `navigation` never upgrades the purpose the original read recorded (value-wins), and
|
|
1622
|
+
// the revision recorded is the one returned, which a replay re-records anyway.
|
|
1623
|
+
await this.sourceCache.tryGet(id, 'navigation');
|
|
1624
|
+
}
|
|
1625
|
+
}
|
|
1626
|
+
|
|
1398
1627
|
/** Report each moved base, naming the revision the operations were computed against and the
|
|
1399
1628
|
* one the cache describes now, and return how many there were. */
|
|
1400
1629
|
private logMovedBases(moved: readonly BlockId[]): number {
|
|
@@ -1426,7 +1655,8 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1426
1655
|
return {
|
|
1427
1656
|
transforms: copyTransforms(this.tracker.transforms),
|
|
1428
1657
|
pins: this.tracker.pins.copy(),
|
|
1429
|
-
pending: [...this.
|
|
1658
|
+
pending: [...this.segments.open],
|
|
1659
|
+
sealedVersion: this.segments.version,
|
|
1430
1660
|
context: structuredClone(this.source.actionContext),
|
|
1431
1661
|
};
|
|
1432
1662
|
}
|
|
@@ -1435,40 +1665,80 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1435
1665
|
* mutations staged since. Reads through the collection then observe exactly the
|
|
1436
1666
|
* snapshot state again; storage is untouched because nothing was ever synced.
|
|
1437
1667
|
*
|
|
1438
|
-
*
|
|
1439
|
-
*
|
|
1440
|
-
*
|
|
1441
|
-
*
|
|
1442
|
-
*
|
|
1443
|
-
*
|
|
1444
|
-
*
|
|
1445
|
-
*
|
|
1446
|
-
*
|
|
1447
|
-
*
|
|
1448
|
-
*
|
|
1449
|
-
*
|
|
1450
|
-
*
|
|
1451
|
-
*
|
|
1452
|
-
*
|
|
1453
|
-
*
|
|
1454
|
-
*
|
|
1455
|
-
*
|
|
1456
|
-
*
|
|
1668
|
+
* The snapshot describes the OPEN segment only (docs/offline-sync.md §Rollback and savepoints
|
|
1669
|
+
* only touch the open segment): its `pending` is the open segment's actions, while its
|
|
1670
|
+
* `transforms` are the whole tracker at capture, the sealed segments' effects included. Which
|
|
1671
|
+
* arm a restore takes is decided from three facts — whether the sealed list has changed since
|
|
1672
|
+
* the capture ({@link CollectionSnapshot.sealedVersion} against {@link SegmentList.version}),
|
|
1673
|
+
* whether the committed boundary has moved (this collection has since ADOPTED a newer
|
|
1674
|
+
* revision), and whether any segment is sealed now:
|
|
1675
|
+
*
|
|
1676
|
+
* - **Verbatim**, when the sealed list is unchanged and the boundary has not moved: the tracker
|
|
1677
|
+
* is reset to a copy of the captured transforms, the captured pins are restored, and the open
|
|
1678
|
+
* segment is set to the captured actions. This keeps an INVENTED collection's header, log
|
|
1679
|
+
* block and root, which live in the tracker until the first sync and would be lost by a
|
|
1680
|
+
* reset. It is the arm every restore took before segments existed, so while nothing is ever
|
|
1681
|
+
* sealed nothing behaves differently.
|
|
1682
|
+
* - **Replay**, when the sealed list has changed — a segment sealed, dropped or refused while
|
|
1683
|
+
* the snapshot was outstanding — or when the boundary has moved while a segment is sealed:
|
|
1684
|
+
* the open segment is set to the captured actions and the tracker is rebuilt by
|
|
1685
|
+
* {@link replayActions}, the sealed segments as they are NOW (refused ones skipped, a newly
|
|
1686
|
+
* refused one recorded and reported) and then the restored open actions. Reinstating the
|
|
1687
|
+
* captured transforms would put a dropped segment's effects back — the drain removes the
|
|
1688
|
+
* head segment after committing it, and the next head commit would commit it a second time
|
|
1689
|
+
* — and a reset would drop the sealed segments' effects.
|
|
1690
|
+
* - A moved boundary with NOTHING sealed keeps the two arms it had before segments. An empty
|
|
1691
|
+
* captured open segment (the transaction-rollback shape: the capture predates the
|
|
1692
|
+
* transaction's first stage) resets the tracker empty, because the captured transforms
|
|
1693
|
+
* describe block state at the OLD boundary and reinstalling them would shadow committed
|
|
1694
|
+
* blocks with stale structure — the observed case being an INVENTED collection's pre-commit
|
|
1695
|
+
* header/root restored over a rival's now-committed collection, after the conflict replay
|
|
1696
|
+
* that refused a guarded insert (TreeKeyTakenError), making every later read descend an
|
|
1697
|
+
* empty tree. A non-empty one restores verbatim (the NOTE below).
|
|
1698
|
+
*
|
|
1699
|
+
* The staged-base rule (docs/internals.md §Staged Edits Keep Their Base: an update names the
|
|
1700
|
+
* base it was computed against, and a rollback never pairs operations with the bases of some
|
|
1701
|
+
* later re-stage) is met differently by the two arms. The verbatim arm restores the captured
|
|
1702
|
+
* pins beside the captured operations. The replay arm restores none: its reset clears the pin
|
|
1703
|
+
* store, and every re-staged update pins its base from the read cache as it is now, which IS
|
|
1704
|
+
* the base the re-staged operations were computed against.
|
|
1705
|
+
*
|
|
1706
|
+
* A refusal of the OPEN segment inside the replay arm propagates, as it would out of a
|
|
1707
|
+
* refresh's replay: the caller rolling back is told that its transaction's own actions no
|
|
1708
|
+
* longer apply at the boundary the collection is now at. Rare — it needs a sealed change, or a
|
|
1709
|
+
* sealed segment across a moved boundary, AND a rival between capture and restore — and the
|
|
1710
|
+
* honest answer; the tracker is then as {@link updateInternal}'s note on a throw out of
|
|
1711
|
+
* `replayActions` describes.
|
|
1712
|
+
*
|
|
1713
|
+
* Latch-free by contract, like {@link snapshotPending}: every caller holds this instance's
|
|
1714
|
+
* latch or runs on the single call path that excludes a concurrent stage (the coordinator's
|
|
1715
|
+
* `rollback` and the bridge's savepoint rollback document that assumption).
|
|
1716
|
+
*
|
|
1717
|
+
* NOTE: a snapshot that carries PENDING actions across a moved boundary with nothing sealed (a
|
|
1718
|
+
* mid-transaction savepoint captured before a mid-transaction refresh adopted a rival's commit)
|
|
1719
|
+
* still restores verbatim. That shape predates the moved-boundary guard and keeps its old
|
|
1720
|
+
* behaviour; if it is ever observed producing stale reads, route it through the replay arm too.
|
|
1457
1721
|
* The WRITE side of that shape is closed here: the snapshot's base pins are restored with
|
|
1458
1722
|
* its transforms, so the restored operations name the bases they were computed on, and the
|
|
1459
1723
|
* pre-pend re-validation (restageIfBasesMoved) finds those bases moved and re-stages. */
|
|
1460
|
-
restorePending(snapshot: CollectionSnapshot<TAction>): void {
|
|
1724
|
+
async restorePending(snapshot: CollectionSnapshot<TAction>): Promise<void> {
|
|
1725
|
+
const sealedChanged = snapshot.sealedVersion !== undefined && snapshot.sealedVersion !== this.segments.version;
|
|
1461
1726
|
const capturedRev = snapshot.context?.rev;
|
|
1462
1727
|
const currentRev = this.source.actionContext?.rev;
|
|
1463
1728
|
const boundaryMoved = currentRev !== undefined && (capturedRev === undefined || currentRev > capturedRev);
|
|
1729
|
+
if (sealedChanged || (boundaryMoved && this.segments.hasSealed())) {
|
|
1730
|
+
this.segments.open = [...snapshot.pending];
|
|
1731
|
+
await this.replayActions();
|
|
1732
|
+
return;
|
|
1733
|
+
}
|
|
1464
1734
|
if (boundaryMoved && snapshot.pending.length === 0) {
|
|
1465
1735
|
this.tracker.reset();
|
|
1466
|
-
this.
|
|
1736
|
+
this.segments.open = [];
|
|
1467
1737
|
return;
|
|
1468
1738
|
}
|
|
1469
1739
|
this.tracker.reset(copyTransforms(snapshot.transforms));
|
|
1470
1740
|
if (snapshot.pins) this.tracker.pins.replaceWith(snapshot.pins);
|
|
1471
|
-
this.
|
|
1741
|
+
this.segments.open = [...snapshot.pending];
|
|
1472
1742
|
}
|
|
1473
1743
|
|
|
1474
1744
|
/** A read-only {@link Tracker} pinned to this collection's committed state AS OF the
|
|
@@ -1533,35 +1803,213 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1533
1803
|
return new Tracker(pinnedCache, copyTransforms(transforms));
|
|
1534
1804
|
}
|
|
1535
1805
|
|
|
1536
|
-
/** The staged (not-yet-synced) actions queued by {@link act}
|
|
1806
|
+
/** The OPEN segment: the staged (not-yet-synced) actions queued by {@link act} that no
|
|
1807
|
+
* {@link sealPending} has closed off.
|
|
1537
1808
|
*
|
|
1538
1809
|
* Exposed so a {@link TransactionCoordinator} can append them to the log at
|
|
1539
1810
|
* commit time — mirroring what {@link sync} does internally — when the actions
|
|
1540
1811
|
* were staged directly into this collection (e.g. through a Tree's stage())
|
|
1541
|
-
* rather than applied via the coordinator's own action path.
|
|
1812
|
+
* rather than applied via the coordinator's own action path.
|
|
1813
|
+
*
|
|
1814
|
+
* @throws SealedSegmentsError while any segment is sealed: the coordinator's only use is a
|
|
1815
|
+
* whole-collection append, which would merge the sealed segments' effects (they are in the
|
|
1816
|
+
* tracker) into one entry under one action id. The throw lands in `commitOnceLatched`'s
|
|
1817
|
+
* existing catch, which restores every participant. */
|
|
1542
1818
|
getPendingActions(): Action<TAction>[] {
|
|
1543
|
-
|
|
1819
|
+
this.assertNoSealedSegments();
|
|
1820
|
+
return this.segments.open;
|
|
1544
1821
|
}
|
|
1545
1822
|
|
|
1546
|
-
/** Drop the
|
|
1547
|
-
*
|
|
1548
|
-
*
|
|
1549
|
-
* externally. */
|
|
1823
|
+
/** Drop the OPEN segment after it has been committed through a coordinator. Counterpart to
|
|
1824
|
+
* {@link getPendingActions}, which cannot have returned anything while a segment was sealed,
|
|
1825
|
+
* so only the open segment is ever cleared here; {@link sync} clears its own inline, so this
|
|
1826
|
+
* is only needed when commit was orchestrated externally. */
|
|
1550
1827
|
clearPendingActions(): void {
|
|
1551
|
-
this.
|
|
1828
|
+
this.segments.open = [];
|
|
1552
1829
|
}
|
|
1553
1830
|
|
|
1554
|
-
/** Whether {@link sync} has anything to push: staged actions, or tracker
|
|
1555
|
-
* that were never committed
|
|
1556
|
-
* until its first sync
|
|
1831
|
+
/** Whether {@link sync} has anything to push: staged actions in the open segment, or tracker
|
|
1832
|
+
* transforms that were never committed — an INVENTED collection's header/root blocks, which
|
|
1833
|
+
* live there until its first sync with no staged action to name them, and the effects of
|
|
1834
|
+
* every sealed segment.
|
|
1557
1835
|
*
|
|
1558
1836
|
* This is the exact predicate {@link syncInternal} loops on, so `false` means a sync
|
|
1559
1837
|
* would commit nothing. Exposed so a caller that would otherwise flush
|
|
1560
1838
|
* unconditionally can skip the round trip — note that {@link Tree.sync} routes
|
|
1561
1839
|
* through {@link updateAndSync}, so an unnecessary flush still pays a full,
|
|
1562
|
-
* cache-bypassing {@link update} before discovering it has nothing to do.
|
|
1840
|
+
* cache-bypassing {@link update} before discovering it has nothing to do.
|
|
1841
|
+
*
|
|
1842
|
+
* `true` does not promise that {@link sync} can push it: while any segment is sealed, `sync`
|
|
1843
|
+
* refuses with {@link SealedSegmentsError} rather than committing the sealed effects as one
|
|
1844
|
+
* entry, so a caller that loops on this over a sealed collection gets that typed error, never
|
|
1845
|
+
* a silent no-op. Check {@link sealedEntries} first, or commit the head segment.
|
|
1846
|
+
*
|
|
1847
|
+
* Nor does `false` promise that nothing is sealed. A sealed segment leaves no tracker transform
|
|
1848
|
+
* when every one of its actions is refused, or wrote nothing (a blind delete of a key nobody
|
|
1849
|
+
* holds), so over an otherwise empty tracker this reads `false` while {@link sealedEntries} is
|
|
1850
|
+
* non-empty. The queue drives off {@link sealedEntries}, never off this predicate. */
|
|
1563
1851
|
hasUnsyncedChanges(): boolean {
|
|
1564
|
-
return this.
|
|
1852
|
+
return this.segments.open.length > 0 || !isTransformsEmpty(this.tracker.transforms);
|
|
1853
|
+
}
|
|
1854
|
+
|
|
1855
|
+
/** Close the open segment into a sealed segment owned by `entryId` (see {@link SegmentList}).
|
|
1856
|
+
* Returns `false` and changes nothing when the open segment is empty: an invented collection's
|
|
1857
|
+
* header transforms are not an action and are not sealed, so an entry that staged nothing here
|
|
1858
|
+
* owns no segment here. Throws when `entryId` is already sealed in this collection.
|
|
1859
|
+
*
|
|
1860
|
+
* Synchronous and latch-free by contract, like {@link snapshotPending}: the caller brackets it
|
|
1861
|
+
* (no concurrent act or sync is in flight). */
|
|
1862
|
+
sealPending(entryId: EntryId): boolean {
|
|
1863
|
+
return this.segments.seal(entryId);
|
|
1864
|
+
}
|
|
1865
|
+
|
|
1866
|
+
/** The entry ids of the sealed segments, oldest first — refused ones included, until dropped. */
|
|
1867
|
+
sealedEntries(): EntryId[] {
|
|
1868
|
+
return this.segments.entryIds();
|
|
1869
|
+
}
|
|
1870
|
+
|
|
1871
|
+
/** The log tail block id the most recent header read named ({@link logTailId}), for a caller that
|
|
1872
|
+
* resolves this collection's cohorts from routing keys without a read — the offline queue's
|
|
1873
|
+
* reachability gate (docs/offline-sync.md §When to submit). `undefined` before the first header
|
|
1874
|
+
* read of an invented collection; possibly stale by one roll-over, which costs that caller nothing
|
|
1875
|
+
* worse than asking about a block the collection has moved on from. */
|
|
1876
|
+
knownLogTailId(): BlockId | undefined {
|
|
1877
|
+
return this.logTailId;
|
|
1878
|
+
}
|
|
1879
|
+
|
|
1880
|
+
/** The refusal recorded for `entryId`'s segment by a replay that excluded it (see
|
|
1881
|
+
* {@link replayActions}), or `undefined` when the segment is not refused — or not sealed here. */
|
|
1882
|
+
sealedRefusal(entryId: EntryId): ActionRefusedError | undefined {
|
|
1883
|
+
return this.segments.find(entryId)?.refused;
|
|
1884
|
+
}
|
|
1885
|
+
|
|
1886
|
+
/** The sealed segment `entryId` owns here: its actions, the array the segment holds (never
|
|
1887
|
+
* mutated by a caller; the offline journal serialises it), or `undefined` when the entry is not
|
|
1888
|
+
* sealed here. Synchronous and latch-free, like {@link sealedEntries}. */
|
|
1889
|
+
sealedActions(entryId: EntryId): readonly Action<TAction>[] | undefined {
|
|
1890
|
+
return this.segments.find(entryId)?.actions;
|
|
1891
|
+
}
|
|
1892
|
+
|
|
1893
|
+
/** The OPEN segment's actions — what the current transaction has staged since the last seal — as
|
|
1894
|
+
* the array the segment holds (never mutated by a caller). Unlike {@link getPendingActions} it
|
|
1895
|
+
* answers while segments are sealed, for a reader that judges the open transaction beside the
|
|
1896
|
+
* queued ones (the Quereus plugin's `CommitOutlook()`). Synchronous and latch-free, like
|
|
1897
|
+
* {@link sealedActions}. */
|
|
1898
|
+
openActions(): readonly Action<TAction>[] {
|
|
1899
|
+
return this.segments.open;
|
|
1900
|
+
}
|
|
1901
|
+
|
|
1902
|
+
/** The exact inverse of {@link sealPending}, list-only and latch-free by the same contract: move
|
|
1903
|
+
* the segment's actions back into the open segment, for an enqueue whose journal write failed
|
|
1904
|
+
* after sealing (`OfflineQueue.enqueue`, which unseals every collection it sealed, in reverse
|
|
1905
|
+
* order, and rethrows). Requires the segment to be the NEWEST sealed one and the open segment to
|
|
1906
|
+
* be empty — both true at that one call site, which has just sealed and staged nothing since —
|
|
1907
|
+
* and throws otherwise (`SegmentList.unseal`). The tracker is untouched: its transforms are
|
|
1908
|
+
* already what they were before the seal. The segment version moves, so a snapshot taken before
|
|
1909
|
+
* the transaction restores by replay ({@link restorePending}), which ends with the transaction's
|
|
1910
|
+
* actions gone once the caller rolls it back. */
|
|
1911
|
+
unseal(entryId: EntryId): void {
|
|
1912
|
+
this.segments.unseal(entryId);
|
|
1913
|
+
}
|
|
1914
|
+
|
|
1915
|
+
/** Whether this collection's committed context names `attempt.actionId` at `attempt.rev`: the
|
|
1916
|
+
* write that attempt sent is committed here, and this handle has adopted it. This is how a restore
|
|
1917
|
+
* after a restart recognises, before re-staging a journaled segment, that the segment's network
|
|
1918
|
+
* commit landed and the crash came after it (docs/offline-sync.md §Restore after a restart):
|
|
1919
|
+
* re-staging such a segment would run its own guards against its own committed rows (`absent`
|
|
1920
|
+
* refuses on a present key) and fail the entry with `constraint`, the opposite of the truth.
|
|
1921
|
+
* `false` for an invented collection, which has no context. Synchronous and latch-free.
|
|
1922
|
+
*
|
|
1923
|
+
* NOTE: `actionIdAt` reaches back only to the most recent checkpoint, and no checkpoint is written
|
|
1924
|
+
* today (backlog `debt-the-collection-log-never-writes-a-checkpoint`); if that changes, read the
|
|
1925
|
+
* log's entry at `attempt.rev` instead, since a committed attempt behind a checkpoint would
|
|
1926
|
+
* otherwise answer `false` and be re-staged against itself. */
|
|
1927
|
+
holdsCommitted(attempt: ActionRev): boolean {
|
|
1928
|
+
const context = this.source.actionContext;
|
|
1929
|
+
return context !== undefined && context.rev >= attempt.rev && actionIdAt(context, attempt.rev) === attempt.actionId;
|
|
1930
|
+
}
|
|
1931
|
+
|
|
1932
|
+
/**
|
|
1933
|
+
* Put a sealed segment back, holding `actions` under `entryId`, at `position` in the sealed list —
|
|
1934
|
+
* ahead of the segment `before` names, or last — and rebuild the tracker by replaying every
|
|
1935
|
+
* replayable segment in order ({@link replayActions}), for the offline queue's restore after a
|
|
1936
|
+
* restart (`OfflineQueue.restore`; docs/offline-sync.md §Restore after a restart). A record
|
|
1937
|
+
* restored late belongs ahead of entries queued since, in the queue and in each collection's
|
|
1938
|
+
* sealed list alike, or the head commit's "head is first" rule and the queue's order disagree;
|
|
1939
|
+
* hence insertion rather than appending, at the cost of the one replay every insertion costs.
|
|
1940
|
+
*
|
|
1941
|
+
* The replay records and reports each refusal it meets as a refresh's would — EXCEPT this
|
|
1942
|
+
* segment's own, which is recorded on the segment and RETURNED rather than reported through
|
|
1943
|
+
* `onSealedRefused`: the queue registers the entry and hears the result from its own `stage`
|
|
1944
|
+
* callback, since the collection cannot report it to a queue that does not yet list the entry. A
|
|
1945
|
+
* later segment the replay newly refuses (this segment inserts the key it also inserts, say) is
|
|
1946
|
+
* reported through `onSealedRefused` as any replay's would be.
|
|
1947
|
+
*
|
|
1948
|
+
* Takes the collection latch, like {@link dropSealed}. Throws before anything changes when the
|
|
1949
|
+
* open segment is non-empty (a transaction is open, and its actions were staged over state without
|
|
1950
|
+
* this segment; the only caller refuses to restore mid-transaction), when a head commit is in
|
|
1951
|
+
* flight ({@link SealedSegmentsError}, `in-flight`), when `entryId` is already sealed here, or when
|
|
1952
|
+
* `before` names no segment here. A replay error that is not a refusal (a block the replay could
|
|
1953
|
+
* not read, say) propagates with the segment REMOVED again: the caller's restore rolls back and
|
|
1954
|
+
* may try this entry again later, which would otherwise meet its own segment as "already sealed".
|
|
1955
|
+
* The tracker is then half re-staged, the state a refresh's replay that throws leaves too (backlog
|
|
1956
|
+
* `debt-a-failed-refresh-can-leave-a-collection-half-restaged`); the next replay rebuilds it.
|
|
1957
|
+
*
|
|
1958
|
+
* @returns this segment's own refusal, when the replay refused it; `undefined` when it staged. */
|
|
1959
|
+
async restoreSealed(entryId: EntryId, actions: readonly Action<TAction>[], position: { before: EntryId } | 'last'): Promise<ActionRefusedError | undefined> {
|
|
1960
|
+
const release = await Latches.acquire(this.latchId);
|
|
1961
|
+
try {
|
|
1962
|
+
if (this.segments.open.length > 0) {
|
|
1963
|
+
throw new Error(`Collection ${this.id}: cannot restore sealed segment ${entryId} while a transaction has `
|
|
1964
|
+
+ `${this.segments.open.length} action(s) staged in the open segment`);
|
|
1965
|
+
}
|
|
1966
|
+
if (this.headInFlight !== undefined) {
|
|
1967
|
+
throw new SealedSegmentsError(this.id, this.segments.entryIds(), 'in-flight', this.headInFlight.entryId);
|
|
1968
|
+
}
|
|
1969
|
+
this.segments.insert(entryId, actions, position === 'last' ? undefined : position.before);
|
|
1970
|
+
try {
|
|
1971
|
+
await this.replayActions(entryId);
|
|
1972
|
+
} catch (err) {
|
|
1973
|
+
this.segments.drop(entryId);
|
|
1974
|
+
throw err;
|
|
1975
|
+
}
|
|
1976
|
+
return this.segments.find(entryId)?.refused;
|
|
1977
|
+
} finally {
|
|
1978
|
+
release();
|
|
1979
|
+
}
|
|
1980
|
+
}
|
|
1981
|
+
|
|
1982
|
+
/** Remove the sealed segment owned by `entryId`, wherever it sits, and rebuild the tracker by
|
|
1983
|
+
* replaying what remains ({@link replayActions}). A later segment whose guard now refuses — one
|
|
1984
|
+
* that updated a row the dropped segment inserted, say — is recorded and reported through
|
|
1985
|
+
* `onSealedRefused` during that replay; cascading the removal through the queue's other
|
|
1986
|
+
* collections is the queue's job (docs/offline-sync.md §Removing an entry). Throws for an id
|
|
1987
|
+
* that is not sealed here, before anything changes, and {@link SealedSegmentsError} (`in-flight`)
|
|
1988
|
+
* for the segment a {@link commitHead} on this instance is carrying to the network — the only
|
|
1989
|
+
* segment that cannot be dropped while it waits, since the outcome being applied names it.
|
|
1990
|
+
* Another segment can be: the replay here rebuilds the live tracker, which the head commit's own
|
|
1991
|
+
* tracker does not depend on.
|
|
1992
|
+
*
|
|
1993
|
+
* Takes the collection latch, like {@link update}. */
|
|
1994
|
+
async dropSealed(entryId: EntryId): Promise<void> {
|
|
1995
|
+
const release = await Latches.acquire(this.latchId);
|
|
1996
|
+
try {
|
|
1997
|
+
if (this.headInFlight?.entryId === entryId) {
|
|
1998
|
+
throw new SealedSegmentsError(this.id, this.segments.entryIds(), 'in-flight', entryId);
|
|
1999
|
+
}
|
|
2000
|
+
this.segments.drop(entryId);
|
|
2001
|
+
await this.replayActions();
|
|
2002
|
+
} finally {
|
|
2003
|
+
release();
|
|
2004
|
+
}
|
|
2005
|
+
}
|
|
2006
|
+
|
|
2007
|
+
/** The refusal every whole-collection commit path makes while a segment is sealed (see
|
|
2008
|
+
* {@link SealedSegmentsError}). */
|
|
2009
|
+
private assertNoSealedSegments(): void {
|
|
2010
|
+
if (this.segments.hasSealed()) {
|
|
2011
|
+
throw new SealedSegmentsError(this.id, this.segments.entryIds());
|
|
2012
|
+
}
|
|
1565
2013
|
}
|
|
1566
2014
|
|
|
1567
2015
|
/** The committed revision this collection currently READS at, or `undefined` for an
|
|
@@ -1714,8 +2162,11 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1714
2162
|
* path, which is the same assumption the participant selection in
|
|
1715
2163
|
* `TransactionCoordinator.commitOnce` and its `rollback` already rest on. If a second writer is
|
|
1716
2164
|
* ever allowed to drive the SAME instance concurrently, this must become a per-attempt token (a
|
|
1717
|
-
* mark object compared by identity, refusing to replace a live one) rather than a bare id.
|
|
1718
|
-
|
|
2165
|
+
* mark object compared by identity, refusing to replace a live one) rather than a bare id.
|
|
2166
|
+
*
|
|
2167
|
+
* `cycle` is what every send of the cycle carries ({@link InFlightCycle}); a re-mark replaces it,
|
|
2168
|
+
* which is harmless because every caller re-marks with what it marked. */
|
|
2169
|
+
beginInFlightAction(actionId: ActionId, cycle: InFlightCycle = {}): () => void {
|
|
1719
2170
|
if (this.inFlightActionId !== actionId) {
|
|
1720
2171
|
// A different action's failed attempt cannot finish this one. Re-marking the SAME id (a
|
|
1721
2172
|
// coordinator re-marks on every attempt) keeps what the previous attempt retained — that
|
|
@@ -1725,11 +2176,13 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1725
2176
|
this.mintedLogBlockIds = undefined;
|
|
1726
2177
|
}
|
|
1727
2178
|
this.inFlightActionId = actionId;
|
|
2179
|
+
this.inFlightCycle = cycle;
|
|
1728
2180
|
return () => {
|
|
1729
2181
|
if (this.inFlightActionId === actionId) {
|
|
1730
2182
|
this.inFlightActionId = undefined;
|
|
1731
2183
|
this.inFlightAttempt = undefined;
|
|
1732
2184
|
this.mintedLogBlockIds = undefined;
|
|
2185
|
+
this.inFlightCycle = {};
|
|
1733
2186
|
}
|
|
1734
2187
|
};
|
|
1735
2188
|
}
|
|
@@ -1741,12 +2194,12 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1741
2194
|
* a path that does not still never reports a half-landed write as saved (the refresh then
|
|
1742
2195
|
* refuses with a `transforms-not-held` {@link TornActionError}), but it cannot recover from one.
|
|
1743
2196
|
*
|
|
1744
|
-
* A no-op unless
|
|
1745
|
-
* cycle has already ended cannot plant transforms under somebody else's mark. Latch-free and
|
|
2197
|
+
* A no-op unless the attempt's action is the one currently marked, so a late call from an attempt
|
|
2198
|
+
* whose cycle has already ended cannot plant transforms under somebody else's mark. Latch-free and
|
|
1746
2199
|
* synchronous, like the mark itself: `TransactionCoordinator` calls it from inside its commit
|
|
1747
2200
|
* span, where it already holds this instance's latch. */
|
|
1748
|
-
retainInFlightAttempt(
|
|
1749
|
-
if (this.inFlightActionId === actionId) {
|
|
2201
|
+
retainInFlightAttempt(attempt: InFlightAttempt): void {
|
|
2202
|
+
if (this.inFlightActionId === attempt.actionId) {
|
|
1750
2203
|
this.inFlightAttempt = attempt;
|
|
1751
2204
|
}
|
|
1752
2205
|
}
|
|
@@ -1819,131 +2272,52 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1819
2272
|
}
|
|
1820
2273
|
}
|
|
1821
2274
|
|
|
2275
|
+
/** The refresh a write's attempt cycle runs between attempts ({@link AttemptCycle.refreshUntilSettled}):
|
|
2276
|
+
* {@link updateInternal}, under the latch the write already holds and with its action marked in
|
|
2277
|
+
* flight, so the refresh recognises the write's own log entry. */
|
|
2278
|
+
private readonly refreshBetweenAttempts: Refresh = (report, lastChance, tailFloor) =>
|
|
2279
|
+
this.updateInternal(report, lastChance, tailFloor);
|
|
2280
|
+
|
|
1822
2281
|
/** Mints the one action id this sync reuses across all of its retry attempts, and owns it for
|
|
1823
2282
|
* the WHOLE cycle — including the inter-attempt refresh, which is the only thing that reads it
|
|
1824
2283
|
* (see {@link inFlightActionId}). `sync()`/`updateAndSync()` hold the collection latch across
|
|
1825
2284
|
* all of this, so the mark's lifetime is contained inside the latched span here; the disposer
|
|
1826
2285
|
* runs on every exit, including a throw out of retry exhaustion or an abort. */
|
|
1827
2286
|
private async syncInternal(options?: SyncOptions): Promise<WriteDurability | undefined> {
|
|
1828
|
-
|
|
1829
|
-
|
|
1830
|
-
|
|
1831
|
-
|
|
1832
|
-
|
|
1833
|
-
|
|
1834
|
-
|
|
1835
|
-
|
|
2287
|
+
// Before an action id is minted: a sync commits the whole tracker as one entry, and over
|
|
2288
|
+
// sealed segments that entry would carry several queue entries' effects.
|
|
2289
|
+
this.assertNoSealedSegments();
|
|
2290
|
+
const identity: WriteIdentity = {
|
|
2291
|
+
actionId: uint8ArrayToString(randomBytes(16), 'base64url'),
|
|
2292
|
+
// One timestamp for the WRITE, minted here beside the action id and for the same reason: an
|
|
2293
|
+
// attempt that takes its own would make the retry's log block differ from the one the
|
|
2294
|
+
// attempt it repeats may already have stored under this `(action id, revision)`.
|
|
2295
|
+
timestamp: Date.now(),
|
|
2296
|
+
};
|
|
2297
|
+
|
|
2298
|
+
const endInFlight = this.beginInFlightAction(identity.actionId, { refuseSolo: options?.refuseSoloCommit });
|
|
1836
2299
|
try {
|
|
1837
|
-
return await this.syncAttempts(
|
|
2300
|
+
return await this.syncAttempts(identity, options);
|
|
1838
2301
|
} finally {
|
|
1839
2302
|
endInFlight();
|
|
1840
2303
|
}
|
|
1841
2304
|
}
|
|
1842
2305
|
|
|
1843
|
-
/** The retry loop behind {@link syncInternal}, run with
|
|
2306
|
+
/** The retry loop behind {@link syncInternal}, run with the action already marked in flight: the
|
|
2307
|
+
* attempt machinery of {@link AttemptCycle} and {@link stageAttempt}, aimed at the open segment
|
|
2308
|
+
* over the live tracker. {@link commitHead} drives the same machinery at the head segment.
|
|
1844
2309
|
*
|
|
1845
|
-
* @param timestamp the WRITE's time, stamped on the log entry every attempt appends — see
|
|
1846
|
-
* {@link syncInternal}, which mints it.
|
|
1847
2310
|
* @returns the durability of what this sync committed, or `undefined` when the loop never ran a
|
|
1848
2311
|
* commit (nothing staged). See {@link sync}. */
|
|
1849
|
-
private async syncAttempts(
|
|
1850
|
-
const
|
|
1851
|
-
const baseBackoffMs = options?.baseBackoffMs ?? PendingRetryDelayMs;
|
|
1852
|
-
const maxBackoffMs = options?.maxBackoffMs ?? DefaultMaxBackoffMs;
|
|
1853
|
-
const maxStalledAttempts = options?.maxStalledAttempts ?? DefaultMaxStalledAttempts;
|
|
1854
|
-
const deadlineMs = options?.deadlineMs;
|
|
1855
|
-
const signal = options?.signal;
|
|
1856
|
-
const startedAt = Date.now();
|
|
1857
|
-
|
|
1858
|
-
// Count of consecutive stale failures that made no forward progress. Reset to 0 on every
|
|
1859
|
-
// successful transact, so the cap bounds only a persistently-failing sync — a legitimate
|
|
1860
|
-
// large multi-batch sync (which iterates many times committing progress) never trips it.
|
|
1861
|
-
let consecutiveFailures = 0;
|
|
1862
|
-
let lastReason: string | undefined;
|
|
1863
|
-
// Highest confirmed revision any responder has reported holding, accumulated with the
|
|
1864
|
-
// codebase's single rule for picking among several candidates. Reported on the error, and
|
|
1865
|
-
// the evidence the stall check below reasons from.
|
|
1866
|
-
let lastStaleAt: { blockId: BlockId; rev: number } | undefined;
|
|
1867
|
-
// Whether the failure most recently handled carried its OWN staleAt. A strike needs the
|
|
1868
|
-
// responder to have re-confirmed the number this round, not merely an older observation
|
|
1869
|
-
// left standing in `lastStaleAt`.
|
|
1870
|
-
let lastFailureConfirmedStaleAt = false;
|
|
1871
|
-
// Refused attempts of this write that carried their own staleAt. Never reset: a member counts
|
|
1872
|
-
// its stale refusals per action for the action's whole life, and this is the writer's view of
|
|
1873
|
-
// that count (see retryBackoffMs).
|
|
1874
|
-
let confirmedLosses = 0;
|
|
1875
|
-
// Consecutive refreshes that moved `getNextRev()` nowhere at all while a confirmed revision
|
|
1876
|
-
// stood at or above it.
|
|
1877
|
-
let consecutiveStalls = 0;
|
|
1878
|
-
// The revision the PREVIOUS iteration would have requested, so the stall check can tell a
|
|
1879
|
-
// refresh that moved nowhere from one that is still climbing toward the confirmed number.
|
|
1880
|
-
let previousRequestedRev: number | undefined;
|
|
1881
|
-
// Who holds what this sync has committed so far. Stays `undefined` while nothing has been
|
|
1882
|
-
// committed, which is also the answer when the loop never runs at all — a sync with nothing
|
|
1883
|
-
// staged writes nothing, and there is no durability to fabricate for it. Failed attempts never
|
|
1884
|
-
// contribute: a refused attempt left nothing behind, so the answer is the committing attempt's.
|
|
1885
|
-
let durability: WriteDurability | undefined;
|
|
1886
|
-
|
|
2312
|
+
private async syncAttempts(identity: WriteIdentity, options?: SyncOptions): Promise<WriteDurability | undefined> {
|
|
2313
|
+
const cycle = new AttemptCycle(this.id, this.instanceTag, options);
|
|
1887
2314
|
while (this.hasUnsyncedChanges()) {
|
|
1888
|
-
|
|
1889
|
-
throw makeAbortError(signal);
|
|
1890
|
-
}
|
|
1891
|
-
// Progress-agnostic ceiling: give up if the wall-clock deadline passed. Deliberately
|
|
1892
|
-
// ahead of the stall check: the deadline is the documented outer bound, so a sync that
|
|
1893
|
-
// is both past it and stalled reports the deadline.
|
|
1894
|
-
if (deadlineMs !== undefined && Date.now() - startedAt >= deadlineMs) {
|
|
1895
|
-
throw new SyncRetryExhaustedError(this.id, consecutiveFailures, lastReason ?? 'deadline exceeded', lastStaleAt);
|
|
1896
|
-
}
|
|
1897
|
-
|
|
1898
|
-
// Can the attempt about to run possibly differ from the one that just failed? Only when
|
|
1899
|
-
// BOTH of these hold is the answer provably no:
|
|
1900
|
-
//
|
|
1901
|
-
// - The revision it would request is at or below one a responder CONFIRMED is taken. A
|
|
1902
|
-
// producer sets `staleAt` only after reading that revision as durably held by someone
|
|
1903
|
-
// else out of its own storage, revisions are one per-collection counter that every
|
|
1904
|
-
// commit touches, and a confirmed revision never becomes un-taken (invalidation takes
|
|
1905
|
-
// a NEW slot). So the request is already lost before it is sent.
|
|
1906
|
-
// - The refresh in between moved the collection nowhere. `advanceContext` never lowers
|
|
1907
|
-
// the held revision, so "nowhere" is exactly `requestedRev` unchanged since the last
|
|
1908
|
-
// iteration. A refresh that moved forward WITHOUT clearing the confirmed number is a
|
|
1909
|
-
// collection still climbing (it read a replica that lags the holder — the same
|
|
1910
|
-
// partial catch-up `reportShortfall` exists to report), and its next attempt is a
|
|
1911
|
-
// genuinely different request that may yet win.
|
|
1912
|
-
//
|
|
1913
|
-
// This is NOT a second answer to "is this failure retryable?" — `isConflictFailure`
|
|
1914
|
-
// remains the sole rule for that, untouched. It only ever stops a loop that rule had
|
|
1915
|
-
// already decided to continue.
|
|
1916
|
-
const requestedRev = this.getNextRev();
|
|
1917
|
-
const refreshMoved = previousRequestedRev !== undefined && requestedRev > previousRequestedRev;
|
|
1918
|
-
previousRequestedRev = requestedRev;
|
|
1919
|
-
if (lastStaleAt !== undefined) {
|
|
1920
|
-
if (requestedRev > lastStaleAt.rev || refreshMoved) {
|
|
1921
|
-
// Either the refresh adopted a revision above the confirmed one — ordinary
|
|
1922
|
-
// contention, where the rival's commit is exactly what we just read — or it made
|
|
1923
|
-
// partial forward progress. Both mean the next attempt differs. Not a stall.
|
|
1924
|
-
consecutiveStalls = 0;
|
|
1925
|
-
} else if (lastFailureConfirmedStaleAt) {
|
|
1926
|
-
consecutiveStalls++;
|
|
1927
|
-
if (log.enabled) {
|
|
1928
|
-
log('collection:sync-stalled id=%s tag=%s heldRev=%s requestedRev=%d staleBlock=%s staleRev=%d strike=%d of=%d',
|
|
1929
|
-
this.id, this.instanceTag, this.source.actionContext?.rev ?? 'none', requestedRev,
|
|
1930
|
-
lastStaleAt.blockId, lastStaleAt.rev, consecutiveStalls, maxStalledAttempts);
|
|
1931
|
-
}
|
|
1932
|
-
// Two strikes, not one: a legitimate loser can transiently read a view that has
|
|
1933
|
-
// not yet caught up with the rival's commit, which looks identical for one round.
|
|
1934
|
-
if (consecutiveStalls >= maxStalledAttempts) {
|
|
1935
|
-
throw new SyncRevisionStalledError(this.id, consecutiveFailures, lastStaleAt,
|
|
1936
|
-
requestedRev, this.source.actionContext?.rev, lastReason);
|
|
1937
|
-
}
|
|
1938
|
-
}
|
|
1939
|
-
// Else: the responder told us nothing new this round. No strike, and no reset either
|
|
1940
|
-
// — the budget stays bounded by maxAttempts.
|
|
1941
|
-
}
|
|
2315
|
+
cycle.beforeAttempt(this.getNextRev(), this.source.actionContext?.rev);
|
|
1942
2316
|
|
|
1943
2317
|
// A pending action is never pended over a base that has moved under it — before EVERY
|
|
1944
2318
|
// attempt, first and retries alike (see restageIfBasesMoved for why the retry needs it).
|
|
1945
|
-
// NOTE: this is the one way the byte-identity the append
|
|
1946
|
-
//
|
|
2319
|
+
// NOTE: this is the one way the byte-identity the append relies on can be broken at an
|
|
2320
|
+
// UNCHANGED revision — a replay re-runs the action handlers, which mint fresh ids for
|
|
1947
2321
|
// whatever blocks they insert, so the retry sends different content under this write's
|
|
1948
2322
|
// `(action id, revision)`. It needs a base to move without this collection adopting a
|
|
1949
2323
|
// newer revision, which takes a block re-read that catches up while the log does not
|
|
@@ -1953,211 +2327,63 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1953
2327
|
// abandon the action id and re-drive as a NEW write rather than to suppress the replay.
|
|
1954
2328
|
await this.restageIfBasesMoved();
|
|
1955
2329
|
|
|
1956
|
-
// Snapshot the
|
|
1957
|
-
|
|
1958
|
-
|
|
1959
|
-
|
|
1960
|
-
|
|
1961
|
-
// stages the data-block updates itself, so without the shared pins the digest pass below
|
|
1962
|
-
// could only describe bases still resident in the read cache.
|
|
1963
|
-
// NOTE: an attempt that ends in a stale failure is abandoned WITHOUT reset(), so the log
|
|
1964
|
-
// tail/header bases its append pinned stay in the shared store until the live tracker's
|
|
1965
|
-
// next reset. Bounded and harmless — a few log blocks per attempt, capped by maxAttempts,
|
|
1966
|
-
// each re-validated against the source generation before any use — but if this loop ever
|
|
1967
|
-
// grows a per-attempt footprint beyond the log blocks, reset the abandoned tracker on the
|
|
1968
|
-
// stale-failure branch instead of letting the residue ride to the end of the sync.
|
|
1969
|
-
const snapshot = copyTransforms(this.tracker.transforms);
|
|
1970
|
-
const tracker = new Tracker(this.sourceCache, snapshot, this.tracker.pins);
|
|
1971
|
-
|
|
1972
|
-
// Add the action to the log (in local tracking space). The append is a fixed function of
|
|
1973
|
-
// this write and the revision it is requesting: the timestamp was minted once for the
|
|
1974
|
-
// whole write (syncInternal) and any data block the append has to mint takes the id an
|
|
1975
|
-
// earlier attempt at this revision already minted (logAppendBlockIds).
|
|
1976
|
-
const newRev = this.getNextRev();
|
|
1977
|
-
const collectionLog = await Log.open<Action<TAction>>(tracker, this.id,
|
|
1978
|
-
{ newDataBlockId: this.logAppendBlockIds(tracker, actionId, newRev) });
|
|
1979
|
-
if (!collectionLog) {
|
|
1980
|
-
throw new Error(`Log not found for collection ${this.id}`);
|
|
1981
|
-
}
|
|
1982
|
-
const addResult = await collectionLog.addActions(pending, actionId, newRev,
|
|
1983
|
-
() => tracker.transformedBlockIds(), { timestamp });
|
|
1984
|
-
|
|
1985
|
-
// Declare what each touched block will contain once committed, computed from this snapshot
|
|
1986
|
-
// tracker (which layers over `this.sourceCache`, so the peek/getCachedRevision probes are
|
|
1987
|
-
// live). Purely local — an id whose base is not already cached is simply omitted and falls
|
|
1988
|
-
// back to corroboration on the member side. Computed AFTER the log append so the log tail
|
|
1989
|
-
// and header transforms this attempt just staged are digested too.
|
|
1990
|
-
// NOTE: recomputed from scratch on every retry attempt (the snapshot tracker is rebuilt each
|
|
1991
|
-
// iteration), so a sync that loses N races pays N full hashing passes over its touched
|
|
1992
|
-
// blocks. Unmeasured and cheap relative to the round trips it is retrying; if a
|
|
1993
|
-
// high-contention sync ever shows digest hashing in a profile, memoize per (id, staged ops).
|
|
1994
|
-
const blockDigests = await computeBlockContentDigests(tracker, tracker.transformedBlockIds());
|
|
1995
|
-
// The base each update-only block's operations were computed against, for the pend (see
|
|
1996
|
-
// `PendRequest.baseRevs`): the tracker's pinned revisions, which `restageIfBasesMoved` at the
|
|
1997
|
-
// top of this iteration has just re-judged, so a moved base was re-staged before it is named.
|
|
1998
|
-
const baseRevs = tracker.stagedBaseRevs(tracker.transformedBlockIds());
|
|
1999
|
-
|
|
2000
|
-
// Commit the action to the transactor. Carry the aged retry priority derived from the
|
|
2001
|
-
// consecutive-failure count so a sync that keeps losing concurrent races out-ranks fresh
|
|
2002
|
-
// (priority-0) rivals in the cluster's resolveRace (fairness-only; capped at MaxPriority).
|
|
2003
|
-
// First attempt has consecutiveFailures == 0, so priority 0 — the common pend is unchanged.
|
|
2004
|
-
const attempt = await this.source.transact(tracker.transforms, actionId, newRev, this.id, addResult.tailPath.block.header.id, clampPriority(consecutiveFailures), blockDigests, baseRevs);
|
|
2330
|
+
// Snapshot the open segment so that any new actions aren't assumed to be part of this action
|
|
2331
|
+
// (no segment is sealed here — syncInternal refused if one was).
|
|
2332
|
+
const pending = [...this.segments.open];
|
|
2333
|
+
const staged = await this.buildAttempt({ actions: pending, transforms: this.tracker.transforms, pins: this.tracker.pins }, identity);
|
|
2334
|
+
const attempt = await this.send(staged, identity, cycle.priority());
|
|
2005
2335
|
if (!attempt.success) {
|
|
2006
|
-
|
|
2007
|
-
|
|
2008
|
-
|
|
2009
|
-
// ran on a snapshot tracker — so the staged actions are still staged for a sync after
|
|
2010
|
-
// the clock is fixed.
|
|
2011
|
-
// NOTE: an expiry refusing a commit SWEEP (`NetworkTransactor.commitTailThenSweep`)
|
|
2012
|
-
// arrives after the log tail was stored, and no refresh follows this throw, so that
|
|
2013
|
-
// attempt's log entry stays behind with none of its data — the state the budget-exhausted
|
|
2014
|
-
// exit below leaves too. Needs a sweep cohort whose clocks disagree while the tail's agree;
|
|
2015
|
-
// tracked with the other leftover-entry exits in
|
|
2016
|
-
// tickets/backlog/bug-a-refused-write-can-leave-its-log-entry-behind.
|
|
2017
|
-
throw new TransactionExpiredError(attempt.expired);
|
|
2018
|
-
}
|
|
2019
|
-
consecutiveFailures++;
|
|
2020
|
-
lastReason = attempt.reason ?? lastReason;
|
|
2021
|
-
// Highest-wins, not last-wins: the next request has to clear EVERY holder, so a later
|
|
2022
|
-
// responder reporting a LOWER number understates the binding constraint. Same rule the
|
|
2023
|
-
// producers and the transactor's aggregation already use.
|
|
2024
|
-
lastStaleAt = highestStaleAt([lastStaleAt, attempt.staleAt]);
|
|
2025
|
-
lastFailureConfirmedStaleAt = attempt.staleAt !== undefined;
|
|
2026
|
-
if (lastFailureConfirmedStaleAt) confirmedLosses++;
|
|
2027
|
-
// Give up once the consecutive no-progress budget is exhausted, so a transactor that
|
|
2028
|
-
// persistently rejects the sync can no longer hold the collection latch forever.
|
|
2029
|
-
// NOTE: this also bounds the legitimate `pending`-wait case (retrying the same action
|
|
2030
|
-
// while another commit is in flight), which used to retry indefinitely. Default 10
|
|
2031
|
-
// attempts ≈ 21s of exponential backoff. If a high-contention workload legitimately
|
|
2032
|
-
// needs to wait longer for a pending commit to clear, raise maxAttempts for that caller.
|
|
2033
|
-
// NOTE: no refresh follows the LAST budgeted attempt, so if that attempt's log tail
|
|
2034
|
-
// landed nobody finds out: the caller gets plain exhaustion over a log that holds an
|
|
2035
|
-
// entry for this write. The write is still never reported saved, which is the rule; what
|
|
2036
|
-
// is lost is the more specific name (TornActionError). The leftover entry itself is
|
|
2037
|
-
// tracked in tickets/backlog/bug-a-refused-write-can-leave-its-log-entry-behind.
|
|
2038
|
-
if (consecutiveFailures >= maxAttempts) {
|
|
2039
|
-
throw new SyncRetryExhaustedError(this.id, consecutiveFailures, lastReason, lastStaleAt);
|
|
2040
|
-
}
|
|
2041
|
-
// Keep exactly what this attempt sent. A refused commit is not proof nothing landed:
|
|
2042
|
-
// the log tail is committed first and can be stored while the answer is still a
|
|
2043
|
-
// failure, and `transact` has just cancelled every block that did not land. If the
|
|
2044
|
-
// refresh below finds this attempt's own entry, these are the transforms that finish
|
|
2045
|
-
// the action (see completeOwnEntry). The snapshot tracker is abandoned after this
|
|
2046
|
-
// iteration, so its transforms are handed over as-is, uncopied.
|
|
2047
|
-
this.retainInFlightAttempt(actionId, {
|
|
2048
|
-
rev: newRev,
|
|
2049
|
-
transforms: tracker.transforms,
|
|
2050
|
-
tailId: addResult.tailPath.block.header.id,
|
|
2051
|
-
...(blockDigests === undefined ? {} : { blockDigests }),
|
|
2052
|
-
...baseRevsField(baseRevs),
|
|
2053
|
-
});
|
|
2054
|
-
// Refresh, and keep refreshing while it reports that this write's own half-landed
|
|
2055
|
-
// action could not be finished YET. It must not fall through to a new attempt in that
|
|
2056
|
-
// state: this action's log entry is already durable, and as soon as a refresh adopts a
|
|
2057
|
-
// newer revision a new attempt appends a SECOND entry under the same action id — the
|
|
2058
|
-
// duplicate consumeOwnEntry exists to prevent. (At an unchanged revision the rebuild
|
|
2059
|
-
// is byte-identical — see logAppendBlockIds — so what is at stake is the second entry,
|
|
2060
|
-
// not two versions of one tail block.) Each round is a failure against the same
|
|
2061
|
-
// no-progress budget as a refused attempt.
|
|
2062
|
-
// Whether the failure just handled was a loss to a rival already durably committed. Only
|
|
2063
|
-
// the attempt's own refusal can say so; a refresh refused for a cause that can clear
|
|
2064
|
-
// (below) is a race against something still in flight, and clears it.
|
|
2065
|
-
let latestConfirmed = lastFailureConfirmedStaleAt;
|
|
2066
|
-
for (;;) {
|
|
2067
|
-
// Back off before every retry (any stale failure — reason/missing/pending), growing
|
|
2068
|
-
// exponentially from the base delay up to the cap, with proportional random jitter so a
|
|
2069
|
-
// herd of clients that lost the same race does not re-collide on the next tick (see
|
|
2070
|
-
// utility/backoff.ts) — except once this write has lost to committed rivals often enough
|
|
2071
|
-
// that a member holds the next slot for it (see retryBackoffMs). The abortable sleep lets
|
|
2072
|
-
// an aborted sync reject promptly instead of finishing the sleep.
|
|
2073
|
-
// NOTE: the `missing`/`reason` conflict paths now pay this backoff too (they previously
|
|
2074
|
-
// retried with zero delay); that is what stops the persistent-`reason` hot spin. If a
|
|
2075
|
-
// high-contention workload ever shows this base delay as recovery latency, lower
|
|
2076
|
-
// baseBackoffMs for that caller rather than reintroducing the zero-delay retry.
|
|
2077
|
-
const delay = retryBackoffMs(consecutiveFailures, confirmedLosses, latestConfirmed,
|
|
2078
|
-
{ baseMs: baseBackoffMs, capMs: maxBackoffMs }, options?.rand);
|
|
2079
|
-
await abortableDelay(delay, signal);
|
|
2080
|
-
try {
|
|
2081
|
-
// Fetch latest state - updateInternal() will call replayActions() if there are conflicts.
|
|
2082
|
-
// This sync's actionId is marked in flight for the whole cycle (see syncInternal), so
|
|
2083
|
-
// the refresh recognizes a log entry written by THIS action (its log tail landed but
|
|
2084
|
-
// the commit answered failure), FINISHES that action from the attempt retained
|
|
2085
|
-
// above, and only then consumes the entry rather than replaying it into a duplicate.
|
|
2086
|
-
// The round that would spend the last of the budget settles a half-landed write
|
|
2087
|
-
// instead of asking for another round, so the error that escapes below says
|
|
2088
|
-
// whether the write can still land. (A deadline cannot be foreseen the same
|
|
2089
|
-
// way; a write given up on it escapes unsettled, as `final: false`.)
|
|
2090
|
-
// The highest revision a responder confirmed is taken rides out as the floor of
|
|
2091
|
-
// the refresh's tail read, so a machine that has not caught up to it is not the
|
|
2092
|
-
// last one asked (see updateInternal).
|
|
2093
|
-
const report: RefreshReport = {};
|
|
2094
|
-
await this.updateInternal(report, consecutiveFailures + 1 >= maxAttempts, lastStaleAt?.rev);
|
|
2095
|
-
const completed = report.ownEntryFinished?.durability;
|
|
2096
|
-
if (completed !== undefined) {
|
|
2097
|
-
// The refresh made this sync's write durable: that is a commit, and it is
|
|
2098
|
-
// reported and counted exactly like one made by an attempt (see the success
|
|
2099
|
-
// branch below for why batches fold to the weakest).
|
|
2100
|
-
durability = durability === undefined ? completed : mergeDurability([durability, completed]);
|
|
2101
|
-
consecutiveFailures = 0;
|
|
2102
|
-
lastReason = undefined;
|
|
2103
|
-
lastStaleAt = undefined;
|
|
2104
|
-
lastFailureConfirmedStaleAt = false;
|
|
2105
|
-
consecutiveStalls = 0;
|
|
2106
|
-
}
|
|
2107
|
-
break;
|
|
2108
|
-
} catch (err) {
|
|
2109
|
-
if (!(err instanceof TornActionError) || err.reason !== 'completion-refused') {
|
|
2110
|
-
throw err;
|
|
2111
|
-
}
|
|
2112
|
-
// Refused for a cause that can clear. The error already names the write as torn,
|
|
2113
|
-
// which is the truth if the budget ends here — so it, not a plain exhaustion,
|
|
2114
|
-
// is what escapes: the log holds an entry for a write that was not saved.
|
|
2115
|
-
consecutiveFailures++;
|
|
2116
|
-
lastReason = err.detail;
|
|
2117
|
-
latestConfirmed = false;
|
|
2118
|
-
if (consecutiveFailures >= maxAttempts
|
|
2119
|
-
|| (deadlineMs !== undefined && Date.now() - startedAt >= deadlineMs)) {
|
|
2120
|
-
throw err;
|
|
2121
|
-
}
|
|
2122
|
-
}
|
|
2123
|
-
}
|
|
2336
|
+
cycle.recordRefusal(attempt);
|
|
2337
|
+
this.retainInFlightAttempt(retainedAttempt(staged, identity.actionId));
|
|
2338
|
+
await cycle.refreshUntilSettled(this.refreshBetweenAttempts);
|
|
2124
2339
|
} else {
|
|
2125
|
-
|
|
2126
|
-
//
|
|
2127
|
-
|
|
2128
|
-
//
|
|
2129
|
-
//
|
|
2130
|
-
//
|
|
2131
|
-
//
|
|
2132
|
-
|
|
2133
|
-
//
|
|
2134
|
-
|
|
2135
|
-
|
|
2136
|
-
|
|
2137
|
-
|
|
2138
|
-
|
|
2139
|
-
// Clear the pending actions that were part of this action
|
|
2140
|
-
this.pending = this.pending.slice(pending.length);
|
|
2141
|
-
// Reset cache and replay any actions that were added during the action
|
|
2142
|
-
const transforms = tracker.reset();
|
|
2143
|
-
// NOTE: this replay runs BEFORE the cache fold and the context bump below — the
|
|
2144
|
-
// inverse of the order `updateInternal` and `TransactionCoordinator.commitOnce`
|
|
2145
|
-
// both document as required, where the newly committed state must be visible
|
|
2146
|
-
// before anything re-reads. Dormant today: `act()` and `syncInternal` take the
|
|
2147
|
-
// same collection latch, so `this.pending` cannot grow during the transact above
|
|
2148
|
-
// and the slice always leaves it empty, making this replay a no-op reset. If a
|
|
2149
|
-
// path ever stages outside that latch, move the transformCache + actionContext
|
|
2150
|
-
// lines above this replay — otherwise the replay re-reads at the superseded
|
|
2151
|
-
// revision over a cache that has not yet seen the commit, and re-stages onto a
|
|
2152
|
-
// root the commit already replaced.
|
|
2340
|
+
cycle.recordCommit(attempt.durability);
|
|
2341
|
+
// Clear the open-segment actions that were part of this action
|
|
2342
|
+
this.segments.open = this.segments.open.slice(pending.length);
|
|
2343
|
+
// Fold the committed transforms into the read cache and adopt the revision BEFORE
|
|
2344
|
+
// replaying whatever is still staged — the order `updateInternal` and
|
|
2345
|
+
// `TransactionCoordinator.commitOnceLatched` require, where the newly committed state
|
|
2346
|
+
// must be visible before anything re-reads. It is load-bearing here for an invented
|
|
2347
|
+
// collection's first commit: the replay resets to the invented baseline while no
|
|
2348
|
+
// context is adopted, so replaying first would reinstate the header insert over the
|
|
2349
|
+
// now-committed header and `hasUnsyncedChanges()` would never turn false. (While
|
|
2350
|
+
// `act()` shares this latch nothing new is staged mid-attempt, so the replay re-stages
|
|
2351
|
+
// nothing; {@link commitHead} stages while its transact is in flight and relies on
|
|
2352
|
+
// this order.)
|
|
2353
|
+
this.foldOwnCommit(staged, identity.actionId);
|
|
2153
2354
|
await this.replayActions();
|
|
2154
|
-
this.sourceCache.transformCache(transforms, newRev);
|
|
2155
|
-
this.source.actionContext = this.source.actionContext
|
|
2156
|
-
? { committed: [...this.source.actionContext.committed, { actionId, rev: newRev }], rev: newRev }
|
|
2157
|
-
: { committed: [{ actionId, rev: newRev }], rev: newRev };
|
|
2158
2355
|
}
|
|
2159
2356
|
}
|
|
2160
|
-
return durability;
|
|
2357
|
+
return cycle.durability;
|
|
2358
|
+
}
|
|
2359
|
+
|
|
2360
|
+
/** Build one attempt at the revision this collection would commit at next ({@link stageAttempt});
|
|
2361
|
+
* the ids its log append may have to mint come from {@link logAppendBlockIds}, so a retry at the
|
|
2362
|
+
* same revision appends the same entry. */
|
|
2363
|
+
private buildAttempt(target: AttemptTarget<TAction>, identity: WriteIdentity): Promise<StagedAttempt> {
|
|
2364
|
+
const rev = this.getNextRev();
|
|
2365
|
+
return stageAttempt(this.id, this.sourceCache, target, identity, rev,
|
|
2366
|
+
store => this.logAppendBlockIds(store, identity.actionId, rev));
|
|
2367
|
+
}
|
|
2368
|
+
|
|
2369
|
+
/** Send one attempt — pend, then commit — under the cycle's aged retry `priority`, carrying what
|
|
2370
|
+
* the cycle asked of every send ({@link inFlightCycle}). */
|
|
2371
|
+
private send(staged: StagedAttempt, identity: WriteIdentity, priority: number): Promise<CommitResult> {
|
|
2372
|
+
return this.source.transact(staged.tracker.transforms, identity.actionId, staged.rev, this.id, staged.tailId, {
|
|
2373
|
+
priority,
|
|
2374
|
+
blockDigests: staged.blockDigests,
|
|
2375
|
+
baseRevs: staged.baseRevs,
|
|
2376
|
+
refuseSolo: this.inFlightCycle.refuseSolo
|
|
2377
|
+
});
|
|
2378
|
+
}
|
|
2379
|
+
|
|
2380
|
+
/** Fold a committed attempt's transforms — the log append included — into this instance's read
|
|
2381
|
+
* cache and adopt the revision it committed at. Every caller does this BEFORE replaying what is
|
|
2382
|
+
* still staged (see the note in {@link syncAttempts}). Takes the transforms out of the attempt's
|
|
2383
|
+
* tracker, which is finished with. */
|
|
2384
|
+
private foldOwnCommit(staged: StagedAttempt, actionId: ActionId): void {
|
|
2385
|
+
this.sourceCache.transformCache(staged.tracker.reset(), staged.rev);
|
|
2386
|
+
this.recordCommitted(actionId, staged.rev);
|
|
2161
2387
|
}
|
|
2162
2388
|
|
|
2163
2389
|
/** Refresh from the transactor, then push. Same return contract as {@link sync}: the durability of
|
|
@@ -2172,6 +2398,287 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
2172
2398
|
}
|
|
2173
2399
|
}
|
|
2174
2400
|
|
|
2401
|
+
/** Commit exactly the head sealed segment — the oldest, `entryId` — as one log entry under the
|
|
2402
|
+
* action id and timestamp `options` supplies, for the offline-sync queue's drain
|
|
2403
|
+
* (docs/offline-sync.md §One entry, one network transaction): {@link openHeadCommit} followed by
|
|
2404
|
+
* the one-collection driver, `driveHeadCommit` in head-commit.ts, with the handle closed on every
|
|
2405
|
+
* exit. The attempt machinery is {@link syncAttempts}' ({@link AttemptCycle}, {@link stageAttempt});
|
|
2406
|
+
* what differs is the target — a head tracker ({@link headTrackerFor}) — and the latch, released
|
|
2407
|
+
* around the one network `await` ({@link HeadCommitHandle.release}). `options.recordAttempt` is
|
|
2408
|
+
* called with each attempt before it is sent, and `options.resume` hands back an attempt an
|
|
2409
|
+
* earlier cycle under the same action id recorded (see {@link HeadCommitOptions}).
|
|
2410
|
+
*
|
|
2411
|
+
* @returns what {@link sync} returns: who holds the commit, or `undefined` when the refresh
|
|
2412
|
+
* established that the write was already saved under `options.actionId` without re-sending.
|
|
2413
|
+
* @throws SealedSegmentsError before anything is done, when `entryId` is not the head segment
|
|
2414
|
+
* (`not-head`), carries a recorded refusal (`refused`), or a head commit is already in flight on
|
|
2415
|
+
* this instance (`in-flight`); the head segment's recorded refusal, an {@link ActionRefusedError},
|
|
2416
|
+
* when a refresh or the head tracker's staging refused it during the cycle; whatever
|
|
2417
|
+
* `options.recordAttempt` throws, before anything is sent; otherwise what {@link sync} throws. */
|
|
2418
|
+
async commitHead(entryId: EntryId, options: HeadCommitOptions): Promise<WriteDurability | undefined> {
|
|
2419
|
+
const handle = await this.openHeadCommit(entryId, { actionId: options.actionId, timestamp: options.timestamp }, {
|
|
2420
|
+
refuseSolo: options.refuseSoloCommit,
|
|
2421
|
+
...(options.resume === undefined ? {} : { resume: options.resume }),
|
|
2422
|
+
...(options.onCommittedHead === undefined ? {} : { onCommittedHead: options.onCommittedHead }),
|
|
2423
|
+
});
|
|
2424
|
+
try {
|
|
2425
|
+
return await driveHeadCommit(handle, options);
|
|
2426
|
+
} finally {
|
|
2427
|
+
handle.close();
|
|
2428
|
+
}
|
|
2429
|
+
}
|
|
2430
|
+
|
|
2431
|
+
/** Open a head commit of `entryId` under `identity` and hand back the handle a driver runs it
|
|
2432
|
+
* through, step by step ({@link HeadCommitHandle}): this is {@link commitHead} with the loop left
|
|
2433
|
+
* to the caller, for the coordinator's per-entry commit over several collections, which runs each
|
|
2434
|
+
* step on every collection it wrote in lock-step. Takes the collection latch, which the handle
|
|
2435
|
+
* holds until its `close()` except around the network round trip; checks the three
|
|
2436
|
+
* preconditions; marks the action in flight for the whole cycle ({@link beginInFlightAction}), as
|
|
2437
|
+
* a sync's is, so the refresh between attempts recognises the write's own entry; sets
|
|
2438
|
+
* {@link headCommit}, which tells {@link consumeOwnEntry} that such an entry records the head
|
|
2439
|
+
* segment; and seeds the retained attempt with `options.resume` when one is given, so that the
|
|
2440
|
+
* opening refresh can finish an earlier cycle's torn attempt from it ({@link completeOwnEntry}) —
|
|
2441
|
+
* and `stage()` re-sends it verbatim while the next attempt would request its revision
|
|
2442
|
+
* ({@link resumedAttempt}). The rest of `options` is the cycle's ({@link InFlightCycle}), recorded
|
|
2443
|
+
* with the in-flight mark, so the handle's `send()` and a refresh's re-send of a torn attempt both
|
|
2444
|
+
* carry it.
|
|
2445
|
+
*
|
|
2446
|
+
* **The target.** The live tracker holds every sealed segment and the open one, cumulatively, so
|
|
2447
|
+
* an attempt cannot run on a copy of it the way a sync's does. It runs on a HEAD TRACKER instead
|
|
2448
|
+
* ({@link headTrackerFor}): the head segment's actions alone, staged atomically over the
|
|
2449
|
+
* committed state, with pins of their own — built once per requested revision and reused across
|
|
2450
|
+
* attempts, since a rebuild mints fresh ids for the blocks the actions insert and would send
|
|
2451
|
+
* different content under one `(action id, revision)` (the rule {@link logAppendBlockIds}
|
|
2452
|
+
* closes). Staging runs the actions' guards against the committed state; a refusal there is the
|
|
2453
|
+
* segment's refusal, recorded and reported exactly as a replay's would be, and thrown out of
|
|
2454
|
+
* `stage()`.
|
|
2455
|
+
*
|
|
2456
|
+
* **The latch.** Held for every step EXCEPT the one `await` on the network, so `act`,
|
|
2457
|
+
* `sealPending`, `update` and the rest are not blocked behind a commit that can take seconds
|
|
2458
|
+
* (docs/offline-sync.md §The drain does not hold the collection latch across the network). While
|
|
2459
|
+
* it is released {@link headInFlight} is set: a refresh that walks into this commit's entry defers
|
|
2460
|
+
* to it, and `dropSealed` of the head refuses. A second head commit on this instance waits on the
|
|
2461
|
+
* latch and then meets the `in-flight` precondition.
|
|
2462
|
+
*
|
|
2463
|
+
* **The head's recorded refusal** is re-checked by `stage()` before every attempt and by
|
|
2464
|
+
* `refused()` after every refused send, because a refresh that adopted a rival — a reader's,
|
|
2465
|
+
* while the latch was released, or this cycle's own — may have replayed and refused it; each
|
|
2466
|
+
* throws the recorded refusal in place of another attempt. On success the driver calls `fold()`
|
|
2467
|
+
* (remove the head segment, bump the segment version, fold the attempt's transforms into the
|
|
2468
|
+
* cache and adopt its revision) and only THEN `replay()` (the remaining segments and the open
|
|
2469
|
+
* segment over the committed state that now holds the head) — the fold-before-replay order
|
|
2470
|
+
* {@link syncAttempts} takes, which anything staged while the commit was on the network relies on.
|
|
2471
|
+
*
|
|
2472
|
+
* A driver that opens handles on more than one collection opens them in sorted collection-id
|
|
2473
|
+
* order, the order `TransactionCoordinator.commitOnce` takes the same latches in; see the
|
|
2474
|
+
* interface.
|
|
2475
|
+
*
|
|
2476
|
+
* @throws Error before the latch is taken when `options.resume` was recorded under an action other than
|
|
2477
|
+
* `identity.actionId` — a caller defect, since the attempt would be re-sent under the wrong id;
|
|
2478
|
+
* SealedSegmentsError, with the latch released again, when `entryId` is not the head segment
|
|
2479
|
+
* (`not-head`), carries a recorded refusal (`refused`), or a head commit is already in flight on
|
|
2480
|
+
* this instance (`in-flight`). */
|
|
2481
|
+
async openHeadCommit(entryId: EntryId, identity: WriteIdentity, options: OpenHeadCommitOptions = {}): Promise<HeadCommitHandle> {
|
|
2482
|
+
const { resume, onCommittedHead, ...cycle } = options;
|
|
2483
|
+
if (resume !== undefined && resume.actionId !== identity.actionId) {
|
|
2484
|
+
throw new Error(`Collection ${this.id}: an attempt recorded under action ${resume.actionId} cannot resume `
|
|
2485
|
+
+ `a head commit of ${entryId} under action ${identity.actionId}`);
|
|
2486
|
+
}
|
|
2487
|
+
const release = await Latches.acquire(this.latchId);
|
|
2488
|
+
try {
|
|
2489
|
+
this.assertHeadCommittable(entryId);
|
|
2490
|
+
} catch (err) {
|
|
2491
|
+
release();
|
|
2492
|
+
throw err;
|
|
2493
|
+
}
|
|
2494
|
+
const endInFlight = this.beginInFlightAction(identity.actionId, cycle);
|
|
2495
|
+
this.headCommit = { entryId, ...(onCommittedHead === undefined ? {} : { onCommitted: onCommittedHead }) };
|
|
2496
|
+
if (resume !== undefined) {
|
|
2497
|
+
this.retainInFlightAttempt(resume);
|
|
2498
|
+
}
|
|
2499
|
+
return this.headCommitHandle(entryId, identity, release, endInFlight, resume);
|
|
2500
|
+
}
|
|
2501
|
+
|
|
2502
|
+
/** The handle {@link openHeadCommit} returns: closures over this instance's private state, so
|
|
2503
|
+
* nothing private becomes public. `release` is the latch release of the latch the caller took;
|
|
2504
|
+
* `endInFlight` the disposer of the in-flight mark. The head tracker lives here, per handle, so it
|
|
2505
|
+
* is reused across the attempts of one cycle exactly as the in-line loop reused it. `resume` is
|
|
2506
|
+
* the attempt the cycle was opened with, which `stage()` re-sends verbatim while the next attempt
|
|
2507
|
+
* would request its revision ({@link resumedAttempt}). */
|
|
2508
|
+
private headCommitHandle(entryId: EntryId, identity: WriteIdentity, release: () => void, endInFlight: () => void,
|
|
2509
|
+
resume: InFlightAttempt | undefined): HeadCommitHandle {
|
|
2510
|
+
let held = true;
|
|
2511
|
+
let closed = false;
|
|
2512
|
+
let head: HeadTracker | undefined;
|
|
2513
|
+
const assertUsable = (step: string, needsLatch: boolean) => {
|
|
2514
|
+
if (closed) {
|
|
2515
|
+
throw new Error(`Collection ${this.id}: head commit of ${entryId} is closed; ${step}() is a defect`);
|
|
2516
|
+
}
|
|
2517
|
+
if (held !== needsLatch) {
|
|
2518
|
+
throw new Error(`Collection ${this.id}: head commit of ${entryId} ${held ? 'holds' : 'has released'} the latch; `
|
|
2519
|
+
+ `${step}() is a defect here`);
|
|
2520
|
+
}
|
|
2521
|
+
};
|
|
2522
|
+
return {
|
|
2523
|
+
collectionId: this.id,
|
|
2524
|
+
instanceTag: this.instanceTag,
|
|
2525
|
+
entryId,
|
|
2526
|
+
refresh: (report, lastChance, tailFloor) => {
|
|
2527
|
+
assertUsable('refresh', true);
|
|
2528
|
+
return this.updateInternal(report, lastChance, tailFloor);
|
|
2529
|
+
},
|
|
2530
|
+
nextRev: () => this.getNextRev(),
|
|
2531
|
+
heldRev: () => this.source.actionContext?.rev,
|
|
2532
|
+
stage: async () => {
|
|
2533
|
+
assertUsable('stage', true);
|
|
2534
|
+
const segment = this.committableHead(entryId);
|
|
2535
|
+
const resumed = resumedAttempt(this.sourceCache, resume, this.getNextRev());
|
|
2536
|
+
if (resumed !== undefined) {
|
|
2537
|
+
return resumed;
|
|
2538
|
+
}
|
|
2539
|
+
head = await this.headTrackerFor(segment, head);
|
|
2540
|
+
return this.buildAttempt({ actions: segment.actions, transforms: head.tracker.transforms, pins: head.tracker.pins }, identity);
|
|
2541
|
+
},
|
|
2542
|
+
send: (staged, priority) => {
|
|
2543
|
+
assertUsable('send', false);
|
|
2544
|
+
return this.send(staged, identity, priority);
|
|
2545
|
+
},
|
|
2546
|
+
release: () => {
|
|
2547
|
+
assertUsable('release', true);
|
|
2548
|
+
this.headInFlight = { entryId, actionId: identity.actionId };
|
|
2549
|
+
held = false;
|
|
2550
|
+
release();
|
|
2551
|
+
},
|
|
2552
|
+
retake: async () => {
|
|
2553
|
+
assertUsable('retake', false);
|
|
2554
|
+
const retaken = await Latches.acquire(this.latchId);
|
|
2555
|
+
if (closed) {
|
|
2556
|
+
// close() ran while the latch was being acquired: it has already cleared the marks
|
|
2557
|
+
// latch-free, so keeping this latch would leak it for the life of the instance.
|
|
2558
|
+
retaken();
|
|
2559
|
+
throw new Error(`Collection ${this.id}: head commit of ${entryId} was closed while retake() was waiting; `
|
|
2560
|
+
+ `a driver closes its handle only after retaking`);
|
|
2561
|
+
}
|
|
2562
|
+
release = retaken;
|
|
2563
|
+
held = true;
|
|
2564
|
+
this.headInFlight = undefined;
|
|
2565
|
+
},
|
|
2566
|
+
fold: (staged) => {
|
|
2567
|
+
assertUsable('fold', true);
|
|
2568
|
+
const dropped = this.segments.drop(this.headSegment(entryId).entryId);
|
|
2569
|
+
this.foldOwnCommit(staged, identity.actionId);
|
|
2570
|
+
this.reportCommittedHead(dropped);
|
|
2571
|
+
},
|
|
2572
|
+
replay: () => {
|
|
2573
|
+
assertUsable('replay', true);
|
|
2574
|
+
// NOTE: the remaining sealed segments and the open segment are replayed after EVERY head
|
|
2575
|
+
// commit, so draining a queue of n entries is quadratic in n (docs/offline-sync.md
|
|
2576
|
+
// §Failure modes and accepted tradeoffs). Negligible for tens of entries; if it shows up
|
|
2577
|
+
// for a device that queued thousands, keep per-segment trackers chained over the cache,
|
|
2578
|
+
// so a committed head is popped and folded instead of replayed.
|
|
2579
|
+
return this.replayActions();
|
|
2580
|
+
},
|
|
2581
|
+
refused: (staged) => {
|
|
2582
|
+
assertUsable('refused', true);
|
|
2583
|
+
this.committableHead(entryId);
|
|
2584
|
+
this.retainInFlightAttempt(retainedAttempt(staged, identity.actionId));
|
|
2585
|
+
},
|
|
2586
|
+
close: () => {
|
|
2587
|
+
if (closed) return;
|
|
2588
|
+
closed = true;
|
|
2589
|
+
this.headCommit = undefined;
|
|
2590
|
+
this.headInFlight = undefined;
|
|
2591
|
+
endInFlight();
|
|
2592
|
+
if (held) {
|
|
2593
|
+
held = false;
|
|
2594
|
+
release();
|
|
2595
|
+
}
|
|
2596
|
+
},
|
|
2597
|
+
};
|
|
2598
|
+
}
|
|
2599
|
+
|
|
2600
|
+
/** {@link commitHead}'s preconditions, each a {@link SealedSegmentsError} naming its reason. */
|
|
2601
|
+
private assertHeadCommittable(entryId: EntryId): void {
|
|
2602
|
+
const sealed = this.segments.entryIds();
|
|
2603
|
+
const head = this.segments.head();
|
|
2604
|
+
if (head === undefined || head.entryId !== entryId) {
|
|
2605
|
+
throw new SealedSegmentsError(this.id, sealed, 'not-head', entryId);
|
|
2606
|
+
}
|
|
2607
|
+
if (head.refused !== undefined) {
|
|
2608
|
+
throw new SealedSegmentsError(this.id, sealed, 'refused', entryId);
|
|
2609
|
+
}
|
|
2610
|
+
if (this.headInFlight !== undefined) {
|
|
2611
|
+
throw new SealedSegmentsError(this.id, sealed, 'in-flight', this.headInFlight.entryId);
|
|
2612
|
+
}
|
|
2613
|
+
}
|
|
2614
|
+
|
|
2615
|
+
/** The head segment, which a running head commit may still commit: it is `entryId` — anything
|
|
2616
|
+
* else is a defect ({@link headSegment}) — and it has not been refused meanwhile. A refresh that
|
|
2617
|
+
* adopted a rival may have replayed and refused it, and that refusal, not another attempt, is
|
|
2618
|
+
* then the cycle's answer. */
|
|
2619
|
+
private committableHead(entryId: EntryId): SealedSegment<TAction> {
|
|
2620
|
+
const head = this.headSegment(entryId);
|
|
2621
|
+
if (head.refused !== undefined) {
|
|
2622
|
+
throw head.refused;
|
|
2623
|
+
}
|
|
2624
|
+
return head;
|
|
2625
|
+
}
|
|
2626
|
+
|
|
2627
|
+
/** The head segment, asserted to be `entryId`. Nothing may remove the head while a head commit
|
|
2628
|
+
* of it runs — a refresh that meets it defers, `dropSealed` of it refuses — so anything else here
|
|
2629
|
+
* is a defect, thrown as one. */
|
|
2630
|
+
private headSegment(entryId: EntryId): SealedSegment<TAction> {
|
|
2631
|
+
const head = this.segments.head();
|
|
2632
|
+
if (head === undefined || head.entryId !== entryId) {
|
|
2633
|
+
throw new Error(`Collection ${this.id}: head segment ${entryId} was removed while its commit was running `
|
|
2634
|
+
+ `(the head is ${head?.entryId ?? 'nothing'})`);
|
|
2635
|
+
}
|
|
2636
|
+
return head;
|
|
2637
|
+
}
|
|
2638
|
+
|
|
2639
|
+
/** The tracker a head attempt is built from (see {@link commitHead}): `current`, while it was
|
|
2640
|
+
* built for the revision the next attempt requests and no base under it has moved; otherwise a
|
|
2641
|
+
* fresh one ({@link buildHeadTracker}). A revision that moved is a write that is genuinely
|
|
2642
|
+
* different. A base that moved at the same revision is re-judged exactly as
|
|
2643
|
+
* {@link restageIfBasesMoved} re-judges the live queue before an attempt, and rebuilds.
|
|
2644
|
+
* NOTE: that rebuild is the same exception to the byte-identical retry that {@link syncAttempts}
|
|
2645
|
+
* records at its `restageIfBasesMoved` call — fresh ids for the blocks the actions insert under
|
|
2646
|
+
* an unchanged `(action id, revision)` — reached the same narrow way and refused by storage's
|
|
2647
|
+
* base guard on the same machines; the same answer applies if it is ever seen. */
|
|
2648
|
+
private async headTrackerFor(segment: SealedSegment<TAction>, current: HeadTracker | undefined): Promise<HeadTracker> {
|
|
2649
|
+
const rev = this.getNextRev();
|
|
2650
|
+
if (current?.rev === rev) {
|
|
2651
|
+
await this.rereadUnretainedBases(current.tracker);
|
|
2652
|
+
if (this.logMovedBases(current.tracker.movedBases()) === 0) {
|
|
2653
|
+
return current;
|
|
2654
|
+
}
|
|
2655
|
+
}
|
|
2656
|
+
return { rev, tracker: await this.buildHeadTracker(segment) };
|
|
2657
|
+
}
|
|
2658
|
+
|
|
2659
|
+
/** A tracker over this instance's read cache, with pins of its own, holding `segment`'s actions
|
|
2660
|
+
* staged atomically over the committed state — from the invented baseline while this collection
|
|
2661
|
+
* has no committed revision ({@link replayBaseline}): its header, log block and root then exist
|
|
2662
|
+
* nowhere else, and the head's commit has to carry them. A refusal is the segment's own,
|
|
2663
|
+
* recorded and reported ({@link recordSealedRefusal}) and thrown; a live replay that found it
|
|
2664
|
+
* first has already done the recording, and the caller never gets here. */
|
|
2665
|
+
private async buildHeadTracker(segment: SealedSegment<TAction>): Promise<Tracker<IBlock>> {
|
|
2666
|
+
const tracker = new Tracker<IBlock>(this.sourceCache, this.replayBaseline());
|
|
2667
|
+
try {
|
|
2668
|
+
segment.applied = await this.stageInto(tracker, ...segment.actions);
|
|
2669
|
+
} catch (err) {
|
|
2670
|
+
if (err instanceof ActionRefusedError) {
|
|
2671
|
+
// NOTE: the live tracker still holds this segment's effects from its last replay, which
|
|
2672
|
+
// judged the same committed state and did not refuse; a reader sees them until the next
|
|
2673
|
+
// replay (the queue's drop of the refused segment). Reachable only if a base re-read
|
|
2674
|
+
// catches up between the two stagings; if that is ever seen, replay here after recording.
|
|
2675
|
+
this.recordSealedRefusal(segment, err);
|
|
2676
|
+
}
|
|
2677
|
+
throw err;
|
|
2678
|
+
}
|
|
2679
|
+
return tracker;
|
|
2680
|
+
}
|
|
2681
|
+
|
|
2175
2682
|
/** Stage `actions` and flush them as one call that either takes effect or leaves NOTHING behind:
|
|
2176
2683
|
* when the flush throws, the actions this call staged are unstaged again before the error escapes.
|
|
2177
2684
|
*
|
|
@@ -2193,6 +2700,9 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
2193
2700
|
async actAndSync(actions: Action<TAction>[], options?: SyncOptions): Promise<WriteDurability | undefined> {
|
|
2194
2701
|
const release = await Latches.acquire(this.latchId);
|
|
2195
2702
|
try {
|
|
2703
|
+
// Refused before staging, so there is nothing to unstage: the sync below would refuse
|
|
2704
|
+
// anyway (syncInternal), and staging first would only have to be taken back.
|
|
2705
|
+
this.assertNoSealedSegments();
|
|
2196
2706
|
const stagedBefore = copyTransforms(this.tracker.transforms);
|
|
2197
2707
|
const revBefore = this.source.actionContext?.rev;
|
|
2198
2708
|
await this.actInternal(...actions);
|
|
@@ -2213,18 +2723,19 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
2213
2723
|
* revision from before the actions were staged.
|
|
2214
2724
|
*
|
|
2215
2725
|
* While the held revision has not moved, the earlier transforms are reinstated verbatim rather
|
|
2216
|
-
* than rebuilt by replay:
|
|
2217
|
-
* no
|
|
2218
|
-
* the
|
|
2219
|
-
*
|
|
2220
|
-
*
|
|
2726
|
+
* than rebuilt by replay: they are exactly the state before the call, and reinstating them costs
|
|
2727
|
+
* no handler run (a replay would rebuild the same state from {@link inventedBaseline} and the
|
|
2728
|
+
* staged actions). Once the revision has moved those transforms describe blocks at a revision
|
|
2729
|
+
* this handle has left, so what remains is re-staged against the adopted one, exactly as a
|
|
2730
|
+
* refresh would have done. */
|
|
2221
2731
|
private async unstage(actions: Action<TAction>[], stagedBefore: Transforms, revBefore: number | undefined): Promise<void> {
|
|
2222
2732
|
// NOTE: matched by identity, which is what `filterAgainstEntry` promises for a kept action.
|
|
2223
2733
|
// A `filterConflict` hook that answers a REPLACEMENT instance for one of these actions would
|
|
2224
2734
|
// leave the replacement staged here. No collection installs such a hook today (`Tree` and
|
|
2225
2735
|
// `Diary` install none); if one ever does, carry a per-call token on the staged actions and
|
|
2226
2736
|
// match on that instead.
|
|
2227
|
-
|
|
2737
|
+
// The actions were staged into the OPEN segment (actAndSync refuses over sealed segments).
|
|
2738
|
+
this.segments.open = this.segments.open.filter(staged => !actions.includes(staged));
|
|
2228
2739
|
if (this.source.actionContext?.rev === revBefore) {
|
|
2229
2740
|
this.tracker.reset(stagedBefore);
|
|
2230
2741
|
} else {
|
|
@@ -2246,14 +2757,70 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
2246
2757
|
}
|
|
2247
2758
|
}
|
|
2248
2759
|
|
|
2249
|
-
|
|
2250
|
-
|
|
2251
|
-
|
|
2252
|
-
|
|
2760
|
+
/** Rebuild the tracker from the staged actions over the committed state this collection now
|
|
2761
|
+
* reads at (always called under latch): reset to {@link replayBaseline}, then every sealed
|
|
2762
|
+
* segment in order, then the open segment.
|
|
2763
|
+
*
|
|
2764
|
+
* A SEALED segment is staged as ONE atomic unit — one `internalTransact` call over all of its
|
|
2765
|
+
* actions — so a refusal of any action in it leaves none of its writes staged, and a refusal
|
|
2766
|
+
* ({@link ActionRefusedError}, the only class caught) is that segment's own: recorded on it,
|
|
2767
|
+
* reported through `onSealedRefused`, and the replay goes on to the next segment. A segment
|
|
2768
|
+
* already refused is skipped and not reported again; it stays listed until dropped. The OPEN
|
|
2769
|
+
* segment keeps the pre-segment behaviour: one `internalTransact` per action, and a refusal
|
|
2770
|
+
* propagates, since it is the live transaction's own (docs/offline-sync.md §Replay with a
|
|
2771
|
+
* per-segment refusal). Any error that is not a refusal propagates from either.
|
|
2772
|
+
*
|
|
2773
|
+
* Each re-staged update pins its base through `Atomic.commit` → `Tracker.absorb`, the path
|
|
2774
|
+
* {@link act} uses, so the pend declares the bases the re-staged operations were computed on. Each
|
|
2775
|
+
* sealed segment that staged records what its actions accepted as already applied
|
|
2776
|
+
* (`SealedSegment.applied`), the tally the head commit reports when the segment is committed.
|
|
2777
|
+
*
|
|
2778
|
+
* @param unreported - a segment whose refusal is recorded but NOT reported through
|
|
2779
|
+
* `onSealedRefused`: the one {@link restoreSealed} is inserting, whose caller reads the recorded
|
|
2780
|
+
* refusal off the segment itself. */
|
|
2781
|
+
private async replayActions(unreported?: EntryId): Promise<void> {
|
|
2782
|
+
this.tracker.reset(this.replayBaseline());
|
|
2783
|
+
for (const segment of this.segments.replayable()) {
|
|
2784
|
+
try {
|
|
2785
|
+
segment.applied = await this.internalTransact(...segment.actions);
|
|
2786
|
+
} catch (err) {
|
|
2787
|
+
if (!(err instanceof ActionRefusedError)) {
|
|
2788
|
+
throw err;
|
|
2789
|
+
}
|
|
2790
|
+
this.recordSealedRefusal(segment, err, segment.entryId !== unreported);
|
|
2791
|
+
}
|
|
2792
|
+
}
|
|
2793
|
+
for (const action of this.segments.open) {
|
|
2253
2794
|
await this.internalTransact(action);
|
|
2254
2795
|
}
|
|
2255
2796
|
}
|
|
2256
2797
|
|
|
2798
|
+
/** What a replay resets the tracker to: a copy of {@link inventedBaseline} while this collection
|
|
2799
|
+
* holds no committed revision (those blocks exist nowhere else), and nothing otherwise. */
|
|
2800
|
+
private replayBaseline(): Transforms {
|
|
2801
|
+
return this.source.actionContext === undefined && this.inventedBaseline !== undefined
|
|
2802
|
+
? copyTransforms(this.inventedBaseline)
|
|
2803
|
+
: emptyTransforms();
|
|
2804
|
+
}
|
|
2805
|
+
|
|
2806
|
+
/** Record a replay's refusal of a sealed segment and, when `report` says so, report it once,
|
|
2807
|
+
* under the latch. The callback's throw is logged rather than raised: the refusal is already
|
|
2808
|
+
* recorded, and the rest of the replay must still run. */
|
|
2809
|
+
private recordSealedRefusal(segment: SealedSegment<TAction>, error: ActionRefusedError, report = true): void {
|
|
2810
|
+
this.segments.refuse(segment.entryId, error);
|
|
2811
|
+
log('collection:sealed-segment-refused id=%s tag=%s entry=%s reported=%s error=%s',
|
|
2812
|
+
this.id, this.instanceTag, segment.entryId, report, error.message);
|
|
2813
|
+
if (!report) {
|
|
2814
|
+
return;
|
|
2815
|
+
}
|
|
2816
|
+
try {
|
|
2817
|
+
this.onSealedRefused?.(segment.entryId, error);
|
|
2818
|
+
} catch (err) {
|
|
2819
|
+
log('collection:refusal-callback-threw id=%s tag=%s entry=%s error=%s',
|
|
2820
|
+
this.id, this.instanceTag, segment.entryId, err instanceof Error ? err.message : String(err));
|
|
2821
|
+
}
|
|
2822
|
+
}
|
|
2823
|
+
|
|
2257
2824
|
getReadDependencies(): ReadDependency[] {
|
|
2258
2825
|
return this.source.getReadDependencies();
|
|
2259
2826
|
}
|
|
@@ -2279,13 +2846,9 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
2279
2846
|
* than kept, because nothing proves it is current at the revision the refresh will pin to.
|
|
2280
2847
|
*
|
|
2281
2848
|
* Both answers pass {@link answeredBlock}'s checks as unpinned reads, header first, so a doubted
|
|
2282
|
-
* header or tail throws exactly as it would through {@link TransactorSource.tryGet}.
|
|
2283
|
-
*
|
|
2284
|
-
*
|
|
2285
|
-
* (`NetworkTransactor.get` throws on a missing id), so an unreachable out-of-date tail fails a
|
|
2286
|
-
* refresh that would not have needed it. Harmless today: the log has no checkpoints, so a
|
|
2287
|
-
* refresh that finds a new tail walks back through the old one anyway. If checkpoints start
|
|
2288
|
-
* letting that walk stop short, read the known tail in its own request instead.
|
|
2849
|
+
* header or tail throws exactly as it would through {@link TransactorSource.tryGet}. An
|
|
2850
|
+
* out-of-date tail no coordinator answered comes back flagged (`NetworkTransactor.get` flags that
|
|
2851
|
+
* one block rather than failing the request), and its answer is dropped unjudged.
|
|
2289
2852
|
*
|
|
2290
2853
|
* `tailFloor` (see {@link updateInternal}) goes on whichever request reads the tail — never on
|
|
2291
2854
|
* the header, which is rewritten only when the tail rolls over or the collection changes it
|
|
@@ -2306,15 +2869,12 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
2306
2869
|
blockIds: knownTailId === undefined ? [id] : [id, knownTailId],
|
|
2307
2870
|
...Collection.tailFloorField(knownTailId, tailFloor),
|
|
2308
2871
|
});
|
|
2309
|
-
const
|
|
2310
|
-
if (
|
|
2872
|
+
const answered = Collection.answeredHeader(id, results?.[id]);
|
|
2873
|
+
if (answered === undefined) {
|
|
2311
2874
|
return undefined;
|
|
2312
2875
|
}
|
|
2313
|
-
const header =
|
|
2314
|
-
|
|
2315
|
-
return undefined;
|
|
2316
|
-
}
|
|
2317
|
-
const served: LogEnds['served'] = [[id, header, servedRevision(headerEntry)]];
|
|
2876
|
+
const { header } = answered;
|
|
2877
|
+
const served: LogEnds['served'] = [[id, header, answered.servedRev]];
|
|
2318
2878
|
const tailId = header.tailId;
|
|
2319
2879
|
if (tailId === undefined) {
|
|
2320
2880
|
return { header, served };
|
|
@@ -2328,6 +2888,73 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
2328
2888
|
return { header, tail, served };
|
|
2329
2889
|
}
|
|
2330
2890
|
|
|
2891
|
+
/** The header a repo answered for collection `id`, judged as an unpinned read, with the
|
|
2892
|
+
* revision it was served at. `undefined` when it is authoritatively absent — no entry, or one
|
|
2893
|
+
* with no block; a throw when the repo could not retrieve it or could not confirm it current
|
|
2894
|
+
* ({@link answeredBlock}). */
|
|
2895
|
+
private static answeredHeader(id: CollectionId, entry: GetBlockResult | undefined): { header: CollectionHeaderBlock; servedRev: number } | undefined {
|
|
2896
|
+
if (entry === undefined) {
|
|
2897
|
+
return undefined;
|
|
2898
|
+
}
|
|
2899
|
+
const header = answeredBlock(id, entry, undefined) as CollectionHeaderBlock | undefined;
|
|
2900
|
+
return header ? { header, servedRev: servedRevision(entry) } : undefined;
|
|
2901
|
+
}
|
|
2902
|
+
|
|
2903
|
+
/** The committed tail a header naming `tailId` describes, given the repo's answer for that
|
|
2904
|
+
* block: `undefined` when the block has no committed revision (nothing committed yet). */
|
|
2905
|
+
private static committedTailOf(tailId: BlockId, tail: GetBlockResult | undefined): CommittedTail | undefined {
|
|
2906
|
+
const rev = tail?.state.latest?.rev;
|
|
2907
|
+
return rev === undefined ? undefined : { tailId, rev };
|
|
2908
|
+
}
|
|
2909
|
+
|
|
2910
|
+
/** The committed tail `tailId` names, read out of `reads` and checked as {@link checkedLogTail}
|
|
2911
|
+
* describes; `undefined` for no tail id. Throws the block's failed read, or a doubted answer. */
|
|
2912
|
+
private static judgedTail(tailId: BlockId | undefined, reads: AttributedReads): CommittedTail | undefined {
|
|
2913
|
+
return tailId === undefined
|
|
2914
|
+
? undefined
|
|
2915
|
+
: Collection.committedTailOf(tailId, Collection.checkedLogTail(tailId, Collection.entryIn(reads, tailId)));
|
|
2916
|
+
}
|
|
2917
|
+
|
|
2918
|
+
/** The repo's entry for `id` in `reads`, or the error reading it failed with, thrown. */
|
|
2919
|
+
private static entryIn(reads: AttributedReads, id: BlockId): GetBlockResult | undefined {
|
|
2920
|
+
const read = reads.get(id);
|
|
2921
|
+
if (read !== undefined && 'error' in read) {
|
|
2922
|
+
throw read.error;
|
|
2923
|
+
}
|
|
2924
|
+
return read?.entry;
|
|
2925
|
+
}
|
|
2926
|
+
|
|
2927
|
+
/** Unpinned reads of `blockIds` in ONE request, each block's answer kept apart. When that
|
|
2928
|
+
* request throws, each block is read in a request of its own — concurrently — so the failure
|
|
2929
|
+
* lands on the blocks it belongs to and every other block still answers.
|
|
2930
|
+
*
|
|
2931
|
+
* NOTE: the fallback is unbounded — two gets per collection at once, only after a failed
|
|
2932
|
+
* request. Fine for the tens of tables a host watches; if callers ever name hundreds, read the
|
|
2933
|
+
* fallback in bounded batches. */
|
|
2934
|
+
private static async readAttributed(transactor: ITransactor, blockIds: BlockId[]): Promise<AttributedReads> {
|
|
2935
|
+
if (blockIds.length === 0) {
|
|
2936
|
+
return new Map();
|
|
2937
|
+
}
|
|
2938
|
+
try {
|
|
2939
|
+
const results = await transactor.get({ blockIds });
|
|
2940
|
+
return new Map(blockIds.map(id => [id, { entry: results?.[id] }]));
|
|
2941
|
+
} catch (error) {
|
|
2942
|
+
if (blockIds.length === 1) {
|
|
2943
|
+
return new Map([[blockIds[0]!, { error }]]);
|
|
2944
|
+
}
|
|
2945
|
+
log('collection:tails-read-split blocks=%d error=%o', blockIds.length, error);
|
|
2946
|
+
return new Map(await Promise.all(blockIds.map(async id => [id, await Collection.readAlone(transactor, id)] as const)));
|
|
2947
|
+
}
|
|
2948
|
+
}
|
|
2949
|
+
|
|
2950
|
+
private static async readAlone(transactor: ITransactor, id: BlockId): Promise<AttributedRead> {
|
|
2951
|
+
try {
|
|
2952
|
+
return { entry: (await transactor.get({ blockIds: [id] }))?.[id] };
|
|
2953
|
+
} catch (error) {
|
|
2954
|
+
return { error };
|
|
2955
|
+
}
|
|
2956
|
+
}
|
|
2957
|
+
|
|
2331
2958
|
/** An unpinned read of the log tail block, checked as {@link checkedLogTail} describes, carrying
|
|
2332
2959
|
* `tailFloor` when the caller has one (see {@link readLogEnds}). */
|
|
2333
2960
|
private static async readLogTail(transactor: ITransactor, tailId: BlockId, tailFloor?: number): Promise<GetBlockResult | undefined> {
|