@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,148 @@
|
|
|
1
|
+
import type { CommitResult, WriteDurability } from "../network/struct.js";
|
|
2
|
+
import type { CollectionId, HeadCommitOptions } from "./struct.js";
|
|
3
|
+
import type { EntryId } from "./segments.js";
|
|
4
|
+
import type { RefreshReport } from "./collection.js";
|
|
5
|
+
import { AttemptCycle, retainedAttempt } from "./write-attempts.js";
|
|
6
|
+
import type { StagedAttempt } from "./write-attempts.js";
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* One collection's head commit — the commit of its oldest sealed segment as one log entry
|
|
10
|
+
* (docs/offline-sync.md §One entry, one network transaction) — exposed one step at a time, so a
|
|
11
|
+
* driver outside the collection can run the steps in the order it needs. `Collection.openHeadCommit`
|
|
12
|
+
* creates one, as a closure over the collection's private state, having taken the collection latch,
|
|
13
|
+
* checked the segment is committable, marked the action in flight and set the head entry for the
|
|
14
|
+
* cycle; the handle holds that latch until {@link close}, except between {@link release} and
|
|
15
|
+
* {@link retake}. Two drivers exist: {@link driveHeadCommit}, the one-collection loop behind
|
|
16
|
+
* `Collection.commitHead`, and the coordinator's per-entry commit over several collections, which
|
|
17
|
+
* has to run each step on every collection it wrote in lock-step — build every attempt, release
|
|
18
|
+
* every latch, one pend-all-then-commit round, retake every latch, apply one outcome each — which
|
|
19
|
+
* is only possible with the steps callable from outside.
|
|
20
|
+
*
|
|
21
|
+
* The step order a driver keeps: {@link refresh} (the cycle opens with one, and one follows every
|
|
22
|
+
* refused attempt); then per attempt {@link stage}, the write-ahead hook with the staged attempt,
|
|
23
|
+
* {@link release}, {@link send} (or the coordinator's own round), {@link retake} in a `finally`,
|
|
24
|
+
* then {@link fold} followed by {@link replay} on success, or {@link refused} on a refusal. Every
|
|
25
|
+
* step but {@link send} runs under the latch, and the handle throws as a defect when one is called
|
|
26
|
+
* with the latch released, after {@link close}, or ({@link retake}) while it is already held.
|
|
27
|
+
*
|
|
28
|
+
* Two handles on two collections are opened in SORTED collection-id order by any driver that opens
|
|
29
|
+
* more than one — the order `TransactionCoordinator.commitOnce` acquires the same latches in —
|
|
30
|
+
* since a multi-collection commit over the same collections would otherwise deadlock against it.
|
|
31
|
+
* The handle does no sorting of its own; it is one collection's.
|
|
32
|
+
*/
|
|
33
|
+
export interface HeadCommitHandle {
|
|
34
|
+
readonly collectionId: CollectionId;
|
|
35
|
+
/** The collection handle's tag (`Collection.instanceTag`), for the cycle's log lines. */
|
|
36
|
+
readonly instanceTag: string;
|
|
37
|
+
/** The sealed segment this handle commits — the head when it was opened, and asserted still
|
|
38
|
+
* the head by every step that touches it. */
|
|
39
|
+
readonly entryId: EntryId;
|
|
40
|
+
/** The refresh between attempts, run under the latch this handle holds: `Collection.updateInternal`
|
|
41
|
+
* with the write's own report, so an entry an earlier attempt stored is finished and consumed as
|
|
42
|
+
* the head (`Collection.consumeHead`). Same contract as `Collection.refreshInFlight`, minus the
|
|
43
|
+
* latch. */
|
|
44
|
+
refresh(report: RefreshReport, lastChance: boolean, tailFloor?: number): Promise<void>;
|
|
45
|
+
/** The revision the next attempt requests, and the one the collection holds, for the cycle's
|
|
46
|
+
* stall accounting (`AttemptCycle.beforeAttempt`). */
|
|
47
|
+
nextRev(): number;
|
|
48
|
+
heldRev(): number | undefined;
|
|
49
|
+
/** Re-check the head is still committable (a refresh may have refused it meanwhile — the
|
|
50
|
+
* recorded refusal is thrown), then build the attempt at {@link nextRev} on the head tracker,
|
|
51
|
+
* reused while the revision and the bases under it are unchanged (`Collection.headTrackerFor`) —
|
|
52
|
+
* or, for a cycle opened with a recorded attempt to resume, answer that attempt itself while
|
|
53
|
+
* {@link nextRev} is its revision (`resumedAttempt`). */
|
|
54
|
+
stage(): Promise<StagedAttempt>;
|
|
55
|
+
/** Send one attempt through this collection's own transactor source — the one-collection
|
|
56
|
+
* path's pend-and-commit, under the cycle's aged retry `priority`. The coordinator never calls
|
|
57
|
+
* it: its round goes through its own phases. Made with the latch released. */
|
|
58
|
+
send(staged: StagedAttempt, priority: number): Promise<CommitResult>;
|
|
59
|
+
/** Release the latch for the network round trip and set `Collection.headInFlight`, so a refresh
|
|
60
|
+
* that walks into this commit's entry meanwhile defers, and `dropSealed` of the head refuses. */
|
|
61
|
+
release(): void;
|
|
62
|
+
/** Retake the latch and clear `Collection.headInFlight`. Never throws for a refusal: the caller
|
|
63
|
+
* re-checks through {@link stage} or {@link refused}, so a send error is not masked. */
|
|
64
|
+
retake(): Promise<void>;
|
|
65
|
+
/** A committed attempt's local treatment, first half, synchronous: remove the head segment
|
|
66
|
+
* (asserted still first), bump the segment version, fold the attempt's transforms into the
|
|
67
|
+
* cache and adopt its revision (`Collection.foldOwnCommit`), and hand the dropped segment's
|
|
68
|
+
* recorded tally to the cycle's `onCommittedHead` hook (`HeadCommitOptions.onCommittedHead`). */
|
|
69
|
+
fold(staged: StagedAttempt): void;
|
|
70
|
+
/** Second half: replay the remaining sealed segments and the open segment over the committed
|
|
71
|
+
* state that now holds the head. Always after {@link fold} — the order `Collection.updateInternal`
|
|
72
|
+
* requires. Two calls rather than one because the coordinator's success path folds every
|
|
73
|
+
* participant in one await-free pass before replaying any, the event-loop atomicity its
|
|
74
|
+
* existing success fold promises (`TransactionCoordinator.commitOnceLatched`). */
|
|
75
|
+
replay(): Promise<void>;
|
|
76
|
+
/** A refused attempt: re-check the head's recorded refusal (thrown), then retain the attempt
|
|
77
|
+
* (`Collection.retainInFlightAttempt`) so the next refresh can finish it. */
|
|
78
|
+
refused(staged: StagedAttempt): void;
|
|
79
|
+
/** End the cycle: clear the head entry, dispose the in-flight mark, release the latch if held.
|
|
80
|
+
* Idempotent, and tolerant of a latch left released (a driver that threw between
|
|
81
|
+
* {@link release} and {@link retake} without retaking): it then clears the marks latch-free
|
|
82
|
+
* rather than block on a latch inside a cleanup. Every exit of a driver passes through it. */
|
|
83
|
+
close(): void;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* The one-collection driver: the attempt cycle behind `Collection.commitHead`, with the
|
|
88
|
+
* {@link AttemptCycle} accounting a sync's attempts use. The cycle opens with a refresh (like
|
|
89
|
+
* `Collection.updateAndSync`), which — the action being marked in flight, and `options.resume`
|
|
90
|
+
* seeded when the caller recorded an earlier attempt — finishes or recognises an entry an earlier
|
|
91
|
+
* cycle under the same action id left in the log, and consumes the head instead of committing a
|
|
92
|
+
* second copy. Then attempts until the head is committed: the pre-attempt checks, the attempt built
|
|
93
|
+
* on the head tracker, the write-ahead hook (`options.recordAttempt`, awaited under the latch, so a
|
|
94
|
+
* throw aborts before anything is sent), the latch released around the one network `await` and
|
|
95
|
+
* retaken whatever becomes of it, and the outcome applied under the retaken latch — fold then
|
|
96
|
+
* replay on a commit, or the refusal retained and the refresh-until-settled loop on a refusal.
|
|
97
|
+
*
|
|
98
|
+
* The head's recorded refusal is re-checked at the two points a refresh may have refused it:
|
|
99
|
+
* building the attempt ({@link HeadCommitHandle.stage}) and right after a refused send
|
|
100
|
+
* ({@link HeadCommitHandle.refused}), each of which throws it in place of a retry. The refusal is
|
|
101
|
+
* re-checked after the cycle's pre-attempt checks rather than before them, so a cycle that is both
|
|
102
|
+
* aborted (or past its deadline) and refused reports the abort; the previous in-line loop checked
|
|
103
|
+
* the refusal first, and nothing observable depends on which wins.
|
|
104
|
+
*
|
|
105
|
+
* Does not close the handle: the caller that opened it does, in a `finally`.
|
|
106
|
+
*
|
|
107
|
+
* @returns what `Collection.sync` returns: who holds the commit, or `undefined` when the opening
|
|
108
|
+
* refresh established the write was already saved under `options.actionId` without re-sending
|
|
109
|
+
* (the status-read fallback of `Collection.completeOwnEntry`).
|
|
110
|
+
* @throws the head's recorded refusal, an `ActionRefusedError`; whatever `options.recordAttempt`
|
|
111
|
+
* throws, before anything is sent; otherwise what `Collection.sync` throws. */
|
|
112
|
+
export async function driveHeadCommit(handle: HeadCommitHandle, options: HeadCommitOptions): Promise<WriteDurability | undefined> {
|
|
113
|
+
const cycle = new AttemptCycle(handle.collectionId, handle.instanceTag, options);
|
|
114
|
+
const refresh = (report: RefreshReport, lastChance: boolean, tailFloor: number | undefined) =>
|
|
115
|
+
handle.refresh(report, lastChance, tailFloor);
|
|
116
|
+
let saved = await cycle.refreshUntilSettled(refresh);
|
|
117
|
+
while (!saved) {
|
|
118
|
+
cycle.beforeAttempt(handle.nextRev(), handle.heldRev());
|
|
119
|
+
const staged = await handle.stage();
|
|
120
|
+
await options.recordAttempt?.(retainedAttempt(staged, options.actionId));
|
|
121
|
+
const attempt = await sendUnlatched(handle, staged, cycle.priority());
|
|
122
|
+
if (attempt.success) {
|
|
123
|
+
cycle.recordCommit(attempt.durability);
|
|
124
|
+
handle.fold(staged);
|
|
125
|
+
await handle.replay();
|
|
126
|
+
saved = true;
|
|
127
|
+
} else {
|
|
128
|
+
// Re-checked before the refusal is counted: a reader's refresh while the latch was
|
|
129
|
+
// released may have adopted the rival this attempt lost to and refused the head in its
|
|
130
|
+
// replay, and that refusal, not another attempt, is then the cycle's answer.
|
|
131
|
+
handle.refused(staged);
|
|
132
|
+
cycle.recordRefusal(attempt);
|
|
133
|
+
saved = await cycle.refreshUntilSettled(refresh);
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
return cycle.durability;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/** The one network round trip, made with the latch released and retaken before anything else runs
|
|
140
|
+
* — on a throw too, so the handle is never closed over a latch it does not hold. */
|
|
141
|
+
async function sendUnlatched(handle: HeadCommitHandle, staged: StagedAttempt, priority: number): Promise<CommitResult> {
|
|
142
|
+
handle.release();
|
|
143
|
+
try {
|
|
144
|
+
return await handle.send(staged, priority);
|
|
145
|
+
} finally {
|
|
146
|
+
await handle.retake();
|
|
147
|
+
}
|
|
148
|
+
}
|
package/src/collection/index.ts
CHANGED
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
import type { Action } from "../index.js";
|
|
2
|
+
import type { AlreadyAppliedTally } from "./action.js";
|
|
3
|
+
import type { ActionRefusedError } from "./struct.js";
|
|
4
|
+
|
|
5
|
+
/** A queue entry's id, opaque to the collection: the offline-sync queue (docs/offline-sync.md)
|
|
6
|
+
* mints one per locally committed transaction and seals that transaction's actions under it. */
|
|
7
|
+
export type EntryId = string;
|
|
8
|
+
|
|
9
|
+
/** The actions one queue entry staged into a collection, closed off from later staging. */
|
|
10
|
+
export type SealedSegment<TAction> = {
|
|
11
|
+
readonly entryId: EntryId;
|
|
12
|
+
/** Exactly the actions the entry staged into this collection, in staging order (invariant 3 of
|
|
13
|
+
* docs/offline-sync.md §The segment model). Never rewritten: the conflict filter applies to the
|
|
14
|
+
* open segment only. */
|
|
15
|
+
readonly actions: readonly Action<TAction>[];
|
|
16
|
+
/** The refusal recorded for this segment, once a replay refused it. A refused segment is excluded
|
|
17
|
+
* from every later replay until it is dropped. */
|
|
18
|
+
refused?: ActionRefusedError;
|
|
19
|
+
/** What the segment's actions accepted as already applied the last time they were staged over the
|
|
20
|
+
* committed state — by a replay (`Collection.replayActions`) or by a head commit's tracker
|
|
21
|
+
* (`Collection.buildHeadTracker`), both of which stage over the state the collection reads at, so
|
|
22
|
+
* when the head commit folds this is the tally of a staging over the state the write committed
|
|
23
|
+
* over. Set directly, with no version bump: it is not a change to the sealed list. Reported to the
|
|
24
|
+
* head commit's `onCommittedHead` hook when the segment is dropped as committed. Absent only before
|
|
25
|
+
* the segment's first staging — a refused staging leaves the previous value, which nothing reads,
|
|
26
|
+
* since a refused segment is never committed. */
|
|
27
|
+
applied?: AlreadyAppliedTally;
|
|
28
|
+
};
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* A collection's staged actions, in two parts: the sealed segments, one per queued entry that wrote
|
|
32
|
+
* the collection, oldest first, and the open segment the current transaction is staging into
|
|
33
|
+
* (docs/offline-sync.md §The segment model). The pure list operations live here; everything that
|
|
34
|
+
* touches the tracker or the collection latch stays on `Collection`.
|
|
35
|
+
*/
|
|
36
|
+
export class SegmentList<TAction> {
|
|
37
|
+
/** Sealed segments in queue order, oldest first (invariant 1). Private so every change goes
|
|
38
|
+
* through a method that bumps `version`; read it through {@link replayable}, {@link find},
|
|
39
|
+
* {@link head} and {@link entryIds}. */
|
|
40
|
+
private readonly sealed: SealedSegment<TAction>[] = [];
|
|
41
|
+
/** The open segment: what the current transaction has staged. */
|
|
42
|
+
open: Action<TAction>[] = [];
|
|
43
|
+
/** Bumped on every change to the sealed list — a seal, an unseal, an insert, a drop, a refusal
|
|
44
|
+
* recorded. Captured by a snapshot so a restore can tell whether the sealed segments it was taken
|
|
45
|
+
* over are still the ones in place (ticket `offline-sync-open-segment-snapshot`). Read and written
|
|
46
|
+
* only under the collection latch or from synchronous callers. */
|
|
47
|
+
version = 0;
|
|
48
|
+
|
|
49
|
+
/** Close the open segment into a sealed segment owned by `entryId`. Returns `false` and changes
|
|
50
|
+
* nothing — the version included — when the open segment is empty: an entry that staged nothing
|
|
51
|
+
* here owns no segment here. Throws when `entryId` is already sealed. */
|
|
52
|
+
seal(entryId: EntryId): boolean {
|
|
53
|
+
if (this.find(entryId) !== undefined) {
|
|
54
|
+
throw new Error(`entry ${entryId} is already sealed in this collection`);
|
|
55
|
+
}
|
|
56
|
+
if (this.open.length === 0) {
|
|
57
|
+
return false;
|
|
58
|
+
}
|
|
59
|
+
this.sealed.push({ entryId, actions: this.open });
|
|
60
|
+
this.open = [];
|
|
61
|
+
this.version++;
|
|
62
|
+
return true;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** The exact inverse of {@link seal}: move the newest sealed segment's actions back into the open
|
|
66
|
+
* segment, for an enqueue whose journal write failed after sealing (`OfflineQueue.enqueue`).
|
|
67
|
+
* Requires the segment to be the NEWEST sealed one and the open segment to be empty — both true at
|
|
68
|
+
* that one call site, which has just sealed and staged nothing since — and throws otherwise, since
|
|
69
|
+
* putting an older segment's actions behind a newer one's would reorder what was staged. Bumps
|
|
70
|
+
* `version`: the sealed list changed, even though the tracker did not (the transforms are already
|
|
71
|
+
* what they were). */
|
|
72
|
+
unseal(entryId: EntryId): void {
|
|
73
|
+
const newest = this.sealed[this.sealed.length - 1];
|
|
74
|
+
if (newest === undefined || newest.entryId !== entryId) {
|
|
75
|
+
throw new Error(`entry ${entryId} is not the newest sealed segment (${newest?.entryId ?? 'nothing is sealed'}); only the newest can be unsealed`);
|
|
76
|
+
}
|
|
77
|
+
if (this.open.length > 0) {
|
|
78
|
+
throw new Error(`entry ${entryId} cannot be unsealed over a non-empty open segment`);
|
|
79
|
+
}
|
|
80
|
+
this.sealed.pop();
|
|
81
|
+
this.open = [...newest.actions];
|
|
82
|
+
this.version++;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** Insert a sealed segment owned by `entryId` holding `actions`, ahead of the segment `before`
|
|
86
|
+
* names, or last when `before` is `undefined` — a segment put back from a journal after a restart
|
|
87
|
+
* (`Collection.restoreSealed`), which belongs wherever its entry sits in queue order. Throws when
|
|
88
|
+
* `entryId` is already sealed or `before` names no segment here, before anything changes. */
|
|
89
|
+
insert(entryId: EntryId, actions: readonly Action<TAction>[], before: EntryId | undefined): void {
|
|
90
|
+
if (this.find(entryId) !== undefined) {
|
|
91
|
+
throw new Error(`entry ${entryId} is already sealed in this collection`);
|
|
92
|
+
}
|
|
93
|
+
const index = before === undefined ? this.sealed.length : this.sealed.findIndex(segment => segment.entryId === before);
|
|
94
|
+
if (index < 0) {
|
|
95
|
+
throw new Error(`entry ${before} is not sealed in this collection; cannot insert ${entryId} before it`);
|
|
96
|
+
}
|
|
97
|
+
this.sealed.splice(index, 0, { entryId, actions: [...actions] });
|
|
98
|
+
this.version++;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/** Remove the segment owned by `entryId`, wherever it sits. Throws for an unknown id. */
|
|
102
|
+
drop(entryId: EntryId): SealedSegment<TAction> {
|
|
103
|
+
const index = this.sealed.findIndex(segment => segment.entryId === entryId);
|
|
104
|
+
if (index < 0) {
|
|
105
|
+
throw new Error(`entry ${entryId} is not sealed in this collection`);
|
|
106
|
+
}
|
|
107
|
+
const [dropped] = this.sealed.splice(index, 1);
|
|
108
|
+
this.version++;
|
|
109
|
+
return dropped!;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/** Record that a replay refused the segment owned by `entryId`, excluding it from later replays. */
|
|
113
|
+
refuse(entryId: EntryId, error: ActionRefusedError): void {
|
|
114
|
+
const segment = this.find(entryId);
|
|
115
|
+
if (segment === undefined) {
|
|
116
|
+
throw new Error(`entry ${entryId} is not sealed in this collection`);
|
|
117
|
+
}
|
|
118
|
+
segment.refused = error;
|
|
119
|
+
this.version++;
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
find(entryId: EntryId): SealedSegment<TAction> | undefined {
|
|
123
|
+
return this.sealed.find(segment => segment.entryId === entryId);
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/** The oldest sealed segment, if any. */
|
|
127
|
+
head(): SealedSegment<TAction> | undefined {
|
|
128
|
+
return this.sealed[0];
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
entryIds(): EntryId[] {
|
|
132
|
+
return this.sealed.map(segment => segment.entryId);
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/** Whether any segment is sealed, refused ones included. */
|
|
136
|
+
hasSealed(): boolean {
|
|
137
|
+
return this.sealed.length > 0;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/** The sealed segments a replay re-stages, in order: every one not refused. */
|
|
141
|
+
replayable(): SealedSegment<TAction>[] {
|
|
142
|
+
return this.sealed.filter(segment => segment.refused === undefined);
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/** How many actions a replay re-stages: the replayable sealed segments' plus the open segment's. */
|
|
146
|
+
replayableCount(): number {
|
|
147
|
+
return this.replayable().reduce((count, segment) => count + segment.actions.length, this.open.length);
|
|
148
|
+
}
|
|
149
|
+
}
|
package/src/collection/struct.ts
CHANGED
|
@@ -1,9 +1,163 @@
|
|
|
1
|
-
import type { IBlock, BlockId, Action, WriteDurability } from "../index.js";
|
|
1
|
+
import type { IBlock, BlockId, Action, ActionId, Transforms, WriteDurability } from "../index.js";
|
|
2
2
|
import type { IChainHeader } from "../chain/chain-nodes.js";
|
|
3
3
|
import type { RandFn } from "../utility/backoff.js";
|
|
4
|
+
import type { EntryId } from "./segments.js";
|
|
5
|
+
import type { AlreadyAppliedTally } from "./action.js";
|
|
6
|
+
import type { BlockBaseRevs, BlockContentDigests } from "../network/struct.js";
|
|
4
7
|
|
|
5
8
|
export type CollectionId = BlockId;
|
|
6
9
|
|
|
10
|
+
/**
|
|
11
|
+
* A handler's statement that an action cannot be applied over the committed state it is being
|
|
12
|
+
* replayed against — a uniqueness or lost-update check failed. Not a transport failure and never
|
|
13
|
+
* retryable: the action's staged writes are discarded (the handler runs inside an Atomic), and
|
|
14
|
+
* nothing downgrades it to a stale failure. `TreeGuardRefusedError` in
|
|
15
|
+
* `packages/db-core/src/collections/tree/struct.ts` is the tree's subclass, and carries the
|
|
16
|
+
* contract every refusal obeys.
|
|
17
|
+
*
|
|
18
|
+
* Lives here rather than beside the tree so the collection can recognise a refusal without
|
|
19
|
+
* importing the tree module (which imports the collection). Segment-aware replay
|
|
20
|
+
* (`Collection.replayActions`) treats a throw of this class from a SEALED segment as that
|
|
21
|
+
* segment's refusal and keeps going; from the open segment it propagates as it always has.
|
|
22
|
+
*/
|
|
23
|
+
export class ActionRefusedError extends Error {
|
|
24
|
+
constructor(
|
|
25
|
+
/** The collection whose handler refused the action. */
|
|
26
|
+
readonly collectionId: CollectionId,
|
|
27
|
+
message: string,
|
|
28
|
+
) {
|
|
29
|
+
super(message);
|
|
30
|
+
this.name = 'ActionRefusedError';
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** Why a sealed segment stood in the way of a commit (see {@link SealedSegmentsError}):
|
|
35
|
+
* - `whole-collection` — a whole-collection commit was asked for while a segment is sealed.
|
|
36
|
+
* - `not-head` — `commitHead` named a segment that is not the oldest sealed one.
|
|
37
|
+
* - `refused` — `commitHead` named a segment a replay has refused; the queue drops it instead.
|
|
38
|
+
* - `in-flight` — a head commit is on the network for the named segment, so neither a second
|
|
39
|
+
* `commitHead` nor a `dropSealed` of it can proceed. */
|
|
40
|
+
export type SealedSegmentsReason = 'whole-collection' | 'not-head' | 'refused' | 'in-flight';
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* Thrown by the whole-collection commit paths — {@link ICollection.sync},
|
|
44
|
+
* {@link ICollection.updateAndSync}, `Collection.actAndSync` and `Collection.getPendingActions`
|
|
45
|
+
* (the coordinator's append) — while the collection holds sealed segments. Those paths commit
|
|
46
|
+
* everything staged as ONE log entry under one action id; over sealed segments that would merge
|
|
47
|
+
* several queue entries into one, which the queue's identity rules forbid
|
|
48
|
+
* (docs/offline-sync.md §Identity across attempts). A sealed segment is committed on its own,
|
|
49
|
+
* through `Collection.commitHead`, whose own preconditions throw this class too, with a
|
|
50
|
+
* {@link reason} other than `whole-collection` (see {@link SealedSegmentsReason}).
|
|
51
|
+
*
|
|
52
|
+
* Nothing is unstaged or changed when this is thrown: every segment, sealed and open, is exactly
|
|
53
|
+
* as it was.
|
|
54
|
+
*/
|
|
55
|
+
export class SealedSegmentsError extends Error {
|
|
56
|
+
constructor(
|
|
57
|
+
readonly collectionId: CollectionId,
|
|
58
|
+
/** The sealed segments' entry ids, in order. */
|
|
59
|
+
readonly sealedEntries: EntryId[],
|
|
60
|
+
readonly reason: SealedSegmentsReason = 'whole-collection',
|
|
61
|
+
/** The entry a `commitHead` or `dropSealed` named, for every reason but `whole-collection`. */
|
|
62
|
+
readonly entryId?: EntryId,
|
|
63
|
+
) {
|
|
64
|
+
super(sealedSegmentsMessage(collectionId, sealedEntries, reason, entryId));
|
|
65
|
+
this.name = 'SealedSegmentsError';
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
function sealedSegmentsMessage(collectionId: CollectionId, sealedEntries: EntryId[], reason: SealedSegmentsReason, entryId: EntryId | undefined): string {
|
|
70
|
+
const listed = sealedEntries.length === 0 ? 'nothing' : sealedEntries.join(', ');
|
|
71
|
+
switch (reason) {
|
|
72
|
+
case 'whole-collection':
|
|
73
|
+
return `collection ${collectionId} holds sealed segment(s) ${listed}; `
|
|
74
|
+
+ `a whole-collection commit would merge them into one log entry — commit the head segment instead`;
|
|
75
|
+
case 'not-head':
|
|
76
|
+
return `collection ${collectionId}: entry ${entryId} is not the head sealed segment (sealed: ${listed}); `
|
|
77
|
+
+ `only the oldest sealed segment can be committed`;
|
|
78
|
+
case 'refused':
|
|
79
|
+
return `collection ${collectionId}: entry ${entryId} carries a recorded refusal; `
|
|
80
|
+
+ `a refused segment is dropped, never committed`;
|
|
81
|
+
case 'in-flight':
|
|
82
|
+
return `collection ${collectionId}: a head commit of entry ${entryId} is in flight on this instance`;
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/** Exactly what one write attempt sent to the transactor — enough to send the same thing again.
|
|
87
|
+
* Retained by `Collection.retainInFlightAttempt` so that a refresh which then finds this attempt's
|
|
88
|
+
* own log entry can land the blocks the attempt left behind, at the same action id and revision
|
|
89
|
+
* (see `Collection.completeOwnEntry`).
|
|
90
|
+
*
|
|
91
|
+
* Also the shape a caller RECORDS before an attempt is sent and hands back on a later cycle
|
|
92
|
+
* ({@link HeadCommitOptions.recordAttempt} and {@link HeadCommitOptions.resume};
|
|
93
|
+
* docs/offline-sync.md §Identity across attempts), so it must stay plain data — ids, numbers and the
|
|
94
|
+
* transforms as the wire carries them, nothing with object identity and no functions: the
|
|
95
|
+
* offline-sync journal serialises it as JSON. */
|
|
96
|
+
export type InFlightAttempt = {
|
|
97
|
+
/** The action id the attempt was sent under — the one every attempt of the write reuses, and
|
|
98
|
+
* the one a cycle that resumes from this record must run under. */
|
|
99
|
+
actionId: ActionId;
|
|
100
|
+
/** The revision the attempt's log entry was stamped with, and pended and committed at. */
|
|
101
|
+
rev: number;
|
|
102
|
+
/** Every transform the attempt pended — the log blocks included. The caller hands over a copy
|
|
103
|
+
* it will not mutate; the collection keeps it as given. */
|
|
104
|
+
transforms: Transforms;
|
|
105
|
+
/** The attempt's log tail block, committed first. */
|
|
106
|
+
tailId: BlockId;
|
|
107
|
+
/** The per-block content declarations the attempt's commit carried, if any. */
|
|
108
|
+
blockDigests?: BlockContentDigests;
|
|
109
|
+
/** The per-block bases the attempt's pend carried, if any (see `PendRequest.baseRevs`). Kept
|
|
110
|
+
* with the transforms because they describe them: a re-send of these operations must name the
|
|
111
|
+
* same bases they were computed against. */
|
|
112
|
+
baseRevs?: BlockBaseRevs;
|
|
113
|
+
};
|
|
114
|
+
|
|
115
|
+
/** What `Collection.commitHead` commits the head segment under, beside the retry bounds of
|
|
116
|
+
* {@link SyncOptions}. Both fields are the queue's (docs/offline-sync.md §Identity across
|
|
117
|
+
* attempts): the collection mints neither. */
|
|
118
|
+
export type HeadCommitOptions = SyncOptions & {
|
|
119
|
+
/** The action id the attempt cycle runs under. The queue mints it, and re-supplies the SAME id
|
|
120
|
+
* when it re-drives an entry whose earlier attempt may have landed, so the refresh that opens the
|
|
121
|
+
* cycle recognises that attempt's log entry as the write's own and finishes or consumes it
|
|
122
|
+
* instead of committing a second copy. */
|
|
123
|
+
actionId: ActionId;
|
|
124
|
+
/** The entry's local commit time, stamped on the log entry in place of the time
|
|
125
|
+
* `Collection.syncInternal` mints for a sync. Fixed per write, so every attempt appends the same
|
|
126
|
+
* entry (see "A write's log append is a fixed function of the write and the revision it is
|
|
127
|
+
* requesting" in docs/internals.md). */
|
|
128
|
+
timestamp: number;
|
|
129
|
+
/** The write-ahead hook: called with each attempt exactly as it is about to be sent — after it is
|
|
130
|
+
* built and BEFORE the collection latch is released for the network — and awaited under that
|
|
131
|
+
* latch. It is where the queue records the attempt's identity before sending it
|
|
132
|
+
* (docs/offline-sync.md §Identity across attempts) and, later, where the journal writes it. A
|
|
133
|
+
* throw aborts the cycle before anything is sent: it escapes `commitHead` unchanged, the handle
|
|
134
|
+
* closes, and every segment is exactly as it was. */
|
|
135
|
+
recordAttempt?: (attempt: InFlightAttempt) => Promise<void>;
|
|
136
|
+
/** The attempt an earlier cycle under the SAME `actionId` handed to `recordAttempt` and did not
|
|
137
|
+
* resolve — it must carry this `actionId`, and `openHeadCommit` throws before touching anything
|
|
138
|
+
* when it does not. Seeded as the retained attempt right after the action is marked in flight,
|
|
139
|
+
* so the cycle's opening refresh, finding that attempt's log entry with blocks missing, finishes
|
|
140
|
+
* it from these transforms (`Collection.completeOwnEntry`) instead of refusing it as torn with
|
|
141
|
+
* `transforms-not-held`. Without it a re-drive can recognise only an attempt that landed whole.
|
|
142
|
+
* The revision check still applies: an attempt recorded at a revision other than the entry's is
|
|
143
|
+
* refused as before. And when that refresh finds nothing new, this attempt is what the cycle
|
|
144
|
+
* re-sends, verbatim, while the next attempt would request its revision (`resumedAttempt`), since
|
|
145
|
+
* it may have landed on machines the refresh did not hear from. */
|
|
146
|
+
resume?: InFlightAttempt;
|
|
147
|
+
/** Called once, with what the head segment's actions accepted as already applied
|
|
148
|
+
* ({@link AlreadyAppliedTally}, as recorded on the segment by its last staging over the committed
|
|
149
|
+
* state), at the moment the segment is made durable and dropped: when the committed attempt is
|
|
150
|
+
* folded (`HeadCommitHandle.fold`), or when the cycle's refresh finds the entry's own log entry and
|
|
151
|
+
* consumes the head (`Collection.consumeHead`) — so a re-drive that finds its earlier attempt landed
|
|
152
|
+
* reports it too. Runs synchronously under the collection latch, like `onSealedRefused`, so it must
|
|
153
|
+
* not call a latched method of the collection; the queue's closure only records into a map. A throw
|
|
154
|
+
* out of it is logged, never raised: the commit is already durable. A hook rather than a widened
|
|
155
|
+
* return type because the partial-commit path reports the committed half through
|
|
156
|
+
* `CoordinatorPartialCommitError` and the refresh-consumed path through `RefreshReport`; one hook
|
|
157
|
+
* reaches all three. */
|
|
158
|
+
onCommittedHead?: (applied: AlreadyAppliedTally) => void;
|
|
159
|
+
};
|
|
160
|
+
|
|
7
161
|
export type CollectionHeaderBlock = IBlock & Partial<IChainHeader>;
|
|
8
162
|
|
|
9
163
|
/** A collection's committed tail: the log tail block its header names, and that block's latest
|
|
@@ -66,8 +220,36 @@ export interface SyncOptions {
|
|
|
66
220
|
* {@link deadlineMs} is still checked first, so a sync that is both past its deadline and
|
|
67
221
|
* stalled reports the deadline (as {@link SyncRetryExhaustedError}), not the stall. */
|
|
68
222
|
maxStalledAttempts?: number;
|
|
223
|
+
/** Refuse to let this write be committed by a lone node — a coordinator whose cohort for the
|
|
224
|
+
* write is only itself — while that node knows of members of the cohort it could not reach, is
|
|
225
|
+
* still waiting to hear from a peer it was configured to join through, or could not route the
|
|
226
|
+
* write at all. A node that is genuinely alone (no absent member known, nothing awaited, routed to
|
|
227
|
+
* itself) still commits. The refusal is a promise shortfall (`PromiseShortfallError`, with
|
|
228
|
+
* `soloRefused` naming the reason), so the write stops and is classified `cohort-unreachable`.
|
|
229
|
+
* Rides on every send of the write's attempt cycle as `PendRequest.refuseSolo` and
|
|
230
|
+
* `CommitRequest.refuseSolo`. Default off: only the offline queue sets it (docs/offline-sync.md
|
|
231
|
+
* §When to submit: the reachability gate). A coordinator on a build that predates the field
|
|
232
|
+
* ignores it and commits alone as before. */
|
|
233
|
+
refuseSoloCommit?: boolean;
|
|
69
234
|
}
|
|
70
235
|
|
|
236
|
+
/** What a write's attempt cycle carries besides its identity, recorded beside the in-flight mark
|
|
237
|
+
* (`Collection.beginInFlightAction`) so that every send of the cycle carries it: each attempt, and
|
|
238
|
+
* the re-send a refresh makes to finish a torn one (`Collection.completeOwnEntry`). */
|
|
239
|
+
export type InFlightCycle = {
|
|
240
|
+
/** {@link SyncOptions.refuseSoloCommit}, for this cycle. */
|
|
241
|
+
readonly refuseSolo?: boolean;
|
|
242
|
+
};
|
|
243
|
+
|
|
244
|
+
/** What `Collection.openHeadCommit` opens a head commit with besides its identity: the cycle's
|
|
245
|
+
* {@link InFlightCycle}, the attempt an earlier cycle under the same action id recorded and did not
|
|
246
|
+
* resolve ({@link HeadCommitOptions.resume}), and the committed-head hook
|
|
247
|
+
* ({@link HeadCommitOptions.onCommittedHead}). */
|
|
248
|
+
export type OpenHeadCommitOptions = InFlightCycle & {
|
|
249
|
+
readonly resume?: InFlightAttempt;
|
|
250
|
+
readonly onCommittedHead?: (applied: AlreadyAppliedTally) => void;
|
|
251
|
+
};
|
|
252
|
+
|
|
71
253
|
/** Thrown by {@link ICollection.sync} / {@link ICollection.updateAndSync} when the retry budget
|
|
72
254
|
* (attempt count or deadline) is exhausted while the transactor keeps returning stale failures.
|
|
73
255
|
* Catchable so callers can surface a clear "gave up syncing" condition instead of hanging.
|