Aether/src/api/handlers/base/chat_handler_base.py

"""
Chat Handler Base - Chat API 格式的通用基类

提供 Chat API 格式（Claude Chat、OpenAI Chat）的通用处理逻辑。
与 CliMessageHandlerBase 的区别：
- CLI 模式：透传请求体，直接转发
- Chat 模式：可能需要格式转换（如 OpenAI -> Claude）

两者共享相同的接口：
- process_stream(): 流式请求
- process_sync(): 非流式请求
- apply_mapped_model(): 模型映射
- get_model_for_url(): URL 模型名
- _extract_usage(): 使用量提取

重构说明：
- StreamContext: 类型安全的流式上下文，替代原有的 ctx dict
- StreamProcessor: 流式响应处理（SSE 解析、预读、错误检测）
- StreamTelemetryRecorder: 统计记录（Usage、Audit、Candidate）
"""

from abc import ABC, abstractmethod
from typing import Any, AsyncGenerator, Callable, Dict, Optional

import httpx
from fastapi import BackgroundTasks, Request
from fastapi.responses import JSONResponse, StreamingResponse
from sqlalchemy.orm import Session

from src.api.handlers.base.base_handler import BaseMessageHandler
from src.api.handlers.base.parsers import get_parser_for_format
from src.api.handlers.base.request_builder import PassthroughRequestBuilder
from src.api.handlers.base.response_parser import ResponseParser
from src.api.handlers.base.stream_context import StreamContext
from src.api.handlers.base.stream_processor import StreamProcessor
from src.api.handlers.base.stream_telemetry import StreamTelemetryRecorder
from src.api.handlers.base.utils import build_sse_headers
from src.config.settings import config
from src.core.exceptions import (
    EmbeddedErrorException,
    ProviderAuthException,
    ProviderNotAvailableException,
    ProviderRateLimitException,
    ProviderTimeoutException,
)
from src.core.logger import logger
from src.models.database import (
    ApiKey,
    Provider,
    ProviderAPIKey,
    ProviderEndpoint,
    User,
)
from src.services.provider.transport import build_provider_url



