feat: Added ability to load spending plans from environment variable.

.github/workflows/acceptance.yml

@@ -43,11 +43,17 @@ jobs:
       testfilter: ratelimiter
       test_ws_server: true
 
-  hbarlimiter:
-    name: HBar Limiter
+  hbarlimiter_batch_1:
+    name: HBar Limiter Batch 1
     uses: ./.github/workflows/acceptance-workflow.yml
     with:
-      testfilter: hbarlimiter
+      testfilter: hbarlimiter_batch1
+
+  hbarlimiter_batch_2:
+    name: HBar Limiter Batch 2
+    uses: ./.github/workflows/acceptance-workflow.yml
+    with:
+      testfilter: hbarlimiter_batch2
 
   tokencreate:
     name: Token Create

docs/configuration.md

@@ -75,7 +75,7 @@ Unless you need to set a non-default value, it is recommended to only populate o
 | `HBAR_RATE_LIMIT_BASIC`                     | "1120000000"               | Individual limit (in tinybars) for spending plans with a BASIC tier. Defaults to 11.2 HBARs.                                                                                                                                                                                                           |
 | `HBAR_RATE_LIMIT_EXTENDED`                  | "3200000000"               | Individual limit (in tinybars) for spending plans with a EXTENDED tier. Defaults to 32 HBARs.                                                                                                                                                                                                          |
 | `HBAR_RATE_LIMIT_PRIVILEGED`                | "8000000000"               | Individual limit (in tinybars) for spending plans with a PRIVILEGED tier. Defaults to 80 HBARs.                                                                                                                                                                                                        |
