@optimystic/db-core 1.5.0 → 1.5.1
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 +336 -336
- package/dist/src/collection/collection.d.ts +44 -4
- package/dist/src/collection/collection.d.ts.map +1 -1
- package/dist/src/collection/collection.js +95 -14
- package/dist/src/collection/collection.js.map +1 -1
- package/dist/src/log/log.d.ts +41 -8
- package/dist/src/log/log.d.ts.map +1 -1
- package/dist/src/log/log.js +15 -10
- package/dist/src/log/log.js.map +1 -1
- package/dist/src/testing/test-transactor.d.ts +36 -0
- package/dist/src/testing/test-transactor.d.ts.map +1 -1
- package/dist/src/testing/test-transactor.js +49 -0
- package/dist/src/testing/test-transactor.js.map +1 -1
- package/dist/src/transaction/coordinator.d.ts.map +1 -1
- package/dist/src/transaction/coordinator.js +26 -9
- package/dist/src/transaction/coordinator.js.map +1 -1
- package/package.json +1 -1
- package/src/blocks/block-store.ts +31 -31
- package/src/blocks/block-types.ts +11 -11
- package/src/blocks/index.ts +5 -5
- package/src/blocks/structs.ts +17 -17
- package/src/btree/btree.ts +872 -872
- package/src/btree/independent-trunk.ts +53 -53
- package/src/btree/index.ts +5 -5
- package/src/btree/key-range.ts +15 -15
- package/src/btree/keyset.ts +6 -6
- package/src/btree/nodes.ts +25 -25
- package/src/btree/path.ts +37 -37
- package/src/btree/tree-block.ts +11 -11
- package/src/btree/trunk.ts +14 -14
- package/src/chain/chain-nodes.ts +26 -26
- package/src/chain/chain.ts +349 -349
- package/src/chain/index.ts +3 -3
- package/src/cluster/i-cluster.ts +6 -6
- package/src/cluster/index.ts +3 -3
- package/src/cohort-topic/addressing.ts +120 -120
- package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
- package/src/cohort-topic/antidos/index.ts +5 -5
- package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
- package/src/cohort-topic/antidos/replay-guard.ts +146 -146
- package/src/cohort-topic/antidos/topic-budget.ts +160 -160
- package/src/cohort-topic/antiflood/index.ts +2 -2
- package/src/cohort-topic/antiflood/invariants.ts +108 -108
- package/src/cohort-topic/antiflood/jitter.ts +117 -117
- package/src/cohort-topic/coldstart.ts +237 -237
- package/src/cohort-topic/dmax.ts +88 -88
- package/src/cohort-topic/gossip/bus.ts +254 -254
- package/src/cohort-topic/gossip/index.ts +3 -3
- package/src/cohort-topic/gossip/records.ts +45 -45
- package/src/cohort-topic/gossip/view.ts +91 -91
- package/src/cohort-topic/index.ts +20 -20
- package/src/cohort-topic/load/barometer.ts +134 -134
- package/src/cohort-topic/load/index.ts +1 -1
- package/src/cohort-topic/member-engine.ts +430 -430
- package/src/cohort-topic/membership/index.ts +3 -3
- package/src/cohort-topic/membership/publisher.ts +163 -163
- package/src/cohort-topic/membership/source.ts +41 -41
- package/src/cohort-topic/ports.ts +157 -157
- package/src/cohort-topic/promotion.ts +477 -477
- package/src/cohort-topic/registration/bytes.ts +37 -37
- package/src/cohort-topic/registration/handoff.ts +154 -154
- package/src/cohort-topic/registration/index.ts +6 -6
- package/src/cohort-topic/registration/renewal.ts +495 -495
- package/src/cohort-topic/registration/sharding.ts +61 -61
- package/src/cohort-topic/registration/store.ts +81 -81
- package/src/cohort-topic/registration/types.ts +91 -91
- package/src/cohort-topic/ring-hash.ts +50 -50
- package/src/cohort-topic/service.ts +416 -416
- package/src/cohort-topic/sig/index.ts +2 -2
- package/src/cohort-topic/sig/payloads.ts +59 -59
- package/src/cohort-topic/sig/threshold.ts +64 -64
- package/src/cohort-topic/tiers.ts +74 -74
- package/src/cohort-topic/traffic.ts +233 -233
- package/src/cohort-topic/walk.ts +326 -326
- package/src/cohort-topic/willingness.ts +237 -237
- package/src/cohort-topic/wire/index.ts +18 -18
- package/src/cohort-topic/wire/payloads.ts +126 -126
- package/src/collection/action.ts +48 -48
- package/src/collection/collection-type-registry.ts +37 -37
- package/src/collection/collection.ts +2203 -2118
- package/src/collection/index.ts +4 -4
- package/src/collections/diary/index.ts +2 -2
- package/src/collections/diary/struct.ts +3 -3
- package/src/collections/index.ts +2 -2
- package/src/collections/tree/collection-trunk.ts +25 -25
- package/src/collections/tree/index.ts +2 -2
- package/src/collections/tree/readme.md +55 -55
- package/src/log/index.ts +2 -2
- package/src/log/log.ts +304 -268
- package/src/log/struct.ts +165 -165
- package/src/matchmaking/capability-filter.ts +45 -45
- package/src/matchmaking/config.ts +98 -98
- package/src/matchmaking/index.ts +21 -21
- package/src/matchmaking/multi-cohort-seeker.ts +234 -234
- package/src/matchmaking/provider.ts +123 -123
- package/src/matchmaking/query-eval.ts +105 -105
- package/src/matchmaking/seeker-walk.ts +127 -127
- package/src/matchmaking/seeker.ts +86 -86
- package/src/matchmaking/topic-anchor.ts +90 -90
- package/src/matchmaking/voting-quorum.ts +394 -394
- package/src/network/i-peer-network.ts +25 -25
- package/src/network/repo-protocol.ts +13 -13
- package/src/network/types.ts +37 -37
- package/src/reactivity/backfill.ts +220 -220
- package/src/reactivity/backpressure.ts +191 -191
- package/src/reactivity/checkpoint.ts +308 -308
- package/src/reactivity/config.ts +172 -172
- package/src/reactivity/dedupe.ts +132 -132
- package/src/reactivity/forwarder.ts +87 -87
- package/src/reactivity/index.ts +34 -34
- package/src/reactivity/notification.ts +123 -123
- package/src/reactivity/policy.ts +79 -79
- package/src/reactivity/push-state.ts +310 -310
- package/src/reactivity/recover.ts +153 -153
- package/src/reactivity/replay-buffer.ts +141 -141
- package/src/reactivity/resume.ts +549 -549
- package/src/reactivity/rotation.ts +415 -415
- package/src/reactivity/subscriber.ts +132 -132
- package/src/reactivity/subscription.ts +66 -66
- package/src/reactivity/topic-anchor.ts +71 -71
- package/src/reactivity/verify.ts +73 -73
- package/src/reactivity/wire-validate.ts +13 -13
- package/src/testing/async-wait.ts +65 -65
- package/src/testing/index.ts +2 -2
- package/src/testing/test-transactor.ts +62 -0
- package/src/transaction/actions-engine.ts +68 -68
- package/src/transaction/coordinator.ts +28 -11
- package/src/transaction/index.ts +52 -52
- package/src/transaction/operations-hash.ts +196 -196
- package/src/transaction/read-dependency-collector.ts +78 -78
- package/src/transaction/session.ts +238 -238
- package/src/transaction/transaction.ts +442 -442
- package/src/transaction/validator.ts +197 -197
- package/src/transactor/block-floors.ts +126 -126
- package/src/transactor/index.ts +6 -6
- package/src/transactor/network-transactor.ts +1545 -1545
- package/src/transform/atomic-proxy.ts +92 -92
- package/src/transform/cache-source.ts +370 -370
- package/src/transform/helpers.ts +164 -164
- package/src/transform/index.ts +7 -7
- package/src/transform/struct.ts +21 -21
- package/src/utility/actor.ts +62 -62
- package/src/utility/backoff.ts +95 -95
- package/src/utility/batch-coordinator.ts +191 -191
- package/src/utility/ensured.ts +32 -32
- package/src/utility/groupby.ts +18 -18
- package/src/utility/hash-string.ts +14 -14
- package/src/utility/is-record-empty.ts +5 -5
- package/src/utility/latches.ts +42 -42
- package/src/utility/lru-map.ts +60 -60
- package/src/utility/nameof.ts +7 -7
- package/src/utility/pending.ts +43 -43
package/src/log/log.ts
CHANGED
|
@@ -1,268 +1,304 @@
|
|
|
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
|
-
|
|
11
|
-
export type LogBlock<TAction> = ChainDataNode<LogEntry<TAction>>
|
|
12
|
-
& {
|
|
13
|
-
/** Base64url encoded Sha256 hash of the prior (predecessor) block - present on every block except the head */
|
|
14
|
-
priorHash?: string,
|
|
15
|
-
};
|
|
16
|
-
|
|
17
|
-
export const priorHash$ = nameof<LogBlock<any>>("priorHash");
|
|
18
|
-
|
|
19
|
-
/**
|
|
20
|
-
* Canonical byte payload covered by {@link LogBlock.priorHash}: every field of a log block EXCEPT
|
|
21
|
-
* the mutable structural links (`nextId`/`priorId`). Those links are rewritten *after* the hash is
|
|
22
|
-
* taken — `nextId` when the following block is appended ({@link Chain.add}), and `priorId`/`nextId`
|
|
23
|
-
* when blocks are removed ({@link Chain.pop}/{@link Chain.dequeue}) — so hashing the raw block would
|
|
24
|
-
* not match the bytes that end up stored. The content-bearing fields (`header`, `entries`,
|
|
25
|
-
* `priorHash`) are covered. Any verifier that re-hashes a stored block to check `priorHash` MUST
|
|
26
|
-
* reproduce exactly this payload (strip `nextId` and `priorId`; hash the rest).
|
|
27
|
-
*
|
|
28
|
-
* NOTE: the caller hashes `JSON.stringify` of this object, which is key-order dependent and not a
|
|
29
|
-
* canonical encoding. Fine today (blocks are built with a stable key order and the in-process store
|
|
30
|
-
* preserves it), but if a block is ever re-serialized by a store/codec that reorders keys or drops
|
|
31
|
-
* `undefined`s differently, a re-hash won't match the recorded priorHash — switch to a canonical
|
|
32
|
-
* encoding (sorted keys / dag-cbor) before that happens.
|
|
33
|
-
*/
|
|
34
|
-
export function logBlockHashPayload<TAction>(block: LogBlock<TAction>) {
|
|
35
|
-
const { nextId, priorId, ...covered } = block;
|
|
36
|
-
return covered;
|
|
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
|
-
|
|
67
|
-
|
|
68
|
-
|
|
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
|
-
const
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
async
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
*
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
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
|
-
if (entry.
|
|
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
|
-
}
|
|
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
|
+
|
|
11
|
+
export type LogBlock<TAction> = ChainDataNode<LogEntry<TAction>>
|
|
12
|
+
& {
|
|
13
|
+
/** Base64url encoded Sha256 hash of the prior (predecessor) block - present on every block except the head */
|
|
14
|
+
priorHash?: string,
|
|
15
|
+
};
|
|
16
|
+
|
|
17
|
+
export const priorHash$ = nameof<LogBlock<any>>("priorHash");
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* Canonical byte payload covered by {@link LogBlock.priorHash}: every field of a log block EXCEPT
|
|
21
|
+
* the mutable structural links (`nextId`/`priorId`). Those links are rewritten *after* the hash is
|
|
22
|
+
* taken — `nextId` when the following block is appended ({@link Chain.add}), and `priorId`/`nextId`
|
|
23
|
+
* when blocks are removed ({@link Chain.pop}/{@link Chain.dequeue}) — so hashing the raw block would
|
|
24
|
+
* not match the bytes that end up stored. The content-bearing fields (`header`, `entries`,
|
|
25
|
+
* `priorHash`) are covered. Any verifier that re-hashes a stored block to check `priorHash` MUST
|
|
26
|
+
* reproduce exactly this payload (strip `nextId` and `priorId`; hash the rest).
|
|
27
|
+
*
|
|
28
|
+
* NOTE: the caller hashes `JSON.stringify` of this object, which is key-order dependent and not a
|
|
29
|
+
* canonical encoding. Fine today (blocks are built with a stable key order and the in-process store
|
|
30
|
+
* preserves it), but if a block is ever re-serialized by a store/codec that reorders keys or drops
|
|
31
|
+
* `undefined`s differently, a re-hash won't match the recorded priorHash — switch to a canonical
|
|
32
|
+
* encoding (sorted keys / dag-cbor) before that happens.
|
|
33
|
+
*/
|
|
34
|
+
export function logBlockHashPayload<TAction>(block: LogBlock<TAction>) {
|
|
35
|
+
const { nextId, priorId, ...covered } = block;
|
|
36
|
+
return covered;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** What {@link Log.open} may be told beyond the block it opens. */
|
|
40
|
+
export type LogOpenOptions = {
|
|
41
|
+
/** Supplies the id for each data block an append mints, in place of a fresh random one. */
|
|
42
|
+
newDataBlockId?: () => BlockId;
|
|
43
|
+
};
|
|
44
|
+
|
|
45
|
+
/** The trailing, mostly-optional inputs to {@link Log.addActions}. An options object rather than
|
|
46
|
+
* positional parameters because the two most interesting ones are the last two, and a caller that
|
|
47
|
+
* needs only the timestamp should not have to spell out the two before it. */
|
|
48
|
+
export type AddActionsOptions = {
|
|
49
|
+
/** Every collection participating in the action this entry records. */
|
|
50
|
+
collectionIds?: CollectionId[];
|
|
51
|
+
/** The transaction's `(blockId, revision)` read set, persisted on the entry so the invalidation
|
|
52
|
+
* cascade can later discover this action's read-dependents (see {@link ActionEntry.reads}).
|
|
53
|
+
* Omit it on the low-level direct-commit path that carries no `Transaction`; the cascade then
|
|
54
|
+
* treats the entry as an unknown dependency. */
|
|
55
|
+
reads?: ReadDependency[];
|
|
56
|
+
/**
|
|
57
|
+
* When the entry was written. Nothing in the tree reads it for logic — it is informational —
|
|
58
|
+
* which is what makes it safe for a writer to supply the time of the WRITE rather than of the
|
|
59
|
+
* attempt, and arguably the more honest value.
|
|
60
|
+
*
|
|
61
|
+
* A writer whose attempt may be retried MUST supply it. Storage identifies a saved block
|
|
62
|
+
* revision by `(action id, revision)` and accepts a retry of the same action at the same
|
|
63
|
+
* revision, so a retry that took a fresh timestamp here would store a second, different log
|
|
64
|
+
* block under one `(action, revision)` on every machine that missed the first attempt.
|
|
65
|
+
* Defaults to `Date.now()` for a caller that appends once.
|
|
66
|
+
*/
|
|
67
|
+
timestamp?: number;
|
|
68
|
+
};
|
|
69
|
+
|
|
70
|
+
export class Log<TAction> {
|
|
71
|
+
protected constructor(
|
|
72
|
+
private readonly chain: Chain<LogEntry<TAction>>,
|
|
73
|
+
) {
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
get id() {
|
|
77
|
+
return this.chain.id;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** Opens a presumably existing log.
|
|
81
|
+
*
|
|
82
|
+
* `options.newDataBlockId` supplies the id for each data block an append has to mint, in place
|
|
83
|
+
* of a fresh random one. A writer whose attempt may be RETRIED passes a source that hands back
|
|
84
|
+
* the ids its earlier attempt minted, so the retry's transforms are byte-identical to the
|
|
85
|
+
* attempt it repeats (see {@link Collection.logAppendBlockIds}); everything else omits it and
|
|
86
|
+
* mints at random exactly as before. */
|
|
87
|
+
static async open<TAction>(store: BlockStore<IBlock>, id: BlockId, options?: LogOpenOptions): Promise<Log<TAction> | undefined> {
|
|
88
|
+
const chain = await Chain.open<LogEntry<TAction>>(store, id, Log.getChainOptions(store, options?.newDataBlockId));
|
|
89
|
+
return chain ? new Log<TAction>(chain) : undefined;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** Creates a new log. */
|
|
93
|
+
static async create<TAction>(store: BlockStore<IBlock>, options?: { newId?: BlockId; existingHeaderId?: BlockId }) {
|
|
94
|
+
return new Log<TAction>(await Chain.create<LogEntry<TAction>>(store, {
|
|
95
|
+
...Log.getChainOptions(store),
|
|
96
|
+
newId: options?.newId,
|
|
97
|
+
existingHeaderId: options?.existingHeaderId,
|
|
98
|
+
}));
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* Adds a new action entry to the log.
|
|
103
|
+
*
|
|
104
|
+
* See {@link AddActionsOptions} for what the trailing options carry, and in particular why a
|
|
105
|
+
* writer that may retry passes its own `timestamp` rather than letting each attempt take one.
|
|
106
|
+
*/
|
|
107
|
+
async addActions(actions: TAction[], actionId: ActionId, rev: number, getBlockIds: () => BlockId[], options?: AddActionsOptions) {
|
|
108
|
+
const { collectionIds = [], reads, timestamp = Date.now() } = options ?? {};
|
|
109
|
+
const action = reads !== undefined
|
|
110
|
+
? { actionId, actions, blockIds: [], collectionIds, reads }
|
|
111
|
+
: { actionId, actions, blockIds: [], collectionIds };
|
|
112
|
+
const entry = { timestamp, rev, action } as LogEntry<TAction>;
|
|
113
|
+
const tailPath = await this.chain.add(entry);
|
|
114
|
+
const entryWithBlockIds = { ...entry, action: { ...entry.action!, blockIds: getBlockIds() } };
|
|
115
|
+
this.chain.updateAt(tailPath, entryWithBlockIds);
|
|
116
|
+
return { entry: entryWithBlockIds, tailPath };
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/** Adds a checkpoint to the log. */
|
|
120
|
+
async addCheckpoint(pendings: ActionRev[], rev: number, timestamp: number = Date.now()) {
|
|
121
|
+
const entry = { timestamp, rev, checkpoint: { pendings } };
|
|
122
|
+
const tailPath = await this.chain.add(entry);
|
|
123
|
+
return { entry, tailPath };
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* Appends a compensating invalidation entry that reverses a previously-committed action proven
|
|
128
|
+
* invalid by dispute. The committed history is never rewritten — this is a new, append-only,
|
|
129
|
+
* prior-hash-linked entry, recoverable on sync exactly like a commit. The caller has already
|
|
130
|
+
* verified `resolution` is a challenger-wins certificate and computed the per-block `reverted`
|
|
131
|
+
* targets (the new revisions restoring the as-if-`T_inv`-absent content).
|
|
132
|
+
*/
|
|
133
|
+
async addInvalidation(
|
|
134
|
+
invalidatedActionId: ActionId,
|
|
135
|
+
invalidatedRev: number,
|
|
136
|
+
resolution: DisputeResolutionProof,
|
|
137
|
+
reverted: ReadonlyArray<RevertedBlock>,
|
|
138
|
+
rev: number,
|
|
139
|
+
cascadeRoot?: ActionId,
|
|
140
|
+
timestamp: number = Date.now()
|
|
141
|
+
) {
|
|
142
|
+
const invalidation: InvalidationEntry = cascadeRoot !== undefined
|
|
143
|
+
? { invalidatedActionId, invalidatedRev, resolution, reverted, cascadeRoot }
|
|
144
|
+
: { invalidatedActionId, invalidatedRev, resolution, reverted };
|
|
145
|
+
const entry = { timestamp, rev, invalidation } as LogEntry<TAction>;
|
|
146
|
+
const tailPath = await this.chain.add(entry);
|
|
147
|
+
return { entry, tailPath };
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/**
|
|
151
|
+
* Finds the most recent invalidation entry that reverses the given committed action, if any.
|
|
152
|
+
* This is the durable source of truth for `committed-invalidated` status — once the entry has
|
|
153
|
+
* landed in the log, the reversal is recoverable on sync independent of any in-memory cache.
|
|
154
|
+
* Scans newest→oldest (O(n) over the chain, matching {@link getFrom}); returns the first match.
|
|
155
|
+
*/
|
|
156
|
+
async findInvalidation(invalidatedActionId: ActionId): Promise<InvalidationEntry | undefined> {
|
|
157
|
+
for await (const path of this.chain.select(undefined, false)) {
|
|
158
|
+
const invalidation = entryAt<LogEntry<TAction>>(path)!.invalidation;
|
|
159
|
+
if (invalidation && invalidation.invalidatedActionId === invalidatedActionId) {
|
|
160
|
+
return invalidation;
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
return undefined;
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
/**
|
|
167
|
+
* Returns the invalidation entries appended after `startRev` (exclusive), newest-first. Used by
|
|
168
|
+
* {@link import("../collection/collection.js").Collection} on `update` to discover reversals that
|
|
169
|
+
* landed since the client last synced: a client holding a result derived from now-reverted content
|
|
170
|
+
* drops it and replays against the reverted base — the same "your base moved, re-sync and retry"
|
|
171
|
+
* path a stale read triggers (`docs/right-is-right.md` §Client notification). Unlike {@link getFrom}
|
|
172
|
+
* (which skips invalidation entries — they are not pending/committed actions), this surfaces exactly
|
|
173
|
+
* the invalidations. Scans newest→oldest and stops once at/below `startRev` (revs are monotonic), so
|
|
174
|
+
* the walk is bounded to the unsynced tail.
|
|
175
|
+
*/
|
|
176
|
+
async getInvalidationsFrom(startRev: number | undefined): Promise<InvalidationEntry[]> {
|
|
177
|
+
const invalidations: InvalidationEntry[] = [];
|
|
178
|
+
for await (const path of this.chain.select(undefined, false)) {
|
|
179
|
+
const entry = entryAt<LogEntry<TAction>>(path)!;
|
|
180
|
+
if (startRev !== undefined && entry.rev <= startRev) {
|
|
181
|
+
break;
|
|
182
|
+
}
|
|
183
|
+
if (entry.invalidation) {
|
|
184
|
+
invalidations.push(entry.invalidation);
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
return invalidations;
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/** Gets the action context of the log. */
|
|
191
|
+
async getActionContext(): Promise<ActionContext | undefined> {
|
|
192
|
+
const tailPath = await this.chain.getTail();
|
|
193
|
+
if (!tailPath || tailPath.block.entries.length === 0) {
|
|
194
|
+
return undefined;
|
|
195
|
+
}
|
|
196
|
+
const checkpoint = await this.findCheckpoint(tailPath);
|
|
197
|
+
// Hermes V1 codegen bug: `[...arr, ...await asyncCall()]` evaluated as an
|
|
198
|
+
// object-literal field value silently produces the number 0 instead of an
|
|
199
|
+
// array. Extracting the await into a local variable bypasses the buggy
|
|
200
|
+
// codegen path. Keep this workaround until Hermes V1 ships a fix.
|
|
201
|
+
const additional = checkpoint ? await this.pendingFrom(checkpoint.path) : [];
|
|
202
|
+
return {
|
|
203
|
+
committed: checkpoint ? [...checkpoint.pendings, ...additional] : [],
|
|
204
|
+
rev: checkpoint?.rev ?? 0,
|
|
205
|
+
};
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/** Gets the actions from startRev (exclusive), to latest in the log. */
|
|
209
|
+
async getFrom(startRev: number | undefined): Promise<GetFromResult<TAction>> {
|
|
210
|
+
const entriesFromTail: ActionEntry<TAction>[] = [];
|
|
211
|
+
const pendingActions: ActionRev[] = [];
|
|
212
|
+
let checkpointPendings: ActionRev[] = [];
|
|
213
|
+
let rev: number | undefined;
|
|
214
|
+
let checkpointPath: ChainPath<LogEntry<TAction>> | undefined;
|
|
215
|
+
// Step through collecting both pending and entries until a checkpoint is found
|
|
216
|
+
for await (const path of this.chain.select(undefined, false)) {
|
|
217
|
+
const entry = entryAt<LogEntry<TAction>>(path)!;
|
|
218
|
+
rev = rev ?? entry.rev;
|
|
219
|
+
if (entry.checkpoint) {
|
|
220
|
+
checkpointPath = path;
|
|
221
|
+
checkpointPendings = entry.checkpoint.pendings;
|
|
222
|
+
break;
|
|
223
|
+
}
|
|
224
|
+
// Invalidation entries take a rev slot but are not pending actions — skip them in
|
|
225
|
+
// the committed/pending set (the reversal is surfaced via findInvalidation instead).
|
|
226
|
+
if (!entry.action) {
|
|
227
|
+
continue;
|
|
228
|
+
}
|
|
229
|
+
pendingActions.push({ actionId: entry.action.actionId, rev: entry.rev });
|
|
230
|
+
if (startRev !== undefined && entry.rev > startRev) {
|
|
231
|
+
entriesFromTail.push(entry.action);
|
|
232
|
+
} // Can't stop at rev, because we need to collect all pending actions for the context
|
|
233
|
+
}
|
|
234
|
+
// Continue stepping past the checkpoint until the given rev is reached
|
|
235
|
+
const entriesFromCheckpoint: ActionEntry<TAction>[] = [];
|
|
236
|
+
if (checkpointPath) {
|
|
237
|
+
for await (const path of this.chain.select(checkpointPath, false)) {
|
|
238
|
+
const entry = entryAt<LogEntry<TAction>>(path)!;
|
|
239
|
+
if (startRev !== undefined && entry.rev > startRev) {
|
|
240
|
+
if (entry.action) {
|
|
241
|
+
entriesFromCheckpoint.push(entry.action);
|
|
242
|
+
}
|
|
243
|
+
} else {
|
|
244
|
+
break;
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
}
|
|
248
|
+
const pendings = [...checkpointPendings, ...pendingActions.reverse()];
|
|
249
|
+
const entries = [...entriesFromCheckpoint.reverse(), ...entriesFromTail.reverse()];
|
|
250
|
+
return { context: rev ? { committed: pendings, rev } : undefined, entries };
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
/** 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. */
|
|
254
|
+
async *select(starting?: ChainPath<LogEntry<TAction>>, forward = true) {
|
|
255
|
+
for await (const path of this.chain.select(starting, forward)) {
|
|
256
|
+
yield entryAt<LogEntry<TAction>>(path)!;
|
|
257
|
+
}
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
/** Returns the set of pending transactions in the most recent checkpoint, at or preceding the given path. */
|
|
261
|
+
private async findCheckpoint(starting: ChainPath<LogEntry<TAction>>) {
|
|
262
|
+
let lastPath: ChainPath<LogEntry<TAction>> | undefined;
|
|
263
|
+
let rev: number | undefined;
|
|
264
|
+
for await (const path of this.chain.select(starting, false)) {
|
|
265
|
+
const entry = entryAt<LogEntry<TAction>>(path)!;
|
|
266
|
+
rev = rev ?? entry.rev;
|
|
267
|
+
if (entry.checkpoint) {
|
|
268
|
+
return { path, pendings: entry.checkpoint.pendings, rev };
|
|
269
|
+
}
|
|
270
|
+
lastPath = path;
|
|
271
|
+
}
|
|
272
|
+
return lastPath ? { path: lastPath, pendings: [], rev } : undefined;
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
/** Returns the set of pending actions following, the given checkpoint path. */
|
|
276
|
+
private async pendingFrom(starting: ChainPath<LogEntry<TAction>>) {
|
|
277
|
+
const pendings: ActionRev[] = [];
|
|
278
|
+
for await (const actionPath of this.chain.select(starting)) {
|
|
279
|
+
const entry = entryAt<LogEntry<TAction>>(actionPath);
|
|
280
|
+
if (entry?.action) {
|
|
281
|
+
pendings.push({ actionId: entry.action.actionId, rev: entry.rev });
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
return pendings;
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
/** Chain options used by every log: block type factories plus the priorHash `newBlock` hook.
|
|
288
|
+
* Exposed (not private) so tests can drive a raw {@link Chain} through the exact same hook. */
|
|
289
|
+
static getChainOptions<TAction>(store: BlockStore<IBlock>, newDataBlockId?: () => BlockId) {
|
|
290
|
+
return {
|
|
291
|
+
createDataBlock: () => ({ header: store.createBlockHeader(LogDataBlockType, newDataBlockId?.()) }),
|
|
292
|
+
createHeaderBlock: (id?: BlockId) => ({ header: store.createBlockHeader(LogHeaderBlockType, id) }),
|
|
293
|
+
newBlock: async (newTail: LogBlock<TAction>, oldTail: LogBlock<TAction> | undefined) => {
|
|
294
|
+
if (oldTail) {
|
|
295
|
+
// Hash the canonical payload (excludes the mutable nextId/priorId links) so the
|
|
296
|
+
// recorded priorHash matches a later re-hash of the stored predecessor block.
|
|
297
|
+
const hash = await sha256.digest(new TextEncoder().encode(JSON.stringify(logBlockHashPayload(oldTail))));
|
|
298
|
+
newTail.priorHash = uint8ArrayToString(hash.digest, 'base64url');
|
|
299
|
+
}
|
|
300
|
+
},
|
|
301
|
+
} as ChainInitOptions<LogEntry<TAction>>;
|
|
302
|
+
|
|
303
|
+
}
|
|
304
|
+
}
|