s3db.js 13.6.1 → 14.0.2

package/src/plugins/scheduler.plugin.js

@@ -80,7 +80,13 @@ import { SchedulerError } from "./scheduler.errors.js";
  *         if (backupPlugin) {
  *           return await backupPlugin.backup('incremental');
  *         }
- *         throw new Error('BackupPlugin not available');
+ *         throw new PluginError('BackupPlugin not available', {
+ *           pluginName: 'SchedulerPlugin',
+ *           operation: 'backupJob',
+ *           statusCode: 500,
+ *           retriable: false,
+ *           suggestion: 'Ensure BackupPlugin is installed before scheduling backup jobs.'
+ *         });
  *       },
  *       retries: 2
  *     },
@@ -94,7 +100,13 @@ import { SchedulerError } from "./scheduler.errors.js";
  *         if (backupPlugin) {
  *           return await backupPlugin.backup('full');
  *         }
- *         throw new Error('BackupPlugin not available');
+ *         throw new PluginError('BackupPlugin not available', {
+ *           pluginName: 'SchedulerPlugin',
+ *           operation: 'backupJob',
+ *           statusCode: 500,
+ *           retriable: false,
+ *           suggestion: 'Ensure BackupPlugin is installed before scheduling backup jobs.'
+ *         });
  *       }
  *     },
  *     
