s3db.js 11.2.2 → 11.2.4

package/src/plugins/backup/base-backup-driver.class.js

@@ -1,3 +1,5 @@
+import { BackupError } from '../backup.errors.js';
+
 /**
  * BaseBackupDriver - Abstract base class for backup drivers
  *
@@ -38,7 +40,12 @@ export default class BaseBackupDriver {
    * @returns {Object} Upload result with destination info
    */
   async upload(filePath, backupId, manifest) {
-    throw new Error('upload() method must be implemented by subclass');
+    throw new BackupError('upload() method must be implemented by subclass', {
+      operation: 'upload',
+      driver: this.constructor.name,
+      backupId,
+      suggestion: 'Extend BaseBackupDriver and implement the upload() method'
+    });
   }
 
   /**
@@ -49,7 +56,12 @@ export default class BaseBackupDriver {
    * @returns {string} Path to downloaded file
    */
   async download(backupId, targetPath, metadata) {
-    throw new Error('download() method must be implemented by subclass');
+    throw new BackupError('download() method must be implemented by subclass', {
+      operation: 'download',
+      driver: this.constructor.name,
+      backupId,
+      suggestion: 'Extend BaseBackupDriver and implement the download() method'
+    });
   }
 
   /**
@@ -58,7 +70,12 @@ export default class BaseBackupDriver {
    * @param {Object} metadata - Backup metadata
    */
   async delete(backupId, metadata) {
-    throw new Error('delete() method must be implemented by subclass');
+    throw new BackupError('delete() method must be implemented by subclass', {
+      operation: 'delete',
+      driver: this.constructor.name,
+      backupId,
+      suggestion: 'Extend BaseBackupDriver and implement the delete() method'
+    });
   }
 
   /**
@@ -67,7 +84,11 @@ export default class BaseBackupDriver {
    * @returns {Array} List of backup metadata
    */
   async list(options = {}) {
-    throw new Error('list() method must be implemented by subclass');
+    throw new BackupError('list() method must be implemented by subclass', {
+      operation: 'list',
+      driver: this.constructor.name,
+      suggestion: 'Extend BaseBackupDriver and implement the list() method'
+    });
   }
 
   /**
@@ -78,7 +99,12 @@ export default class BaseBackupDriver {
    * @returns {boolean} True if backup is valid
    */
   async verify(backupId, expectedChecksum, metadata) {
-    throw new Error('verify() method must be implemented by subclass');
+    throw new BackupError('verify() method must be implemented by subclass', {
+      operation: 'verify',
+      driver: this.constructor.name,
+      backupId,
+      suggestion: 'Extend BaseBackupDriver and implement the verify() method'
+    });
   }
 
   /**
@@ -86,7 +112,11 @@ export default class BaseBackupDriver {
    * @returns {string} Driver type
    */
   getType() {
-    throw new Error('getType() method must be implemented by subclass');
+    throw new BackupError('getType() method must be implemented by subclass', {
+      operation: 'getType',
+      driver: this.constructor.name,
+      suggestion: 'Extend BaseBackupDriver and implement the getType() method'
+    });
   }
 
   /**

package/src/plugins/backup/filesystem-backup-driver.class.js

@@ -5,6 +5,7 @@ import { pipeline } from 'stream/promises';
 import path from 'path';
 import crypto from 'crypto';
 import tryFn from '../../concerns/try-fn.js';
+import { BackupError } from '../backup.errors.js';
 
 /**
  * FilesystemBackupDriver - Stores backups on local/network filesystem
@@ -31,7 +32,11 @@ export default class FilesystemBackupDriver extends BaseBackupDriver {
   async onSetup() {
     // Validate path configuration
     if (!this.config.path) {
-      throw new Error('FilesystemBackupDriver: path configuration is required');
+      throw new BackupError('FilesystemBackupDriver: path configuration is required', {
+        operation: 'onSetup',
+        driver: 'filesystem',
+        suggestion: 'Provide a path in config: new FilesystemBackupDriver({ path: "/path/to/backups" })'
+      });
     }
 
     this.log(`Initialized with path: ${this.config.path}`);
@@ -69,13 +74,28 @@ export default class FilesystemBackupDriver extends BaseBackupDriver {
     );
     
     if (!createDirOk) {
-      throw new Error(`Failed to create backup directory: ${createDirErr.message}`);
+      throw new BackupError('Failed to create backup directory', {
+        operation: 'upload',
+        driver: 'filesystem',
+        backupId,
+        targetDir,
+        original: createDirErr,
+        suggestion: 'Check directory permissions and disk space'
+      });
     }
 
     // Copy backup file
     const [copyOk, copyErr] = await tryFn(() => copyFile(filePath, targetPath));
     if (!copyOk) {
-      throw new Error(`Failed to copy backup file: ${copyErr.message}`);
+      throw new BackupError('Failed to copy backup file', {
+        operation: 'upload',
+        driver: 'filesystem',
+        backupId,
+        filePath,
+        targetPath,
+        original: copyErr,
+        suggestion: 'Check file permissions and disk space'
+      });
     }
 
     // Write manifest
@@ -90,7 +110,14 @@ export default class FilesystemBackupDriver extends BaseBackupDriver {
     if (!manifestOk) {
       // Clean up backup file if manifest fails
       await tryFn(() => unlink(targetPath));
-      throw new Error(`Failed to write manifest: ${manifestErr.message}`);
+      throw new BackupError('Failed to write manifest file', {
+        operation: 'upload',
+        driver: 'filesystem',
+        backupId,
+        manifestPath,
+        original: manifestErr,
+        suggestion: 'Check directory permissions and disk space'
+      });
     }
 
     // Get file stats
@@ -116,7 +143,13 @@ export default class FilesystemBackupDriver extends BaseBackupDriver {
     // Check if source exists
     const [existsOk] = await tryFn(() => access(sourcePath));
     if (!existsOk) {
-      throw new Error(`Backup file not found: ${sourcePath}`);
+      throw new BackupError('Backup file not found', {
+        operation: 'download',
+        driver: 'filesystem',
+        backupId,
+        sourcePath,
+        suggestion: 'Check if backup exists using list() method'
+      });
     }
 
     // Create target directory if needed
@@ -126,7 +159,15 @@ export default class FilesystemBackupDriver extends BaseBackupDriver {
     // Copy file
     const [copyOk, copyErr] = await tryFn(() => copyFile(sourcePath, targetPath));
     if (!copyOk) {
-      throw new Error(`Failed to download backup: ${copyErr.message}`);
+      throw new BackupError('Failed to download backup', {
+        operation: 'download',
+        driver: 'filesystem',
+        backupId,
+        sourcePath,
+        targetPath,
+        original: copyErr,
+        suggestion: 'Check file permissions and disk space'
+      });
     }
 
     this.log(`Downloaded backup ${backupId} from ${sourcePath} to ${targetPath}`);
@@ -150,7 +191,14 @@ export default class FilesystemBackupDriver extends BaseBackupDriver {
     const [deleteManifestOk] = await tryFn(() => unlink(manifestPath));
 
     if (!deleteBackupOk && !deleteManifestOk) {
-      throw new Error(`Failed to delete backup files for ${backupId}`);
+      throw new BackupError('Failed to delete backup files', {
+        operation: 'delete',
+        driver: 'filesystem',
+        backupId,
+        backupPath,
+        manifestPath,
+        suggestion: 'Check file permissions'
+      });
     }
 
     this.log(`Deleted backup ${backupId}`);

package/src/plugins/backup/index.js

@@ -2,6 +2,7 @@ import BaseBackupDriver from './base-backup-driver.class.js';
 import FilesystemBackupDriver from './filesystem-backup-driver.class.js';
 import S3BackupDriver from './s3-backup-driver.class.js';
 import MultiBackupDriver from './multi-backup-driver.class.js';
+import { BackupError } from '../backup.errors.js';
 
 export { 
   BaseBackupDriver, 
@@ -27,11 +28,16 @@ export const BACKUP_DRIVERS = {
  */
 export function createBackupDriver(driver, config = {}) {
   const DriverClass = BACKUP_DRIVERS[driver];
-  
+
   if (!DriverClass) {
-    throw new Error(`Unknown backup driver: ${driver}. Available drivers: ${Object.keys(BACKUP_DRIVERS).join(', ')}`);
+    throw new BackupError(`Unknown backup driver: ${driver}`, {
+      operation: 'createBackupDriver',
+      driver,
+      availableDrivers: Object.keys(BACKUP_DRIVERS),
+      suggestion: `Use one of the available drivers: ${Object.keys(BACKUP_DRIVERS).join(', ')}`
+    });
   }
-  
+
   return new DriverClass(config);
 }
 
