lumisjs 1.0.0

package/src/client/ShardingManager.js

@@ -0,0 +1,274 @@
+'use strict';
+
+const { EventEmitter } = require('node:events');
+const { fork } = require('node:child_process');
+const path = require('node:path');
+const Logger = require('../utils/Logger');
+const Collection = require('../utils/Collection');
+
+class ShardingManager extends EventEmitter {
+  /**
+   * @param {string} file - Path to the bot's main file
+   * @param {object} [options]
+   * @param {string} [options.token] - Bot token (used to fetch shard count)
+   * @param {number|'auto'} [options.totalShards='auto']
+   * @param {string[]} [options.execArgv]
+   * @param {number} [options.spawnDelay=5500] - ms delay between shard spawns
+   * @param {number} [options.respawnDelay=5000] - ms before crashed shard respawns
+   * @param {number} [options.maxRespawnAttempts=5]
+   */
+  constructor(file, options = {}) {
+    super();
+
+    if (!file || typeof file !== 'string') {
+      throw new TypeError('ShardingManager requires a valid file path.');
+    }
+
+    this.file = path.resolve(file);
+    this.token = options.token ? options.token.replace(/^Bot\s*/i, '') : null;
+    this.totalShards = options.totalShards ?? 'auto';
+    this.execArgv = options.execArgv ?? [];
+    this.autoFetchShards = options.autoFetchShards ?? true;
+    this.spawnDelay = options.spawnDelay ?? 5500;
+    this.respawnDelay = options.respawnDelay ?? 5000;
+    this.maxRespawnAttempts = options.maxRespawnAttempts ?? 5;
+
+    /** @type {Collection<number, import('node:child_process').ChildProcess>} */
+    this.shards = new Collection();
+
+    this.logger = new Logger({ prefix: 'ShardingManager', level: 'info' });
+
+    /** @type {Map<string, { resolve: Function, reject: Function, timer: NodeJS.Timeout }>} */
+    this._promises = new Map();
+    this._nonce = 0;
+
+    /** @type {Map<number, number>} */
+    this._respawnCounts = new Map();
+  }
+
+  /**
+   * Fetch the recommended shard count from Discord.
+   * @returns {Promise<number>}
+   */
+  async fetchRecommendedShards() {
+    if (!this.token) {
+      throw new Error('A token is required to fetch the recommended shard count.');
+    }
+
+    const { fetch } = require('undici');
+
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 5000);
+
+      const res = await fetch('https://discord.com/api/v10/gateway/bot', {
+        headers: { Authorization: `Bot ${this.token}` },
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeout);
+
+      if (!res.ok) {
+        throw new Error(`Failed to fetch gateway info: ${res.status} ${res.statusText}`);
+      }
+
+      const data = await res.json();
+
+      if (!data || typeof data.shards !== 'number' || data.shards < 1) {
+        throw new Error('Invalid shard data received from gateway.');
+      }
+
+      return data.shards;
+    } catch (err) {
+      // Provide actionable message while keeping original error available
+      throw new Error(`Could not determine recommended shard count: ${err.message}`);
+    }
+  }
+
+  /**
+   * Spawn all shards sequentially.
+   * @returns {Promise<void>}
+   */
+  async spawn() {
+    if (this.totalShards === 'auto') {
+      if (!this.autoFetchShards) {
+        throw new Error(
+          "totalShards is set to 'auto' but autoFetchShards is disabled. Provide totalShards explicitly."
+        );
+      }
+
+      this.logger.info('Fetching recommended shard count from Discord...');
+      this.totalShards = await this.fetchRecommendedShards();
+      this.logger.info(`Recommended shard count: ${this.totalShards}`);
+    }
+
+    if (typeof this.totalShards !== 'number' || this.totalShards < 1) {
+      throw new RangeError('totalShards must be a positive integer.');
+    }
+
+    this.logger.info(`Spawning ${this.totalShards} shard(s)...`);
+
+    for (let i = 0; i < this.totalShards; i++) {
+      this._spawnShard(i);
+      if (i < this.totalShards - 1) {
+        // Discord requires a delay between shard connections to avoid rate limits
+        await new Promise((r) => setTimeout(r, this.spawnDelay));
+      }
+    }
+  }
+
+  /**
+   * Spawn a single shard by ID.
+   * @param {number} id
+   */
+  _spawnShard(id) {
+    this.logger.info(`[Shard ${id}] Spawning...`);
+
+    const env = {
+      ...process.env,
+      SHARD_ID: String(id),
+      TOTAL_SHARDS: String(this.totalShards),
+      ...(this.token ? { DISCORD_TOKEN: this.token } : {}),
+    };
+
+    const child = fork(this.file, [], {
+      env,
+      execArgv: this.execArgv,
+    });
+
+    this.shards.set(id, child);
+
+    child.on('message', (message) => this._handleMessage(child, message, id));
+
+    child.on('exit', (code, signal) => {
+      this.shards.delete(id);
+
+      const attempts = this._respawnCounts.get(id) ?? 0;
+
+      if (attempts >= this.maxRespawnAttempts) {
+        this.logger.error(
+          `[Shard ${id}] Reached max respawn attempts (${this.maxRespawnAttempts}). Giving up.`
+        );
+        this.emit('shardDeath', id);
+        return;
+      }
+
+      this.logger.warn(
+        `[Shard ${id}] Exited (code=${code ?? 'null'}, signal=${signal ?? 'null'}). ` +
+          `Respawning in ${this.respawnDelay}ms (${attempts + 1}/${this.maxRespawnAttempts})...`
+      );
+
+      this._respawnCounts.set(id, attempts + 1);
+
+      setTimeout(() => {
+        this._spawnShard(id);
+      }, this.respawnDelay).unref();
+    });
+
+    child.on('error', (err) => {
+      this.logger.error(`[Shard ${id}] Process error: ${err.message}`);
+      this.emit('shardError', err, id);
+    });
+
+    // Reset respawn counter once it stays alive for >30s
+    const stableTimer = setTimeout(() => {
+      this._respawnCounts.delete(id);
+    }, 30_000).unref();
+
+    this.emit('shardCreate', child, id);
+  }
+
+  /**
+   * Broadcast a named action to all shards. Shards must register handlers
+   * via `client.registerBroadcastHandler(name, fn)` to respond to actions.
+   * @param {string} action
+   * @param {Array<any>} [args]
+   * @param {object} [options]
+   */
+  async broadcastAction(action, args = [], options = {}) {
+    if (typeof action !== 'string') throw new TypeError('action must be a string');
+
+    const timeout = options.timeout ?? 10_000;
+    const nonce = `${Date.now()}_${++this._nonce}`;
+    const promises = [];
+
+    for (const [id, shard] of this.shards) {
+      promises.push(
+        new Promise((resolve, reject) => {
+          const key = `${nonce}_${id}`;
+
+          const timer = setTimeout(() => {
+            this._promises.delete(key);
+            reject(new Error(`Shard ${id} action timed out after ${timeout}ms`));
+          }, timeout);
+
+          this._promises.set(key, { resolve, reject, timer });
+
+          shard.send({
+            _type: 'BROADCAST_ACTION',
+            _nonce: nonce,
+            action,
+            args,
+          });
+        })
+      );
+    }
+
+    return Promise.all(promises);
+  }
+
+  /**
+   * Send a message to a specific shard.
+   * @param {number} shardId
+   * @param {any} message
+   */
+  sendTo(shardId, message) {
+    const shard = this.shards.get(shardId);
+    if (!shard) throw new Error(`Shard ${shardId} is not running.`);
+    shard.send(message);
+  }
+
+  /** @private */
+  _handleMessage(shard, message, shardId) {
+    if (!message || typeof message !== 'object') return;
+
+    if (message._type === 'ACTION_RESULT') {
+      const key = `${message._nonce}_${message._shardId}`;
+      const entry = this._promises.get(key);
+      if (!entry) return;
+
+      clearTimeout(entry.timer);
+      this._promises.delete(key);
+
+      if (message._error) {
+        entry.reject(new Error(message._error));
+      } else {
+        entry.resolve(message._result);
+      }
+    } else {
+      this.emit('message', shard, message, shardId);
+    }
+  }
+
+  /**
+   * Kill all shards and clean up.
+   */
+  destroy() {
+    for (const [id, shard] of this.shards) {
+      this.logger.info(`[Shard ${id}] Killing...`);
+      shard.removeAllListeners();
+      shard.kill();
+    }
+    this.shards.clear();
+    this._respawnCounts.clear();
+
+    // Reject pending evals
+    for (const [key, entry] of this._promises) {
+      clearTimeout(entry.timer);
+      entry.reject(new Error('ShardingManager was destroyed.'));
+    }
+    this._promises.clear();
+  }
+}
+
+module.exports = ShardingManager;