@@ -414,8 +426,8 @@ export class SchedulerPlugin extends Plugin {
 
     // Acquire distributed lock with TTL to prevent concurrent execution across instances
     const storage = this.getStorage();
-    const lockKey = `job-${jobName}`;
-    const lock = await storage.acquireLock(lockKey, {
+    const lockName = `job-${jobName}`;
+    const lock = await storage.acquireLock(lockName, {
       ttl: Math.ceil(job.timeout / 1000) + 60, // Job timeout + 60 seconds buffer
       timeout: 0, // Don't wait if locked
       workerId: process.pid ? String(process.pid) : 'unknown'
@@ -571,7 +583,9 @@ export class SchedulerPlugin extends Plugin {
       }
     } finally {
       // Always release the distributed lock
-      await tryFn(() => storage.releaseLock(lockKey));
+      if (lock) {
+        await tryFn(() => storage.releaseLock(lock));
+      }
     }
   }
 
@@ -921,4 +935,4 @@ export class SchedulerPlugin extends Plugin {
     this.activeJobs.clear();
     this.removeAllListeners();
   }
-}
+}

package/src/plugins/state-machine.plugin.js

@@ -1,5 +1,6 @@
 import { Plugin } from "./plugin.class.js";
 import tryFn from "../concerns/try-fn.js";
+import { resolveResourceNames } from "./concerns/resource-names.js";
 import { StateMachineError } from "./state-machine.errors.js";
 import { ErrorClassifier } from "../concerns/error-classifier.js";
 
@@ -102,13 +103,27 @@ export class StateMachinePlugin extends Plugin {
   constructor(options = {}) {
     super();
 
+    const resourceNamesOption = options.resourceNames || {};
+
+    this._resourceDescriptors = {
+      transitionLog: {
+        defaultName: 'plg_state_transitions',
+        override: resourceNamesOption.transitionLog || options.transitionLogResource
+      },
+      states: {
+        defaultName: 'plg_entity_states',
+        override: resourceNamesOption.states || options.stateResource
+      }
+    };
+    this.resourceNames = this._resolveResourceNames();
+
     this.config = {
       stateMachines: options.stateMachines || {},
       actions: options.actions || {},
       guards: options.guards || {},
       persistTransitions: options.persistTransitions !== false,
-      transitionLogResource: options.transitionLogResource || 'plg_state_transitions',
-      stateResource: options.stateResource || 'plg_entity_states',
+      transitionLogResource: this.resourceNames.transitionLog,
+      stateResource: this.resourceNames.states,
       retryAttempts: options.retryAttempts || 3,
       retryDelay: options.retryDelay || 100,
       verbose: options.verbose || false,
@@ -138,6 +153,20 @@ export class StateMachinePlugin extends Plugin {
     this._validateConfiguration();
   }
 
+  _resolveResourceNames() {
+    return resolveResourceNames('state_machine', this._resourceDescriptors, {
+      namespace: this.namespace
+    });
+  }
+
+  onNamespaceChanged() {
+    this.resourceNames = this._resolveResourceNames();
+    if (this.config) {
+      this.config.transitionLogResource = this.resourceNames.transitionLog;
+      this.config.stateResource = this.resourceNames.states;
+    }
+  }
+
   /**
    * Wait for all pending event handlers to complete
    * Useful when working with async events (asyncEvents: true)
@@ -290,7 +319,7 @@ export class StateMachinePlugin extends Plugin {
     }
 
     // Acquire distributed lock to prevent concurrent transitions
-    const lockName = await this._acquireTransitionLock(machineId, entityId);
+    const lock = await this._acquireTransitionLock(machineId, entityId);
 
     try {
       const currentState = await this.getState(machineId, entityId);
@@ -366,7 +395,7 @@ export class StateMachinePlugin extends Plugin {
       };
     } finally {
       // Always release lock, even if transition fails
-      await this._releaseTransitionLock(lockName);
+      await this._releaseTransitionLock(lock);
     }
   }
 
@@ -610,19 +639,21 @@ export class StateMachinePlugin extends Plugin {
       });
     }
 
-    return lockName;
+    return lock;
   }
 
   /**
    * Release distributed lock for transition
    * @private
    */
-  async _releaseTransitionLock(lockName) {
+  async _releaseTransitionLock(lock) {
+    if (!lock) return;
+
     const storage = this.getStorage();
-    const [ok, err] = await tryFn(() => storage.releaseLock(lockName));
+    const [ok, err] = await tryFn(() => storage.releaseLock(lock));
 
     if (!ok && this.config.verbose) {
-      console.warn(`[StateMachinePlugin] Failed to release lock '${lockName}':`, err.message);
+      console.warn(`[StateMachinePlugin] Failed to release lock '${lock?.name}':`, err.message);
     }
   }
 
@@ -1500,4 +1531,4 @@ export class StateMachinePlugin extends Plugin {
     this.machines.clear();
     this.removeAllListeners();
   }
-}
+}

package/src/plugins/tfstate/base-driver.js

@@ -1,3 +1,5 @@
+import { TfStateError } from './errors.js';
+
 /**
  * Base Driver Class for TfState Plugin
  *
@@ -14,7 +16,12 @@ export class TfStateDriver {
    * Called during plugin installation
    */
   async initialize() {
-    throw new Error('Driver must implement initialize()');
+    throw new TfStateError('Driver must implement initialize()', {
+      operation: 'initialize',
+      statusCode: 501,
+      retriable: false,
+      suggestion: 'Extend TfStateDriver and implement initialize() to configure backend connections.'
+    });
   }
 
   /**
@@ -22,7 +29,12 @@ export class TfStateDriver {
    * @returns {Promise<Array>} Array of state file metadata { path, lastModified, size }
    */
   async listStateFiles() {
-    throw new Error('Driver must implement listStateFiles()');
+    throw new TfStateError('Driver must implement listStateFiles()', {
+      operation: 'listStateFiles',
+      statusCode: 501,
+      retriable: false,
+      suggestion: 'Override listStateFiles() to return available Terraform state metadata.'
+    });
   }
 
   /**
@@ -31,7 +43,13 @@ export class TfStateDriver {
    * @returns {Promise<Object>} Parsed state file content
    */
   async readStateFile(path) {
-    throw new Error('Driver must implement readStateFile()');
+    throw new TfStateError('Driver must implement readStateFile()', {
+      operation: 'readStateFile',
+      statusCode: 501,
+      retriable: false,
+      suggestion: 'Override readStateFile(path) to load and parse the Terraform state JSON.',
+      path
+    });
   }
 
   /**
@@ -40,7 +58,13 @@ export class TfStateDriver {
    * @returns {Promise<Object>} Metadata { path, lastModified, size, etag }
    */
   async getStateFileMetadata(path) {
-    throw new Error('Driver must implement getStateFileMetadata()');
+    throw new TfStateError('Driver must implement getStateFileMetadata()', {
+      operation: 'getStateFileMetadata',
+      statusCode: 501,
+      retriable: false,
+      suggestion: 'Override getStateFileMetadata(path) to return lastModified, size, and ETag information.',
+      path
+    });
   }
 
   /**

package/src/plugins/tfstate/errors.js

@@ -1,3 +1,5 @@
+import { PluginError } from '../../errors.js';
+
 /**
  * TfStatePlugin Error Classes
  * Custom errors for Terraform/OpenTofu state operations
@@ -6,12 +8,19 @@
 /**
  * Base error for all Terraform/OpenTofu state operations
  */
-export class TfStateError extends Error {
+export class TfStateError extends PluginError {
   constructor(message, context = {}) {
-    super(message);
+    const merged = {
+      pluginName: context.pluginName || 'TfStatePlugin',
+      operation: context.operation || 'unknown',
+      statusCode: context.statusCode ?? 500,
+      retriable: context.retriable ?? false,
+      suggestion: context.suggestion ?? 'Verify Terraform/OpenTofu configuration and state storage before retrying.',
+      ...context
+    };
+    super(message, merged);
     this.name = 'TfStateError';
     this.context = context;
-    Error.captureStackTrace(this, this.constructor);
   }
 }
 
@@ -20,7 +29,14 @@ export class TfStateError extends Error {
  */
 export class InvalidStateFileError extends TfStateError {
   constructor(filePath, reason, context = {}) {
-    super(`Invalid Tfstate file "${filePath}": ${reason}`, context);
+    super(`Invalid Tfstate file "${filePath}": ${reason}`, {
+      statusCode: context.statusCode ?? 422,
+      retriable: false,
+      suggestion: context.suggestion ?? 'Validate Terraform state integrity or re-run terraform state pull.',
+      filePath,
+      reason,
+      ...context
+    });
     this.name = 'InvalidStateFileError';
     this.filePath = filePath;
     this.reason = reason;
@@ -34,7 +50,14 @@ export class UnsupportedStateVersionError extends TfStateError {
   constructor(version, supportedVersions, context = {}) {
     super(
       `Tfstate version ${version} is not supported. Supported versions: ${supportedVersions.join(', ')}`,
-      context
+      {
+        statusCode: context.statusCode ?? 400,
+        retriable: false,
+        suggestion: context.suggestion ?? `Upgrade/downgrade Terraform state to one of the supported versions: ${supportedVersions.join(', ')}.`,
+        version,
+        supportedVersions,
+        ...context
+      }
     );
     this.name = 'UnsupportedStateVersionError';
     this.version = version;
@@ -47,7 +70,13 @@ export class UnsupportedStateVersionError extends TfStateError {
  */
 export class StateFileNotFoundError extends TfStateError {
   constructor(filePath, context = {}) {
-    super(`Tfstate file not found: ${filePath}`, context);
+    super(`Tfstate file not found: ${filePath}`, {
+      statusCode: context.statusCode ?? 404,
+      retriable: false,
+      suggestion: context.suggestion ?? 'Ensure the state file exists at the configured path/bucket.',
+      filePath,
+      ...context
+    });
     this.name = 'StateFileNotFoundError';
     this.filePath = filePath;
   }
@@ -60,7 +89,13 @@ export class ResourceExtractionError extends TfStateError {
   constructor(resourceAddress, originalError, context = {}) {
     super(
       `Failed to extract resource "${resourceAddress}": ${originalError.message}`,
-      context
+      {
+        retriable: context.retriable ?? false,
+        suggestion: context.suggestion ?? 'Check resource address and state structure; rerun extraction after fixing the state.',
+        resourceAddress,
+        originalError,
+        ...context
+      }
     );
     this.name = 'ResourceExtractionError';
     this.resourceAddress = resourceAddress;
@@ -75,7 +110,14 @@ export class StateDiffError extends TfStateError {
   constructor(oldSerial, newSerial, originalError, context = {}) {
     super(
       `Failed to calculate diff between state serials ${oldSerial} and ${newSerial}: ${originalError.message}`,
-      context
+      {
+        retriable: context.retriable ?? true,
+        suggestion: context.suggestion ?? 'Refresh the latest state snapshots and retry the diff operation.',
+        oldSerial,
+        newSerial,
+        originalError,
+        ...context
+      }
     );
     this.name = 'StateDiffError';
     this.oldSerial = oldSerial;
@@ -89,7 +131,13 @@ export class StateDiffError extends TfStateError {
  */
 export class FileWatchError extends TfStateError {
   constructor(path, originalError, context = {}) {
-    super(`Failed to watch path "${path}": ${originalError.message}`, context);
+    super(`Failed to watch path "${path}": ${originalError.message}`, {
+      retriable: context.retriable ?? true,
+      suggestion: context.suggestion ?? 'Verify filesystem permissions and that the watch path exists.',
+      path,
+      originalError,
+      ...context
+    });
     this.name = 'FileWatchError';
     this.path = path;
     this.originalError = originalError;
@@ -103,7 +151,14 @@ export class ResourceFilterError extends TfStateError {
   constructor(filterExpression, originalError, context = {}) {
     super(
       `Failed to apply resource filter "${filterExpression}": ${originalError.message}`,
-      context
+      {
+        statusCode: context.statusCode ?? 400,
+        retriable: context.retriable ?? false,
+        suggestion: context.suggestion ?? 'Validate the filter expression syntax and ensure referenced resources exist.',
+        filterExpression,
+        originalError,
+        ...context
+      }
     );
     this.name = 'ResourceFilterError';
     this.filterExpression = filterExpression;

package/src/plugins/tfstate/filesystem-driver.js

@@ -6,8 +6,9 @@
  */
 import { TfStateDriver } from './base-driver.js';
 import { readFile, stat } from 'fs/promises';
-import { join, relative } from 'path';
+import { join } from 'path';
 import { glob } from 'glob';
+import { TfStateError, StateFileNotFoundError } from './errors.js';
 
 export class FilesystemTfStateDriver extends TfStateDriver {
   constructor(config = {}) {
@@ -23,10 +24,23 @@ export class FilesystemTfStateDriver extends TfStateDriver {
     try {
       const stats = await stat(this.basePath);
       if (!stats.isDirectory()) {
-        throw new Error(`Base path is not a directory: ${this.basePath}`);
+        throw new TfStateError(`Base path is not a directory: ${this.basePath}`, {
+          operation: 'initialize',
+          statusCode: 400,
+          retriable: false,
+          suggestion: 'Update the TfState filesystem driver configuration to point to a directory containing .tfstate files.',
+          basePath: this.basePath
+        });
       }
     } catch (error) {
-      throw new Error(`Invalid base path: ${this.basePath} - ${error.message}`);
+      throw new TfStateError(`Invalid base path: ${this.basePath}`, {
+        operation: 'initialize',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Ensure the basePath exists and is readable by the current process.',
+        basePath: this.basePath,
+        original: error
+      });
     }
   }
 
@@ -60,7 +74,15 @@ export class FilesystemTfStateDriver extends TfStateDriver {
 
       return stateFiles;
     } catch (error) {
-      throw new Error(`Failed to list state files: ${error.message}`);
+      throw new TfStateError('Failed to list Terraform state files', {
+        operation: 'listStateFiles',
+        statusCode: 500,
+        retriable: false,
+        suggestion: 'Verify filesystem permissions and glob selector pattern.',
+        selector: this.selector,
+        basePath: this.basePath,
+        original: error
+      });
     }
   }
 
@@ -77,9 +99,20 @@ export class FilesystemTfStateDriver extends TfStateDriver {
       return JSON.parse(content);
     } catch (error) {
       if (error.code === 'ENOENT') {
-        throw new Error(`State file not found: ${path}`);
+        throw new StateFileNotFoundError(path, {
+          operation: 'readStateFile',
+          retriable: false,
+          suggestion: 'Ensure the Terraform state file exists at the specified path.',
+          original: error
+        });
       }
-      throw new Error(`Failed to read state file ${path}: ${error.message}`);
+      throw new TfStateError(`Failed to read state file ${path}`, {
+        operation: 'readStateFile',
+        retriable: false,
+        suggestion: 'Validate file permissions and state file contents (must be valid JSON).',
+        path,
+        original: error
+      });
     }
   }
 
@@ -103,9 +136,20 @@ export class FilesystemTfStateDriver extends TfStateDriver {
       };
     } catch (error) {
       if (error.code === 'ENOENT') {
-        throw new Error(`State file not found: ${path}`);
+        throw new StateFileNotFoundError(path, {
+          operation: 'getStateFileMetadata',
+          retriable: false,
+          suggestion: 'Ensure the Terraform state file exists at the specified path.',
+          original: error
+        });
       }
-      throw new Error(`Failed to get metadata for ${path}: ${error.message}`);
+      throw new TfStateError(`Failed to get metadata for ${path}`, {
+        operation: 'getStateFileMetadata',
+        retriable: false,
+        suggestion: 'Check filesystem permissions and path configuration for TfStatePlugin.',
+        path,
+        original: error
+      });
     }
   }