@optimystic/db-core 1.19.0 → 1.20.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/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 +533 -120
- package/dist/src/collection/collection.d.ts.map +1 -1
- package/dist/src/collection/collection.js +974 -500
- 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 +156 -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 +112 -26
- 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/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 +3 -0
- package/dist/src/network/index.d.ts.map +1 -1
- package/dist/src/network/index.js +3 -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 +148 -2
- package/dist/src/network/struct.d.ts.map +1 -1
- package/dist/src/network/struct.js.map +1 -1
- 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/testing/test-transactor.d.ts +29 -0
- package/dist/src/testing/test-transactor.d.ts.map +1 -1
- package/dist/src/testing/test-transactor.js +50 -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 +165 -41
- package/dist/src/transaction/coordinator.d.ts.map +1 -1
- package/dist/src/transaction/coordinator.js +605 -300
- 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/network-transactor.d.ts +1 -0
- package/dist/src/transactor/network-transactor.d.ts.map +1 -1
- package/dist/src/transactor/network-transactor.js +61 -28
- 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/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/cluster/structs.ts +42 -7
- package/src/collection/action.ts +34 -0
- package/src/collection/collection.ts +1048 -543
- 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 +183 -1
- package/src/collection/write-attempts.ts +506 -0
- package/src/collections/tree/struct.ts +97 -17
- package/src/collections/tree/tree.ts +125 -29
- package/src/index.ts +2 -0
- package/src/network/i-repo.ts +3 -0
- package/src/network/index.ts +3 -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 +154 -2
- 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/testing/test-transactor.ts +53 -0
- package/src/transaction/commit-failure-class.ts +133 -0
- package/src/transaction/coordinator.ts +696 -349
- 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/network-transactor.ts +62 -28
- package/src/transactor/transactor-source.ts +29 -13
- 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
|
|
@@ -4,28 +4,39 @@ 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
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";
|
|
7
9
|
import {
|
|
8
10
|
TreeHeaderBlockType, TreeDeleteGuardKindError, TreeEntryChangedError, TreeKeyTakenError,
|
|
9
|
-
TreeRangeTakenError, type TreeEntryGuard, type TreeReplaceAction,
|
|
11
|
+
TreeRangeTakenError, TreeUpsertGuardKindError, type TreeEntryGuard, type TreeReplaceAction,
|
|
10
12
|
} from "./struct.js";
|
|
11
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
|
+
|
|
12
20
|
/**
|
|
13
21
|
* Enforce a guard carried by an UPSERT element against the CURRENT content of `actionTree` —
|
|
14
22
|
* the same Atomic store the upsert writes to, so it sees what earlier elements of this same
|
|
15
23
|
* replay already staged or deleted (an UPDATE's delete-old half runs before its guarded insert
|
|
16
|
-
* 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.
|
|
17
26
|
*
|
|
18
27
|
* @returns `'skip'` when the element must be left unwritten (`keepExisting` found the key
|
|
19
|
-
* 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.
|
|
20
30
|
*/
|
|
21
31
|
async function enforceUpsertGuard<TKey, TEntry>(
|
|
22
32
|
actionTree: BTree<TKey, TEntry>,
|
|
23
33
|
id: CollectionId,
|
|
24
34
|
key: TKey,
|
|
35
|
+
entry: TEntry,
|
|
25
36
|
guard: TreeEntryGuard<TKey, TEntry>,
|
|
26
37
|
keyFromEntry: (entry: TEntry) => TKey,
|
|
27
38
|
compare: (a: TKey, b: TKey) => number,
|
|
28
|
-
): Promise<
|
|
39
|
+
): Promise<GuardVerdict> {
|
|
29
40
|
switch (guard.kind) {
|
|
30
41
|
case 'absentRange': {
|
|
31
42
|
// Secondary-UNIQUE: the claimed range (a unique index's framed value prefix) must hold
|
|
@@ -53,6 +64,86 @@ async function enforceUpsertGuard<TKey, TEntry>(
|
|
|
53
64
|
// keepExisting: leave the present (rival's) entry in place and skip this element.
|
|
54
65
|
return 'skip';
|
|
55
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 };
|
|
56
147
|
}
|
|
57
148
|
}
|
|
58
149
|
|
|
@@ -70,21 +161,6 @@ function assertEntryUnchanged<TKey, TEntry>(
|
|
|
70
161
|
}
|
|
71
162
|
}
|
|
72
163
|
|
|
73
|
-
/** Narrow a DELETE element's guard to the only kind a delete can act on. The element type already
|
|
74
|
-
* says this ({@link TreeDeleteElement}), but a replayed log entry is deserialized data that no
|
|
75
|
-
* type policed, so the handler re-checks it and throws {@link TreeDeleteGuardKindError} rather
|
|
76
|
-
* than silently ignoring a guard the writer believed was being enforced. */
|
|
77
|
-
function deleteGuardExpected<TKey, TEntry>(
|
|
78
|
-
id: CollectionId,
|
|
79
|
-
key: TKey,
|
|
80
|
-
guard: TreeEntryGuard<TKey, TEntry>,
|
|
81
|
-
): TEntry {
|
|
82
|
-
if (guard.kind !== 'unchanged') {
|
|
83
|
-
throw new TreeDeleteGuardKindError(id, key, guard.kind);
|
|
84
|
-
}
|
|
85
|
-
return guard.expected;
|
|
86
|
-
}
|
|
87
|
-
|
|
88
164
|
/**
|
|
89
165
|
* Read-only surface of a tree: every navigation/lookup method a reader needs, with
|
|
90
166
|
* none of the mutation (stage/sync) or network-refresh (update) entry points. Both
|
|
@@ -108,6 +184,11 @@ interface BTreeHolder<TKey, TEntry> {
|
|
|
108
184
|
btree?: BTree<TKey, TEntry>;
|
|
109
185
|
}
|
|
110
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
|
+
|
|
111
192
|
export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
|
|
112
193
|
|
|
113
194
|
private constructor(
|
|
@@ -130,9 +211,11 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
|
|
|
130
211
|
compare = (a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0,
|
|
131
212
|
/** See {@link Tree.createOrOpen}'s `nodeCapacity`. */
|
|
132
213
|
nodeCapacity?: number,
|
|
214
|
+
/** See {@link Tree.createOrOpen}'s `options`. */
|
|
215
|
+
options?: TreeCollectionOptions,
|
|
133
216
|
): Promise<Tree<TKey, TEntry> | undefined> {
|
|
134
217
|
const held: BTreeHolder<TKey, TEntry> = {};
|
|
135
|
-
const init = Tree.buildInit(id, keyFromEntry, compare, nodeCapacity, held);
|
|
218
|
+
const init = Tree.buildInit(id, keyFromEntry, compare, nodeCapacity, held, options);
|
|
136
219
|
const collection = await Collection.open<TreeReplaceAction<TKey, TEntry>>(network, id, init);
|
|
137
220
|
return collection ? Tree.attach(collection, held, keyFromEntry, compare, nodeCapacity) : undefined;
|
|
138
221
|
}
|
|
@@ -154,9 +237,12 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
|
|
|
154
237
|
* they pass it consistently); if a persisted tree ever needs a custom fan-out, persist it in
|
|
155
238
|
* the header and read it back on reopen rather than trusting the caller to re-supply it. */
|
|
156
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,
|
|
157
243
|
): Promise<Tree<TKey, TEntry>> {
|
|
158
244
|
const held: BTreeHolder<TKey, TEntry> = {};
|
|
159
|
-
const init = Tree.buildInit(id, keyFromEntry, compare, nodeCapacity, held);
|
|
245
|
+
const init = Tree.buildInit(id, keyFromEntry, compare, nodeCapacity, held, options);
|
|
160
246
|
const collection = await Collection.createOrOpen<TreeReplaceAction<TKey, TEntry>>(network, id, init);
|
|
161
247
|
return Tree.attach(collection, held, keyFromEntry, compare, nodeCapacity);
|
|
162
248
|
}
|
|
@@ -169,10 +255,12 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
|
|
|
169
255
|
compare: (a: TKey, b: TKey) => number,
|
|
170
256
|
nodeCapacity: number | undefined,
|
|
171
257
|
held: BTreeHolder<TKey, TEntry>,
|
|
258
|
+
options: TreeCollectionOptions | undefined,
|
|
172
259
|
): CollectionInitOptions<TreeReplaceAction<TKey, TEntry>> {
|
|
173
260
|
return {
|
|
261
|
+
...options,
|
|
174
262
|
modules: {
|
|
175
|
-
"replace": async ({ data: actions }, trx) => {
|
|
263
|
+
"replace": async ({ data: actions }, trx): Promise<AlreadyAppliedTally> => {
|
|
176
264
|
// Write through the Atomic store the handler is handed (`trx`), NOT the captured
|
|
177
265
|
// read btree, so `internalTransact`'s all-or-nothing wrapper actually governs this
|
|
178
266
|
// action: if any entry throws, `atomic.commit()` is skipped and every staged node
|
|
@@ -187,6 +275,7 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
|
|
|
187
275
|
nodeCapacity, // keep the write btree's fan-out in lock-step with the read btree
|
|
188
276
|
BLOCK_TARGET_BYTES, // and its node size rule: every node is a block that must stay copyable
|
|
189
277
|
);
|
|
278
|
+
const tally = new TallyBuilder();
|
|
190
279
|
for (const [key, entry, guard] of actions) {
|
|
191
280
|
// NOTE: an element is a DELETE when its entry slot is falsy, not when it is
|
|
192
281
|
// strictly `undefined`. That is deliberate and load-bearing: JSON encodes the
|
|
@@ -211,9 +300,10 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
|
|
|
211
300
|
// slot above: an explicitly-passed `undefined` guard (the shape every unguarded
|
|
212
301
|
// index write stages) comes back from JSON as `null`, and reading `.kind` off it
|
|
213
302
|
// would throw a TypeError mid-replay instead of meaning "no guard".
|
|
214
|
-
if (guard
|
|
215
|
-
|
|
216
|
-
|
|
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;
|
|
217
307
|
}
|
|
218
308
|
await actionTree.upsert(entry);
|
|
219
309
|
} else {
|
|
@@ -221,7 +311,9 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
|
|
|
221
311
|
// consumes it, with no mutation in between to invalidate it.
|
|
222
312
|
const path = await actionTree.find(key);
|
|
223
313
|
if (guard) {
|
|
224
|
-
|
|
314
|
+
const verdict = enforceDeleteGuard(id, key, guard, actionTree.at(path));
|
|
315
|
+
tally.count(guard, verdict);
|
|
316
|
+
if (verdict === 'already-applied') continue;
|
|
225
317
|
}
|
|
226
318
|
await actionTree.deleteAt(path);
|
|
227
319
|
}
|
|
@@ -230,6 +322,7 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
|
|
|
230
322
|
// Bump it to invalidate any Path a caller still holds — preserving the path-invalidation
|
|
231
323
|
// the previous in-place handler gave for free.
|
|
232
324
|
held.btree?.invalidatePaths();
|
|
325
|
+
return tally.result();
|
|
233
326
|
}
|
|
234
327
|
},
|
|
235
328
|
createHeaderBlock: (hid: BlockId, store: BlockStore<IBlock>) => { // Only called if the collection does not exist
|
|
@@ -311,9 +404,12 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
|
|
|
311
404
|
|
|
312
405
|
/** Restore the staged state captured by {@link snapshot}, discarding mutations
|
|
313
406
|
* staged since. Counterpart to {@link stage} for transaction rollback —
|
|
314
|
-
* preserves a never-synced collection's header/root rather than wiping it.
|
|
315
|
-
|
|
316
|
-
|
|
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);
|
|
317
413
|
}
|
|
318
414
|
|
|
319
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/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
|
@@ -4,6 +4,8 @@ export * from "./block-size.js";
|
|
|
4
4
|
export * from "./durability.js";
|
|
5
5
|
export * from "./i-repo.js";
|
|
6
6
|
export * from "./lineage.js";
|
|
7
|
+
export * from "./promise-shortfall-error.js";
|
|
8
|
+
export * from "./refuse-solo.js";
|
|
7
9
|
export * from "./repo-protocol.js";
|
|
8
10
|
export * from "./routing-key.js";
|
|
9
11
|
export * from "./stale-failure.js";
|
|
@@ -11,3 +13,4 @@ export * from "./struct.js";
|
|
|
11
13
|
export * from "./transaction-expired-error.js";
|
|
12
14
|
export * from "./transaction-size.js";
|
|
13
15
|
export * from "./types.js";
|
|
16
|
+
export * from "./validity-rejected-error.js";
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import type { PromiseShortfall, ShortfallFailure, SoloRefusalReason } from "./struct.js";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* A pend the cohort could not accept because too few of its members answered the promise round: the
|
|
5
|
+
* approvals fell short of the bar with no member refusing the write as a lost race or a held block,
|
|
6
|
+
* and too few rejecting it for a rejection. Nobody judged the write; the cohort was not all there.
|
|
7
|
+
* Not retryable by a write path — every coordinator of the cohort meets the same silent members, so a
|
|
8
|
+
* re-read and re-pend fails the same way until they answer again. Nothing was saved: the members that
|
|
9
|
+
* approved release their reservation when the writer cancels.
|
|
10
|
+
*
|
|
11
|
+
* ONE class for every place it is raised, as `TransactionExpiredError` is. The cluster coordinator
|
|
12
|
+
* (db-p2p `ClusterCoordinator`) raises it; the coordinating repo returns its facts as a
|
|
13
|
+
* {@link ShortfallFailure} ({@link toFailure}), which is what lets a remote writer receive them at
|
|
14
|
+
* all; and each write path (`Collection.sync`, `TransactionCoordinator.commit`) raises it again from
|
|
15
|
+
* that refusal.
|
|
16
|
+
*
|
|
17
|
+
* The message is the sentence the coordinator has always thrown, byte for byte: a downstream
|
|
18
|
+
* repository matches it to retry a silent cohort (backlog
|
|
19
|
+
* `debt-a-downstream-repo-classifies-retries-by-parsing-our-error-text`). Test for this class, or for
|
|
20
|
+
* the refusal with `isShortfallFailure`, rather than for the text.
|
|
21
|
+
*/
|
|
22
|
+
export class PromiseShortfallError extends Error {
|
|
23
|
+
/** Approve votes the round received. */
|
|
24
|
+
readonly approvals: number;
|
|
25
|
+
/** Reject votes the round received — fewer than would make the round a rejection. */
|
|
26
|
+
readonly rejections: number;
|
|
27
|
+
/** How many members the cohort the round ran on has. */
|
|
28
|
+
readonly peerCount: number;
|
|
29
|
+
/** The approvals the round needed. */
|
|
30
|
+
readonly needed: number;
|
|
31
|
+
/** Peer-id strings of the cohort members that cast no promise vote at all. */
|
|
32
|
+
readonly silentPeers: readonly string[];
|
|
33
|
+
/** Why a lone coordinator refused to write alone, when that is what this shortfall is
|
|
34
|
+
* ({@link PromiseShortfall.soloRefused}); absent when a consensus round fell short. */
|
|
35
|
+
readonly soloRefused?: SoloRefusalReason;
|
|
36
|
+
|
|
37
|
+
constructor(shortfall: PromiseShortfall) {
|
|
38
|
+
// NOTE: `shortfall` off the wire is trusted as shaped (`isShortfallFailure` checks only presence),
|
|
39
|
+
// so a malformed coordinator answer throws a TypeError here (no `silentPeers` array) instead of
|
|
40
|
+
// this error. Either still ends the write; if hostile coordinators become a concern, validate the
|
|
41
|
+
// shape where the refusal is received, as for `TransactionExpiredError`.
|
|
42
|
+
super(`Failed to get super-majority: ${shortfall.approvals}/${shortfall.peerCount} approvals (needed ${shortfall.needed}, ${shortfall.rejections} rejections)`);
|
|
43
|
+
this.name = 'PromiseShortfallError';
|
|
44
|
+
this.approvals = shortfall.approvals;
|
|
45
|
+
this.rejections = shortfall.rejections;
|
|
46
|
+
this.peerCount = shortfall.peerCount;
|
|
47
|
+
this.needed = shortfall.needed;
|
|
48
|
+
this.silentPeers = [...shortfall.silentPeers];
|
|
49
|
+
if (shortfall.soloRefused !== undefined) this.soloRefused = shortfall.soloRefused;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** The refusal a coordinating repo returns for this error, so it crosses the repo protocol as an
|
|
53
|
+
* answer rather than as a reset stream. */
|
|
54
|
+
toFailure(): ShortfallFailure {
|
|
55
|
+
return {
|
|
56
|
+
success: false,
|
|
57
|
+
conflict: false,
|
|
58
|
+
reason: this.message,
|
|
59
|
+
shortfall: {
|
|
60
|
+
approvals: this.approvals,
|
|
61
|
+
rejections: this.rejections,
|
|
62
|
+
peerCount: this.peerCount,
|
|
63
|
+
needed: this.needed,
|
|
64
|
+
silentPeers: [...this.silentPeers],
|
|
65
|
+
...(this.soloRefused === undefined ? {} : { soloRefused: this.soloRefused }),
|
|
66
|
+
},
|
|
67
|
+
};
|
|
68
|
+
}
|
|
69
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/** Wraps `PendRequest.refuseSolo` and `CommitRequest.refuseSolo` so the field spreads onto a request
|
|
2
|
+
* only when the write refuses to be committed alone. A write that does not is omitted rather than
|
|
3
|
+
* sent as `false`: the request is hashed verbatim into every cohort signature preimage, so it must
|
|
4
|
+
* serialize exactly as it did before the field existed. Every producer of the field goes through here. */
|
|
5
|
+
export function refuseSoloField(refuse: boolean | undefined): { refuseSolo?: true } {
|
|
6
|
+
return refuse === true ? { refuseSolo: true } : {};
|
|
7
|
+
}
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { ActionId, ActionRev } from "../collection/action.js";
|
|
2
|
-
import type { ExpiredFailure, StaleFailure, WriteFailure } from "./struct.js";
|
|
2
|
+
import type { ExpiredFailure, RejectedFailure, ShortfallFailure, StaleFailure, WriteFailure } from "./struct.js";
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
5
|
* The single rule for "is this non-success retryable after a re-read?" Both write paths and the
|
|
@@ -7,11 +7,12 @@ import type { ExpiredFailure, StaleFailure, WriteFailure } from "./struct.js";
|
|
|
7
7
|
*
|
|
8
8
|
* {@link StaleFailure.conflict} is authoritative when present. The `missing`/`pending` fallback
|
|
9
9
|
* covers producers that have not been taught the field, including a remote peer on an older build
|
|
10
|
-
* (the repo protocol is plain JSON, so an unset field simply arrives absent). An expiry
|
|
11
|
-
*
|
|
10
|
+
* (the repo protocol is plain JSON, so an unset field simply arrives absent). An expiry
|
|
11
|
+
* ({@link isExpiryFailure}), a promise shortfall ({@link isShortfallFailure}) and a validity
|
|
12
|
+
* rejection ({@link isRejectedFailure}) are never a conflict, whatever else arrived beside them.
|
|
12
13
|
*/
|
|
13
14
|
export function isConflictFailure(failure: WriteFailure): boolean {
|
|
14
|
-
if (isExpiryFailure(failure)) return false;
|
|
15
|
+
if (isExpiryFailure(failure) || isShortfallFailure(failure) || isRejectedFailure(failure)) return false;
|
|
15
16
|
return failure.conflict ?? Boolean(failure.missing?.length || failure.pending?.length);
|
|
16
17
|
}
|
|
17
18
|
|
|
@@ -26,6 +27,28 @@ export function isExpiryFailure(failure: WriteFailure): failure is ExpiredFailur
|
|
|
26
27
|
return failure.expired !== undefined;
|
|
27
28
|
}
|
|
28
29
|
|
|
30
|
+
/**
|
|
31
|
+
* The single rule for "did the cohort refuse this pend because too few of its members answered the
|
|
32
|
+
* promise round?" ({@link ShortfallFailure}). Every write path stops on it rather than retrying, since
|
|
33
|
+
* every coordinator of the cohort meets the same silent members. Decided by the structured field,
|
|
34
|
+
* never the reason text; a coordinator on a build that predates the field throws the shortfall
|
|
35
|
+
* instead of returning it, which a writer sees as it always did.
|
|
36
|
+
*/
|
|
37
|
+
export function isShortfallFailure(failure: WriteFailure): failure is ShortfallFailure {
|
|
38
|
+
return failure.shortfall !== undefined;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* The single rule for "did the cohort refuse this pend because the members that sank it judged the
|
|
43
|
+
* transaction invalid?" ({@link RejectedFailure}). Every write path stops on it rather than retrying,
|
|
44
|
+
* since re-sending the same content to the same checks is refused the same way. Decided by the
|
|
45
|
+
* structured field, never the reason text; a coordinator on a build that predates the field throws the
|
|
46
|
+
* rejection instead of returning it, which a writer sees as it always did.
|
|
47
|
+
*/
|
|
48
|
+
export function isRejectedFailure(failure: WriteFailure): failure is RejectedFailure {
|
|
49
|
+
return failure.rejected !== undefined;
|
|
50
|
+
}
|
|
51
|
+
|
|
29
52
|
/**
|
|
30
53
|
* The single rule for picking one {@link StaleFailure.staleAt} out of several candidates.
|
|
31
54
|
*
|