Update app.py

app.py

@@ -0,0 +1,352 @@
+#!/usr/bin/env python3
+"""Application entry point for Telegram AI SaaS.
+
+Performs the following startup sequence:
+1. Load Settings from environment variables (lazy)
+2. Initialize structured logging
+3. Validate required configuration
+4. Create LLMManager
+5. Register OpenAI provider (if API key available)
+6. Start HTTP health check server (with /health and /ready)
+7. Log successful start
+
+Shutdown signals (SIGTERM, SIGINT) are handled gracefully.
+Windows-compatible signal handling is supported.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import signal
+import sys
+from contextlib import AsyncExitStack
+from typing import NoReturn
+
+from aiohttp import web
+
+from core.config.settings import get_settings
+from core.logging.logger import get_logger, setup_logging
+from core.security.validators import validate_admin_id, validate_bot_token
+from llm.manager import (
+    AllProvidersFailedError,
+    FallbackPolicy,
+    LLMManager,
+    LLMManagerError,
+    ProviderNotFoundError,
+)
+from llm.providers.base_provider import LLMProviderError
+from llm.providers.openai_provider import OpenAIProvider
+
+
+# ---------------------------------------------------------------------------
+# Application-level exception
+# ---------------------------------------------------------------------------
+
+class ConfigurationError(Exception):
+    """Raised when required configuration is missing or invalid."""
+
+
+# ---------------------------------------------------------------------------
+# Health states
+# ---------------------------------------------------------------------------
+
+class AppHealth:
+    """Tracks application readiness state for health endpoints.
+
+    Separates infrastructure liveness (process alive) from business
+    capability readiness (providers registered, config valid).
+    """
+
+    def __init__(self) -> None:
+        self._config_valid: bool = False
+        self._llm_managers_ready: bool = False
+
+    def mark_config_valid(self) -> None:
+        self._config_valid = True
+
+    def mark_llm_ready(self) -> None:
+        self._llm_managers_ready = True
+
+    @property
+    def is_healthy(self) -> bool:
+        """Liveness: process is alive and basic infrastructure works."""
+        return True
+
+    @property
+    def is_ready(self) -> bool:
+        """Readiness: can serve LLM requests."""
+        return self._config_valid and self._llm_managers_ready
+
+    @property
+    def status_detail(self) -> dict[str, str]:
+        """Return a dict with readiness details."""
+        details: dict[str, str] = {}
+        if not self._config_valid:
+            details["config"] = "invalid"
+        if not self._llm_managers_ready:
+            details["llm_providers"] = "none_registered"
+        return details
+
+
+# Global health state — set during startup
+_app_health: AppHealth = AppHealth()
+_llm_manager: LLMManager | None = None
+
+
+# ---------------------------------------------------------------------------
+# Configuration validation
+# ---------------------------------------------------------------------------
+
+def validate_configuration() -> None:
+    """Validate all required configuration fields.
+
+    Checks that required environment variables are present and
+    that their values pass format validation.
+
+    Raises:
+        ConfigurationError: If any required variable is missing or invalid.
+    """
+    log = get_logger("config_validator")
+    settings = get_settings()
+
+    required = settings.required_fields
+    missing = [name for name, value in required.items() if not value]
+
+    if missing:
+        log.error(
+            "missing_required_environment_variables",
+            missing=missing,
+        )
+        raise ConfigurationError(
+            f"Missing required environment variables: {missing}"
+        )
+
+    try:
+        validate_bot_token(settings.BOT_TOKEN)
+    except ValueError as exc:
+        log.error("configuration_validation_failed", field="BOT_TOKEN", error=str(exc))
+        raise ConfigurationError(str(exc)) from exc
+
+    try:
+        validate_admin_id(settings.ADMIN_ID)
+    except ValueError as exc:
+        log.error("configuration_validation_failed", field="ADMIN_ID", error=str(exc))
+        raise ConfigurationError(str(exc)) from exc
+
+
+# ---------------------------------------------------------------------------
+# HTTP handlers
+# ---------------------------------------------------------------------------
+
+async def _health_handler(request: web.Request) -> web.Response:
+    """Liveness probe — process is alive and responsive.
+
+    Always returns 200 while the process is running.
+    """
+    return web.json_response({"status": "ok"})
+
+
+async def _ready_handler(request: web.Request) -> web.Response:
+    """Readiness probe — can serve LLM requests.
+
+    Returns 200 if providers are registered and config is valid.
+    Returns 503 with details if not ready.
+    """
+    if _app_health.is_ready:
+        return web.json_response({"status": "ok"})
+
+    details = _app_health.status_detail
+    return web.json_response(
+        {"status": "degraded", "reasons": details},
+        status=503,
+    )
+
+
+# ---------------------------------------------------------------------------
+# HTTP server
+# ---------------------------------------------------------------------------
+
+async def _start_health_server(port: int) -> web.AppRunner:
+    """Start a minimal HTTP server for health checks.
+
+    Registers /health (liveness) and /ready (readiness) endpoints.
+
+    Args:
+        port: Port number to listen on.
+
+    Returns:
+        The aiohttp AppRunner (caller is responsible for cleanup).
+    """
+    app = web.Application()
+    app.router.add_get("/health", _health_handler)
+    app.router.add_get("/ready", _ready_handler)
+    runner = web.AppRunner(app)
+    await runner.setup()
+    site = web.TCPSite(runner, "0.0.0.0", port)
+    await site.start()
+    return runner
+
+
+# ---------------------------------------------------------------------------
+# Async main
+# ---------------------------------------------------------------------------
+
+async def _async_main() -> None:
+    """Async application entry point with graceful shutdown support."""
+    log = get_logger("app")
+
+    # 1. Setup logging (idempotent, thread-safe)
+    settings = get_settings()
+    setup_logging(log_level=settings.LOG_LEVEL, log_format=settings.LOG_FORMAT)
+
+    log.info(
+        "settings_loaded",
+        default_provider=settings.DEFAULT_PROVIDER,
+        port=settings.PORT,
+        log_level=settings.LOG_LEVEL,
+        log_format=settings.LOG_FORMAT,
+    )
+
+    log.info(
+        "logging_initialized",
+        level=settings.LOG_LEVEL,
+        format=settings.LOG_FORMAT,
+    )
+
+    # 2. Validate configuration
+    validate_configuration()
+    log.info("configuration_validated")
+    _app_health.mark_config_valid()
+
+    # 3. Create LLMManager with fallback policy
+    fallback_policy = FallbackPolicy(
+        providers=["openai", "claude", "gemini", "glm", "qwen"],
+        max_retries_per_provider=2,
+        base_delay_seconds=1.0,
+        max_delay_seconds=30.0,
+    )
+
+    global _llm_manager
+    _llm_manager = LLMManager(
+        default_provider=settings.DEFAULT_PROVIDER,
+        fallback_policy=fallback_policy,
+    )
+
+    log.info(
+        "llm_manager_initialized",
+        default_provider=_llm_manager.default_provider,
+        registered_providers=_llm_manager.list_providers(),
+    )
+
+    # 4. Register OpenAI provider if API key is available
+    if settings.OPENAI_API_KEY:
+        try:
+            openai_provider = OpenAIProvider(
+                api_key=settings.OPENAI_API_KEY,
+            )
+            await _llm_manager.register_provider("openai", openai_provider)
+            _app_health.mark_llm_ready()
+            log.info("openai_provider_registered")
+        except Exception as exc:
+            log.warning(
+                "openai_provider_registration_failed",
+                error=str(exc),
+            )
+    else:
+        log.warning(
+            "no_openai_api_key",
+            message="OPENAI_API_KEY not set — no LLM provider available",
+        )
+
+    if not _llm_manager.has_providers():
+        log.warning(
+            "no_providers_registered",
+            message="LLMManager has no providers. "
+            "Register providers before making LLM requests. "
+            "The /ready endpoint will return 503.",
+        )
+
+    # 5. Start health server
+    runner = await _start_health_server(settings.PORT)
+    log.info("health_server_started", port=settings.PORT)
+
+    log.info(
+        "application_started",
+        port=settings.PORT,
+        default_provider=settings.DEFAULT_PROVIDER,
+        telegram_api_server=settings.TELEGRAM_API_SERVER,
+        providers_count=len(_llm_manager.list_providers()),
+    )
+
+    # 6. Wait for shutdown signal (cross-platform)
+    shutdown_event = asyncio.Event()
+
+    def _set_shutdown() -> None:
+        log.info("shutdown_signal_received")
+        shutdown_event.set()
+
+    loop = asyncio.get_running_loop()
+
+    try:
+        for sig in (signal.SIGTERM, signal.SIGINT):
+            loop.add_signal_handler(sig, _set_shutdown)
+    except NotImplementedError:
+        # Windows fallback — signal.signal works with SIGINT on Windows
+        signal.signal(signal.SIGINT, lambda *_: _set_shutdown())
+        try:
+            signal.signal(signal.SIGTERM, lambda *_: _set_shutdown())
+        except (OSError, ValueError):
+            # SIGTERM may not be signal-able on Windows
+            pass
+
+    # 7. Graceful shutdown
+    try:
+        await shutdown_event.wait()
+    finally:
+        log.info("application_shutting_down")
+        await runner.cleanup()
+        logging.shutdown()
+        log.info("application_stopped")
+
+
+# ---------------------------------------------------------------------------
+# Synchronous entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    """Application entry point — uses asyncio.run() for proper lifecycle."""
+    try:
+        asyncio.run(_async_main())
+    except ConfigurationError as exc:
+        try:
+            # Logging may not be configured yet — try structlog, fallback to print
+            get_logger("app").error(
+                "configuration_error",
+                error=str(exc),
+            )
+        except Exception:
+            print(f"FATAL: Configuration error: {exc}", file=sys.stderr)
+        logging.shutdown()
+        sys.exit(1)
+
+    except KeyboardInterrupt:
+        # asyncio.run() handles cleanup — just exit cleanly
+        pass
+
+    except Exception as exc:
+        try:
+            get_logger("app").error(
+                "unexpected_startup_error",
+                error=str(exc),
+                exc_info=True,
+            )
+        except Exception:
+            print(f"FATAL: Unexpected error: {exc}", file=sys.stderr)
+        logging.shutdown()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
+