rpc-express-toolkit 2.0.0

package/src/logger.js

@@ -0,0 +1,153 @@
+"use strict";
+
+/**
+ * Simple structured logger for JSON-RPC operations
+ */
+class Logger {
+  constructor(options = {}) {
+    this.level = options.level || 'info';
+    this.enabled = options.enabled !== false;
+    this.prefix = options.prefix || '[JSON-RPC]';
+    this.customLogger = options.logger || null;
+    
+    this.levels = {
+      error: 0,
+      warn: 1,
+      info: 2,
+      debug: 3,
+      trace: 4
+    };
+  }
+
+  /**
+   * Check if the given level should be logged
+   * @param {string} level 
+   * @returns {boolean}
+   */
+  shouldLog(level) {
+    return this.enabled && this.levels[level] <= this.levels[this.level];
+  }
+
+  /**
+   * Format log message with metadata
+   * @param {string} level 
+   * @param {string} message 
+   * @param {Object} meta 
+   * @returns {Object}
+   */
+  formatMessage(level, message, meta = {}) {
+    return {
+      timestamp: new Date().toISOString(),
+      level: level.toUpperCase(),
+      message,
+      ...meta
+    };
+  }
+
+  /**
+   * Generic log method
+   * @param {string} level 
+   * @param {string} message 
+   * @param {Object} meta 
+   */
+  log(level, message, meta = {}) {
+    if (!this.shouldLog(level)) return;
+
+    const logData = this.formatMessage(level, message, meta);
+    
+    if (this.customLogger) {
+      this.customLogger[level](logData);
+    } else {
+      const logMessage = `${this.prefix} ${logData.timestamp} [${logData.level}] ${message}`;
+      const metaStr = Object.keys(meta).length > 0 ? ` | ${JSON.stringify(meta)}` : '';
+      console[level === 'debug' || level === 'trace' ? 'log' : level](`${logMessage}${metaStr}`);
+    }
+  }
+
+  error(message, meta) { this.log('error', message, meta); }
+  warn(message, meta) { this.log('warn', message, meta); }
+  info(message, meta) { this.log('info', message, meta); }
+  debug(message, meta) { this.log('debug', message, meta); }
+  trace(message, meta) { this.log('trace', message, meta); }
+
+  /**
+   * Log RPC call start
+   * @param {string} method 
+   * @param {any} params 
+   * @param {string|number} id 
+   * @param {Object} req 
+   */
+  rpcCall(method, params, id, req) {
+    this.info('RPC call started', {
+      method,
+      id,
+      params: this.sanitizeParams(params),
+      userAgent: req.headers['user-agent'],
+      ip: req.ip || req.connection?.remoteAddress
+    });
+  }
+
+  /**
+   * Log RPC call success
+   * @param {string} method 
+   * @param {string|number} id 
+   * @param {number} duration 
+   * @param {any} result 
+   */
+  rpcSuccess(method, id, duration, result) {
+    this.info('RPC call completed', {
+      method,
+      id,
+      duration: `${duration}ms`,
+      resultType: typeof result,
+      resultSize: JSON.stringify(result).length
+    });
+  }
+
+  /**
+   * Log RPC call error
+   * @param {string} method 
+   * @param {string|number} id 
+   * @param {number} duration 
+   * @param {Error} error 
+   */
+  rpcError(method, id, duration, error) {
+    this.error('RPC call failed', {
+      method,
+      id,
+      duration: `${duration}ms`,
+      error: error.message,
+      code: error.code,
+      stack: error.stack
+    });
+  }
+
+  /**
+   * Sanitize parameters for logging (remove sensitive data)
+   * @param {any} params 
+   * @returns {any}
+   */
+  sanitizeParams(params) {
+    if (!params || typeof params !== 'object') return params;
+    
+    const sensitiveKeys = ['password', 'token', 'key', 'secret', 'auth', 'authorization'];
+    const sanitized = Array.isArray(params) ? [...params] : { ...params };
+    
+    const sanitizeObj = (obj) => {
+      if (typeof obj !== 'object' || obj === null) return obj;
+      
+      for (const [key, value] of Object.entries(obj)) {
+        if (sensitiveKeys.some(sensitive => key.toLowerCase().includes(sensitive))) {
+          obj[key] = '[REDACTED]';
+        } else if (typeof value === 'object') {
+          sanitizeObj(value);
+        }
+      }
+      return obj;
+    };
+    
+    return sanitizeObj(sanitized);
+  }
+}
+
+module.exports = Logger;

