@941design/marmot 0.0.0-stage → 0.2.0-alpha.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/CHANGELOG.md +739 -0
- package/LICENSE +21 -0
- package/README.md +33 -2
- package/dist/account/admin.d.ts +72 -0
- package/dist/account/admin.js +209 -0
- package/dist/account/device-deps.d.ts +379 -0
- package/dist/account/device-deps.js +36 -0
- package/dist/account/device-lineage.d.ts +199 -0
- package/dist/account/device-lineage.js +390 -0
- package/dist/account/device-registry.d.ts +93 -0
- package/dist/account/device-registry.js +1290 -0
- package/dist/account/device-rotation.d.ts +61 -0
- package/dist/account/device-rotation.js +827 -0
- package/dist/account/enrolment.d.ts +339 -0
- package/dist/account/enrolment.js +1247 -0
- package/dist/account/identity-proof.d.ts +79 -0
- package/dist/account/identity-proof.js +264 -0
- package/dist/account/index.d.ts +17 -0
- package/dist/account/index.js +16 -0
- package/dist/account/restore-rotation.d.ts +21 -0
- package/dist/account/restore-rotation.js +22 -0
- package/dist/account/same-account-authorization.d.ts +86 -0
- package/dist/account/same-account-authorization.js +180 -0
- package/dist/account/teardown.d.ts +190 -0
- package/dist/account/teardown.js +878 -0
- package/dist/client/admission-cleanup.d.ts +197 -0
- package/dist/client/admission-cleanup.js +635 -0
- package/dist/client/adoption-proof.d.ts +39 -0
- package/dist/client/adoption-proof.js +102 -0
- package/dist/client/before-create-group.d.ts +18 -0
- package/dist/client/before-create-group.js +65 -0
- package/dist/client/before-publish-hooks.d.ts +121 -0
- package/dist/client/before-publish-hooks.js +182 -0
- package/dist/client/client-config.d.ts +42 -0
- package/dist/client/client-config.js +13 -0
- package/dist/client/commit-redrive.d.ts +92 -0
- package/dist/client/commit-redrive.js +274 -0
- package/dist/client/component-update.d.ts +43 -0
- package/dist/client/component-update.js +53 -0
- package/dist/client/confirm-hooks.d.ts +55 -0
- package/dist/client/confirm-hooks.js +74 -0
- package/dist/client/create-client.d.ts +1126 -0
- package/dist/client/create-client.js +1232 -0
- package/dist/client/group-availability.d.ts +182 -0
- package/dist/client/group-availability.js +301 -0
- package/dist/client/group-disband.d.ts +28 -0
- package/dist/client/group-disband.js +64 -0
- package/dist/client/group-history.d.ts +461 -0
- package/dist/client/group-history.js +1365 -0
- package/dist/client/group-profile.d.ts +31 -0
- package/dist/client/group-profile.js +62 -0
- package/dist/client/group-records.d.ts +522 -0
- package/dist/client/group-records.js +1117 -0
- package/dist/client/group-removal.d.ts +36 -0
- package/dist/client/group-removal.js +127 -0
- package/dist/client/group-remove-member.d.ts +49 -0
- package/dist/client/group-remove-member.js +163 -0
- package/dist/client/group-runtime.d.ts +415 -0
- package/dist/client/group-runtime.js +2811 -0
- package/dist/client/group-snapshot.d.ts +104 -0
- package/dist/client/group-snapshot.js +474 -0
- package/dist/client/history-pages.d.ts +107 -0
- package/dist/client/history-pages.js +194 -0
- package/dist/client/inbox-send.d.ts +19 -0
- package/dist/client/inbox-send.js +71 -0
- package/dist/client/index.d.ts +24 -0
- package/dist/client/index.js +13 -0
- package/dist/client/ingest.d.ts +82 -0
- package/dist/client/ingest.js +1584 -0
- package/dist/client/invitation-outcomes.d.ts +50 -0
- package/dist/client/invitation-outcomes.js +135 -0
- package/dist/client/lifecycle-events.d.ts +63 -0
- package/dist/client/lifecycle-events.js +35 -0
- package/dist/client/opaque-candidates.d.ts +82 -0
- package/dist/client/opaque-candidates.js +170 -0
- package/dist/client/own-change-outbox.d.ts +66 -0
- package/dist/client/own-change-outbox.js +158 -0
- package/dist/client/pending-leaf.d.ts +116 -0
- package/dist/client/pending-leaf.js +378 -0
- package/dist/client/permissions.d.ts +9 -0
- package/dist/client/permissions.js +12 -0
- package/dist/client/pipeline.d.ts +583 -0
- package/dist/client/pipeline.js +3666 -0
- package/dist/client/reentrancy-guard.d.ts +102 -0
- package/dist/client/reentrancy-guard.js +159 -0
- package/dist/client/rekey.d.ts +58 -0
- package/dist/client/rekey.js +149 -0
- package/dist/client/transport-policy.d.ts +181 -0
- package/dist/client/transport-policy.js +214 -0
- package/dist/history/admission-lineage.d.ts +186 -0
- package/dist/history/admission-lineage.js +589 -0
- package/dist/history/equivocation.d.ts +55 -0
- package/dist/history/equivocation.js +113 -0
- package/dist/history/fencing.d.ts +66 -0
- package/dist/history/fencing.js +121 -0
- package/dist/history/hex.d.ts +3 -0
- package/dist/history/hex.js +10 -0
- package/dist/history/index.d.ts +74 -0
- package/dist/history/index.js +32 -0
- package/dist/history/notifications.d.ts +270 -0
- package/dist/history/notifications.js +264 -0
- package/dist/history/ordering-key.d.ts +24 -0
- package/dist/history/ordering-key.js +101 -0
- package/dist/history/own-change-fork.d.ts +112 -0
- package/dist/history/own-change-fork.js +196 -0
- package/dist/history/own-change.d.ts +118 -0
- package/dist/history/own-change.js +146 -0
- package/dist/history/policy.d.ts +48 -0
- package/dist/history/policy.js +52 -0
- package/dist/history/retained-window.d.ts +215 -0
- package/dist/history/retained-window.js +565 -0
- package/dist/inbox/demux.d.ts +90 -0
- package/dist/inbox/demux.js +78 -0
- package/dist/inbox/handler-registry.d.ts +42 -0
- package/dist/inbox/handler-registry.js +37 -0
- package/dist/inbox/index.d.ts +11 -0
- package/dist/inbox/index.js +10 -0
- package/dist/inbox/seen-set.d.ts +82 -0
- package/dist/inbox/seen-set.js +202 -0
- package/dist/inbox/subscription.d.ts +236 -0
- package/dist/inbox/subscription.js +644 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.js +9 -0
- package/dist/invitations/competing-welcome.d.ts +223 -0
- package/dist/invitations/competing-welcome.js +128 -0
- package/dist/invitations/decline.d.ts +67 -0
- package/dist/invitations/decline.js +149 -0
- package/dist/invitations/delivery-evidence.d.ts +288 -0
- package/dist/invitations/delivery-evidence.js +766 -0
- package/dist/invitations/expect-welcome.d.ts +66 -0
- package/dist/invitations/expect-welcome.js +138 -0
- package/dist/invitations/index.d.ts +18 -0
- package/dist/invitations/index.js +18 -0
- package/dist/invitations/invitation-outcome.d.ts +110 -0
- package/dist/invitations/invitation-outcome.js +210 -0
- package/dist/invitations/invite.d.ts +358 -0
- package/dist/invitations/invite.js +1102 -0
- package/dist/invitations/offers.d.ts +79 -0
- package/dist/invitations/offers.js +115 -0
- package/dist/invitations/on-proposal.d.ts +47 -0
- package/dist/invitations/on-proposal.js +40 -0
- package/dist/invitations/pending-proposal-policy.d.ts +52 -0
- package/dist/invitations/pending-proposal-policy.js +139 -0
- package/dist/invitations/proposal-deadline.d.ts +133 -0
- package/dist/invitations/proposal-deadline.js +164 -0
- package/dist/invitations/relay-planes.d.ts +43 -0
- package/dist/invitations/relay-planes.js +70 -0
- package/dist/invitations/welcome-processor.d.ts +272 -0
- package/dist/invitations/welcome-processor.js +1241 -0
- package/dist/key-packages/device-key.d.ts +131 -0
- package/dist/key-packages/device-key.js +272 -0
- package/dist/key-packages/device-rotation-records.d.ts +83 -0
- package/dist/key-packages/device-rotation-records.js +173 -0
- package/dist/key-packages/group-refs.d.ts +40 -0
- package/dist/key-packages/group-refs.js +79 -0
- package/dist/key-packages/index.d.ts +18 -0
- package/dist/key-packages/index.js +18 -0
- package/dist/key-packages/key-package-ref.d.ts +16 -0
- package/dist/key-packages/key-package-ref.js +21 -0
- package/dist/key-packages/observation-stream.d.ts +4 -0
- package/dist/key-packages/observation-stream.js +120 -0
- package/dist/key-packages/offer-rumor.d.ts +26 -0
- package/dist/key-packages/offer-rumor.js +69 -0
- package/dist/key-packages/publisher.d.ts +174 -0
- package/dist/key-packages/publisher.js +1247 -0
- package/dist/key-packages/select-key-package.d.ts +24 -0
- package/dist/key-packages/select-key-package.js +90 -0
- package/dist/key-packages/slot-manager.d.ts +167 -0
- package/dist/key-packages/slot-manager.js +327 -0
- package/dist/key-packages/validate-key-package-event.d.ts +3 -0
- package/dist/key-packages/validate-key-package-event.js +49 -0
- package/dist/media/cache.d.ts +14 -0
- package/dist/media/cache.js +10 -0
- package/dist/media/index.d.ts +52 -0
- package/dist/media/index.js +71 -0
- package/dist/mls.d.ts +15 -0
- package/dist/mls.js +15 -0
- package/dist/shared/account-pubkey.d.ts +4 -0
- package/dist/shared/account-pubkey.js +10 -0
- package/dist/shared/errors.d.ts +28 -0
- package/dist/shared/errors.js +96 -0
- package/dist/shared/hex.d.ts +4 -0
- package/dist/shared/hex.js +13 -0
- package/dist/shared/index.d.ts +14 -0
- package/dist/shared/index.js +14 -0
- package/dist/shared/kinds.d.ts +8 -0
- package/dist/shared/kinds.js +28 -0
- package/dist/shared/publish-classification.d.ts +26 -0
- package/dist/shared/publish-classification.js +31 -0
- package/dist/storage/envelope.d.ts +39 -0
- package/dist/storage/envelope.js +201 -0
- package/dist/storage/index.d.ts +237 -0
- package/dist/storage/index.js +491 -0
- package/dist/storage/indexeddb/idb-types.d.ts +68 -0
- package/dist/storage/indexeddb/idb-types.js +1 -0
- package/dist/storage/indexeddb/index.d.ts +17 -0
- package/dist/storage/indexeddb/index.js +141 -0
- package/dist/storage/lease.d.ts +54 -0
- package/dist/storage/lease.js +168 -0
- package/dist/storage/memory/deterministic-signer.d.ts +27 -0
- package/dist/storage/memory/deterministic-signer.js +65 -0
- package/dist/storage/memory/index.d.ts +32 -0
- package/dist/storage/memory/index.js +87 -0
- package/dist/storage/memory/lock-manager.d.ts +8 -0
- package/dist/storage/memory/lock-manager.js +71 -0
- package/package.json +66 -3
|
@@ -0,0 +1,565 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The persisted rewind window (S10; the `rewindTree` group artifact of
|
|
3
|
+
* ADR-007 §1): the part of the engine's full-fork history tree fork recovery
|
|
4
|
+
* needs — every state on the canonical path within the rollback horizon
|
|
5
|
+
* (`maxRewindCommits` commits below the tip), the commit that produced each,
|
|
6
|
+
* with the confirmation-time stamp of an own commit, and every fork node
|
|
7
|
+
* hanging off that path.
|
|
8
|
+
*
|
|
9
|
+
* The engine keeps this only in memory, and `marmot` rebuilds engines from
|
|
10
|
+
* `ClientState` alone on every reload and rollback. A rebuilt engine had no
|
|
11
|
+
* retained root at the fork epoch, so a sibling commit arriving after it was
|
|
12
|
+
* skipped as `beyond-anchor` and the group forked for good; and an own commit
|
|
13
|
+
* confirmed by a rebuild (a resumed or retried confirmation) carried no stamp,
|
|
14
|
+
* so it could never be a candidate again (a committer cannot replay its own
|
|
15
|
+
* commit). The window is written in the same transaction as every
|
|
16
|
+
* `clientState` that moves the tip and handed back to every engine built over
|
|
17
|
+
* that state ({@link restoreHistory}), so fork recovery works the same across
|
|
18
|
+
* a reload as it does in one process.
|
|
19
|
+
*
|
|
20
|
+
* Layout: `tip` → the tip node (no snapshot: the stored `clientState` is it);
|
|
21
|
+
* `node:<tag>` → every other node, with its serialized state. A node's tag
|
|
22
|
+
* does not pin its content: the engine re-snapshots a retained node when a
|
|
23
|
+
* proposal is staged onto it (`GroupHistoryTree.updateSnapshot`, same tag),
|
|
24
|
+
* so a write rewrites every node whose stored encoding differs.
|
|
25
|
+
*/
|
|
26
|
+
import { commitDigest, deserializeClientState, serializeClientState } from '@941design/marmot-engine/core';
|
|
27
|
+
import { authenticatedSenderOf, decodeOwnCommitRecord, encodeOwnCommitRecord, GroupHistoryTree, RetainedHistoryStore, tipCommitterOf, } from '@941design/marmot-engine/engine';
|
|
28
|
+
import { contentTypes, decode, encode, mlsMessageDecoder, mlsMessageEncoder, wireformats } from '@941design/marmot-engine/mls';
|
|
29
|
+
import { bytesOfHex64, isHex64 } from '../shared/index.js';
|
|
30
|
+
import { hexOf } from './hex.js';
|
|
31
|
+
import { MARMOT_CONVERGENCE_POLICY, REWIND_HORIZON } from './policy.js';
|
|
32
|
+
export { hexOf, REWIND_HORIZON };
|
|
33
|
+
const TIP_KEY = 'tip';
|
|
34
|
+
const NODE_PREFIX = 'node:';
|
|
35
|
+
export function tagOf(state) {
|
|
36
|
+
return hexOf(state.confirmationTag);
|
|
37
|
+
}
|
|
38
|
+
/** The window of a state with no retained history: the tip alone, carrying `evidence` when the device joined into it. */
|
|
39
|
+
export function tipOnlyWindow(state, evidence) {
|
|
40
|
+
// Evidence is two 64-lowercase-hex strings or nothing: a malformed claim is a caller bug, never stored.
|
|
41
|
+
if (evidence !== undefined && !(isHex64(evidence.digest) && isHex64(evidence.committer)))
|
|
42
|
+
throw new Error('tipOnlyWindow: join evidence needs a 64 lowercase hex digest and committer');
|
|
43
|
+
const tag = tagOf(state);
|
|
44
|
+
const node = { tag, epoch: Number(state.groupContext.epoch), ...(evidence === undefined ? {} : { joinEvidence: { digest: evidence.digest, committer: evidence.committer } }) };
|
|
45
|
+
return { tipTag: tag, nodes: new Map([[tag, node]]) };
|
|
46
|
+
}
|
|
47
|
+
function commitRecord(wire, stamp) {
|
|
48
|
+
return stamp === undefined ? wire : encodeOwnCommitRecord({ wireBytes: wire, stamp });
|
|
49
|
+
}
|
|
50
|
+
/** The commit a node carries: its MLS message and, for an own commit, its stamp. */
|
|
51
|
+
export function commitOf(node) {
|
|
52
|
+
if (node.commit === undefined)
|
|
53
|
+
return undefined;
|
|
54
|
+
const record = decodeOwnCommitRecord(node.commit);
|
|
55
|
+
const message = decode(mlsMessageDecoder, record.wireBytes);
|
|
56
|
+
if (message === undefined)
|
|
57
|
+
return undefined;
|
|
58
|
+
return record.kind === 'stamped' ? { message, stamp: record.stamp } : { message };
|
|
59
|
+
}
|
|
60
|
+
/** Whether `message` is a framed MLS Commit (public or private framing) — the only content a rewind link can carry. */
|
|
61
|
+
function isFramedCommit(message) {
|
|
62
|
+
switch (message.wireformat) {
|
|
63
|
+
case wireformats.mls_public_message:
|
|
64
|
+
return message.publicMessage.content.contentType === contentTypes.commit;
|
|
65
|
+
case wireformats.mls_private_message:
|
|
66
|
+
return message.privateMessage.contentType === contentTypes.commit;
|
|
67
|
+
default:
|
|
68
|
+
return false;
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Whether `node`'s link carries what restoring it needs ({@link restoreHistory}, and a rewind's notifications):
|
|
73
|
+
* a commit record that decodes to a framed MLS Commit — anything else (an application message, a proposal, a
|
|
74
|
+
* Welcome) would be recorded as a fabricated commit edge — and the digest of that message's wire bytes. Never throws.
|
|
75
|
+
*/
|
|
76
|
+
export function linkRestorable(node) {
|
|
77
|
+
if (node.commit === undefined || node.digest === undefined)
|
|
78
|
+
return false;
|
|
79
|
+
try {
|
|
80
|
+
const record = decodeOwnCommitRecord(node.commit);
|
|
81
|
+
const message = decode(mlsMessageDecoder, record.wireBytes);
|
|
82
|
+
if (message === undefined || !isFramedCommit(message))
|
|
83
|
+
return false;
|
|
84
|
+
return hexOf(commitDigest(record.wireBytes)) === node.digest;
|
|
85
|
+
}
|
|
86
|
+
catch {
|
|
87
|
+
return false;
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
/** Keeps the canonical path from `tipTag` down to the horizon and every fork node hanging off it. */
|
|
91
|
+
function bounded(tipTag, nodes, horizon) {
|
|
92
|
+
const tip = nodes.get(tipTag);
|
|
93
|
+
if (tip === undefined)
|
|
94
|
+
throw new Error('retained window: the tip is not among its nodes');
|
|
95
|
+
const floor = tip.epoch - horizon;
|
|
96
|
+
const keep = new Set();
|
|
97
|
+
for (let node = tip; node !== undefined && node.epoch >= floor; node = node.parentTag === undefined ? undefined : nodes.get(node.parentTag)) {
|
|
98
|
+
keep.add(node.tag);
|
|
99
|
+
}
|
|
100
|
+
// Forks: any node whose ancestry reaches a kept canonical node.
|
|
101
|
+
let grew = true;
|
|
102
|
+
while (grew) {
|
|
103
|
+
grew = false;
|
|
104
|
+
for (const node of nodes.values()) {
|
|
105
|
+
if (keep.has(node.tag) || node.parentTag === undefined || !keep.has(node.parentTag) || node.epoch < floor)
|
|
106
|
+
continue;
|
|
107
|
+
keep.add(node.tag);
|
|
108
|
+
grew = true;
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
const out = new Map();
|
|
112
|
+
for (const tag of keep) {
|
|
113
|
+
const node = nodes.get(tag);
|
|
114
|
+
// The lowest kept canonical node is the window's root: it keeps no parent link.
|
|
115
|
+
out.set(tag, node.parentTag !== undefined && keep.has(node.parentTag)
|
|
116
|
+
? node
|
|
117
|
+
: { tag: node.tag, epoch: node.epoch, ...(node.snapshot === undefined ? {} : { snapshot: node.snapshot }), ...(node.joinEvidence === undefined ? {} : { joinEvidence: node.joinEvidence }) });
|
|
118
|
+
}
|
|
119
|
+
return { tipTag, nodes: out };
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* The window of an engine's history tree around `tip` (the engine's current
|
|
123
|
+
* state): every node within the horizon, with the snapshots and commit
|
|
124
|
+
* records the tree holds for them. The engine's tree knows nothing of a join, so
|
|
125
|
+
* the join evidence of the window this capture replaces (`prior`) is carried over
|
|
126
|
+
* by node tag: a captured node gets the evidence `prior` holds for its tag, and
|
|
127
|
+
* evidence of a node the capture no longer holds leaves with it.
|
|
128
|
+
*/
|
|
129
|
+
export async function captureWindow(tree, tip, horizon = REWIND_HORIZON, prior) {
|
|
130
|
+
const tipTag = tagOf(tip);
|
|
131
|
+
if (!tree.hasNode(tipTag))
|
|
132
|
+
return tipOnlyWindow(tip, prior?.nodes.get(tipTag)?.joinEvidence);
|
|
133
|
+
const floor = Number(tip.groupContext.epoch) - horizon;
|
|
134
|
+
const nodes = new Map();
|
|
135
|
+
for (const tag of tree.tags()) {
|
|
136
|
+
const node = tree.node(tag);
|
|
137
|
+
if (node.epoch < floor)
|
|
138
|
+
continue;
|
|
139
|
+
const snapshot = tag === tipTag ? undefined : await tree.snapshotOf(tag);
|
|
140
|
+
if (tag !== tipTag && snapshot === undefined)
|
|
141
|
+
continue;
|
|
142
|
+
let commit;
|
|
143
|
+
let digest;
|
|
144
|
+
const sender = node.edge?.senderLeafIndex;
|
|
145
|
+
if (node.parentTag !== undefined) {
|
|
146
|
+
const wire = await tree.commitBytesOf(tag);
|
|
147
|
+
if (wire !== undefined) {
|
|
148
|
+
commit = commitRecord(wire, await tree.ownCommitStampOf(tag));
|
|
149
|
+
digest = hexOf(commitDigest(wire));
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
const joinEvidence = prior?.nodes.get(tag)?.joinEvidence;
|
|
153
|
+
nodes.set(tag, {
|
|
154
|
+
tag,
|
|
155
|
+
epoch: node.epoch,
|
|
156
|
+
...(node.parentTag === undefined || commit === undefined || digest === undefined ? {} : { parentTag: node.parentTag, commit, digest, ...(sender === undefined ? {} : { sender }) }),
|
|
157
|
+
...(snapshot === undefined ? {} : { snapshot }),
|
|
158
|
+
...(joinEvidence === undefined ? {} : { joinEvidence }),
|
|
159
|
+
});
|
|
160
|
+
}
|
|
161
|
+
return bounded(tipTag, nodes, horizon);
|
|
162
|
+
}
|
|
163
|
+
/**
|
|
164
|
+
* `window` with an own commit applied on top of its tip: the old tip becomes
|
|
165
|
+
* a node with `parentState`'s snapshot (the state the commit was built from,
|
|
166
|
+
* its staged proposals included), and the new state is the tip.
|
|
167
|
+
*/
|
|
168
|
+
export function extendWindow(window, link, horizon = REWIND_HORIZON) {
|
|
169
|
+
const parentTag = tagOf(link.parentState);
|
|
170
|
+
const nodes = new Map(window.nodes);
|
|
171
|
+
const parent = nodes.get(parentTag);
|
|
172
|
+
nodes.set(parentTag, { ...(parent ?? { tag: parentTag, epoch: Number(link.parentState.groupContext.epoch) }), snapshot: serializeClientState(link.parentState) });
|
|
173
|
+
const tag = tagOf(link.newState);
|
|
174
|
+
// An own commit: its sender is this device's own leaf at the parent.
|
|
175
|
+
const sender = Number(link.parentState.privatePath.leafIndex);
|
|
176
|
+
const joinEvidence = window.nodes.get(tag)?.joinEvidence;
|
|
177
|
+
nodes.set(tag, {
|
|
178
|
+
tag,
|
|
179
|
+
epoch: Number(link.newState.groupContext.epoch),
|
|
180
|
+
parentTag,
|
|
181
|
+
commit: commitRecord(link.commit, link.stamp),
|
|
182
|
+
digest: hexOf(commitDigest(link.commit)),
|
|
183
|
+
sender,
|
|
184
|
+
...(joinEvidence === undefined ? {} : { joinEvidence }),
|
|
185
|
+
});
|
|
186
|
+
return bounded(tag, nodes, horizon);
|
|
187
|
+
}
|
|
188
|
+
/**
|
|
189
|
+
* `window` with an own commit that is NOT on the canonical path added as a fork node: the commit was built from
|
|
190
|
+
* `parentState` (a node the window holds, with its snapshot) and a foreign commit at the same epoch won, so the tip
|
|
191
|
+
* stays where it is. The node carries `newState`'s snapshot, the own-commit record and the device's own leaf as
|
|
192
|
+
* sender — exactly what {@link extendWindow} stores for a confirmed own commit — so {@link restoreHistory} hands the
|
|
193
|
+
* engine's history tree the edge fork recovery needs to decrypt a peer's commit built on top of it.
|
|
194
|
+
*
|
|
195
|
+
* `undefined` when it cannot be retained: the parent is not in the window (or has no snapshot — it is the tip), or
|
|
196
|
+
* the node falls below the horizon. A node already in the window leaves it unchanged.
|
|
197
|
+
*/
|
|
198
|
+
export function withForkNode(window, link, horizon = REWIND_HORIZON) {
|
|
199
|
+
const parentTag = tagOf(link.parentState);
|
|
200
|
+
const tag = tagOf(link.newState);
|
|
201
|
+
if (window.nodes.has(tag))
|
|
202
|
+
return window;
|
|
203
|
+
if (window.nodes.get(parentTag)?.snapshot === undefined)
|
|
204
|
+
return undefined;
|
|
205
|
+
const nodes = new Map(window.nodes);
|
|
206
|
+
const sender = Number(link.parentState.privatePath.leafIndex);
|
|
207
|
+
nodes.set(tag, {
|
|
208
|
+
tag,
|
|
209
|
+
epoch: Number(link.newState.groupContext.epoch),
|
|
210
|
+
parentTag,
|
|
211
|
+
snapshot: serializeClientState(link.newState),
|
|
212
|
+
commit: commitRecord(link.commit, link.stamp),
|
|
213
|
+
digest: hexOf(commitDigest(link.commit)),
|
|
214
|
+
sender,
|
|
215
|
+
});
|
|
216
|
+
const out = bounded(window.tipTag, nodes, horizon);
|
|
217
|
+
return out.nodes.get(tag)?.parentTag === parentTag ? out : undefined;
|
|
218
|
+
}
|
|
219
|
+
/**
|
|
220
|
+
* `window` rewound onto its tip's parent: the tip node (and anything hanging off it) removed, the parent the new tip.
|
|
221
|
+
* Every other node stays — in particular each fork node whose ancestry reaches a kept canonical node, which is what lets
|
|
222
|
+
* a rebuilt engine weigh a competitor of the removed tip structurally, with no relay re-fetch. As everywhere, the tip
|
|
223
|
+
* carries no snapshot (the stored `clientState` is it).
|
|
224
|
+
*
|
|
225
|
+
* `undefined` when the window cannot be rewound: the tip has no link to a parent, the parent is not in the window, or
|
|
226
|
+
* it has no serialized state (the state the rewound `clientState` is read from).
|
|
227
|
+
*/
|
|
228
|
+
export function rewoundToParent(window) {
|
|
229
|
+
const removed = window.nodes.get(window.tipTag);
|
|
230
|
+
if (removed?.parentTag === undefined)
|
|
231
|
+
return undefined;
|
|
232
|
+
const parent = window.nodes.get(removed.parentTag);
|
|
233
|
+
if (parent?.snapshot === undefined)
|
|
234
|
+
return undefined;
|
|
235
|
+
const gone = new Set([removed.tag]);
|
|
236
|
+
for (let grew = true; grew;) {
|
|
237
|
+
grew = false;
|
|
238
|
+
for (const node of window.nodes.values()) {
|
|
239
|
+
if (gone.has(node.tag) || node.parentTag === undefined || !gone.has(node.parentTag))
|
|
240
|
+
continue;
|
|
241
|
+
gone.add(node.tag);
|
|
242
|
+
grew = true;
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
const nodes = new Map();
|
|
246
|
+
for (const node of window.nodes.values()) {
|
|
247
|
+
if (gone.has(node.tag))
|
|
248
|
+
continue;
|
|
249
|
+
if (node.tag === parent.tag) {
|
|
250
|
+
const { snapshot: _state, ...asTip } = node;
|
|
251
|
+
nodes.set(node.tag, asTip);
|
|
252
|
+
}
|
|
253
|
+
else
|
|
254
|
+
nodes.set(node.tag, node);
|
|
255
|
+
}
|
|
256
|
+
return { window: { tipTag: parent.tag, nodes }, removed, parent: parent };
|
|
257
|
+
}
|
|
258
|
+
/**
|
|
259
|
+
* `window` without the nodes not in `keep` (and anything hanging off them):
|
|
260
|
+
* what an engine's history held before a drain whose result was discarded.
|
|
261
|
+
* The tip is always kept.
|
|
262
|
+
*/
|
|
263
|
+
export function restrictWindow(window, keep) {
|
|
264
|
+
const nodes = new Map();
|
|
265
|
+
const kept = (node) => {
|
|
266
|
+
for (let n = node; n !== undefined; n = n.parentTag === undefined ? undefined : window.nodes.get(n.parentTag)) {
|
|
267
|
+
if (n.tag !== window.tipTag && !keep.has(n.tag))
|
|
268
|
+
return false;
|
|
269
|
+
if (n.tag === window.tipTag)
|
|
270
|
+
return true;
|
|
271
|
+
}
|
|
272
|
+
return true;
|
|
273
|
+
};
|
|
274
|
+
for (const node of window.nodes.values())
|
|
275
|
+
if (node.tag === window.tipTag || kept(node))
|
|
276
|
+
nodes.set(node.tag, node);
|
|
277
|
+
return { tipTag: window.tipTag, nodes };
|
|
278
|
+
}
|
|
279
|
+
/**
|
|
280
|
+
* The canonical path of `window`, root first. Total over any window: the walk from the tip stops at a node with
|
|
281
|
+
* no parent link, at a link leaving the window, and at a link back to a node already on the path (a cycle no
|
|
282
|
+
* window marmot writes has, but one a snapshot from elsewhere could carry — `openGroupSnapshot` refuses it); the
|
|
283
|
+
* path then starts at the node whose link was cut, with that link still set.
|
|
284
|
+
*/
|
|
285
|
+
export function canonicalPath(window) {
|
|
286
|
+
const out = [];
|
|
287
|
+
const seen = new Set();
|
|
288
|
+
for (let node = window.nodes.get(window.tipTag); node !== undefined && !seen.has(node.tag); node = node.parentTag === undefined ? undefined : window.nodes.get(node.parentTag)) {
|
|
289
|
+
seen.add(node.tag);
|
|
290
|
+
out.unshift(node);
|
|
291
|
+
}
|
|
292
|
+
return out;
|
|
293
|
+
}
|
|
294
|
+
// ---------------------------------------------------------------------------
|
|
295
|
+
// Persistence (the `rewindTree` artifact)
|
|
296
|
+
// ---------------------------------------------------------------------------
|
|
297
|
+
function encodeNode(node) {
|
|
298
|
+
return {
|
|
299
|
+
e: node.epoch,
|
|
300
|
+
...(node.parentTag === undefined ? {} : { p: node.parentTag }),
|
|
301
|
+
...(node.snapshot === undefined ? {} : { s: node.snapshot }),
|
|
302
|
+
...(node.commit === undefined ? {} : { c: node.commit }),
|
|
303
|
+
...(node.digest === undefined ? {} : { d: node.digest }),
|
|
304
|
+
...(node.sender === undefined ? {} : { l: node.sender }),
|
|
305
|
+
...(node.joinEvidence === undefined ? {} : { j: { d: node.joinEvidence.digest, c: node.joinEvidence.committer } }),
|
|
306
|
+
};
|
|
307
|
+
}
|
|
308
|
+
/** The join evidence of a stored node row: both fields 64 lowercase hex, else none (a malformed claim is no evidence). */
|
|
309
|
+
function evidenceOfStored(raw) {
|
|
310
|
+
if (typeof raw !== 'object' || raw === null || raw instanceof Uint8Array || Array.isArray(raw))
|
|
311
|
+
return undefined;
|
|
312
|
+
const { d, c } = raw;
|
|
313
|
+
return typeof d === 'string' && typeof c === 'string' && isHex64(d) && isHex64(c) ? { digest: d, committer: c } : undefined;
|
|
314
|
+
}
|
|
315
|
+
/** A stored sender leaf index: a non-negative safe integer, else none. */
|
|
316
|
+
export function senderOfStored(raw) {
|
|
317
|
+
return typeof raw === 'number' && Number.isSafeInteger(raw) && raw >= 0 ? raw : undefined;
|
|
318
|
+
}
|
|
319
|
+
/**
|
|
320
|
+
* The authenticated sender of a window node's commit `message`: the stored `sender`, else — a node written before
|
|
321
|
+
* senders were stored (ADR-016 AR-7) — the framing's, via the engine's one resolver. The single place this fallback is
|
|
322
|
+
* written for marmot (restoreHistory and the tests that re-derive a tip committer use it).
|
|
323
|
+
*/
|
|
324
|
+
export function senderOfNode(node, message) {
|
|
325
|
+
return node.sender ?? authenticatedSenderOf(undefined, message);
|
|
326
|
+
}
|
|
327
|
+
function decodeNode(tag, raw) {
|
|
328
|
+
if (typeof raw !== 'object' || raw === null || raw instanceof Uint8Array || Array.isArray(raw))
|
|
329
|
+
return undefined;
|
|
330
|
+
const r = raw;
|
|
331
|
+
if (typeof r.e !== 'number')
|
|
332
|
+
return undefined;
|
|
333
|
+
// Lenient, like every other optional field of this device's own store: a malformed sender is dropped and the node
|
|
334
|
+
// restores its sender from the framing (senderOfNode). A well-formed one is trusted like the stored `clientState`:
|
|
335
|
+
// only marmot writes this store, and an imported snapshot reaches it with senders re-derived from its commits
|
|
336
|
+
// (group-snapshot.ts authenticateWindowSenders), never with the claim it carried. An imported snapshot refuses a
|
|
337
|
+
// malformed sender instead (group-snapshot.ts decodeNode) — the split is deliberate (SC-1 note).
|
|
338
|
+
const sender = senderOfStored(r.l);
|
|
339
|
+
const joinEvidence = evidenceOfStored(r.j);
|
|
340
|
+
return {
|
|
341
|
+
tag,
|
|
342
|
+
epoch: r.e,
|
|
343
|
+
...(typeof r.p === 'string' ? { parentTag: r.p } : {}),
|
|
344
|
+
...(r.s instanceof Uint8Array ? { snapshot: r.s } : {}),
|
|
345
|
+
...(r.c instanceof Uint8Array ? { commit: r.c } : {}),
|
|
346
|
+
...(typeof r.d === 'string' ? { digest: r.d } : {}),
|
|
347
|
+
...(sender === undefined ? {} : { sender }),
|
|
348
|
+
...(joinEvidence === undefined ? {} : { joinEvidence }),
|
|
349
|
+
};
|
|
350
|
+
}
|
|
351
|
+
function sameBytes(a, b) {
|
|
352
|
+
if (a === b)
|
|
353
|
+
return true;
|
|
354
|
+
if (a === undefined || b === undefined || a.length !== b.length)
|
|
355
|
+
return false;
|
|
356
|
+
for (let i = 0; i < a.length; i++)
|
|
357
|
+
if (a[i] !== b[i])
|
|
358
|
+
return false;
|
|
359
|
+
return true;
|
|
360
|
+
}
|
|
361
|
+
function sameEvidence(a, b) {
|
|
362
|
+
return a === b || (a !== undefined && b !== undefined && a.digest === b.digest && a.committer === b.committer);
|
|
363
|
+
}
|
|
364
|
+
/** Whether two nodes carry the same content (tag, epoch, link, digest, sender, join evidence, snapshot, commit). */
|
|
365
|
+
export function sameNode(a, b) {
|
|
366
|
+
return (a.tag === b.tag &&
|
|
367
|
+
a.epoch === b.epoch &&
|
|
368
|
+
a.parentTag === b.parentTag &&
|
|
369
|
+
a.digest === b.digest &&
|
|
370
|
+
a.sender === b.sender &&
|
|
371
|
+
sameEvidence(a.joinEvidence, b.joinEvidence) &&
|
|
372
|
+
sameBytes(a.snapshot, b.snapshot) &&
|
|
373
|
+
sameBytes(a.commit, b.commit));
|
|
374
|
+
}
|
|
375
|
+
/** Whether two windows describe the same tip and the same nodes, content included. */
|
|
376
|
+
export function sameWindow(a, b) {
|
|
377
|
+
if (a.tipTag !== b.tipTag || a.nodes.size !== b.nodes.size)
|
|
378
|
+
return false;
|
|
379
|
+
for (const node of a.nodes.values()) {
|
|
380
|
+
const other = b.nodes.get(node.tag);
|
|
381
|
+
if (other === undefined || !sameNode(node, other))
|
|
382
|
+
return false;
|
|
383
|
+
}
|
|
384
|
+
return true;
|
|
385
|
+
}
|
|
386
|
+
/** Writes `window` over whatever window is stored (inside the caller's transaction): a node is rewritten when its content differs. */
|
|
387
|
+
export async function writeWindow(view, window) {
|
|
388
|
+
const tip = window.nodes.get(window.tipTag);
|
|
389
|
+
await view.put(TIP_KEY, { ...encodeNode(tip), t: tip.tag });
|
|
390
|
+
const wanted = new Set();
|
|
391
|
+
for (const node of window.nodes.values())
|
|
392
|
+
if (node.tag !== window.tipTag)
|
|
393
|
+
wanted.add(NODE_PREFIX + node.tag);
|
|
394
|
+
const stored = new Set((await view.keys()).filter((k) => k.startsWith(NODE_PREFIX)));
|
|
395
|
+
for (const key of stored)
|
|
396
|
+
if (!wanted.has(key))
|
|
397
|
+
await view.delete(key);
|
|
398
|
+
for (const node of window.nodes.values()) {
|
|
399
|
+
if (node.tag === window.tipTag)
|
|
400
|
+
continue;
|
|
401
|
+
const key = NODE_PREFIX + node.tag;
|
|
402
|
+
const current = stored.has(key) ? decodeNode(node.tag, await view.get(key)) : undefined;
|
|
403
|
+
if (current === undefined || !sameNode(current, node))
|
|
404
|
+
await view.put(key, encodeNode(node));
|
|
405
|
+
}
|
|
406
|
+
}
|
|
407
|
+
/** The stored window, or `undefined` when none (or an unreadable one) is stored. */
|
|
408
|
+
export async function readWindow(view) {
|
|
409
|
+
const rawTip = await view.get(TIP_KEY);
|
|
410
|
+
const tipTag = typeof rawTip === 'object' && rawTip !== null && !(rawTip instanceof Uint8Array) && !Array.isArray(rawTip) ? rawTip.t : undefined;
|
|
411
|
+
if (typeof tipTag !== 'string')
|
|
412
|
+
return undefined;
|
|
413
|
+
const tip = decodeNode(tipTag, rawTip);
|
|
414
|
+
if (tip === undefined)
|
|
415
|
+
return undefined;
|
|
416
|
+
const nodes = new Map([[tipTag, tip]]);
|
|
417
|
+
for (const key of await view.keys()) {
|
|
418
|
+
if (!key.startsWith(NODE_PREFIX))
|
|
419
|
+
continue;
|
|
420
|
+
const tag = key.slice(NODE_PREFIX.length);
|
|
421
|
+
const node = decodeNode(tag, await view.get(key));
|
|
422
|
+
if (node?.snapshot !== undefined)
|
|
423
|
+
nodes.set(tag, node);
|
|
424
|
+
}
|
|
425
|
+
return { tipTag, nodes };
|
|
426
|
+
}
|
|
427
|
+
// ---------------------------------------------------------------------------
|
|
428
|
+
// Restore into an engine
|
|
429
|
+
// ---------------------------------------------------------------------------
|
|
430
|
+
/**
|
|
431
|
+
* The window an engine built over `state` starts from, and the "before" of
|
|
432
|
+
* its next transition: the stored window whenever it describes `state` (its
|
|
433
|
+
* tip). That includes a multi-node window `restoreHistory` could not hand to
|
|
434
|
+
* the engine (a root without a snapshot, a broken link) — the next
|
|
435
|
+
* transition still diffs against what is persisted, so a withdrawal is never
|
|
436
|
+
* missed for a node the engine dropped. Otherwise the tip alone — with the join
|
|
437
|
+
* evidence of the stored node of that state, if the stored window holds one.
|
|
438
|
+
*/
|
|
439
|
+
export function windowFor(stored, state) {
|
|
440
|
+
const tag = tagOf(state);
|
|
441
|
+
// A stored window of another tip still names the state's node when it is one the device joined into: its evidence follows.
|
|
442
|
+
return stored !== undefined && stored.tipTag === tag ? stored : tipOnlyWindow(state, stored?.nodes.get(tag)?.joinEvidence);
|
|
443
|
+
}
|
|
444
|
+
/**
|
|
445
|
+
* The engine options that hand `window`'s history to an engine built over
|
|
446
|
+
* `state`, or `undefined` when the window does not describe `state` (another
|
|
447
|
+
* tip) or holds nothing beyond it. `state` itself is the tip, in both the tree
|
|
448
|
+
* and the retained store, so the engine and its retained tip are one object.
|
|
449
|
+
*/
|
|
450
|
+
export function restoreHistory(window, state) {
|
|
451
|
+
if (window === undefined || window.tipTag !== tagOf(state) || window.nodes.size <= 1)
|
|
452
|
+
return undefined;
|
|
453
|
+
const path = canonicalPath(window);
|
|
454
|
+
const root = path[0];
|
|
455
|
+
// A path cut by a cycle (its root still links into the window) is no history an engine can be handed.
|
|
456
|
+
if (root.parentTag !== undefined && window.nodes.has(root.parentTag))
|
|
457
|
+
return undefined;
|
|
458
|
+
// The root is the tip itself when nothing below it is retained (a state joined at that epoch): its state is
|
|
459
|
+
// `state` — the fork nodes hanging off it are still restored (S20: a removal's sibling must survive a reload).
|
|
460
|
+
if (root.snapshot === undefined && root.tag !== window.tipTag)
|
|
461
|
+
return undefined;
|
|
462
|
+
const states = new Map();
|
|
463
|
+
const stateOf = (node) => {
|
|
464
|
+
if (node.tag === window.tipTag)
|
|
465
|
+
return state;
|
|
466
|
+
if (node.snapshot === undefined)
|
|
467
|
+
return undefined;
|
|
468
|
+
let s = states.get(node.tag);
|
|
469
|
+
if (s === undefined)
|
|
470
|
+
states.set(node.tag, (s = deserializeClientState(node.snapshot)));
|
|
471
|
+
return s;
|
|
472
|
+
};
|
|
473
|
+
const historyTree = new GroupHistoryTree(root.tag === window.tipTag ? state : deserializeClientState(root.snapshot));
|
|
474
|
+
const ordered = [...window.nodes.values()].filter((n) => n.tag !== root.tag).sort((a, b) => a.epoch - b.epoch);
|
|
475
|
+
for (const node of ordered) {
|
|
476
|
+
if (node.parentTag === undefined || !historyTree.hasNode(node.parentTag))
|
|
477
|
+
continue;
|
|
478
|
+
const commit = commitOf(node);
|
|
479
|
+
// The tree serializes the child it records: hand it a copy, never the retained object itself.
|
|
480
|
+
const child = node.tag === window.tipTag ? state : node.snapshot === undefined ? undefined : deserializeClientState(node.snapshot);
|
|
481
|
+
if (commit === undefined || child === undefined)
|
|
482
|
+
continue;
|
|
483
|
+
// The committer's leaf index, not just the edge's identity, must survive
|
|
484
|
+
// a reload: `compareBranchScores`' `tip_committer` tie-break (fork-
|
|
485
|
+
// recovery.ts) needs it to agree with the pool-replay path's own
|
|
486
|
+
// derivation, or a tree-fed re-convergence pass can pick a different
|
|
487
|
+
// winner than live fork recovery did for the identical pair of branches
|
|
488
|
+
// (same-epoch-own-commit-fork, scenario 4/5 of fork-convergence.test.ts) —
|
|
489
|
+
// and equivocation credit needs it for a PrivateMessage-framed commit
|
|
490
|
+
// too, whose framing names no sender: the stored authenticated sender,
|
|
491
|
+
// else (a node written before it was stored) the framing's.
|
|
492
|
+
historyTree.recordCommit(node.parentTag, commit.message, child, senderOfNode(node, commit.message), commit.stamp);
|
|
493
|
+
}
|
|
494
|
+
const retained = new RetainedHistoryStore(stateOf(root), MARMOT_CONVERGENCE_POLICY);
|
|
495
|
+
for (let i = 1; i < path.length; i++) {
|
|
496
|
+
const parent = stateOf(path[i - 1]);
|
|
497
|
+
const child = stateOf(path[i]);
|
|
498
|
+
const commit = commitOf(path[i]);
|
|
499
|
+
if (parent === undefined || child === undefined || commit === undefined)
|
|
500
|
+
return undefined;
|
|
501
|
+
retained.record(parent, commit.message, child, [], commit.stamp);
|
|
502
|
+
}
|
|
503
|
+
return { retained, historyTree };
|
|
504
|
+
}
|
|
505
|
+
/** The MLS wire bytes of a commit message. */
|
|
506
|
+
export function wireOf(message) {
|
|
507
|
+
return encode(mlsMessageEncoder, message);
|
|
508
|
+
}
|
|
509
|
+
/** The digest of a link node's commit: its stored hex digest, when it is one. */
|
|
510
|
+
function linkDigest(node) {
|
|
511
|
+
return bytesOfHex64(node.digest);
|
|
512
|
+
}
|
|
513
|
+
/** The credential pubkey of the link's sender in the parent snapshot (`tipCommitterOf`), when the window holds what resolves it. */
|
|
514
|
+
function linkCommitter(window, node) {
|
|
515
|
+
const parent = node.parentTag === undefined ? undefined : window.nodes.get(node.parentTag);
|
|
516
|
+
if (parent?.snapshot === undefined)
|
|
517
|
+
return undefined;
|
|
518
|
+
try {
|
|
519
|
+
const commit = node.sender === undefined ? commitOf(node) : undefined;
|
|
520
|
+
const sender = node.sender ?? (commit === undefined ? undefined : senderOfNode(node, commit.message));
|
|
521
|
+
if (sender === undefined)
|
|
522
|
+
return undefined;
|
|
523
|
+
const committer = tipCommitterOf(deserializeClientState(parent.snapshot), sender);
|
|
524
|
+
return committer.length === 0 ? undefined : committer;
|
|
525
|
+
}
|
|
526
|
+
catch {
|
|
527
|
+
return undefined;
|
|
528
|
+
}
|
|
529
|
+
}
|
|
530
|
+
/**
|
|
531
|
+
* The held side of the comparison a Welcome for an already-held group is decided by (`compareBranchScores`, epic
|
|
532
|
+
* marmot-welcome-race-joiner): the branch whose tip is `tip`, scored the way the members score it with witnesses off:
|
|
533
|
+
* `validCommitDepth` and `effectiveCommitDepth` the tip epoch, no witness quorum, `appWitnessScore` 0.
|
|
534
|
+
*
|
|
535
|
+
* `tipDigest` is the digest of the tip's own link when the tip has one (it was produced by a commit this window
|
|
536
|
+
* holds), else the digest of the join evidence recorded when the device joined into the tip; `tipCommitter` is the
|
|
537
|
+
* credential pubkey of the link's sender in the parent snapshot (`tipCommitterOf`), else the join evidence's
|
|
538
|
+
* committer. A tip with a link never mixes in the evidence (it describes another commit).
|
|
539
|
+
*
|
|
540
|
+
* A digest or committer the window cannot supply makes the result `{ complete: false, missing }` with no score, and a
|
|
541
|
+
* window that does not describe `tip` is incomplete on both.
|
|
542
|
+
*/
|
|
543
|
+
export function heldBranchScore(window, tip) {
|
|
544
|
+
const depth = Number(tip.groupContext.epoch);
|
|
545
|
+
const node = window.tipTag === tagOf(tip) ? window.nodes.get(window.tipTag) : undefined;
|
|
546
|
+
let digest;
|
|
547
|
+
let committer;
|
|
548
|
+
if (node !== undefined) {
|
|
549
|
+
if (node.parentTag !== undefined) {
|
|
550
|
+
digest = linkDigest(node);
|
|
551
|
+
committer = linkCommitter(window, node);
|
|
552
|
+
}
|
|
553
|
+
else {
|
|
554
|
+
digest = bytesOfHex64(node.joinEvidence?.digest);
|
|
555
|
+
committer = bytesOfHex64(node.joinEvidence?.committer);
|
|
556
|
+
}
|
|
557
|
+
}
|
|
558
|
+
if (digest === undefined || committer === undefined) {
|
|
559
|
+
return { complete: false, missing: [...(digest === undefined ? ['digest'] : []), ...(committer === undefined ? ['committer'] : [])] };
|
|
560
|
+
}
|
|
561
|
+
return {
|
|
562
|
+
complete: true,
|
|
563
|
+
score: { validCommitDepth: depth, effectiveCommitDepth: depth, witnessQuorumMet: false, appWitnessScore: 0, tipDigest: digest, tipCommitter: committer },
|
|
564
|
+
};
|
|
565
|
+
}
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The inbox demux (S7): what S6's rumor dispatch point (`subscription.ts`
|
|
3
|
+
* `deps.dispatch`) does with each unwrapped rumor. It runs on the inbox's
|
|
4
|
+
* serial queue, one rumor at a time, and never inside a store transaction.
|
|
5
|
+
*
|
|
6
|
+
* 1. `RUMOR_KINDS.WELCOME` → S6's Welcome processor.
|
|
7
|
+
* 2. `RUMOR_KINDS.ENROLMENT_REQUEST` / `KEYPACKAGE_OFFER` → the native
|
|
8
|
+
* handler installed for that kind through {@link RumorDemux.setNativeHandler}
|
|
9
|
+
* (same-account enrolment and KeyPackage offers, S8). Until one is
|
|
10
|
+
* installed such a rumor is `unhandled` (marked seen): it is never handed
|
|
11
|
+
* to consumer code, which could not act on it anyway.
|
|
12
|
+
* 3. A kind claimed through `registerInboxHandler` → that handler
|
|
13
|
+
* (AC-INBOX-5; how `account-sync` receives its bootstrap blobs).
|
|
14
|
+
* 4. Anything else — including `RUMOR_KINDS.DECLINE`, the app-level decline
|
|
15
|
+
* (ADR-008) — → `onApplicationRumor`, unmodified (AC-INBOX-2); `unhandled`
|
|
16
|
+
* when the consumer supplied none. A DECLINE first passes the native
|
|
17
|
+
* bookkeeping hook ({@link RumorDemuxDeps.decline}, AC-HYG-3), which only
|
|
18
|
+
* records — its rumor's route and disposition stay exactly as above.
|
|
19
|
+
*
|
|
20
|
+
* Consumer callbacks (3, 4) are invoked through the re-entrancy guard
|
|
21
|
+
* (`callConsumer`, ADR-013) with frozen copies of the rumor and the wrap.
|
|
22
|
+
* Delivery is at-least-once: the subscription marks the wrap seen only after
|
|
23
|
+
* the callback resolved (`delivered`), so a crash or reload in between
|
|
24
|
+
* redelivers it. A callback that throws yields a COUNTED `deferred`
|
|
25
|
+
* (`handler-failed`): the wrap is retried by later passes, and after the
|
|
26
|
+
* inbox's processing-failure cap (S6, default 10) it is dropped as
|
|
27
|
+
* `rejected('processing-failed')` and marked seen. Every consumer failure
|
|
28
|
+
* counts, whatever it wraps: `marmot` cannot tell whether a consumer's error
|
|
29
|
+
* is transient, and an uncounted retry would keep the wrap (and its retry
|
|
30
|
+
* passes) forever. The counted deferral stores the unwrapped rumor with the
|
|
31
|
+
* wrap, so a retry redispatches it without a second signer unwrap (no
|
|
32
|
+
* repeated bunker prompt; handler-retry-reunwraps-wrap). A handler that must
|
|
33
|
+
* survive a longer outage stores the rumor itself and returns.
|
|
34
|
+
*
|
|
35
|
+
* Handlers must not await long work: the queue waits for each one. A call
|
|
36
|
+
* still running after `handlerBudget.ms` is reported once (`handlerSlow`,
|
|
37
|
+
* inbox-handler-time-budget) — a diagnostic only: it is neither detached nor
|
|
38
|
+
* redelivered, and the queue keeps waiting for it.
|
|
39
|
+
*/
|
|
40
|
+
import type { NostrEvent, Rumor } from '@941design/nostr-events/event';
|
|
41
|
+
import { RUMOR_KINDS } from '../shared/index.js';
|
|
42
|
+
import type { InboxHandlerRegistry, InboxRumorHandler } from './handler-registry.js';
|
|
43
|
+
import { type DispatchContext, type RumorDisposition } from './subscription.js';
|
|
44
|
+
/** A `marmot`-internal handler for a reserved rumor kind: the dispatch point's own signature (it may mark the wrap seen inside its final transaction). */
|
|
45
|
+
export type NativeRumorHandler = (rumor: Rumor, wrap: NostrEvent, ctx: DispatchContext) => Promise<RumorDisposition>;
|
|
46
|
+
/** The reserved kinds whose owner installs a native handler (S8). */
|
|
47
|
+
export type NativeRumorKind = typeof RUMOR_KINDS.ENROLMENT_REQUEST | typeof RUMOR_KINDS.KEYPACKAGE_OFFER;
|
|
48
|
+
/** The consumer surfaces the demux calls into (the re-entrancy guard's names for them). */
|
|
49
|
+
export type InboxConsumerSurface = 'inboxHandler' | 'onApplicationRumor';
|
|
50
|
+
export interface RumorDemuxDeps {
|
|
51
|
+
/** S6's Welcome processor. */
|
|
52
|
+
welcome(rumor: Rumor, wrap: NostrEvent, ctx: DispatchContext): Promise<RumorDisposition>;
|
|
53
|
+
readonly handlers: InboxHandlerRegistry;
|
|
54
|
+
/** The consumer's `onApplicationRumor`, if it supplied one. */
|
|
55
|
+
readonly application: InboxRumorHandler | undefined;
|
|
56
|
+
/**
|
|
57
|
+
* AC-HYG-3: native bookkeeping of a `RUMOR_KINDS.DECLINE` rumor (the inviter's Welcome delivery it declines),
|
|
58
|
+
* run before the rumor's unchanged route. Must tolerate redelivery (at-least-once). A transient failure (store
|
|
59
|
+
* lease, signer timeout, …) defers the wrap uncounted, so the bookkeeping and the delivery are both retried; any
|
|
60
|
+
* other failure skips the bookkeeping and the rumor is still delivered.
|
|
61
|
+
*/
|
|
62
|
+
decline?(rumor: Rumor): Promise<void>;
|
|
63
|
+
/** Runs `fn` (a call into consumer code) through the client's re-entrancy guard. */
|
|
64
|
+
callConsumer(surface: InboxConsumerSurface, fn: () => void | Promise<void>): Promise<void>;
|
|
65
|
+
/**
|
|
66
|
+
* inbox-handler-time-budget: `onSlow` is called once for a consumer call still running `ms` after it started
|
|
67
|
+
* (`ms` 0: never). Omitted: no budget.
|
|
68
|
+
*/
|
|
69
|
+
readonly handlerBudget?: {
|
|
70
|
+
readonly ms: number;
|
|
71
|
+
readonly timers: {
|
|
72
|
+
set(callback: () => void, ms: number): unknown;
|
|
73
|
+
clear(handle: unknown): void;
|
|
74
|
+
};
|
|
75
|
+
onSlow(slow: {
|
|
76
|
+
readonly surface: InboxConsumerSurface;
|
|
77
|
+
readonly rumorKind: number;
|
|
78
|
+
readonly wrapId: string;
|
|
79
|
+
readonly budgetMs: number;
|
|
80
|
+
}): void;
|
|
81
|
+
};
|
|
82
|
+
isDisposed(): boolean;
|
|
83
|
+
}
|
|
84
|
+
export interface RumorDemux {
|
|
85
|
+
/** The rumor dispatch point (`InboxSubscriptionDeps.dispatch`). */
|
|
86
|
+
dispatch(rumor: Rumor, wrap: NostrEvent, ctx: DispatchContext): Promise<RumorDisposition>;
|
|
87
|
+
/** Installs (or, with `undefined`, removes) the native handler of a reserved kind S8 owns. */
|
|
88
|
+
setNativeHandler(kind: NativeRumorKind, handler: NativeRumorHandler | undefined): void;
|
|
89
|
+
}
|
|
90
|
+
export declare function createRumorDemux(deps: RumorDemuxDeps): RumorDemux;
|