@optimystic/db-p2p-storage-web 1.15.0 → 1.16.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.
@@ -0,0 +1,38 @@
1
+ /**
2
+ * Whether this runtime's IndexedDB honours `IDBTransactionOptions.durability`. A browser that does
3
+ * exposes the durability a transaction was given as `IDBTransaction.durability`, an accessor on
4
+ * the prototype (Chrome 83+, and Firefox and Safari in their current releases); one that does not
5
+ * ignores the option and commits every transaction at its default, which current browsers treat
6
+ * as relaxed. Asked once per store, at construction, since a store's `durability` never changes
7
+ * over its life.
8
+ *
9
+ * `fake-indexeddb` keeps the durability a transaction asked for as an own property of the
10
+ * transaction and puts nothing on the prototype, so under it this answers false and the tests
11
+ * override it with `strictDurability: true`.
12
+ */
13
+ export function supportsStrictDurability(): boolean {
14
+ return typeof IDBTransaction !== 'undefined' && 'durability' in IDBTransaction.prototype;
15
+ }
16
+
17
+ /** The option every store of this package takes: whether the transactions that must reach the disk ask for strict durability. */
18
+ export interface IndexedDBDurabilityOptions {
19
+ /**
20
+ * Whether a transaction that must survive a power cut asks for `durability: 'strict'`. Defaults to
21
+ * {@link supportsStrictDurability}. Tests set it, since `fake-indexeddb` honours the option
22
+ * without advertising it; a host has no reason to.
23
+ */
24
+ readonly strictDurability?: boolean;
25
+ }
26
+
27
+ export function resolveStrictDurability(options: IndexedDBDurabilityOptions): boolean {
28
+ return options.strictDurability ?? supportsStrictDurability();
29
+ }
30
+
31
+ /**
32
+ * The durability a transaction asks for: `'strict'` for one that must be on the disk before it
33
+ * completes, where the browser supports it, and `'relaxed'` otherwise — what every current
34
+ * browser's default already is, and what a browser without the option does whatever is asked.
35
+ */
36
+ export function transactionDurability(strict: boolean): IDBTransactionDurability {
37
+ return strict ? 'strict' : 'relaxed';
38
+ }
package/src/identity.ts CHANGED
@@ -1,12 +1,15 @@
1
1
  import { generateKeyPair, privateKeyFromProtobuf, privateKeyToProtobuf } from '@libp2p/crypto/keys';
2
2
  import type { PrivateKey } from '@libp2p/interface';
3
3
  import type { OptimysticWebDBHandle } from './db.js';
4
+ import { resolveStrictDurability, transactionDurability, type IndexedDBDurabilityOptions } from './durability.js';
4
5
 
5
6
  export const DEFAULT_PEER_KEY_NAME = 'peer-private-key';
6
7
 
