feat: make class propertie configurable

Signed-off-by: Logan Nguyen <[email protected]>

Author: quiet-node

docs/configuration.md

@@ -67,6 +67,10 @@ Unless you need to set a non-default value, it is recommended to only populate o
 | `IP_RATE_LIMIT_STORE`                       | null                                  | Specifies the rate limit store to use for IP-based rate limiting: valid values are "LRU", "REDIS", with the possibility to be extended with a custom implementation (see [Store Selection](rate-limiting.md#store-selection)). If unset, falls back to Redis when `REDIS_ENABLED=true`, otherwise uses in-memory LRU.                                                                                                                                                                      |
 | `JUMBO_TX_ENABLED`                          | "true"                                | Controls how large transactions are handled during `eth_sendRawTransaction`. When set to `true`, transactions up to 128KB can be sent directly to consensus nodes without using Hedera File Service (HFS), as long as contract bytecode doesn't exceed 24KB. When set to `false`, all transactions containing contract deployments use the traditional HFS approach. This feature leverages the increased transaction size limit to simplify processing of standard Ethereum transactions. |
 | `LIMIT_DURATION`                            | "60000"                               | The maximum duration in ms applied to IP-method based rate limits.                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `LOCK_ACQUISITION_TIMEOUT_MS`               | "300000"                              | Maximum time a process will wait to acquire a lock before giving up (default: 5 minutes). Applies to both local and Redis-based locks.                                                                                                                                                                                                                                                                                                                                                     |
+| `LOCK_LOCAL_MAX_CAPACITY`                   | "1000"                                | Maximum number of locks that can be held simultaneously in local memory. When this limit is reached, least recently used locks are evicted to make space for new ones.                                                                                                                                                                                                                                                                                                                     |
+| `LOCK_REDIS_ACQUISITION_POLL_INTERVAL_MS`   | "50"                                  | Interval in milliseconds between polling checks when waiting to acquire a Redis lock.                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `LOCK_TTL_MS`                               | "900000"                              | Maximum lifetime in milliseconds for any lock before it automatically expires (default: 15 minutes). This safety mechanism prevents abandoned locks from permanently blocking resources if a process crashes or the lock is not properly released. Applies to both local and Redis-based locks.                                                                                                                                                                                            |
 | `MAX_GAS_ALLOWANCE_HBAR`                    | "0"                                   | The maximum amount, in hbars, that the JSON-RPC Relay is willing to pay to complete the transaction in case the senders don't provide enough funds. Please note, in case of fully subsidized transactions, the sender must set the gas price to `0` and the JSON-RPC Relay must configure the `MAX_GAS_ALLOWANCE_HBAR` parameter high enough to cover the entire transaction cost.                                                                                                         |
 | `MAX_TRANSACTION_FEE_THRESHOLD`             | "15000000"                            | Used to set the max transaction fee. This is the HAPI fee which is paid by the relay operator account.                                                                                                                                                                                                                                                                                                                                                                                     |
 | `MIRROR_NODE_AGENT_CACHEABLE_DNS`           | "true"                                | Flag to set if the mirror node agent should cacheable DNS lookups, using better-lookup library.                                                                                                                                                                                                                                                                                                                                                                                            |

packages/config-service/src/services/globalConfig.ts

@@ -23,14 +23,14 @@ type ExtractTypeStringFromKey<K extends string> = K extends keyof typeof _CONFIG
 type StringTypeToActualType<Tstr extends string> = Tstr extends 'string'
   ? string
   : Tstr extends 'boolean'
-  ? boolean
-  : Tstr extends 'number'
-  ? number
-  : Tstr extends 'strArray'
-  ? string[]
-  : Tstr extends 'numArray'
-  ? number[]
-  : never;
+    ? boolean
+    : Tstr extends 'number'
+      ? number
+      : Tstr extends 'strArray'
+        ? string[]
+        : Tstr extends 'numArray'
+          ? number[]
+          : never;
 
 /**
  * Determines if a configuration value can be `undefined` based on two conditions:
@@ -46,8 +46,8 @@ type CanBeUndefined<K extends string> = K extends keyof typeof _CONFIG
   ? (typeof _CONFIG)[K]['required'] extends true
     ? false
     : (typeof _CONFIG)[K]['defaultValue'] extends null
-    ? true
-    : false
+      ? true
+      : false
   : never;
 
 /**
@@ -59,9 +59,10 @@ type CanBeUndefined<K extends string> = K extends keyof typeof _CONFIG
  * - `'WEB_SOCKET_PORT'` (`type: 'number'`, `required: false`, `defaultValue: 8546`) → `number`
  * - `'GITHUB_PR_NUMBER'` (`type: 'string'`, `required: false`, `defaultValue: null`) → `string | undefined`
  */
-export type GetTypeOfConfigKey<K extends string> = CanBeUndefined<K> extends true
-  ? StringTypeToActualType<ExtractTypeStringFromKey<K>> | undefined
-  : StringTypeToActualType<ExtractTypeStringFromKey<K>>;
+export type GetTypeOfConfigKey<K extends string> =
+  CanBeUndefined<K> extends true
+    ? StringTypeToActualType<ExtractTypeStringFromKey<K>> | undefined
+    : StringTypeToActualType<ExtractTypeStringFromKey<K>>;
 
 /**
  * Interface defining the structure of a configuration property.
@@ -357,6 +358,26 @@ const _CONFIG = {
     required: false,
     defaultValue: null,
   },
+  LOCK_ACQUISITION_TIMEOUT_MS: {
+    type: 'number',
+    required: false,
+    defaultValue: 300_000,
+  },
+  LOCK_LOCAL_MAX_CAPACITY: {
+    type: 'number',
+    required: false,
+    defaultValue: 1000,
+  },
+  LOCK_REDIS_ACQUISITION_POLL_INTERVAL_MS: {
+    type: 'number',
+    required: false,
+    defaultValue: 50,
+  },
+  LOCK_TTL_MS: {
+    type: 'number',
+    required: false,
+    defaultValue: 900_000,
+  },
   LOG_LEVEL: {
     type: 'string',
     required: false,

packages/relay/src/lib/services/lockService/LocalLockStrategy.ts

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 
+import { ConfigService } from '@hashgraph/json-rpc-config-service/dist/services';
 import { Mutex, withTimeout } from 'async-mutex';
 import { randomUUID } from 'crypto';
 import { LRUCache } from 'lru-cache';
@@ -19,25 +20,29 @@ interface LockState {
 }
 
 export class LocalLockStrategy implements LockStrategy {
+  /**
+   * Maximum time in milliseconds to wait for lock acquisition before timing out.
+   */
+  private readonly lockAcquisitionTimeoutMs = ConfigService.get('LOCK_ACQUISITION_TIMEOUT_MS');
+
+  /**
+   * LRU cache storing lock states indexed by lock ID.
+   * Automatically evicts least recently used locks when capacity is exceeded.
+   */
   private readonly lockStates: LRUCache<string, LockState>;
 
   /**
    * Creates a new LocalLockStrategy instance.
    *
    * @param logger - Logger instance for debugging and monitoring
-   * @param lockTimeoutMs - Lock acquisition timeout in milliseconds
-   * @param stateTtlMs - Lock state TTL for cleanup in milliseconds
-   * @param maxLocks - Maximum number of locks to track in LRU cache
    */
-  constructor(
-    private readonly logger: Logger,
-    private readonly lockTimeoutMs: number,
-    private readonly stateTtlMs: number,
-    private readonly maxLocks: number,
-  ) {
+  constructor(private readonly logger: Logger) {
+    const lockLocalMaxCapacity = ConfigService.get('LOCK_LOCAL_MAX_CAPACITY');
+    const lockTtlMs = ConfigService.get('LOCK_TTL_MS');
+
     this.lockStates = new LRUCache<string, LockState>({
-      max: this.maxLocks,
-      ttl: this.stateTtlMs,
+      max: lockLocalMaxCapacity,
+      ttl: lockTtlMs,
       dispose: (lockState: LockState, lockId: string) => {
         if (lockState.mutex.isLocked()) {
           try {
@@ -50,13 +55,16 @@ export class LocalLockStrategy implements LockStrategy {
         lockState.activeSessionKeys.clear();
       },
     });
+    this.logger.info(
+      `Local lock strategy initialized: lockAcquisitionTimeoutMs=${this.lockAcquisitionTimeoutMs}ms, lockTtlMs=${lockTtlMs}ms, lockLocalMaxCapacity=${lockLocalMaxCapacity}`,
+    );
   }
 
   /**
    * Acquires a local mutex lock for the specified resource.
    *
    * Uses async-mutex with timeout protection and session key tracking.
-   * If the lock is not available, waits up to lockTimeoutMs before throwing.
+   * If the lock is not available, waits up to lockAcquisitionTimeoutMs before throwing.
    *
    * @param lockId - The unique identifier of the resource to acquire the lock for
    * @returns Promise that resolves to a unique session key when the lock is acquired
@@ -74,7 +82,7 @@ export class LocalLockStrategy implements LockStrategy {
       this.lockStates.set(lockKey, lockState);
     }
 
-    const timeoutMutex = withTimeout(lockState.mutex, this.lockTimeoutMs);
+    const timeoutMutex = withTimeout(lockState.mutex, this.lockAcquisitionTimeoutMs);
     const waitStartedAt = Date.now();
     const sessionKey = randomUUID();
 
@@ -88,7 +96,9 @@ export class LocalLockStrategy implements LockStrategy {
       return sessionKey;
     } catch (error) {
       if (error instanceof Error && error.message.includes('timeout')) {
-        throw new Error(`Failed to acquire lock for resource ${lockId}: timeout after ${this.lockTimeoutMs}ms`);
+        throw new Error(
+          `Failed to acquire lock for resource ${lockId}: timeout after ${this.lockAcquisitionTimeoutMs}ms`,
+        );
       }
       this.logger.error(`Failed to acquire lock for ${lockId}:`, error);
       throw error;

packages/relay/src/lib/services/lockService/LockService.ts

@@ -8,18 +8,9 @@ import { LockStrategy } from './LockStrategy';
 import { RedisLockStrategy } from './RedisLockStrategy';
 
 export class LockService {
-  /** Lock acquisition timeout - how long a request waits before giving up (5 minutes) */
-  private static readonly DEFAULT_LOCK_TIMEOUT_MS = 300_000;
-
-  /** Prevents memory leaks from abandoned locks (15 minutes) */
-  private static readonly LOCK_TTL_MS = 15 * 60 * 1000;
-
-  /** Maximum concurrent resource locks to track (LRU eviction beyond this) */
-  private static readonly MAX_LOCKS = 1000;
-
-  /** Redis queue polling interval - checks FIFO position every 50ms */
-  private static readonly REDIS_POLL_INTERVAL_MS = 50;
-
+  /**
+   * The underlying lock strategy used for lock operations.
+   */
   private readonly lockStrategy: LockStrategy;
 
   /**
@@ -30,31 +21,16 @@ export class LockService {
    */
   constructor(logger: Logger) {
     // Initialize LocalLockStrategy as default lock strategy
-    this.lockStrategy = new LocalLockStrategy(
-      logger.child({ name: 'local-lock' }),
-      LockService.DEFAULT_LOCK_TIMEOUT_MS,
-      LockService.LOCK_TTL_MS,
-      LockService.MAX_LOCKS,
-    );
+    this.lockStrategy = new LocalLockStrategy(logger.child({ name: 'local-lock' }));
 
     // Initialize RedisLockStrategy
-    const redisLockStrategy = new RedisLockStrategy(
-      logger.child({ name: 'redis-lock' }),
-      LockService.DEFAULT_LOCK_TIMEOUT_MS,
-      LockService.LOCK_TTL_MS,
-      LockService.REDIS_POLL_INTERVAL_MS,
-    );
+    const redisLockStrategy = new RedisLockStrategy(logger.child({ name: 'redis-lock' }));
 
     if (this.isRedisEnabled()) {
-      // Switch to RedisLockStrategy if redis is enabled
       this.lockStrategy = redisLockStrategy;
-      logger.info(
-        `Using Redis distributed locking for main Lock Service: lockTimeoutMs=${LockService.DEFAULT_LOCK_TIMEOUT_MS}, lockTtlMs=${LockService.LOCK_TTL_MS}`,
-      );
+      logger.info('Lock Service main strategy set to Redis-distributed locking.');
     } else {
-      logger.info(
-        `Using local in-memory locking for main Lock Service: lockTimeoutMs=${LockService.DEFAULT_LOCK_TIMEOUT_MS}, lockTtlMs=${LockService.LOCK_TTL_MS}, maxLocks=${LockService.MAX_LOCKS}`,
-      );
+      logger.info('Lock Service main strategy set to local in-memory locking.');
     }
   }
 

packages/relay/src/lib/services/lockService/RedisLockStrategy.ts

@@ -8,24 +8,35 @@ import { createClient, type RedisClientType } from 'redis';
 import { LockStrategy } from './LockStrategy';
 
 export class RedisLockStrategy implements LockStrategy {
+  /**
+   * Maximum time in milliseconds to wait for lock acquisition before timing out.
+   */
+  private readonly lockAcquisitionTimeoutMs = ConfigService.get('LOCK_ACQUISITION_TIMEOUT_MS');
+
+  /**
+   * Maximum duration in milliseconds that a lock can exist before automatic expiration in Redis.
+   */
+  private readonly lockTtlMs = ConfigService.get('LOCK_TTL_MS');
+
+  /**
+   * Polling interval in milliseconds for checking queue position during lock acquisition.
+   * Lower values provide faster lock acquisition but increase Redis load.
+   */
+  private readonly acquisitionPollIntervalMs = ConfigService.get('LOCK_REDIS_ACQUISITION_POLL_INTERVAL_MS');
+
+  /** Redis client instance for distributed locking operations. */
   private redisClient?: RedisClientType;
+
+  /** Tracks Redis connection status. */
   private _isConnected: boolean = false;
 
   /**
    * Creates a new RedisLockStrategy instance and initializes Redis connection
-   * if enabled and resource is properly provided.
+   * if enabled and properly configured.
    *
    * @param logger - Logger instance for debugging and monitoring
-   * @param lockTimeoutMs - Lock acquisition timeout in milliseconds
-   * @param lockTtlMs - Redis lock TTL in milliseconds (auto-expiration)
-   * @param pollIntervalMs - Polling interval for queue checking in milliseconds
    */
-  constructor(
-    private readonly logger: Logger,
-    private readonly lockTimeoutMs: number,
-    private readonly lockTtlMs: number,
-    private readonly pollIntervalMs: number,
-  ) {
+  constructor(private readonly logger: Logger) {
     // Initialize Redis client only if enabled and URL is provided
     if (ConfigService.get('REDIS_ENABLED')) {
       try {
@@ -59,6 +70,10 @@ export class RedisLockStrategy implements LockStrategy {
           this._isConnected = false;
           this.logger.error('Error occurred with Redis Connection during Redis Lock Strategy initialization:', error);
         });
+
+        this.logger.info(
+          `Redis lock strategy initialized: lockAcquisitionTimeoutMs=${this.lockAcquisitionTimeoutMs}ms, lockTtlMs=${this.lockTtlMs}ms, acquisitionPollIntervalMs=${this.acquisitionPollIntervalMs}ms`,
+        );
       } catch (error) {
         this._isConnected = false;
         this.logger.error('Failed to create Redis client for Redis Lock Strategy:', error);
@@ -92,7 +107,7 @@ export class RedisLockStrategy implements LockStrategy {
       this.logger.debug(`New item joined lock queue: lockId=${lockId}, session=${sessionKey}`);
 
       // Poll until first in queue and can acquire the lock, or until exceeding timeout
-      while (Date.now() - waitStartedAt < this.lockTimeoutMs) {
+      while (Date.now() - waitStartedAt < this.lockAcquisitionTimeoutMs) {
         const firstInQueue = await this.redisClient.lIndex(queueKey, -1);
 
         if (firstInQueue === sessionKey) {
@@ -115,12 +130,14 @@ export class RedisLockStrategy implements LockStrategy {
           }
         }
 
-        await new Promise((resolve) => setTimeout(resolve, this.pollIntervalMs));
+        await new Promise((resolve) => setTimeout(resolve, this.acquisitionPollIntervalMs));
       }
 
       // Cleanup and throw if lock timed out
       await this.redisClient.lRem(queueKey, 1, sessionKey);
-      throw new Error(`Failed to acquire Redis lock for resource ${lockId}: timeout after ${this.lockTimeoutMs}ms`);
+      throw new Error(
+        `Failed to acquire Redis lock for resource ${lockId}: timeout after ${this.lockAcquisitionTimeoutMs}ms`,
+      );
     } catch (error) {
       // Cleanup queue entry on any error
       await this.redisClient.lRem(queueKey, 1, sessionKey).catch((cleanupError) => {