VIA-537 SB Initial lazy config object.

acerathereinspirative-nhs-nvir · acerathereinspirative-nhs-nvir · commit eef6c268db21 · 2025-11-20T15:30:21.000Z
VIA-537 SB Add SSM retrieval.

VIA-537 SB Add test for missing values and reuse of values from cache.

VIA-537 SB Implement TTL.

VIA-537 SB Docstrings for lazy objects.

VIA-537 SB Should retry if SSM call fails.

VIA-537 SB Set TTL in reset method, and log resets.

VIA-537 SB Improve type coercion.
diff --git a/src/utils/lazy-config.test.ts b/src/utils/lazy-config.test.ts
@@ -0,0 +1,155 @@
+import getSSMParam from "@src/utils/get-ssm-param";
+import lazyConfig, { ConfigError } from "@src/utils/lazy-config";
+import { randomString } from "@test-data/meta-builder";
+
+jest.mock("@src/utils/get-ssm-param");
+jest.mock("sanitize-data", () => ({ sanitize: jest.fn() }));
+
+describe("lazyConfig", () => {
+  const nowInSeconds = 0;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.useFakeTimers();
+    jest.setSystemTime(nowInSeconds * 1000);
+    lazyConfig.resetCache();
+    process.env = {
+      NODE_ENV: "test",
+    };
+  });
+
+  afterEach(() => {
+    jest.resetAllMocks();
+  });
+
+  afterAll(() => {
+    jest.useRealTimers();
+  });
+
+  const setupTestEnvVars = (prefix: string) => {
+    process.env.SSM_PREFIX = prefix;
+    process.env.CONTENT_API_ENDPOINT = "https://api-endpoint";
+    process.env.ELIGIBILITY_API_ENDPOINT = "https://elid-endpoint";
+    process.env.APIM_AUTH_URL = "https://apim-endpoint";
+  };
+
+  it("should return values from env if present, else from getSSMParam", async () => {
+    const prefix: string = "test/";
+    setupTestEnvVars(prefix);
+    const mockGetSSMParam = (getSSMParam as jest.Mock).mockResolvedValue("api-key");
+
+    expect(await lazyConfig.CONTENT_API_ENDPOINT).toEqual(new URL("https://api-endpoint"));
+    expect(await lazyConfig.CONTENT_API_KEY).toEqual("api-key");
+
+    expect(mockGetSSMParam).toHaveBeenCalledWith(`${prefix}CONTENT_API_KEY`);
+    expect(mockGetSSMParam).not.toHaveBeenCalledWith(`${prefix}CONTENT_API_ENDPOINT`);
+  });
+
+  it("should throw error if values aren't in env or SSM", async () => {
+    const prefix: string = "test/";
+    process.env.SSM_PREFIX = prefix;
+    const mockGetSSMParam = (getSSMParam as jest.Mock).mockResolvedValue(undefined);
+
+    await expect(async () => {
+      await lazyConfig.CONTENT_API_ENDPOINT;
+      await lazyConfig.CONTENT_API_KEY;
+    }).rejects.toThrow("Unable to get config item CONTENT_API_ENDPOINT");
+    expect(mockGetSSMParam).not.toHaveBeenCalledWith(`${prefix}CONTENT_API_KEY`);
+    expect(mockGetSSMParam).toHaveBeenCalledWith(`${prefix}CONTENT_API_ENDPOINT`);
+    expect(mockGetSSMParam).toHaveBeenCalledTimes(1);
+  });
+
+  it("should convert IS_APIM_AUTH_ENABLED to a false boolean value", async () => {
+    setupTestEnvVars("test/");
+    process.env.IS_APIM_AUTH_ENABLED = "false";
+
+    const actual = await lazyConfig.IS_APIM_AUTH_ENABLED;
+
+    expect(actual).toBe(false);
+  });
+
+  it("should convert IS_APIM_AUTH_ENABLED to a true boolean value", async () => {
+    setupTestEnvVars("test/");
+    process.env.IS_APIM_AUTH_ENABLED = "true";
+
+    const actual = await lazyConfig.IS_APIM_AUTH_ENABLED;
+
+    expect(actual).toBe(true);
+  });
+
+  it("should convert MAX_SESSION_AGE_MINUTES to a number", async () => {
+    setupTestEnvVars("test/");
+    process.env.MAX_SESSION_AGE_MINUTES = "99";
+
+    const actual = await lazyConfig.MAX_SESSION_AGE_MINUTES;
+
+    expect(actual).toBe(99);
+  });
+
+  it("should throw for invalid URL", async () => {
+    setupTestEnvVars("test/");
+    process.env.APIM_AUTH_URL = "not-a-url";
+
+    await expect(async () => {
+      await lazyConfig.APIM_AUTH_URL;
+    }).rejects.toThrow(ConfigError);
+  });
+
+  it("should throw for invalid number", async () => {
+    setupTestEnvVars("test/");
+    process.env.MAX_SESSION_AGE_MINUTES = "not-a-number";
+
+    await expect(async () => {
+      await lazyConfig.MAX_SESSION_AGE_MINUTES;
+    }).rejects.toThrow(ConfigError);
+  });
+
+  it("should reuse config values between subsequent calls", async () => {
+    setupTestEnvVars("test/");
+    const mockGetSSMParam = (getSSMParam as jest.Mock).mockImplementation(() => randomString(5));
+
+    await lazyConfig.NHS_LOGIN_CLIENT_ID;
+
+    expect(mockGetSSMParam).toHaveBeenCalled();
+    mockGetSSMParam.mockClear();
+
+    await lazyConfig.NHS_LOGIN_CLIENT_ID;
+
+    expect(mockGetSSMParam).not.toHaveBeenCalled();
+  });
+
+  it("should expire config after ttl", async () => {
+    setupTestEnvVars("test/");
+    const mockGetSSMParam = (getSSMParam as jest.Mock).mockImplementation(() => "test-value");
+
+    await lazyConfig.CONTENT_API_KEY;
+
+    expect(mockGetSSMParam).toHaveBeenCalled();
+    mockGetSSMParam.mockClear();
+    jest.setSystemTime(nowInSeconds * 1000 + 300 * 1000 + 1);
+
+    await lazyConfig.CONTENT_API_KEY;
+
+    expect(mockGetSSMParam).toHaveBeenCalled();
+  });
+
+  it("should retry fetching from SSM if the first attempt fails", async () => {
+    const key = "API_SECRET";
+    const expectedValue = "value-from-ssm-on-second-try";
+    const expectedSsmPath = `/test/ci/${key}`;
+
+    process.env.SSM_PREFIX = "/test/ci/";
+
+    const mockGetSSMParam = (getSSMParam as jest.Mock)
+      .mockRejectedValueOnce(new Error("SSM is temporarily unavailable"))
+      .mockResolvedValue(expectedValue);
+
+    const resultPromise = lazyConfig.API_SECRET;
+    await jest.runOnlyPendingTimersAsync();
+    const result = await resultPromise;
+
+    expect(result).toBe(expectedValue);
+    expect(mockGetSSMParam).toHaveBeenCalledTimes(2);
+    expect(mockGetSSMParam).toHaveBeenCalledWith(expectedSsmPath);
+  });
+});
diff --git a/src/utils/lazy-config.ts b/src/utils/lazy-config.ts
@@ -0,0 +1,180 @@
+import { EligibilityApiError } from "@src/services/eligibility-api/gateway/exceptions";
+import getSSMParam from "@src/utils/get-ssm-param";
+import { logger } from "@src/utils/logger";
+import { retry } from "es-toolkit";
+import { Logger } from "pino";
+
+const log: Logger = logger.child({ module: "lazy-config" });
+
+type ConfigValue = string | number | boolean | URL | undefined;
+
+/**
+ * A wrapper around an object which intercepts access to properties. If the property really exists on the object,
+ * that's what the caller gets, but if it doesn't, the object's getAttribute("property-name") is called instead.
+ */
+function createReadOnlyDynamic<T extends object>(instance: T): T & { [key: string]: Promise<unknown> } {
+  const handler: ProxyHandler<T> = {
+    get(target, prop, receiver) {
+      if (prop in target) {
+        return Reflect.get(target, prop, receiver);
+      }
+      if (typeof prop === "symbol") {
+        return Reflect.get(target, prop, receiver);
+      }
+      if ("getAttribute" in target && typeof target.getAttribute === "function") {
+        return target.getAttribute(prop);
+      }
+      return Promise.resolve(undefined);
+    },
+  };
+
+  return new Proxy(instance, handler) as T & { [key: string]: Promise<unknown> };
+}
+
+/**
+ * Config object which only loads config items when, and crucially if, they are used.
+ * Loads config from environment if it exists there, from SSM otherwise.
+ * Caches items for CACHE_TTL_MILLIS milliseconds, so we don't get items more than once.
+ */
+class LazyConfig {
+  private _cache = new Map<string, ConfigValue>();
+  private ttl: number = Date.now() + LazyConfig.CACHE_TTL_MILLIS;
+  static readonly CACHE_TTL_MILLIS: number = 300 * 1000;
+
+  private static toUrl = (value: string): URL => new URL(value);
+  private static toBoolean = (value: string): boolean | undefined => {
+    const lower = value.toLowerCase();
+    if (lower === "true") return true;
+    if (lower === "false") return false;
+    return undefined;
+  };
+  static readonly converters: Record<string, (value: string) => ConfigValue> = {
+    APIM_AUTH_URL: LazyConfig.toUrl,
+    CONTENT_API_ENDPOINT: LazyConfig.toUrl,
+    ELIGIBILITY_API_ENDPOINT: LazyConfig.toUrl,
+    NBS_URL: LazyConfig.toUrl,
+    NHS_LOGIN_URL: LazyConfig.toUrl,
+    CONTENT_CACHE_IS_CHANGE_APPROVAL_ENABLED: LazyConfig.toBoolean,
+    IS_APIM_AUTH_ENABLED: LazyConfig.toBoolean,
+    MAX_SESSION_AGE_MINUTES: (value: string) => {
+      const num = Number(value);
+      if (!isNaN(num)) return num;
+      return undefined;
+    },
+  };
+
+  /**
+   * Make sure that the config items are returned as the correct types - booleans, numbers, strings, what have you.
+   */
+  private _coerceType(key: string, value: string | undefined): ConfigValue {
+    let result: ConfigValue;
+
+    if (value === undefined || value.trim() === "") {
+      result = undefined;
+    } else {
+      const converter = LazyConfig.converters[key];
+      if (!converter) {
+        result = value.trim();
+      } else {
+        try {
+          result = converter(value.trim());
+        } catch (error) {
+          log.warn({ context: { key, value }, error }, "Config item type coercion failed");
+          result = undefined;
+        }
+      }
+    }
+
+    if (result === undefined) {
+      log.error({ context: { key, value } }, "Unable to get config item");
+      throw new ConfigError(`Unable to get config item ${key}`);
+    }
+    return result;
+  }
+
+  public async getAttribute(key: string): Promise<ConfigValue> {
+    if (this.ttl < Date.now()) {
+      (this.resetCache(), (this.ttl = Date.now() + LazyConfig.CACHE_TTL_MILLIS));
+    }
+
+    if (this._cache.has(key)) {
+      log.debug({ context: { key } }, "cache hit");
+      return this._cache.get(key);
+    }
+
+    log.debug({ context: { key } }, "cache miss");
+    const value = await this.getFromEnvironmentOrSSM(key);
+
+    const coercedValue = this._coerceType(key, value);
+
+    this._cache.set(key, coercedValue);
+
+    return coercedValue;
+  }
+
+  private getFromEnvironmentOrSSM = async (key: string): Promise<string> => {
+    let value = process.env[key];
+
+    if (value === undefined || value === null) {
+      const ssmPrefix = await this.getAttribute("SSM_PREFIX");
+
+      if (typeof ssmPrefix !== "string" || ssmPrefix === "") {
+        log.error(
+          { context: { key, ssmPrefix } },
+          "SSM_PREFIX is not configured correctly. Expected a non-empty string.",
+        );
+        throw new Error(`SSM_PREFIX is not configured correctly. Expected a non-empty string, but got: ${ssmPrefix}`);
+      }
+
+      log.debug({ context: { key, ssmPrefix } }, "getting from SSM");
+      value = await retry(() => getSSMParam(`${ssmPrefix}${key}`), {
+        retries: 10,
+        delay: (attempt) => 100 * Math.pow(2, attempt - 1),
+      });
+    }
+
+    if (value === undefined || value === null) {
+      log.error({ context: { key } }, "Unable to get config item.");
+      throw new ConfigError(`Unable to get config item ${key}`);
+    }
+
+    return value;
+  }
+
+  private async getSsmPrefix(): Promise<string> {
+    const key = "SSM_PREFIX";
+
+    if (this._cache.has(key)) {
+      return this._cache.get(key) as string;
+    }
+
+    const prefix = process.env[key];
+    if (typeof prefix === "string" && prefix !== "") {
+      this._cache.set(key, prefix);
+      return prefix;
+    }
+
+    log.error({ context: { key } }, "SSM_PREFIX is not configured in the environment.");
+    throw new ConfigError("SSM_PREFIX is not configured correctly in the environment.");
+  }
+
+  public resetCache() {
+    log.info("reset cache");
+    this._cache.clear();
+    this.ttl = Date.now() + LazyConfig.CACHE_TTL_MILLIS;
+  }
+}
+
+export class ConfigError extends EligibilityApiError {
+  constructor(message: string) {
+    super(message);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "ConfigError";
+  }
+}
+
+const lazyConfigInstance = new LazyConfig();
+
+const lazyConfig = createReadOnlyDynamic(lazyConfigInstance);
+
+export default lazyConfig;
