@optimystic/db-core 1.10.1 → 1.12.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 +48 -7
- package/dist/src/cluster/structs.d.ts.map +1 -1
- package/dist/src/cluster/structs.js +33 -13
- package/dist/src/cluster/structs.js.map +1 -1
- package/dist/src/cohort-topic/coldstart.d.ts +8 -4
- package/dist/src/cohort-topic/coldstart.d.ts.map +1 -1
- package/dist/src/cohort-topic/coldstart.js +3 -3
- package/dist/src/cohort-topic/coldstart.js.map +1 -1
- package/dist/src/cohort-topic/member-engine.d.ts +5 -1
- package/dist/src/cohort-topic/member-engine.d.ts.map +1 -1
- package/dist/src/cohort-topic/member-engine.js.map +1 -1
- package/dist/src/cohort-topic/registration/store.d.ts +8 -1
- package/dist/src/cohort-topic/registration/store.d.ts.map +1 -1
- package/dist/src/cohort-topic/registration/store.js +57 -0
- package/dist/src/cohort-topic/registration/store.js.map +1 -1
- package/dist/src/cohort-topic/willingness.d.ts +4 -3
- package/dist/src/cohort-topic/willingness.d.ts.map +1 -1
- package/dist/src/cohort-topic/willingness.js.map +1 -1
- package/dist/src/cohort-topic/wire/primitives.d.ts +5 -0
- package/dist/src/cohort-topic/wire/primitives.d.ts.map +1 -1
- package/dist/src/cohort-topic/wire/primitives.js +5 -0
- package/dist/src/cohort-topic/wire/primitives.js.map +1 -1
- package/dist/src/cohort-topic/wire/validate.d.ts.map +1 -1
- package/dist/src/cohort-topic/wire/validate.js +1 -3
- package/dist/src/cohort-topic/wire/validate.js.map +1 -1
- package/dist/src/collection/action.d.ts +15 -1
- package/dist/src/collection/action.d.ts.map +1 -1
- package/dist/src/collection/action.js.map +1 -1
- package/dist/src/collection/collection.d.ts.map +1 -1
- package/dist/src/collection/collection.js +60 -5
- package/dist/src/collection/collection.js.map +1 -1
- package/dist/src/collection/struct.d.ts +6 -2
- package/dist/src/collection/struct.d.ts.map +1 -1
- package/dist/src/collection/struct.js.map +1 -1
- package/dist/src/index.d.ts +1 -0
- package/dist/src/index.d.ts.map +1 -1
- package/dist/src/index.js +1 -0
- package/dist/src/index.js.map +1 -1
- package/dist/src/matchmaking/arrival-push.d.ts +35 -0
- package/dist/src/matchmaking/arrival-push.d.ts.map +1 -0
- package/dist/src/matchmaking/arrival-push.js +56 -0
- package/dist/src/matchmaking/arrival-push.js.map +1 -0
- package/dist/src/matchmaking/config.d.ts +12 -2
- package/dist/src/matchmaking/config.d.ts.map +1 -1
- package/dist/src/matchmaking/config.js +8 -2
- package/dist/src/matchmaking/config.js.map +1 -1
- package/dist/src/matchmaking/index.d.ts +3 -2
- package/dist/src/matchmaking/index.d.ts.map +1 -1
- package/dist/src/matchmaking/index.js +3 -2
- package/dist/src/matchmaking/index.js.map +1 -1
- package/dist/src/matchmaking/seeker.d.ts +5 -2
- package/dist/src/matchmaking/seeker.d.ts.map +1 -1
- package/dist/src/matchmaking/seeker.js +6 -1
- package/dist/src/matchmaking/seeker.js.map +1 -1
- package/dist/src/matchmaking/wire.d.ts +66 -3
- package/dist/src/matchmaking/wire.d.ts.map +1 -1
- package/dist/src/matchmaking/wire.js +79 -11
- package/dist/src/matchmaking/wire.js.map +1 -1
- package/dist/src/network/i-key-network.d.ts +8 -0
- package/dist/src/network/i-key-network.d.ts.map +1 -1
- package/dist/src/network/index.d.ts +1 -0
- package/dist/src/network/index.d.ts.map +1 -1
- package/dist/src/network/index.js +1 -0
- package/dist/src/network/index.js.map +1 -1
- package/dist/src/network/stale-failure.d.ts +12 -3
- package/dist/src/network/stale-failure.d.ts.map +1 -1
- package/dist/src/network/stale-failure.js +14 -1
- package/dist/src/network/stale-failure.js.map +1 -1
- package/dist/src/network/struct.d.ts +54 -4
- package/dist/src/network/struct.d.ts.map +1 -1
- package/dist/src/network/struct.js.map +1 -1
- package/dist/src/network/transaction-expired-error.d.ts +44 -0
- package/dist/src/network/transaction-expired-error.d.ts.map +1 -0
- package/dist/src/network/transaction-expired-error.js +77 -0
- package/dist/src/network/transaction-expired-error.js.map +1 -0
- package/dist/src/testing/test-transactor.d.ts.map +1 -1
- package/dist/src/testing/test-transactor.js +28 -46
- package/dist/src/testing/test-transactor.js.map +1 -1
- package/dist/src/transaction/coordinator.d.ts +4 -1
- package/dist/src/transaction/coordinator.d.ts.map +1 -1
- package/dist/src/transaction/coordinator.js +31 -5
- package/dist/src/transaction/coordinator.js.map +1 -1
- package/dist/src/transaction/index.d.ts +1 -1
- package/dist/src/transaction/index.d.ts.map +1 -1
- package/dist/src/transaction/index.js +1 -1
- package/dist/src/transaction/index.js.map +1 -1
- package/dist/src/transaction/transaction.d.ts +27 -0
- package/dist/src/transaction/transaction.d.ts.map +1 -1
- package/dist/src/transaction/transaction.js +27 -0
- package/dist/src/transaction/transaction.js.map +1 -1
- package/dist/src/transactor/network-transactor.d.ts.map +1 -1
- package/dist/src/transactor/network-transactor.js +32 -39
- package/dist/src/transactor/network-transactor.js.map +1 -1
- package/dist/src/transactor/transactor-source.d.ts.map +1 -1
- package/dist/src/transactor/transactor-source.js +6 -2
- package/dist/src/transactor/transactor-source.js.map +1 -1
- package/dist/src/utility/format-instant.d.ts +8 -0
- package/dist/src/utility/format-instant.d.ts.map +1 -0
- package/dist/src/utility/format-instant.js +11 -0
- package/dist/src/utility/format-instant.js.map +1 -0
- package/package.json +1 -1
- package/src/cluster/structs.ts +72 -14
- package/src/cohort-topic/coldstart.ts +8 -4
- package/src/cohort-topic/member-engine.ts +5 -1
- package/src/cohort-topic/registration/store.ts +68 -0
- package/src/cohort-topic/willingness.ts +4 -3
- package/src/cohort-topic/wire/primitives.ts +6 -0
- package/src/cohort-topic/wire/validate.ts +1 -3
- package/src/collection/action.ts +15 -1
- package/src/collection/collection.ts +63 -5
- package/src/collection/struct.ts +6 -2
- package/src/index.ts +1 -0
- package/src/matchmaking/arrival-push.ts +66 -0
- package/src/matchmaking/config.ts +17 -2
- package/src/matchmaking/index.ts +3 -2
- package/src/matchmaking/seeker.ts +11 -3
- package/src/matchmaking/wire.ts +134 -10
- package/src/network/i-key-network.ts +9 -0
- package/src/network/index.ts +1 -0
- package/src/network/stale-failure.ts +16 -3
- package/src/network/struct.ts +57 -4
- package/src/network/transaction-expired-error.ts +81 -0
- package/src/testing/test-transactor.ts +28 -40
- package/src/transaction/coordinator.ts +37 -7
- package/src/transaction/index.ts +2 -1
- package/src/transaction/transaction.ts +28 -0
- package/src/transactor/network-transactor.ts +36 -43
- package/src/transactor/transactor-source.ts +6 -2
- package/src/utility/format-instant.ts +10 -0
package/src/matchmaking/wire.ts
CHANGED
|
@@ -11,9 +11,10 @@
|
|
|
11
11
|
* which base64url-encodes them on the wire. They are therefore **not** length-framed here — the
|
|
12
12
|
* cohort-topic `RegisterV1` frame wraps them.
|
|
13
13
|
*
|
|
14
|
-
* 2. **
|
|
15
|
-
*
|
|
16
|
-
*
|
|
14
|
+
* 2. **Standalone RPC messages** — the query protocol ({@link QueryV1} / {@link QueryReplyV1} /
|
|
15
|
+
* {@link AggregateCountV1}) and the arrival push ({@link ArrivalPushV1} / {@link ArrivalPushAckV1})
|
|
16
|
+
* — sent over the matchmaking application protocols. These ride the same length-prefixed UTF-8
|
|
17
|
+
* JSON framing as cohort-topic messages ({@link encodeCohortMessage}).
|
|
17
18
|
*
|
|
18
19
|
* Conventions (matching the cohort-topic wire conventions): all JSON, byte fields base64url (no
|
|
19
20
|
* padding), unix-millisecond timestamps, per-message structural validation on decode. Byte fidelity
|
|
@@ -34,10 +35,13 @@ import {
|
|
|
34
35
|
b64urlField,
|
|
35
36
|
b64urlFixedLen,
|
|
36
37
|
COORD_BYTES,
|
|
38
|
+
CORRELATION_BYTES,
|
|
37
39
|
failWire as fail,
|
|
38
40
|
optBool,
|
|
39
41
|
optFiniteNumber,
|
|
42
|
+
optString,
|
|
40
43
|
reqBool,
|
|
44
|
+
reqEnum,
|
|
41
45
|
reqFiniteNumber,
|
|
42
46
|
reqIntInRange,
|
|
43
47
|
reqString,
|
|
@@ -75,6 +79,15 @@ export interface SeekerAppPayloadV1 {
|
|
|
75
79
|
contactHint: string;
|
|
76
80
|
/** Opt into arrival pushes; default false (poll path). */
|
|
77
81
|
pushOnArrival?: boolean;
|
|
82
|
+
/**
|
|
83
|
+
* The registration id an {@link ArrivalPushV1} is bound to, 16 bytes, base64url. Required when
|
|
84
|
+
* `pushOnArrival` is `true`; accepted and ignored otherwise. Riding in the payload puts it in the
|
|
85
|
+
* cohort's gossip-replicated record, so any member can derive the seeker's push binding after a
|
|
86
|
+
* failover. Deliberately outside {@link seekerSigningPayload} (a forwarded {@link SeekerEntryV1}
|
|
87
|
+
* does not carry it); it is still authenticated, because the cohort admits the payload only inside
|
|
88
|
+
* a peer-key-signed `RegisterV1`, whose signing image covers `appPayload`.
|
|
89
|
+
*/
|
|
90
|
+
correlationId?: string;
|
|
78
91
|
/** base64url. */
|
|
79
92
|
signature: string;
|
|
80
93
|
}
|
|
@@ -181,6 +194,44 @@ export interface AggregateBucketV1 {
|
|
|
181
194
|
count: number;
|
|
182
195
|
}
|
|
183
196
|
|
|
197
|
+
// --- Arrival push (cohort member → push-opted seeker) ---
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* A cohort member's notification to a push-opted seeker that fresh matchable providers arrived
|
|
201
|
+
* (`docs/matchmaking.md` §Arrival push on provider arrival). Advisory, with the same trust model as
|
|
202
|
+
* {@link QueryReplyV1}: `signature` is the pushing member's single peer-key signature over
|
|
203
|
+
* {@link arrivalPushSigningPayload}, and the seeker re-validates every entry's `registrationSig`
|
|
204
|
+
* ({@link verifyProviderEntry}) before dialing.
|
|
205
|
+
*/
|
|
206
|
+
export interface ArrivalPushV1 {
|
|
207
|
+
v: 1;
|
|
208
|
+
/** Topic id, 32 bytes, base64url. */
|
|
209
|
+
topicId: string;
|
|
210
|
+
/** Cohort epoch the push was computed under, 32 bytes, base64url. */
|
|
211
|
+
cohortEpoch: string;
|
|
212
|
+
/** The seeker registration this push is bound to ({@link SeekerAppPayloadV1.correlationId}), 16 bytes, base64url. */
|
|
213
|
+
correlationId: string;
|
|
214
|
+
/** The fresh, filter-matched, coalesced batch: `1..QUERY_LIMIT_MAX` entries. */
|
|
215
|
+
providers: ProviderEntryV1[];
|
|
216
|
+
/** Current traffic snapshot, so the seeker can re-run its hang-out math without a poll. */
|
|
217
|
+
topicTraffic: TopicTrafficV1;
|
|
218
|
+
/** The pushing member's single peer-key signature (NOT threshold), base64url. */
|
|
219
|
+
signature: string;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/** The outcomes a seeker may report for an {@link ArrivalPushV1}. */
|
|
223
|
+
export const ARRIVAL_PUSH_RESULTS = ["ok", "unknown_seeker"] as const;
|
|
224
|
+
export type ArrivalPushResult = typeof ARRIVAL_PUSH_RESULTS[number];
|
|
225
|
+
|
|
226
|
+
/**
|
|
227
|
+
* A seeker's reply to an {@link ArrivalPushV1}. `unknown_seeker` says the push's `correlationId` is not
|
|
228
|
+
* the seeker's current registration (it re-registered, or finished), so the pusher drops the binding.
|
|
229
|
+
*/
|
|
230
|
+
export interface ArrivalPushAckV1 {
|
|
231
|
+
v: 1;
|
|
232
|
+
result: ArrivalPushResult;
|
|
233
|
+
}
|
|
234
|
+
|
|
184
235
|
// --- matchmaking-local wire state (generic validation primitives live in cohort-topic/wire/primitives.js) ---
|
|
185
236
|
|
|
186
237
|
const utf8Encoder = new TextEncoder();
|
|
@@ -248,6 +299,13 @@ export function validateSeekerAppPayloadV1(value: unknown): SeekerAppPayloadV1 {
|
|
|
248
299
|
if (pushOnArrival !== undefined) {
|
|
249
300
|
out.pushOnArrival = pushOnArrival;
|
|
250
301
|
}
|
|
302
|
+
const correlationId = optString(obj, "correlationId", what);
|
|
303
|
+
if (correlationId !== undefined) {
|
|
304
|
+
out.correlationId = b64urlFixedLen(correlationId, "correlationId", CORRELATION_BYTES, what);
|
|
305
|
+
}
|
|
306
|
+
if (out.pushOnArrival === true && out.correlationId === undefined) {
|
|
307
|
+
fail(`${what}: field "correlationId" is required when "pushOnArrival" is true`);
|
|
308
|
+
}
|
|
251
309
|
return out;
|
|
252
310
|
}
|
|
253
311
|
|
|
@@ -433,6 +491,34 @@ export function validateAggregateCountV1(value: unknown): AggregateCountV1 {
|
|
|
433
491
|
};
|
|
434
492
|
}
|
|
435
493
|
|
|
494
|
+
/** Narrow an already-parsed value to {@link ArrivalPushV1}, throwing on any defect. */
|
|
495
|
+
export function validateArrivalPushV1(value: unknown): ArrivalPushV1 {
|
|
496
|
+
const what = "ArrivalPushV1";
|
|
497
|
+
const obj = asObject(value, what);
|
|
498
|
+
requireV1(obj, what);
|
|
499
|
+
const providers = obj["providers"];
|
|
500
|
+
if (!Array.isArray(providers) || providers.length < 1 || providers.length > QUERY_LIMIT_MAX) {
|
|
501
|
+
fail(`${what}: field "providers" must be an array of 1..${QUERY_LIMIT_MAX} entries`);
|
|
502
|
+
}
|
|
503
|
+
return {
|
|
504
|
+
v: 1,
|
|
505
|
+
topicId: b64urlFixedLen(reqString(obj, "topicId", what), "topicId", COORD_BYTES, what),
|
|
506
|
+
cohortEpoch: b64urlFixedLen(reqString(obj, "cohortEpoch", what), "cohortEpoch", COORD_BYTES, what),
|
|
507
|
+
correlationId: b64urlFixedLen(reqString(obj, "correlationId", what), "correlationId", CORRELATION_BYTES, what),
|
|
508
|
+
providers: providers.map(validateProviderEntryV1),
|
|
509
|
+
topicTraffic: validateTopicTrafficV1(obj["topicTraffic"], `${what}.topicTraffic`),
|
|
510
|
+
signature: b64urlField(reqString(obj, "signature", what), "signature", what),
|
|
511
|
+
};
|
|
512
|
+
}
|
|
513
|
+
|
|
514
|
+
/** Narrow an already-parsed value to {@link ArrivalPushAckV1}, throwing on any defect. */
|
|
515
|
+
export function validateArrivalPushAckV1(value: unknown): ArrivalPushAckV1 {
|
|
516
|
+
const what = "ArrivalPushAckV1";
|
|
517
|
+
const obj = asObject(value, what);
|
|
518
|
+
requireV1(obj, what);
|
|
519
|
+
return { v: 1, result: reqEnum(obj, "result", ARRIVAL_PUSH_RESULTS, what) };
|
|
520
|
+
}
|
|
521
|
+
|
|
436
522
|
/** Encode a {@link QueryV1} as a length-prefixed UTF-8 JSON frame. */
|
|
437
523
|
export function encodeQueryV1(msg: QueryV1, maxMessageBytes: number = DEFAULT_MAX_MESSAGE_BYTES): Uint8Array {
|
|
438
524
|
return encodeCohortMessage(validateQueryV1(msg), maxMessageBytes);
|
|
@@ -463,6 +549,26 @@ export function decodeAggregateCountV1(bytes: Uint8Array, maxMessageBytes?: numb
|
|
|
463
549
|
return validateAggregateCountV1(decodeCohortMessage(bytes, maxMessageBytes));
|
|
464
550
|
}
|
|
465
551
|
|
|
552
|
+
/** Encode an {@link ArrivalPushV1} as a length-prefixed UTF-8 JSON frame. */
|
|
553
|
+
export function encodeArrivalPushV1(msg: ArrivalPushV1, maxMessageBytes: number = DEFAULT_MAX_MESSAGE_BYTES): Uint8Array {
|
|
554
|
+
return encodeCohortMessage(validateArrivalPushV1(msg), maxMessageBytes);
|
|
555
|
+
}
|
|
556
|
+
|
|
557
|
+
/** Decode a length-prefixed {@link ArrivalPushV1} frame. */
|
|
558
|
+
export function decodeArrivalPushV1(bytes: Uint8Array, maxMessageBytes?: number): ArrivalPushV1 {
|
|
559
|
+
return validateArrivalPushV1(decodeCohortMessage(bytes, maxMessageBytes));
|
|
560
|
+
}
|
|
561
|
+
|
|
562
|
+
/** Encode an {@link ArrivalPushAckV1} as a length-prefixed UTF-8 JSON frame. */
|
|
563
|
+
export function encodeArrivalPushAckV1(msg: ArrivalPushAckV1, maxMessageBytes: number = DEFAULT_MAX_MESSAGE_BYTES): Uint8Array {
|
|
564
|
+
return encodeCohortMessage(validateArrivalPushAckV1(msg), maxMessageBytes);
|
|
565
|
+
}
|
|
566
|
+
|
|
567
|
+
/** Decode a length-prefixed {@link ArrivalPushAckV1} frame. */
|
|
568
|
+
export function decodeArrivalPushAckV1(bytes: Uint8Array, maxMessageBytes?: number): ArrivalPushAckV1 {
|
|
569
|
+
return validateArrivalPushAckV1(decodeCohortMessage(bytes, maxMessageBytes));
|
|
570
|
+
}
|
|
571
|
+
|
|
466
572
|
// --- canonical participant-signature payloads (provider/seeker registration sigs) ---
|
|
467
573
|
|
|
468
574
|
/**
|
|
@@ -558,18 +664,36 @@ export function queryReplySigningPayload(reply: Omit<QueryReplyV1, "signature">)
|
|
|
558
664
|
reply.v,
|
|
559
665
|
reply.cohortEpoch,
|
|
560
666
|
reply.truncated,
|
|
561
|
-
|
|
562
|
-
reply.topicTraffic.windowSeconds,
|
|
563
|
-
reply.topicTraffic.arrivalsPerMin,
|
|
564
|
-
reply.topicTraffic.queriesPerMin,
|
|
565
|
-
reply.topicTraffic.directParticipants,
|
|
566
|
-
reply.topicTraffic.childCohortCount,
|
|
567
|
-
],
|
|
667
|
+
topicTrafficImage(reply.topicTraffic),
|
|
568
668
|
(reply.providers ?? []).map((p) => p.participantId),
|
|
569
669
|
(reply.seekers ?? []).map((s) => s.participantId),
|
|
570
670
|
]));
|
|
571
671
|
}
|
|
572
672
|
|
|
673
|
+
/**
|
|
674
|
+
* Canonical signed byte image of an {@link ArrivalPushV1} — the pushing member's single-member
|
|
675
|
+
* signature, mirroring {@link queryReplySigningPayload}. It binds the topic, epoch, the seeker
|
|
676
|
+
* registration the push is addressed to, the traffic snapshot, and the providers' participant ids
|
|
677
|
+
* (order-sensitive); the per-entry signatures stay outside it, since the seeker re-validates each entry
|
|
678
|
+
* on its own ({@link verifyProviderEntry}).
|
|
679
|
+
*/
|
|
680
|
+
export function arrivalPushSigningPayload(unsigned: Omit<ArrivalPushV1, "signature">): Uint8Array {
|
|
681
|
+
return utf8Encoder.encode(JSON.stringify([
|
|
682
|
+
"ArrivalPushV1",
|
|
683
|
+
unsigned.v,
|
|
684
|
+
unsigned.topicId,
|
|
685
|
+
unsigned.cohortEpoch,
|
|
686
|
+
unsigned.correlationId,
|
|
687
|
+
topicTrafficImage(unsigned.topicTraffic),
|
|
688
|
+
unsigned.providers.map((p) => p.participantId),
|
|
689
|
+
]));
|
|
690
|
+
}
|
|
691
|
+
|
|
692
|
+
/** The traffic snapshot as an explicitly ordered array, shared by the single-member signing images. */
|
|
693
|
+
function topicTrafficImage(t: TopicTrafficV1): number[] {
|
|
694
|
+
return [t.windowSeconds, t.arrivalsPerMin, t.queriesPerMin, t.directParticipants, t.childCohortCount];
|
|
695
|
+
}
|
|
696
|
+
|
|
573
697
|
// --- aggregate-count log-bucketing + canonical threshold-signing image (multi-cohort sweep) ---
|
|
574
698
|
|
|
575
699
|
/**
|
|
@@ -62,4 +62,13 @@ export type IKeyNetwork = {
|
|
|
62
62
|
* @param ttlMs Optional time-to-live for the cached hint, in ms
|
|
63
63
|
*/
|
|
64
64
|
recordCoordinator?(key: RoutingKey, peerId: PeerId, ttlMs?: number): void;
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Optionally report that this node was configured with peers to join through and has not yet
|
|
68
|
+
* heard from all of them. While true, a `findCluster` answer naming nobody but this node is
|
|
69
|
+
* what the node would see whether or not those peers hold a block, so a repo must not treat
|
|
70
|
+
* its own lack of the block as proof the block was never created. Implementations with no
|
|
71
|
+
* such configuration omit this, which reads as "not awaiting".
|
|
72
|
+
*/
|
|
73
|
+
awaitingBootstrapContact?(): Promise<boolean>;
|
|
65
74
|
}
|
package/src/network/index.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { ActionId, ActionRev } from "../collection/action.js";
|
|
2
|
-
import type { StaleFailure } from "./struct.js";
|
|
2
|
+
import type { ExpiredFailure, StaleFailure, WriteFailure } from "./struct.js";
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
5
|
* The single rule for "is this non-success retryable after a re-read?" Both write paths and the
|
|
@@ -7,12 +7,25 @@ import type { StaleFailure } from "./struct.js";
|
|
|
7
7
|
*
|
|
8
8
|
* {@link StaleFailure.conflict} is authoritative when present. The `missing`/`pending` fallback
|
|
9
9
|
* covers producers that have not been taught the field, including a remote peer on an older build
|
|
10
|
-
* (the repo protocol is plain JSON, so an unset field simply arrives absent).
|
|
10
|
+
* (the repo protocol is plain JSON, so an unset field simply arrives absent). An expiry is never a
|
|
11
|
+
* conflict ({@link isExpiryFailure}), whatever else arrived beside it.
|
|
11
12
|
*/
|
|
12
|
-
export function isConflictFailure(failure:
|
|
13
|
+
export function isConflictFailure(failure: WriteFailure): boolean {
|
|
14
|
+
if (isExpiryFailure(failure)) return false;
|
|
13
15
|
return failure.conflict ?? Boolean(failure.missing?.length || failure.pending?.length);
|
|
14
16
|
}
|
|
15
17
|
|
|
18
|
+
/**
|
|
19
|
+
* The single rule for "did the cohort refuse this write because the transaction had already expired
|
|
20
|
+
* by the members' clocks?" ({@link ExpiredFailure}). Every write path stops on it rather than
|
|
21
|
+
* retrying, since a retry's expiration comes from the same clock. Decided by the structured field,
|
|
22
|
+
* never the reason text; a peer on a build that predates the field never sends it, and its refusal
|
|
23
|
+
* reads as the shape it always had.
|
|
24
|
+
*/
|
|
25
|
+
export function isExpiryFailure(failure: WriteFailure): failure is ExpiredFailure {
|
|
26
|
+
return failure.expired !== undefined;
|
|
27
|
+
}
|
|
28
|
+
|
|
16
29
|
/**
|
|
17
30
|
* The single rule for picking one {@link StaleFailure.staleAt} out of several candidates.
|
|
18
31
|
*
|
package/src/network/struct.ts
CHANGED
|
@@ -184,9 +184,50 @@ export type StaleFailure = {
|
|
|
184
184
|
* the presence of this field.
|
|
185
185
|
*/
|
|
186
186
|
staleAt?: { blockId: BlockId; rev: number };
|
|
187
|
+
/** Never set on a lost race — an expiry is its own failure shape, {@link ExpiredFailure}. */
|
|
188
|
+
expired?: never;
|
|
187
189
|
};
|
|
188
190
|
|
|
189
|
-
|
|
191
|
+
/**
|
|
192
|
+
* Why a cohort refused a write as expired: by each refusing member's own clock, the transaction's
|
|
193
|
+
* `expiration` had already passed when the record reached it. Plain data, so it crosses the JSON repo
|
|
194
|
+
* protocol intact. `TransactionExpiredError` is built from it, wherever it is raised.
|
|
195
|
+
*/
|
|
196
|
+
export type TransactionExpiry = {
|
|
197
|
+
/** The transaction's expiration (unix ms), as the writer's transactor set it from its own clock. */
|
|
198
|
+
expiration: number;
|
|
199
|
+
/** Per refusing cohort member (peer-id string), the clock reading (unix ms) it signed when it
|
|
200
|
+
* judged the record expired (`Signature.expiredAt`). Never empty. */
|
|
201
|
+
memberClocks: Record<string, number>;
|
|
202
|
+
/** The coordinating node's clock (unix ms) when it concluded the refusal. */
|
|
203
|
+
coordinatorClock: number;
|
|
204
|
+
};
|
|
205
|
+
|
|
206
|
+
/**
|
|
207
|
+
* The cohort refused the write because the transaction had already EXPIRED by the members' clocks —
|
|
208
|
+
* a clock disagreement between the writer and the cohort, not a lost race and not a judgement of the
|
|
209
|
+
* write. Never retryable: every retry carries an expiration set by the same clock, and is refused the
|
|
210
|
+
* same way until a clock is corrected. A sibling of {@link StaleFailure} rather than a field on it,
|
|
211
|
+
* because "lost to a newer revision" is exactly what this is not; the fields it can never carry are
|
|
212
|
+
* typed `never`, so a consumer reads `reason`, `missing` or `staleAt` off either shape unnarrowed.
|
|
213
|
+
* Tell the two apart with `isExpiryFailure`, never by reading `reason`.
|
|
214
|
+
*/
|
|
215
|
+
export type ExpiredFailure = {
|
|
216
|
+
success: false;
|
|
217
|
+
/** The coordinator's description of the refusal, for a log line. Never branch on it. */
|
|
218
|
+
reason?: string;
|
|
219
|
+
/** Always false: an expiry is never a conflict a re-read can win. */
|
|
220
|
+
conflict: false;
|
|
221
|
+
expired: TransactionExpiry;
|
|
222
|
+
missing?: never;
|
|
223
|
+
pending?: never;
|
|
224
|
+
staleAt?: never;
|
|
225
|
+
};
|
|
226
|
+
|
|
227
|
+
/** Every way a pend or a commit can be refused with an answer rather than a throw. */
|
|
228
|
+
export type WriteFailure = StaleFailure | ExpiredFailure;
|
|
229
|
+
|
|
230
|
+
export type PendResult = PendSuccess | WriteFailure;
|
|
190
231
|
|
|
191
232
|
/** What one block will materialize to at the committing revision, declared by the client that
|
|
192
233
|
* authored the transforms. */
|
|
@@ -265,7 +306,7 @@ export type InvalidateRequest = {
|
|
|
265
306
|
resolution: DisputeResolutionProof;
|
|
266
307
|
};
|
|
267
308
|
|
|
268
|
-
export type CommitResult = CommitSuccess |
|
|
309
|
+
export type CommitResult = CommitSuccess | WriteFailure;
|
|
269
310
|
|
|
270
311
|
export type CommitSuccess = {
|
|
271
312
|
success: true;
|
|
@@ -387,13 +428,25 @@ export type BlockUnavailableReason =
|
|
|
387
428
|
/** Nothing is held locally and NO cohort member outside the answering node could be
|
|
388
429
|
* asked at all. Distinct from `peers-unreachable` in exactly the way that matters to
|
|
389
430
|
* a caller: there is no better-connected coordinator to re-ask, so the answer will
|
|
390
|
-
* not improve until that node's connectivity does. Its local view is all there is.
|
|
431
|
+
* not improve until that node's connectivity does. Its local view is all there is.
|
|
432
|
+
* Also the answer of a node whose cohort view holds only itself while a peer it was
|
|
433
|
+
* configured to join through has never been heard from
|
|
434
|
+
* (`IKeyNetwork.awaitingBootstrapContact`): it knows of a machine outside itself and
|
|
435
|
+
* has not reached it. */
|
|
391
436
|
| 'cohort-unreachable'
|
|
392
437
|
/** Nothing is held locally, but a cohort peer positively CLAIMED a revision of this
|
|
393
438
|
* block, and the answering node could neither corroborate that claim to a quorum nor
|
|
394
439
|
* acquire the content. The block is known to exist somewhere; reporting it absent
|
|
395
440
|
* would be a lie regardless of whether anyone was silent. */
|
|
396
|
-
| 'claimed-elsewhere'
|
|
441
|
+
| 'claimed-elsewhere'
|
|
442
|
+
/** Nothing is held locally and the answering node had nobody to ask (its cohort view
|
|
443
|
+
* was empty, or only itself), but the read carried a floor for the block
|
|
444
|
+
* ({@link BlockGets.floors}): the asker walked a log entry committing a revision of it.
|
|
445
|
+
* The block is known to exist, from the asker's own evidence, so "never created" would
|
|
446
|
+
* contradict what the asker already knows. Unlike `cohort-unreachable` this is never
|
|
447
|
+
* "the local view is all there is": another machine may hold the block, and asking one
|
|
448
|
+
* is the remedy. */
|
|
449
|
+
| 'named-by-log';
|
|
397
450
|
|
|
398
451
|
export type GetBlockResult = {
|
|
399
452
|
/** The retrieved block - undefined if the block was deleted */
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
import type { ExpiredFailure, TransactionExpiry } from "./struct.js";
|
|
2
|
+
import { formatInstant } from "../utility/format-instant.js";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* A write the cohort refused because, by the refusing members' own clocks, the transaction had
|
|
6
|
+
* already expired when it reached them. Nobody judged the write and nobody was unreachable: the clock
|
|
7
|
+
* that set the expiration (the writer's) and the members' clocks disagree by more than the
|
|
8
|
+
* transaction timeout (30 s by default). Not retryable — a retry's expiration comes from the same
|
|
9
|
+
* clock, so it is refused the same way until one of the clocks is corrected. Nothing was saved.
|
|
10
|
+
*
|
|
11
|
+
* ONE class for every place it is raised, so the coordinator's report and the writer's cannot drift.
|
|
12
|
+
* The cluster coordinator (db-p2p `ClusterCoordinator`) raises it when every reject vote that sank a
|
|
13
|
+
* transaction was an expiry vote; the coordinating repo returns its facts as an
|
|
14
|
+
* {@link ExpiredFailure} ({@link toFailure}), which is what lets a remote writer receive them at all;
|
|
15
|
+
* and each write path (`Collection.sync`, `TransactionCoordinator.commit`) raises it again from that
|
|
16
|
+
* refusal, with its own clock as {@link localClock}. Deliberately not a db-p2p
|
|
17
|
+
* `ValidatorRejectionError`, which means "the cohort judged the write": the coordinating repo turns
|
|
18
|
+
* this one into its refusal before its validator-rejection classifiers run.
|
|
19
|
+
*/
|
|
20
|
+
export class TransactionExpiredError extends Error {
|
|
21
|
+
/** The transaction's expiration (unix ms), as the writer's transactor set it. */
|
|
22
|
+
readonly expiration: number;
|
|
23
|
+
/** Per refusing cohort member (peer-id string), the clock reading (unix ms) it signed. */
|
|
24
|
+
readonly memberClocks: Readonly<Record<string, number>>;
|
|
25
|
+
/** The coordinating node's clock (unix ms) when it concluded the refusal. */
|
|
26
|
+
readonly coordinatorClock: number;
|
|
27
|
+
/**
|
|
28
|
+
* How far ahead of {@link localClock} the most-skewed refusing member's clock appeared: the largest
|
|
29
|
+
* `memberClocks[peer] − localClock`. An estimate, low by the time the answer took to travel back
|
|
30
|
+
* (a member read its clock before then). Raised by a write path, this is how far the cohort's
|
|
31
|
+
* clocks appear to be from the writer's own — the number to act on whichever side is wrong. Zero or
|
|
32
|
+
* less means this node's clock has the expiration past as well.
|
|
33
|
+
*/
|
|
34
|
+
readonly apparentSkewMs: number;
|
|
35
|
+
|
|
36
|
+
constructor(
|
|
37
|
+
expiry: TransactionExpiry,
|
|
38
|
+
/** This node's clock (unix ms) when it raised the error: the coordinator's where the cluster
|
|
39
|
+
* raised it, the writer's where a write path raised it from a returned refusal. */
|
|
40
|
+
readonly localClock: number = Date.now(),
|
|
41
|
+
) {
|
|
42
|
+
// NOTE: `expiry` off the wire is trusted as shaped (`isExpiryFailure` checks only presence), so a
|
|
43
|
+
// malformed coordinator answer gives NaN here, or a TypeError when `memberClocks` is missing,
|
|
44
|
+
// instead of this error. Either still ends the write; if hostile coordinators become a concern,
|
|
45
|
+
// validate the shape where the refusal is received.
|
|
46
|
+
const apparentSkewMs = Math.max(...Object.values(expiry.memberClocks)) - localClock;
|
|
47
|
+
super(transactionExpiredMessage(expiry, localClock, apparentSkewMs));
|
|
48
|
+
this.name = 'TransactionExpiredError';
|
|
49
|
+
this.expiration = expiry.expiration;
|
|
50
|
+
this.memberClocks = { ...expiry.memberClocks };
|
|
51
|
+
this.coordinatorClock = expiry.coordinatorClock;
|
|
52
|
+
this.apparentSkewMs = apparentSkewMs;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** The refusal a coordinating repo returns for this error, so it crosses the repo protocol as an
|
|
56
|
+
* answer rather than as a reset stream. */
|
|
57
|
+
toFailure(): ExpiredFailure {
|
|
58
|
+
return {
|
|
59
|
+
success: false,
|
|
60
|
+
conflict: false,
|
|
61
|
+
reason: this.message,
|
|
62
|
+
expired: { expiration: this.expiration, memberClocks: { ...this.memberClocks }, coordinatorClock: this.coordinatorClock },
|
|
63
|
+
};
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Written to be shown to a person. Deliberately free of the shortfall error's text ("Failed to get
|
|
69
|
+
* super-majority"), which a downstream repository matches to retry a silent cohort: a clock
|
|
70
|
+
* disagreement is neither silence nor transient.
|
|
71
|
+
*/
|
|
72
|
+
function transactionExpiredMessage(expiry: TransactionExpiry, localClock: number, apparentSkewMs: number): string {
|
|
73
|
+
const seconds = (ms: number) => (ms / 1000).toFixed(1);
|
|
74
|
+
const refusing = Object.keys(expiry.memberClocks).length;
|
|
75
|
+
const gap = apparentSkewMs > 0
|
|
76
|
+
? `Their clocks appear to be about ${seconds(apparentSkewMs)} s ahead of this device's.`
|
|
77
|
+
: `This device's clock has it ${seconds(localClock - expiry.expiration)} s past as well, so the clock that set the expiration may be behind, or the transaction outlived its deadline.`;
|
|
78
|
+
return `The transaction expired before the cohort could accept it: by their own clocks, ${refusing} cohort member(s) found its expiration (${formatInstant(expiry.expiration)}) already past. `
|
|
79
|
+
+ `${gap} This is a clock disagreement, not a conflict or an unreachable cohort, and retrying fails the same way until it is resolved: `
|
|
80
|
+
+ `correct the clock of whichever device is wrong — this one, or the refusing members.`;
|
|
81
|
+
}
|
|
@@ -73,27 +73,22 @@ export class TestTransactor implements ITransactor {
|
|
|
73
73
|
// revision-pinned read of a block committed further since the pin makes them differ,
|
|
74
74
|
// and there the pinned value is what the reader observed (see the field's doc).
|
|
75
75
|
let materializedRev: number | undefined;
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
}
|
|
92
|
-
} else if (blockGets.context?.committed) {
|
|
93
|
-
// Check context.committed for matching pending actions — mirrors coordinator
|
|
94
|
-
// behavior: context.committed proves the action succeeded, so pending blocks
|
|
95
|
-
// for that action should be served.
|
|
96
|
-
for (const { actionId: cId } of blockGets.context.committed) {
|
|
76
|
+
// A named pending is overlaid only where this block holds it; every other block gets the
|
|
77
|
+
// plain answer for the same context (mirrors StorageRepo.get).
|
|
78
|
+
const pin = blockGets.context?.rev;
|
|
79
|
+
const namedPending = blockGets.context?.actionId !== undefined
|
|
80
|
+
? blockState.pendingActions.get(blockGets.context.actionId) : undefined;
|
|
81
|
+
if (namedPending) {
|
|
82
|
+
// Overlay over the committed base at the context's pin, as StorageRepo does.
|
|
83
|
+
const base = committedAt(blockState, pin);
|
|
84
|
+
block = applyTransformSafe(base?.block, namedPending);
|
|
85
|
+
// A pending carries no revision of its own — report the committed base it was
|
|
86
|
+
// applied over. Absent when there was no base (a pending-only insert).
|
|
87
|
+
materializedRev = base?.rev;
|
|
88
|
+
} else {
|
|
89
|
+
// context.committed proves its actions succeeded, so a block still holding one of them
|
|
90
|
+
// pending is served with it applied — mirrors the coordinator's read-driven promotion.
|
|
91
|
+
for (const { actionId: cId } of blockGets.context?.committed ?? []) {
|
|
97
92
|
const pendingTransform = blockState.pendingActions.get(cId);
|
|
98
93
|
if (pendingTransform) {
|
|
99
94
|
const baseBlock = blockState.materializedBlocks.get(blockState.latestRev);
|
|
@@ -102,29 +97,14 @@ export class TestTransactor implements ITransactor {
|
|
|
102
97
|
break;
|
|
103
98
|
}
|
|
104
99
|
}
|
|
105
|
-
//
|
|
100
|
+
// Otherwise the committed content at the highest revision ≤ the pin, or the latest.
|
|
106
101
|
if (block === undefined) {
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
materializedRev = found?.rev;
|
|
111
|
-
} else {
|
|
112
|
-
block = structuredClone(blockState.materializedBlocks.get(blockState.latestRev));
|
|
113
|
-
if (block) materializedRev = blockState.latestRev;
|
|
114
|
-
}
|
|
102
|
+
const found = committedAt(blockState, pin);
|
|
103
|
+
block = structuredClone(found?.block);
|
|
104
|
+
materializedRev = found?.rev;
|
|
115
105
|
}
|
|
116
|
-
} else if (blockGets.context?.rev !== undefined) {
|
|
117
|
-
// Return the materialized block at the highest revision ≤ requested
|
|
118
|
-
const found = latestMaterializedAt(blockState, blockGets.context.rev);
|
|
119
|
-
block = structuredClone(found?.block);
|
|
120
|
-
materializedRev = found?.rev;
|
|
121
|
-
} else {
|
|
122
|
-
// Otherwise return latest materialized block
|
|
123
|
-
block = structuredClone(blockState.materializedBlocks.get(blockState.latestRev));
|
|
124
|
-
if (block) materializedRev = blockState.latestRev;
|
|
125
106
|
}
|
|
126
107
|
|
|
127
|
-
|
|
128
108
|
const actionId = blockState.revisionActions.get(blockState.latestRev);
|
|
129
109
|
// The materialized revision travels WITH its action id (one field, so the pair can
|
|
130
110
|
// never disagree) — the same `(rev, actionId)` the commit recorded for it.
|
|
@@ -963,6 +943,14 @@ function latestActionRev(blockState: BlockState): ActionRev | undefined {
|
|
|
963
943
|
return actionId === undefined ? undefined : { actionId, rev: blockState.latestRev };
|
|
964
944
|
}
|
|
965
945
|
|
|
946
|
+
/** The committed content a read at `pin` sees — the highest materialized revision at or below
|
|
947
|
+
* it — or the latest revision's content when the read is unpinned. */
|
|
948
|
+
function committedAt(blockState: BlockState, pin: number | undefined): { block: IBlock, rev: number } | undefined {
|
|
949
|
+
if (pin !== undefined) return latestMaterializedAt(blockState, pin);
|
|
950
|
+
const block = blockState.materializedBlocks.get(blockState.latestRev);
|
|
951
|
+
return block ? { block, rev: blockState.latestRev } : undefined;
|
|
952
|
+
}
|
|
953
|
+
|
|
966
954
|
/** Returns the materialized block at the highest revision ≤ the given revision, together with
|
|
967
955
|
* that revision — the caller reports it as {@link GetBlockResult.materialized}. */
|
|
968
956
|
function latestMaterializedAt(blockState: BlockState, maxRev: number): { block: IBlock, rev: number } | undefined {
|