@le-space/orbitdb-storage-bridge 0.21.0 → 0.22.1
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 +45 -3
- package/lib/backends/aleph-pin.js +3 -1
- package/lib/backends/aleph.js +13 -7
- package/lib/backends/storacha.js +2 -4
- package/lib/backends/types.js +3 -1
- package/lib/backup-car.js +7 -9
- package/lib/backup-helpers.js +1 -1
- package/lib/live-backup.js +5 -3
- package/lib/orbitdb-storacha-bridge.js +12 -7
- package/lib/storacha-client.js +36 -0
- package/package.json +14 -11
- package/lib/backup.js +0 -249
package/README.md
CHANGED
|
@@ -25,8 +25,8 @@ Where "somewhere else" is, is a choice:
|
|
|
25
25
|
|
|
26
26
|
| Backend | Needs | |
|
|
27
27
|
| --- | --- | --- |
|
|
28
|
-
| `aleph` | nothing | the only backend a browser can write to with no key; ingest only |
|
|
29
|
-
| `aleph-pin` | a signing key: the paying account's, or one it authorised | the signed STORE message that makes Aleph keep it, paid in credits |
|
|
28
|
+
| `aleph` | nothing | the only backend a browser can write to with no key; ingest only — nothing is kept, listed or deleted here, see `aleph-pin` |
|
|
29
|
+
| `aleph-pin` | a signing key: the paying account's, or one it authorised | the signed STORE message that makes Aleph keep it, paid in credits — and the FORGET that releases it |
|
|
30
30
|
| `pinata` | a scoped JWT | pin-by-CID as well as CAR upload |
|
|
31
31
|
| `lighthouse` | an API key | pay once, stored in perpetuity |
|
|
32
32
|
| `memory` | nothing | in-process, for tests and demos |
|
|
@@ -39,12 +39,54 @@ points do not involve a storage service at all — `courier-sync` replicates ove
|
|
|
39
39
|
(a LoRa mesh, a QR relay, a file), and `dehydrate`/`hydrate` put a database where a second device
|
|
40
40
|
can find it from a passkey alone.
|
|
41
41
|
|
|
42
|
+
How the pieces fit, as sequence diagrams: a full backup with a delegate's STORE and the restore on
|
|
43
|
+
an empty device in [docs/APP-BACKUP.md](docs/APP-BACKUP.md), the increments between two backups in
|
|
44
|
+
[docs/LIVE-BACKUP.md](docs/LIVE-BACKUP.md), the FORGET in
|
|
45
|
+
[docs/STORAGE-BACKENDS.md](docs/STORAGE-BACKENDS.md#forgetting).
|
|
46
|
+
|
|
47
|
+
## Entry points
|
|
48
|
+
|
|
49
|
+
Every import path the package exports, and what it is for. New code uses the sub-paths; the main
|
|
50
|
+
entry is the Storacha-era class and the helpers it grew.
|
|
51
|
+
|
|
52
|
+
| Import (`@le-space/orbitdb-storage-bridge` + …) | What it is |
|
|
53
|
+
| --- | --- |
|
|
54
|
+
| `.` | `OrbitDBStorachaBridge` and the older helpers (`backupDatabase`, `restoreDatabase`, `analyzeBlocks`, `extractManifestCID`); Storacha itself loads only when a Storacha path is called |
|
|
55
|
+
| `/backup-car` | `createCARFromBlocks`, `readBlocksFromCAR`, `backupDatabaseCAR` — the CAR every backup is ([docs/CAR-BACKUP.md](docs/CAR-BACKUP.md)) |
|
|
56
|
+
| `/restore-cid` | `restoreFromCID`, `restoreFromBlocks`: a database back from a CID, or from blocks verified one by one |
|
|
57
|
+
| `/extract-blocks` | `extractDatabaseBlocks`, `bundleDatabases`: one database's blocks, or several databases' in one bundle |
|
|
58
|
+
| `/app-backup` | one sealed file for an application: `buildAppBackup`, `openAppBackup`, `restoreAppBackup`, `readAppBackupHeader`, `isAppBackup` |
|
|
59
|
+
| `/live-backup` | increments: `createLiveBackup`, `collectIncrement`, `readIncrement`, `mergeIncrements`, `restoreFromIncrements`, `joinIncrements` |
|
|
60
|
+
| `/dehydrate` | `dehydrate`, `hydrate`: a database where a second device finds it from a secret alone |
|
|
61
|
+
| `/pointer-ipns` | `publishPointer`, `resolvePointer`: the IPNS pointer `dehydrate` publishes, under a name derived from a seed |
|
|
62
|
+
| `/gateway-fetch` | `fetchFromGateways`: bytes by CID over HTTP, verified against the CID |
|
|
63
|
+
| `/peer-fetch` | `createPeerFetch`, `createGatewayFirstFetch`: bytes by CID from the peers that hold them, over libp2p |
|
|
64
|
+
| `/courier-sync` | `createCourierSync`: replication over any byte courier — a LoRa mesh, a QR relay, a file |
|
|
65
|
+
| `/memory-courier` | `createMemoryCourierPair`: the in-process courier for tests and demos |
|
|
66
|
+
| `/backends/types` | the contract: `defineBackend`, `BackendError`, the capability flags |
|
|
67
|
+
| `/backends/memory` | the in-process driver |
|
|
68
|
+
| `/backends/aleph` | `createAlephBackend`: ingest to Aleph's IPFS with no key; nothing kept, listed or deleted here |
|
|
69
|
+
| `/backends/aleph-pin` | `createAlephPin`, `createAlephAuthorizer`, `listAlephStores`, `waitForMessage`, `createAlephForget`, `forgetAlephStores`: what makes Aleph keep a file, and lets it go |
|
|
70
|
+
| `/backends/pinata` | Pinata: pin by CID or upload, with a scoped JWT; `remove()` by file id |
|
|
71
|
+
| `/backends/lighthouse` | Lighthouse: upload with an API key; `list()` and `remove()` |
|
|
72
|
+
| `/backends/storacha` | the Storacha driver; needs the optional peer `@storacha/client`, and a service that no longer answers |
|
|
73
|
+
| `/backends/mirror` | one backup to several backends |
|
|
74
|
+
| `/backends/encryption` | `withEncryption`: the service holds ciphertext |
|
|
75
|
+
| `/backends/choose` | `createBackendFromChoice`: a backend from a name and a key, for a page's form |
|
|
76
|
+
| `/backends/resolve` | `resolveBackend`: the options-to-backend step the older functions share |
|
|
77
|
+
| `/StorachaAuth.svelte`, `/StorachaIntegration.svelte`, `/storacha-backup`, `/components/*` | point into a `dist/` that no build produces; not importable ([docs/STORACHA-UI-HISTORY.md](docs/STORACHA-UI-HISTORY.md)) |
|
|
78
|
+
|
|
42
79
|
## Install
|
|
43
80
|
|
|
44
81
|
```bash
|
|
45
82
|
npm install @le-space/orbitdb-storage-bridge
|
|
46
83
|
```
|
|
47
84
|
|
|
85
|
+
That brings Aleph, Pinata, Lighthouse and the in-memory driver. The Storacha driver
|
|
86
|
+
(`backends/storacha`, the `OrbitDBStorachaBridge` class) needs `@storacha/client`, an optional
|
|
87
|
+
peer dependency since 0.22.0 — the service shut down on 2026-05-15, and 28 packages for a backend
|
|
88
|
+
nobody can reach were not worth every install. `npm install @storacha/client` puts them back.
|
|
89
|
+
|
|
48
90
|
## Quick start
|
|
49
91
|
|
|
50
92
|
The demos back up to Aleph, which accepts an upload without an account, so they run straight after
|
|
@@ -82,7 +124,7 @@ Galaxy A57 with the same key brought the database back and wrote to it. Source:
|
|
|
82
124
|
| [docs/DESIGN.md](docs/DESIGN.md) | the problem this solves, and how a backup and a restore actually work |
|
|
83
125
|
| [docs/STORAGE-BACKENDS.md](docs/STORAGE-BACKENDS.md) | every backend evaluated — prices, limits, and what has been verified against a live account |
|
|
84
126
|
| [docs/RECOVERY-ON-A-SECOND-DEVICE.md](docs/RECOVERY-ON-A-SECOND-DEVICE.md) | the passkey recovery procedure, step by step |
|
|
85
|
-
| [docs/CAR-BACKUP.md](docs/CAR-BACKUP.md) | CAR-
|
|
127
|
+
| [docs/CAR-BACKUP.md](docs/CAR-BACKUP.md) | the CAR as the unit of every backup, and the Storacha-era timestamped listing |
|
|
86
128
|
| [docs/APP-BACKUP.md](docs/APP-BACKUP.md) | an application's backup in one sealed file: several databases, a keyring header, kept on Aleph from the browser, restored by merging |
|
|
87
129
|
| [docs/LIVE-BACKUP.md](docs/LIVE-BACKUP.md) | increments between two full backups: what was written since the last one, shipped as one small CAR, with nobody clicking and no peer online |
|
|
88
130
|
| [SVELTE-COMPONENTS.md](SVELTE-COMPONENTS.md) | the browser components — older than this repository's copy of them; [docs/STORACHA-UI-HISTORY.md](docs/STORACHA-UI-HISTORY.md) records what each piece could do and where it went |
|
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* @fileoverview Making Aleph keep something
|
|
2
|
+
* @fileoverview Making Aleph keep something, and letting it go: the STORE
|
|
3
|
+
* message, the owner's `security` authorizations, listing by owner, waiting
|
|
4
|
+
* for a decision, and FORGET.
|
|
3
5
|
*
|
|
4
6
|
* `createAlephBackend` stores without a key and says plainly that it does not
|
|
5
7
|
* retain. This is the other half — and it is deliberately a separate module,
|
package/lib/backends/aleph.js
CHANGED
|
@@ -35,8 +35,8 @@
|
|
|
35
35
|
* STORE message with the `ipfs` engine, posted to `api2.aleph.im`. That needs a
|
|
36
36
|
* wallet and an SDK, so it is **injected rather than imported**: pass `pin` and
|
|
37
37
|
* the driver declares `pinByCid`; leave it out and the driver is honest about
|
|
38
|
-
* being ingest-only.
|
|
39
|
-
*
|
|
38
|
+
* being ingest-only. `./aleph-pin.js` is that implementation: `createAlephPin`
|
|
39
|
+
* builds and signs the STORE, and is what a caller passes as `pin`.
|
|
40
40
|
*
|
|
41
41
|
* @author @NiKrause
|
|
42
42
|
* @requires ./types.js - the backend contract
|
|
@@ -53,8 +53,9 @@ import { fetchFromGateways } from "../gateway-fetch.js";
|
|
|
53
53
|
* `dweb.link` and `ipfs.io` were the two fallbacks behind it until Protocol
|
|
54
54
|
* Labs retired them on 2026-09-21; they answer 429 with a `Sunset` header now.
|
|
55
55
|
* Nothing free was found to replace them that will serve an arbitrary CID, so
|
|
56
|
-
* this driver's retrieval depends on one host
|
|
57
|
-
*
|
|
56
|
+
* this driver's retrieval over HTTP depends on one host; `peer-fetch` (since
|
|
57
|
+
* 0.12.0) is the other path, over libp2p. A caller with its own gateway passes
|
|
58
|
+
* `gateways`.
|
|
58
59
|
*/
|
|
59
60
|
export const ALEPH_GATEWAYS = Object.freeze(["https://ipfs.aleph.cloud/ipfs"]);
|
|
60
61
|
|
|
@@ -103,14 +104,19 @@ export function createAlephBackend(options = {}) {
|
|
|
103
104
|
preservesInnerCids: true,
|
|
104
105
|
// No key exists to leak.
|
|
105
106
|
browserSafeAuth: true,
|
|
107
|
+
// Aleph's `security` aggregate (`createAlephAuthorizer` in ./aleph-pin.js)
|
|
108
|
+
// lets a paying account authorise another key for STORE on a channel, and
|
|
109
|
+
// revoke it — but never for a time, and the contract's `delegation` means
|
|
110
|
+
// scoped *and* time-bounded. So: no, with the grant documented there.
|
|
106
111
|
delegation: false,
|
|
107
112
|
// The IPFS host offers no listing, and the messages API needs the paying
|
|
108
113
|
// account's address, which this driver deliberately does not hold:
|
|
109
114
|
// `listAlephStores` in ./aleph-pin.js takes it.
|
|
110
115
|
listing: false,
|
|
111
|
-
// Unpinning is a FORGET message
|
|
112
|
-
//
|
|
113
|
-
//
|
|
116
|
+
// Unpinning is a FORGET message signed by the paying account:
|
|
117
|
+
// `createAlephForget` / `forgetAlephStores` in ./aleph-pin.js. `remove()`
|
|
118
|
+
// would need a key this driver does not hold, and claiming a deletion it
|
|
119
|
+
// cannot perform would be worse than saying no.
|
|
114
120
|
deletion: false,
|
|
115
121
|
minBlobSize: 0,
|
|
116
122
|
},
|
package/lib/backends/storacha.js
CHANGED
|
@@ -17,11 +17,8 @@
|
|
|
17
17
|
* @see {@link ../../docs/STORAGE-BACKENDS.md} for what replaced it
|
|
18
18
|
*/
|
|
19
19
|
|
|
20
|
-
import * as Client from "@storacha/client";
|
|
21
|
-
import { StoreMemory } from "@storacha/client/stores/memory";
|
|
22
|
-
import { Signer } from "@storacha/client/principal/ed25519";
|
|
23
|
-
import * as Proof from "@storacha/client/proof";
|
|
24
20
|
import { CID } from "multiformats/cid";
|
|
21
|
+
import { loadStorachaClient } from "../storacha-client.js";
|
|
25
22
|
import { defineBackend, handleId, BackendError } from "./types.js";
|
|
26
23
|
|
|
27
24
|
/**
|
|
@@ -61,6 +58,7 @@ async function resolveClient(options) {
|
|
|
61
58
|
);
|
|
62
59
|
}
|
|
63
60
|
|
|
61
|
+
const { Client, StoreMemory, Signer, Proof } = await loadStorachaClient();
|
|
64
62
|
const clientOptions = {
|
|
65
63
|
principal: Signer.parse(options.storachaKey),
|
|
66
64
|
store: new StoreMemory(),
|
package/lib/backends/types.js
CHANGED
|
@@ -30,7 +30,9 @@
|
|
|
30
30
|
* @property {boolean} browserSafeAuth - no shared secret has to reach the browser
|
|
31
31
|
* @property {boolean} delegation - access can be handed on, scoped and time-bounded
|
|
32
32
|
* @property {boolean} listing - `list()` is implemented
|
|
33
|
-
* @property {boolean} deletion - `remove()` is implemented
|
|
33
|
+
* @property {boolean} deletion - `remove()` by handle is implemented. A service whose
|
|
34
|
+
* release is a signed message (Aleph's FORGET) says false here and documents the message
|
|
35
|
+
* elsewhere
|
|
34
36
|
* @property {number} minBlobSize - smallest accepted upload in bytes; 0 when there is no minimum
|
|
35
37
|
*/
|
|
36
38
|
|
package/lib/backup-car.js
CHANGED
|
@@ -1,14 +1,12 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* CAR
|
|
2
|
+
* CAR backup and restore through any backend.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
* - More efficient upload (fewer files)
|
|
11
|
-
* - Better organization (grouped by timestamp)
|
|
4
|
+
* `createCARFromBlocks` and `readBlocksFromCAR` are the pair every other
|
|
5
|
+
* module builds on. `backupDatabaseCAR` packs one database into a CAR and
|
|
6
|
+
* uploads it with a metadata file through the backend `resolveBackend` picks
|
|
7
|
+
* from the options. `listAvailableBackups` and `restoreFromSpaceCAR` are
|
|
8
|
+
* Storacha-era: they need a backend that lists, and find a backup by reading
|
|
9
|
+
* every file in the listing. Works in Node.js and in a browser.
|
|
12
10
|
*/
|
|
13
11
|
|
|
14
12
|
import { CarWriter, CarReader } from "@ipld/car";
|
package/lib/backup-helpers.js
CHANGED
|
@@ -6,7 +6,7 @@ import { logger } from "./logger.js";
|
|
|
6
6
|
/**
|
|
7
7
|
* Generate backup prefix with timestamp
|
|
8
8
|
*
|
|
9
|
-
* @param {string} spaceName -
|
|
9
|
+
* @param {string} spaceName - a label kept in the metadata (a Storacha space, once)
|
|
10
10
|
* @returns {string} - Backup prefix including timestamp
|
|
11
11
|
*/
|
|
12
12
|
export function generateBackupPrefix(spaceName) {
|
package/lib/live-backup.js
CHANGED
|
@@ -27,8 +27,8 @@
|
|
|
27
27
|
* ## One upload, one STORE
|
|
28
28
|
*
|
|
29
29
|
* An increment is one CAR whose root is a dag-cbor manifest
|
|
30
|
-
* (`{ kind: "increment", v: 1, sequence, base, previous, metadata }`),
|
|
31
|
-
* single blob is self-describing. Every increment carries each database's
|
|
30
|
+
* (`{ kind: "increment", v: 1, sequence, base, previous, createdAt, metadata }`),
|
|
31
|
+
* so a single blob is self-describing. Every increment carries each database's
|
|
32
32
|
* manifest and access controller (a few hundred bytes) and the identity of
|
|
33
33
|
* every writer it has entries from, so a chain of increments restores on its
|
|
34
34
|
* own, with no base, if it is complete from the beginning; and so
|
|
@@ -430,7 +430,9 @@ function assertContiguous({ gaps, duplicates }, allowGaps) {
|
|
|
430
430
|
* @param {Function} [params.onProgress]
|
|
431
431
|
* @param {boolean} [params.allowGaps=false] - join a chain with missing or
|
|
432
432
|
* duplicate sequence numbers instead of refusing it
|
|
433
|
-
* @returns {Promise<{ blocks: number, databases: object[], sequences: number[] }>}
|
|
433
|
+
* @returns {Promise<{ blocks: number, databases: object[], sequences: number[], gaps: number[], duplicates: number[] }>}
|
|
434
|
+
* `gaps` and `duplicates`: the sequence numbers `mergeIncrements` found missing
|
|
435
|
+
* or twice — both empty unless `allowGaps` let such a chain through.
|
|
434
436
|
*/
|
|
435
437
|
export async function restoreFromIncrements(
|
|
436
438
|
orbitdb,
|
|
@@ -1,14 +1,17 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* Main entry: the Storacha-era bridge class and the block, CID and restore
|
|
3
|
+
* helpers it grew. New code imports the sub-paths (`./backup-car`,
|
|
4
|
+
* `./restore-cid`, `./app-backup`, `./live-backup`, the drivers under
|
|
5
|
+
* `./backends/`); this file stays for the class and for the helpers the
|
|
6
|
+
* sub-paths still share.
|
|
3
7
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
8
|
+
* `@storacha/client` is an optional peer dependency since 0.22.0: the service
|
|
9
|
+
* shut down on 2026-05-15, and a consumer that only ever reaches Aleph, Pinata
|
|
10
|
+
* or Lighthouse should not carry 28 packages for it. Nothing here imports it
|
|
11
|
+
* at load time; `initializeStorachaClient` loads it on first use and says
|
|
12
|
+
* what is missing when it is not installed.
|
|
6
13
|
*/
|
|
7
14
|
|
|
8
|
-
import * as Client from "@storacha/client";
|
|
9
|
-
import { StoreMemory } from "@storacha/client/stores/memory";
|
|
10
|
-
import { Signer } from "@storacha/client/principal/ed25519";
|
|
11
|
-
import * as Proof from "@storacha/client/proof";
|
|
12
15
|
import { BackendError } from "./backends/types.js";
|
|
13
16
|
import { CID } from "multiformats/cid";
|
|
14
17
|
import * as Block from "multiformats/block";
|
|
@@ -31,6 +34,7 @@ import { readBlockBytes } from "./block-bytes.js";
|
|
|
31
34
|
// every vintage look for it.
|
|
32
35
|
import { extractDatabaseBlocks } from "./extract-blocks.js";
|
|
33
36
|
import { resolveBackend } from "./backends/resolve.js";
|
|
37
|
+
import { loadStorachaClient } from "./storacha-client.js";
|
|
34
38
|
|
|
35
39
|
export { extractDatabaseBlocks };
|
|
36
40
|
|
|
@@ -112,6 +116,7 @@ async function initializeStorachaClient(
|
|
|
112
116
|
serviceConf,
|
|
113
117
|
receiptsEndpoint,
|
|
114
118
|
) {
|
|
119
|
+
const { Client, StoreMemory, Signer, Proof } = await loadStorachaClient();
|
|
115
120
|
const principal = Signer.parse(storachaKey);
|
|
116
121
|
const store = new StoreMemory();
|
|
117
122
|
const clientOptions = { principal, store };
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Storacha client, loaded when first needed and never at import time.
|
|
3
|
+
*
|
|
4
|
+
* `@storacha/client` is an optional peer dependency since 0.22.0. A static
|
|
5
|
+
* `import` of it anywhere under lib/ would break a consumer's bundle: Vite and
|
|
6
|
+
* Rollup follow dynamic imports into chunks and resolve their named imports at
|
|
7
|
+
* build time, so even a driver that is only ever `import()`ed — `resolve.js`
|
|
8
|
+
* reaches `backends/storacha.js` that way — fails the build of an application
|
|
9
|
+
* that never chose Storacha. So the client is imported here, dynamically, and
|
|
10
|
+
* nowhere else; without the package the Storacha paths fail at the call, with
|
|
11
|
+
* a message that names it. test/no-static-storacha-import.test.js keeps it so.
|
|
12
|
+
*
|
|
13
|
+
* @returns {Promise<{ Client: typeof import("@storacha/client"), StoreMemory: Function, Signer: { parse: Function }, Proof: { parse: Function } }>}
|
|
14
|
+
*/
|
|
15
|
+
export async function loadStorachaClient() {
|
|
16
|
+
try {
|
|
17
|
+
const [Client, { StoreMemory }, { Signer }, Proof] = await Promise.all([
|
|
18
|
+
import("@storacha/client"),
|
|
19
|
+
import("@storacha/client/stores/memory"),
|
|
20
|
+
import("@storacha/client/principal/ed25519"),
|
|
21
|
+
import("@storacha/client/proof"),
|
|
22
|
+
]);
|
|
23
|
+
return { Client, StoreMemory, Signer, Proof };
|
|
24
|
+
} catch (error) {
|
|
25
|
+
if (
|
|
26
|
+
error?.code === "ERR_MODULE_NOT_FOUND" ||
|
|
27
|
+
error?.code === "MODULE_NOT_FOUND"
|
|
28
|
+
) {
|
|
29
|
+
throw new Error(
|
|
30
|
+
"The Storacha backend needs @storacha/client, an optional peer dependency since 0.22.0: npm install @storacha/client",
|
|
31
|
+
{ cause: error },
|
|
32
|
+
);
|
|
33
|
+
}
|
|
34
|
+
throw error;
|
|
35
|
+
}
|
|
36
|
+
}
|
package/package.json
CHANGED
|
@@ -1,15 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@le-space/orbitdb-storage-bridge",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.22.1",
|
|
4
4
|
"description": "Back up, restore and replicate OrbitDB databases through pluggable storage backends, with hash and identity preservation",
|
|
5
5
|
"main": "lib/orbitdb-storacha-bridge.js",
|
|
6
6
|
"svelte": "dist/components/",
|
|
7
7
|
"type": "module",
|
|
8
8
|
"exports": {
|
|
9
|
-
".":
|
|
10
|
-
"types": "./lib/orbitdb-storacha-bridge.d.ts",
|
|
11
|
-
"default": "./lib/orbitdb-storacha-bridge.js"
|
|
12
|
-
},
|
|
9
|
+
".": "./lib/orbitdb-storacha-bridge.js",
|
|
13
10
|
"./backup-car": "./lib/backup-car.js",
|
|
14
11
|
"./courier-sync": "./lib/courier-sync.js",
|
|
15
12
|
"./pointer-ipns": "./lib/pointer-ipns.js",
|
|
@@ -58,7 +55,6 @@
|
|
|
58
55
|
},
|
|
59
56
|
"keywords": [
|
|
60
57
|
"orbitdb",
|
|
61
|
-
"storacha",
|
|
62
58
|
"filecoin",
|
|
63
59
|
"ipfs",
|
|
64
60
|
"backup",
|
|
@@ -73,6 +69,7 @@
|
|
|
73
69
|
"car",
|
|
74
70
|
"aleph",
|
|
75
71
|
"pinata",
|
|
72
|
+
"storacha",
|
|
76
73
|
"local-first"
|
|
77
74
|
],
|
|
78
75
|
"files": [
|
|
@@ -96,7 +93,6 @@
|
|
|
96
93
|
"@helia/unixfs": "^8.0.7",
|
|
97
94
|
"@ipld/car": "^5.4.1",
|
|
98
95
|
"@ipld/dag-cbor": "^9.0.6",
|
|
99
|
-
"@ipld/dag-ucan": "^3.4.5",
|
|
100
96
|
"@libp2p/bootstrap": "^12.0.27",
|
|
101
97
|
"@libp2p/crypto": "^5.1.21",
|
|
102
98
|
"@libp2p/gossipsub": "^16.1.0",
|
|
@@ -107,12 +103,9 @@
|
|
|
107
103
|
"@libp2p/tcp": "^11.0.28",
|
|
108
104
|
"@orbitdb/core": "^4.0.0",
|
|
109
105
|
"@scure/bip39": "^1.3.0",
|
|
110
|
-
"@storacha/capabilities": "^2.0.0",
|
|
111
|
-
"@storacha/client": "^2.0.0",
|
|
112
106
|
"blockstore-level": "^4.0.1",
|
|
113
107
|
"cbor-web": "^10.0.11",
|
|
114
108
|
"datastore-level": "^13.0.1",
|
|
115
|
-
"dotenv": "^17.2.1",
|
|
116
109
|
"helia": "^7.1.15",
|
|
117
110
|
"libp2p": "^3.3.6",
|
|
118
111
|
"multiformats": "^14.0.5"
|
|
@@ -120,10 +113,13 @@
|
|
|
120
113
|
"devDependencies": {
|
|
121
114
|
"@eslint/js": "^10.0.1",
|
|
122
115
|
"@ibm/plex": "^6.4.1",
|
|
116
|
+
"@ipld/dag-ucan": "^3.4.5",
|
|
123
117
|
"@jest/globals": "^30.5.1",
|
|
124
118
|
"@le-space/ucanto-principal": "^9.1.1",
|
|
125
119
|
"@libp2p/websockets": "^10.1.17",
|
|
126
120
|
"@orbitdb/identity-provider-did": "^1.0.2",
|
|
121
|
+
"@storacha/capabilities": "^2.0.0",
|
|
122
|
+
"@storacha/client": "^2.0.0",
|
|
127
123
|
"@storacha/did-mailto": "^1.0.1",
|
|
128
124
|
"@storacha/upload-api": "^3.0.0",
|
|
129
125
|
"@types/jest": "^30.0.0",
|
|
@@ -135,6 +131,7 @@
|
|
|
135
131
|
"@web3-storage/sigv4": "^1.0.2",
|
|
136
132
|
"carbon-components-svelte": "^0.89.7",
|
|
137
133
|
"carbon-icons-svelte": "^12.17.0",
|
|
134
|
+
"dotenv": "^17.2.1",
|
|
138
135
|
"eslint": "^10.10.0",
|
|
139
136
|
"jest": "^30.5.1",
|
|
140
137
|
"key-did-provider-ed25519": "^4.0.2",
|
|
@@ -145,7 +142,8 @@
|
|
|
145
142
|
},
|
|
146
143
|
"peerDependencies": {
|
|
147
144
|
"lucide-svelte": ">=0.400.0 <1.0.0",
|
|
148
|
-
"svelte": "^3.0.0 || ^4.0.0 || ^5.0.0"
|
|
145
|
+
"svelte": "^3.0.0 || ^4.0.0 || ^5.0.0",
|
|
146
|
+
"@storacha/client": "^2.0.0"
|
|
149
147
|
},
|
|
150
148
|
"engines": {
|
|
151
149
|
"node": ">=22.0.0"
|
|
@@ -176,5 +174,10 @@
|
|
|
176
174
|
},
|
|
177
175
|
"overrides": {
|
|
178
176
|
"test-exclude": "^8.0.0"
|
|
177
|
+
},
|
|
178
|
+
"peerDependenciesMeta": {
|
|
179
|
+
"@storacha/client": {
|
|
180
|
+
"optional": true
|
|
181
|
+
}
|
|
179
182
|
}
|
|
180
183
|
}
|
package/lib/backup.js
DELETED
|
@@ -1,249 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* OrbitDB database backup with timestamps and error handling
|
|
3
|
-
* NOTE: This file is a placeholder/example and is incomplete
|
|
4
|
-
*/
|
|
5
|
-
|
|
6
|
-
/* eslint-disable no-undef, no-unused-vars */
|
|
7
|
-
import { Readable } from "stream";
|
|
8
|
-
import { CarReader } from "@ipld/car";
|
|
9
|
-
import * as Signer from "@storacha/client/principal/ed25519";
|
|
10
|
-
import { createWritableCarReader } from "@storacha/client/utils";
|
|
11
|
-
import { logger } from "./logger.js";
|
|
12
|
-
import {
|
|
13
|
-
generateBackupPrefix,
|
|
14
|
-
getBackupFilenames,
|
|
15
|
-
isValidMetadata,
|
|
16
|
-
findLatestBackup,
|
|
17
|
-
} from "./backup-helpers.js";
|
|
18
|
-
|
|
19
|
-
const DEFAULT_OPTIONS = {
|
|
20
|
-
verbose: false,
|
|
21
|
-
};
|
|
22
|
-
|
|
23
|
-
/**
|
|
24
|
-
* Backup an OrbitDB database with timestamps and error handling
|
|
25
|
-
*
|
|
26
|
-
* @param {Object} orbitdb - OrbitDB instance
|
|
27
|
-
* @param {string} databaseAddress - Database address or name
|
|
28
|
-
* @param {Object} options - Backup options
|
|
29
|
-
* @returns {Promise<Object>} - Backup result
|
|
30
|
-
*/
|
|
31
|
-
export async function backupDatabase(orbitdb, databaseAddress, options = {}) {
|
|
32
|
-
const config = { ...DEFAULT_OPTIONS, ...options };
|
|
33
|
-
const { verbose } = config;
|
|
34
|
-
const { spaceName } = config;
|
|
35
|
-
const eventEmitter = options.eventEmitter;
|
|
36
|
-
const logDebug = (message) => {
|
|
37
|
-
if (verbose) {
|
|
38
|
-
logger.debug(message);
|
|
39
|
-
}
|
|
40
|
-
};
|
|
41
|
-
|
|
42
|
-
logDebug("🚀 Starting OrbitDB Database Backup");
|
|
43
|
-
logDebug(`📍 Database: ${databaseAddress}`);
|
|
44
|
-
|
|
45
|
-
try {
|
|
46
|
-
// Open database and extract blocks
|
|
47
|
-
const database = await orbitdb.open(databaseAddress, options.dbConfig);
|
|
48
|
-
const { blocks, blockSources, manifestCID } = await extractDatabaseBlocks(
|
|
49
|
-
database,
|
|
50
|
-
{ logEntriesOnly: false },
|
|
51
|
-
);
|
|
52
|
-
|
|
53
|
-
// Generate timestamped backup paths
|
|
54
|
-
const backupPrefix = generateBackupPrefix(spaceName);
|
|
55
|
-
const backupFiles = getBackupFilenames(backupPrefix);
|
|
56
|
-
|
|
57
|
-
// Create metadata
|
|
58
|
-
const metadata = {
|
|
59
|
-
version: "1.0",
|
|
60
|
-
timestamp: Date.now(),
|
|
61
|
-
databaseCount: 1,
|
|
62
|
-
totalEntries: blocks.size,
|
|
63
|
-
databases: [
|
|
64
|
-
{
|
|
65
|
-
root: database.address.root,
|
|
66
|
-
path: database.address.path,
|
|
67
|
-
},
|
|
68
|
-
],
|
|
69
|
-
};
|
|
70
|
-
|
|
71
|
-
// Validate metadata structure
|
|
72
|
-
if (!isValidMetadata(metadata)) {
|
|
73
|
-
throw new Error("Invalid metadata structure");
|
|
74
|
-
}
|
|
75
|
-
|
|
76
|
-
// Write metadata with error handling
|
|
77
|
-
try {
|
|
78
|
-
await Signer.writeFile(
|
|
79
|
-
backupFiles.metadata,
|
|
80
|
-
JSON.stringify(metadata, null, 2),
|
|
81
|
-
);
|
|
82
|
-
} catch (error) {
|
|
83
|
-
throw new Error(`Failed to write backup metadata: ${error.message}`, { cause: error });
|
|
84
|
-
}
|
|
85
|
-
|
|
86
|
-
// Write blocks with error handling
|
|
87
|
-
try {
|
|
88
|
-
// Create CAR storage and add blocks
|
|
89
|
-
const storage = await CARStorage({
|
|
90
|
-
path: ".",
|
|
91
|
-
name: "backup-temp",
|
|
92
|
-
autoFlush: false,
|
|
93
|
-
});
|
|
94
|
-
|
|
95
|
-
for (const [key, value] of blocks) {
|
|
96
|
-
await storage.put(key, value);
|
|
97
|
-
}
|
|
98
|
-
|
|
99
|
-
await storage.persist();
|
|
100
|
-
const reader = await CarReader.fromIterable(storage.iterator());
|
|
101
|
-
const stream = Readable.from(reader.blocks());
|
|
102
|
-
|
|
103
|
-
await stream.pipe(
|
|
104
|
-
await createWritableCarReader({
|
|
105
|
-
name: backupFiles.blocks,
|
|
106
|
-
comment: `OrbitDB backup blocks (created at ${new Date().toISOString()})`,
|
|
107
|
-
space: spaceName,
|
|
108
|
-
}),
|
|
109
|
-
);
|
|
110
|
-
|
|
111
|
-
// Clean up temp storage
|
|
112
|
-
await storage.close();
|
|
113
|
-
await storage.clear();
|
|
114
|
-
} catch (error) {
|
|
115
|
-
// Try to clean up failed metadata
|
|
116
|
-
try {
|
|
117
|
-
await Signer.rm(backupFiles.metadata);
|
|
118
|
-
} catch (cleanupError) {
|
|
119
|
-
logDebug(
|
|
120
|
-
`Failed to clean up metadata after error: ${cleanupError.message}`,
|
|
121
|
-
);
|
|
122
|
-
}
|
|
123
|
-
throw new Error(`Failed to write backup blocks: ${error.message}`, { cause: error });
|
|
124
|
-
}
|
|
125
|
-
|
|
126
|
-
// Return success with file info
|
|
127
|
-
return {
|
|
128
|
-
success: true,
|
|
129
|
-
manifestCID,
|
|
130
|
-
databaseAddress: database.address,
|
|
131
|
-
databaseName: database.name,
|
|
132
|
-
blocksTotal: blocks.size,
|
|
133
|
-
blocksUploaded: blocks.size,
|
|
134
|
-
blockSummary: blockSources,
|
|
135
|
-
backupFiles,
|
|
136
|
-
};
|
|
137
|
-
} catch (error) {
|
|
138
|
-
return {
|
|
139
|
-
success: false,
|
|
140
|
-
error: error.message,
|
|
141
|
-
};
|
|
142
|
-
}
|
|
143
|
-
}
|
|
144
|
-
|
|
145
|
-
/**
|
|
146
|
-
* Restore from the latest valid backup in a space
|
|
147
|
-
*
|
|
148
|
-
* @param {Object} orbitdb - OrbitDB instance
|
|
149
|
-
* @param {Object} options - Restore options
|
|
150
|
-
* @returns {Promise<Object>} - Restore result
|
|
151
|
-
*/
|
|
152
|
-
export async function restoreFromSpace(orbitdb, options = {}) {
|
|
153
|
-
const config = { ...DEFAULT_OPTIONS, ...options };
|
|
154
|
-
const { verbose } = config;
|
|
155
|
-
const { spaceName } = config;
|
|
156
|
-
const logDebug = (message) => {
|
|
157
|
-
if (verbose) {
|
|
158
|
-
logger.debug(message);
|
|
159
|
-
}
|
|
160
|
-
};
|
|
161
|
-
|
|
162
|
-
logDebug("🔄 Starting OrbitDB Restore");
|
|
163
|
-
|
|
164
|
-
try {
|
|
165
|
-
// Find latest valid backup
|
|
166
|
-
const spaceFiles = await listStorachaSpaceFiles(config);
|
|
167
|
-
const latestBackup = findLatestBackup(spaceFiles, {
|
|
168
|
-
verbose,
|
|
169
|
-
});
|
|
170
|
-
|
|
171
|
-
if (!latestBackup) {
|
|
172
|
-
throw new Error("No valid backup found in space");
|
|
173
|
-
}
|
|
174
|
-
|
|
175
|
-
// Read and validate metadata
|
|
176
|
-
let metadata;
|
|
177
|
-
try {
|
|
178
|
-
const metadataJson = await Signer.readFile(
|
|
179
|
-
`${spaceName}/${latestBackup.metadata}`,
|
|
180
|
-
);
|
|
181
|
-
metadata = JSON.parse(metadataJson);
|
|
182
|
-
if (!isValidMetadata(metadata)) {
|
|
183
|
-
throw new Error("Invalid backup metadata structure");
|
|
184
|
-
}
|
|
185
|
-
} catch (error) {
|
|
186
|
-
throw new Error(`Failed to read/validate metadata: ${error.message}`, { cause: error });
|
|
187
|
-
}
|
|
188
|
-
|
|
189
|
-
// Create storage and load blocks
|
|
190
|
-
const storage = await CARStorage({
|
|
191
|
-
path: ".",
|
|
192
|
-
name: "restore-temp",
|
|
193
|
-
autoFlush: false,
|
|
194
|
-
});
|
|
195
|
-
|
|
196
|
-
try {
|
|
197
|
-
// Get blocks stream
|
|
198
|
-
const carStream = await Signer.readStream(
|
|
199
|
-
`${spaceName}/${latestBackup.blocks}`,
|
|
200
|
-
);
|
|
201
|
-
const reader = await fromReadableStream(carStream);
|
|
202
|
-
|
|
203
|
-
// Load blocks with validation
|
|
204
|
-
let validBlocks = 0;
|
|
205
|
-
for await (const block of reader.blocks()) {
|
|
206
|
-
try {
|
|
207
|
-
await storage.put(block.cid.toString(), block.bytes);
|
|
208
|
-
validBlocks++;
|
|
209
|
-
} catch (blockError) {
|
|
210
|
-
logDebug(`⚠️ Failed to restore block: ${blockError.message}`);
|
|
211
|
-
}
|
|
212
|
-
}
|
|
213
|
-
|
|
214
|
-
if (validBlocks === 0) {
|
|
215
|
-
throw new Error("No valid blocks found in backup");
|
|
216
|
-
}
|
|
217
|
-
|
|
218
|
-
// Open database using metadata
|
|
219
|
-
const databaseAddress = `/orbitdb/${metadata.databases[0].root}`;
|
|
220
|
-
const database = await orbitdb.open(databaseAddress);
|
|
221
|
-
|
|
222
|
-
// Replace storage and load entries
|
|
223
|
-
await database._index.replaceStorage(storage);
|
|
224
|
-
await database.load();
|
|
225
|
-
|
|
226
|
-
const entries = await database.all();
|
|
227
|
-
|
|
228
|
-
return {
|
|
229
|
-
success: true,
|
|
230
|
-
database,
|
|
231
|
-
databaseAddress,
|
|
232
|
-
entriesRecovered: entries.length,
|
|
233
|
-
blocksRestored: validBlocks,
|
|
234
|
-
backupUsed: latestBackup,
|
|
235
|
-
};
|
|
236
|
-
} catch (error) {
|
|
237
|
-
throw new Error(`Failed to restore blocks: ${error.message}`, { cause: error });
|
|
238
|
-
} finally {
|
|
239
|
-
// Clean up temp storage
|
|
240
|
-
await storage.close();
|
|
241
|
-
await storage.clear();
|
|
242
|
-
}
|
|
243
|
-
} catch (error) {
|
|
244
|
-
return {
|
|
245
|
-
success: false,
|
|
246
|
-
error: error.message,
|
|
247
|
-
};
|
|
248
|
-
}
|
|
249
|
-
}
|