chore: Implement custom LRU cache with protected keys

packages/relay/src/lib/clients/cache/impl/customLRUCache.ts

@@ -0,0 +1,172 @@
+/*
+ *
+ * Hedera JSON RPC Relay
+ *
+ * Copyright (C) 2024 Hedera Hashgraph, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import LRUCache from 'lru-cache';
+import findConfig from 'find-config';
+import fs from 'fs';
+import { Logger } from 'pino';
+import { SpendingPlanConfig } from '../../../types/spendingPlanConfig';
+import { EthAddressHbarSpendingPlanRepository } from '../../../db/repositories/hbarLimiter/ethAddressHbarSpendingPlanRepository';
+import { IPAddressHbarSpendingPlanRepository } from '../../../db/repositories/hbarLimiter/ipAddressHbarSpendingPlanRepository';
+import { HbarSpendingPlanRepository } from '../../../db/repositories/hbarLimiter/hbarSpendingPlanRepository';
+
+export class CustomLRUCache<K, V> extends LRUCache<K, V> {
+  /**
+   * The name of the spending plans configuration file. Defaults to `spendingPlansConfig.json`.
+   *
+   * @type {string}
+   * @private
+   */
+  private readonly SPENDING_PLANS_CONFIG_FILE: string =
+    process.env.HBAR_SPENDING_PLANS_CONFIG_FILE || 'spendingPlansConfig.json';
+
+  /**
+   * The spending plans configuration. This is loaded from the spending plans configuration file.
+   *
+   * @type {SpendingPlanConfig[]}
+   * @private
+   */
+  private readonly spendingPlansConfig: SpendingPlanConfig[];
+
+  constructor(
+    private readonly logger: Logger,
+    options: LRUCache.Options<K, V>,
+  ) {
+    super(options);
+    this.spendingPlansConfig = this.loadSpendingPlansConfig();
+  }
+
+  /**
+   * Deletes a key from the cache. If the key is protected, the deletion is ignored.
+   * @param {K} key - The key to delete.
+   * @returns {boolean} - True if the key was deleted, false otherwise.
+   * @template K - The key type.
+   */
+  delete(key: K): boolean {
+    if (typeof key === 'string' && this.isKeyProtected(key)) {
+      this.logger.trace(`Deletion of key ${key} is ignored as it is protected.`);
+      return false;
+    }
+    return super.delete(key);
+  }
+
+  /**
+   * Deletes a key from the cache without checking if it is protected.
+   * @param {K} key - The key to delete.
+   * @returns {boolean} - True if the key was deleted, false otherwise.
+   * @template K - The key type.
+   */
+  deleteUnsafe(key: K): boolean {
+    return super.delete(key);
+  }
+
+  /**
+   * Loads the pre-configured spending plans from the spending plans configuration file.
+   * @returns {SpendingPlanConfig[]} - The pre-configured spending plans.
+   * @private
+   */
+  private loadSpendingPlansConfig(): SpendingPlanConfig[] {
+    const configPath = findConfig(this.SPENDING_PLANS_CONFIG_FILE);
+    if (!configPath || !fs.existsSync(configPath)) {
+      this.logger.trace(`Configuration file not found at path "${configPath ?? this.SPENDING_PLANS_CONFIG_FILE}"`);
+      return [];
+    }
+    try {
+      const rawData = fs.readFileSync(configPath, 'utf-8');
+      return JSON.parse(rawData) as SpendingPlanConfig[];
+    } catch (error: any) {
+      this.logger.error(`Failed to parse JSON from ${configPath}: ${error.message}`);
+      return [];
+    }
+  }
+
+  /**
+   * Determines if a key is protected. A key is protected if it is associated with a pre-configured spending plan.
+   * @param {string} key - The key to check.
+   * @returns {boolean} - True if the key is protected, false otherwise.
+   * @private
+   */
+  private isKeyProtected(key: string): boolean {
+    if (this.isHbarSpendingPlanRepositoryKey(key)) {
+      return this.spendingPlansConfig.some((plan) => {
+        return (
+          this.isPreconfiguredPlanKey(key, plan) ||
+          this.isPreconfiguredEthAddressKey(key, plan) ||
+          this.isPreconfiguredIpAddressKey(key, plan)
+        );
+      });
+    }
+    return false;
+  }
+
+  /**
+   * Determines if a key is associated with any of the spending plan repositories.
+   * @param {string} key - The key to check.
+   * @returns {boolean} - True if the key is associated with a spending plan repository, false otherwise.
+   * @private
+   */
+  private isHbarSpendingPlanRepositoryKey(key: string): boolean {
+    if (!key) {
+      return false;
+    }
+    return (
+      key.startsWith(HbarSpendingPlanRepository.collectionKey) ||
+      key.startsWith(EthAddressHbarSpendingPlanRepository.collectionKey) ||
+      key.startsWith(IPAddressHbarSpendingPlanRepository.collectionKey)
+    );
+  }
+
+  /**
+   * Determines if a key is associated with a pre-configured spending plan.
+   * @param {string} key - The key to check.
+   * @param {SpendingPlanConfig} plan - The spending plan to check against.
+   * @returns {boolean} - True if the key is associated with the spending plan, false otherwise.
+   * @private
+   */
+  private isPreconfiguredPlanKey(key: string, plan: SpendingPlanConfig): boolean {
+    return key.includes(`${HbarSpendingPlanRepository.collectionKey}:${plan.id}`);
+  }
+
+  /**
+   * Determines if a key is associated with a pre-configured ETH address.
+   * @param {string} key - The key to check.
+   * @param {SpendingPlanConfig} plan - The spending plan to check against.
+   * @returns {boolean} - True if the key is associated with the ETH address, false otherwise.
+   * @private
+   */
+  private isPreconfiguredEthAddressKey(key: string, plan: SpendingPlanConfig): boolean {
+    return (plan.ethAddresses || []).some((ethAddress) => {
+      return key.includes(`${EthAddressHbarSpendingPlanRepository.collectionKey}:${ethAddress.trim().toLowerCase()}`);
+    });
+  }
+
+  /**
+   * Determines if a key is associated with a pre-configured IP address.
+   * @param {string} key - The key to check.
+   * @param {SpendingPlanConfig} plan - The spending plan to check against.
+   * @returns {boolean} - True if the key is associated with the IP address, false otherwise.
+   * @private
+   */
+  private isPreconfiguredIpAddressKey(key: string, plan: SpendingPlanConfig): boolean {
+    return (plan.ipAddresses || []).some((ipAddress) => {
+      return key.includes(`${IPAddressHbarSpendingPlanRepository.collectionKey}:${ipAddress}`);
+    });
+  }
+}

