headplane/app/server/config/load.ts

import { access, constants, readFile } from "node:fs/promises";

import { type } from "arktype";
import { load } from "js-yaml";

import log from "~/utils/log";

import {
  headplaneConfig,
  PartialHeadplaneConfig,
  partialHeadplaneConfig,
  pathSupportedKeys,
} from "./config-schema";
import { ConfigError } from "./error";

/**
 * Main entrypoint that attempts to load and merge configuration from both
 * a YAML config file (if available) and environment variables. Importantly,
 * the environment variables will override any values set in the config file.
 *
 * The function also supports loading secret values from file paths for
 * specific configuration keys (e.g., certificates, private keys) by checking
 * for corresponding `_path` suffixed environment variables or config file
 * entries.
 *
 * @param configPathOverride Used for testing to override the config file path
 * @returns @ref{HeadplaneConfig} The fully validated configuration
 * @throws {Error} If there are validation errors in the final configuration
 */
export async function loadConfig(configPathOverride?: string) {
  const configPath =
    configPathOverride != null
      ? configPathOverride
      : process.env.HEADPLANE_CONFIG_PATH != null
        ? String(process.env.HEADPLANE_CONFIG_PATH)
        : "/etc/headplane/config.yaml";

  const fileConfig = await loadConfigFile(configPath);
  const envConfig = await loadConfigEnv();

  const combinedConfig = deepMerge(fileConfig, envConfig);
  await loadConfigKeyPaths(combinedConfig);

  const finalConfig = headplaneConfig(combinedConfig);
  if (finalConfig instanceof type.errors) {
    throw ConfigError.from("INVALID_REQUIRED_FIELDS", {
      messages: finalConfig.map((e) => e.toString()),
    });
  }

  return finalConfig;
}

/**
 * Attempts to load configuration from a YAML file at the specified path.
 * If the file is not accessible, it returns undefined.
 *
 * @param path The file path to load the configuration from
 * @returns A partial configuration object or undefined
 * @throws {Error} If there are validation errors in the loaded configuration
 */
export async function loadConfigFile(path: string) {
  try {
    await access(path, constants.R_OK);
  } catch {
    log.info("config", "Could not access config file at path: %s", path);
    return;
  }

  const rawBuffer = await readFile(path, "utf8");
  const rawConfig = load(rawBuffer);
  const config = partialHeadplaneConfig(rawConfig);
  if (config instanceof type.errors) {
    throw ConfigError.from("INVALID_REQUIRED_FIELDS", {
      messages: config.map((e) => e.toString()),
    });
  }

  return config;
}

/**
 * Loads configuration overrides from environment variables prefixed with
 * `HEADPLANE_`. Nested configuration keys can be represented using double
 * underscores (`__`). For example, `HEADPLANE_SERVER__PORT=8080` would set
 * the `server.port` configuration key to `8080`.
 *
 * @returns A partial configuration object or undefined
 * @throws {Error} If there are validation errors in the loaded configuration
 */
export async function loadConfigEnv() {
  if (process.env.HEADPLANE_LOAD_ENV_OVERRIDES != null) {
    log.warn(
      "config",
      "HEADPLANE_LOAD_ENV_OVERRIDES is deprecated and will be removed in future versions",
    );
    log.warn(
      "config",
      "Environment variables are always loaded and `.env` files are no longer supported",
    );
  }

  const rawConfig: Record<string, unknown> = {};
  for (const [key, value] of Object.entries(process.env)) {
    if (value == null || !key.startsWith("HEADPLANE_")) {
      continue;
    }

    const parsedValue = parseEnvValue(value);
    const configKey = key.slice("HEADPLANE_".length).toLowerCase();
    deepSet(rawConfig, configKey.split("__"), parsedValue);
  }

  const config = partialHeadplaneConfig(rawConfig);
  if (config instanceof type.errors) {
    throw ConfigError.from("INVALID_REQUIRED_FIELDS", {
      messages: config.map((e) => e.toString()),
    });
  }

  return Object.keys(config).length > 0 ? config : undefined;
}

