@optimystic/db-core 1.18.0 → 1.20.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 +2 -1
- package/dist/src/blocks/helpers.d.ts +7 -0
- package/dist/src/blocks/helpers.d.ts.map +1 -1
- package/dist/src/blocks/helpers.js +7 -1
- package/dist/src/blocks/helpers.js.map +1 -1
- package/dist/src/btree/btree.d.ts +100 -4
- package/dist/src/btree/btree.d.ts.map +1 -1
- package/dist/src/btree/btree.js +252 -90
- package/dist/src/btree/btree.js.map +1 -1
- package/dist/src/btree/node-division.d.ts +37 -0
- package/dist/src/btree/node-division.d.ts.map +1 -0
- package/dist/src/btree/node-division.js +133 -0
- package/dist/src/btree/node-division.js.map +1 -0
- package/dist/src/chain/chain.d.ts +23 -0
- package/dist/src/chain/chain.d.ts.map +1 -1
- package/dist/src/chain/chain.js +43 -6
- package/dist/src/chain/chain.js.map +1 -1
- package/dist/src/cluster/structs.d.ts +41 -8
- package/dist/src/cluster/structs.d.ts.map +1 -1
- package/dist/src/cluster/structs.js +18 -7
- package/dist/src/cluster/structs.js.map +1 -1
- package/dist/src/collection/action.d.ts +29 -0
- package/dist/src/collection/action.d.ts.map +1 -1
- package/dist/src/collection/action.js +6 -0
- package/dist/src/collection/action.js.map +1 -1
- package/dist/src/collection/collection.d.ts +566 -120
- package/dist/src/collection/collection.d.ts.map +1 -1
- package/dist/src/collection/collection.js +1084 -495
- package/dist/src/collection/collection.js.map +1 -1
- package/dist/src/collection/head-commit.d.ts +110 -0
- package/dist/src/collection/head-commit.d.ts.map +1 -0
- package/dist/src/collection/head-commit.js +65 -0
- package/dist/src/collection/head-commit.js.map +1 -0
- package/dist/src/collection/index.d.ts +2 -0
- package/dist/src/collection/index.d.ts.map +1 -1
- package/dist/src/collection/index.js +2 -0
- package/dist/src/collection/index.js.map +1 -1
- package/dist/src/collection/segments.d.ts +77 -0
- package/dist/src/collection/segments.d.ts.map +1 -0
- package/dist/src/collection/segments.js +110 -0
- package/dist/src/collection/segments.js.map +1 -0
- package/dist/src/collection/struct.d.ts +176 -1
- package/dist/src/collection/struct.d.ts.map +1 -1
- package/dist/src/collection/struct.js +70 -0
- package/dist/src/collection/struct.js.map +1 -1
- package/dist/src/collection/write-attempts.d.ts +245 -0
- package/dist/src/collection/write-attempts.d.ts.map +1 -0
- package/dist/src/collection/write-attempts.js +439 -0
- package/dist/src/collection/write-attempts.js.map +1 -0
- package/dist/src/collections/tree/struct.d.ts +100 -17
- package/dist/src/collections/tree/struct.d.ts.map +1 -1
- package/dist/src/collections/tree/struct.js +38 -7
- package/dist/src/collections/tree/struct.js.map +1 -1
- package/dist/src/collections/tree/tree.d.ts +17 -5
- package/dist/src/collections/tree/tree.d.ts.map +1 -1
- package/dist/src/collections/tree/tree.js +117 -29
- package/dist/src/collections/tree/tree.js.map +1 -1
- 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/log/log.d.ts +5 -1
- package/dist/src/log/log.d.ts.map +1 -1
- package/dist/src/log/log.js +7 -1
- package/dist/src/log/log.js.map +1 -1
- package/dist/src/network/block-size.d.ts +67 -0
- package/dist/src/network/block-size.d.ts.map +1 -0
- package/dist/src/network/block-size.js +82 -0
- package/dist/src/network/block-size.js.map +1 -0
- package/dist/src/network/i-repo.d.ts +3 -0
- package/dist/src/network/i-repo.d.ts.map +1 -1
- package/dist/src/network/index.d.ts +5 -0
- package/dist/src/network/index.d.ts.map +1 -1
- package/dist/src/network/index.js +5 -0
- package/dist/src/network/index.js.map +1 -1
- package/dist/src/network/promise-shortfall-error.d.ts +40 -0
- package/dist/src/network/promise-shortfall-error.d.ts.map +1 -0
- package/dist/src/network/promise-shortfall-error.js +67 -0
- package/dist/src/network/promise-shortfall-error.js.map +1 -0
- package/dist/src/network/refuse-solo.d.ts +8 -0
- package/dist/src/network/refuse-solo.d.ts.map +1 -0
- package/dist/src/network/refuse-solo.js +8 -0
- package/dist/src/network/refuse-solo.js.map +1 -0
- package/dist/src/network/stale-failure.d.ts +20 -3
- package/dist/src/network/stale-failure.d.ts.map +1 -1
- package/dist/src/network/stale-failure.js +24 -3
- package/dist/src/network/stale-failure.js.map +1 -1
- package/dist/src/network/struct.d.ts +161 -13
- package/dist/src/network/struct.d.ts.map +1 -1
- package/dist/src/network/struct.js.map +1 -1
- package/dist/src/network/transaction-size.d.ts +59 -0
- package/dist/src/network/transaction-size.d.ts.map +1 -0
- package/dist/src/network/transaction-size.js +74 -0
- package/dist/src/network/transaction-size.js.map +1 -0
- package/dist/src/network/validity-rejected-error.d.ts +28 -0
- package/dist/src/network/validity-rejected-error.d.ts.map +1 -0
- package/dist/src/network/validity-rejected-error.js +51 -0
- package/dist/src/network/validity-rejected-error.js.map +1 -0
- package/dist/src/offline/entry.d.ts +72 -0
- package/dist/src/offline/entry.d.ts.map +1 -0
- package/dist/src/offline/entry.js +73 -0
- package/dist/src/offline/entry.js.map +1 -0
- package/dist/src/offline/index.d.ts +5 -0
- package/dist/src/offline/index.d.ts.map +1 -0
- package/dist/src/offline/index.js +5 -0
- package/dist/src/offline/index.js.map +1 -0
- package/dist/src/offline/journal.d.ts +61 -0
- package/dist/src/offline/journal.d.ts.map +1 -0
- package/dist/src/offline/journal.js +2 -0
- package/dist/src/offline/journal.js.map +1 -0
- package/dist/src/offline/queue.d.ts +484 -0
- package/dist/src/offline/queue.d.ts.map +1 -0
- package/dist/src/offline/queue.js +1236 -0
- package/dist/src/offline/queue.js.map +1 -0
- package/dist/src/offline/reachability.d.ts +25 -0
- package/dist/src/offline/reachability.d.ts.map +1 -0
- package/dist/src/offline/reachability.js +13 -0
- package/dist/src/offline/reachability.js.map +1 -0
- package/dist/src/offline/status.d.ts +148 -0
- package/dist/src/offline/status.d.ts.map +1 -0
- package/dist/src/offline/status.js +63 -0
- package/dist/src/offline/status.js.map +1 -0
- package/dist/src/offline/wake.d.ts +30 -0
- package/dist/src/offline/wake.d.ts.map +1 -0
- package/dist/src/offline/wake.js +68 -0
- package/dist/src/offline/wake.js.map +1 -0
- package/dist/src/reactivity/config.d.ts +8 -4
- package/dist/src/reactivity/config.d.ts.map +1 -1
- package/dist/src/reactivity/config.js +7 -3
- package/dist/src/reactivity/config.js.map +1 -1
- package/dist/src/reactivity/rotation.d.ts +9 -3
- package/dist/src/reactivity/rotation.d.ts.map +1 -1
- package/dist/src/reactivity/rotation.js +8 -2
- package/dist/src/reactivity/rotation.js.map +1 -1
- package/dist/src/testing/test-transactor.d.ts +31 -0
- package/dist/src/testing/test-transactor.d.ts.map +1 -1
- package/dist/src/testing/test-transactor.js +60 -0
- package/dist/src/testing/test-transactor.js.map +1 -1
- package/dist/src/transaction/commit-failure-class.d.ts +103 -0
- package/dist/src/transaction/commit-failure-class.d.ts.map +1 -0
- package/dist/src/transaction/commit-failure-class.js +96 -0
- package/dist/src/transaction/commit-failure-class.js.map +1 -0
- package/dist/src/transaction/coordinator.d.ts +224 -31
- package/dist/src/transaction/coordinator.d.ts.map +1 -1
- package/dist/src/transaction/coordinator.js +841 -362
- package/dist/src/transaction/coordinator.js.map +1 -1
- package/dist/src/transaction/entry-commit.d.ts +139 -0
- package/dist/src/transaction/entry-commit.d.ts.map +1 -0
- package/dist/src/transaction/entry-commit.js +199 -0
- package/dist/src/transaction/entry-commit.js.map +1 -0
- package/dist/src/transaction/index.d.ts +4 -1
- package/dist/src/transaction/index.d.ts.map +1 -1
- package/dist/src/transaction/index.js +1 -0
- package/dist/src/transaction/index.js.map +1 -1
- package/dist/src/transaction/transaction.d.ts +20 -0
- package/dist/src/transaction/transaction.d.ts.map +1 -1
- package/dist/src/transaction/validator.d.ts +7 -0
- package/dist/src/transaction/validator.d.ts.map +1 -1
- package/dist/src/transaction/validator.js +21 -12
- package/dist/src/transaction/validator.js.map +1 -1
- package/dist/src/transactor/change-notifier.d.ts +13 -4
- package/dist/src/transactor/change-notifier.d.ts.map +1 -1
- package/dist/src/transactor/change-notifier.js.map +1 -1
- package/dist/src/transactor/network-transactor.d.ts +58 -8
- package/dist/src/transactor/network-transactor.d.ts.map +1 -1
- package/dist/src/transactor/network-transactor.js +244 -50
- package/dist/src/transactor/network-transactor.js.map +1 -1
- package/dist/src/transactor/transactor-source.d.ts +22 -11
- package/dist/src/transactor/transactor-source.d.ts.map +1 -1
- package/dist/src/transactor/transactor-source.js +9 -13
- package/dist/src/transactor/transactor-source.js.map +1 -1
- package/dist/src/transactor/transactor.d.ts +14 -0
- package/dist/src/transactor/transactor.d.ts.map +1 -1
- package/dist/src/transform/digest.d.ts +20 -0
- package/dist/src/transform/digest.d.ts.map +1 -1
- package/dist/src/transform/digest.js +23 -3
- package/dist/src/transform/digest.js.map +1 -1
- package/dist/src/utility/visit-every.d.ts +14 -0
- package/dist/src/utility/visit-every.d.ts.map +1 -0
- package/dist/src/utility/visit-every.js +27 -0
- package/dist/src/utility/visit-every.js.map +1 -0
- package/package.json +1 -1
- package/src/blocks/helpers.ts +8 -1
- package/src/btree/btree.ts +266 -88
- package/src/btree/node-division.ts +155 -0
- package/src/chain/chain.ts +55 -6
- package/src/cluster/structs.ts +42 -7
- package/src/collection/action.ts +34 -0
- package/src/collection/collection.ts +1167 -540
- package/src/collection/head-commit.ts +148 -0
- package/src/collection/index.ts +2 -0
- package/src/collection/segments.ts +149 -0
- package/src/collection/struct.ts +201 -1
- package/src/collection/write-attempts.ts +506 -0
- package/src/collections/tree/struct.ts +97 -17
- package/src/collections/tree/tree.ts +129 -31
- package/src/index.ts +2 -0
- package/src/log/log.ts +7 -1
- package/src/network/block-size.ts +81 -0
- package/src/network/i-repo.ts +3 -0
- package/src/network/index.ts +5 -0
- package/src/network/promise-shortfall-error.ts +69 -0
- package/src/network/refuse-solo.ts +7 -0
- package/src/network/stale-failure.ts +27 -4
- package/src/network/struct.ts +169 -15
- package/src/network/transaction-size.ts +73 -0
- package/src/network/validity-rejected-error.ts +55 -0
- package/src/offline/entry.ts +127 -0
- package/src/offline/index.ts +4 -0
- package/src/offline/journal.ts +60 -0
- package/src/offline/queue.ts +1342 -0
- package/src/offline/reachability.ts +32 -0
- package/src/offline/status.ts +183 -0
- package/src/offline/wake.ts +67 -0
- package/src/reactivity/config.ts +8 -4
- package/src/reactivity/rotation.ts +9 -3
- package/src/testing/test-transactor.ts +65 -0
- package/src/transaction/commit-failure-class.ts +133 -0
- package/src/transaction/coordinator.ts +969 -393
- package/src/transaction/entry-commit.ts +285 -0
- package/src/transaction/index.ts +4 -0
- package/src/transaction/transaction.ts +21 -0
- package/src/transaction/validator.ts +22 -12
- package/src/transactor/change-notifier.ts +13 -4
- package/src/transactor/network-transactor.ts +252 -55
- package/src/transactor/transactor-source.ts +29 -13
- package/src/transactor/transactor.ts +16 -0
- package/src/transform/digest.ts +36 -3
- package/src/utility/visit-every.ts +25 -0
|
@@ -2,6 +2,7 @@ import type { BlockId, CollectionHeaderBlock, CollectionId } from "../../index.j
|
|
|
2
2
|
import type { KeyRange } from "../../btree/index.js";
|
|
3
3
|
import { registerBlockType } from "../../blocks/block-types.js";
|
|
4
4
|
import { registerCollectionType } from "../../collection/collection-type-registry.js";
|
|
5
|
+
import { ActionRefusedError } from "../../collection/struct.js";
|
|
5
6
|
import { nameof } from "../../utility/nameof.js";
|
|
6
7
|
|
|
7
8
|
export const TreeHeaderBlockType = registerBlockType("TRE", "TreeHeaderBlock");
|
|
@@ -39,6 +40,9 @@ export const rootId$ = nameof<TreeCollectionHeaderBlock>("rootId");
|
|
|
39
40
|
* re-stage of a present key (a replay after a clean refresh) would refuse itself.
|
|
40
41
|
* - `unchanged` — see {@link TreeUnchangedGuard}: the only kind that says something must
|
|
41
42
|
* still BE here, rather than that nothing may be.
|
|
43
|
+
* - `absentOrEqual`, `unchangedOrEqual`, `unchangedOrAbsent` — the three ALREADY-APPLIED variants
|
|
44
|
+
* (see {@link TreeAlreadyAppliedGuard}): each accepts, and SKIPS the element, where a rival has
|
|
45
|
+
* already made exactly the change this element makes, instead of refusing it.
|
|
42
46
|
*
|
|
43
47
|
* MIXED VERSIONS: a peer running a build that predates guards destructures `[key, entry]`
|
|
44
48
|
* and ignores the third slot — its replays revert to today's silent overwrite. No version
|
|
@@ -48,7 +52,52 @@ export type TreeEntryGuard<TKey, TEntry = unknown> =
|
|
|
48
52
|
| { kind: 'absent' }
|
|
49
53
|
| { kind: 'keepExisting' }
|
|
50
54
|
| { kind: 'absentRange', range: KeyRange<TKey> }
|
|
51
|
-
| TreeUnchangedGuard<TEntry
|
|
55
|
+
| TreeUnchangedGuard<TEntry>
|
|
56
|
+
| TreeAlreadyAppliedGuard<TEntry>;
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* The three guard kinds that accept a row another writer already changed the same way, for the
|
|
60
|
+
* offline-sync queue's rebase of a queued entry (docs/offline-sync.md §Guards that make idempotent
|
|
61
|
+
* writes assured). Every guard above refuses when the row is not as the staged write found it, which
|
|
62
|
+
* includes the rival that made exactly the change this write makes: two machines marking one task
|
|
63
|
+
* done, two machines deleting one row. Each variant below has three outcomes, where its base kind has
|
|
64
|
+
* two — it ACCEPTS AND WRITES as the base kind does, it ACCEPTS AS ALREADY APPLIED and skips the
|
|
65
|
+
* element (the final state is the one the write intended), or it REFUSES with the base kind's error:
|
|
66
|
+
*
|
|
67
|
+
* | Kind | Element | Writes when | Skips as already applied when | Refuses with |
|
|
68
|
+
* |---|---|---|---|---|
|
|
69
|
+
* | `absentOrEqual` | upsert | the key is absent | the present entry equals the element's own `entry` | {@link TreeKeyTakenError}, as `absent` does |
|
|
70
|
+
* | `unchangedOrEqual` | upsert | the present entry equals `expected` | the present entry equals the element's own `entry` (checked second, so a no-op update whose `expected` equals its `entry` writes) | {@link TreeEntryChangedError} on absent or any other entry |
|
|
71
|
+
* | `unchangedOrAbsent` | delete | the present entry equals `expected` | the key is absent | {@link TreeEntryChangedError} on any other entry |
|
|
72
|
+
*
|
|
73
|
+
* "Equals" is `structuralEquals` in `packages/db-core/src/utility/structural-equals.ts`, the
|
|
74
|
+
* comparison `unchanged` uses, with the same JSON caveats {@link TreeUnchangedGuard} states. The
|
|
75
|
+
* post-image an upsert variant compares against is the element's own `entry`, not a second copy on
|
|
76
|
+
* the guard: the element already carries it, so the guard stays the size its base kind is.
|
|
77
|
+
*
|
|
78
|
+
* Kinds and elements: `unchangedOrAbsent` is meaningful only on a delete (on an upsert it would mean
|
|
79
|
+
* "resurrect the row"), and the two `…OrEqual` kinds only on an upsert (a delete has no `entry` to
|
|
80
|
+
* compare, and would be a no-op by construction). The handler narrows both ways at runtime: a delete
|
|
81
|
+
* carrying an upsert-only kind throws {@link TreeDeleteGuardKindError}, an upsert carrying the
|
|
82
|
+
* delete-only kind {@link TreeUpsertGuardKindError} — malformed actions, outside the refusal
|
|
83
|
+
* hierarchy, never ignored.
|
|
84
|
+
*
|
|
85
|
+
* Whether an element accepted as already applied changed anything is reported out of the handler
|
|
86
|
+
* as an `AlreadyAppliedTally` (`packages/db-core/src/collection/action.ts`), which the offline queue
|
|
87
|
+
* folds into the `effect` of its `committed` status.
|
|
88
|
+
*/
|
|
89
|
+
export type TreeAlreadyAppliedGuard<TEntry = unknown> =
|
|
90
|
+
| { kind: 'absentOrEqual' }
|
|
91
|
+
| { kind: 'unchangedOrEqual', /** The entry image the staged write read, as stored. */ expected: TEntry }
|
|
92
|
+
| { kind: 'unchangedOrAbsent', /** The entry image the staged delete read, as stored. */ expected: TEntry };
|
|
93
|
+
|
|
94
|
+
/** The kinds a {@link TreeUpsertElement} may carry: every kind but the delete-only
|
|
95
|
+
* `unchangedOrAbsent`. */
|
|
96
|
+
export type TreeUpsertGuard<TKey, TEntry = unknown> = Exclude<TreeEntryGuard<TKey, TEntry>, { kind: 'unchangedOrAbsent' }>;
|
|
97
|
+
|
|
98
|
+
/** The kinds a {@link TreeDeleteElement} may carry: the two that say something must still BE at the
|
|
99
|
+
* key — `unchanged`, and `unchangedOrAbsent`, which also accepts the key already gone. */
|
|
100
|
+
export type TreeDeleteGuard<TEntry = unknown> = TreeUnchangedGuard<TEntry> | Extract<TreeAlreadyAppliedGuard<TEntry>, { kind: 'unchangedOrAbsent' }>;
|
|
52
101
|
|
|
53
102
|
/**
|
|
54
103
|
* "The entry I am replacing must still be exactly the one I read" — the optimistic-concurrency
|
|
@@ -61,8 +110,9 @@ export type TreeEntryGuard<TKey, TEntry = unknown> =
|
|
|
61
110
|
* exists, so re-applying it is never right: an upsert would resurrect a row a rival deleted, and
|
|
62
111
|
* a delete would be the second of two racing deletes. Refusing both is the optimistic answer —
|
|
63
112
|
* the writer read a row that is now gone, and an application-level retry then affects zero rows
|
|
64
|
-
* sequentially.
|
|
65
|
-
*
|
|
113
|
+
* sequentially. A delete that means "gone either way" carries `unchangedOrAbsent` instead, and an
|
|
114
|
+
* upsert that means "equal either way" carries `unchangedOrEqual` ({@link TreeAlreadyAppliedGuard});
|
|
115
|
+
* this kind's contract is not weakened for them.
|
|
66
116
|
*
|
|
67
117
|
* `expected` is the entry AS STORED, not a digest: a guard rides in the log beside its action
|
|
68
118
|
* under the same encoding entries already use, so a full copy round-trips by construction and no
|
|
@@ -80,8 +130,8 @@ export type TreeUnchangedGuard<TEntry = unknown> = {
|
|
|
80
130
|
expected: TEntry,
|
|
81
131
|
};
|
|
82
132
|
|
|
83
|
-
/** An element that writes (inserts or replaces) an entry.
|
|
84
|
-
* meaningful here. */
|
|
133
|
+
/** An element that writes (inserts or replaces) an entry. Every {@link TreeEntryGuard} kind but the
|
|
134
|
+
* delete-only `unchangedOrAbsent` is meaningful here ({@link TreeUpsertGuard}). */
|
|
85
135
|
export type TreeUpsertElement<TKey, TEntry> = [
|
|
86
136
|
// The key to write at
|
|
87
137
|
key: TKey,
|
|
@@ -90,20 +140,22 @@ export type TreeUpsertElement<TKey, TEntry> = [
|
|
|
90
140
|
// Optional intent, re-checked on every handler run (see TreeEntryGuard). Absent = plain
|
|
91
141
|
// upsert, so existing callers and previously committed log entries deserialize and replay
|
|
92
142
|
// unchanged.
|
|
93
|
-
guard?:
|
|
143
|
+
guard?: TreeUpsertGuard<TKey, TEntry>,
|
|
94
144
|
];
|
|
95
145
|
|
|
96
|
-
/** An element that deletes the entry at a key. Only
|
|
97
|
-
* delete can act on — the other kinds all assert
|
|
98
|
-
* delete a no-op by construction. The handler rejects
|
|
99
|
-
* replayed log entry is deserialized data that this type
|
|
146
|
+
/** An element that deletes the entry at a key. Only the two kinds that say something must still BE
|
|
147
|
+
* at the key say anything a delete can act on ({@link TreeDeleteGuard}) — the other kinds all assert
|
|
148
|
+
* that nothing is present, which would make the delete a no-op by construction. The handler rejects
|
|
149
|
+
* any other kind at runtime too, since a replayed log entry is deserialized data that this type
|
|
150
|
+
* never policed. */
|
|
100
151
|
export type TreeDeleteElement<TKey, TEntry> = [
|
|
101
152
|
// The key to delete
|
|
102
153
|
key: TKey,
|
|
103
154
|
// Always empty: the absent entry is what marks this element a delete
|
|
104
155
|
entry?: undefined,
|
|
105
156
|
// Optional lost-update guard: refuse the delete unless the entry is still the one that was read
|
|
106
|
-
|
|
157
|
+
// (`unchanged`), or unless it is either that or already gone (`unchangedOrAbsent`)
|
|
158
|
+
guard?: TreeDeleteGuard<TEntry>,
|
|
107
159
|
];
|
|
108
160
|
|
|
109
161
|
/** Represents a unit of change to a tree collection. */
|
|
@@ -129,16 +181,21 @@ export type TreeReplaceAction<TKey, TEntry> = (
|
|
|
129
181
|
* {@link TreeEntryChangedError} is a lost update (the bridge raises its
|
|
130
182
|
* `ConcurrentModificationError`, status code BUSY, which is not a constraint error). Catch
|
|
131
183
|
* this base to treat any guard refusal uniformly; catch a subclass to say which happened.
|
|
184
|
+
*
|
|
185
|
+
* It is the tree's {@link ActionRefusedError}, which is what the collection's segment-aware
|
|
186
|
+
* replay recognises (a refusal from a sealed segment is recorded against that segment rather
|
|
187
|
+
* than thrown — see `Collection.replayActions`); the classifier and the bridge keep matching
|
|
188
|
+
* this class, which the subclass relation leaves unchanged.
|
|
132
189
|
*/
|
|
133
|
-
export class TreeGuardRefusedError<TKey = unknown> extends
|
|
190
|
+
export class TreeGuardRefusedError<TKey = unknown> extends ActionRefusedError {
|
|
134
191
|
constructor(
|
|
135
192
|
/** The collection whose tree refused the entry. */
|
|
136
|
-
|
|
193
|
+
collectionId: CollectionId,
|
|
137
194
|
/** The key whose staged entry was refused. */
|
|
138
195
|
public readonly key: TKey,
|
|
139
196
|
message: string,
|
|
140
197
|
) {
|
|
141
|
-
super(message);
|
|
198
|
+
super(collectionId, message);
|
|
142
199
|
this.name = 'TreeGuardRefusedError';
|
|
143
200
|
}
|
|
144
201
|
}
|
|
@@ -226,7 +283,8 @@ export class TreeEntryChangedError<TKey = unknown, TEntry = unknown> extends Tre
|
|
|
226
283
|
* present, which would make the delete a no-op by construction, so this is a malformed action —
|
|
227
284
|
* a caller bug, or a log entry written by a build whose element types disagree with this one.
|
|
228
285
|
* The handler raises it rather than ignoring the guard (the pre-guard behaviour) so a writer
|
|
229
|
-
* never believes an unenforceable guard is being enforced.
|
|
286
|
+
* never believes an unenforceable guard is being enforced. {@link TreeUpsertGuardKindError} is the
|
|
287
|
+
* upsert side of the same check.
|
|
230
288
|
*/
|
|
231
289
|
export class TreeDeleteGuardKindError<TKey = unknown> extends Error {
|
|
232
290
|
constructor(
|
|
@@ -234,15 +292,37 @@ export class TreeDeleteGuardKindError<TKey = unknown> extends Error {
|
|
|
234
292
|
public readonly collectionId: CollectionId,
|
|
235
293
|
/** The key the malformed delete named. */
|
|
236
294
|
public readonly key: TKey,
|
|
237
|
-
/** The `kind` that was carried; only `'unchanged'`
|
|
295
|
+
/** The `kind` that was carried; only `'unchanged'` and `'unchangedOrAbsent'` are meaningful on
|
|
296
|
+
* a delete. */
|
|
238
297
|
public readonly guardKind: string,
|
|
239
298
|
) {
|
|
240
299
|
super(`Tree collection ${collectionId}: the delete of key ${renderKey(key)} carries a `
|
|
241
|
-
+ `'${guardKind}' guard; only 'unchanged'
|
|
300
|
+
+ `'${guardKind}' guard; only 'unchanged' and 'unchangedOrAbsent' are meaningful on a delete`);
|
|
242
301
|
this.name = 'TreeDeleteGuardKindError';
|
|
243
302
|
}
|
|
244
303
|
}
|
|
245
304
|
|
|
305
|
+
/**
|
|
306
|
+
* An UPSERT element carries the delete-only guard kind, `unchangedOrAbsent`: on an upsert it would
|
|
307
|
+
* mean "write the row whether or not a rival deleted it", which resurrects a row the staged write
|
|
308
|
+
* never meant to and so is a malformed action, not a concurrency refusal — the mirror of
|
|
309
|
+
* {@link TreeDeleteGuardKindError}, and like it deliberately not a {@link TreeGuardRefusedError}.
|
|
310
|
+
*/
|
|
311
|
+
export class TreeUpsertGuardKindError<TKey = unknown> extends Error {
|
|
312
|
+
constructor(
|
|
313
|
+
/** The collection whose tree rejected the element. */
|
|
314
|
+
public readonly collectionId: CollectionId,
|
|
315
|
+
/** The key the malformed upsert named. */
|
|
316
|
+
public readonly key: TKey,
|
|
317
|
+
/** The `kind` that was carried. */
|
|
318
|
+
public readonly guardKind: string,
|
|
319
|
+
) {
|
|
320
|
+
super(`Tree collection ${collectionId}: the upsert of key ${renderKey(key)} carries a `
|
|
321
|
+
+ `'${guardKind}' guard, which is meaningful only on a delete`);
|
|
322
|
+
this.name = 'TreeUpsertGuardKindError';
|
|
323
|
+
}
|
|
324
|
+
}
|
|
325
|
+
|
|
246
326
|
/** String keys render JSON-quoted so framing control bytes stay visible/escaped in logs;
|
|
247
327
|
* everything else via String() — JSON.stringify would throw on a bigint key, and an error
|
|
248
328
|
* constructor must never be the second failure. Module-private on purpose: every tree message
|
|
@@ -3,28 +3,40 @@ import type { ITransactor, BlockId, BlockStore, IBlock, ActionId, WriteDurabilit
|
|
|
3
3
|
import { BTree, type Path, type KeyRange } from "../../btree/index.js";
|
|
4
4
|
import { CollectionTrunk } from "./collection-trunk.js";
|
|
5
5
|
import { structuralEquals } from "../../utility/structural-equals.js";
|
|
6
|
+
import { BLOCK_TARGET_BYTES } from "../../network/block-size.js";
|
|
7
|
+
import { ZeroTally } from "../../collection/action.js";
|
|
8
|
+
import type { AlreadyAppliedTally } from "../../collection/action.js";
|
|
6
9
|
import {
|
|
7
10
|
TreeHeaderBlockType, TreeDeleteGuardKindError, TreeEntryChangedError, TreeKeyTakenError,
|
|
8
|
-
TreeRangeTakenError, type TreeEntryGuard, type TreeReplaceAction,
|
|
11
|
+
TreeRangeTakenError, TreeUpsertGuardKindError, type TreeEntryGuard, type TreeReplaceAction,
|
|
9
12
|
} from "./struct.js";
|
|
10
13
|
|
|
14
|
+
/** What a guard decided for its element: write it, skip it with no claim about equality
|
|
15
|
+
* (`keepExisting` found the key occupied), or skip it because a rival already made exactly this
|
|
16
|
+
* change — the already-applied acceptance a `TreeAlreadyAppliedGuard` kind makes, which is the one
|
|
17
|
+
* skip the handler counts (`alreadyApplied` on the {@link AlreadyAppliedTally}). */
|
|
18
|
+
type GuardVerdict = 'proceed' | 'skip' | 'already-applied';
|
|
19
|
+
|
|
11
20
|
/**
|
|
12
21
|
* Enforce a guard carried by an UPSERT element against the CURRENT content of `actionTree` —
|
|
13
22
|
* the same Atomic store the upsert writes to, so it sees what earlier elements of this same
|
|
14
23
|
* replay already staged or deleted (an UPDATE's delete-old half runs before its guarded insert
|
|
15
|
-
* half). Throws the guard's refusal, which discards the whole action's staged writes.
|
|
24
|
+
* half). Throws the guard's refusal, which discards the whole action's staged writes. `entry` is the
|
|
25
|
+
* element's own entry, the post-image the `…OrEqual` kinds compare against.
|
|
16
26
|
*
|
|
17
27
|
* @returns `'skip'` when the element must be left unwritten (`keepExisting` found the key
|
|
18
|
-
* occupied — the INSERT OR IGNORE disposition), `'
|
|
28
|
+
* occupied — the INSERT OR IGNORE disposition), `'already-applied'` when an already-applied kind
|
|
29
|
+
* found the rival had made this change, `'proceed'` otherwise.
|
|
19
30
|
*/
|
|
20
31
|
async function enforceUpsertGuard<TKey, TEntry>(
|
|
21
32
|
actionTree: BTree<TKey, TEntry>,
|
|
22
33
|
id: CollectionId,
|
|
23
34
|
key: TKey,
|
|
35
|
+
entry: TEntry,
|
|
24
36
|
guard: TreeEntryGuard<TKey, TEntry>,
|
|
25
37
|
keyFromEntry: (entry: TEntry) => TKey,
|
|
26
38
|
compare: (a: TKey, b: TKey) => number,
|
|
27
|
-
): Promise<
|
|
39
|
+
): Promise<GuardVerdict> {
|
|
28
40
|
switch (guard.kind) {
|
|
29
41
|
case 'absentRange': {
|
|
30
42
|
// Secondary-UNIQUE: the claimed range (a unique index's framed value prefix) must hold
|
|
@@ -52,6 +64,86 @@ async function enforceUpsertGuard<TKey, TEntry>(
|
|
|
52
64
|
// keepExisting: leave the present (rival's) entry in place and skip this element.
|
|
53
65
|
return 'skip';
|
|
54
66
|
}
|
|
67
|
+
case 'absentOrEqual': {
|
|
68
|
+
const actual = actionTree.at(await actionTree.find(key));
|
|
69
|
+
if (actual === undefined) return 'proceed';
|
|
70
|
+
if (structuralEquals(actual, entry)) return 'already-applied';
|
|
71
|
+
throw new TreeKeyTakenError(id, key);
|
|
72
|
+
}
|
|
73
|
+
case 'unchangedOrEqual': {
|
|
74
|
+
const actual = actionTree.at(await actionTree.find(key));
|
|
75
|
+
// `expected` first: a no-op update (expected equals entry) writes and counts as applied.
|
|
76
|
+
if (actual !== undefined && structuralEquals(actual, guard.expected)) return 'proceed';
|
|
77
|
+
if (actual !== undefined && structuralEquals(actual, entry)) return 'already-applied';
|
|
78
|
+
throw new TreeEntryChangedError(id, key, guard.expected, actual);
|
|
79
|
+
}
|
|
80
|
+
case 'unchangedOrAbsent': {
|
|
81
|
+
throw new TreeUpsertGuardKindError(id, key, guard.kind);
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* Enforce a guard carried by a DELETE element against the entry found at its path. Throws the
|
|
88
|
+
* guard's refusal, or {@link TreeDeleteGuardKindError} for a kind no delete can act on — the element
|
|
89
|
+
* type already says so ({@link TreeDeleteElement}), but a replayed log entry is deserialized data
|
|
90
|
+
* that no type policed, so the handler re-checks rather than silently ignoring a guard the writer
|
|
91
|
+
* believed was being enforced.
|
|
92
|
+
*
|
|
93
|
+
* @returns `'already-applied'` when `unchangedOrAbsent` found the key already gone (nothing to
|
|
94
|
+
* delete), `'proceed'` otherwise.
|
|
95
|
+
*/
|
|
96
|
+
function enforceDeleteGuard<TKey, TEntry>(
|
|
97
|
+
id: CollectionId,
|
|
98
|
+
key: TKey,
|
|
99
|
+
guard: TreeEntryGuard<TKey, TEntry>,
|
|
100
|
+
actual: TEntry | undefined,
|
|
101
|
+
): Exclude<GuardVerdict, 'skip'> {
|
|
102
|
+
switch (guard.kind) {
|
|
103
|
+
case 'unchanged': {
|
|
104
|
+
assertEntryUnchanged(id, key, guard.expected, actual);
|
|
105
|
+
return 'proceed';
|
|
106
|
+
}
|
|
107
|
+
case 'unchangedOrAbsent': {
|
|
108
|
+
if (actual === undefined) return 'already-applied';
|
|
109
|
+
assertEntryUnchanged(id, key, guard.expected, actual);
|
|
110
|
+
return 'proceed';
|
|
111
|
+
}
|
|
112
|
+
default: {
|
|
113
|
+
throw new TreeDeleteGuardKindError(id, key, guard.kind);
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/** Whether a write under `guard` counts as `applied` on the tally (see {@link AlreadyAppliedTally}):
|
|
119
|
+
* the three already-applied kinds, whose skips are the `alreadyApplied` side, and the two exact-key
|
|
120
|
+
* base kinds that write whenever they do not refuse — `absent` and `unchanged`, which the SQL layer
|
|
121
|
+
* stages on every main-table element and never on an index tree — so an entry with a plain insert
|
|
122
|
+
* beside an already-applied update reads `applied`, as a host taking `already-applied` for "none of
|
|
123
|
+
* my changes landed" needs. Not counted: `keepExisting` (its skip says nothing about equality),
|
|
124
|
+
* `absentRange` and an unguarded element, the shapes an index tree's entries take, whose writes
|
|
125
|
+
* under an already-applied entry are rewrites of what the rival's row already implies. */
|
|
126
|
+
function countsWrite<TKey, TEntry>(guard: TreeEntryGuard<TKey, TEntry>): boolean {
|
|
127
|
+
return guard.kind === 'absent' || guard.kind === 'unchanged'
|
|
128
|
+
|| guard.kind === 'absentOrEqual' || guard.kind === 'unchangedOrEqual' || guard.kind === 'unchangedOrAbsent';
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/** A tally over one handler run, mutable while the run counts. */
|
|
132
|
+
class TallyBuilder {
|
|
133
|
+
private alreadyApplied = 0;
|
|
134
|
+
private applied = 0;
|
|
135
|
+
|
|
136
|
+
/** Count `verdict` for an element carrying `guard`. Only an already-applied kind answers
|
|
137
|
+
* `'already-applied'`; a write counts when {@link countsWrite} says so. */
|
|
138
|
+
count<TKey, TEntry>(guard: TreeEntryGuard<TKey, TEntry>, verdict: GuardVerdict): void {
|
|
139
|
+
if (verdict === 'already-applied') this.alreadyApplied++;
|
|
140
|
+
else if (verdict === 'proceed' && countsWrite(guard)) this.applied++;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
result(): AlreadyAppliedTally {
|
|
144
|
+
return this.alreadyApplied === 0 && this.applied === 0
|
|
145
|
+
? ZeroTally
|
|
146
|
+
: { alreadyApplied: this.alreadyApplied, applied: this.applied };
|
|
55
147
|
}
|
|
56
148
|
}
|
|
57
149
|
|
|
@@ -69,21 +161,6 @@ function assertEntryUnchanged<TKey, TEntry>(
|
|
|
69
161
|
}
|
|
70
162
|
}
|
|
71
163
|
|
|
72
|
-
/** Narrow a DELETE element's guard to the only kind a delete can act on. The element type already
|
|
73
|
-
* says this ({@link TreeDeleteElement}), but a replayed log entry is deserialized data that no
|
|
74
|
-
* type policed, so the handler re-checks it and throws {@link TreeDeleteGuardKindError} rather
|
|
75
|
-
* than silently ignoring a guard the writer believed was being enforced. */
|
|
76
|
-
function deleteGuardExpected<TKey, TEntry>(
|
|
77
|
-
id: CollectionId,
|
|
78
|
-
key: TKey,
|
|
79
|
-
guard: TreeEntryGuard<TKey, TEntry>,
|
|
80
|
-
): TEntry {
|
|
81
|
-
if (guard.kind !== 'unchanged') {
|
|
82
|
-
throw new TreeDeleteGuardKindError(id, key, guard.kind);
|
|
83
|
-
}
|
|
84
|
-
return guard.expected;
|
|
85
|
-
}
|
|
86
|
-
|
|
87
164
|
/**
|
|
88
165
|
* Read-only surface of a tree: every navigation/lookup method a reader needs, with
|
|
89
166
|
* none of the mutation (stage/sync) or network-refresh (update) entry points. Both
|
|
@@ -107,6 +184,11 @@ interface BTreeHolder<TKey, TEntry> {
|
|
|
107
184
|
btree?: BTree<TKey, TEntry>;
|
|
108
185
|
}
|
|
109
186
|
|
|
187
|
+
/** The collection options a tree's opener may set — the ones that are not the tree's own to
|
|
188
|
+
* decide. Today that is the sealed-segment refusal callback the offline-sync queue installs
|
|
189
|
+
* (see {@link CollectionInitOptions.onSealedRefused}). */
|
|
190
|
+
export type TreeCollectionOptions = Pick<CollectionInitOptions<unknown>, 'onSealedRefused'>;
|
|
191
|
+
|
|
110
192
|
export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
|
|
111
193
|
|
|
112
194
|
private constructor(
|
|
@@ -129,9 +211,11 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
|
|
|
129
211
|
compare = (a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0,
|
|
130
212
|
/** See {@link Tree.createOrOpen}'s `nodeCapacity`. */
|
|
131
213
|
nodeCapacity?: number,
|
|
214
|
+
/** See {@link Tree.createOrOpen}'s `options`. */
|
|
215
|
+
options?: TreeCollectionOptions,
|
|
132
216
|
): Promise<Tree<TKey, TEntry> | undefined> {
|
|
133
217
|
const held: BTreeHolder<TKey, TEntry> = {};
|
|
134
|
-
const init = Tree.buildInit(id, keyFromEntry, compare, nodeCapacity, held);
|
|
218
|
+
const init = Tree.buildInit(id, keyFromEntry, compare, nodeCapacity, held, options);
|
|
135
219
|
const collection = await Collection.open<TreeReplaceAction<TKey, TEntry>>(network, id, init);
|
|
136
220
|
return collection ? Tree.attach(collection, held, keyFromEntry, compare, nodeCapacity) : undefined;
|
|
137
221
|
}
|
|
@@ -153,9 +237,12 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
|
|
|
153
237
|
* they pass it consistently); if a persisted tree ever needs a custom fan-out, persist it in
|
|
154
238
|
* the header and read it back on reopen rather than trusting the caller to re-supply it. */
|
|
155
239
|
nodeCapacity?: number,
|
|
240
|
+
/** Collection options the opener sets rather than the tree: the sealed-segment refusal
|
|
241
|
+
* callback (see {@link TreeCollectionOptions}). Omit for a tree nothing seals. */
|
|
242
|
+
options?: TreeCollectionOptions,
|
|
156
243
|
): Promise<Tree<TKey, TEntry>> {
|
|
157
244
|
const held: BTreeHolder<TKey, TEntry> = {};
|
|
158
|
-
const init = Tree.buildInit(id, keyFromEntry, compare, nodeCapacity, held);
|
|
245
|
+
const init = Tree.buildInit(id, keyFromEntry, compare, nodeCapacity, held, options);
|
|
159
246
|
const collection = await Collection.createOrOpen<TreeReplaceAction<TKey, TEntry>>(network, id, init);
|
|
160
247
|
return Tree.attach(collection, held, keyFromEntry, compare, nodeCapacity);
|
|
161
248
|
}
|
|
@@ -168,10 +255,12 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
|
|
|
168
255
|
compare: (a: TKey, b: TKey) => number,
|
|
169
256
|
nodeCapacity: number | undefined,
|
|
170
257
|
held: BTreeHolder<TKey, TEntry>,
|
|
258
|
+
options: TreeCollectionOptions | undefined,
|
|
171
259
|
): CollectionInitOptions<TreeReplaceAction<TKey, TEntry>> {
|
|
172
260
|
return {
|
|
261
|
+
...options,
|
|
173
262
|
modules: {
|
|
174
|
-
"replace": async ({ data: actions }, trx) => {
|
|
263
|
+
"replace": async ({ data: actions }, trx): Promise<AlreadyAppliedTally> => {
|
|
175
264
|
// Write through the Atomic store the handler is handed (`trx`), NOT the captured
|
|
176
265
|
// read btree, so `internalTransact`'s all-or-nothing wrapper actually governs this
|
|
177
266
|
// action: if any entry throws, `atomic.commit()` is skipped and every staged node
|
|
@@ -184,7 +273,9 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
|
|
|
184
273
|
keyFromEntry,
|
|
185
274
|
compare,
|
|
186
275
|
nodeCapacity, // keep the write btree's fan-out in lock-step with the read btree
|
|
276
|
+
BLOCK_TARGET_BYTES, // and its node size rule: every node is a block that must stay copyable
|
|
187
277
|
);
|
|
278
|
+
const tally = new TallyBuilder();
|
|
188
279
|
for (const [key, entry, guard] of actions) {
|
|
189
280
|
// NOTE: an element is a DELETE when its entry slot is falsy, not when it is
|
|
190
281
|
// strictly `undefined`. That is deliberate and load-bearing: JSON encodes the
|
|
@@ -209,9 +300,10 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
|
|
|
209
300
|
// slot above: an explicitly-passed `undefined` guard (the shape every unguarded
|
|
210
301
|
// index write stages) comes back from JSON as `null`, and reading `.kind` off it
|
|
211
302
|
// would throw a TypeError mid-replay instead of meaning "no guard".
|
|
212
|
-
if (guard
|
|
213
|
-
|
|
214
|
-
|
|
303
|
+
if (guard) {
|
|
304
|
+
const verdict = await enforceUpsertGuard(actionTree, id, key, entry, guard, keyFromEntry, compare);
|
|
305
|
+
tally.count(guard, verdict);
|
|
306
|
+
if (verdict !== 'proceed') continue;
|
|
215
307
|
}
|
|
216
308
|
await actionTree.upsert(entry);
|
|
217
309
|
} else {
|
|
@@ -219,7 +311,9 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
|
|
|
219
311
|
// consumes it, with no mutation in between to invalidate it.
|
|
220
312
|
const path = await actionTree.find(key);
|
|
221
313
|
if (guard) {
|
|
222
|
-
|
|
314
|
+
const verdict = enforceDeleteGuard(id, key, guard, actionTree.at(path));
|
|
315
|
+
tally.count(guard, verdict);
|
|
316
|
+
if (verdict === 'already-applied') continue;
|
|
223
317
|
}
|
|
224
318
|
await actionTree.deleteAt(path);
|
|
225
319
|
}
|
|
@@ -228,6 +322,7 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
|
|
|
228
322
|
// Bump it to invalidate any Path a caller still holds — preserving the path-invalidation
|
|
229
323
|
// the previous in-place handler gave for free.
|
|
230
324
|
held.btree?.invalidatePaths();
|
|
325
|
+
return tally.result();
|
|
231
326
|
}
|
|
232
327
|
},
|
|
233
328
|
createHeaderBlock: (hid: BlockId, store: BlockStore<IBlock>) => { // Only called if the collection does not exist
|
|
@@ -237,7 +332,7 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
|
|
|
237
332
|
held.btree = BTree.create<TKey, TEntry>(store, (_s, r) => {
|
|
238
333
|
rootId = r;
|
|
239
334
|
return new CollectionTrunk(store, hid);
|
|
240
|
-
}, keyFromEntry, compare, nodeCapacity);
|
|
335
|
+
}, keyFromEntry, compare, nodeCapacity, undefined, BLOCK_TARGET_BYTES);
|
|
241
336
|
return {
|
|
242
337
|
header: store.createBlockHeader(TreeHeaderBlockType, hid),
|
|
243
338
|
rootId: rootId!,
|
|
@@ -258,7 +353,7 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
|
|
|
258
353
|
nodeCapacity: number | undefined,
|
|
259
354
|
): Tree<TKey, TEntry> {
|
|
260
355
|
held.btree = held.btree
|
|
261
|
-
?? new BTree<TKey, TEntry>(collection.tracker, new CollectionTrunk(collection.tracker, collection.id), keyFromEntry, compare, nodeCapacity);
|
|
356
|
+
?? new BTree<TKey, TEntry>(collection.tracker, new CollectionTrunk(collection.tracker, collection.id), keyFromEntry, compare, nodeCapacity, BLOCK_TARGET_BYTES);
|
|
262
357
|
return new Tree<TKey, TEntry>(collection, held.btree, keyFromEntry, compare);
|
|
263
358
|
}
|
|
264
359
|
|
|
@@ -309,9 +404,12 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
|
|
|
309
404
|
|
|
310
405
|
/** Restore the staged state captured by {@link snapshot}, discarding mutations
|
|
311
406
|
* staged since. Counterpart to {@link stage} for transaction rollback —
|
|
312
|
-
* preserves a never-synced collection's header/root rather than wiping it.
|
|
313
|
-
|
|
314
|
-
|
|
407
|
+
* preserves a never-synced collection's header/root rather than wiping it.
|
|
408
|
+
* Resolves once the restore is complete: a restore across a change to the
|
|
409
|
+
* collection's sealed segments replays them, which runs the action handlers
|
|
410
|
+
* (see {@link Collection.restorePending}). */
|
|
411
|
+
async restore(snapshot: CollectionSnapshot<TreeReplaceAction<TKey, TEntry>>): Promise<void> {
|
|
412
|
+
await this.collection.restorePending(snapshot);
|
|
315
413
|
}
|
|
316
414
|
|
|
317
415
|
/** Build a read-only view of this tree as captured by an earlier {@link snapshot}
|
package/src/index.ts
CHANGED
|
@@ -9,6 +9,7 @@ export * from "./log/index.js";
|
|
|
9
9
|
export * from "./logger-registry.js";
|
|
10
10
|
export * from "./matchmaking/index.js";
|
|
11
11
|
export * from "./network/index.js";
|
|
12
|
+
export * from "./offline/index.js";
|
|
12
13
|
export * from "./reactivity/index.js";
|
|
13
14
|
export * from "./transaction/index.js";
|
|
14
15
|
export * from "./transactor/index.js";
|
|
@@ -25,3 +26,4 @@ export * from "./utility/pending.js";
|
|
|
25
26
|
export * from "./utility/lru-map.js";
|
|
26
27
|
export * from "./utility/backoff.js";
|
|
27
28
|
export * from "./utility/unref-timer.js";
|
|
29
|
+
export * from "./utility/visit-every.js";
|
package/src/log/log.ts
CHANGED
|
@@ -7,6 +7,7 @@ import type { LogEntry, ActionEntry, DisputeResolutionProof, InvalidationEntry,
|
|
|
7
7
|
import { LogDataBlockType, LogHeaderBlockType } from "./struct.js";
|
|
8
8
|
import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
|
|
9
9
|
import type { GetFromResult } from './struct.js';
|
|
10
|
+
import { BLOCK_TARGET_BYTES } from '../network/block-size.js';
|
|
10
11
|
|
|
11
12
|
export type LogBlock<TAction> = ChainDataNode<LogEntry<TAction>>
|
|
12
13
|
& {
|
|
@@ -284,10 +285,15 @@ export class Log<TAction> {
|
|
|
284
285
|
return pendings;
|
|
285
286
|
}
|
|
286
287
|
|
|
287
|
-
/** Chain options used by every log: block type factories
|
|
288
|
+
/** Chain options used by every log: block type factories, the priorHash `newBlock` hook, and the
|
|
289
|
+
* byte target a log block rolls over at. Every entry carries its action's data, so a count alone
|
|
290
|
+
* would let a log of large entries build a block too large to copy between machines; with
|
|
291
|
+
* {@link BLOCK_TARGET_BYTES} a log block either holds one entry (and is then no larger than the
|
|
292
|
+
* transaction that wrote it) or stays near the target.
|
|
288
293
|
* Exposed (not private) so tests can drive a raw {@link Chain} through the exact same hook. */
|
|
289
294
|
static getChainOptions<TAction>(store: BlockStore<IBlock>, newDataBlockId?: () => BlockId) {
|
|
290
295
|
return {
|
|
296
|
+
blockTargetBytes: BLOCK_TARGET_BYTES,
|
|
291
297
|
createDataBlock: () => ({ header: store.createBlockHeader(LogDataBlockType, newDataBlockId?.()) }),
|
|
292
298
|
createHeaderBlock: (id?: BlockId) => ({ header: store.createBlockHeader(LogHeaderBlockType, id) }),
|
|
293
299
|
newBlock: async (newTail: LogBlock<TAction>, oldTail: LogBlock<TAction> | undefined) => {
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
import type { BlockId } from "../blocks/structs.js";
|
|
2
|
+
import { MAX_TRANSACTION_BYTES } from "./transaction-size.js";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* The most bytes one block may encode to, measured by `jsonEncodedBytes` (the UTF-8 length of its
|
|
6
|
+
* `JSON.stringify`): 7.5 MiB, the same as {@link MAX_TRANSACTION_BYTES}.
|
|
7
|
+
*
|
|
8
|
+
* Every path that copies a whole block to another machine sends it in one message under db-p2p's
|
|
9
|
+
* `MAX_BLOCK_MESSAGE_BYTES` frame cap — a replication push, a sync archive answer, a remote `get` reply —
|
|
10
|
+
* so a block larger than one frame can never be replicated, repaired or read remotely. Two things pin the
|
|
11
|
+
* value:
|
|
12
|
+
*
|
|
13
|
+
* - **It fits the frame with its wrapping.** A block at this size, plus what it travels in (a `get`
|
|
14
|
+
* reply entry's state, an archive revision entry, a push's metadata and commit proof), fits the
|
|
15
|
+
* 8 MiB frame inside the same envelope reserve a transaction gets (`TRANSACTION_ENVELOPE_RESERVE_BYTES`).
|
|
16
|
+
* - **No single transaction can exceed it on its own.** A block holding one entry or child is never
|
|
17
|
+
* larger than the transaction that wrote it, since that entry is inside the transaction's pend (as the
|
|
18
|
+
* new block's insert, or as the update operation that appends it), and the pend is held to
|
|
19
|
+
* {@link MAX_TRANSACTION_BYTES}.
|
|
20
|
+
*
|
|
21
|
+
* Structures that hold many entries per block (the log, tree nodes) keep each block that holds more than
|
|
22
|
+
* one entry near {@link BLOCK_TARGET_BYTES}, far under this limit; this is the bound itself.
|
|
23
|
+
*/
|
|
24
|
+
export const MAX_BLOCK_BYTES = MAX_TRANSACTION_BYTES;
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* The size past which a block holding more than one entry starts a new block: 1 MiB, by the same
|
|
28
|
+
* `jsonEncodedBytes` measure as {@link MAX_BLOCK_BYTES}. The log rolls over to a new tail block at it
|
|
29
|
+
* (`ChainInitOptions.blockTargetBytes`); an entry larger than it sits alone in its own block.
|
|
30
|
+
*
|
|
31
|
+
* Why 1 MiB:
|
|
32
|
+
*
|
|
33
|
+
* - One block's copy stays far under the 8 MiB frame, so a remote `get` reply carrying a few blocks
|
|
34
|
+
* still fits one message in the ordinary case, and a single replication push stays short on a slow
|
|
35
|
+
* relayed link.
|
|
36
|
+
* - It is 32 entries of 32 KiB, so a log of ordinary small entries keeps rolling over by count
|
|
37
|
+
* (`EntriesPerBlock`) exactly as it did before the size rule.
|
|
38
|
+
*
|
|
39
|
+
* The cost: a structure of large entries spreads over more blocks, so walking it reads more blocks.
|
|
40
|
+
*/
|
|
41
|
+
export const BLOCK_TARGET_BYTES = 1024 * 1024;
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* A write that would leave a block larger than {@link MAX_BLOCK_BYTES}: once committed, the block could
|
|
45
|
+
* never be copied to another machine in one message. Raised by the writer before anything is sent
|
|
46
|
+
* ({@link oversizedBlock}), so nothing was reserved and nothing needs cancelling. Not a `StaleFailure`
|
|
47
|
+
* and never retried — the same write leaves the same block on every attempt. The structures that hold
|
|
48
|
+
* many entries per block split by size (the log rolls over, a tree node divides), so this names a block
|
|
49
|
+
* that outgrew the limit some other way; the change has to be written in a form that does not.
|
|
50
|
+
*/
|
|
51
|
+
export class BlockTooLargeError extends Error {
|
|
52
|
+
constructor(
|
|
53
|
+
readonly blockId: BlockId,
|
|
54
|
+
/** What the block's post-write content encodes to, by `jsonEncodedBytes`. */
|
|
55
|
+
readonly bytes: number,
|
|
56
|
+
/** The limit it exceeded: {@link MAX_BLOCK_BYTES}. */
|
|
57
|
+
readonly limit: number = MAX_BLOCK_BYTES,
|
|
58
|
+
) {
|
|
59
|
+
super(`block ${blockId} would encode to ${bytes} bytes once written, over the per-block limit MAX_BLOCK_BYTES (${limit} bytes); a block that large could never be copied to another machine`);
|
|
60
|
+
this.name = 'BlockTooLargeError';
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* The refusal for the first block in `bytes` — per block, what a write would leave its content encoding
|
|
66
|
+
* to — that is over {@link MAX_BLOCK_BYTES}, or `undefined` when every one fits. The one rule both write
|
|
67
|
+
* paths apply before anything is sent. It judges only the blocks it is given: a writer measures what it
|
|
68
|
+
* can materialize locally (`describeTouchedBlocks`), which leaves out a deleted block and an updated
|
|
69
|
+
* block whose base it cannot materialize.
|
|
70
|
+
*/
|
|
71
|
+
// NOTE: accepted tradeoff (no backwards compatibility yet, AGENTS.md) — a block a build without the split
|
|
72
|
+
// rules already grew past the limit refuses every write that leaves it over, including ones that do not
|
|
73
|
+
// grow it: a log tail's roll-over (which rewrites its `nextId`) wedges every later write to that
|
|
74
|
+
// collection, and a delete from an oversized leaf is refused. If a deployment must keep writing over such
|
|
75
|
+
// data, refuse only a block that grows past its base's size here, rather than every block over the limit.
|
|
76
|
+
export function oversizedBlock(bytes: Readonly<Record<BlockId, number>>): BlockTooLargeError | undefined {
|
|
77
|
+
for (const [blockId, size] of Object.entries(bytes)) {
|
|
78
|
+
if (size > MAX_BLOCK_BYTES) return new BlockTooLargeError(blockId, size);
|
|
79
|
+
}
|
|
80
|
+
return undefined;
|
|
81
|
+
}
|
package/src/network/i-repo.ts
CHANGED
|
@@ -57,6 +57,9 @@ export type RepoCommitRequest = {
|
|
|
57
57
|
// durable commit proof and so cannot gain holders by push. Full rationale and the measured cost of
|
|
58
58
|
// making it required live at {@link CommitRequest.blockDigests} in `struct.ts`; keep the two in sync.
|
|
59
59
|
blockDigests?: BlockContentDigests;
|
|
60
|
+
/** {@link CommitRequest.refuseSolo}: present on every per-coordinator commit of a write that asked
|
|
61
|
+
* not to be committed alone, and omitted otherwise. */
|
|
62
|
+
refuseSolo?: true;
|
|
60
63
|
};
|
|
61
64
|
|
|
62
65
|
export type IRepo = {
|
package/src/network/index.ts
CHANGED
|
@@ -1,11 +1,16 @@
|
|
|
1
1
|
export * from "./i-key-network.js";
|
|
2
2
|
export * from "./i-peer-network.js";
|
|
3
|
+
export * from "./block-size.js";
|
|
3
4
|
export * from "./durability.js";
|
|
4
5
|
export * from "./i-repo.js";
|
|
5
6
|
export * from "./lineage.js";
|
|
7
|
+
export * from "./promise-shortfall-error.js";
|
|
8
|
+
export * from "./refuse-solo.js";
|
|
6
9
|
export * from "./repo-protocol.js";
|
|
7
10
|
export * from "./routing-key.js";
|
|
8
11
|
export * from "./stale-failure.js";
|
|
9
12
|
export * from "./struct.js";
|
|
10
13
|
export * from "./transaction-expired-error.js";
|
|
14
|
+
export * from "./transaction-size.js";
|
|
11
15
|
export * from "./types.js";
|
|
16
|
+
export * from "./validity-rejected-error.js";
|