package/src/middleware.js

@@ -0,0 +1,224 @@
+"use strict";
+
+/**
+ * Middleware manager for JSON-RPC operations
+ */
+class MiddlewareManager {
+  constructor() {
+    this.middlewares = {
+      beforeCall: [],
+      afterCall: [],
+      onError: [],
+      beforeValidation: [],
+      afterValidation: []
+    };
+  }
+
+  /**
+   * Add middleware for a specific hook
+   * @param {string} hook - The hook name (beforeCall, afterCall, onError, etc.)
+   * @param {Function} middleware - The middleware function
+   */
+  use(hook, middleware) {
+    if (!this.middlewares[hook]) {
+      throw new Error(`Unknown middleware hook: ${hook}`);
+    }
+    
+    if (typeof middleware !== 'function') {
+      throw new Error('Middleware must be a function');
+    }
+    
+    this.middlewares[hook].push(middleware);
+  }
+
+  /**
+   * Execute middlewares for a specific hook
+   * @param {string} hook 
+   * @param {Object} context 
+   * @returns {Promise<Object>}
+   */
+  async execute(hook, context) {
+    const middlewares = this.middlewares[hook] || [];
+    let result = context;
+    
+    for (const middleware of middlewares) {
+      try {
+        const middlewareResult = await middleware(result);
+        
+        // If middleware returns an object, merge it with context
+        if (middlewareResult && typeof middlewareResult === 'object') {
+          result = { ...result, ...middlewareResult };
+        }
+        
+        // If middleware explicitly returns false, stop execution
+        if (middlewareResult === false) {
+          throw new Error('Middleware execution stopped');
+        }
+      } catch (error) {
+        // For error hooks, continue even if middleware fails
+        if (hook === 'onError') {
+          console.error('Error middleware failed:', error);
+          continue;
+        }
+        throw error;
+      }
+    }
+    
+    return result;
+  }
+
+  /**
+   * Get all middlewares for a hook
+   * @param {string} hook 
+   * @returns {Function[]}
+   */
+  getMiddlewares(hook) {
+    return this.middlewares[hook] || [];
+  }
+
+  /**
+   * Remove all middlewares for a hook
+   * @param {string} hook 
+   */
+  clear(hook) {
+    if (hook) {
+      this.middlewares[hook] = [];
+    } else {
+      // Clear all hooks
+      Object.keys(this.middlewares).forEach(h => {
+        this.middlewares[h] = [];
+      });
+    }
+  }
+
+  /**
+   * Remove a specific middleware from a hook
+   * @param {string} hook 
+   * @param {Function} middleware 
+   */
+  remove(hook, middleware) {
+    if (!this.middlewares[hook]) return;
+    
+    const index = this.middlewares[hook].indexOf(middleware);
+    if (index > -1) {
+      this.middlewares[hook].splice(index, 1);
+    }
+  }
+}
+
+/**
+ * Built-in middleware functions
+ */
+const builtInMiddlewares = {
+  /**
+   * Rate limiting middleware
+   * @param {Object} options 
+   * @returns {Function}
+   */
+  rateLimit(options = {}) {
+    const windowMs = options.windowMs || 60000; // 1 minute
+    const max = options.max || 100; // 100 requests per window
+    const message = options.message || 'Too many requests';
+    
+    const requests = new Map();
+    
+    return async (context) => {
+      const { req } = context;
+      const key = req.ip || req.connection?.remoteAddress || 'unknown';
+      const now = Date.now();
+      
+      // Clean old entries
+      if (requests.has(key)) {
+        const userRequests = requests.get(key);
+        const validRequests = userRequests.filter(time => now - time < windowMs);
+        requests.set(key, validRequests);
+      }
+      
+      const userRequests = requests.get(key) || [];
+      
+      if (userRequests.length >= max) {
+        const error = new Error(message);
+        error.code = -32000; // Custom JSON-RPC error code
+        throw error;
+      }
+      
+      userRequests.push(now);
+      requests.set(key, userRequests);
+      
+      return context;
+    };
+  },
+
+  /**
+   * Authentication middleware
+   * @param {Function} authFunction 
+   * @returns {Function}
+   */
+  auth(authFunction) {
+    return async (context) => {
+      const { req } = context;
+      const isAuthenticated = await authFunction(req);
+      
+      if (!isAuthenticated) {
+        const error = new Error('Authentication required');
+        error.code = -32001;
+        throw error;
+      }
+      
+      return context;
+    };
+  },
+
+  /**
+   * CORS middleware
+   * @param {Object} options 
+   * @returns {Function}
+   */
+  cors(options = {}) {
+    const origin = options.origin || '*';
+    const methods = options.methods || ['POST'];
+    const headers = options.headers || ['Content-Type'];
+    
+    return async (context) => {
+      const { res } = context;
+      
+      res.header('Access-Control-Allow-Origin', origin);
+      res.header('Access-Control-Allow-Methods', methods.join(', '));
+      res.header('Access-Control-Allow-Headers', headers.join(', '));
+      
+      return context;
+    };
+  },
+
+  /**
+   * Request timing middleware
+   * @returns {Function}
+   */
+  timing() {
+    return async (context) => {
+      context.startTime = Date.now();
+      return context;
+    };
+  },
+
+  /**
+   * Method whitelist middleware
+   * @param {string[]} allowedMethods 
+   * @returns {Function}
+   */
+  methodWhitelist(allowedMethods) {
+    return async (context) => {
+      const { method } = context;
+      
+      if (!allowedMethods.includes(method)) {
+        const error = new Error(`Method '${method}' is not allowed`);
+        error.code = -32601;
+        throw error;
+      }
+      
+      return context;
+    };
+  }
+};
+
+module.exports = { MiddlewareManager, builtInMiddlewares };

