holosphere 1.1.20 → 2.0.0-alpha1

package/src/storage/migration.js

@@ -0,0 +1,338 @@
+/**
+ * Migration Tool for HoloSphere Storage Backends
+ *
+ * Enables data migration between different storage backends:
+ * - Export data from any backend to a portable format
+ * - Import data to any backend from the portable format
+ * - Direct migration between backends
+ * - Validation of migrated data
+ */
+
+import { BackendFactory } from './backend-factory.js';
+
+/**
+ * Portable data bundle format
+ * @typedef {Object} DataBundle
+ * @property {string} version - Bundle format version
+ * @property {string} exportedAt - ISO timestamp
+ * @property {string} sourceType - Source backend type
+ * @property {string} sourceKey - Source public key
+ * @property {number} recordCount - Number of records
+ * @property {Object[]} records - Array of data records
+ */
+
+/**
+ * Migration record format
+ * @typedef {Object} MigrationRecord
+ * @property {string} path - Storage path
+ * @property {Object} data - Record data
+ * @property {number} timestamp - Creation timestamp
+ * @property {string} [author] - Author public key
+ */
+
+/**
+ * Migration results
+ * @typedef {Object} MigrationResults
+ * @property {number} success - Successfully migrated records
+ * @property {number} failed - Failed records
+ * @property {Object[]} errors - Error details
+ */
+
+export class MigrationTool {
+  constructor() {
+    this.sourceBackend = null;
+    this.targetBackend = null;
+  }
+
+  /**
+   * Configure source backend
+   * @param {string} type - Backend type: 'nostr' | 'gundb' | 'activitypub'
+   * @param {Object} config - Backend configuration
+   * @returns {Promise<void>}
+   */
+  async setSource(type, config) {
+    this.sourceBackend = await BackendFactory.create(type, config);
+  }
+
+  /**
+   * Configure target backend
+   * @param {string} type - Backend type: 'nostr' | 'gundb' | 'activitypub'
+   * @param {Object} config - Backend configuration
+   * @returns {Promise<void>}
+   */
+  async setTarget(type, config) {
+    this.targetBackend = await BackendFactory.create(type, config);
+  }
+
+  /**
+   * Use an existing backend instance as source
+   * @param {StorageBackend} backend - Backend instance
+   */
+  useSourceBackend(backend) {
+    this.sourceBackend = backend;
+  }
+
+  /**
+   * Use an existing backend instance as target
+   * @param {StorageBackend} backend - Backend instance
+   */
+  useTargetBackend(backend) {
+    this.targetBackend = backend;
+  }
+
+  /**
+   * Export data from source to portable format
+   * @param {string} [pathPrefix] - Optional path prefix filter
+   * @returns {Promise<DataBundle>} Exportable data bundle
+   */
+  async export(pathPrefix = '') {
+    if (!this.sourceBackend) {
+      throw new Error('Source backend not configured. Call setSource() first.');
+    }
+
+    console.log(`Exporting data from ${this.sourceBackend.getStatus().type}...`);
+
+    const records = await this.sourceBackend.exportData(pathPrefix);
+    const status = this.sourceBackend.getStatus();
+
+    const bundle = {
+      version: '1.0',
+      exportedAt: new Date().toISOString(),
+      sourceType: status.type,
+      sourceKey: status.publicKey || 'unknown',
+      pathPrefix: pathPrefix || '',
+      recordCount: records.length,
+      records,
+    };
+
+    console.log(`Exported ${records.length} records.`);
+    return bundle;
+  }
+
+  /**
+   * Import data to target backend
+   * @param {DataBundle} bundle - Data bundle from export()
+   * @param {Object} [options] - Import options
+   * @param {boolean} [options.overwrite] - Overwrite existing data
+   * @param {boolean} [options.dryRun] - Simulate without writing
+   * @param {Function} [options.onProgress] - Progress callback (current, total)
+   * @returns {Promise<MigrationResults>} Import results
+   */
+  async import(bundle, options = {}) {
+    if (!this.targetBackend) {
+      throw new Error('Target backend not configured. Call setTarget() first.');
+    }
+
+    if (!bundle || !bundle.records) {
+      throw new Error('Invalid bundle format. Expected { version, records }');
+    }
+
+    console.log(`Importing ${bundle.recordCount} records to ${this.targetBackend.getStatus().type}...`);
+
+    if (options.dryRun) {
+      console.log('Dry run mode - no data will be written.');
+      return {
+        dryRun: true,
+        wouldImport: bundle.recordCount,
+        records: bundle.records.map(r => r.path),
+      };
+    }
+
+    const results = await this.targetBackend.importData(bundle.records, options);
+
+    if (options.onProgress) {
+      options.onProgress(results.success + results.failed, bundle.recordCount);
+    }
+
+    console.log(`Import complete: ${results.success} succeeded, ${results.failed} failed.`);
+    return results;
+  }
+
+  /**
+   * Migrate data directly from source to target
+   * @param {string} [pathPrefix] - Optional path prefix filter
+   * @param {Object} [options] - Migration options
+   * @param {boolean} [options.dryRun] - Simulate without writing
+   * @param {Function} [options.onProgress] - Progress callback
+   * @returns {Promise<Object>} Migration results
+   */
+  async migrate(pathPrefix = '', options = {}) {
+    if (!this.sourceBackend || !this.targetBackend) {
+      throw new Error('Both source and target backends must be configured.');
+    }
+
+    const sourceStatus = this.sourceBackend.getStatus();
+    const targetStatus = this.targetBackend.getStatus();
+
+    console.log(`\nMigrating data:`);
+    console.log(`  From: ${sourceStatus.type} (${sourceStatus.publicKey || 'unknown'})`);
+    console.log(`  To:   ${targetStatus.type}`);
+    console.log(`  Filter: ${pathPrefix || '(all data)'}\n`);
+
+    // Export from source
+    const bundle = await this.export(pathPrefix);
+
+    // Import to target
+    const importResults = await this.import(bundle, options);
+
+    return {
+      sourceType: sourceStatus.type,
+      targetType: targetStatus.type,
+      pathPrefix,
+      exportedCount: bundle.recordCount,
+      ...importResults,
+    };
+  }
+
+  /**
+   * Validate data integrity after migration
+   * @param {string} [pathPrefix] - Optional path prefix filter
+   * @returns {Promise<Object>} Validation results
+   */
+  async validate(pathPrefix = '') {
+    if (!this.sourceBackend || !this.targetBackend) {
+      throw new Error('Both source and target backends must be configured.');
+    }
+
+    console.log('Validating migration...');
+
+    const sourceData = await this.sourceBackend.exportData(pathPrefix);
+    const targetData = await this.targetBackend.exportData(pathPrefix);
+
+    const sourceMap = new Map(sourceData.map(r => [r.path, r]));
+    const targetMap = new Map(targetData.map(r => [r.path, r]));
+
+    const missing = [];
+    const different = [];
+    const extra = [];
+
+    // Check for missing or different records
+    for (const [path, sourceRecord] of sourceMap) {
+      const targetRecord = targetMap.get(path);
+
+      if (!targetRecord) {
+        missing.push(path);
+      } else {
+        // Compare data (ignoring metadata that may differ)
+        const sourceDataStr = JSON.stringify(this._normalizeForComparison(sourceRecord.data));
+        const targetDataStr = JSON.stringify(this._normalizeForComparison(targetRecord.data));
+
+        if (sourceDataStr !== targetDataStr) {
+          different.push({
+            path,
+            source: sourceRecord.data,
+            target: targetRecord.data,
+          });
+        }
+      }
+    }
+
+    // Check for extra records in target
+    for (const path of targetMap.keys()) {
+      if (!sourceMap.has(path)) {
+        extra.push(path);
+      }
+    }
+
+    const valid = missing.length === 0 && different.length === 0;
+
+    console.log(`Validation ${valid ? 'PASSED' : 'FAILED'}:`);
+    console.log(`  Source records: ${sourceData.length}`);
+    console.log(`  Target records: ${targetData.length}`);
+    console.log(`  Missing: ${missing.length}`);
+    console.log(`  Different: ${different.length}`);
+    console.log(`  Extra: ${extra.length}`);
+
+    return {
+      valid,
+      sourceCount: sourceData.length,
+      targetCount: targetData.length,
+      missing,
+      different,
+      extra,
+    };
+  }
+
+  /**
+   * Normalize data for comparison (remove volatile metadata)
+   * @private
+   */
+  _normalizeForComparison(data) {
+    if (!data || typeof data !== 'object') return data;
+
+    const normalized = { ...data };
+
+    // Remove metadata that may legitimately differ
+    delete normalized._meta;
+    delete normalized._author;
+    delete normalized._timestamp;
+
+    return normalized;
+  }
+
+  /**
+   * Export bundle to JSON file (for manual transfer)
+   * @param {DataBundle} bundle - Data bundle
+   * @param {string} filePath - Output file path
+   */
+  async exportToFile(bundle, filePath) {
+    const fs = await import('fs/promises');
+    await fs.writeFile(filePath, JSON.stringify(bundle, null, 2), 'utf-8');
+    console.log(`Bundle exported to ${filePath}`);
+  }
+
+  /**
+   * Import bundle from JSON file
+   * @param {string} filePath - Input file path
+   * @returns {Promise<DataBundle>} Loaded bundle
+   */
+  async importFromFile(filePath) {
+    const fs = await import('fs/promises');
+    const content = await fs.readFile(filePath, 'utf-8');
+    const bundle = JSON.parse(content);
+    console.log(`Bundle loaded from ${filePath}: ${bundle.recordCount} records`);
+    return bundle;
+  }
+
+  /**
+   * Close all backend connections
+   */
+  close() {
+    if (this.sourceBackend) {
+      this.sourceBackend.close();
+    }
+    if (this.targetBackend) {
+      this.targetBackend.close();
+    }
+  }
+}
+
+/**
+ * Quick migration function for common use cases
+ * @param {Object} sourceConfig - Source backend config with 'type' field
+ * @param {Object} targetConfig - Target backend config with 'type' field
+ * @param {string} [pathPrefix] - Optional path filter
+ * @param {Object} [options] - Migration options
+ * @returns {Promise<Object>} Migration results
+ */
+export async function quickMigrate(sourceConfig, targetConfig, pathPrefix = '', options = {}) {
+  const tool = new MigrationTool();
+
+  try {
+    await tool.setSource(sourceConfig.type, sourceConfig);
+    await tool.setTarget(targetConfig.type, targetConfig);
+
+    const results = await tool.migrate(pathPrefix, options);
+
+    if (!options.skipValidation) {
+      const validation = await tool.validate(pathPrefix);
+      results.validation = validation;
+    }
+
+    return results;
+  } finally {
+    tool.close();
+  }
+}
+
+export default MigrationTool;