Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

19.0 KB
Raw Blame
"""
Environment-only settings that are loaded early and never stored in database.

These settings are:
1. Required before database initialization
2. Used for testing/CI configuration
3. System bootstrap configuration

They are accessed through SettingsManager but always read from environment variables.

Why some settings must be environment-only:
- Bootstrap settings (the plaintext-SQLite fallback policy) are needed to initialize the database itself
- Database configuration settings must be available before connecting to the database
- Testing flags need to be checked before any database operations occur
- CI/CD variables control build-time behavior before the application starts

These settings cannot be stored in the database because they are prerequisites for
accessing the database. This creates a bootstrapping requirement where certain
configuration must come from the environment to establish the system state needed
to access persisted settings.
"""

import os
import re
from pathlib import Path
from typing import Any, Dict, Optional, List, Set, TypeVar, Generic
from abc import ABC, abstractmethod
from loguru import logger

from .exceptions import (
    EnvironmentPathNotFoundError,
    EnvironmentValueRangeError,
    InvalidEnvironmentValueError,
    MissingEnvironmentVariableError,
    SettingsValueError,
)

T = TypeVar("T")


class EnvSetting(ABC, Generic[T]):
    """Base class for all environment settings."""

    def __init__(
        self,
        key: str,
        description: str,
        default: Optional[T] = None,
        required: bool = False,
        deprecated_env_var: Optional[str] = None,
    ):
        self.key = key
        # Auto-generate env_var from key
        # e.g., "testing.test_mode" -> "LDR_TESTING_TEST_MODE"
        self.env_var = "LDR_" + key.upper().replace(".", "_")
        self.description = description
        self.default = default
        self.required = required
        self.deprecated_env_var = deprecated_env_var

    def get_value(
        self, *, strict: bool = False, check_env: bool = True
    ) -> Optional[T]:
        """Get the value from environment with type conversion."""
        raw = self._get_raw_value() if check_env else None
        if raw is None:
            if self.required and self.default is None:
                raise MissingEnvironmentVariableError(self.env_var)
            return self.default
        if strict:
            return self._convert_value(raw, strict=True)
        return self._convert_value(raw)

    @abstractmethod
    def _convert_value(self, raw: str, *, strict: bool = False) -> T:
        """Convert raw string value to the appropriate type."""
        pass

    def _get_raw_value(self) -> Optional[str]:
        """Get raw string value from environment.

        Checks the canonical env var first. If not set and a deprecated
        alias is configured, falls back to the deprecated name with a
        warning guiding users to migrate.
        """
        value = os.environ.get(self.env_var)
        if value is not None:
            return value

        if self.deprecated_env_var:
            deprecated_value = os.environ.get(self.deprecated_env_var)
            if deprecated_value is not None:
                logger.warning(
                    f"Environment variable '{self.deprecated_env_var}' is deprecated "
                    f"and will be removed in a future release. "
                    f"Please use '{self.env_var}' instead."
                )
                return deprecated_value

        return None

    @property
    def is_set(self) -> bool:
        """Check if the environment variable is set."""
        return self.env_var in os.environ

    def __repr__(self) -> str:
        """String representation for debugging."""
        return f"{self.__class__.__name__}(key='{self.key}', env_var='{self.env_var}')"


class BooleanSetting(EnvSetting[bool]):
    """Boolean environment setting."""

    def __init__(
        self,
        key: str,
        description: str,
        default: bool = False,
        deprecated_env_var: Optional[str] = None,
    ):
        super().__init__(
            key, description, default, deprecated_env_var=deprecated_env_var
        )

    def _convert_value(self, raw: str, *, strict: bool = False) -> bool:
        """Convert string to boolean."""
        if strict:
            normalized = raw.strip().lower()
            if normalized in ("true", "1", "yes", "on", "enabled"):
                return True
            if normalized in ("false", "0", "no", "off", "disabled", ""):
                return False
            raise ValueError("Expected a boolean token")
        return raw.lower() in ("true", "1", "yes", "on", "enabled")


