@optimystic/db-core 1.5.0 → 1.5.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/README.md +336 -336
- package/dist/src/collection/collection.d.ts +44 -4
- package/dist/src/collection/collection.d.ts.map +1 -1
- package/dist/src/collection/collection.js +95 -14
- package/dist/src/collection/collection.js.map +1 -1
- package/dist/src/log/log.d.ts +41 -8
- package/dist/src/log/log.d.ts.map +1 -1
- package/dist/src/log/log.js +15 -10
- package/dist/src/log/log.js.map +1 -1
- package/dist/src/testing/test-transactor.d.ts +36 -0
- package/dist/src/testing/test-transactor.d.ts.map +1 -1
- package/dist/src/testing/test-transactor.js +49 -0
- package/dist/src/testing/test-transactor.js.map +1 -1
- package/dist/src/transaction/coordinator.d.ts.map +1 -1
- package/dist/src/transaction/coordinator.js +26 -9
- package/dist/src/transaction/coordinator.js.map +1 -1
- package/package.json +1 -1
- package/src/blocks/block-store.ts +31 -31
- package/src/blocks/block-types.ts +11 -11
- package/src/blocks/index.ts +5 -5
- package/src/blocks/structs.ts +17 -17
- package/src/btree/btree.ts +872 -872
- package/src/btree/independent-trunk.ts +53 -53
- package/src/btree/index.ts +5 -5
- package/src/btree/key-range.ts +15 -15
- package/src/btree/keyset.ts +6 -6
- package/src/btree/nodes.ts +25 -25
- package/src/btree/path.ts +37 -37
- package/src/btree/tree-block.ts +11 -11
- package/src/btree/trunk.ts +14 -14
- package/src/chain/chain-nodes.ts +26 -26
- package/src/chain/chain.ts +349 -349
- package/src/chain/index.ts +3 -3
- package/src/cluster/i-cluster.ts +6 -6
- package/src/cluster/index.ts +3 -3
- package/src/cohort-topic/addressing.ts +120 -120
- package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
- package/src/cohort-topic/antidos/index.ts +5 -5
- package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
- package/src/cohort-topic/antidos/replay-guard.ts +146 -146
- package/src/cohort-topic/antidos/topic-budget.ts +160 -160
- package/src/cohort-topic/antiflood/index.ts +2 -2
- package/src/cohort-topic/antiflood/invariants.ts +108 -108
- package/src/cohort-topic/antiflood/jitter.ts +117 -117
- package/src/cohort-topic/coldstart.ts +237 -237
- package/src/cohort-topic/dmax.ts +88 -88
- package/src/cohort-topic/gossip/bus.ts +254 -254
- package/src/cohort-topic/gossip/index.ts +3 -3
- package/src/cohort-topic/gossip/records.ts +45 -45
- package/src/cohort-topic/gossip/view.ts +91 -91
- package/src/cohort-topic/index.ts +20 -20
- package/src/cohort-topic/load/barometer.ts +134 -134
- package/src/cohort-topic/load/index.ts +1 -1
- package/src/cohort-topic/member-engine.ts +430 -430
- package/src/cohort-topic/membership/index.ts +3 -3
- package/src/cohort-topic/membership/publisher.ts +163 -163
- package/src/cohort-topic/membership/source.ts +41 -41
- package/src/cohort-topic/ports.ts +157 -157
- package/src/cohort-topic/promotion.ts +477 -477
- package/src/cohort-topic/registration/bytes.ts +37 -37
- package/src/cohort-topic/registration/handoff.ts +154 -154
- package/src/cohort-topic/registration/index.ts +6 -6
- package/src/cohort-topic/registration/renewal.ts +495 -495
- package/src/cohort-topic/registration/sharding.ts +61 -61
- package/src/cohort-topic/registration/store.ts +81 -81
- package/src/cohort-topic/registration/types.ts +91 -91
- package/src/cohort-topic/ring-hash.ts +50 -50
- package/src/cohort-topic/service.ts +416 -416
- package/src/cohort-topic/sig/index.ts +2 -2
- package/src/cohort-topic/sig/payloads.ts +59 -59
- package/src/cohort-topic/sig/threshold.ts +64 -64
- package/src/cohort-topic/tiers.ts +74 -74
- package/src/cohort-topic/traffic.ts +233 -233
- package/src/cohort-topic/walk.ts +326 -326
- package/src/cohort-topic/willingness.ts +237 -237
- package/src/cohort-topic/wire/index.ts +18 -18
- package/src/cohort-topic/wire/payloads.ts +126 -126
- package/src/collection/action.ts +48 -48
- package/src/collection/collection-type-registry.ts +37 -37
- package/src/collection/collection.ts +2203 -2118
- package/src/collection/index.ts +4 -4
- package/src/collections/diary/index.ts +2 -2
- package/src/collections/diary/struct.ts +3 -3
- package/src/collections/index.ts +2 -2
- package/src/collections/tree/collection-trunk.ts +25 -25
- package/src/collections/tree/index.ts +2 -2
- package/src/collections/tree/readme.md +55 -55
- package/src/log/index.ts +2 -2
- package/src/log/log.ts +304 -268
- package/src/log/struct.ts +165 -165
- package/src/matchmaking/capability-filter.ts +45 -45
- package/src/matchmaking/config.ts +98 -98
- package/src/matchmaking/index.ts +21 -21
- package/src/matchmaking/multi-cohort-seeker.ts +234 -234
- package/src/matchmaking/provider.ts +123 -123
- package/src/matchmaking/query-eval.ts +105 -105
- package/src/matchmaking/seeker-walk.ts +127 -127
- package/src/matchmaking/seeker.ts +86 -86
- package/src/matchmaking/topic-anchor.ts +90 -90
- package/src/matchmaking/voting-quorum.ts +394 -394
- package/src/network/i-peer-network.ts +25 -25
- package/src/network/repo-protocol.ts +13 -13
- package/src/network/types.ts +37 -37
- package/src/reactivity/backfill.ts +220 -220
- package/src/reactivity/backpressure.ts +191 -191
- package/src/reactivity/checkpoint.ts +308 -308
- package/src/reactivity/config.ts +172 -172
- package/src/reactivity/dedupe.ts +132 -132
- package/src/reactivity/forwarder.ts +87 -87
- package/src/reactivity/index.ts +34 -34
- package/src/reactivity/notification.ts +123 -123
- package/src/reactivity/policy.ts +79 -79
- package/src/reactivity/push-state.ts +310 -310
- package/src/reactivity/recover.ts +153 -153
- package/src/reactivity/replay-buffer.ts +141 -141
- package/src/reactivity/resume.ts +549 -549
- package/src/reactivity/rotation.ts +415 -415
- package/src/reactivity/subscriber.ts +132 -132
- package/src/reactivity/subscription.ts +66 -66
- package/src/reactivity/topic-anchor.ts +71 -71
- package/src/reactivity/verify.ts +73 -73
- package/src/reactivity/wire-validate.ts +13 -13
- package/src/testing/async-wait.ts +65 -65
- package/src/testing/index.ts +2 -2
- package/src/testing/test-transactor.ts +62 -0
- package/src/transaction/actions-engine.ts +68 -68
- package/src/transaction/coordinator.ts +28 -11
- package/src/transaction/index.ts +52 -52
- package/src/transaction/operations-hash.ts +196 -196
- package/src/transaction/read-dependency-collector.ts +78 -78
- package/src/transaction/session.ts +238 -238
- package/src/transaction/transaction.ts +442 -442
- package/src/transaction/validator.ts +197 -197
- package/src/transactor/block-floors.ts +126 -126
- package/src/transactor/index.ts +6 -6
- package/src/transactor/network-transactor.ts +1545 -1545
- package/src/transform/atomic-proxy.ts +92 -92
- package/src/transform/cache-source.ts +370 -370
- package/src/transform/helpers.ts +164 -164
- package/src/transform/index.ts +7 -7
- package/src/transform/struct.ts +21 -21
- package/src/utility/actor.ts +62 -62
- package/src/utility/backoff.ts +95 -95
- package/src/utility/batch-coordinator.ts +191 -191
- package/src/utility/ensured.ts +32 -32
- package/src/utility/groupby.ts +18 -18
- package/src/utility/hash-string.ts +14 -14
- package/src/utility/is-record-empty.ts +5 -5
- package/src/utility/latches.ts +42 -42
- package/src/utility/lru-map.ts +60 -60
- package/src/utility/nameof.ts +7 -7
- package/src/utility/pending.ts +43 -43
package/src/reactivity/verify.ts
CHANGED
|
@@ -1,73 +1,73 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Reactivity — subscriber/forwarder notification verification seam
|
|
3
|
-
* (`docs/reactivity.md` §Propagation, §Delivery, §Authentication).
|
|
4
|
-
*
|
|
5
|
-
* A forwarder and a subscriber both verify a notification's threshold signature against the **tail
|
|
6
|
-
* cohort's** `MembershipCertV1` before trusting it — forwarders never re-sign, so the same end-to-end
|
|
7
|
-
* signature is verified regardless of hop count. The standard cohort-topic membership-snapshot path
|
|
8
|
-
* ({@link MembershipVerifier}) already provides the **one fetch-and-retry** on a stale/missing cached
|
|
9
|
-
* cert, so this module is a thin adapter: derive the tail cohort's `coord_0(_, topicId)` from the
|
|
10
|
-
* notification's `tailId`, then hand `(signers, coord, tier, digest, sig)` to the verifier.
|
|
11
|
-
*
|
|
12
|
-
* The signed payload is the commit `digest` (the commit cert's threshold signature is over the commit
|
|
13
|
-
* hash — see {@link import("./notification.js").buildNotificationV1}). `signers` arrive base64url-encoded
|
|
14
|
-
* as the cohort member-id bytes the verifier compares against `cert.members`; a custom `signersToBytes`
|
|
15
|
-
* seam is exposed for bindings that carry signers in a different encoding.
|
|
16
|
-
*/
|
|
17
|
-
|
|
18
|
-
import { createTierAddressing, DEFAULT_FANOUT } from "../cohort-topic/addressing.js";
|
|
19
|
-
import { createRingHash } from "../cohort-topic/ring-hash.js";
|
|
20
|
-
import { b64urlToBytes } from "../cohort-topic/wire/codec.js";
|
|
21
|
-
import { Tier } from "../cohort-topic/tiers.js";
|
|
22
|
-
import type { IRingHash } from "../cohort-topic/ports.js";
|
|
23
|
-
import type { MembershipVerifier, VerifyResult } from "../cohort-topic/membership/verifier.js";
|
|
24
|
-
import { reactivityTopicId } from "./topic-anchor.js";
|
|
25
|
-
import type { NotificationV1 } from "./wire.js";
|
|
26
|
-
|
|
27
|
-
/** Verifies a {@link NotificationV1}'s threshold signature against the tail cohort's membership. */
|
|
28
|
-
export interface NotificationVerifier {
|
|
29
|
-
/** `"verified"` iff `sig` is a valid `≥ minSigs` cohort signature over the commit digest. */
|
|
30
|
-
verify(n: NotificationV1): Promise<VerifyResult>;
|
|
31
|
-
}
|
|
32
|
-
|
|
33
|
-
/** Construction inputs for the default {@link NotificationVerifier}. */
|
|
34
|
-
export interface NotificationVerifierDeps {
|
|
35
|
-
/** The cohort-topic participant-side membership verifier (owns the one fetch-and-retry). */
|
|
36
|
-
readonly verifier: MembershipVerifier;
|
|
37
|
-
/** Ring hash for `topicId` / `coord_0` derivation. Default db-core 256-bit SHA-256. */
|
|
38
|
-
readonly hash?: IRingHash;
|
|
39
|
-
/** Fan-out `F` for tier addressing. Default {@link DEFAULT_FANOUT}. */
|
|
40
|
-
readonly fanout?: number;
|
|
41
|
-
/** Reactivity runs at T3; overridable for tests. */
|
|
42
|
-
readonly tier?: Tier;
|
|
43
|
-
/** Map a wire signer string to the verifier's member-id bytes. Default base64url decode. */
|
|
44
|
-
readonly signersToBytes?: (signer: string) => Uint8Array;
|
|
45
|
-
}
|
|
46
|
-
|
|
47
|
-
class MembershipNotificationVerifier implements NotificationVerifier {
|
|
48
|
-
private readonly addressing: ReturnType<typeof createTierAddressing>;
|
|
49
|
-
private readonly hash: IRingHash;
|
|
50
|
-
private readonly tier: Tier;
|
|
51
|
-
private readonly signersToBytes: (signer: string) => Uint8Array;
|
|
52
|
-
|
|
53
|
-
constructor(private readonly deps: NotificationVerifierDeps) {
|
|
54
|
-
this.hash = deps.hash ?? createRingHash();
|
|
55
|
-
this.addressing = createTierAddressing(this.hash, deps.fanout ?? DEFAULT_FANOUT);
|
|
56
|
-
this.tier = deps.tier ?? Tier.T3;
|
|
57
|
-
this.signersToBytes = deps.signersToBytes ?? b64urlToBytes;
|
|
58
|
-
}
|
|
59
|
-
|
|
60
|
-
async verify(n: NotificationV1): Promise<VerifyResult> {
|
|
61
|
-
const topicId = reactivityTopicId(b64urlToBytes(n.tailId), this.hash);
|
|
62
|
-
const expectedCoord = this.addressing.coord0(topicId);
|
|
63
|
-
const signers = n.signers.map(this.signersToBytes);
|
|
64
|
-
const payload = b64urlToBytes(n.digest);
|
|
65
|
-
const sig = b64urlToBytes(n.sig);
|
|
66
|
-
return this.deps.verifier.verifyMessage(signers, expectedCoord, this.tier, payload, sig);
|
|
67
|
-
}
|
|
68
|
-
}
|
|
69
|
-
|
|
70
|
-
/** Build the default {@link NotificationVerifier} over the cohort-topic {@link MembershipVerifier}. */
|
|
71
|
-
export function createNotificationVerifier(deps: NotificationVerifierDeps): NotificationVerifier {
|
|
72
|
-
return new MembershipNotificationVerifier(deps);
|
|
73
|
-
}
|
|
1
|
+
/**
|
|
2
|
+
* Reactivity — subscriber/forwarder notification verification seam
|
|
3
|
+
* (`docs/reactivity.md` §Propagation, §Delivery, §Authentication).
|
|
4
|
+
*
|
|
5
|
+
* A forwarder and a subscriber both verify a notification's threshold signature against the **tail
|
|
6
|
+
* cohort's** `MembershipCertV1` before trusting it — forwarders never re-sign, so the same end-to-end
|
|
7
|
+
* signature is verified regardless of hop count. The standard cohort-topic membership-snapshot path
|
|
8
|
+
* ({@link MembershipVerifier}) already provides the **one fetch-and-retry** on a stale/missing cached
|
|
9
|
+
* cert, so this module is a thin adapter: derive the tail cohort's `coord_0(_, topicId)` from the
|
|
10
|
+
* notification's `tailId`, then hand `(signers, coord, tier, digest, sig)` to the verifier.
|
|
11
|
+
*
|
|
12
|
+
* The signed payload is the commit `digest` (the commit cert's threshold signature is over the commit
|
|
13
|
+
* hash — see {@link import("./notification.js").buildNotificationV1}). `signers` arrive base64url-encoded
|
|
14
|
+
* as the cohort member-id bytes the verifier compares against `cert.members`; a custom `signersToBytes`
|
|
15
|
+
* seam is exposed for bindings that carry signers in a different encoding.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
import { createTierAddressing, DEFAULT_FANOUT } from "../cohort-topic/addressing.js";
|
|
19
|
+
import { createRingHash } from "../cohort-topic/ring-hash.js";
|
|
20
|
+
import { b64urlToBytes } from "../cohort-topic/wire/codec.js";
|
|
21
|
+
import { Tier } from "../cohort-topic/tiers.js";
|
|
22
|
+
import type { IRingHash } from "../cohort-topic/ports.js";
|
|
23
|
+
import type { MembershipVerifier, VerifyResult } from "../cohort-topic/membership/verifier.js";
|
|
24
|
+
import { reactivityTopicId } from "./topic-anchor.js";
|
|
25
|
+
import type { NotificationV1 } from "./wire.js";
|
|
26
|
+
|
|
27
|
+
/** Verifies a {@link NotificationV1}'s threshold signature against the tail cohort's membership. */
|
|
28
|
+
export interface NotificationVerifier {
|
|
29
|
+
/** `"verified"` iff `sig` is a valid `≥ minSigs` cohort signature over the commit digest. */
|
|
30
|
+
verify(n: NotificationV1): Promise<VerifyResult>;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/** Construction inputs for the default {@link NotificationVerifier}. */
|
|
34
|
+
export interface NotificationVerifierDeps {
|
|
35
|
+
/** The cohort-topic participant-side membership verifier (owns the one fetch-and-retry). */
|
|
36
|
+
readonly verifier: MembershipVerifier;
|
|
37
|
+
/** Ring hash for `topicId` / `coord_0` derivation. Default db-core 256-bit SHA-256. */
|
|
38
|
+
readonly hash?: IRingHash;
|
|
39
|
+
/** Fan-out `F` for tier addressing. Default {@link DEFAULT_FANOUT}. */
|
|
40
|
+
readonly fanout?: number;
|
|
41
|
+
/** Reactivity runs at T3; overridable for tests. */
|
|
42
|
+
readonly tier?: Tier;
|
|
43
|
+
/** Map a wire signer string to the verifier's member-id bytes. Default base64url decode. */
|
|
44
|
+
readonly signersToBytes?: (signer: string) => Uint8Array;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
class MembershipNotificationVerifier implements NotificationVerifier {
|
|
48
|
+
private readonly addressing: ReturnType<typeof createTierAddressing>;
|
|
49
|
+
private readonly hash: IRingHash;
|
|
50
|
+
private readonly tier: Tier;
|
|
51
|
+
private readonly signersToBytes: (signer: string) => Uint8Array;
|
|
52
|
+
|
|
53
|
+
constructor(private readonly deps: NotificationVerifierDeps) {
|
|
54
|
+
this.hash = deps.hash ?? createRingHash();
|
|
55
|
+
this.addressing = createTierAddressing(this.hash, deps.fanout ?? DEFAULT_FANOUT);
|
|
56
|
+
this.tier = deps.tier ?? Tier.T3;
|
|
57
|
+
this.signersToBytes = deps.signersToBytes ?? b64urlToBytes;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
async verify(n: NotificationV1): Promise<VerifyResult> {
|
|
61
|
+
const topicId = reactivityTopicId(b64urlToBytes(n.tailId), this.hash);
|
|
62
|
+
const expectedCoord = this.addressing.coord0(topicId);
|
|
63
|
+
const signers = n.signers.map(this.signersToBytes);
|
|
64
|
+
const payload = b64urlToBytes(n.digest);
|
|
65
|
+
const sig = b64urlToBytes(n.sig);
|
|
66
|
+
return this.deps.verifier.verifyMessage(signers, expectedCoord, this.tier, payload, sig);
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** Build the default {@link NotificationVerifier} over the cohort-topic {@link MembershipVerifier}. */
|
|
71
|
+
export function createNotificationVerifier(deps: NotificationVerifierDeps): NotificationVerifier {
|
|
72
|
+
return new MembershipNotificationVerifier(deps);
|
|
73
|
+
}
|
|
@@ -1,13 +1,13 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Reactivity — shared wire-validation primitives.
|
|
3
|
-
*
|
|
4
|
-
* The reactivity message codecs ({@link import("./wire.js")}, {@link import("./push-state.js")},
|
|
5
|
-
* {@link import("./backfill.js")}, {@link import("./resume.js")}, plus checkpoint / rotation / recover)
|
|
6
|
-
* decode untrusted JSON into validated V1 shapes with the same structural checks the rest of the
|
|
7
|
-
* substrate uses. Those generic primitives now live in one place —
|
|
8
|
-
* {@link import("../cohort-topic/wire/primitives.js")} — so a hardening tweak lands once; this module is
|
|
9
|
-
* a thin re-export kept so the reactivity codecs import from a sibling path. Every helper throws
|
|
10
|
-
* {@link CohortWireError} on a defect (base64url byte fields, finite/integer numbers, `v: 1`).
|
|
11
|
-
*/
|
|
12
|
-
|
|
13
|
-
export * from "../cohort-topic/wire/primitives.js";
|
|
1
|
+
/**
|
|
2
|
+
* Reactivity — shared wire-validation primitives.
|
|
3
|
+
*
|
|
4
|
+
* The reactivity message codecs ({@link import("./wire.js")}, {@link import("./push-state.js")},
|
|
5
|
+
* {@link import("./backfill.js")}, {@link import("./resume.js")}, plus checkpoint / rotation / recover)
|
|
6
|
+
* decode untrusted JSON into validated V1 shapes with the same structural checks the rest of the
|
|
7
|
+
* substrate uses. Those generic primitives now live in one place —
|
|
8
|
+
* {@link import("../cohort-topic/wire/primitives.js")} — so a hardening tweak lands once; this module is
|
|
9
|
+
* a thin re-export kept so the reactivity codecs import from a sibling path. Every helper throws
|
|
10
|
+
* {@link CohortWireError} on a defect (base64url byte fields, finite/integer numbers, `v: 1`).
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
export * from "../cohort-topic/wire/primitives.js";
|
|
@@ -1,65 +1,65 @@
|
|
|
1
|
-
export interface WaitForOptions {
|
|
2
|
-
// NOTE: default is tuned for in-process settles; integration callers over real libp2p
|
|
3
|
-
// pass explicit 10k–90k bounds. A new caller that omits timeoutMs gets 2s — fine for
|
|
4
|
-
// fast local conditions, but if a slow CI machine flakes on a legitimately-slow wait,
|
|
5
|
-
// give that call site an explicit timeoutMs rather than raising this default.
|
|
6
|
-
/** Upper bound before the poll gives up. Default 2_000. */
|
|
7
|
-
timeoutMs?: number;
|
|
8
|
-
/** Poll cadence. Default 10. */
|
|
9
|
-
intervalMs?: number;
|
|
10
|
-
/** Included in the thrown message so a failure says WHAT never became true. */
|
|
11
|
-
description?: string;
|
|
12
|
-
}
|
|
13
|
-
|
|
14
|
-
/** Real-time sleep. Retain ONLY for residual cases a condition poll cannot cover. */
|
|
15
|
-
export const delay = (ms: number): Promise<void> =>
|
|
16
|
-
new Promise((resolve) => setTimeout(resolve, ms));
|
|
17
|
-
|
|
18
|
-
/**
|
|
19
|
-
* Poll `predicate` until it returns true or `timeoutMs` elapses; throws on timeout.
|
|
20
|
-
* `predicate` may be sync or async; a thrown/rejected predicate propagates immediately.
|
|
21
|
-
* `undefined` is treated as `false` (not ready yet).
|
|
22
|
-
*/
|
|
23
|
-
export async function waitFor(
|
|
24
|
-
predicate: () => boolean | Promise<boolean>,
|
|
25
|
-
opts?: WaitForOptions,
|
|
26
|
-
): Promise<void> {
|
|
27
|
-
const { timeoutMs = 2_000, intervalMs = 10, description } = opts ?? {};
|
|
28
|
-
const deadline = Date.now() + timeoutMs;
|
|
29
|
-
for (;;) {
|
|
30
|
-
if (await predicate()) return;
|
|
31
|
-
if (Date.now() >= deadline) {
|
|
32
|
-
throw new Error(
|
|
33
|
-
description
|
|
34
|
-
? `waitFor timed out after ${timeoutMs}ms: ${description}`
|
|
35
|
-
: `waitFor timed out after ${timeoutMs}ms`,
|
|
36
|
-
);
|
|
37
|
-
}
|
|
38
|
-
await delay(intervalMs);
|
|
39
|
-
}
|
|
40
|
-
}
|
|
41
|
-
|
|
42
|
-
/**
|
|
43
|
-
* Poll `fn` until it returns a non-undefined value or `timeoutMs` elapses; throws on timeout.
|
|
44
|
-
* `undefined` means "not ready yet" — callers needing to wait for an actual `undefined`
|
|
45
|
-
* should use `waitFor` on a separate flag.
|
|
46
|
-
*/
|
|
47
|
-
export async function waitForValue<T>(
|
|
48
|
-
fn: () => T | undefined | Promise<T | undefined>,
|
|
49
|
-
opts?: WaitForOptions,
|
|
50
|
-
): Promise<T> {
|
|
51
|
-
const { timeoutMs = 2_000, intervalMs = 10, description } = opts ?? {};
|
|
52
|
-
const deadline = Date.now() + timeoutMs;
|
|
53
|
-
for (;;) {
|
|
54
|
-
const value = await fn();
|
|
55
|
-
if (value !== undefined) return value;
|
|
56
|
-
if (Date.now() >= deadline) {
|
|
57
|
-
throw new Error(
|
|
58
|
-
description
|
|
59
|
-
? `waitForValue timed out after ${timeoutMs}ms: ${description}`
|
|
60
|
-
: `waitForValue timed out after ${timeoutMs}ms`,
|
|
61
|
-
);
|
|
62
|
-
}
|
|
63
|
-
await delay(intervalMs);
|
|
64
|
-
}
|
|
65
|
-
}
|
|
1
|
+
export interface WaitForOptions {
|
|
2
|
+
// NOTE: default is tuned for in-process settles; integration callers over real libp2p
|
|
3
|
+
// pass explicit 10k–90k bounds. A new caller that omits timeoutMs gets 2s — fine for
|
|
4
|
+
// fast local conditions, but if a slow CI machine flakes on a legitimately-slow wait,
|
|
5
|
+
// give that call site an explicit timeoutMs rather than raising this default.
|
|
6
|
+
/** Upper bound before the poll gives up. Default 2_000. */
|
|
7
|
+
timeoutMs?: number;
|
|
8
|
+
/** Poll cadence. Default 10. */
|
|
9
|
+
intervalMs?: number;
|
|
10
|
+
/** Included in the thrown message so a failure says WHAT never became true. */
|
|
11
|
+
description?: string;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
/** Real-time sleep. Retain ONLY for residual cases a condition poll cannot cover. */
|
|
15
|
+
export const delay = (ms: number): Promise<void> =>
|
|
16
|
+
new Promise((resolve) => setTimeout(resolve, ms));
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* Poll `predicate` until it returns true or `timeoutMs` elapses; throws on timeout.
|
|
20
|
+
* `predicate` may be sync or async; a thrown/rejected predicate propagates immediately.
|
|
21
|
+
* `undefined` is treated as `false` (not ready yet).
|
|
22
|
+
*/
|
|
23
|
+
export async function waitFor(
|
|
24
|
+
predicate: () => boolean | Promise<boolean>,
|
|
25
|
+
opts?: WaitForOptions,
|
|
26
|
+
): Promise<void> {
|
|
27
|
+
const { timeoutMs = 2_000, intervalMs = 10, description } = opts ?? {};
|
|
28
|
+
const deadline = Date.now() + timeoutMs;
|
|
29
|
+
for (;;) {
|
|
30
|
+
if (await predicate()) return;
|
|
31
|
+
if (Date.now() >= deadline) {
|
|
32
|
+
throw new Error(
|
|
33
|
+
description
|
|
34
|
+
? `waitFor timed out after ${timeoutMs}ms: ${description}`
|
|
35
|
+
: `waitFor timed out after ${timeoutMs}ms`,
|
|
36
|
+
);
|
|
37
|
+
}
|
|
38
|
+
await delay(intervalMs);
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* Poll `fn` until it returns a non-undefined value or `timeoutMs` elapses; throws on timeout.
|
|
44
|
+
* `undefined` means "not ready yet" — callers needing to wait for an actual `undefined`
|
|
45
|
+
* should use `waitFor` on a separate flag.
|
|
46
|
+
*/
|
|
47
|
+
export async function waitForValue<T>(
|
|
48
|
+
fn: () => T | undefined | Promise<T | undefined>,
|
|
49
|
+
opts?: WaitForOptions,
|
|
50
|
+
): Promise<T> {
|
|
51
|
+
const { timeoutMs = 2_000, intervalMs = 10, description } = opts ?? {};
|
|
52
|
+
const deadline = Date.now() + timeoutMs;
|
|
53
|
+
for (;;) {
|
|
54
|
+
const value = await fn();
|
|
55
|
+
if (value !== undefined) return value;
|
|
56
|
+
if (Date.now() >= deadline) {
|
|
57
|
+
throw new Error(
|
|
58
|
+
description
|
|
59
|
+
? `waitForValue timed out after ${timeoutMs}ms: ${description}`
|
|
60
|
+
: `waitForValue timed out after ${timeoutMs}ms`,
|
|
61
|
+
);
|
|
62
|
+
}
|
|
63
|
+
await delay(intervalMs);
|
|
64
|
+
}
|
|
65
|
+
}
|
package/src/testing/index.ts
CHANGED
|
@@ -1,3 +1,3 @@
|
|
|
1
|
-
export * from './test-transactor.js';
|
|
2
|
-
export * from './async-wait.js';
|
|
1
|
+
export * from './test-transactor.js';
|
|
2
|
+
export * from './async-wait.js';
|
|
3
3
|
export * from './refresh-probe.js';
|
|
@@ -676,6 +676,68 @@ export class TailLandsButReportsStale extends DelegatingTransactor {
|
|
|
676
676
|
}
|
|
677
677
|
}
|
|
678
678
|
|
|
679
|
+
/** What one attempt of a write put on the wire: the pend's transforms, with the action id and
|
|
680
|
+
* revision it was pended under. Recorded by {@link RecordsAttemptsRefusesFirstCommit}. */
|
|
681
|
+
export type RecordedAttempt = {
|
|
682
|
+
actionId: ActionId;
|
|
683
|
+
rev?: number;
|
|
684
|
+
transforms: Transforms;
|
|
685
|
+
};
|
|
686
|
+
|
|
687
|
+
/**
|
|
688
|
+
* Records what every attempt of a write pends, and refuses the FIRST commit outright — nothing is
|
|
689
|
+
* delegated, so nothing lands and the retry's refresh cannot find the write's own log entry.
|
|
690
|
+
*
|
|
691
|
+
* That is the case `Collection.completeOwnEntry` does NOT reach: the refused commit left the log
|
|
692
|
+
* block (and, for a brand-new collection, the header) uncommitted, so the refresh has no entry to
|
|
693
|
+
* finish from and the retry REBUILDS its log append from scratch. Storage identifies a saved block
|
|
694
|
+
* revision by `(action id, revision)` and deliberately accepts a retry of the same action at the
|
|
695
|
+
* same revision, so any per-attempt value in that rebuild becomes two contents under one
|
|
696
|
+
* `(action, revision)` across the machines that landed different attempts.
|
|
697
|
+
*
|
|
698
|
+
* `attempts` is therefore asserted on WHOLE — not field by field — so the rule it pins ("a retry at
|
|
699
|
+
* the same revision sends byte-identical transforms") fails for any future per-attempt value, not
|
|
700
|
+
* only the ones known today. Transforms are cloned on the way in, since the caller keeps mutating
|
|
701
|
+
* the live tracker afterwards.
|
|
702
|
+
*
|
|
703
|
+
* Lives here beside {@link CommitLandsButReportsStale} for the reason that one gives: the
|
|
704
|
+
* collection-path and coordinator-path specs must not drift apart on the double they share.
|
|
705
|
+
*/
|
|
706
|
+
export class RecordsAttemptsRefusesFirstCommit extends DelegatingTransactor {
|
|
707
|
+
readonly attempts: RecordedAttempt[] = [];
|
|
708
|
+
private refusals: number;
|
|
709
|
+
|
|
710
|
+
constructor(inner: TestTransactor, refusals = 1) {
|
|
711
|
+
super(inner);
|
|
712
|
+
this.refusals = refusals;
|
|
713
|
+
}
|
|
714
|
+
|
|
715
|
+
/** Arm (or re-arm) the refusal counter, so a test can let its setup writes land cleanly and
|
|
716
|
+
* then refuse only the write under test. Replaces whatever is left of the current count. */
|
|
717
|
+
refuseNextCommits(count: number): void {
|
|
718
|
+
this.refusals = count;
|
|
719
|
+
}
|
|
720
|
+
|
|
721
|
+
override async pend(request: PendRequest): Promise<PendResult> {
|
|
722
|
+
this.attempts.push({
|
|
723
|
+
actionId: request.actionId,
|
|
724
|
+
rev: request.rev,
|
|
725
|
+
transforms: structuredClone(request.transforms),
|
|
726
|
+
});
|
|
727
|
+
return this.inner.pend(request);
|
|
728
|
+
}
|
|
729
|
+
|
|
730
|
+
override async commit(request: CommitRequest): Promise<CommitResult> {
|
|
731
|
+
if (this.refusals > 0) {
|
|
732
|
+
this.refusals--;
|
|
733
|
+
// Never delegated: nothing of this attempt is durable, so `TransactorSource.transact`
|
|
734
|
+
// cancels the pend and the writer re-drives at the same action id and revision.
|
|
735
|
+
return { success: false, conflict: true, reason: 'stale commit: injected refusal, nothing landed' };
|
|
736
|
+
}
|
|
737
|
+
return this.inner.commit(request);
|
|
738
|
+
}
|
|
739
|
+
}
|
|
740
|
+
|
|
679
741
|
/** A competing writer: a real write driven against the UNWRAPPED transactor, so its own
|
|
680
742
|
* pend/commit calls are invisible to {@link CompetingWriterTransactor}'s counters and cannot
|
|
681
743
|
* re-trigger the interception. See {@link commitRivalTreeWrite} for the usual implementation. */
|
|
@@ -1,68 +1,68 @@
|
|
|
1
|
-
import type { ITransactionEngine, Transaction, ExecutionResult, CollectionActions } from './transaction.js';
|
|
2
|
-
|
|
3
|
-
export const ACTIONS_ENGINE_ID = "actions@1.0.0";
|
|
4
|
-
|
|
5
|
-
/**
|
|
6
|
-
* Built-in action-based transaction engine for testing.
|
|
7
|
-
*
|
|
8
|
-
* This engine treats each statement as a JSON-encoded CollectionActions object.
|
|
9
|
-
* It's useful for testing the transaction infrastructure without needing SQL.
|
|
10
|
-
*
|
|
11
|
-
* This is a PURE TRANSLATOR (model (a) of the {@link ITransactionEngine} contract):
|
|
12
|
-
* execute() parses statements into CollectionActions[] and RETURNS them. It never
|
|
13
|
-
* touches a coordinator or mutates any collection state — application is the sole
|
|
14
|
-
* responsibility of the session/coordinator that receives the returned actions.
|
|
15
|
-
*
|
|
16
|
-
* Each statement format:
|
|
17
|
-
* ```json
|
|
18
|
-
* {
|
|
19
|
-
* "collectionId": "users",
|
|
20
|
-
* "actions": [
|
|
21
|
-
* { "type": "insert", "data": { "id": 1, "name": "Alice" } }
|
|
22
|
-
* ]
|
|
23
|
-
* }
|
|
24
|
-
* ```
|
|
25
|
-
*/
|
|
26
|
-
export class ActionsEngine implements ITransactionEngine {
|
|
27
|
-
readonly id = ACTIONS_ENGINE_ID;
|
|
28
|
-
|
|
29
|
-
async execute(transaction: Transaction): Promise<ExecutionResult> {
|
|
30
|
-
try {
|
|
31
|
-
// Parse each statement as a CollectionActions object
|
|
32
|
-
const allActions: CollectionActions[] = [];
|
|
33
|
-
|
|
34
|
-
for (const statement of transaction.statements) {
|
|
35
|
-
const collectionActions = JSON.parse(statement) as CollectionActions;
|
|
36
|
-
|
|
37
|
-
// Validate structure
|
|
38
|
-
if (!collectionActions.collectionId || typeof collectionActions.collectionId !== 'string') {
|
|
39
|
-
return {
|
|
40
|
-
success: false,
|
|
41
|
-
error: 'Invalid statement: missing collectionId'
|
|
42
|
-
};
|
|
43
|
-
}
|
|
44
|
-
|
|
45
|
-
if (!collectionActions.actions || !Array.isArray(collectionActions.actions)) {
|
|
46
|
-
return {
|
|
47
|
-
success: false,
|
|
48
|
-
error: `Invalid statement: collection ${collectionActions.collectionId} missing or invalid actions array`
|
|
49
|
-
};
|
|
50
|
-
}
|
|
51
|
-
|
|
52
|
-
allActions.push(collectionActions);
|
|
53
|
-
}
|
|
54
|
-
|
|
55
|
-
// Pure translation: return parsed actions WITHOUT applying them. The caller
|
|
56
|
-
// (session.execute / coordinator.execute) applies them exactly once.
|
|
57
|
-
return {
|
|
58
|
-
success: true,
|
|
59
|
-
actions: allActions
|
|
60
|
-
};
|
|
61
|
-
} catch (error) {
|
|
62
|
-
return {
|
|
63
|
-
success: false,
|
|
64
|
-
error: `Failed to execute transaction: ${error instanceof Error ? error.message : String(error)}`
|
|
65
|
-
};
|
|
66
|
-
}
|
|
67
|
-
}
|
|
68
|
-
}
|
|
1
|
+
import type { ITransactionEngine, Transaction, ExecutionResult, CollectionActions } from './transaction.js';
|
|
2
|
+
|
|
3
|
+
export const ACTIONS_ENGINE_ID = "actions@1.0.0";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Built-in action-based transaction engine for testing.
|
|
7
|
+
*
|
|
8
|
+
* This engine treats each statement as a JSON-encoded CollectionActions object.
|
|
9
|
+
* It's useful for testing the transaction infrastructure without needing SQL.
|
|
10
|
+
*
|
|
11
|
+
* This is a PURE TRANSLATOR (model (a) of the {@link ITransactionEngine} contract):
|
|
12
|
+
* execute() parses statements into CollectionActions[] and RETURNS them. It never
|
|
13
|
+
* touches a coordinator or mutates any collection state — application is the sole
|
|
14
|
+
* responsibility of the session/coordinator that receives the returned actions.
|
|
15
|
+
*
|
|
16
|
+
* Each statement format:
|
|
17
|
+
* ```json
|
|
18
|
+
* {
|
|
19
|
+
* "collectionId": "users",
|
|
20
|
+
* "actions": [
|
|
21
|
+
* { "type": "insert", "data": { "id": 1, "name": "Alice" } }
|
|
22
|
+
* ]
|
|
23
|
+
* }
|
|
24
|
+
* ```
|
|
25
|
+
*/
|
|
26
|
+
export class ActionsEngine implements ITransactionEngine {
|
|
27
|
+
readonly id = ACTIONS_ENGINE_ID;
|
|
28
|
+
|
|
29
|
+
async execute(transaction: Transaction): Promise<ExecutionResult> {
|
|
30
|
+
try {
|
|
31
|
+
// Parse each statement as a CollectionActions object
|
|
32
|
+
const allActions: CollectionActions[] = [];
|
|
33
|
+
|
|
34
|
+
for (const statement of transaction.statements) {
|
|
35
|
+
const collectionActions = JSON.parse(statement) as CollectionActions;
|
|
36
|
+
|
|
37
|
+
// Validate structure
|
|
38
|
+
if (!collectionActions.collectionId || typeof collectionActions.collectionId !== 'string') {
|
|
39
|
+
return {
|
|
40
|
+
success: false,
|
|
41
|
+
error: 'Invalid statement: missing collectionId'
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
if (!collectionActions.actions || !Array.isArray(collectionActions.actions)) {
|
|
46
|
+
return {
|
|
47
|
+
success: false,
|
|
48
|
+
error: `Invalid statement: collection ${collectionActions.collectionId} missing or invalid actions array`
|
|
49
|
+
};
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
allActions.push(collectionActions);
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
// Pure translation: return parsed actions WITHOUT applying them. The caller
|
|
56
|
+
// (session.execute / coordinator.execute) applies them exactly once.
|
|
57
|
+
return {
|
|
58
|
+
success: true,
|
|
59
|
+
actions: allActions
|
|
60
|
+
};
|
|
61
|
+
} catch (error) {
|
|
62
|
+
return {
|
|
63
|
+
success: false,
|
|
64
|
+
error: `Failed to execute transaction: ${error instanceof Error ? error.message : String(error)}`
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
}
|
|
@@ -415,9 +415,12 @@ export class TransactionCoordinator {
|
|
|
415
415
|
// A participant whose log tail landed despite the reported loss finds its own entry
|
|
416
416
|
// here and FINISHES that action before consuming it (Collection.completeOwnEntry,
|
|
417
417
|
// from the attempt commitOnceLatched retained). When finishing is refused for a cause
|
|
418
|
-
// that can clear, the refresh — not the commit — is what gets retried:
|
|
419
|
-
//
|
|
420
|
-
//
|
|
418
|
+
// that can clear, the refresh — not the commit — is what gets retried: the
|
|
419
|
+
// participant's log entry is already durable, and once a refresh adopts a newer
|
|
420
|
+
// revision commitOnce appends a SECOND entry under this transaction's id. (At an
|
|
421
|
+
// unchanged revision the re-append is byte-identical — see
|
|
422
|
+
// Collection.logAppendBlockIds — so what is at stake is the duplicate entry, not two
|
|
423
|
+
// versions of one tail block.)
|
|
421
424
|
// Each such round counts against the same budget as a stale loss; a permanent
|
|
422
425
|
// refusal (a rival holds the revision) escapes as the named TornActionError at once.
|
|
423
426
|
// Re-refreshing collections an earlier round already refreshed is a no-op.
|
|
@@ -1323,8 +1326,27 @@ export class TransactionCoordinator {
|
|
|
1323
1326
|
// Get transforms from the collection's tracker
|
|
1324
1327
|
const transforms = collection.tracker.transforms;
|
|
1325
1328
|
|
|
1326
|
-
//
|
|
1327
|
-
const
|
|
1329
|
+
// Generate action ID from transaction ID
|
|
1330
|
+
const actionId = transaction.id;
|
|
1331
|
+
const newRev = collection.getNextRev();
|
|
1332
|
+
|
|
1333
|
+
// Write actions to the collection's log to get the log tail block ID. The append must be a
|
|
1334
|
+
// fixed function of this write and the revision it requests, because a refused commit is
|
|
1335
|
+
// retried under the same action id and — when nothing else committed in between — at the
|
|
1336
|
+
// same revision, and storage keys a saved block revision by `(action id, revision)`. So any
|
|
1337
|
+
// data block the append mints takes the id an earlier attempt at this revision minted
|
|
1338
|
+
// (Collection.logAppendBlockIds), and the entry is stamped with the transaction's own
|
|
1339
|
+
// timestamp, which is fixed at BEGIN and already stable across attempts, rather than with
|
|
1340
|
+
// the time of the attempt.
|
|
1341
|
+
//
|
|
1342
|
+
// NOTE: execute() reaches this method without marking its transaction in flight, so it mints
|
|
1343
|
+
// afresh every time — correct today, because it re-runs the engine and re-stages, so a
|
|
1344
|
+
// re-drive of it is a DIFFERENT write, and because nothing re-drives it under one transaction
|
|
1345
|
+
// (it returns its failure rather than looping). If execute() ever grows a retry that reuses
|
|
1346
|
+
// the transaction id, it must mark each participant in flight the way commitOnce does, or it
|
|
1347
|
+
// reintroduces exactly the divergence logAppendBlockIds closes.
|
|
1348
|
+
const log = await Log.open(collection.tracker, collectionActions.collectionId,
|
|
1349
|
+
{ newDataBlockId: collection.logAppendBlockIds(collection.tracker, actionId, newRev) });
|
|
1328
1350
|
if (!log) {
|
|
1329
1351
|
return {
|
|
1330
1352
|
success: false,
|
|
@@ -1332,10 +1354,6 @@ export class TransactionCoordinator {
|
|
|
1332
1354
|
};
|
|
1333
1355
|
}
|
|
1334
1356
|
|
|
1335
|
-
// Generate action ID from transaction ID
|
|
1336
|
-
const actionId = transaction.id;
|
|
1337
|
-
const newRev = collection.getNextRev();
|
|
1338
|
-
|
|
1339
1357
|
// Add actions to log (this updates the tracker with log block changes).
|
|
1340
1358
|
// Persist the transaction's read set on the entry so a later invalidation cascade can
|
|
1341
1359
|
// discover this action's read-dependents (see ActionEntry.reads). The whole transaction's
|
|
@@ -1359,8 +1377,7 @@ export class TransactionCoordinator {
|
|
|
1359
1377
|
actionId,
|
|
1360
1378
|
newRev,
|
|
1361
1379
|
() => blockIdsForTransforms(transforms),
|
|
1362
|
-
allCollectionIds,
|
|
1363
|
-
transaction.reads
|
|
1380
|
+
{ collectionIds: allCollectionIds, reads: transaction.reads, timestamp: transaction.stamp.timestamp }
|
|
1364
1381
|
);
|
|
1365
1382
|
|
|
1366
1383
|
// Return the transforms and log tail block ID
|