@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 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-based timestamped backups |
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: the STORE message, and nothing else.
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,
@@ -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. `relay-button`'s `@le-space/browser` already speaks that
39
- * API, which is the implementation this hook is shaped for.
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 until the peer path in #112
57
- * lands. A caller with its own gateway passes `gateways`.
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, so it belongs with `pin` rather than
112
- // here. Claiming deletion the driver cannot perform would be worse than
113
- // saying no.
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
  },
@@ -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(),
@@ -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-based OrbitDB Backup with Timestamps
2
+ * CAR backup and restore through any backend.
3
3
  *
4
- * Alternative implementation using CAR (Content Addressable Archive) files
5
- * for efficient timestamped backups. Works in both Node.js and browser environments.
6
- *
7
- * This is backward compatible with the existing individual block upload approach.
8
- * Use this when you want:
9
- * - Timestamped backups (multiple backup points)
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";
@@ -6,7 +6,7 @@ import { logger } from "./logger.js";
6
6
  /**
7
7
  * Generate backup prefix with timestamp
8
8
  *
9
- * @param {string} spaceName - Name of the Storacha space
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) {
@@ -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 }`), so a
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
- * OrbitDB Storacha Bridge - Main Library
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
- * Provides complete OrbitDB database backup and restoration via Storacha/Filecoin
5
- * with 100% hash preservation and identity recovery.
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.21.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
- }