@intranefr/superbackend 1.5.1 → 1.5.2

package/src/helpers/scriptRunner.js

@@ -0,0 +1,335 @@
+const { ScriptBase } = require('./scriptBase');
+
+/**
+ * Utility for running scripts with proper error handling and cleanup
+ * Provides CLI wrapper functionality and execution management
+ */
+class ScriptRunner {
+  /**
+   * Run a script class or function
+   * @param {Function|ScriptBase} ScriptClass - Script class or function
+   * @param {Object} options - Execution options
+   * @returns {Promise<any>} Script result
+   */
+  static async run(ScriptClass, options = {}) {
+    let script;
+    
+    try {
+      // Handle different script types
+      script = ScriptRunner._createScriptInstance(ScriptClass, options);
+      
+      // Validate script before running
+      const validation = script.validate();
+      if (!validation.valid) {
+        throw new Error(`Script validation failed: ${validation.errors.join(', ')}`);
+      }
+      
+      // Log warnings if any
+      if (validation.warnings.length > 0) {
+        validation.warnings.forEach(warning => {
+          console.warn(`[ScriptRunner] Warning: ${warning}`);
+        });
+      }
+
+      return await script.run();
+    } catch (error) {
+      console.error('[ScriptRunner] Execution failed:', error.message);
+      
+      if (script) {
+        await script.cleanup(script.context);
+      }
+      
+      throw error;
+    }
+  }
+
+  /**
+   * Create script instance from various input types
+   * @private
+   * @param {Function|ScriptBase} ScriptClass - Script class or function
+   * @param {Object} options - Options for script creation
+   * @returns {ScriptBase} Script instance
+   */
+  static _createScriptInstance(ScriptClass, options = {}) {
+    // Handle plain async functions
+    if (typeof ScriptClass === 'function' && !ScriptBase.prototype.isPrototypeOf(ScriptClass.prototype)) {
+      // Wrap the function in a ScriptBase class
+      const WrappedScript = class extends ScriptBase {
+        async execute(context) {
+          return await ScriptClass(context, options);
+        }
+      };
+      
+      return new WrappedScript(options);
+    }
+    
+    // Handle ScriptBase classes
+    if (typeof ScriptClass === 'function' && ScriptBase.prototype.isPrototypeOf(ScriptClass.prototype)) {
+      return new ScriptClass(options);
+    }
+    
+    // Handle ScriptBase instances
+    if (ScriptBase.prototype.isPrototypeOf(ScriptClass)) {
+      return ScriptClass;
+    }
+    
+    throw new Error('Invalid script type: must be a function, ScriptBase class, or ScriptBase instance');
+  }
+
+  /**
+   * Create a CLI wrapper for scripts
+   * @param {Function|ScriptBase} ScriptClass - Script class or function
+   * @param {Object} defaultOptions - Default options
+   * @returns {Function} CLI-ready function
+   */
+  static createCli(ScriptClass, defaultOptions = {}) {
+    return async (options = {}) => {
+      const mergedOptions = { ...defaultOptions, ...options };
+      
+      // Handle CLI execution
+      if (require.main === module) {
+        try {
+          // Parse command line arguments if provided
+          const cliOptions = ScriptRunner._parseCliArgs();
+          const finalOptions = { ...mergedOptions, ...cliOptions };
+          
+          await ScriptRunner.run(ScriptClass, finalOptions);
+          console.log('✅ Script completed successfully');
+          process.exit(0);
+        } catch (error) {
+          console.error('❌ Script failed:', error.message);
+          
+          // Show stack trace in debug mode
+          if (process.env.DEBUG || process.env.NODE_ENV === 'development') {
+            console.error(error.stack);
+          }
+          
+          process.exit(1);
+        }
+      } else {
+        // Return result when required as module
+        return await ScriptRunner.run(ScriptClass, mergedOptions);
+      }
+    };
+  }
+
+  /**
+   * Parse command line arguments
+   * @private
+   * @returns {Object} Parsed arguments
+   */
+  static _parseCliArgs() {
+    const args = process.argv.slice(2);
+    const options = {};
+    
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
+      
+      // Handle --key=value or --key value format
+      if (arg.startsWith('--')) {
+        const equalsIndex = arg.indexOf('=');
+        
+        if (equalsIndex > 0) {
+          // --key=value format
+          const key = arg.substring(2, equalsIndex);
+          const value = arg.substring(equalsIndex + 1);
+          options[key] = ScriptRunner._parseValue(value);
+        } else {
+          // --key value format
+          const key = arg.substring(2);
+          
+          if (i + 1 < args.length && !args[i + 1].startsWith('--')) {
+            const value = args[i + 1];
+            options[key] = ScriptRunner._parseValue(value);
+            i++; // Skip next argument as it's a value
+          } else {
+            // Boolean flag
+            options[key] = true;
+          }
+        }
+      }
+    }
+    
+    return options;
+  }
+
+  /**
+   * Parse string value to appropriate type
+   * @private
+   * @param {string} value - String value to parse
+   * @returns {any} Parsed value
+   */
+  static _parseValue(value) {
+    // Try parsing as JSON
+    try {
+      return JSON.parse(value);
+    } catch {
+      // Fallback to string
+      return value;
+    }
+  }
+
+  /**
+   * Create a batch script runner for multiple scripts
+   * @param {Array} scripts - Array of script configurations
+   * @param {Object} options - Batch options
+   * @returns {Function} Batch runner function
+   */
+  static createBatch(scripts, options = {}) {
+    const { 
+      stopOnError = true, 
+      parallel = false, 
+      maxConcurrency = 3 
+    } = options;
+
+    return async (runOptions = {}) => {
+      const results = [];
+      const errors = [];
+      
+      console.log(`[BatchRunner] Running ${scripts.length} scripts (${parallel ? 'parallel' : 'sequential'})`);
+      
+      if (parallel) {
+        // Run scripts in parallel with concurrency limit
+        const chunks = ScriptRunner._chunkArray(scripts, maxConcurrency);
+        
+        for (const chunk of chunks) {
+          const chunkPromises = chunk.map(async (scriptConfig, index) => {
+            try {
+              const { script, options: scriptOptions } = scriptConfig;
+              const result = await ScriptRunner.run(script, { ...runOptions, ...scriptOptions });
+              return { index, result, error: null };
+            } catch (error) {
+              return { index, result: null, error };
+            }
+          });
+          
+          const chunkResults = await Promise.all(chunkPromises);
+          
+          for (const { index, result, error } of chunkResults) {
+            if (error) {
+              errors.push({ index, error });
+              if (stopOnError) {
+                throw error;
+              }
+            } else {
+              results[index] = result;
+            }
+          }
+        }
+      } else {
+        // Run scripts sequentially
+        for (let i = 0; i < scripts.length; i++) {
+          const { script, options: scriptOptions } = scripts[i];
+          
+          try {
+            console.log(`[BatchRunner] Running script ${i + 1}/${scripts.length}`);
+            const result = await ScriptRunner.run(script, { ...runOptions, ...scriptOptions });
+            results.push(result);
+          } catch (error) {
+            errors.push({ index: i, error });
+            if (stopOnError) {
+              throw error;
+            }
+          }
+        }
+      }
+      
+      return { results, errors };
+    };
+  }
+
+  /**
+   * Split array into chunks
+   * @private
+   * @param {Array} array - Array to split
+   * @param {number} size - Chunk size
+   * @returns {Array} Array of chunks
+   */
+  static _chunkArray(array, size) {
+    const chunks = [];
+    for (let i = 0; i < array.length; i += size) {
+      chunks.push(array.slice(i, i + size));
+    }
+    return chunks;
+  }
+
+  /**
+   * Create a scheduled script runner
+   * @param {Function|ScriptBase} ScriptClass - Script to run
+   * @param {Object} schedule - Schedule configuration
+   * @returns {Object} Scheduled runner
+   */
+  static createScheduled(ScriptClass, schedule = {}) {
+    const { 
+      interval, 
+      cron, 
+      maxRuns = null, 
+      runOnStart = false 
+    } = schedule;
+
+    let runCount = 0;
+    let timer = null;
+
+    const scheduledRunner = {
+      isRunning: false,
+      start() {
+        if (this.isRunning) {
+          throw new Error('Scheduled runner is already running');
+        }
+
+        this.isRunning = true;
+        
+        if (runOnStart) {
+          this.runScript();
+        }
+
+        if (interval) {
+          timer = setInterval(() => this.runScript(), interval);
+        } else if (cron) {
+          // Note: Would need a cron library implementation
+          throw new Error('Cron scheduling not implemented yet');
+        } else {
+          throw new Error('Must specify either interval or cron schedule');
+        }
+      },
+
+      stop() {
+        if (timer) {
+          clearInterval(timer);
+          timer = null;
+        }
+        this.isRunning = false;
+      },
+
+      async runScript() {
+        if (maxRuns && runCount >= maxRuns) {
+          console.log('[ScheduledRunner] Maximum runs reached, stopping');
+          this.stop();
+          return;
+        }
+
+        try {
+          runCount++;
+          console.log(`[ScheduledRunner] Run #${runCount}`);
+          await ScriptRunner.run(ScriptClass);
+        } catch (error) {
+          console.error('[ScheduledRunner] Scheduled run failed:', error);
+        }
+      },
+
+      getStatus() {
+        return {
+          isRunning: this.isRunning,
+          runCount,
+          maxRuns,
+          interval,
+          cron
+        };
+      }
+    };
+
+    return scheduledRunner;
+  }
+}
+
+module.exports = { ScriptRunner };

