불변 Configuration Snapshot과 계층 우선순위

Defaults < Config File < Environment < Command Line

Configuration Snapshot
= Ordered Raw Layers
→ Canonical Key Merge
→ Field Parse and Validation
→ Optional Cross-Field Validation
→ Immutable AppConfig
Precedence
= Defaults < File < Environment < CLI
Runtime Rule
= 실행 코드는 raw 설정 공급원을 직접 읽지 않는다

apiBaseUrl
= 외부 API의 HTTPS base URL
maxConcurrency
= 동시에 실행할 요청 수, 1~64
requestTimeoutMs
= 개별 요청 timeout, 100~60,000ms
dryRun
= 외부 변경을 실제 반영하지 않을지 여부

기본값:
maxConcurrency=4
requestTimeoutMs=5000
dryRun=true
설정 파일:
apiBaseUrl=https://api.example.com
maxConcurrency=8
환경 변수:
maxConcurrency=12
명령행:
dryRun=true

apiBaseUrl=https://api.example.com
maxConcurrency=12
requestTimeoutMs=5000
dryRun=true

ConfigLayer:
- sourceName
- values: key → raw string
Known Keys:
- apiBaseUrl
- maxConcurrency
- requestTimeoutMs
- dryRun

using System;
using System.Collections.Generic;
using System.Globalization;
public sealed record AppConfig(
    Uri ApiBaseUrl,
    int MaxConcurrency,
    TimeSpan RequestTimeout,
    bool DryRun);
public sealed record ConfigLayer(
    string SourceName,
    IReadOnlyDictionary<string, string> Values);
public sealed record ConfigError(
    string Code,
    string Key,
    string SourceName,
    string Message);
