@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
package/src/log/struct.ts
CHANGED
|
@@ -1,9 +1,24 @@
|
|
|
1
1
|
import type { BlockId, CollectionId, ActionContext, ActionId, ActionRev, ReadDependency } from "../index.js";
|
|
2
|
+
import { legacyHlc, type Hlc } from "../hlc/hlc.js";
|
|
3
|
+
import type { Lane } from "../lane/lane.js";
|
|
2
4
|
|
|
3
5
|
/** A log entry - an action, a checkpoint, or an invalidation */
|
|
4
6
|
export type LogEntry<TAction> = {
|
|
5
|
-
/**
|
|
7
|
+
/** The wall-clock time the writer's clock read when it wrote the entry. Informational: nothing
|
|
8
|
+
* orders by it. Kept beside {@link hlc}, which is a second fact, not this one twice — its `wallMs`
|
|
9
|
+
* is at or above this and may be a future time after the writer's clock observed a jump. */
|
|
6
10
|
readonly timestamp: number;
|
|
11
|
+
/**
|
|
12
|
+
* The hybrid logical clock value the writer minted for the write this entry records
|
|
13
|
+
* (docs/crdt-sync.md §Migration Path, Stage 1). Minted once per write and re-sent verbatim by
|
|
14
|
+
* every retry, like {@link timestamp}; one value for every entry of a multi-collection write.
|
|
15
|
+
* Nothing orders by it yet — the revision is the order within a collection — but it is what a
|
|
16
|
+
* later merge of divergent histories orders by, and the entry is the unit such a merge orders.
|
|
17
|
+
*
|
|
18
|
+
* Every entry this build writes carries it. A STORED entry written before the field existed lacks
|
|
19
|
+
* it; read an entry's HLC through {@link hlcOf}, never off the field.
|
|
20
|
+
*/
|
|
21
|
+
readonly hlc: Hlc;
|
|
7
22
|
/** Revision number - monotonically increasing from the prior entry's rev. Starts at 1. */
|
|
8
23
|
readonly rev: number;
|
|
9
24
|
readonly action?: ActionEntry<TAction>;
|
|
@@ -22,6 +37,20 @@ export type ActionEntry<TAction> = {
|
|
|
22
37
|
blockIds: BlockId[]; // NOTE: this is updated after being generated to include the log-related block transforms
|
|
23
38
|
/** Other collection ids affected by the action - this action is conditional on successful commit in all of these collections */
|
|
24
39
|
readonly collectionIds?: CollectionId[];
|
|
40
|
+
/**
|
|
41
|
+
* The write's lane (`Lane` in `packages/db-core/src/lane/lane.ts`): whether its conflicts with
|
|
42
|
+
* other machines' concurrent writes are decided by the quorum and the revision order
|
|
43
|
+
* (`serializable`) or may be merged later under the collection's declaration (`convergent`).
|
|
44
|
+
* Minted once per write beside the action id, timestamp and HLC (`WriteIdentity.lane`,
|
|
45
|
+
* `Transaction.lane`), and re-sent verbatim by every retry; one lane for every entry of a
|
|
46
|
+
* multi-collection write. On the action entry rather than the log entry because a checkpoint has
|
|
47
|
+
* no lane and an invalidation reverses an action under the strong rules. Nothing admits by it yet.
|
|
48
|
+
*
|
|
49
|
+
* Every entry this build writes carries it. A STORED entry written before the field existed lacks
|
|
50
|
+
* it (every write then was serializable); read an entry's lane through {@link laneOf}, never off
|
|
51
|
+
* the field.
|
|
52
|
+
*/
|
|
53
|
+
readonly lane: Lane;
|
|
25
54
|
/**
|
|
26
55
|
* The `(blockId, revision)` reads this transaction observed during execution — the same
|
|
27
56
|
* read set the {@link Transaction} carried in its PEND request (see `Transaction.reads`).
|
|
@@ -156,10 +185,42 @@ export type CheckpointEntry = {
|
|
|
156
185
|
readonly pendings: ActionRev[];
|
|
157
186
|
};
|
|
158
187
|
|
|
188
|
+
/**
|
|
189
|
+
* The one reader rule for an entry's HLC: the field when the entry carries one, else the legacy
|
|
190
|
+
* value derived from its timestamp (`legacyHlc`: the wall time, no logical count, the empty node
|
|
191
|
+
* id). The parameter admits an absent field because a stored entry written before the field existed
|
|
192
|
+
* has none, whatever {@link LogEntry} declares about the entries this build writes.
|
|
193
|
+
*/
|
|
194
|
+
export function hlcOf(entry: { readonly timestamp: number; readonly hlc?: Hlc }): Hlc {
|
|
195
|
+
return entry.hlc ?? legacyHlc(entry.timestamp);
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
/**
|
|
199
|
+
* The one reader rule for an action entry's lane: the field when the entry carries one, else
|
|
200
|
+
* `serializable`, since every write made before the field existed took the quorum lane. The
|
|
201
|
+
* parameter admits an absent field because a stored entry written before the field existed has
|
|
202
|
+
* none, whatever {@link ActionEntry} declares about the entries this build writes.
|
|
203
|
+
*
|
|
204
|
+
* NOTE: `ActionEntry.lane` is declared required while a stored legacy entry lacks it, so a reader
|
|
205
|
+
* that takes the field directly compiles and meets `undefined` on such an entry — the same tripwire
|
|
206
|
+
* `hlcOf` records for `LogEntry.hlc`. Read through here. Splitting the stored and written shapes
|
|
207
|
+
* into two types was declined for one reader; if a second direct reader ever appears, split then.
|
|
208
|
+
*/
|
|
209
|
+
export function laneOf(entry: { readonly lane?: Lane }): Lane {
|
|
210
|
+
return entry.lane ?? 'serializable';
|
|
211
|
+
}
|
|
212
|
+
|
|
159
213
|
export const LogDataBlockType = "LGD";
|
|
160
214
|
export const LogHeaderBlockType = "LGH";
|
|
161
215
|
|
|
162
216
|
export type GetFromResult<TAction> = {
|
|
163
217
|
context: ActionContext | undefined;
|
|
164
218
|
entries: ActionEntry<TAction>[];
|
|
219
|
+
/**
|
|
220
|
+
* The highest HLC ({@link hlcOf}) among every entry the walk read — action, checkpoint and
|
|
221
|
+
* invalidation entries alike, the ones below `startRev` it read to find its way included — so the
|
|
222
|
+
* reader's clock can observe it (docs/crdt-sync.md §Migration Path, Stage 1). One value rather than
|
|
223
|
+
* one per entry, since the clock keeps only a maximum. Absent when the walk read no entry.
|
|
224
|
+
*/
|
|
225
|
+
hlcHighWater?: Hlc;
|
|
165
226
|
};
|
package/src/network/i-repo.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import type { ActionBlocks, BlockContentDigests, CommitResult, GetBlockResults, PendResult, PendRequest, BlockGets, BlockId, ActionId } from "../index.js";
|
|
1
|
+
import type { ActionBlocks, BlockContentDigests, CommitResult, GetBlockResults, PendResult, PendRequest, BlockGets, BlockId, ActionId, CommitRequest } from "../index.js";
|
|
2
|
+
import type { Lane } from "../lane/lane.js";
|
|
2
3
|
|
|
3
4
|
export type MessageOptions = {
|
|
4
5
|
expiration?: number;
|
|
@@ -29,12 +30,21 @@ export type MessageOptions = {
|
|
|
29
30
|
* call, where there is no asker to stand in for.
|
|
30
31
|
*/
|
|
31
32
|
asker?: string;
|
|
33
|
+
/**
|
|
34
|
+
* Answer a read from this node's own storage alone: no cohort consult, and no consult-derived
|
|
35
|
+
* flag. Set by every block-repair answer (an archive, a consult answer, a lineage answer), so a
|
|
36
|
+
* peer reports what it holds itself, never what its cohort says. Never sent.
|
|
37
|
+
*/
|
|
38
|
+
skipClusterFetch?: boolean;
|
|
32
39
|
}
|
|
33
40
|
|
|
34
41
|
export type RepoCommitRequest = {
|
|
35
42
|
blockIds: BlockId[];
|
|
36
43
|
actionId: ActionId;
|
|
37
44
|
rev: number;
|
|
45
|
+
/** The write's lane ({@link CommitRequest.lane}), carried onto every per-block commit the
|
|
46
|
+
* transactor sends; absent on bare per-block paths and for an older writer. */
|
|
47
|
+
lane?: Lane;
|
|
38
48
|
/**
|
|
39
49
|
* The collection's chain tail block id (the {@link CommitRequest.tailId}). Optional on the per-block
|
|
40
50
|
* repo operation: the transactor threads the committing collection's tail through every per-block
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { BlockId } from "../index.js";
|
|
1
2
|
import type { ActionId, ActionRev } from "../collection/action.js";
|
|
2
3
|
import type { ExpiredFailure, RejectedFailure, ShortfallFailure, StaleFailure, WriteFailure } from "./struct.js";
|
|
3
4
|
|
|
@@ -67,13 +68,12 @@ export function isRejectedFailure(failure: WriteFailure): failure is RejectedFai
|
|
|
67
68
|
* NOTE: comparing revisions across blocks is meaningful only within one collection, where every
|
|
68
69
|
* candidate comes from the same revision counter. A batch (`IRepo.pendMany` / `commitMany`) spans
|
|
69
70
|
* collections, and `CoordinatorRepo` still picks the highest across them, so its `staleAt` names the
|
|
70
|
-
* block — and so the collection — of one loser among several counters.
|
|
71
|
-
*
|
|
72
|
-
*
|
|
73
|
-
*
|
|
74
|
-
*
|
|
75
|
-
*
|
|
76
|
-
* per-collection.
|
|
71
|
+
* block — and so the collection — of one loser among several counters. The multi-collection
|
|
72
|
+
* coordinator, the only writer that sends a batch, therefore attributes a batched answer's number by
|
|
73
|
+
* its block id ({@link staleAtOwner}): the collection owning `staleAt.blockId` gets the number, and
|
|
74
|
+
* every other collection of the batch is treated as refused with no confirmed number. The other
|
|
75
|
+
* collections' losses are understated by that, never overstated — a number is only ever compared
|
|
76
|
+
* against the counter it came from.
|
|
77
77
|
*/
|
|
78
78
|
export function highestStaleAt(candidates: readonly StaleFailure['staleAt'][]): StaleFailure['staleAt'] {
|
|
79
79
|
let best: StaleFailure['staleAt'];
|
|
@@ -85,6 +85,30 @@ export function highestStaleAt(candidates: readonly StaleFailure['staleAt'][]):
|
|
|
85
85
|
return best;
|
|
86
86
|
}
|
|
87
87
|
|
|
88
|
+
/**
|
|
89
|
+
* The single rule for attributing a {@link StaleFailure.staleAt} that answered a request spanning
|
|
90
|
+
* several collections: the one collection whose blocks include `staleAt.blockId`, or `undefined`
|
|
91
|
+
* when no candidate owns it (a block none of them sent, or no number at all).
|
|
92
|
+
*
|
|
93
|
+
* A revision is a per-collection counter, so the number is meaningful only against the counter of
|
|
94
|
+
* the collection that owns the block it names. A request for ONE collection needs no attribution —
|
|
95
|
+
* its number is that collection's whatever block it names — so this is for the batched answer
|
|
96
|
+
* (`IRepo.pendMany` / `commitMany`), where `CoordinatorRepo` reports one number, the highest across
|
|
97
|
+
* the batch's collections ({@link highestStaleAt}), and only the owner of the named block may count
|
|
98
|
+
* it as its own.
|
|
99
|
+
*/
|
|
100
|
+
export function staleAtOwner<Owner>(staleAt: StaleFailure['staleAt'], blocksByOwner: ReadonlyMap<Owner, readonly BlockId[]>): Owner | undefined {
|
|
101
|
+
if (staleAt === undefined) {
|
|
102
|
+
return undefined;
|
|
103
|
+
}
|
|
104
|
+
for (const [owner, blockIds] of blocksByOwner) {
|
|
105
|
+
if (blockIds.includes(staleAt.blockId)) {
|
|
106
|
+
return owner;
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
return undefined;
|
|
110
|
+
}
|
|
111
|
+
|
|
88
112
|
/**
|
|
89
113
|
* The single rule for "is the action holding this revision OUR OWN?" — true only when `latest`
|
|
90
114
|
* names exactly the revision being requested AND the same action requesting it.
|
package/src/network/struct.ts
CHANGED
|
@@ -2,6 +2,8 @@ import type { CollectionId, BlockId, IBlock, ActionId, Transform, Transforms } f
|
|
|
2
2
|
import type { ActionContext, ActionRev } from "../collection/action.js";
|
|
3
3
|
import type { Transaction, ValidityRejection } from "../transaction/transaction.js";
|
|
4
4
|
import type { DisputeResolutionProof } from "../log/struct.js";
|
|
5
|
+
import type { Hlc } from "../hlc/hlc.js";
|
|
6
|
+
import type { Lane } from "../lane/lane.js";
|
|
5
7
|
import type { PeerId } from "./types.js";
|
|
6
8
|
|
|
7
9
|
export type ActionBlocks = {
|
|
@@ -54,6 +56,31 @@ export type PendRequest = ActionTransforms & {
|
|
|
54
56
|
};
|
|
55
57
|
/** For multi-collection transactions: supercluster nominees for consensus */
|
|
56
58
|
superclusterNominees?: PeerId[];
|
|
59
|
+
/**
|
|
60
|
+
* The HLC of the write this pend carries (`LogEntry.hlc`, `Transaction.hlc`): the same value the
|
|
61
|
+
* log entry inside `transforms` carries, put here so a storage node observes the HLC of every
|
|
62
|
+
* write it stores without parsing log blocks out of transforms (docs/crdt-sync.md §Migration
|
|
63
|
+
* Path, Stage 1). The writer always sets it (`TransactorSource.transact`,
|
|
64
|
+
* `TransactionCoordinator.pendRequestFor`); optional on the wire because an older writer sends
|
|
65
|
+
* none, and because the re-send of a retained attempt has none at hand. Observational: a member
|
|
66
|
+
* reads it into its clock and never judges the pend by it. Omitted rather than `undefined`, for
|
|
67
|
+
* the same preimage reason as {@link baseRevs}.
|
|
68
|
+
*/
|
|
69
|
+
hlc?: Hlc;
|
|
70
|
+
/**
|
|
71
|
+
* The lane of the write this pend carries (`ActionEntry.lane`, `Transaction.lane`): whether its
|
|
72
|
+
* conflicts with concurrent writes are the quorum's to decide (`serializable`) or may be merged
|
|
73
|
+
* later under the collection's declaration (`convergent`) — see `Lane` in
|
|
74
|
+
* `packages/db-core/src/lane/lane.ts`. The same value the log entry inside `transforms` carries,
|
|
75
|
+
* put here so a storage node reads it without parsing log blocks. Every writer of this build sets
|
|
76
|
+
* it (`TransactorSource.transact`, `TransactionCoordinator.pendRequestFor`); optional on the wire
|
|
77
|
+
* because an older writer sends none. A reader treats absence as "not stated", never as a lane.
|
|
78
|
+
* Observational: nothing judges the pend by it — a validating member checks the lane the
|
|
79
|
+
* transaction inside {@link validation} claims (`TransactionValidator.validate`) — and the
|
|
80
|
+
* coordinator's solo log lines report it. Omitted rather than `undefined`, for the same preimage
|
|
81
|
+
* reason as {@link baseRevs}.
|
|
82
|
+
*/
|
|
83
|
+
lane?: Lane;
|
|
57
84
|
/**
|
|
58
85
|
* Aged, advisory retry priority for a pend that carries no transaction (default 0 when absent).
|
|
59
86
|
* A validated multi-collection pend instead carries priority on the transaction inside
|
|
@@ -474,6 +501,14 @@ export type CommitRequest = ActionBlocks & {
|
|
|
474
501
|
* {@link blockDigests} is.
|
|
475
502
|
*/
|
|
476
503
|
refuseSolo?: true;
|
|
504
|
+
/**
|
|
505
|
+
* {@link PendRequest.lane}, on the commit, so a coordinator handling the commit reads the write's
|
|
506
|
+
* lane with no memory of the pend. Carried through every per-coordinator rebuild of the commit
|
|
507
|
+
* (`repoCommitRequest` in `NetworkTransactor`); optional on the wire for an older writer, and
|
|
508
|
+
* absence is "not stated". Omitted rather than `undefined`, for the preimage reason
|
|
509
|
+
* {@link blockDigests} is.
|
|
510
|
+
*/
|
|
511
|
+
lane?: Lane;
|
|
477
512
|
};
|
|
478
513
|
|
|
479
514
|
/**
|
|
@@ -576,6 +611,21 @@ export type BlockGets = {
|
|
|
576
611
|
* reads as `unknown`. Asked only by a writer deciding whether its own superseded write is saved
|
|
577
612
|
* (`ITransactor.getLineage`); an ordinary read never sets it. */
|
|
578
613
|
lineageOf?: ActionRev;
|
|
614
|
+
/** The asker does not want this read to start the read-repair consult that the lazy window alone
|
|
615
|
+
* would run BEHIND the read: a held block whose window has expired (or that the lazy mode's
|
|
616
|
+
* `readRepairSampleRate` picked for a re-check) is answered from the answering repo's own copy and
|
|
617
|
+
* no cohort consult is started for it. An effort hint, never a correctness one —
|
|
618
|
+
* the doubt an earlier consult recorded still stamps `unconfirmedAheadRev`, and the window's
|
|
619
|
+
* freshness stamp is untouched, so the next read without the flag consults as before.
|
|
620
|
+
*
|
|
621
|
+
* It never skips a consult whose answer the read depends on: a block missing locally (the absence
|
|
622
|
+
* verdict), a held block whose read carries a floor above it ({@link floors}), and every consult
|
|
623
|
+
* under `'paranoid'` read-repair still run and still block. Whole-read, so `NetworkTransactor.get`
|
|
624
|
+
* forwards it on every batch: a remote coordinator also skips its own background consult. A peer
|
|
625
|
+
* that predates the field ignores it and consults as before. Meant for the node's watch tick,
|
|
626
|
+
* through `Collection.readCommittedTails`, which reads every watched tail on a timer. Distinct from
|
|
627
|
+
* `skipClusterFetch`, the sync protocol's guard, which skips every consult and never flags. */
|
|
628
|
+
skipWindowConsult?: true;
|
|
579
629
|
};
|
|
580
630
|
|
|
581
631
|
/**
|
package/src/offline/entry.ts
CHANGED
|
@@ -4,6 +4,8 @@ import type { Collection } from '../collection/collection.js';
|
|
|
4
4
|
import type { EntryId } from '../collection/segments.js';
|
|
5
5
|
import type { CollectionId, InFlightAttempt } from '../collection/struct.js';
|
|
6
6
|
import type { WriteDurability } from '../network/struct.js';
|
|
7
|
+
import type { Hlc } from '../hlc/hlc.js';
|
|
8
|
+
import type { Lane } from '../lane/lane.js';
|
|
7
9
|
import type { CommittedEffect, EntryStatus, EntryWaitingFor, QueuedEntry } from './status.js';
|
|
8
10
|
import type { JournalDriveState } from './journal.js';
|
|
9
11
|
|
|
@@ -12,6 +14,18 @@ export type Entry = {
|
|
|
12
14
|
readonly id: EntryId;
|
|
13
15
|
readonly seq: number;
|
|
14
16
|
readonly queuedAt: number;
|
|
17
|
+
/** The local commit time as an HLC (`JournalEntryRecord.hlc`): minted at enqueue from the sealed
|
|
18
|
+
* collections' transactor clock, restored from the journal, and passed to every drive of the entry
|
|
19
|
+
* as the write's HLC. Fixed for the entry's whole life, like `queuedAt` — a renewed action id
|
|
20
|
+
* does not renew it, since the entry is the same local commit. */
|
|
21
|
+
readonly hlc: Hlc;
|
|
22
|
+
/** The entry's lane (`JournalEntryRecord.lane`): the caller's classification at enqueue, or the
|
|
23
|
+
* stricter of the sealed collections' own declarations over their segments, restored from the
|
|
24
|
+
* journal, and passed to every drive as the write's lane. Fixed for the entry's whole life, like
|
|
25
|
+
* `hlc`: a later change to a collection's declaration, or to a SQL table's tags, does not
|
|
26
|
+
* reclassify an entry already queued — its lane is what was true of its statements when the
|
|
27
|
+
* application made them. */
|
|
28
|
+
readonly lane: Lane;
|
|
15
29
|
readonly expiresAt: number | undefined;
|
|
16
30
|
/** The collections the entry sealed a segment in — the ones `sealPending` answered `true` for. */
|
|
17
31
|
readonly collections: readonly Collection<any>[];
|
|
@@ -56,6 +70,7 @@ export function queuedStatus(entry: Entry): QueuedStatus {
|
|
|
56
70
|
seq: entry.seq,
|
|
57
71
|
collections: entry.collections.map(collection => collection.id),
|
|
58
72
|
queuedAt: entry.queuedAt,
|
|
73
|
+
lane: entry.lane,
|
|
59
74
|
attempts: entry.attempts,
|
|
60
75
|
inDoubt: entry.inDoubt,
|
|
61
76
|
waitingFor: entry.waitingFor,
|
|
@@ -82,6 +97,7 @@ export function snapshot(entry: Entry): QueuedEntry {
|
|
|
82
97
|
id: entry.id,
|
|
83
98
|
seq: entry.seq,
|
|
84
99
|
queuedAt: entry.queuedAt,
|
|
100
|
+
lane: entry.lane,
|
|
85
101
|
collections: entry.collections.map(collection => collection.id),
|
|
86
102
|
...committedField(entry),
|
|
87
103
|
status: currentStatus(entry),
|
package/src/offline/journal.ts
CHANGED
|
@@ -2,6 +2,8 @@ import type { Action, ActionId } from '../collection/action.js';
|
|
|
2
2
|
import type { EntryId } from '../collection/segments.js';
|
|
3
3
|
import type { CollectionId, InFlightAttempt } from '../collection/struct.js';
|
|
4
4
|
import type { WriteDurability } from '../network/struct.js';
|
|
5
|
+
import type { Hlc } from '../hlc/hlc.js';
|
|
6
|
+
import type { Lane } from '../lane/lane.js';
|
|
5
7
|
import type { EntryStatus } from './status.js';
|
|
6
8
|
|
|
7
9
|
/**
|
|
@@ -21,6 +23,14 @@ export type JournalEntryRecord = {
|
|
|
21
23
|
readonly id: EntryId;
|
|
22
24
|
readonly seq: number;
|
|
23
25
|
readonly queuedAt: number;
|
|
26
|
+
/** The entry's local commit time as an HLC, minted at enqueue and carried on every log entry the
|
|
27
|
+
* entry's drives append (`HeadCommitOptions.hlc`, `EntryCommit.hlc`), so a restore re-supplies the
|
|
28
|
+
* value the first drive used. */
|
|
29
|
+
readonly hlc: Hlc;
|
|
30
|
+
/** The entry's lane, fixed at enqueue and carried on every log entry, pend and commit the entry's
|
|
31
|
+
* drives make (`HeadCommitOptions.lane`, `EntryCommit.lane`), so a restore re-supplies the value the
|
|
32
|
+
* first drive used rather than reclassifying the entry under declarations that may have changed. */
|
|
33
|
+
readonly lane: Lane;
|
|
24
34
|
readonly expiresAt?: number;
|
|
25
35
|
/** One per collection the entry sealed a segment in, in sealing order: the segment's actions,
|
|
26
36
|
* verbatim — the array the segment holds, which the journal serialises and never mutates. */
|
package/src/offline/queue.ts
CHANGED
|
@@ -6,6 +6,9 @@ import { ActionRefusedError, SealedSegmentsError } from '../collection/struct.js
|
|
|
6
6
|
import type { CollectionId, InFlightAttempt, SyncOptions } from '../collection/struct.js';
|
|
7
7
|
import type { AlreadyAppliedTally } from '../collection/action.js';
|
|
8
8
|
import type { ITransactor } from '../transactor/transactor.js';
|
|
9
|
+
import { clockOf } from '../hlc/clock.js';
|
|
10
|
+
import type { Hlc } from '../hlc/hlc.js';
|
|
11
|
+
import { stricterLane, type Lane } from '../lane/lane.js';
|
|
9
12
|
import { TransactionCoordinator } from '../transaction/coordinator.js';
|
|
10
13
|
import { classifyCommitFailure, refusalReason } from '../transaction/commit-failure-class.js';
|
|
11
14
|
import { recordCollectionDurability, transactionDurability } from '../transaction/durability.js';
|
|
@@ -73,6 +76,12 @@ export type RestoreInit = {
|
|
|
73
76
|
readonly id: EntryId;
|
|
74
77
|
readonly seq: number;
|
|
75
78
|
readonly queuedAt: number;
|
|
79
|
+
/** The record's HLC (`JournalEntryRecord.hlc`); a record written before the field existed is
|
|
80
|
+
* restored with `legacyHlc(queuedAt)`, the one shape a legacy entry already has. */
|
|
81
|
+
readonly hlc: Hlc;
|
|
82
|
+
/** The record's lane (`JournalEntryRecord.lane`); a record written before the field existed is
|
|
83
|
+
* restored as `serializable`, the lane every entry then took. */
|
|
84
|
+
readonly lane: Lane;
|
|
76
85
|
readonly expiresAt?: number;
|
|
77
86
|
/** The collections the entry sealed a segment in, in the record's order — `stage` is called for
|
|
78
87
|
* each, in this order. */
|
|
@@ -140,21 +149,29 @@ function entryDurability(entry: Entry, written: TransactionDurability | undefine
|
|
|
140
149
|
* is its own storage); the queue's callers never seal such a set together, so this is a defect that
|
|
141
150
|
* stops the drain rather than a failure of the entry.
|
|
142
151
|
*/
|
|
143
|
-
function sharedTransactor(
|
|
152
|
+
function sharedTransactor(entryId: EntryId, remaining: readonly Collection<any>[]): ITransactor {
|
|
144
153
|
const transactor = remaining[0]!.transactor;
|
|
145
154
|
const stranger = remaining.find(collection => collection.transactor !== transactor);
|
|
146
155
|
if (stranger !== undefined) {
|
|
147
|
-
throw new Error(`offline queue: entry ${
|
|
156
|
+
throw new Error(`offline queue: entry ${entryId} spans collections on different transactors (${remaining[0]!.id} and ${stranger.id}); an entry is one network transaction on one transactor`);
|
|
148
157
|
}
|
|
149
158
|
return transactor;
|
|
150
159
|
}
|
|
151
160
|
|
|
161
|
+
/** The lane of an entry nobody classified: the stricter of each sealed collection's own declaration
|
|
162
|
+
* over the segment it sealed under `entryId` (`Collection.laneOf`). */
|
|
163
|
+
function sealedLaneOf(sealed: readonly Collection<any>[], entryId: EntryId): Lane {
|
|
164
|
+
return stricterLane(sealed.map(collection => collection.laneOf(collection.sealedActions(entryId) ?? [])));
|
|
165
|
+
}
|
|
166
|
+
|
|
152
167
|
/** The journal's entry record for `entry`, built from each sealed collection's segment. */
|
|
153
168
|
function entryRecord(entry: Entry): JournalEntryRecord {
|
|
154
169
|
return {
|
|
155
170
|
id: entry.id,
|
|
156
171
|
seq: entry.seq,
|
|
157
172
|
queuedAt: entry.queuedAt,
|
|
173
|
+
hlc: entry.hlc,
|
|
174
|
+
lane: entry.lane,
|
|
158
175
|
...(entry.expiresAt === undefined ? {} : { expiresAt: entry.expiresAt }),
|
|
159
176
|
segments: entry.collections.map(collection => {
|
|
160
177
|
const actions = collection.sealedActions(entry.id);
|
|
@@ -294,7 +311,7 @@ export class OfflineQueue {
|
|
|
294
311
|
*
|
|
295
312
|
* @throws QueueDisposedError after {@link dispose}; the drain's defect, as `cause`, once the
|
|
296
313
|
* drain has stopped on one (nothing queued then would ever drain); whatever the journal threw. */
|
|
297
|
-
async enqueue(collections: readonly Collection<any>[], init?: { id?: EntryId; timestamp?: number }): Promise<QueuedEntry | undefined> {
|
|
314
|
+
async enqueue(collections: readonly Collection<any>[], init?: { id?: EntryId; timestamp?: number; hlc?: Hlc; lane?: Lane }): Promise<QueuedEntry | undefined> {
|
|
298
315
|
this.assertAccepting();
|
|
299
316
|
const id = init?.id ?? mintId();
|
|
300
317
|
if (this.byId.has(id)) throw new Error(`entry ${id} is already queued`);
|
|
@@ -305,6 +322,17 @@ export class OfflineQueue {
|
|
|
305
322
|
id,
|
|
306
323
|
seq: this.nextSeq,
|
|
307
324
|
queuedAt,
|
|
325
|
+
// The local commit time in HLC form, from the clock the entry will be sent through. Minted
|
|
326
|
+
// here, once, so every drive of the entry — first or re-drive, after a restart or not —
|
|
327
|
+
// appends the same entry. Read off the first sealed collection rather than through
|
|
328
|
+
// `sharedTransactor`, whose stranger check must not fail an enqueue that has already sealed:
|
|
329
|
+
// it runs, and throws, at the send.
|
|
330
|
+
hlc: init?.hlc ?? clockOf(sealed[0]!.transactor).now(),
|
|
331
|
+
// The caller's classification when it gave one (the SQL bridge's, from the statements), else
|
|
332
|
+
// the stricter of the sealed collections' own declarations over what each sealed. Fixed here
|
|
333
|
+
// for the entry's life and journaled: a reclassification later would make a re-drive differ
|
|
334
|
+
// from the attempt it repeats.
|
|
335
|
+
lane: init?.lane ?? sealedLaneOf(sealed, id),
|
|
308
336
|
expiresAt: this.expireAfterMs === undefined ? undefined : queuedAt + this.expireAfterMs,
|
|
309
337
|
collections: sealed,
|
|
310
338
|
actionId: mintId(),
|
|
@@ -732,19 +760,23 @@ export class OfflineQueue {
|
|
|
732
760
|
...submit,
|
|
733
761
|
actionId: entry.actionId,
|
|
734
762
|
timestamp: entry.queuedAt,
|
|
763
|
+
hlc: entry.hlc,
|
|
764
|
+
lane: entry.lane,
|
|
735
765
|
recordAttempt: attempt => recordAttempt(new Map([[collection.id, attempt]])),
|
|
736
766
|
onCommittedHead: applied => onCommittedHead(collection.id, applied),
|
|
737
767
|
...(resume === undefined ? {} : { resume }),
|
|
738
768
|
});
|
|
739
769
|
return transactionDurability(new Map([[collection.id, written]]));
|
|
740
770
|
}
|
|
741
|
-
const coordinator = new TransactionCoordinator(sharedTransactor(entry, remaining),
|
|
771
|
+
const coordinator = new TransactionCoordinator(sharedTransactor(entry.id, remaining),
|
|
742
772
|
new Map(remaining.map(collection => [collection.id, collection])), { pendValidation: 'none' });
|
|
743
773
|
const resume = new Map([...entry.retained].filter(([collectionId]) => remaining.some(collection => collection.id === collectionId)));
|
|
744
774
|
return coordinator.commitEntry({
|
|
745
775
|
entryId: entry.id,
|
|
746
776
|
actionId: entry.actionId,
|
|
747
777
|
timestamp: entry.queuedAt,
|
|
778
|
+
hlc: entry.hlc,
|
|
779
|
+
lane: entry.lane,
|
|
748
780
|
collectionIds: remaining.map(collection => collection.id),
|
|
749
781
|
recordAttempt,
|
|
750
782
|
onCommittedHead,
|
|
@@ -1058,6 +1090,8 @@ export class OfflineQueue {
|
|
|
1058
1090
|
id: init.id,
|
|
1059
1091
|
seq: init.seq,
|
|
1060
1092
|
queuedAt: init.queuedAt,
|
|
1093
|
+
hlc: init.hlc,
|
|
1094
|
+
lane: init.lane,
|
|
1061
1095
|
expiresAt: init.expiresAt,
|
|
1062
1096
|
collections: init.collections,
|
|
1063
1097
|
actionId: drive?.actionId ?? mintId(),
|
package/src/offline/status.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import type { CollectionId } from '../collection/struct.js';
|
|
2
2
|
import type { EntryId } from '../collection/segments.js';
|
|
3
3
|
import type { TransactionDurability } from '../transaction/durability.js';
|
|
4
|
+
import type { Lane } from '../lane/lane.js';
|
|
4
5
|
|
|
5
6
|
/**
|
|
6
7
|
* The status an offline-sync queue reports for each entry (docs/offline-sync.md §Following
|
|
@@ -42,6 +43,10 @@ export type EntryStatus =
|
|
|
42
43
|
/** The collections the entry sealed a segment in — every collection it changed. */
|
|
43
44
|
collections: readonly CollectionId[];
|
|
44
45
|
queuedAt: number;
|
|
46
|
+
/** The entry's lane (`Lane` in `packages/db-core/src/lane/lane.ts`): whether a later merge
|
|
47
|
+
* will handle it (`convergent`) or the cohort must agree to it (`serializable`). Fixed at
|
|
48
|
+
* enqueue for the entry's whole life, so it is never announced on its own. */
|
|
49
|
+
lane: Lane;
|
|
45
50
|
/** Submissions made so far. */
|
|
46
51
|
attempts: number;
|
|
47
52
|
/** Whether an attempt may have landed (see `OfflineQueue`'s in-doubt rule): such an entry can
|
|
@@ -115,6 +120,8 @@ export type QueuedEntry = {
|
|
|
115
120
|
readonly id: EntryId;
|
|
116
121
|
readonly seq: number;
|
|
117
122
|
readonly queuedAt: number;
|
|
123
|
+
/** As on the `queued` status. */
|
|
124
|
+
readonly lane: Lane;
|
|
118
125
|
readonly collections: readonly CollectionId[];
|
|
119
126
|
/** As on the `queued` status: the collections already committed, once part of the entry is. */
|
|
120
127
|
readonly committedCollections?: readonly CollectionId[];
|