@optimystic/db-core 1.19.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/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
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import type { BlockId } from '../blocks/structs.js';
|
|
2
|
+
import type { Collection } from '../collection/collection.js';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Whether the cohorts responsible for these blocks can be reached now — the gate of
|
|
6
|
+
* docs/offline-sync.md §When to submit. db-p2p implements it over the key network (stage 6);
|
|
7
|
+
* absent, the queue treats the cohort as always reachable ({@link alwaysReachable}), which is right
|
|
8
|
+
* for `TestTransactor`, the local transactor and the in-process mesh. Asked with each collection's
|
|
9
|
+
* header id and its last known log tail id, so an implementation resolves cohorts from routing keys
|
|
10
|
+
* alone and never needs the network to answer whether the network can be reached.
|
|
11
|
+
*/
|
|
12
|
+
export interface ICohortReachability {
|
|
13
|
+
reachable(blockIds: readonly BlockId[]): Promise<boolean>;
|
|
14
|
+
/** Optionally call `listener` when reachability may have improved — a machine connected or was
|
|
15
|
+
* identified. A hint, not an answer: the listener asks `reachable` again. Returns an idempotent
|
|
16
|
+
* unsubscribe. Absent → nothing wakes the asker but its own timer. */
|
|
17
|
+
onChange?(listener: () => void): () => void;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/** The gate that is always open: what a queue over a transactor with no cohort to lose uses. */
|
|
21
|
+
export const alwaysReachable: ICohortReachability = {
|
|
22
|
+
reachable: () => Promise.resolve(true),
|
|
23
|
+
};
|
|
24
|
+
|
|
25
|
+
/** What a gate is asked with for one collection: its header id and its last known log tail id
|
|
26
|
+
* (`Collection.knownLogTailId`), when it knows one. The offline queue asks with these for every
|
|
27
|
+
* collection the head entry still has to commit, and the Quereus plugin's live-read degrade for the
|
|
28
|
+
* tree it is about to refresh, so the two ask one gate the same question. */
|
|
29
|
+
export function gateBlockIds(collection: Collection<any>): BlockId[] {
|
|
30
|
+
const tailId = collection.knownLogTailId();
|
|
31
|
+
return tailId === undefined ? [collection.id] : [collection.id, tailId];
|
|
32
|
+
}
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
import type { CollectionId } from '../collection/struct.js';
|
|
2
|
+
import type { EntryId } from '../collection/segments.js';
|
|
3
|
+
import type { TransactionDurability } from '../transaction/durability.js';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* The status an offline-sync queue reports for each entry (docs/offline-sync.md §Following
|
|
7
|
+
* transactions), in its db-core form: collections stand in for tables. The plugin's `followed`,
|
|
8
|
+
* `persisted` and `outlook` are its own and never appear here — the outlook needs the catalog's tags
|
|
9
|
+
* and key decoding, which only the plugin has.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
/** Why an entry failed. `constraint` and `concurrent-modification` are the two guard refusals
|
|
13
|
+
* (`refusalReason` in `packages/db-core/src/transaction/commit-failure-class.ts`); the other four
|
|
14
|
+
* are the queue's own: a validator judged the write invalid, it can never fit a message, it outlived
|
|
15
|
+
* `OfflineQueueOptions.expireAfterMs`, or the application withdrew it with `OfflineQueue.discard`. */
|
|
16
|
+
export type QueuedFailureReason = 'constraint' | 'concurrent-modification' | 'rejected' | 'too-large' | 'expired' | 'discarded';
|
|
17
|
+
|
|
18
|
+
/** What an entry still queued is waiting on: an earlier entry (the drain is strictly first in,
|
|
19
|
+
* first out), the cohort (the reachability gate said no, or the last attempt could not reach it),
|
|
20
|
+
* or the backoff timer after a transient failure. `undefined` for a head about to be submitted. */
|
|
21
|
+
export type EntryWaitingFor = 'earlier-entry' | 'cohort' | 'backoff';
|
|
22
|
+
|
|
23
|
+
/** What a committed entry did to the rows it wrote (docs/offline-sync.md §Guards that make idempotent
|
|
24
|
+
* writes assured): `already-applied` when every element that carried one of the already-applied guard
|
|
25
|
+
* kinds (`TreeAlreadyAppliedGuard` in `packages/db-core/src/collections/tree/struct.ts`) was skipped
|
|
26
|
+
* because a rival had already made exactly its change, and at least one did — summed over every
|
|
27
|
+
* collection the entry wrote (`AlreadyAppliedTally`); `applied` otherwise, including for an entry with
|
|
28
|
+
* no such element and for one of which any collection's tally was never heard — one a restore found
|
|
29
|
+
* already committed, or one committed before a restart lost the tally. "All, not any": an entry of two
|
|
30
|
+
* guarded updates of which one was already done did change a row, and a host reading
|
|
31
|
+
* `already-applied` as "none of my guarded changes landed" must be right — and a write under `absent`
|
|
32
|
+
* or `unchanged`, the main-table base kinds, counts as applied for the same reason. Says nothing about
|
|
33
|
+
* elements carrying no guard, `keepExisting` or `absentRange`, which are never counted. */
|
|
34
|
+
export type CommittedEffect = 'applied' | 'already-applied';
|
|
35
|
+
|
|
36
|
+
export type EntryStatus =
|
|
37
|
+
| {
|
|
38
|
+
kind: 'queued';
|
|
39
|
+
entryId: EntryId;
|
|
40
|
+
/** Per queue, monotonic: the order entries were queued in, which is the order they drain in. */
|
|
41
|
+
seq: number;
|
|
42
|
+
/** The collections the entry sealed a segment in — every collection it changed. */
|
|
43
|
+
collections: readonly CollectionId[];
|
|
44
|
+
queuedAt: number;
|
|
45
|
+
/** Submissions made so far. */
|
|
46
|
+
attempts: number;
|
|
47
|
+
/** Whether an attempt may have landed (see `OfflineQueue`'s in-doubt rule): such an entry can
|
|
48
|
+
* neither be discarded nor expired, and is re-sent only under its own action id. */
|
|
49
|
+
inDoubt: boolean;
|
|
50
|
+
waitingFor: EntryWaitingFor | undefined;
|
|
51
|
+
/** What the last attempt failed with, when one has. */
|
|
52
|
+
lastError?: unknown;
|
|
53
|
+
/** The collections of the entry already durably committed, once a submission has committed
|
|
54
|
+
* part of it (docs/offline-sync.md §Partial commits); absent while none is. */
|
|
55
|
+
committedCollections?: readonly CollectionId[];
|
|
56
|
+
}
|
|
57
|
+
| { kind: 'submitting'; entryId: EntryId; attempt: number }
|
|
58
|
+
| {
|
|
59
|
+
kind: 'committed';
|
|
60
|
+
entryId: EntryId;
|
|
61
|
+
/** Every collection the entry wrote, each with its class — across submissions, so a partly
|
|
62
|
+
* committed entry's earlier half is listed beside the remainder's. */
|
|
63
|
+
durability: TransactionDurability;
|
|
64
|
+
/** Whether the entry's guarded changes were already in place when it committed
|
|
65
|
+
* ({@link CommittedEffect}). */
|
|
66
|
+
effect: CommittedEffect;
|
|
67
|
+
}
|
|
68
|
+
| {
|
|
69
|
+
/** A submission committed part of the entry and not the rest (`CoordinatorPartialCommitError`).
|
|
70
|
+
* Emitted in place of the `queued` status that transition would otherwise report: the entry
|
|
71
|
+
* stays at the head, in doubt, and the drain drives the pending collections on the next
|
|
72
|
+
* submission. Between submissions `status` and `entries` report it `queued`, with
|
|
73
|
+
* `committedCollections` set. */
|
|
74
|
+
kind: 'partially-committed';
|
|
75
|
+
entryId: EntryId;
|
|
76
|
+
/** Every collection of the entry durably committed so far, across submissions. */
|
|
77
|
+
committedCollections: readonly CollectionId[];
|
|
78
|
+
/** The collections in which the entry is still a sealed segment: what the next submission drives. */
|
|
79
|
+
pendingCollections: readonly CollectionId[];
|
|
80
|
+
/** Why the rest did not commit: the partial commit's `reason` when that is an `Error`, otherwise
|
|
81
|
+
* the partial commit error itself (whose message names the reason). */
|
|
82
|
+
cause: Error;
|
|
83
|
+
}
|
|
84
|
+
| {
|
|
85
|
+
kind: 'failed';
|
|
86
|
+
entryId: EntryId;
|
|
87
|
+
reason: QueuedFailureReason;
|
|
88
|
+
error: Error;
|
|
89
|
+
/** The earlier entry whose removal made this one fail (docs/offline-sync.md §Removing an entry). */
|
|
90
|
+
causedBy?: EntryId;
|
|
91
|
+
/** The collections whose visible content this removal changed — the ones the entry still had a
|
|
92
|
+
* segment in when it was removed. */
|
|
93
|
+
changedCollections: readonly CollectionId[];
|
|
94
|
+
/** Set only when part of the entry had committed before the rest failed: the network now holds
|
|
95
|
+
* half of the transaction, which the application has to reconcile (docs/offline-sync.md
|
|
96
|
+
* §Partial commits). */
|
|
97
|
+
committedCollections?: readonly CollectionId[];
|
|
98
|
+
};
|
|
99
|
+
|
|
100
|
+
/** Queue-wide state, for a status bar. */
|
|
101
|
+
export type OfflineQueueState = {
|
|
102
|
+
depth: number;
|
|
103
|
+
oldestQueuedAt: number | undefined;
|
|
104
|
+
/** A submission is on the network. */
|
|
105
|
+
draining: boolean;
|
|
106
|
+
/** What the head is waiting on, when it is not an earlier entry. */
|
|
107
|
+
waitingFor: 'cohort' | 'backoff' | undefined;
|
|
108
|
+
/** Attempts whose failure the drain could not classify (`offline:unclassified-failure`); such an
|
|
109
|
+
* entry is retried rather than dropped, so a rising count with a stuck depth is the signal. */
|
|
110
|
+
unclassifiedFailures: number;
|
|
111
|
+
};
|
|
112
|
+
|
|
113
|
+
/** One entry as `OfflineQueue.entries` lists it: its identity and its current status. */
|
|
114
|
+
export type QueuedEntry = {
|
|
115
|
+
readonly id: EntryId;
|
|
116
|
+
readonly seq: number;
|
|
117
|
+
readonly queuedAt: number;
|
|
118
|
+
readonly collections: readonly CollectionId[];
|
|
119
|
+
/** As on the `queued` status: the collections already committed, once part of the entry is. */
|
|
120
|
+
readonly committedCollections?: readonly CollectionId[];
|
|
121
|
+
readonly status: EntryStatus;
|
|
122
|
+
};
|
|
123
|
+
|
|
124
|
+
/** Thrown by `OfflineQueue.discard` for an entry that cannot be withdrawn: it has been sent at least
|
|
125
|
+
* once and so may already be saved (`inDoubt`), or it is being submitted right now — and by the
|
|
126
|
+
* plugin's restore after a restart for a journaled entry a pass is putting back right now
|
|
127
|
+
* (`restoring`): withdrawn then, its outcome would be written while the queue goes on to admit and
|
|
128
|
+
* drive it. */
|
|
129
|
+
export class EntryNotDiscardableError extends Error {
|
|
130
|
+
constructor(
|
|
131
|
+
readonly entryId: EntryId,
|
|
132
|
+
readonly because: 'in-doubt' | 'submitting' | 'restoring',
|
|
133
|
+
) {
|
|
134
|
+
super(notDiscardableMessage(entryId, because));
|
|
135
|
+
this.name = 'EntryNotDiscardableError';
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
function notDiscardableMessage(entryId: EntryId, because: EntryNotDiscardableError['because']): string {
|
|
140
|
+
switch (because) {
|
|
141
|
+
case 'in-doubt': return `entry ${entryId} has been sent at least once and may already be saved; it cannot be discarded`;
|
|
142
|
+
case 'submitting': return `entry ${entryId} is being submitted; it cannot be discarded`;
|
|
143
|
+
case 'restoring': return `entry ${entryId} is being put back from its journal record; it cannot be discarded until the pass has put it back`;
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/** Thrown by `OfflineQueue.discard` for an id the queue does not hold — never queued, or already
|
|
148
|
+
* committed or failed. */
|
|
149
|
+
export class UnknownEntryError extends Error {
|
|
150
|
+
constructor(readonly entryId: EntryId) {
|
|
151
|
+
super(`entry ${entryId} is not queued`);
|
|
152
|
+
this.name = 'UnknownEntryError';
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/** Thrown by `OfflineQueue.enqueue` after `dispose`, and the rejection of every `whenDrained` the
|
|
157
|
+
* disposal cut short. */
|
|
158
|
+
export class QueueDisposedError extends Error {
|
|
159
|
+
constructor() {
|
|
160
|
+
super('the offline queue has been disposed');
|
|
161
|
+
this.name = 'QueueDisposedError';
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/** The error a discarded entry fails with (`reason: 'discarded'`): the application withdrew it. */
|
|
166
|
+
export class EntryDiscardedError extends Error {
|
|
167
|
+
constructor(readonly entryId: EntryId) {
|
|
168
|
+
super(`entry ${entryId} was discarded before it was sent`);
|
|
169
|
+
this.name = 'EntryDiscardedError';
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/** The error an expired entry fails with (`reason: 'expired'`). */
|
|
174
|
+
export class EntryExpiredError extends Error {
|
|
175
|
+
constructor(
|
|
176
|
+
readonly entryId: EntryId,
|
|
177
|
+
readonly queuedAt: number,
|
|
178
|
+
readonly expiresAt: number,
|
|
179
|
+
) {
|
|
180
|
+
super(`entry ${entryId} queued at ${queuedAt} was not settled by ${expiresAt}`);
|
|
181
|
+
this.name = 'EntryExpiredError';
|
|
182
|
+
}
|
|
183
|
+
}
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import { jitteredBackoffMs } from '../utility/backoff.js';
|
|
2
|
+
import type { JitteredBackoffConfig, RandFn } from '../utility/backoff.js';
|
|
3
|
+
import { armUnrefTimer } from '../utility/unref-timer.js';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Where the drain loop parks, and what wakes it: a wake signal — a new local commit, a connection
|
|
7
|
+
* event, a disposal — and ONE re-check timer, shared by the reachability gate and the transient
|
|
8
|
+
* failures, whose delay climbs a jittered exponential step (`jitteredBackoffMs`) that a wake or a
|
|
9
|
+
* committed entry resets. A wake that finds nothing parked is kept and consumed by the next park, so
|
|
10
|
+
* a connection event that arrives during a submission is not lost (the cost: a transient failure
|
|
11
|
+
* right after such a wake is re-driven at once rather than after the backoff). The timer is unref'd,
|
|
12
|
+
* so an idle queue holds no process open, and the wake that pre-empts it cancels it.
|
|
13
|
+
*/
|
|
14
|
+
export class DrainWaker {
|
|
15
|
+
private step = 0;
|
|
16
|
+
private waiter: (() => void) | undefined;
|
|
17
|
+
private pending = false;
|
|
18
|
+
|
|
19
|
+
constructor(private readonly config: JitteredBackoffConfig, private readonly rand: RandFn | undefined) {}
|
|
20
|
+
|
|
21
|
+
/** Wake whatever is parked, or keep the wake for the next park; either way the re-check step
|
|
22
|
+
* starts over. */
|
|
23
|
+
wake(): void {
|
|
24
|
+
this.step = 0;
|
|
25
|
+
const waiter = this.waiter;
|
|
26
|
+
if (waiter === undefined) {
|
|
27
|
+
this.pending = true;
|
|
28
|
+
return;
|
|
29
|
+
}
|
|
30
|
+
this.waiter = undefined;
|
|
31
|
+
waiter();
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** A committed entry: the cohort answered, so the next wait starts the climb over. */
|
|
35
|
+
resetBackoff(): void {
|
|
36
|
+
this.step = 0;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** Park until {@link wake}; a wake that arrived meanwhile returns at once. */
|
|
40
|
+
untilWoken(): Promise<void> {
|
|
41
|
+
if (this.takePending()) return Promise.resolve();
|
|
42
|
+
return new Promise<void>(resolve => { this.waiter = resolve; });
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** Park until the re-check timer at the current step fires or {@link wake} is called, whichever
|
|
46
|
+
* is first. */
|
|
47
|
+
untilWokenOrTimer(): Promise<void> {
|
|
48
|
+
if (this.takePending()) return Promise.resolve();
|
|
49
|
+
const delayMs = jitteredBackoffMs(this.step++, this.config, this.rand);
|
|
50
|
+
return new Promise<void>(resolve => {
|
|
51
|
+
const cancelTimer = armUnrefTimer(() => {
|
|
52
|
+
this.waiter = undefined;
|
|
53
|
+
resolve();
|
|
54
|
+
}, delayMs);
|
|
55
|
+
this.waiter = () => {
|
|
56
|
+
cancelTimer();
|
|
57
|
+
resolve();
|
|
58
|
+
};
|
|
59
|
+
});
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
private takePending(): boolean {
|
|
63
|
+
if (!this.pending) return false;
|
|
64
|
+
this.pending = false;
|
|
65
|
+
return true;
|
|
66
|
+
}
|
|
67
|
+
}
|
|
@@ -668,6 +668,36 @@ export class TailLandsButReportsStale extends DelegatingTransactor {
|
|
|
668
668
|
}
|
|
669
669
|
}
|
|
670
670
|
|
|
671
|
+
/**
|
|
672
|
+
* Answers every pend with a promise shortfall — the cohort's silence, in the shape
|
|
673
|
+
* `CoordinatorRepo.pend` returns it — and delegates nothing, so nothing is reserved and nothing
|
|
674
|
+
* lands. For the write paths' "stopped by name" cases: a shortfall is not a conflict a retry can
|
|
675
|
+
* win, so one attempt is made and `PromiseShortfallError` escapes with every staged action still
|
|
676
|
+
* staged.
|
|
677
|
+
*/
|
|
678
|
+
export class RefusesPendsAsShortfall extends DelegatingTransactor {
|
|
679
|
+
/** Pends refused so far. */
|
|
680
|
+
pends = 0;
|
|
681
|
+
/** While `true` every pend is refused; set `false` to let pends through again — the cohort back
|
|
682
|
+
* in reach, for a test of what waits on it. */
|
|
683
|
+
refusing = true;
|
|
684
|
+
|
|
685
|
+
constructor(inner: TestTransactor) {
|
|
686
|
+
super(inner);
|
|
687
|
+
}
|
|
688
|
+
|
|
689
|
+
override async pend(request: PendRequest): Promise<PendResult> {
|
|
690
|
+
if (!this.refusing) return this.inner.pend(request);
|
|
691
|
+
this.pends++;
|
|
692
|
+
return {
|
|
693
|
+
success: false,
|
|
694
|
+
conflict: false,
|
|
695
|
+
reason: 'Failed to get super-majority: injected shortfall',
|
|
696
|
+
shortfall: { approvals: 1, rejections: 0, peerCount: 3, needed: 3, silentPeers: ['peer-b', 'peer-c'] },
|
|
697
|
+
};
|
|
698
|
+
}
|
|
699
|
+
}
|
|
700
|
+
|
|
671
701
|
/** What one attempt of a write put on the wire: the pend's transforms, with the action id and
|
|
672
702
|
* revision it was pended under. Recorded by {@link RecordsAttemptsRefusesFirstCommit}. */
|
|
673
703
|
export type RecordedAttempt = {
|
|
@@ -869,6 +899,29 @@ export class GatedCommitTransactor extends DelegatingTransactor {
|
|
|
869
899
|
openGate(): void { this.gate.resolve(); }
|
|
870
900
|
}
|
|
871
901
|
|
|
902
|
+
/**
|
|
903
|
+
* Throws, nothing delegated, on every commit of the collection whose log tail is `tailId` while
|
|
904
|
+
* `armed` — the hard failure of one participant's commit after its siblings' landed, which a
|
|
905
|
+
* multi-collection commit reports as `CoordinatorPartialCommitError`. Disarmed, everything delegates.
|
|
906
|
+
*/
|
|
907
|
+
export class ThrowsOnCommitOf extends DelegatingTransactor {
|
|
908
|
+
/** Commits thrown so far. */
|
|
909
|
+
thrown = 0;
|
|
910
|
+
armed = true;
|
|
911
|
+
|
|
912
|
+
constructor(inner: TestTransactor, private readonly tailId: BlockId) {
|
|
913
|
+
super(inner);
|
|
914
|
+
}
|
|
915
|
+
|
|
916
|
+
override async commit(request: CommitRequest): Promise<CommitResult> {
|
|
917
|
+
if (this.armed && request.tailId === this.tailId) {
|
|
918
|
+
this.thrown++;
|
|
919
|
+
throw new Error('connection dropped before the commit was sent');
|
|
920
|
+
}
|
|
921
|
+
return this.inner.commit(request);
|
|
922
|
+
}
|
|
923
|
+
}
|
|
924
|
+
|
|
872
925
|
/**
|
|
873
926
|
* Parks the FIRST pend BEFORE it reaches the inner transactor, so a rival can durably take the
|
|
874
927
|
* revision while the coordinator is already committed to a set of transforms it captured at the
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
import { BlockUnavailableError, type BlockUnavailableReason } from "../network/struct.js";
|
|
2
|
+
import { PromiseShortfallError } from "../network/promise-shortfall-error.js";
|
|
3
|
+
import { ValidityRejectedError } from "../network/validity-rejected-error.js";
|
|
4
|
+
import { TransactionExpiredError } from "../network/transaction-expired-error.js";
|
|
5
|
+
import { TransactionTooLargeError } from "../network/transaction-size.js";
|
|
6
|
+
import { BlockTooLargeError } from "../network/block-size.js";
|
|
7
|
+
import { SyncRetryExhaustedError, TornActionError } from "../collection/struct.js";
|
|
8
|
+
import type { ActionRefusedError } from "../collection/struct.js";
|
|
9
|
+
import { TreeEntryChangedError, TreeGuardRefusedError } from "../collections/tree/struct.js";
|
|
10
|
+
import { CoordinatorPartialCommitError, CoordinatorStaleLossError } from "./errors.js";
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* What a failed commit attempt says about the write, sorted for a caller that has to decide whether
|
|
14
|
+
* to wait and send it again, give it up, or treat it as possibly saved (docs/offline-sync.md
|
|
15
|
+
* §Classifying an attempt's outcome). Each arm carries the error it was sorted from, narrowed to the
|
|
16
|
+
* classes that produce it.
|
|
17
|
+
*
|
|
18
|
+
* - `cohort-unreachable` — too few of the cohort answered, so the attempt that met it stored nothing.
|
|
19
|
+
* Wait for the cohort.
|
|
20
|
+
* - `contention` — the write lost races until its retry budget ran out and was not saved, though an
|
|
21
|
+
* earlier attempt's log entry may still stand (see {@link SyncRetryExhaustedError}). Back off.
|
|
22
|
+
* - `guard-refused` — a rival's commit made the write wrong: `constraint` for a uniqueness refusal,
|
|
23
|
+
* `concurrent-modification` for a lost update. Final.
|
|
24
|
+
* - `rejected` — the members that sank the write judged it invalid. Final.
|
|
25
|
+
* - `too-large` — the transaction, or a block it writes, is over the size limit. Final: it can never
|
|
26
|
+
* commit as it is.
|
|
27
|
+
* - `expired` — the attempt outlived its expiry; a new attempt gets a fresh one.
|
|
28
|
+
* - `torn-not-saved` — the write half-landed and is provably not saved; sending it again stores it once.
|
|
29
|
+
* - `in-doubt` — the write half-landed and may be saved or may still land.
|
|
30
|
+
* - `partial` — some collections of a multi-collection commit are saved and the rest are not.
|
|
31
|
+
* - `unknown` — anything else. Treat as in doubt: retry only under the attempt's own identity.
|
|
32
|
+
*/
|
|
33
|
+
export type CommitFailureClass =
|
|
34
|
+
| { kind: 'cohort-unreachable'; error: PromiseShortfallError | BlockUnavailableError }
|
|
35
|
+
| { kind: 'contention'; error: SyncRetryExhaustedError | CoordinatorStaleLossError }
|
|
36
|
+
| { kind: 'guard-refused'; refusal: 'constraint' | 'concurrent-modification'; error: TreeGuardRefusedError }
|
|
37
|
+
| { kind: 'rejected'; error: ValidityRejectedError }
|
|
38
|
+
| { kind: 'too-large'; error: TransactionTooLargeError | BlockTooLargeError }
|
|
39
|
+
| { kind: 'expired'; error: TransactionExpiredError }
|
|
40
|
+
| { kind: 'torn-not-saved'; error: TornActionError }
|
|
41
|
+
| { kind: 'in-doubt'; error: TornActionError }
|
|
42
|
+
| { kind: 'partial'; error: CoordinatorPartialCommitError }
|
|
43
|
+
| { kind: 'unknown'; error: unknown };
|
|
44
|
+
|
|
45
|
+
/** The two unavailability reasons that mean the cohort could not be reached. The others are doubts
|
|
46
|
+
* about one block's read (a reconstruction gap, a claim nobody corroborated, a log naming a block
|
|
47
|
+
* nobody serves) and say nothing about whether a write could be sent. */
|
|
48
|
+
const cohortUnreachableReasons: ReadonlySet<BlockUnavailableReason> = new Set(['cohort-unreachable', 'peers-unreachable']);
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Whether `error` is a read that failed because the cohort could not be reached: a
|
|
52
|
+
* {@link BlockUnavailableError} with one of the two unreachability reasons — exactly the errors
|
|
53
|
+
* {@link classifyCommitFailure} sorts as `cohort-unreachable` from that class. Every other
|
|
54
|
+
* unavailability reason is a doubt about one block that reaching the cohort would not settle. Shared
|
|
55
|
+
* with the Quereus plugin's live-read degrade (docs/offline-sync.md §Reads in offline mode), so a read
|
|
56
|
+
* served from this machine's own copy and a write left waiting for the cohort are sorted by one rule.
|
|
57
|
+
*/
|
|
58
|
+
export function isCohortUnreachableRead(error: unknown): error is BlockUnavailableError {
|
|
59
|
+
return error instanceof BlockUnavailableError && cohortUnreachableReasons.has(error.reason);
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Sorts a commit failure into a {@link CommitFailureClass} — the one place every commit failure is
|
|
64
|
+
* sorted, so no caller has to read an error's message to decide what to do with a write.
|
|
65
|
+
*
|
|
66
|
+
* Two rules keep the answer safe:
|
|
67
|
+
*
|
|
68
|
+
* - **Type only, never text.** It reads the error's class and the structured fields
|
|
69
|
+
* `BlockUnavailableError.reason` and `TornActionError.final`, never `message`.
|
|
70
|
+
* - **The error thrown, never its `cause`.** A commit-phase shortfall reaches a local writer nested
|
|
71
|
+
* as the `cause` of the transactor's plain `Some peers did not complete` aggregate; that write is
|
|
72
|
+
* in doubt, not "nothing sent", and walking `cause` would sort it as unreachable. A wrapper whose
|
|
73
|
+
* wrapping means something is its own arm (`CoordinatorPartialCommitError`).
|
|
74
|
+
*
|
|
75
|
+
* The Quereus bridge's mapped errors (`ConstraintError`, `ConcurrentModificationError`) are not
|
|
76
|
+
* recognised: classify the db-core error before mapping it.
|
|
77
|
+
*
|
|
78
|
+
* Classes are matched with `instanceof`, so an error constructed by a second copy of this package
|
|
79
|
+
* sorts as `unknown` — the conservative answer, but a host that installs two copies loses every
|
|
80
|
+
* other class. No guard in this repository checks for that.
|
|
81
|
+
*/
|
|
82
|
+
export function classifyCommitFailure(error: unknown): CommitFailureClass {
|
|
83
|
+
if (error instanceof PromiseShortfallError) {
|
|
84
|
+
return { kind: 'cohort-unreachable', error };
|
|
85
|
+
}
|
|
86
|
+
if (error instanceof BlockUnavailableError) {
|
|
87
|
+
return isCohortUnreachableRead(error)
|
|
88
|
+
? { kind: 'cohort-unreachable', error }
|
|
89
|
+
: { kind: 'unknown', error };
|
|
90
|
+
}
|
|
91
|
+
// `SyncRevisionStalledError` is a `SyncRetryExhaustedError`, so the base class covers it.
|
|
92
|
+
if (error instanceof SyncRetryExhaustedError || error instanceof CoordinatorStaleLossError) {
|
|
93
|
+
return { kind: 'contention', error };
|
|
94
|
+
}
|
|
95
|
+
if (error instanceof TreeGuardRefusedError) {
|
|
96
|
+
// Every guard refusal other than a lost update is a uniqueness refusal, including a subclass
|
|
97
|
+
// added later: the hierarchy's contract is that a refusal is never downgraded to retryable.
|
|
98
|
+
// NOTE: matched at the tree's class, not at its base `ActionRefusedError`, because the
|
|
99
|
+
// `constraint` / `concurrent-modification` split and the bridge's `mapRefusal` are tree
|
|
100
|
+
// vocabulary; the tree is the only collection type that refuses today. If another type ever
|
|
101
|
+
// throws an `ActionRefusedError`, widen this arm (and the `error` type on `guard-refused`)
|
|
102
|
+
// to the base, or its refusal sorts as `unknown` and the drain retries a final failure.
|
|
103
|
+
return { kind: 'guard-refused', refusal: refusalReason(error), error };
|
|
104
|
+
}
|
|
105
|
+
if (error instanceof ValidityRejectedError) {
|
|
106
|
+
return { kind: 'rejected', error };
|
|
107
|
+
}
|
|
108
|
+
if (error instanceof TransactionTooLargeError || error instanceof BlockTooLargeError) {
|
|
109
|
+
return { kind: 'too-large', error };
|
|
110
|
+
}
|
|
111
|
+
if (error instanceof TransactionExpiredError) {
|
|
112
|
+
return { kind: 'expired', error };
|
|
113
|
+
}
|
|
114
|
+
if (error instanceof TornActionError) {
|
|
115
|
+
return error.final ? { kind: 'torn-not-saved', error } : { kind: 'in-doubt', error };
|
|
116
|
+
}
|
|
117
|
+
if (error instanceof CoordinatorPartialCommitError) {
|
|
118
|
+
return { kind: 'partial', error };
|
|
119
|
+
}
|
|
120
|
+
return { kind: 'unknown', error };
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/**
|
|
124
|
+
* The failure reason a guard refusal reports to an application: `concurrent-modification` for a lost
|
|
125
|
+
* update ({@link TreeEntryChangedError}), `constraint` for every other refusal — a uniqueness refusal,
|
|
126
|
+
* or a refusal by a collection type other than the tree, which has no finer vocabulary. The ONE
|
|
127
|
+
* mapping {@link classifyCommitFailure}'s `guard-refused` arm and the offline queue share — for the
|
|
128
|
+
* refusals a collection reports through `onSealedRefused`, which never pass through a commit — so the
|
|
129
|
+
* two cannot disagree about one error.
|
|
130
|
+
*/
|
|
131
|
+
export function refusalReason(error: ActionRefusedError): 'constraint' | 'concurrent-modification' {
|
|
132
|
+
return error instanceof TreeEntryChangedError ? 'concurrent-modification' : 'constraint';
|
|
133
|
+
}
|