package/src/validation.js

@@ -0,0 +1,221 @@
+"use strict";
+
+const Ajv = require('ajv');
+const addFormats = require('ajv-formats');
+
+/**
+ * Schema validator for JSON-RPC methods
+ */
+class SchemaValidator {
+  constructor(options = {}) {
+    this.ajv = new Ajv({ 
+      allErrors: true,
+      removeAdditional: options.removeAdditional || false,
+      useDefaults: options.useDefaults !== false,
+      ...options.ajvOptions 
+    });
+    
+    addFormats(this.ajv);
+    
+    // Add custom formats
+    this.addCustomFormats();
+  }
+
+  /**
+   * Add custom format validators
+   */
+  addCustomFormats() {
+    // BigInt format
+    this.ajv.addFormat('bigint', {
+      type: 'string',
+      validate: (data) => /^-?\d+n?$/.test(data)
+    });
+    
+    // ObjectId format (MongoDB style)
+    this.ajv.addFormat('objectid', {
+      type: 'string',
+      validate: (data) => /^[0-9a-fA-F]{24}$/.test(data)
+    });
+  }
+
+  /**
+   * Validate parameters against a schema
+   * @param {any} params 
+   * @param {Object} schema 
+   * @returns {Object} validation result
+   */
+  validate(params, schema) {
+    const validator = this.ajv.compile(schema);
+    const valid = validator(params);
+    
+    return {
+      valid,
+      errors: valid ? null : validator.errors,
+      data: params
+    };
+  }
+
+  /**
+   * Create a validation middleware
+   * @param {Object} schema 
+   * @returns {Function}
+   */
+  middleware(schema) {
+    return async (context) => {
+      const { params } = context;
+      const result = this.validate(params, schema);
+      
+      if (!result.valid) {
+        const error = new Error('Validation failed');
+        error.code = -32602; // Invalid params
+        error.data = {
+          validationErrors: result.errors.map(err => ({
+            field: err.instancePath || err.schemaPath,
+            message: err.message,
+            value: err.data
+          }))
+        };
+        throw error;
+      }
+      
+      // Update params with validated/coerced data
+      context.params = result.data;
+      return context;
+    };
+  }
+
+  /**
+   * Add a custom keyword
+   * @param {string} name 
+   * @param {Object} definition 
+   */
+  addKeyword(name, definition) {
+    this.ajv.addKeyword(name, definition);
+  }
+}
+
+/**
+ * Common schema definitions
+ */
+const commonSchemas = {
+  // Pagination parameters
+  pagination: {
+    type: 'object',
+    properties: {
+      page: { type: 'integer', minimum: 1, default: 1 },
+      limit: { type: 'integer', minimum: 1, maximum: 100, default: 10 },
+      sort: { type: 'string' },
+      order: { type: 'string', enum: ['asc', 'desc'], default: 'asc' }
+    }
+  },
+
+  // User identification
+  userId: {
+    oneOf: [
+      { type: 'string', format: 'objectid' },
+      { type: 'string', format: 'uuid' },
+      { type: 'integer', minimum: 1 }
+    ]
+  },
+
+  // Email validation
+  email: {
+    type: 'string',
+    format: 'email',
+    maxLength: 255
+  },
+
+  // Password requirements
+  password: {
+    type: 'string',
+    minLength: 8,
+    maxLength: 128,
+    pattern: '^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)'
+  },
+
+  // BigInt validation
+  bigintString: {
+    type: 'string',
+    format: 'bigint'
+  },
+
+  // Date validation
+  dateString: {
+    type: 'string',
+    format: 'date-time'
+  }
+};
+
+/**
+ * Schema builder helper
+ */
+class SchemaBuilder {
+  constructor() {
+    this.schema = {
+      type: 'object',
+      properties: {},
+      required: []
+    };
+  }
+
+  /**
+   * Add a property to the schema
+   * @param {string} name 
+   * @param {Object} definition 
+   * @param {boolean} required 
+   * @returns {SchemaBuilder}
+   */
+  property(name, definition, required = false) {
+    this.schema.properties[name] = definition;
+    if (required) {
+      this.schema.required.push(name);
+    }
+    return this;
+  }
+
+  /**
+   * Add multiple properties
+   * @param {Object} properties 
+   * @returns {SchemaBuilder}
+   */
+  properties(properties) {
+    Object.entries(properties).forEach(([name, definition]) => {
+      this.property(name, definition);
+    });
+    return this;
+  }
+
+  /**
+   * Set required fields
+   * @param {string[]} fields 
+   * @returns {SchemaBuilder}
+   */
+  required(fields) {
+    this.schema.required = [...new Set([...this.schema.required, ...fields])];
+    return this;
+  }
+
+  /**
+   * Add additional properties setting
+   * @param {boolean} allowed 
+   * @returns {SchemaBuilder}
+   */
+  additionalProperties(allowed) {
+    this.schema.additionalProperties = allowed;
+    return this;
+  }
+
+  /**
+   * Build and return the schema
+   * @returns {Object}
+   */
+  build() {
+    return this.schema;
+  }
+}
+
+module.exports = { 
+  SchemaValidator, 
+  commonSchemas, 
+  SchemaBuilder 
+};