s3db.js 13.6.0 → 14.0.2

package/src/plugins/cloud-inventory/drivers/base-driver.js

@@ -27,6 +27,8 @@
  * The plugin normalizes the payload, computes configuration digests and
  * manages versioning/diffing.
  */
+import { PluginError } from '../../../errors.js';
+
 export class BaseCloudDriver {
   /**
    * @param {Object} options
@@ -48,7 +50,13 @@ export class BaseCloudDriver {
     } = options;
 
     if (!driver) {
-      throw new Error('Cloud driver requires a "driver" identifier');
+      throw new PluginError('Cloud driver requires a "driver" identifier', {
+        pluginName: 'CloudInventoryPlugin',
+        operation: 'cloudDriver:constructor',
+        statusCode: 500,
+        retriable: false,
+        suggestion: 'Specify the driver key (e.g. "aws", "gcp") when instantiating a cloud inventory driver.'
+      });
     }
 
     this.id = id || driver;
@@ -77,7 +85,13 @@ export class BaseCloudDriver {
    */
   // eslint-disable-next-line no-unused-vars
   async listResources(options = {}) {
-    throw new Error(`Driver "${this.driver}" does not implement listResources()`);
+    throw new PluginError(`Driver "${this.driver}" does not implement listResources()`, {
+      pluginName: 'CloudInventoryPlugin',
+      operation: 'cloudDriver:listResources',
+      statusCode: 500,
+      retriable: false,
+      suggestion: 'Implement listResources(options) in the concrete cloud driver to fetch inventory data.'
+    });
   }
 
   /**

package/src/plugins/cloud-inventory/drivers/cloudflare-driver.js

@@ -1,4 +1,5 @@
 import { BaseCloudDriver } from './base-driver.js';
+import { PluginError } from '../../../errors.js';
 
 /**
  * Production-ready Cloudflare inventory driver using official cloudflare SDK.
@@ -47,7 +48,13 @@ export class CloudflareInventoryDriver extends BaseCloudDriver {
     this._accountId = credentials.accountId || this.config?.accountId || process.env.CLOUDFLARE_ACCOUNT_ID;
 
     if (!this._apiToken) {
-      throw new Error('Cloudflare API token is required. Provide via credentials.apiToken or CLOUDFLARE_API_TOKEN env var.');
+      throw new PluginError('Cloudflare API token is required. Provide via credentials.apiToken or CLOUDFLARE_API_TOKEN env var.', {
+        pluginName: 'CloudInventoryPlugin',
+        operation: 'cloudflare:initClient',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Populate credentials.apiToken or set the CLOUDFLARE_API_TOKEN environment variable before initializing the Cloudflare driver.'
+      });
     }
 
     // Lazy import

package/src/plugins/cloud-inventory/drivers/digitalocean-driver.js

@@ -1,4 +1,5 @@
 import { BaseCloudDriver } from './base-driver.js';
+import { PluginError } from '../../../errors.js';
 
 /**
  * Production-ready DigitalOcean inventory driver using digitalocean-js library.
@@ -59,7 +60,13 @@ export class DigitalOceanInventoryDriver extends BaseCloudDriver {
     this._apiToken = credentials.token || credentials.apiToken || process.env.DIGITALOCEAN_TOKEN;
 
     if (!this._apiToken) {
-      throw new Error('DigitalOcean API token is required. Provide via credentials.token or DIGITALOCEAN_TOKEN env var.');
+      throw new PluginError('DigitalOcean API token is required. Provide via credentials.token or DIGITALOCEAN_TOKEN env var.', {
+        pluginName: 'CloudInventoryPlugin',
+        operation: 'digitalocean:initClient',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Set credentials.token or the DIGITALOCEAN_TOKEN environment variable before initializing the driver.'
+      });
     }
 
     // Lazy import to keep core package lightweight

package/src/plugins/cloud-inventory/drivers/hetzner-driver.js

@@ -1,4 +1,5 @@
 import { BaseCloudDriver } from './base-driver.js';
+import { PluginError } from '../../../errors.js';
 
 /**
  * Production-ready Hetzner Cloud inventory driver using hcloud-js library.
@@ -47,7 +48,13 @@ export class HetznerInventoryDriver extends BaseCloudDriver {
     this._apiToken = credentials.token || credentials.apiToken || process.env.HETZNER_TOKEN;
 
     if (!this._apiToken) {
-      throw new Error('Hetzner API token is required. Provide via credentials.token or HETZNER_TOKEN env var.');
+      throw new PluginError('Hetzner API token is required. Provide via credentials.token or HETZNER_TOKEN env var.', {
+        pluginName: 'CloudInventoryPlugin',
+        operation: 'hetzner:initClient',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Set credentials.token or HETZNER_TOKEN prior to initializing the Hetzner driver.'
+      });
     }
 
     // Lazy import to keep core package lightweight

package/src/plugins/cloud-inventory/drivers/linode-driver.js

@@ -1,4 +1,5 @@
 import { BaseCloudDriver } from './base-driver.js';
+import { PluginError } from '../../../errors.js';
 
 /**
  * Production-ready Linode (Akamai Cloud) inventory driver using official @linode/api-v4 SDK.
@@ -52,7 +53,13 @@ export class LinodeInventoryDriver extends BaseCloudDriver {
     this._apiToken = credentials.token || credentials.apiToken || process.env.LINODE_TOKEN;
 
     if (!this._apiToken) {
-      throw new Error('Linode API token is required. Provide via credentials.token or LINODE_TOKEN env var.');
+      throw new PluginError('Linode API token is required. Provide via credentials.token or LINODE_TOKEN env var.', {
+        pluginName: 'CloudInventoryPlugin',
+        operation: 'linode:initClient',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Set credentials.token or LINODE_TOKEN before running the Linode inventory driver.'
+      });
     }
 
     // Import and set token

package/src/plugins/cloud-inventory/drivers/mongodb-atlas-driver.js

@@ -1,4 +1,5 @@
 import { BaseCloudDriver } from './base-driver.js';
+import { PluginError } from '../../../errors.js';
 
 /**
  * Production-ready MongoDB Atlas inventory driver using mongodb-atlas-api-client.
@@ -54,7 +55,13 @@ export class MongoDBAtlasInventoryDriver extends BaseCloudDriver {
     this._organizationId = credentials.organizationId || this._organizationId;
 
     if (!this._publicKey || !this._privateKey) {
-      throw new Error('MongoDB Atlas API keys are required. Provide via credentials.publicKey/privateKey or env vars.');
+      throw new PluginError('MongoDB Atlas API keys are required. Provide via credentials.publicKey/privateKey or env vars.', {
+        pluginName: 'CloudInventoryPlugin',
+        operation: 'mongodbAtlas:initClient',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Set credentials.publicKey/privateKey or env variables MONGODB_ATLAS_PUBLIC_KEY / MONGODB_ATLAS_PRIVATE_KEY.'
+      });
     }
 
     this.logger('info', 'MongoDB Atlas credentials initialized', {

package/src/plugins/cloud-inventory/drivers/vultr-driver.js

@@ -1,4 +1,5 @@
 import { BaseCloudDriver } from './base-driver.js';
+import { PluginError } from '../../../errors.js';
 
 /**
  * Production-ready Vultr inventory driver using official @vultr/vultr-node SDK.
@@ -50,7 +51,13 @@ export class VultrInventoryDriver extends BaseCloudDriver {
     this._apiKey = credentials.apiKey || credentials.token || process.env.VULTR_API_KEY;
 
     if (!this._apiKey) {
-      throw new Error('Vultr API key is required. Provide via credentials.apiKey or VULTR_API_KEY env var.');
+      throw new PluginError('Vultr API key is required. Provide via credentials.apiKey or VULTR_API_KEY env var.', {
+        pluginName: 'CloudInventoryPlugin',
+        operation: 'vultr:initClient',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Set credentials.apiKey or the VULTR_API_KEY environment variable before initializing the driver.'
+      });
     }
 
     // Lazy import to keep core package lightweight

package/src/plugins/cloud-inventory/index.js

@@ -9,12 +9,33 @@ export {
 export {
   AwsInventoryDriver
 } from './drivers/aws-driver.js';
-
 export {
-  AwsMockDriver,
-  GcpMockDriver,
-  DigitalOceanMockDriver,
-  OracleMockDriver,
-  AzureMockDriver,
-  VultrMockDriver
-} from './drivers/mock-drivers.js';
+  GcpInventoryDriver
+} from './drivers/gcp-driver.js';
+export {
+  AzureInventoryDriver
+} from './drivers/azure-driver.js';
+export {
+  DigitalOceanInventoryDriver
+} from './drivers/digitalocean-driver.js';
+export {
+  OracleInventoryDriver
+} from './drivers/oracle-driver.js';
+export {
+  VultrInventoryDriver
+} from './drivers/vultr-driver.js';
+export {
+  LinodeInventoryDriver
+} from './drivers/linode-driver.js';
+export {
+  HetznerInventoryDriver
+} from './drivers/hetzner-driver.js';
+export {
+  AlibabaInventoryDriver
+} from './drivers/alibaba-driver.js';
+export {
+  CloudflareInventoryDriver
+} from './drivers/cloudflare-driver.js';
+export {
+  MongoDBAtlasInventoryDriver
+} from './drivers/mongodb-atlas-driver.js';

package/src/plugins/cloud-inventory/registry.js

@@ -10,20 +10,7 @@ import { HetznerInventoryDriver } from './drivers/hetzner-driver.js';
 import { AlibabaInventoryDriver } from './drivers/alibaba-driver.js';
 import { CloudflareInventoryDriver } from './drivers/cloudflare-driver.js';
 import { MongoDBAtlasInventoryDriver } from './drivers/mongodb-atlas-driver.js';
-import {
-  AwsMockDriver,
-  GcpMockDriver,
-  DigitalOceanMockDriver,
-  OracleMockDriver,
-  AzureMockDriver,
-  VultrMockDriver,
-  LinodeMockDriver,
-  HetznerMockDriver,
-  AlibabaMockDriver,
-  CloudflareMockDriver,
-  MongoDBAtlasMockDriver
-} from './drivers/mock-drivers.js';
-
+import { PluginError } from '../../errors.js';
 const CLOUD_DRIVERS = new Map();
 
 /**
@@ -33,11 +20,23 @@ const CLOUD_DRIVERS = new Map();
  */
 export function registerCloudDriver(name, factory) {
   if (!name || typeof name !== 'string') {
-    throw new Error('registerCloudDriver: name must be a non-empty string');
+    throw new PluginError('registerCloudDriver: name must be a non-empty string', {
+      pluginName: 'CloudInventoryPlugin',
+      operation: 'registry:register',
+      statusCode: 400,
+      retriable: false,
+      suggestion: 'Call registerCloudDriver with a string identifier, e.g. registerCloudDriver("aws", factory).'
+    });
   }
 
   if (typeof factory !== 'function') {
-    throw new Error(`registerCloudDriver("${name}") expects a factory function`);
+    throw new PluginError(`registerCloudDriver("${name}") expects a factory function`, {
+      pluginName: 'CloudInventoryPlugin',
+      operation: 'registry:register',
+      statusCode: 400,
+      retriable: false,
+      suggestion: 'Pass a factory function that returns an instance of BaseCloudDriver.'
+    });
   }
 
   CLOUD_DRIVERS.set(name, factory);
@@ -51,12 +50,29 @@ export function registerCloudDriver(name, factory) {
  */
 export function createCloudDriver(name, options) {
   if (!CLOUD_DRIVERS.has(name)) {
-    throw new Error(`Cloud driver "${name}" is not registered. Registered drivers: ${[...CLOUD_DRIVERS.keys()].join(', ') || 'none'}`);
+    throw new PluginError(`Cloud driver "${name}" is not registered.`, {
+      pluginName: 'CloudInventoryPlugin',
+      operation: 'registry:create',
+      statusCode: 400,
+      retriable: false,
+      suggestion: `Register the driver via registerCloudDriver before creating it. Registered drivers: ${[...CLOUD_DRIVERS.keys()].join(', ') || 'none'}`
+    });
+  }
+
+  const resolvedOptions = { ...(options || {}) };
+  if (!resolvedOptions.driver) {
+    resolvedOptions.driver = name;
   }
 
-  const driver = CLOUD_DRIVERS.get(name)(options);
+  const driver = CLOUD_DRIVERS.get(name)(resolvedOptions);
   if (!(driver instanceof BaseCloudDriver)) {
-    throw new Error(`Driver "${name}" factory must return an instance of BaseCloudDriver`);
+    throw new PluginError(`Driver "${name}" factory must return an instance of BaseCloudDriver`, {
+      pluginName: 'CloudInventoryPlugin',
+      operation: 'registry:create',
+      statusCode: 500,
+      retriable: false,
+      suggestion: 'Ensure the factory returns a class extending BaseCloudDriver.'
+    });
   }
   return driver;
 }
@@ -76,24 +92,48 @@ export function listCloudDrivers() {
  */
 export function validateCloudDefinition(cloud) {
   if (!cloud || typeof cloud !== 'object') {
-    throw new Error('Each cloud configuration must be an object');
+    throw new PluginError('Each cloud configuration must be an object', {
+      pluginName: 'CloudInventoryPlugin',
+      operation: 'registry:validateDefinition',
+      statusCode: 400,
+      retriable: false,
+      suggestion: 'Provide cloud definitions as objects (e.g. { driver: "aws", credentials: {...} }).'
+    });
   }
 
   const { driver, credentials } = cloud;
   if (!driver || typeof driver !== 'string') {
-    throw new Error('Cloud configuration requires a "driver" string');
+    throw new PluginError('Cloud configuration requires a "driver" string', {
+      pluginName: 'CloudInventoryPlugin',
+      operation: 'registry:validateDefinition',
+      statusCode: 400,
+      retriable: false,
+      suggestion: 'Set the driver field to a registered driver name.'
+    });
   }
 
   if (!CLOUD_DRIVERS.has(driver)) {
-    throw new Error(`Cloud driver "${driver}" is not registered`);
+    throw new PluginError(`Cloud driver "${driver}" is not registered`, {
+      pluginName: 'CloudInventoryPlugin',
+      operation: 'registry:validateDefinition',
+      statusCode: 400,
+      retriable: false,
+      suggestion: 'Register the driver via registerCloudDriver before referencing it in configuration.'
+    });
   }
 
   if (!credentials || typeof credentials !== 'object') {
-    throw new Error(`Cloud "${driver}" requires a credentials object`);
+    throw new PluginError(`Cloud "${driver}" requires a credentials object`, {
+      pluginName: 'CloudInventoryPlugin',
+      operation: 'registry:validateDefinition',
+      statusCode: 400,
+      retriable: false,
+      suggestion: 'Provide credentials for each cloud entry (e.g. credentials: { token: "..." }).'
+    });
   }
 }
 
-// Register a no-op driver as a placeholder / mock implementation.
+// Register a no-op driver as a placeholder implementation.
 registerCloudDriver('noop', (options = {}) => {
   class NoopDriver extends BaseCloudDriver {
     async listResources() {
@@ -107,13 +147,6 @@ registerCloudDriver('noop', (options = {}) => {
   });
 });
 
-function registerMockDriver(names, DriverClass) {
-  const list = Array.isArray(names) ? names : [names];
-  for (const name of list) {
-    registerCloudDriver(name, (options = {}) => new DriverClass(options));
-  }
-}
-
 registerCloudDriver('aws', (options = {}) => new AwsInventoryDriver(options));
 registerCloudDriver('gcp', (options = {}) => new GcpInventoryDriver(options));
 registerCloudDriver('vultr', (options = {}) => new VultrInventoryDriver(options));
@@ -131,16 +164,5 @@ registerCloudDriver('cloudflare', (options = {}) => new CloudflareInventoryDrive
 registerCloudDriver('cf', (options = {}) => new CloudflareInventoryDriver(options));
 registerCloudDriver('mongodb-atlas', (options = {}) => new MongoDBAtlasInventoryDriver(options));
 registerCloudDriver('atlas', (options = {}) => new MongoDBAtlasInventoryDriver(options));
-registerMockDriver('aws-mock', AwsMockDriver);
-registerMockDriver('gcp-mock', GcpMockDriver);
-registerMockDriver('vultr-mock', VultrMockDriver);
-registerMockDriver(['digitalocean-mock', 'do-mock'], DigitalOceanMockDriver);
-registerMockDriver(['oracle-mock', 'oci-mock'], OracleMockDriver);
-registerMockDriver(['azure-mock', 'az-mock'], AzureMockDriver);
-registerMockDriver('linode-mock', LinodeMockDriver);
-registerMockDriver('hetzner-mock', HetznerMockDriver);
-registerMockDriver(['alibaba-mock', 'aliyun-mock'], AlibabaMockDriver);
-registerMockDriver(['cloudflare-mock', 'cf-mock'], CloudflareMockDriver);
-registerMockDriver(['mongodb-atlas-mock', 'atlas-mock'], MongoDBAtlasMockDriver);
 
 export { BaseCloudDriver } from './drivers/base-driver.js';