class StringSetting(EnvSetting[str]):
    """String environment setting."""

    def __init__(
        self,
        key: str,
        description: str,
        default: Optional[str] = None,
        required: bool = False,
        deprecated_env_var: Optional[str] = None,
    ):
        super().__init__(
            key,
            description,
            default,
            required,
            deprecated_env_var=deprecated_env_var,
        )

    def _convert_value(self, raw: str, *, strict: bool = False) -> str:
        """Return string value as-is."""
        return raw


#: Plain ASCII decimal integer, optionally negative. Deliberately NOT what
#: ``int()`` accepts: ``int`` also takes underscore separators (``"1_0"``
#: -> 10), a leading ``"+"``, surrounding whitespace, and any Unicode
#: decimal digit (``"٣"`` -> 3). For a setting that defines a trust
#: boundary those spellings are a review hazard -- ``"1_0"`` reads as one
#: hop and means ten -- so ``strict_digits`` settings reject them. The
#: optional ``-`` is matched (rather than rejected outright) so a negative
#: value still reaches the ``min_value`` check and gets the specific
#: "below minimum" range error instead of a generic parse error.
_STRICT_INTEGER_LITERAL = re.compile(r"-?[0-9]+")


class IntegerSetting(EnvSetting[int]):
    """Integer environment setting.

    ``raise_on_validation_error`` makes malformed and out-of-range values
    propagate instead of falling back through ``SettingsRegistry``.

    ``strict_digits`` restricts accepted spellings to a plain ASCII
    decimal literal (see ``_STRICT_INTEGER_LITERAL``).

    An empty value is treated as UNSET in every mode: ``LDR_X=""`` falls
    back to the default rather than failing, because orchestrators
    (Compose, k8s manifests, Unraid templates) routinely emit an empty
    string for an unconfigured variable -- the repo-wide contract pinned
    by ``tests/test_config_env_var_contracts.py::
    test_empty_env_var_is_treated_as_unset_not_as_false``.
    """

    def __init__(
        self,
        key: str,
        description: str,
        default: Optional[int] = None,
        min_value: Optional[int] = None,
        max_value: Optional[int] = None,
        deprecated_env_var: Optional[str] = None,
        raise_on_validation_error: bool = False,
        strict_digits: bool = False,
    ):
        super().__init__(
            key,
            description,
            default,
            deprecated_env_var=deprecated_env_var,
        )
        self.min_value = min_value
        self.max_value = max_value
        self.raise_on_validation_error = raise_on_validation_error
        self.strict_digits = strict_digits

    def _convert_value(
        self, raw: str, *, strict: bool = False
    ) -> Optional[int]:
        """Convert string to integer with validation."""
        candidate = raw.strip()
        if not candidate:
            logger.warning(
                f"Empty value for {self.env_var}, treating it as unset and using default: {self.default}"
            )
            return self.default

        value: Optional[int] = None
        parse_error: Optional[ValueError] = None
        if self.strict_digits and not _STRICT_INTEGER_LITERAL.fullmatch(
            candidate
        ):
            parse_error = ValueError(
                f"invalid literal for int() with base 10: {raw!r}"
            )
        else:
            try:
                value = int(candidate)
            except ValueError as exc:
                parse_error = exc

        if parse_error is not None:
            if strict:
                raise parse_error
            if self.raise_on_validation_error:
                raise InvalidEnvironmentValueError(
                    self.env_var, raw, expected_type="integer"
                ) from parse_error
            logger.warning(
                f"Invalid integer value '{raw}' for {self.env_var}, using default: {self.default}"
            )
            return self.default

        if self.min_value is not None and value < self.min_value:
            raise EnvironmentValueRangeError(
                self.env_var, value, min_val=self.min_value
            )
        if self.max_value is not None and value > self.max_value:
            raise EnvironmentValueRangeError(
                self.env_var, value, max_val=self.max_value
            )
        return value