/**
 * Deeply merges multiple objects together. Later objects in the arguments
 * list will override properties of earlier objects.
 *
 * @param objects The objects to merge
 * @returns The merged object
 */
function deepMerge<T>(...objects: (T | undefined)[]): T {
  const result: { [key: string]: unknown } = {};
  for (const obj of objects.filter((o) => o != null)) {
    for (const [key, value] of Object.entries(
      obj as {
        [key: string]: unknown;
      },
    )) {
      if (value != null && typeof value === "object" && !Array.isArray(value)) {
        if (result[key] == null || typeof result[key] !== "object" || Array.isArray(result[key])) {
          result[key] = {};
        }
        result[key] = deepMerge(result[key], value);
      } else {
        result[key] = value;
      }
    }
  }

  return result as T;
}

/**
 * Sets a value deeply within an object based on the provided path.
 *
 * @param obj The object to set the value in
 * @param path An array of keys representing the path to set
 * @param value The value to set at the specified path
 */
function deepSet(obj: { [key: string]: unknown }, path: string[], value: unknown): void {
  let current = obj;
  for (let i = 0; i < path.length - 1; i++) {
    const key = path[i];
    if (current[key] == null || typeof current[key] !== "object") {
      current[key] = {};
    }

    current = current[key] as { [key: string]: unknown };
  }

  current[path[path.length - 1]] = value;
}

/**
 * Parses an environment variable string value into an appropriate type.
 * Supports booleans, null, undefined, and numbers. Falls back to string.
 *
 * @param value The environment variable string value
 * @returns The parsed value
 */
function parseEnvValue(value: string): unknown {
  const v = value.trim().toLowerCase();
  if (v === "true") return true;
  if (v === "false") return false;
  if (v === "null") return null;
  if (v === "undefined") return undefined;

  if (/^-?\d+(\.\d+)?$/.test(v)) {
    const num = Number(v);
    if (!Number.isNaN(num)) return num;
  }

  return value;
}

/**
 * For configuration keys that support loading from file paths (e.g.,
 * certificates, private keys), this function checks for corresponding
 * `_path` suffixed keys and loads the file content if the main key is
 * not already set.
 *
 * @param partial The partial configuration object to update
 */
export async function loadConfigKeyPaths(partial: PartialHeadplaneConfig) {
  for (const key of pathSupportedKeys) {
    const pathKey = `${key}_path`;
    const pathValue = deepGet(partial, pathKey.split("."));
    const existing = deepGet(partial, key.split("."));

    if (pathValue == null || typeof pathValue !== "string") {
      continue;
    }

    if (existing != null) {
      throw ConfigError.from("CONFLICTING_SECRET_PATH_FIELD", {
        fieldName: key,
      });
    }

    const realPath = pathValue.replace(/\$\{([^}]+)\}/g, (_, variableName) => {
      const value = process.env[variableName];
      if (value === undefined) {
        throw ConfigError.from("MISSING_INTERPOLATION_VARIABLE", {
          pathKey: `${key}_path`,
          variableName: variableName,
        });
      }

      return value;
    });

    try {
      const fileContent = await readFile(realPath, "utf8");
      deepSet(partial, key.split("."), fileContent.trim().normalize());
    } catch {
      throw ConfigError.from("MISSING_SECRET_FILE", {
        pathKey: `${key}_path`,
        filePath: realPath,
      });
    }
  }
}

/**
 * Deeply retrieves a value from an object based on the provided path.
 *
 * @param obj The object to retrieve the value from
 * @param path An array of keys representing the path to retrieve
 * @returns The value at the specified path or undefined if not found
 */
function deepGet(obj: { [key: string]: unknown }, path: string[]): unknown {
  let current = obj;
  for (const segment of path) {
    if (current == null || typeof current !== "object") {
      return undefined;
    }

    current = current[segment] as { [key: string]: unknown };
  }

  return current;
}