public abstract record ConfigLoadResult
{
    public sealed record Loaded(AppConfig Config) : ConfigLoadResult;
    public sealed record Rejected(ConfigError Error) : ConfigLoadResult;
}
public static class AppConfigLoader
{
    private static readonly HashSet<string> KnownKeys =
    [
        "apiBaseUrl",
        "maxConcurrency",
        "requestTimeoutMs",
        "dryRun",
    ];
    public static ConfigLoadResult Load(
        IReadOnlyList<ConfigLayer> layers)
    {
        ArgumentNullException.ThrowIfNull(layers);
        Dictionary<string, RawConfigValue> merged =
            new(StringComparer.Ordinal);
        foreach (ConfigLayer layer in layers)
        {
            ConfigError? error = MergeLayer(merged, layer);
            if (error is not null)
            {
                return new ConfigLoadResult.Rejected(error);
            }
        }
        return ParseSnapshot(merged);
    }
    private static ConfigError? MergeLayer(
        IDictionary<string, RawConfigValue> merged,
        ConfigLayer layer)
    {
        foreach ((string key, string value) in layer.Values)
        {
            if (!KnownKeys.Contains(key))
            {
                return CreateError(
                    "unknown_key",
                    key,
                    layer.SourceName,
                    "지원하지 않는 설정 key입니다.");
            }
            merged[key] = new RawConfigValue(
                value,
                layer.SourceName);
        }
        return null;
    }
    private static ConfigLoadResult ParseSnapshot(
        IReadOnlyDictionary<string, RawConfigValue> values)
    {
        ConfigFieldReader reader = new(values);
        ConfigReadResult<Uri> url =
            reader.ReadHttpsUri("apiBaseUrl");
        ConfigReadResult<int> concurrency =
            reader.ReadInteger("maxConcurrency", 1, 64);
        ConfigReadResult<int> timeout =
            reader.ReadInteger("requestTimeoutMs", 100, 60_000);
        ConfigReadResult<bool> dryRun =
            reader.ReadBoolean("dryRun");
        ConfigError? error = FirstError(
            url.Error,
            concurrency.Error,
            timeout.Error,
            dryRun.Error);
        if (error is not null)
        {
            return new ConfigLoadResult.Rejected(error);
        }
        AppConfig config = new(
            url.Value!,
            concurrency.Value,
            TimeSpan.FromMilliseconds(timeout.Value),
            dryRun.Value);
        return new ConfigLoadResult.Loaded(config);
    }
    private static ConfigError? FirstError(
        params ConfigError?[] errors)
    {
        foreach (ConfigError? error in errors)
        {
            if (error is not null)
            {
                return error;
            }
        }
        return null;
    }
    private static ConfigError CreateError(
        string code,
        string key,
        string sourceName,
        string message)
    {
        return new ConfigError(
            code,
            key,
            sourceName,
            message);
    }
    private sealed record RawConfigValue(
        string Value,
        string SourceName);
    private readonly record struct ConfigReadResult<T>(
        T Value,
        ConfigError? Error);
    private sealed class ConfigFieldReader
    {
        private readonly IReadOnlyDictionary<string, RawConfigValue> values;
        public ConfigFieldReader(
            IReadOnlyDictionary<string, RawConfigValue> values)
        {
            this.values = values;
        }
        public ConfigReadResult<Uri> ReadHttpsUri(string key)
        {
            if (!this.values.TryGetValue(key, out RawConfigValue? raw))
            {
                return this.Missing<Uri>(key);
            }
            bool valid = Uri.TryCreate(
                raw.Value,
                UriKind.Absolute,
                out Uri? uri)
                && uri.Scheme == Uri.UriSchemeHttps
                && !string.IsNullOrWhiteSpace(uri.Host)
                && string.IsNullOrEmpty(uri.UserInfo)
                && string.IsNullOrEmpty(uri.Query)
                && string.IsNullOrEmpty(uri.Fragment);
            return valid
                ? new ConfigReadResult<Uri>(uri!, null)
                : this.Invalid<Uri>(
                    key,
                    raw,
                    "사용자 정보, query, fragment가 없는 HTTPS URL이 필요합니다.");
        }
        public ConfigReadResult<int> ReadInteger(
            string key,
            int minimum,
            int maximum)
        {
            if (!this.values.TryGetValue(key, out RawConfigValue? raw))
            {
                return this.Missing<int>(key);
            }
            if (!IsCanonicalDecimal(raw.Value))
            {
                return this.Invalid<int>(
                    key,
                    raw,
                    "선행 0 없는 ASCII 10진 정수가 필요합니다.");
            }
            bool valid = int.TryParse(
                    raw.Value,
                    NumberStyles.None,
                    CultureInfo.InvariantCulture,
                    out int value)
                && value >= minimum
                && value <= maximum;
            return valid
                ? new ConfigReadResult<int>(value, null)
                : this.Invalid<int>(
                    key,
                    raw,
                    $"{minimum} 이상 {maximum} 이하 정수가 필요합니다.");
        }
        public ConfigReadResult<bool> ReadBoolean(string key)
        {
            if (!this.values.TryGetValue(key, out RawConfigValue? raw))
            {
                return this.Missing<bool>(key);
            }
            if (raw.Value == "true")
            {
                return new ConfigReadResult<bool>(true, null);
            }
            if (raw.Value == "false")
            {
                return new ConfigReadResult<bool>(false, null);
            }
            return this.Invalid<bool>(
                key,
                raw,
                "true 또는 false가 필요합니다.");
        }
        private static bool IsCanonicalDecimal(string value)
        {
            if (value.Length == 0)
            {
                return false;
            }
            if (value == "0")
            {
                return true;
            }
            if (value[0] == '0')
            {
                return false;
            }
            foreach (char c in value)
            {
                if (c < '0' || c > '9')
                {
                    return false;
                }
            }
            return true;
        }
        private ConfigReadResult<T> Missing<T>(string key)
        {
            return new ConfigReadResult<T>(
                default!,
                CreateError(
                    "missing_key",
                    key,
                    "merged",
                    "필수 설정이 없습니다."));
        }
        private ConfigReadResult<T> Invalid<T>(
            string key,
            RawConfigValue raw,
            string message)
        {
            return new ConfigReadResult<T>(
                default!,
                CreateError(
                    "invalid_value",
                    key,
                    raw.SourceName,
                    message));
        }
    }
}

type ConfigKey =
  | "apiBaseUrl"
  | "maxConcurrency"
  | "requestTimeoutMs"
  | "dryRun";
type ConfigLayer = Readonly<{
  sourceName: string;
  values: Readonly<Record<string, string>>;
}>;
declare const httpsUrlBrand: unique symbol;
type HttpsUrl = string & Readonly<{
  [httpsUrlBrand]: true;
}>;
type AppConfig = Readonly<{
  apiBaseUrl: HttpsUrl;
  maxConcurrency: number;
  requestTimeoutMs: number;
  dryRun: boolean;
}>;
type ConfigError = Readonly<{
  code: "unknownKey" | "missingKey" | "invalidValue";
  key: string;
  sourceName: string;
  message: string;
}>;
type ConfigLoadResult =
  | Readonly<{
      kind: "loaded";
      config: AppConfig;
    }>
  | Readonly<{
      kind: "rejected";
      error: ConfigError;
    }>;
