impr(CLDSRV-853): Refactor rate limit configuration to use joi schema

Author: tmacro

lib/api/apiUtils/rateLimit/config.js

@@ -1,4 +1,4 @@
-const assert = require('assert');
+const Joi = require('@hapi/joi');
 const { errors, ArsenalError } = require('arsenal');
 
 const { rateLimitDefaultConfigCacheTTL, rateLimitDefaultBurstCapacity } = require('../../../../constants');
@@ -48,6 +48,32 @@ const { calculateInterval } = require('./gcra');
  *       "defaultBurstCapacity": 1
  *     },
  *
+ *     // Optional: Account-level rate limiting configuration
+ *     "account": {
+ *       // Optional: Global default rate limit for all accounts
+ *       // Can be overridden per-bucket via PutBucketRateLimit API
+ *       "defaultConfig": {
+ *         "requestsPerSecond": {
+ *           // Required: Requests per second limit (0 = unlimited)
+ *           "limit": 100,
+ *
+ *           // Optional: Burst capacity (allows temporary spikes)
+ *           // Default: 1 (no burst allowed)
+ *           // Higher values allow more requests in quick succession
+ *           "burstCapacity": 2
+ *         }
+ *       },
+ *
+ *       // Optional: How long to cache rate limit configs (milliseconds)
+ *       // Default: 30000 (30 seconds)
+ *       // Higher values = better performance, slower config updates
+ *       "configCacheTTL": 30000,
+ *
+ *       // Optional: Default burst capacity for per-bucket configs
+ *       // Default: 1
+ *       "defaultBurstCapacity": 1
+ *     },
+ *
  *     // Optional: Custom error response for rate limited requests
  *     "error": {
  *       // Optional: HTTP status code (400-599)
@@ -125,6 +151,91 @@ const { calculateInterval } = require('./gcra');
  * - Enforced atomically in Redis during token grants using GCRA
  */
 
+/**
+ * RateLimitClassConfig
+ * @typedef {Object} RateLimitClassConfig
+ * @property {object} defaultConfig - Default config applied if no resource specific configuration is found.
+ * @property {number} configCacheTTL - Number of milliseconds to cache per resource configs
+ * @property {number} defaultBurstCapacity - Default used if resource does not specify a burst capacity.
+*/
+
+const rateLimitClassConfigSchema = Joi.object({
+    defaultConfig: Joi.object({
+        requestsPerSecond: Joi.object({
+            limit: Joi.number().integer().min(0).required(),
+            burstCapacity: Joi.number().positive(),
+        }),
+    }),
+    configCacheTTL: Joi.number().integer().positive(),
+    defaultBurstCapacity: Joi.number().integer().positive(),
+});
+
+const rateLimitConfigSchema = Joi.object({
+    enabled: Joi.boolean().default(false),
+    serviceUserArn: Joi.string().required(),
+    nodes: Joi.number().integer().positive().default(1),
+    tokenBucketBufferSize: Joi.number().integer().positive().default(50),
+    tokenBucketRefillThreshold: Joi.number().integer().positive().default(20),
+    bucket: rateLimitClassConfigSchema,
+    account: rateLimitClassConfigSchema,
+    error: Joi.object({
+        statusCode: Joi.number().integer().min(400).max(599).default(503),
+        code: Joi.string().default(errors.SlowDown.message),
+        message: Joi.string().default(errors.SlowDown.description),
+    }),
+});
+
+/**
+ * Transform validated class config (bucket or account) by calculating intervals
+ * and applying business logic
+ *
+ * @param {string} className - Rate limit class name ('bucket' or 'account')
+ * @param {object} validatedCfg - Already validated config from Joi
+ * @param {number} clusters - Number of worker processes spawned per instance
+ * @param {number} nodes - Number of instances that requests will be load balanced across
+ * @returns {RateLimitClassConfig} Transformed rate limit config
+ */
+function transformClassConfig(className, validatedCfg, clusters, nodes) {
+    const transformed = {
+        defaultConfig: undefined,
+        configCacheTTL: validatedCfg.configCacheTTL || rateLimitDefaultConfigCacheTTL,
+        defaultBurstCapacity: validatedCfg.defaultBurstCapacity || rateLimitDefaultBurstCapacity,
+    };
+
+    if (validatedCfg.defaultConfig?.requestsPerSecond) {
+        const { limit, burstCapacity } = validatedCfg.defaultConfig.requestsPerSecond;
+
+        // Validate limit against nodes AND workers (business rule)
+        const minLimit = nodes * clusters;
+        if (limit > 0 && limit < minLimit) {
+            throw new Error(
+                `rateLimiting.${className}.defaultConfig.` +
+                `requestsPerSecond.limit (${limit}) must be >= ` +
+                `(nodes x workers = ${nodes} x ${clusters} = ${minLimit}) ` +
+                'or 0 (unlimited). Each worker enforces limit/nodes/workers locally. ' +
+                `With limit < ${minLimit}, per-worker rate would be < 1 req/s, effectively blocking traffic.`
+            );
+        }
+
+        // Use provided burstCapacity or fall back to default
+        const effectiveBurstCapacity = burstCapacity || transformed.defaultBurstCapacity;
+
+        // Calculate per-worker interval using distributed architecture
+        const interval = calculateInterval(limit, nodes, clusters);
+
+        // Store both the original limit and the calculated values
+        transformed.defaultConfig = {
+            limit,
+            requestsPerSecond: {
+                interval,
+                bucketSize: effectiveBurstCapacity * 1000,
+            },
+        };
+    }
+
+    return transformed;
+}
+
 /**
  * Parse and validate the complete rate limiting configuration
  *
@@ -134,195 +245,58 @@ const { calculateInterval } = require('./gcra');
  * @throws {Error} If configuration is invalid
  */
 function parseRateLimitConfig(rateLimitingConfig, clusters) {
-    const parsed = {
-        enabled: true,
-    };
-
-    // Validate and set serviceUserArn
-    assert.strictEqual(
-        typeof rateLimitingConfig.serviceUserArn, 'string',
-        'rateLimiting.serviceUserArn must be a string'
+    // Validate configuration using Joi schema
+    const { error: validationError, value: validated } = rateLimitConfigSchema.validate(
+        rateLimitingConfig,
+        { abortEarly: false, allowUnknown: false, convert: false }
     );
-    parsed.serviceUserArn = rateLimitingConfig.serviceUserArn;
 
-    // Parse and validate node count
-    if (rateLimitingConfig.nodes !== undefined) {
-        assert(
-            typeof rateLimitingConfig.nodes === 'number' &&
-            Number.isInteger(rateLimitingConfig.nodes) &&
-            rateLimitingConfig.nodes > 0,
-            'rateLimiting.nodes must be a positive integer'
-        );
-        parsed.nodes = rateLimitingConfig.nodes;
-    } else {
-        parsed.nodes = 1; // Default to 1 node
+    if (validationError) {
+        const details = validationError.details.map(d => d.message).join('; ');
+        throw new Error(`rateLimiting configuration is invalid: ${details}`);
     }
 
-    if (rateLimitingConfig.tokenBucketBufferSize !== undefined) {
-        assert(
-            typeof rateLimitingConfig.tokenBucketBufferSize === 'number' &&
-            Number.isInteger(rateLimitingConfig.tokenBucketBufferSize) &&
-            rateLimitingConfig.tokenBucketBufferSize > 0,
-            'rateLimiting.tokenBucketBufferSize must be a positive integer'
-        );
-        parsed.tokenBucketBufferSize = rateLimitingConfig.tokenBucketBufferSize;
-    } else {
-        parsed.tokenBucketBufferSize = 50; // (5 seconds @ 10 req/s)
-    }
-
-    if (rateLimitingConfig.tokenBucketRefillThreshold !== undefined) {
-        assert(
-            typeof rateLimitingConfig.tokenBucketRefillThreshold === 'number' &&
-            Number.isInteger(rateLimitingConfig.tokenBucketRefillThreshold) &&
-            rateLimitingConfig.tokenBucketRefillThreshold > 0,
-            'rateLimiting.tokenBucketRefillThreshold must be a positive integer'
-        );
-        parsed.tokenBucketRefillThreshold = rateLimitingConfig.tokenBucketRefillThreshold;
-    } else {
-        parsed.tokenBucketRefillThreshold = 20;
-    }
+    // Initialize parsed config with validated values (including defaults)
+    const parsed = {
+        enabled: validated.enabled,
+        serviceUserArn: validated.serviceUserArn,
+        nodes: validated.nodes,
+        tokenBucketBufferSize: validated.tokenBucketBufferSize,
+        tokenBucketRefillThreshold: validated.tokenBucketRefillThreshold,
+    };
 
-    // Parse bucket configuration
+    // Transform bucket configuration
     // Always initialize bucket config to support per-bucket rate limits set via API
-    // This ensures caching and default values work even when no global default is configured
     parsed.bucket = {
-        defaultConfig: undefined,  // No global default unless specified
-        configCacheTTL: rateLimitDefaultConfigCacheTTL,  // Default cache TTL
-        defaultBurstCapacity: rateLimitDefaultBurstCapacity,  // Default burst capacity for per-bucket configs
+        defaultConfig: undefined,
+        configCacheTTL: rateLimitDefaultConfigCacheTTL,
+        defaultBurstCapacity: rateLimitDefaultBurstCapacity,
     };
 
-    // Override with user-provided bucket configuration
-    if (rateLimitingConfig.bucket) {
-        assert.strictEqual(
-            typeof rateLimitingConfig.bucket, 'object',
-            'rateLimiting.bucket must be an object'
-        );
-
-        // Parse default config for buckets (global default applied to all buckets)
-        // If defaultConfig is specified: Parse and validate the bucket rate limit settings
-        if (rateLimitingConfig.bucket.defaultConfig) {
-            const bucketConfig = rateLimitingConfig.bucket.defaultConfig;
-
-            // Validate config structure
-            assert.strictEqual(
-                typeof bucketConfig, 'object',
-                'rate limit config must be an object'
-            );
-
-            const limitConfig = {};
-
-            if (bucketConfig.requestsPerSecond) {
-                assert.strictEqual(
-                    typeof bucketConfig.requestsPerSecond, 'object',
-                    'requestsPerSecond must be an object'
-                );
-
-                const { limit } = bucketConfig.requestsPerSecond;
-
-                // Validate limit
-                assert(
-                    typeof limit === 'number' && Number.isInteger(limit) && limit >= 0,
-                    'requestsPerSecond.limit must be a non-negative integer'
-                );
-
-                // Validate limit against nodes AND workers
-                const minLimit = parsed.nodes * clusters;
-                if (limit > 0 && limit < minLimit) {
-                    throw new Error(
-                        `requestsPerSecond.limit (${limit}) must be >= ` +
-                        `(nodes × workers = ${parsed.nodes} × ${clusters} = ${minLimit}) ` +
-                        'or 0 (unlimited). Each worker enforces limit/nodes/workers locally. ' +
-                        `With limit < ${minLimit}, per-worker rate would be < 1 req/s, effectively blocking traffic.`
-                    );
-                }
-
-                // Default to global default burst capacity
-                let burstCapacity = parsed.bucket.defaultBurstCapacity;
-
-                // Override if provided in config
-                if (bucketConfig.requestsPerSecond.burstCapacity !== undefined) {
-                    burstCapacity = bucketConfig.requestsPerSecond.burstCapacity;
-                    assert(
-                        typeof burstCapacity === 'number' && Number.isInteger(burstCapacity) && burstCapacity > 0,
-                        'requestsPerSecond.burstCapacity must be a positive integer'
-                    );
-                }
-
-                // Calculate per-worker interval using distributed architecture
-                const interval = calculateInterval(limit, parsed.nodes, clusters);
-
-                // Store both the original limit and the calculated values
-                limitConfig.limit = limit;
-                limitConfig.requestsPerSecond = {
-                    interval,
-                    bucketSize: burstCapacity * 1000,
-                };
-            }
-
-            parsed.bucket.defaultConfig = limitConfig;
-        }
+    if (validated.bucket) {
+        parsed.bucket = transformClassConfig('bucket', validated.bucket, clusters, parsed.nodes);
+    }
 
-        // Parse config cache TTL
-        // If configCacheTTL is specified: Override the default cache TTL
-        if (rateLimitingConfig.bucket.configCacheTTL !== undefined) {
-            const configCacheTTL = rateLimitingConfig.bucket.configCacheTTL;
-            assert(
-                typeof configCacheTTL === 'number' &&
-                Number.isInteger(configCacheTTL) &&
-                configCacheTTL > 0,
-                'rateLimiting.bucket.configCacheTTL must be a positive integer'
-            );
-            parsed.bucket.configCacheTTL = configCacheTTL;
-        }
+    // Transform account configuration (if provided)
+    if (validated.account) {
+        parsed.account = transformClassConfig('account', validated.account, clusters, parsed.nodes);
     }
 
     // Parse error configuration (supports any HTTP 4xx/5xx status code)
     // Default to SlowDown error
     parsed.error = errors.SlowDown;
 
     // Override with custom error if specified
-    if (rateLimitingConfig.error !== undefined) {
-        // Validate error is an object
-        assert.strictEqual(
-            typeof rateLimitingConfig.error, 'object',
-            'rateLimiting.error must be an object'
-        );
-
-        // If statusCode is specified, validate and create custom error
-        if (rateLimitingConfig.error.statusCode !== undefined) {
-            assert(
-                typeof rateLimitingConfig.error.statusCode === 'number' &&
-                Number.isInteger(rateLimitingConfig.error.statusCode) &&
-                rateLimitingConfig.error.statusCode >= 400 &&
-                rateLimitingConfig.error.statusCode < 600,
-                'rateLimiting.error.statusCode must be a valid HTTP status code (400-599)'
-            );
-
-            // Validate error code if provided
-            const errorCode = rateLimitingConfig.error.code || 'SlowDown';
-            if (rateLimitingConfig.error.code !== undefined) {
-                assert.strictEqual(
-                    typeof rateLimitingConfig.error.code, 'string',
-                    'rateLimiting.error.code must be a string'
-                );
-            }
+    if (validated.error) {
+        const errorCode = validated.error.code || 'SlowDown';
+        const errorMessage = validated.error.message || errors.SlowDown.description;
 
-            // Validate error message if provided
-            const errorMessage = rateLimitingConfig.error.message || errors.SlowDown.description;
-            if (rateLimitingConfig.error.message !== undefined) {
-                assert.strictEqual(
-                    typeof rateLimitingConfig.error.message, 'string',
-                    'rateLimiting.error.message must be a string'
-                );
-            }
-
-            // Override default with custom Arsenal error
-            parsed.error = new ArsenalError(
-                errorCode,
-                rateLimitingConfig.error.statusCode,
-                errorMessage
-            );
-        }
+        // Create custom Arsenal error
+        parsed.error = new ArsenalError(
+            errorCode,
+            validated.error.statusCode,
+            errorMessage
+        );
     }
 
     return parsed;