package/src/middleware.js

@@ -1,10 +1,20 @@
 const consoleOverride = require("./services/consoleOverride.service");
-const consoleManager = require("./services/consoleManager.service");
+const { consoleManager } = require("./services/consoleManager.service");
 
 // Initialize console override service early to capture all logs
 // Avoid keeping timers/streams alive during Jest runs.
 if (process.env.NODE_ENV !== "test" && !process.env.JEST_WORKER_ID) {
   consoleOverride.init()
+  
+  // Initialize console manager after a short delay to ensure consoleOverride is fully set up
+  setTimeout(() => {
+    // Set module prefix for this middleware
+    consoleManager.setModulePrefix('middleware');
+    
+    // Initialize console manager early to enable prefixing for all subsequent logs
+    consoleManager.init();
+    console.log("[Console Manager] Initialized - prefixing enabled");
+  }, 20);
 }
 
 const express = require("express");
@@ -119,6 +129,11 @@ function createMiddleware(options = {}) {
       attachTerminalWebsocketServer,
     } = require("./services/terminalsWs.service");
     attachTerminalWebsocketServer(server, { basePathPrefix: adminPath });
+
+    const {
+      attachExperimentsWebsocketServer,
+    } = require("./services/experimentsWs.service");
+    attachExperimentsWebsocketServer(server);
   };
 
   if (!errorCaptureInitialized) {
@@ -156,17 +171,10 @@ function createMiddleware(options = {}) {
         await healthChecksScheduler.start();
         await healthChecksBootstrap.bootstrap();
         await blogCronsBootstrap.bootstrap();
+        await require("./services/experimentsCronsBootstrap.service").bootstrap();
         
-        // Initialize console manager AFTER database is connected
-        if (process.env.NODE_ENV !== "test" && !process.env.JEST_WORKER_ID) {
-          const consoleManagerEnabled = await isConsoleManagerEnabled();
-          if (consoleManagerEnabled) {
-            consoleManager.init();
-            console.log("[Console Manager] Initialized");
-          } else {
-            console.log("[Console Manager] Disabled - console methods not overridden");
-          }
-        }
+        // Console manager is already initialized early in the middleware
+        console.log("[Console Manager] MongoDB connection established");
         
         return true;
       })