type RawConfigValue = Readonly<{
  value: string;
  sourceName: string;
}>;
const knownKeys: ReadonlySet<string> = new Set<ConfigKey>([
  "apiBaseUrl",
  "maxConcurrency",
  "requestTimeoutMs",
  "dryRun",
]);
export function loadAppConfig(
  layers: readonly ConfigLayer[],
): ConfigLoadResult
{
  const merged = new Map<string, RawConfigValue>();
  for (const layer of layers) {
    const error = mergeLayer(merged, layer);
    if (error !== undefined) {
      return {
        kind: "rejected",
        error,
      };
    }
  }
  return parseSnapshot(merged);
}
function mergeLayer(
  merged: Map<string, RawConfigValue>,
  layer: ConfigLayer,
): ConfigError | undefined
{
  for (const [key, value] of Object.entries(layer.values)) {
    if (!knownKeys.has(key)) {
      return {
        code: "unknownKey",
        key,
        sourceName: layer.sourceName,
        message: "지원하지 않는 설정 key입니다.",
      };
    }
    merged.set(key, {
      value,
      sourceName: layer.sourceName,
    });
  }
  return undefined;
}
function parseSnapshot(
  values: ReadonlyMap<string, RawConfigValue>,
): ConfigLoadResult
{
  const apiBaseUrl = readHttpsUrl(values, "apiBaseUrl");
  const maxConcurrency = readInteger(
    values,
    "maxConcurrency",
    1,
    64,
  );
  const requestTimeoutMs = readInteger(
    values,
    "requestTimeoutMs",
    100,
    60_000,
  );
  const dryRun = readBoolean(values, "dryRun");
  if (apiBaseUrl.kind === "error") {
    return {
      kind: "rejected",
      error: apiBaseUrl.error,
    };
  }
  if (maxConcurrency.kind === "error") {
    return {
      kind: "rejected",
      error: maxConcurrency.error,
    };
  }
  if (requestTimeoutMs.kind === "error") {
    return {
      kind: "rejected",
      error: requestTimeoutMs.error,
    };
  }
  if (dryRun.kind === "error") {
    return {
      kind: "rejected",
      error: dryRun.error,
    };
  }
  return {
    kind: "loaded",
    config: Object.freeze({
      apiBaseUrl: apiBaseUrl.value,
      maxConcurrency: maxConcurrency.value,
      requestTimeoutMs: requestTimeoutMs.value,
      dryRun: dryRun.value,
    }),
  };
}
type ReadResult<TValue> =
  | Readonly<{
      kind: "value";
      value: TValue;
    }>
  | Readonly<{
      kind: "error";
      error: ConfigError;
    }>;
function readHttpsUrl(
  values: ReadonlyMap<string, RawConfigValue>,
  key: ConfigKey,
): ReadResult<HttpsUrl>
{
  const raw = values.get(key);
  if (raw === undefined) {
    return missingKey(key);
  }
  try {
    const url = new URL(raw.value);
    if (url.protocol !== "https:"
      || url.hostname === ""
      || url.username !== ""
      || url.password !== ""
      || url.search !== ""
      || url.hash !== "") {
      return invalidValue(
        key,
        raw.sourceName,
        "사용자 정보, query, fragment가 없는 HTTPS URL이 필요합니다.",
      );
    }
    return {
      kind: "value",
      // URL 객체는 가변이므로 정규화된 문자열만 snapshot에 저장한다.
      value: url.href as HttpsUrl,
    };
  } catch {
    return invalidValue(
      key,
      raw.sourceName,
      "유효한 URL이 필요합니다.",
    );
  }
}
function readInteger(
  values: ReadonlyMap<string, RawConfigValue>,
  key: ConfigKey,
  minimum: number,
  maximum: number,
): ReadResult<number>
{
  const raw = values.get(key);
  if (raw === undefined) {
    return missingKey(key);
  }
  if (!/^(0|[1-9][0-9]*)$/.test(raw.value)) {
    return invalidValue(
      key,
      raw.sourceName,
      "선행 0 없는 ASCII 10진 정수가 필요합니다.",
    );
  }
  const value = Number(raw.value);
  if (!Number.isSafeInteger(value)
    || value < minimum
    || value > maximum) {
    return invalidValue(
      key,
      raw.sourceName,
      `${minimum} 이상 ${maximum} 이하 정수가 필요합니다.`,
    );
  }
  return {
    kind: "value",
    value,
  };
}
function readBoolean(
  values: ReadonlyMap<string, RawConfigValue>,
  key: ConfigKey,
): ReadResult<boolean>
{
  const raw = values.get(key);
  if (raw === undefined) {
    return missingKey(key);
  }
  if (raw.value === "true" || raw.value === "false") {
    return {
      kind: "value",
      value: raw.value === "true",
    };
  }
  return invalidValue(
    key,
    raw.sourceName,
    "true 또는 false가 필요합니다.",
  );
}
function missingKey(key: ConfigKey): ReadResult<never>
{
  return {
    kind: "error",
    error: {
      code: "missingKey",
      key,
      sourceName: "merged",
      message: "필수 설정이 없습니다.",
    },
  };
}
function invalidValue(
  key: ConfigKey,
  sourceName: string,
  message: string,
): ReadResult<never>
{
  return {
    kind: "error",
    error: {
      code: "invalidValue",
      key,
      sourceName,
      message,
    },
  };
}

