@optimystic/db-core 1.21.0 → 1.23.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/btree/btree.d.ts +36 -4
- package/dist/src/btree/btree.d.ts.map +1 -1
- package/dist/src/btree/btree.js +86 -18
- package/dist/src/btree/btree.js.map +1 -1
- 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 +177 -51
- package/dist/src/collection/collection.d.ts.map +1 -1
- package/dist/src/collection/collection.js +265 -81
- package/dist/src/collection/collection.js.map +1 -1
- package/dist/src/collection/struct.d.ts +44 -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 +18 -10
- package/dist/src/collections/tree/tree.d.ts.map +1 -1
- package/dist/src/collections/tree/tree.js +17 -9
- 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 +50 -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 +12 -3
- 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 +16 -5
- package/dist/src/transaction/coordinator.d.ts.map +1 -1
- package/dist/src/transaction/coordinator.js +203 -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 +9 -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/btree/btree.ts +92 -18
- package/src/collection/action.ts +13 -5
- package/src/collection/collection.ts +3272 -3039
- package/src/collection/struct.ts +493 -456
- package/src/collection/write-attempts.ts +213 -109
- package/src/collections/diary/diary.ts +5 -1
- package/src/collections/tree/tree.ts +33 -18
- 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 +50 -0
- 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 -1050
- package/src/transaction/actions-engine.ts +3 -0
- package/src/transaction/coordinator.ts +235 -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 +1908 -1896
- package/src/transactor/transactor-source.ts +15 -1
- package/src/transactor/transactor.ts +9 -0
- package/src/transform/cache-source.ts +15 -17
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { Log } from "../log/log.js";
|
|
2
|
+
import { hlcOf } from "../log/struct.js";
|
|
2
3
|
import { Atomic } from "../transform/atomic.js";
|
|
3
4
|
import { Tracker } from "../transform/tracker.js";
|
|
4
5
|
import { CacheSource } from "../transform/cache-source.js";
|
|
@@ -12,6 +13,9 @@ import { actionIdAt, addTallies, ZeroTally } from "./action.js";
|
|
|
12
13
|
import { AttemptCycle, resumedAttempt, retainedAttempt, stageAttempt } from "./write-attempts.js";
|
|
13
14
|
import { driveHeadCommit } from "./head-commit.js";
|
|
14
15
|
import { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
|
|
16
|
+
import { clockOf } from "../hlc/clock.js";
|
|
17
|
+
import { maxHlc } from "../hlc/hlc.js";
|
|
18
|
+
import { stricterLane } from "../lane/lane.js";
|
|
15
19
|
import { randomBytes } from '@noble/hashes/utils.js';
|
|
16
20
|
import { toString as uint8ArrayToString } from 'uint8arrays/to-string';
|
|
17
21
|
import { Latches } from "../utility/latches.js";
|
|
@@ -25,8 +29,9 @@ export class Collection {
|
|
|
25
29
|
sourceCache;
|
|
26
30
|
tracker;
|
|
27
31
|
floors;
|
|
28
|
-
|
|
32
|
+
merge;
|
|
29
33
|
onSealedRefused;
|
|
34
|
+
onViewChanged;
|
|
30
35
|
instanceTag;
|
|
31
36
|
/** The staged actions: sealed segments, one per queued entry, ahead of the open segment the
|
|
32
37
|
* current transaction stages into (see {@link SegmentList}). While nothing is sealed this is
|
|
@@ -106,7 +111,7 @@ export class Collection {
|
|
|
106
111
|
* ({@link InFlightCycle}) — read by {@link send} and by the re-send {@link completeOwnEntry} makes
|
|
107
112
|
* to finish a torn attempt, so neither needs it threaded through. Set by
|
|
108
113
|
* {@link beginInFlightAction} and cleared by its disposer. */
|
|
109
|
-
inFlightCycle
|
|
114
|
+
inFlightCycle;
|
|
110
115
|
/** The head commit running on this instance ({@link openHeadCommit}), for the whole cycle — set and
|
|
111
116
|
* cleared beside {@link inFlightActionId}: the sealed segment it is committing, and the hook told
|
|
112
117
|
* what that segment accepted as already applied when it is dropped as committed
|
|
@@ -138,9 +143,13 @@ export class Collection {
|
|
|
138
143
|
/** What each block named by a walked log entry must be at least as new as — raised by
|
|
139
144
|
* {@link updateInternal}, and shared with every read source this handle builds (see
|
|
140
145
|
* {@link BlockFloors}). */
|
|
141
|
-
floors,
|
|
146
|
+
floors,
|
|
147
|
+
/** See {@link CollectionInitOptions.merge}. */
|
|
148
|
+
merge,
|
|
142
149
|
/** See {@link CollectionInitOptions.onSealedRefused}. */
|
|
143
150
|
onSealedRefused,
|
|
151
|
+
/** See {@link CollectionInitOptions.onViewChanged}. */
|
|
152
|
+
onViewChanged,
|
|
144
153
|
/** Short random tag naming THIS instance (see {@link newInstanceTag}). Open paths generate
|
|
145
154
|
* it BEFORE construction (so pre-construction diagnostics such as attachToLog can carry it);
|
|
146
155
|
* the default covers direct construction in tests. */
|
|
@@ -152,8 +161,9 @@ export class Collection {
|
|
|
152
161
|
this.sourceCache = sourceCache;
|
|
153
162
|
this.tracker = tracker;
|
|
154
163
|
this.floors = floors;
|
|
155
|
-
this.
|
|
164
|
+
this.merge = merge;
|
|
156
165
|
this.onSealedRefused = onSealedRefused;
|
|
166
|
+
this.onViewChanged = onViewChanged;
|
|
157
167
|
this.instanceTag = instanceTag;
|
|
158
168
|
// Instance-scoped, deliberately NOT shared across instances of one collection id. The
|
|
159
169
|
// latch protects per-instance state only — the tracker, the pending queue, and
|
|
@@ -197,8 +207,8 @@ export class Collection {
|
|
|
197
207
|
// that ignores the undefined cannot later sync a phantom collection into existence.
|
|
198
208
|
return undefined;
|
|
199
209
|
}
|
|
200
|
-
await Collection.attachToLog(source, sourceCache, tracker, floors, id, instanceTag, ends);
|
|
201
|
-
const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.
|
|
210
|
+
await Collection.attachToLog(source, sourceCache, tracker, floors, id, instanceTag, ends, clockOf(transactor));
|
|
211
|
+
const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.merge, init.onSealedRefused, init.onViewChanged, instanceTag);
|
|
202
212
|
collection.logTailId = ends.header.tailId;
|
|
203
213
|
return collection;
|
|
204
214
|
}
|
|
@@ -214,7 +224,7 @@ export class Collection {
|
|
|
214
224
|
const { source, sourceCache, tracker, floors, ends } = await Collection.probeHeader(transactor, id, instanceTag);
|
|
215
225
|
let inventedBaseline;
|
|
216
226
|
if (ends) { // Collection already exists
|
|
217
|
-
await Collection.attachToLog(source, sourceCache, tracker, floors, id, instanceTag, ends);
|
|
227
|
+
await Collection.attachToLog(source, sourceCache, tracker, floors, id, instanceTag, ends, clockOf(transactor));
|
|
218
228
|
}
|
|
219
229
|
else { // Collection does not exist
|
|
220
230
|
log('collection:invented id=%s — no committed header found; staging a fresh empty collection', id);
|
|
@@ -227,7 +237,7 @@ export class Collection {
|
|
|
227
237
|
// replay has to put back while this collection has no committed revision.
|
|
228
238
|
inventedBaseline = copyTransforms(tracker.transforms);
|
|
229
239
|
}
|
|
230
|
-
const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.
|
|
240
|
+
const collection = new Collection(id, transactor, init.modules, source, sourceCache, tracker, floors, init.merge, init.onSealedRefused, init.onViewChanged, instanceTag);
|
|
231
241
|
collection.logTailId = ends?.header.tailId;
|
|
232
242
|
collection.inventedBaseline = inventedBaseline;
|
|
233
243
|
return collection;
|
|
@@ -264,10 +274,14 @@ export class Collection {
|
|
|
264
274
|
* coordinator's answer leaves a block out — is not every collection's failure either:
|
|
265
275
|
* {@link readAttributed} then reads each block alone and only the collections whose blocks failed
|
|
266
276
|
* report an error. That fallback costs what reading each collection separately costs, and only
|
|
267
|
-
* when a request fails.
|
|
268
|
-
|
|
277
|
+
* when a request fails.
|
|
278
|
+
*
|
|
279
|
+
* `options.skipWindowConsult` puts {@link BlockGets.skipWindowConsult} on every request this read
|
|
280
|
+
* makes, the per-block fallback included. */
|
|
281
|
+
static async readCommittedTails(transactor, queries, options) {
|
|
282
|
+
const reads = Collection.tailReadFields(options);
|
|
269
283
|
const knownTails = new Map(queries.map(query => [query.id, query.knownTailId]));
|
|
270
|
-
const ends = await Collection.readAttributed(transactor, [...knownTails].flatMap(([id, knownTailId]) => knownTailId === undefined ? [id] : [id, knownTailId]));
|
|
284
|
+
const ends = await Collection.readAttributed(transactor, [...knownTails].flatMap(([id, knownTailId]) => knownTailId === undefined ? [id] : [id, knownTailId]), reads);
|
|
271
285
|
const answers = new Map();
|
|
272
286
|
/** Collections whose header names a tail other than the known one, with the tail it names. */
|
|
273
287
|
const moved = new Map();
|
|
@@ -286,7 +300,7 @@ export class Collection {
|
|
|
286
300
|
}
|
|
287
301
|
}
|
|
288
302
|
if (moved.size > 0) {
|
|
289
|
-
const tails = await Collection.readAttributed(transactor, [...new Set(moved.values())]);
|
|
303
|
+
const tails = await Collection.readAttributed(transactor, [...new Set(moved.values())], reads);
|
|
290
304
|
for (const [id, tailId] of moved) {
|
|
291
305
|
try {
|
|
292
306
|
answers.set(id, { tail: Collection.judgedTail(tailId, tails) });
|
|
@@ -342,11 +356,14 @@ export class Collection {
|
|
|
342
356
|
static async attachToLog(source, sourceCache, tracker, floors, id,
|
|
343
357
|
/** The tag the calling open path minted for the Collection it is ABOUT to construct, so a
|
|
344
358
|
* diagnostic emitted here carries the same instance name as every post-construction one. */
|
|
345
|
-
instanceTag, ends
|
|
359
|
+
instanceTag, ends,
|
|
360
|
+
/** The clock the handle's writes will mint from, which observes the tail it read. */
|
|
361
|
+
clock) {
|
|
346
362
|
// Bootstrap ActionContext from the committed tail before walking the chain.
|
|
347
363
|
// This allows the transactor to serve pending non-tail blocks during Log.open.
|
|
348
364
|
Collection.bootstrapContext(source, ends.tail);
|
|
349
365
|
Collection.floorTailEntries(floors, ends);
|
|
366
|
+
Collection.observeTailEntries(clock, ends);
|
|
350
367
|
// The walk starts from the header and the tail, which the probe just read: keep them, so the
|
|
351
368
|
// walk reads neither again. Its first read of each through the cache then records the read
|
|
352
369
|
// dependency the probe's own read of the header used to.
|
|
@@ -384,6 +401,22 @@ export class Collection {
|
|
|
384
401
|
}
|
|
385
402
|
}
|
|
386
403
|
}
|
|
404
|
+
/** Have `clock` observe the highest HLC among the opened log's tail block entries, which the open
|
|
405
|
+
* has read but does not walk — the open's half of what a refresh's walk feeds the clock
|
|
406
|
+
* ({@link forgetAndAdopt}), so a write through this handle never mints below a write it has seen.
|
|
407
|
+
* Only the tail block, which the open read anyway; an older log block would cost a read for entries
|
|
408
|
+
* committed earlier. Their HLCs are usually lower, but not always — an offline entry keeps the HLC
|
|
409
|
+
* minted at enqueue and a retry its first attempt's (the `NOTE:` at `WriteIdentity.hlc`) — so
|
|
410
|
+
* a write may mint below an entry in an older block, one this handle never read. */
|
|
411
|
+
static observeTailEntries(clock, ends) {
|
|
412
|
+
const tail = ends.tail?.block;
|
|
413
|
+
let highWater;
|
|
414
|
+
for (const entry of tail?.entries ?? []) {
|
|
415
|
+
highWater = maxHlc(highWater, hlcOf(entry));
|
|
416
|
+
}
|
|
417
|
+
if (highWater !== undefined)
|
|
418
|
+
clock.observe(highWater);
|
|
419
|
+
}
|
|
387
420
|
/** Adopt a freshly-read action context WITHOUT ever lowering the revision already held.
|
|
388
421
|
*
|
|
389
422
|
* The revision a collection last committed at is knowledge it earned; a read that found
|
|
@@ -410,23 +443,20 @@ export class Collection {
|
|
|
410
443
|
* tag, two handles' lines interleave into what reads like one handle contradicting itself.
|
|
411
444
|
*
|
|
412
445
|
* Logs, does not throw — same reasoning as {@link reportShortfall}: `update()` runs
|
|
413
|
-
* blanket-style over every registered collection between commit retries
|
|
414
|
-
*
|
|
415
|
-
*
|
|
416
|
-
*
|
|
417
|
-
*
|
|
418
|
-
*
|
|
419
|
-
*
|
|
420
|
-
*
|
|
421
|
-
*
|
|
422
|
-
*
|
|
423
|
-
*
|
|
424
|
-
*
|
|
425
|
-
*
|
|
426
|
-
*
|
|
427
|
-
* — that is a behaviour change, and this seam deliberately makes none.
|
|
428
|
-
*
|
|
429
|
-
* The comparison is {@link earliestFork}, not a single lookup at the current revision: the
|
|
446
|
+
* blanket-style over every registered collection between commit retries. Whether the read is
|
|
447
|
+
* adopted, and whether it is another lineage, is {@link judgeAdoption}'s call, made before this
|
|
448
|
+
* runs so a refresh can act on it first: a refresh that ADOPTS another lineage drops its whole
|
|
449
|
+
* read cache and its floors and re-stages every staged action ({@link forgetAndAdopt},
|
|
450
|
+
* {@link mustReplay}), since everything it cached and computed was computed against a history the
|
|
451
|
+
* network does not hold; an open has no cache to drop and nothing staged. The line is therefore a
|
|
452
|
+
* PER-DISCOVERY report: adopting `next` overwrites the held lineage marker with the log's, the
|
|
453
|
+
* drop leaves the handle consistent with the log, and the next refresh compares log to log and
|
|
454
|
+
* has nothing to report. A REFUSED read leaves the held marker in place, so a fork sealed by a
|
|
455
|
+
* `collection:context-not-lowered` refusal is reported on every refresh, beside that line, with
|
|
456
|
+
* nothing dropped — bringing such a handle onto the network's lineage is reconciliation, backlog
|
|
457
|
+
* `feat-replay-mode-collections-merge-divergent-histories`.
|
|
458
|
+
*
|
|
459
|
+
* The comparison printed is {@link earliestFork}, not a single lookup at the current revision: the
|
|
430
460
|
* two `committed` lists overlap across several revisions, and the LOWEST one they disagree at
|
|
431
461
|
* is where the lineages actually parted — a fork below the current revision was previously
|
|
432
462
|
* silent. `forkRev=` names it, `heldAction=`/`readAction=` are the two ids AT it, and
|
|
@@ -443,14 +473,17 @@ export class Collection {
|
|
|
443
473
|
* the NOTE in {@link bootstrapContext}), which is exactly the case {@link earliestFork} has no
|
|
444
474
|
* shared revision to report on.
|
|
445
475
|
*
|
|
446
|
-
*
|
|
447
|
-
*
|
|
448
|
-
*
|
|
476
|
+
* The two printed comparisons are gated on `log.enabled`: they buy nothing when the line has no
|
|
477
|
+
* sink. Nothing the handle DOES is: the adoption and the lineage verdict behind it
|
|
478
|
+
* ({@link judgeAdoption}) run whatever the logging.
|
|
449
479
|
* Silence proves nothing either way, because a revision is only comparable when BOTH sides
|
|
450
480
|
* name an action for it: an invented collection has no context at all, a revision slot the log
|
|
451
481
|
* gave to a checkpoint or invalidation entry names none, and a revision older than the read
|
|
452
|
-
* log's most recent checkpoint has already fallen off the read side's list.
|
|
453
|
-
|
|
482
|
+
* log's most recent checkpoint has already fallen off the read side's list.
|
|
483
|
+
*
|
|
484
|
+
* @param adoption what adopting `next` does, as {@link judgeAdoption} answers it for the context
|
|
485
|
+
* `source` holds now — passed in by a caller that had to act on it before calling. */
|
|
486
|
+
static advanceContext(source, id, instanceTag, site, next, adoption = Collection.judgeAdoption(source.actionContext, next)) {
|
|
454
487
|
const current = source.actionContext;
|
|
455
488
|
if (next === undefined) {
|
|
456
489
|
return; // The read learned nothing — keep what we already know.
|
|
@@ -461,15 +494,47 @@ export class Collection {
|
|
|
461
494
|
log('collection:lineage-divergence id=%s tag=%s site=%s forkRev=%d heldAction=%s readAction=%s heldRev=%d readRev=%d', id, instanceTag, site, fork.rev, fork.heldAction, fork.readAction, current.rev, next.rev);
|
|
462
495
|
}
|
|
463
496
|
}
|
|
464
|
-
if (
|
|
497
|
+
if (adoption === 'refuse') {
|
|
465
498
|
// The refusal itself is unconditional; only the id lookups that explain it are gated.
|
|
466
|
-
if (log.enabled) {
|
|
499
|
+
if (current !== undefined && log.enabled) {
|
|
467
500
|
log('collection:context-not-lowered id=%s tag=%s site=%s heldRev=%d readRev=%d heldAction=%s readAction=%s', id, instanceTag, site, current.rev, next.rev, actionIdAt(current, next.rev) ?? 'none', actionIdAt(next, next.rev) ?? 'none');
|
|
468
501
|
}
|
|
469
502
|
return;
|
|
470
503
|
}
|
|
471
504
|
source.actionContext = next;
|
|
472
505
|
}
|
|
506
|
+
/** Whether a read context `next` is adopted over the `held` one, and whether it is another
|
|
507
|
+
* lineage ({@link Adoption}). Runs whatever the logging, because the answer is behaviour.
|
|
508
|
+
*
|
|
509
|
+
* Another lineage means the two name different actions at the HELD revision. One comparison is
|
|
510
|
+
* enough because an action id is unique per commit: two lineages that parted at or below the held
|
|
511
|
+
* revision name different actions at every revision both have reached since, the held one
|
|
512
|
+
* included. The exception, one action landing on both sides (a writer's torn retry), is the same
|
|
513
|
+
* lineage at that revision, which is the right answer. A side naming no action there is missing
|
|
514
|
+
* evidence, not disagreement, as in {@link earliestFork} — the held revision's slot went to an
|
|
515
|
+
* invalidation or checkpoint entry, or it predates the read side's most recent checkpoint — so a
|
|
516
|
+
* fork visible only below such a slot is not acted on (the line may still report it). A refused
|
|
517
|
+
* read names no action at the held revision, being below it, so `adopt-divergent` never comes
|
|
518
|
+
* with a refusal.
|
|
519
|
+
*
|
|
520
|
+
* NOTE: two {@link actionIdAt} scans per refresh that walks the log, never per read. Each searches
|
|
521
|
+
* from the end: the held side's entry is normally its last, and the read side's is as far back as
|
|
522
|
+
* the entries the walk found. Both lists truncate only at a checkpoint, which nothing writes yet
|
|
523
|
+
* (tickets/backlog/debt-the-collection-log-never-writes-a-checkpoint); if they grow long enough
|
|
524
|
+
* for that to show, index them by revision. */
|
|
525
|
+
static judgeAdoption(held, next) {
|
|
526
|
+
if (next === undefined || (held !== undefined && next.rev < held.rev)) {
|
|
527
|
+
return 'refuse';
|
|
528
|
+
}
|
|
529
|
+
if (held === undefined) {
|
|
530
|
+
return 'adopt';
|
|
531
|
+
}
|
|
532
|
+
const heldAction = actionIdAt(held, held.rev);
|
|
533
|
+
const readAction = actionIdAt(next, held.rev);
|
|
534
|
+
return heldAction !== undefined && readAction !== undefined && heldAction !== readAction
|
|
535
|
+
? 'adopt-divergent'
|
|
536
|
+
: 'adopt';
|
|
537
|
+
}
|
|
473
538
|
/** The EARLIEST revision the two contexts provably disagree about: the lowest revision both
|
|
474
539
|
* `committed` lists name an action for, where the two ids differ.
|
|
475
540
|
*
|
|
@@ -555,7 +620,9 @@ export class Collection {
|
|
|
555
620
|
}
|
|
556
621
|
/** Run `actions` through their handlers over `tracker` as ONE atomic unit: a throw from any
|
|
557
622
|
* handler leaves none of their writes staged. The live tracker's path ({@link internalTransact})
|
|
558
|
-
* and a head commit's tracker ({@link buildHeadTracker}) share it.
|
|
623
|
+
* and a head commit's tracker ({@link buildHeadTracker}) share it. Only the live tracker's
|
|
624
|
+
* commit changes what this collection's reads see ({@link viewChanged}); a head commit's tracker
|
|
625
|
+
* is private to the commit.
|
|
559
626
|
*
|
|
560
627
|
* @returns the sum of what the handlers accepted as already applied ({@link AlreadyAppliedTally});
|
|
561
628
|
* a handler that answers nothing adds the zero tally. */
|
|
@@ -572,9 +639,24 @@ export class Collection {
|
|
|
572
639
|
applied = addTallies(applied, tally);
|
|
573
640
|
}
|
|
574
641
|
}
|
|
642
|
+
if (tracker === this.tracker) {
|
|
643
|
+
this.viewChanged();
|
|
644
|
+
}
|
|
575
645
|
atomic.commit();
|
|
576
646
|
return applied;
|
|
577
647
|
}
|
|
648
|
+
/** Tell {@link CollectionInitOptions.onViewChanged} that what this collection's reads see is
|
|
649
|
+
* about to change. Every caller calls it in the same synchronous step as the change itself — no
|
|
650
|
+
* `await` between them — which is what lets a reader trust "the counter did not move" as "nothing
|
|
651
|
+
* I read changed". */
|
|
652
|
+
viewChanged() {
|
|
653
|
+
try {
|
|
654
|
+
this.onViewChanged?.();
|
|
655
|
+
}
|
|
656
|
+
catch (err) {
|
|
657
|
+
log('collection:view-changed-callback-threw id=%s tag=%s error=%s', this.id, this.instanceTag, err instanceof Error ? err.message : String(err));
|
|
658
|
+
}
|
|
659
|
+
}
|
|
578
660
|
/** Load external changes and update our context to the latest log revision - resolve any conflicts with our pending actions. */
|
|
579
661
|
async update() {
|
|
580
662
|
const release = await Latches.acquire(this.latchId);
|
|
@@ -599,10 +681,8 @@ export class Collection {
|
|
|
599
681
|
* ask for another (see {@link completeOwnEntry}).
|
|
600
682
|
*
|
|
601
683
|
* `tailFloor` is optional: a revision a responder confirmed is taken, when the caller has one (see
|
|
602
|
-
* {@link updateInternal}). `TransactionCoordinator.commit`
|
|
603
|
-
*
|
|
604
|
-
* debt-multi-collection-retry-cannot-see-the-taken-revision) — and this is the parameter it will
|
|
605
|
-
* pass it through. */
|
|
684
|
+
* {@link updateInternal}). `TransactionCoordinator.commit` passes the highest one its refusals of
|
|
685
|
+
* THIS collection carried (`RetryBudget.tailFloor`), and nothing for a collection none did. */
|
|
606
686
|
async refreshInFlight(report, lastChance, tailFloor) {
|
|
607
687
|
const release = await Latches.acquire(this.latchId);
|
|
608
688
|
try {
|
|
@@ -697,10 +777,19 @@ export class Collection {
|
|
|
697
777
|
// pair is not obviously right either: a member re-executing the transaction after a sibling
|
|
698
778
|
// participant has landed no longer sees the state it was staged against. Tracked as an arm
|
|
699
779
|
// of tickets/backlog/feat-no-deployment-validates-transactions-at-pend.
|
|
780
|
+
// NOTE: the re-send carries no pend-level `hlc` either: the retained attempt holds the write's
|
|
781
|
+
// HLC only inside the log entry in its transforms, and the ActionEntry the refresh hands this
|
|
782
|
+
// method does not carry it. A member that missed the first pend and stores this re-send
|
|
783
|
+
// therefore observes the write's HLC when it next reads the entry, not at the pend. Fine while
|
|
784
|
+
// the HLC is observational; if a feed point at the pend ever becomes load-bearing, retain the
|
|
785
|
+
// HLC on `InFlightAttempt` beside the transforms and put it on this request. The write's LANE
|
|
786
|
+
// does ride here, from the in-flight cycle (`InFlightCycle.lane`), which every write path marks
|
|
787
|
+
// with the lane it minted: the same value the retained entry carries.
|
|
700
788
|
const result = await this.source.transact(attempt.transforms, entry.actionId, rev, this.id, attempt.tailId, {
|
|
701
789
|
blockDigests: attempt.blockDigests,
|
|
702
790
|
baseRevs: attempt.baseRevs,
|
|
703
|
-
|
|
791
|
+
lane: this.inFlightCycle?.lane,
|
|
792
|
+
refuseSolo: this.inFlightCycle?.refuseSolo
|
|
704
793
|
});
|
|
705
794
|
if (result.success) {
|
|
706
795
|
return result.durability;
|
|
@@ -910,8 +999,11 @@ export class Collection {
|
|
|
910
999
|
* replace => new instance.
|
|
911
1000
|
*
|
|
912
1001
|
* A SEALED segment's action list is the queue entry's own and is never rewritten (invariant 3
|
|
913
|
-
* of docs/offline-sync.md §The segment model), so the hook is not offered them.
|
|
914
|
-
*
|
|
1002
|
+
* of docs/offline-sync.md §The segment model), so the hook is not offered them. The hook is the
|
|
1003
|
+
* convergent lane's rule ({@link ConvergentMerge.filterConflict}): {@link doFilterConflict} offers
|
|
1004
|
+
* it only an action the declaration classifies `convergent`, and keeps a serializable one as-is.
|
|
1005
|
+
* `Tree` declares nothing and `Diary` declares no hook, so nothing observable changes for them
|
|
1006
|
+
* either way.
|
|
915
1007
|
*
|
|
916
1008
|
* NOTE: a filterConflict hook that always allocates a fresh (but equal) instance instead of
|
|
917
1009
|
* returning the same one forces a replay on every update — if that ever shows up as a hot path,
|
|
@@ -1060,11 +1152,11 @@ export class Collection {
|
|
|
1060
1152
|
if (invalidations.length > 0 && this.segments.replayableCount() > 0) {
|
|
1061
1153
|
anyConflicts = true;
|
|
1062
1154
|
}
|
|
1063
|
-
this.forgetAndAdopt(latest, entryRevs, revertedBlockIds, ends);
|
|
1155
|
+
const adoption = this.forgetAndAdopt(latest, entryRevs, revertedBlockIds, ends);
|
|
1064
1156
|
Collection.reportShortfall(this.id, this.instanceTag, tailRev, actionContext?.rev, this.source.actionContext?.rev);
|
|
1065
1157
|
// Re-stage the staged actions against the adopted revision. The affected
|
|
1066
|
-
// blocks were already dropped from sourceCache above (per log entry / per invalidation
|
|
1067
|
-
// so the replay's reads re-materialize from the transactor.
|
|
1158
|
+
// blocks were already dropped from sourceCache above (per log entry / per invalidation, or
|
|
1159
|
+
// all of them on an adopted divergence), so the replay's reads re-materialize from the transactor.
|
|
1068
1160
|
// NOTE: a throw out of replayActions — a refusal of the OPEN segment, or any non-refusal
|
|
1069
1161
|
// error — leaves the tracker holding only the transforms replayed so far while the open
|
|
1070
1162
|
// segment still lists all of its actions; the caller's error handling is expected to
|
|
@@ -1073,7 +1165,7 @@ export class Collection {
|
|
|
1073
1165
|
// collection-half-restaged). A SEALED segment is not left half-replayed: it is staged
|
|
1074
1166
|
// atomically, and a refusal of one is recorded and skipped rather than thrown. If replay ever
|
|
1075
1167
|
// gains a routinely-throwing read path, rebuild into a scratch tracker and swap on success.
|
|
1076
|
-
if (this.mustReplay(anyConflicts, actionContext)) {
|
|
1168
|
+
if (this.mustReplay(anyConflicts, actionContext, adoption)) {
|
|
1077
1169
|
await this.replayActions();
|
|
1078
1170
|
}
|
|
1079
1171
|
}
|
|
@@ -1090,21 +1182,51 @@ export class Collection {
|
|
|
1090
1182
|
* and the adopting, a concurrent read either lands before both and is forgotten with the rest,
|
|
1091
1183
|
* or lands after both and is judged at the adopted revision — against the floor
|
|
1092
1184
|
* ({@link TransactorSource.tryGet} reads its context when the answer arrives, not when it was
|
|
1093
|
-
* asked for) and against the generation the clear moved (`CacheSource.stillWanted`).
|
|
1185
|
+
* asked for) and against the generation the clear moved (`CacheSource.stillWanted`). That keeps
|
|
1186
|
+
* each single read sound; a reader part-way through SEVERAL reads — a tree descent — can still hold
|
|
1187
|
+
* blocks of the revision being left while it reads the rest at the adopted one, so it is told
|
|
1188
|
+
* through {@link viewChanged}.
|
|
1094
1189
|
*
|
|
1095
1190
|
* The advance is monotonic (see {@link advanceContext}): an empty or unopenable log yields no
|
|
1096
1191
|
* context at all, and a log read that lags what this handle already committed yields an older
|
|
1097
1192
|
* one; neither is grounds for forgetting the revision held. It also has to precede
|
|
1098
1193
|
* {@link replayActions}, which re-reads blocks through `this.source` at whatever revision the
|
|
1099
|
-
* context names — replaying first would refill the cache at the revision being left.
|
|
1194
|
+
* context names — replaying first would refill the cache at the revision being left.
|
|
1195
|
+
*
|
|
1196
|
+
* **An adopted divergence forgets everything first** ({@link judgeAdoption}): the whole read cache
|
|
1197
|
+
* and every floor, ahead of the per-entry loop so this walk's floors — the new lineage's — are the
|
|
1198
|
+
* ones left standing. Not just the blocks the walked entries name: the walk covers only entries
|
|
1199
|
+
* above the held revision, so the blocks the old lineage built at and below it are named by
|
|
1200
|
+
* entries this handle will never walk, the cache has no expiry, and an idle refresh stops after
|
|
1201
|
+
* one request while the log does not move — nothing would ever clear them. And not the floors
|
|
1202
|
+
* kept: a floor raised under the old lineage is no bound on the new one, where the block may
|
|
1203
|
+
* legitimately sit below it, and would make every read of it a below-floor answer for the life of
|
|
1204
|
+
* the handle. The header and tail {@link keepLogEnds} offers came from the new lineage and may be
|
|
1205
|
+
* kept. The staged actions were computed against the old content, so the verdict is returned for
|
|
1206
|
+
* {@link mustReplay}.
|
|
1207
|
+
*
|
|
1208
|
+
* The handle's clock observes the highest HLC the walk read (`GetFromResult.hlcHighWater`), so a
|
|
1209
|
+
* write through it never mints below an entry it has seen — whatever the verdict, since a clock
|
|
1210
|
+
* only rises and the entries were read either way.
|
|
1211
|
+
*
|
|
1212
|
+
* @returns what the adoption did, as {@link judgeAdoption} answered it before anything changed. */
|
|
1100
1213
|
forgetAndAdopt(latest, entryRevs, revertedBlockIds, ends) {
|
|
1214
|
+
const adoption = Collection.judgeAdoption(this.source.actionContext, latest?.context);
|
|
1215
|
+
if (latest?.hlcHighWater !== undefined)
|
|
1216
|
+
clockOf(this.transactor).observe(latest.hlcHighWater);
|
|
1217
|
+
this.viewChanged();
|
|
1218
|
+
if (adoption === 'adopt-divergent') {
|
|
1219
|
+
this.sourceCache.clear();
|
|
1220
|
+
this.floors.clear();
|
|
1221
|
+
}
|
|
1101
1222
|
for (const entry of latest?.entries ?? []) {
|
|
1102
1223
|
this.sourceCache.clear(entry.blockIds);
|
|
1103
1224
|
this.raiseFloors(entry, entryRevs.get(entry.actionId));
|
|
1104
1225
|
}
|
|
1105
1226
|
this.sourceCache.clear(revertedBlockIds);
|
|
1106
|
-
Collection.advanceContext(this.source, this.id, this.instanceTag, 'refresh', latest?.context);
|
|
1227
|
+
Collection.advanceContext(this.source, this.id, this.instanceTag, 'refresh', latest?.context, adoption);
|
|
1107
1228
|
Collection.keepLogEnds(this.sourceCache, this.floors, this.source.actionContext, ends);
|
|
1229
|
+
return adoption;
|
|
1108
1230
|
}
|
|
1109
1231
|
/** Put the header and log tail block {@link readLogEnds} already fetched into a handle's own
|
|
1110
1232
|
* cache, so the next read of either is a hit rather than a second fetch of a block just
|
|
@@ -1245,7 +1367,8 @@ export class Collection {
|
|
|
1245
1367
|
* claim (`collection:context-short-of-tail`, or `collection:context-not-lowered` for a handle
|
|
1246
1368
|
* pinned by an over-claiming tail), or an invalidation or checkpoint took the newest slot;
|
|
1247
1369
|
* - any action entry in the tail block naming a different action than `held` names at the same
|
|
1248
|
-
* revision (`collection:lineage-divergence`, and the walk's adoption of the log's list
|
|
1370
|
+
* revision (`collection:lineage-divergence`, and the walk's adoption of the log's list, which
|
|
1371
|
+
* drops the read cache when it adopts another lineage — see {@link forgetAndAdopt}).
|
|
1249
1372
|
*
|
|
1250
1373
|
* NOTE: the lineage comparison sees only the entries the tail block holds. A fork below them, on
|
|
1251
1374
|
* a log that has not moved, is not looked at again until a refresh finds something new — that
|
|
@@ -1307,8 +1430,10 @@ export class Collection {
|
|
|
1307
1430
|
* (`index-backfill-cost.spec.ts`, `cold-apply-cost.spec.ts`), because the replay's reads are
|
|
1308
1431
|
* served from `sourceCache`. If a long transaction's reads ever show up as slow, narrow the
|
|
1309
1432
|
* replay to the actions whose reads the adopted entries actually invalidated — NOT back to
|
|
1310
|
-
* conflicts alone, which is the defect above.
|
|
1311
|
-
|
|
1433
|
+
* conflicts alone, which is the defect above.
|
|
1434
|
+
*
|
|
1435
|
+
* @param adoption what the refresh's adoption did ({@link forgetAndAdopt}). */
|
|
1436
|
+
mustReplay(anyConflicts, priorContext, adoption) {
|
|
1312
1437
|
if (anyConflicts) {
|
|
1313
1438
|
return true;
|
|
1314
1439
|
}
|
|
@@ -1317,6 +1442,14 @@ export class Collection {
|
|
|
1317
1442
|
if (adoptedRev !== undefined && adoptedRev !== priorContext?.rev && replayable > 0) {
|
|
1318
1443
|
return true;
|
|
1319
1444
|
}
|
|
1445
|
+
// Fourth reason, ahead of the third: the refresh adopted another lineage, so every staged
|
|
1446
|
+
// action was computed against content the network does not hold. A fork at the SAME revision
|
|
1447
|
+
// advances nothing, so the reason above does not see it. The whole-cache clear behind it
|
|
1448
|
+
// would usually make every pinned base read as moved too, but this keeps the rule readable,
|
|
1449
|
+
// covers staged actions that pinned nothing, and spares a `restage-moved-base` line per pin.
|
|
1450
|
+
if (adoption === 'adopt-divergent' && replayable > 0) {
|
|
1451
|
+
return true;
|
|
1452
|
+
}
|
|
1320
1453
|
// Third reason: a staged block's base has MOVED — the read cache no longer describes it at
|
|
1321
1454
|
// the revision its operations were computed against (see `Tracker.movedBases`). A refresh
|
|
1322
1455
|
// that adopted nothing and found no conflict can still be standing over such a block: a
|
|
@@ -1469,6 +1602,7 @@ export class Collection {
|
|
|
1469
1602
|
await this.replayActions();
|
|
1470
1603
|
return;
|
|
1471
1604
|
}
|
|
1605
|
+
this.viewChanged();
|
|
1472
1606
|
if (boundaryMoved && snapshot.pending.length === 0) {
|
|
1473
1607
|
this.tracker.reset();
|
|
1474
1608
|
this.segments.open = [];
|
|
@@ -1801,9 +1935,14 @@ export class Collection {
|
|
|
1801
1935
|
* revision because {@link update} sees its rev is already current and refetches
|
|
1802
1936
|
* nothing. Call BEFORE resetting the tracker (the transforms are read live).
|
|
1803
1937
|
*
|
|
1938
|
+
* Tells {@link viewChanged} for the fold AND for the tracker reset that follows it, so the
|
|
1939
|
+
* caller must reset in the same synchronous step, with no `await` between the two — every
|
|
1940
|
+
* coordinator site does.
|
|
1941
|
+
*
|
|
1804
1942
|
* @param revision - the committed revision these transforms land at (from
|
|
1805
1943
|
* {@link recordCommitted}), so cached read-dependency revisions advance to it. */
|
|
1806
1944
|
applyCommittedToCache(transforms, revision) {
|
|
1945
|
+
this.viewChanged();
|
|
1807
1946
|
this.sourceCache.transformCache(transforms, revision);
|
|
1808
1947
|
}
|
|
1809
1948
|
/** Next revision this collection would commit at (current committed rev + 1). */
|
|
@@ -1884,7 +2023,7 @@ export class Collection {
|
|
|
1884
2023
|
*
|
|
1885
2024
|
* `cycle` is what every send of the cycle carries ({@link InFlightCycle}); a re-mark replaces it,
|
|
1886
2025
|
* which is harmless because every caller re-marks with what it marked. */
|
|
1887
|
-
beginInFlightAction(actionId, cycle
|
|
2026
|
+
beginInFlightAction(actionId, cycle) {
|
|
1888
2027
|
if (this.inFlightActionId !== actionId) {
|
|
1889
2028
|
// A different action's failed attempt cannot finish this one. Re-marking the SAME id (a
|
|
1890
2029
|
// coordinator re-marks on every attempt) keeps what the previous attempt retained — that
|
|
@@ -1900,7 +2039,7 @@ export class Collection {
|
|
|
1900
2039
|
this.inFlightActionId = undefined;
|
|
1901
2040
|
this.inFlightAttempt = undefined;
|
|
1902
2041
|
this.mintedLogBlockIds = undefined;
|
|
1903
|
-
this.inFlightCycle =
|
|
2042
|
+
this.inFlightCycle = undefined;
|
|
1904
2043
|
}
|
|
1905
2044
|
};
|
|
1906
2045
|
}
|
|
@@ -2002,12 +2141,21 @@ export class Collection {
|
|
|
2002
2141
|
this.assertNoSealedSegments();
|
|
2003
2142
|
const identity = {
|
|
2004
2143
|
actionId: uint8ArrayToString(randomBytes(16), 'base64url'),
|
|
2005
|
-
// One timestamp for the WRITE, minted here beside the action id and for
|
|
2006
|
-
// attempt that
|
|
2007
|
-
// attempt it repeats may already have stored under this `(action id, revision)`.
|
|
2144
|
+
// One timestamp, one HLC and one lane for the WRITE, minted here beside the action id and for
|
|
2145
|
+
// the same reason: an attempt that took its own would make the retry's log block differ from
|
|
2146
|
+
// the one the attempt it repeats may already have stored under this `(action id, revision)`.
|
|
2008
2147
|
timestamp: Date.now(),
|
|
2148
|
+
hlc: clockOf(this.transactor).now(),
|
|
2149
|
+
// The caller's classification wins over the declaration, and the declaration over nothing
|
|
2150
|
+
// (`SyncOptions.lane`): the caller knows more about the write than the collection does.
|
|
2151
|
+
// NOTE: judged over the open segment as staged NOW and fixed for the write; a
|
|
2152
|
+
// `merge.filterConflict` hook that answered a replacement of a different lane during an
|
|
2153
|
+
// inter-attempt refresh would leave the entry claiming the lane of the action it replaced. No
|
|
2154
|
+
// hook in this repository replaces an action; if one ever does, the member-side lane check is
|
|
2155
|
+
// what catches the mismatch.
|
|
2156
|
+
lane: options?.lane ?? this.laneOf(this.segments.open),
|
|
2009
2157
|
};
|
|
2010
|
-
const endInFlight = this.beginInFlightAction(identity.actionId, { refuseSolo: options?.refuseSoloCommit });
|
|
2158
|
+
const endInFlight = this.beginInFlightAction(identity.actionId, { lane: identity.lane, refuseSolo: options?.refuseSoloCommit });
|
|
2011
2159
|
try {
|
|
2012
2160
|
return await this.syncAttempts(identity, options);
|
|
2013
2161
|
}
|
|
@@ -2079,9 +2227,11 @@ export class Collection {
|
|
|
2079
2227
|
send(staged, identity, priority) {
|
|
2080
2228
|
return this.source.transact(staged.tracker.transforms, identity.actionId, staged.rev, this.id, staged.tailId, {
|
|
2081
2229
|
priority,
|
|
2230
|
+
hlc: identity.hlc,
|
|
2231
|
+
lane: identity.lane,
|
|
2082
2232
|
blockDigests: staged.blockDigests,
|
|
2083
2233
|
baseRevs: staged.baseRevs,
|
|
2084
|
-
refuseSolo: this.inFlightCycle
|
|
2234
|
+
refuseSolo: this.inFlightCycle?.refuseSolo
|
|
2085
2235
|
});
|
|
2086
2236
|
}
|
|
2087
2237
|
/** Fold a committed attempt's transforms — the log append included — into this instance's read
|
|
@@ -2089,6 +2239,7 @@ export class Collection {
|
|
|
2089
2239
|
* still staged (see the note in {@link syncAttempts}). Takes the transforms out of the attempt's
|
|
2090
2240
|
* tracker, which is finished with. */
|
|
2091
2241
|
foldOwnCommit(staged, actionId) {
|
|
2242
|
+
this.viewChanged();
|
|
2092
2243
|
this.sourceCache.transformCache(staged.tracker.reset(), staged.rev);
|
|
2093
2244
|
this.recordCommitted(actionId, staged.rev);
|
|
2094
2245
|
}
|
|
@@ -2122,7 +2273,7 @@ export class Collection {
|
|
|
2122
2273
|
* when a refresh or the head tracker's staging refused it during the cycle; whatever
|
|
2123
2274
|
* `options.recordAttempt` throws, before anything is sent; otherwise what {@link sync} throws. */
|
|
2124
2275
|
async commitHead(entryId, options) {
|
|
2125
|
-
const handle = await this.openHeadCommit(entryId, { actionId: options.actionId, timestamp: options.timestamp }, {
|
|
2276
|
+
const handle = await this.openHeadCommit(entryId, { actionId: options.actionId, timestamp: options.timestamp, hlc: options.hlc, lane: options.lane }, {
|
|
2126
2277
|
refuseSolo: options.refuseSoloCommit,
|
|
2127
2278
|
...(options.resume === undefined ? {} : { resume: options.resume }),
|
|
2128
2279
|
...(options.onCommittedHead === undefined ? {} : { onCommittedHead: options.onCommittedHead }),
|
|
@@ -2145,9 +2296,9 @@ export class Collection {
|
|
|
2145
2296
|
* segment; and seeds the retained attempt with `options.resume` when one is given, so that the
|
|
2146
2297
|
* opening refresh can finish an earlier cycle's torn attempt from it ({@link completeOwnEntry}) —
|
|
2147
2298
|
* and `stage()` re-sends it verbatim while the next attempt would request its revision
|
|
2148
|
-
* ({@link resumedAttempt}). The rest of `options` is the cycle's ({@link InFlightCycle}
|
|
2149
|
-
* with the in-flight mark, so the handle's `send()` and a
|
|
2150
|
-
* carry it.
|
|
2299
|
+
* ({@link resumedAttempt}). The rest of `options` is the cycle's ({@link InFlightCycle}, its lane
|
|
2300
|
+
* taken from `identity`), recorded with the in-flight mark, so the handle's `send()` and a
|
|
2301
|
+
* refresh's re-send of a torn attempt both carry it.
|
|
2151
2302
|
*
|
|
2152
2303
|
* **The target.** The live tracker holds every sealed segment and the open one, cumulatively, so
|
|
2153
2304
|
* an attempt cannot run on a copy of it the way a sync's does. It runs on a HEAD TRACKER instead
|
|
@@ -2198,7 +2349,7 @@ export class Collection {
|
|
|
2198
2349
|
release();
|
|
2199
2350
|
throw err;
|
|
2200
2351
|
}
|
|
2201
|
-
const endInFlight = this.beginInFlightAction(identity.actionId, cycle);
|
|
2352
|
+
const endInFlight = this.beginInFlightAction(identity.actionId, { ...cycle, lane: identity.lane });
|
|
2202
2353
|
this.headCommit = { entryId, ...(onCommittedHead === undefined ? {} : { onCommitted: onCommittedHead }) };
|
|
2203
2354
|
if (resume !== undefined) {
|
|
2204
2355
|
this.retainInFlightAttempt(resume);
|
|
@@ -2341,21 +2492,27 @@ export class Collection {
|
|
|
2341
2492
|
/** The tracker a head attempt is built from (see {@link commitHead}): `current`, while it was
|
|
2342
2493
|
* built for the revision the next attempt requests and no base under it has moved; otherwise a
|
|
2343
2494
|
* fresh one ({@link buildHeadTracker}). A revision that moved is a write that is genuinely
|
|
2344
|
-
* different
|
|
2345
|
-
* {@link
|
|
2495
|
+
* different, and so is one whose held lineage moved at the same revision: a refresh between
|
|
2496
|
+
* attempts that adopted another lineage ({@link judgeAdoption}) dropped the read cache the
|
|
2497
|
+
* tracker was staged over, and an action that inserted a block computed from that content pinned
|
|
2498
|
+
* no base the re-judge below would see as moved. A base that moved at the same revision is
|
|
2499
|
+
* re-judged exactly as {@link restageIfBasesMoved} re-judges the live queue before an attempt,
|
|
2500
|
+
* and rebuilds.
|
|
2346
2501
|
* NOTE: that rebuild is the same exception to the byte-identical retry that {@link syncAttempts}
|
|
2347
2502
|
* records at its `restageIfBasesMoved` call — fresh ids for the blocks the actions insert under
|
|
2348
2503
|
* an unchanged `(action id, revision)` — reached the same narrow way and refused by storage's
|
|
2349
2504
|
* base guard on the same machines; the same answer applies if it is ever seen. */
|
|
2350
2505
|
async headTrackerFor(segment, current) {
|
|
2351
2506
|
const rev = this.getNextRev();
|
|
2352
|
-
|
|
2507
|
+
const held = this.source.actionContext;
|
|
2508
|
+
const lineage = held === undefined ? undefined : actionIdAt(held, held.rev);
|
|
2509
|
+
if (current?.rev === rev && current.lineage === lineage) {
|
|
2353
2510
|
await this.rereadUnretainedBases(current.tracker);
|
|
2354
2511
|
if (this.logMovedBases(current.tracker.movedBases()) === 0) {
|
|
2355
2512
|
return current;
|
|
2356
2513
|
}
|
|
2357
2514
|
}
|
|
2358
|
-
return { rev, tracker: await this.buildHeadTracker(segment) };
|
|
2515
|
+
return { rev, lineage, tracker: await this.buildHeadTracker(segment) };
|
|
2359
2516
|
}
|
|
2360
2517
|
/** A tracker over this instance's read cache, with pins of its own, holding `segment`'s actions
|
|
2361
2518
|
* staged atomically over the committed state — from the invented baseline while this collection
|
|
@@ -2432,13 +2589,14 @@ export class Collection {
|
|
|
2432
2589
|
* refresh would have done. */
|
|
2433
2590
|
async unstage(actions, stagedBefore, revBefore) {
|
|
2434
2591
|
// NOTE: matched by identity, which is what `filterAgainstEntry` promises for a kept action.
|
|
2435
|
-
// A `filterConflict` hook that answers a REPLACEMENT instance for one of these actions
|
|
2436
|
-
// leave the replacement staged here. No collection installs such a hook today (`Tree`
|
|
2437
|
-
// `Diary`
|
|
2438
|
-
// match on that instead.
|
|
2592
|
+
// A `merge.filterConflict` hook that answers a REPLACEMENT instance for one of these actions
|
|
2593
|
+
// would leave the replacement staged here. No collection installs such a hook today (`Tree`
|
|
2594
|
+
// declares no merge and `Diary` declares no hook); if one ever does, carry a per-call token on
|
|
2595
|
+
// the staged actions and match on that instead.
|
|
2439
2596
|
// The actions were staged into the OPEN segment (actAndSync refuses over sealed segments).
|
|
2440
2597
|
this.segments.open = this.segments.open.filter(staged => !actions.includes(staged));
|
|
2441
2598
|
if (this.source.actionContext?.rev === revBefore) {
|
|
2599
|
+
this.viewChanged();
|
|
2442
2600
|
this.tracker.reset(stagedBefore);
|
|
2443
2601
|
}
|
|
2444
2602
|
else {
|
|
@@ -2476,10 +2634,16 @@ export class Collection {
|
|
|
2476
2634
|
* sealed segment that staged records what its actions accepted as already applied
|
|
2477
2635
|
* (`SealedSegment.applied`), the tally the head commit reports when the segment is committed.
|
|
2478
2636
|
*
|
|
2637
|
+
* A replay changes the tree beneath unlatched readers twice over: the reset drops every block a
|
|
2638
|
+
* staged action inserted, and the re-staging inserts them again under fresh ids. Both are told
|
|
2639
|
+
* through {@link viewChanged} — the reset here, each re-staged unit in {@link stageInto} — so a
|
|
2640
|
+
* reader part-way through a descent knows to read again rather than follow an id that is gone.
|
|
2641
|
+
*
|
|
2479
2642
|
* @param unreported - a segment whose refusal is recorded but NOT reported through
|
|
2480
2643
|
* `onSealedRefused`: the one {@link restoreSealed} is inserting, whose caller reads the recorded
|
|
2481
2644
|
* refusal off the segment itself. */
|
|
2482
2645
|
async replayActions(unreported) {
|
|
2646
|
+
this.viewChanged();
|
|
2483
2647
|
this.tracker.reset(this.replayBaseline());
|
|
2484
2648
|
for (const segment of this.segments.replayable()) {
|
|
2485
2649
|
try {
|
|
@@ -2525,14 +2689,30 @@ export class Collection {
|
|
|
2525
2689
|
clearReadDependencies() {
|
|
2526
2690
|
this.source.clearReadDependencies();
|
|
2527
2691
|
}
|
|
2692
|
+
/** The lane of a write made of `actions` under this collection's merge declaration
|
|
2693
|
+
* ({@link CollectionInitOptions.merge}): the stricter lane over the declaration's answer for each
|
|
2694
|
+
* (`stricterLane`), `serializable` without a declaration and for an empty list. Pure. The source
|
|
2695
|
+
* of a sync's lane when its caller gave none (`SyncOptions.lane`), and of a queued entry's
|
|
2696
|
+
* (`OfflineQueue.enqueue`). */
|
|
2697
|
+
laneOf(actions) {
|
|
2698
|
+
const merge = this.merge;
|
|
2699
|
+
return merge === undefined ? 'serializable' : stricterLane(actions.map(action => merge.laneOf(action)));
|
|
2700
|
+
}
|
|
2528
2701
|
/** Called for each local action that may be in conflict with a remote action (always called under latch).
|
|
2702
|
+
* The merge declaration's hook ({@link ConvergentMerge.filterConflict}) decides only for an action the
|
|
2703
|
+
* declaration classifies `convergent`; a serializable action is kept as-is, since its guards decide
|
|
2704
|
+
* on replay, and so is every action of a collection with no declaration or no hook.
|
|
2529
2705
|
* @param action - The local action to check
|
|
2530
2706
|
* @param potential - The remote actions that are potentially in conflict
|
|
2531
2707
|
* @returns The effective action to keep: the original (unchanged), a replacement
|
|
2532
2708
|
* instance (applied instead of the original), or undefined to discard it.
|
|
2533
2709
|
*/
|
|
2534
2710
|
doFilterConflict(action, potential) {
|
|
2535
|
-
|
|
2711
|
+
const merge = this.merge;
|
|
2712
|
+
if (merge?.filterConflict === undefined || merge.laneOf(action) !== 'convergent') {
|
|
2713
|
+
return action;
|
|
2714
|
+
}
|
|
2715
|
+
return merge.filterConflict(action, potential);
|
|
2536
2716
|
}
|
|
2537
2717
|
/** The two blocks every refresh starts from — the collection header and the log tail block it
|
|
2538
2718
|
* names — read unpinned ("latest"), in ONE request when `knownTailId` is the tail the header
|
|
@@ -2621,12 +2801,12 @@ export class Collection {
|
|
|
2621
2801
|
* NOTE: the fallback is unbounded — two gets per collection at once, only after a failed
|
|
2622
2802
|
* request. Fine for the tens of tables a host watches; if callers ever name hundreds, read the
|
|
2623
2803
|
* fallback in bounded batches. */
|
|
2624
|
-
static async readAttributed(transactor, blockIds) {
|
|
2804
|
+
static async readAttributed(transactor, blockIds, reads) {
|
|
2625
2805
|
if (blockIds.length === 0) {
|
|
2626
2806
|
return new Map();
|
|
2627
2807
|
}
|
|
2628
2808
|
try {
|
|
2629
|
-
const results = await transactor.get({ blockIds });
|
|
2809
|
+
const results = await transactor.get({ blockIds, ...reads });
|
|
2630
2810
|
return new Map(blockIds.map(id => [id, { entry: results?.[id] }]));
|
|
2631
2811
|
}
|
|
2632
2812
|
catch (error) {
|
|
@@ -2634,17 +2814,21 @@ export class Collection {
|
|
|
2634
2814
|
return new Map([[blockIds[0], { error }]]);
|
|
2635
2815
|
}
|
|
2636
2816
|
log('collection:tails-read-split blocks=%d error=%o', blockIds.length, error);
|
|
2637
|
-
return new Map(await Promise.all(blockIds.map(async (id) => [id, await Collection.readAlone(transactor, id)])));
|
|
2817
|
+
return new Map(await Promise.all(blockIds.map(async (id) => [id, await Collection.readAlone(transactor, id, reads)])));
|
|
2638
2818
|
}
|
|
2639
2819
|
}
|
|
2640
|
-
static async readAlone(transactor, id) {
|
|
2820
|
+
static async readAlone(transactor, id, reads) {
|
|
2641
2821
|
try {
|
|
2642
|
-
return { entry: (await transactor.get({ blockIds: [id] }))?.[id] };
|
|
2822
|
+
return { entry: (await transactor.get({ blockIds: [id], ...reads }))?.[id] };
|
|
2643
2823
|
}
|
|
2644
2824
|
catch (error) {
|
|
2645
2825
|
return { error };
|
|
2646
2826
|
}
|
|
2647
2827
|
}
|
|
2828
|
+
/** The `BlockGets` fields every request of a {@link readCommittedTails} carries. */
|
|
2829
|
+
static tailReadFields(options) {
|
|
2830
|
+
return options?.skipWindowConsult ? { skipWindowConsult: true } : {};
|
|
2831
|
+
}
|
|
2648
2832
|
/** An unpinned read of the log tail block, checked as {@link checkedLogTail} describes, carrying
|
|
2649
2833
|
* `tailFloor` when the caller has one (see {@link readLogEnds}). */
|
|
2650
2834
|
static async readLogTail(transactor, tailId, tailFloor) {
|