@@ -254,12 +262,20 @@ function createMiddleware(options = {}) {
     blogCronsBootstrap.bootstrap().catch((err) => {
       console.error("Failed to bootstrap blog crons:", err);
     });
+
+    require("./services/experimentsCronsBootstrap.service")
+      .bootstrap()
+      .catch((err) => {
+        console.error("Failed to bootstrap experiments crons:", err);
+      });
     
     // Initialize console manager AFTER database is already connected
     if (process.env.NODE_ENV !== "test" && !process.env.JEST_WORKER_ID) {
       isConsoleManagerEnabled().then(consoleManagerEnabled => {
         if (consoleManagerEnabled) {
           consoleManager.init();
+          // Set module prefix after initialization
+          consoleManager.setModulePrefix('middleware');
           console.log("[Console Manager] Initialized");
         } else {
           console.log("[Console Manager] Disabled - console methods not overridden");
@@ -268,6 +284,8 @@ function createMiddleware(options = {}) {
         console.error("[Console Manager] Error checking enabled status:", error);
         console.log("[Console Manager] Fallback to enabled due to error");
         consoleManager.init();
+        // Set module prefix after initialization
+        consoleManager.setModulePrefix('middleware');
         console.log("[Console Manager] Initialized (fallback)");
       });
     }
@@ -467,6 +485,37 @@ function createMiddleware(options = {}) {
     });
   });
 