from __future__ import annotations
import re
from dataclasses import dataclass
from types import MappingProxyType
from typing import Literal, Mapping, TypeAlias
from urllib.parse import urlsplit
ConfigKey: TypeAlias = Literal[
    "apiBaseUrl",
    "maxConcurrency",
    "requestTimeoutMs",
    "dryRun",
]
@dataclass(frozen=True)
class ConfigLayer:
    source_name: str
    values: Mapping[str, str]
@dataclass(frozen=True)
class AppConfig:
    api_base_url: str
    max_concurrency: int
    request_timeout_ms: int
    dry_run: bool
@dataclass(frozen=True)
class ConfigError:
    code: Literal[
        "unknown_key",
        "missing_key",
        "invalid_value",
    ]
    key: str
    source_name: str
    message: str
@dataclass(frozen=True)
class ConfigLoaded:
    config: AppConfig
ConfigLoadResult: TypeAlias = ConfigLoaded | ConfigError
@dataclass(frozen=True)
class RawConfigValue:
    value: str
    source_name: str
_KNOWN_KEYS = frozenset(
    {
        "apiBaseUrl",
        "maxConcurrency",
        "requestTimeoutMs",
        "dryRun",
    }
)
_DECIMAL_RE = re.compile(r"0|[1-9][0-9]*")
def load_app_config(
    layers: tuple[ConfigLayer, ...],
) -> ConfigLoadResult:
    merged: dict[str, RawConfigValue] = {}
    for layer in layers:
        error = _merge_layer(merged, layer)
        if error is not None:
            return error
    readonly_values = MappingProxyType(merged)
    return _parse_snapshot(readonly_values)
def _merge_layer(
    merged: dict[str, RawConfigValue],
    layer: ConfigLayer,
) -> ConfigError | None:
    for key, value in layer.values.items():
        if key not in _KNOWN_KEYS:
            return ConfigError(
                code="unknown_key",
                key=key,
                source_name=layer.source_name,
                message="지원하지 않는 설정 key입니다.",
            )
        merged[key] = RawConfigValue(
            value=value,
            source_name=layer.source_name,
        )
    return None
def _parse_snapshot(
    values: Mapping[str, RawConfigValue],
) -> ConfigLoadResult:
    api_base_url = _read_https_url(
        values,
        "apiBaseUrl",
    )
    max_concurrency = _read_integer(
        values,
        "maxConcurrency",
        1,
        64,
    )
    request_timeout_ms = _read_integer(
        values,
        "requestTimeoutMs",
        100,
        60_000,
    )
    dry_run = _read_boolean(
        values,
        "dryRun",
    )
    error = _first_error(
        api_base_url,
        max_concurrency,
        request_timeout_ms,
        dry_run,
    )
    if error is not None:
        return error
    return ConfigLoaded(
        config=AppConfig(
            api_base_url=api_base_url,
            max_concurrency=max_concurrency,
            request_timeout_ms=request_timeout_ms,
            dry_run=dry_run,
        )
    )
def _read_https_url(
    values: Mapping[str, RawConfigValue],
    key: ConfigKey,
) -> str | ConfigError:
    raw = values.get(key)
    if raw is None:
        return _missing_key(key)
    try:
        parsed = urlsplit(raw.value)
        # port 접근은 잘못된 포트 문법에서 ValueError를 낼 수 있다.
        _ = parsed.port
        valid = (
            parsed.scheme == "https"
            and parsed.hostname is not None
            and parsed.username is None
            and parsed.password is None
            and parsed.query == ""
            and parsed.fragment == ""
        )
        # 다른 언어 예제처럼 raw 문자열이 아니라 파서를 거친 값을 저장한다.
        # 단, stdlib의 URL 정규화는 WHATWG URL이나 url crate보다 가볍다.
        normalized = parsed.geturl()
    except ValueError:
        valid = False
        normalized = ""
    if not valid:
        return _invalid_value(
            key,
            raw.source_name,
            "사용자 정보, query, fragment가 없는 HTTPS URL이 필요합니다.",
        )
    return normalized
def _read_integer(
    values: Mapping[str, RawConfigValue],
    key: ConfigKey,
    minimum: int,
    maximum: int,
) -> int | ConfigError:
    raw = values.get(key)
    if raw is None:
        return _missing_key(key)
    if _DECIMAL_RE.fullmatch(raw.value) is None:
        return _invalid_value(
            key,
            raw.source_name,
            "선행 0 없는 ASCII 10진 정수가 필요합니다.",
        )
    value = int(raw.value)
    if value < minimum or value > maximum:
        return _invalid_value(
            key,
            raw.source_name,
            f"{minimum} 이상 {maximum} 이하 값이 필요합니다.",
        )
    return value