@@ -43,18 +49,32 @@ export function createBackupDriver(driver, config = {}) {
  */
 export function validateBackupConfig(driver, config = {}) {
   if (!driver || typeof driver !== 'string') {
-    throw new Error('Driver type must be a non-empty string');
+    throw new BackupError('Driver type must be a non-empty string', {
+      operation: 'validateBackupConfig',
+      driver,
+      suggestion: 'Provide a valid driver type string (filesystem, s3, or multi)'
+    });
   }
 
   if (!BACKUP_DRIVERS[driver]) {
-    throw new Error(`Unknown backup driver: ${driver}. Available drivers: ${Object.keys(BACKUP_DRIVERS).join(', ')}`);
+    throw new BackupError(`Unknown backup driver: ${driver}`, {
+      operation: 'validateBackupConfig',
+      driver,
+      availableDrivers: Object.keys(BACKUP_DRIVERS),
+      suggestion: `Use one of the available drivers: ${Object.keys(BACKUP_DRIVERS).join(', ')}`
+    });
   }
 
   // Driver-specific validation
   switch (driver) {
     case 'filesystem':
       if (!config.path) {
-        throw new Error('FilesystemBackupDriver requires "path" configuration');
+        throw new BackupError('FilesystemBackupDriver requires "path" configuration', {
+          operation: 'validateBackupConfig',
+          driver: 'filesystem',
+          config,
+          suggestion: 'Provide a "path" property in config: { path: "/path/to/backups" }'
+        });
       }
       break;
 
@@ -64,13 +84,24 @@ export function validateBackupConfig(driver, config = {}) {
 
     case 'multi':
       if (!Array.isArray(config.destinations) || config.destinations.length === 0) {
-        throw new Error('MultiBackupDriver requires non-empty "destinations" array');
+        throw new BackupError('MultiBackupDriver requires non-empty "destinations" array', {
+          operation: 'validateBackupConfig',
+          driver: 'multi',
+          config,
+          suggestion: 'Provide destinations array: { destinations: [{ driver: "s3", config: {...} }] }'
+        });
       }
-      
+
       // Validate each destination
       config.destinations.forEach((dest, index) => {
         if (!dest.driver) {
-          throw new Error(`Destination ${index} must have a "driver" property`);
+          throw new BackupError(`Destination ${index} must have a "driver" property`, {
+            operation: 'validateBackupConfig',
+            driver: 'multi',
+            destinationIndex: index,
+            destination: dest,
+            suggestion: 'Each destination must have a driver property: { driver: "s3", config: {...} }'
+          });
         }
         
         // Recursive validation for nested drivers

package/src/plugins/backup/multi-backup-driver.class.js

@@ -1,6 +1,7 @@
 import BaseBackupDriver from './base-backup-driver.class.js';
 import { createBackupDriver } from './index.js';
 import tryFn from '../../concerns/try-fn.js';
+import { BackupError } from '../backup.errors.js';
 
 /**
  * MultiBackupDriver - Manages multiple backup destinations
@@ -34,13 +35,24 @@ export default class MultiBackupDriver extends BaseBackupDriver {
 
   async onSetup() {
     if (!Array.isArray(this.config.destinations) || this.config.destinations.length === 0) {
-      throw new Error('MultiBackupDriver: destinations array is required and must not be empty');
+      throw new BackupError('MultiBackupDriver requires non-empty destinations array', {
+        operation: 'onSetup',
+        driver: 'multi',
+        destinationsProvided: this.config.destinations,
+        suggestion: 'Provide destinations array: { destinations: [{ driver: "s3", config: {...} }, { driver: "filesystem", config: {...} }] }'
+      });
     }
 
     // Create and setup all driver instances
     for (const [index, destConfig] of this.config.destinations.entries()) {
       if (!destConfig.driver) {
-        throw new Error(`MultiBackupDriver: destination[${index}] must have a driver type`);
+        throw new BackupError(`Destination ${index} missing driver type`, {
+          operation: 'onSetup',
+          driver: 'multi',
+          destinationIndex: index,
+          destination: destConfig,
+          suggestion: 'Each destination must have a driver property: { driver: "s3", config: {...} } or { driver: "filesystem", config: {...} }'
+        });
       }
 
       try {
@@ -51,10 +63,18 @@ export default class MultiBackupDriver extends BaseBackupDriver {
           config: destConfig,
           index
         });
-        
+
         this.log(`Setup destination ${index}: ${destConfig.driver}`);
       } catch (error) {
-        throw new Error(`Failed to setup destination ${index} (${destConfig.driver}): ${error.message}`);
+        throw new BackupError(`Failed to setup destination ${index}`, {
+          operation: 'onSetup',
+          driver: 'multi',
+          destinationIndex: index,
+          destinationDriver: destConfig.driver,
+          destinationConfig: destConfig.config,
+          original: error,
+          suggestion: 'Check destination driver configuration and ensure dependencies are available'
+        });
       }
     }
 
@@ -92,7 +112,15 @@ export default class MultiBackupDriver extends BaseBackupDriver {
         }
       }
 
-      throw new Error(`All priority destinations failed: ${errors.map(e => `${e.destination}: ${e.error}`).join('; ')}`);
+      throw new BackupError('All priority destinations failed', {
+        operation: 'upload',
+        driver: 'multi',
+        strategy: 'priority',
+        backupId,
+        totalDestinations: this.drivers.length,
+        failures: errors,
+        suggestion: 'Check destination configurations and ensure at least one destination is accessible'
+      });
     }
 
     // For 'all' and 'any' strategies, upload to all destinations
@@ -128,11 +156,29 @@ export default class MultiBackupDriver extends BaseBackupDriver {
     const failedResults = allResults.filter(r => r.status === 'failed');
 
     if (strategy === 'all' && failedResults.length > 0) {
-      throw new Error(`Some destinations failed: ${failedResults.map(r => `${r.destination}: ${r.error}`).join('; ')}`);
+      throw new BackupError('Some destinations failed with strategy "all"', {
+        operation: 'upload',
+        driver: 'multi',
+        strategy: 'all',
+        backupId,
+        totalDestinations: this.drivers.length,
+        successCount: successResults.length,
+        failedCount: failedResults.length,
+        failures: failedResults,
+        suggestion: 'All destinations must succeed with "all" strategy. Use "any" strategy to tolerate failures, or fix failing destinations.'
+      });
     }
 
     if (strategy === 'any' && successResults.length === 0) {
-      throw new Error(`All destinations failed: ${failedResults.map(r => `${r.destination}: ${r.error}`).join('; ')}`);
+      throw new BackupError('All destinations failed with strategy "any"', {
+        operation: 'upload',
+        driver: 'multi',
+        strategy: 'any',
+        backupId,
+        totalDestinations: this.drivers.length,
+        failures: failedResults,
+        suggestion: 'At least one destination must succeed with "any" strategy. Check all destination configurations.'
+      });
     }
 
     return allResults;
@@ -160,7 +206,14 @@ export default class MultiBackupDriver extends BaseBackupDriver {
       }
     }
 
-    throw new Error(`Failed to download backup from any destination`);
+    throw new BackupError('Failed to download backup from any destination', {
+      operation: 'download',
+      driver: 'multi',
+      backupId,
+      targetPath,
+      attemptedDestinations: destinations.length,
+      suggestion: 'Check if backup exists in at least one destination and destinations are accessible'
+    });
   }
 
   async delete(backupId, metadata) {
@@ -188,7 +241,14 @@ export default class MultiBackupDriver extends BaseBackupDriver {
     }
 
     if (successCount === 0 && errors.length > 0) {
-      throw new Error(`Failed to delete from any destination: ${errors.join('; ')}`);
+      throw new BackupError('Failed to delete from any destination', {
+        operation: 'delete',
+        driver: 'multi',
+        backupId,
+        attemptedDestinations: destinations.length,
+        failures: errors,
+        suggestion: 'Check if backup exists in destinations and destinations are accessible with delete permissions'
+      });
     }
 
     if (errors.length > 0) {

package/src/plugins/backup/s3-backup-driver.class.js

@@ -4,6 +4,7 @@ import { stat } from 'fs/promises';
 import path from 'path';
 import crypto from 'crypto';
 import tryFn from '../../concerns/try-fn.js';
+import { BackupError } from '../backup.errors.js';
 
 /**
  * S3BackupDriver - Stores backups in S3-compatible storage
@@ -43,11 +44,19 @@ export default class S3BackupDriver extends BaseBackupDriver {
     }
 
     if (!this.config.client) {
-      throw new Error('S3BackupDriver: client is required (either via config or database)');
+      throw new BackupError('S3BackupDriver: client is required', {
+        operation: 'onSetup',
+        driver: 's3',
+        suggestion: 'Provide a client in config or ensure database has a client configured'
+      });
     }
 
     if (!this.config.bucket) {
-      throw new Error('S3BackupDriver: bucket is required (either via config or database)');
+      throw new BackupError('S3BackupDriver: bucket is required', {
+        operation: 'onSetup',
+        driver: 's3',
+        suggestion: 'Provide a bucket in config or ensure database has a bucket configured'
+      });
     }
 
     this.log(`Initialized with bucket: ${this.config.bucket}, path: ${this.config.path}`);
@@ -108,7 +117,15 @@ export default class S3BackupDriver extends BaseBackupDriver {
     });
 
     if (!uploadOk) {
-      throw new Error(`Failed to upload backup file: ${uploadErr.message}`);
+      throw new BackupError('Failed to upload backup file to S3', {
+        operation: 'upload',
+        driver: 's3',
+        backupId,
+        bucket: this.config.bucket,
+        key: backupKey,
+        original: uploadErr,
+        suggestion: 'Check S3 permissions and bucket configuration'
+      });
     }
 
     // Upload manifest
@@ -133,7 +150,15 @@ export default class S3BackupDriver extends BaseBackupDriver {
         bucket: this.config.bucket,
         key: backupKey
       }));
-      throw new Error(`Failed to upload manifest: ${manifestErr.message}`);
+      throw new BackupError('Failed to upload manifest to S3', {
+        operation: 'upload',
+        driver: 's3',
+        backupId,
+        bucket: this.config.bucket,
+        manifestKey,
+        original: manifestErr,
+        suggestion: 'Check S3 permissions and bucket configuration'
+      });
     }
 
     this.log(`Uploaded backup ${backupId} to s3://${this.config.bucket}/${backupKey} (${fileSize} bytes)`);
@@ -161,7 +186,16 @@ export default class S3BackupDriver extends BaseBackupDriver {
     );
 
     if (!downloadOk) {
-      throw new Error(`Failed to download backup: ${downloadErr.message}`);
+      throw new BackupError('Failed to download backup from S3', {
+        operation: 'download',
+        driver: 's3',
+        backupId,
+        bucket: this.config.bucket,
+        key: backupKey,
+        targetPath,
+        original: downloadErr,
+        suggestion: 'Check if backup exists and S3 permissions are correct'
+      });
     }
 
     this.log(`Downloaded backup ${backupId} from s3://${this.config.bucket}/${backupKey} to ${targetPath}`);
@@ -189,7 +223,15 @@ export default class S3BackupDriver extends BaseBackupDriver {
     );
 
     if (!deleteBackupOk && !deleteManifestOk) {
-      throw new Error(`Failed to delete backup objects for ${backupId}`);
+      throw new BackupError('Failed to delete backup from S3', {
+        operation: 'delete',
+        driver: 's3',
+        backupId,
+        bucket: this.config.bucket,
+        backupKey,
+        manifestKey,
+        suggestion: 'Check S3 delete permissions'
+      });
     }
 
     this.log(`Deleted backup ${backupId} from S3`);

package/src/plugins/backup.errors.js

@@ -0,0 +1,45 @@
+import { S3dbError } from '../errors.js';
+
+/**
+ * BackupError - Errors related to backup operations
+ *
+ * Used for backup driver operations including:
+ * - Driver initialization and setup
+ * - Backup upload/download/delete operations
+ * - Driver configuration validation
+ * - Multi-destination backup strategies
+ *
+ * @extends S3dbError
+ */
+export class BackupError extends S3dbError {
+  constructor(message, details = {}) {
+    const { driver = 'unknown', operation = 'unknown', backupId, ...rest } = details;
+
+    let description = details.description;
+    if (!description) {
+      description = `
+Backup Operation Error
+
+Driver: ${driver}
+Operation: ${operation}
+${backupId ? `Backup ID: ${backupId}` : ''}
+
+Common causes:
+1. Invalid backup driver configuration
+2. Destination storage not accessible
+3. Insufficient permissions
+4. Network connectivity issues
+5. Invalid backup file format
+
+Solution:
+Check driver configuration and ensure destination storage is accessible.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/backup.md
+`.trim();
+    }
+
+    super(message, { ...rest, driver, operation, backupId, description });
+  }
+}
+
+export default BackupError;

package/src/plugins/cache/cache.class.js

@@ -1,4 +1,5 @@
 import EventEmitter from "events";
+import { CacheError } from "../cache.errors.js";
 
 export class Cache extends EventEmitter {
   constructor(config = {}) {
@@ -13,7 +14,13 @@ export class Cache extends EventEmitter {
 
   validateKey(key) {
     if (key === null || key === undefined || typeof key !== 'string' || !key) {
-      throw new Error('Invalid key');
+      throw new CacheError('Invalid cache key', {
+        operation: 'validateKey',
+        driver: this.constructor.name,
+        key,
+        keyType: typeof key,
+        suggestion: 'Cache key must be a non-empty string'
+      });
     }
   }