s3db.js 13.6.0 → 14.0.2

package/src/plugins/metrics.plugin.js

@@ -575,10 +575,34 @@
 
 import { Plugin } from "./plugin.class.js";
 import tryFn from "../concerns/try-fn.js";
+import { resolveResourceNames } from "./concerns/resource-names.js";
+import { PluginError } from '../errors.js';
 
 export class MetricsPlugin extends Plugin {
   constructor(options = {}) {
     super();
+    const resourceNamesOption = options.resourceNames || {};
+    const legacyResourceOption = options.resources || {};
+    const resourceOverrides = {
+      metrics: resourceNamesOption.metrics ?? legacyResourceOption.metrics,
+      errors: resourceNamesOption.errors ?? legacyResourceOption.errors,
+      performance: resourceNamesOption.performance ?? legacyResourceOption.performance
+    };
+    this._resourceDescriptors = {
+      metrics: {
+        defaultName: 'plg_metrics',
+        override: resourceOverrides.metrics
+      },
+      errors: {
+        defaultName: 'plg_metrics_errors',
+        override: resourceOverrides.errors
+      },
+      performance: {
+        defaultName: 'plg_metrics_performance',
+        override: resourceOverrides.performance
+      }
+    };
+    this.resourceNames = this._resolveResourceNames();
     this.config = {
       collectPerformance: options.collectPerformance !== false,
       collectErrors: options.collectErrors !== false,
@@ -617,12 +641,22 @@ export class MetricsPlugin extends Plugin {
     this.metricsServer = null; // Standalone HTTP server (if needed)
   }
 
+  _resolveResourceNames() {
+    return resolveResourceNames('metrics', this._resourceDescriptors, {
+      namespace: this.namespace
+    });
+  }
+
+  onNamespaceChanged() {
+    this.resourceNames = this._resolveResourceNames();
+  }
+
   async onInstall() {
     if (typeof process !== 'undefined' && process.env.NODE_ENV === 'test') return;
 
     const [ok, err] = await tryFn(async () => {
       const [ok1, err1, metricsResource] = await tryFn(() => this.database.createResource({
-        name: 'plg_metrics',
+        name: this.resourceNames.metrics,
         attributes: {
           id: 'string|required',
           type: 'string|required', // 'operation', 'error', 'performance'
@@ -641,10 +675,12 @@ export class MetricsPlugin extends Plugin {
         },
         behavior: 'body-overflow'
       }));
-      this.metricsResource = ok1 ? metricsResource : this.database.resources.plg_metrics;
+      this.metricsResource = ok1
+        ? metricsResource
+        : this.database.resources[this.resourceNames.metrics];
 
       const [ok2, err2, errorsResource] = await tryFn(() => this.database.createResource({
-        name: 'plg_error_logs',
+        name: this.resourceNames.errors,
         attributes: {
           id: 'string|required',
           resourceName: 'string|required',
@@ -659,10 +695,12 @@ export class MetricsPlugin extends Plugin {
         },
         behavior: 'body-overflow'
       }));
-      this.errorsResource = ok2 ? errorsResource : this.database.resources.plg_error_logs;
+      this.errorsResource = ok2
+        ? errorsResource
+        : this.database.resources[this.resourceNames.errors];
 
       const [ok3, err3, performanceResource] = await tryFn(() => this.database.createResource({
-        name: 'plg_performance_logs',
+        name: this.resourceNames.performance,
         attributes: {
           id: 'string|required',
           resourceName: 'string|required',
@@ -677,13 +715,15 @@ export class MetricsPlugin extends Plugin {
         },
         behavior: 'body-overflow'
       }));
-      this.performanceResource = ok3 ? performanceResource : this.database.resources.plg_performance_logs;
+      this.performanceResource = ok3
+        ? performanceResource
+        : this.database.resources[this.resourceNames.performance];
     });
     if (!ok) {
       // Resources might already exist
-      this.metricsResource = this.database.resources.plg_metrics;
-      this.errorsResource = this.database.resources.plg_error_logs;
-      this.performanceResource = this.database.resources.plg_performance_logs;
+      this.metricsResource = this.database.resources[this.resourceNames.metrics];
+      this.errorsResource = this.database.resources[this.resourceNames.errors];
+      this.performanceResource = this.database.resources[this.resourceNames.performance];
     }
 
     // Use database hooks for automatic resource discovery
@@ -728,7 +768,7 @@ export class MetricsPlugin extends Plugin {
   installDatabaseHooks() {
     // Use the new database hooks system for automatic resource discovery
     this.database.addHook('afterCreateResource', (resource) => {
-      if (resource.name !== 'plg_metrics' && resource.name !== 'plg_error_logs' && resource.name !== 'plg_performance_logs') {
+      if (!this.isInternalResource(resource.name)) {
         this.installResourceHooks(resource);
       }
     });
@@ -739,10 +779,14 @@ export class MetricsPlugin extends Plugin {
     this.database.removeHook('afterCreateResource', this.installResourceHooks.bind(this));
   }
 
+  isInternalResource(resourceName) {
+    return Object.values(this.resourceNames).includes(resourceName);
+  }
+
   installMetricsHooks() {
     // Only hook into non-metrics resources
     for (const resource of Object.values(this.database.resources)) {
-      if (['plg_metrics', 'plg_error_logs', 'plg_performance_logs'].includes(resource.name)) {
+      if (this.isInternalResource(resource.name)) {
         continue; // Skip metrics resources to avoid recursion
       }
 
@@ -753,7 +797,7 @@ export class MetricsPlugin extends Plugin {
     this.database._createResource = this.database.createResource;
     this.database.createResource = async function (...args) {
       const resource = await this._createResource(...args);
-      if (this.plugins?.metrics && !['plg_metrics', 'plg_error_logs', 'plg_performance_logs'].includes(resource.name)) {
+      if (this.plugins?.metrics && !this.plugins.metrics.isInternalResource(resource.name)) {
         this.plugins.metrics.installResourceHooks(resource);
       }
       return resource;
@@ -1305,9 +1349,13 @@ export class MetricsPlugin extends Plugin {
     // INTEGRATED mode: requires API Plugin
     else if (mode === 'integrated') {
       if (!apiPlugin || !apiPlugin.server) {
-        throw new Error(
-          '[Metrics Plugin] prometheus.mode=integrated requires API Plugin to be active'
-        );
+        throw new PluginError('[Metrics Plugin] prometheus.mode=integrated requires API Plugin to be active', {
+          pluginName: 'MetricsPlugin',
+          operation: '_setupPrometheusExporter',
+          statusCode: 400,
+          retriable: false,
+          suggestion: 'Install and start the API plugin or switch prometheus.mode to "standalone" or "auto".'
+        });
       }
       await this._setupIntegratedMetrics(apiPlugin);
     }
@@ -1406,4 +1454,4 @@ export class MetricsPlugin extends Plugin {
       console.error('[Metrics Plugin] Standalone metrics server error:', err);
     });
   }
-} 
+} 

package/src/plugins/ml/base-model.class.js

@@ -5,6 +5,7 @@
  * Provides common functionality for training, prediction, and persistence
  */
 
+import { createRequire } from 'module';
 import {
   TrainingError,
   PredictionError,
@@ -13,11 +14,20 @@ import {
   InsufficientDataError,
   TensorFlowDependencyError
 } from '../ml.errors.js';
+import { PluginError } from '../../errors.js';
+
+const require = createRequire(import.meta.url);
 
 export class BaseModel {
   constructor(config = {}) {
     if (this.constructor === BaseModel) {
-      throw new Error('BaseModel is an abstract class and cannot be instantiated directly');
+      throw new PluginError('BaseModel is an abstract class and cannot be instantiated directly', {
+        pluginName: 'MLPlugin',
+        operation: 'baseModel:constructor',
+        statusCode: 500,
+        retriable: false,
+        suggestion: 'Extend BaseModel and instantiate the concrete subclass instead.'
+      });
     }
 
     this.config = {
@@ -68,21 +78,15 @@ export class BaseModel {
     }
 
     try {
-      // Try CommonJS require first (works in most environments)
+      // Use CommonJS require with createRequire (works reliably in both Node.js and Jest ESM mode)
+      // This avoids TensorFlow.js internal ESM compatibility issues in Jest
       this.tf = require('@tensorflow/tfjs-node');
       this._tfValidated = true;
-    } catch (requireError) {
-      // If require fails (e.g., Jest VM modules), try dynamic import
-      try {
-        const tfModule = await import('@tensorflow/tfjs-node');
-        this.tf = tfModule.default || tfModule;
-        this._tfValidated = true;
-      } catch (importError) {
-        throw new TensorFlowDependencyError(
-          'TensorFlow.js is not installed. Run: pnpm add @tensorflow/tfjs-node',
-          { originalError: importError.message }
-        );
-      }
+    } catch (error) {
+      throw new TensorFlowDependencyError(
+        'TensorFlow.js is not installed. Run: pnpm add @tensorflow/tfjs-node',
+        { originalError: error.message }
+      );
     }
   }
 
@@ -92,7 +96,13 @@ export class BaseModel {
    * @abstract
    */
   buildModel() {
-    throw new Error('buildModel() must be implemented by subclass');
+    throw new PluginError('buildModel() must be implemented by subclass', {
+      pluginName: 'MLPlugin',
+      operation: 'baseModel:buildModel',
+      statusCode: 500,
+      retriable: false,
+      suggestion: 'Override buildModel() in your model subclass to define the underlying ML architecture.'
+    });
   }
 
   /**

package/src/plugins/ml/regression-model.class.js

@@ -6,7 +6,7 @@
  */
 
 import { BaseModel } from './base-model.class.js';
-import { ModelConfigError } from '../ml.errors.js';
+import { ModelConfigError, ModelNotTrainedError } from '../ml.errors.js';
 
 export class RegressionModel extends BaseModel {
   constructor(config = {}) {

package/src/plugins/ml.errors.js

@@ -1,3 +1,5 @@
+import { PluginError } from '../errors.js';
+
 /**
  * Machine Learning Plugin Errors
  *
@@ -7,25 +9,18 @@
 /**
  * Base ML Error
  */
-export class MLError extends Error {
+export class MLError extends PluginError {
   constructor(message, context = {}) {
-    super(message);
-    this.name = 'MLError';
-    this.context = context;
-
-    // Capture stack trace
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, this.constructor);
-    }
-  }
-
-  toJSON() {
-    return {
-      name: this.name,
-      message: this.message,
-      context: this.context,
-      stack: this.stack
+    const merged = {
+      pluginName: context.pluginName || 'MLPlugin',
+      operation: context.operation || 'unknown',
+      statusCode: context.statusCode ?? 500,
+      retriable: context.retriable ?? false,
+      suggestion: context.suggestion ?? 'Review ML plugin configuration and datasets before retrying.',
+      ...context
     };
+    super(message, merged);
+    this.name = 'MLError';
   }
 }
 
@@ -35,7 +30,12 @@ export class MLError extends Error {
  */
 export class ModelConfigError extends MLError {
   constructor(message, context = {}) {
-    super(message, context);
+    super(message, {
+      statusCode: context.statusCode ?? 400,
+      retriable: context.retriable ?? false,
+      suggestion: context.suggestion ?? 'Validate layer definitions, optimizer, and loss function values.',
+      ...context
+    });
     this.name = 'ModelConfigError';
   }
 }
@@ -46,7 +46,11 @@ export class ModelConfigError extends MLError {
  */
 export class TrainingError extends MLError {
   constructor(message, context = {}) {
-    super(message, context);
+    super(message, {
+      retriable: context.retriable ?? true,
+      suggestion: context.suggestion ?? 'Inspect training logs, data shapes, and GPU availability, then retry.',
+      ...context
+    });
     this.name = 'TrainingError';
   }
 }
@@ -57,7 +61,11 @@ export class TrainingError extends MLError {
  */
 export class PredictionError extends MLError {
   constructor(message, context = {}) {
-    super(message, context);
+    super(message, {
+      retriable: context.retriable ?? true,
+      suggestion: context.suggestion ?? 'Verify the model is loaded and input tensors match the expected schema.',
+      ...context
+    });
     this.name = 'PredictionError';
   }
 }
@@ -68,7 +76,12 @@ export class PredictionError extends MLError {
  */
 export class ModelNotFoundError extends MLError {
   constructor(message, context = {}) {
-    super(message, context);
+    super(message, {
+      statusCode: 404,
+      retriable: false,
+      suggestion: context.suggestion ?? 'Train the model or load it from storage before invoking inference.',
+      ...context
+    });
     this.name = 'ModelNotFoundError';
   }
 }
@@ -79,7 +92,12 @@ export class ModelNotFoundError extends MLError {
  */
 export class ModelNotTrainedError extends MLError {
   constructor(message, context = {}) {
-    super(message, context);
+    super(message, {
+      statusCode: 409,
+      retriable: false,
+      suggestion: context.suggestion ?? 'Run train() for this model or load a trained checkpoint.',
+      ...context
+    });
     this.name = 'ModelNotTrainedError';
   }
 }
@@ -90,7 +108,12 @@ export class ModelNotTrainedError extends MLError {
  */
 export class DataValidationError extends MLError {
   constructor(message, context = {}) {
-    super(message, context);
+    super(message, {
+      statusCode: 422,
+      retriable: false,
+      suggestion: context.suggestion ?? 'Normalize input data and ensure required features are provided.',
+      ...context
+    });
     this.name = 'DataValidationError';
   }
 }
@@ -101,7 +124,12 @@ export class DataValidationError extends MLError {
  */
 export class InsufficientDataError extends MLError {
   constructor(message, context = {}) {
-    super(message, context);
+    super(message, {
+      statusCode: 400,
+      retriable: false,
+      suggestion: context.suggestion ?? 'Collect more samples, reduce batch size, or adjust minimumRecords configuration.',
+      ...context
+    });
     this.name = 'InsufficientDataError';
   }
 }
@@ -112,7 +140,11 @@ export class InsufficientDataError extends MLError {
  */
 export class TensorFlowDependencyError extends MLError {
   constructor(message = 'TensorFlow.js is not installed. Run: pnpm add @tensorflow/tfjs-node', context = {}) {
-    super(message, context);
+    super(message, {
+      retriable: false,
+      suggestion: context.suggestion ?? 'Install @tensorflow/tfjs-node or @tensorflow/tfjs to enable ML features.',
+      ...context
+    });
     this.name = 'TensorFlowDependencyError';
   }
 }

package/src/plugins/ml.plugin.js

@@ -284,7 +284,13 @@ export class MLPlugin extends Plugin {
           const mlPlugin = resource.database?._mlPlugin;
 
           if (!mlPlugin) {
-            throw new Error('MLPlugin not installed');
+            throw new MLError('MLPlugin is not installed on this database instance', {
+              pluginName: 'MLPlugin',
+              operation: 'Resource.ml accessor',
+              statusCode: 400,
+              retriable: false,
+              suggestion: 'Install MLPlugin via db.usePlugin(new MLPlugin(...)) before calling resource.ml.* methods.'
+            });
           }
 
           return {
@@ -437,7 +443,13 @@ export class MLPlugin extends Plugin {
       Resource.prototype.predict = async function(input, targetAttribute) {
         const mlPlugin = this.database?._mlPlugin;
         if (!mlPlugin) {
-          throw new Error('MLPlugin not installed');
+          throw new MLError('MLPlugin is not installed on this database instance', {
+            pluginName: 'MLPlugin',
+            operation: 'Resource.predict',
+            statusCode: 400,
+            retriable: false,
+            suggestion: 'Install MLPlugin via db.usePlugin(new MLPlugin(...)) before calling resource.predict().' 
+          });
         }
 
         return await mlPlugin._resourcePredict(this.name, input, targetAttribute);
@@ -449,7 +461,13 @@ export class MLPlugin extends Plugin {
       Resource.prototype.trainModel = async function(targetAttribute, options = {}) {
         const mlPlugin = this.database?._mlPlugin;
         if (!mlPlugin) {
-          throw new Error('MLPlugin not installed');
+          throw new MLError('MLPlugin is not installed on this database instance', {
+            pluginName: 'MLPlugin',
+            operation: 'Resource.trainModel',
+            statusCode: 400,
+            retriable: false,
+            suggestion: 'Install MLPlugin via db.usePlugin(new MLPlugin(...)) before calling resource.trainModel().' 
+          });
         }
 
         return await mlPlugin._resourceTrainModel(this.name, targetAttribute, options);
@@ -461,7 +479,13 @@ export class MLPlugin extends Plugin {
       Resource.prototype.listModels = function() {
         const mlPlugin = this.database?._mlPlugin;
         if (!mlPlugin) {
-          throw new Error('MLPlugin not installed');
+          throw new MLError('MLPlugin is not installed on this database instance', {
+            pluginName: 'MLPlugin',
+            operation: 'Resource.listModels',
+            statusCode: 400,
+            retriable: false,
+            suggestion: 'Install MLPlugin via db.usePlugin(new MLPlugin(...)) before calling resource.listModels().'
+          });
         }
 
         return mlPlugin._resourceListModels(this.name);

package/src/plugins/namespace.js

@@ -0,0 +1,210 @@
+/**
+ * Plugin Namespace Detection and Logging
+ *
+ * Provides standardized namespace detection and console warnings for all plugins.
+ *
+ * @module concerns/plugin-namespace
+ */
+
+/**
+ * List all existing namespaces for a plugin by scanning storage
+ *
+ * @param {Object} storage - Plugin storage instance
+ * @param {string} pluginPrefix - Plugin prefix (e.g., 'recon', 'scheduler', 'cache')
+ * @returns {Promise<string[]>} Array of namespace strings, sorted alphabetically
+ *
+ * @example
+ * const storage = plugin.getStorage();
+ * const namespaces = await listPluginNamespaces(storage, 'recon');
+ * // ['aggressive', 'default', 'stealth', 'uptime']
+ */
+export async function listPluginNamespaces(storage, pluginPrefix) {
+  if (!storage) {
+    return [];
+  }
+
+  try {
+    // Get base key for plugin: plugin=<pluginPrefix>/
+    const baseKey = storage.getPluginKey(null);
+
+    // List all keys under plugin prefix
+    const allKeys = await storage.list(baseKey);
+
+    // Extract unique namespaces from keys like: plugin=<pluginPrefix>/<namespace>/...
+    const namespaces = new Set();
+    const prefix = baseKey.endsWith('/') ? baseKey : `${baseKey}/`;
+
+    for (const key of allKeys) {
+      // Remove prefix and extract first segment (namespace)
+      const relativePath = key.replace(prefix, '');
+      const parts = relativePath.split('/');
+
+      if (parts.length > 0 && parts[0]) {
+        namespaces.add(parts[0]);
+      }
+    }
+
+    return Array.from(namespaces).sort();
+  } catch (error) {
+    // If no keys exist yet or storage error, return empty array
+    return [];
+  }
+}
+
+/**
+ * Emit console warnings about namespace detection and usage
+ *
+ * Standardized format for all plugins:
+ * - Lists detected namespaces (if any)
+ * - Warns which namespace is being used
+ *
+ * @param {string} pluginName - Plugin name for logging (e.g., 'ReconPlugin', 'SchedulerPlugin')
+ * @param {string} currentNamespace - The namespace being used by this instance
+ * @param {string[]} existingNamespaces - Array of detected namespaces
+ *
+ * @example
+ * warnNamespaceUsage('ReconPlugin', 'uptime', ['default', 'stealth']);
+ * // Console output:
+ * // [ReconPlugin] Detected 2 existing namespace(s): default, stealth
+ * // [ReconPlugin] Using namespace: "uptime"
+ */
+export function warnNamespaceUsage(pluginName, currentNamespace, existingNamespaces = []) {
+  if (existingNamespaces.length > 0) {
+    console.warn(
+      `[${pluginName}] Detected ${existingNamespaces.length} existing namespace(s): ${existingNamespaces.join(', ')}`
+    );
+  }
+
+  const namespaceDisplay = currentNamespace === '' ? '(none)' : `"${currentNamespace}"`;
+  console.warn(`[${pluginName}] Using namespace: ${namespaceDisplay}`);
+}
+
+/**
+ * Complete namespace detection and warning flow
+ *
+ * Convenience method that combines listing and warning in one call.
+ *
+ * @param {Object} storage - Plugin storage instance
+ * @param {string} pluginName - Plugin name for logging
+ * @param {string} pluginPrefix - Plugin prefix for storage scanning
+ * @param {string} currentNamespace - The namespace being used
+ * @returns {Promise<string[]>} Array of detected namespaces
+ *
+ * @example
+ * const namespaces = await detectAndWarnNamespaces(
+ *   plugin.getStorage(),
+ *   'ReconPlugin',
+ *   'recon',
+ *   'uptime'
+ * );
+ * // Console output:
+ * // [ReconPlugin] Detected 2 existing namespace(s): default, stealth
+ * // [ReconPlugin] Using namespace: "uptime"
+ * // Returns: ['default', 'stealth']
+ */
+export async function detectAndWarnNamespaces(storage, pluginName, pluginPrefix, currentNamespace) {
+  const existingNamespaces = await listPluginNamespaces(storage, pluginPrefix);
+  warnNamespaceUsage(pluginName, currentNamespace, existingNamespaces);
+  return existingNamespaces;
+}
+
+/**
+ * Get namespaced resource name
+ *
+ * Generates consistent resource names across all plugins.
+ * Pattern: plg_<namespace>_<plugin>_<resource>
+ * Empty namespace: plg_<plugin>_<resource>
+ *
+ * @param {string} baseResourceName - Base resource name (e.g., 'plg_recon_hosts')
+ * @param {string} namespace - Namespace to apply (empty string = no namespace)
+ * @param {string} pluginPrefix - Plugin prefix (e.g., 'plg_recon')
+ * @returns {string} Namespaced resource name
+ *
+ * @example
+ * getNamespacedResourceName('plg_recon_hosts', '', 'plg_recon');
+ * // 'plg_recon_hosts'
+ *
+ * getNamespacedResourceName('plg_recon_hosts', 'uptime', 'plg_recon');
+ * // 'plg_uptime_recon_hosts'
+ *
+ * getNamespacedResourceName('plg_scheduler_jobs', 'prod', 'plg_scheduler');
+ * // 'plg_prod_scheduler_jobs'
+ */
+export function getNamespacedResourceName(baseResourceName, namespace, pluginPrefix) {
+  if (!namespace) {
+    return baseResourceName;
+  }
+
+  // Insert namespace after 'plg_' prefix
+  // Example: 'plg_recon_hosts' → 'plg_uptime_recon_hosts'
+  return baseResourceName.replace('plg_', `plg_${namespace}_`);
+}
+
+/**
+ * Validate namespace string
+ *
+ * Ensures namespace follows naming conventions:
+ * - Alphanumeric + hyphens + underscores only
+ * - 1-50 characters
+ * - Empty string is allowed (no namespace)
+ *
+ * @param {string} namespace - Namespace to validate
+ * @throws {Error} If namespace is invalid
+ *
+ * @example
+ * validateNamespace('uptime');        // OK
+ * validateNamespace('client-acme');   // OK
+ * validateNamespace('prod_env_2');    // OK
+ * validateNamespace('');              // OK (no namespace)
+ * validateNamespace('invalid space'); // Throws
+ * validateNamespace('a'.repeat(51));  // Throws
+ */
+export function validateNamespace(namespace) {
+  // Empty string is allowed (no namespace)
+  if (namespace === '') {
+    return;
+  }
+
+  if (!namespace || typeof namespace !== 'string') {
+    throw new Error('Namespace must be a string');
+  }
+
+  if (namespace.length > 50) {
+    throw new Error('Namespace must be 50 characters or less');
+  }
+
+  // Allow alphanumeric, hyphens, and underscores only
+  const validPattern = /^[a-zA-Z0-9_-]+$/;
+  if (!validPattern.test(namespace)) {
+    throw new Error(
+      'Namespace can only contain alphanumeric characters, hyphens, and underscores'
+    );
+  }
+}
+
+/**
+ * Get namespace from config with validation
+ *
+ * Extracts and validates namespace from plugin config.
+ * Defaults to empty string if not specified (no namespace).
+ *
+ * @param {Object} config - Plugin configuration
+ * @param {string} defaultNamespace - Default namespace if not specified (default: '')
+ * @returns {string} Validated namespace
+ * @throws {Error} If namespace is invalid
+ *
+ * @example
+ * getValidatedNamespace({ namespace: 'uptime' });
+ * // 'uptime'
+ *
+ * getValidatedNamespace({});
+ * // ''
+ *
+ * getValidatedNamespace({ namespace: 'invalid space' });
+ * // Throws Error
+ */
+export function getValidatedNamespace(config = {}, defaultNamespace = '') {
+  const namespace = (config.namespace !== undefined && config.namespace !== null) ? config.namespace : defaultNamespace;
+  validateNamespace(namespace);
+  return namespace;
+}