class PathSetting(StringSetting):
    """Path environment setting with validation."""

    def __init__(
        self,
        key: str,
        description: str,
        default: Optional[str] = None,
        must_exist: bool = False,
        create_if_missing: bool = False,
    ):
        super().__init__(key, description, default)
        self.must_exist = must_exist
        self.create_if_missing = create_if_missing

    def get_value(
        self, *, strict: bool = False, check_env: bool = True
    ) -> Optional[str]:
        """Get path value with optional validation/creation."""
        path_str = super().get_value(strict=strict, check_env=check_env)
        if path_str is None or not check_env:
            return path_str
        if strict and not path_str.strip():
            raise ValueError("Expected a nonempty path")

        # Use pathlib for path operations
        path = Path(path_str).expanduser()
        # Expand environment variables manually since pathlib doesn't have expandvars
        # Note: os.path.expandvars is kept here as there's no pathlib equivalent
        # noqa: PLR0402 - Suppress pathlib check for this line
        path_str = os.path.expandvars(str(path))
        path = Path(path_str).resolve()

        if (
            strict
            and self.create_if_missing
            and path.exists()
            and not path.is_dir()
        ):
            raise ValueError("Expected a directory")
        if self.create_if_missing and not path.exists():
            # Lazy import: this module is loaded very early (bootstrap
            # env-only settings), before the database and app are
            # initialized, so importing security at module load time
            # risks an import cycle.
            from ..security.directory_creation import (
                DirectoryCreationSecurityError,
                create_directory,
            )

            try:
                create_directory(
                    path,
                    context=f"env-configured path setting '{self.key}'",
                )
            except DirectoryCreationSecurityError:
                if strict:
                    raise ValueError(
                        "Could not prepare configured path"
                    ) from None
                raise
            except OSError:
                if strict:
                    raise
                logger.warning("Failed to create directory")
        elif self.must_exist and not path.exists():
            # Only raise if explicitly required to exist
            raise EnvironmentPathNotFoundError(self.env_var, path)

        return str(path)


class SecretSetting(StringSetting):
    """Secret/sensitive environment setting."""

    def __init__(
        self,
        key: str,
        description: str,
        default: Optional[str] = None,
        required: bool = False,
    ):
        super().__init__(key, description, default, required)

    def __repr__(self) -> str:
        """Hide the value in string representation."""
        return f"SecretSetting(key='{self.key}', value=***)"

    def __str__(self) -> str:
        """Hide the value in string conversion."""
        value = "SET" if self.is_set else "NOT SET"
        return f"{self.key}=<{value}>"


class EnumSetting(EnvSetting[str]):
    """Enum-style setting with allowed values."""

    def __init__(
        self,
        key: str,
        description: str,
        allowed_values: Set[str],
        default: Optional[str] = None,
        case_sensitive: bool = False,
        deprecated_env_var: Optional[str] = None,
    ):
        super().__init__(
            key, description, default, deprecated_env_var=deprecated_env_var
        )
        self.allowed_values = allowed_values
        self.case_sensitive = case_sensitive

        # Store lowercase versions for case-insensitive comparison
        if not case_sensitive:
            self._allowed_lower = {v.lower() for v in allowed_values}
            # Create a mapping from lowercase to original case
            self._canonical_map = {v.lower(): v for v in allowed_values}

    def _convert_value(self, raw: str, *, strict: bool = False) -> str:
        """Convert and validate value against allowed values."""
        if self.case_sensitive:
            if raw not in self.allowed_values:
                raise InvalidEnvironmentValueError(
                    self.env_var, raw, list(self.allowed_values)
                )
            return raw
        # Case-insensitive matching
        raw_lower = raw.lower()
        if raw_lower not in self._allowed_lower:
            raise InvalidEnvironmentValueError(
                self.env_var, raw, list(self.allowed_values)
            )
        # Return the canonical version (from allowed_values)
        return self._canonical_map[raw_lower]


