@optimystic/db-p2p-storage-web 1.15.0 → 1.17.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
package/README.md
CHANGED
|
@@ -4,8 +4,8 @@ IndexedDB-backed storage backend for Optimystic browser peers. Provides:
|
|
|
4
4
|
|
|
5
5
|
- **`IndexedDBRawStorage`** — implements `IRawStorage` so a browser node persists
|
|
6
6
|
block metadata, revisions, pending transactions, committed transactions,
|
|
7
|
-
commit proofs, and
|
|
8
|
-
|
|
7
|
+
commit proofs, and materialized blocks across page reloads, each group of
|
|
8
|
+
writes journaled and applied as one transaction.
|
|
9
9
|
- **`IndexedDBKVStore`** — implements `IKVStore` for the persistent transaction
|
|
10
10
|
state used to recover crashed two-phase commits.
|
|
11
11
|
- **`loadOrCreateBrowserPeerKey`** — generates an Ed25519 libp2p private key on
|
|
@@ -14,7 +14,8 @@ IndexedDB-backed storage backend for Optimystic browser peers. Provides:
|
|
|
14
14
|
|
|
15
15
|
This package is browser-only — it imports no Node built-ins. Counterparts:
|
|
16
16
|
|
|
17
|
-
- `@optimystic/db-p2p-storage-rn` — React Native (
|
|
17
|
+
- `@optimystic/db-p2p-storage-rn` — React Native (LevelDB)
|
|
18
|
+
- `@optimystic/db-p2p-storage-ns` — NativeScript (SQLite)
|
|
18
19
|
- `@optimystic/db-p2p-storage-fs` — Node filesystem
|
|
19
20
|
|
|
20
21
|
## Install
|
|
@@ -57,14 +58,27 @@ The same `IDBPDatabase` handle is shared by all three consumers — IndexedDB
|
|
|
57
58
|
permits concurrent transactions across disjoint object stores, so the storage
|
|
58
59
|
layer parallelises naturally.
|
|
59
60
|
|
|
61
|
+
Close the storage and the key-value store before the handle, and the handle last:
|
|
62
|
+
|
|
63
|
+
```ts
|
|
64
|
+
await rawStorage.close(); // applies what it still holds, disarms its timers
|
|
65
|
+
await kvStore.close(); // commits what it still holds, disarms its timer
|
|
66
|
+
db.close();
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Neither `close()` closes the shared handle. A write a store still holds when the
|
|
70
|
+
handle is closed under it is lost, and a timer it still has armed would fire on
|
|
71
|
+
a closed handle.
|
|
72
|
+
|
|
60
73
|
## Persistence semantics
|
|
61
74
|
|
|
62
75
|
The package opens a single IndexedDB database (`optimystic` by default) with
|
|
63
|
-
|
|
64
|
-
`
|
|
65
|
-
JSON/UTF-8 serialization, so the
|
|
66
|
-
kernel-encoded `Uint8Array` bytes rather
|
|
67
|
-
logical types the kernel decodes them back
|
|
76
|
+
eight object stores. `IndexedDBRawStorage` is the shared `KvRawStorage` kernel
|
|
77
|
+
over a `WriteGroupDriver` over a `JournalBatchBackend` over an
|
|
78
|
+
`IndexedDBJournalStore`: the kernel owns all JSON/UTF-8 serialization, so the
|
|
79
|
+
six block-storage stores hold opaque kernel-encoded `Uint8Array` bytes rather
|
|
80
|
+
than live objects. The keys and the logical types the kernel decodes them back
|
|
81
|
+
into are unchanged from earlier builds, so data written by one reads unchanged:
|
|
68
82
|
|
|
69
83
|
| Store | Key | Stored value | Decoded (logical) type |
|
|
70
84
|
|----------------|----------------------|--------------|------------------------|
|
|
@@ -74,24 +88,92 @@ logical types the kernel decodes them back into are unchanged:
|
|
|
74
88
|
| `transactions` | `[blockId, actionId]`| `Uint8Array` | `Transform` |
|
|
75
89
|
| `proofs` | `[blockId, rev]` | `Uint8Array` | `BlockCommitProof` |
|
|
76
90
|
| `materialized` | `[blockId, actionId]`| `Uint8Array` | `IBlock` |
|
|
91
|
+
| `journal` | `seq` (a number), or `'applied-through'` | a `JournalRecord` by structured clone, or the number of the last record applied | — (owned by `IndexedDBJournalStore`) |
|
|
77
92
|
| `kv` | `key` | `string` or `Uint8Array` | — (not kernel-backed) |
|
|
78
93
|
|
|
79
94
|
`listRevisions` and `listPendingTransactions` use real IndexedDB range cursors
|
|
80
95
|
— never `getAllKeys()` + JS filter — so list latency stays bounded as the store
|
|
81
|
-
grows. `promotePendingTransaction`
|
|
82
|
-
|
|
96
|
+
grows. `promotePendingTransaction` records two entries of one write group — the
|
|
97
|
+
committed row's put and the pending row's delete — applied in that group's
|
|
98
|
+
transaction, so the move is atomic across crashes.
|
|
83
99
|
|
|
84
100
|
`getApproximateBytesUsed()` returns `(await navigator.storage.estimate()).usage`,
|
|
85
101
|
which is **per-origin**, not per-database. That is adequate for `StorageMonitor`
|
|
86
102
|
— which uses the figure as an advisory ring-selection input — but is not a
|
|
87
103
|
precise per-database accounting.
|
|
88
104
|
|
|
105
|
+
## Durability
|
|
106
|
+
|
|
107
|
+
A write resolves into memory and is served from there; `flush()` hands every
|
|
108
|
+
write made since the last flush to the journal backend as **one group**, so a
|
|
109
|
+
group lands whole or not at all. IndexedDB can make one transaction durable
|
|
110
|
+
(`durability: 'strict'`: the transaction completes only once the browser has
|
|
111
|
+
put it on the disk) but promises nothing about the order relaxed transactions
|
|
112
|
+
reach the disk, so the backend journals rather than committing groups directly:
|
|
113
|
+
|
|
114
|
+
- a strict `flush()` (no `withinMs`, or 0) applies the group — and every group
|
|
115
|
+
journaled and not yet applied — as one strict transaction over the six data
|
|
116
|
+
stores and `journal`, and resolves once that transaction has completed;
|
|
117
|
+
- a relaxed `flush({ withinMs })` — what a node uses for a write its cohort
|
|
118
|
+
also holds, see [storage.md §How long a write may wait for its sync](../db-p2p/docs/storage.md#how-long-a-write-may-wait-for-its-sync) —
|
|
119
|
+
appends the group as one journal record in one relaxed transaction on
|
|
120
|
+
`journal` alone and resolves; one strict apply by the earliest deadline, or a
|
|
121
|
+
strict flush before then, applies every record appended since the last apply,
|
|
122
|
+
in order, and deletes them. `whenDurable()` resolves once the groups flushed
|
|
123
|
+
so far are applied.
|
|
124
|
+
|
|
125
|
+
Every apply carries every byte it applies, and the backend applies one at a
|
|
126
|
+
time, so what a power cut leaves is a prefix of the groups: a journal record the
|
|
127
|
+
browser did not keep is a missing number, and recovery at the next open applies
|
|
128
|
+
the consecutive run before it and discards everything after it (details in
|
|
129
|
+
[storage.md §6, *The journal backend*](../db-p2p/docs/storage.md#6-a-write-survives-a-crash-once-a-flush-called-after-it-has-resolved)).
|
|
130
|
+
|
|
131
|
+
Whether a transaction can be strict is the browser's: `IndexedDBRawStorage`
|
|
132
|
+
reports `durability: 'power-loss'` where the browser honours the option (Chrome
|
|
133
|
+
83+, and Firefox and Safari in their current releases, detected once at
|
|
134
|
+
construction by `supportsStrictDurability`), and `'process-crash'` where it
|
|
135
|
+
ignores it. In the latter the backend journals nothing and applies each group
|
|
136
|
+
at once as one relaxed transaction, and the node's start-up line says such a
|
|
137
|
+
store cannot keep the window.
|
|
138
|
+
|
|
139
|
+
What a crash loses, with strict transactions:
|
|
140
|
+
|
|
141
|
+
| Crash | Lost |
|
|
142
|
+
|---|---|
|
|
143
|
+
| the tab, or the browser's process | a group not yet flushed, still in memory; nothing a flush has resolved for: a completed transaction survives the page, so a journaled group is applied at the next open |
|
|
144
|
+
| a power cut or operating-system crash | at most the groups still inside their window, always the most recent ones, each whole; nothing a strict flush has resolved for, and nothing once the window has passed |
|
|
145
|
+
|
|
146
|
+
Without strict transactions the first row holds and the second does not: a
|
|
147
|
+
power cut may lose any write the operating system has not written out, and may
|
|
148
|
+
keep a later group while losing an earlier one.
|
|
149
|
+
|
|
150
|
+
Two things sit outside this. Browser storage can be **evicted** under storage
|
|
151
|
+
pressure, which loses the whole database, unless the page holds persistent
|
|
152
|
+
storage (`navigator.storage.persist()`); that is the host's decision and the
|
|
153
|
+
backend cannot tell the difference between eviction and a database that was
|
|
154
|
+
never written. And two tabs over one database run two nodes over one store,
|
|
155
|
+
which [storage.md §5](../db-p2p/docs/storage.md#5-a-store-is-owned-by-exactly-one-process)
|
|
156
|
+
forbids and nothing here enforces.
|
|
157
|
+
|
|
158
|
+
A failed transaction latches the storage: every later write, flush and
|
|
159
|
+
`whenDurable()` rejects with `StoreFailedError` until the page reopens the store
|
|
160
|
+
(rule 5 of the flush contract,
|
|
161
|
+
[storage.md §6](../db-p2p/docs/storage.md#6-a-write-survives-a-crash-once-a-flush-called-after-it-has-resolved)).
|
|
162
|
+
|
|
163
|
+
`IndexedDBKVStore` writes through a `WriteGroup` over its keys the same way:
|
|
164
|
+
`set` and `delete` resolve into memory, and `flush()` commits everything since
|
|
165
|
+
the last flush as one `readwrite` transaction on `kv`, strict where the browser
|
|
166
|
+
supports it — every flush of this store is strict, so nothing of it is ever
|
|
167
|
+
journaled. `whenDurable()` and `close()` are the group's.
|
|
168
|
+
|
|
89
169
|
## Identity
|
|
90
170
|
|
|
91
171
|
`loadOrCreateBrowserPeerKey(db, keyName?)` writes the libp2p private key as
|
|
92
172
|
raw protobuf bytes (`Uint8Array`) under `keyName` in the `kv` store
|
|
93
|
-
(default `peer-private-key`)
|
|
94
|
-
|
|
173
|
+
(default `peer-private-key`), in one transaction that is strict where the
|
|
174
|
+
browser supports it, so a power cut right after first start cannot give the
|
|
175
|
+
node a different peer id next time. IndexedDB stores typed arrays natively, so
|
|
176
|
+
no base64 round-trip is needed. To rotate the identity, delete that one key:
|
|
95
177
|
|
|
96
178
|
```ts
|
|
97
179
|
await db.delete('kv', 'peer-private-key');
|
|
@@ -107,4 +189,11 @@ indexedDB.deleteDatabase('optimystic');
|
|
|
107
189
|
|
|
108
190
|
`yarn test` runs the spec suite under [`fake-indexeddb`](https://www.npmjs.com/package/fake-indexeddb)
|
|
109
191
|
in Node so CI doesn't need a real browser. Production code only uses the
|
|
110
|
-
IndexedDB W3C API, so fake-indexeddb is a faithful behavioural surrogate
|
|
192
|
+
IndexedDB W3C API, so fake-indexeddb is a faithful behavioural surrogate — with
|
|
193
|
+
one gap: it has no disk, so it keeps the durability a transaction asked for and
|
|
194
|
+
does nothing with it, and does not advertise the option on
|
|
195
|
+
`IDBTransaction.prototype`. The tests pass `strictDurability: true` to take the
|
|
196
|
+
path a strict-capable browser takes, and check which durability each
|
|
197
|
+
transaction asked for, not what a disk did. That a strict transaction survives
|
|
198
|
+
a power cut rests on the browser; a device, or a manual check in one, is the
|
|
199
|
+
only real test of it.
|
package/dist/src/db.d.ts
CHANGED
|
@@ -1,11 +1,18 @@
|
|
|
1
1
|
import { type DBSchema, type IDBPDatabase } from 'idb';
|
|
2
2
|
import type { ActionId, BlockId } from '@optimystic/db-core';
|
|
3
|
+
import type { JournalRecord } from '@optimystic/db-p2p';
|
|
4
|
+
/**
|
|
5
|
+
* The key of the applied-through mark in the `journal` store. A string, where every record's key
|
|
6
|
+
* is a number: IndexedDB orders numbers before strings, so a key range over the numbers never
|
|
7
|
+
* reaches the mark.
|
|
8
|
+
*/
|
|
9
|
+
export declare const JOURNAL_MARK_KEY = "applied-through";
|
|
3
10
|
/**
|
|
4
11
|
* IndexedDB schema for the Optimystic browser storage backend.
|
|
5
12
|
*
|
|
6
13
|
* The six block-storage stores keep their original object stores and compound
|
|
7
|
-
* array keys, but their values are
|
|
8
|
-
* `KvRawStorage` kernel owns JSON (de)serialization, so `
|
|
14
|
+
* array keys, but their values are opaque `Uint8Array` blobs: the shared
|
|
15
|
+
* `KvRawStorage` kernel owns JSON (de)serialization, so `IndexedDBJournalStore`
|
|
9
16
|
* only ever hands IndexedDB kernel-encoded bytes. IndexedDB stores a
|
|
10
17
|
* `Uint8Array` natively via structured clone and returns a `Uint8Array`, so the
|
|
11
18
|
* bytes round-trip without a codec here.
|
|
@@ -20,7 +27,11 @@ import type { ActionId, BlockId } from '@optimystic/db-core';
|
|
|
20
27
|
* as `revisions`, deliberately NOT the action keyspace (an action id is caller-chosen,
|
|
21
28
|
* so no reserved id could be relied on).
|
|
22
29
|
* - `materialized`: materialized block bytes keyed by `[blockId, actionId]`. Deleting
|
|
23
|
-
* the row is a
|
|
30
|
+
* the row is an entry of a write group with no value, not a stored `undefined`.
|
|
31
|
+
* - `journal`: the write groups appended and not yet applied to the six stores above, each a
|
|
32
|
+
* `JournalRecord` stored by structured clone under its `seq` (no codec: the record's keys are
|
|
33
|
+
* plain objects and its values `Uint8Array`s), and under {@link JOURNAL_MARK_KEY} the number of
|
|
34
|
+
* the last record applied. `IndexedDBJournalStore` owns both; nothing else touches the store.
|
|
24
35
|
* - `kv`: a generic string keyspace shared by `IndexedDBKVStore` and the
|
|
25
36
|
* identity helper. Identity keys are stored as raw `Uint8Array` blobs (under
|
|
26
37
|
* a separate logical store from string-only `IKVStore` data, but the same
|
|
@@ -51,13 +62,17 @@ export interface OptimysticWebDB extends DBSchema {
|
|
|
51
62
|
key: [BlockId, ActionId];
|
|
52
63
|
value: Uint8Array;
|
|
53
64
|
};
|
|
65
|
+
journal: {
|
|
66
|
+
key: number | typeof JOURNAL_MARK_KEY;
|
|
67
|
+
value: JournalRecord | number;
|
|
68
|
+
};
|
|
54
69
|
kv: {
|
|
55
70
|
key: string;
|
|
56
71
|
value: string | Uint8Array;
|
|
57
72
|
};
|
|
58
73
|
}
|
|
59
74
|
export declare const DEFAULT_DB_NAME = "optimystic";
|
|
60
|
-
export declare const DEFAULT_DB_VERSION =
|
|
75
|
+
export declare const DEFAULT_DB_VERSION = 3;
|
|
61
76
|
export type OptimysticWebDBHandle = IDBPDatabase<OptimysticWebDB>;
|
|
62
77
|
/**
|
|
63
78
|
* Opens (and creates if necessary) the Optimystic IndexedDB database used by
|
package/dist/src/db.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,KAAK,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;
|
|
1
|
+
{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,KAAK,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,eAAgB,SAAQ,QAAQ;IAChD,QAAQ,EAAE;QACT,GAAG,EAAE,OAAO,CAAC;QACb,KAAK,EAAE,UAAU,CAAC;KAClB,CAAC;IACF,SAAS,EAAE;QACV,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACvB,KAAK,EAAE,UAAU,CAAC;KAClB,CAAC;IACF,OAAO,EAAE;QACR,GAAG,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACzB,KAAK,EAAE,UAAU,CAAC;KAClB,CAAC;IACF,YAAY,EAAE;QACb,GAAG,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACzB,KAAK,EAAE,UAAU,CAAC;KAClB,CAAC;IACF,MAAM,EAAE;QACP,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACvB,KAAK,EAAE,UAAU,CAAC;KAClB,CAAC;IACF,YAAY,EAAE;QACb,GAAG,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACzB,KAAK,EAAE,UAAU,CAAC;KAClB,CAAC;IACF,OAAO,EAAE;QACR,GAAG,EAAE,MAAM,GAAG,OAAO,gBAAgB,CAAC;QACtC,KAAK,EAAE,aAAa,GAAG,MAAM,CAAC;KAC9B,CAAC;IACF,EAAE,EAAE;QACH,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC;KAC3B,CAAC;CACF;AAED,eAAO,MAAM,eAAe,eAAe,CAAC;AAK5C,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC,MAAM,MAAM,qBAAqB,GAAG,YAAY,CAAC,eAAe,CAAC,CAAC;AAElE;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACxC,IAAI,GAAE,MAAwB,EAC9B,OAAO,GAAE,MAA2B,GAClC,OAAO,CAAC,qBAAqB,CAAC,CA6BhC"}
|
package/dist/src/db.js
CHANGED
|
@@ -1,8 +1,16 @@
|
|
|
1
1
|
import { openDB } from 'idb';
|
|
2
|
+
/**
|
|
3
|
+
* The key of the applied-through mark in the `journal` store. A string, where every record's key
|
|
4
|
+
* is a number: IndexedDB orders numbers before strings, so a key range over the numbers never
|
|
5
|
+
* reaches the mark.
|
|
6
|
+
*/
|
|
7
|
+
export const JOURNAL_MARK_KEY = 'applied-through';
|
|
2
8
|
export const DEFAULT_DB_NAME = 'optimystic';
|
|
3
|
-
// Bumped to 2 when the `proofs` object store was added
|
|
4
|
-
// by `objectStoreNames.contains`, so an existing
|
|
5
|
-
|
|
9
|
+
// Bumped to 2 when the `proofs` object store was added and to 3 for `journal`. The `upgrade` hook
|
|
10
|
+
// is guarded by `objectStoreNames.contains`, so an existing database gains only the stores it
|
|
11
|
+
// lacks (backlog `debt-indexeddb-version-upgrade-is-untested-and-unhandled` owns testing that, and
|
|
12
|
+
// the open that another tab's older connection blocks).
|
|
13
|
+
export const DEFAULT_DB_VERSION = 3;
|
|
6
14
|
/**
|
|
7
15
|
* Opens (and creates if necessary) the Optimystic IndexedDB database used by
|
|
8
16
|
* `IndexedDBRawStorage`, `IndexedDBKVStore`, and `loadOrCreateBrowserPeerKey`.
|
|
@@ -31,6 +39,9 @@ export async function openOptimysticWebDb(name = DEFAULT_DB_NAME, version = DEFA
|
|
|
31
39
|
if (!db.objectStoreNames.contains('materialized')) {
|
|
32
40
|
db.createObjectStore('materialized');
|
|
33
41
|
}
|
|
42
|
+
if (!db.objectStoreNames.contains('journal')) {
|
|
43
|
+
db.createObjectStore('journal');
|
|
44
|
+
}
|
|
34
45
|
if (!db.objectStoreNames.contains('kv')) {
|
|
35
46
|
db.createObjectStore('kv');
|
|
36
47
|
}
|
package/dist/src/db.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"db.js","sourceRoot":"","sources":["../../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAoC,MAAM,KAAK,CAAC;
|
|
1
|
+
{"version":3,"file":"db.js","sourceRoot":"","sources":["../../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAoC,MAAM,KAAK,CAAC;AAI/D;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;AAmElD,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,CAAC;AAC5C,kGAAkG;AAClG,8FAA8F;AAC9F,mGAAmG;AACnG,wDAAwD;AACxD,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAIpC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACxC,OAAe,eAAe,EAC9B,UAAkB,kBAAkB;IAEpC,OAAO,MAAM,CAAkB,IAAI,EAAE,OAAO,EAAE;QAC7C,OAAO,CAAC,EAAE;YACT,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC/C,EAAE,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC;YAClC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;gBAChD,EAAE,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;YACnC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC9C,EAAE,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;YACjC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;gBACnD,EAAE,CAAC,iBAAiB,CAAC,cAAc,CAAC,CAAC;YACtC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC7C,EAAE,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC;YAChC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;gBACnD,EAAE,CAAC,iBAAiB,CAAC,cAAc,CAAC,CAAC;YACtC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC9C,EAAE,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;YACjC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzC,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;YAC5B,CAAC;QACF,CAAC;KACD,CAAC,CAAC;AACJ,CAAC"}
|
|
@@ -0,0 +1,30 @@
|
|
|
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 declare function supportsStrictDurability(): boolean;
|
|
14
|
+
/** The option every store of this package takes: whether the transactions that must reach the disk ask for strict durability. */
|
|
15
|
+
export interface IndexedDBDurabilityOptions {
|
|
16
|
+
/**
|
|
17
|
+
* Whether a transaction that must survive a power cut asks for `durability: 'strict'`. Defaults to
|
|
18
|
+
* {@link supportsStrictDurability}. Tests set it, since `fake-indexeddb` honours the option
|
|
19
|
+
* without advertising it; a host has no reason to.
|
|
20
|
+
*/
|
|
21
|
+
readonly strictDurability?: boolean;
|
|
22
|
+
}
|
|
23
|
+
export declare function resolveStrictDurability(options: IndexedDBDurabilityOptions): boolean;
|
|
24
|
+
/**
|
|
25
|
+
* The durability a transaction asks for: `'strict'` for one that must be on the disk before it
|
|
26
|
+
* completes, where the browser supports it, and `'relaxed'` otherwise — what every current
|
|
27
|
+
* browser's default already is, and what a browser without the option does whatever is asked.
|
|
28
|
+
*/
|
|
29
|
+
export declare function transactionDurability(strict: boolean): IDBTransactionDurability;
|
|
30
|
+
//# sourceMappingURL=durability.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"durability.d.ts","sourceRoot":"","sources":["../../src/durability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED,iIAAiI;AACjI,MAAM,WAAW,0BAA0B;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAEpF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,wBAAwB,CAE/E"}
|
|
@@ -0,0 +1,27 @@
|
|
|
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() {
|
|
14
|
+
return typeof IDBTransaction !== 'undefined' && 'durability' in IDBTransaction.prototype;
|
|
15
|
+
}
|
|
16
|
+
export function resolveStrictDurability(options) {
|
|
17
|
+
return options.strictDurability ?? supportsStrictDurability();
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* The durability a transaction asks for: `'strict'` for one that must be on the disk before it
|
|
21
|
+
* completes, where the browser supports it, and `'relaxed'` otherwise — what every current
|
|
22
|
+
* browser's default already is, and what a browser without the option does whatever is asked.
|
|
23
|
+
*/
|
|
24
|
+
export function transactionDurability(strict) {
|
|
25
|
+
return strict ? 'strict' : 'relaxed';
|
|
26
|
+
}
|
|
27
|
+
//# sourceMappingURL=durability.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"durability.js","sourceRoot":"","sources":["../../src/durability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,wBAAwB;IACvC,OAAO,OAAO,cAAc,KAAK,WAAW,IAAI,YAAY,IAAI,cAAc,CAAC,SAAS,CAAC;AAC1F,CAAC;AAYD,MAAM,UAAU,uBAAuB,CAAC,OAAmC;IAC1E,OAAO,OAAO,CAAC,gBAAgB,IAAI,wBAAwB,EAAE,CAAC;AAC/D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAe;IACpD,OAAO,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;AACtC,CAAC"}
|
package/dist/src/identity.d.ts
CHANGED
|
@@ -1,9 +1,12 @@
|
|
|
1
1
|
import type { PrivateKey } from '@libp2p/interface';
|
|
2
2
|
import type { OptimysticWebDBHandle } from './db.js';
|
|
3
|
+
import { type IndexedDBDurabilityOptions } from './durability.js';
|
|
3
4
|
export declare const DEFAULT_PEER_KEY_NAME = "peer-private-key";
|
|
4
5
|
/**
|
|
5
6
|
* Loads the persisted browser peer's libp2p private key, or generates a fresh
|
|
6
|
-
* Ed25519 key on first call and persists it
|
|
7
|
+
* Ed25519 key on first call and persists it in one transaction that is strict
|
|
8
|
+
* where the browser supports it, so a power cut right after first start cannot
|
|
9
|
+
* give the node a different peer id next time. An existing key is read as it is.
|
|
7
10
|
*
|
|
8
11
|
* Stores the key as raw protobuf bytes (a `Uint8Array`) under `keyName` in the
|
|
9
12
|
* `kv` object store. IndexedDB stores typed arrays natively — no base64 round-trip.
|
|
@@ -11,5 +14,5 @@ export declare const DEFAULT_PEER_KEY_NAME = "peer-private-key";
|
|
|
11
14
|
* The returned `PrivateKey` can be passed directly to `createLibp2pNode({ privateKey })`,
|
|
12
15
|
* giving a browser peer a stable, reload-surviving identity.
|
|
13
16
|
*/
|
|
14
|
-
export declare function loadOrCreateBrowserPeerKey(db: OptimysticWebDBHandle, keyName?: string): Promise<PrivateKey>;
|
|
17
|
+
export declare function loadOrCreateBrowserPeerKey(db: OptimysticWebDBHandle, keyName?: string, options?: IndexedDBDurabilityOptions): Promise<PrivateKey>;
|
|
15
18
|
//# sourceMappingURL=identity.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/identity.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;
|
|
1
|
+
{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/identity.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAkD,KAAK,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAElH,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,wBAAsB,0BAA0B,CAC/C,EAAE,EAAE,qBAAqB,EACzB,OAAO,GAAE,MAA8B,EACvC,OAAO,GAAE,0BAA+B,GACtC,OAAO,CAAC,UAAU,CAAC,CAUrB"}
|
package/dist/src/identity.js
CHANGED
|
@@ -1,8 +1,11 @@
|
|
|
1
1
|
import { generateKeyPair, privateKeyFromProtobuf, privateKeyToProtobuf } from '@libp2p/crypto/keys';
|
|
2
|
+
import { resolveStrictDurability, transactionDurability } from './durability.js';
|
|
2
3
|
export const DEFAULT_PEER_KEY_NAME = 'peer-private-key';
|
|
3
4
|
/**
|
|
4
5
|
* Loads the persisted browser peer's libp2p private key, or generates a fresh
|
|
5
|
-
* Ed25519 key on first call and persists it
|
|
6
|
+
* Ed25519 key on first call and persists it in one transaction that is strict
|
|
7
|
+
* where the browser supports it, so a power cut right after first start cannot
|
|
8
|
+
* give the node a different peer id next time. An existing key is read as it is.
|
|
6
9
|
*
|
|
7
10
|
* Stores the key as raw protobuf bytes (a `Uint8Array`) under `keyName` in the
|
|
8
11
|
* `kv` object store. IndexedDB stores typed arrays natively — no base64 round-trip.
|
|
@@ -10,14 +13,15 @@ export const DEFAULT_PEER_KEY_NAME = 'peer-private-key';
|
|
|
10
13
|
* The returned `PrivateKey` can be passed directly to `createLibp2pNode({ privateKey })`,
|
|
11
14
|
* giving a browser peer a stable, reload-surviving identity.
|
|
12
15
|
*/
|
|
13
|
-
export async function loadOrCreateBrowserPeerKey(db, keyName = DEFAULT_PEER_KEY_NAME) {
|
|
16
|
+
export async function loadOrCreateBrowserPeerKey(db, keyName = DEFAULT_PEER_KEY_NAME, options = {}) {
|
|
14
17
|
const stored = await db.get('kv', keyName);
|
|
15
18
|
if (stored instanceof Uint8Array) {
|
|
16
19
|
return privateKeyFromProtobuf(stored);
|
|
17
20
|
}
|
|
18
21
|
const key = await generateKeyPair('Ed25519');
|
|
19
22
|
const bytes = privateKeyToProtobuf(key);
|
|
20
|
-
|
|
23
|
+
const tx = db.transaction('kv', 'readwrite', { durability: transactionDurability(resolveStrictDurability(options)) });
|
|
24
|
+
await Promise.all([tx.store.put(bytes, keyName), tx.done]);
|
|
21
25
|
return key;
|
|
22
26
|
}
|
|
23
27
|
//# sourceMappingURL=identity.js.map
|
package/dist/src/identity.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;
|
|
1
|
+
{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGpG,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAmC,MAAM,iBAAiB,CAAC;AAElH,MAAM,CAAC,MAAM,qBAAqB,GAAG,kBAAkB,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC/C,EAAyB,EACzB,UAAkB,qBAAqB,EACvC,UAAsC,EAAE;IAExC,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC3C,IAAI,MAAM,YAAY,UAAU,EAAE,CAAC;QAClC,OAAO,sBAAsB,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,eAAe,CAAC,SAAS,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE,UAAU,EAAE,qBAAqB,CAAC,uBAAuB,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IACtH,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3D,OAAO,GAAG,CAAC;AACZ,CAAC"}
|
package/dist/src/index.d.ts
CHANGED
package/dist/src/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,eAAe,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,eAAe,CAAC"}
|
package/dist/src/index.js
CHANGED
package/dist/src/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,eAAe,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,eAAe,CAAC"}
|
|
@@ -1,20 +1,43 @@
|
|
|
1
|
-
import type
|
|
1
|
+
import { type FlushOptions, type IKVStore, type WriteGroupOptions } from '@optimystic/db-p2p';
|
|
2
2
|
import type { OptimysticWebDBHandle } from './db.js';
|
|
3
|
+
import { type IndexedDBDurabilityOptions } from './durability.js';
|
|
4
|
+
/** The write group's options (`idleFlushMs`, `maxUnsyncedBytes`, the test-only `setTimer`), and whether to ask for strict transactions. */
|
|
5
|
+
export type IndexedDBKVStoreOptions = WriteGroupOptions & IndexedDBDurabilityOptions;
|
|
3
6
|
/**
|
|
4
7
|
* IndexedDB-backed `IKVStore` adapter for browser peers.
|
|
5
8
|
*
|
|
6
|
-
* Stored keys are namespaced with `prefix` so the `kv` object store can be
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
9
|
+
* Stored keys are namespaced with `prefix` so the `kv` object store can be shared with the identity
|
|
10
|
+
* helper without collisions. `list(prefix)` uses a range-bounded key cursor — never `getAllKeys()` —
|
|
11
|
+
* so a large `kv` store does not pay an O(n) JS-side filter cost.
|
|
12
|
+
*
|
|
13
|
+
* Writes go through a {@link WriteGroup} over the plain keys, as `FileKVStore` does: a `set` or
|
|
14
|
+
* `delete` resolves into memory, served from there to `get` and `list`, and `flush()` commits
|
|
15
|
+
* everything written since the last flush as ONE `readwrite` transaction on `kv`, strict where the
|
|
16
|
+
* browser supports it (`supportsStrictDurability`), so the writes are on the disk before the flush
|
|
17
|
+
* resolves. Every flush the node makes of this store is strict, and so is the group's own idle
|
|
18
|
+
* flush, so there is no relaxed path to journal: a flush given a window is treated as strict, as a
|
|
19
|
+
* store that cannot defer a sync treats every window. A failed commit latches the store, after which
|
|
20
|
+
* every write and flush throws `StoreFailedError` (rule 5 of the flush contract on
|
|
21
|
+
* `RawStoreDriver.flush`); reads keep serving the overlay.
|
|
10
22
|
*/
|
|
11
23
|
export declare class IndexedDBKVStore implements IKVStore {
|
|
12
24
|
private readonly db;
|
|
13
25
|
private readonly prefix;
|
|
14
|
-
|
|
26
|
+
private readonly group;
|
|
27
|
+
private readonly strict;
|
|
28
|
+
constructor(db: OptimysticWebDBHandle, prefix?: string, options?: IndexedDBKVStoreOptions);
|
|
15
29
|
get(key: string): Promise<string | undefined>;
|
|
16
30
|
set(key: string, value: string): Promise<void>;
|
|
17
31
|
delete(key: string): Promise<void>;
|
|
32
|
+
/** Every key under `prefix`: the store's, plus those written and not yet flushed, less those deleted and not yet flushed. */
|
|
18
33
|
list(prefix: string): Promise<string[]>;
|
|
34
|
+
/** Make every write resolved before this call durable: one transaction, strict where supported, whatever `options.withinMs` says. The contract is `RawStoreDriver.flush`'s. */
|
|
35
|
+
flush(options?: FlushOptions): Promise<void>;
|
|
36
|
+
/** Resolves once every write covered by a flush that resolved before this call is durable; `RawStoreDriver.whenDurable`'s contract. */
|
|
37
|
+
whenDurable(): Promise<void>;
|
|
38
|
+
/** Flush what is still held and disarm the idle timer. The host closes the shared handle after this resolves. */
|
|
39
|
+
close(): Promise<void>;
|
|
40
|
+
private commit;
|
|
41
|
+
private listStored;
|
|
19
42
|
}
|
|
20
43
|
//# sourceMappingURL=indexeddb-kv-store.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"indexeddb-kv-store.d.ts","sourceRoot":"","sources":["../../src/indexeddb-kv-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;
|
|
1
|
+
{"version":3,"file":"indexeddb-kv-store.d.ts","sourceRoot":"","sources":["../../src/indexeddb-kv-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmC,KAAK,YAAY,EAAE,KAAK,QAAQ,EAAwB,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACrJ,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAkD,KAAK,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAElH,2IAA2I;AAC3I,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,GAAG,0BAA0B,CAAC;AAQrF;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,gBAAiB,YAAW,QAAQ;IAK/C,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM;IALxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;gBAGf,EAAE,EAAE,qBAAqB,EACzB,MAAM,GAAE,MAA0B,EACnD,OAAO,GAAE,uBAA4B;IAUhC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAO7C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC,6HAA6H;IACvH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAY7C,+KAA+K;IAC/K,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C,uIAAuI;IACvI,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,iHAAiH;IACjH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAIR,MAAM;YAUN,UAAU;CAkBxB"}
|
|
@@ -1,29 +1,91 @@
|
|
|
1
|
+
import { WriteGroup } from '@optimystic/db-p2p';
|
|
2
|
+
import { resolveStrictDurability, transactionDurability } from './durability.js';
|
|
3
|
+
const encoder = new TextEncoder();
|
|
4
|
+
// Built on first use rather than at module load, like every other `TextDecoder` in library source
|
|
5
|
+
// (see NO_MODULE_SCOPE_TEXT_DECODER in eslint.config.js).
|
|
6
|
+
let decoderInstance;
|
|
7
|
+
const decoder = () => decoderInstance ??= new TextDecoder();
|
|
1
8
|
/**
|
|
2
9
|
* IndexedDB-backed `IKVStore` adapter for browser peers.
|
|
3
10
|
*
|
|
4
|
-
* Stored keys are namespaced with `prefix` so the `kv` object store can be
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
11
|
+
* Stored keys are namespaced with `prefix` so the `kv` object store can be shared with the identity
|
|
12
|
+
* helper without collisions. `list(prefix)` uses a range-bounded key cursor — never `getAllKeys()` —
|
|
13
|
+
* so a large `kv` store does not pay an O(n) JS-side filter cost.
|
|
14
|
+
*
|
|
15
|
+
* Writes go through a {@link WriteGroup} over the plain keys, as `FileKVStore` does: a `set` or
|
|
16
|
+
* `delete` resolves into memory, served from there to `get` and `list`, and `flush()` commits
|
|
17
|
+
* everything written since the last flush as ONE `readwrite` transaction on `kv`, strict where the
|
|
18
|
+
* browser supports it (`supportsStrictDurability`), so the writes are on the disk before the flush
|
|
19
|
+
* resolves. Every flush the node makes of this store is strict, and so is the group's own idle
|
|
20
|
+
* flush, so there is no relaxed path to journal: a flush given a window is treated as strict, as a
|
|
21
|
+
* store that cannot defer a sync treats every window. A failed commit latches the store, after which
|
|
22
|
+
* every write and flush throws `StoreFailedError` (rule 5 of the flush contract on
|
|
23
|
+
* `RawStoreDriver.flush`); reads keep serving the overlay.
|
|
8
24
|
*/
|
|
9
25
|
export class IndexedDBKVStore {
|
|
10
26
|
db;
|
|
11
27
|
prefix;
|
|
12
|
-
|
|
28
|
+
group;
|
|
29
|
+
strict;
|
|
30
|
+
constructor(db, prefix = 'optimystic:txn:', options = {}) {
|
|
13
31
|
this.db = db;
|
|
14
32
|
this.prefix = prefix;
|
|
33
|
+
this.strict = resolveStrictDurability(options);
|
|
34
|
+
this.group = new WriteGroup(key => key, {
|
|
35
|
+
commit: entries => this.commit(entries),
|
|
36
|
+
// Every commit is as durable as this store can make it when it resolves, so nothing is ever owed a sync.
|
|
37
|
+
sync: () => Promise.resolve(),
|
|
38
|
+
}, options);
|
|
15
39
|
}
|
|
16
40
|
async get(key) {
|
|
41
|
+
const held = this.group.lookup(key);
|
|
42
|
+
if (held !== undefined)
|
|
43
|
+
return held === null ? undefined : decoder().decode(held);
|
|
17
44
|
const value = await this.db.get('kv', this.prefix + key);
|
|
18
45
|
return typeof value === 'string' ? value : undefined;
|
|
19
46
|
}
|
|
20
47
|
async set(key, value) {
|
|
21
|
-
|
|
48
|
+
this.group.put(key, encoder.encode(value));
|
|
22
49
|
}
|
|
23
50
|
async delete(key) {
|
|
24
|
-
|
|
51
|
+
this.group.delete(key);
|
|
25
52
|
}
|
|
53
|
+
/** Every key under `prefix`: the store's, plus those written and not yet flushed, less those deleted and not yet flushed. */
|
|
26
54
|
async list(prefix) {
|
|
55
|
+
// Taken before awaiting the store: a commit resolving meanwhile drops entries from the overlay
|
|
56
|
+
// that the listing below may have been taken without.
|
|
57
|
+
const held = [...this.group.entries()].filter(([key]) => key.startsWith(prefix));
|
|
58
|
+
const keys = new Set(await this.listStored(prefix));
|
|
59
|
+
for (const [key, value] of held) {
|
|
60
|
+
if (value === null)
|
|
61
|
+
keys.delete(key);
|
|
62
|
+
else
|
|
63
|
+
keys.add(key);
|
|
64
|
+
}
|
|
65
|
+
return [...keys];
|
|
66
|
+
}
|
|
67
|
+
/** Make every write resolved before this call durable: one transaction, strict where supported, whatever `options.withinMs` says. The contract is `RawStoreDriver.flush`'s. */
|
|
68
|
+
flush(options) {
|
|
69
|
+
return this.group.flush(options);
|
|
70
|
+
}
|
|
71
|
+
/** Resolves once every write covered by a flush that resolved before this call is durable; `RawStoreDriver.whenDurable`'s contract. */
|
|
72
|
+
whenDurable() {
|
|
73
|
+
return this.group.whenDurable();
|
|
74
|
+
}
|
|
75
|
+
/** Flush what is still held and disarm the idle timer. The host closes the shared handle after this resolves. */
|
|
76
|
+
close() {
|
|
77
|
+
return this.group.close();
|
|
78
|
+
}
|
|
79
|
+
async commit(entries) {
|
|
80
|
+
const tx = this.db.transaction('kv', 'readwrite', { durability: transactionDurability(this.strict) });
|
|
81
|
+
// Queued synchronously and awaited together with the transaction: IndexedDB commits a transaction that is left idle.
|
|
82
|
+
const requests = entries.map(({ key, value }) => value === undefined
|
|
83
|
+
? tx.store.delete(this.prefix + key)
|
|
84
|
+
: tx.store.put(decoder().decode(value), this.prefix + key));
|
|
85
|
+
await Promise.all([...requests, tx.done]);
|
|
86
|
+
return { durable: Promise.resolve() };
|
|
87
|
+
}
|
|
88
|
+
async listStored(prefix) {
|
|
27
89
|
const fullPrefix = this.prefix + prefix;
|
|
28
90
|
// '' is the highest BMP code unit; appending it produces a string
|
|
29
91
|
// that is >= every string starting with `fullPrefix`. IndexedDB compares
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"indexeddb-kv-store.js","sourceRoot":"","sources":["../../src/indexeddb-kv-store.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"indexeddb-kv-store.js","sourceRoot":"","sources":["../../src/indexeddb-kv-store.ts"],"names":[],"mappings":"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"}
|