@optimystic/db-core 1.22.0 → 1.24.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 +8 -4
- package/dist/src/collection/action.d.ts +7 -4
- package/dist/src/collection/action.d.ts.map +1 -1
- package/dist/src/collection/action.js +13 -5
- package/dist/src/collection/action.js.map +1 -1
- package/dist/src/collection/collection.d.ts +134 -46
- package/dist/src/collection/collection.d.ts.map +1 -1
- package/dist/src/collection/collection.js +207 -70
- package/dist/src/collection/collection.js.map +1 -1
- package/dist/src/collection/struct.d.ts +38 -8
- package/dist/src/collection/struct.d.ts.map +1 -1
- package/dist/src/collection/struct.js.map +1 -1
- package/dist/src/collection/write-attempts.d.ts +138 -34
- package/dist/src/collection/write-attempts.d.ts.map +1 -1
- package/dist/src/collection/write-attempts.js +168 -101
- package/dist/src/collection/write-attempts.js.map +1 -1
- package/dist/src/collections/diary/diary.d.ts.map +1 -1
- package/dist/src/collections/diary/diary.js +5 -1
- package/dist/src/collections/diary/diary.js.map +1 -1
- package/dist/src/collections/tree/tree.d.ts +15 -9
- package/dist/src/collections/tree/tree.d.ts.map +1 -1
- package/dist/src/collections/tree/tree.js +6 -4
- package/dist/src/collections/tree/tree.js.map +1 -1
- package/dist/src/hlc/clock-store.d.ts +63 -0
- package/dist/src/hlc/clock-store.d.ts.map +1 -0
- package/dist/src/hlc/clock-store.js +49 -0
- package/dist/src/hlc/clock-store.js.map +1 -0
- package/dist/src/hlc/clock.d.ts +64 -0
- package/dist/src/hlc/clock.d.ts.map +1 -0
- package/dist/src/hlc/clock.js +171 -0
- package/dist/src/hlc/clock.js.map +1 -0
- package/dist/src/hlc/hlc.d.ts +38 -0
- package/dist/src/hlc/hlc.d.ts.map +1 -0
- package/dist/src/hlc/hlc.js +41 -0
- package/dist/src/hlc/hlc.js.map +1 -0
- package/dist/src/hlc/index.d.ts +5 -0
- package/dist/src/hlc/index.d.ts.map +1 -0
- package/dist/src/hlc/index.js +5 -0
- package/dist/src/hlc/index.js.map +1 -0
- package/dist/src/hlc/skew.d.ts +35 -0
- package/dist/src/hlc/skew.d.ts.map +1 -0
- package/dist/src/hlc/skew.js +35 -0
- package/dist/src/hlc/skew.js.map +1 -0
- 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/lane/index.d.ts +2 -0
- package/dist/src/lane/index.d.ts.map +1 -0
- package/dist/src/lane/index.js +2 -0
- package/dist/src/lane/index.js.map +1 -0
- package/dist/src/lane/lane.d.ts +46 -0
- package/dist/src/lane/lane.d.ts.map +1 -0
- package/dist/src/lane/lane.js +26 -0
- package/dist/src/lane/lane.js.map +1 -0
- package/dist/src/log/log.d.ts +50 -22
- package/dist/src/log/log.d.ts.map +1 -1
- package/dist/src/log/log.js +21 -13
- package/dist/src/log/log.js.map +1 -1
- package/dist/src/log/struct.d.ts +61 -1
- package/dist/src/log/struct.d.ts.map +1 -1
- package/dist/src/log/struct.js +24 -0
- package/dist/src/log/struct.js.map +1 -1
- package/dist/src/network/i-repo.d.ts +10 -0
- package/dist/src/network/i-repo.d.ts.map +1 -1
- package/dist/src/network/stale-failure.d.ts +20 -7
- package/dist/src/network/stale-failure.d.ts.map +1 -1
- package/dist/src/network/stale-failure.js +29 -7
- package/dist/src/network/stale-failure.js.map +1 -1
- package/dist/src/network/struct.d.ts +35 -0
- package/dist/src/network/struct.d.ts.map +1 -1
- package/dist/src/network/struct.js.map +1 -1
- package/dist/src/offline/entry.d.ts +14 -0
- package/dist/src/offline/entry.d.ts.map +1 -1
- package/dist/src/offline/entry.js +2 -0
- package/dist/src/offline/entry.js.map +1 -1
- package/dist/src/offline/journal.d.ts +10 -0
- package/dist/src/offline/journal.d.ts.map +1 -1
- package/dist/src/offline/queue.d.ts +10 -0
- package/dist/src/offline/queue.d.ts.map +1 -1
- package/dist/src/offline/queue.js +29 -3
- package/dist/src/offline/queue.js.map +1 -1
- package/dist/src/offline/status.d.ts +7 -0
- package/dist/src/offline/status.d.ts.map +1 -1
- package/dist/src/offline/status.js.map +1 -1
- package/dist/src/testing/test-transactor.d.ts +9 -1
- package/dist/src/testing/test-transactor.d.ts.map +1 -1
- package/dist/src/testing/test-transactor.js +6 -1
- package/dist/src/testing/test-transactor.js.map +1 -1
- package/dist/src/transaction/actions-engine.d.ts +3 -0
- package/dist/src/transaction/actions-engine.d.ts.map +1 -1
- package/dist/src/transaction/actions-engine.js +3 -0
- package/dist/src/transaction/actions-engine.js.map +1 -1
- package/dist/src/transaction/coordinator.d.ts +10 -5
- package/dist/src/transaction/coordinator.d.ts.map +1 -1
- package/dist/src/transaction/coordinator.js +197 -48
- package/dist/src/transaction/coordinator.js.map +1 -1
- package/dist/src/transaction/entry-commit.d.ts +45 -10
- package/dist/src/transaction/entry-commit.d.ts.map +1 -1
- package/dist/src/transaction/entry-commit.js +20 -7
- package/dist/src/transaction/entry-commit.js.map +1 -1
- package/dist/src/transaction/errors.d.ts +69 -1
- package/dist/src/transaction/errors.d.ts.map +1 -1
- package/dist/src/transaction/errors.js +70 -1
- package/dist/src/transaction/errors.js.map +1 -1
- package/dist/src/transaction/index.d.ts +1 -1
- package/dist/src/transaction/index.d.ts.map +1 -1
- package/dist/src/transaction/index.js +1 -1
- package/dist/src/transaction/index.js.map +1 -1
- package/dist/src/transaction/session.d.ts.map +1 -1
- package/dist/src/transaction/session.js +18 -5
- package/dist/src/transaction/session.js.map +1 -1
- package/dist/src/transaction/transaction.d.ts +74 -15
- package/dist/src/transaction/transaction.d.ts.map +1 -1
- package/dist/src/transaction/transaction.js +35 -15
- package/dist/src/transaction/transaction.js.map +1 -1
- package/dist/src/transaction/validator.d.ts +25 -4
- package/dist/src/transaction/validator.d.ts.map +1 -1
- package/dist/src/transaction/validator.js +45 -5
- package/dist/src/transaction/validator.js.map +1 -1
- package/dist/src/transactor/block-floors.d.ts +12 -1
- package/dist/src/transactor/block-floors.d.ts.map +1 -1
- package/dist/src/transactor/block-floors.js +14 -1
- package/dist/src/transactor/block-floors.js.map +1 -1
- package/dist/src/transactor/network-transactor.d.ts +8 -0
- package/dist/src/transactor/network-transactor.d.ts.map +1 -1
- package/dist/src/transactor/network-transactor.js +8 -4
- package/dist/src/transactor/network-transactor.js.map +1 -1
- package/dist/src/transactor/transactor-source.d.ts +11 -0
- package/dist/src/transactor/transactor-source.d.ts.map +1 -1
- package/dist/src/transactor/transactor-source.js +5 -1
- package/dist/src/transactor/transactor-source.js.map +1 -1
- package/dist/src/transactor/transactor.d.ts +8 -0
- package/dist/src/transactor/transactor.d.ts.map +1 -1
- package/dist/src/transform/cache-source.d.ts +7 -0
- package/dist/src/transform/cache-source.d.ts.map +1 -1
- package/dist/src/transform/cache-source.js +14 -18
- package/dist/src/transform/cache-source.js.map +1 -1
- package/package.json +1 -1
- package/src/collection/action.ts +13 -5
- package/src/collection/collection.ts +250 -76
- package/src/collection/struct.ts +38 -8
- package/src/collection/write-attempts.ts +213 -109
- package/src/collections/diary/diary.ts +5 -1
- package/src/collections/tree/tree.ts +18 -11
- package/src/hlc/clock-store.ts +68 -0
- package/src/hlc/clock.ts +196 -0
- package/src/hlc/hlc.ts +56 -0
- package/src/hlc/index.ts +4 -0
- package/src/hlc/skew.ts +55 -0
- package/src/index.ts +2 -0
- package/src/lane/index.ts +1 -0
- package/src/lane/lane.ts +54 -0
- package/src/log/log.ts +341 -310
- package/src/log/struct.ts +62 -1
- package/src/network/i-repo.ts +11 -1
- package/src/network/stale-failure.ts +31 -7
- package/src/network/struct.ts +805 -770
- package/src/offline/entry.ts +16 -0
- package/src/offline/journal.ts +10 -0
- package/src/offline/queue.ts +38 -4
- package/src/offline/status.ts +7 -0
- package/src/testing/test-transactor.ts +1065 -1053
- package/src/transaction/actions-engine.ts +3 -0
- package/src/transaction/coordinator.ts +229 -54
- package/src/transaction/entry-commit.ts +56 -14
- package/src/transaction/errors.ts +60 -0
- package/src/transaction/index.ts +1 -1
- package/src/transaction/session.ts +18 -5
- package/src/transaction/transaction.ts +90 -17
- package/src/transaction/validator.ts +46 -5
- package/src/transactor/block-floors.ts +15 -1
- package/src/transactor/network-transactor.ts +15 -4
- package/src/transactor/transactor-source.ts +15 -1
- package/src/transactor/transactor.ts +9 -0
- package/src/transform/cache-source.ts +15 -17
|
@@ -2,6 +2,7 @@ import type { IBlock, Action, ActionType, ActionHandler, BlockId, ITransactor, B
|
|
|
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";
|
|
5
|
+
import { hlcOf } from "../log/struct.js";
|
|
5
6
|
import { Atomic } from "../transform/atomic.js";
|
|
6
7
|
import { Tracker } from "../transform/tracker.js";
|
|
7
8
|
import type { BasePins } from "../transform/base-pins.js";
|
|
@@ -24,6 +25,9 @@ import { driveHeadCommit } from "./head-commit.js";
|
|
|
24
25
|
import type { HeadCommitHandle } from "./head-commit.js";
|
|
25
26
|
import type { ReadDependency } from "../transaction/transaction.js";
|
|
26
27
|
import { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
|
|
28
|
+
import { clockOf, type HlcClock } from "../hlc/clock.js";
|
|
29
|
+
import { maxHlc, type Hlc } from "../hlc/hlc.js";
|
|
30
|
+
import { stricterLane, type Lane } from "../lane/lane.js";
|
|
27
31
|
import { randomBytes } from '@noble/hashes/utils.js';
|
|
28
32
|
import { toString as uint8ArrayToString } from 'uint8arrays/to-string';
|
|
29
33
|
import { Latches } from "../utility/latches.js";
|
|
@@ -52,6 +56,18 @@ type DivergenceSite = 'refresh' | 'attach';
|
|
|
52
56
|
* as `forkRev=` / `heldAction=` / `readAction=`. */
|
|
53
57
|
type LineageFork = { rev: number, heldAction: ActionId, readAction: ActionId };
|
|
54
58
|
|
|
59
|
+
/** What adopting a freshly-read context does to the one a handle holds — {@link Collection.judgeAdoption}'s
|
|
60
|
+
* answer, decided before anything changes because an adopted divergence has to clear the read cache
|
|
61
|
+
* and the floors before the refresh's walk raises the new lineage's floors.
|
|
62
|
+
*
|
|
63
|
+
* - `refuse` — the read is not adopted: it learned nothing, or it is older than the held revision
|
|
64
|
+
* (`collection:context-not-lowered`).
|
|
65
|
+
* - `adopt` — the read is adopted, and names the same action as the held context at the held
|
|
66
|
+
* revision, or one side names none there.
|
|
67
|
+
* - `adopt-divergent` — the read is adopted, and names a different action at the held revision: the
|
|
68
|
+
* handle has been reading another lineage than the one the network holds. */
|
|
69
|
+
type Adoption = 'refuse' | 'adopt' | 'adopt-divergent';
|
|
70
|
+
|
|
55
71
|
/** What one refresh ({@link Collection.refreshInFlight}, and the refresh inside a sync) found out
|
|
56
72
|
* about the write in flight on the instance's behalf. The caller hands in an empty report and the
|
|
57
73
|
* refresh fills it in AS IT GOES, rather than returning it at the end, so a refresh that throws
|
|
@@ -90,27 +106,51 @@ type AttributedReads = Map<BlockId, AttributedRead>;
|
|
|
90
106
|
type TailReadFields = Pick<BlockGets, 'skipWindowConsult'>;
|
|
91
107
|
|
|
92
108
|
/** The tracker a head commit's attempts are built from: the head segment's actions staged over the
|
|
93
|
-
* committed state,
|
|
109
|
+
* committed state, the revision the attempt built from it requests, and the lineage it was staged
|
|
110
|
+
* over — the action the held context named at its own revision, `undefined` when none (see
|
|
94
111
|
* {@link Collection.headTrackerFor}). */
|
|
95
112
|
type HeadTracker = {
|
|
96
113
|
rev: number;
|
|
114
|
+
lineage: ActionId | undefined;
|
|
97
115
|
tracker: Tracker<IBlock>;
|
|
98
116
|
};
|
|
99
117
|
|
|
118
|
+
/**
|
|
119
|
+
* The convergent lane's conflict rule for a collection (`Lane` in `packages/db-core/src/lane/lane.ts`):
|
|
120
|
+
* which of its actions may be committed by one machine without first agreeing with the others and
|
|
121
|
+
* merged into their concurrent writes later, and how such an action is rebased over a stranger's
|
|
122
|
+
* committed ones. A collection with NO declaration is strong: every action is `serializable`, the
|
|
123
|
+
* revision order decides every conflict, and nothing merges — today's behaviour, and `Tree`'s. The
|
|
124
|
+
* declaration is the opt-in; db-core has no notion of a table's profile beyond it.
|
|
125
|
+
*
|
|
126
|
+
* Convergence is a property of the OPERATION, never of the collection as a whole (idempotence is not
|
|
127
|
+
* the criterion — see `Lane`), which is why the declaration classifies per action.
|
|
128
|
+
*/
|
|
129
|
+
export type ConvergentMerge<TAction> = {
|
|
130
|
+
/** The lane of one of this collection's actions when no engine has classified it: a bare
|
|
131
|
+
* `Collection.sync` with no `SyncOptions.lane`, or an offline-queue entry sealed without a
|
|
132
|
+
* classification (`OfflineQueue.enqueue`). The stricter answer over several actions is the write's
|
|
133
|
+
* (`Collection.laneOf`). */
|
|
134
|
+
laneOf(action: Action<TAction>): Lane;
|
|
135
|
+
/** Rebase one of this collection's CONVERGENT actions over a stranger's committed actions, which a
|
|
136
|
+
* refresh found in the log after the action was staged. Offered only an action whose
|
|
137
|
+
* {@link laneOf} is `convergent`: a serializable action is kept as-is, since its guards decide on
|
|
138
|
+
* replay. Return the same instance to keep the action unchanged, a new instance to apply in its
|
|
139
|
+
* place (re-staged by the conflict replay), or `undefined` to drop it. Optional, since a convergent
|
|
140
|
+
* action that touches no shared block (a diary append) has nothing to rebase. */
|
|
141
|
+
filterConflict?(action: Action<TAction>, committed: Action<TAction>[]): Action<TAction> | undefined;
|
|
142
|
+
};
|
|
143
|
+
|
|
100
144
|
export type CollectionInitOptions<TAction> = {
|
|
101
145
|
/** One handler per action type. A handler may answer what the action accepted as already applied
|
|
102
146
|
* ({@link AlreadyAppliedTally}); one that answers nothing counts as the zero tally, so a collection
|
|
103
147
|
* type with no such notion returns nothing. */
|
|
104
148
|
modules: Record<ActionType, ActionHandler<TAction, AlreadyAppliedTally | void>>;
|
|
105
149
|
createHeaderBlock: (id: BlockId, store: BlockStore<IBlock>) => IBlock;
|
|
106
|
-
/**
|
|
107
|
-
*
|
|
108
|
-
*
|
|
109
|
-
|
|
110
|
-
* action (return a new instance to apply instead of the original — it is re-staged via
|
|
111
|
-
* the conflict replay), or undefined to discard this action
|
|
112
|
-
*/
|
|
113
|
-
filterConflict?: (action: Action<TAction>, potential: Action<TAction>[]) => Action<TAction> | undefined;
|
|
150
|
+
/** The convergent lane's conflict rule for this collection ({@link ConvergentMerge}): which of its
|
|
151
|
+
* actions are convergent, and how one is rebased over a stranger's committed actions. Omit for a
|
|
152
|
+
* strong collection, whose every action is `serializable` and is kept as-is through a refresh. */
|
|
153
|
+
merge?: ConvergentMerge<TAction>;
|
|
114
154
|
/** Called once per refusal of a SEALED segment discovered by a replay (see
|
|
115
155
|
* {@link Collection.replayActions}): the segment's entry id and the handler's refusal. Called
|
|
116
156
|
* synchronously from inside the replay, under the collection latch, so it MUST NOT call a
|
|
@@ -267,7 +307,7 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
267
307
|
* ({@link InFlightCycle}) — read by {@link send} and by the re-send {@link completeOwnEntry} makes
|
|
268
308
|
* to finish a torn attempt, so neither needs it threaded through. Set by
|
|
269
309
|
* {@link beginInFlightAction} and cleared by its disposer. */
|
|
270
|
-
private inFlightCycle: InFlightCycle
|
|
310
|
+
private inFlightCycle: InFlightCycle | undefined;
|
|
271
311
|
|
|
272
312
|
/** The head commit running on this instance ({@link openHeadCommit}), for the whole cycle — set and
|
|
273
313
|
* cleared beside {@link inFlightActionId}: the sealed segment it is committing, and the hook told
|
|
@@ -308,7 +348,8 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
308
348
|
* {@link updateInternal}, and shared with every read source this handle builds (see
|
|
309
349
|
* {@link BlockFloors}). */
|
|
310
350
|
private readonly floors: BlockFloors,
|
|
311
|
-
|
|
351
|
+
/** See {@link CollectionInitOptions.merge}. */
|
|
352
|
+
private readonly merge?: ConvergentMerge<TAction>,
|
|
312
353
|
/** See {@link CollectionInitOptions.onSealedRefused}. */
|
|
313
354
|
private readonly onSealedRefused?: (entryId: EntryId, error: ActionRefusedError) => void,
|
|
314
355
|
/** See {@link CollectionInitOptions.onViewChanged}. */
|
|
@@ -362,8 +403,8 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
362
403
|
// that ignores the undefined cannot later sync a phantom collection into existence.
|
|
363
404
|
return undefined;
|
|
364
405
|
}
|
|
365
|
-
await Collection.attachToLog<TAction>(source, sourceCache, tracker, floors, id, instanceTag, ends);
|
|
366
|
-
const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.
|
|
406
|
+
await Collection.attachToLog<TAction>(source, sourceCache, tracker, floors, id, instanceTag, ends, clockOf(transactor));
|
|
407
|
+
const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.merge, init.onSealedRefused, init.onViewChanged, instanceTag);
|
|
367
408
|
collection.logTailId = ends.header.tailId;
|
|
368
409
|
return collection;
|
|
369
410
|
}
|
|
@@ -381,7 +422,7 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
381
422
|
|
|
382
423
|
let inventedBaseline: Transforms | undefined;
|
|
383
424
|
if (ends) { // Collection already exists
|
|
384
|
-
await Collection.attachToLog<TAction>(source, sourceCache, tracker, floors, id, instanceTag, ends);
|
|
425
|
+
await Collection.attachToLog<TAction>(source, sourceCache, tracker, floors, id, instanceTag, ends, clockOf(transactor));
|
|
385
426
|
} else { // Collection does not exist
|
|
386
427
|
log('collection:invented id=%s — no committed header found; staging a fresh empty collection', id);
|
|
387
428
|
const headerBlock = init.createHeaderBlock(id, tracker);
|
|
@@ -394,7 +435,7 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
394
435
|
inventedBaseline = copyTransforms(tracker.transforms);
|
|
395
436
|
}
|
|
396
437
|
|
|
397
|
-
const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.
|
|
438
|
+
const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.merge, init.onSealedRefused, init.onViewChanged, instanceTag);
|
|
398
439
|
collection.logTailId = ends?.header.tailId;
|
|
399
440
|
collection.inventedBaseline = inventedBaseline;
|
|
400
441
|
return collection;
|
|
@@ -530,11 +571,14 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
530
571
|
* diagnostic emitted here carries the same instance name as every post-construction one. */
|
|
531
572
|
instanceTag: string,
|
|
532
573
|
ends: LogEnds,
|
|
574
|
+
/** The clock the handle's writes will mint from, which observes the tail it read. */
|
|
575
|
+
clock: HlcClock,
|
|
533
576
|
): Promise<void> {
|
|
534
577
|
// Bootstrap ActionContext from the committed tail before walking the chain.
|
|
535
578
|
// This allows the transactor to serve pending non-tail blocks during Log.open.
|
|
536
579
|
Collection.bootstrapContext(source, ends.tail);
|
|
537
580
|
Collection.floorTailEntries(floors, ends);
|
|
581
|
+
Collection.observeTailEntries(clock, ends);
|
|
538
582
|
// The walk starts from the header and the tail, which the probe just read: keep them, so the
|
|
539
583
|
// walk reads neither again. Its first read of each through the cache then records the read
|
|
540
584
|
// dependency the probe's own read of the header used to.
|
|
@@ -575,6 +619,22 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
575
619
|
}
|
|
576
620
|
}
|
|
577
621
|
|
|
622
|
+
/** Have `clock` observe the highest HLC among the opened log's tail block entries, which the open
|
|
623
|
+
* has read but does not walk — the open's half of what a refresh's walk feeds the clock
|
|
624
|
+
* ({@link forgetAndAdopt}), so a write through this handle never mints below a write it has seen.
|
|
625
|
+
* Only the tail block, which the open read anyway; an older log block would cost a read for entries
|
|
626
|
+
* committed earlier. Their HLCs are usually lower, but not always — an offline entry keeps the HLC
|
|
627
|
+
* minted at enqueue and a retry its first attempt's (the `NOTE:` at `WriteIdentity.hlc`) — so
|
|
628
|
+
* a write may mint below an entry in an older block, one this handle never read. */
|
|
629
|
+
private static observeTailEntries(clock: HlcClock, ends: LogEnds): void {
|
|
630
|
+
const tail = ends.tail?.block as LogBlock<unknown> | undefined;
|
|
631
|
+
let highWater: Hlc | undefined;
|
|
632
|
+
for (const entry of tail?.entries ?? []) {
|
|
633
|
+
highWater = maxHlc(highWater, hlcOf(entry));
|
|
634
|
+
}
|
|
635
|
+
if (highWater !== undefined) clock.observe(highWater);
|
|
636
|
+
}
|
|
637
|
+
|
|
578
638
|
/** Adopt a freshly-read action context WITHOUT ever lowering the revision already held.
|
|
579
639
|
*
|
|
580
640
|
* The revision a collection last committed at is knowledge it earned; a read that found
|
|
@@ -601,23 +661,20 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
601
661
|
* tag, two handles' lines interleave into what reads like one handle contradicting itself.
|
|
602
662
|
*
|
|
603
663
|
* Logs, does not throw — same reasoning as {@link reportShortfall}: `update()` runs
|
|
604
|
-
* blanket-style over every registered collection between commit retries
|
|
605
|
-
*
|
|
606
|
-
*
|
|
607
|
-
*
|
|
608
|
-
*
|
|
609
|
-
*
|
|
610
|
-
*
|
|
611
|
-
*
|
|
612
|
-
*
|
|
613
|
-
*
|
|
614
|
-
*
|
|
615
|
-
*
|
|
616
|
-
*
|
|
617
|
-
*
|
|
618
|
-
* — that is a behaviour change, and this seam deliberately makes none.
|
|
619
|
-
*
|
|
620
|
-
* The comparison is {@link earliestFork}, not a single lookup at the current revision: the
|
|
664
|
+
* blanket-style over every registered collection between commit retries. Whether the read is
|
|
665
|
+
* adopted, and whether it is another lineage, is {@link judgeAdoption}'s call, made before this
|
|
666
|
+
* runs so a refresh can act on it first: a refresh that ADOPTS another lineage drops its whole
|
|
667
|
+
* read cache and its floors and re-stages every staged action ({@link forgetAndAdopt},
|
|
668
|
+
* {@link mustReplay}), since everything it cached and computed was computed against a history the
|
|
669
|
+
* network does not hold; an open has no cache to drop and nothing staged. The line is therefore a
|
|
670
|
+
* PER-DISCOVERY report: adopting `next` overwrites the held lineage marker with the log's, the
|
|
671
|
+
* drop leaves the handle consistent with the log, and the next refresh compares log to log and
|
|
672
|
+
* has nothing to report. A REFUSED read leaves the held marker in place, so a fork sealed by a
|
|
673
|
+
* `collection:context-not-lowered` refusal is reported on every refresh, beside that line, with
|
|
674
|
+
* nothing dropped — bringing such a handle onto the network's lineage is reconciliation, backlog
|
|
675
|
+
* `feat-replay-mode-collections-merge-divergent-histories`.
|
|
676
|
+
*
|
|
677
|
+
* The comparison printed is {@link earliestFork}, not a single lookup at the current revision: the
|
|
621
678
|
* two `committed` lists overlap across several revisions, and the LOWEST one they disagree at
|
|
622
679
|
* is where the lineages actually parted — a fork below the current revision was previously
|
|
623
680
|
* silent. `forkRev=` names it, `heldAction=`/`readAction=` are the two ids AT it, and
|
|
@@ -634,19 +691,23 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
634
691
|
* the NOTE in {@link bootstrapContext}), which is exactly the case {@link earliestFork} has no
|
|
635
692
|
* shared revision to report on.
|
|
636
693
|
*
|
|
637
|
-
*
|
|
638
|
-
*
|
|
639
|
-
*
|
|
694
|
+
* The two printed comparisons are gated on `log.enabled`: they buy nothing when the line has no
|
|
695
|
+
* sink. Nothing the handle DOES is: the adoption and the lineage verdict behind it
|
|
696
|
+
* ({@link judgeAdoption}) run whatever the logging.
|
|
640
697
|
* Silence proves nothing either way, because a revision is only comparable when BOTH sides
|
|
641
698
|
* name an action for it: an invented collection has no context at all, a revision slot the log
|
|
642
699
|
* gave to a checkpoint or invalidation entry names none, and a revision older than the read
|
|
643
|
-
* log's most recent checkpoint has already fallen off the read side's list.
|
|
700
|
+
* log's most recent checkpoint has already fallen off the read side's list.
|
|
701
|
+
*
|
|
702
|
+
* @param adoption what adopting `next` does, as {@link judgeAdoption} answers it for the context
|
|
703
|
+
* `source` holds now — passed in by a caller that had to act on it before calling. */
|
|
644
704
|
private static advanceContext(
|
|
645
705
|
source: TransactorSource<IBlock>,
|
|
646
706
|
id: CollectionId,
|
|
647
707
|
instanceTag: string,
|
|
648
708
|
site: DivergenceSite,
|
|
649
709
|
next: ActionContext | undefined,
|
|
710
|
+
adoption: Adoption = Collection.judgeAdoption(source.actionContext, next),
|
|
650
711
|
): void {
|
|
651
712
|
const current = source.actionContext;
|
|
652
713
|
if (next === undefined) {
|
|
@@ -659,9 +720,9 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
659
720
|
id, instanceTag, site, fork.rev, fork.heldAction, fork.readAction, current.rev, next.rev);
|
|
660
721
|
}
|
|
661
722
|
}
|
|
662
|
-
if (
|
|
723
|
+
if (adoption === 'refuse') {
|
|
663
724
|
// The refusal itself is unconditional; only the id lookups that explain it are gated.
|
|
664
|
-
if (log.enabled) {
|
|
725
|
+
if (current !== undefined && log.enabled) {
|
|
665
726
|
log('collection:context-not-lowered id=%s tag=%s site=%s heldRev=%d readRev=%d heldAction=%s readAction=%s',
|
|
666
727
|
id, instanceTag, site, current.rev, next.rev,
|
|
667
728
|
actionIdAt(current, next.rev) ?? 'none', actionIdAt(next, next.rev) ?? 'none');
|
|
@@ -671,6 +732,39 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
671
732
|
source.actionContext = next;
|
|
672
733
|
}
|
|
673
734
|
|
|
735
|
+
/** Whether a read context `next` is adopted over the `held` one, and whether it is another
|
|
736
|
+
* lineage ({@link Adoption}). Runs whatever the logging, because the answer is behaviour.
|
|
737
|
+
*
|
|
738
|
+
* Another lineage means the two name different actions at the HELD revision. One comparison is
|
|
739
|
+
* enough because an action id is unique per commit: two lineages that parted at or below the held
|
|
740
|
+
* revision name different actions at every revision both have reached since, the held one
|
|
741
|
+
* included. The exception, one action landing on both sides (a writer's torn retry), is the same
|
|
742
|
+
* lineage at that revision, which is the right answer. A side naming no action there is missing
|
|
743
|
+
* evidence, not disagreement, as in {@link earliestFork} — the held revision's slot went to an
|
|
744
|
+
* invalidation or checkpoint entry, or it predates the read side's most recent checkpoint — so a
|
|
745
|
+
* fork visible only below such a slot is not acted on (the line may still report it). A refused
|
|
746
|
+
* read names no action at the held revision, being below it, so `adopt-divergent` never comes
|
|
747
|
+
* with a refusal.
|
|
748
|
+
*
|
|
749
|
+
* NOTE: two {@link actionIdAt} scans per refresh that walks the log, never per read. Each searches
|
|
750
|
+
* from the end: the held side's entry is normally its last, and the read side's is as far back as
|
|
751
|
+
* the entries the walk found. Both lists truncate only at a checkpoint, which nothing writes yet
|
|
752
|
+
* (tickets/backlog/debt-the-collection-log-never-writes-a-checkpoint); if they grow long enough
|
|
753
|
+
* for that to show, index them by revision. */
|
|
754
|
+
private static judgeAdoption(held: ActionContext | undefined, next: ActionContext | undefined): Adoption {
|
|
755
|
+
if (next === undefined || (held !== undefined && next.rev < held.rev)) {
|
|
756
|
+
return 'refuse';
|
|
757
|
+
}
|
|
758
|
+
if (held === undefined) {
|
|
759
|
+
return 'adopt';
|
|
760
|
+
}
|
|
761
|
+
const heldAction = actionIdAt(held, held.rev);
|
|
762
|
+
const readAction = actionIdAt(next, held.rev);
|
|
763
|
+
return heldAction !== undefined && readAction !== undefined && heldAction !== readAction
|
|
764
|
+
? 'adopt-divergent'
|
|
765
|
+
: 'adopt';
|
|
766
|
+
}
|
|
767
|
+
|
|
674
768
|
/** The EARLIEST revision the two contexts provably disagree about: the lowest revision both
|
|
675
769
|
* `committed` lists name an action for, where the two ids differ.
|
|
676
770
|
*
|
|
@@ -826,10 +920,8 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
826
920
|
* ask for another (see {@link completeOwnEntry}).
|
|
827
921
|
*
|
|
828
922
|
* `tailFloor` is optional: a revision a responder confirmed is taken, when the caller has one (see
|
|
829
|
-
* {@link updateInternal}). `TransactionCoordinator.commit`
|
|
830
|
-
*
|
|
831
|
-
* debt-multi-collection-retry-cannot-see-the-taken-revision) — and this is the parameter it will
|
|
832
|
-
* pass it through. */
|
|
923
|
+
* {@link updateInternal}). `TransactionCoordinator.commit` passes the highest one its refusals of
|
|
924
|
+
* THIS collection carried (`RetryBudget.tailFloor`), and nothing for a collection none did. */
|
|
833
925
|
async refreshInFlight(report: RefreshReport, lastChance: boolean, tailFloor?: number): Promise<void> {
|
|
834
926
|
const release = await Latches.acquire(this.latchId);
|
|
835
927
|
try {
|
|
@@ -926,10 +1018,19 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
926
1018
|
// pair is not obviously right either: a member re-executing the transaction after a sibling
|
|
927
1019
|
// participant has landed no longer sees the state it was staged against. Tracked as an arm
|
|
928
1020
|
// of tickets/backlog/feat-no-deployment-validates-transactions-at-pend.
|
|
1021
|
+
// NOTE: the re-send carries no pend-level `hlc` either: the retained attempt holds the write's
|
|
1022
|
+
// HLC only inside the log entry in its transforms, and the ActionEntry the refresh hands this
|
|
1023
|
+
// method does not carry it. A member that missed the first pend and stores this re-send
|
|
1024
|
+
// therefore observes the write's HLC when it next reads the entry, not at the pend. Fine while
|
|
1025
|
+
// the HLC is observational; if a feed point at the pend ever becomes load-bearing, retain the
|
|
1026
|
+
// HLC on `InFlightAttempt` beside the transforms and put it on this request. The write's LANE
|
|
1027
|
+
// does ride here, from the in-flight cycle (`InFlightCycle.lane`), which every write path marks
|
|
1028
|
+
// with the lane it minted: the same value the retained entry carries.
|
|
929
1029
|
const result = await this.source.transact(attempt.transforms, entry.actionId, rev, this.id, attempt.tailId, {
|
|
930
1030
|
blockDigests: attempt.blockDigests,
|
|
931
1031
|
baseRevs: attempt.baseRevs,
|
|
932
|
-
|
|
1032
|
+
lane: this.inFlightCycle?.lane,
|
|
1033
|
+
refuseSolo: this.inFlightCycle?.refuseSolo
|
|
933
1034
|
});
|
|
934
1035
|
if (result.success) {
|
|
935
1036
|
return result.durability;
|
|
@@ -1172,8 +1273,11 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1172
1273
|
* replace => new instance.
|
|
1173
1274
|
*
|
|
1174
1275
|
* A SEALED segment's action list is the queue entry's own and is never rewritten (invariant 3
|
|
1175
|
-
* of docs/offline-sync.md §The segment model), so the hook is not offered them.
|
|
1176
|
-
*
|
|
1276
|
+
* of docs/offline-sync.md §The segment model), so the hook is not offered them. The hook is the
|
|
1277
|
+
* convergent lane's rule ({@link ConvergentMerge.filterConflict}): {@link doFilterConflict} offers
|
|
1278
|
+
* it only an action the declaration classifies `convergent`, and keeps a serializable one as-is.
|
|
1279
|
+
* `Tree` declares nothing and `Diary` declares no hook, so nothing observable changes for them
|
|
1280
|
+
* either way.
|
|
1177
1281
|
*
|
|
1178
1282
|
* NOTE: a filterConflict hook that always allocates a fresh (but equal) instance instead of
|
|
1179
1283
|
* returning the same one forces a replay on every update — if that ever shows up as a hot path,
|
|
@@ -1334,13 +1438,13 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1334
1438
|
anyConflicts = true;
|
|
1335
1439
|
}
|
|
1336
1440
|
|
|
1337
|
-
this.forgetAndAdopt(latest, entryRevs, revertedBlockIds, ends);
|
|
1441
|
+
const adoption = this.forgetAndAdopt(latest, entryRevs, revertedBlockIds, ends);
|
|
1338
1442
|
|
|
1339
1443
|
Collection.reportShortfall(this.id, this.instanceTag, tailRev, actionContext?.rev, this.source.actionContext?.rev);
|
|
1340
1444
|
|
|
1341
1445
|
// Re-stage the staged actions against the adopted revision. The affected
|
|
1342
|
-
// blocks were already dropped from sourceCache above (per log entry / per invalidation
|
|
1343
|
-
// so the replay's reads re-materialize from the transactor.
|
|
1446
|
+
// blocks were already dropped from sourceCache above (per log entry / per invalidation, or
|
|
1447
|
+
// all of them on an adopted divergence), so the replay's reads re-materialize from the transactor.
|
|
1344
1448
|
// NOTE: a throw out of replayActions — a refusal of the OPEN segment, or any non-refusal
|
|
1345
1449
|
// error — leaves the tracker holding only the transforms replayed so far while the open
|
|
1346
1450
|
// segment still lists all of its actions; the caller's error handling is expected to
|
|
@@ -1349,7 +1453,7 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1349
1453
|
// collection-half-restaged). A SEALED segment is not left half-replayed: it is staged
|
|
1350
1454
|
// atomically, and a refusal of one is recorded and skipped rather than thrown. If replay ever
|
|
1351
1455
|
// gains a routinely-throwing read path, rebuild into a scratch tracker and swap on success.
|
|
1352
|
-
if (this.mustReplay(anyConflicts, actionContext)) {
|
|
1456
|
+
if (this.mustReplay(anyConflicts, actionContext, adoption)) {
|
|
1353
1457
|
await this.replayActions();
|
|
1354
1458
|
}
|
|
1355
1459
|
}
|
|
@@ -1376,21 +1480,46 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1376
1480
|
* context at all, and a log read that lags what this handle already committed yields an older
|
|
1377
1481
|
* one; neither is grounds for forgetting the revision held. It also has to precede
|
|
1378
1482
|
* {@link replayActions}, which re-reads blocks through `this.source` at whatever revision the
|
|
1379
|
-
* context names — replaying first would refill the cache at the revision being left.
|
|
1483
|
+
* context names — replaying first would refill the cache at the revision being left.
|
|
1484
|
+
*
|
|
1485
|
+
* **An adopted divergence forgets everything first** ({@link judgeAdoption}): the whole read cache
|
|
1486
|
+
* and every floor, ahead of the per-entry loop so this walk's floors — the new lineage's — are the
|
|
1487
|
+
* ones left standing. Not just the blocks the walked entries name: the walk covers only entries
|
|
1488
|
+
* above the held revision, so the blocks the old lineage built at and below it are named by
|
|
1489
|
+
* entries this handle will never walk, the cache has no expiry, and an idle refresh stops after
|
|
1490
|
+
* one request while the log does not move — nothing would ever clear them. And not the floors
|
|
1491
|
+
* kept: a floor raised under the old lineage is no bound on the new one, where the block may
|
|
1492
|
+
* legitimately sit below it, and would make every read of it a below-floor answer for the life of
|
|
1493
|
+
* the handle. The header and tail {@link keepLogEnds} offers came from the new lineage and may be
|
|
1494
|
+
* kept. The staged actions were computed against the old content, so the verdict is returned for
|
|
1495
|
+
* {@link mustReplay}.
|
|
1496
|
+
*
|
|
1497
|
+
* The handle's clock observes the highest HLC the walk read (`GetFromResult.hlcHighWater`), so a
|
|
1498
|
+
* write through it never mints below an entry it has seen — whatever the verdict, since a clock
|
|
1499
|
+
* only rises and the entries were read either way.
|
|
1500
|
+
*
|
|
1501
|
+
* @returns what the adoption did, as {@link judgeAdoption} answered it before anything changed. */
|
|
1380
1502
|
private forgetAndAdopt(
|
|
1381
1503
|
latest: GetFromResult<Action<TAction>> | undefined,
|
|
1382
1504
|
entryRevs: ReadonlyMap<ActionId, number>,
|
|
1383
1505
|
revertedBlockIds: BlockId[],
|
|
1384
1506
|
ends: LogEnds,
|
|
1385
|
-
):
|
|
1507
|
+
): Adoption {
|
|
1508
|
+
const adoption = Collection.judgeAdoption(this.source.actionContext, latest?.context);
|
|
1509
|
+
if (latest?.hlcHighWater !== undefined) clockOf(this.transactor).observe(latest.hlcHighWater);
|
|
1386
1510
|
this.viewChanged();
|
|
1511
|
+
if (adoption === 'adopt-divergent') {
|
|
1512
|
+
this.sourceCache.clear();
|
|
1513
|
+
this.floors.clear();
|
|
1514
|
+
}
|
|
1387
1515
|
for (const entry of latest?.entries ?? []) {
|
|
1388
1516
|
this.sourceCache.clear(entry.blockIds);
|
|
1389
1517
|
this.raiseFloors(entry, entryRevs.get(entry.actionId));
|
|
1390
1518
|
}
|
|
1391
1519
|
this.sourceCache.clear(revertedBlockIds);
|
|
1392
|
-
Collection.advanceContext(this.source, this.id, this.instanceTag, 'refresh', latest?.context);
|
|
1520
|
+
Collection.advanceContext(this.source, this.id, this.instanceTag, 'refresh', latest?.context, adoption);
|
|
1393
1521
|
Collection.keepLogEnds(this.sourceCache, this.floors, this.source.actionContext, ends);
|
|
1522
|
+
return adoption;
|
|
1394
1523
|
}
|
|
1395
1524
|
|
|
1396
1525
|
/** Put the header and log tail block {@link readLogEnds} already fetched into a handle's own
|
|
@@ -1537,7 +1666,8 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1537
1666
|
* claim (`collection:context-short-of-tail`, or `collection:context-not-lowered` for a handle
|
|
1538
1667
|
* pinned by an over-claiming tail), or an invalidation or checkpoint took the newest slot;
|
|
1539
1668
|
* - any action entry in the tail block naming a different action than `held` names at the same
|
|
1540
|
-
* revision (`collection:lineage-divergence`, and the walk's adoption of the log's list
|
|
1669
|
+
* revision (`collection:lineage-divergence`, and the walk's adoption of the log's list, which
|
|
1670
|
+
* drops the read cache when it adopts another lineage — see {@link forgetAndAdopt}).
|
|
1541
1671
|
*
|
|
1542
1672
|
* NOTE: the lineage comparison sees only the entries the tail block holds. A fork below them, on
|
|
1543
1673
|
* a log that has not moved, is not looked at again until a refresh finds something new — that
|
|
@@ -1601,8 +1731,10 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1601
1731
|
* (`index-backfill-cost.spec.ts`, `cold-apply-cost.spec.ts`), because the replay's reads are
|
|
1602
1732
|
* served from `sourceCache`. If a long transaction's reads ever show up as slow, narrow the
|
|
1603
1733
|
* replay to the actions whose reads the adopted entries actually invalidated — NOT back to
|
|
1604
|
-
* conflicts alone, which is the defect above.
|
|
1605
|
-
|
|
1734
|
+
* conflicts alone, which is the defect above.
|
|
1735
|
+
*
|
|
1736
|
+
* @param adoption what the refresh's adoption did ({@link forgetAndAdopt}). */
|
|
1737
|
+
private mustReplay(anyConflicts: boolean, priorContext: ActionContext | undefined, adoption: Adoption): boolean {
|
|
1606
1738
|
if (anyConflicts) {
|
|
1607
1739
|
return true;
|
|
1608
1740
|
}
|
|
@@ -1611,6 +1743,14 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
1611
1743
|
if (adoptedRev !== undefined && adoptedRev !== priorContext?.rev && replayable > 0) {
|
|
1612
1744
|
return true;
|
|
1613
1745
|
}
|
|
1746
|
+
// Fourth reason, ahead of the third: the refresh adopted another lineage, so every staged
|
|
1747
|
+
// action was computed against content the network does not hold. A fork at the SAME revision
|
|
1748
|
+
// advances nothing, so the reason above does not see it. The whole-cache clear behind it
|
|
1749
|
+
// would usually make every pinned base read as moved too, but this keeps the rule readable,
|
|
1750
|
+
// covers staged actions that pinned nothing, and spares a `restage-moved-base` line per pin.
|
|
1751
|
+
if (adoption === 'adopt-divergent' && replayable > 0) {
|
|
1752
|
+
return true;
|
|
1753
|
+
}
|
|
1614
1754
|
// Third reason: a staged block's base has MOVED — the read cache no longer describes it at
|
|
1615
1755
|
// the revision its operations were computed against (see `Tracker.movedBases`). A refresh
|
|
1616
1756
|
// that adopted nothing and found no conflict can still be standing over such a block: a
|
|
@@ -2212,7 +2352,7 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
2212
2352
|
*
|
|
2213
2353
|
* `cycle` is what every send of the cycle carries ({@link InFlightCycle}); a re-mark replaces it,
|
|
2214
2354
|
* which is harmless because every caller re-marks with what it marked. */
|
|
2215
|
-
beginInFlightAction(actionId: ActionId, cycle: InFlightCycle
|
|
2355
|
+
beginInFlightAction(actionId: ActionId, cycle: InFlightCycle): () => void {
|
|
2216
2356
|
if (this.inFlightActionId !== actionId) {
|
|
2217
2357
|
// A different action's failed attempt cannot finish this one. Re-marking the SAME id (a
|
|
2218
2358
|
// coordinator re-marks on every attempt) keeps what the previous attempt retained — that
|
|
@@ -2228,7 +2368,7 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
2228
2368
|
this.inFlightActionId = undefined;
|
|
2229
2369
|
this.inFlightAttempt = undefined;
|
|
2230
2370
|
this.mintedLogBlockIds = undefined;
|
|
2231
|
-
this.inFlightCycle =
|
|
2371
|
+
this.inFlightCycle = undefined;
|
|
2232
2372
|
}
|
|
2233
2373
|
};
|
|
2234
2374
|
}
|
|
@@ -2335,13 +2475,22 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
2335
2475
|
this.assertNoSealedSegments();
|
|
2336
2476
|
const identity: WriteIdentity = {
|
|
2337
2477
|
actionId: uint8ArrayToString(randomBytes(16), 'base64url'),
|
|
2338
|
-
// One timestamp for the WRITE, minted here beside the action id and for
|
|
2339
|
-
// attempt that
|
|
2340
|
-
// attempt it repeats may already have stored under this `(action id, revision)`.
|
|
2478
|
+
// One timestamp, one HLC and one lane for the WRITE, minted here beside the action id and for
|
|
2479
|
+
// the same reason: an attempt that took its own would make the retry's log block differ from
|
|
2480
|
+
// the one the attempt it repeats may already have stored under this `(action id, revision)`.
|
|
2341
2481
|
timestamp: Date.now(),
|
|
2482
|
+
hlc: clockOf(this.transactor).now(),
|
|
2483
|
+
// The caller's classification wins over the declaration, and the declaration over nothing
|
|
2484
|
+
// (`SyncOptions.lane`): the caller knows more about the write than the collection does.
|
|
2485
|
+
// NOTE: judged over the open segment as staged NOW and fixed for the write; a
|
|
2486
|
+
// `merge.filterConflict` hook that answered a replacement of a different lane during an
|
|
2487
|
+
// inter-attempt refresh would leave the entry claiming the lane of the action it replaced. No
|
|
2488
|
+
// hook in this repository replaces an action; if one ever does, the member-side lane check is
|
|
2489
|
+
// what catches the mismatch.
|
|
2490
|
+
lane: options?.lane ?? this.laneOf(this.segments.open),
|
|
2342
2491
|
};
|
|
2343
2492
|
|
|
2344
|
-
const endInFlight = this.beginInFlightAction(identity.actionId, { refuseSolo: options?.refuseSoloCommit });
|
|
2493
|
+
const endInFlight = this.beginInFlightAction(identity.actionId, { lane: identity.lane, refuseSolo: options?.refuseSoloCommit });
|
|
2345
2494
|
try {
|
|
2346
2495
|
return await this.syncAttempts(identity, options);
|
|
2347
2496
|
} finally {
|
|
@@ -2417,9 +2566,11 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
2417
2566
|
private send(staged: StagedAttempt, identity: WriteIdentity, priority: number): Promise<CommitResult> {
|
|
2418
2567
|
return this.source.transact(staged.tracker.transforms, identity.actionId, staged.rev, this.id, staged.tailId, {
|
|
2419
2568
|
priority,
|
|
2569
|
+
hlc: identity.hlc,
|
|
2570
|
+
lane: identity.lane,
|
|
2420
2571
|
blockDigests: staged.blockDigests,
|
|
2421
2572
|
baseRevs: staged.baseRevs,
|
|
2422
|
-
refuseSolo: this.inFlightCycle
|
|
2573
|
+
refuseSolo: this.inFlightCycle?.refuseSolo
|
|
2423
2574
|
});
|
|
2424
2575
|
}
|
|
2425
2576
|
|
|
@@ -2463,7 +2614,7 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
2463
2614
|
* when a refresh or the head tracker's staging refused it during the cycle; whatever
|
|
2464
2615
|
* `options.recordAttempt` throws, before anything is sent; otherwise what {@link sync} throws. */
|
|
2465
2616
|
async commitHead(entryId: EntryId, options: HeadCommitOptions): Promise<WriteDurability | undefined> {
|
|
2466
|
-
const handle = await this.openHeadCommit(entryId, { actionId: options.actionId, timestamp: options.timestamp }, {
|
|
2617
|
+
const handle = await this.openHeadCommit(entryId, { actionId: options.actionId, timestamp: options.timestamp, hlc: options.hlc, lane: options.lane }, {
|
|
2467
2618
|
refuseSolo: options.refuseSoloCommit,
|
|
2468
2619
|
...(options.resume === undefined ? {} : { resume: options.resume }),
|
|
2469
2620
|
...(options.onCommittedHead === undefined ? {} : { onCommittedHead: options.onCommittedHead }),
|
|
@@ -2486,9 +2637,9 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
2486
2637
|
* segment; and seeds the retained attempt with `options.resume` when one is given, so that the
|
|
2487
2638
|
* opening refresh can finish an earlier cycle's torn attempt from it ({@link completeOwnEntry}) —
|
|
2488
2639
|
* and `stage()` re-sends it verbatim while the next attempt would request its revision
|
|
2489
|
-
* ({@link resumedAttempt}). The rest of `options` is the cycle's ({@link InFlightCycle}
|
|
2490
|
-
* with the in-flight mark, so the handle's `send()` and a
|
|
2491
|
-
* carry it.
|
|
2640
|
+
* ({@link resumedAttempt}). The rest of `options` is the cycle's ({@link InFlightCycle}, its lane
|
|
2641
|
+
* taken from `identity`), recorded with the in-flight mark, so the handle's `send()` and a
|
|
2642
|
+
* refresh's re-send of a torn attempt both carry it.
|
|
2492
2643
|
*
|
|
2493
2644
|
* **The target.** The live tracker holds every sealed segment and the open one, cumulatively, so
|
|
2494
2645
|
* an attempt cannot run on a copy of it the way a sync's does. It runs on a HEAD TRACKER instead
|
|
@@ -2538,7 +2689,7 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
2538
2689
|
release();
|
|
2539
2690
|
throw err;
|
|
2540
2691
|
}
|
|
2541
|
-
const endInFlight = this.beginInFlightAction(identity.actionId, cycle);
|
|
2692
|
+
const endInFlight = this.beginInFlightAction(identity.actionId, { ...cycle, lane: identity.lane });
|
|
2542
2693
|
this.headCommit = { entryId, ...(onCommittedHead === undefined ? {} : { onCommitted: onCommittedHead }) };
|
|
2543
2694
|
if (resume !== undefined) {
|
|
2544
2695
|
this.retainInFlightAttempt(resume);
|
|
@@ -2686,21 +2837,27 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
2686
2837
|
/** The tracker a head attempt is built from (see {@link commitHead}): `current`, while it was
|
|
2687
2838
|
* built for the revision the next attempt requests and no base under it has moved; otherwise a
|
|
2688
2839
|
* fresh one ({@link buildHeadTracker}). A revision that moved is a write that is genuinely
|
|
2689
|
-
* different
|
|
2690
|
-
* {@link
|
|
2840
|
+
* different, and so is one whose held lineage moved at the same revision: a refresh between
|
|
2841
|
+
* attempts that adopted another lineage ({@link judgeAdoption}) dropped the read cache the
|
|
2842
|
+
* tracker was staged over, and an action that inserted a block computed from that content pinned
|
|
2843
|
+
* no base the re-judge below would see as moved. A base that moved at the same revision is
|
|
2844
|
+
* re-judged exactly as {@link restageIfBasesMoved} re-judges the live queue before an attempt,
|
|
2845
|
+
* and rebuilds.
|
|
2691
2846
|
* NOTE: that rebuild is the same exception to the byte-identical retry that {@link syncAttempts}
|
|
2692
2847
|
* records at its `restageIfBasesMoved` call — fresh ids for the blocks the actions insert under
|
|
2693
2848
|
* an unchanged `(action id, revision)` — reached the same narrow way and refused by storage's
|
|
2694
2849
|
* base guard on the same machines; the same answer applies if it is ever seen. */
|
|
2695
2850
|
private async headTrackerFor(segment: SealedSegment<TAction>, current: HeadTracker | undefined): Promise<HeadTracker> {
|
|
2696
2851
|
const rev = this.getNextRev();
|
|
2697
|
-
|
|
2852
|
+
const held = this.source.actionContext;
|
|
2853
|
+
const lineage = held === undefined ? undefined : actionIdAt(held, held.rev);
|
|
2854
|
+
if (current?.rev === rev && current.lineage === lineage) {
|
|
2698
2855
|
await this.rereadUnretainedBases(current.tracker);
|
|
2699
2856
|
if (this.logMovedBases(current.tracker.movedBases()) === 0) {
|
|
2700
2857
|
return current;
|
|
2701
2858
|
}
|
|
2702
2859
|
}
|
|
2703
|
-
return { rev, tracker: await this.buildHeadTracker(segment) };
|
|
2860
|
+
return { rev, lineage, tracker: await this.buildHeadTracker(segment) };
|
|
2704
2861
|
}
|
|
2705
2862
|
|
|
2706
2863
|
/** A tracker over this instance's read cache, with pins of its own, holding `segment`'s actions
|
|
@@ -2777,10 +2934,10 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
2777
2934
|
* refresh would have done. */
|
|
2778
2935
|
private async unstage(actions: Action<TAction>[], stagedBefore: Transforms, revBefore: number | undefined): Promise<void> {
|
|
2779
2936
|
// NOTE: matched by identity, which is what `filterAgainstEntry` promises for a kept action.
|
|
2780
|
-
// A `filterConflict` hook that answers a REPLACEMENT instance for one of these actions
|
|
2781
|
-
// leave the replacement staged here. No collection installs such a hook today (`Tree`
|
|
2782
|
-
// `Diary`
|
|
2783
|
-
// match on that instead.
|
|
2937
|
+
// A `merge.filterConflict` hook that answers a REPLACEMENT instance for one of these actions
|
|
2938
|
+
// would leave the replacement staged here. No collection installs such a hook today (`Tree`
|
|
2939
|
+
// declares no merge and `Diary` declares no hook); if one ever does, carry a per-call token on
|
|
2940
|
+
// the staged actions and match on that instead.
|
|
2784
2941
|
// The actions were staged into the OPEN segment (actAndSync refuses over sealed segments).
|
|
2785
2942
|
this.segments.open = this.segments.open.filter(staged => !actions.includes(staged));
|
|
2786
2943
|
if (this.source.actionContext?.rev === revBefore) {
|
|
@@ -2883,14 +3040,31 @@ export class Collection<TAction> implements ICollection<TAction> {
|
|
|
2883
3040
|
this.source.clearReadDependencies();
|
|
2884
3041
|
}
|
|
2885
3042
|
|
|
3043
|
+
/** The lane of a write made of `actions` under this collection's merge declaration
|
|
3044
|
+
* ({@link CollectionInitOptions.merge}): the stricter lane over the declaration's answer for each
|
|
3045
|
+
* (`stricterLane`), `serializable` without a declaration and for an empty list. Pure. The source
|
|
3046
|
+
* of a sync's lane when its caller gave none (`SyncOptions.lane`), and of a queued entry's
|
|
3047
|
+
* (`OfflineQueue.enqueue`). */
|
|
3048
|
+
laneOf(actions: readonly Action<TAction>[]): Lane {
|
|
3049
|
+
const merge = this.merge;
|
|
3050
|
+
return merge === undefined ? 'serializable' : stricterLane(actions.map(action => merge.laneOf(action)));
|
|
3051
|
+
}
|
|
3052
|
+
|
|
2886
3053
|
/** Called for each local action that may be in conflict with a remote action (always called under latch).
|
|
3054
|
+
* The merge declaration's hook ({@link ConvergentMerge.filterConflict}) decides only for an action the
|
|
3055
|
+
* declaration classifies `convergent`; a serializable action is kept as-is, since its guards decide
|
|
3056
|
+
* on replay, and so is every action of a collection with no declaration or no hook.
|
|
2887
3057
|
* @param action - The local action to check
|
|
2888
3058
|
* @param potential - The remote actions that are potentially in conflict
|
|
2889
3059
|
* @returns The effective action to keep: the original (unchanged), a replacement
|
|
2890
3060
|
* instance (applied instead of the original), or undefined to discard it.
|
|
2891
3061
|
*/
|
|
2892
3062
|
protected doFilterConflict(action: Action<TAction>, potential: Action<TAction>[]): Action<TAction> | undefined {
|
|
2893
|
-
|
|
3063
|
+
const merge = this.merge;
|
|
3064
|
+
if (merge?.filterConflict === undefined || merge.laneOf(action) !== 'convergent') {
|
|
3065
|
+
return action;
|
|
3066
|
+
}
|
|
3067
|
+
return merge.filterConflict(action, potential);
|
|
2894
3068
|
}
|
|
2895
3069
|
|
|
2896
3070
|
/** The two blocks every refresh starts from — the collection header and the log tail block it
|