@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
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.
|