@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/log.ts
CHANGED
|
@@ -1,310 +1,341 @@
|
|
|
1
|
-
import { sha256 } from 'multiformats/hashes/sha2'
|
|
2
|
-
import { Chain, entryAt } from "../chain/chain.js";
|
|
3
|
-
import { nameof } from "../utility/nameof.js";
|
|
4
|
-
import type { IBlock, BlockId, ActionId, CollectionId, ChainPath, ActionRev, ActionContext, ChainInitOptions, BlockStore, ReadDependency } from "../index.js";
|
|
5
|
-
import type { ChainDataNode } from '../chain/chain-nodes.js';
|
|
6
|
-
import type { LogEntry, ActionEntry, DisputeResolutionProof, InvalidationEntry, RevertedBlock } from "./index.js";
|
|
7
|
-
import { LogDataBlockType, LogHeaderBlockType } from "./struct.js";
|
|
8
|
-
import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
|
|
9
|
-
import type { GetFromResult } from './struct.js';
|
|
10
|
-
import {
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
*
|
|
24
|
-
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
}
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
*
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
*
|
|
64
|
-
*
|
|
65
|
-
*
|
|
66
|
-
* Defaults to `Date.now()` for a caller that appends once.
|
|
67
|
-
*/
|
|
68
|
-
timestamp?: number;
|
|
69
|
-
};
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
/**
|
|
82
|
-
*
|
|
83
|
-
*
|
|
84
|
-
*
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
}
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
const
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
}
|
|
126
|
-
|
|
127
|
-
/**
|
|
128
|
-
*
|
|
129
|
-
*
|
|
130
|
-
*
|
|
131
|
-
*
|
|
132
|
-
*
|
|
133
|
-
*/
|
|
134
|
-
async
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
rev
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
*
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
}
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
1
|
+
import { sha256 } from 'multiformats/hashes/sha2'
|
|
2
|
+
import { Chain, entryAt } from "../chain/chain.js";
|
|
3
|
+
import { nameof } from "../utility/nameof.js";
|
|
4
|
+
import type { IBlock, BlockId, ActionId, CollectionId, ChainPath, ActionRev, ActionContext, ChainInitOptions, BlockStore, ReadDependency } from "../index.js";
|
|
5
|
+
import type { ChainDataNode } from '../chain/chain-nodes.js';
|
|
6
|
+
import type { LogEntry, ActionEntry, DisputeResolutionProof, InvalidationEntry, RevertedBlock } from "./index.js";
|
|
7
|
+
import { LogDataBlockType, LogHeaderBlockType, hlcOf } from "./struct.js";
|
|
8
|
+
import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
|
|
9
|
+
import type { GetFromResult } from './struct.js';
|
|
10
|
+
import { maxHlc, type Hlc } from '../hlc/hlc.js';
|
|
11
|
+
import type { Lane } from '../lane/lane.js';
|
|
12
|
+
import { BLOCK_TARGET_BYTES } from '../network/block-size.js';
|
|
13
|
+
|
|
14
|
+
export type LogBlock<TAction> = ChainDataNode<LogEntry<TAction>>
|
|
15
|
+
& {
|
|
16
|
+
/** Base64url encoded Sha256 hash of the prior (predecessor) block - present on every block except the head */
|
|
17
|
+
priorHash?: string,
|
|
18
|
+
};
|
|
19
|
+
|
|
20
|
+
export const priorHash$ = nameof<LogBlock<any>>("priorHash");
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Canonical byte payload covered by {@link LogBlock.priorHash}: every field of a log block EXCEPT
|
|
24
|
+
* the mutable structural links (`nextId`/`priorId`). Those links are rewritten *after* the hash is
|
|
25
|
+
* taken — `nextId` when the following block is appended ({@link Chain.add}), and `priorId`/`nextId`
|
|
26
|
+
* when blocks are removed ({@link Chain.pop}/{@link Chain.dequeue}) — so hashing the raw block would
|
|
27
|
+
* not match the bytes that end up stored. The content-bearing fields (`header`, `entries`,
|
|
28
|
+
* `priorHash`) are covered. Any verifier that re-hashes a stored block to check `priorHash` MUST
|
|
29
|
+
* reproduce exactly this payload (strip `nextId` and `priorId`; hash the rest).
|
|
30
|
+
*
|
|
31
|
+
* NOTE: the caller hashes `JSON.stringify` of this object, which is key-order dependent and not a
|
|
32
|
+
* canonical encoding. Fine today (blocks are built with a stable key order and the in-process store
|
|
33
|
+
* preserves it), but if a block is ever re-serialized by a store/codec that reorders keys or drops
|
|
34
|
+
* `undefined`s differently, a re-hash won't match the recorded priorHash — switch to a canonical
|
|
35
|
+
* encoding (sorted keys / dag-cbor) before that happens.
|
|
36
|
+
*/
|
|
37
|
+
export function logBlockHashPayload<TAction>(block: LogBlock<TAction>) {
|
|
38
|
+
const { nextId, priorId, ...covered } = block;
|
|
39
|
+
return covered;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** What {@link Log.open} may be told beyond the block it opens. */
|
|
43
|
+
export type LogOpenOptions = {
|
|
44
|
+
/** Supplies the id for each data block an append mints, in place of a fresh random one. */
|
|
45
|
+
newDataBlockId?: () => BlockId;
|
|
46
|
+
};
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* The two per-write time values every entry kind carries (`LogEntry.hlc` and `LogEntry.timestamp`),
|
|
50
|
+
* taken by {@link Log.addActions}, {@link Log.addCheckpoint} and {@link Log.addInvalidation} alike.
|
|
51
|
+
*
|
|
52
|
+
* Both belong to the WRITE, not to the attempt. Storage identifies a saved block revision by
|
|
53
|
+
* `(action id, revision)` and accepts a retry of the same action at the same revision, so a value a
|
|
54
|
+
* retry minted afresh would store a second, different log block under one `(action, revision)` on
|
|
55
|
+
* every machine that missed the first attempt (docs/internals.md, "A write's log append is a fixed
|
|
56
|
+
* function of the write and the revision it is requesting").
|
|
57
|
+
*/
|
|
58
|
+
export type EntryTimes = {
|
|
59
|
+
/** The HLC the writer minted for the write (`clockOf(transactor).now()`), re-sent verbatim by every
|
|
60
|
+
* retry. No default: the clock is the writer's, and an append has none of its own. */
|
|
61
|
+
hlc: Hlc;
|
|
62
|
+
/**
|
|
63
|
+
* When the entry was written. Nothing in the tree reads it for logic — it is informational —
|
|
64
|
+
* which is what makes it safe for a writer to supply the time of the WRITE rather than of the
|
|
65
|
+
* attempt, and arguably the more honest value. A writer whose attempt may be retried MUST supply
|
|
66
|
+
* it, for the reason above. Defaults to `Date.now()` for a caller that appends once.
|
|
67
|
+
*/
|
|
68
|
+
timestamp?: number;
|
|
69
|
+
};
|
|
70
|
+
|
|
71
|
+
/** The trailing inputs to {@link Log.addActions}: the write's {@link EntryTimes} plus the two
|
|
72
|
+
* optional fields an action entry alone carries. An options object rather than positional
|
|
73
|
+
* parameters because a caller that needs only the times should not have to spell out the rest. */
|
|
74
|
+
export type AddActionsOptions = EntryTimes & {
|
|
75
|
+
/** The write's lane (`ActionEntry.lane`), minted once per write by the same rule as the times
|
|
76
|
+
* above and re-sent verbatim by every retry. No default: the lane is the write's, decided by the
|
|
77
|
+
* caller's classification or the collection's declaration, and an append has none of its own. */
|
|
78
|
+
lane: Lane;
|
|
79
|
+
/** Every collection participating in the action this entry records. */
|
|
80
|
+
collectionIds?: CollectionId[];
|
|
81
|
+
/** The transaction's `(blockId, revision)` read set, persisted on the entry so the invalidation
|
|
82
|
+
* cascade can later discover this action's read-dependents (see {@link ActionEntry.reads}).
|
|
83
|
+
* Omit it on the low-level direct-commit path that carries no `Transaction`; the cascade then
|
|
84
|
+
* treats the entry as an unknown dependency. */
|
|
85
|
+
reads?: ReadDependency[];
|
|
86
|
+
};
|
|
87
|
+
|
|
88
|
+
/** The trailing inputs to {@link Log.addInvalidation}: the write's {@link EntryTimes}, and the root
|
|
89
|
+
* invalidation when this entry is a cascade step. */
|
|
90
|
+
export type AddInvalidationOptions = EntryTimes & {
|
|
91
|
+
/** The root invalidation that triggered this cascade step; absent for a root invalidation
|
|
92
|
+
* (see {@link InvalidationEntry.cascadeRoot}). */
|
|
93
|
+
cascadeRoot?: ActionId;
|
|
94
|
+
};
|
|
95
|
+
|
|
96
|
+
export class Log<TAction> {
|
|
97
|
+
protected constructor(
|
|
98
|
+
private readonly chain: Chain<LogEntry<TAction>>,
|
|
99
|
+
) {
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
get id() {
|
|
103
|
+
return this.chain.id;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/** Opens a presumably existing log.
|
|
107
|
+
*
|
|
108
|
+
* `options.newDataBlockId` supplies the id for each data block an append has to mint, in place
|
|
109
|
+
* of a fresh random one. A writer whose attempt may be RETRIED passes a source that hands back
|
|
110
|
+
* the ids its earlier attempt minted, so the retry's transforms are byte-identical to the
|
|
111
|
+
* attempt it repeats (see {@link Collection.logAppendBlockIds}); everything else omits it and
|
|
112
|
+
* mints at random exactly as before. */
|
|
113
|
+
static async open<TAction>(store: BlockStore<IBlock>, id: BlockId, options?: LogOpenOptions): Promise<Log<TAction> | undefined> {
|
|
114
|
+
const chain = await Chain.open<LogEntry<TAction>>(store, id, Log.getChainOptions(store, options?.newDataBlockId));
|
|
115
|
+
return chain ? new Log<TAction>(chain) : undefined;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/** Creates a new log. */
|
|
119
|
+
static async create<TAction>(store: BlockStore<IBlock>, options?: { newId?: BlockId; existingHeaderId?: BlockId }) {
|
|
120
|
+
return new Log<TAction>(await Chain.create<LogEntry<TAction>>(store, {
|
|
121
|
+
...Log.getChainOptions(store),
|
|
122
|
+
newId: options?.newId,
|
|
123
|
+
existingHeaderId: options?.existingHeaderId,
|
|
124
|
+
}));
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* Adds a new action entry to the log.
|
|
129
|
+
*
|
|
130
|
+
* See {@link AddActionsOptions} for what the trailing options carry, and in particular why a
|
|
131
|
+
* writer that may retry passes its own `hlc` and `timestamp` rather than letting each attempt
|
|
132
|
+
* take its own.
|
|
133
|
+
*/
|
|
134
|
+
async addActions(actions: TAction[], actionId: ActionId, rev: number, getBlockIds: () => BlockId[], options: AddActionsOptions) {
|
|
135
|
+
const { collectionIds = [], reads, hlc, lane, timestamp = Date.now() } = options;
|
|
136
|
+
const action = reads !== undefined
|
|
137
|
+
? { actionId, actions, blockIds: [], collectionIds, lane, reads }
|
|
138
|
+
: { actionId, actions, blockIds: [], collectionIds, lane };
|
|
139
|
+
const entry = { timestamp, hlc, rev, action } as LogEntry<TAction>;
|
|
140
|
+
const tailPath = await this.chain.add(entry);
|
|
141
|
+
const entryWithBlockIds = { ...entry, action: { ...entry.action!, blockIds: getBlockIds() } };
|
|
142
|
+
this.chain.updateAt(tailPath, entryWithBlockIds);
|
|
143
|
+
return { entry: entryWithBlockIds, tailPath };
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/** Adds a checkpoint to the log, under the write's {@link EntryTimes}. */
|
|
147
|
+
async addCheckpoint(pendings: ActionRev[], rev: number, times: EntryTimes) {
|
|
148
|
+
const { hlc, timestamp = Date.now() } = times;
|
|
149
|
+
const entry = { timestamp, hlc, rev, checkpoint: { pendings } };
|
|
150
|
+
const tailPath = await this.chain.add(entry);
|
|
151
|
+
return { entry, tailPath };
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/**
|
|
155
|
+
* Appends a compensating invalidation entry that reverses a previously-committed action proven
|
|
156
|
+
* invalid by dispute. The committed history is never rewritten — this is a new, append-only,
|
|
157
|
+
* prior-hash-linked entry, recoverable on sync exactly like a commit. The caller has already
|
|
158
|
+
* verified `resolution` is a challenger-wins certificate and computed the per-block `reverted`
|
|
159
|
+
* targets (the new revisions restoring the as-if-`T_inv`-absent content). The entry carries the
|
|
160
|
+
* applying node's {@link EntryTimes} like every other entry kind.
|
|
161
|
+
*/
|
|
162
|
+
async addInvalidation(
|
|
163
|
+
invalidatedActionId: ActionId,
|
|
164
|
+
invalidatedRev: number,
|
|
165
|
+
resolution: DisputeResolutionProof,
|
|
166
|
+
reverted: ReadonlyArray<RevertedBlock>,
|
|
167
|
+
rev: number,
|
|
168
|
+
options: AddInvalidationOptions
|
|
169
|
+
) {
|
|
170
|
+
const { hlc, timestamp = Date.now(), cascadeRoot } = options;
|
|
171
|
+
const invalidation: InvalidationEntry = cascadeRoot !== undefined
|
|
172
|
+
? { invalidatedActionId, invalidatedRev, resolution, reverted, cascadeRoot }
|
|
173
|
+
: { invalidatedActionId, invalidatedRev, resolution, reverted };
|
|
174
|
+
const entry = { timestamp, hlc, rev, invalidation } as LogEntry<TAction>;
|
|
175
|
+
const tailPath = await this.chain.add(entry);
|
|
176
|
+
return { entry, tailPath };
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* Finds the most recent invalidation entry that reverses the given committed action, if any.
|
|
181
|
+
* This is the durable source of truth for `committed-invalidated` status — once the entry has
|
|
182
|
+
* landed in the log, the reversal is recoverable on sync independent of any in-memory cache.
|
|
183
|
+
* Scans newest→oldest (O(n) over the chain, matching {@link getFrom}); returns the first match.
|
|
184
|
+
*/
|
|
185
|
+
async findInvalidation(invalidatedActionId: ActionId): Promise<InvalidationEntry | undefined> {
|
|
186
|
+
for await (const path of this.chain.select(undefined, false)) {
|
|
187
|
+
const invalidation = entryAt<LogEntry<TAction>>(path)!.invalidation;
|
|
188
|
+
if (invalidation && invalidation.invalidatedActionId === invalidatedActionId) {
|
|
189
|
+
return invalidation;
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
return undefined;
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
/**
|
|
196
|
+
* Returns the invalidation entries appended after `startRev` (exclusive), newest-first. Used by
|
|
197
|
+
* {@link import("../collection/collection.js").Collection} on `update` to discover reversals that
|
|
198
|
+
* landed since the client last synced: a client holding a result derived from now-reverted content
|
|
199
|
+
* drops it and replays against the reverted base — the same "your base moved, re-sync and retry"
|
|
200
|
+
* path a stale read triggers (`docs/right-is-right.md` §Client notification). Unlike {@link getFrom}
|
|
201
|
+
* (which skips invalidation entries — they are not pending/committed actions), this surfaces exactly
|
|
202
|
+
* the invalidations. Scans newest→oldest and stops once at/below `startRev` (revs are monotonic), so
|
|
203
|
+
* the walk is bounded to the unsynced tail.
|
|
204
|
+
*/
|
|
205
|
+
async getInvalidationsFrom(startRev: number | undefined): Promise<InvalidationEntry[]> {
|
|
206
|
+
const invalidations: InvalidationEntry[] = [];
|
|
207
|
+
for await (const path of this.chain.select(undefined, false)) {
|
|
208
|
+
const entry = entryAt<LogEntry<TAction>>(path)!;
|
|
209
|
+
if (startRev !== undefined && entry.rev <= startRev) {
|
|
210
|
+
break;
|
|
211
|
+
}
|
|
212
|
+
if (entry.invalidation) {
|
|
213
|
+
invalidations.push(entry.invalidation);
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
return invalidations;
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
/** Gets the action context of the log. */
|
|
220
|
+
async getActionContext(): Promise<ActionContext | undefined> {
|
|
221
|
+
const tailPath = await this.chain.getTail();
|
|
222
|
+
if (!tailPath || tailPath.block.entries.length === 0) {
|
|
223
|
+
return undefined;
|
|
224
|
+
}
|
|
225
|
+
const checkpoint = await this.findCheckpoint(tailPath);
|
|
226
|
+
// Hermes V1 codegen bug: `[...arr, ...await asyncCall()]` evaluated as an
|
|
227
|
+
// object-literal field value silently produces the number 0 instead of an
|
|
228
|
+
// array. Extracting the await into a local variable bypasses the buggy
|
|
229
|
+
// codegen path. Keep this workaround until Hermes V1 ships a fix.
|
|
230
|
+
const additional = checkpoint ? await this.pendingFrom(checkpoint.path) : [];
|
|
231
|
+
return {
|
|
232
|
+
committed: checkpoint ? [...checkpoint.pendings, ...additional] : [],
|
|
233
|
+
rev: checkpoint?.rev ?? 0,
|
|
234
|
+
};
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
/** Gets the actions from startRev (exclusive), to latest in the log. */
|
|
238
|
+
async getFrom(startRev: number | undefined): Promise<GetFromResult<TAction>> {
|
|
239
|
+
const entriesFromTail: ActionEntry<TAction>[] = [];
|
|
240
|
+
const pendingActions: ActionRev[] = [];
|
|
241
|
+
let checkpointPendings: ActionRev[] = [];
|
|
242
|
+
let rev: number | undefined;
|
|
243
|
+
let checkpointPath: ChainPath<LogEntry<TAction>> | undefined;
|
|
244
|
+
let hlcHighWater: Hlc | undefined;
|
|
245
|
+
// Step through collecting both pending and entries until a checkpoint is found
|
|
246
|
+
for await (const path of this.chain.select(undefined, false)) {
|
|
247
|
+
const entry = entryAt<LogEntry<TAction>>(path)!;
|
|
248
|
+
hlcHighWater = maxHlc(hlcHighWater, hlcOf(entry));
|
|
249
|
+
rev = rev ?? entry.rev;
|
|
250
|
+
if (entry.checkpoint) {
|
|
251
|
+
checkpointPath = path;
|
|
252
|
+
checkpointPendings = entry.checkpoint.pendings;
|
|
253
|
+
break;
|
|
254
|
+
}
|
|
255
|
+
// Invalidation entries take a rev slot but are not pending actions — skip them in
|
|
256
|
+
// the committed/pending set (the reversal is surfaced via findInvalidation instead).
|
|
257
|
+
if (!entry.action) {
|
|
258
|
+
continue;
|
|
259
|
+
}
|
|
260
|
+
pendingActions.push({ actionId: entry.action.actionId, rev: entry.rev });
|
|
261
|
+
if (startRev !== undefined && entry.rev > startRev) {
|
|
262
|
+
entriesFromTail.push(entry.action);
|
|
263
|
+
} // Can't stop at rev, because we need to collect all pending actions for the context
|
|
264
|
+
}
|
|
265
|
+
// Continue stepping past the checkpoint until the given rev is reached
|
|
266
|
+
const entriesFromCheckpoint: ActionEntry<TAction>[] = [];
|
|
267
|
+
if (checkpointPath) {
|
|
268
|
+
for await (const path of this.chain.select(checkpointPath, false)) {
|
|
269
|
+
const entry = entryAt<LogEntry<TAction>>(path)!;
|
|
270
|
+
hlcHighWater = maxHlc(hlcHighWater, hlcOf(entry));
|
|
271
|
+
if (startRev !== undefined && entry.rev > startRev) {
|
|
272
|
+
if (entry.action) {
|
|
273
|
+
entriesFromCheckpoint.push(entry.action);
|
|
274
|
+
}
|
|
275
|
+
} else {
|
|
276
|
+
break;
|
|
277
|
+
}
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
const pendings = [...checkpointPendings, ...pendingActions.reverse()];
|
|
281
|
+
const entries = [...entriesFromCheckpoint.reverse(), ...entriesFromTail.reverse()];
|
|
282
|
+
return { context: rev ? { committed: pendings, rev } : undefined, entries, hlcHighWater };
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
/** Enumerates log entries from the given starting path or end if undefined, in forward (from tail to head) or reverse (from head to tail) order. */
|
|
286
|
+
async *select(starting?: ChainPath<LogEntry<TAction>>, forward = true) {
|
|
287
|
+
for await (const path of this.chain.select(starting, forward)) {
|
|
288
|
+
yield entryAt<LogEntry<TAction>>(path)!;
|
|
289
|
+
}
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
/** Returns the set of pending transactions in the most recent checkpoint, at or preceding the given path. */
|
|
293
|
+
private async findCheckpoint(starting: ChainPath<LogEntry<TAction>>) {
|
|
294
|
+
let lastPath: ChainPath<LogEntry<TAction>> | undefined;
|
|
295
|
+
let rev: number | undefined;
|
|
296
|
+
for await (const path of this.chain.select(starting, false)) {
|
|
297
|
+
const entry = entryAt<LogEntry<TAction>>(path)!;
|
|
298
|
+
rev = rev ?? entry.rev;
|
|
299
|
+
if (entry.checkpoint) {
|
|
300
|
+
return { path, pendings: entry.checkpoint.pendings, rev };
|
|
301
|
+
}
|
|
302
|
+
lastPath = path;
|
|
303
|
+
}
|
|
304
|
+
return lastPath ? { path: lastPath, pendings: [], rev } : undefined;
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
/** Returns the set of pending actions following, the given checkpoint path. */
|
|
308
|
+
private async pendingFrom(starting: ChainPath<LogEntry<TAction>>) {
|
|
309
|
+
const pendings: ActionRev[] = [];
|
|
310
|
+
for await (const actionPath of this.chain.select(starting)) {
|
|
311
|
+
const entry = entryAt<LogEntry<TAction>>(actionPath);
|
|
312
|
+
if (entry?.action) {
|
|
313
|
+
pendings.push({ actionId: entry.action.actionId, rev: entry.rev });
|
|
314
|
+
}
|
|
315
|
+
}
|
|
316
|
+
return pendings;
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
/** Chain options used by every log: block type factories, the priorHash `newBlock` hook, and the
|
|
320
|
+
* byte target a log block rolls over at. Every entry carries its action's data, so a count alone
|
|
321
|
+
* would let a log of large entries build a block too large to copy between machines; with
|
|
322
|
+
* {@link BLOCK_TARGET_BYTES} a log block either holds one entry (and is then no larger than the
|
|
323
|
+
* transaction that wrote it) or stays near the target.
|
|
324
|
+
* Exposed (not private) so tests can drive a raw {@link Chain} through the exact same hook. */
|
|
325
|
+
static getChainOptions<TAction>(store: BlockStore<IBlock>, newDataBlockId?: () => BlockId) {
|
|
326
|
+
return {
|
|
327
|
+
blockTargetBytes: BLOCK_TARGET_BYTES,
|
|
328
|
+
createDataBlock: () => ({ header: store.createBlockHeader(LogDataBlockType, newDataBlockId?.()) }),
|
|
329
|
+
createHeaderBlock: (id?: BlockId) => ({ header: store.createBlockHeader(LogHeaderBlockType, id) }),
|
|
330
|
+
newBlock: async (newTail: LogBlock<TAction>, oldTail: LogBlock<TAction> | undefined) => {
|
|
331
|
+
if (oldTail) {
|
|
332
|
+
// Hash the canonical payload (excludes the mutable nextId/priorId links) so the
|
|
333
|
+
// recorded priorHash matches a later re-hash of the stored predecessor block.
|
|
334
|
+
const hash = await sha256.digest(new TextEncoder().encode(JSON.stringify(logBlockHashPayload(oldTail))));
|
|
335
|
+
newTail.priorHash = uint8ArrayToString(hash.digest, 'base64url');
|
|
336
|
+
}
|
|
337
|
+
},
|
|
338
|
+
} as ChainInitOptions<LogEntry<TAction>>;
|
|
339
|
+
|
|
340
|
+
}
|
|
341
|
+
}
|