@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
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import type { ActionId, AlreadyAppliedTally, CollectionId } from "../index.js";
|
|
2
2
|
import type { ReadDependency, Transaction } from "./transaction.js";
|
|
3
|
+
import type { Hlc } from "../hlc/hlc.js";
|
|
4
|
+
import type { Lane } from "../lane/lane.js";
|
|
3
5
|
import { clampPriority } from "./transaction.js";
|
|
4
6
|
import type { Collection, RefreshReport } from "../collection/collection.js";
|
|
5
7
|
import type { HeadCommitHandle } from "../collection/head-commit.js";
|
|
@@ -12,8 +14,9 @@ import { refuseSoloField } from "../network/refuse-solo.js";
|
|
|
12
14
|
|
|
13
15
|
/**
|
|
14
16
|
* What the coordinator's phases know about the write they are sending — everything they used to
|
|
15
|
-
* read off a `Transaction`: the action id every pend and commit names, the timestamp
|
|
16
|
-
* carry, the reads recorded on them, and the aged retry priority an unvalidated pend
|
|
17
|
+
* read off a `Transaction`: the action id every pend and commit names, the timestamp, HLC and lane
|
|
18
|
+
* its log entries carry, the reads recorded on them, and the aged retry priority an unvalidated pend
|
|
19
|
+
* carries.
|
|
17
20
|
* `commit` and `execute` derive one from their transaction ({@link writeContextOf}); the per-entry
|
|
18
21
|
* commit (`TransactionCoordinator.commitEntry`) builds its own, since a queued entry has no
|
|
19
22
|
* transaction. A `TransactionStamp` is deliberately NOT fabricated for it: a stamp carries a peer id,
|
|
@@ -21,8 +24,16 @@ import { refuseSoloField } from "../network/refuse-solo.js";
|
|
|
21
24
|
*/
|
|
22
25
|
export type WriteContext = {
|
|
23
26
|
readonly actionId: ActionId;
|
|
24
|
-
/** Stamped on every log entry of the write; fixed per write, never per attempt.
|
|
27
|
+
/** Stamped on every log entry of the write; fixed per write, never per attempt. The second
|
|
28
|
+
* per-write value, {@link hlc}, follows the same rule. */
|
|
25
29
|
readonly timestamp: number;
|
|
30
|
+
/** Stamped on every log entry of the write (`LogEntry.hlc`) and carried on every pend of it
|
|
31
|
+
* (`PendRequest.hlc`): one HLC for every participant, the transaction's own or the queued entry's. */
|
|
32
|
+
readonly hlc: Hlc;
|
|
33
|
+
/** Stamped on every log entry of the write (`ActionEntry.lane`) and carried on every pend and
|
|
34
|
+
* commit of it (`PendRequest.lane`, `CommitRequest.lane`): one lane for every participant, the
|
|
35
|
+
* transaction's own (`Transaction.lane`) or the queued entry's (`EntryCommit.lane`). */
|
|
36
|
+
readonly lane: Lane;
|
|
26
37
|
/** Recorded on every log entry of the write (`ActionEntry.reads`). */
|
|
27
38
|
readonly reads: readonly ReadDependency[];
|
|
28
39
|
/** Already clamped (`clampPriority`); 0 on a first attempt. */
|
|
@@ -35,11 +46,14 @@ export type WriteContext = {
|
|
|
35
46
|
|
|
36
47
|
/** The write context of a transaction's attempt, read when the attempt starts: `commitAttempts` ages
|
|
37
48
|
* the transaction's priority between attempts, so it is read per attempt rather than once. `cycle`
|
|
38
|
-
* is what the commit was asked of every send ({@link InFlightCycle})
|
|
39
|
-
|
|
49
|
+
* is what the commit was asked of every send ({@link InFlightCycle}) beyond the lane, which is the
|
|
50
|
+
* transaction's own. */
|
|
51
|
+
export function writeContextOf(transaction: Transaction, cycle: Omit<InFlightCycle, 'lane'> = {}): WriteContext {
|
|
40
52
|
return {
|
|
41
53
|
actionId: transaction.id as ActionId,
|
|
42
54
|
timestamp: transaction.stamp.timestamp,
|
|
55
|
+
hlc: transaction.hlc,
|
|
56
|
+
lane: transaction.lane,
|
|
43
57
|
reads: transaction.reads,
|
|
44
58
|
priority: clampPriority(transaction.priority),
|
|
45
59
|
...refuseSoloField(cycle.refuseSolo),
|
|
@@ -60,6 +74,12 @@ export type EntryCommit = {
|
|
|
60
74
|
readonly actionId: ActionId;
|
|
61
75
|
/** The entry's local commit time: every participant's log entry carries it (`WriteIdentity`). */
|
|
62
76
|
readonly timestamp: number;
|
|
77
|
+
/** The entry's local commit time as an HLC, minted by the queue at enqueue and re-supplied on every
|
|
78
|
+
* drive: every participant's log entry carries it (`WriteIdentity.hlc`). */
|
|
79
|
+
readonly hlc: Hlc;
|
|
80
|
+
/** The entry's lane, fixed at enqueue and re-supplied on every drive: one lane for every
|
|
81
|
+
* participant's log entry, pend and commit (`WriteIdentity.lane`, `HeadCommitOptions.lane`). */
|
|
82
|
+
readonly lane: Lane;
|
|
63
83
|
/** The collections the entry wrote, each of which must hold `entryId` as its HEAD sealed segment. */
|
|
64
84
|
readonly collectionIds: readonly CollectionId[];
|
|
65
85
|
/** Attempts an earlier `commitEntry` under this action id recorded through {@link recordAttempt}
|
|
@@ -82,12 +102,23 @@ export type EntryCommit = {
|
|
|
82
102
|
export type RefreshParticipant = {
|
|
83
103
|
readonly collectionId: CollectionId;
|
|
84
104
|
/** The refresh itself — `Collection.refreshInFlight` for a transaction's participant, the
|
|
85
|
-
* handle's `refresh` for an entry's — with the write's own report.
|
|
86
|
-
|
|
105
|
+
* handle's `refresh` for an entry's — with the write's own report. `tailFloor` is the highest
|
|
106
|
+
* revision a responder confirmed is taken under THIS collection, for the refresh's log-tail read
|
|
107
|
+
* (see `Collection.updateInternal`); `undefined` when no refusal of it carried one. */
|
|
108
|
+
refresh(report: RefreshReport, lastChance: boolean, tailFloor: number | undefined): Promise<void>;
|
|
87
109
|
/** Called after the refresh finished the write's own entry and the round recorded it as saved. */
|
|
88
110
|
saved?(): void;
|
|
89
111
|
};
|
|
90
112
|
|
|
113
|
+
/** What one participant's next attempt would request, for the stall check the coordinator's retry
|
|
114
|
+
* loop runs per participant (`RevisionStallWatch.check`): the revision it would request and the one
|
|
115
|
+
* it holds (`Collection.getNextRev` and `committedRevision`, or the handle's `nextRev` and `heldRev`). */
|
|
116
|
+
export type NextRevision = {
|
|
117
|
+
readonly collectionId: CollectionId;
|
|
118
|
+
readonly requestedRev: number;
|
|
119
|
+
readonly heldRev: number | undefined;
|
|
120
|
+
};
|
|
121
|
+
|
|
91
122
|
/**
|
|
92
123
|
* The handles of one entry's participants — a `HeadCommitHandle` per collection the entry wrote —
|
|
93
124
|
* and the moves the per-entry commit makes over all of them in lock-step. The handles are opened in
|
|
@@ -112,10 +143,10 @@ export class EntryParticipants {
|
|
|
112
143
|
* one twice (opening it twice would deadlock on its own latch) or names one `collections` does
|
|
113
144
|
* not hold; and closes the handles already opened when a later `openHeadCommit` throws (a
|
|
114
145
|
* `SealedSegmentsError` precondition, say), so no latch is left held. Every handle's cycle carries
|
|
115
|
-
* `cycle` ({@link InFlightCycle}), so a refresh that finishes a torn
|
|
116
|
-
* same terms the coordinator's own round sends it.
|
|
146
|
+
* `cycle` ({@link InFlightCycle}, whose lane is the entry's), so a refresh that finishes a torn
|
|
147
|
+
* attempt re-sends it on the same terms the coordinator's own round sends it.
|
|
117
148
|
*/
|
|
118
|
-
static async open(collections: ReadonlyMap<CollectionId, Collection<any>>, entry: EntryCommit, cycle: InFlightCycle = {}): Promise<EntryParticipants> {
|
|
149
|
+
static async open(collections: ReadonlyMap<CollectionId, Collection<any>>, entry: EntryCommit, cycle: Omit<InFlightCycle, 'lane'> = {}): Promise<EntryParticipants> {
|
|
119
150
|
if (entry.collectionIds.length === 0) {
|
|
120
151
|
throw new Error(`commitEntry ${entry.entryId}: an entry commit names at least one collection`);
|
|
121
152
|
}
|
|
@@ -136,7 +167,7 @@ export class EntryParticipants {
|
|
|
136
167
|
for (const { collectionId, collection } of participants) {
|
|
137
168
|
const resume = entry.resume?.get(collectionId);
|
|
138
169
|
handles.set(collectionId, await collection.openHeadCommit(entry.entryId,
|
|
139
|
-
{ actionId: entry.actionId, timestamp: entry.timestamp },
|
|
170
|
+
{ actionId: entry.actionId, timestamp: entry.timestamp, hlc: entry.hlc, lane: entry.lane },
|
|
140
171
|
{
|
|
141
172
|
...cycle,
|
|
142
173
|
...(resume === undefined ? {} : { resume }),
|
|
@@ -167,11 +198,21 @@ export class EntryParticipants {
|
|
|
167
198
|
refreshers(): RefreshParticipant[] {
|
|
168
199
|
return [...this.handles].map(([collectionId, handle]) => ({
|
|
169
200
|
collectionId,
|
|
170
|
-
refresh: (report, lastChance) => handle.refresh(report, lastChance),
|
|
201
|
+
refresh: (report, lastChance, tailFloor) => handle.refresh(report, lastChance, tailFloor),
|
|
171
202
|
saved: () => this.drop(collectionId),
|
|
172
203
|
}));
|
|
173
204
|
}
|
|
174
205
|
|
|
206
|
+
/** What every remaining participant's next attempt would request, in sorted order, for the retry
|
|
207
|
+
* loop's stall check. Read under the latches the handles hold, so nothing moves it meanwhile. */
|
|
208
|
+
nextRevisions(): NextRevision[] {
|
|
209
|
+
return [...this.handles].map(([collectionId, handle]) => ({
|
|
210
|
+
collectionId,
|
|
211
|
+
requestedRev: handle.nextRev(),
|
|
212
|
+
heldRev: handle.heldRev(),
|
|
213
|
+
}));
|
|
214
|
+
}
|
|
215
|
+
|
|
175
216
|
/** Build the attempt of every remaining participant, in sorted order, under the latches
|
|
176
217
|
* (`HeadCommitHandle.stage`). A throw — a participant's recorded refusal, a block too large to
|
|
177
218
|
* send — leaves nothing sent and nothing on any participant changed: an attempt is built on a
|
|
@@ -271,8 +312,9 @@ export class EntryParticipants {
|
|
|
271
312
|
}
|
|
272
313
|
|
|
273
314
|
/** The latch-acquisition order of `TransactionCoordinator.commitOnce` and `execute`, spelled the
|
|
274
|
-
* same way: a plain string comparison. Change all three together.
|
|
275
|
-
|
|
315
|
+
* same way: a plain string comparison. Change all three together. Also the order the retry loop's
|
|
316
|
+
* stall check visits participants in (`RetryBudget.assertNotStalled`), where only determinism matters. */
|
|
317
|
+
export function compareCollectionIds(a: CollectionId, b: CollectionId): number {
|
|
276
318
|
return a < b ? -1 : a > b ? 1 : 0;
|
|
277
319
|
}
|
|
278
320
|
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { CollectionId } from "../collection/index.js";
|
|
2
|
+
import type { ConfirmedRevision } from "../collection/write-attempts.js";
|
|
2
3
|
import type { WriteDurability } from "../network/struct.js";
|
|
3
4
|
import { transactionDurability, type TransactionDurability } from "./durability.js";
|
|
4
5
|
|
|
@@ -119,6 +120,13 @@ export class CoordinatorStaleLossError extends Error {
|
|
|
119
120
|
public readonly failedCollections: readonly CollectionId[],
|
|
120
121
|
/** The underlying stale/conflict reason surfaced by the failed pend/commit phase. */
|
|
121
122
|
public readonly reason?: string,
|
|
123
|
+
/** Per collection, the revision a responder CONFIRMED is committed under another action
|
|
124
|
+
* (`StaleFailure.staleAt`), for every failed collection whose refusal carried one. A collection
|
|
125
|
+
* refused with no confirmed number, cancelled because a sibling was refused, or refused in a
|
|
126
|
+
* batch whose number belongs to a sibling (see `staleAtOwner`) has no entry. Revisions are
|
|
127
|
+
* per-collection counters, which is why this is a map and not one number; the coordinator's
|
|
128
|
+
* retry loop reads each entry against its own collection's next revision (`RevisionStallWatch`). */
|
|
129
|
+
public readonly staleAtByCollection: ReadonlyMap<CollectionId, ConfirmedRevision> = new Map(),
|
|
122
130
|
) {
|
|
123
131
|
// Deliberately does not assert that nothing committed: this is also the internal signal a
|
|
124
132
|
// half-landed attempt retries on, and it then surfaces as a partial error's `reason`.
|
|
@@ -130,6 +138,58 @@ export class CoordinatorStaleLossError extends Error {
|
|
|
130
138
|
}
|
|
131
139
|
}
|
|
132
140
|
|
|
141
|
+
/**
|
|
142
|
+
* Thrown by {@link TransactionCoordinator.commit} and {@link TransactionCoordinator.commitEntry}
|
|
143
|
+
* when refreshing repeatedly moved one participant nowhere at all while a responder confirmed a
|
|
144
|
+
* revision at or above the one that participant's next attempt would request — the client's view
|
|
145
|
+
* of that collection disagrees with the cluster's, and retrying would re-send the identical taken
|
|
146
|
+
* number. The multi-collection counterpart of `SyncRevisionStalledError`, decided by the same rule
|
|
147
|
+
* per participant (`RevisionStallWatch` in `packages/db-core/src/collection/write-attempts.ts`,
|
|
148
|
+
* `SyncOptions.maxStalledAttempts` strikes), and reported as `commit:revision-stalled`.
|
|
149
|
+
*
|
|
150
|
+
* The distinction from plain stale-loss exhaustion matters because the two failures need different
|
|
151
|
+
* responses: a budget spent on lost races can succeed on a later try, where this one is provably
|
|
152
|
+
* identical on every remaining attempt, so the caller's view of {@link collectionId} has to be
|
|
153
|
+
* repaired first. The coordinator deliberately does NOT adopt the confirmed revision to get past
|
|
154
|
+
* it, for the reason `SyncRevisionStalledError` gives.
|
|
155
|
+
*
|
|
156
|
+
* Extends {@link CoordinatorStaleLossError} so existing catches keep working and
|
|
157
|
+
* `classifyCommitFailure` files it as `contention`, the choice `SyncRevisionStalledError` made by
|
|
158
|
+
* subclassing exhaustion. Like any error escaping the retry loop after a participant was saved, it
|
|
159
|
+
* surfaces inside a {@link CoordinatorPartialCommitError} as its `reason`.
|
|
160
|
+
*/
|
|
161
|
+
export class CoordinatorRevisionStalledError extends CoordinatorStaleLossError {
|
|
162
|
+
constructor(
|
|
163
|
+
/** The participant whose view is wedged. */
|
|
164
|
+
public readonly collectionId: CollectionId,
|
|
165
|
+
/** The confirmed revision the stall is based on: the block a responder named, and the
|
|
166
|
+
* revision it reported that block already committed at, under {@link collectionId}'s counter. */
|
|
167
|
+
public readonly staleAt: ConfirmedRevision,
|
|
168
|
+
/** The revision the participant's next attempt would have requested. */
|
|
169
|
+
public readonly requestedRev: number,
|
|
170
|
+
/** The revision this client holds for the participant; `undefined` for a collection that has
|
|
171
|
+
* committed nothing. */
|
|
172
|
+
public readonly heldRev: number | undefined,
|
|
173
|
+
/** Losses the commit took before stopping — attempts refused, and refresh rounds refused for a
|
|
174
|
+
* cause that can clear. */
|
|
175
|
+
public readonly attempts: number,
|
|
176
|
+
/** Every participant still to commit when the commit stopped, the wedged one included. */
|
|
177
|
+
failedCollections: readonly CollectionId[],
|
|
178
|
+
/** The last refusal's reason, when one was given. */
|
|
179
|
+
reason?: string,
|
|
180
|
+
) {
|
|
181
|
+
super(failedCollections, reason, new Map([[collectionId, staleAt]]));
|
|
182
|
+
// The base class's "lost a stale race" wording is deliberately NOT reused: it reads as
|
|
183
|
+
// ordinary contention, which is exactly the misdiagnosis this class exists to prevent.
|
|
184
|
+
this.message = `Multi-collection commit stopped after ${attempts} attempts: `
|
|
185
|
+
+ `this client holds rev ${heldRev ?? 'none'} of collection ${collectionId} and would request rev ${requestedRev}, `
|
|
186
|
+
+ `but block ${staleAt.blockId} is confirmed committed at rev ${staleAt.rev} and `
|
|
187
|
+
+ `refreshing did not close the gap`
|
|
188
|
+
+ (reason ? `: ${reason}` : '');
|
|
189
|
+
this.name = 'CoordinatorRevisionStalledError';
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
|
|
133
193
|
/**
|
|
134
194
|
* Thrown by {@link TransactionCoordinator.applyActions} and {@link TransactionCoordinator.commit}
|
|
135
195
|
* (and returned as a failure result by {@link TransactionCoordinator.execute}) when a second
|
package/src/transaction/index.ts
CHANGED
|
@@ -37,7 +37,7 @@ export {
|
|
|
37
37
|
export { ReadDependencyCollector } from './read-dependency-collector.js';
|
|
38
38
|
export { TransactionCoordinator } from './coordinator.js';
|
|
39
39
|
export type { CoordinatorOptions, PendValidationMode } from './coordinator.js';
|
|
40
|
-
export { CoordinatorConcurrentStampError, CoordinatorPartialCommitError, CoordinatorStaleLossError } from './errors.js';
|
|
40
|
+
export { CoordinatorConcurrentStampError, CoordinatorPartialCommitError, CoordinatorStaleLossError, CoordinatorRevisionStalledError } from './errors.js';
|
|
41
41
|
export { classifyCommitFailure, isCohortUnreachableRead, refusalReason } from './commit-failure-class.js';
|
|
42
42
|
export type { CommitFailureClass } from './commit-failure-class.js';
|
|
43
43
|
export { transactionDurability, recordCollectionDurability } from './durability.js';
|
|
@@ -88,11 +88,15 @@ export class TransactionSession {
|
|
|
88
88
|
actionsToApply = actions;
|
|
89
89
|
} else {
|
|
90
90
|
// Create a temporary transaction with just this statement for translation
|
|
91
|
+
// Temporary, for translation only: neither the id, the HLC nor the lane is ever read,
|
|
92
|
+
// since the engine translates statements here and commits nothing.
|
|
91
93
|
const tempTransaction: Transaction = {
|
|
92
94
|
stamp: this.stamp,
|
|
93
95
|
statements: [statement],
|
|
94
96
|
reads: [],
|
|
95
|
-
|
|
97
|
+
hlc: this.coordinator.clock.now(),
|
|
98
|
+
lane: 'serializable',
|
|
99
|
+
id: 'temp'
|
|
96
100
|
};
|
|
97
101
|
const result = await this.engine.execute(tempTransaction);
|
|
98
102
|
if (!result.success || !result.actions) {
|
|
@@ -139,22 +143,31 @@ export class TransactionSession {
|
|
|
139
143
|
|
|
140
144
|
// Collect read dependencies from all participating collections
|
|
141
145
|
const reads = this.coordinator.getReadDependencies();
|
|
146
|
+
// The HLC is minted AFTER the read set is final, so it sits above every HLC a read of this
|
|
147
|
+
// transaction observed (see Transaction.hlc), and once per transaction: the coordinator's
|
|
148
|
+
// retries re-send this same object.
|
|
149
|
+
const hlc = this.coordinator.clock.now();
|
|
150
|
+
// The lane is the caller's classification of the whole transaction (`SyncOptions.lane`, one
|
|
151
|
+
// lane over every participant), and `serializable` for an engine that declared nothing.
|
|
152
|
+
const lane = options?.lane ?? 'serializable';
|
|
142
153
|
|
|
143
154
|
// Create the complete transaction
|
|
144
155
|
const transaction: Transaction = {
|
|
145
156
|
stamp: this.stamp,
|
|
146
157
|
statements: this.statements,
|
|
147
158
|
reads,
|
|
148
|
-
|
|
159
|
+
hlc,
|
|
160
|
+
lane,
|
|
161
|
+
id: await createTransactionId(this.stamp.id, this.statements, reads, hlc, lane)
|
|
149
162
|
};
|
|
150
163
|
|
|
151
|
-
// Sign the canonical client-signature payload if a signer was supplied. The
|
|
152
|
-
//
|
|
164
|
+
// Sign the canonical client-signature payload if a signer was supplied. The payload covers
|
|
165
|
+
// stamp.id + statements + reads + hlc + lane, which are all final now. A signer failure
|
|
153
166
|
// (e.g. a wrong-key-type libp2p sign) is caught and surfaced as a clean commit failure BEFORE
|
|
154
167
|
// coordinator.commit runs — the transaction object is local and discarded, so a failed sign can
|
|
155
168
|
// never leak a partially-built unsigned transaction into consensus.
|
|
156
169
|
if (this.signer) {
|
|
157
|
-
const payload = clientSignaturePayload(this.stamp.id, this.statements, reads);
|
|
170
|
+
const payload = clientSignaturePayload(this.stamp.id, this.statements, reads, hlc, lane);
|
|
158
171
|
try {
|
|
159
172
|
transaction.signature = await this.signer(payload);
|
|
160
173
|
} catch (error) {
|
|
@@ -3,6 +3,8 @@ import { toString as uint8ArrayToString } from "uint8arrays/to-string";
|
|
|
3
3
|
import type { BlockId } from "../blocks/index.js";
|
|
4
4
|
import type { CollectionId } from "../collection/index.js";
|
|
5
5
|
import type { TransactionDurability } from "./durability.js";
|
|
6
|
+
import type { Hlc } from "../hlc/hlc.js";
|
|
7
|
+
import type { Lane } from "../lane/lane.js";
|
|
6
8
|
import { hashString } from "../utility/hash-string.js";
|
|
7
9
|
|
|
8
10
|
/**
|
|
@@ -62,14 +64,47 @@ export type Transaction = {
|
|
|
62
64
|
/** Read dependencies for optimistic concurrency control */
|
|
63
65
|
reads: ReadDependency[];
|
|
64
66
|
|
|
65
|
-
/**
|
|
67
|
+
/**
|
|
68
|
+
* The transaction's hybrid logical clock value (docs/crdt-sync.md §Migration Path, Stage 1):
|
|
69
|
+
* minted at COMMIT, after the read set is final, from the committing transactor's clock
|
|
70
|
+
* (`clockOf(transactor).now()`), and stamped on every participant's log entry (`LogEntry.hlc`,
|
|
71
|
+
* through `WriteContext.hlc`). On the transaction rather than the stamp because the stamp is
|
|
72
|
+
* fixed at BEGIN, before any of the transaction's reads, and an HLC minted then could sit below
|
|
73
|
+
* one a later read observed — the causal rule the HLC exists to keep. Folded into {@link id} and
|
|
74
|
+
* into the client signature ({@link clientSignaturePayload}), so a relaying peer cannot alter
|
|
75
|
+
* it; excluded from nothing else. Fixed per transaction: a retry of the same `Transaction` object
|
|
76
|
+
* re-sends it, like `stamp.timestamp`.
|
|
77
|
+
*
|
|
78
|
+
* Required of every transaction this build builds; a validator meeting one from an older build
|
|
79
|
+
* on the wire tolerates its absence at that one ingress (`TransactionValidator.validate`).
|
|
80
|
+
*/
|
|
81
|
+
hlc: Hlc;
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* The transaction's lane (`Lane` in `packages/db-core/src/lane/lane.ts`): whether its conflicts
|
|
85
|
+
* with other machines' concurrent writes are the quorum's to decide (`serializable`) or may be
|
|
86
|
+
* merged later under each collection's declaration (`convergent`). ONE lane for every
|
|
87
|
+
* participant: a transaction over several collections takes the stricter of its parts, decided by
|
|
88
|
+
* the caller before the transaction is built (`TransactionSession.commit` takes it from
|
|
89
|
+
* `SyncOptions.lane`, `serializable` when the engine declared nothing), and stamped on every
|
|
90
|
+
* participant's log entry (`ActionEntry.lane`, through `WriteContext.lane`) and on every pend and
|
|
91
|
+
* commit of it. Folded into {@link id} and into the client signature
|
|
92
|
+
* ({@link clientSignaturePayload}), so a relaying peer cannot alter it. Nothing admits by it yet.
|
|
93
|
+
*
|
|
94
|
+
* Required of every transaction this build builds; a validator meeting one from an older build
|
|
95
|
+
* on the wire tolerates its absence at that one ingress as `serializable`
|
|
96
|
+
* (`TransactionValidator.validate`), every write then having been serializable.
|
|
97
|
+
*/
|
|
98
|
+
lane: Lane;
|
|
99
|
+
|
|
100
|
+
/** Transaction identifier (hash of stamp.id + statements + reads + hlc + lane)
|
|
66
101
|
* Final transaction identity, used in logs
|
|
67
102
|
*/
|
|
68
103
|
id: string;
|
|
69
104
|
|
|
70
105
|
/**
|
|
71
106
|
* Optional client signature (base64url) over {@link clientSignaturePayload}
|
|
72
|
-
* `(stamp.id, statements, reads)`, produced at commit by an injected
|
|
107
|
+
* `(stamp.id, statements, reads, hlc, lane)`, produced at commit by an injected
|
|
73
108
|
* {@link TransactionSigner}.
|
|
74
109
|
*
|
|
75
110
|
* A node that wires a {@link ClientSignatureVerifier} into its
|
|
@@ -226,8 +261,9 @@ export async function createTransactionStamp(
|
|
|
226
261
|
}
|
|
227
262
|
|
|
228
263
|
/**
|
|
229
|
-
* Create a transaction id from stamp id, statements, and
|
|
230
|
-
* This is the final transaction identity used in logs
|
|
264
|
+
* Create a transaction id from stamp id, statements, reads, the transaction's HLC and its lane.
|
|
265
|
+
* This is the final transaction identity used in logs, and the action id the log records, so two
|
|
266
|
+
* transactions that differ only in when they committed, or in the lane they claim, differ in id.
|
|
231
267
|
*
|
|
232
268
|
* NOTE: reads are serialized in their given order here (non-canonical). This differs
|
|
233
269
|
* from {@link clientSignaturePayload}, which canonicalises reads before hashing. That is
|
|
@@ -236,15 +272,17 @@ export async function createTransactionStamp(
|
|
|
236
272
|
* design-consensus-hygiene-notes), NOT fixed here to avoid changing existing tx ids.
|
|
237
273
|
*
|
|
238
274
|
* NOTE: {@link Transaction.priority} is deliberately absent from this preimage — the id is a pure
|
|
239
|
-
* function of `(stampId, statements, reads)`, so two retry attempts that differ only in
|
|
240
|
-
* priority produce the SAME id. Do not add priority here.
|
|
275
|
+
* function of `(stampId, statements, reads, hlc, lane)`, so two retry attempts that differ only in
|
|
276
|
+
* aged priority produce the SAME id. Do not add priority here.
|
|
241
277
|
*/
|
|
242
278
|
export async function createTransactionId(
|
|
243
279
|
stampId: string,
|
|
244
280
|
statements: string[],
|
|
245
|
-
reads: ReadDependency[]
|
|
281
|
+
reads: ReadDependency[],
|
|
282
|
+
hlc: Hlc,
|
|
283
|
+
lane: Lane
|
|
246
284
|
): Promise<string> {
|
|
247
|
-
const txData = JSON.stringify({ stampId, statements, reads });
|
|
285
|
+
const txData = JSON.stringify({ stampId, statements, reads, hlc: canonicalHlc(hlc), lane });
|
|
248
286
|
return `tx:${await hashString(txData)}`;
|
|
249
287
|
}
|
|
250
288
|
|
|
@@ -252,18 +290,31 @@ export async function createTransactionId(
|
|
|
252
290
|
* Version prefix for the client-signature payload, so the signed form can evolve
|
|
253
291
|
* without ambiguity. Distinct from (but consistent in spirit with) the operations-hash
|
|
254
292
|
* canonical form — this covers transaction INPUTS, not operations.
|
|
293
|
+
*
|
|
294
|
+
* `v2` added the transaction's HLC to the signed bytes, and `v3` its lane. Mixed-version cost, the
|
|
295
|
+
* same for both bumps: a writer on an earlier build signs the old payload, and a verifier on this
|
|
296
|
+
* build reports `Invalid client signature` against it. Accepted on the precedent the validity marker
|
|
297
|
+
* set (docs/internals.md, *A reject that judges the transaction itself wrong*), because no deployment
|
|
298
|
+
* wires a `ClientSignatureVerifier` today (backlog `feat-no-deployment-validates-transactions-at-pend`),
|
|
299
|
+
* and because the question "can a relaying peer alter the HLC, or the lane a write claims" is best
|
|
300
|
+
* settled while nothing verifies.
|
|
255
301
|
*/
|
|
256
|
-
export const CLIENT_SIG_VERSION = 'txsig:
|
|
302
|
+
export const CLIENT_SIG_VERSION = 'txsig:v3';
|
|
257
303
|
|
|
258
304
|
/**
|
|
259
305
|
* Canonical bytes a client signs and a node verifies. Deterministic: reads are sorted
|
|
260
|
-
* (blockId, then revision); statements keep their sequential order
|
|
306
|
+
* (blockId, then revision); statements keep their sequential order; the HLC's three fields are
|
|
307
|
+
* written in a fixed order; the lane is one of two literal strings.
|
|
261
308
|
*
|
|
262
|
-
* Binds
|
|
263
|
-
* nonce), the EXACT statements,
|
|
264
|
-
* binding" for anti-replay)
|
|
265
|
-
*
|
|
266
|
-
*
|
|
309
|
+
* Binds five things at once: the CLIENT IDENTITY (via `stampId`, which hashes peerId +
|
|
310
|
+
* nonce), the EXACT statements, the OCC read set (blockId + revision — "tail
|
|
311
|
+
* binding" for anti-replay), the transaction's HLC, which validators order by in a later
|
|
312
|
+
* stage and a relaying peer must therefore not be able to alter, and the lane the writer claims,
|
|
313
|
+
* which a member checks against the collections' declarations in a later stage and a relaying peer
|
|
314
|
+
* must not be able to loosen. Both signer and verifier derive the bytes from
|
|
315
|
+
* `transaction.stamp.id` + `transaction.statements` + `transaction.reads` + `transaction.hlc` +
|
|
316
|
+
* `transaction.lane` through this one function, so they reproduce identical bytes regardless of
|
|
317
|
+
* read ordering.
|
|
267
318
|
*
|
|
268
319
|
* NOTE: {@link Transaction.priority} is deliberately absent from the signed bytes — a retry that
|
|
269
320
|
* only bumps priority keeps the same signature, so anti-replay / OCC binding never churns. Do not
|
|
@@ -272,16 +323,25 @@ export const CLIENT_SIG_VERSION = 'txsig:v1';
|
|
|
272
323
|
export function clientSignaturePayload(
|
|
273
324
|
stampId: string,
|
|
274
325
|
statements: readonly string[],
|
|
275
|
-
reads: readonly ReadDependency[]
|
|
326
|
+
reads: readonly ReadDependency[],
|
|
327
|
+
hlc: Hlc,
|
|
328
|
+
lane: Lane
|
|
276
329
|
): Uint8Array {
|
|
277
330
|
const canonicalReads = [...reads].sort(
|
|
278
331
|
(a, b) => a.blockId < b.blockId ? -1 : a.blockId > b.blockId ? 1
|
|
279
332
|
: a.revision - b.revision
|
|
280
333
|
);
|
|
281
|
-
const body = JSON.stringify({ stampId, statements, reads: canonicalReads });
|
|
334
|
+
const body = JSON.stringify({ stampId, statements, reads: canonicalReads, hlc: canonicalHlc(hlc), lane });
|
|
282
335
|
return new TextEncoder().encode(`${CLIENT_SIG_VERSION}:${body}`);
|
|
283
336
|
}
|
|
284
337
|
|
|
338
|
+
/** The HLC's three fields in one fixed key order, so the two preimages above do not depend on the
|
|
339
|
+
* key order of whatever object carried the value — a JSON round trip preserves order, but a value
|
|
340
|
+
* rebuilt by hand need not. */
|
|
341
|
+
function canonicalHlc(hlc: Hlc): Hlc {
|
|
342
|
+
return { wallMs: hlc.wallMs, logical: hlc.logical, nodeId: hlc.nodeId };
|
|
343
|
+
}
|
|
344
|
+
|
|
285
345
|
/**
|
|
286
346
|
* Signs the canonical client-signature payload, returning base64url. Async to allow
|
|
287
347
|
* libp2p `PrivateKey.sign`; tests pass a synchronous fake.
|
|
@@ -353,6 +413,18 @@ export interface ITransactionEngine {
|
|
|
353
413
|
* @returns The resulting actions from execution
|
|
354
414
|
*/
|
|
355
415
|
execute(transaction: Transaction): Promise<ExecutionResult>;
|
|
416
|
+
|
|
417
|
+
/**
|
|
418
|
+
* The strictest lane this engine's catalog allows the transaction's statements: `serializable`
|
|
419
|
+
* when any statement's write must be ordered by the quorum, else `convergent`. What a
|
|
420
|
+
* {@link TransactionValidator} checks a `convergent` claim against (docs/transactions.md §Which
|
|
421
|
+
* lane a transaction takes), so it must be computable identically by every machine whose schema
|
|
422
|
+
* hash matches the writer's, from the statements as replicated — never from what only the writer
|
|
423
|
+
* saw (a key's provenance, a value read). Omitted by an engine with no catalog to classify against
|
|
424
|
+
* ({@link ActionsEngine}), whose transactions' lanes a validator then accepts unchecked; a throw
|
|
425
|
+
* means this node could not judge.
|
|
426
|
+
*/
|
|
427
|
+
laneCeiling?(transaction: Transaction): Promise<Lane>;
|
|
356
428
|
}
|
|
357
429
|
|
|
358
430
|
/**
|
|
@@ -476,6 +548,7 @@ export interface ITransactionValidator {
|
|
|
476
548
|
* 0.5. Verify the client signature (only if a signature verifier is wired)
|
|
477
549
|
* 1. Verify stamp.engineId matches a known engine
|
|
478
550
|
* 2. Verify stamp.schemaHash matches local schema
|
|
551
|
+
* 2.5. Verify a `convergent` lane claim against the engine's ceiling (only if the engine offers one)
|
|
479
552
|
* 3. Verify read dependencies (no stale reads)
|
|
480
553
|
* 4. Re-execute transaction.statements through engine (isolated state)
|
|
481
554
|
* 5. Collect operations from re-execution
|
|
@@ -3,6 +3,7 @@ import type { Transaction, ITransactionEngine, ITransactionValidator, Validation
|
|
|
3
3
|
import type { BlockActionState } from '../network/struct.js';
|
|
4
4
|
import { isTransactionExpired, clientSignaturePayload, computeStampId } from './transaction.js';
|
|
5
5
|
import { collectOperations, hashOperations, opsHashVersion, OPS_HASH_VERSION } from './operations-hash.js';
|
|
6
|
+
import { legacyHlc } from '../hlc/hlc.js';
|
|
6
7
|
|
|
7
8
|
/**
|
|
8
9
|
* Engine registration for validation.
|
|
@@ -50,11 +51,12 @@ function validityRefusal(reason: string, computedHash?: string): ValidationResul
|
|
|
50
51
|
* Used by cluster participants when receiving PendRequests.
|
|
51
52
|
*
|
|
52
53
|
* Every refusal is classed, because a writer and the dispute path act on the class and must never
|
|
53
|
-
* read the prose to find it.
|
|
54
|
+
* read the prose to find it. Six refusals judge the transaction itself wrong and carry
|
|
54
55
|
* `validity` ({@link validityRefusal}): a tampered stamp, a missing or invalid client signature, a
|
|
55
|
-
* failed re-execution, and an operations-hash mismatch. The rest carry none: an
|
|
56
|
-
* clock judgement), a stale read (out of date — a re-read can win), and an unknown
|
|
57
|
-
* mismatch or an operations-hash format this node does not produce (this node
|
|
56
|
+
* lane mismatch, a failed re-execution, and an operations-hash mismatch. The rest carry none: an
|
|
57
|
+
* expired stamp (a clock judgement), a stale read (out of date — a re-read can win), and an unknown
|
|
58
|
+
* engine, a schema mismatch or an operations-hash format this node does not produce (this node
|
|
59
|
+
* cannot judge).
|
|
58
60
|
*/
|
|
59
61
|
export class TransactionValidator implements ITransactionValidator {
|
|
60
62
|
constructor(
|
|
@@ -92,7 +94,16 @@ export class TransactionValidator implements ITransactionValidator {
|
|
|
92
94
|
if (transaction.signature === undefined) {
|
|
93
95
|
return validityRefusal('Missing client signature');
|
|
94
96
|
}
|
|
95
|
-
|
|
97
|
+
// The one wire ingress that tolerates a transaction without an HLC or a lane: a writer on
|
|
98
|
+
// a build before either field. Its payload is derived from the stamp's time and the lane
|
|
99
|
+
// every write then took (`serializable`) so the check is well-typed; such a writer signed
|
|
100
|
+
// the `txsig:v1` or `v2` bytes, so it is refused here regardless (see CLIENT_SIG_VERSION
|
|
101
|
+
// for the accepted mixed-version cost). The derived values are used for this check only:
|
|
102
|
+
// the transaction object is handed on unchanged, never rewritten with a value its writer
|
|
103
|
+
// did not stamp.
|
|
104
|
+
const hlc = transaction.hlc ?? legacyHlc(stamp.timestamp);
|
|
105
|
+
const lane = transaction.lane ?? 'serializable';
|
|
106
|
+
const payload = clientSignaturePayload(stamp.id, transaction.statements, transaction.reads, hlc, lane);
|
|
96
107
|
if (!this.verifyClientSignature(stamp.peerId, payload, transaction.signature)) {
|
|
97
108
|
return validityRefusal('Invalid client signature');
|
|
98
109
|
}
|
|
@@ -116,6 +127,12 @@ export class TransactionValidator implements ITransactionValidator {
|
|
|
116
127
|
};
|
|
117
128
|
}
|
|
118
129
|
|
|
130
|
+
// 2.5. Check the lane the transaction claims. Here because the ceiling reads only the
|
|
131
|
+
// statements and the catalog step 2 just proved equal, and needs no re-execution.
|
|
132
|
+
if (await this.claimsLaneAboveCeiling(transaction, registration.engine)) {
|
|
133
|
+
return validityRefusal('Lane mismatch: transaction claims convergent, this node computes serializable');
|
|
134
|
+
}
|
|
135
|
+
|
|
119
136
|
// 3. Verify read dependencies (optimistic concurrency)
|
|
120
137
|
if (this.blockStateProvider && transaction.reads.length > 0) {
|
|
121
138
|
for (const read of transaction.reads) {
|
|
@@ -199,6 +216,30 @@ export class TransactionValidator implements ITransactionValidator {
|
|
|
199
216
|
}
|
|
200
217
|
}
|
|
201
218
|
|
|
219
|
+
/**
|
|
220
|
+
* Whether `transaction` claims `convergent` where this node's engine computes `serializable`
|
|
221
|
+
* (docs/transactions.md §Which lane a transaction takes). The classification is the writer's
|
|
222
|
+
* engine's; this node never reclassifies, it only refuses a claim it can disprove. Only a
|
|
223
|
+
* `convergent` claim is checked, since `serializable` is always acceptable; an absent lane (a
|
|
224
|
+
* writer on a build before the field) is `serializable`; an engine without `laneCeiling` is not
|
|
225
|
+
* asked. A throw out of the engine propagates: the node could not judge, which the pend check in
|
|
226
|
+
* db-p2p turns into an unmarked `validator-fault` reject.
|
|
227
|
+
*
|
|
228
|
+
* The bound of the check: the ceiling is what every machine with the writer's schema computes
|
|
229
|
+
* from the replicated statements alone, and an honest writer's lane is at or below it. What only
|
|
230
|
+
* the writer saw is not in the replicated statements — a key's provenance, a value it read, and
|
|
231
|
+
* for Quereus's rebuilt statements which columns an UPDATE assigned — so a writer that lies about
|
|
232
|
+
* those passes here; the replay stage's guards are what catch that, at merge time.
|
|
233
|
+
*
|
|
234
|
+
* NOTE: no deployment validates at pend today (backlog
|
|
235
|
+
* `feat-no-deployment-validates-transactions-at-pend`), so this runs only where a validator is
|
|
236
|
+
* wired by hand — db-p2p's mesh specs and unit tests.
|
|
237
|
+
*/
|
|
238
|
+
private async claimsLaneAboveCeiling(transaction: Transaction, engine: ITransactionEngine): Promise<boolean> {
|
|
239
|
+
if (transaction.lane !== 'convergent' || engine.laneCeiling === undefined) return false;
|
|
240
|
+
return await engine.laneCeiling(transaction) === 'serializable';
|
|
241
|
+
}
|
|
242
|
+
|
|
202
243
|
async getSchemaHash(engineId: string): Promise<string | undefined> {
|
|
203
244
|
const registration = this.engines.get(engineId);
|
|
204
245
|
return registration ? await registration.getSchemaHash() : undefined;
|
|
@@ -56,7 +56,8 @@ export interface BlockFloorCheck {
|
|
|
56
56
|
*
|
|
57
57
|
* Raised where log entries are consumed (`Collection.updateInternal`) and checked where answers
|
|
58
58
|
* arrive (`TransactorSource.tryGet`). A floor, once raised, STANDS for the life of the handle: an
|
|
59
|
-
* answer that meets it does not remove it.
|
|
59
|
+
* answer that meets it does not remove it. The one thing that does is the handle adopting another
|
|
60
|
+
* lineage ({@link clear}).
|
|
60
61
|
*
|
|
61
62
|
* Why a met floor is not dropped. The source that judges an answer cannot know whether any cache
|
|
62
63
|
* went on to keep it, and "an answer met the floor" is not "the cache now holds that answer": the
|
|
@@ -93,6 +94,19 @@ export class BlockFloors implements BlockFloorCheck {
|
|
|
93
94
|
}
|
|
94
95
|
}
|
|
95
96
|
|
|
97
|
+
/** Drop every floor. Only for a handle that has learned its floors describe a history the network
|
|
98
|
+
* does not hold — a refresh adopting another lineage (`Collection.forgetAndAdopt`). A floor raised
|
|
99
|
+
* under the old lineage says nothing about the new one, where the block may legitimately sit below
|
|
100
|
+
* it, and a standing floor would then make every read of the block a below-floor answer for the
|
|
101
|
+
* life of the handle. The exception to "a floor, once raised, stands".
|
|
102
|
+
*
|
|
103
|
+
* Every read source the handle built shares these floors, so a pinned read view created before
|
|
104
|
+
* the drop loses its floors too. It reads at the old boundary of the old lineage, which the
|
|
105
|
+
* network does not hold either, so the floors it loses bound content no machine will serve it. */
|
|
106
|
+
clear(): void {
|
|
107
|
+
this.floors.clear();
|
|
108
|
+
}
|
|
109
|
+
|
|
96
110
|
applicableTo(blockId: BlockId, context: ActionContext | undefined): BlockFloor | undefined {
|
|
97
111
|
const floor = this.floors.get(blockId);
|
|
98
112
|
return floor !== undefined && (context === undefined || context.rev >= floor.rev) ? floor : undefined;
|