@le-space/orbitdb-storage-bridge 0.10.0

package/lib/backup-helpers.js

@@ -0,0 +1,87 @@
+/**
+ * Helper functions for timestamped backup feature
+ */
+import { logger } from "./logger.js";
+
+/**
+ * Generate backup prefix with timestamp
+ *
+ * @param {string} spaceName - Name of the Storacha space
+ * @returns {string} - Backup prefix including timestamp
+ */
+export function generateBackupPrefix(spaceName) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  return `${spaceName}/backup-${timestamp}`;
+}
+
+// `getBackupFilenames` and `isValidMetadata` live in `backup-metadata.js`,
+// which imports nothing — so a browser consumer can read a backup without
+// pulling a logging framework in behind a predicate (issue #58). Re-exported
+// here so every existing importer keeps working.
+export { getBackupFilenames, isValidMetadata } from "./backup-metadata.js";
+
+/**
+ * Find the latest valid backup in a space
+ *
+ * @param {Array} spaceFiles - List of files in the space
+ * @param {Object} options - Options
+ * @param {Function} options.onWarning - Warning callback
+ * @returns {Object|null} - Latest valid backup or null
+ */
+export function findLatestBackup(spaceFiles, options = {}) {
+  const { onWarning, verbose = false } = options;
+  const warn =
+    onWarning ||
+    (verbose
+      ? (message) => {
+          logger.debug(message);
+        }
+      : () => {});
+  const filenames = spaceFiles.map((f) => f.root.toString());
+
+  // Group files by full backup path (preserving directory structure)
+  const backupGroups = new Map();
+  for (const file of filenames) {
+    // Match pattern: (optional-prefix/)backup-(timestamp)-(metadata.json|blocks.car)
+    const match = file.match(/^(.*)backup-(.*?)-(metadata\.json|blocks\.car)$/);
+    if (match) {
+      const [, prefix, timestamp, type] = match;
+      const backupKey = `${prefix}backup-${timestamp}`;
+
+      if (!backupGroups.has(backupKey)) {
+        backupGroups.set(backupKey, { files: new Set(), timestamp, prefix });
+      }
+      backupGroups.get(backupKey).files.add(type);
+    }
+  }
+
+  // Find complete and valid backups
+  const completeBackups = Array.from(backupGroups.entries())
+    .filter(([backupKey, { files }]) => {
+      const isComplete = files.has("metadata.json") && files.has("blocks.car");
+      if (!isComplete) {
+        warn(`⚠️ Incomplete backup found: ${backupKey}-*`);
+        files.forEach((file) => {
+          warn(`   Orphaned file: ${backupKey}-${file}`);
+        });
+      }
+      return isComplete;
+    })
+    .sort((a, b) => b[1].timestamp.localeCompare(a[1].timestamp)); // Sort descending by timestamp
+
+  if (completeBackups.length === 0) {
+    if (backupGroups.size > 0) {
+      warn(
+        "⚠️ No complete backup sets found (missing metadata or blocks files)",
+      );
+    }
+    return null;
+  }
+
+  const [backupKey, { timestamp }] = completeBackups[0];
+  return {
+    metadata: `${backupKey}-metadata.json`,
+    blocks: `${backupKey}-blocks.car`,
+    timestamp: timestamp,
+  };
+}

package/lib/backup-metadata.js

@@ -0,0 +1,40 @@
+/**
+ * What a backup's metadata is, with no dependencies at all.
+ *
+ * Split out of `backup-helpers.js` for one reason: that module logs, so
+ * importing a *predicate* from it pulls in the logging framework and, through
+ * it, `@libp2p/logger`. Fine in Node; measurable in a browser bundle, where
+ * `restore-cid.js` exists precisely so that reading a backup costs almost
+ * nothing (issue #58).
+ *
+ * Nothing here imports anything. That is the point, and it is worth keeping
+ * true: anything added below that needs a logger belongs in `backup-helpers.js`
+ * instead.
+ */
+
+/** Names are `<prefix>-metadata.json` and `<prefix>-blocks.car`. */
+export function getBackupFilenames(prefix) {
+  return { metadata: `${prefix}-metadata.json`, blocks: `${prefix}-blocks.car` };
+}
+
+/**
+ * Whether this is metadata we can act on.
+ *
+ * Accepts both shapes deliberately: the pre-CAR `{ root, path }` databases and
+ * the CAR-era `{ address, manifestCID }` ones. A reader that only handles one
+ * of them checks for its own fields after this, so that "not a backup" and
+ * "a backup of the other kind" stay different answers.
+ */
+export function isValidMetadata(metadata) {
+  if (
+    !metadata ||
+    typeof metadata.version !== "string" ||
+    typeof metadata.timestamp !== "number" ||
+    !Array.isArray(metadata.databases)
+  ) {
+    return false;
+  }
+  return metadata.databases.every(
+    (db) => Boolean(db?.root && db?.path) || Boolean(db?.address && db?.manifestCID),
+  );
+}

