@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/transaction/index.ts
CHANGED
|
@@ -1,52 +1,52 @@
|
|
|
1
|
-
export type {
|
|
2
|
-
Transaction,
|
|
3
|
-
TransactionStamp,
|
|
4
|
-
StampFields,
|
|
5
|
-
ReadDependency,
|
|
6
|
-
TransactionRef,
|
|
7
|
-
ITransactionEngine,
|
|
8
|
-
ExecutionResult,
|
|
9
|
-
CollectionActions,
|
|
10
|
-
ValidationResult,
|
|
11
|
-
ITransactionValidator,
|
|
12
|
-
ActionsStatement,
|
|
13
|
-
TransactionSigner,
|
|
14
|
-
ClientSignatureVerifier
|
|
15
|
-
} from './transaction.js';
|
|
16
|
-
|
|
17
|
-
export {
|
|
18
|
-
createTransactionStamp,
|
|
19
|
-
computeStampId,
|
|
20
|
-
createTransactionId,
|
|
21
|
-
createActionsStatements,
|
|
22
|
-
DEFAULT_TRANSACTION_TTL_MS,
|
|
23
|
-
isTransactionExpired,
|
|
24
|
-
clientSignaturePayload,
|
|
25
|
-
CLIENT_SIG_VERSION,
|
|
26
|
-
MaxPriority,
|
|
27
|
-
clampPriority
|
|
28
|
-
} from './transaction.js';
|
|
29
|
-
|
|
30
|
-
export {
|
|
31
|
-
ActionsEngine,
|
|
32
|
-
ACTIONS_ENGINE_ID,
|
|
33
|
-
} from './actions-engine.js';
|
|
34
|
-
|
|
35
|
-
export { ReadDependencyCollector } from './read-dependency-collector.js';
|
|
36
|
-
export { TransactionCoordinator } from './coordinator.js';
|
|
37
|
-
export type { CoordinatorOptions, PendValidationMode } from './coordinator.js';
|
|
38
|
-
export { CoordinatorConcurrentStampError, CoordinatorPartialCommitError, CoordinatorStaleLossError } from './errors.js';
|
|
39
|
-
export { TransactionSession } from './session.js';
|
|
40
|
-
export { TransactionValidator } from './validator.js';
|
|
41
|
-
export type { EngineRegistration, ValidationCoordinatorFactory, BlockStateProvider } from './validator.js';
|
|
42
|
-
|
|
43
|
-
export {
|
|
44
|
-
collectOperations,
|
|
45
|
-
hashOperations,
|
|
46
|
-
canonicalStringify,
|
|
47
|
-
canonicalOperationsPayload,
|
|
48
|
-
opsHashVersion,
|
|
49
|
-
OPS_HASH_VERSION,
|
|
50
|
-
OPS_HASH_PREFIX,
|
|
51
|
-
} from './operations-hash.js';
|
|
52
|
-
export type { Operation } from './operations-hash.js';
|
|
1
|
+
export type {
|
|
2
|
+
Transaction,
|
|
3
|
+
TransactionStamp,
|
|
4
|
+
StampFields,
|
|
5
|
+
ReadDependency,
|
|
6
|
+
TransactionRef,
|
|
7
|
+
ITransactionEngine,
|
|
8
|
+
ExecutionResult,
|
|
9
|
+
CollectionActions,
|
|
10
|
+
ValidationResult,
|
|
11
|
+
ITransactionValidator,
|
|
12
|
+
ActionsStatement,
|
|
13
|
+
TransactionSigner,
|
|
14
|
+
ClientSignatureVerifier
|
|
15
|
+
} from './transaction.js';
|
|
16
|
+
|
|
17
|
+
export {
|
|
18
|
+
createTransactionStamp,
|
|
19
|
+
computeStampId,
|
|
20
|
+
createTransactionId,
|
|
21
|
+
createActionsStatements,
|
|
22
|
+
DEFAULT_TRANSACTION_TTL_MS,
|
|
23
|
+
isTransactionExpired,
|
|
24
|
+
clientSignaturePayload,
|
|
25
|
+
CLIENT_SIG_VERSION,
|
|
26
|
+
MaxPriority,
|
|
27
|
+
clampPriority
|
|
28
|
+
} from './transaction.js';
|
|
29
|
+
|
|
30
|
+
export {
|
|
31
|
+
ActionsEngine,
|
|
32
|
+
ACTIONS_ENGINE_ID,
|
|
33
|
+
} from './actions-engine.js';
|
|
34
|
+
|
|
35
|
+
export { ReadDependencyCollector } from './read-dependency-collector.js';
|
|
36
|
+
export { TransactionCoordinator } from './coordinator.js';
|
|
37
|
+
export type { CoordinatorOptions, PendValidationMode } from './coordinator.js';
|
|
38
|
+
export { CoordinatorConcurrentStampError, CoordinatorPartialCommitError, CoordinatorStaleLossError } from './errors.js';
|
|
39
|
+
export { TransactionSession } from './session.js';
|
|
40
|
+
export { TransactionValidator } from './validator.js';
|
|
41
|
+
export type { EngineRegistration, ValidationCoordinatorFactory, BlockStateProvider } from './validator.js';
|
|
42
|
+
|
|
43
|
+
export {
|
|
44
|
+
collectOperations,
|
|
45
|
+
hashOperations,
|
|
46
|
+
canonicalStringify,
|
|
47
|
+
canonicalOperationsPayload,
|
|
48
|
+
opsHashVersion,
|
|
49
|
+
OPS_HASH_VERSION,
|
|
50
|
+
OPS_HASH_PREFIX,
|
|
51
|
+
} from './operations-hash.js';
|
|
52
|
+
export type { Operation } from './operations-hash.js';
|
|
@@ -1,196 +1,196 @@
|
|
|
1
|
-
import type { BlockId, IBlock, BlockOperations } from '../blocks/structs.js';
|
|
2
|
-
import type { CollectionId } from '../collection/struct.js';
|
|
3
|
-
import type { Transforms } from '../transform/struct.js';
|
|
4
|
-
import { hashString } from '../utility/hash-string.js';
|
|
5
|
-
|
|
6
|
-
/**
|
|
7
|
-
* Represents an operation on a block within a collection.
|
|
8
|
-
*
|
|
9
|
-
* This is the SINGLE source of truth for the operation shape used by the
|
|
10
|
-
* transaction "operations hash" — the fingerprint a coordinator sends and a
|
|
11
|
-
* validator recomputes. Both {@link TransactionCoordinator} and
|
|
12
|
-
* {@link TransactionValidator} import this type; it must never be duplicated,
|
|
13
|
-
* because the two sides disagreeing is exactly the bug this module prevents.
|
|
14
|
-
*/
|
|
15
|
-
export type Operation =
|
|
16
|
-
| { readonly type: 'insert'; readonly collectionId: CollectionId; readonly blockId: BlockId; readonly block: IBlock }
|
|
17
|
-
| { readonly type: 'update'; readonly collectionId: CollectionId; readonly blockId: BlockId; readonly operations: BlockOperations }
|
|
18
|
-
| { readonly type: 'delete'; readonly collectionId: CollectionId; readonly blockId: BlockId };
|
|
19
|
-
|
|
20
|
-
/**
|
|
21
|
-
* Rank of each operation type, used ONLY as the final tiebreaker when the same
|
|
22
|
-
* (collectionId, blockId) legitimately carries more than one operation — a block
|
|
23
|
-
* staged, then mutated, then deleted within one transform (Transforms apply order
|
|
24
|
-
* is insert → update → delete; see transform/struct.ts). This is the semantic
|
|
25
|
-
* apply order. The exact ranking is arbitrary for correctness (both sides use it),
|
|
26
|
-
* but it MUST be defined in exactly one place — here.
|
|
27
|
-
*/
|
|
28
|
-
const TYPE_RANK: Record<Operation['type'], number> = {
|
|
29
|
-
insert: 0,
|
|
30
|
-
update: 1,
|
|
31
|
-
delete: 2,
|
|
32
|
-
};
|
|
33
|
-
|
|
34
|
-
/**
|
|
35
|
-
* Collect every block operation across all collections into a flat list.
|
|
36
|
-
*
|
|
37
|
-
* The returned order reflects Map/object insertion order and is therefore NOT
|
|
38
|
-
* canonical — {@link hashOperations} sorts before hashing, so callers do not need
|
|
39
|
-
* to pre-sort. Shared by the coordinator (both commit() and execute()) and the
|
|
40
|
-
* validator so all three collect sites produce the identical logical set.
|
|
41
|
-
*/
|
|
42
|
-
export function collectOperations(transforms: Map<CollectionId, Transforms>): Operation[] {
|
|
43
|
-
const operations: Operation[] = [];
|
|
44
|
-
for (const [collectionId, t] of transforms) {
|
|
45
|
-
for (const [blockId, block] of Object.entries(t.inserts ?? {})) {
|
|
46
|
-
operations.push({ type: 'insert', collectionId, blockId, block });
|
|
47
|
-
}
|
|
48
|
-
for (const [blockId, ops] of Object.entries(t.updates ?? {})) {
|
|
49
|
-
operations.push({ type: 'update', collectionId, blockId, operations: ops });
|
|
50
|
-
}
|
|
51
|
-
for (const blockId of t.deletes ?? []) {
|
|
52
|
-
operations.push({ type: 'delete', collectionId, blockId });
|
|
53
|
-
}
|
|
54
|
-
}
|
|
55
|
-
return operations;
|
|
56
|
-
}
|
|
57
|
-
|
|
58
|
-
/**
|
|
59
|
-
* Total order over operations by the tuple (collectionId, blockId, type), using
|
|
60
|
-
* plain string comparison on the first two components and {@link TYPE_RANK} on the
|
|
61
|
-
* third. This is the cross-node ordering contract: two honest nodes that see the
|
|
62
|
-
* same logical set MUST produce the same sorted sequence regardless of the order
|
|
63
|
-
* they happened to collect operations in.
|
|
64
|
-
*/
|
|
65
|
-
function compareOperations(a: Operation, b: Operation): number {
|
|
66
|
-
if (a.collectionId !== b.collectionId) return a.collectionId < b.collectionId ? -1 : 1;
|
|
67
|
-
if (a.blockId !== b.blockId) return a.blockId < b.blockId ? -1 : 1;
|
|
68
|
-
return TYPE_RANK[a.type] - TYPE_RANK[b.type];
|
|
69
|
-
}
|
|
70
|
-
|
|
71
|
-
/**
|
|
72
|
-
* Canonical JSON encoder: recursively sorts object keys but PRESERVES array element
|
|
73
|
-
* order, and matches JSON.stringify leaf semantics.
|
|
74
|
-
*
|
|
75
|
-
* - Object keys are emitted in ascending (sorted) order, so two objects with the
|
|
76
|
-
* same content but different key-insertion order encode identically.
|
|
77
|
-
* - Array element order is preserved because BlockOperations is an ordered list of
|
|
78
|
-
* [entity, index, deleteCount, inserted] tuples whose order is semantically
|
|
79
|
-
* meaningful (as are any data arrays nested inside an IBlock).
|
|
80
|
-
* - Leaf semantics mirror JSON.stringify: `undefined`/function/symbol object-values
|
|
81
|
-
* are dropped, the same in arrays encode as `null`, `null` encodes as `null`,
|
|
82
|
-
* non-finite numbers as `null`, and other primitives via JSON.stringify.
|
|
83
|
-
*
|
|
84
|
-
* Exported so the order-independence test can exercise it directly.
|
|
85
|
-
*
|
|
86
|
-
* NOTE: no toJSON/Date special-casing — a value carrying toJSON (e.g. a Date)
|
|
87
|
-
* encodes as its plain enumerable keys ({} for a Date), not JSON.stringify's
|
|
88
|
-
* toJSON string. Harmless today (blocks hold plain JSON) and still deterministic
|
|
89
|
-
* across nodes (both sides run this same encoder); if IBlock content ever grows
|
|
90
|
-
* toJSON-bearing values and matching JSON.stringify exactly matters, add the hook.
|
|
91
|
-
*/
|
|
92
|
-
export function canonicalStringify(value: unknown): string {
|
|
93
|
-
if (value === null) return 'null';
|
|
94
|
-
|
|
95
|
-
const type = typeof value;
|
|
96
|
-
if (type === 'number') return Number.isFinite(value) ? JSON.stringify(value) : 'null';
|
|
97
|
-
if (type === 'string' || type === 'boolean') return JSON.stringify(value);
|
|
98
|
-
if (type === 'bigint') throw new TypeError('Do not know how to serialize a BigInt');
|
|
99
|
-
if (type === 'undefined' || type === 'function' || type === 'symbol') return 'null';
|
|
100
|
-
|
|
101
|
-
if (Array.isArray(value)) {
|
|
102
|
-
const items = value.map(element => {
|
|
103
|
-
const et = typeof element;
|
|
104
|
-
// In arrays, undefined/function/symbol serialize as null (JSON.stringify semantics).
|
|
105
|
-
if (element === undefined || et === 'function' || et === 'symbol') return 'null';
|
|
106
|
-
return canonicalStringify(element);
|
|
107
|
-
});
|
|
108
|
-
return `[${items.join(',')}]`;
|
|
109
|
-
}
|
|
110
|
-
|
|
111
|
-
// Plain object: sort keys ascending, drop undefined/function/symbol values.
|
|
112
|
-
const obj = value as Record<string, unknown>;
|
|
113
|
-
const parts: string[] = [];
|
|
114
|
-
for (const key of Object.keys(obj).sort()) {
|
|
115
|
-
const v = obj[key];
|
|
116
|
-
const vt = typeof v;
|
|
117
|
-
if (v === undefined || vt === 'function' || vt === 'symbol') continue;
|
|
118
|
-
parts.push(`${JSON.stringify(key)}:${canonicalStringify(v)}`);
|
|
119
|
-
}
|
|
120
|
-
return `{${parts.join(',')}}`;
|
|
121
|
-
}
|
|
122
|
-
|
|
123
|
-
/**
|
|
124
|
-
* Current operations-hash FORMAT VERSION. Versions the *serialization* of operations
|
|
125
|
-
* into bytes (the sort key, {@link canonicalStringify} rules, and the SHA-256/base64url
|
|
126
|
-
* step) — distinct from `engineId` in the TransactionStamp, which versions the operation
|
|
127
|
-
* *content* an engine produces from the same statements. Two honest nodes must agree on
|
|
128
|
-
* BOTH dimensions to produce the same ops-hash.
|
|
129
|
-
*
|
|
130
|
-
* Bump this whenever a change to the canonical serialization alters the emitted bytes,
|
|
131
|
-
* so a peer running the old format is *detected* (a legible version-skew error) rather
|
|
132
|
-
* than mistaken for a content disagreement or a Byzantine lie. See docs/transactions.md
|
|
133
|
-
* ("Operations Hash — Canonical Serialization").
|
|
134
|
-
*/
|
|
135
|
-
export const OPS_HASH_VERSION = 'v1';
|
|
136
|
-
|
|
137
|
-
/**
|
|
138
|
-
* Wire-token prefix carrying {@link OPS_HASH_VERSION}: `ops.v1:`. The `.` delimiter is
|
|
139
|
-
* outside the base64url alphabet (A–Z a–z 0–9 `-` `_`) that follows the trailing `:`, so
|
|
140
|
-
* the version segment can always be sliced back out unambiguously — see {@link opsHashVersion}.
|
|
141
|
-
*/
|
|
142
|
-
export const OPS_HASH_PREFIX = `ops.${OPS_HASH_VERSION}:`;
|
|
143
|
-
|
|
144
|
-
/**
|
|
145
|
-
* Extract the format-version segment from an ops-hash token — the `v1` in `ops.v1:<hash>` —
|
|
146
|
-
* or `null` if the string is not a recognizable versioned ops-hash token.
|
|
147
|
-
*
|
|
148
|
-
* Total: never throws. A bare legacy `ops:<hash>` token (no `.` delimiter), an empty
|
|
149
|
-
* string, or any garbage all return `null`. A validator treats a `null` (or a version it
|
|
150
|
-
* does not recognize) as an unsupported/foreign format — a legible version-skew error —
|
|
151
|
-
* never as an accidental content match.
|
|
152
|
-
*/
|
|
153
|
-
export function opsHashVersion(token: string): string | null {
|
|
154
|
-
if (typeof token !== 'string') return null;
|
|
155
|
-
if (!token.startsWith('ops.')) return null;
|
|
156
|
-
const colon = token.indexOf(':', 4);
|
|
157
|
-
if (colon <= 4) return null; // no version characters between "ops." and ":"
|
|
158
|
-
return token.slice(4, colon);
|
|
159
|
-
}
|
|
160
|
-
|
|
161
|
-
/**
|
|
162
|
-
* The EXACT canonical byte-string {@link hashOperations} feeds into SHA-256: the operations
|
|
163
|
-
* sorted by {@link compareOperations} and run through {@link canonicalStringify}. The version
|
|
164
|
-
* token is NOT part of this preimage — it wraps the resulting hash, it is not hashed.
|
|
165
|
-
*
|
|
166
|
-
* Exposed so a future client signature (design-client-transaction-signatures) can bind the
|
|
167
|
-
* IDENTICAL bytes the validators hash, rather than re-deriving the serialization and risking
|
|
168
|
-
* drift. Pair it with {@link OPS_HASH_VERSION} to record which format the bytes belong to.
|
|
169
|
-
*/
|
|
170
|
-
export function canonicalOperationsPayload(operations: readonly Operation[]): string {
|
|
171
|
-
return canonicalStringify([...operations].sort(compareOperations));
|
|
172
|
-
}
|
|
173
|
-
|
|
174
|
-
/**
|
|
175
|
-
* Compute the transaction operations hash: sort into canonical order, canonically
|
|
176
|
-
* stringify, SHA-256 (base64url) via {@link hashString}, then prefix the versioned
|
|
177
|
-
* {@link OPS_HASH_PREFIX} token (`ops.v1:`) so the wire string is self-describing.
|
|
178
|
-
*
|
|
179
|
-
* This is the fingerprint the coordinator sends in PendRequest.validation.operationsHash and
|
|
180
|
-
* the validator recomputes; equality of this string is the cross-node agreement
|
|
181
|
-
* that a transaction's operations match.
|
|
182
|
-
*
|
|
183
|
-
* NOTE: the ops-hash carries a format-version token, so a mixed-version cluster now
|
|
184
|
-
* *detects* skew — a validator seeing a foreign/legacy version emits a distinct
|
|
185
|
-
* "unsupported operations-hash format version" error instead of the ambiguous
|
|
186
|
-
* "Operations hash mismatch" (see TransactionValidator). What it does NOT do is
|
|
187
|
-
* *cross-compute* older formats: a node only recognizes that a peer speaks a different
|
|
188
|
-
* version, it cannot reproduce that peer's historical bytes. Mixed-version clusters
|
|
189
|
-
* therefore fail LEGIBLY, not interoperably; multi-version compatibility is future
|
|
190
|
-
* work if rolling upgrades ship. The ops-hash is recomputed fresh on both sides and
|
|
191
|
-
* never persisted, so bumping the version cannot retroactively invalidate committed
|
|
192
|
-
* transactions (unlike transaction.id, which IS persisted — leave it untouched).
|
|
193
|
-
*/
|
|
194
|
-
export async function hashOperations(operations: readonly Operation[]): Promise<string> {
|
|
195
|
-
return `${OPS_HASH_PREFIX}${await hashString(canonicalOperationsPayload(operations))}`;
|
|
196
|
-
}
|
|
1
|
+
import type { BlockId, IBlock, BlockOperations } from '../blocks/structs.js';
|
|
2
|
+
import type { CollectionId } from '../collection/struct.js';
|
|
3
|
+
import type { Transforms } from '../transform/struct.js';
|
|
4
|
+
import { hashString } from '../utility/hash-string.js';
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Represents an operation on a block within a collection.
|
|
8
|
+
*
|
|
9
|
+
* This is the SINGLE source of truth for the operation shape used by the
|
|
10
|
+
* transaction "operations hash" — the fingerprint a coordinator sends and a
|
|
11
|
+
* validator recomputes. Both {@link TransactionCoordinator} and
|
|
12
|
+
* {@link TransactionValidator} import this type; it must never be duplicated,
|
|
13
|
+
* because the two sides disagreeing is exactly the bug this module prevents.
|
|
14
|
+
*/
|
|
15
|
+
export type Operation =
|
|
16
|
+
| { readonly type: 'insert'; readonly collectionId: CollectionId; readonly blockId: BlockId; readonly block: IBlock }
|
|
17
|
+
| { readonly type: 'update'; readonly collectionId: CollectionId; readonly blockId: BlockId; readonly operations: BlockOperations }
|
|
18
|
+
| { readonly type: 'delete'; readonly collectionId: CollectionId; readonly blockId: BlockId };
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Rank of each operation type, used ONLY as the final tiebreaker when the same
|
|
22
|
+
* (collectionId, blockId) legitimately carries more than one operation — a block
|
|
23
|
+
* staged, then mutated, then deleted within one transform (Transforms apply order
|
|
24
|
+
* is insert → update → delete; see transform/struct.ts). This is the semantic
|
|
25
|
+
* apply order. The exact ranking is arbitrary for correctness (both sides use it),
|
|
26
|
+
* but it MUST be defined in exactly one place — here.
|
|
27
|
+
*/
|
|
28
|
+
const TYPE_RANK: Record<Operation['type'], number> = {
|
|
29
|
+
insert: 0,
|
|
30
|
+
update: 1,
|
|
31
|
+
delete: 2,
|
|
32
|
+
};
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* Collect every block operation across all collections into a flat list.
|
|
36
|
+
*
|
|
37
|
+
* The returned order reflects Map/object insertion order and is therefore NOT
|
|
38
|
+
* canonical — {@link hashOperations} sorts before hashing, so callers do not need
|
|
39
|
+
* to pre-sort. Shared by the coordinator (both commit() and execute()) and the
|
|
40
|
+
* validator so all three collect sites produce the identical logical set.
|
|
41
|
+
*/
|
|
42
|
+
export function collectOperations(transforms: Map<CollectionId, Transforms>): Operation[] {
|
|
43
|
+
const operations: Operation[] = [];
|
|
44
|
+
for (const [collectionId, t] of transforms) {
|
|
45
|
+
for (const [blockId, block] of Object.entries(t.inserts ?? {})) {
|
|
46
|
+
operations.push({ type: 'insert', collectionId, blockId, block });
|
|
47
|
+
}
|
|
48
|
+
for (const [blockId, ops] of Object.entries(t.updates ?? {})) {
|
|
49
|
+
operations.push({ type: 'update', collectionId, blockId, operations: ops });
|
|
50
|
+
}
|
|
51
|
+
for (const blockId of t.deletes ?? []) {
|
|
52
|
+
operations.push({ type: 'delete', collectionId, blockId });
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
return operations;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Total order over operations by the tuple (collectionId, blockId, type), using
|
|
60
|
+
* plain string comparison on the first two components and {@link TYPE_RANK} on the
|
|
61
|
+
* third. This is the cross-node ordering contract: two honest nodes that see the
|
|
62
|
+
* same logical set MUST produce the same sorted sequence regardless of the order
|
|
63
|
+
* they happened to collect operations in.
|
|
64
|
+
*/
|
|
65
|
+
function compareOperations(a: Operation, b: Operation): number {
|
|
66
|
+
if (a.collectionId !== b.collectionId) return a.collectionId < b.collectionId ? -1 : 1;
|
|
67
|
+
if (a.blockId !== b.blockId) return a.blockId < b.blockId ? -1 : 1;
|
|
68
|
+
return TYPE_RANK[a.type] - TYPE_RANK[b.type];
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Canonical JSON encoder: recursively sorts object keys but PRESERVES array element
|
|
73
|
+
* order, and matches JSON.stringify leaf semantics.
|
|
74
|
+
*
|
|
75
|
+
* - Object keys are emitted in ascending (sorted) order, so two objects with the
|
|
76
|
+
* same content but different key-insertion order encode identically.
|
|
77
|
+
* - Array element order is preserved because BlockOperations is an ordered list of
|
|
78
|
+
* [entity, index, deleteCount, inserted] tuples whose order is semantically
|
|
79
|
+
* meaningful (as are any data arrays nested inside an IBlock).
|
|
80
|
+
* - Leaf semantics mirror JSON.stringify: `undefined`/function/symbol object-values
|
|
81
|
+
* are dropped, the same in arrays encode as `null`, `null` encodes as `null`,
|
|
82
|
+
* non-finite numbers as `null`, and other primitives via JSON.stringify.
|
|
83
|
+
*
|
|
84
|
+
* Exported so the order-independence test can exercise it directly.
|
|
85
|
+
*
|
|
86
|
+
* NOTE: no toJSON/Date special-casing — a value carrying toJSON (e.g. a Date)
|
|
87
|
+
* encodes as its plain enumerable keys ({} for a Date), not JSON.stringify's
|
|
88
|
+
* toJSON string. Harmless today (blocks hold plain JSON) and still deterministic
|
|
89
|
+
* across nodes (both sides run this same encoder); if IBlock content ever grows
|
|
90
|
+
* toJSON-bearing values and matching JSON.stringify exactly matters, add the hook.
|
|
91
|
+
*/
|
|
92
|
+
export function canonicalStringify(value: unknown): string {
|
|
93
|
+
if (value === null) return 'null';
|
|
94
|
+
|
|
95
|
+
const type = typeof value;
|
|
96
|
+
if (type === 'number') return Number.isFinite(value) ? JSON.stringify(value) : 'null';
|
|
97
|
+
if (type === 'string' || type === 'boolean') return JSON.stringify(value);
|
|
98
|
+
if (type === 'bigint') throw new TypeError('Do not know how to serialize a BigInt');
|
|
99
|
+
if (type === 'undefined' || type === 'function' || type === 'symbol') return 'null';
|
|
100
|
+
|
|
101
|
+
if (Array.isArray(value)) {
|
|
102
|
+
const items = value.map(element => {
|
|
103
|
+
const et = typeof element;
|
|
104
|
+
// In arrays, undefined/function/symbol serialize as null (JSON.stringify semantics).
|
|
105
|
+
if (element === undefined || et === 'function' || et === 'symbol') return 'null';
|
|
106
|
+
return canonicalStringify(element);
|
|
107
|
+
});
|
|
108
|
+
return `[${items.join(',')}]`;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
// Plain object: sort keys ascending, drop undefined/function/symbol values.
|
|
112
|
+
const obj = value as Record<string, unknown>;
|
|
113
|
+
const parts: string[] = [];
|
|
114
|
+
for (const key of Object.keys(obj).sort()) {
|
|
115
|
+
const v = obj[key];
|
|
116
|
+
const vt = typeof v;
|
|
117
|
+
if (v === undefined || vt === 'function' || vt === 'symbol') continue;
|
|
118
|
+
parts.push(`${JSON.stringify(key)}:${canonicalStringify(v)}`);
|
|
119
|
+
}
|
|
120
|
+
return `{${parts.join(',')}}`;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/**
|
|
124
|
+
* Current operations-hash FORMAT VERSION. Versions the *serialization* of operations
|
|
125
|
+
* into bytes (the sort key, {@link canonicalStringify} rules, and the SHA-256/base64url
|
|
126
|
+
* step) — distinct from `engineId` in the TransactionStamp, which versions the operation
|
|
127
|
+
* *content* an engine produces from the same statements. Two honest nodes must agree on
|
|
128
|
+
* BOTH dimensions to produce the same ops-hash.
|
|
129
|
+
*
|
|
130
|
+
* Bump this whenever a change to the canonical serialization alters the emitted bytes,
|
|
131
|
+
* so a peer running the old format is *detected* (a legible version-skew error) rather
|
|
132
|
+
* than mistaken for a content disagreement or a Byzantine lie. See docs/transactions.md
|
|
133
|
+
* ("Operations Hash — Canonical Serialization").
|
|
134
|
+
*/
|
|
135
|
+
export const OPS_HASH_VERSION = 'v1';
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* Wire-token prefix carrying {@link OPS_HASH_VERSION}: `ops.v1:`. The `.` delimiter is
|
|
139
|
+
* outside the base64url alphabet (A–Z a–z 0–9 `-` `_`) that follows the trailing `:`, so
|
|
140
|
+
* the version segment can always be sliced back out unambiguously — see {@link opsHashVersion}.
|
|
141
|
+
*/
|
|
142
|
+
export const OPS_HASH_PREFIX = `ops.${OPS_HASH_VERSION}:`;
|
|
143
|
+
|
|
144
|
+
/**
|
|
145
|
+
* Extract the format-version segment from an ops-hash token — the `v1` in `ops.v1:<hash>` —
|
|
146
|
+
* or `null` if the string is not a recognizable versioned ops-hash token.
|
|
147
|
+
*
|
|
148
|
+
* Total: never throws. A bare legacy `ops:<hash>` token (no `.` delimiter), an empty
|
|
149
|
+
* string, or any garbage all return `null`. A validator treats a `null` (or a version it
|
|
150
|
+
* does not recognize) as an unsupported/foreign format — a legible version-skew error —
|
|
151
|
+
* never as an accidental content match.
|
|
152
|
+
*/
|
|
153
|
+
export function opsHashVersion(token: string): string | null {
|
|
154
|
+
if (typeof token !== 'string') return null;
|
|
155
|
+
if (!token.startsWith('ops.')) return null;
|
|
156
|
+
const colon = token.indexOf(':', 4);
|
|
157
|
+
if (colon <= 4) return null; // no version characters between "ops." and ":"
|
|
158
|
+
return token.slice(4, colon);
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* The EXACT canonical byte-string {@link hashOperations} feeds into SHA-256: the operations
|
|
163
|
+
* sorted by {@link compareOperations} and run through {@link canonicalStringify}. The version
|
|
164
|
+
* token is NOT part of this preimage — it wraps the resulting hash, it is not hashed.
|
|
165
|
+
*
|
|
166
|
+
* Exposed so a future client signature (design-client-transaction-signatures) can bind the
|
|
167
|
+
* IDENTICAL bytes the validators hash, rather than re-deriving the serialization and risking
|
|
168
|
+
* drift. Pair it with {@link OPS_HASH_VERSION} to record which format the bytes belong to.
|
|
169
|
+
*/
|
|
170
|
+
export function canonicalOperationsPayload(operations: readonly Operation[]): string {
|
|
171
|
+
return canonicalStringify([...operations].sort(compareOperations));
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
/**
|
|
175
|
+
* Compute the transaction operations hash: sort into canonical order, canonically
|
|
176
|
+
* stringify, SHA-256 (base64url) via {@link hashString}, then prefix the versioned
|
|
177
|
+
* {@link OPS_HASH_PREFIX} token (`ops.v1:`) so the wire string is self-describing.
|
|
178
|
+
*
|
|
179
|
+
* This is the fingerprint the coordinator sends in PendRequest.validation.operationsHash and
|
|
180
|
+
* the validator recomputes; equality of this string is the cross-node agreement
|
|
181
|
+
* that a transaction's operations match.
|
|
182
|
+
*
|
|
183
|
+
* NOTE: the ops-hash carries a format-version token, so a mixed-version cluster now
|
|
184
|
+
* *detects* skew — a validator seeing a foreign/legacy version emits a distinct
|
|
185
|
+
* "unsupported operations-hash format version" error instead of the ambiguous
|
|
186
|
+
* "Operations hash mismatch" (see TransactionValidator). What it does NOT do is
|
|
187
|
+
* *cross-compute* older formats: a node only recognizes that a peer speaks a different
|
|
188
|
+
* version, it cannot reproduce that peer's historical bytes. Mixed-version clusters
|
|
189
|
+
* therefore fail LEGIBLY, not interoperably; multi-version compatibility is future
|
|
190
|
+
* work if rolling upgrades ship. The ops-hash is recomputed fresh on both sides and
|
|
191
|
+
* never persisted, so bumping the version cannot retroactively invalidate committed
|
|
192
|
+
* transactions (unlike transaction.id, which IS persisted — leave it untouched).
|
|
193
|
+
*/
|
|
194
|
+
export async function hashOperations(operations: readonly Operation[]): Promise<string> {
|
|
195
|
+
return `${OPS_HASH_PREFIX}${await hashString(canonicalOperationsPayload(operations))}`;
|
|
196
|
+
}
|