"""
Registry of all environment-only settings.

This module creates the global registry and registers all environment settings
defined in the env_definitions subfolder.
"""

from typing import Optional, Any

from .env_settings import SettingsRegistry
from .env_definitions import ALL_SETTINGS


def _create_registry() -> SettingsRegistry:
    """Create and initialize the global registry with all defined settings."""
    registry = SettingsRegistry()

    # Register all setting categories
    for category_name, settings_list in ALL_SETTINGS.items():
        registry.register_category(category_name, settings_list)

    return registry


# Global registry instance (singleton)
registry = _create_registry()


# Convenience functions for direct access
def get_env_setting(key: str, default: Optional[Any] = None) -> Any:
    """
    Get an environment setting value.

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

    Returns:
        Setting value or default
    """
    return registry.get(key, default)


def is_test_mode() -> bool:
    """Quick check for test mode."""
    return bool(registry.get("testing.test_mode", False))


def is_ci_environment() -> bool:
    """Quick check for CI environment."""
    # CI is now an external variable, read it dynamically
    import os

    return os.environ.get("CI", "false").lower() in ("true", "1", "yes")


def is_github_actions() -> bool:
    """Check if running in GitHub Actions."""
    # GITHUB_ACTIONS is now an external variable, read it dynamically
    import os

    return os.environ.get("GITHUB_ACTIONS", "false").lower() in (
        "true",
        "1",
        "yes",
    )


# Module-level flag so the deprecation warning fires at most once per process.
_legacy_disable_warned = False


def _reset_legacy_warning_flag_for_tests() -> None:
    """Test seam: reset the module-level deprecation-warning flag.

    Tests that exercise the legacy `DISABLE_RATE_LIMITING` form
    multiple times need to verify the warning fires once per process,
    not once per call. Reload-based tests should also call this.
    """
    global _legacy_disable_warned
    _legacy_disable_warned = False


def is_rate_limiting_enabled() -> bool:
    """
    Check if HTTP rate limiting (Flask-Limiter) should be enabled.

    Returns:
        True if rate limiting should be enabled, False otherwise

    Logic:
        - Canonical: ``LDR_DISABLE_RATE_LIMITING=true`` disables rate limiting
        - Legacy:    ``DISABLE_RATE_LIMITING=true`` (no LDR_ prefix) is still
          honored for backward compatibility, but emits a one-shot deprecation
          warning. Operators should migrate to the canonical name.
        - Otherwise, rate limiting is enabled (default).

    Name-collision warning:
        ``LDR_RATE_LIMITING_ENABLED`` (without DISABLE_) is a DIFFERENT
        env var that controls the *adaptive search-engine* rate limiter
        (see ``rate_limiting.enabled`` setting and
        ``web_search_engines/rate_limiting/tracker.py``). It does NOT affect
        the Flask HTTP rate limiter governed by this function. Operators
        routinely confuse the two — see issue #3905.

    Note:
        This function intentionally does NOT check the CI environment.
        Rate-limiting control should be explicit via the dedicated flag.
    """
    import os
    from loguru import logger

    # Canonical form takes absolute precedence when set to any value.
    # An explicit `LDR_DISABLE_RATE_LIMITING=false` should override a stale
    # legacy `DISABLE_RATE_LIMITING=true` from another tool's environment.
    canonical_raw = os.environ.get("LDR_DISABLE_RATE_LIMITING")
    if canonical_raw is not None and canonical_raw != "":
        if canonical_raw.lower() in ("true", "1", "yes"):
            logger.debug(
                "Rate limiting DISABLED due to LDR_DISABLE_RATE_LIMITING=true"
            )
            return False
        logger.debug(
            "Rate limiting ENABLED (LDR_DISABLE_RATE_LIMITING set non-truthy)"
        )
        return True

    legacy = os.environ.get("DISABLE_RATE_LIMITING", "").lower()
    if legacy in ("true", "1", "yes"):
        global _legacy_disable_warned
        if not _legacy_disable_warned:
            logger.warning(
                "DISABLE_RATE_LIMITING is deprecated; use "
                "LDR_DISABLE_RATE_LIMITING for consistency with the LDR_ "
                "env-var convention. The legacy name still works but will "
                "be removed in a future release."
            )
            _legacy_disable_warned = True
        logger.debug("Rate limiting DISABLED due to DISABLE_RATE_LIMITING=true")
        return False

    logger.debug("Rate limiting ENABLED (default)")
    return True


# Export the registry and convenience functions
__all__ = [
    "registry",
    "get_env_setting",
    "is_test_mode",
    "is_ci_environment",
    "is_github_actions",
    "is_rate_limiting_enabled",
    "_reset_legacy_warning_flag_for_tests",
]
