ForcePilot/backend/package/yuxi/external_systems/integrations/twilio/operations.py

"""Twilio discover / preview_tools / create_tools handler 实现 +
Webhook 签名验证 + 资源可达性探测。

handler 签名遵循 ``OperationHandler`` 协议：
``(source_type: str, system_config: dict[str, Any]) -> Awaitable[Any]``。

handler 内部职责（见设计文档 §7.4）：
1. 从 ``system_config`` 提取 ``connection_config`` / ``auth_config`` / ``resolved_credential``
2. 构建 Basic Auth 请求头（Account SID + Auth Token）
3. 调用 Twilio API 探测资源可达性（discover）或调用生成器（preview/create）

与 dynamics365 的关键差异：dynamics365 使用 OAuth2（``is_token_based=True``），
``system_config`` 含 ``_resolved_token``；Twilio 使用 Basic Auth（``is_token_based=False``），
``system_config`` 含 ``resolved_credential``（dict 形态，含 username / password）。

429 退避分层（见设计文档 §6.4）：
- discover/preview/create 阶段：本模块 ``_request_with_retry`` 实现（解析 Retry-After）
- 运行时工具执行：通过工具 ``retry_policy.retry_status_codes: [429]`` 配置（见 generators.py）
"""

from __future__ import annotations

import asyncio
import base64
import hashlib
import hmac
from collections.abc import Awaitable, Callable
from typing import TYPE_CHECKING, Any

from yuxi.external_systems.exceptions import (
    AuthError,
    DomainValidationError,
    ExecutionError,
    RateLimitExceededError,
    WebhookError,
)
from yuxi.external_systems.integrations.schemas import GeneratedToolsDraft
from yuxi.external_systems.integrations.twilio.error_mapper import (
    map_twilio_error,
)
from yuxi.external_systems.integrations.twilio.generators import (
    TwilioConfigGenerator,
)
from yuxi.external_systems.integrations.twilio.metadata import (
    DEFAULT_API_VERSION,
    DEFAULT_BASE_URL,
)

if TYPE_CHECKING:
    import httpx

# discover/preview/create 阶段 429 退避参数（与 dynamics365 一致）
_RETRY_MAX_ATTEMPTS = 5
_RETRY_BASE_DELAY = 1.0

# discover 阶段资源可达性探测的路径与描述
# accessible=True 表示该资源可被当前账户访问
_RESOURCE_PROBES: list[dict[str, Any]] = [
    {
        "resource": "Messages",
        "path_template": "/{api_version}/Accounts/{account_sid}/Messages.json",
        "operations": ["list", "get", "create"],
        "description": "短信发送与查询",
    },
    {
        "resource": "Calls",
        "path_template": "/{api_version}/Accounts/{account_sid}/Calls.json",
        "operations": ["list", "get", "create"],
        "description": "语音通话发起与查询",
    },
    {
        "resource": "IncomingPhoneNumbers",
        "path_template": "/{api_version}/Accounts/{account_sid}/IncomingPhoneNumbers.json",
        "operations": ["list", "get", "create", "update", "delete"],
        "description": "已购号码管理",
    },
    {
        "resource": "AvailablePhoneNumbers",
        "path_template": ("/{api_version}/Accounts/{account_sid}/AvailablePhoneNumbers/US/Local.json"),
        "operations": ["list"],
        "description": "可用号码查询（按国家）",
    },
    {
        "resource": "UsageRecords",
        "path_template": "/{api_version}/Accounts/{account_sid}/Usage/Records.json",
        "operations": ["list"],
        "description": "用量与费用查询",
    },
]


# ═══════════════════════════════════════════════════════════════════════════
# Webhook 签名验证
# ═══════════════════════════════════════════════════════════════════════════