-| `HBAR_SPENDING_PLANS_CONFIG_FILE`           | "spendingPlansConfig.json" | The name of the JSON file containing the pre-configured spending plans for supported projects and partner projects.                                                                                                                                                                                    |
+| `HBAR_SPENDING_PLANS_CONFIG`                | "spendingPlansConfig.json" | The environment variable that either points to a file containing the spending plans, or the JSON content defining the spending plans.                                                                                                                                                                                    |
 | `HAPI_CLIENT_DURATION_RESET`                | "3600000"                  | Time until client reinitialization. (ms)                                                                                                                                                                                                                                                               |
 | `HAPI_CLIENT_ERROR_RESET`                   | [21, 50]                   | Array of status codes, which when encountered will trigger a reinitialization. Status codes are availble [here](https://github.com/hashgraph/hedera-protobufs/blob/main/services/response_code.proto).                                                                                                 |
 | `HAPI_CLIENT_TRANSACTION_RESET`             | "50"                       | Number of transaction executions, until client reinitialization.                                                                                                                                                                                                                                       |

docs/design/hbar-limiter.md

@@ -12,6 +12,9 @@
     - [Early Detection and Prevention (Preemptive Rate Limit)](#early-detection-and-prevention-preemptive-rate-limit)
   - [Architecture](#architecture)
     - [High-Level Design](#high-level-design)
+    - [What is an HbarSpendingPlan?](#what-is-an-hbarspendingplan)
+    - [General Users (BASIC tier):](#general-users-basic-tier)
+    - [Supported Projects (EXTENDED tier) and Trusted Partners (PRIVILEGED tier):](#supported-projects-extended-tier-and-trusted-partners-privileged-tier)
     - [Class Diagram](#class-diagram)
       - [Service Layer](#service-layer)
       - [Database Layer:](#database-layer)
@@ -21,6 +24,12 @@
         - [Allocation Algorithm](#allocation-algorithm)
   - [Configurations](#configurations)
     - [Pre-populating the Cache with Spending Plans for Supported Projects and Partner Projects](#pre-populating-the-cache-with-spending-plans-for-supported-projects-and-partner-projects)
+    - [JSON Configuration File](#json-configuration-file)
+      - [The JSON file should have the following structure:](#the-json-file-should-have-the-following-structure)
+      - [Important notes](#important-notes)
+    - [Incremental changes to the JSON file](#incremental-changes-to-the-json-file)
+      - [Adding new partners or supported projects](#adding-new-partners-or-supported-projects)
+      - [Removing or updating existing partners or supported projects](#removing-or-updating-existing-partners-or-supported-projects)
     - [Spending Limits of Different Tiers](#spending-limits-of-different-tiers)
     - [Total Budget and Limit Duration](#total-budget-and-limit-duration)
   - [Additional Considerations](#additional-considerations)
@@ -319,8 +328,8 @@ All other users (ETH and IP addresses which are not specified in the configurati
 
 The relay will read the pre-configured spending plans from a JSON file. This file should be placed in the root directory of the relay.
 
-The default filename for the configuration file is `spendingPlansConfig.json`, but it could also be specified by the environment variable `HBAR_SPENDING_PLANS_CONFIG_FILE`.
-- `HBAR_SPENDING_PLANS_CONFIG_FILE`: The name of the file containing the pre-configured spending plans for supported projects and partners.
+The default filename for the configuration file is `spendingPlansConfig.json`, but it could also be specified by the environment variable `HBAR_SPENDING_PLANS_CONFIG`.
+- `HBAR_SPENDING_PLANS_CONFIG`: The name of the file or environment variable containing the pre-configured spending plans for supported projects and partners.
 
 #### The JSON file should have the following structure:
 ```json

package.json

@@ -47,7 +47,8 @@
     "acceptancetest:api_batch3": "nyc ts-mocha packages/server/tests/acceptance/index.spec.ts  -g '@api-batch-3' --exit",
     "acceptancetest:erc20": "nyc ts-mocha packages/server/tests/acceptance/index.spec.ts  -g '@erc20' --exit",
     "acceptancetest:ratelimiter": "nyc ts-mocha packages/ws-server/tests/acceptance/index.spec.ts -g '@web-socket-ratelimiter' --exit && ts-mocha packages/server/tests/acceptance/index.spec.ts -g '@ratelimiter' --exit",
-    "acceptancetest:hbarlimiter": "HBAR_RATE_LIMIT_TINYBAR=5000000000 HBAR_RATE_LIMIT_BASIC=1000000000 HBAR_RATE_LIMIT_EXTENDED=1500000000 HBAR_RATE_LIMIT_PRIVILEGED=2000000000 nyc ts-mocha packages/server/tests/acceptance/index.spec.ts -g '@hbarlimiter' --exit",
+    "acceptancetest:hbarlimiter_batch1": "HBAR_RATE_LIMIT_BASIC=1000000000 HBAR_RATE_LIMIT_EXTENDED=1500000000 HBAR_RATE_LIMIT_PRIVILEGED=2000000000 nyc ts-mocha packages/server/tests/acceptance/index.spec.ts -g '@hbarlimiter-batch1' --exit",
+    "acceptancetest:hbarlimiter_batch2": "HBAR_RATE_LIMIT_BASIC=1000000000 HBAR_RATE_LIMIT_EXTENDED=1500000000 HBAR_RATE_LIMIT_PRIVILEGED=2000000000 nyc ts-mocha packages/server/tests/acceptance/index.spec.ts -g '@hbarlimiter-batch2' --exit",
     "acceptancetest:tokencreate": "nyc ts-mocha packages/server/tests/acceptance/index.spec.ts  -g '@tokencreate' --exit",
     "acceptancetest:tokenmanagement": "nyc ts-mocha packages/server/tests/acceptance/index.spec.ts  -g '@tokenmanagement' --exit",
     "acceptancetest:htsprecompilev1": "nyc ts-mocha packages/server/tests/acceptance/index.spec.ts  -g '@htsprecompilev1' --exit",

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

@@ -321,8 +321,8 @@ export class GlobalConfig {
       required: true,
       defaultValue: null,
     },
-    HBAR_SPENDING_PLANS_CONFIG_FILE: {
-      envName: 'HBAR_SPENDING_PLANS_CONFIG_FILE',
+    HBAR_SPENDING_PLANS_CONFIG: {
+      envName: 'HBAR_SPENDING_PLANS_CONFIG',
       type: 'string',
       required: false,
       defaultValue: 'spendingPlansConfig.json',

packages/config-service/tests/src/services/loggerService.spec.ts

@@ -37,7 +37,7 @@ describe('LoggerService tests', async function () {
   });
 
   it('should be able to mask every value if it starts with known secret prefix', async () => {
-    const { envName } = GlobalConfig.ENTRIES.HBAR_SPENDING_PLANS_CONFIG_FILE;
+    const { envName } = GlobalConfig.ENTRIES.OPERATOR_KEY_MAIN;
 
     for (const prefix of LoggerService.KNOWN_SECRET_PREFIXES) {
       const value = prefix + '_VVurqVVh68wgxgcVjrvVVVcNcVVVVi3CRwl1';

packages/relay/src/lib/config/hbarSpendingPlanConfigService.ts

@@ -30,13 +30,6 @@
 import { IDetailedHbarSpendingPlan } from '../db/types/hbarLimiter/hbarSpendingPlan';
 import { ConfigService } from '@hashgraph/json-rpc-config-service/dist/services';
 
-/**
- * Service for managing pre-configured {@link HbarSpendingPlan} entities.
- *
- * It reads the pre-configured spending plans from a JSON file and populates the cache with them.
- *
- * @see SpendingPlanConfig
- */
 export class HbarSpendingPlanConfigService {
   /**
    * The time-to-live (TTL) for the pre-configured spending plans in the cache.
@@ -127,17 +120,31 @@
    * @private
    */
   private static loadSpendingPlansConfig(logger: Logger): SpendingPlanConfig[] {
-    const filename = String(ConfigService.get('HBAR_SPENDING_PLANS_CONFIG_FILE'));
-    const configPath = findConfig(filename);
-    if (!configPath || !fs.existsSync(configPath)) {
-      logger.trace(`Configuration file not found at path "${configPath ?? filename}"`);
-      return [];
+    const spendingPlanConfig = ConfigService.get('HBAR_SPENDING_PLANS_CONFIG') as string;
+
+    if (!spendingPlanConfig) {
+      throw new Error('HBAR_SPENDING_PLANS_CONFIG is undefined');
     }
+
+    // Try to parse the value directly as JSON
     try {
-      const rawData = fs.readFileSync(configPath, 'utf-8');
-      return JSON.parse(rawData) as SpendingPlanConfig[];
-    } catch (error: any) {
-      throw new Error(`Failed to parse JSON from ${configPath}: ${error.message}`);
+      return JSON.parse(spendingPlanConfig) as SpendingPlanConfig[];
+    } catch (jsonParseError: any) {
+      // If parsing as JSON fails, treat it as a file path
+      logger.trace(
+        `Failed to parse HBAR_SPENDING_PLAN as JSON: ${jsonParseError.message}, now treating it as a file path...`,
+      );
+      try {
+        const configFilePath = findConfig(spendingPlanConfig);
+        if (configFilePath && fs.existsSync(configFilePath)) {
+          const fileContent = fs.readFileSync(configFilePath, 'utf-8');
+          return JSON.parse(fileContent) as SpendingPlanConfig[];
+        } else {
+          throw new Error(`Configuration file not found at path "${configFilePath ?? spendingPlanConfig}"`);
+        }
+      } catch (fileError: any) {
+        throw new Error(`File error: ${fileError.message}`);
+      }
     }
   }
 

packages/relay/tests/lib/config/hbarSpendingPlanConfigService.spec.ts

@@ -29,7 +29,14 @@ import chai, { expect } from 'chai';
 import chaiAsPromised from 'chai-as-promised';
 import { SpendingPlanConfig } from '../../../src/lib/types/spendingPlanConfig';
 import { RequestDetails } from '../../../src/lib/types';
-import { overrideEnvsInMochaDescribe, toHex, useInMemoryRedisServer, verifyResult } from '../../helpers';
+import {
+  overrideEnvsInMochaDescribe,
+  startRedisInMemoryServer,
+  stopRedisInMemoryServer,
+  toHex,
+  verifyResult,
+  withOverriddenEnvsInMochaTest,
+} from '../../helpers';
 import findConfig from 'find-config';
 import { HbarSpendingPlanConfigService } from '../../../src/lib/config/hbarSpendingPlanConfigService';
 import { CacheService } from '../../../src/lib/services/cacheService/cacheService';
@@ -40,6 +47,8 @@ import {
   HbarSpendingPlanNotFoundError,
   IPAddressHbarSpendingPlanNotFoundError,
 } from '../../../src/lib/db/types/hbarLimiter/errors';
+import { ConfigServiceTestHelper } from '@hashgraph/json-rpc-config-service/tests/configServiceTestHelper';
+import { RedisInMemoryServer } from '../../redisInMemoryServer';
 
 chai.use(chaiAsPromised);
 
@@ -62,7 +71,7 @@ describe('HbarSpendingPlanConfigService', function () {
   const path = findConfig(spendingPlansConfigFile);
   const spendingPlansConfig = JSON.parse(fs.readFileSync(path!, 'utf-8')) as SpendingPlanConfig[];
 
-  const tests = (isSharedCacheEnabled: boolean) => {
+  const tests = (isSharedCacheEnabled: boolean, isSpendingPlansConfigFile: boolean) => {
     let cacheService: CacheService;
     let hbarSpendingPlanRepository: HbarSpendingPlanRepository;
     let ethAddressHbarSpendingPlanRepository: EthAddressHbarSpendingPlanRepository;
@@ -74,20 +83,26 @@ describe('HbarSpendingPlanConfigService', function () {
     let hbarSpendingPlanRepositorySpy: sinon.SinonSpiedInstance<HbarSpendingPlanRepository>;
     let ethAddressHbarSpendingPlanRepositorySpy: sinon.SinonSpiedInstance<EthAddressHbarSpendingPlanRepository>;
     let ipAddressHbarSpendingPlanRepositorySpy: sinon.SinonSpiedInstance<IPAddressHbarSpendingPlanRepository>;
+    let redisInMemoryServer: RedisInMemoryServer;
 
     overrideEnvsInMochaDescribe({
-      HBAR_SPENDING_PLANS_CONFIG_FILE: spendingPlansConfigFile,
       CACHE_TTL: '100',
       CACHE_MAX: spendingPlansConfig.length.toString(),
     });
 
-    if (isSharedCacheEnabled) {
-      useInMemoryRedisServer(logger, 6384);
+    if (isSpendingPlansConfigFile) {
+      ConfigServiceTestHelper.dynamicOverride('HBAR_SPENDING_PLANS_CONFIG', spendingPlansConfigFile);
     } else {
-      overrideEnvsInMochaDescribe({ REDIS_ENABLED: 'false' });
+      ConfigServiceTestHelper.dynamicOverride('HBAR_SPENDING_PLANS_CONFIG', JSON.stringify(spendingPlansConfig));
     }
 
-    before(function () {
+    before(async function () {
+      if (isSharedCacheEnabled) {
+        redisInMemoryServer = await startRedisInMemoryServer(logger, 6384);
+      } else {
+        overrideEnvsInMochaDescribe({ REDIS_ENABLED: 'false' });
+      }
+
       const reservedKeys = HbarSpendingPlanConfigService.getPreconfiguredSpendingPlanKeys(logger);
       cacheService = new CacheService(logger.child({ name: 'cache-service' }), registry, reservedKeys);
       hbarSpendingPlanRepository = new HbarSpendingPlanRepository(
@@ -110,6 +125,12 @@ describe('HbarSpendingPlanConfigService', function () {
       );
     });
 
+    after(async function () {
+      if (isSharedCacheEnabled) {
+        await stopRedisInMemoryServer(redisInMemoryServer);
+      }
+    });
+
     beforeEach(function () {
       loggerSpy = sinon.spy(logger);
       cacheServiceSpy = sinon.spy(cacheService);
@@ -130,12 +151,19 @@ describe('HbarSpendingPlanConfigService', function () {
           await expect(hbarSpendingPlanConfigService.populatePreconfiguredSpendingPlans()).not.to.be.rejected;
         });
 
-        it('should throw an error if configuration file is not a parsable JSON', async function () {
-          sinon.stub(fs, 'readFileSync').returns('invalid JSON');
-          await expect(hbarSpendingPlanConfigService.populatePreconfiguredSpendingPlans()).to.be.rejectedWith(
-            `Failed to parse JSON from ${path}: Unexpected token 'i', "invalid JSON" is not valid JSON`,
-          );
-        });
+        withOverriddenEnvsInMochaTest(
+          {
+            HBAR_SPENDING_PLANS_CONFIG: spendingPlansConfigFile,
+          },
+          () => {
+            it('should throw an error if configuration file is not a parsable JSON', async function () {
+              sinon.stub(fs, 'readFileSync').returns('invalid JSON');
+              await expect(hbarSpendingPlanConfigService.populatePreconfiguredSpendingPlans()).to.be.rejectedWith(
+                `Unexpected token 'i', "invalid JSON" is not valid JSON`,
+              );
+            });
+          },
+        );
 
         it('should throw an error if the configuration file has entry without ID', async function () {
           const invalidPlan = {
@@ -356,6 +384,11 @@ describe('HbarSpendingPlanConfigService', function () {
         };
 
         it('should populate the database with pre-configured spending plans', async function () {
+          // Clear existing spending plans.  Needed in CI environment where the plans are already populated
+          for (const plan of spendingPlansConfig) {
+            await hbarSpendingPlanRepository.delete(plan.id, emptyRequestDetails);
+          }
+
           await hbarSpendingPlanConfigService.populatePreconfiguredSpendingPlans();
 
           spendingPlansConfig.forEach(({ id, name, subscriptionTier }) => {
@@ -651,11 +684,23 @@ describe('HbarSpendingPlanConfigService', function () {
     });
   };
 
-  describe('with shared cache enabled', function () {
-    tests(true);
+  describe('using Redis cache', function () {
+    describe('and with a spending plan config file', function () {
+      tests(true, true);
+    });
+
+    describe('and with a spending plan config variable', function () {
+      tests(true, false);
+    });
   });
 
-  describe('with shared cache disabled', function () {
-    tests(false);
+  describe('using LRU cache', function () {
+    describe('and with a spending plan config file', function () {
+      tests(false, true);
+    });
+
+    describe('and with a spending plan config variable', function () {
+      tests(false, false);
+    });
   });
 });

packages/relay/tests/lib/relay.spec.ts

@@ -94,7 +94,7 @@ describe('RelayImpl', () => {
     });
 
     describe('when a configuration file is provided', () => {
-      overrideEnvsInMochaDescribe({ HBAR_SPENDING_PLANS_CONFIG_FILE: 'spendingPlansConfig.example.json' });
+      overrideEnvsInMochaDescribe({ HBAR_SPENDING_PLANS_CONFIG: 'spendingPlansConfig.example.json' });
 
       it('should populate preconfigured spending plans successfully', async () => {
         expect((relay = new RelayImpl(logger, register))).to.not.throw;
@@ -121,7 +121,7 @@ describe('RelayImpl', () => {
     describe('when a configuration file with invalid JSON is provided', () => {
       let path: string | null;
 
-      overrideEnvsInMochaDescribe({ HBAR_SPENDING_PLANS_CONFIG_FILE: 'spendingPlansConfig.example.json' });
+      overrideEnvsInMochaDescribe({ HBAR_SPENDING_PLANS_CONFIG: 'spendingPlansConfig.example.json' });
 
       beforeEach(() => {
         path = findConfig('spendingPlansConfig.example.json');
@@ -134,8 +134,7 @@ describe('RelayImpl', () => {
         expect(populatePreconfiguredSpendingPlansSpy.calledOnce).to.be.true;
         await expect(populatePreconfiguredSpendingPlansSpy.returnValues[0]).not.to.be.rejected;
 
-        const cause = `Failed to parse JSON from ${path}: Unexpected token 'i', "invalid JSON" is not valid JSON`;
-        const message = `Failed to load pre-configured spending plans: ${cause}`;
+        const message = `Failed to load pre-configured spending plans: File error: Unexpected token 'i', "invalid JSON" is not valid JSON`;
         expect(loggerSpy.warn.calledWith(message)).to.be.true;
       });
     });