s3db.js 11.3.2 → 12.0.0

package/src/plugins/index.js

@@ -3,16 +3,27 @@ export * from './plugin.obj.js'
 export { default as Plugin } from './plugin.class.js'
 
 // plugins:
+export * from './api/index.js'
 export * from './audit.plugin.js'
 export * from './backup.plugin.js'
 export * from './cache.plugin.js'
 export * from './costs.plugin.js'
 export * from './eventual-consistency/index.js'
 export * from './fulltext.plugin.js'
+export * from './geo.plugin.js'
 export * from './metrics.plugin.js'
 export * from './queue-consumer.plugin.js'
+export * from './relation.plugin.js'
 export * from './replicator.plugin.js'
 export * from './s3-queue.plugin.js'
 export * from './scheduler.plugin.js'
 export * from './state-machine.plugin.js'
+export * from './tfstate/index.js'
+export * from './ttl.plugin.js'
 export * from './vector.plugin.js'
+
+// plugin drivers & utilities:
+export * from './backup/index.js'
+export * from './cache/index.js'
+export * from './replicators/index.js'
+export * from './consumers/index.js'

package/src/plugins/metrics.plugin.js

@@ -10,9 +10,19 @@ export class MetricsPlugin extends Plugin {
       collectUsage: options.collectUsage !== false,
       retentionDays: options.retentionDays || 30,
       flushInterval: options.flushInterval || 60000, // 1 minute
+
+      // Prometheus configuration
+      prometheus: {
+        enabled: options.prometheus?.enabled !== false, // Enabled by default
+        mode: options.prometheus?.mode || 'auto',       // 'auto' | 'integrated' | 'standalone'
+        port: options.prometheus?.port || 9090,         // Standalone server port
+        path: options.prometheus?.path || '/metrics',   // Metrics endpoint path
+        includeResourceLabels: options.prometheus?.includeResourceLabels !== false
+      },
+
       ...options
     };
-    
+
     this.metrics = {
       operations: {
         insert: { count: 0, totalTime: 0, errors: 0 },
@@ -27,8 +37,9 @@ export class MetricsPlugin extends Plugin {
       performance: [],
       startTime: new Date().toISOString()
     };
-    
+
     this.flushTimer = null;
+    this.metricsServer = null; // Standalone HTTP server (if needed)
   }
 
   async onInstall() {
@@ -113,7 +124,8 @@ export class MetricsPlugin extends Plugin {
   }
 
   async start() {
-    // Plugin is ready
+    // Setup Prometheus metrics exporter
+    await this._setupPrometheusExporter();
   }
 
   async stop() {
@@ -122,7 +134,18 @@ export class MetricsPlugin extends Plugin {
       clearInterval(this.flushTimer);
       this.flushTimer = null;
     }
-    
+
+    // Stop standalone metrics server if running
+    if (this.metricsServer) {
+      await new Promise((resolve) => {
+        this.metricsServer.close(() => {
+          console.log('[Metrics Plugin] Standalone metrics server stopped');
+          this.metricsServer = null;
+          resolve();
+        });
+      });
+    }
+
     // Remove database hooks
     this.removeDatabaseHooks();
   }
@@ -672,6 +695,142 @@ export class MetricsPlugin extends Plugin {
       }
     }
   }