def verify_twilio_signature(
    auth_token: str,
    webhook_url: str,
    form_params: dict[str, Any],
    signature: str,
) -> bool:
    """验证 Twilio Webhook 签名。

    Twilio 签名规则：
        1. 将 webhook_url 与排序后的表单参数（key=value）拼接为字符串
        2. 使用 auth_token 作为 HMAC-SHA256 密钥计算哈希
        3. Base64 编码后与 ``X-Twilio-Signature`` 头比对

    Args:
        auth_token: Account Auth Token（HMAC 密钥）
        webhook_url: Twilio 控制台配置的 Webhook URL（必须完全一致）
        form_params: Webhook 请求的表单参数（application/x-www-form-urlencoded）
        signature: ``X-Twilio-Signature`` 头的值（Base64）

    Returns:
        True 表示验签通过，False 表示签名不匹配。
    """
    # 1. 拼接 URL + 排序后的参数
    sorted_params = sorted(form_params.items())
    param_str = "".join(f"{k}{v}" for k, v in sorted_params)
    data = f"{webhook_url}{param_str}".encode()

    # 2. HMAC-SHA256 + Base64
    expected = base64.b64encode(hmac.new(auth_token.encode("utf-8"), data, hashlib.sha256).digest()).decode("utf-8")

    # 3. 常量时间比对（防时序攻击）
    return hmac.compare_digest(expected, signature)


def verify_twilio_signature_or_raise(
    auth_token: str,
    webhook_url: str,
    form_params: dict[str, Any],
    signature: str,
    *,
    account_sid: str | None = None,
) -> None:
    """验证 Twilio Webhook 签名，失败时抛 ``WebhookError``。

    Args:
        auth_token: Account Auth Token（HMAC 密钥）
        webhook_url: Twilio 控制台配置的 Webhook URL
        form_params: Webhook 请求的表单参数
        signature: ``X-Twilio-Signature`` 头的值
        account_sid: Account SID（用于错误上下文，可选）

    Raises:
        WebhookError: 签名不匹配。
    """
    if not verify_twilio_signature(auth_token, webhook_url, form_params, signature):
        context = f" (account_sid={account_sid})" if account_sid else ""
        raise WebhookError(
            f"Twilio Webhook 签名验证失败{context}",
            details={
                "webhook_url": webhook_url,
                "account_sid": account_sid,
            },
        )


# ═══════════════════════════════════════════════════════════════════════════
# system_config 解析辅助函数
# ═══════════════════════════════════════════════════════════════════════════


def _resolve_base_url(system_config: dict[str, Any]) -> str:
    """从 system_config 提取 base_url，默认 https://api.twilio.com。"""
    connection_config = system_config.get("connection_config") or {}
    base_url = connection_config.get("base_url") or DEFAULT_BASE_URL
    return str(base_url)


def _resolve_account_sid(system_config: dict[str, Any]) -> str:
    """从 system_config 提取 account_sid，校验非空。"""
    connection_config = system_config.get("connection_config") or {}
    account_sid = connection_config.get("account_sid")
    if not account_sid:
        raise DomainValidationError("twilio: connection_config.account_sid 不能为空")
    return str(account_sid)


def _resolve_api_version(system_config: dict[str, Any]) -> str:
    """从 system_config 提取 api_version，默认 2010-04-01。"""
    connection_config = system_config.get("connection_config") or {}
    return str(connection_config.get("api_version", DEFAULT_API_VERSION))


def _build_basic_auth_headers(system_config: dict[str, Any]) -> dict[str, str]:
    """从 system_config 构造 Basic Auth 请求头。

    Twilio Basic Auth: username=Account SID, password=Auth Token。
    ``resolved_credential`` 为 use_cases 层注入的解析后凭证（dict 形态，
    含 username / password；或 ``BasicCredential`` 实例）。
    """
    credential = system_config.get("resolved_credential")
    if credential is None:
        raise AuthError("twilio: system_config 缺少 resolved_credential，use_cases 层未注入解析后的凭证")

    # 兼容 dict 与 BasicCredential 两种形态
    if isinstance(credential, dict):
        username = credential.get("username")
        password = credential.get("password")
    else:
        # BasicCredential 实例（框架 _resolve_credential 返回）
        username = getattr(credential, "username", None)
        password = getattr(credential, "password", None)

    if not username or not password:
        raise AuthError("twilio: resolved_credential 缺少 username 或 password")

    credentials = f"{username}:{password}".encode()
    token = base64.b64encode(credentials).decode("utf-8")
    return {
        "Authorization": f"Basic {token}",
        "Accept": "application/json",
    }