class SettingsRegistry:
    """Registry for all environment settings."""

    def __init__(self):
        self._settings: Dict[str, EnvSetting] = {}
        self._categories: Dict[str, List[EnvSetting]] = {}

    def register_category(self, category: str, settings: List[EnvSetting]):
        """Register a category of settings."""
        self._categories[category] = settings
        for setting in settings:
            self._settings[setting.key] = setting

    def get(self, key: str, default: Optional[Any] = None) -> Any:
        """
        Get a setting value.

        Args:
            key: Setting key (e.g., "testing.test_mode")
            default: Default value if not set or on error

        Returns:
            Setting value or default
        """
        setting = self._settings.get(key)
        if not setting:
            return default

        try:
            value = setting.get_value()
            # Use provided default if setting returns None
            return value if value is not None else default
        except ValueError:
            if (
                isinstance(setting, IntegerSetting)
                and setting.raise_on_validation_error
            ):
                raise
            logger.warning(
                "Validation error for setting '{}', using default", key
            )
            return default

    def get_strict(
        self,
        key: str,
        default: Optional[Any] = None,
        *,
        check_env: bool = True,
    ) -> Any:
        """Read for a settings manager without hiding invalid configuration.

        Missing optional settings retain their registered or caller default.
        Disabling environment lookup also disables path resolution/creation.
        The legacy bootstrap ``get`` API retains its historical behavior.
        """
        setting = self._settings.get(key)
        if setting is None:
            return default

        source = "default"
        if check_env and (
            setting.env_var in os.environ
            or (
                setting.deprecated_env_var is not None
                and setting.deprecated_env_var in os.environ
            )
        ):
            source = "environment"

        # A custom converter has no strict-read contract. Do not call it and
        # accidentally accept a fallback or suppress its validation failure.
        reasons = {
            BooleanSetting: "expected a boolean token",
            IntegerSetting: "expected an integer within the allowed range",
            EnumSetting: "expected one of the declared choices",
            PathSetting: "could not resolve or prepare the configured path",
            StringSetting: "required value is missing",
            SecretSetting: "required value is missing",
        }
        reason = reasons.get(type(setting))
        if reason is None:
            raise SettingsValueError(
                key,
                source=source,
                reason="unsupported environment setting type",
            )

        try:
            value = setting.get_value(strict=True, check_env=check_env)
        except (ValueError, TypeError, OSError, RuntimeError):
            # Converters and filesystem errors can contain configured secrets
            # or paths. Raise outside the handler so no raw exception is kept
            # as the exception context or emitted in the traceback.
            pass
        else:
            return value if value is not None else default
        raise SettingsValueError(key, source=source, reason=reason)

    def get_setting_object(self, key: str) -> Optional[EnvSetting]:
        """Get the setting object itself for introspection."""
        return self._settings.get(key)

    def is_env_only(self, key: str) -> bool:
        """Check if a key is an env-only setting."""
        return key in self._settings

    def get_env_var(self, key: str) -> Optional[str]:
        """Get the environment variable name for a key."""
        setting = self._settings.get(key)
        return setting.env_var if setting else None

    def get_all_env_vars(self) -> Dict[str, str]:
        """Get all environment variables and descriptions."""
        return {
            setting.env_var: setting.description
            for setting in self._settings.values()
        }

    def get_category_settings(self, category: str) -> List[EnvSetting]:
        """Get all settings in a category."""
        return self._categories.get(category, [])

    def get_bootstrap_vars(self) -> Dict[str, str]:
        """Get bootstrap environment variables (bootstrap + db_config)."""
        result = {}
        for category in ["bootstrap", "db_config"]:
            for setting in self._categories.get(category, []):
                result[setting.env_var] = setting.description
        return result

    def get_testing_vars(self) -> Dict[str, str]:
        """Get testing environment variables."""
        result = {}
        for setting in self._categories.get("testing", []):
            result[setting.env_var] = setting.description
        return result

    def list_all_settings(self) -> List[str]:
        """List all registered setting keys."""
        return list(self._settings.keys())


# Export list for better IDE discovery
__all__ = [
    "EnvSetting",
    "BooleanSetting",
    "StringSetting",
    "IntegerSetting",
    "PathSetting",
    "SecretSetting",
    "EnumSetting",
    "SettingsRegistry",
]