7
8
  /**
8
9
  * Loads the persisted browser peer's libp2p private key, or generates a fresh
9
- * Ed25519 key on first call and persists it.
10
+ * Ed25519 key on first call and persists it in one transaction that is strict
11
+ * where the browser supports it, so a power cut right after first start cannot
12
+ * give the node a different peer id next time. An existing key is read as it is.
10
13
  *
11
14
  * Stores the key as raw protobuf bytes (a `Uint8Array`) under `keyName` in the
12
15
  * `kv` object store. IndexedDB stores typed arrays natively — no base64 round-trip.
@@ -17,6 +20,7 @@ export const DEFAULT_PEER_KEY_NAME = 'peer-private-key';
17
20
  export async function loadOrCreateBrowserPeerKey(
18
21
  db: OptimysticWebDBHandle,
19
22
  keyName: string = DEFAULT_PEER_KEY_NAME,
23
+ options: IndexedDBDurabilityOptions = {},
20
24
  ): Promise<PrivateKey> {
21
25
  const stored = await db.get('kv', keyName);
22
26
  if (stored instanceof Uint8Array) {
@@ -24,6 +28,7 @@ export async function loadOrCreateBrowserPeerKey(
24
28
  }
25
29
  const key = await generateKeyPair('Ed25519');
26
30
  const bytes = privateKeyToProtobuf(key);
27
- await db.put('kv', bytes, keyName);
31
+ const tx = db.transaction('kv', 'readwrite', { durability: transactionDurability(resolveStrictDurability(options)) });
32
+ await Promise.all([tx.store.put(bytes, keyName), tx.done]);
28
33
  return key;
29
34
  }
package/src/index.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  export * from './db.js';
2
+ export * from './durability.js';
2
3
  export * from './indexeddb-storage.js';
3
4
  export * from './indexeddb-kv-store.js';
4
5
  export * from './identity.js';
@@ -1,34 +1,104 @@
1
- import type { IKVStore } from '@optimystic/db-p2p';
1
+ import { WriteGroup, type CommittedBatch, type FlushOptions, type IKVStore, type WriteGroupEntry, type WriteGroupOptions } from '@optimystic/db-p2p';
2
2
  import type { OptimysticWebDBHandle } from './db.js';
3
+ import { resolveStrictDurability, transactionDurability, type IndexedDBDurabilityOptions } from './durability.js';
4
+
5
+ /** The write group's options (`idleFlushMs`, `maxUnsyncedBytes`, the test-only `setTimer`), and whether to ask for strict transactions. */
6
+ export type IndexedDBKVStoreOptions = WriteGroupOptions & IndexedDBDurabilityOptions;
7
+
8
+ const encoder = new TextEncoder();
9
+ // Built on first use rather than at module load, like every other `TextDecoder` in library source
10
+ // (see NO_MODULE_SCOPE_TEXT_DECODER in eslint.config.js).
11
+ let decoderInstance: TextDecoder | undefined;
12
+ const decoder = (): TextDecoder => decoderInstance ??= new TextDecoder();
3
13
 
4
14
  /**
5
15
  * IndexedDB-backed `IKVStore` adapter for browser peers.
6
16
  *
7
- * Stored keys are namespaced with `prefix` so the `kv` object store can be
8
- * shared with the identity helper without collisions. `list(prefix)` uses a
9
- * range-bounded key cursor — never `getAllKeys()` — so a large `kv` store
10
- * does not pay an O(n) JS-side filter cost.
17
+ * Stored keys are namespaced with `prefix` so the `kv` object store can be shared with the identity
18
+ * helper without collisions. `list(prefix)` uses a range-bounded key cursor — never `getAllKeys()` —
19
+ * so a large `kv` store does not pay an O(n) JS-side filter cost.
20
+ *
21
+ * Writes go through a {@link WriteGroup} over the plain keys, as `FileKVStore` does: a `set` or
22
+ * `delete` resolves into memory, served from there to `get` and `list`, and `flush()` commits
23
+ * everything written since the last flush as ONE `readwrite` transaction on `kv`, strict where the
24
+ * browser supports it (`supportsStrictDurability`), so the writes are on the disk before the flush
25
+ * resolves. Every flush the node makes of this store is strict, and so is the group's own idle
26
+ * flush, so there is no relaxed path to journal: a flush given a window is treated as strict, as a
27
+ * store that cannot defer a sync treats every window. A failed commit latches the store, after which
28
+ * every write and flush throws `StoreFailedError` (rule 5 of the flush contract on
29
+ * `RawStoreDriver.flush`); reads keep serving the overlay.
11
30
  */
12
31
  export class IndexedDBKVStore implements IKVStore {
32
+ private readonly group: WriteGroup<string>;
33
+ private readonly strict: boolean;
34
+
13
35
  constructor(
14
36
  private readonly db: OptimysticWebDBHandle,
15
37
  private readonly prefix: string = 'optimystic:txn:',
16
- ) {}
38
+ options: IndexedDBKVStoreOptions = {},
39
+ ) {
40
+ this.strict = resolveStrictDurability(options);
41
+ this.group = new WriteGroup<string>(key => key, {
42
+ commit: entries => this.commit(entries),
43
+ // Every commit is as durable as this store can make it when it resolves, so nothing is ever owed a sync.
44
+ sync: () => Promise.resolve(),
45
+ }, options);
46
+ }
17
47
 