# ═══════════════════════════════════════════════════════════════════════════
# HTTP 请求辅助（带 429 退避）
# ═══════════════════════════════════════════════════════════════════════════


async def _request_with_retry(
    method: str,
    url: str,
    headers: dict[str, str],
    *,
    max_retries: int = _RETRY_MAX_ATTEMPTS,
    base_delay: float = _RETRY_BASE_DELAY,
) -> httpx.Response:
    """handler 内部 HTTP 调用的 429 退避（仅用于 discover/preview/create 阶段）。

    与 dynamics365 ``_request_with_retry`` 模式一致：
    - 优先使用响应头 ``Retry-After``，否则指数退避
    - 非 2xx 响应（非 429）通过 ``map_twilio_error`` 转换为 ``ExternalSystemError`` 子类
    - 网络层异常转换为 ``ExecutionError``
    """
    import httpx

    try:
        async with httpx.AsyncClient() as client:
            last_response: httpx.Response | None = None
            for attempt in range(max_retries + 1):
                response = await client.request(method, url, headers=headers)
                if response.status_code != 429:
                    last_response = response
                    break
                if attempt == max_retries:
                    retry_after_header = response.headers.get("Retry-After", "1")
                    try:
                        retry_after = int(retry_after_header)
                    except ValueError:
                        retry_after = 1
                    raise RateLimitExceededError(
                        f"Twilio 限流，已重试 {max_retries} 次仍失败: {url}",
                        retry_after=retry_after,
                        limit_type="qps",
                    )
                # 优先使用 Retry-After 头，否则指数退避
                retry_after_header = response.headers.get("Retry-After")
                if retry_after_header:
                    try:
                        delay = float(retry_after_header)
                    except ValueError:
                        delay = base_delay * (2**attempt)
                else:
                    delay = base_delay * (2**attempt)
                await asyncio.sleep(delay)
    except httpx.RequestError as exc:
        raise ExecutionError(f"Twilio 网络请求失败: {exc}") from exc

    assert last_response is not None
    if last_response.is_success:
        return last_response
    # 非 2xx：解析错误 body 并映射为 ExternalSystemError 子类
    try:
        error_body = last_response.json()
    except Exception:
        error_body = {"message": last_response.text}
    raise map_twilio_error(last_response.status_code, error_body)


def _make_request_fn() -> Callable[[str, str, dict[str, str]], Awaitable[httpx.Response]]:
    """构造带 429 退避的 request_fn，供 ``_discover_resources`` 使用。"""

    async def request_fn(method: str, url: str, headers: dict[str, str]) -> httpx.Response:
        return await _request_with_retry(method, url, headers)

    return request_fn


# ═══════════════════════════════════════════════════════════════════════════
# 资源可达性探测
# ═══════════════════════════════════════════════════════════════════════════


async def _discover_resources(
    base_url: str,
    api_version: str,
    account_sid: str,
    auth_headers: dict[str, str],
    request_fn: Callable[[str, str, dict[str, str]], Awaitable[httpx.Response]],
) -> list[dict[str, Any]]:
    """探测 Twilio 资源可达性，返回资源描述列表。

    探测策略（见设计文档 §4.2）：
    1. 调用 ``GET /Accounts/{AccountSid}.json`` 获取账户信息
    2. 并行探测 Messages / Calls / IncomingPhoneNumbers / AvailablePhoneNumbers /
       UsageRecords 资源可达性（``PageSize=1``）
    3. 对可达资源构造资源描述 dict
    4. 探测失败的资源标记 ``accessible=False``，不中断整体发现流程
    """
    resources: list[dict[str, Any]] = []

    # 1. 账户信息（用于上下文，失败不中断）
    account_info: dict[str, Any] = {}
    try:
        account_url = f"{base_url}/{api_version}/Accounts/{account_sid}.json"
        resp = await request_fn("GET", account_url, auth_headers)
        account_info = resp.json() if resp.is_success else {}
    except Exception:
        # 账户信息获取失败不中断资源探测
        account_info = {}

    # 2. 并行探测资源可达性
    async def _probe(probe: dict[str, Any]) -> dict[str, Any]:
        path = probe["path_template"].format(api_version=api_version, account_sid=account_sid)
        url = f"{base_url}{path}?PageSize=1"
        try:
            resp = await request_fn("GET", url, auth_headers)
            accessible = resp.is_success
        except Exception:
            accessible = False
        return {
            "resource": probe["resource"],
            "path": probe["path_template"],
            "operations": probe["operations"],
            "accessible": accessible,
            "description": probe["description"],
        }

    probe_results = await asyncio.gather(*[_probe(p) for p in _RESOURCE_PROBES])
    resources.extend(probe_results)

    # 3. 注入账户上下文（friendly_name / status / type）
    if account_info:
        for r in resources:
            r["account_friendly_name"] = account_info.get("friendly_name")
            r["account_status"] = account_info.get("status")
            r["account_type"] = account_info.get("type")

    return resources


