@devilsdev/rag-pipeline-utils 2.1.12 → 2.2.1

package/src/utils/plugin-scaffolder.js

@@ -0,0 +1,447 @@
+/**
+ * Version: 1.0.0
+ * Path: /src/utils/plugin-scaffolder.js
+ * Description: Plugin scaffolding utility for creating new plugins with best practices
+ * Author: Ali Kahwaji
+ */
+
+const fs = require('fs');
+// eslint-disable-line global-require
+const path = require('path');
+// eslint-disable-line global-require
+const { pluginContracts } = require('../core/plugin-contracts.js');
+// eslint-disable-line global-require
+
+class PluginScaffolder {
+  constructor(_options = {}) {
+    this.outputDir = _options.outputDir || process.cwd();
+    this.author = _options.author || 'Your Name';
+    this.namespace = _options.namespace || 'your-namespace';
+  }
+
+  /**
+   * Scaffold a new plugin with all necessary files
+   * @param {string} pluginType - Type of plugin (loader, embedder, retriever, llm, reranker)
+   * @param {string} pluginName - Name of the plugin
+   * @param {object} _options - Additional _options
+   */
+  async scaffoldPlugin(pluginType, pluginName, _options = {}) {
+    if (!pluginContracts[pluginType]) {
+      throw new Error(
+        `Unknown plugin _type: ${pluginType}. Available types: ${Object.keys(pluginContracts).join(', ')}`,
+      );
+    }
+
+    const pluginDir = path.join(this.outputDir, `${pluginName}-${pluginType}`);
+
+    // Create plugin directory
+    if (!fs.existsSync(pluginDir)) {
+      fs.mkdirSync(pluginDir, { recursive: true });
+    }
+
+    // Generate all plugin files
+    await this.generatePluginFile(pluginDir, pluginType, pluginName, _options);
+    await this.generateTestFile(pluginDir, pluginType, pluginName);
+    await this.generateMockFile(pluginDir, pluginType, pluginName);
+    await this.generateConfigExample(pluginDir, pluginType, pluginName);
+    await this.generateReadme(pluginDir, pluginType, pluginName, _options);
+    await this.generatePackageJson(pluginDir, pluginType, pluginName, _options);
+
+    console.log(`✅ Plugin scaffolded successfully at: ${pluginDir}`);
+    // eslint-disable-line no-console
+    console.log('📁 Generated files:');
+    // eslint-disable-line no-console
+    console.log(`   - src/${pluginName}-${pluginType}.js (main plugin)`);
+    // eslint-disable-line no-console
+    console.log(`   - __tests__/${pluginName}-${pluginType}.test.js (tests)`);
+    // eslint-disable-line no-console
+    console.log(
+      `   - mocks/${pluginName}-${pluginType}-mock.js (mock implementation)`,
+    );
+    // eslint-disable-line no-console
+    console.log('   - .ragrc.example.json (configuration example)');
+    // eslint-disable-line no-console
+    console.log('   - README.md (documentation)');
+    // eslint-disable-line no-console
+    console.log('   - package.json (npm package)');
+    // eslint-disable-line no-console
+  }
+
+  /**
+   * Generate the main plugin implementation file
+   */
+  async generatePluginFile(pluginDir, pluginType, pluginName, _options) {
+    const contract = pluginContracts[pluginType];
+    const className = this.toPascalCase(`${pluginName}_${pluginType}`);
+    const srcDir = path.join(pluginDir, 'src');
+
+    if (!fs.existsSync(srcDir)) {
+      fs.mkdirSync(srcDir, { recursive: true });
+    }
+
+    const methods = contract.requiredMethods
+      .map((methodName) => {
+        const signature = contract.methodSignatures?.[methodName];
+        return this.generateMethodStub(methodName, signature);
+      })
+      .join('\n\n');
+
+    const optionalMethods =
+      contract.optionalMethods
+        ?.map((methodName) => {
+          const signature = contract.methodSignatures?.[methodName];
+          return this.generateMethodStub(methodName, signature, true);
+        })
+        .join('\n\n') || '';
+
+    const kebabName = pluginName
+      .replace(/([A-Z])/g, '-$1')
+      .toLowerCase()
+      .replace(/^-/, '');
+
+    const content = `/**
+ * ${className} - ${pluginType} plugin implementation
+ * Generated by RAG Pipeline Utils Plugin Scaffolder
+ * Author: ${this.author}
+ */
+
+class ${className} {
+  constructor(options = {}) {
+    this.name = '${kebabName}';
+    this.options = options;
+    
+    // Add your initialization logic here
+    // Example: this.apiKey = options.apiKey;
+    // Example: this.endpoint = options.endpoint || 'https://api.example.com';
+  }
+
+${methods}${optionalMethods ? '\n\n  // Optional methods\n' + optionalMethods : ''}
+}
+
+module.exports = ${className};
+`;
+
+    const _filePath = path.join(srcDir, `${pluginName}-${pluginType}.js`);
+    fs.writeFileSync(_filePath, content);
+  }
+
+  /**
+   * Generate method stub with proper signature
+   */
+  generateMethodStub(methodName, signature, isOptional = false) {
+    const params = signature?.params || ['input'];
+    const paramTypes = signature?.paramTypes || ['any'];
+    const returnType = signature?.returnType || 'Promise<any>';
+    const description =
+      signature?.description ||
+      `${isOptional ? 'Optional: ' : ''}Implement ${methodName} functionality`;
+
+    const paramList = params.map((param, _i) => `${param}`).join(', ');
+    const paramDocs = params
+      .map((param, _i) => `   * @param {${paramTypes[_i]}} ${param}`)
+      .join('\n');
+
+    return `  /**
+   * ${description}
+${paramDocs}
+   * @returns {${returnType}}
+   */
+  async ${methodName}(${paramList}) {
+    // TODO: Implement ${methodName} logic
+    throw new Error('${methodName} not yet implemented');
+  }`;
+  }
+
+  /**
+   * Generate test file
+   */
+  async generateTestFile(pluginDir, pluginType, pluginName) {
+    const className = this.toPascalCase(`${pluginName}_${pluginType}`);
+    const testDir = path.join(pluginDir, '__tests__');
+
+    if (!fs.existsSync(testDir)) {
+      fs.mkdirSync(testDir, { recursive: true });
+    }
+
+    const contract = pluginContracts[pluginType];
+    const testCases = contract.requiredMethods
+      .map((method) => {
+        return `  describe('${method}', () => {
+    it('should implement ${method} method', () => {
+      expect(typeof plugin.${method}).toBe('function');
+    });
+
+    it('should handle ${method} functionality', async () => {
+      // TODO: Add specific test cases for ${method}
+      // Example: const result = await plugin.${method}(testInput);
+      // Example: expect(result).toBeDefined();
+    });
+  });`;
+      })
+      .join('\n\n');
+
+    const content = `/**
+ * Tests for ${className}
+ * Generated by RAG Pipeline Utils Plugin Scaffolder
+ */
+
+const { ${className} } = require('../src/${pluginName}-${pluginType}.js');
+
+describe('${className}', () => {
+  let plugin;
+
+  beforeEach(() => {
+    plugin = new ${className}({
+      // Add test configuration _options here
+    });
+  });
+
+  describe('constructor', () => {
+    it('should create _instance with default _options', () => {
+      const _instance = new ${className}();
+      expect(_instance).toBeInstanceOf(${className});
+    });
+
+    it('should accept configuration _options', () => {
+      const _options = { testOption: 'value' };
+      const _instance = new ${className}(_options);
+      expect(_instance._options).toEqual(_options);
+    });
+  });
+
+${testCases}
+
+  describe('error handling', () => {
+    it('should handle invalid inputs gracefully', async () => {
+      // TODO: Add error handling tests
+      // Example: await expect(plugin.someMethod(null)).rejects.toThrow();
+    });
+  });
+});
+`;
+
+    const _filePath = path.join(testDir, `${pluginName}-${pluginType}.test.js`);
+    fs.writeFileSync(_filePath, content);
+  }
+
+  /**
+   * Generate mock implementation file
+   */
+  async generateMockFile(pluginDir, pluginType, pluginName) {
+    const className = this.toPascalCase(`${pluginName}_${pluginType}`);
+    const mockDir = path.join(pluginDir, 'mocks');
+
+    if (!fs.existsSync(mockDir)) {
+      fs.mkdirSync(mockDir, { recursive: true });
+    }
+
+    const contract = pluginContracts[pluginType];
+    const mockMethods = contract.requiredMethods
+      .map((methodName) => {
+        return `  async ${methodName}(...args) {
+    // Mock implementation for ${methodName}
+    console.log(\`Mock ${className}.${methodName} called with:\`, args);
+ // eslint-disable-line no-console
+    return \`Mock result from ${methodName}\`;
+  }`;
+      })
+      .join('\n\n');
+
+    const content = `/**
+ * Mock implementation of ${className}
+ * Generated by RAG Pipeline Utils Plugin Scaffolder
+ * Use this for testing and development
+ */
+
+class Mock${className} {
+  constructor(_options = {}) {
+    this._options = _options;
+    this.mockMode = true;
+  }
+
+${mockMethods}
+}
+
+// Export default instance for easy use
+ Mock${className}();
+`;
+
+    const _filePath = path.join(mockDir, `${pluginName}-${pluginType}-mock.js`);
+    fs.writeFileSync(_filePath, content);
+  }
+
+  /**
+   * Generate configuration example
+   */
+  async generateConfigExample(pluginDir, pluginType, pluginName) {
+    const _config = {
+      [pluginType]: {
+        [pluginName]: `./src/${pluginName}-${pluginType}.js`,
+      },
+      namespace: `${pluginName}-namespace`,
+      pipeline: ['loader', 'embedder', 'retriever'],
+    };
+
+    const content = JSON.stringify(_config, null, 2);
+    const _filePath = path.join(pluginDir, '.ragrc.example.json');
+    fs.writeFileSync(_filePath, content);
+  }
+
+  /**
+   * Generate README documentation
+   */
+  async generateReadme(pluginDir, pluginType, pluginName, _options) {
+    const className = this.toPascalCase(`${pluginName}_${pluginType}`);
+    const contract = pluginContracts[pluginType];
+
+    const methodDocs = contract.requiredMethods
+      .map((method) => {
+        const signature = contract.methodSignatures?.[method];
+        return `### \`${method}(${signature?.params?.join(', ') || '...args'})\`
+
+${signature?.description || `Implements ${method} functionality`}
+
+**Parameters:**
+${signature?.params?.map((param, _i) => `- \`${param}\` (${signature.paramTypes?.[_i] || 'any'})`).join('\n') || '- TBD'}
+
+**Returns:** \`${signature?.returnType || 'Promise<any>'}\``;
+      })
+      .join('\n\n');
+
+    const content = `# ${className}
+
+A ${pluginType} plugin for RAG Pipeline Utils.
+
+## Description
+
+${_options.description || `This plugin provides ${pluginType} functionality for RAG (Retrieval-Augmented Generation) pipelines.`}
+
+## Installation
+
+\`\`\`bash
+npm install ${this.namespace}/${pluginName}-${pluginType}
+\`\`\`
+
+## Usage
+
+### Basic Usage
+
+\`\`\`javascript
+const { ${className} } = require('${this.namespace}/${pluginName}-${pluginType}');
+
+const plugin = new ${className}({
+  // Configuration _options
+});
+
+// Use the plugin methods
+// const result = await plugin.someMethod(input);
+\`\`\`
+
+### With RAG Pipeline Utils
+
+\`\`\`json
+{
+  "${pluginType}": {
+    "${pluginName}": "./src/${pluginName}-${pluginType}.js"
+  }
+}
+\`\`\`
+
+## API Reference
+
+${methodDocs}
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| \`option1\` | \`string\` | \`"default"\` | Description of option1 |
+| \`option2\` | \`number\` | \`100\` | Description of option2 |
+
+## Testing
+
+\`\`\`bash
+npm test
+\`\`\`
+
+## Development
+
+1. Clone the repository
+2. Install dependencies: \`npm install\`
+3. Run tests: \`npm test\`
+4. Build: \`npm run build\`
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+## License
+
+MIT
+
+## Author
+
+${this.author}
+`;
+
+    const _filePath = path.join(pluginDir, 'README.md');
+    fs.writeFileSync(_filePath, content);
+  }
+
+  /**
+   * Generate package.json
+   */
+  async generatePackageJson(pluginDir, pluginType, pluginName, _options) {
+    const packageName = `${this.namespace}/${pluginName}-${pluginType}`;
+
+    const packageJson = {
+      name: packageName,
+      version: '1.0.0',
+      description:
+        _options.description || `A ${pluginType} plugin for RAG Pipeline Utils`,
+      main: `src/${pluginName}-${pluginType}.js`,
+      _type: 'module',
+      scripts: {
+        test: 'jest',
+        'test:watch': 'jest --watch',
+        lint: 'eslint src/ __tests__/',
+        'lint:fix': 'eslint src/ __tests__/ --fix',
+      },
+      keywords: ['rag', 'pipeline', 'plugin', pluginType, 'ai', 'ml'],
+      author: this.author,
+      license: 'MIT',
+      peerDependencies: {
+        '@devilsdev/rag-pipeline-utils': '^2.0.0',
+      },
+      devDependencies: {
+        jest: '^29.7.0',
+        eslint: '^8.57.1',
+      },
+      files: ['src/', 'mocks/', 'README.md', '.ragrc.example.json'],
+    };
+
+    const content = JSON.stringify(packageJson, null, 2);
+    const _filePath = path.join(pluginDir, 'package.json');
+    fs.writeFileSync(_filePath, content);
+  }
+
+  /**
+   * Convert string to PascalCase
+   */
+  toPascalCase(str) {
+    return str
+      .split(/[-_\s]/)
+      .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+      .join('');
+  }
+}
+
+// Default export
+
+module.exports = {
+  PluginScaffolder,
+};

