@optimystic/db-core 1.11.0 → 1.12.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/src/cluster/structs.d.ts +13 -0
- package/dist/src/cluster/structs.d.ts.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/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 +40 -4
- 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/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/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/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/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/package.json +1 -1
- package/src/cluster/structs.ts +13 -0
- package/src/cohort-topic/registration/store.ts +68 -0
- 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 +43 -4
- package/src/collection/struct.ts +6 -2
- 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/testing/test-transactor.ts +28 -40
- package/src/transaction/index.ts +2 -1
- package/src/transaction/transaction.ts +28 -0
- package/src/transactor/transactor-source.ts +6 -2
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
|
/**
|
|
@@ -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 {
|
package/src/transaction/index.ts
CHANGED
|
@@ -152,6 +152,34 @@ export function clampPriority(priority: number | undefined): number {
|
|
|
152
152
|
return Math.floor(priority);
|
|
153
153
|
}
|
|
154
154
|
|
|
155
|
+
/**
|
|
156
|
+
* How many times a storage member must ITSELF have refused one action's pend as stale — a rival's
|
|
157
|
+
* revision already committed under the requested one — before it holds the next slot of that pend's
|
|
158
|
+
* blocks for the action. Counted per action id, which is one sync cycle (`Collection.syncInternal`
|
|
159
|
+
* mints the id once and every attempt of that cycle reuses it), so the count is "losses in a row of
|
|
160
|
+
* one write" and never needs resetting.
|
|
161
|
+
*
|
|
162
|
+
* What the member holds, and how it answers a rival while it holds, is in db-p2p's
|
|
163
|
+
* `ClusterMember.validatePendOperations` (`cluster/cluster-repo.ts`): the hold answers the next
|
|
164
|
+
* other-action pend of each block with the same `held` vote a storage reservation produces, once,
|
|
165
|
+
* for a bounded window, and is consumed by the aged action's own next pend. It closes the
|
|
166
|
+
* sequential starvation the aged {@link Transaction.priority} cannot reach — a stream of quick
|
|
167
|
+
* writers that each commit and leave before the slow one's attempt arrives never co-pend with it,
|
|
168
|
+
* so `resolveRace` never meets them (docs/correctness.md Theorem 9, "Bound").
|
|
169
|
+
*
|
|
170
|
+
* The count is the member's own and never the self-asserted priority: a member grants only on
|
|
171
|
+
* refusals it issued, so no claimant can talk it into a hold with a number. The writer side counts the
|
|
172
|
+
* refusals that confirmed a committed revision against the same constant to stop backing off on the
|
|
173
|
+
* loss after which a member holds for it (`retryBackoffMs` in `collection/collection.ts`), so the two
|
|
174
|
+
* sides agree with nothing on the wire — wherever the refused pends reached the member.
|
|
175
|
+
*
|
|
176
|
+
* Three: the plan-stage measurement (ticket `slot-hold-for-an-aged-writer`) showed an honest slow
|
|
177
|
+
* writer behind a quick stream losing nine of ten attempts, so two losses are an ordinary lost race
|
|
178
|
+
* and three are the stream. Lower, and a single lost race would hold a block against every other
|
|
179
|
+
* writer; higher, and the slow writer pays more refused round trips before it is helped.
|
|
180
|
+
*/
|
|
181
|
+
export const SlotHoldAfterLosses = 3;
|
|
182
|
+
|
|
155
183
|
/** Check whether a transaction stamp has expired. */
|
|
156
184
|
export function isTransactionExpired(stamp: TransactionStamp): boolean {
|
|
157
185
|
return Date.now() > stamp.expiration;
|
|
@@ -134,8 +134,12 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
|
|
|
134
134
|
this.readRevisions.set(id, rev);
|
|
135
135
|
this.served.set(block, { rev, mayRetain: this.mayRetain(id, rev) });
|
|
136
136
|
}
|
|
137
|
-
//
|
|
138
|
-
//
|
|
137
|
+
// NOTE: rival pendings in `state.pendings` are deliberately not remembered for a refresh
|
|
138
|
+
// before the next pend. It would save one doomed pend round only when the rival commits in
|
|
139
|
+
// between; the hint goes stale on a cache hit (which never re-reads), stuck records would
|
|
140
|
+
// trigger refreshes for nothing (backlog `debt-unpromotable-pending-records-need-a-sweep`),
|
|
141
|
+
// and while the rival is still pending a refresh changes nothing and the pend is refused
|
|
142
|
+
// `held` anyway. Revisit if lost pend rounds after a rival commit show up in measurements.
|
|
139
143
|
return block as TBlock;
|
|
140
144
|
}
|
|
141
145
|
}
|