def _read_boolean(
    values: Mapping[str, RawConfigValue],
    key: ConfigKey,
) -> bool | ConfigError:
    raw = values.get(key)
    if raw is None:
        return _missing_key(key)
    if raw.value == "true":
        return True
    if raw.value == "false":
        return False
    return _invalid_value(
        key,
        raw.source_name,
        "true 또는 false가 필요합니다.",
    )
def _first_error(
    *values: object,
) -> ConfigError | None:
    for value in values:
        if isinstance(value, ConfigError):
            return value
    return None
def _missing_key(key: ConfigKey) -> ConfigError:
    return ConfigError(
        code="missing_key",
        key=key,
        source_name="merged",
        message="필수 설정이 없습니다.",
    )
def _invalid_value(
    key: ConfigKey,
    source_name: str,
    message: str,
) -> ConfigError:
    return ConfigError(
        code="invalid_value",
        key=key,
        source_name=source_name,
        message=message,
    )

use std::collections::{BTreeMap, BTreeSet};
use url::Url;
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ConfigLayer {
    source_name: String,
    values: BTreeMap<String, String>,
}
impl ConfigLayer {
    pub fn new(
        source_name: String,
        values: BTreeMap<String, String>,
    ) -> Self {
        Self {
            source_name,
            values,
        }
    }
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AppConfig {
    api_base_url: Url,
    max_concurrency: usize,
    request_timeout_ms: u64,
    dry_run: bool,
}
impl AppConfig {
    pub fn get_api_base_url(&self) -> &Url {
        &self.api_base_url
    }
    pub fn get_max_concurrency(&self) -> usize {
        self.max_concurrency
    }
    pub fn get_request_timeout_ms(&self) -> u64 {
        self.request_timeout_ms
    }
    pub fn get_dry_run(&self) -> bool {
        self.dry_run
    }
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ConfigErrorCode {
    UnknownKey,
    MissingKey,
    InvalidValue,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ConfigError {
    pub code: ConfigErrorCode,
    pub key: String,
    pub source_name: String,
    pub message: String,
}
#[derive(Debug, Clone, PartialEq, Eq)]
struct RawConfigValue {
    value: String,
    source_name: String,
}
pub fn load_app_config(
    layers: &[ConfigLayer],
) -> Result<AppConfig, ConfigError> {
    let known_keys = known_keys();
    let mut merged = BTreeMap::new();
    for layer in layers {
        merge_layer(
            &mut merged,
            layer,
            &known_keys,
        )?;
    }
    parse_snapshot(&merged)
}
fn merge_layer(
    merged: &mut BTreeMap<String, RawConfigValue>,
    layer: &ConfigLayer,
    known_keys: &BTreeSet<&'static str>,
) -> Result<(), ConfigError> {
    for (key, value) in &layer.values {
        if !known_keys.contains(key.as_str()) {
            return Err(ConfigError {
                code: ConfigErrorCode::UnknownKey,
                key: key.clone(),
                source_name: layer.source_name.clone(),
                message: "지원하지 않는 설정 key입니다.".to_owned(),
            });
        }
        merged.insert(
            key.clone(),
            RawConfigValue {
                value: value.clone(),
                source_name: layer.source_name.clone(),
            },
        );
    }
    Ok(())
}
fn parse_snapshot(
    values: &BTreeMap<String, RawConfigValue>,
) -> Result<AppConfig, ConfigError> {
    let api_base_url = read_https_url(
        values,
        "apiBaseUrl",
    )?;
    let max_concurrency = read_usize(
        values,
        "maxConcurrency",
        1,
        64,
    )?;
    let request_timeout_ms = read_u64(
        values,
        "requestTimeoutMs",
        100,
        60_000,
    )?;
    let dry_run = read_bool(
        values,
        "dryRun",
    )?;
    Ok(AppConfig {
        api_base_url,
        max_concurrency,
        request_timeout_ms,
        dry_run,
    })
}
fn read_https_url(
    values: &BTreeMap<String, RawConfigValue>,
    key: &str,
) -> Result<Url, ConfigError> {
    let raw = get_required(values, key)?;
    let parsed = Url::parse(&raw.value)
        .map_err(|_| invalid_value(
            key,
            raw,
            "유효한 URL이 필요합니다.",
        ))?;
    if parsed.scheme() != "https"
        || parsed.host_str().is_none()
        || !parsed.username().is_empty()
        || parsed.password().is_some()
        || parsed.query().is_some()
        || parsed.fragment().is_some()
    {
        return Err(invalid_value(
            key,
            raw,
            "사용자 정보, query, fragment가 없는 HTTPS URL이 필요합니다.",
        ));
    }
    Ok(parsed)
}
fn read_usize(
    values: &BTreeMap<String, RawConfigValue>,
    key: &str,
    minimum: usize,
    maximum: usize,
) -> Result<usize, ConfigError> {
    let raw = get_required(values, key)?;
    if !is_canonical_decimal(&raw.value) {
        return Err(invalid_value(
            key,
            raw,
            "선행 0 없는 ASCII 10진 정수가 필요합니다.",
        ));
    }
    let value = raw.value
        .parse::<usize>()
        .map_err(|_| invalid_value(
            key,
            raw,
            "정수가 필요합니다.",
        ))?;
    if !(minimum..=maximum).contains(&value) {
        return Err(invalid_value(
            key,
            raw,
            "허용 범위를 벗어났습니다.",
        ));
    }
    Ok(value)
}
fn read_u64(
    values: &BTreeMap<String, RawConfigValue>,
    key: &str,
    minimum: u64,
    maximum: u64,
) -> Result<u64, ConfigError> {
    let raw = get_required(values, key)?;
    if !is_canonical_decimal(&raw.value) {
        return Err(invalid_value(
            key,
            raw,
            "선행 0 없는 ASCII 10진 정수가 필요합니다.",
        ));
    }
    let value = raw.value
        .parse::<u64>()
        .map_err(|_| invalid_value(
            key,
            raw,
            "정수가 필요합니다.",
        ))?;
    if !(minimum..=maximum).contains(&value) {
        return Err(invalid_value(
            key,
            raw,
            "허용 범위를 벗어났습니다.",
        ));
    }
    Ok(value)
}
fn read_bool(
    values: &BTreeMap<String, RawConfigValue>,
    key: &str,
) -> Result<bool, ConfigError> {
    let raw = get_required(values, key)?;
    match raw.value.as_str() {
        "true" => Ok(true),
        "false" => Ok(false),
        _ => Err(invalid_value(
            key,
            raw,
            "true 또는 false가 필요합니다.",
        )),
    }
}
fn get_required<'a>(
    values: &'a BTreeMap<String, RawConfigValue>,
    key: &str,
) -> Result<&'a RawConfigValue, ConfigError> {
    values.get(key).ok_or_else(|| ConfigError {
        code: ConfigErrorCode::MissingKey,
        key: key.to_owned(),
        source_name: "merged".to_owned(),
        message: "필수 설정이 없습니다.".to_owned(),
    })
}
fn is_canonical_decimal(value: &str) -> bool {
    if value.is_empty() {
        return false;
    }
    if value == "0" {
        return true;
    }
    let bytes = value.as_bytes();
    if bytes[0] == b'0' {
        return false;
    }
    bytes.iter().all(|byte| byte.is_ascii_digit())
}
fn invalid_value(
    key: &str,
    raw: &RawConfigValue,
    message: &str,
) -> ConfigError {
    ConfigError {
        code: ConfigErrorCode::InvalidValue,
        key: key.to_owned(),
        source_name: raw.source_name.clone(),
        message: message.to_owned(),
    }
}
fn known_keys() -> BTreeSet<&'static str> {
    BTreeSet::from([
        "apiBaseUrl",
        "maxConcurrency",
        "requestTimeoutMs",
        "dryRun",
    ])
}

