@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.
Files changed (171) hide show
  1. package/dist/src/cluster/structs.d.ts +41 -8
  2. package/dist/src/cluster/structs.d.ts.map +1 -1
  3. package/dist/src/cluster/structs.js +18 -7
  4. package/dist/src/cluster/structs.js.map +1 -1
  5. package/dist/src/collection/action.d.ts +29 -0
  6. package/dist/src/collection/action.d.ts.map +1 -1
  7. package/dist/src/collection/action.js +6 -0
  8. package/dist/src/collection/action.js.map +1 -1
  9. package/dist/src/collection/collection.d.ts +533 -120
  10. package/dist/src/collection/collection.d.ts.map +1 -1
  11. package/dist/src/collection/collection.js +974 -500
  12. package/dist/src/collection/collection.js.map +1 -1
  13. package/dist/src/collection/head-commit.d.ts +110 -0
  14. package/dist/src/collection/head-commit.d.ts.map +1 -0
  15. package/dist/src/collection/head-commit.js +65 -0
  16. package/dist/src/collection/head-commit.js.map +1 -0
  17. package/dist/src/collection/index.d.ts +2 -0
  18. package/dist/src/collection/index.d.ts.map +1 -1
  19. package/dist/src/collection/index.js +2 -0
  20. package/dist/src/collection/index.js.map +1 -1
  21. package/dist/src/collection/segments.d.ts +77 -0
  22. package/dist/src/collection/segments.d.ts.map +1 -0
  23. package/dist/src/collection/segments.js +110 -0
  24. package/dist/src/collection/segments.js.map +1 -0
  25. package/dist/src/collection/struct.d.ts +156 -1
  26. package/dist/src/collection/struct.d.ts.map +1 -1
  27. package/dist/src/collection/struct.js +70 -0
  28. package/dist/src/collection/struct.js.map +1 -1
  29. package/dist/src/collection/write-attempts.d.ts +245 -0
  30. package/dist/src/collection/write-attempts.d.ts.map +1 -0
  31. package/dist/src/collection/write-attempts.js +439 -0
  32. package/dist/src/collection/write-attempts.js.map +1 -0
  33. package/dist/src/collections/tree/struct.d.ts +100 -17
  34. package/dist/src/collections/tree/struct.d.ts.map +1 -1
  35. package/dist/src/collections/tree/struct.js +38 -7
  36. package/dist/src/collections/tree/struct.js.map +1 -1
  37. package/dist/src/collections/tree/tree.d.ts +17 -5
  38. package/dist/src/collections/tree/tree.d.ts.map +1 -1
  39. package/dist/src/collections/tree/tree.js +112 -26
  40. package/dist/src/collections/tree/tree.js.map +1 -1
  41. package/dist/src/index.d.ts +2 -0
  42. package/dist/src/index.d.ts.map +1 -1
  43. package/dist/src/index.js +2 -0
  44. package/dist/src/index.js.map +1 -1
  45. package/dist/src/network/i-repo.d.ts +3 -0
  46. package/dist/src/network/i-repo.d.ts.map +1 -1
  47. package/dist/src/network/index.d.ts +3 -0
  48. package/dist/src/network/index.d.ts.map +1 -1
  49. package/dist/src/network/index.js +3 -0
  50. package/dist/src/network/index.js.map +1 -1
  51. package/dist/src/network/promise-shortfall-error.d.ts +40 -0
  52. package/dist/src/network/promise-shortfall-error.d.ts.map +1 -0
  53. package/dist/src/network/promise-shortfall-error.js +67 -0
  54. package/dist/src/network/promise-shortfall-error.js.map +1 -0
  55. package/dist/src/network/refuse-solo.d.ts +8 -0
  56. package/dist/src/network/refuse-solo.d.ts.map +1 -0
  57. package/dist/src/network/refuse-solo.js +8 -0
  58. package/dist/src/network/refuse-solo.js.map +1 -0
  59. package/dist/src/network/stale-failure.d.ts +20 -3
  60. package/dist/src/network/stale-failure.d.ts.map +1 -1
  61. package/dist/src/network/stale-failure.js +24 -3
  62. package/dist/src/network/stale-failure.js.map +1 -1
  63. package/dist/src/network/struct.d.ts +148 -2
  64. package/dist/src/network/struct.d.ts.map +1 -1
  65. package/dist/src/network/struct.js.map +1 -1
  66. package/dist/src/network/validity-rejected-error.d.ts +28 -0
  67. package/dist/src/network/validity-rejected-error.d.ts.map +1 -0
  68. package/dist/src/network/validity-rejected-error.js +51 -0
  69. package/dist/src/network/validity-rejected-error.js.map +1 -0
  70. package/dist/src/offline/entry.d.ts +72 -0
  71. package/dist/src/offline/entry.d.ts.map +1 -0
  72. package/dist/src/offline/entry.js +73 -0
  73. package/dist/src/offline/entry.js.map +1 -0
  74. package/dist/src/offline/index.d.ts +5 -0
  75. package/dist/src/offline/index.d.ts.map +1 -0
  76. package/dist/src/offline/index.js +5 -0
  77. package/dist/src/offline/index.js.map +1 -0
  78. package/dist/src/offline/journal.d.ts +61 -0
  79. package/dist/src/offline/journal.d.ts.map +1 -0
  80. package/dist/src/offline/journal.js +2 -0
  81. package/dist/src/offline/journal.js.map +1 -0
  82. package/dist/src/offline/queue.d.ts +484 -0
  83. package/dist/src/offline/queue.d.ts.map +1 -0
  84. package/dist/src/offline/queue.js +1236 -0
  85. package/dist/src/offline/queue.js.map +1 -0
  86. package/dist/src/offline/reachability.d.ts +25 -0
  87. package/dist/src/offline/reachability.d.ts.map +1 -0
  88. package/dist/src/offline/reachability.js +13 -0
  89. package/dist/src/offline/reachability.js.map +1 -0
  90. package/dist/src/offline/status.d.ts +148 -0
  91. package/dist/src/offline/status.d.ts.map +1 -0
  92. package/dist/src/offline/status.js +63 -0
  93. package/dist/src/offline/status.js.map +1 -0
  94. package/dist/src/offline/wake.d.ts +30 -0
  95. package/dist/src/offline/wake.d.ts.map +1 -0
  96. package/dist/src/offline/wake.js +68 -0
  97. package/dist/src/offline/wake.js.map +1 -0
  98. package/dist/src/testing/test-transactor.d.ts +29 -0
  99. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  100. package/dist/src/testing/test-transactor.js +50 -0
  101. package/dist/src/testing/test-transactor.js.map +1 -1
  102. package/dist/src/transaction/commit-failure-class.d.ts +103 -0
  103. package/dist/src/transaction/commit-failure-class.d.ts.map +1 -0
  104. package/dist/src/transaction/commit-failure-class.js +96 -0
  105. package/dist/src/transaction/commit-failure-class.js.map +1 -0
  106. package/dist/src/transaction/coordinator.d.ts +165 -41
  107. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  108. package/dist/src/transaction/coordinator.js +605 -300
  109. package/dist/src/transaction/coordinator.js.map +1 -1
  110. package/dist/src/transaction/entry-commit.d.ts +139 -0
  111. package/dist/src/transaction/entry-commit.d.ts.map +1 -0
  112. package/dist/src/transaction/entry-commit.js +199 -0
  113. package/dist/src/transaction/entry-commit.js.map +1 -0
  114. package/dist/src/transaction/index.d.ts +4 -1
  115. package/dist/src/transaction/index.d.ts.map +1 -1
  116. package/dist/src/transaction/index.js +1 -0
  117. package/dist/src/transaction/index.js.map +1 -1
  118. package/dist/src/transaction/transaction.d.ts +20 -0
  119. package/dist/src/transaction/transaction.d.ts.map +1 -1
  120. package/dist/src/transaction/validator.d.ts +7 -0
  121. package/dist/src/transaction/validator.d.ts.map +1 -1
  122. package/dist/src/transaction/validator.js +21 -12
  123. package/dist/src/transaction/validator.js.map +1 -1
  124. package/dist/src/transactor/network-transactor.d.ts +1 -0
  125. package/dist/src/transactor/network-transactor.d.ts.map +1 -1
  126. package/dist/src/transactor/network-transactor.js +61 -28
  127. package/dist/src/transactor/network-transactor.js.map +1 -1
  128. package/dist/src/transactor/transactor-source.d.ts +22 -11
  129. package/dist/src/transactor/transactor-source.d.ts.map +1 -1
  130. package/dist/src/transactor/transactor-source.js +9 -13
  131. package/dist/src/transactor/transactor-source.js.map +1 -1
  132. package/dist/src/utility/visit-every.d.ts +14 -0
  133. package/dist/src/utility/visit-every.d.ts.map +1 -0
  134. package/dist/src/utility/visit-every.js +27 -0
  135. package/dist/src/utility/visit-every.js.map +1 -0
  136. package/package.json +1 -1
  137. package/src/cluster/structs.ts +42 -7
  138. package/src/collection/action.ts +34 -0
  139. package/src/collection/collection.ts +1048 -543
  140. package/src/collection/head-commit.ts +148 -0
  141. package/src/collection/index.ts +2 -0
  142. package/src/collection/segments.ts +149 -0
  143. package/src/collection/struct.ts +183 -1
  144. package/src/collection/write-attempts.ts +506 -0
  145. package/src/collections/tree/struct.ts +97 -17
  146. package/src/collections/tree/tree.ts +125 -29
  147. package/src/index.ts +2 -0
  148. package/src/network/i-repo.ts +3 -0
  149. package/src/network/index.ts +3 -0
  150. package/src/network/promise-shortfall-error.ts +69 -0
  151. package/src/network/refuse-solo.ts +7 -0
  152. package/src/network/stale-failure.ts +27 -4
  153. package/src/network/struct.ts +154 -2
  154. package/src/network/validity-rejected-error.ts +55 -0
  155. package/src/offline/entry.ts +127 -0
  156. package/src/offline/index.ts +4 -0
  157. package/src/offline/journal.ts +60 -0
  158. package/src/offline/queue.ts +1342 -0
  159. package/src/offline/reachability.ts +32 -0
  160. package/src/offline/status.ts +183 -0
  161. package/src/offline/wake.ts +67 -0
  162. package/src/testing/test-transactor.ts +53 -0
  163. package/src/transaction/commit-failure-class.ts +133 -0
  164. package/src/transaction/coordinator.ts +696 -349
  165. package/src/transaction/entry-commit.ts +285 -0
  166. package/src/transaction/index.ts +4 -0
  167. package/src/transaction/transaction.ts +21 -0
  168. package/src/transaction/validator.ts +22 -12
  169. package/src/transactor/network-transactor.ts +62 -28
  170. package/src/transactor/transactor-source.ts +29 -13
  171. package/src/utility/visit-every.ts +25 -0