18
48
  async get(key: string): Promise<string | undefined> {
49
+ const held = this.group.lookup(key);
50
+ if (held !== undefined) return held === null ? undefined : decoder().decode(held);
19
51
  const value = await this.db.get('kv', this.prefix + key);
20
52
  return typeof value === 'string' ? value : undefined;
21
53
  }
22
54
 
23
55
  async set(key: string, value: string): Promise<void> {
24
- await this.db.put('kv', value, this.prefix + key);
56
+ this.group.put(key, encoder.encode(value));
25
57
  }
26
58
 
27
59
  async delete(key: string): Promise<void> {
28
- await this.db.delete('kv', this.prefix + key);
60
+ this.group.delete(key);
29
61
  }
30
62
 
63
+ /** Every key under `prefix`: the store's, plus those written and not yet flushed, less those deleted and not yet flushed. */
31
64
  async list(prefix: string): Promise<string[]> {
65
+ // Taken before awaiting the store: a commit resolving meanwhile drops entries from the overlay
66
+ // that the listing below may have been taken without.
67
+ const held = [...this.group.entries()].filter(([key]) => key.startsWith(prefix));
68
+ const keys = new Set(await this.listStored(prefix));
69
+ for (const [key, value] of held) {
70
+ if (value === null) keys.delete(key);
71
+ else keys.add(key);
72
+ }
73
+ return [...keys];
74
+ }
75
+
76
+ /** Make every write resolved before this call durable: one transaction, strict where supported, whatever `options.withinMs` says. The contract is `RawStoreDriver.flush`'s. */
77
+ flush(options?: FlushOptions): Promise<void> {
78
+ return this.group.flush(options);
79
+ }
80
+
81
+ /** Resolves once every write covered by a flush that resolved before this call is durable; `RawStoreDriver.whenDurable`'s contract. */
82
+ whenDurable(): Promise<void> {
83
+ return this.group.whenDurable();
84
+ }
85
+
86
+ /** Flush what is still held and disarm the idle timer. The host closes the shared handle after this resolves. */
87
+ close(): Promise<void> {
88
+ return this.group.close();
89
+ }
90
+
91
+ private async commit(entries: readonly WriteGroupEntry<string>[]): Promise<CommittedBatch> {
92
+ const tx = this.db.transaction('kv', 'readwrite', { durability: transactionDurability(this.strict) });
93
+ // Queued synchronously and awaited together with the transaction: IndexedDB commits a transaction that is left idle.
94
+ const requests = entries.map(({ key, value }) => value === undefined
95
+ ? tx.store.delete(this.prefix + key)
96
+ : tx.store.put(decoder().decode(value), this.prefix + key));
97
+ await Promise.all([...requests, tx.done]);
98
+ return { durable: Promise.resolve() };
99
+ }
100
+
101
+ private async listStored(prefix: string): Promise<string[]> {
32
102
  const fullPrefix = this.prefix + prefix;
33
103
  // '￿' is the highest BMP code unit; appending it produces a string
34
104
  // that is >= every string starting with `fullPrefix`. IndexedDB compares
@@ -1,29 +1,136 @@
1
1
  import type { ActionId, BlockId } from '@optimystic/db-core';
2
- import { KvRawStorage, identityForHandle, type RawStoreDriver, type StoreIdentity } from '@optimystic/db-p2p';
3
- import type { OptimysticWebDBHandle } from './db.js';
2
+ import {
3
+ JournalBatchBackend,
4
+ KvRawStorage,
5
+ WriteGroupDriver,
6
+ identityForHandle,
7
+ type BatchEntry,
8
+ type JournalBatchBackendOptions,
9
+ type JournalContents,
10
+ type JournalRecord,
11
+ type JournalStore,
12
+ type StoreDurability,
13
+ type StoreIdentity,
14
+ type StoreKey,
15
+ type WriteGroupOptions,
16
+ } from '@optimystic/db-p2p';
17
+ import { JOURNAL_MARK_KEY, type OptimysticWebDBHandle } from './db.js';
18
+ import { resolveStrictDurability, transactionDurability, type IndexedDBDurabilityOptions } from './durability.js';
4
19
  import { createLogger } from './logger.js';
5
20
 
6
21
  const log = createLogger('storage:indexeddb');
7
22
 
23
+ /** The object stores an apply writes: the six block-storage stores and the journal itself. */
24
+ const APPLY_STORES = ['metadata', 'revisions', 'pending', 'transactions', 'proofs', 'materialized', 'journal'] as const;
25
+
26
+ /** The IndexedDB key a `StoreKey` addresses in its object store: the compound array keys the schema declares. */
27
+ type IdbKey = BlockId | [BlockId, number] | [BlockId, ActionId];
28
+
29
+ function idbKeyOf(key: StoreKey): IdbKey {
30
+ switch (key.store) {
31
+ case 'metadata':
32
+ return key.blockId;
33
+ case 'revisions':
34
+ case 'proofs':
35
+ return [key.blockId, key.rev];
36
+ case 'pending':
37
+ case 'transactions':
38
+ case 'materialized':
39
+ return [key.blockId, key.actionId];
40
+ }
41
+ }
42
+
8
43
  /**
9
- * IndexedDB {@link RawStoreDriver}: the six logical block-storage stores mapped
10
- * to the six IndexedDB object stores (`metadata`, `revisions`, `pending`,
11
- * `transactions`, `proofs`, `materialized`) with their compound array keys.
44
+ * The stored value as a record this build can read, or `undefined`. A record is stored by
45
+ * structured clone, so this is the check the byte codec's decode makes for LevelDB: a record it
46
+ * fails is left out of `readJournal`, and recovery treats its number as missing.
47
+ */
48
+ function asJournalRecord(value: unknown): JournalRecord | undefined {
49
+ if (typeof value !== 'object' || value === null) return undefined;
50
+ const { seq, entries } = value as { seq?: unknown; entries?: unknown };
51
+ if (typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < 1 || !Array.isArray(entries)) return undefined;
52
+ return entries.every(isBatchEntry) ? { seq, entries } : undefined;
53
+ }
54
+
55
+ function isBatchEntry(entry: unknown): entry is BatchEntry {
56
+ if (typeof entry !== 'object' || entry === null) return false;
57
+ const { key, value } = entry as { key?: unknown; value?: unknown };
58
+ return isStoreKey(key) && (value === undefined || value instanceof Uint8Array);
59
+ }
60
+
61
+ function isStoreKey(key: unknown): key is StoreKey {
62
+ if (typeof key !== 'object' || key === null) return false;
63
+ const { store, blockId, rev, actionId } = key as { store?: unknown; blockId?: unknown; rev?: unknown; actionId?: unknown };
64
+ if (typeof blockId !== 'string') return false;
65
+ switch (store) {
66
+ case 'metadata':
67
+ return true;
68
+ case 'revisions':
69
+ case 'proofs':
70
+ return Number.isInteger(rev);
71
+ case 'pending':
72
+ case 'transactions':
73
+ case 'materialized':
74
+ return typeof actionId === 'string';
75
+ default:
76
+ return false;
77
+ }
78
+ }
79
+
80
+ export type IndexedDBJournalStoreOptions = IndexedDBDurabilityOptions;
81
+
82
+ /**
83
+ * IndexedDB {@link JournalStore}: the six logical block-storage stores mapped to the six IndexedDB
84
+ * object stores (`metadata`, `revisions`, `pending`, `transactions`, `proofs`, `materialized`)
85
+ * with their compound array keys, read exactly as the per-write driver before it read them, so
86
+ * data an earlier build wrote reads unchanged; and the journal in the `journal` object store,
87
+ * which `JournalBatchBackend` drives.
12
88
  *
13
- * `KvRawStorage` now owns all JSON serialization, so this driver only ever
14
- * reads/writes `Uint8Array` values — IndexedDB stores a typed array natively via
15
- * structured clone and returns a `Uint8Array`, so no codec lives here. Everything
16
- * IndexedDB-specific stays: the range/key cursors (drained snapshot-first before
17
- * yielding), and the single `readwrite` transaction that makes `promote` atomic.
89
+ * `KvRawStorage` owns all JSON serialization, so this store only ever reads/writes `Uint8Array`
90
+ * values — IndexedDB stores a typed array natively via structured clone and returns a `Uint8Array`,
91
+ * so no codec lives here; a journal record is stored by structured clone too. Everything
92
+ * IndexedDB-specific stays: the range/key cursors (drained snapshot-first before yielding), and the
93
+ * one `readwrite` transaction each journal write is.
94
+ *
95
+ * ### Why a group survives a power cut, and in order
96
+ *
97
+ * IndexedDB makes one transaction durable when it is asked to (`durability: 'strict'`: the
98
+ * transaction completes only once the browser has put it on the disk) but promises nothing about
99
+ * the order relaxed transactions reach the disk, which is why the backend journals (see
100
+ * `JournalBatchBackend`). Here an append is one relaxed transaction on `journal` alone, and an
101
+ * apply is one strict transaction over the six stores and `journal`: every record's entries in
102
+ * order, the applied-through mark, and the delete of each record applied or discarded. The apply
103
+ * carries every byte it applies, so its durability depends on no earlier transaction, and the
104
+ * backend syncs each apply before the next starts — so what a power cut leaves is a prefix of the
105
+ * groups, and `durability` is `'power-loss'` wherever the browser honours the option
106
+ * (`supportsStrictDurability`). Every request of a transaction is queued synchronously and the
107
+ * transaction awaited once, because IndexedDB commits a transaction that is left idle.
108
+ *
109
+ * The handle is shared with `IndexedDBKVStore` and `loadOrCreateBrowserPeerKey`, so there is no
110
+ * `close` here: the host closes the handle after `storage.close()` has resolved.
18
111
  */
19
- export class IndexedDBStoreDriver implements RawStoreDriver {
112
+ export class IndexedDBJournalStore implements JournalStore {
113
+ // NOTE: in a browser that ignores `durability` this is `'process-crash'`, and there the backend
114
+ // journals nothing and applies every group at once as one relaxed transaction: a group lands
115
+ // whole, but browsers do not promise that what survives an operating-system crash or power cut is
116
+ // a prefix of relaxed transactions (flush contract rule 3). With strict transactions both hold,
117
+ // as the class doc says.
118
+ readonly durability: StoreDurability;
119
+
20
120
  // NOTE: identity is the HANDLE object, so two handles opened over the same IndexedDB database
21
121
  // NAME read as two identities. Resolving that would mean naming the underlying database,
22
122
  // which `OptimysticWebDBHandle` does not expose. The package opener (`db.ts`) hands out one
23
123
  // handle per database name in practice, so this is the reachable case, not the complete one.
124
+ // Two tabs over one database run two nodes over one store, which Invariant 5 of
125
+ // `packages/db-p2p/docs/storage.md` forbids and nothing here enforces: the second tab's open
126
+ // applies the journal records the first tab still holds, and each then numbers its records from
127
+ // its own count.
24
128
  private readonly identity: StoreIdentity;
129
+ private readonly strict: boolean;
25
130
 
26
- constructor(private readonly db: OptimysticWebDBHandle) {
131
+ constructor(private readonly db: OptimysticWebDBHandle, options: IndexedDBJournalStoreOptions = {}) {
132
+ this.strict = resolveStrictDurability(options);
133
+ this.durability = this.strict ? 'power-loss' : 'process-crash';
27
134
  this.identity = identityForHandle('idb-handle', db);
28
135
  }
29
136
 
@@ -31,61 +138,30 @@ export class IndexedDBStoreDriver implements RawStoreDriver {
31
138
  return this.identity;
32
139
  }
33
140
 
34
- // --- metadata ---
141
+ // --- reads: the applied stores ---
35
142
 
36
- async getMetadata(blockId: BlockId): Promise<Uint8Array | undefined> {
37
- return this.db.get('metadata', blockId);
143
+ async get(key: StoreKey): Promise<Uint8Array | undefined> {
144
+ return this.db.get(key.store, idbKeyOf(key));
38
145
  }
39
146
 
40
- async putMetadata(blockId: BlockId, value: Uint8Array): Promise<void> {
41
- await this.db.put('metadata', value, blockId);
42
- }
43
-
44
- // --- revisions ---
45
-
46
- async getRevision(blockId: BlockId, rev: number): Promise<Uint8Array | undefined> {
47
- return this.db.get('revisions', [blockId, rev]);
48
- }
49
-
50
- async putRevision(blockId: BlockId, rev: number, value: Uint8Array): Promise<void> {
51
- await this.db.put('revisions', value, [blockId, rev]);
52
- }
53
-
54
- async *rangeRevisions(blockId: BlockId, lo: number, hi: number, reverse: boolean): AsyncIterable<[number, Uint8Array]> {
147
+ async rangeRevisions(blockId: BlockId, lo: number, hi: number): Promise<[number, Uint8Array][]> {
55
148
  const range = IDBKeyRange.bound([blockId, lo], [blockId, hi]);
56
149
  const tx = this.db.transaction('revisions', 'readonly');
57
150
  const store = tx.objectStore('revisions');
58
- // Snapshot first so we don't hold the transaction open across yields —
59
- // IndexedDB auto-commits idle transactions, which would invalidate the
60
- // cursor between the consumer's awaits (the kernel's drain-before-yield
61
- // contract). Do NOT switch to lazy yielding mid-transaction.
151
+ // Snapshot first so the transaction is not held open across the caller's awaits —
152
+ // IndexedDB auto-commits idle transactions, which would invalidate the cursor
153
+ // (the kernel's drain-before-yield contract). Do NOT switch to lazy yielding mid-transaction.
62
154
  const results: [number, Uint8Array][] = [];
63
- let cursor = await store.openCursor(range, reverse ? 'prev' : 'next');
155
+ let cursor = await store.openCursor(range);
64
156
  while (cursor) {
65
157
  results.push([(cursor.key as [BlockId, number])[1], cursor.value]);
66
158
  cursor = await cursor.continue();
67
159
  }
68
160
  await tx.done;
69
- for (const result of results) {
70
- yield result;
71
- }
161
+ return results;
72
162
  }
73
163
 
74
- // --- pending ---
75
-
76
- async getPending(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
77
- return this.db.get('pending', [blockId, actionId]);
78
- }
79
-
80
- async putPending(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
81
- await this.db.put('pending', value, [blockId, actionId]);
82
- }
83
-
84
- async deletePending(blockId: BlockId, actionId: ActionId): Promise<void> {
85
- await this.db.delete('pending', [blockId, actionId]);
86
- }
87
-
88
- async *listPendingActionIds(blockId: BlockId): AsyncIterable<ActionId> {
164
+ async listPendingActionIds(blockId: BlockId): Promise<ActionId[]> {
89
165
  // IndexedDB key ordering: array keys compare element-by-element, and a
90
166
  // shorter prefix-equal array is less than a longer one; arrays sort
91
167
  // above all primitive types. So `[blockId]` < `[blockId, anyActionId]`
@@ -101,70 +177,9 @@ export class IndexedDBStoreDriver implements RawStoreDriver {
101
177
  cursor = await cursor.continue();
102
178
  }
103
179
  await tx.done;
104
- for (const actionId of results) {
105
- yield actionId;
106
- }
180
+ return results;
107
181
  }
108
182
 
109
- // --- transactions ---
110
-
111
- async getTransaction(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
112
- return this.db.get('transactions', [blockId, actionId]);
113
- }
114
-
115
- async putTransaction(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
116
- await this.db.put('transactions', value, [blockId, actionId]);
117
- }
118
-
119
- // --- proofs (keyed [blockId, rev] like revisions; no delete — see RawStoreDriver.getProof) ---
120
-
121
- async getProof(blockId: BlockId, rev: number): Promise<Uint8Array | undefined> {
122
- return this.db.get('proofs', [blockId, rev]);
123
- }
124
-
125
- async putProof(blockId: BlockId, rev: number, value: Uint8Array): Promise<void> {
126
- await this.db.put('proofs', value, [blockId, rev]);
127
- }
128
-
129
- // --- materialized ---
130
-
131
- async getMaterialized(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
132
- return this.db.get('materialized', [blockId, actionId]);
133
- }
134
-
135
- async putMaterialized(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
136
- await this.db.put('materialized', value, [blockId, actionId]);
137
- }
138
-
139
- // The kernel owns the put-or-delete branch of `saveMaterializedBlock`, so the
140
- // driver exposes delete as a separate op.
141
- async deleteMaterialized(blockId: BlockId, actionId: ActionId): Promise<void> {
142
- await this.db.delete('materialized', [blockId, actionId]);
143
- }
144
-
145
- // --- promote (the only cross-key atomic op) ---
146
-
147
- async promote(blockId: BlockId, actionId: ActionId): Promise<void> {
148
- const key: [BlockId, ActionId] = [blockId, actionId];
149
- // Single readwrite transaction over both stores IS the atomic move: a crash
150
- // leaves either the pending or the committed entry, never both/neither.
151
- const tx = this.db.transaction(['pending', 'transactions'], 'readwrite');
152
- const pendingStore = tx.objectStore('pending');
153
- const transactionsStore = tx.objectStore('transactions');
154
- const value = await pendingStore.get(key);
155
- if (!value) {
156
- // Settle the transaction before throwing so the failed promote does not
157
- // leak an open transaction — keep this ordering.
158
- await tx.done.catch(() => undefined);
159
- throw new Error(`Pending action ${actionId} not found for block ${blockId}`);
160
- }
161
- await transactionsStore.put(value, key);
162
- await pendingStore.delete(key);
163
- await tx.done;
164
- }
165
-
166
- // --- optional passthroughs ---
167
-
168
183
  async *listBlockIds(): AsyncIterable<BlockId> {
169
184
  // The `metadata` store is keyed by blockId directly, so its keys ARE the
170
185
  // distinct block ids. getAllKeys reads them under an implicit readonly
@@ -185,26 +200,86 @@ export class IndexedDBStoreDriver implements RawStoreDriver {
185
200
  return 0;
186
201
  }
187
202
  }
203
+
204
+ // --- the journal ---
205
+
206
+ /** One relaxed transaction on `journal`: the record under its `seq`. `JournalStore.appendJournal`'s contract. */
207
+ async appendJournal(record: JournalRecord): Promise<void> {
208
+ const tx = this.db.transaction('journal', 'readwrite', { durability: 'relaxed' });
209
+ await Promise.all([tx.store.put(record, record.seq), tx.done]);
210
+ }
211
+
212
+ /**
213
+ * One transaction over the six stores and `journal`, strict where the browser supports it: each
214
+ * record's entries in order, then the mark, then the delete of every numbered record. A number
215
+ * with no record present (a strict group's, never appended) deletes nothing.
216
+ * `JournalStore.applyJournal`'s contract.
217
+ */
218
+ async applyJournal(apply: readonly JournalRecord[], appliedThrough: number, discard: readonly number[]): Promise<void> {
219
+ const tx = this.db.transaction(APPLY_STORES, 'readwrite', { durability: transactionDurability(this.strict) });
220
+ const requests: Promise<unknown>[] = [];
221
+ for (const record of apply) {
222
+ for (const { key, value } of record.entries) {
223
+ const store = tx.objectStore(key.store);
224
+ requests.push(value === undefined ? store.delete(idbKeyOf(key)) : store.put(value, idbKeyOf(key)));
225
+ }
226
+ }
227
+ const journal = tx.objectStore('journal');
228
+ requests.push(journal.put(appliedThrough, JOURNAL_MARK_KEY));
229
+ for (const { seq } of apply) requests.push(journal.delete(seq));
230
+ for (const seq of discard) requests.push(journal.delete(seq));
231
+ await Promise.all([...requests, tx.done]);
232
+ }
233
+
234
+ /** One readonly transaction: every numbered record and the mark. `JournalStore.readJournal`'s contract. */
235
+ async readJournal(): Promise<JournalContents> {
236
+ const tx = this.db.transaction('journal', 'readonly');
237
+ // Every record's key is a positive safe integer; the mark's string key sorts above every number.
238
+ const [values, mark] = await Promise.all([
239
+ tx.store.getAll(IDBKeyRange.bound(1, Number.MAX_SAFE_INTEGER)),
240
+ tx.store.get(JOURNAL_MARK_KEY),
241
+ tx.done,
242
+ ]);
243
+ const records: JournalRecord[] = [];
244
+ for (const value of values) {
245
+ const record = asJournalRecord(value);
246
+ if (record) {
247
+ records.push(record);
248
+ } else {
249
+ log('read-journal: a journal record of %s is not one this build can read and is left out; recovery treats its number as missing', this.identity);
250
+ }
251
+ }
252
+ records.sort((a, b) => a.seq - b.seq);
253
+ const appliedThrough = typeof mark === 'number' && Number.isSafeInteger(mark) && mark >= 0 ? mark : 0;
254
+ return { appliedThrough, records };
255
+ }
188
256
  }
189
257
 
258
+ /** The write group's and the journal backend's options (`idleFlushMs`, `maxUnsyncedBytes`, the test-only `setTimer` and `now`), and whether to ask for strict transactions. */
259
+ export type IndexedDBRawStorageOptions = WriteGroupOptions & JournalBatchBackendOptions & IndexedDBDurabilityOptions;
260
+
190
261
  /**
191
- * IndexedDB-backed {@link IRawStorage} for browser peers, now a thin shell over
192
- * the shared {@link KvRawStorage} kernel driven by an {@link IndexedDBStoreDriver}.
193
- * The public name/constructor (`new IndexedDBRawStorage(handle)`) is unchanged so
194
- * existing imports keep resolving; the kernel supplies the `IRawStorage` surface
195
- * and the driver supplies IndexedDB behavior.
262
+ * IndexedDB-backed {@link IRawStorage} for browser peers: the shared {@link KvRawStorage} kernel
263
+ * over a {@link WriteGroupDriver} over a {@link JournalBatchBackend} over an
264
+ * {@link IndexedDBJournalStore}. Every write resolves into the driver's in-memory overlay;
265
+ * `flush()` hands the group to the backend, which applies it as one strict transaction before the
266
+ * flush resolves, or — a flush with a window — appends it as one relaxed journal record and applies
267
+ * it by the deadline. The public name/constructor (`new IndexedDBRawStorage(handle)`) is unchanged
268
+ * so existing imports keep resolving.
196
269
  *
197
- * `listBlockIds`/`getApproximateBytesUsed` are re-declared here as always-present
198
- * (the IndexedDB driver always implements them, so the kernel constructor always
199
- * wires them) — the base declares them optional, but every web consumer relies
200
- * on them.
270
+ * `listBlockIds`/`getApproximateBytesUsed`/`getStoreIdentity`/`close` are re-declared here as
271
+ * always-present (the store always implements the first three, so the backend, driver and kernel
272
+ * always wire them, and the driver always has a `close`) — the base declares them optional, but
273
+ * every web consumer relies on them. `close()` applies what is still held and disarms the timers; it
274
+ * does not close the shared handle, which the host closes afterwards.
201
275
  */
202
276
  export class IndexedDBRawStorage extends KvRawStorage {
203
277
  declare listBlockIds: () => AsyncIterable<BlockId>;
204
278
  declare getApproximateBytesUsed: () => Promise<number>;
205
279
  declare getStoreIdentity: () => StoreIdentity;
280
+ declare close: () => Promise<void>;
206
281
 
207
- constructor(db: OptimysticWebDBHandle) {
208
- super(new IndexedDBStoreDriver(db));
282
+ constructor(db: OptimysticWebDBHandle, options: IndexedDBRawStorageOptions = {}) {
283
+ super(new WriteGroupDriver(new JournalBatchBackend(new IndexedDBJournalStore(db, options), options), options));
209
284
  }
210
285
  }