@optimystic/db-p2p-storage-web 1.14.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.
- package/README.md +102 -13
- package/dist/src/db.d.ts +19 -4
- package/dist/src/db.d.ts.map +1 -1
- package/dist/src/db.js +14 -3
- package/dist/src/db.js.map +1 -1
- package/dist/src/durability.d.ts +30 -0
- package/dist/src/durability.d.ts.map +1 -0
- package/dist/src/durability.js +27 -0
- package/dist/src/durability.js.map +1 -0
- package/dist/src/identity.d.ts +5 -2
- package/dist/src/identity.d.ts.map +1 -1
- package/dist/src/identity.js +7 -3
- package/dist/src/identity.js.map +1 -1
- package/dist/src/index.d.ts +1 -0
- package/dist/src/index.d.ts.map +1 -1
- package/dist/src/index.js +1 -0
- package/dist/src/index.js.map +1 -1
- package/dist/src/indexeddb-kv-store.d.ts +29 -6
- package/dist/src/indexeddb-kv-store.d.ts.map +1 -1
- package/dist/src/indexeddb-kv-store.js +69 -7
- package/dist/src/indexeddb-kv-store.js.map +1 -1
- package/dist/src/indexeddb-storage.d.ts +65 -39
- package/dist/src/indexeddb-storage.d.ts.map +1 -1
- package/dist/src/indexeddb-storage.js +176 -104
- package/dist/src/indexeddb-storage.js.map +1 -1
- package/package.json +3 -3
- package/src/db.ts +27 -6
- package/src/durability.ts +38 -0
- package/src/identity.ts +7 -2
- package/src/index.ts +1 -0
- package/src/indexeddb-kv-store.ts +78 -8
- package/src/indexeddb-storage.ts +201 -126
|
@@ -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
|
-
|
|
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,34 +1,104 @@
|
|
|
1
|
-
import type
|
|
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
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
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
|
-
|
|
56
|
+
this.group.put(key, encoder.encode(value));
|
|
25
57
|
}
|
|
26
58
|
|
|
27
59
|
async delete(key: string): Promise<void> {
|
|
28
|
-
|
|
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
|
package/src/indexeddb-storage.ts
CHANGED
|
@@ -1,29 +1,136 @@
|
|
|
1
1
|
import type { ActionId, BlockId } from '@optimystic/db-core';
|
|
2
|
-
import {
|
|
3
|
-
|
|
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
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
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`
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
* IndexedDB-specific stays: the range/key cursors (drained snapshot-first before
|
|
17
|
-
*
|
|
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
|
|
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
|
-
// ---
|
|
141
|
+
// --- reads: the applied stores ---
|
|
35
142
|
|
|
36
|
-
async
|
|
37
|
-
return this.db.get(
|
|
143
|
+
async get(key: StoreKey): Promise<Uint8Array | undefined> {
|
|
144
|
+
return this.db.get(key.store, idbKeyOf(key));
|
|
38
145
|
}
|
|
39
146
|
|
|
40
|
-
async
|
|
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
|
|
59
|
-
// IndexedDB auto-commits idle transactions, which would invalidate the
|
|
60
|
-
//
|
|
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
|
|
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
|
-
|
|
70
|
-
yield result;
|
|
71
|
-
}
|
|
161
|
+
return results;
|
|
72
162
|
}
|
|
73
163
|
|
|
74
|
-
|
|
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
|
-
|
|
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
|
|
192
|
-
*
|
|
193
|
-
*
|
|
194
|
-
*
|
|
195
|
-
*
|
|
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
|
|
198
|
-
* (the
|
|
199
|
-
*
|
|
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
|
|
282
|
+
constructor(db: OptimysticWebDBHandle, options: IndexedDBRawStorageOptions = {}) {
|
|
283
|
+
super(new WriteGroupDriver(new JournalBatchBackend(new IndexedDBJournalStore(db, options), options), options));
|
|
209
284
|
}
|
|
210
285
|
}
|