# ═══════════════════════════════════════════════════════════════════════════
# OperationHandler 实现
# ═══════════════════════════════════════════════════════════════════════════


async def discover_twilio(
    source_type: str,
    system_config: dict[str, Any],
) -> list[dict[str, Any]]:
    """discover handler：发现 Twilio 可用资源（账户信息 + 资源可达性探测）。

    Returns:
        资源摘要列表，每项含 resource / path / operations / accessible / description。
    """
    base_url = _resolve_base_url(system_config)
    account_sid = _resolve_account_sid(system_config)
    api_version = _resolve_api_version(system_config)
    auth_headers = _build_basic_auth_headers(system_config)
    request_fn = _make_request_fn()

    return await _discover_resources(base_url, api_version, account_sid, auth_headers, request_fn)


async def preview_twilio_tools(
    source_type: str,
    system_config: dict[str, Any],
) -> list[dict[str, Any]]:
    """preview_tools handler：预览将生成的工具列表。

    Returns:
        工具预览列表，每项为 ExternalToolCreateInput 兼容的 dict。
    """
    payload = _build_generator_payload(system_config)
    generator = TwilioConfigGenerator()
    return await generator.generate(payload)


async def create_twilio_tools(
    source_type: str,
    system_config: dict[str, Any],
) -> GeneratedToolsDraft:
    """create_tools handler：生成工具草稿（不直接持久化）。

    Returns:
        GeneratedToolsDraft，由 use_cases 层统一持久化。
    """
    payload = _build_generator_payload(system_config)
    generator = TwilioConfigGenerator()
    tool_configs = await generator.generate(payload)
    return GeneratedToolsDraft(tool_configs=tool_configs, override_existing=False)


# ═══════════════════════════════════════════════════════════════════════════
# 生成器 payload 构造
# ═══════════════════════════════════════════════════════════════════════════


def _build_generator_payload(system_config: dict[str, Any]) -> dict[str, Any]:
    """从 system_config 构造生成器 payload。

    生成器 payload 是 system_config 的子集，包含：
    - account_sid: str — 烘焙到 path_template
    - base_url: str
    - api_version: str
    - resources: list[dict] — discover 返回的资源描述（若已存在）
    - selected_resources: list[str] | None
    - auth_type: str
    - auth_config: dict
    """
    discovery_options = system_config.get("discovery_options") or {}
    # 若 system_config 已含 discover 结果（由 use_cases 层注入），直接复用；
    # 否则使用全量资源（生成器内部按 selected_resources 过滤）。
    resources = system_config.get("discovered_resources") or _get_default_resources()

    return {
        "account_sid": _resolve_account_sid(system_config),
        "base_url": _resolve_base_url(system_config),
        "api_version": _resolve_api_version(system_config),
        "resources": resources,
        "auth_type": (system_config.get("auth_config") or {}).get("auth_type", "basic"),
        "auth_config": system_config.get("auth_config") or {},
        "selected_resources": discovery_options.get("selected_resources"),
    }


def _get_default_resources() -> list[dict[str, Any]]:
    """返回默认资源列表（全部 accessible=True，供 preview/create 在未 discover 时使用）。"""
    return [
        {
            "resource": probe["resource"],
            "path": probe["path_template"],
            "operations": probe["operations"],
            "accessible": True,
            "description": probe["description"],
        }
        for probe in _RESOURCE_PROBES
    ]