+
+  /**
+   * Get metrics in Prometheus format
+   * @returns {Promise<string>} Prometheus metrics text
+   */
+  async getPrometheusMetrics() {
+    const { formatPrometheusMetrics } = await import('./concerns/prometheus-formatter.js');
+    return formatPrometheusMetrics(this);
+  }
+
+  /**
+   * Setup Prometheus metrics exporter
+   * Chooses mode based on configuration and API Plugin availability
+   * @private
+   */
+  async _setupPrometheusExporter() {
+    if (!this.config.prometheus.enabled) {
+      return; // Prometheus export disabled
+    }
+
+    const mode = this.config.prometheus.mode;
+    const apiPlugin = this.database.plugins?.api || this.database.plugins?.ApiPlugin;
+
+    // AUTO mode: detect API Plugin
+    if (mode === 'auto') {
+      if (apiPlugin && apiPlugin.server) {
+        await this._setupIntegratedMetrics(apiPlugin);
+      } else {
+        await this._setupStandaloneMetrics();
+      }
+    }
+
+    // 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'
+        );
+      }
+      await this._setupIntegratedMetrics(apiPlugin);
+    }
+
+    // STANDALONE mode: always separate server
+    else if (mode === 'standalone') {
+      await this._setupStandaloneMetrics();
+    }
+
+    else {
+      console.warn(
+        `[Metrics Plugin] Unknown prometheus.mode="${mode}". Valid modes: auto, integrated, standalone`
+      );
+    }
+  }
+
+  /**
+   * Setup integrated metrics (uses API Plugin's server)
+   * @param {ApiPlugin} apiPlugin - API Plugin instance
+   * @private
+   */
+  async _setupIntegratedMetrics(apiPlugin) {
+    const app = apiPlugin.getApp();
+    const path = this.config.prometheus.path;
+
+    if (!app) {
+      console.error('[Metrics Plugin] Failed to get Hono app from API Plugin');
+      return;
+    }
+
+    // Add /metrics route to Hono app
+    app.get(path, async (c) => {
+      try {
+        const metrics = await this.getPrometheusMetrics();
+        return c.text(metrics, 200, {
+          'Content-Type': 'text/plain; version=0.0.4; charset=utf-8'
+        });
+      } catch (err) {
+        console.error('[Metrics Plugin] Error generating Prometheus metrics:', err);
+        return c.text('Internal Server Error', 500);
+      }
+    });
+
+    const port = apiPlugin.config?.port || 3000;
+    console.log(
+      `[Metrics Plugin] Prometheus metrics available at http://localhost:${port}${path} (integrated mode)`
+    );
+  }
+
+  /**
+   * Setup standalone metrics server (separate HTTP server)
+   * @private
+   */
+  async _setupStandaloneMetrics() {
+    const { createServer } = await import('http');
+    const port = this.config.prometheus.port;
+    const path = this.config.prometheus.path;
+
+    this.metricsServer = createServer(async (req, res) => {
+      // CORS headers to allow scraping from anywhere
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      res.setHeader('Access-Control-Allow-Methods', 'GET');
+      res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+      if (req.url === path && req.method === 'GET') {
+        try {
+          const metrics = await this.getPrometheusMetrics();
+          res.writeHead(200, {
+            'Content-Type': 'text/plain; version=0.0.4; charset=utf-8',
+            'Content-Length': Buffer.byteLength(metrics, 'utf8')
+          });
+          res.end(metrics);
+        } catch (err) {
+          console.error('[Metrics Plugin] Error generating Prometheus metrics:', err);
+          res.writeHead(500, { 'Content-Type': 'text/plain' });
+          res.end('Internal Server Error');
+        }
+      } else if (req.method === 'OPTIONS') {
+        // Handle preflight requests
+        res.writeHead(204);
+        res.end();
+      } else {
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('Not Found');
+      }
+    });
+
+    this.metricsServer.listen(port, '0.0.0.0', () => {
+      console.log(
+        `[Metrics Plugin] Prometheus metrics available at http://0.0.0.0:${port}${path} (standalone mode)`
+      );
+    });
+
+    // Handle server errors
+    this.metricsServer.on('error', (err) => {
+      console.error('[Metrics Plugin] Standalone metrics server error:', err);
+    });
+  }
 }
 
 export default MetricsPlugin; 

package/src/plugins/queue-consumer.plugin.js

