@941design/marmot 0.0.0-stage → 0.2.0-alpha.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +709 -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 +127 -0
- package/dist/account/teardown.js +856 -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 +180 -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 +68 -0
- package/dist/client/commit-redrive.js +221 -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 +50 -0
- package/dist/client/confirm-hooks.js +59 -0
- package/dist/client/create-client.d.ts +1022 -0
- package/dist/client/create-client.js +1125 -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 +435 -0
- package/dist/client/group-history.js +1295 -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 +485 -0
- package/dist/client/group-records.js +1034 -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 +388 -0
- package/dist/client/group-runtime.js +2701 -0
- package/dist/client/group-snapshot.d.ts +98 -0
- package/dist/client/group-snapshot.js +453 -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 +21 -0
- package/dist/client/index.js +13 -0
- package/dist/client/ingest.d.ts +82 -0
- package/dist/client/ingest.js +1550 -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 +81 -0
- package/dist/client/opaque-candidates.js +169 -0
- package/dist/client/own-change-outbox.d.ts +66 -0
- package/dist/client/own-change-outbox.js +156 -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 +554 -0
- package/dist/client/pipeline.js +3545 -0
- package/dist/client/reentrancy-guard.d.ts +96 -0
- package/dist/client/reentrancy-guard.js +153 -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/equivocation.d.ts +55 -0
- package/dist/history/equivocation.js +113 -0
- package/dist/history/fencing.d.ts +25 -0
- package/dist/history/fencing.js +61 -0
- package/dist/history/hex.d.ts +3 -0
- package/dist/history/hex.js +10 -0
- package/dist/history/index.d.ts +73 -0
- package/dist/history/index.js +31 -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 +106 -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 +61 -0
- package/dist/invitations/decline.js +143 -0
- package/dist/invitations/expect-welcome.d.ts +66 -0
- package/dist/invitations/expect-welcome.js +138 -0
- package/dist/invitations/index.d.ts +16 -0
- package/dist/invitations/index.js +16 -0
- package/dist/invitations/invite.d.ts +303 -0
- package/dist/invitations/invite.js +966 -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 +253 -0
- package/dist/invitations/welcome-processor.js +1180 -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 +21 -0
- package/dist/shared/errors.js +85 -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 +227 -0
- package/dist/storage/index.js +459 -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 +41 -0
- package/dist/storage/lease.js +117 -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,63 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Lifecycle events (S7, AC-INBOX-6): `enrolmentApproved`, `deviceForgotten`
|
|
3
|
+
* and `groupCreated` — and, since epic marmot-device-key-rotation, `deviceKeyRotated`
|
|
4
|
+
* and `deviceKeyRotationSettled` — fire only AFTER the transaction(s) that made them true
|
|
5
|
+
* committed — never before, never for an operation whose commit failed.
|
|
6
|
+
*
|
|
7
|
+
* The discipline is structural: an operation hands its committing step to
|
|
8
|
+
* {@link LifecycleEvents.afterCommit}, which awaits it and emits with the
|
|
9
|
+
* payload built from its result. There is no other emit path for any
|
|
10
|
+
* `LifecycleEventPayloads` member inside the client (`groups.create` uses it since S7; same-account
|
|
11
|
+
* enrolment approval and `devices.forget` (S8) call it the same way).
|
|
12
|
+
*
|
|
13
|
+
* Payloads are frozen copies: a listener cannot mutate what the operation
|
|
14
|
+
* still holds (the `groups` arrays in particular). Listener errors never
|
|
15
|
+
* reach the operation (the client's `emit` swallows them).
|
|
16
|
+
*/
|
|
17
|
+
import type { DeviceKeyRotationGroupOutcome } from '../key-packages/index.js';
|
|
18
|
+
export interface LifecycleEventPayloads {
|
|
19
|
+
/** A sibling device's enrolment was approved and committed (S8). */
|
|
20
|
+
enrolmentApproved: {
|
|
21
|
+
readonly account: string;
|
|
22
|
+
readonly leafIndex: number;
|
|
23
|
+
readonly leafKey: string;
|
|
24
|
+
readonly groups: readonly string[];
|
|
25
|
+
};
|
|
26
|
+
/** A device (leaf) was forgotten; `groups` still holding the leaf, if any (S8, AC-DEV-7). */
|
|
27
|
+
deviceForgotten: {
|
|
28
|
+
readonly leafKey: string;
|
|
29
|
+
readonly groups: readonly string[];
|
|
30
|
+
};
|
|
31
|
+
/** A group was created and persisted (its state and its account index entry). */
|
|
32
|
+
groupCreated: {
|
|
33
|
+
readonly groupId: string;
|
|
34
|
+
};
|
|
35
|
+
/**
|
|
36
|
+
* `devices.rotateKey()` committed its prepare transaction (epic marmot-device-key-rotation, S7, AC-ROT-8): `to` is now the
|
|
37
|
+
* device key, `from` the keys it replaces and `groups` the held groups whose own leaf the rotation re-keys. Fires once per
|
|
38
|
+
* rotation, never for one whose prepare failed, and — like `deviceForgotten` — at most once: a crash between the commit and
|
|
39
|
+
* the emit loses it, so a consumer must not depend on it for correctness.
|
|
40
|
+
*/
|
|
41
|
+
deviceKeyRotated: {
|
|
42
|
+
readonly rotationId: string;
|
|
43
|
+
readonly from: readonly string[];
|
|
44
|
+
readonly to: string;
|
|
45
|
+
readonly groups: readonly string[];
|
|
46
|
+
};
|
|
47
|
+
/** Every group of a rotation reached a terminal outcome and the rotation was recorded settled (or given up); fires once per rotation. */
|
|
48
|
+
deviceKeyRotationSettled: {
|
|
49
|
+
readonly rotationId: string;
|
|
50
|
+
readonly perGroupOutcome: Readonly<Record<string, DeviceKeyRotationGroupOutcome>>;
|
|
51
|
+
};
|
|
52
|
+
}
|
|
53
|
+
export type LifecycleEventName = keyof LifecycleEventPayloads;
|
|
54
|
+
export interface LifecycleEvents {
|
|
55
|
+
/**
|
|
56
|
+
* Runs `commit` — the operation's committing step (its store
|
|
57
|
+
* transaction(s)) — and, once it resolved, emits `event` with
|
|
58
|
+
* `payload(result)`. A rejected `commit` emits nothing and rejects with
|
|
59
|
+
* its error. Resolves with `commit`'s result after the emit.
|
|
60
|
+
*/
|
|
61
|
+
afterCommit<E extends LifecycleEventName, T>(event: E, commit: () => Promise<T>, payload: (result: T) => LifecycleEventPayloads[E]): Promise<T>;
|
|
62
|
+
}
|
|
63
|
+
export declare function createLifecycleEvents(emit: <E extends LifecycleEventName>(event: E, payload: LifecycleEventPayloads[E]) => void): LifecycleEvents;
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Lifecycle events (S7, AC-INBOX-6): `enrolmentApproved`, `deviceForgotten`
|
|
3
|
+
* and `groupCreated` — and, since epic marmot-device-key-rotation, `deviceKeyRotated`
|
|
4
|
+
* and `deviceKeyRotationSettled` — fire only AFTER the transaction(s) that made them true
|
|
5
|
+
* committed — never before, never for an operation whose commit failed.
|
|
6
|
+
*
|
|
7
|
+
* The discipline is structural: an operation hands its committing step to
|
|
8
|
+
* {@link LifecycleEvents.afterCommit}, which awaits it and emits with the
|
|
9
|
+
* payload built from its result. There is no other emit path for any
|
|
10
|
+
* `LifecycleEventPayloads` member inside the client (`groups.create` uses it since S7; same-account
|
|
11
|
+
* enrolment approval and `devices.forget` (S8) call it the same way).
|
|
12
|
+
*
|
|
13
|
+
* Payloads are frozen copies: a listener cannot mutate what the operation
|
|
14
|
+
* still holds (the `groups` arrays in particular). Listener errors never
|
|
15
|
+
* reach the operation (the client's `emit` swallows them).
|
|
16
|
+
*/
|
|
17
|
+
function frozenPayload(payload) {
|
|
18
|
+
const copy = { ...payload };
|
|
19
|
+
if (Array.isArray(copy.groups))
|
|
20
|
+
copy.groups = Object.freeze([...copy.groups]);
|
|
21
|
+
if (Array.isArray(copy.from))
|
|
22
|
+
copy.from = Object.freeze([...copy.from]);
|
|
23
|
+
if (typeof copy.perGroupOutcome === 'object' && copy.perGroupOutcome !== null)
|
|
24
|
+
copy.perGroupOutcome = Object.freeze({ ...copy.perGroupOutcome });
|
|
25
|
+
return Object.freeze(copy);
|
|
26
|
+
}
|
|
27
|
+
export function createLifecycleEvents(emit) {
|
|
28
|
+
return {
|
|
29
|
+
async afterCommit(event, commit, payload) {
|
|
30
|
+
const result = await commit();
|
|
31
|
+
emit(event, frozenPayload(payload(result)));
|
|
32
|
+
return result;
|
|
33
|
+
},
|
|
34
|
+
};
|
|
35
|
+
}
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Epic `marmot-branch-aware-own-leaf-fence` S8 (AC-PERS-1, AC-PERS-6, AC-PERS-11..13): the engine's held opaque
|
|
3
|
+
* candidates and its undecryptable set `U`, persisted.
|
|
4
|
+
*
|
|
5
|
+
* The engine (`MarmotGroupEngine.opaque`) holds every opaque candidate it judged `skipped` — a commit that
|
|
6
|
+
* authenticated at a node of the history tree but failed with the lost-path-secrets error — together with its
|
|
7
|
+
* ORIGINAL envelope, and decides it again on every convergence pass: a later pass may find that it could win, and
|
|
8
|
+
* then the group is fenced with that envelope. A `skipped` is therefore provisional, and only as durable as the
|
|
9
|
+
* record that holds it. The record is the group extension `marmot.opaque`, written in the SAME transaction as the
|
|
10
|
+
* batch that ledgers the provisional `skipped` (client/ingest.ts) — never before, never after — and handed back to
|
|
11
|
+
* every engine of the group on load, reload and rollback (client/group-runtime.ts), exactly as `marmot.removal` is.
|
|
12
|
+
*
|
|
13
|
+
* What is stored is the engine's record VERBATIM (`HeldOpaqueRecord<NostrEvent>`): the candidates (digest, parent
|
|
14
|
+
* tag, epoch, sender, error message, the full Nostr event the engine was handed) and `U`. The event comes back
|
|
15
|
+
* field for field because the `unreadable` the engine yields later carries it and the client fences and ledgers
|
|
16
|
+
* by it. `U` is persisted with the candidates: a rebuilt engine that lost it would undercount hidden edges and
|
|
17
|
+
* could skip a commit that should fence.
|
|
18
|
+
*
|
|
19
|
+
* Fail closed. The extension is read from a store, so its bytes are untrusted: a record of the wrong shape,
|
|
20
|
+
* with more than {@link MAX_HELD_OPAQUE_CANDIDATES} candidates, with a non-hex digest or a malformed event is
|
|
21
|
+
* CORRUPT. {@link readOpaque} throws {@link OpaqueRecordCorrupt} for it, and the caller (the group's load and
|
|
22
|
+
* reload) FENCES the group: reading it as "nothing held" would forget a candidate that may still be able to win
|
|
23
|
+
* (the unsafe direction), and handing it on would make the engine's constructor throw a `TypeError` and brick the
|
|
24
|
+
* load for good. A fenced group stays loadable, refuses to send and never processes input. An ABSENT extension is
|
|
25
|
+
* the empty record, not corruption.
|
|
26
|
+
*
|
|
27
|
+
* Size and write amplification (BACKLOG engine-undecryptable-set-unbounded; measured in
|
|
28
|
+
* `test/client/opaque-persistence.test.ts`, "record size and write amplification"):
|
|
29
|
+
* - The candidates are capped by the engine (16). An event is the Nostr envelope of one MLS commit: a few KiB.
|
|
30
|
+
* - `U` is bounded by the engine's cap (`MAX_UNDECRYPTABLE_IDS`, 1,024 ids: at most about 69 KB). One id is 64 hex
|
|
31
|
+
* characters, 67 bytes with its quotes and comma in the stored JSON. The id that would exceed the cap SATURATES
|
|
32
|
+
* `U`: the engine drops every id and the record carries one flag, `undecryptableSaturated` (about 30 bytes), which
|
|
33
|
+
* the engine reads as an unbounded count, so every opaque candidate fences (today's behaviour). That is the only
|
|
34
|
+
* safe direction: dropping an id and keeping a count would undercount hidden edges (a junk flood could then turn
|
|
35
|
+
* a fence into a skip). Saturation is sticky — a dropped id can no longer be told to have decrypted — and is
|
|
36
|
+
* persisted and restored like the ids it replaces. A record with ids and the flag is read as saturated.
|
|
37
|
+
* - The record is one value, so a change rewrites all of it: a batch that adds ids writes `|record|` bytes once,
|
|
38
|
+
* however many events it carried; `n` junk envelopes delivered in `n` separate batches write it `n` times
|
|
39
|
+
* (about `34 * n^2` bytes in total for ids alone, `n` at most the cap, then nothing). A batch that changed
|
|
40
|
+
* neither the candidates nor `U` writes nothing ({@link nextOpaque}). Sharding `U` per id would make growth
|
|
41
|
+
* O(delta); the cap makes it bounded instead.
|
|
42
|
+
*/
|
|
43
|
+
import type { HeldOpaqueRecord } from '@941design/marmot-engine/engine';
|
|
44
|
+
import type { NostrEvent } from '@941design/nostr-events/event';
|
|
45
|
+
import type { KeyValueView } from '../storage/index.js';
|
|
46
|
+
/** Group extension holding the opaque record (one value). */
|
|
47
|
+
export declare const OPAQUE_EXTENSION = "marmot.opaque";
|
|
48
|
+
/** The engine's record, as the client persists it. */
|
|
49
|
+
export type OpaqueRecord = HeldOpaqueRecord<NostrEvent>;
|
|
50
|
+
/** What an absent extension reads as. */
|
|
51
|
+
export declare const EMPTY_OPAQUE: OpaqueRecord;
|
|
52
|
+
/** The stored `marmot.opaque` record is not a valid engine record: the group cannot be known safe (see the module comment). */
|
|
53
|
+
export declare class OpaqueRecordCorrupt extends Error {
|
|
54
|
+
readonly reason: string;
|
|
55
|
+
readonly name = "OpaqueRecordCorrupt";
|
|
56
|
+
constructor(reason: string);
|
|
57
|
+
}
|
|
58
|
+
/** Whether `record` holds nothing (the engine exposes that as `undefined`). */
|
|
59
|
+
export declare function isEmptyOpaque(record: OpaqueRecord | undefined): boolean;
|
|
60
|
+
/**
|
|
61
|
+
* Validates a stored value as an engine record. Throws {@link OpaqueRecordCorrupt}; never returns a partial record.
|
|
62
|
+
* Exported for the tests that feed it malformed shapes.
|
|
63
|
+
*/
|
|
64
|
+
export declare function parseOpaque(raw: unknown): OpaqueRecord;
|
|
65
|
+
/**
|
|
66
|
+
* The group's stored record; the empty record while the extension holds none. Throws {@link OpaqueRecordCorrupt}
|
|
67
|
+
* for a value that is not a valid record.
|
|
68
|
+
*/
|
|
69
|
+
export declare function readOpaque(view: KeyValueView): Promise<OpaqueRecord>;
|
|
70
|
+
/** Writes (or replaces) the record inside the caller's transaction. */
|
|
71
|
+
export declare function writeOpaque(view: KeyValueView, record: OpaqueRecord): Promise<void>;
|
|
72
|
+
export declare function clearOpaque(view: KeyValueView): Promise<void>;
|
|
73
|
+
/** Whether two records hold the same candidates (field for field, the event by id and signature) and the same `U`. */
|
|
74
|
+
export declare function sameOpaque(a: OpaqueRecord | undefined, b: OpaqueRecord | undefined): boolean;
|
|
75
|
+
/**
|
|
76
|
+
* What to persist after the engine's record moved from `before` (the stored one, `undefined` = none) to `now`
|
|
77
|
+
* (`engine.opaque`): `undefined` = unchanged (nothing to write — the engine returns the same object while neither
|
|
78
|
+
* the held set nor `U` changed, and a rebuilt engine's equal record is recognised by content), `null` = it became
|
|
79
|
+
* empty (delete), else the new record. A change of `U` alone is a change.
|
|
80
|
+
*/
|
|
81
|
+
export declare function nextOpaque(before: OpaqueRecord | undefined, now: OpaqueRecord | undefined): OpaqueRecord | null | undefined;
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
import { MAX_HELD_OPAQUE_CANDIDATES } from '@941design/marmot-engine/engine';
|
|
2
|
+
/** Group extension holding the opaque record (one value). */
|
|
3
|
+
export const OPAQUE_EXTENSION = 'marmot.opaque';
|
|
4
|
+
const KEY = 'opaque';
|
|
5
|
+
/** The longest `U` id accepted on read (event ids are 64 hex characters; the margin keeps any transport's id form). */
|
|
6
|
+
const MAX_ID_LENGTH = 128;
|
|
7
|
+
/** What an absent extension reads as. */
|
|
8
|
+
export const EMPTY_OPAQUE = Object.freeze({ candidates: Object.freeze([]), undecryptableIds: Object.freeze([]) });
|
|
9
|
+
/** The stored `marmot.opaque` record is not a valid engine record: the group cannot be known safe (see the module comment). */
|
|
10
|
+
export class OpaqueRecordCorrupt extends Error {
|
|
11
|
+
reason;
|
|
12
|
+
name = 'OpaqueRecordCorrupt';
|
|
13
|
+
constructor(reason) {
|
|
14
|
+
super(`marmot.opaque is corrupt: ${reason}`);
|
|
15
|
+
this.reason = reason;
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
/** Whether `record` holds nothing (the engine exposes that as `undefined`). */
|
|
19
|
+
export function isEmptyOpaque(record) {
|
|
20
|
+
return record === undefined || (record.candidates.length === 0 && record.undecryptableIds.length === 0 && record.undecryptableSaturated !== true);
|
|
21
|
+
}
|
|
22
|
+
const isHex = (value, length) => typeof value === 'string' && /^(?:[0-9a-f]{2})+$/.test(value) && (length === undefined || value.length === length);
|
|
23
|
+
const isCount = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
|
|
24
|
+
function eventOf(raw) {
|
|
25
|
+
const corrupt = (what) => {
|
|
26
|
+
throw new OpaqueRecordCorrupt(`a candidate's event ${what}`);
|
|
27
|
+
};
|
|
28
|
+
if (typeof raw !== 'object' || raw === null || Array.isArray(raw) || raw instanceof Uint8Array)
|
|
29
|
+
return corrupt('is not an object');
|
|
30
|
+
const e = raw;
|
|
31
|
+
if (typeof e.id !== 'string' || e.id.length === 0 || e.id.length > MAX_ID_LENGTH)
|
|
32
|
+
return corrupt('has no id');
|
|
33
|
+
if (typeof e.pubkey !== 'string')
|
|
34
|
+
return corrupt('has no pubkey');
|
|
35
|
+
if (!isCount(e.kind))
|
|
36
|
+
return corrupt('has no kind');
|
|
37
|
+
if (!isCount(e.created_at))
|
|
38
|
+
return corrupt('has no created_at');
|
|
39
|
+
if (typeof e.content !== 'string')
|
|
40
|
+
return corrupt('has no content');
|
|
41
|
+
if (typeof e.sig !== 'string')
|
|
42
|
+
return corrupt('has no sig');
|
|
43
|
+
if (!Array.isArray(e.tags) || !e.tags.every((t) => Array.isArray(t) && t.every((x) => typeof x === 'string')))
|
|
44
|
+
return corrupt('has malformed tags');
|
|
45
|
+
return e;
|
|
46
|
+
}
|
|
47
|
+
function candidateOf(raw) {
|
|
48
|
+
const corrupt = (what) => {
|
|
49
|
+
throw new OpaqueRecordCorrupt(`a candidate ${what}`);
|
|
50
|
+
};
|
|
51
|
+
if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
|
|
52
|
+
return corrupt('is not an object');
|
|
53
|
+
const c = raw;
|
|
54
|
+
if (!isHex(c.digest, 64))
|
|
55
|
+
return corrupt('digest is not 32-byte hex');
|
|
56
|
+
if (!isHex(c.parentTag))
|
|
57
|
+
return corrupt('parent tag is not hex');
|
|
58
|
+
if (!isCount(c.epoch))
|
|
59
|
+
return corrupt('epoch is not a non-negative integer');
|
|
60
|
+
if (c.sender !== undefined && !isCount(c.sender))
|
|
61
|
+
return corrupt('sender is not a non-negative integer');
|
|
62
|
+
if (typeof c.errorMessage !== 'string')
|
|
63
|
+
return corrupt('error message is not a string');
|
|
64
|
+
if (c.decided !== undefined && c.decided !== 'fenced')
|
|
65
|
+
return corrupt('decided mark is unknown');
|
|
66
|
+
const event = eventOf(c.event);
|
|
67
|
+
return {
|
|
68
|
+
digest: c.digest,
|
|
69
|
+
parentTag: c.parentTag,
|
|
70
|
+
epoch: c.epoch,
|
|
71
|
+
...(c.sender === undefined ? {} : { sender: c.sender }),
|
|
72
|
+
errorMessage: c.errorMessage,
|
|
73
|
+
event,
|
|
74
|
+
...(c.decided === undefined ? {} : { decided: 'fenced' }),
|
|
75
|
+
};
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Validates a stored value as an engine record. Throws {@link OpaqueRecordCorrupt}; never returns a partial record.
|
|
79
|
+
* Exported for the tests that feed it malformed shapes.
|
|
80
|
+
*/
|
|
81
|
+
export function parseOpaque(raw) {
|
|
82
|
+
if (typeof raw !== 'object' || raw === null || Array.isArray(raw) || raw instanceof Uint8Array)
|
|
83
|
+
throw new OpaqueRecordCorrupt('not a record');
|
|
84
|
+
const r = raw;
|
|
85
|
+
if (!Array.isArray(r.candidates))
|
|
86
|
+
throw new OpaqueRecordCorrupt('candidates is not a list');
|
|
87
|
+
if (!Array.isArray(r.undecryptableIds))
|
|
88
|
+
throw new OpaqueRecordCorrupt('undecryptableIds is not a list');
|
|
89
|
+
// Present only as `true`: a flag that is anything else is not read as "unsaturated" (the unsafe direction).
|
|
90
|
+
if (r.undecryptableSaturated !== undefined && r.undecryptableSaturated !== true)
|
|
91
|
+
throw new OpaqueRecordCorrupt('undecryptableSaturated is not true');
|
|
92
|
+
if (r.candidates.length > MAX_HELD_OPAQUE_CANDIDATES)
|
|
93
|
+
throw new OpaqueRecordCorrupt(`more than ${String(MAX_HELD_OPAQUE_CANDIDATES)} candidates (${String(r.candidates.length)})`);
|
|
94
|
+
const candidates = r.candidates.map(candidateOf);
|
|
95
|
+
if (new Set(candidates.map((c) => c.digest)).size !== candidates.length)
|
|
96
|
+
throw new OpaqueRecordCorrupt('two candidates share a digest');
|
|
97
|
+
const ids = [];
|
|
98
|
+
for (const id of r.undecryptableIds) {
|
|
99
|
+
if (typeof id !== 'string' || id.length === 0 || id.length > MAX_ID_LENGTH)
|
|
100
|
+
throw new OpaqueRecordCorrupt('an undecryptable id is not a short non-empty string');
|
|
101
|
+
ids.push(id);
|
|
102
|
+
}
|
|
103
|
+
return { candidates, undecryptableIds: ids, ...(r.undecryptableSaturated === true ? { undecryptableSaturated: true } : {}) };
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* The group's stored record; the empty record while the extension holds none. Throws {@link OpaqueRecordCorrupt}
|
|
107
|
+
* for a value that is not a valid record.
|
|
108
|
+
*/
|
|
109
|
+
export async function readOpaque(view) {
|
|
110
|
+
const raw = await view.get(KEY);
|
|
111
|
+
if (raw === undefined)
|
|
112
|
+
return EMPTY_OPAQUE;
|
|
113
|
+
return parseOpaque(raw);
|
|
114
|
+
}
|
|
115
|
+
/** Writes (or replaces) the record inside the caller's transaction. */
|
|
116
|
+
export async function writeOpaque(view, record) {
|
|
117
|
+
await view.put(KEY, {
|
|
118
|
+
candidates: record.candidates.map((c) => ({
|
|
119
|
+
digest: c.digest,
|
|
120
|
+
parentTag: c.parentTag,
|
|
121
|
+
epoch: c.epoch,
|
|
122
|
+
...(c.sender === undefined ? {} : { sender: c.sender }),
|
|
123
|
+
errorMessage: c.errorMessage,
|
|
124
|
+
event: c.event,
|
|
125
|
+
...(c.decided === undefined ? {} : { decided: c.decided }),
|
|
126
|
+
})),
|
|
127
|
+
undecryptableIds: [...record.undecryptableIds],
|
|
128
|
+
...(record.undecryptableSaturated === true ? { undecryptableSaturated: true } : {}),
|
|
129
|
+
});
|
|
130
|
+
}
|
|
131
|
+
export async function clearOpaque(view) {
|
|
132
|
+
await view.delete(KEY);
|
|
133
|
+
}
|
|
134
|
+
/** Whether two records hold the same candidates (field for field, the event by id and signature) and the same `U`. */
|
|
135
|
+
export function sameOpaque(a, b) {
|
|
136
|
+
if (a === b)
|
|
137
|
+
return true;
|
|
138
|
+
const x = a ?? EMPTY_OPAQUE;
|
|
139
|
+
const y = b ?? EMPTY_OPAQUE;
|
|
140
|
+
if (x.candidates.length !== y.candidates.length || x.undecryptableIds.length !== y.undecryptableIds.length)
|
|
141
|
+
return false;
|
|
142
|
+
if ((x.undecryptableSaturated === true) !== (y.undecryptableSaturated === true))
|
|
143
|
+
return false;
|
|
144
|
+
for (let i = 0; i < x.candidates.length; i++) {
|
|
145
|
+
const p = x.candidates[i];
|
|
146
|
+
const q = y.candidates[i];
|
|
147
|
+
if (p.digest !== q.digest || p.parentTag !== q.parentTag || p.epoch !== q.epoch || p.sender !== q.sender || p.errorMessage !== q.errorMessage || p.decided !== q.decided)
|
|
148
|
+
return false;
|
|
149
|
+
if (p.event !== q.event && (p.event.id !== q.event.id || p.event.sig !== q.event.sig))
|
|
150
|
+
return false;
|
|
151
|
+
}
|
|
152
|
+
for (let i = 0; i < x.undecryptableIds.length; i++)
|
|
153
|
+
if (x.undecryptableIds[i] !== y.undecryptableIds[i])
|
|
154
|
+
return false;
|
|
155
|
+
return true;
|
|
156
|
+
}
|
|
157
|
+
/**
|
|
158
|
+
* What to persist after the engine's record moved from `before` (the stored one, `undefined` = none) to `now`
|
|
159
|
+
* (`engine.opaque`): `undefined` = unchanged (nothing to write — the engine returns the same object while neither
|
|
160
|
+
* the held set nor `U` changed, and a rebuilt engine's equal record is recognised by content), `null` = it became
|
|
161
|
+
* empty (delete), else the new record. A change of `U` alone is a change.
|
|
162
|
+
*/
|
|
163
|
+
export function nextOpaque(before, now) {
|
|
164
|
+
if (now === before)
|
|
165
|
+
return undefined;
|
|
166
|
+
if (isEmptyOpaque(now))
|
|
167
|
+
return isEmptyOpaque(before) ? undefined : null;
|
|
168
|
+
return sameOpaque(before, now) ? undefined : now;
|
|
169
|
+
}
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The terminal-notification outbox (epic marmot-rewound-own-commit-no-signal, S11; spec DD7 Delivery, DD11 Durability,
|
|
3
|
+
* AC-COMP-10). `own-change-reapplied` and `own-change-lost` are delivered AT LEAST ONCE: the terminal is written here in
|
|
4
|
+
* the SAME transaction that makes its fact durable (a record update or delete, a mint, a confirm, a restore), dispatched
|
|
5
|
+
* after that transaction commits, and removed in a follow-up transaction. A crash or a client dispose in between leaves
|
|
6
|
+
* the entry; the next load (or the next listener of the group) announces it again with an IDENTICAL payload.
|
|
7
|
+
* `own-change-withdrawn` stays at most once and has no entry here.
|
|
8
|
+
*
|
|
9
|
+
* Why an extension record and not a flag on the re-drive record: the paths that decide a terminal DELETE the re-drive
|
|
10
|
+
* record (no survivor, budget spent, publish refused, stranded, retired by a restore), so nothing durable would remain
|
|
11
|
+
* to carry the verdict. A separate namespace also keeps the verdict out of every reader of `pendingIntents`: it can never
|
|
12
|
+
* be driven, published, counted as an own commit pending, settled as stale, or matched by a restore or by
|
|
13
|
+
* `cancelRestoredReenqueues` (the same reason `proposalExpired`'s marker is an extension, not a flag on the proposal).
|
|
14
|
+
*
|
|
15
|
+
* Dedup key (what an application deduplicates by): `(groupId, intentId, change, type)`, plus `commitDigest` for a
|
|
16
|
+
* `reapplied` (a change reapplied by two different commits is two different facts). It is also the storage key
|
|
17
|
+
* (`groupId` is the store's own scope), so writing the same terminal twice is one entry, and growth is bounded by the
|
|
18
|
+
* number of distinct terminals not yet delivered. The only repeats an application may see are the identical redelivery
|
|
19
|
+
* after an injected crash or dispose, and a `reapplied` of the same change by the DD14 restore (a different commit, or
|
|
20
|
+
* the same one: then the same dedup key).
|
|
21
|
+
*
|
|
22
|
+
* Retention: the namespace is its own, so neither the terminal-ledger prune nor the marker prune touches it. Entries
|
|
23
|
+
* are removed only once delivered to at least one listener, or, for a row that does not decode, when the drain evicts it
|
|
24
|
+
* and reports it once as `groupStateFailed` (`store-failed`, `details.malformed`). As a last bound on a group nobody listens
|
|
25
|
+
* to, the OUTBOX_CAP most recent entries are kept (oldest evicted on write).
|
|
26
|
+
*/
|
|
27
|
+
import { type OwnChangeLostNotification, type OwnChangeReappliedNotification } from '../history/index.js';
|
|
28
|
+
import { MarmotError } from '../shared/index.js';
|
|
29
|
+
import type { KeyValueView } from '../storage/index.js';
|
|
30
|
+
/** The group extension holding one entry per undelivered terminal, keyed by {@link terminalKey}. */
|
|
31
|
+
export declare const OWN_CHANGE_OUTBOX_EXTENSION = "marmot.own-change-outbox";
|
|
32
|
+
/** The most entries kept; the oldest is evicted when a write would exceed it (a group nobody listens to). */
|
|
33
|
+
export declare const OUTBOX_CAP = 512;
|
|
34
|
+
export type TerminalNotification = OwnChangeReappliedNotification | OwnChangeLostNotification;
|
|
35
|
+
/** One stored terminal with its delivery order (`seq`, ascending). */
|
|
36
|
+
export interface OutboxEntry {
|
|
37
|
+
readonly key: string;
|
|
38
|
+
readonly seq: number;
|
|
39
|
+
readonly notification: TerminalNotification;
|
|
40
|
+
}
|
|
41
|
+
export declare function isTerminalNotification(n: {
|
|
42
|
+
readonly type: string;
|
|
43
|
+
}): n is TerminalNotification;
|
|
44
|
+
/** The dedup key of a terminal: `(intentId, change, type)` plus `commitDigest` for a reapplied (`groupId` is the store's scope). */
|
|
45
|
+
export declare function terminalKey(n: TerminalNotification): string;
|
|
46
|
+
/** Every entry, in delivery order. `view` is the group's {@link OWN_CHANGE_OUTBOX_EXTENSION} namespace. */
|
|
47
|
+
export declare function readOutbox(view: KeyValueView): Promise<OutboxEntry[]>;
|
|
48
|
+
/**
|
|
49
|
+
* Like {@link readOutbox}, row by row: the rows that decode, in delivery order, and the ones that do not (a poisoned row, a future
|
|
50
|
+
* version) with their `store-failed` error, so one bad row neither blocks the good ones nor goes unnoticed.
|
|
51
|
+
*/
|
|
52
|
+
export declare function readOutboxLenient(view: KeyValueView): Promise<{
|
|
53
|
+
readonly entries: OutboxEntry[];
|
|
54
|
+
readonly bad: {
|
|
55
|
+
readonly key: string;
|
|
56
|
+
readonly error: MarmotError;
|
|
57
|
+
}[];
|
|
58
|
+
}>;
|
|
59
|
+
/**
|
|
60
|
+
* Writes `notifications` (in order) into the outbox, in the caller's transaction. A terminal already stored under its
|
|
61
|
+
* dedup key is rewritten at the end of the order (same payload by construction for a repeat of the same fact).
|
|
62
|
+
* Evicts the oldest entries beyond {@link OUTBOX_CAP}.
|
|
63
|
+
*/
|
|
64
|
+
export declare function enqueueTerminals(view: KeyValueView, notifications: readonly TerminalNotification[]): Promise<void>;
|
|
65
|
+
/** Removes the entries just delivered; one rewritten since (a different `seq`) is a newer fact and stays. */
|
|
66
|
+
export declare function dropDelivered(view: KeyValueView, delivered: readonly OutboxEntry[]): Promise<void>;
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The terminal-notification outbox (epic marmot-rewound-own-commit-no-signal, S11; spec DD7 Delivery, DD11 Durability,
|
|
3
|
+
* AC-COMP-10). `own-change-reapplied` and `own-change-lost` are delivered AT LEAST ONCE: the terminal is written here in
|
|
4
|
+
* the SAME transaction that makes its fact durable (a record update or delete, a mint, a confirm, a restore), dispatched
|
|
5
|
+
* after that transaction commits, and removed in a follow-up transaction. A crash or a client dispose in between leaves
|
|
6
|
+
* the entry; the next load (or the next listener of the group) announces it again with an IDENTICAL payload.
|
|
7
|
+
* `own-change-withdrawn` stays at most once and has no entry here.
|
|
8
|
+
*
|
|
9
|
+
* Why an extension record and not a flag on the re-drive record: the paths that decide a terminal DELETE the re-drive
|
|
10
|
+
* record (no survivor, budget spent, publish refused, stranded, retired by a restore), so nothing durable would remain
|
|
11
|
+
* to carry the verdict. A separate namespace also keeps the verdict out of every reader of `pendingIntents`: it can never
|
|
12
|
+
* be driven, published, counted as an own commit pending, settled as stale, or matched by a restore or by
|
|
13
|
+
* `cancelRestoredReenqueues` (the same reason `proposalExpired`'s marker is an extension, not a flag on the proposal).
|
|
14
|
+
*
|
|
15
|
+
* Dedup key (what an application deduplicates by): `(groupId, intentId, change, type)`, plus `commitDigest` for a
|
|
16
|
+
* `reapplied` (a change reapplied by two different commits is two different facts). It is also the storage key
|
|
17
|
+
* (`groupId` is the store's own scope), so writing the same terminal twice is one entry, and growth is bounded by the
|
|
18
|
+
* number of distinct terminals not yet delivered. The only repeats an application may see are the identical redelivery
|
|
19
|
+
* after an injected crash or dispose, and a `reapplied` of the same change by the DD14 restore (a different commit, or
|
|
20
|
+
* the same one: then the same dedup key).
|
|
21
|
+
*
|
|
22
|
+
* Retention: the namespace is its own, so neither the terminal-ledger prune nor the marker prune touches it. Entries
|
|
23
|
+
* are removed only once delivered to at least one listener, or, for a row that does not decode, when the drain evicts it
|
|
24
|
+
* and reports it once as `groupStateFailed` (`store-failed`, `details.malformed`). As a last bound on a group nobody listens
|
|
25
|
+
* to, the OUTBOX_CAP most recent entries are kept (oldest evicted on write).
|
|
26
|
+
*/
|
|
27
|
+
import { OWN_CHANGE_LOST_REASONS } from '../history/index.js';
|
|
28
|
+
import { MarmotError } from '../shared/index.js';
|
|
29
|
+
import { decodeOwnChange } from './group-records.js';
|
|
30
|
+
/** The group extension holding one entry per undelivered terminal, keyed by {@link terminalKey}. */
|
|
31
|
+
export const OWN_CHANGE_OUTBOX_EXTENSION = 'marmot.own-change-outbox';
|
|
32
|
+
/** The most entries kept; the oldest is evicted when a write would exceed it (a group nobody listens to). */
|
|
33
|
+
export const OUTBOX_CAP = 512;
|
|
34
|
+
export function isTerminalNotification(n) {
|
|
35
|
+
return n.type === 'own-change-reapplied' || n.type === 'own-change-lost';
|
|
36
|
+
}
|
|
37
|
+
function changeKey(c) {
|
|
38
|
+
switch (c.type) {
|
|
39
|
+
case 'member-removed':
|
|
40
|
+
return `member-removed:${c.account}`;
|
|
41
|
+
case 'member-added':
|
|
42
|
+
return `member-added:${c.account}:${c.leafKey}`;
|
|
43
|
+
case 'admin':
|
|
44
|
+
return `admin:${c.account}:${String(c.admin)}`;
|
|
45
|
+
case 'component':
|
|
46
|
+
return `component:${String(c.componentId)}`;
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
/** The dedup key of a terminal: `(intentId, change, type)` plus `commitDigest` for a reapplied (`groupId` is the store's scope). */
|
|
50
|
+
export function terminalKey(n) {
|
|
51
|
+
return n.type === 'own-change-reapplied' ? `${n.type}|${n.intentId}|${changeKey(n.change)}|${n.commitDigest}` : `${n.type}|${n.intentId}|${changeKey(n.change)}`;
|
|
52
|
+
}
|
|
53
|
+
function malformed(key, detail) {
|
|
54
|
+
return new MarmotError('store-failed', `${OWN_CHANGE_OUTBOX_EXTENSION}/${key}: malformed record (${detail})`, { details: { key, malformed: true } });
|
|
55
|
+
}
|
|
56
|
+
function encode(seq, n) {
|
|
57
|
+
return {
|
|
58
|
+
v: 1,
|
|
59
|
+
seq,
|
|
60
|
+
n: n.type === 'own-change-reapplied'
|
|
61
|
+
? { type: n.type, intentId: n.intentId, commitDigest: n.commitDigest, change: { ...n.change } }
|
|
62
|
+
: { type: n.type, intentId: n.intentId, reason: n.reason, change: { ...n.change } },
|
|
63
|
+
};
|
|
64
|
+
}
|
|
65
|
+
function decode(key, raw) {
|
|
66
|
+
const fail = (detail) => malformed(key, detail);
|
|
67
|
+
const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
|
|
68
|
+
if (!isObj(raw) || raw.v !== 1 || typeof raw.seq !== 'number' || !Number.isSafeInteger(raw.seq) || !isObj(raw.n))
|
|
69
|
+
throw fail('record invalid');
|
|
70
|
+
const n = raw.n;
|
|
71
|
+
if (typeof n.intentId !== 'string')
|
|
72
|
+
throw fail('intentId missing');
|
|
73
|
+
const change = decodeOwnChange(n.change, 'change', fail);
|
|
74
|
+
if (n.type === 'own-change-reapplied') {
|
|
75
|
+
if (typeof n.commitDigest !== 'string')
|
|
76
|
+
throw fail('commitDigest missing');
|
|
77
|
+
return { seq: raw.seq, notification: { type: 'own-change-reapplied', intentId: n.intentId, commitDigest: n.commitDigest, change } };
|
|
78
|
+
}
|
|
79
|
+
if (n.type === 'own-change-lost') {
|
|
80
|
+
if (!OWN_CHANGE_LOST_REASONS.includes(n.reason))
|
|
81
|
+
throw fail('reason invalid');
|
|
82
|
+
return { seq: raw.seq, notification: { type: 'own-change-lost', intentId: n.intentId, change, reason: n.reason } };
|
|
83
|
+
}
|
|
84
|
+
throw fail('type unknown');
|
|
85
|
+
}
|
|
86
|
+
/** Every entry, in delivery order. `view` is the group's {@link OWN_CHANGE_OUTBOX_EXTENSION} namespace. */
|
|
87
|
+
export async function readOutbox(view) {
|
|
88
|
+
const entries = [];
|
|
89
|
+
for (const key of await view.keys()) {
|
|
90
|
+
const raw = await view.get(key);
|
|
91
|
+
if (raw !== undefined)
|
|
92
|
+
entries.push({ key, ...decode(key, raw) });
|
|
93
|
+
}
|
|
94
|
+
return entries.sort((a, b) => a.seq - b.seq || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* Like {@link readOutbox}, row by row: the rows that decode, in delivery order, and the ones that do not (a poisoned row, a future
|
|
98
|
+
* version) with their `store-failed` error, so one bad row neither blocks the good ones nor goes unnoticed.
|
|
99
|
+
*/
|
|
100
|
+
export async function readOutboxLenient(view) {
|
|
101
|
+
const entries = [];
|
|
102
|
+
const bad = [];
|
|
103
|
+
for (const key of await view.keys()) {
|
|
104
|
+
const raw = await view.get(key);
|
|
105
|
+
if (raw === undefined)
|
|
106
|
+
continue;
|
|
107
|
+
try {
|
|
108
|
+
entries.push({ key, ...decode(key, raw) });
|
|
109
|
+
}
|
|
110
|
+
catch (error) {
|
|
111
|
+
bad.push({ key, error: error });
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
entries.sort((a, b) => a.seq - b.seq || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
|
|
115
|
+
return { entries, bad };
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* Writes `notifications` (in order) into the outbox, in the caller's transaction. A terminal already stored under its
|
|
119
|
+
* dedup key is rewritten at the end of the order (same payload by construction for a repeat of the same fact).
|
|
120
|
+
* Evicts the oldest entries beyond {@link OUTBOX_CAP}.
|
|
121
|
+
*/
|
|
122
|
+
export async function enqueueTerminals(view, notifications) {
|
|
123
|
+
if (notifications.length === 0)
|
|
124
|
+
return;
|
|
125
|
+
// Lenient on the write path: an entry that does not decode (a poisoned row, a future version) must not fail the deciding
|
|
126
|
+
// transaction -- and with it every transition of the group. Its `seq` is read if present; the strict read stays on announce.
|
|
127
|
+
const existing = [];
|
|
128
|
+
for (const key of await view.keys()) {
|
|
129
|
+
const raw = await view.get(key);
|
|
130
|
+
const seq = typeof raw === 'object' && raw !== null && !Array.isArray(raw) && typeof raw.seq === 'number' ? raw.seq : 0;
|
|
131
|
+
existing.push({ key, seq });
|
|
132
|
+
}
|
|
133
|
+
existing.sort((a, b) => a.seq - b.seq);
|
|
134
|
+
let seq = existing.reduce((max, e) => Math.max(max, e.seq), 0);
|
|
135
|
+
const written = new Set();
|
|
136
|
+
for (const n of notifications) {
|
|
137
|
+
seq += 1;
|
|
138
|
+
const key = terminalKey(n);
|
|
139
|
+
await view.put(key, encode(seq, n));
|
|
140
|
+
written.add(key);
|
|
141
|
+
}
|
|
142
|
+
const overflow = existing.filter((e) => !written.has(e.key)).length + written.size - OUTBOX_CAP;
|
|
143
|
+
if (overflow > 0)
|
|
144
|
+
for (const e of existing.filter((x) => !written.has(x.key)).slice(0, overflow))
|
|
145
|
+
await view.delete(e.key);
|
|
146
|
+
}
|
|
147
|
+
/** Removes the entries just delivered; one rewritten since (a different `seq`) is a newer fact and stays. */
|
|
148
|
+
export async function dropDelivered(view, delivered) {
|
|
149
|
+
for (const e of delivered) {
|
|
150
|
+
const raw = await view.get(e.key);
|
|
151
|
+
if (raw === undefined)
|
|
152
|
+
continue;
|
|
153
|
+
if (decode(e.key, raw).seq === e.seq)
|
|
154
|
+
await view.delete(e.key);
|
|
155
|
+
}
|
|
156
|
+
}
|