@@ -0,0 +1,1236 @@
1
+ import { randomBytes } from '@noble/hashes/utils.js';
2
+ import { toString as uint8ArrayToString } from 'uint8arrays/to-string';
3
+ import { ActionRefusedError, SealedSegmentsError } from '../collection/struct.js';
4
+ import { TransactionCoordinator } from '../transaction/coordinator.js';
5
+ import { classifyCommitFailure, refusalReason } from '../transaction/commit-failure-class.js';
6
+ import { recordCollectionDurability, transactionDurability } from '../transaction/durability.js';
7
+ import { createLogger } from '../logger.js';
8
+ import { alwaysReachable, gateBlockIds } from './reachability.js';
9
+ import { EntryDiscardedError, EntryExpiredError, EntryNotDiscardableError, QueueDisposedError, UnknownEntryError, } from './status.js';
10
+ import { committedField, currentStatus, driveState, effectOf, queuedStatus, queuedStatusChanged, snapshot } from './entry.js';
11
+ import { DrainWaker } from './wake.js';
12
+ const log = createLogger('offline');
13
+ /** The re-check timer's defaults while the cohort is unreachable or after a transient failure. */
14
+ const DefaultRecheckBaseMs = 1_000;
15
+ const DefaultRecheckMaxMs = 60_000;
16
+ /** The journal's write-ahead write threw: nothing was sent, so the entry is kept queued and re-driven
17
+ * after the backoff. Private to the queue — the journal's own error travels as `cause`. */
18
+ class RecordAttemptFailed extends Error {
19
+ cause;
20
+ constructor(cause) {
21
+ super('the journal refused the attempt before it was sent');
22
+ this.cause = cause;
23
+ this.name = 'RecordAttemptFailed';
24
+ }
25
+ }
26
+ /** A fresh entry or action id: 16 random bytes, base64url — the shape a sync's action id has. */
27
+ function mintId() {
28
+ return uint8ArrayToString(randomBytes(16), 'base64url');
29
+ }
30
+ function describe(error) {
31
+ return error instanceof Error ? error.message : String(error);
32
+ }
33
+ /** What `entry` wrote across every submission: the collections earlier partial commits committed,
34
+ * beside what the last submission answered (`undefined` when it answered nothing new). */
35
+ function entryDurability(entry, written) {
36
+ const collections = new Map(entry.committed);
37
+ for (const [collectionId, durability] of written?.collections ?? []) {
38
+ recordCollectionDurability(collections, collectionId, durability);
39
+ }
40
+ return transactionDurability(collections);
41
+ }
42
+ /**
43
+ * The one transactor `remaining` share, which the per-entry coordinator commits through. An entry
44
+ * whose collections sit on different transactors cannot be one network transaction (each transactor
45
+ * is its own storage); the queue's callers never seal such a set together, so this is a defect that
46
+ * stops the drain rather than a failure of the entry.
47
+ */
48
+ function sharedTransactor(entry, remaining) {
49
+ const transactor = remaining[0].transactor;
50
+ const stranger = remaining.find(collection => collection.transactor !== transactor);
51
+ if (stranger !== undefined) {
52
+ throw new Error(`offline queue: entry ${entry.id} spans collections on different transactors (${remaining[0].id} and ${stranger.id}); an entry is one network transaction on one transactor`);
53
+ }
54
+ return transactor;
55
+ }
56
+ /** The journal's entry record for `entry`, built from each sealed collection's segment. */
57
+ function entryRecord(entry) {
58
+ return {
59
+ id: entry.id,
60
+ seq: entry.seq,
61
+ queuedAt: entry.queuedAt,
62
+ ...(entry.expiresAt === undefined ? {} : { expiresAt: entry.expiresAt }),
63
+ segments: entry.collections.map(collection => {
64
+ const actions = collection.sealedActions(entry.id);
65
+ if (actions === undefined) {
66
+ throw new Error(`offline queue: entry ${entry.id} is not sealed in ${collection.id}, which sealPending just answered true for`);
67
+ }
68
+ return { collectionId: collection.id, actions };
69
+ }),
70
+ };
71
+ }
72
+ /**
73
+ * The offline-sync queue (docs/offline-sync.md §Draining): an in-memory list of locally committed
74
+ * entries, each the sealed segments one local commit left in the collections it wrote, drained one
75
+ * at a time in queue order once the cohort can be reached.
76
+ *
77
+ * **One drain loop per queue, serialised.** At most one submission is on the network at a time, and
78
+ * the loop is the only thing that removes entries' segments from the collections apart from
79
+ * {@link discard}, whose removal runs on the same removal chain. Each iteration: park while a
80
+ * {@link restore} holds the drain; apply the refusals {@link onSealedRefused} has collected; expire
81
+ * what has outlived `expireAfterMs`; wait for a wake when the queue is empty; fail the head when a
82
+ * collection already records its refusal; ask the reachability gate; submit the head —
83
+ * `Collection.commitHead` for an entry over one collection, `TransactionCoordinator.commitEntry`
84
+ * over several — and apply the outcome by its class (`classifyCommitFailure`). The gate and the
85
+ * transient failures share one re-check timer, whose step a wake or a committed entry resets.
86
+ *
87
+ * **A partly committed entry is finished, not rolled back** (docs/offline-sync.md §Partial commits):
88
+ * the committed collections' segments are consumed, the entry stays at the head in doubt, and each
89
+ * later submission drives only the collections still holding its segment, under the same action id.
90
+ *
91
+ * **Removing an entry cascades** (docs/offline-sync.md §Removing an entry): a failed entry's
92
+ * segments are dropped from its collections, each drop replays what remains, a later entry the
93
+ * replay refuses is reported through {@link onSealedRefused} and failed in turn with `causedBy`
94
+ * set, until nothing is pending. The callback runs under the collection latch, so it only records
95
+ * and wakes; the loop acts.
96
+ *
97
+ * **The journal is written through at every step of an entry's life** (docs/offline-sync.md
98
+ * §Write ordering), when one is given: {@link enqueue} writes the entry record before it admits the
99
+ * entry, every send is preceded by the drive record (`IOfflineJournal.driving`, the write-ahead that
100
+ * makes the identity rule survive a crash), a partial commit and an identity renewal rewrite it, and
101
+ * each terminal status is written before it is emitted. {@link restore} is the inverse, for a journal
102
+ * putting its records back after a restart.
103
+ *
104
+ * Everything an application sees goes through {@link onStatus} and {@link onQueueState}; a listener
105
+ * that throws is logged and never breaks the drain.
106
+ */
107
+ export class OfflineQueue {
108
+ list = [];
109
+ byId = new Map();
110
+ nextSeq = 1;
111
+ reachability;
112
+ waker;
113
+ submitOptions;
114
+ refuseSoloCommit;
115
+ expireAfterMs;
116
+ journal;
117
+ now;
118
+ unsubscribeWake;
119
+ statusListeners = new Set();
120
+ stateListeners = new Set();
121
+ lastState;
122
+ unclassifiedFailures = 0;
123
+ pendingRefusals = new Map();
124
+ /** The entry whose segments are being dropped, while they are: the attribution of the refusals
125
+ * those drops report (see {@link causeOf}). */
126
+ removing;
127
+ /** Every removal — the loop's and {@link discard}'s — runs on this chain, one at a time, so two
128
+ * never interleave their drops and {@link causeOf} always names one removal. Never rejects: a
129
+ * removal's throw reaches whoever awaited that removal, or {@link noteDefect} for a discard. */
130
+ removals = Promise.resolve();
131
+ /** Removals chained and not yet finished — a `discard`'s runs off the loop's path, and
132
+ * `whenDrained` answers at once only when none is. */
133
+ pendingRemovals = 0;
134
+ /** Every {@link restore} runs on this chain, one at a time, so two never hold the drain at once.
135
+ * Never rejects: a restore's throw reaches its own caller. */
136
+ restores = Promise.resolve();
137
+ /** The hold the restore in progress has on the drain, while it has one (see {@link restore}). */
138
+ hold;
139
+ /** The entry a {@link restore} has registered and not yet admitted: listed, so the refusals its
140
+ * insertion reports about other entries are attributed and its `stage` can read its position, but
141
+ * not yet discardable.
142
+ * NOTE: a `discard` of ANOTHER entry chained while `stage` runs is not held back; its drops run
143
+ * beside the insertion, serialised per collection only by the collection latch, and a refusal of
144
+ * the restoring entry's already-inserted segment that such a drop's replay reports is attributed
145
+ * by {@link causeOf} to the entry being discarded. Fine while restores run at start-up, before an
146
+ * application discards anything; if that attribution ever misleads, make `discard` wait out the
147
+ * hold too. */
148
+ restoring;
149
+ inFlight;
150
+ loop;
151
+ /** The loop ran and has exited (disposal, or a defect): nothing parks any more. */
152
+ loopStopped = false;
153
+ /** The loop is parked on an empty queue (so `whenDrained` can answer at once). */
154
+ waitingForWork = false;
155
+ drainedWaiters = [];
156
+ disposed = false;
157
+ disposal;
158
+ /** The error that stopped the drain (`SealedSegmentsError` out of a submission, a removal that
159
+ * threw): `whenDrained` rejects with it and `enqueue` refuses. */
160
+ defect;
161
+ constructor(options = {}) {
162
+ this.reachability = options.reachability ?? alwaysReachable;
163
+ this.waker = new DrainWaker({ baseMs: options.recheck?.baseMs ?? DefaultRecheckBaseMs, capMs: options.recheck?.maxMs ?? DefaultRecheckMaxMs }, options.recheck?.rand);
164
+ this.submitOptions = options.submit;
165
+ this.refuseSoloCommit = options.allowSoloCommit !== true;
166
+ this.expireAfterMs = options.expireAfterMs;
167
+ this.journal = options.journal;
168
+ this.now = options.now ?? Date.now;
169
+ this.unsubscribeWake = options.wakeOn?.(() => this.wake());
170
+ }
171
+ /**
172
+ * Seal each collection's open segment under a new entry, write the journal's entry record, and
173
+ * queue it — in that order, so an entry is never admitted that the journal does not hold
174
+ * (docs/offline-sync.md §Write ordering, rule 1). `undefined` when no collection had anything
175
+ * staged — nothing to queue, nothing sealed, nothing written (`Collection.sealPending` answers
176
+ * `false` and changes nothing for an empty open segment, so a sibling with nothing staged is
177
+ * simply not part of the entry). Emits `queued` before resolving, so a caller can attribute it to
178
+ * the commit it is in. Starts the drain on the first call.
179
+ *
180
+ * **A journal write that throws fails the enqueue**: every collection sealed is unsealed again, in
181
+ * reverse sealing order (`Collection.unseal`, which puts each segment's actions back into its open
182
+ * segment), nothing is registered, no status is emitted, and the journal's error is rethrown. The
183
+ * caller then rolls its transaction back as for any failed commit. Without a journal the write is
184
+ * skipped and the enqueue cannot fail this way; it is one path either way.
185
+ *
186
+ * Latch-free like `sealPending`: the caller brackets it (no act or commit of these collections is
187
+ * in flight, and no second enqueue of them runs until this one has resolved — the unseal on
188
+ * failure requires each segment to still be the newest sealed one).
189
+ *
190
+ * @throws QueueDisposedError after {@link dispose}; the drain's defect, as `cause`, once the
191
+ * drain has stopped on one (nothing queued then would ever drain); whatever the journal threw. */
192
+ async enqueue(collections, init) {
193
+ this.assertAccepting();
194
+ const id = init?.id ?? mintId();
195
+ if (this.byId.has(id))
196
+ throw new Error(`entry ${id} is already queued`);
197
+ const sealed = collections.filter(collection => collection.sealPending(id));
198
+ if (sealed.length === 0)
199
+ return undefined;
200
+ const queuedAt = init?.timestamp ?? this.now();
201
+ const entry = {
202
+ id,
203
+ seq: this.nextSeq,
204
+ queuedAt,
205
+ expiresAt: this.expireAfterMs === undefined ? undefined : queuedAt + this.expireAfterMs,
206
+ collections: sealed,
207
+ actionId: mintId(),
208
+ attempts: 0,
209
+ inDoubt: false,
210
+ retained: new Map(),
211
+ committed: new Map(),
212
+ applied: new Map(),
213
+ phase: 'queued',
214
+ waitingFor: this.list.length > 0 ? 'earlier-entry' : undefined,
215
+ lastError: undefined,
216
+ lastQueued: undefined,
217
+ expiryDeferredLogged: false,
218
+ };
219
+ // The sequence number is reserved for the write, so a restore that runs meanwhile takes a later
220
+ // one, and handed back when the write is refused and nothing took a later one since, so a
221
+ // refused enqueue leaves no gap in the order the journal lists.
222
+ this.nextSeq = entry.seq + 1;
223
+ try {
224
+ await this.journalQueued(entry);
225
+ }
226
+ catch (err) {
227
+ if (this.nextSeq === entry.seq + 1)
228
+ this.nextSeq = entry.seq;
229
+ throw err;
230
+ }
231
+ this.list.push(entry);
232
+ this.byId.set(id, entry);
233
+ this.emitQueued(entry);
234
+ this.publishState();
235
+ this.startDrain();
236
+ return snapshot(entry);
237
+ }
238
+ /**
239
+ * Put an entry back from a journal's records after a restart (docs/offline-sync.md §Restore after
240
+ * a restart): the only way to register an entry whose segments `enqueue` did not seal. The entry
241
+ * is registered first — inserted by `seq`, so a record restored late sits ahead of entries queued
242
+ * since — and `stage` is then called for each of its collections, in `init.collections` order, to
243
+ * put the segment in place (`Collection.restoreSealed`, at the position the caller finds by
244
+ * reading {@link entries}) or to answer that the collection already holds the entry's recorded
245
+ * attempt as committed (`Collection.holdsCommitted`). What `stage` answers decides what follows:
246
+ *
247
+ * - every collection `already-committed`: the entry is settled `committed` at once, with a
248
+ * durability whose every collection has an `undefined` class (the write is saved; who holds it
249
+ * is unknown), the journal's `settled` written as for any commit, and no `queued` status;
250
+ * - some `already-committed`: those are recorded as committed with `undefined` durability and the
251
+ * entry stays queued in doubt, as after a partial commit, the next submission driving the rest;
252
+ * - a `staged` segment `refused`: the refusal is queued for the loop's first step, which fails the
253
+ * entry through the ordinary cascade (with no `causedBy`);
254
+ * - otherwise it is simply queued. In every case but the first, `queued` is emitted and the drain
255
+ * woken, and the result is the entry as {@link entries} lists it.
256
+ *
257
+ * **The drain is held for the whole call.** The call waits until the loop is parked between
258
+ * iterations — not mid-submission, not mid-removal — holds it there, registers the entry, runs
259
+ * `stage`, and releases. A segment inserted ahead of the current head while that head's commit
260
+ * is on the network would fail the commit's own "head still first" assertion when it retakes the
261
+ * latch, and a `commitHead` that finds another segment ahead of the one it was asked for throws
262
+ * `SealedSegmentsError` (`not-head`), which the loop reads as a defect. A loop that is not
263
+ * running, or is parked on an empty queue, counts as parked at once; several restores serialise.
264
+ * `discard` during a restore is refused for the entry being restored (`UnknownEntryError`: it is
265
+ * registered but not yet admitted) and allowed for others, whose removals run on the removal
266
+ * chain the hold waits out before `stage` runs. A removal chained DURING `stage` runs beside it,
267
+ * serialised per collection by the collection latch only.
268
+ *
269
+ * **Identity.** With `init.drive`: the action id, the attempts to resume and the committed
270
+ * collections are taken from it, and the entry is in doubt when either map is non-empty. Without:
271
+ * a fresh action id, nothing retained, not in doubt.
272
+ *
273
+ * **A `stage` that throws** rolls the registration back: the entry leaves the queue, every segment
274
+ * `stage` already put in place is dropped (`Collection.dropSealed`), nothing is emitted, and the
275
+ * error is rethrown.
276
+ *
277
+ * **`dispose` during a restore.** A restore that has not started `stage` when the queue is
278
+ * disposed rejects with `QueueDisposedError` and releases the hold; one that has finishes its
279
+ * registration (the loop is stopping anyway, and an entry registered after disposal is left
280
+ * sealed for the application exactly like one that was queued before it).
281
+ *
282
+ * @throws QueueDisposedError after {@link dispose}; the drain's defect, as `cause`, once the
283
+ * drain has stopped on one; an `Error` for an id or a `seq` already queued; whatever `stage`
284
+ * threw. */
285
+ restore(init, stage) {
286
+ this.assertAccepting();
287
+ if (this.byId.has(init.id))
288
+ throw new Error(`entry ${init.id} is already queued`);
289
+ const run = this.restores.then(() => this.restoreHeld(init, stage));
290
+ const settled = () => { };
291
+ this.restores = run.then(settled, settled);
292
+ return run;
293
+ }
294
+ /**
295
+ * The collection callback: pass as `CollectionInitOptions.onSealedRefused` of every collection
296
+ * whose entries this queue drains. Runs synchronously under the collection latch, so it calls no
297
+ * latched method (`dropSealed`, `update`, `commitHead`): it records the refusal and wakes the
298
+ * loop, which acts on it (step one of each iteration). A refusal for an entry this queue does not
299
+ * hold — another queue's, or one already removed — is ignored; for the entry being submitted it
300
+ * is noted and left to that submission, whose cycle re-checks the recorded refusal and throws it.
301
+ */
302
+ onSealedRefused = (entryId, error) => {
303
+ const entry = this.byId.get(entryId);
304
+ if (entry === undefined) {
305
+ // NOTE: this also covers an entry `enqueue` has sealed but not yet registered (its journal
306
+ // write is outstanding) whose segment a head commit's replay refused meanwhile. The refusal
307
+ // stays recorded on the segment, and the loop's head check (`recordedRefusal`) fails the entry
308
+ // once it reaches the head — later than a pending refusal would, never lost. If that delay
309
+ // ever matters, re-check `sealedRefusal` for each collection when `enqueue` registers.
310
+ log('offline:refusal-for-unknown-entry entry=%s error=%s', entryId, error.message);
311
+ return;
312
+ }
313
+ // The first refusal reported for an entry is the one it fails with; a second collection's
314
+ // refusal of the same entry adds nothing the application can act on separately.
315
+ if (this.pendingRefusals.has(entryId))
316
+ return;
317
+ this.pendingRefusals.set(entryId, { error, causedBy: this.causeOf(entry) });
318
+ this.wake();
319
+ };
320
+ /**
321
+ * Reserve every sequence number up to and including `seq`: the next {@link enqueue} takes a higher
322
+ * one. For a journal that has read records it cannot put back yet (a table it cannot reach), so a
323
+ * transaction queued meanwhile never takes a journaled record's number — {@link restore} refuses a
324
+ * `seq` another queued entry holds. Never lowers the counter.
325
+ */
326
+ reserveSeqThrough(seq) {
327
+ this.nextSeq = Math.max(this.nextSeq, seq + 1);
328
+ }
329
+ /** The queued entries, in queue order. */
330
+ entries() {
331
+ return this.list.map(entry => snapshot(entry));
332
+ }
333
+ /** The current status of a queued entry, or `undefined` for an id not queued — never queued, or
334
+ * already committed or failed (a settled entry leaves the queue with its terminal status event). */
335
+ status(entryId) {
336
+ const entry = this.byId.get(entryId);
337
+ return entry === undefined ? undefined : currentStatus(entry);
338
+ }
339
+ /**
340
+ * Withdraw a never-sent entry: it fails with reason `discarded` and cascades like any failure
341
+ * (docs/offline-sync.md §Removing an entry). Removed from the queue at once, so the drain cannot
342
+ * pick it up; its segments are dropped on the removal chain and `failed` is emitted when the drops
343
+ * are done.
344
+ *
345
+ * @throws EntryNotDiscardableError for an entry that is in doubt (sent at least once — the
346
+ * application cannot withdraw a change it cannot rule out having saved) or being submitted;
347
+ * UnknownEntryError for an id not queued, or one a {@link restore} has registered but not yet
348
+ * admitted. */
349
+ discard(entryId) {
350
+ const entry = this.byId.get(entryId);
351
+ if (entry === undefined || this.restoring === entry)
352
+ throw new UnknownEntryError(entryId);
353
+ if (this.inFlight?.entry === entry)
354
+ throw new EntryNotDiscardableError(entryId, 'submitting');
355
+ if (entry.inDoubt)
356
+ throw new EntryNotDiscardableError(entryId, 'in-doubt');
357
+ this.claimRemoval(entry);
358
+ this.chainRemoval(entry, 'discarded', new EntryDiscardedError(entryId), undefined)
359
+ .catch(err => this.noteDefect(err));
360
+ this.wake();
361
+ }
362
+ onStatus(listener) {
363
+ this.statusListeners.add(listener);
364
+ return () => { this.statusListeners.delete(listener); };
365
+ }
366
+ onQueueState(listener) {
367
+ this.stateListeners.add(listener);
368
+ return () => { this.stateListeners.delete(listener); };
369
+ }
370
+ queueState() {
371
+ const head = this.list[0];
372
+ const waitingFor = head?.waitingFor;
373
+ return {
374
+ depth: this.list.length,
375
+ oldestQueuedAt: head?.queuedAt,
376
+ draining: this.inFlight !== undefined,
377
+ waitingFor: waitingFor === 'cohort' || waitingFor === 'backoff' ? waitingFor : undefined,
378
+ unclassifiedFailures: this.unclassifiedFailures,
379
+ };
380
+ }
381
+ /** Kick the drain: a new local commit ({@link enqueue} calls it), a connection event, a test. A
382
+ * wake that finds the loop busy is kept for its next wait, and a wake resets the re-check backoff. */
383
+ wake() {
384
+ this.waker.wake();
385
+ }
386
+ /** Resolves when the queue is empty and every removal has finished; rejects with
387
+ * {@link QueueDisposedError} on {@link dispose}, and with the drain's defect once it has stopped
388
+ * on one.
389
+ * NOTE: a {@link restore} in progress is not waited for: on an empty queue it answers at once
390
+ * while the restore is about to register an entry. Fine while restores run at start-up, before
391
+ * anything awaits a drain; if a host ever awaits both, make this wait out the restore chain. */
392
+ whenDrained() {
393
+ if (this.disposed)
394
+ return Promise.reject(new QueueDisposedError());
395
+ if (this.defect !== undefined)
396
+ return Promise.reject(this.defect);
397
+ const idle = this.loop === undefined || (this.waitingForWork && this.pendingRemovals === 0);
398
+ if (this.list.length === 0 && idle)
399
+ return Promise.resolve();
400
+ return new Promise((resolve, reject) => { this.drainedWaiters.push({ resolve, reject }); });
401
+ }
402
+ /**
403
+ * Stop draining. Unsubscribes the wake signal, clears the timer, aborts the submission in flight
404
+ * (its cycle stops after its current network `await`) and resolves once the loop has applied that
405
+ * submission's outcome locally — a committed outcome is still emitted, a failure is recorded on the
406
+ * entry as usual, and no further entry is submitted. Entries left queued stay sealed in their
407
+ * collections (they are the application's; nothing is dropped). `whenDrained` rejects with
408
+ * {@link QueueDisposedError}; a later `enqueue` throws it. Idempotent.
409
+ */
410
+ dispose() {
411
+ this.disposal ??= this.disposeOnce();
412
+ return this.disposal;
413
+ }
414
+ async disposeOnce() {
415
+ this.disposed = true;
416
+ this.unsubscribeWake?.();
417
+ this.inFlight?.controller.abort(new QueueDisposedError());
418
+ this.wake();
419
+ await this.loop;
420
+ await this.settledRemovals();
421
+ const error = new QueueDisposedError();
422
+ for (const waiter of this.drainedWaiters.splice(0))
423
+ waiter.reject(error);
424
+ this.publishState();
425
+ }
426
+ /** The refusal every entry point makes after {@link dispose} and once the drain has stopped on a
427
+ * defect: nothing queued then would ever drain. */
428
+ assertAccepting() {
429
+ if (this.disposed)
430
+ throw new QueueDisposedError();
431
+ if (this.defect !== undefined)
432
+ throw new Error('the offline queue stopped on a defect; see cause', { cause: this.defect });
433
+ }
434
+ /** Start the drain on the first entry; wake it for every later one. */
435
+ startDrain() {
436
+ if (this.loop === undefined) {
437
+ this.loop = this.drain();
438
+ }
439
+ else {
440
+ this.wake();
441
+ }
442
+ }
443
+ // ── the drain ──────────────────────────────────────────────────────────────────────────────
444
+ async drain() {
445
+ try {
446
+ while (!this.disposed) {
447
+ if (this.defect !== undefined)
448
+ throw this.defect;
449
+ await this.parkForHold();
450
+ if (this.disposed)
451
+ break;
452
+ await this.processPendingRefusals();
453
+ if (this.disposed)
454
+ break;
455
+ await this.expireDue();
456
+ if (this.disposed)
457
+ break;
458
+ const head = this.list[0];
459
+ if (head === undefined) {
460
+ this.settleDrained();
461
+ this.publishState();
462
+ this.waitingForWork = true;
463
+ try {
464
+ await this.waker.untilWoken();
465
+ }
466
+ finally {
467
+ this.waitingForWork = false;
468
+ }
469
+ continue;
470
+ }
471
+ const refusal = this.recordedRefusal(head);
472
+ if (refusal !== undefined) {
473
+ // A refresh found it before the drain did: reported at once, nothing sent.
474
+ await this.failAndCascade(head, refusalReason(refusal), refusal, this.pendingRefusals.get(head.id)?.causedBy);
475
+ continue;
476
+ }
477
+ if (!await this.gateOpen(head)) {
478
+ this.setQueued(head, 'cohort');
479
+ await this.waker.untilWokenOrTimer();
480
+ continue;
481
+ }
482
+ // `discard` may have taken the head, or `dispose` may have run, while the gate was asked;
483
+ // a new iteration re-reads the one and ends on the other.
484
+ if (this.disposed || this.list[0] !== head)
485
+ continue;
486
+ const retryLater = await this.submit(head);
487
+ if (retryLater) {
488
+ await this.waker.untilWokenOrTimer();
489
+ }
490
+ }
491
+ }
492
+ catch (err) {
493
+ this.stopOnDefect(err);
494
+ }
495
+ finally {
496
+ // Nothing parks any more: a restore waiting for the loop to park proceeds, since the loop
497
+ // touches no entry from here on.
498
+ this.loopStopped = true;
499
+ this.hold?.signalParked();
500
+ }
501
+ }
502
+ /** Step zero of every iteration: while a {@link restore} holds the drain, say so and wait for its
503
+ * release — between iterations, so no submission and no removal of the loop's is under way. */
504
+ async parkForHold() {
505
+ const hold = this.hold;
506
+ if (hold === undefined)
507
+ return;
508
+ hold.signalParked();
509
+ await hold.held;
510
+ }
511
+ /** Step one of every iteration: fail each entry a replay has refused since the last one, in
512
+ * queue order, each failure through the removal chain and so able to report more. */
513
+ async processPendingRefusals() {
514
+ for (;;) {
515
+ await this.settledRemovals();
516
+ const next = this.nextPendingRefusal();
517
+ if (next === undefined)
518
+ return;
519
+ const { entry, refusal } = next;
520
+ await this.fail(entry, refusalReason(refusal.error), refusal.error, refusal.causedBy);
521
+ }
522
+ }
523
+ /** The pending refusal whose entry is earliest in queue order, dropping any for an entry no
524
+ * longer queued. The submitting entry's is never met here: the loop runs this step only between
525
+ * submissions, and its submission throws the refusal itself. */
526
+ nextPendingRefusal() {
527
+ for (const entryId of [...this.pendingRefusals.keys()]) {
528
+ if (!this.byId.has(entryId))
529
+ this.pendingRefusals.delete(entryId);
530
+ }
531
+ for (const entry of this.list) {
532
+ const refusal = this.pendingRefusals.get(entry.id);
533
+ if (refusal !== undefined)
534
+ return { entry, refusal };
535
+ }
536
+ return undefined;
537
+ }
538
+ /** Step two: expire what has outlived its `expiresAt`, in queue order, head or not. An entry in
539
+ * doubt is kept and logged (`offline:expiry-deferred`): a possibly-landed write is never dropped
540
+ * on a clock; it expires once its doubt resolves without committing. Stops when the queue is
541
+ * disposed mid-step, since disposal leaves every entry as it is.
542
+ * NOTE: checked once per iteration, and a non-empty queue always has a timer or a submission
543
+ * pending, so an expiry is applied at most one re-check delay (`recheck.maxMs`, 60 s by default)
544
+ * late; if an application ever needs it on the minute, arm a timer at the earliest `expiresAt`. */
545
+ async expireDue() {
546
+ const now = this.now();
547
+ for (const entry of [...this.list]) {
548
+ if (this.disposed)
549
+ return;
550
+ if (entry.expiresAt === undefined || entry.expiresAt > now || !this.byId.has(entry.id))
551
+ continue;
552
+ if (entry.inDoubt) {
553
+ if (!entry.expiryDeferredLogged) {
554
+ entry.expiryDeferredLogged = true;
555
+ log('offline:expiry-deferred entry=%s action=%s expiresAt=%d: in doubt, kept until its outcome is known', entry.id, entry.actionId, entry.expiresAt);
556
+ }
557
+ continue;
558
+ }
559
+ await this.failAndCascade(entry, 'expired', new EntryExpiredError(entry.id, entry.queuedAt, entry.expiresAt));
560
+ }
561
+ }
562
+ /** The refusal a collection has recorded for `entry`'s segment, if any has. */
563
+ recordedRefusal(entry) {
564
+ for (const collection of entry.collections) {
565
+ const refusal = collection.sealedRefusal(entry.id);
566
+ if (refusal !== undefined)
567
+ return refusal;
568
+ }
569
+ return undefined;
570
+ }
571
+ /** The collections in which `entry` is still a sealed segment: every collection it wrote, until a
572
+ * partial commit consumes some. */
573
+ remainingCollections(entry) {
574
+ return entry.collections.filter(collection => collection.sealedEntries().includes(entry.id));
575
+ }
576
+ /** The gate, asked with each of the head's remaining collections' header id and known log tail id.
577
+ * A gate that throws is logged and read as closed: the next re-check asks again. */
578
+ async gateOpen(entry) {
579
+ const blockIds = this.remainingCollections(entry).flatMap(gateBlockIds);
580
+ try {
581
+ return await this.reachability.reachable(blockIds);
582
+ }
583
+ catch (err) {
584
+ log('offline:reachability-threw entry=%s error=%s', entry.id, describe(err));
585
+ return false;
586
+ }
587
+ }
588
+ // ── submitting ─────────────────────────────────────────────────────────────────────────────
589
+ /** Submit the head once and apply the outcome. Answers whether the loop should wait out the
590
+ * re-check timer before its next iteration (a transient failure) rather than go straight on (the
591
+ * entry committed or failed). */
592
+ async submit(entry) {
593
+ const remaining = this.remainingCollections(entry);
594
+ if (remaining.length === 0) {
595
+ throw new Error(`offline queue: entry ${entry.id} holds no sealed segment in any collection it wrote`);
596
+ }
597
+ entry.attempts++;
598
+ entry.phase = 'submitting';
599
+ const controller = new AbortController();
600
+ this.inFlight = { entry, controller };
601
+ this.emit({ kind: 'submitting', entryId: entry.id, attempt: entry.attempts });
602
+ this.publishState();
603
+ let outcome;
604
+ try {
605
+ outcome = { durability: await this.send(entry, remaining, controller.signal) };
606
+ }
607
+ catch (error) {
608
+ outcome = { error };
609
+ }
610
+ finally {
611
+ this.inFlight = undefined;
612
+ }
613
+ if ('durability' in outcome) {
614
+ await this.committed(entry, outcome.durability);
615
+ return false;
616
+ }
617
+ return this.applyFailure(entry, outcome.error);
618
+ }
619
+ /** One submission: `commitHead` for an entry over one collection, the coordinator's per-entry
620
+ * slice over several — built on the transactor the remaining collections share, since a queue
621
+ * holds collections of whatever transactor each was opened on — each under the entry's action id
622
+ * and local commit time, resuming from the attempts retained under that id, and — unless the queue
623
+ * allows it — refusing to be committed by a lone node that knows it is not alone. Each committed
624
+ * head segment's tally reaches {@link recordApplied} through the `onCommittedHead` hook. */
625
+ async send(entry, remaining, signal) {
626
+ const submit = { ...this.submitOptions, signal, ...(this.refuseSoloCommit ? { refuseSoloCommit: true } : {}) };
627
+ const recordAttempt = (attempts) => this.recordAttempts(entry, attempts);
628
+ const onCommittedHead = (collectionId, applied) => this.recordApplied(entry, collectionId, applied);
629
+ if (remaining.length === 1) {
630
+ const collection = remaining[0];
631
+ const resume = entry.retained.get(collection.id);
632
+ const written = await collection.commitHead(entry.id, {
633
+ ...submit,
634
+ actionId: entry.actionId,
635
+ timestamp: entry.queuedAt,
636
+ recordAttempt: attempt => recordAttempt(new Map([[collection.id, attempt]])),
637
+ onCommittedHead: applied => onCommittedHead(collection.id, applied),
638
+ ...(resume === undefined ? {} : { resume }),
639
+ });
640
+ return transactionDurability(new Map([[collection.id, written]]));
641
+ }
642
+ const coordinator = new TransactionCoordinator(sharedTransactor(entry, remaining), new Map(remaining.map(collection => [collection.id, collection])), { pendValidation: 'none' });
643
+ const resume = new Map([...entry.retained].filter(([collectionId]) => remaining.some(collection => collection.id === collectionId)));
644
+ return coordinator.commitEntry({
645
+ entryId: entry.id,
646
+ actionId: entry.actionId,
647
+ timestamp: entry.queuedAt,
648
+ collectionIds: remaining.map(collection => collection.id),
649
+ recordAttempt,
650
+ onCommittedHead,
651
+ ...(resume.size === 0 ? {} : { resume }),
652
+ }, submit);
653
+ }
654
+ /** The `onCommittedHead` hook's closure: record what `collectionId`'s head segment accepted as
655
+ * already applied, for the entry's `effect` (`effectOf`). Runs under the collection latch, so it
656
+ * records and nothing else. One segment per collection per entry is dropped as committed exactly
657
+ * once, so this is a set, not a sum. */
658
+ recordApplied(entry, collectionId, applied) {
659
+ entry.applied.set(collectionId, applied);
660
+ }
661
+ /** The queue's write-ahead wrapper: the one moment before a send the queue is told about. The
662
+ * journal's drive record goes first, with the attempts about to go beside the ones already
663
+ * retained (docs/offline-sync.md §Write ordering, rule 2); a throw out of it aborts the cycle with
664
+ * nothing sent (both drivers promise that), so an attempt it refused is neither retained nor a
665
+ * reason for doubt — the entry stays discardable, and `resume` on the next drive names only
666
+ * attempts that may have landed. */
667
+ async recordAttempts(entry, attempts) {
668
+ try {
669
+ await this.journal?.driving(entry.id, driveState(entry, attempts));
670
+ }
671
+ catch (err) {
672
+ log('offline:journal-write-failed entry=%s action=%s step=send error=%s', entry.id, entry.actionId, describe(err));
673
+ throw new RecordAttemptFailed(err);
674
+ }
675
+ // NOTE: in doubt is STICKY — set here, once the first attempt of the entry is about to be sent,
676
+ // and cleared only by a terminal outcome or by `torn-not-saved`. A cycle's own refreshes
677
+ // resolve its earlier attempts (each refresh finds a landed own entry, and an attempt at an
678
+ // unchanged revision finishes an earlier one as the same action), so the last cycle's
679
+ // classification speaks for the cycle; but a coordinator lagging its cohort can still hide a
680
+ // minority-held tail, and the sticky rule is what keeps that from ever discarding a
681
+ // possibly-landed entry. While in doubt the entry is neither discardable nor expirable, and is
682
+ // re-driven only under its action id with its retained attempts as `resume`.
683
+ entry.inDoubt = true;
684
+ for (const [collectionId, attempt] of attempts) {
685
+ entry.retained.set(collectionId, attempt);
686
+ }
687
+ }
688
+ /** Settle `entry` committed, reporting every collection it wrote: `written`, the last submission's
689
+ * answer, beside what earlier partial commits committed. The journal hears the status first
690
+ * (docs/offline-sync.md §Write ordering, rule 3). */
691
+ async committed(entry, written) {
692
+ this.claimRemoval(entry);
693
+ this.pendingRefusals.delete(entry.id);
694
+ entry.retained.clear();
695
+ entry.inDoubt = false;
696
+ const status = {
697
+ kind: 'committed',
698
+ entryId: entry.id,
699
+ durability: entryDurability(entry, written),
700
+ effect: effectOf(entry),
701
+ };
702
+ await this.journalSettled(status);
703
+ this.emit(status);
704
+ this.waker.resetBackoff();
705
+ this.publishState();
706
+ }
707
+ /**
708
+ * Apply a failed submission by its class (docs/offline-sync.md §Classifying an attempt's outcome):
709
+ *
710
+ * | class | transition |
711
+ * |---|---|
712
+ * | the journal's write-ahead threw | `queued`, `backoff` — nothing was sent |
713
+ * | `ActionRefusedError` thrown directly (the head's recorded refusal) | `failed`, `refusalReason` |
714
+ * | `cohort-unreachable` | `queued`, `cohort`; the timer re-checks the gate |
715
+ * | `contention`, `expired`, `in-doubt`, `unknown` | `queued`, `backoff`; `unknown` is also logged and counted |
716
+ * | `guard-refused`, `rejected`, `too-large` | `failed`, with the class's reason |
717
+ * | `torn-not-saved` | `queued`, `backoff`; doubt cleared (unless part of the entry is committed), a fresh action id, retained attempts cleared, the drive record rewritten |
718
+ * | `partial` | `partially-committed`, then `queued`, `backoff`, in doubt, under the same id unless its cause is `torn-not-saved` ({@link partiallyCommitted}) |
719
+ *
720
+ * `SealedSegmentsError` out of a submission means the head alignment invariant broke — a queue
721
+ * defect — and is thrown out of the loop, which stops the drain.
722
+ *
723
+ * **One action id for the entry's whole life, with one exception.** Storage treats a re-send of
724
+ * the same action at the same revision as finishing it and at a new revision as a new write, so
725
+ * re-driving under the same id is always safe and keeps the member-side slot hold the write earned
726
+ * by losing. The exception is `torn-not-saved`: a re-drive under that id would find its own
727
+ * stranded log entry on every refresh, re-send it, and be told again that a rival built past it —
728
+ * a loop. A fresh id lets the next refresh treat the stranded entry as a stranger's and move on,
729
+ * which is exactly the proof `final: true` gives. A refused pend does NOT mint a fresh id here: it
730
+ * proves nothing about the cycle's earlier attempts under the same id.
731
+ *
732
+ * @returns whether the entry stays queued (wait out the timer) rather than having settled. */
733
+ async applyFailure(entry, error) {
734
+ if (error instanceof SealedSegmentsError)
735
+ throw error;
736
+ if (error instanceof RecordAttemptFailed) {
737
+ this.setQueued(entry, 'backoff', error.cause);
738
+ return true;
739
+ }
740
+ if (error instanceof QueueDisposedError && this.disposed) {
741
+ // The queue's own abort of the submission in flight: not a failure of the write, so not
742
+ // its `lastError` either.
743
+ this.setQueued(entry, undefined);
744
+ return true;
745
+ }
746
+ if (error instanceof ActionRefusedError) {
747
+ await this.failAndCascade(entry, refusalReason(error), error, this.pendingRefusals.get(entry.id)?.causedBy);
748
+ return false;
749
+ }
750
+ const outcome = classifyCommitFailure(error);
751
+ switch (outcome.kind) {
752
+ case 'cohort-unreachable': {
753
+ this.setQueued(entry, 'cohort', error);
754
+ return true;
755
+ }
756
+ case 'contention':
757
+ case 'expired':
758
+ case 'in-doubt': {
759
+ this.setQueued(entry, 'backoff', error);
760
+ return true;
761
+ }
762
+ case 'torn-not-saved': {
763
+ // The torn attempt is provably not saved, but a partial commit's half is: an entry with a
764
+ // committed part stays in doubt, so it is never discarded or expired.
765
+ entry.inDoubt = entry.committed.size > 0;
766
+ this.renewIdentity(entry);
767
+ await this.journalDriving(entry, 'renewal');
768
+ this.setQueued(entry, 'backoff', error);
769
+ return true;
770
+ }
771
+ case 'partial': {
772
+ return this.partiallyCommitted(entry, outcome.error);
773
+ }
774
+ case 'unknown': {
775
+ this.unclassifiedFailures++;
776
+ log('offline:unclassified-failure entry=%s action=%s error=%s', entry.id, entry.actionId, describe(error));
777
+ this.setQueued(entry, 'backoff', error);
778
+ return true;
779
+ }
780
+ case 'guard-refused': {
781
+ await this.failAndCascade(entry, outcome.refusal, outcome.error, this.pendingRefusals.get(entry.id)?.causedBy);
782
+ return false;
783
+ }
784
+ case 'rejected': {
785
+ await this.failAndCascade(entry, 'rejected', outcome.error);
786
+ return false;
787
+ }
788
+ case 'too-large': {
789
+ await this.failAndCascade(entry, 'too-large', outcome.error);
790
+ return false;
791
+ }
792
+ }
793
+ }
794
+ /**
795
+ * A submission committed part of the entry (docs/offline-sync.md §Partial commits). The committed
796
+ * collections' segments are already consumed and their attempts resolved, so they are recorded on
797
+ * the entry and leave `retained`; the rest are still sealed and first, their attempts retained, and
798
+ * the next submission drives exactly them, under the same action id (a fresh one when the rest
799
+ * failed `torn-not-saved`). The entry is in doubt from here to its terminal outcome, so it is
800
+ * neither discarded nor expired. The journal's drive record is rewritten once the entry's state is
801
+ * settled — after a renewal too, so one write carries both — and `partially-committed` is emitted
802
+ * in place of the `queued` status this transition would otherwise report.
803
+ *
804
+ * @returns whether the entry stays queued: `false` only when no collection still holds its segment
805
+ * (the failure came after every collection was saved), which settles it committed. */
806
+ async partiallyCommitted(entry, error) {
807
+ for (const [collectionId, durability] of error.durability.collections) {
808
+ recordCollectionDurability(entry.committed, collectionId, durability);
809
+ entry.retained.delete(collectionId);
810
+ }
811
+ entry.inDoubt = true;
812
+ const pending = this.remainingCollections(entry).map(collection => collection.id);
813
+ if (pending.length === 0) {
814
+ await this.committed(entry);
815
+ return false;
816
+ }
817
+ // The coordinator reports any failure after a saved participant as a partial commit, so the
818
+ // rest may have failed `torn-not-saved`; re-driving it under the same id would only meet that
819
+ // stranded entry again.
820
+ if (classifyCommitFailure(error.reason).kind === 'torn-not-saved')
821
+ this.renewIdentity(entry);
822
+ await this.journalDriving(entry, 'partial-commit');
823
+ const committedCollections = [...entry.committed.keys()];
824
+ log('offline:partially-committed entry=%s action=%s committed=%o pending=%o reason=%s', entry.id, entry.actionId, committedCollections, pending, describe(error.reason));
825
+ entry.phase = 'queued';
826
+ entry.waitingFor = 'backoff';
827
+ entry.lastError = error;
828
+ entry.lastQueued = queuedStatus(entry);
829
+ this.emit({
830
+ kind: 'partially-committed',
831
+ entryId: entry.id,
832
+ committedCollections,
833
+ pendingCollections: pending,
834
+ cause: error.reason instanceof Error ? error.reason : error,
835
+ });
836
+ this.publishState();
837
+ return true;
838
+ }
839
+ /** After a `torn-not-saved` outcome: nothing sent under the entry's action id is saved or will
840
+ * land, so the next submission goes under a fresh one with nothing to resume. A partly committed
841
+ * entry's committed half keeps the old id; only the remainder commits under the new one. The
842
+ * caller writes the journal's drive record afterwards ({@link journalDriving}). */
843
+ renewIdentity(entry) {
844
+ entry.actionId = mintId();
845
+ entry.retained.clear();
846
+ }
847
+ // ── the journal ────────────────────────────────────────────────────────────────────────────
848
+ /** Rule 1 of docs/offline-sync.md §Write ordering: the entry record, before the entry is admitted.
849
+ * On a throw every collection sealed is unsealed, in reverse sealing order, and the error
850
+ * rethrown — nothing is queued. */
851
+ async journalQueued(entry) {
852
+ if (this.journal === undefined)
853
+ return;
854
+ try {
855
+ await this.journal.queued(entryRecord(entry));
856
+ }
857
+ catch (err) {
858
+ for (const collection of [...entry.collections].reverse()) {
859
+ collection.unseal(entry.id);
860
+ }
861
+ log('offline:journal-write-failed entry=%s step=queued error=%s: the enqueue fails and nothing is queued', entry.id, describe(err));
862
+ throw err;
863
+ }
864
+ }
865
+ /** The drive record after a partial commit or an identity renewal (rules 2 and 4 of
866
+ * docs/offline-sync.md §Write ordering). A throw is logged and the drain goes on: the entry stays
867
+ * at the head in doubt either way, and the next send's write-ahead repeats the state. The write
868
+ * before a send is {@link recordAttempts}', whose throw aborts the send. */
869
+ async journalDriving(entry, step) {
870
+ try {
871
+ await this.journal?.driving(entry.id, driveState(entry));
872
+ }
873
+ catch (err) {
874
+ log('offline:journal-write-failed entry=%s action=%s step=%s error=%s: the drain goes on; the next send rewrites the record', entry.id, entry.actionId, step, describe(err));
875
+ }
876
+ }
877
+ /** Rule 3 of docs/offline-sync.md §Write ordering: the terminal status, before it is emitted. A
878
+ * throw is logged and swallowed here, never where the outcome was decided: the network has the
879
+ * write, or the segments are gone, and a stale record is what the restore after a restart
880
+ * resolves. */
881
+ async journalSettled(status) {
882
+ try {
883
+ await this.journal?.settled(status);
884
+ }
885
+ catch (err) {
886
+ log('offline:journal-write-failed entry=%s step=settled error=%s: the outcome stands; a restart resolves the stale record', status.entryId, describe(err));
887
+ }
888
+ }
889
+ // ── restoring ──────────────────────────────────────────────────────────────────────────────
890
+ // NOTE: this file is near 1300 lines (`wc -l`). The restore machinery below (the hold, the
891
+ // registration by seq, the staging and its rollback) reads and writes the queue's private state
892
+ // directly, which is why it stays here; if the file grows again, it is the section to extract
893
+ // behind a small interface over `list`, `byId` and the hold.
894
+ /** One {@link restore}, run on the restore chain: take the hold, wait for the loop to park and the
895
+ * removal chain to drain, register, stage, admit, release. */
896
+ async restoreHeld(init, stage) {
897
+ const hold = this.takeHold();
898
+ try {
899
+ await hold.parked;
900
+ await this.settledRemovals();
901
+ this.assertAccepting();
902
+ const entry = this.registerRestored(init);
903
+ this.restoring = entry;
904
+ let outcomes;
905
+ try {
906
+ outcomes = await this.stageRestored(entry, stage);
907
+ }
908
+ finally {
909
+ this.restoring = undefined;
910
+ }
911
+ return await this.admitRestored(entry, outcomes);
912
+ }
913
+ finally {
914
+ this.releaseHold(hold);
915
+ }
916
+ }
917
+ /** Hold the drain: the loop parks at the top of its next iteration. A loop that is not running
918
+ * (never started, or stopped) or is parked on an empty queue is parked already; one waiting out
919
+ * the re-check timer is woken so it reaches the hold without waiting the timer out. */
920
+ takeHold() {
921
+ let release;
922
+ let signalParked;
923
+ const held = new Promise(resolve => { release = resolve; });
924
+ const parked = new Promise(resolve => { signalParked = resolve; });
925
+ const hold = { held, release, parked, signalParked };
926
+ this.hold = hold;
927
+ if (this.loop === undefined || this.loopStopped || this.waitingForWork) {
928
+ signalParked();
929
+ }
930
+ else {
931
+ this.wake();
932
+ }
933
+ return hold;
934
+ }
935
+ /** Release the hold and wake the loop, which goes on from the top of the iteration it parked in. */
936
+ releaseHold(hold) {
937
+ if (this.hold === hold)
938
+ this.hold = undefined;
939
+ hold.release();
940
+ if (this.loop !== undefined)
941
+ this.wake();
942
+ }
943
+ /** Register a restored entry: built from the record and the drive state, inserted by `seq`, with
944
+ * `waitingFor` set by position and `nextSeq` raised past it. */
945
+ registerRestored(init) {
946
+ if (this.byId.has(init.id))
947
+ throw new Error(`entry ${init.id} is already queued`);
948
+ if (this.list.some(queued => queued.seq === init.seq)) {
949
+ throw new Error(`entry ${init.id} cannot be restored at seq ${init.seq}, which another queued entry holds`);
950
+ }
951
+ const drive = init.drive;
952
+ const entry = {
953
+ id: init.id,
954
+ seq: init.seq,
955
+ queuedAt: init.queuedAt,
956
+ expiresAt: init.expiresAt,
957
+ collections: init.collections,
958
+ actionId: drive?.actionId ?? mintId(),
959
+ // The count of submissions is not journaled. A drive record is written only ahead of a send,
960
+ // so one proves at least one submission was made; it is reported as exactly one, the least
961
+ // that is true, rather than invented.
962
+ attempts: drive === undefined ? 0 : 1,
963
+ inDoubt: drive !== undefined && (drive.attempts.size > 0 || drive.committed.size > 0),
964
+ retained: new Map(drive?.attempts),
965
+ committed: new Map(drive?.committed),
966
+ applied: new Map(),
967
+ phase: 'queued',
968
+ waitingFor: undefined,
969
+ lastError: undefined,
970
+ lastQueued: undefined,
971
+ expiryDeferredLogged: false,
972
+ };
973
+ this.insertBySeq(entry);
974
+ this.byId.set(entry.id, entry);
975
+ this.nextSeq = Math.max(this.nextSeq, entry.seq + 1);
976
+ return entry;
977
+ }
978
+ /** Insert `entry` into the list by `seq` and re-derive every entry's "waiting for an earlier
979
+ * entry" flag from its position: the head waits for no earlier entry, every other entry does. */
980
+ insertBySeq(entry) {
981
+ const index = this.list.findIndex(queued => queued.seq > entry.seq);
982
+ this.list.splice(index < 0 ? this.list.length : index, 0, entry);
983
+ this.list.forEach((queued, position) => {
984
+ if (position === 0) {
985
+ if (queued.waitingFor === 'earlier-entry')
986
+ queued.waitingFor = undefined;
987
+ }
988
+ else {
989
+ queued.waitingFor = 'earlier-entry';
990
+ }
991
+ });
992
+ }
993
+ /** Run `stage` for each of the entry's collections, in order; on a throw, roll the registration
994
+ * back — the entry leaves the queue and every segment already staged is dropped — and rethrow. */
995
+ async stageRestored(entry, stage) {
996
+ const outcomes = new Map();
997
+ try {
998
+ for (const collection of entry.collections) {
999
+ outcomes.set(collection.id, await stage(collection));
1000
+ }
1001
+ }
1002
+ catch (err) {
1003
+ await this.unregisterRestored(entry, outcomes);
1004
+ throw err;
1005
+ }
1006
+ return outcomes;
1007
+ }
1008
+ /** The rollback of a restore whose `stage` threw: the entry leaves the queue, and each segment
1009
+ * `stage` put in place is dropped — every one, a drop that throws being logged, since the stage's
1010
+ * own error is the one the caller hears. */
1011
+ async unregisterRestored(entry, outcomes) {
1012
+ this.claimRemoval(entry);
1013
+ this.pendingRefusals.delete(entry.id);
1014
+ for (const collection of entry.collections) {
1015
+ if (outcomes.get(collection.id)?.kind !== 'staged' || !collection.sealedEntries().includes(entry.id))
1016
+ continue;
1017
+ try {
1018
+ await collection.dropSealed(entry.id);
1019
+ }
1020
+ catch (err) {
1021
+ log('offline:restore-rollback-drop-failed entry=%s collection=%s error=%s', entry.id, collection.id, describe(err));
1022
+ }
1023
+ }
1024
+ }
1025
+ /** Admit a registered entry by what `stage` answered (see {@link restore}). */
1026
+ async admitRestored(entry, outcomes) {
1027
+ let staged = 0;
1028
+ for (const [collectionId, outcome] of outcomes) {
1029
+ if (outcome.kind === 'already-committed') {
1030
+ // A class the drive record knew is kept; one it did not is unknown, not fabricated.
1031
+ if (!entry.committed.has(collectionId))
1032
+ entry.committed.set(collectionId, undefined);
1033
+ entry.inDoubt = true;
1034
+ continue;
1035
+ }
1036
+ staged++;
1037
+ if (outcome.refused !== undefined && !this.pendingRefusals.has(entry.id)) {
1038
+ this.pendingRefusals.set(entry.id, { error: outcome.refused, causedBy: undefined });
1039
+ }
1040
+ }
1041
+ if (staged === 0) {
1042
+ log('offline:restored-already-committed entry=%s action=%s collections=%o', entry.id, entry.actionId, [...outcomes.keys()]);
1043
+ // Every collection is in `entry.committed` by now, each with the class the drive record knew
1044
+ // or none; nothing new was written, so nothing is merged over them.
1045
+ await this.committed(entry);
1046
+ return undefined;
1047
+ }
1048
+ this.emitQueued(entry);
1049
+ this.publishState();
1050
+ this.startDrain();
1051
+ return snapshot(entry);
1052
+ }
1053
+ // ── removing ───────────────────────────────────────────────────────────────────────────────
1054
+ /** Fail `entry` and then act on every refusal its removal reported, in queue order, until none is
1055
+ * pending (docs/offline-sync.md §Removing an entry). */
1056
+ async failAndCascade(entry, reason, error, causedBy) {
1057
+ await this.fail(entry, reason, error, causedBy);
1058
+ await this.processPendingRefusals();
1059
+ }
1060
+ /** Fail one entry: removed from the queue at once, its segments dropped on the removal chain.
1061
+ * Nothing happens for an entry a `discard` has already claimed. */
1062
+ async fail(entry, reason, error, causedBy) {
1063
+ if (!this.claimRemoval(entry))
1064
+ return;
1065
+ await this.chainRemoval(entry, reason, error, causedBy);
1066
+ }
1067
+ /** Take `entry` out of the queue (the synchronous half of every removal, a commit's included), so
1068
+ * the drain cannot pick it again. Answers `false` when it was already taken. */
1069
+ claimRemoval(entry) {
1070
+ if (!this.byId.delete(entry.id))
1071
+ return false;
1072
+ const index = this.list.indexOf(entry);
1073
+ if (index >= 0)
1074
+ this.list.splice(index, 1);
1075
+ const head = this.list[0];
1076
+ if (head !== undefined && head.waitingFor === 'earlier-entry')
1077
+ head.waitingFor = undefined;
1078
+ return true;
1079
+ }
1080
+ /** Queue `entry`'s drops behind every removal already chained; the returned promise is that
1081
+ * removal's own, so its throw reaches the caller while the chain itself never rejects. */
1082
+ chainRemoval(entry, reason, error, causedBy) {
1083
+ this.pendingRemovals++;
1084
+ const removal = this.removals.then(() => this.remove(entry, reason, error, causedBy));
1085
+ const settled = () => { this.pendingRemovals--; };
1086
+ this.removals = removal.then(settled, settled);
1087
+ return removal;
1088
+ }
1089
+ /** The asynchronous half of a failure: drop the entry's segment from every collection that still
1090
+ * holds one (a collection the entry had no segment in, or whose segment a partial commit consumed,
1091
+ * is skipped), then emit `failed` naming those collections, and the ones a partial commit
1092
+ * committed whatever triggered the failure — the journal hearing the status first. Each drop
1093
+ * replays and may report refusals of later entries through {@link onSealedRefused}, which
1094
+ * {@link causeOf} attributes while `removing` names this entry. */
1095
+ async remove(entry, reason, error, causedBy) {
1096
+ this.pendingRefusals.delete(entry.id);
1097
+ const changedCollections = [];
1098
+ this.removing = entry;
1099
+ try {
1100
+ for (const collection of entry.collections) {
1101
+ if (!collection.sealedEntries().includes(entry.id))
1102
+ continue;
1103
+ changedCollections.push(collection.id);
1104
+ await collection.dropSealed(entry.id);
1105
+ }
1106
+ }
1107
+ finally {
1108
+ this.removing = undefined;
1109
+ }
1110
+ if (entry.committed.size > 0) {
1111
+ log('offline:partially-committed-entry-failed entry=%s action=%s committed=%o dropped=%o reason=%s: the network holds part of the transaction', entry.id, entry.actionId, [...entry.committed.keys()], changedCollections, reason);
1112
+ }
1113
+ const status = {
1114
+ kind: 'failed',
1115
+ entryId: entry.id,
1116
+ reason,
1117
+ error,
1118
+ changedCollections,
1119
+ ...(causedBy === undefined ? {} : { causedBy }),
1120
+ ...committedField(entry),
1121
+ };
1122
+ await this.journalSettled(status);
1123
+ this.emit(status);
1124
+ this.publishState();
1125
+ }
1126
+ /**
1127
+ * Which earlier entry a refusal of `entry` is attributed to: the nearest one, in queue order, that
1128
+ * is being removed right now or already has a refusal pending; `undefined` when there is none (a
1129
+ * rival's commit refused the entry directly, found by a reader's refresh — or a restore's
1130
+ * insertion did, which removes nothing).
1131
+ *
1132
+ * Nearest rather than the entry being dropped, because one replay refuses every later segment
1133
+ * that no longer applies at once: dropping E1 re-stages E2 (refused) and then E3 over state
1134
+ * without E2, so E3's refusal is reported during E1's drop even though it is E2's image E3 built on.
1135
+ * Naming the nearest failing entry gives the chain E3 ← E2 ← E1 an application can follow, where
1136
+ * the literal "the entry whose drop ran the replay" would flatten it to E3 ← E1, E2 ← E1.
1137
+ */
1138
+ causeOf(entry) {
1139
+ let cause;
1140
+ for (const earlier of this.list) {
1141
+ if (earlier.seq >= entry.seq)
1142
+ break;
1143
+ if (this.pendingRefusals.has(earlier.id))
1144
+ cause = earlier;
1145
+ }
1146
+ const removing = this.removing;
1147
+ if (removing !== undefined && removing.seq < entry.seq && (cause === undefined || removing.seq > cause.seq)) {
1148
+ cause = removing;
1149
+ }
1150
+ return cause?.id;
1151
+ }
1152
+ /** The removal chain, once every removal chained so far — including ones chained while waiting —
1153
+ * has finished. */
1154
+ async settledRemovals() {
1155
+ let chain;
1156
+ do {
1157
+ chain = this.removals;
1158
+ await chain;
1159
+ } while (chain !== this.removals);
1160
+ }
1161
+ // ── stopping ───────────────────────────────────────────────────────────────────────────────
1162
+ settleDrained() {
1163
+ for (const waiter of this.drainedWaiters.splice(0))
1164
+ waiter.resolve();
1165
+ }
1166
+ /** The drain has met a defect: stop it, reject every `whenDrained`, and leave every entry as it
1167
+ * is. Segments stay sealed in their collections, so nothing the application committed is lost.
1168
+ * NOTE: a removal that threw is read as a defect too, though `dropSealed`'s replay reads blocks
1169
+ * through the collection's source and so can throw for a read that could not be served (a cache
1170
+ * miss while the cohort is unreachable). Fine while every replay runs over blocks the staging
1171
+ * read into the cache; if `offline:drain-stopped` is ever seen with such an error, a removal
1172
+ * needs to be retried on the re-check timer rather than stop the drain. */
1173
+ stopOnDefect(error) {
1174
+ this.defect = error;
1175
+ log('offline:drain-stopped error=%s', describe(error));
1176
+ for (const waiter of this.drainedWaiters.splice(0))
1177
+ waiter.reject(error);
1178
+ this.publishState();
1179
+ }
1180
+ /** A removal off the loop's path (a `discard`) threw: the loop meets it on its next iteration. */
1181
+ noteDefect(error) {
1182
+ this.defect ??= error;
1183
+ this.wake();
1184
+ }
1185
+ // ── reporting ──────────────────────────────────────────────────────────────────────────────
1186
+ /** Back to `queued` after a gate check or a failed submission; emitted only when something an
1187
+ * application can see changed since the last `queued` status. */
1188
+ setQueued(entry, waitingFor, lastError) {
1189
+ entry.phase = 'queued';
1190
+ entry.waitingFor = waitingFor;
1191
+ if (lastError !== undefined)
1192
+ entry.lastError = lastError;
1193
+ if (!queuedStatusChanged(entry.lastQueued, queuedStatus(entry)))
1194
+ return;
1195
+ this.emitQueued(entry);
1196
+ this.publishState();
1197
+ }
1198
+ emitQueued(entry) {
1199
+ const status = queuedStatus(entry);
1200
+ entry.lastQueued = status;
1201
+ this.emit(status);
1202
+ }
1203
+ emit(status) {
1204
+ for (const listener of this.statusListeners) {
1205
+ try {
1206
+ listener(status);
1207
+ }
1208
+ catch (err) {
1209
+ log('offline:listener-threw listener=status entry=%s kind=%s error=%s', status.entryId, status.kind, describe(err));
1210
+ }
1211
+ }
1212
+ }
1213
+ /** Publish the queue-wide state when it differs from the last one published. */
1214
+ publishState() {
1215
+ const state = this.queueState();
1216
+ const last = this.lastState;
1217
+ if (last !== undefined
1218
+ && last.depth === state.depth
1219
+ && last.oldestQueuedAt === state.oldestQueuedAt
1220
+ && last.draining === state.draining
1221
+ && last.waitingFor === state.waitingFor
1222
+ && last.unclassifiedFailures === state.unclassifiedFailures) {
1223
+ return;
1224
+ }
1225
+ this.lastState = state;
1226
+ for (const listener of this.stateListeners) {
1227
+ try {
1228
+ listener(state);
1229
+ }
1230
+ catch (err) {
1231
+ log('offline:listener-threw listener=state error=%s', describe(err));
1232
+ }
1233
+ }
1234
+ }
1235
+ }
1236
+ //# sourceMappingURL=queue.js.map