package/src/config/ConfigValidator.js

@@ -0,0 +1,172 @@
+'use strict';
+
+const Logger = require('../utils/Logger');
+
+/**
+ * Configuration Validator
+ * Validates configuration objects against schemas.
+ */
+
+class ConfigValidator {
+  constructor() {
+    this.logger = new Logger({ prefix: 'ConfigValidator', level: 'info' });
+    this.schemas = new Map();
+  }
+
+  /**
+   * Register a configuration schema.
+   * @param {string} name
+   * @param {object} schema - Schema definition
+   */
+  registerSchema(name, schema) {
+    this.schemas.set(name, schema);
+    this.logger.info(`Registered schema: ${name}`);
+  }
+
+  /**
+   * Validate configuration against a schema.
+   * @param {string} schemaName
+   * @param {object} config
+   * @returns {object} { valid: boolean, errors: string[] }
+   */
+  validate(schemaName, config) {
+    const schema = this.schemas.get(schemaName);
+    if (!schema) {
+      throw new Error(`Schema not found: ${schemaName}`);
+    }
+
+    const errors = [];
+    const warnings = [];
+
+    this._validateObject(config, schema, '', errors, warnings);
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+    };
+  }
+
+  /**
+   * Validate an object against a schema.
+   * @private
+   */
+  _validateObject(obj, schema, path, errors, warnings) {
+    // Check required fields
+    if (schema.required) {
+      for (const field of schema.required) {
+        if (!(field in obj)) {
+          errors.push(`${path}${field}: Required field is missing`);
+        }
+      }
+    }
+
+    // Check each property
+    for (const [key, value] of Object.entries(obj)) {
+      const fieldSchema = schema.properties?.[key];
+      if (!fieldSchema) {
+        warnings.push(`${path}${key}: Unknown field`);
+        continue;
+      }
+
+      const fieldPath = path ? `${path}.${key}` : key;
+      this._validateValue(value, fieldSchema, fieldPath, errors, warnings);
+    }
+  }
+
+  /**
+   * Validate a value against a field schema.
+   * @private
+   */
+  _validateValue(value, schema, path, errors, warnings) {
+    // Check type
+    if (schema.type && typeof value !== schema.type) {
+      errors.push(`${path}: Expected type '${schema.type}', got '${typeof value}'`);
+      return;
+    }
+
+    // Check enum
+    if (schema.enum && !schema.enum.includes(value)) {
+      errors.push(`${path}: Must be one of ${schema.enum.join(', ')}`);
+      return;
+    }
+
+    // Check range for numbers
+    if (typeof value === 'number') {
+      if (schema.min !== undefined && value < schema.min) {
+        errors.push(`${path}: Must be >= ${schema.min}`);
+      }
+      if (schema.max !== undefined && value > schema.max) {
+        errors.push(`${path}: Must be <= ${schema.max}`);
+      }
+    }
+
+    // Check length for strings
+    if (typeof value === 'string') {
+      if (schema.minLength && value.length < schema.minLength) {
+        errors.push(`${path}: Must be at least ${schema.minLength} characters`);
+      }
+      if (schema.maxLength && value.length > schema.maxLength) {
+        errors.push(`${path}: Must be at most ${schema.maxLength} characters`);
+      }
+      if (schema.pattern && !new RegExp(schema.pattern).test(value)) {
+        errors.push(`${path}: Does not match required pattern`);
+      }
+    }
+
+    // Check array
+    if (Array.isArray(value)) {
+      if (schema.minItems && value.length < schema.minItems) {
+        errors.push(`${path}: Must have at least ${schema.minItems} items`);
+      }
+      if (schema.maxItems && value.length > schema.maxItems) {
+        errors.push(`${path}: Must have at most ${schema.maxItems} items`);
+      }
+      if (schema.items) {
+        value.forEach((item, index) => {
+          this._validateValue(item, schema.items, `${path}[${index}]`, errors, warnings);
+        });
+      }
+    }
+
+    // Check nested object
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      if (schema.properties) {
+        this._validateObject(value, schema, path, errors, warnings);
+      }
+    }
+
+    // Custom validator
+    if (schema.validator && typeof schema.validator === 'function') {
+      const result = schema.validator(value);
+      if (result !== true) {
+        errors.push(`${path}: ${result || 'Custom validation failed'}`);
+      }
+    }
+  }
+
+  /**
+   * Get all registered schemas.
+   * @returns {Array}
+   */
+  getSchemas() {
+    return Array.from(this.schemas.keys());
+  }
+
+  /**
+   * Remove a schema.
+   * @param {string} name
+   */
+  removeSchema(name) {
+    this.schemas.delete(name);
+  }
+
+  /**
+   * Clear all schemas.
+   */
+  clear() {
+    this.schemas.clear();
+  }
+}
+
+module.exports = ConfigValidator;

package/src/config/index.js

@@ -0,0 +1,7 @@
+'use strict';
+
+const ConfigValidator = require('./ConfigValidator');
+
+module.exports = {
+  ConfigValidator,
+};