package/lib/backup.js

@@ -0,0 +1,249 @@
+/**
+ * OrbitDB database backup with timestamps and error handling
+ * NOTE: This file is a placeholder/example and is incomplete
+ */
+
+/* eslint-disable no-undef, no-unused-vars */
+import { Readable } from "stream";
+import { CarReader } from "@ipld/car";
+import * as Signer from "@storacha/client/principal/ed25519";
+import { createWritableCarReader } from "@storacha/client/utils";
+import { logger } from "./logger.js";
+import {
+  generateBackupPrefix,
+  getBackupFilenames,
+  isValidMetadata,
+  findLatestBackup,
+} from "./backup-helpers.js";
+
+const DEFAULT_OPTIONS = {
+  verbose: false,
+};
+
+/**
+ * Backup an OrbitDB database with timestamps and error handling
+ *
+ * @param {Object} orbitdb - OrbitDB instance
+ * @param {string} databaseAddress - Database address or name
+ * @param {Object} options - Backup options
+ * @returns {Promise<Object>} - Backup result
+ */
+export async function backupDatabase(orbitdb, databaseAddress, options = {}) {
+  const config = { ...DEFAULT_OPTIONS, ...options };
+  const { verbose } = config;
+  const { spaceName } = config;
+  const eventEmitter = options.eventEmitter;
+  const logDebug = (message) => {
+    if (verbose) {
+      logger.debug(message);
+    }
+  };
+
+  logDebug("🚀 Starting OrbitDB Database Backup");
+  logDebug(`📍 Database: ${databaseAddress}`);
+
+  try {
+    // Open database and extract blocks
+    const database = await orbitdb.open(databaseAddress, options.dbConfig);
+    const { blocks, blockSources, manifestCID } = await extractDatabaseBlocks(
+      database,
+      { logEntriesOnly: false },
+    );
+
+    // Generate timestamped backup paths
+    const backupPrefix = generateBackupPrefix(spaceName);
+    const backupFiles = getBackupFilenames(backupPrefix);
+
+    // Create metadata
+    const metadata = {
+      version: "1.0",
+      timestamp: Date.now(),
+      databaseCount: 1,
+      totalEntries: blocks.size,
+      databases: [
+        {
+          root: database.address.root,
+          path: database.address.path,
+        },
+      ],
+    };
+
+    // Validate metadata structure
+    if (!isValidMetadata(metadata)) {
+      throw new Error("Invalid metadata structure");
+    }
+
+    // Write metadata with error handling
+    try {
+      await Signer.writeFile(
+        backupFiles.metadata,
+        JSON.stringify(metadata, null, 2),
+      );
+    } catch (error) {
+      throw new Error(`Failed to write backup metadata: ${error.message}`, { cause: error });
+    }
+
+    // Write blocks with error handling
+    try {
+      // Create CAR storage and add blocks
+      const storage = await CARStorage({
+        path: ".",
+        name: "backup-temp",
+        autoFlush: false,
+      });
+
+      for (const [key, value] of blocks) {
+        await storage.put(key, value);
+      }
+
+      await storage.persist();
+      const reader = await CarReader.fromIterable(storage.iterator());
+      const stream = Readable.from(reader.blocks());
+
+      await stream.pipe(
+        await createWritableCarReader({
+          name: backupFiles.blocks,
+          comment: `OrbitDB backup blocks (created at ${new Date().toISOString()})`,
+          space: spaceName,
+        }),
+      );
+
+      // Clean up temp storage
+      await storage.close();
+      await storage.clear();
+    } catch (error) {
+      // Try to clean up failed metadata
+      try {
+        await Signer.rm(backupFiles.metadata);
+      } catch (cleanupError) {
+        logDebug(
+          `Failed to clean up metadata after error: ${cleanupError.message}`,
+        );
+      }
+      throw new Error(`Failed to write backup blocks: ${error.message}`, { cause: error });
+    }
+
+    // Return success with file info
+    return {
+      success: true,
+      manifestCID,
+      databaseAddress: database.address,
+      databaseName: database.name,
+      blocksTotal: blocks.size,
+      blocksUploaded: blocks.size,
+      blockSummary: blockSources,
+      backupFiles,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Restore from the latest valid backup in a space
+ *
+ * @param {Object} orbitdb - OrbitDB instance
+ * @param {Object} options - Restore options
+ * @returns {Promise<Object>} - Restore result
+ */
+export async function restoreFromSpace(orbitdb, options = {}) {
+  const config = { ...DEFAULT_OPTIONS, ...options };
+  const { verbose } = config;
+  const { spaceName } = config;
+  const logDebug = (message) => {
+    if (verbose) {
+      logger.debug(message);
+    }
+  };
+
+  logDebug("🔄 Starting OrbitDB Restore");
+
+  try {
+    // Find latest valid backup
+    const spaceFiles = await listStorachaSpaceFiles(config);
+    const latestBackup = findLatestBackup(spaceFiles, {
+      verbose,
+    });
+
+    if (!latestBackup) {
+      throw new Error("No valid backup found in space");
+    }
+
+    // Read and validate metadata
+    let metadata;
+    try {
+      const metadataJson = await Signer.readFile(
+        `${spaceName}/${latestBackup.metadata}`,
+      );
+      metadata = JSON.parse(metadataJson);
+      if (!isValidMetadata(metadata)) {
+        throw new Error("Invalid backup metadata structure");
+      }
+    } catch (error) {
+      throw new Error(`Failed to read/validate metadata: ${error.message}`, { cause: error });
+    }
+
+    // Create storage and load blocks
+    const storage = await CARStorage({
+      path: ".",
+      name: "restore-temp",
+      autoFlush: false,
+    });
+
+    try {
+      // Get blocks stream
+      const carStream = await Signer.readStream(
+        `${spaceName}/${latestBackup.blocks}`,
+      );
+      const reader = await fromReadableStream(carStream);
+
+      // Load blocks with validation
+      let validBlocks = 0;
+      for await (const block of reader.blocks()) {
+        try {
+          await storage.put(block.cid.toString(), block.bytes);
+          validBlocks++;
+        } catch (blockError) {
+          logDebug(`⚠️ Failed to restore block: ${blockError.message}`);
+        }
+      }
+
+      if (validBlocks === 0) {
+        throw new Error("No valid blocks found in backup");
+      }
+
+      // Open database using metadata
+      const databaseAddress = `/orbitdb/${metadata.databases[0].root}`;
+      const database = await orbitdb.open(databaseAddress);
+
+      // Replace storage and load entries
+      await database._index.replaceStorage(storage);
+      await database.load();
+
+      const entries = await database.all();
+
+      return {
+        success: true,
+        database,
+        databaseAddress,
+        entriesRecovered: entries.length,
+        blocksRestored: validBlocks,
+        backupUsed: latestBackup,
+      };
+    } catch (error) {
+      throw new Error(`Failed to restore blocks: ${error.message}`, { cause: error });
+    } finally {
+      // Clean up temp storage
+      await storage.close();
+      await storage.clear();
+    }
+  } catch (error) {
+    return {
+      success: false,
+      error: error.message,
+    };
+  }
+}

package/lib/block-bytes.js

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Read a block's bytes from any Helia blockstore.
+ *
+ * `interface-blockstore` 7 — what Helia 6 and later hand out — streams a block
+ * in chunks: `blockstore.get(cid)` returns an async iterable rather than a
+ * promise of the bytes. Code written for the earlier interface still runs,
+ * `await`s the iterable, and passes an object where bytes belong; the decode
+ * after it fails far from the cause. This reads both.
+ *
+ * Imports nothing, so the light restore path can use it without pulling in a
+ * node stack.
+ */
+
+/**
+ * @param {{ get: (cid: any, options?: object) => any }} blockstore
+ * @param {any} cid
+ * @param {object} [options] - passed through, e.g. `{ signal }`
+ * @returns {Promise<Uint8Array>}
+ */
+export async function readBlockBytes(blockstore, cid, options) {
+  const result = blockstore.get(cid, options);
+  if (result == null || typeof result[Symbol.asyncIterator] !== "function") {
+    return await result;
+  }
+  const chunks = [];
+  let length = 0;
+  for await (const chunk of result) {
+    chunks.push(chunk);
+    length += chunk.length;
+  }
+  if (chunks.length === 1) return chunks[0];
+  const bytes = new Uint8Array(length);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return bytes;
+}