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.

9.9 KB
Raw Blame
"""
Centralized utility for logging settings and configuration.
Controls when and how settings are logged based on environment variables.

Environment variable LDR_LOG_SETTINGS controls the verbosity:
- "none" or "false": No settings logging at all (default)
- "summary" or "info": Only log count and summary of settings
- "debug" or "full": Log complete settings (with sensitive keys redacted)
- "debug_unsafe"/"unsafe"/"raw": REMOVED for security — maps to "none" with a deprecation warning
"""

import os
import re
from collections.abc import Mapping
from typing import Any, Dict, Optional
from loguru import logger


# Check environment variable once at module load
SETTINGS_LOG_LEVEL = os.getenv("LDR_LOG_SETTINGS", "none").lower()

# Map various values to standardized levels
if SETTINGS_LOG_LEVEL in ("false", "0", "no", "none", "off"):
    SETTINGS_LOG_LEVEL = "none"
elif SETTINGS_LOG_LEVEL in ("true", "1", "yes", "info", "summary"):
    SETTINGS_LOG_LEVEL = "summary"
elif SETTINGS_LOG_LEVEL in ("debug", "full", "all"):
    SETTINGS_LOG_LEVEL = "debug"
elif SETTINGS_LOG_LEVEL in ("debug_unsafe", "unsafe", "raw"):
    import warnings

    warnings.warn(
        f"LDR_LOG_SETTINGS={os.getenv('LDR_LOG_SETTINGS')!r} is deprecated and has been "
        "removed for security. Use 'debug' for full settings with sensitive keys redacted. "
        "Defaulting to 'none'.",
        DeprecationWarning,
        stacklevel=2,
    )
    # logger.warning() won't work here — loguru is disabled at module load time
    # (see __init__.py). Write directly to stderr so users actually see this.
    import sys

    print(
        f"WARNING: LDR_LOG_SETTINGS={os.getenv('LDR_LOG_SETTINGS')!r} is deprecated and "
        "has been removed for security. Use 'debug' for full settings with sensitive keys "
        "redacted. Defaulting to 'none'.",
        file=sys.stderr,
    )
    SETTINGS_LOG_LEVEL = "none"
else:
    # Invalid value, default to none
    SETTINGS_LOG_LEVEL = "none"


def log_settings(
    settings: Any,
    message: str = "Settings loaded",
    force_level: Optional[str] = None,
) -> None:
    """
    Centralized settings logging with conditional output based on LDR_LOG_SETTINGS env var.

    Args:
        settings: Settings object or dict to log
        message: Log message prefix
        force_level: Override the environment variable setting (for critical messages)

    Behavior based on LDR_LOG_SETTINGS:
        - "none": No output
        - "summary": Log count and basic info at INFO level
        - "debug": Log full settings at DEBUG level (sensitive keys redacted)
        - "debug_unsafe"/"unsafe"/"raw": REMOVED — maps to "none" with a deprecation warning
    """
    log_level = force_level or SETTINGS_LOG_LEVEL

    if log_level == "none":
        return

    if log_level == "summary":
        # Log only summary at INFO level
        summary = create_settings_summary(settings)
        logger.info(f"{message}: {summary}")

    elif log_level == "debug":
        # Log full settings at DEBUG level with redaction
        if isinstance(settings, dict):
            safe_settings = _redact_url_values(redact_sensitive_keys(settings))
            logger.debug(f"{message} (redacted): {safe_settings}")
        else:
            # Non-dict settings get the same redaction: coerce to a dict
            # (mapping, pydantic model_dump, or instance attrs) so
            # redact_sensitive_keys can mask secret-bearing keys. An
            # unredactable shape logs the type name ONLY — never a raw
            # repr, which would bypass the redaction this level promises
            # for both shapes (see the docstring above).
            def _unredactable_shape_message() -> str:
                return (
                    f"{message}: <{type(settings).__name__} not logged — "
                    f"unredactable shape>"
                )

            # The whole coercion (including Mapping iteration, model_dump(),
            # and vars()/__dict__ access) AND the redaction/formatting run
            # inside one try: any of these can raise on an adversarial or
            # malformed object (e.g. a Mapping with a raising __iter__, a
            # __dict__ property that raises, or a coerced dict with
            # non-string keys that break is_sensitive_setting_key()). On any
            # exception we fall back to the type name only — never a raw
            # repr or partially-redacted value.
            try:
                coerced = None
                if isinstance(settings, Mapping):
                    coerced = dict(settings)
                elif hasattr(settings, "model_dump"):
                    coerced = dict(settings.model_dump())
                elif hasattr(settings, "__dict__"):
                    coerced = dict(vars(settings))
                if coerced is not None:
                    safe_coerced = _redact_url_values(
                        redact_sensitive_keys(coerced)
                    )
                    logger.debug(f"{message} (redacted): {safe_coerced}")
                else:
                    logger.debug(_unredactable_shape_message())
            except Exception:
                logger.debug(_unredactable_shape_message())