class ChatHandlerBase(BaseMessageHandler, ABC):
    """
    Chat Handler 基类

    主要职责：
    - 通过 FallbackOrchestrator 选择 Provider/Endpoint/Key
    - 发送请求并处理响应
    - 记录日志、审计、统计
    - 错误处理

    子类需要实现：
    - FORMAT_ID: API 格式标识
    - _convert_request(): 请求格式转换
    - _extract_usage(): 从响应中提取 token 使用情况
    - _normalize_response(): 响应规范化（可选）

    与 CliMessageHandlerBase 共享的接口：
    - apply_mapped_model(): 模型映射到请求体
    - get_model_for_url(): 获取 URL 中的模型名
    """

    FORMAT_ID: str = ""  # 子类覆盖

    def __init__(
        self,
        db: Session,
        user: User,
        api_key: ApiKey,
        request_id: str,
        client_ip: str,
        user_agent: str,
        start_time: float,
        allowed_api_formats: Optional[list] = None,
        adapter_detector: Optional[Callable[[Dict[str, str], Optional[Dict[str, Any]]], Dict[str, bool]]] = None,
    ):
        allowed = allowed_api_formats or [self.FORMAT_ID]
        super().__init__(
            db=db,
            user=user,
            api_key=api_key,
            request_id=request_id,
            client_ip=client_ip,
            user_agent=user_agent,
            start_time=start_time,
            allowed_api_formats=allowed,
            adapter_detector=adapter_detector,
        )
        self._parser: Optional[ResponseParser] = None
        self._request_builder = PassthroughRequestBuilder()

    @property
    def parser(self) -> ResponseParser:
        """获取响应解析器（懒加载）"""
        if self._parser is None:
            self._parser = get_parser_for_format(self.FORMAT_ID)
        return self._parser

    # ==================== 抽象方法 ====================

    @abstractmethod
    async def _convert_request(self, request: Any) -> Any:
        """
        将请求转换为目标格式

        Args:
            request: 原始请求对象

        Returns:
            转换后的请求对象
        """
        pass

    @abstractmethod
    def _extract_usage(self, response: Dict) -> Dict[str, int]:
        """
        从响应中提取 token 使用情况

        Args:
            response: 响应数据

        Returns:
            Dict with keys: input_tokens, output_tokens,
                           cache_creation_input_tokens, cache_read_input_tokens
        """
        pass

    def _normalize_response(self, response: Dict) -> Dict:
        """
        规范化响应（可选覆盖）

        Args:
            response: 原始响应

        Returns:
            规范化后的响应
        """
        return response

    # ==================== 统一接口方法 ====================

    def extract_model_from_request(
        self,
        request_body: Dict[str, Any],
        path_params: Optional[Dict[str, Any]] = None,  # noqa: ARG002 - 子类使用
    ) -> str:
        """
        从请求中提取模型名 - 子类可覆盖

        不同 API 格式的 model 位置不同：
        - OpenAI/Claude: 在请求体中 request_body["model"]
        - Gemini: 在 URL 路径中 path_params["model"]

        子类应覆盖此方法实现各自的提取逻辑。

        Args:
            request_body: 请求体
            path_params: URL 路径参数

        Returns:
            模型名，如果无法提取则返回 "unknown"
        """
        # 默认实现：从请求体获取
        model = request_body.get("model")
        return str(model) if model else "unknown"

    def apply_mapped_model(
        self,
        request_body: Dict[str, Any],
        mapped_model: str,  # noqa: ARG002 - 子类使用
    ) -> Dict[str, Any]:
        """
        将映射后的模型名应用到请求体

        基类默认实现：不修改请求体，保持原样透传。
        子类应覆盖此方法实现各自的模型名替换逻辑。

        Args:
            request_body: 原始请求体
            mapped_model: 映射后的模型名（子类使用）

        Returns:
            请求体（默认不修改）
        """
        # 基类不修改请求体，子类覆盖此方法实现特定格式的处理
        return request_body

    def get_model_for_url(
        self,
        request_body: Dict[str, Any],
        mapped_model: Optional[str],
    ) -> Optional[str]:
        """
        获取用于 URL 路径的模型名

        某些 API 格式（如 Gemini）需要将 model 放入 URL 路径中。
        子类应覆盖此方法返回正确的值。

        Args:
            request_body: 请求体
            mapped_model: 映射后的模型名（如果有）

        Returns:
            用于 URL 路径的模型名
        """
        return mapped_model or request_body.get("model")

    def prepare_provider_request_body(
        self,
        request_body: Dict[str, Any],
    ) -> Dict[str, Any]:
        """
        准备发送给 Provider 的请求体 - 子类可覆盖

        在模型映射之后、发送请求之前调用，用于移除不需要发送给上游的字段。
        例如 Gemini API 需要移除请求体中的 model 字段（因为 model 在 URL 路径中）。

        Args:
            request_body: 经过模型映射处理后的请求体

        Returns:
            准备好的请求体
        """
        return request_body

    async def _get_mapped_model(
        self,
        source_model: str,
        provider_id: str,
    ) -> Optional[str]:
        """
        获取模型映射后的实际模型名

        Args:
            source_model: 用户请求的模型名
            provider_id: Provider ID

        Returns:
            映射后的 provider_model_name，没有映射则返回 None
        """
        from src.services.model.mapper import ModelMapperMiddleware

        mapper = ModelMapperMiddleware(self.db)
        mapping = await mapper.get_mapping(source_model, provider_id)

        if mapping and mapping.model:
            # 使用 select_provider_model_name 支持映射功能
            # 传入 api_key.id 作为 affinity_key，实现相同用户稳定选择同一映射
            # 传入 api_format 用于过滤适用的映射作用域
            affinity_key = self.api_key.id if self.api_key else None
            mapped_name = mapping.model.select_provider_model_name(
                affinity_key, api_format=self.FORMAT_ID
            )
            logger.debug(f"[Chat] 模型映射: {source_model} -> {mapped_name}")
            return mapped_name

        return None

    # ==================== 流式处理 ====================

    async def process_stream(
        self,
        request: Any,
        http_request: Request,
        original_headers: Dict[str, Any],
        original_request_body: Dict[str, Any],
        query_params: Optional[Dict[str, str]] = None,
    ) -> StreamingResponse:
        """处理流式响应"""
        logger.debug(f"开始流式响应处理 ({self.FORMAT_ID})")

        # 转换请求格式
        converted_request = await self._convert_request(request)
        model = getattr(converted_request, "model", original_request_body.get("model", "unknown"))
        api_format = self.allowed_api_formats[0]

        # 创建类型安全的流式上下文
        ctx = StreamContext(model=model, api_format=api_format)

        # 创建更新状态的回调闭包（可以访问 ctx）
        def update_streaming_status() -> None:
            self._update_usage_to_streaming_with_ctx(ctx)

        # 创建流处理器
        stream_processor = StreamProcessor(
            request_id=self.request_id,
            default_parser=self.parser,
            on_streaming_start=update_streaming_status,
        )

        # 定义请求函数
        async def stream_request_func(
            provider: Provider,
            endpoint: ProviderEndpoint,
            key: ProviderAPIKey,
        ) -> AsyncGenerator[bytes, None]:
            return await self._execute_stream_request(
                ctx,
                stream_processor,
                provider,
                endpoint,
                key,
                original_request_body,
                original_headers,
                query_params,
            )

        try:
            # 解析能力需求
            capability_requirements = self._resolve_capability_requirements(
                model_name=model,
                request_headers=original_headers,
            )

            # 执行请求（通过 FallbackOrchestrator）
            (
                stream_generator,
                provider_name,
                attempt_id,
                provider_id,
                endpoint_id,
                key_id,
            ) = await self.orchestrator.execute_with_fallback(
                api_format=api_format,
                model_name=model,
                user_api_key=self.api_key,
                request_func=stream_request_func,
                request_id=self.request_id,
                is_stream=True,
                capability_requirements=capability_requirements or None,
            )

            # 更新上下文
            ctx.attempt_id = attempt_id
            ctx.provider_name = provider_name
            ctx.provider_id = provider_id
            ctx.endpoint_id = endpoint_id
            ctx.key_id = key_id

            # 创建遥测记录器
            telemetry_recorder = StreamTelemetryRecorder(
                request_id=self.request_id,
                user_id=str(self.user.id),
                api_key_id=str(self.api_key.id),
                client_ip=self.client_ip,
                format_id=self.FORMAT_ID,
            )

            # 创建后台任务记录统计
            background_tasks = BackgroundTasks()
            background_tasks.add_task(
                telemetry_recorder.record_stream_stats,
                ctx,
                original_headers,
                original_request_body,
                self.start_time,  # 传入开始时间，让 telemetry 在流结束后计算响应时间
            )

            # 创建监控流
            monitored_stream = stream_processor.create_monitored_stream(
                ctx,
                stream_generator,
                http_request.is_disconnected,
            )

            return StreamingResponse(
                monitored_stream,
                media_type="text/event-stream",
                headers=build_sse_headers(),
                background=background_tasks,
            )

        except Exception as e:
            self._log_request_error("流式请求失败", e)
            await self._record_stream_failure(ctx, e, original_headers, original_request_body)
            raise

    async def _execute_stream_request(
        self,
        ctx: StreamContext,
        stream_processor: StreamProcessor,
        provider: Provider,
        endpoint: ProviderEndpoint,
        key: ProviderAPIKey,
        original_request_body: Dict[str, Any],
        original_headers: Dict[str, str],
        query_params: Optional[Dict[str, str]] = None,
    ) -> AsyncGenerator[bytes, None]:
        """执行流式请求并返回流生成器"""
        # 重置上下文状态（重试时清除之前的数据）
        ctx.reset_for_retry()

        # 更新 Provider 信息
        ctx.update_provider_info(
            provider_name=str(provider.name),
            provider_id=str(provider.id),
            endpoint_id=str(endpoint.id),
            key_id=str(key.id),
            provider_api_format=str(endpoint.api_format) if endpoint.api_format else None,
        )

        # 获取模型映射
        mapped_model = await self._get_mapped_model(
            source_model=ctx.model,
            provider_id=str(provider.id),
        )

        # 应用模型映射到请求体
        if mapped_model:
            ctx.mapped_model = mapped_model
            request_body = self.apply_mapped_model(original_request_body, mapped_model)
        else:
            request_body = dict(original_request_body)

        # 准备发送给 Provider 的请求体
        request_body = self.prepare_provider_request_body(request_body)

        # 构建请求
        provider_payload, provider_headers = self._request_builder.build(
            request_body,
            original_headers,
            endpoint,
            key,
            is_stream=True,
        )

        ctx.provider_request_headers = provider_headers
        ctx.provider_request_body = provider_payload

        # 获取 URL 模型名
        url_model = self.get_model_for_url(request_body, mapped_model) or ctx.model

        url = build_provider_url(
            endpoint,
            query_params=query_params,
            path_params={"model": url_model},
            is_stream=True,
        )

        logger.debug(
            f"  [{self.request_id}] 发送流式请求: Provider={provider.name}, "
            f"模型={ctx.model} -> {mapped_model or '无映射'}"
        )

        # 发送请求（使用配置中的超时设置）
        timeout_config = httpx.Timeout(
            connect=config.http_connect_timeout,
            read=float(endpoint.timeout),
            write=config.http_write_timeout,
            pool=config.http_pool_timeout,
        )

        # 创建 HTTP 客户端（支持代理配置）
        from src.clients.http_client import HTTPClientPool

        http_client = HTTPClientPool.create_client_with_proxy(
            proxy_config=endpoint.proxy,
            timeout=timeout_config,
        )
        try:
            response_ctx = http_client.stream(
                "POST", url, json=provider_payload, headers=provider_headers
            )
            stream_response = await response_ctx.__aenter__()

            ctx.status_code = stream_response.status_code
            ctx.response_headers = dict(stream_response.headers)

            stream_response.raise_for_status()

            # 使用字节流迭代器（避免 aiter_lines 的性能问题）
            # aiter_raw() 返回原始数据块，无缓冲，实现真正的流式传输
            byte_iterator = stream_response.aiter_raw()

            # 预读检测嵌套错误
            prefetched_chunks = await stream_processor.prefetch_and_check_error(
                byte_iterator,
                provider,
                endpoint,
                ctx,
                max_prefetch_lines=config.stream_prefetch_lines,
            )

        except httpx.HTTPStatusError as e:
            error_text = await self._extract_error_text(e)
            logger.error(f"Provider 返回错误: {e.response.status_code}\n  Response: {error_text}")
            await http_client.aclose()
            raise

        except EmbeddedErrorException:
            try:
                await response_ctx.__aexit__(None, None, None)
            except Exception:
                pass
            await http_client.aclose()
            raise

        except Exception:
            await http_client.aclose()
            raise

        # 创建流生成器（传入字节流迭代器）
        return stream_processor.create_response_stream(
            ctx,
            byte_iterator,
            response_ctx,
            http_client,
            prefetched_chunks,
            start_time=self.start_time,
        )

    async def _record_stream_failure(
        self,
        ctx: StreamContext,
        error: Exception,
        original_headers: Dict[str, str],
        original_request_body: Dict[str, Any],
    ) -> None:
        """记录流式请求失败"""
        response_time_ms = self.elapsed_ms()

        status_code = 503
        if isinstance(error, ProviderAuthException):
            status_code = 503
        elif isinstance(error, ProviderRateLimitException):
            status_code = 429
        elif isinstance(error, ProviderTimeoutException):
            status_code = 504

        actual_request_body = ctx.provider_request_body or original_request_body

        await self.telemetry.record_failure(
            provider=ctx.provider_name or "unknown",
            model=ctx.model,
            response_time_ms=response_time_ms,
            status_code=status_code,
            error_message=str(error),
            request_headers=original_headers,
            request_body=actual_request_body,
            is_stream=True,
            api_format=ctx.api_format,
            provider_request_headers=ctx.provider_request_headers,
            target_model=ctx.mapped_model,
        )

    # ==================== 非流式处理 ====================

    async def process_sync(
        self,
        request: Any,
        http_request: Request,
        original_headers: Dict[str, Any],
        original_request_body: Dict[str, Any],
        query_params: Optional[Dict[str, str]] = None,
    ) -> JSONResponse:
        """处理非流式响应"""
        logger.debug(f"开始非流式响应处理 ({self.FORMAT_ID})")

        # 转换请求格式
        converted_request = await self._convert_request(request)
        model = getattr(converted_request, "model", original_request_body.get("model", "unknown"))
        api_format = self.allowed_api_formats[0]

        # 用于跟踪的变量
        provider_name: Optional[str] = None
        response_json: Optional[Dict[str, Any]] = None
        status_code = 200
        response_headers: Dict[str, str] = {}
        provider_request_headers: Dict[str, str] = {}
        provider_request_body: Optional[Dict[str, Any]] = None
        provider_id: Optional[str] = None  # Provider ID（用于失败记录）
        endpoint_id: Optional[str] = None  # Endpoint ID（用于失败记录）
        key_id: Optional[str] = None  # Key ID（用于失败记录）
        mapped_model_result: Optional[str] = None  # 映射后的目标模型名（用于 Usage 记录）

        async def sync_request_func(
            provider: Provider,
            endpoint: ProviderEndpoint,
            key: ProviderAPIKey,
        ) -> Dict[str, Any]:
            nonlocal provider_name, response_json, status_code, response_headers
            nonlocal provider_request_headers, provider_request_body, mapped_model_result

            provider_name = str(provider.name)

            # 获取模型映射
            mapped_model = await self._get_mapped_model(
                source_model=model,
                provider_id=str(provider.id),
            )

            # 应用模型映射
            if mapped_model:
                mapped_model_result = mapped_model  # 保存映射后的模型名，用于 Usage 记录
                request_body = self.apply_mapped_model(original_request_body, mapped_model)
            else:
                request_body = dict(original_request_body)

            # 准备发送给 Provider 的请求体（子类可覆盖以移除不需要的字段）
            request_body = self.prepare_provider_request_body(request_body)

            # 构建请求
            provider_payload, provider_hdrs = self._request_builder.build(
                request_body,
                original_headers,
                endpoint,
                key,
                is_stream=False,
            )

            provider_request_headers = provider_hdrs
            provider_request_body = provider_payload

            # 获取 URL 模型名（兜底使用外层的 model，确保 Gemini 等格式能正确构建 URL）
            url_model = self.get_model_for_url(request_body, mapped_model) or model

            url = build_provider_url(
                endpoint,
                query_params=query_params,
                path_params={"model": url_model},
                is_stream=False,
            )

            logger.info(f"  [{self.request_id}] 发送非流式请求: Provider={provider.name}, "
                f"模型={model} -> {mapped_model or '无映射'}")
            logger.debug(f"  [{self.request_id}] 请求URL: {url}")
            logger.debug(f"  [{self.request_id}] 请求体stream字段: {provider_payload.get('stream', 'N/A')}")

            # 创建 HTTP 客户端（支持代理配置）
            from src.clients.http_client import HTTPClientPool

            http_client = HTTPClientPool.create_client_with_proxy(
                proxy_config=endpoint.proxy,
                timeout=httpx.Timeout(float(endpoint.timeout)),
            )
            async with http_client:
                resp = await http_client.post(url, json=provider_payload, headers=provider_hdrs)

                status_code = resp.status_code
                response_headers = dict(resp.headers)

                if resp.status_code == 401:
                    raise ProviderAuthException(f"提供商认证失败: {provider.name}")
                elif resp.status_code == 429:
                    raise ProviderRateLimitException(
                        f"提供商速率限制: {provider.name}",
                        provider_name=str(provider.name),
                        response_headers=response_headers,
                    )
                elif resp.status_code >= 500:
                    # 记录响应体以便调试
                    error_body = ""
                    try:
                        error_body = resp.text[:1000]
                        logger.error(f"  [{self.request_id}] 上游返回5xx错误: status={resp.status_code}, body={error_body[:500]}")
                    except Exception:
                        pass
                    raise ProviderNotAvailableException(
                        f"提供商服务不可用: {provider.name}",
                        provider_name=str(provider.name),
                        upstream_status=resp.status_code,
                        upstream_response=error_body,
                    )
                elif resp.status_code != 200:
                    # 记录非200响应以便调试
                    error_body = ""
                    try:
                        error_body = resp.text[:1000]
                        logger.warning(f"  [{self.request_id}] 上游返回非200: status={resp.status_code}, body={error_body[:500]}")
                    except Exception:
                        pass
                    raise ProviderNotAvailableException(
                        f"提供商返回错误: {provider.name}, 状态: {resp.status_code}",
                        provider_name=str(provider.name),
                        upstream_status=resp.status_code,
                        upstream_response=error_body,
                    )

                response_json = resp.json()
                return response_json if isinstance(response_json, dict) else {}

        try:
            # 解析能力需求
            capability_requirements = self._resolve_capability_requirements(
                model_name=model,
                request_headers=original_headers,
            )

            (
                result,
                actual_provider_name,
                attempt_id,
                provider_id,
                endpoint_id,
                key_id,
            ) = await self.orchestrator.execute_with_fallback(
                api_format=api_format,
                model_name=model,
                user_api_key=self.api_key,
                request_func=sync_request_func,
                request_id=self.request_id,
                capability_requirements=capability_requirements or None,
            )

            provider_name = actual_provider_name
            response_time_ms = self.elapsed_ms()

            # 确保 response_json 不为 None
            if response_json is None:
                response_json = {}

            # 规范化响应
            response_json = self._normalize_response(response_json)

            # 提取 usage
            usage_info = self._extract_usage(response_json)
            input_tokens = usage_info.get("input_tokens", 0)
            output_tokens = usage_info.get("output_tokens", 0)
            cache_creation_tokens = usage_info.get("cache_creation_input_tokens", 0)
            cached_tokens = usage_info.get("cache_read_input_tokens", 0)

            actual_request_body = provider_request_body or original_request_body

            total_cost = await self.telemetry.record_success(
                provider=provider_name,
                model=model,
                input_tokens=input_tokens,
                output_tokens=output_tokens,
                response_time_ms=response_time_ms,
                status_code=status_code,
                request_headers=original_headers,
                request_body=actual_request_body,
                response_headers=response_headers,
                response_body=response_json,
                cache_creation_tokens=cache_creation_tokens,
                cache_read_tokens=cached_tokens,
                is_stream=False,
                provider_request_headers=provider_request_headers,
                api_format=api_format,
                provider_id=provider_id,
                provider_endpoint_id=endpoint_id,
                provider_api_key_id=key_id,
                # 模型映射信息
                target_model=mapped_model_result,
            )

            logger.debug(f"{self.FORMAT_ID} 非流式响应完成")

            # 简洁的请求完成摘要
            logger.info(f"[OK] {self.request_id[:8]} | {model} | {provider_name or 'unknown'} | {response_time_ms}ms | "
                f"in:{input_tokens or 0} out:{output_tokens or 0}")

            return JSONResponse(status_code=status_code, content=response_json)

        except Exception as e:
            response_time_ms = self.elapsed_ms()

            status_code = 503
            if isinstance(e, ProviderAuthException):
                status_code = 503
            elif isinstance(e, ProviderRateLimitException):
                status_code = 429
            elif isinstance(e, ProviderTimeoutException):
                status_code = 504

            actual_request_body = provider_request_body or original_request_body

            await self.telemetry.record_failure(
                provider=provider_name or "unknown",
                model=model,
                response_time_ms=response_time_ms,
                status_code=status_code,
                error_message=str(e),
                request_headers=original_headers,
                request_body=actual_request_body,
                is_stream=False,
                api_format=api_format,
                provider_request_headers=provider_request_headers,
                # 模型映射信息
                target_model=mapped_model_result,
            )

            raise

    async def _extract_error_text(self, e: httpx.HTTPStatusError) -> str:
        """从 HTTP 错误中提取错误文本"""
        try:
            if hasattr(e.response, "is_stream_consumed") and not e.response.is_stream_consumed:
                error_bytes = await e.response.aread()
                return error_bytes.decode("utf-8", errors="replace")[:500]
            else:
                return (
                    e.response.text[:500] if hasattr(e.response, "_content") else "Unable to read"
                )
        except Exception as decode_error:
            return f"Unable to read error: {decode_error}"