@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,459 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@941design/marmot/storage` — the ADR-007 storage contract.
|
|
3
|
+
*
|
|
4
|
+
* Two scopes: a {@link GroupStore} per group and an {@link AccountStore} per
|
|
5
|
+
* account, each with `transaction(fn)`. A transaction is a buffered unit of
|
|
6
|
+
* work: reads go to the backend (seeing the transaction's own writes first),
|
|
7
|
+
* writes are buffered, and when `fn` settles the buffer is flushed in ONE
|
|
8
|
+
* backend transaction — or dropped if `fn` threw. `fn` may therefore await
|
|
9
|
+
* anything (a `Signer.nip44` call, a relay round-trip); an IndexedDB
|
|
10
|
+
* transaction would auto-commit across such an await, a buffer does not
|
|
11
|
+
* (AC-STORE-1).
|
|
12
|
+
*
|
|
13
|
+
* Every value is persisted inside a versioned envelope (./envelope.ts); a
|
|
14
|
+
* read of an envelope stamped with another engine state format (or ts-mls pin) rejects
|
|
15
|
+
* `envelope-mismatch` and is reported to `onIncompatible` listeners
|
|
16
|
+
* (AC-STORE-2). Stores are only obtainable through a lease (./lease.ts,
|
|
17
|
+
* AC-STORE-3). Backends plug in as a {@link StorageDriver}; the reference
|
|
18
|
+
* ones live on the `storage/indexeddb` and `storage/memory` subpaths, and
|
|
19
|
+
* this module never imports them (AC-STORE-7).
|
|
20
|
+
*
|
|
21
|
+
* Re-entrancy rule (DD13 / ADR-013). Inside `fn`, use the `tx` view — never
|
|
22
|
+
* the store itself. A same-scope store-level write (`transaction()`,
|
|
23
|
+
* `artifact(x)/extension(id).put/delete()`, `AccountStore.wipe()`) made
|
|
24
|
+
* while `fn`'s synchronous part runs — the call to `fn` itself, up to its
|
|
25
|
+
* first `await` — rejects `reentrant` without queueing: JavaScript is
|
|
26
|
+
* single-threaded, so such a call can only come from `fn` or a callee of
|
|
27
|
+
* it, and queueing it behind the running transaction would deadlock the
|
|
28
|
+
* scope. After `fn` has awaited, a same-scope store-level write cannot be
|
|
29
|
+
* told apart from an independent concurrent caller (the platform has no
|
|
30
|
+
* portable async context), and rejecting every write that overlaps a
|
|
31
|
+
* running transaction would make independent callers on one scope fail
|
|
32
|
+
* depending on timing; so it queues behind the running transaction as any
|
|
33
|
+
* concurrent write does. Awaiting such a call from inside `fn` therefore
|
|
34
|
+
* never settles — a caller bug the `tx` view exists to avoid. Store-level
|
|
35
|
+
* reads never queue and are always allowed. Other scopes (another group,
|
|
36
|
+
* the account store from a group transaction) are unaffected.
|
|
37
|
+
*
|
|
38
|
+
* Cross-scope lock order. Scopes are totally ordered group → account. From
|
|
39
|
+
* inside a transaction's `fn`, code may `await` a transaction or a
|
|
40
|
+
* store-level write on a scope LATER in that order than the scope `fn` is
|
|
41
|
+
* running on (a group transaction awaiting an account-store write) — but
|
|
42
|
+
* never on a scope EARLIER in the order (an account transaction must never
|
|
43
|
+
* await a group-store write). This is a documentation-only convention for
|
|
44
|
+
* now; this module does not detect or enforce it. The order exists to rule
|
|
45
|
+
* out a cross-scope deadlock cycle: suppose a group transaction's `fn`
|
|
46
|
+
* awaited a write on the account store (the allowed direction) while, on
|
|
47
|
+
* that account store, a transaction queued ahead of it in turn awaited a
|
|
48
|
+
* store-level write on that same group (the forbidden direction). Each
|
|
49
|
+
* side would then be waiting on a queue only the other side's completion
|
|
50
|
+
* can drain — the group transaction can't finish until its account-store
|
|
51
|
+
* await settles, and that queued account transaction can't even start
|
|
52
|
+
* until the group scope is free — so neither queue ever advances. Holding
|
|
53
|
+
* every await to the group → account direction and never the reverse means
|
|
54
|
+
* no scope ever waits, even transitively, on a scope earlier in the order,
|
|
55
|
+
* which breaks the cycle by construction.
|
|
56
|
+
*
|
|
57
|
+
* Commit gate. A driver guarantees each commit is atomic, not that commits
|
|
58
|
+
* complete in the order they were issued. So the flush — the only step that
|
|
59
|
+
* calls `driver.commit` — is serialised across the whole account (every
|
|
60
|
+
* scope of one handle) by one commit gate, and the lease and wipe
|
|
61
|
+
* generation are re-checked inside the gate immediately before the commit:
|
|
62
|
+
* a group write can therefore never land after a wipe it began before. Only
|
|
63
|
+
* the flush enters the gate, never `fn`, and a gated flush awaits nothing
|
|
64
|
+
* but `driver.commit`, so the gate is the innermost lock of the group →
|
|
65
|
+
* account order and cannot close a cycle. `close()` stops accepting work,
|
|
66
|
+
* waits for the gate to drain (a flush already queued there rejects
|
|
67
|
+
* `no-lease` unapplied), and only then releases the lease, so no write of a
|
|
68
|
+
* closed handle lands after another handle holds the lease.
|
|
69
|
+
*/
|
|
70
|
+
import { MarmotError } from '../shared/index.js';
|
|
71
|
+
import { CURRENT_CODEC_VERSIONS, openEnvelope, openEnvelopeUnchecked, sealEnvelope, } from './envelope.js';
|
|
72
|
+
import { acquireLease, setReleaseBarrier, validateLeaseTimeout } from './lease.js';
|
|
73
|
+
export { CURRENT_CODEC_VERSIONS, ENVELOPE_FORMAT, decodePayload, encodePayload, openEnvelope, sealEnvelope, } from './envelope.js';
|
|
74
|
+
export { DEFAULT_LEASE_TIMEOUT_MS, acquireLease, defaultLockManager, } from './lease.js';
|
|
75
|
+
// ---------------------------------------------------------------------------
|
|
76
|
+
// Artifacts (AC-STORE-9; ADR-007 §1 extended by the spec's Amendments)
|
|
77
|
+
// ---------------------------------------------------------------------------
|
|
78
|
+
export const GROUP_ARTIFACTS = Object.freeze([
|
|
79
|
+
'clientState',
|
|
80
|
+
'ingestCursor',
|
|
81
|
+
'terminalLedger',
|
|
82
|
+
'rewindTree',
|
|
83
|
+
'removalMarker',
|
|
84
|
+
'pendingIntents',
|
|
85
|
+
'queuedRumors',
|
|
86
|
+
'leafBackup',
|
|
87
|
+
'retainedHistory',
|
|
88
|
+
]);
|
|
89
|
+
export const ACCOUNT_ARTIFACTS = Object.freeze([
|
|
90
|
+
'keyPackages',
|
|
91
|
+
'keyPackageGroupRefs',
|
|
92
|
+
'invites',
|
|
93
|
+
'pendingInvitations',
|
|
94
|
+
'enrolmentManifests',
|
|
95
|
+
'enrolmentSessions',
|
|
96
|
+
'deviceRegistry',
|
|
97
|
+
'inboxSeenSet',
|
|
98
|
+
'syncKeyVersions',
|
|
99
|
+
'wipeMarker',
|
|
100
|
+
]);
|
|
101
|
+
/** Object-store / bucket name holding every `extension(id)` view (the `extension/*` artifact). */
|
|
102
|
+
export const EXTENSION_BUCKET = 'extension';
|
|
103
|
+
/** Every bucket a backend must provide: both artifact lists plus {@link EXTENSION_BUCKET}. */
|
|
104
|
+
export const ALL_BUCKETS = Object.freeze([...GROUP_ARTIFACTS, ...ACCOUNT_ARTIFACTS, EXTENSION_BUCKET]);
|
|
105
|
+
/** The key the wipe marker lives under in the `wipeMarker` artifact. */
|
|
106
|
+
export const WIPE_MARKER_KEY = 'current';
|
|
107
|
+
const ACCOUNT_PATTERN = /^[0-9a-f]{64}$/;
|
|
108
|
+
function validateAccount(account, where) {
|
|
109
|
+
if (typeof account !== 'string' || !ACCOUNT_PATTERN.test(account)) {
|
|
110
|
+
throw new MarmotError('invalid-options', `${where}: account must be a 64-character lowercase hex pubkey`);
|
|
111
|
+
}
|
|
112
|
+
return account;
|
|
113
|
+
}
|
|
114
|
+
function validateName(value, what) {
|
|
115
|
+
if (typeof value !== 'string' || value.length === 0)
|
|
116
|
+
throw new MarmotError('invalid-options', `${what} must be a non-empty string`);
|
|
117
|
+
return value;
|
|
118
|
+
}
|
|
119
|
+
function validateKey(key) {
|
|
120
|
+
if (typeof key !== 'string')
|
|
121
|
+
throw new MarmotError('invalid-options', 'store key must be a string');
|
|
122
|
+
return key;
|
|
123
|
+
}
|
|
124
|
+
class SerialQueue {
|
|
125
|
+
#tail = Promise.resolve();
|
|
126
|
+
run(task) {
|
|
127
|
+
const result = this.#tail.then(task, task);
|
|
128
|
+
this.#tail = result.catch(() => undefined);
|
|
129
|
+
return result;
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
function rowId(bucket, path) {
|
|
133
|
+
return JSON.stringify([bucket, ...path]);
|
|
134
|
+
}
|
|
135
|
+
function samePrefix(path, prefix) {
|
|
136
|
+
return path.length === prefix.length + 1 && prefix.every((p, i) => path[i] === p);
|
|
137
|
+
}
|
|
138
|
+
/** Builds a {@link StorageBackend} over a driver — how the reference backends, and any consumer backend, are made. */
|
|
139
|
+
export function createStorageBackend(driver, options = {}) {
|
|
140
|
+
const defaultTimeout = validateLeaseTimeout(options.leaseTimeoutMs, 'storage backend');
|
|
141
|
+
const versions = options.codecVersions ?? CURRENT_CODEC_VERSIONS;
|
|
142
|
+
const clock = options.clock ?? { now: () => Date.now() };
|
|
143
|
+
// Leases this backend instance issued, and the one handle each opened (INV-NO-SINGLETONS: per instance).
|
|
144
|
+
const issued = new WeakSet();
|
|
145
|
+
const handles = new WeakMap();
|
|
146
|
+
async function acquire(account, opts) {
|
|
147
|
+
validateAccount(account, 'acquireLease');
|
|
148
|
+
const timeoutMs = opts?.leaseTimeoutMs === undefined ? defaultTimeout : validateLeaseTimeout(opts.leaseTimeoutMs, 'acquireLease');
|
|
149
|
+
const lease = await acquireLease(driver.locks, driver.lockName(account), account, { timeoutMs });
|
|
150
|
+
issued.add(lease);
|
|
151
|
+
return lease;
|
|
152
|
+
}
|
|
153
|
+
function open(account, lease) {
|
|
154
|
+
validateAccount(account, 'open');
|
|
155
|
+
if (lease === undefined || lease === null || !issued.has(lease) || lease.account !== account || !lease.held) {
|
|
156
|
+
throw new MarmotError('no-lease', `open: no live lease of this backend for account ${account}`, { details: { account } });
|
|
157
|
+
}
|
|
158
|
+
let handle = handles.get(lease);
|
|
159
|
+
if (handle === undefined) {
|
|
160
|
+
handle = createHandle(driver, account, lease, versions, clock);
|
|
161
|
+
handles.set(lease, handle);
|
|
162
|
+
}
|
|
163
|
+
return handle;
|
|
164
|
+
}
|
|
165
|
+
return {
|
|
166
|
+
acquireLease: acquire,
|
|
167
|
+
open,
|
|
168
|
+
async openForWrite(account, opts) {
|
|
169
|
+
return open(account, await acquire(account, opts));
|
|
170
|
+
},
|
|
171
|
+
};
|
|
172
|
+
}
|
|
173
|
+
function createHandle(driver, account, lease, versions, clock) {
|
|
174
|
+
let closed = false;
|
|
175
|
+
// Bumped once a wipe has committed; a transaction that began before the
|
|
176
|
+
// wipe must not flush afterwards and resurrect wiped rows.
|
|
177
|
+
let wipeGeneration = 0;
|
|
178
|
+
// The account-wide commit gate (module comment): every flush of every scope runs here, one at a time.
|
|
179
|
+
const commitGate = new SerialQueue();
|
|
180
|
+
// Every release of this lease (close(), stores.lease.release(), or the caller's own reference) first
|
|
181
|
+
// stops new writes and lets a flush already committing finish; flushes queued behind it reject no-lease.
|
|
182
|
+
setReleaseBarrier(lease, async () => {
|
|
183
|
+
closed = true;
|
|
184
|
+
await commitGate.run(async () => { });
|
|
185
|
+
});
|
|
186
|
+
function assertLease() {
|
|
187
|
+
if (closed || !lease.held) {
|
|
188
|
+
throw new MarmotError('no-lease', `store for account ${account} is not held under a live lease`, { details: { account } });
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
async function readRow(bucket, path) {
|
|
192
|
+
try {
|
|
193
|
+
return await driver.read(account, bucket, path);
|
|
194
|
+
}
|
|
195
|
+
catch (err) {
|
|
196
|
+
throw new MarmotError('store-failed', `read of ${bucket} failed`, { cause: err });
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
async function listKeys(bucket, prefix) {
|
|
200
|
+
try {
|
|
201
|
+
return await driver.keys(account, bucket, prefix);
|
|
202
|
+
}
|
|
203
|
+
catch (err) {
|
|
204
|
+
throw new MarmotError('store-failed', `key listing of ${bucket} failed`, { cause: err });
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
function decode(internals, key, raw) {
|
|
208
|
+
try {
|
|
209
|
+
return openEnvelope(key, raw, versions);
|
|
210
|
+
}
|
|
211
|
+
catch (err) {
|
|
212
|
+
const error = err;
|
|
213
|
+
for (const listener of [...internals.listeners]) {
|
|
214
|
+
try {
|
|
215
|
+
listener({ key, error });
|
|
216
|
+
}
|
|
217
|
+
catch {
|
|
218
|
+
// A throwing listener must not change the read's outcome.
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
throw error;
|
|
222
|
+
}
|
|
223
|
+
}
|
|
224
|
+
/** A transaction's buffer and the views over it. */
|
|
225
|
+
class Tx {
|
|
226
|
+
internals;
|
|
227
|
+
open = true;
|
|
228
|
+
cleared = false;
|
|
229
|
+
/** `GroupStore.clear()`: every row of this scope goes, before the buffered writes. */
|
|
230
|
+
scopeCleared = false;
|
|
231
|
+
buffer = new Map();
|
|
232
|
+
constructor(internals) {
|
|
233
|
+
this.internals = internals;
|
|
234
|
+
}
|
|
235
|
+
assertOpen() {
|
|
236
|
+
if (!this.open)
|
|
237
|
+
throw new MarmotError('transaction-closed', 'store transaction already settled; writes after it are not part of it');
|
|
238
|
+
}
|
|
239
|
+
view(bucket, prefix, labelPrefix) {
|
|
240
|
+
const tx = this;
|
|
241
|
+
return {
|
|
242
|
+
async get(rawKey) {
|
|
243
|
+
tx.assertOpen();
|
|
244
|
+
const key = validateKey(rawKey);
|
|
245
|
+
const path = [...prefix, key];
|
|
246
|
+
const buffered = tx.buffer.get(rowId(bucket, path));
|
|
247
|
+
if (buffered !== undefined)
|
|
248
|
+
return buffered.envelope === null ? undefined : openEnvelope(`${labelPrefix}/${key}`, buffered.envelope, versions);
|
|
249
|
+
if (tx.cleared || tx.scopeCleared)
|
|
250
|
+
return undefined;
|
|
251
|
+
const raw = await readRow(bucket, path);
|
|
252
|
+
return raw === undefined ? undefined : decode(tx.internals, `${labelPrefix}/${key}`, raw);
|
|
253
|
+
},
|
|
254
|
+
async put(rawKey, value) {
|
|
255
|
+
tx.assertOpen();
|
|
256
|
+
const key = validateKey(rawKey);
|
|
257
|
+
const path = [...prefix, key];
|
|
258
|
+
tx.buffer.set(rowId(bucket, path), { bucket, path, envelope: sealEnvelope(value, versions) });
|
|
259
|
+
},
|
|
260
|
+
async delete(rawKey) {
|
|
261
|
+
tx.assertOpen();
|
|
262
|
+
const key = validateKey(rawKey);
|
|
263
|
+
const path = [...prefix, key];
|
|
264
|
+
tx.buffer.set(rowId(bucket, path), { bucket, path, envelope: null });
|
|
265
|
+
},
|
|
266
|
+
async keys() {
|
|
267
|
+
tx.assertOpen();
|
|
268
|
+
const present = new Set(tx.cleared || tx.scopeCleared ? [] : await listKeys(bucket, prefix));
|
|
269
|
+
for (const write of tx.buffer.values()) {
|
|
270
|
+
if (write.bucket !== bucket || !samePrefix(write.path, prefix))
|
|
271
|
+
continue;
|
|
272
|
+
const key = write.path[write.path.length - 1];
|
|
273
|
+
if (write.envelope === null)
|
|
274
|
+
present.delete(key);
|
|
275
|
+
else
|
|
276
|
+
present.add(key);
|
|
277
|
+
}
|
|
278
|
+
return [...present].sort();
|
|
279
|
+
},
|
|
280
|
+
};
|
|
281
|
+
}
|
|
282
|
+
scopeApi() {
|
|
283
|
+
const { scope, label, artifacts } = this.internals;
|
|
284
|
+
return {
|
|
285
|
+
artifact: (name) => {
|
|
286
|
+
if (!artifacts.includes(name))
|
|
287
|
+
throw new MarmotError('invalid-options', `unknown artifact ${JSON.stringify(name)} for ${label}`);
|
|
288
|
+
return this.view(name, [scope], `${label}/${name}`);
|
|
289
|
+
},
|
|
290
|
+
extension: (rawId) => {
|
|
291
|
+
const id = validateName(rawId, 'extension id');
|
|
292
|
+
return this.view(EXTENSION_BUCKET, [scope, id], `${label}/extension/${id}`);
|
|
293
|
+
},
|
|
294
|
+
};
|
|
295
|
+
}
|
|
296
|
+
writes() {
|
|
297
|
+
const out = this.cleared ? [{ type: 'clear' }] : this.scopeCleared ? [{ type: 'clearScope', scope: this.internals.scope }] : [];
|
|
298
|
+
for (const w of this.buffer.values()) {
|
|
299
|
+
out.push(w.envelope === null ? { type: 'delete', bucket: w.bucket, path: w.path } : { type: 'put', bucket: w.bucket, path: w.path, envelope: w.envelope });
|
|
300
|
+
}
|
|
301
|
+
return out;
|
|
302
|
+
}
|
|
303
|
+
}
|
|
304
|
+
function runTransaction(internals, fn, setup) {
|
|
305
|
+
if (typeof fn !== 'function')
|
|
306
|
+
return Promise.reject(new MarmotError('invalid-options', 'transaction(fn): fn must be a function'));
|
|
307
|
+
if (internals.inSyncFn) {
|
|
308
|
+
// Queueing would wait on the transaction whose `fn` is making this call.
|
|
309
|
+
return Promise.reject(new MarmotError('reentrant', `${internals.label}: store-level write from inside a running transaction on the same store; use the transaction's tx view`, {
|
|
310
|
+
details: { scope: internals.label },
|
|
311
|
+
}));
|
|
312
|
+
}
|
|
313
|
+
return internals.queue.run(async () => {
|
|
314
|
+
assertLease();
|
|
315
|
+
const generation = wipeGeneration;
|
|
316
|
+
const tx = new Tx(internals);
|
|
317
|
+
setup?.(tx);
|
|
318
|
+
let result;
|
|
319
|
+
try {
|
|
320
|
+
let pending;
|
|
321
|
+
internals.inSyncFn = true;
|
|
322
|
+
try {
|
|
323
|
+
pending = fn(tx.scopeApi());
|
|
324
|
+
}
|
|
325
|
+
finally {
|
|
326
|
+
internals.inSyncFn = false;
|
|
327
|
+
}
|
|
328
|
+
result = await pending;
|
|
329
|
+
}
|
|
330
|
+
finally {
|
|
331
|
+
tx.open = false;
|
|
332
|
+
}
|
|
333
|
+
const writes = tx.writes();
|
|
334
|
+
if (writes.length === 0) {
|
|
335
|
+
assertCommittable(generation);
|
|
336
|
+
return result;
|
|
337
|
+
}
|
|
338
|
+
await commitGate.run(async () => {
|
|
339
|
+
// Re-checked inside the gate, immediately before the commit (ADR-013; module comment: commit gate).
|
|
340
|
+
assertCommittable(generation);
|
|
341
|
+
try {
|
|
342
|
+
await driver.commit(account, writes);
|
|
343
|
+
}
|
|
344
|
+
catch (err) {
|
|
345
|
+
throw new MarmotError('store-failed', `commit for account ${account} failed; no write was applied`, { cause: err });
|
|
346
|
+
}
|
|
347
|
+
// Only a wipe that actually committed invalidates transactions begun before it.
|
|
348
|
+
if (tx.cleared)
|
|
349
|
+
wipeGeneration++;
|
|
350
|
+
});
|
|
351
|
+
return result;
|
|
352
|
+
});
|
|
353
|
+
}
|
|
354
|
+
/** Throws unless a transaction that began at wipe `generation` may still commit: lease live, no wipe since. */
|
|
355
|
+
function assertCommittable(generation) {
|
|
356
|
+
assertLease();
|
|
357
|
+
if (generation !== wipeGeneration) {
|
|
358
|
+
throw new MarmotError('transaction-closed', `account ${account} was wiped while the transaction ran; its writes were dropped`);
|
|
359
|
+
}
|
|
360
|
+
}
|
|
361
|
+
function makeScope(scope, label, artifacts) {
|
|
362
|
+
const internals = { scope, label, artifacts, queue: new SerialQueue(), listeners: new Set(), inSyncFn: false };
|
|
363
|
+
/** A store-level view: reads go straight to the backend, each write is its own transaction. */
|
|
364
|
+
function autoView(select) {
|
|
365
|
+
const reader = () => {
|
|
366
|
+
assertLease();
|
|
367
|
+
const tx = new Tx(internals);
|
|
368
|
+
return select(tx.scopeApi());
|
|
369
|
+
};
|
|
370
|
+
return {
|
|
371
|
+
get: (key) => Promise.resolve().then(() => reader().get(key)),
|
|
372
|
+
keys: () => Promise.resolve().then(() => reader().keys()),
|
|
373
|
+
put: (key, value) => runTransaction(internals, (tx) => select(tx).put(key, value)),
|
|
374
|
+
delete: (key) => runTransaction(internals, (tx) => select(tx).delete(key)),
|
|
375
|
+
};
|
|
376
|
+
}
|
|
377
|
+
const base = {
|
|
378
|
+
artifact(name) {
|
|
379
|
+
if (!artifacts.includes(name))
|
|
380
|
+
throw new MarmotError('invalid-options', `unknown artifact ${JSON.stringify(name)} for ${label}`);
|
|
381
|
+
return autoView((tx) => tx.artifact(name));
|
|
382
|
+
},
|
|
383
|
+
extension(rawId) {
|
|
384
|
+
const id = validateName(rawId, 'extension id');
|
|
385
|
+
return autoView((tx) => tx.extension(id));
|
|
386
|
+
},
|
|
387
|
+
onIncompatible(listener) {
|
|
388
|
+
if (typeof listener !== 'function')
|
|
389
|
+
throw new MarmotError('invalid-options', 'onIncompatible: listener must be a function');
|
|
390
|
+
internals.listeners.add(listener);
|
|
391
|
+
return () => {
|
|
392
|
+
internals.listeners.delete(listener);
|
|
393
|
+
};
|
|
394
|
+
},
|
|
395
|
+
};
|
|
396
|
+
return { internals, base };
|
|
397
|
+
}
|
|
398
|
+
const accountScope = makeScope('account', `account:${account}`, ACCOUNT_ARTIFACTS);
|
|
399
|
+
const accountStore = {
|
|
400
|
+
account,
|
|
401
|
+
artifact: (name) => accountScope.base.artifact(name),
|
|
402
|
+
extension: (id) => accountScope.base.extension(id),
|
|
403
|
+
onIncompatible: (listener) => accountScope.base.onIncompatible(listener),
|
|
404
|
+
transaction: (fn) => runTransaction(accountScope.internals, fn),
|
|
405
|
+
async wipe(opts) {
|
|
406
|
+
const reason = opts?.reason;
|
|
407
|
+
if (reason !== 'incompatible' && reason !== 'application') {
|
|
408
|
+
throw new MarmotError('invalid-options', "wipe: reason must be 'incompatible' or 'application'");
|
|
409
|
+
}
|
|
410
|
+
const at = clock.now();
|
|
411
|
+
await runTransaction(accountScope.internals, async (tx) => {
|
|
412
|
+
await tx.artifact('wipeMarker').put(WIPE_MARKER_KEY, { at, reason });
|
|
413
|
+
}, (tx) => {
|
|
414
|
+
tx.cleared = true;
|
|
415
|
+
});
|
|
416
|
+
return Object.freeze({ engine: versions.engine, tsMls: versions.tsMls, at, reason });
|
|
417
|
+
},
|
|
418
|
+
async wipeMarker() {
|
|
419
|
+
const key = `${accountScope.internals.label}/wipeMarker/${WIPE_MARKER_KEY}`;
|
|
420
|
+
const raw = await readRow('wipeMarker', ['account', WIPE_MARKER_KEY]);
|
|
421
|
+
if (raw === undefined)
|
|
422
|
+
return undefined;
|
|
423
|
+
const { stamp, value } = openEnvelopeUnchecked(key, raw);
|
|
424
|
+
const v = value;
|
|
425
|
+
if (typeof v !== 'object' || v === null || typeof v.at !== 'number' || (v.reason !== 'incompatible' && v.reason !== 'application')) {
|
|
426
|
+
throw new MarmotError('envelope-mismatch', `stored artifact ${key}: malformed wipe marker`, { details: { key, reason: 'malformed' } });
|
|
427
|
+
}
|
|
428
|
+
return Object.freeze({ engine: stamp.engine, tsMls: stamp.tsMls, at: v.at, reason: v.reason });
|
|
429
|
+
},
|
|
430
|
+
};
|
|
431
|
+
const groups = new Map();
|
|
432
|
+
function groupFactory(rawGroupId) {
|
|
433
|
+
const groupId = validateName(rawGroupId, 'groupId');
|
|
434
|
+
let store = groups.get(groupId);
|
|
435
|
+
if (store === undefined) {
|
|
436
|
+
const scope = makeScope(`group:${groupId}`, `group:${groupId}`, GROUP_ARTIFACTS);
|
|
437
|
+
store = {
|
|
438
|
+
groupId,
|
|
439
|
+
artifact: (name) => scope.base.artifact(name),
|
|
440
|
+
extension: (id) => scope.base.extension(id),
|
|
441
|
+
onIncompatible: (listener) => scope.base.onIncompatible(listener),
|
|
442
|
+
transaction: (fn) => runTransaction(scope.internals, fn),
|
|
443
|
+
clear: () => runTransaction(scope.internals, () => undefined, (tx) => {
|
|
444
|
+
tx.scopeCleared = true;
|
|
445
|
+
}),
|
|
446
|
+
};
|
|
447
|
+
groups.set(groupId, store);
|
|
448
|
+
}
|
|
449
|
+
return store;
|
|
450
|
+
}
|
|
451
|
+
return {
|
|
452
|
+
account: accountStore,
|
|
453
|
+
groupFactory,
|
|
454
|
+
lease,
|
|
455
|
+
close() {
|
|
456
|
+
return lease.release();
|
|
457
|
+
},
|
|
458
|
+
};
|
|
459
|
+
}
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The structural subset of IndexedDB this backend uses. `@941design/marmot`
|
|
3
|
+
* compiles without the DOM lib, so these stand in for the DOM's
|
|
4
|
+
* `IDBFactory` & co.; the real browser objects and `fake-indexeddb`'s
|
|
5
|
+
* satisfy them.
|
|
6
|
+
*
|
|
7
|
+
* Two rules keep native `window.indexedDB` / `IDBKeyRange` (and
|
|
8
|
+
* `fake-indexeddb`'s exports) structurally assignable WITHOUT casts, even
|
|
9
|
+
* though this package compiles without `lib: dom`:
|
|
10
|
+
* 1. Event-handler properties (`onsuccess` & co.) are typed
|
|
11
|
+
* `(this: any, ev: any) => any`, not `(this: unknown, ev: unknown) =>
|
|
12
|
+
* unknown` — a property-typed function is checked contravariantly on its
|
|
13
|
+
* `this`/parameter types under `strictFunctionTypes`, and native DOM
|
|
14
|
+
* handlers declare a concrete `this`/event type that `unknown` there
|
|
15
|
+
* would reject; `any` opts out of that check for a callback signature
|
|
16
|
+
* this backend only ever assigns, never calls with a synthetic `this`.
|
|
17
|
+
* 2. `IDBValidKeyLike` mirrors the DOM lib's own
|
|
18
|
+
* `IDBValidKey = number | string | Date | BufferSource | IDBValidKey[]`
|
|
19
|
+
* (`ArrayBufferView` is an ES lib type, not DOM-only, so it's in scope
|
|
20
|
+
* here) rather than narrowing to the `string[]` paths this backend
|
|
21
|
+
* actually passes — the interface describes what native IndexedDB
|
|
22
|
+
* accepts, not what this backend happens to send.
|
|
23
|
+
*/
|
|
24
|
+
export type IDBValidKeyLike = number | string | Date | ArrayBuffer | ArrayBufferView | IDBValidKeyLike[];
|
|
25
|
+
export interface IDBRequestLike<T> {
|
|
26
|
+
readonly result: T;
|
|
27
|
+
readonly error: unknown;
|
|
28
|
+
onsuccess: ((this: any, ev: any) => any) | null;
|
|
29
|
+
onerror: ((this: any, ev: any) => any) | null;
|
|
30
|
+
}
|
|
31
|
+
export interface IDBOpenDBRequestLike extends IDBRequestLike<IDBDatabaseLike> {
|
|
32
|
+
onupgradeneeded: ((this: any, ev: any) => any) | null;
|
|
33
|
+
onblocked: ((this: any, ev: any) => any) | null;
|
|
34
|
+
}
|
|
35
|
+
export interface IDBObjectStoreLike {
|
|
36
|
+
get(key: IDBValidKeyLike): IDBRequestLike<unknown>;
|
|
37
|
+
getAllKeys(query?: unknown): IDBRequestLike<IDBValidKeyLike[]>;
|
|
38
|
+
put(value: unknown, key: IDBValidKeyLike): IDBRequestLike<unknown>;
|
|
39
|
+
/** A key, or a key range (`IDBKeyRangeStaticLike.bound`). */
|
|
40
|
+
delete(query: IDBValidKeyLike | unknown): IDBRequestLike<unknown>;
|
|
41
|
+
clear(): IDBRequestLike<unknown>;
|
|
42
|
+
}
|
|
43
|
+
export interface IDBTransactionLike {
|
|
44
|
+
readonly error: unknown;
|
|
45
|
+
objectStore(name: string): IDBObjectStoreLike;
|
|
46
|
+
abort(): void;
|
|
47
|
+
oncomplete: ((this: any, ev: any) => any) | null;
|
|
48
|
+
onerror: ((this: any, ev: any) => any) | null;
|
|
49
|
+
onabort: ((this: any, ev: any) => any) | null;
|
|
50
|
+
}
|
|
51
|
+
export interface IDBDatabaseLike {
|
|
52
|
+
readonly objectStoreNames: {
|
|
53
|
+
contains(name: string): boolean;
|
|
54
|
+
readonly length: number;
|
|
55
|
+
item(index: number): string | null;
|
|
56
|
+
};
|
|
57
|
+
createObjectStore(name: string): unknown;
|
|
58
|
+
transaction(storeNames: string | string[], mode: 'readonly' | 'readwrite'): IDBTransactionLike;
|
|
59
|
+
close(): void;
|
|
60
|
+
onversionchange: ((this: any, ev: any) => any) | null;
|
|
61
|
+
onclose: ((this: any, ev: any) => any) | null;
|
|
62
|
+
}
|
|
63
|
+
export interface IDBFactoryLike {
|
|
64
|
+
open(name: string, version?: number): IDBOpenDBRequestLike;
|
|
65
|
+
}
|
|
66
|
+
export interface IDBKeyRangeStaticLike {
|
|
67
|
+
bound(lower: unknown, upper: unknown, lowerOpen?: boolean, upperOpen?: boolean): unknown;
|
|
68
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import { type BackendOptions, type StorageBackend } from '../index.js';
|
|
2
|
+
import { type LockManagerLike } from '../lease.js';
|
|
3
|
+
import type { IDBFactoryLike, IDBKeyRangeStaticLike } from './idb-types.js';
|
|
4
|
+
export type { IDBDatabaseLike, IDBFactoryLike, IDBKeyRangeStaticLike, IDBObjectStoreLike, IDBOpenDBRequestLike, IDBRequestLike, IDBTransactionLike, IDBValidKeyLike, } from './idb-types.js';
|
|
5
|
+
export declare const DEFAULT_DB_PREFIX = "marmot:";
|
|
6
|
+
export declare const DB_VERSION = 1;
|
|
7
|
+
export interface IndexedDbStorageOptions extends BackendOptions {
|
|
8
|
+
/** Defaults to `globalThis.indexedDB`. */
|
|
9
|
+
readonly indexedDB?: IDBFactoryLike;
|
|
10
|
+
/** Defaults to `globalThis.IDBKeyRange`. */
|
|
11
|
+
readonly IDBKeyRange?: IDBKeyRangeStaticLike;
|
|
12
|
+
/** Defaults to `navigator.locks`. Required where the host has no Web Locks. */
|
|
13
|
+
readonly locks?: LockManagerLike;
|
|
14
|
+
/** Database name prefix; the account pubkey is appended. Default `'marmot:'`. */
|
|
15
|
+
readonly dbPrefix?: string;
|
|
16
|
+
}
|
|
17
|
+
export declare function createIndexedDbStorage(options?: IndexedDbStorageOptions): StorageBackend;
|