_SENSITIVE_KEY_PATTERNS = (
    "api_key",
    "apikey",
    "password",
    "secret",
    "token",
    "credential",
    "auth",
    "private",
    # Ported from #5602. main added this to a function-local list in
    # redact_sensitive_keys(); this branch had already refactored that list
    # into this module-level tuple, so taking "ours" would have silently
    # dropped the fix. The apprise-style notification URL embeds credentials
    # (mailto://user:pass@host, discord://webhook_id/token), so it must be
    # redacted wherever settings are rendered.
    "service_url",
)


# ``user:password@host...`` without a scheme (matched after leading
# whitespace is stripped). The user part -- possibly empty, as in
# ``:TOKEN@host/v1`` -- has no whitespace, ``@``, ``:`` or ``/``. Two
# forms:
#   * a password with no whitespace or ``@`` up to the first ``@`` -- any
#     host may follow (``ollama_server``, an IDN, ``[fe80::1%eth0]``);
#   * a password that contains whitespace (a newline too) or ``@`` but does
#     not START with whitespace, followed by a host-like part (no
#     whitespace, ``@``, ``/``, ``?`` or ``#``) and then ``/``, ``?``,
#     ``#``, whitespace or the end.
# A password must not start with whitespace, so prose such as
# ``"Note: mail [email protected]"`` is not mistaken for userinfo. Known
# limits: a password that begins with whitespace is not recognised, and
# neither is a token-only ``TOKEN@host`` (no ``:``). The pattern is
# anchored and its backtracking is linear in the value's length.
_SCHEMELESS_USERINFO_RE = re.compile(
    r"^[^\s@:/]*:(?:[^\s@]*@|[^\s@][\s\S]*@[^\s@/?#]+(?:[/?#\s]|$))"
)


def _looks_like_url(value: str) -> bool:
    """Whether a setting value should go through the URL redactor: it
    contains ``://``, starts with scheme-less userinfo, or is a single
    whitespace-free token (surrounding whitespace ignored) with a query or
    fragment (a scheme-less ``localhost:1234/v1?api_key=...``)."""
    token = value.strip()
    if "://" in token or _SCHEMELESS_USERINFO_RE.match(token):
        return True
    return ("?" in token or "#" in token) and not any(
        c.isspace() for c in token
    )


def _redact_url_values(value: Any) -> Any:
    """Redact credentials embedded in URL-valued settings (e.g. an
    ``llm.openai_endpoint.url`` of ``https://host/v1?api_key=...``) for the
    debug settings log. Key-name redaction alone misses them because the
    setting's key (``*.url``) is not sensitive. See ``_looks_like_url``
    for which strings are treated as URLs."""
    if isinstance(value, dict):
        return {k: _redact_url_values(v) for k, v in value.items()}
    if isinstance(value, list):
        return [_redact_url_values(v) for v in value]
    if isinstance(value, str) and _looks_like_url(value):
        # Lazy import: the security package imports settings modules.
        from ..security.url_redaction import redact_url_credentials

        return redact_url_credentials(value)
    return value


def is_sensitive_setting_key(key: str) -> bool:
    """Return True if the setting key should be redacted in responses."""
    key_lower = key.lower()
    return any(p in key_lower for p in _SENSITIVE_KEY_PATTERNS)


def redact_sensitive_keys(settings: Dict[str, Any]) -> Dict[str, Any]:
    """
    Redact sensitive keys from settings dictionary.

    Args:
        settings: Settings dictionary

    Returns:
        Settings dictionary with sensitive values redacted
    """
    redacted = {}
    for key, value in settings.items():
        if is_sensitive_setting_key(key):
            # Redact the value
            if isinstance(value, dict) and "value" in value:
                redacted[key] = {**value, "value": "***REDACTED***"}
            elif isinstance(value, str):
                redacted[key] = "***REDACTED***"
            else:
                redacted[key] = "***REDACTED***"
        elif isinstance(value, dict):
            # Recursively redact nested dicts
            redacted[key] = redact_sensitive_keys(value)
        else:
            redacted[key] = value

    return redacted


def create_settings_summary(settings: Any) -> str:
    """
    Create a summary of settings for logging.

    Args:
        settings: Settings object or dict

    Returns:
        Summary string
    """
    if isinstance(settings, dict):
        # Count different types of settings
        search_engines = sum(1 for k in settings.keys() if "search.engine" in k)
        llm_settings = sum(1 for k in settings.keys() if "llm." in k)
        total = len(settings)

        return f"{total} total settings (search engines: {search_engines}, LLM: {llm_settings})"
    return f"Settings object of type {type(settings).__name__}"


def get_settings_log_level() -> str:
    """
    Get the current settings logging level.

    Returns:
        Current log level: "none", "summary", or "debug"
    """
    return SETTINGS_LOG_LEVEL