package/src/utils/rate-limiter.js

@@ -0,0 +1,244 @@
+/**
+ * Rate Limiter Utility
+ * Protects against brute force attacks and abuse
+ *
+ * Features:
+ * - Sliding window rate limiting
+ * - Per-identifier tracking (IP, user, tenant)
+ * - Automatic cleanup of expired entries
+ * - Configurable thresholds and windows
+ */
+
+const crypto = require('crypto');
+
+class RateLimiter {
+  /**
+   * Create a rate limiter instance
+   * @param {Object} options - Configuration options
+   * @param {number} options.maxAttempts - Maximum attempts allowed (default: 5)
+   * @param {number} options.windowMs - Time window in milliseconds (default: 15 minutes)
+   * @param {number} options.blockDurationMs - How long to block after exceeding limit (default: 1 hour)
+   * @param {number} options.cleanupIntervalMs - How often to cleanup expired entries (default: 5 minutes)
+   */
+  constructor(options = {}) {
+    this.maxAttempts = options.maxAttempts || 5;
+    this.windowMs = options.windowMs || 15 * 60 * 1000; // 15 minutes
+    this.blockDurationMs = options.blockDurationMs || 60 * 60 * 1000; // 1 hour
+    this.cleanupIntervalMs = options.cleanupIntervalMs || 5 * 60 * 1000; // 5 minutes
+
+    // Map of identifier -> { attempts: [], blockedUntil: timestamp }
+    this.store = new Map();
+
+    // Start automatic cleanup
+    this._startCleanup();
+  }
+
+  /**
+   * Check if a request should be allowed
+   * @param {string} identifier - Unique identifier (IP, userId, tenantId, etc.)
+   * @returns {Object} { allowed: boolean, remaining: number, resetAt: Date, blockedUntil: Date|null }
+   */
+  allowRequest(identifier) {
+    const key = this._hashIdentifier(identifier);
+    const now = Date.now();
+
+    // Get or create record
+    let record = this.store.get(key);
+    if (!record) {
+      record = { attempts: [], blockedUntil: null };
+      this.store.set(key, record);
+    }
+
+    // Check if currently blocked
+    if (record.blockedUntil && record.blockedUntil > now) {
+      return {
+        allowed: false,
+        remaining: 0,
+        resetAt: new Date(record.blockedUntil),
+        blockedUntil: new Date(record.blockedUntil),
+        retryAfter: Math.ceil((record.blockedUntil - now) / 1000), // seconds
+      };
+    }
+
+    // Clear expired block
+    if (record.blockedUntil && record.blockedUntil <= now) {
+      record.blockedUntil = null;
+    }
+
+    // Remove expired attempts
+    const windowStart = now - this.windowMs;
+    record.attempts = record.attempts.filter(
+      (timestamp) => timestamp > windowStart,
+    );
+
+    // Check if exceeded limit
+    if (record.attempts.length >= this.maxAttempts) {
+      // Block the identifier
+      record.blockedUntil = now + this.blockDurationMs;
+      return {
+        allowed: false,
+        remaining: 0,
+        resetAt: new Date(record.blockedUntil),
+        blockedUntil: new Date(record.blockedUntil),
+        retryAfter: Math.ceil(this.blockDurationMs / 1000), // seconds
+      };
+    }
+
+    // Allow request and record attempt
+    record.attempts.push(now);
+
+    return {
+      allowed: true,
+      remaining: this.maxAttempts - record.attempts.length,
+      resetAt: new Date(now + this.windowMs),
+      blockedUntil: null,
+      retryAfter: 0,
+    };
+  }
+
+  /**
+   * Manually reset rate limit for an identifier
+   * @param {string} identifier - Identifier to reset
+   */
+  reset(identifier) {
+    const key = this._hashIdentifier(identifier);
+    this.store.delete(key);
+  }
+
+  /**
+   * Get current status for an identifier
+   * @param {string} identifier - Identifier to check
+   * @returns {Object} Current rate limit status
+   */
+  getStatus(identifier) {
+    const key = this._hashIdentifier(identifier);
+    const record = this.store.get(key);
+    const now = Date.now();
+
+    if (!record) {
+      return {
+        attempts: 0,
+        remaining: this.maxAttempts,
+        blocked: false,
+        blockedUntil: null,
+      };
+    }
+
+    // Remove expired attempts
+    const windowStart = now - this.windowMs;
+    const validAttempts = record.attempts.filter(
+      (timestamp) => timestamp > windowStart,
+    );
+
+    const blocked = !!(record.blockedUntil && record.blockedUntil > now);
+
+    return {
+      attempts: validAttempts.length,
+      remaining: Math.max(0, this.maxAttempts - validAttempts.length),
+      blocked,
+      blockedUntil: blocked ? new Date(record.blockedUntil) : null,
+    };
+  }
+
+  /**
+   * Clean up expired entries
+   */
+  cleanup() {
+    const now = Date.now();
+    const expiredKeys = [];
+
+    for (const [key, record] of this.store.entries()) {
+      // Check if block has expired and no recent attempts
+      const blockExpired = !record.blockedUntil || record.blockedUntil < now;
+      const windowStart = now - this.windowMs;
+      const hasRecentAttempts = record.attempts.some(
+        (timestamp) => timestamp > windowStart,
+      );
+
+      if (blockExpired && !hasRecentAttempts) {
+        expiredKeys.push(key);
+      }
+    }
+
+    // Delete expired entries
+    expiredKeys.forEach((key) => this.store.delete(key));
+
+    return {
+      cleaned: expiredKeys.length,
+      remaining: this.store.size,
+    };
+  }
+
+  /**
+   * Get statistics about rate limiter usage
+   * @returns {Object} Statistics
+   */
+  getStats() {
+    const now = Date.now();
+    let totalAttempts = 0;
+    let blockedIdentifiers = 0;
+    let activeIdentifiers = 0;
+
+    for (const record of this.store.values()) {
+      const windowStart = now - this.windowMs;
+      const validAttempts = record.attempts.filter(
+        (timestamp) => timestamp > windowStart,
+      );
+
+      if (validAttempts.length > 0) {
+        activeIdentifiers++;
+        totalAttempts += validAttempts.length;
+      }
+
+      if (record.blockedUntil && record.blockedUntil > now) {
+        blockedIdentifiers++;
+      }
+    }
+
+    return {
+      totalIdentifiers: this.store.size,
+      activeIdentifiers,
+      blockedIdentifiers,
+      totalAttempts,
+      averageAttemptsPerIdentifier:
+        activeIdentifiers > 0 ? totalAttempts / activeIdentifiers : 0,
+    };
+  }
+
+  /**
+   * Stop the rate limiter and cleanup
+   */
+  destroy() {
+    if (this._cleanupInterval) {
+      clearInterval(this._cleanupInterval);
+      this._cleanupInterval = null;
+    }
+    this.store.clear();
+  }
+
+  /**
+   * Hash identifier for storage (privacy)
+   * @private
+   */
+  _hashIdentifier(identifier) {
+    return crypto.createHash('sha256').update(identifier).digest('hex');
+  }
+
+  /**
+   * Start automatic cleanup timer
+   * @private
+   */
+  _startCleanup() {
+    this._cleanupInterval = setInterval(() => {
+      this.cleanup();
+    }, this.cleanupIntervalMs);
+
+    // Don't prevent process exit
+    if (this._cleanupInterval.unref) {
+      this._cleanupInterval.unref();
+    }
+  }
+}
+
+module.exports = RateLimiter;
+module.exports.default = module.exports;