@@ -35,42 +35,21 @@ export class QueueConsumerPlugin extends Plugin {
     
     for (const driverDef of this.driversConfig) {
       const { driver, config: driverConfig = {}, consumers: consumerDefs = [] } = driverDef;
-      
-      // Handle legacy format where config is mixed with driver definition
-      if (consumerDefs.length === 0 && driverDef.resources) {
-        // Legacy format: { driver: 'sqs', resources: 'users', config: {...} }
-        const { resources, driver: defDriver, config: nestedConfig, ...directConfig } = driverDef;
+
+      // Structured format: { driver: 'sqs', config: {...}, consumers: [{ resources: 'users', ... }] }
+      for (const consumerDef of consumerDefs) {
+        const { resources, ...consumerConfig } = consumerDef;
         const resourceList = Array.isArray(resources) ? resources : [resources];
-        
-        // Flatten config - prioritize nested config if it exists, otherwise use direct config
-        const flatConfig = nestedConfig ? { ...directConfig, ...nestedConfig } : directConfig;
-        
         for (const resource of resourceList) {
+          const mergedConfig = { ...driverConfig, ...consumerConfig };
           const consumer = createConsumer(driver, {
-            ...flatConfig,
+            ...mergedConfig,
             onMessage: (msg) => this._handleMessage(msg, resource),
             onError: (err, raw) => this._handleError(err, raw, resource)
           });
-          
           await consumer.start();
           this.consumers.push(consumer);
         }
-      } else {
-        // New format: { driver: 'sqs', config: {...}, consumers: [{ resources: 'users', ... }] }
-        for (const consumerDef of consumerDefs) {
-          const { resources, ...consumerConfig } = consumerDef;
-          const resourceList = Array.isArray(resources) ? resources : [resources];
-          for (const resource of resourceList) {
-            const mergedConfig = { ...driverConfig, ...consumerConfig };
-            const consumer = createConsumer(driver, {
-              ...mergedConfig,
-              onMessage: (msg) => this._handleMessage(msg, resource),
-              onError: (err, raw) => this._handleError(err, raw, resource)
-            });
-            await consumer.start();
-            this.consumers.push(consumer);
-          }
-        }
       }
     }
   }

package/src/plugins/relation.errors.js

@@ -0,0 +1,139 @@
+/**
+ * RelationPlugin Error Classes
+ * Custom errors for relation operations
+ */
+
+/**
+ * Base error for all relation operations
+ */
+export class RelationError extends Error {
+  constructor(message, context = {}) {
+    super(message);
+    this.name = 'RelationError';
+    this.context = context;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+/**
+ * Thrown when relation configuration is invalid
+ */
+export class RelationConfigError extends RelationError {
+  constructor(message, context = {}) {
+    super(message, context);
+    this.name = 'RelationConfigError';
+  }
+}
+
+/**
+ * Thrown when a relation type is not supported
+ */
+export class UnsupportedRelationTypeError extends RelationError {
+  constructor(type, context = {}) {
+    super(`Unsupported relation type: ${type}. Supported types: hasOne, hasMany, belongsTo, belongsToMany`, context);
+    this.name = 'UnsupportedRelationTypeError';
+    this.relationType = type;
+  }
+}
+
+/**
+ * Thrown when a related resource is not found
+ */
+export class RelatedResourceNotFoundError extends RelationError {
+  constructor(resourceName, context = {}) {
+    super(`Related resource "${resourceName}" not found`, context);
+    this.name = 'RelatedResourceNotFoundError';
+    this.resourceName = resourceName;
+  }
+}
+
+/**
+ * Thrown when a junction table is missing for belongsToMany
+ */
+export class JunctionTableNotFoundError extends RelationError {
+  constructor(junctionTable, context = {}) {
+    super(`Junction table "${junctionTable}" not found for belongsToMany relation`, context);
+    this.name = 'JunctionTableNotFoundError';
+    this.junctionTable = junctionTable;
+  }
+}
+
+/**
+ * Thrown when cascade operation fails
+ */
+export class CascadeError extends RelationError {
+  constructor(operation, resourceName, recordId, originalError, context = {}) {
+    super(
+      `Cascade ${operation} failed for resource "${resourceName}" record "${recordId}": ${originalError.message}`,
+      context
+    );
+    this.name = 'CascadeError';
+    this.operation = operation;
+    this.resourceName = resourceName;
+    this.recordId = recordId;
+    this.originalError = originalError;
+  }
+}
+
+/**
+ * Thrown when foreign key is missing
+ */
+export class MissingForeignKeyError extends RelationError {
+  constructor(foreignKey, resourceName, context = {}) {
+    super(`Foreign key "${foreignKey}" not found in resource "${resourceName}"`, context);
+    this.name = 'MissingForeignKeyError';
+    this.foreignKey = foreignKey;
+    this.resourceName = resourceName;
+  }
+}
+
+/**
+ * Thrown when trying to load relations on non-existent record
+ */
+export class RecordNotFoundError extends RelationError {
+  constructor(recordId, resourceName, context = {}) {
+    super(`Record "${recordId}" not found in resource "${resourceName}"`, context);
+    this.name = 'RecordNotFoundError';
+    this.recordId = recordId;
+    this.resourceName = resourceName;
+  }
+}
+
+/**
+ * Thrown when circular relation is detected
+ */
+export class CircularRelationError extends RelationError {
+  constructor(path, context = {}) {
+    super(`Circular relation detected in path: ${path.join(' -> ')}`, context);
+    this.name = 'CircularRelationError';
+    this.relationPath = path;
+  }
+}
+
+/**
+ * Thrown when include path is invalid
+ */
+export class InvalidIncludePathError extends RelationError {
+  constructor(path, reason, context = {}) {
+    super(`Invalid include path "${path}": ${reason}`, context);
+    this.name = 'InvalidIncludePathError';
+    this.includePath = path;
+    this.reason = reason;
+  }
+}
+
+/**
+ * Thrown when batch loading fails
+ */
+export class BatchLoadError extends RelationError {
+  constructor(relation, batchSize, failedCount, context = {}) {
+    super(
+      `Batch loading failed for relation "${relation}". Failed ${failedCount} out of ${batchSize} records`,
+      context
+    );
+    this.name = 'BatchLoadError';
+    this.relation = relation;
+    this.batchSize = batchSize;
+    this.failedCount = failedCount;
+  }
+}