+  router.get(`${adminPath}/experiments`, basicAuth, (req, res) => {
+    const templatePath = path.join(
+      __dirname,
+      "..",
+      "views",
+      "admin-experiments.ejs",
+    );
+    fs.readFile(templatePath, "utf8", (err, template) => {
+      if (err) {
+        console.error("Error reading template:", err);
+        return res.status(500).send("Error loading page");
+      }
+      try {
+        const html = ejs.render(
+          template,
+          {
+            baseUrl: req.baseUrl,
+            adminPath,
+          },
+          {
+            filename: templatePath,
+          },
+        );
+        res.send(html);
+      } catch (renderErr) {
+        console.error("Error rendering template:", renderErr);
+        res.status(500).send("Error rendering page");
+      }
+    });
+  });
+
   router.get(`${adminPath}/rbac`, basicAuth, (req, res) => {
     const templatePath = path.join(__dirname, "..", "views", "admin-rbac.ejs");
     fs.readFile(templatePath, "utf8", (err, template) => {
@@ -677,6 +726,7 @@ function createMiddleware(options = {}) {
     require("./routes/adminDbBrowser.routes"),
   );
   router.use("/api/admin/terminals", require("./routes/adminTerminals.routes"));
+  router.use("/api/admin/experiments", require("./routes/adminExperiments.routes"));
   router.use("/api/admin/assets", require("./routes/adminAssets.routes"));
   router.use(
     "/api/admin/upload-namespaces",
@@ -724,6 +774,7 @@ function createMiddleware(options = {}) {
   router.use("/api/ui-components", require("./routes/uiComponentsPublic.routes"));
   router.use("/api/rbac", require("./routes/rbac.routes"));
   router.use("/api/file-manager", require("./routes/fileManager.routes"));
+  router.use("/api/experiments", require("./routes/experiments.routes"));
 
   // Public blog APIs (headless)
   router.use("/api", require("./routes/blogPublic.routes"));
@@ -731,6 +782,9 @@ function createMiddleware(options = {}) {
   // Internal blog endpoints (used by HTTP CronJobs)
   router.use("/api/internal", require("./routes/blogInternal.routes"));
 
+  // Internal experiments endpoints (used by HTTP CronJobs)
+  router.use("/api/internal", require("./routes/internalExperiments.routes"));
+
   // Public health checks status (gated by global setting)
   router.use(
     "/api/health-checks",

package/src/models/CacheEntry.js

@@ -10,7 +10,7 @@ const cacheEntrySchema = new mongoose.Schema(
 
     sizeBytes: { type: Number, default: 0 },
 
-    expiresAt: { type: Date, default: null, index: true },
+    expiresAt: { type: Date, default: null },
 
     hits: { type: Number, default: 0 },
     lastAccessAt: { type: Date, default: null },

package/src/models/ConsoleLog.js

@@ -12,7 +12,7 @@ const consoleLogSchema = new mongoose.Schema(
     requestId: { type: String, default: '', index: true },
 
     createdAt: { type: Date, default: Date.now, index: true },
-    expiresAt: { type: Date, default: null, index: true },
+    expiresAt: { type: Date, default: null },
   },
   { timestamps: false, collection: 'console_logs' },
 );

package/src/models/Experiment.js

@@ -0,0 +1,75 @@
+const mongoose = require('mongoose');
+
+const experimentVariantSchema = new mongoose.Schema(
+  {
+    key: { type: String, required: true },
+    weight: { type: Number, default: 0 },
+    configSlug: { type: String, default: '' },
+  },
+  { _id: false },
+);
+
+const metricDefinitionSchema = new mongoose.Schema(
+  {
+    key: { type: String, required: true },
+    kind: { type: String, enum: ['count', 'sum', 'avg', 'rate'], default: 'count' },
+    numeratorEventKey: { type: String, default: '' },
+    denominatorEventKey: { type: String, default: '' },
+    objective: { type: String, enum: ['maximize', 'minimize'], default: 'maximize' },
+  },
+  { _id: false },
+);
+
+const winnerPolicySchema = new mongoose.Schema(
+  {
+    mode: { type: String, enum: ['manual', 'automatic'], default: 'manual' },
+    pickAfterMs: { type: Number, default: 0 },
+    minAssignments: { type: Number, default: 0 },
+    minExposures: { type: Number, default: 0 },
+    minConversions: { type: Number, default: 0 },
+    statMethod: { type: String, enum: ['simple_rate', 'bayesian_beta'], default: 'simple_rate' },
+    overrideWinnerVariantKey: { type: String, default: '' },
+  },
+  { _id: false },
+);
+
+const experimentSchema = new mongoose.Schema(
+  {
+    organizationId: { type: mongoose.Schema.Types.ObjectId, ref: 'Organization', default: null, index: true },
+
+    code: { type: String, required: true },
+    name: { type: String, default: '' },
+    description: { type: String, default: '' },
+
+    status: { type: String, enum: ['draft', 'running', 'paused', 'completed'], default: 'draft', index: true },
+
+    startedAt: { type: Date, default: null },
+    endsAt: { type: Date, default: null },
+
+    assignment: {
+      unit: { type: String, enum: ['subjectId'], default: 'subjectId' },
+      sticky: { type: Boolean, default: true },
+      salt: { type: String, default: '' },
+    },
+
+    variants: { type: [experimentVariantSchema], default: [] },
+
+    primaryMetric: { type: metricDefinitionSchema, required: true },
+    secondaryMetrics: { type: [metricDefinitionSchema], default: [] },
+
+    winnerPolicy: { type: winnerPolicySchema, default: () => ({}) },
+
+    winnerVariantKey: { type: String, default: '' },
+    winnerDecidedAt: { type: Date, default: null },
+    winnerReason: { type: String, default: '' },
+
+    createdByUserId: { type: mongoose.Schema.Types.ObjectId, ref: 'User', default: null },
+    updatedByUserId: { type: mongoose.Schema.Types.ObjectId, ref: 'User', default: null },
+  },
+  { timestamps: true, collection: 'experiments' },
+);
+
+experimentSchema.index({ organizationId: 1, code: 1 }, { unique: true });
+experimentSchema.index({ status: 1, startedAt: 1 });
+
+module.exports = mongoose.models.Experiment || mongoose.model('Experiment', experimentSchema);

package/src/models/ExperimentAssignment.js

@@ -0,0 +1,23 @@
+const mongoose = require('mongoose');
+
+const experimentAssignmentSchema = new mongoose.Schema(
+  {
+    experimentId: { type: mongoose.Schema.Types.ObjectId, ref: 'Experiment', required: true, index: true },
+    organizationId: { type: mongoose.Schema.Types.ObjectId, ref: 'Organization', default: null, index: true },
+
+    subjectKey: { type: String, required: true },
+
+    variantKey: { type: String, required: true },
+    assignedAt: { type: Date, default: () => new Date() },
+
+    context: { type: mongoose.Schema.Types.Mixed, default: {} },
+  },
+  { timestamps: true, collection: 'experiment_assignments' },
+);
+
+experimentAssignmentSchema.index({ experimentId: 1, subjectKey: 1 }, { unique: true });
+experimentAssignmentSchema.index({ organizationId: 1, subjectKey: 1 });
+
+module.exports =
+  mongoose.models.ExperimentAssignment ||
+  mongoose.model('ExperimentAssignment', experimentAssignmentSchema);

package/src/models/ExperimentEvent.js

@@ -0,0 +1,26 @@
+const mongoose = require('mongoose');
+
+const experimentEventSchema = new mongoose.Schema(
+  {
+    experimentId: { type: mongoose.Schema.Types.ObjectId, ref: 'Experiment', required: true, index: true },
+    organizationId: { type: mongoose.Schema.Types.ObjectId, ref: 'Organization', default: null, index: true },
+
+    subjectKey: { type: String, required: true },
+
+    variantKey: { type: String, required: true, index: true },
+
+    eventKey: { type: String, required: true, index: true },
+    value: { type: Number, default: 1 },
+
+    ts: { type: Date, required: true, index: true },
+
+    meta: { type: mongoose.Schema.Types.Mixed, default: {} },
+  },
+  { timestamps: true, collection: 'experiment_events' },
+);
+
+experimentEventSchema.index({ experimentId: 1, ts: 1 });
+experimentEventSchema.index({ organizationId: 1, ts: 1 });
+experimentEventSchema.index({ experimentId: 1, eventKey: 1, ts: 1 });
+
+module.exports = mongoose.models.ExperimentEvent || mongoose.model('ExperimentEvent', experimentEventSchema);

package/src/models/ExperimentMetricBucket.js

@@ -0,0 +1,30 @@
+const mongoose = require('mongoose');
+
+const experimentMetricBucketSchema = new mongoose.Schema(
+  {
+    experimentId: { type: mongoose.Schema.Types.ObjectId, ref: 'Experiment', required: true, index: true },
+    organizationId: { type: mongoose.Schema.Types.ObjectId, ref: 'Organization', default: null, index: true },
+
+    variantKey: { type: String, required: true, index: true },
+    metricKey: { type: String, required: true, index: true },
+
+    bucketStart: { type: Date, required: true, index: true },
+    bucketMs: { type: Number, required: true },
+
+    count: { type: Number, default: 0 },
+    sum: { type: Number, default: 0 },
+    sumSq: { type: Number, default: 0 },
+    min: { type: Number, default: null },
+    max: { type: Number, default: null },
+  },
+  { timestamps: true, collection: 'experiment_metric_buckets' },
+);
+
+experimentMetricBucketSchema.index(
+  { experimentId: 1, variantKey: 1, metricKey: 1, bucketStart: 1, bucketMs: 1 },
+  { unique: true },
+);
+
+module.exports =
+  mongoose.models.ExperimentMetricBucket ||
+  mongoose.model('ExperimentMetricBucket', experimentMetricBucketSchema);

package/src/models/GlobalSetting.js

@@ -4,8 +4,7 @@ const globalSettingSchema = new mongoose.Schema({
   key: {
     type: String,
     required: true,
-    unique: true,
-    index: true
+    unique: true
   },
   value: {
     type: String,

package/src/models/RateLimitCounter.js

@@ -8,7 +8,7 @@ const rateLimitCounterSchema = new mongoose.Schema(
 
     count: { type: Number, default: 0 },
 
-    expiresAt: { type: Date, default: null, index: true },
+    expiresAt: { type: Date, default: null },
   },
   { timestamps: true, collection: 'rate_limit_counters' },
 );

package/src/models/ScriptDefinition.js

@@ -16,6 +16,7 @@ const scriptDefinitionSchema = new mongoose.Schema(
     type: { type: String, enum: ['bash', 'node', 'browser'], required: true },
     runner: { type: String, enum: ['host', 'vm2', 'browser'], required: true },
     script: { type: String, required: true },
+    scriptFormat: { type: String, enum: ['string', 'base64'], default: 'string' },
     defaultWorkingDirectory: { type: String, default: '' },
     env: { type: [envVarSchema], default: [] },
     timeoutMs: { type: Number, default: 5 * 60 * 1000 },