packages/relay/src/lib/clients/cache/localLRUCache.ts

@@ -22,9 +22,10 @@ import { Logger } from 'pino';
 import { Gauge, Registry } from 'prom-client';
 import { ICacheClient } from './ICacheClient';
 import constants from '../../constants';
-import LRUCache, { LimitedByCount, LimitedByTTL } from 'lru-cache';
+import { LimitedByCount, LimitedByTTL } from 'lru-cache';
 import { RequestDetails } from '../../types';
 import { Utils } from '../../../utils';
+import { CustomLRUCache } from './impl/customLRUCache';
 
 /**
  * Represents a LocalLRUCache instance that uses an LRU (Least Recently Used) caching strategy
@@ -49,7 +50,7 @@ export class LocalLRUCache implements ICacheClient {
    *
    * @private
    */
-  private readonly cache: LRUCache<string, any>;
+  private readonly cache: CustomLRUCache<string, any>;
 
   /**
    * The logger used for logging all output from this class.
@@ -74,7 +75,7 @@ export class LocalLRUCache implements ICacheClient {
    * @param {Registry} register - The registry instance used for metrics tracking.
    */
   public constructor(logger: Logger, register: Registry) {
-    this.cache = new LRUCache(this.options);
+    this.cache = new CustomLRUCache(logger.child({ name: 'custom-lru-cache' }), this.options);
     this.logger = logger;
     this.register = register;
 
@@ -212,7 +213,7 @@ export class LocalLRUCache implements ICacheClient {
    */
   public async delete(key: string, callingMethod: string, requestDetails: RequestDetails): Promise<void> {
     this.logger.trace(`${requestDetails.formattedRequestId} delete cache for ${key}`);
-    this.cache.delete(key);
+    this.cache.deleteUnsafe(key);
   }
 
   /**

packages/relay/src/lib/db/repositories/hbarLimiter/ethAddressHbarSpendingPlanRepository.ts

@@ -26,7 +26,7 @@ import { EthAddressHbarSpendingPlan } from '../../entities/hbarLimiter/ethAddres
 import { RequestDetails } from '../../../types';
 
 export class EthAddressHbarSpendingPlanRepository {
-  private readonly collectionKey = 'ethAddressHbarSpendingPlan';
+  public static readonly collectionKey = 'ethAddressHbarSpendingPlan';
 
   /**
    * The cache service used for storing data.
@@ -161,6 +161,6 @@ export class EthAddressHbarSpendingPlanRepository {
    * @private
    */
   private getKey(ethAddress: string): string {
-    return `${this.collectionKey}:${ethAddress?.trim().toLowerCase()}`;
+    return `${EthAddressHbarSpendingPlanRepository.collectionKey}:${ethAddress?.trim().toLowerCase()}`;
   }
 }

packages/relay/src/lib/db/repositories/hbarLimiter/hbarSpendingPlanRepository.ts

@@ -30,7 +30,7 @@ import { HbarSpendingPlan } from '../../entities/hbarLimiter/hbarSpendingPlan';
 import { RequestDetails } from '../../../types';
 
 export class HbarSpendingPlanRepository {
-  private readonly collectionKey = 'hbarSpendingPlan';
+  public static readonly collectionKey = 'hbarSpendingPlan';
 
   /**
    * The cache service used for storing data.
@@ -266,7 +266,7 @@ export class HbarSpendingPlanRepository {
    * @private
    */
   private getKey(id: string): string {
-    return `${this.collectionKey}:${id}`;
+    return `${HbarSpendingPlanRepository.collectionKey}:${id}`;
   }
 
   /**
@@ -275,7 +275,7 @@ export class HbarSpendingPlanRepository {
    * @private
    */
   private getAmountSpentKey(id: string): string {
-    return `${this.collectionKey}:${id}:amountSpent`;
+    return `${HbarSpendingPlanRepository.collectionKey}:${id}:amountSpent`;
   }
 
   /**
@@ -284,6 +284,6 @@ export class HbarSpendingPlanRepository {
    * @private
    */
   private getSpendingHistoryKey(id: string): string {
-    return `${this.collectionKey}:${id}:spendingHistory`;
+    return `${HbarSpendingPlanRepository.collectionKey}:${id}:spendingHistory`;
   }
 }

packages/relay/src/lib/db/repositories/hbarLimiter/ipAddressHbarSpendingPlanRepository.ts

@@ -26,7 +26,7 @@ import { IPAddressHbarSpendingPlan } from '../../entities/hbarLimiter/ipAddressH
 import { RequestDetails } from '../../../types';
 
 export class IPAddressHbarSpendingPlanRepository {
-  private readonly collectionKey = 'ipAddressHbarSpendingPlan';
+  public static readonly collectionKey = 'ipAddressHbarSpendingPlan';
 
   /**
    * The cache service used for storing data.
@@ -161,6 +161,6 @@ export class IPAddressHbarSpendingPlanRepository {
    * @private
    */
   private getKey(ipAddress: string): string {
-    return `${this.collectionKey}:${ipAddress}`;
+    return `${IPAddressHbarSpendingPlanRepository.collectionKey}:${ipAddress}`;
   }
 }

packages/relay/tests/helpers.ts

@@ -65,6 +65,10 @@ const random20BytesAddress = (addHexPrefix = true) => {
   return (addHexPrefix ? '0x' : '') + crypto.randomBytes(20).toString('hex');
 };
 
+const randomIpAddress = () => {
+  return Array.from({ length: 4 }, () => Math.floor(Math.random() * 256)).join('.');
+};
+
 export const toHex = (num) => {
   return `0x${Number(num).toString(16)}`;
 };
@@ -358,6 +362,7 @@ export {
   signTransaction,
   mockData,
   random20BytesAddress,
+  randomIpAddress,
   getRequestId,
   getQueryParams,
 };