[dependencies]
url = "2"

type SyncService = Readonly<{
  runAsync: (
    config: AppConfig,
    signal?: AbortSignal,
  ) => Promise<void>;
}>;
export async function startApplicationAsync(
  service: SyncService,
  fileValues: Readonly<Record<string, string>>,
  commandLineValues: Readonly<Record<string, string>>,
  signal?: AbortSignal,
): Promise<number>
{
  const result = loadAppConfig([
    createDefaultLayer(),
    {
      sourceName: "configFile",
      values: fileValues,
    },
    createEnvironmentLayer(process.env),
    {
      sourceName: "commandLine",
      values: commandLineValues,
    },
  ]);
  if (result.kind === "rejected") {
    writeConfigError(result.error);
    return 2;
  }
  await service.runAsync(result.config, signal);
  return 0;
}
function createDefaultLayer(): ConfigLayer
{
  return {
    sourceName: "defaults",
    values: {
      maxConcurrency: "4",
      requestTimeoutMs: "5000",
      dryRun: "true",
    },
  };
}
function createEnvironmentLayer(
  environment: NodeJS.ProcessEnv,
): ConfigLayer
{
  const values: Record<string, string> = {};
  assignIfPresent(
    values,
    "apiBaseUrl",
    environment.SYNC_API_BASE_URL,
  );
  assignIfPresent(
    values,
    "maxConcurrency",
    environment.SYNC_MAX_CONCURRENCY,
  );
  assignIfPresent(
    values,
    "requestTimeoutMs",
    environment.SYNC_REQUEST_TIMEOUT_MS,
  );
  assignIfPresent(
    values,
    "dryRun",
    environment.SYNC_DRY_RUN,
  );
  return {
    sourceName: "environment",
    values,
  };
}
function assignIfPresent(
  target: Record<string, string>,
  key: ConfigKey,
  value: string | undefined,
): void
{
  if (value !== undefined) {
    target[key] = value;
  }
}
function writeConfigError(error: ConfigError): void
{
  console.error(JSON.stringify({
    eventName: "application.configuration.rejected",
    code: error.code,
    key: error.key,
    sourceName: error.sourceName,
    message: error.message,
  }));
}

