@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
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Matchmaking — arrival-push fan-out selection (db-core, pure).
|
|
3
|
+
*
|
|
4
|
+
* Decides which push-opted seekers a newly arrived provider is pushed to (`docs/matchmaking.md`
|
|
5
|
+
* §Fairness — FCFS by `attachedAt`, fan-out bounded by `capacityBudget`). Every cohort member runs the
|
|
6
|
+
* same selection over the same gossip-replicated records and then delivers only to the selected seekers
|
|
7
|
+
* whose slot primary it is, so the cohort as a whole notifies about `capacityBudget` seekers rather than
|
|
8
|
+
* that many per member.
|
|
9
|
+
*
|
|
10
|
+
* Pure: no clock, no I/O. The db-p2p cohort driver decodes the records, keeps the targets it is primary
|
|
11
|
+
* for, coalesces, signs and delivers.
|
|
12
|
+
*/
|
|
13
|
+
import type { LocalProviderRegistration, LocalSeekerRegistration } from "./query-eval.js";
|
|
14
|
+
/** A decoded seeker registration held at this cohort, considered as a push target. */
|
|
15
|
+
export type ArrivalPushCandidate = LocalSeekerRegistration;
|
|
16
|
+
/**
|
|
17
|
+
* Seekers to notify about `provider`, longest-waiting first: of the push-opted seekers whose filter the
|
|
18
|
+
* provider matches and that attached no later than it did, the first `capacityBudget` by `attachedAt`
|
|
19
|
+
* (ties broken by `participantId`, so every member computes the same order). Generic so the caller gets
|
|
20
|
+
* back its own richer candidate objects.
|
|
21
|
+
*
|
|
22
|
+
* The `attachedAt` rule exists for a member that receives the whole record set at once (catching up by
|
|
23
|
+
* gossip, or pulling records in a rotation handoff): without it, that member would push every existing
|
|
24
|
+
* provider to every seeker. A provider that attached before a seeker was answerable by that seeker's own
|
|
25
|
+
* first query, and its safety poll still finds it.
|
|
26
|
+
*
|
|
27
|
+
* NOTE: accepted tradeoff — the ranking reads only replicated state, so a seeker already satisfied,
|
|
28
|
+
* finished, or answering `unknown_seeker` to its own primary keeps holding a fan-out slot until its
|
|
29
|
+
* record leaves the cohort (withdraw on finish, or its `seeker_ttl` expiry), under-filling that arrival's fan-out;
|
|
30
|
+
* members whose gossip views differ can also over- or under-fill by a few. Excluding them would mean
|
|
31
|
+
* gossiping per-seeker push state; the seeker's safety poll covers what is missed. Revisit if push
|
|
32
|
+
* under-fill shows up as seekers routinely falling back to the safety poll on a busy topic.
|
|
33
|
+
*/
|
|
34
|
+
export declare function selectArrivalPushTargets<S extends ArrivalPushCandidate>(provider: LocalProviderRegistration, seekers: readonly S[]): S[];
|
|
35
|
+
//# sourceMappingURL=arrival-push.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"arrival-push.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/arrival-push.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE1F,sFAAsF;AACtF,MAAM,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;AAE3D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,oBAAoB,EACtE,QAAQ,EAAE,yBAAyB,EACnC,OAAO,EAAE,SAAS,CAAC,EAAE,GACnB,CAAC,EAAE,CASL"}
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Matchmaking — arrival-push fan-out selection (db-core, pure).
|
|
3
|
+
*
|
|
4
|
+
* Decides which push-opted seekers a newly arrived provider is pushed to (`docs/matchmaking.md`
|
|
5
|
+
* §Fairness — FCFS by `attachedAt`, fan-out bounded by `capacityBudget`). Every cohort member runs the
|
|
6
|
+
* same selection over the same gossip-replicated records and then delivers only to the selected seekers
|
|
7
|
+
* whose slot primary it is, so the cohort as a whole notifies about `capacityBudget` seekers rather than
|
|
8
|
+
* that many per member.
|
|
9
|
+
*
|
|
10
|
+
* Pure: no clock, no I/O. The db-p2p cohort driver decodes the records, keeps the targets it is primary
|
|
11
|
+
* for, coalesces, signs and delivers.
|
|
12
|
+
*/
|
|
13
|
+
import { matchesFilter } from "./capability-filter.js";
|
|
14
|
+
/**
|
|
15
|
+
* Seekers to notify about `provider`, longest-waiting first: of the push-opted seekers whose filter the
|
|
16
|
+
* provider matches and that attached no later than it did, the first `capacityBudget` by `attachedAt`
|
|
17
|
+
* (ties broken by `participantId`, so every member computes the same order). Generic so the caller gets
|
|
18
|
+
* back its own richer candidate objects.
|
|
19
|
+
*
|
|
20
|
+
* The `attachedAt` rule exists for a member that receives the whole record set at once (catching up by
|
|
21
|
+
* gossip, or pulling records in a rotation handoff): without it, that member would push every existing
|
|
22
|
+
* provider to every seeker. A provider that attached before a seeker was answerable by that seeker's own
|
|
23
|
+
* first query, and its safety poll still finds it.
|
|
24
|
+
*
|
|
25
|
+
* NOTE: accepted tradeoff — the ranking reads only replicated state, so a seeker already satisfied,
|
|
26
|
+
* finished, or answering `unknown_seeker` to its own primary keeps holding a fan-out slot until its
|
|
27
|
+
* record leaves the cohort (withdraw on finish, or its `seeker_ttl` expiry), under-filling that arrival's fan-out;
|
|
28
|
+
* members whose gossip views differ can also over- or under-fill by a few. Excluding them would mean
|
|
29
|
+
* gossiping per-seeker push state; the seeker's safety poll covers what is missed. Revisit if push
|
|
30
|
+
* under-fill shows up as seekers routinely falling back to the safety poll on a busy topic.
|
|
31
|
+
*/
|
|
32
|
+
export function selectArrivalPushTargets(provider, seekers) {
|
|
33
|
+
const budget = provider.payload.capacityBudget;
|
|
34
|
+
if (budget === 0) {
|
|
35
|
+
return [];
|
|
36
|
+
}
|
|
37
|
+
return seekers
|
|
38
|
+
.filter((s) => isPushTarget(provider, s))
|
|
39
|
+
.sort(byLongestWaiting)
|
|
40
|
+
.slice(0, budget);
|
|
41
|
+
}
|
|
42
|
+
/** True iff `seeker` holds a push binding, matches `provider`, and was waiting when it arrived. */
|
|
43
|
+
function isPushTarget(provider, seeker) {
|
|
44
|
+
return seeker.payload.pushOnArrival === true
|
|
45
|
+
&& seeker.payload.correlationId !== undefined
|
|
46
|
+
&& matchesFilter(provider.payload, seeker.payload.filter)
|
|
47
|
+
&& provider.attachedAt >= seeker.attachedAt;
|
|
48
|
+
}
|
|
49
|
+
/** Ascending `attachedAt`, then code-unit order of `participantId` (locale-independent, so members agree). */
|
|
50
|
+
function byLongestWaiting(a, b) {
|
|
51
|
+
if (a.attachedAt !== b.attachedAt) {
|
|
52
|
+
return a.attachedAt - b.attachedAt;
|
|
53
|
+
}
|
|
54
|
+
return a.participantId < b.participantId ? -1 : a.participantId > b.participantId ? 1 : 0;
|
|
55
|
+
}
|
|
56
|
+
//# sourceMappingURL=arrival-push.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"arrival-push.js","sourceRoot":"","sources":["../../../src/matchmaking/arrival-push.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAMvD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,wBAAwB,CACvC,QAAmC,EACnC,OAAqB;IAErB,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,cAAc,CAAC;IAC/C,IAAI,MAAM,KAAK,CAAC,EAAE,CAAC;QAClB,OAAO,EAAE,CAAC;IACX,CAAC;IACD,OAAO,OAAO;SACZ,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;SACxC,IAAI,CAAC,gBAAgB,CAAC;SACtB,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AACpB,CAAC;AAED,mGAAmG;AACnG,SAAS,YAAY,CAAC,QAAmC,EAAE,MAA4B;IACtF,OAAO,MAAM,CAAC,OAAO,CAAC,aAAa,KAAK,IAAI;WACxC,MAAM,CAAC,OAAO,CAAC,aAAa,KAAK,SAAS;WAC1C,aAAa,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;WACtD,QAAQ,CAAC,UAAU,IAAI,MAAM,CAAC,UAAU,CAAC;AAC9C,CAAC;AAED,8GAA8G;AAC9G,SAAS,gBAAgB,CAAC,CAAuB,EAAE,CAAuB;IACzE,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU,EAAE,CAAC;QACnC,OAAO,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC;IACpC,CAAC;IACD,OAAO,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3F,CAAC"}
|
|
@@ -10,8 +10,9 @@
|
|
|
10
10
|
* The TTL/limit constants are wire-stable and do **not** depend on simulator findings; the hang-out
|
|
11
11
|
* rows DO (folded via `fold-simulator-findings-into-design-docs`) — they carry the simulator-validated
|
|
12
12
|
* defaults (`contention_factor_cap = 4.0`, `mean_want_count = 3`, …; see `docs/matchmaking.md`
|
|
13
|
-
* §Configuration "Defaults validated by simulator").
|
|
14
|
-
*
|
|
13
|
+
* §Configuration "Defaults validated by simulator"). Of the arrival-push rows, `push_safety_poll_ms` is
|
|
14
|
+
* seeker-side and lives on {@link HangOutConfig}; `push_coalesce_ms` is the one cohort-side knob and
|
|
15
|
+
* lives on {@link ArrivalPushConfig}.
|
|
15
16
|
*/
|
|
16
17
|
import type { NodeProfile } from "../cohort-topic/tiers.js";
|
|
17
18
|
/** Provider registration TTL on a Core node (ms). */
|
|
@@ -55,9 +56,18 @@ export interface HangOutConfig {
|
|
|
55
56
|
readonly contentionFactorCap: number;
|
|
56
57
|
/** Hang-out poll cadence on the non-push path. */
|
|
57
58
|
readonly requeryIntervalMs: number;
|
|
59
|
+
/** Sparse safety-poll cadence beneath the pushes, for a seeker that set `pushOnArrival`. */
|
|
60
|
+
readonly pushSafetyPollMs: number;
|
|
58
61
|
}
|
|
59
62
|
/** The default hang-out decision config (simulator-validated). */
|
|
60
63
|
export declare const DEFAULT_HANG_OUT_CONFIG: HangOutConfig;
|
|
64
|
+
/** Cohort-side arrival-push tuning (`docs/matchmaking.md` §Coalescing). */
|
|
65
|
+
export interface ArrivalPushConfig {
|
|
66
|
+
/** Window the pushing member batches fresh matchable arrivals per seeker before flushing one push. */
|
|
67
|
+
readonly coalesceMs: number;
|
|
68
|
+
}
|
|
69
|
+
/** The default arrival-push config. */
|
|
70
|
+
export declare const DEFAULT_ARRIVAL_PUSH_CONFIG: ArrivalPushConfig;
|
|
61
71
|
/** The full matchmaking config, with the documented defaults. */
|
|
62
72
|
export interface MatchmakingConfig {
|
|
63
73
|
readonly providerTtlCoreMs: number;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/config.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,qDAAqD;AACrD,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAC3C,sDAAsD;AACtD,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAC3C,oFAAoF;AACpF,eAAO,MAAM,aAAa,QAAS,CAAC;AACpC,wEAAwE;AACxE,eAAO,MAAM,iBAAiB,OAAQ,CAAC;AACvC,eAAO,MAAM,iBAAiB,QAAS,CAAC;AACxC,wDAAwD;AACxD,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAC3C,yEAAyE;AACzE,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAI9C,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAC1C,gHAAgH;AAChH,eAAO,MAAM,0BAA0B,IAAM,CAAC;AAC9C,8FAA8F;AAC9F,eAAO,MAAM,2BAA2B,IAAM,CAAC;AAC/C,6GAA6G;AAC7G,eAAO,MAAM,qBAAqB,IAAM,CAAC;AACzC,mHAAmH;AACnH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AACzC,2FAA2F;AAC3F,eAAO,MAAM,mBAAmB,OAAQ,CAAC;AACzC,qHAAqH;AACrH,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,OAAQ,CAAC;AAEzC;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,0GAA0G;IAC1G,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,kDAAkD;IAClD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,4FAA4F;IAC5F,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CAClC;AAED,kEAAkE;AAClE,eAAO,MAAM,uBAAuB,EAAE,aAIrC,CAAC;AAEF,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IACjC,sGAAsG;IACtG,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AAED,uCAAuC;AACvC,eAAO,MAAM,2BAA2B,EAAE,iBAEzC,CAAC;AAEF,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;CAC3C;AAED,4DAA4D;AAC5D,eAAO,MAAM,0BAA0B,EAAE,iBAOxC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,GAAE,iBAA8C,GAAG,MAAM,CAE1H"}
|
|
@@ -10,8 +10,9 @@
|
|
|
10
10
|
* The TTL/limit constants are wire-stable and do **not** depend on simulator findings; the hang-out
|
|
11
11
|
* rows DO (folded via `fold-simulator-findings-into-design-docs`) — they carry the simulator-validated
|
|
12
12
|
* defaults (`contention_factor_cap = 4.0`, `mean_want_count = 3`, …; see `docs/matchmaking.md`
|
|
13
|
-
* §Configuration "Defaults validated by simulator").
|
|
14
|
-
*
|
|
13
|
+
* §Configuration "Defaults validated by simulator"). Of the arrival-push rows, `push_safety_poll_ms` is
|
|
14
|
+
* seeker-side and lives on {@link HangOutConfig}; `push_coalesce_ms` is the one cohort-side knob and
|
|
15
|
+
* lives on {@link ArrivalPushConfig}.
|
|
15
16
|
*/
|
|
16
17
|
/** Provider registration TTL on a Core node (ms). */
|
|
17
18
|
export const PROVIDER_TTL_CORE_MS = 90_000;
|
|
@@ -49,6 +50,11 @@ export const PUSH_SAFETY_POLL_MS = 5_000;
|
|
|
49
50
|
export const DEFAULT_HANG_OUT_CONFIG = {
|
|
50
51
|
contentionFactorCap: CONTENTION_FACTOR_CAP,
|
|
51
52
|
requeryIntervalMs: REQUERY_INTERVAL_MS,
|
|
53
|
+
pushSafetyPollMs: PUSH_SAFETY_POLL_MS,
|
|
54
|
+
};
|
|
55
|
+
/** The default arrival-push config. */
|
|
56
|
+
export const DEFAULT_ARRIVAL_PUSH_CONFIG = {
|
|
57
|
+
coalesceMs: PUSH_COALESCE_MS,
|
|
52
58
|
};
|
|
53
59
|
/** The default matchmaking config (this ticket's slice). */
|
|
54
60
|
export const DEFAULT_MATCHMAKING_CONFIG = {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/matchmaking/config.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/matchmaking/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,qDAAqD;AACrD,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAC3C,sDAAsD;AACtD,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAC3C,oFAAoF;AACpF,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC;AACpC,wEAAwE;AACxE,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AACvC,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC;AACxC,wDAAwD;AACxD,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAC;AACnC,0EAA0E;AAC1E,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAC;AAC3C,yEAAyE;AACzE,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAE9C,kGAAkG;AAElG,6EAA6E;AAC7E,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAC1C,gHAAgH;AAChH,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAC9C,8FAA8F;AAC9F,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAC/C,6GAA6G;AAC7G,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AACzC,mHAAmH;AACnH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AACzC,2FAA2F;AAC3F,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AACzC,qHAAqH;AACrH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AACpC,qGAAqG;AACrG,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAgBzC,kEAAkE;AAClE,MAAM,CAAC,MAAM,uBAAuB,GAAkB;IACrD,mBAAmB,EAAE,qBAAqB;IAC1C,iBAAiB,EAAE,mBAAmB;IACtC,gBAAgB,EAAE,mBAAmB;CACrC,CAAC;AAQF,uCAAuC;AACvC,MAAM,CAAC,MAAM,2BAA2B,GAAsB;IAC7D,UAAU,EAAE,gBAAgB;CAC5B,CAAC;AAYF,4DAA4D;AAC5D,MAAM,CAAC,MAAM,0BAA0B,GAAsB;IAC5D,iBAAiB,EAAE,oBAAoB;IACvC,iBAAiB,EAAE,oBAAoB;IACvC,WAAW,EAAE,aAAa;IAC1B,aAAa,EAAE,eAAe;IAC9B,kBAAkB,EAAE,qBAAqB;IACzC,yBAAyB,EAAE,4BAA4B;CACvD,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAoB,EAAE,SAA4B,0BAA0B;IACjH,OAAO,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC;AACtF,CAAC"}
|
|
@@ -4,8 +4,8 @@
|
|
|
4
4
|
* See `docs/matchmaking.md`. The db-core layer owns the transport-agnostic pieces: wire codecs +
|
|
5
5
|
* seeker-side entry re-validation, the stable topic-anchor derivation, configuration, both
|
|
6
6
|
* registration roles' decision/state (provider attach/renew/self-throttle; seeker short-TTL
|
|
7
|
-
* registration), the cohort-side capability filter + pure query evaluation,
|
|
8
|
-
* hang-out-vs-continue decision engine. The db-p2p layer wires these to the cohort-topic substrate
|
|
7
|
+
* registration), the cohort-side capability filter + pure query evaluation, the arrival-push fan-out
|
|
8
|
+
* selection, and the seeker hang-out-vs-continue decision engine. The db-p2p layer wires these to the cohort-topic substrate
|
|
9
9
|
* (managers, the cohort query handler, the seeker walk client).
|
|
10
10
|
*/
|
|
11
11
|
export * from "./config.js";
|
|
@@ -15,6 +15,7 @@ export * from "./provider.js";
|
|
|
15
15
|
export * from "./seeker.js";
|
|
16
16
|
export * from "./capability-filter.js";
|
|
17
17
|
export * from "./query-eval.js";
|
|
18
|
+
export * from "./arrival-push.js";
|
|
18
19
|
export * from "./seeker-walk.js";
|
|
19
20
|
export * from "./multi-cohort-seeker.js";
|
|
20
21
|
export * from "./voting-quorum.js";
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC"}
|
|
@@ -4,8 +4,8 @@
|
|
|
4
4
|
* See `docs/matchmaking.md`. The db-core layer owns the transport-agnostic pieces: wire codecs +
|
|
5
5
|
* seeker-side entry re-validation, the stable topic-anchor derivation, configuration, both
|
|
6
6
|
* registration roles' decision/state (provider attach/renew/self-throttle; seeker short-TTL
|
|
7
|
-
* registration), the cohort-side capability filter + pure query evaluation,
|
|
8
|
-
* hang-out-vs-continue decision engine. The db-p2p layer wires these to the cohort-topic substrate
|
|
7
|
+
* registration), the cohort-side capability filter + pure query evaluation, the arrival-push fan-out
|
|
8
|
+
* selection, and the seeker hang-out-vs-continue decision engine. The db-p2p layer wires these to the cohort-topic substrate
|
|
9
9
|
* (managers, the cohort query handler, the seeker walk client).
|
|
10
10
|
*/
|
|
11
11
|
export * from "./config.js";
|
|
@@ -15,6 +15,7 @@ export * from "./provider.js";
|
|
|
15
15
|
export * from "./seeker.js";
|
|
16
16
|
export * from "./capability-filter.js";
|
|
17
17
|
export * from "./query-eval.js";
|
|
18
|
+
export * from "./arrival-push.js";
|
|
18
19
|
export * from "./seeker-walk.js";
|
|
19
20
|
export * from "./multi-cohort-seeker.js";
|
|
20
21
|
export * from "./voting-quorum.js";
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/matchmaking/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/matchmaking/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC"}
|
|
@@ -24,11 +24,14 @@ export interface MatchmakingSeekerOptions {
|
|
|
24
24
|
readonly contactHint: string;
|
|
25
25
|
/** Optional capability filter (evaluated cohort-side in the next ticket; carried here). */
|
|
26
26
|
readonly filter?: CapabilityFilter;
|
|
27
|
-
/** Opt into arrival pushes; default false (poll path).
|
|
27
|
+
/** Opt into arrival pushes; default false (poll path). */
|
|
28
28
|
readonly pushOnArrival?: boolean;
|
|
29
29
|
/** Sign the canonical registration image; resolves the base64url signature. */
|
|
30
30
|
readonly sign: (payload: Uint8Array) => Promise<string>;
|
|
31
|
-
/**
|
|
31
|
+
/**
|
|
32
|
+
* 16-byte registration correlation id (not signature-bound); default fresh CSPRNG bytes. Sent in the
|
|
33
|
+
* payload when `pushOnArrival` is set, as the id arrival pushes are bound to.
|
|
34
|
+
*/
|
|
32
35
|
readonly correlationId?: Uint8Array;
|
|
33
36
|
/** CSPRNG source (injectable for deterministic tests). Default `@noble/hashes` `randomBytes`. */
|
|
34
37
|
readonly randomBytes?: (n: number) => Uint8Array;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"seeker.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/seeker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;
|
|
1
|
+
{"version":3,"file":"seeker.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/seeker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAAwB,KAAK,gBAAgB,EAAE,KAAK,kBAAkB,EAA0B,MAAM,WAAW,CAAC;AAEzH,2DAA2D;AAC3D,MAAM,WAAW,wBAAwB;IACxC,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACxD;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,UAAU,CAAC;IACpC,iGAAiG;IACjG,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,UAAU,CAAC;CACjD;AAED,gGAAgG;AAChG,qBAAa,iBAAiB;IAC7B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA2C;gBAEpD,OAAO,EAAE,wBAAwB;IAc7C,kFAAkF;IAC5E,eAAe,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAoBpD,gFAAgF;IAC1E,eAAe,IAAI,OAAO,CAAC,UAAU,CAAC;CAG5C"}
|
|
@@ -14,6 +14,8 @@
|
|
|
14
14
|
* Crypto-free: signing is an injected callback, matching {@link MatchmakingProvider}.
|
|
15
15
|
*/
|
|
16
16
|
import { randomBytes } from "@noble/hashes/utils.js";
|
|
17
|
+
import { bytesToB64url } from "../cohort-topic/wire/codec.js";
|
|
18
|
+
import { CORRELATION_BYTES } from "../cohort-topic/wire/primitives.js";
|
|
17
19
|
import { seekerSigningPayload, encodeSeekerAppPayload } from "./wire.js";
|
|
18
20
|
/** Live seeker state + signed-payload builder for one matchmaking topic (registration only). */
|
|
19
21
|
export class MatchmakingSeeker {
|
|
@@ -35,7 +37,7 @@ export class MatchmakingSeeker {
|
|
|
35
37
|
this.pushOnArrival = options.pushOnArrival;
|
|
36
38
|
this.sign = options.sign;
|
|
37
39
|
const rand = options.randomBytes ?? randomBytes;
|
|
38
|
-
this.correlationId = options.correlationId ?? rand(
|
|
40
|
+
this.correlationId = options.correlationId ?? rand(CORRELATION_BYTES);
|
|
39
41
|
}
|
|
40
42
|
/** Build the signed {@link SeekerAppPayloadV1} for this seeker's registration. */
|
|
41
43
|
async buildAppPayload() {
|
|
@@ -52,6 +54,9 @@ export class MatchmakingSeeker {
|
|
|
52
54
|
if (this.pushOnArrival !== undefined) {
|
|
53
55
|
payload.pushOnArrival = this.pushOnArrival;
|
|
54
56
|
}
|
|
57
|
+
if (this.pushOnArrival === true) {
|
|
58
|
+
payload.correlationId = bytesToB64url(this.correlationId);
|
|
59
|
+
}
|
|
55
60
|
return payload;
|
|
56
61
|
}
|
|
57
62
|
/** Build the opaque bytes for the cohort-topic `RegisterV1.appPayload` slot. */
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"seeker.js","sourceRoot":"","sources":["../../../src/matchmaking/seeker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAkD,sBAAsB,EAAE,MAAM,WAAW,CAAC;
|
|
1
|
+
{"version":3,"file":"seeker.js","sourceRoot":"","sources":["../../../src/matchmaking/seeker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,EAAE,oBAAoB,EAAkD,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAyBzH,gGAAgG;AAChG,MAAM,OAAO,iBAAiB;IACpB,OAAO,CAAa;IACpB,aAAa,CAAa;IAClB,SAAS,CAAS;IAClB,WAAW,CAAS;IACpB,MAAM,CAAoB;IAC1B,aAAa,CAAW;IACxB,IAAI,CAA2C;IAEhE,YAAY,OAAiC;QAC5C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;YACnE,MAAM,IAAI,UAAU,CAAC,8DAA8D,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;QACzG,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;QAC3C,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,IAAI,WAAW,CAAC;QAChD,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,IAAI,CAAC,iBAAiB,CAAC,CAAC;IACvE,CAAC;IAED,kFAAkF;IAClF,KAAK,CAAC,eAAe;QACpB,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;QACtF,MAAM,OAAO,GAAuB;YACnC,IAAI,EAAE,cAAc;YACpB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,SAAS;SACT,CAAC;QACF,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC/B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC9B,CAAC;QACD,IAAI,IAAI,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;YACtC,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;QAC5C,CAAC;QACD,IAAI,IAAI,CAAC,aAAa,KAAK,IAAI,EAAE,CAAC;YACjC,OAAO,CAAC,aAAa,GAAG,aAAa,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC3D,CAAC;QACD,OAAO,OAAO,CAAC;IAChB,CAAC;IAED,gFAAgF;IAChF,KAAK,CAAC,eAAe;QACpB,OAAO,sBAAsB,CAAC,MAAM,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC;IAC7D,CAAC;CACD"}
|
|
@@ -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
|
|
@@ -47,6 +48,15 @@ export interface SeekerAppPayloadV1 {
|
|
|
47
48
|
contactHint: string;
|
|
48
49
|
/** Opt into arrival pushes; default false (poll path). */
|
|
49
50
|
pushOnArrival?: boolean;
|
|
51
|
+
/**
|
|
52
|
+
* The registration id an {@link ArrivalPushV1} is bound to, 16 bytes, base64url. Required when
|
|
53
|
+
* `pushOnArrival` is `true`; accepted and ignored otherwise. Riding in the payload puts it in the
|
|
54
|
+
* cohort's gossip-replicated record, so any member can derive the seeker's push binding after a
|
|
55
|
+
* failover. Deliberately outside {@link seekerSigningPayload} (a forwarded {@link SeekerEntryV1}
|
|
56
|
+
* does not carry it); it is still authenticated, because the cohort admits the payload only inside
|
|
57
|
+
* a peer-key-signed `RegisterV1`, whose signing image covers `appPayload`.
|
|
58
|
+
*/
|
|
59
|
+
correlationId?: string;
|
|
50
60
|
/** base64url. */
|
|
51
61
|
signature: string;
|
|
52
62
|
}
|
|
@@ -143,6 +153,39 @@ export interface AggregateBucketV1 {
|
|
|
143
153
|
/** Log-bucketed. */
|
|
144
154
|
count: number;
|
|
145
155
|
}
|
|
156
|
+
/**
|
|
157
|
+
* A cohort member's notification to a push-opted seeker that fresh matchable providers arrived
|
|
158
|
+
* (`docs/matchmaking.md` §Arrival push on provider arrival). Advisory, with the same trust model as
|
|
159
|
+
* {@link QueryReplyV1}: `signature` is the pushing member's single peer-key signature over
|
|
160
|
+
* {@link arrivalPushSigningPayload}, and the seeker re-validates every entry's `registrationSig`
|
|
161
|
+
* ({@link verifyProviderEntry}) before dialing.
|
|
162
|
+
*/
|
|
163
|
+
export interface ArrivalPushV1 {
|
|
164
|
+
v: 1;
|
|
165
|
+
/** Topic id, 32 bytes, base64url. */
|
|
166
|
+
topicId: string;
|
|
167
|
+
/** Cohort epoch the push was computed under, 32 bytes, base64url. */
|
|
168
|
+
cohortEpoch: string;
|
|
169
|
+
/** The seeker registration this push is bound to ({@link SeekerAppPayloadV1.correlationId}), 16 bytes, base64url. */
|
|
170
|
+
correlationId: string;
|
|
171
|
+
/** The fresh, filter-matched, coalesced batch: `1..QUERY_LIMIT_MAX` entries. */
|
|
172
|
+
providers: ProviderEntryV1[];
|
|
173
|
+
/** Current traffic snapshot, so the seeker can re-run its hang-out math without a poll. */
|
|
174
|
+
topicTraffic: TopicTrafficV1;
|
|
175
|
+
/** The pushing member's single peer-key signature (NOT threshold), base64url. */
|
|
176
|
+
signature: string;
|
|
177
|
+
}
|
|
178
|
+
/** The outcomes a seeker may report for an {@link ArrivalPushV1}. */
|
|
179
|
+
export declare const ARRIVAL_PUSH_RESULTS: readonly ["ok", "unknown_seeker"];
|
|
180
|
+
export type ArrivalPushResult = typeof ARRIVAL_PUSH_RESULTS[number];
|
|
181
|
+
/**
|
|
182
|
+
* A seeker's reply to an {@link ArrivalPushV1}. `unknown_seeker` says the push's `correlationId` is not
|
|
183
|
+
* the seeker's current registration (it re-registered, or finished), so the pusher drops the binding.
|
|
184
|
+
*/
|
|
185
|
+
export interface ArrivalPushAckV1 {
|
|
186
|
+
v: 1;
|
|
187
|
+
result: ArrivalPushResult;
|
|
188
|
+
}
|
|
146
189
|
/** Ceiling for an opaque app payload (provider/seeker), guarding decode allocation. */
|
|
147
190
|
export declare const DEFAULT_MAX_APP_PAYLOAD_BYTES: number;
|
|
148
191
|
/** Narrow an already-parsed value to {@link ProviderAppPayloadV1}, throwing on any defect. */
|
|
@@ -173,6 +216,10 @@ export declare function validateQueryV1(value: unknown): QueryV1;
|
|
|
173
216
|
export declare function validateQueryReplyV1(value: unknown): QueryReplyV1;
|
|
174
217
|
/** Narrow an already-parsed value to {@link AggregateCountV1}, throwing on any defect. */
|
|
175
218
|
export declare function validateAggregateCountV1(value: unknown): AggregateCountV1;
|
|
219
|
+
/** Narrow an already-parsed value to {@link ArrivalPushV1}, throwing on any defect. */
|
|
220
|
+
export declare function validateArrivalPushV1(value: unknown): ArrivalPushV1;
|
|
221
|
+
/** Narrow an already-parsed value to {@link ArrivalPushAckV1}, throwing on any defect. */
|
|
222
|
+
export declare function validateArrivalPushAckV1(value: unknown): ArrivalPushAckV1;
|
|
176
223
|
/** Encode a {@link QueryV1} as a length-prefixed UTF-8 JSON frame. */
|
|
177
224
|
export declare function encodeQueryV1(msg: QueryV1, maxMessageBytes?: number): Uint8Array;
|
|
178
225
|
/** Decode a length-prefixed {@link QueryV1} frame. */
|
|
@@ -185,6 +232,14 @@ export declare function decodeQueryReplyV1(bytes: Uint8Array, maxMessageBytes?:
|
|
|
185
232
|
export declare function encodeAggregateCountV1(msg: AggregateCountV1, maxMessageBytes?: number): Uint8Array;
|
|
186
233
|
/** Decode a length-prefixed {@link AggregateCountV1} frame. */
|
|
187
234
|
export declare function decodeAggregateCountV1(bytes: Uint8Array, maxMessageBytes?: number): AggregateCountV1;
|
|
235
|
+
/** Encode an {@link ArrivalPushV1} as a length-prefixed UTF-8 JSON frame. */
|
|
236
|
+
export declare function encodeArrivalPushV1(msg: ArrivalPushV1, maxMessageBytes?: number): Uint8Array;
|
|
237
|
+
/** Decode a length-prefixed {@link ArrivalPushV1} frame. */
|
|
238
|
+
export declare function decodeArrivalPushV1(bytes: Uint8Array, maxMessageBytes?: number): ArrivalPushV1;
|
|
239
|
+
/** Encode an {@link ArrivalPushAckV1} as a length-prefixed UTF-8 JSON frame. */
|
|
240
|
+
export declare function encodeArrivalPushAckV1(msg: ArrivalPushAckV1, maxMessageBytes?: number): Uint8Array;
|
|
241
|
+
/** Decode a length-prefixed {@link ArrivalPushAckV1} frame. */
|
|
242
|
+
export declare function decodeArrivalPushAckV1(bytes: Uint8Array, maxMessageBytes?: number): ArrivalPushAckV1;
|
|
188
243
|
/**
|
|
189
244
|
* Canonical signed byte image of a provider registration — `(topicId, capabilities, capacityBudget)`
|
|
190
245
|
* per `docs/matchmaking.md` §Wire formats.
|
|
@@ -237,6 +292,14 @@ export declare function verifySeekerEntry(topicId: Uint8Array, entry: SeekerEntr
|
|
|
237
292
|
* advisory per-entry signatures.
|
|
238
293
|
*/
|
|
239
294
|
export declare function queryReplySigningPayload(reply: Omit<QueryReplyV1, "signature">): Uint8Array;
|
|
295
|
+
/**
|
|
296
|
+
* Canonical signed byte image of an {@link ArrivalPushV1} — the pushing member's single-member
|
|
297
|
+
* signature, mirroring {@link queryReplySigningPayload}. It binds the topic, epoch, the seeker
|
|
298
|
+
* registration the push is addressed to, the traffic snapshot, and the providers' participant ids
|
|
299
|
+
* (order-sensitive); the per-entry signatures stay outside it, since the seeker re-validates each entry
|
|
300
|
+
* on its own ({@link verifyProviderEntry}).
|
|
301
|
+
*/
|
|
302
|
+
export declare function arrivalPushSigningPayload(unsigned: Omit<ArrivalPushV1, "signature">): Uint8Array;
|
|
240
303
|
/**
|
|
241
304
|
* Log-bucket a raw provider count for an {@link AggregateCountV1} bucket: the largest power of two
|
|
242
305
|
* `<= n` (and `0` for `n <= 0`). The root reports bucketed, not exact, per-shard populations
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/wire.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/wire.ts"],"names":[],"mappings":"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"}
|
|
@@ -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
|
|
@@ -22,8 +23,10 @@
|
|
|
22
23
|
* be unit-tested against fixtures.
|
|
23
24
|
*/
|
|
24
25
|
import { bytesToB64url, b64urlToBytes, decodeCohortMessage, encodeCohortMessage, DEFAULT_MAX_MESSAGE_BYTES, } from "../cohort-topic/wire/codec.js";
|
|
25
|
-
import { asObject, b64urlField, b64urlFixedLen, COORD_BYTES, failWire as fail, optBool, optFiniteNumber, reqBool, reqFiniteNumber, reqIntInRange, reqString, reqStringArray, requireV1, } from "../cohort-topic/wire/primitives.js";
|
|
26
|
+
import { asObject, b64urlField, b64urlFixedLen, COORD_BYTES, CORRELATION_BYTES, failWire as fail, optBool, optFiniteNumber, optString, reqBool, reqEnum, reqFiniteNumber, reqIntInRange, reqString, reqStringArray, requireV1, } from "../cohort-topic/wire/primitives.js";
|
|
26
27
|
import { QUERY_LIMIT_MAX } from "./config.js";
|
|
28
|
+
/** The outcomes a seeker may report for an {@link ArrivalPushV1}. */
|
|
29
|
+
export const ARRIVAL_PUSH_RESULTS = ["ok", "unknown_seeker"];
|
|
27
30
|
// --- matchmaking-local wire state (generic validation primitives live in cohort-topic/wire/primitives.js) ---
|
|
28
31
|
const utf8Encoder = new TextEncoder();
|
|
29
32
|
// Built on first use, not at module load: Hermes (React Native) has no native `TextDecoder`, so a
|
|
@@ -85,6 +88,13 @@ export function validateSeekerAppPayloadV1(value) {
|
|
|
85
88
|
if (pushOnArrival !== undefined) {
|
|
86
89
|
out.pushOnArrival = pushOnArrival;
|
|
87
90
|
}
|
|
91
|
+
const correlationId = optString(obj, "correlationId", what);
|
|
92
|
+
if (correlationId !== undefined) {
|
|
93
|
+
out.correlationId = b64urlFixedLen(correlationId, "correlationId", CORRELATION_BYTES, what);
|
|
94
|
+
}
|
|
95
|
+
if (out.pushOnArrival === true && out.correlationId === undefined) {
|
|
96
|
+
fail(`${what}: field "correlationId" is required when "pushOnArrival" is true`);
|
|
97
|
+
}
|
|
88
98
|
return out;
|
|
89
99
|
}
|
|
90
100
|
/** Serialize a {@link ProviderAppPayloadV1} to the opaque UTF-8 JSON bytes for `RegisterV1.appPayload`. */
|
|
@@ -254,6 +264,32 @@ export function validateAggregateCountV1(value) {
|
|
|
254
264
|
cohortEpoch: b64urlFixedLen(reqString(obj, "cohortEpoch", what), "cohortEpoch", COORD_BYTES, what),
|
|
255
265
|
};
|
|
256
266
|
}
|
|
267
|
+
/** Narrow an already-parsed value to {@link ArrivalPushV1}, throwing on any defect. */
|
|
268
|
+
export function validateArrivalPushV1(value) {
|
|
269
|
+
const what = "ArrivalPushV1";
|
|
270
|
+
const obj = asObject(value, what);
|
|
271
|
+
requireV1(obj, what);
|
|
272
|
+
const providers = obj["providers"];
|
|
273
|
+
if (!Array.isArray(providers) || providers.length < 1 || providers.length > QUERY_LIMIT_MAX) {
|
|
274
|
+
fail(`${what}: field "providers" must be an array of 1..${QUERY_LIMIT_MAX} entries`);
|
|
275
|
+
}
|
|
276
|
+
return {
|
|
277
|
+
v: 1,
|
|
278
|
+
topicId: b64urlFixedLen(reqString(obj, "topicId", what), "topicId", COORD_BYTES, what),
|
|
279
|
+
cohortEpoch: b64urlFixedLen(reqString(obj, "cohortEpoch", what), "cohortEpoch", COORD_BYTES, what),
|
|
280
|
+
correlationId: b64urlFixedLen(reqString(obj, "correlationId", what), "correlationId", CORRELATION_BYTES, what),
|
|
281
|
+
providers: providers.map(validateProviderEntryV1),
|
|
282
|
+
topicTraffic: validateTopicTrafficV1(obj["topicTraffic"], `${what}.topicTraffic`),
|
|
283
|
+
signature: b64urlField(reqString(obj, "signature", what), "signature", what),
|
|
284
|
+
};
|
|
285
|
+
}
|
|
286
|
+
/** Narrow an already-parsed value to {@link ArrivalPushAckV1}, throwing on any defect. */
|
|
287
|
+
export function validateArrivalPushAckV1(value) {
|
|
288
|
+
const what = "ArrivalPushAckV1";
|
|
289
|
+
const obj = asObject(value, what);
|
|
290
|
+
requireV1(obj, what);
|
|
291
|
+
return { v: 1, result: reqEnum(obj, "result", ARRIVAL_PUSH_RESULTS, what) };
|
|
292
|
+
}
|
|
257
293
|
/** Encode a {@link QueryV1} as a length-prefixed UTF-8 JSON frame. */
|
|
258
294
|
export function encodeQueryV1(msg, maxMessageBytes = DEFAULT_MAX_MESSAGE_BYTES) {
|
|
259
295
|
return encodeCohortMessage(validateQueryV1(msg), maxMessageBytes);
|
|
@@ -278,6 +314,22 @@ export function encodeAggregateCountV1(msg, maxMessageBytes = DEFAULT_MAX_MESSAG
|
|
|
278
314
|
export function decodeAggregateCountV1(bytes, maxMessageBytes) {
|
|
279
315
|
return validateAggregateCountV1(decodeCohortMessage(bytes, maxMessageBytes));
|
|
280
316
|
}
|
|
317
|
+
/** Encode an {@link ArrivalPushV1} as a length-prefixed UTF-8 JSON frame. */
|
|
318
|
+
export function encodeArrivalPushV1(msg, maxMessageBytes = DEFAULT_MAX_MESSAGE_BYTES) {
|
|
319
|
+
return encodeCohortMessage(validateArrivalPushV1(msg), maxMessageBytes);
|
|
320
|
+
}
|
|
321
|
+
/** Decode a length-prefixed {@link ArrivalPushV1} frame. */
|
|
322
|
+
export function decodeArrivalPushV1(bytes, maxMessageBytes) {
|
|
323
|
+
return validateArrivalPushV1(decodeCohortMessage(bytes, maxMessageBytes));
|
|
324
|
+
}
|
|
325
|
+
/** Encode an {@link ArrivalPushAckV1} as a length-prefixed UTF-8 JSON frame. */
|
|
326
|
+
export function encodeArrivalPushAckV1(msg, maxMessageBytes = DEFAULT_MAX_MESSAGE_BYTES) {
|
|
327
|
+
return encodeCohortMessage(validateArrivalPushAckV1(msg), maxMessageBytes);
|
|
328
|
+
}
|
|
329
|
+
/** Decode a length-prefixed {@link ArrivalPushAckV1} frame. */
|
|
330
|
+
export function decodeArrivalPushAckV1(bytes, maxMessageBytes) {
|
|
331
|
+
return validateArrivalPushAckV1(decodeCohortMessage(bytes, maxMessageBytes));
|
|
332
|
+
}
|
|
281
333
|
// --- canonical participant-signature payloads (provider/seeker registration sigs) ---
|
|
282
334
|
/**
|
|
283
335
|
* Canonical signed byte image of a provider registration — `(topicId, capabilities, capacityBudget)`
|
|
@@ -360,17 +412,33 @@ export function queryReplySigningPayload(reply) {
|
|
|
360
412
|
reply.v,
|
|
361
413
|
reply.cohortEpoch,
|
|
362
414
|
reply.truncated,
|
|
363
|
-
|
|
364
|
-
reply.topicTraffic.windowSeconds,
|
|
365
|
-
reply.topicTraffic.arrivalsPerMin,
|
|
366
|
-
reply.topicTraffic.queriesPerMin,
|
|
367
|
-
reply.topicTraffic.directParticipants,
|
|
368
|
-
reply.topicTraffic.childCohortCount,
|
|
369
|
-
],
|
|
415
|
+
topicTrafficImage(reply.topicTraffic),
|
|
370
416
|
(reply.providers ?? []).map((p) => p.participantId),
|
|
371
417
|
(reply.seekers ?? []).map((s) => s.participantId),
|
|
372
418
|
]));
|
|
373
419
|
}
|
|
420
|
+
/**
|
|
421
|
+
* Canonical signed byte image of an {@link ArrivalPushV1} — the pushing member's single-member
|
|
422
|
+
* signature, mirroring {@link queryReplySigningPayload}. It binds the topic, epoch, the seeker
|
|
423
|
+
* registration the push is addressed to, the traffic snapshot, and the providers' participant ids
|
|
424
|
+
* (order-sensitive); the per-entry signatures stay outside it, since the seeker re-validates each entry
|
|
425
|
+
* on its own ({@link verifyProviderEntry}).
|
|
426
|
+
*/
|
|
427
|
+
export function arrivalPushSigningPayload(unsigned) {
|
|
428
|
+
return utf8Encoder.encode(JSON.stringify([
|
|
429
|
+
"ArrivalPushV1",
|
|
430
|
+
unsigned.v,
|
|
431
|
+
unsigned.topicId,
|
|
432
|
+
unsigned.cohortEpoch,
|
|
433
|
+
unsigned.correlationId,
|
|
434
|
+
topicTrafficImage(unsigned.topicTraffic),
|
|
435
|
+
unsigned.providers.map((p) => p.participantId),
|
|
436
|
+
]));
|
|
437
|
+
}
|
|
438
|
+
/** The traffic snapshot as an explicitly ordered array, shared by the single-member signing images. */
|
|
439
|
+
function topicTrafficImage(t) {
|
|
440
|
+
return [t.windowSeconds, t.arrivalsPerMin, t.queriesPerMin, t.directParticipants, t.childCohortCount];
|
|
441
|
+
}
|
|
374
442
|
// --- aggregate-count log-bucketing + canonical threshold-signing image (multi-cohort sweep) ---
|
|
375
443
|
/**
|
|
376
444
|
* Log-bucket a raw provider count for an {@link AggregateCountV1} bucket: the largest power of two
|