File Adapter
= 파일 I/O와 파일 형식 파싱
Environment Adapter
= 환경 변수 이름을 canonical key로 변환
CLI Adapter
= 명령행 syntax를 canonical key로 변환
AppConfigLoader
= 우선순위 병합, unknown key 거절, 타입 변환
AppConfig
= 실행 코드가 사용하는 불변 설정
Startup Policy
= 설정 실패를 종료 코드와 운영 로그로 변환
SyncService
= 이미 검증된 설정을 사용해 실제 업무 I/O 수행

설정 공급원은 무엇인가
→ 각 공급원이 canonical key로 변환되는가
→ 계층 우선순위가 명시되어 있는가
→ 덮어쓰기는 raw 값 단계에서 수행되는가
→ 알 수 없는 key를 거절하는가
→ 모든 필드를 타입과 범위로 변환하는가
→ 필드 사이 규칙이 있다면 교차 불변식을 확인하는가
→ 완성된 설정이 불변 객체인가
→ 실행 코드가 raw 공급원을 다시 읽지 않는가
→ 설정 실패가 실제 I/O 시작 전에 발생하는가

적합:
- API base URL
- timeout
- connection pool 크기
- worker 수
- 기능의 시작 모드
- 경로와 format 선택
별도 설계가 필요한 값:
- 실시간 feature flag
- 동적 rate limit
- 운영 중 교체되는 인증서
- tenant별 정책
- 즉시 반영되어야 하는 kill switch

기본값에 적합:
- 보수적인 timeout
- 낮은 worker 수
- 외부 변경을 막는 dryRun=true
기본값을 피할 후보:
- 결제 대상 계정
- production API URL
- 암호화 key
- 데이터 삭제 허용 여부
- tenant 식별자

- 서비스 내부에서 환경 변수를 반복해서 읽음
- source마다 서로 다른 기본값과 파싱 규칙을 사용함
- 우선순위가 코드 순서에 암묵적으로만 존재함
- unknown key를 무시해 설정 오타가 숨겨짐
- "0", "-1", 지나치게 큰 timeout을 허용함
- 설정 파일 reload 중 필드 일부만 먼저 교체됨
- raw dictionary를 application core 전체에 주입함
- secret을 명령행과 startup log에 출력함
- 기본값이 위험한 production 동작을 자동 허용함
- 설정 실패 후 일부 background worker가 이미 시작됨

async function synchronizeBadAsync(): Promise<void>
{
  const apiBaseUrl =
    process.env.SYNC_API_BASE_URL
    ?? "https://production.example.com";
  const maxConcurrency = Number(
    process.env.SYNC_MAX_CONCURRENCY ?? "1000",
  );
  const dryRun =
    process.env.SYNC_DRY_RUN === "true";
  await runSynchronization({
    apiBaseUrl,
    maxConcurrency,
    dryRun,
  });
}
async function runSynchronization(
  config: {
    apiBaseUrl: string;
    maxConcurrency: number;
    dryRun: boolean;
  },
): Promise<void>
{
  const timeoutMs = Number(
    process.env.SYNC_REQUEST_TIMEOUT_MS ?? "0",
  );
  console.log("실행 설정", process.env);
  // 실제 동기화 작업
  void config;
  void timeoutMs;
}

- 설정을 두 함수에서 서로 다른 시점에 읽는다.
- 하나의 실행이 서로 다른 환경 변수 snapshot을 볼 수 있다.
- maxConcurrency=1000이라는 공격적인 기본값을 사용한다.
- Number 변환 결과가 NaN이어도 검증하지 않는다.
- timeoutMs=0의 의미가 즉시 timeout인지 무제한인지 불분명하다.
- production URL 누락을 기본값으로 조용히 숨긴다.
- process.env 전체를 출력해 secret이 유출될 수 있다.
- 실행 코드가 raw 설정 공급원에 직접 결합된다.
- 어느 source가 최종 값을 제공했는지 추적할 수 없다.

type ConfigSourceName =
  | "defaults"
  | "configFile"
  | "environment"
  | "commandLine";
type ConfigSnapshot = Readonly<{
  config: AppConfig;
  sourceByKey: Readonly<Record<ConfigKey, ConfigSourceName>>;
}>;
type MergeResult = Readonly<{
  values: ReadonlyMap<string, RawConfigValue>;
  sourceByKey: Readonly<Record<ConfigKey, ConfigSourceName>>;
}>;

function createConfigStartupSummary(
  snapshot: ConfigSnapshot,
): Readonly<Record<string, unknown>>
{
  return {
    eventName: "application.configuration.loaded",
    apiBaseUrlHost: new URL(snapshot.config.apiBaseUrl).host,
    maxConcurrency: snapshot.config.maxConcurrency,
    requestTimeoutMs: snapshot.config.requestTimeoutMs,
    dryRun: snapshot.config.dryRun,
    sourceByKey: snapshot.sourceByKey,
  };
}

import assert from "node:assert/strict";
import test from "node:test";
test("CLI가 환경 변수와 파일과 기본값을 덮어쓴다", () =>
{
  const result = loadAppConfig([
    {
      sourceName: "defaults",
      values: {
        apiBaseUrl: "https://default.example.com",
        maxConcurrency: "4",
        requestTimeoutMs: "5000",
        dryRun: "true",
      },
    },
    {
      sourceName: "configFile",
      values: {
        maxConcurrency: "8",
      },
    },
    {
      sourceName: "environment",
      values: {
        maxConcurrency: "12",
        dryRun: "false",
      },
    },
    {
      sourceName: "commandLine",
      values: {
        maxConcurrency: "16",
      },
    },
  ]);
  assert.equal(result.kind, "loaded");
  if (result.kind !== "loaded") {
    return;
  }
  assert.equal(result.config.maxConcurrency, 16);
  assert.equal(result.config.dryRun, false);
});
test("알 수 없는 key는 시작 단계에서 거절한다", () =>
{
  const result = loadAppConfig([
    {
      sourceName: "defaults",
      values: {
        apiBaseUrl: "https://api.example.com",
        maxConcurrency: "4",
        requestTimeoutMs: "5000",
        dryRun: "true",
        maxConcurreny: "32",
      },
    },
  ]);
  assert.deepEqual(result, {
    kind: "rejected",
    error: {
      code: "unknownKey",
      key: "maxConcurreny",
      sourceName: "defaults",
      message: "지원하지 않는 설정 key입니다.",
    },
  });
});
test("상위 계층의 유효한 값이 하위 계층 값을 대체한다", () =>
{
  const result = loadAppConfig([
    {
      sourceName: "defaults",
      values: {
        apiBaseUrl: "https://api.example.com",
        maxConcurrency: "not-a-number",
        requestTimeoutMs: "5000",
        dryRun: "true",
      },
    },
    {
      sourceName: "environment",
      values: {
        maxConcurrency: "8",
      },
    },
  ]);
  assert.equal(result.kind, "loaded");
  if (result.kind !== "loaded") {
    return;
  }
  assert.equal(result.config.maxConcurrency, 8);
});
test("최종 병합 결과가 범위를 벗어나면 거절한다", () =>
{
  const result = loadAppConfig([
    {
      sourceName: "defaults",
      values: {
        apiBaseUrl: "https://api.example.com",
        maxConcurrency: "4",
        requestTimeoutMs: "5000",
        dryRun: "true",
      },
    },
    {
      sourceName: "commandLine",
      values: {
        maxConcurrency: "1000",
      },
    },
  ]);
  assert.equal(result.kind, "rejected");
});
test("선행 0이 붙은 정수는 거절한다", () =>
{
  const result = loadAppConfig([
    {
      sourceName: "defaults",
      values: {
        apiBaseUrl: "https://api.example.com",
        maxConcurrency: "08",
        requestTimeoutMs: "5000",
        dryRun: "true",
      },
    },
  ]);
  assert.equal(result.kind, "rejected");
});

application.config.loaded.count
application.config.rejected.count
application.config.rejected.by_code
application.config.reload.succeeded.count
application.config.reload.rejected.count
application.config.snapshot.version

설정은 문자열 dictionary로 소비하지 않고,
시작 경계에서 의미와 단위가 확정된 불변 타입으로 변환한다.

설정은 필요한 순간마다 읽지 말고,
시작할 때 전부 합쳐 검증한 뒤 하나의 불변 값으로 들고 가라.