coding-proxy 0.1.0__py3-none-any.whl

coding/proxy/routing/quota_guard.py

@@ -0,0 +1,169 @@
+"""用量配额守卫 (Quota Guard) — 滑动窗口限额与探测恢复."""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from collections import deque
+from enum import Enum
+
+logger = logging.getLogger(__name__)
+
+
+class QuotaState(Enum):
+    WITHIN_QUOTA = "within_quota"
+    QUOTA_EXCEEDED = "quota_exceeded"
+
+
+class QuotaGuard:
+    """基于滑动窗口的用量配额守卫.
+
+    状态转换:
+    - WITHIN_QUOTA → QUOTA_EXCEEDED: 窗口用量 >= budget × threshold% 或检测到 cap 错误
+    - QUOTA_EXCEEDED → WITHIN_QUOTA: 窗口用量自然滑出 < threshold% 或探测成功
+    """
+
+    def __init__(
+        self,
+        *,
+        enabled: bool = False,
+        token_budget: int = 0,
+        window_seconds: int = 18000,
+        threshold_percent: float = 99.0,
+        probe_interval_seconds: int = 300,
+    ) -> None:
+        self._enabled = enabled
+        self._budget = token_budget
+        self._window = window_seconds
+        self._threshold = threshold_percent / 100.0
+        self._probe_interval = probe_interval_seconds
+
+        self._state = QuotaState.WITHIN_QUOTA
+        self._entries: deque[tuple[float, int]] = deque()
+        self._total: int = 0
+        self._last_probe: float = 0.0
+        self._cap_error_active: bool = False
+        self._effective_probe_interval: float = probe_interval_seconds
+        self._lock = threading.Lock()
+
+    @property
+    def enabled(self) -> bool:
+        return self._enabled
+
+    @property
+    def window_hours(self) -> float:
+        """滑动窗口小时数（供基线加载使用）."""
+        return self._window / 3600
+
+    def can_use_primary(self) -> bool:
+        """判断是否可以使用主后端."""
+        if not self._enabled:
+            return True
+        with self._lock:
+            self._expire()
+            if self._state == QuotaState.WITHIN_QUOTA:
+                if self._budget > 0 and self._total >= int(self._budget * self._threshold):
+                    self._transition_to(QuotaState.QUOTA_EXCEEDED)
+                    logger.warning(
+                        "Quota guard: WITHIN_QUOTA → EXCEEDED (%.1f%%)",
+                        self._total / self._budget * 100,
+                    )
+                    return False
+                return True
+            # QUOTA_EXCEEDED — cap 错误触发时仅允许探测恢复，不做预算自动恢复
+            if not self._cap_error_active and self._budget > 0 and self._total < int(self._budget * self._threshold):
+                self._transition_to(QuotaState.WITHIN_QUOTA)
+                logger.info("Quota guard: EXCEEDED → WITHIN_QUOTA (usage dropped)")
+                return True
+            now = time.monotonic()
+            if now - self._last_probe >= self._effective_probe_interval:
+                self._last_probe = now
+                logger.info("Quota guard: allowing probe request")
+                return True
+            return False
+
+    def record_usage(self, tokens: int) -> None:
+        """记录新 token 用量到滑动窗口."""
+        if not self._enabled or tokens <= 0:
+            return
+        with self._lock:
+            self._entries.append((time.monotonic(), tokens))
+            self._total += tokens
+
+    def record_primary_success(self) -> None:
+        """记录主后端请求成功（探测恢复触发点）."""
+        if not self._enabled:
+            return
+        with self._lock:
+            if self._state == QuotaState.QUOTA_EXCEEDED:
+                self._transition_to(QuotaState.WITHIN_QUOTA)
+                logger.info("Quota guard: EXCEEDED → WITHIN_QUOTA (probe success)")
+
+    def notify_cap_error(self, retry_after_seconds: float | None = None) -> None:
+        """外部通知检测到用量上限错误.
+
+        Args:
+            retry_after_seconds: 从响应头解析的建议恢复时间。
+                若提供，更新探测间隔以避免过早探测。
+        """
+        if not self._enabled:
+            return
+        with self._lock:
+            if self._state != QuotaState.QUOTA_EXCEEDED:
+                self._transition_to(QuotaState.QUOTA_EXCEEDED)
+            if retry_after_seconds is not None:
+                self._effective_probe_interval = max(
+                    retry_after_seconds * 1.1,
+                    self._probe_interval,
+                )
+            self._cap_error_active = True
+            logger.warning(
+                "Quota guard: cap error detected → EXCEEDED (effective_probe=%ds)",
+                int(self._effective_probe_interval),
+            )
+
+    def load_baseline(self, total_tokens: int) -> None:
+        """从数据库加载窗口历史用量基线."""
+        if not self._enabled or total_tokens <= 0:
+            return
+        with self._lock:
+            midpoint = time.monotonic() - self._window / 2
+            self._entries.append((midpoint, total_tokens))
+            self._total += total_tokens
+            logger.info("Quota guard: loaded baseline %d tokens", total_tokens)
+
+    def reset(self) -> None:
+        """手动重置为 WITHIN_QUOTA 状态."""
+        with self._lock:
+            self._transition_to(QuotaState.WITHIN_QUOTA)
+            self._entries.clear()
+            self._total = 0
+            logger.info("Quota guard: manually reset to WITHIN_QUOTA")
+
+    def get_info(self) -> dict:
+        """获取配额守卫状态信息."""
+        with self._lock:
+            self._expire()
+            return {
+                "state": self._state.value,
+                "window_usage_tokens": self._total,
+                "budget_tokens": self._budget,
+                "usage_percent": round(self._total / self._budget * 100, 1) if self._budget > 0 else 0,
+                "threshold_percent": self._threshold * 100,
+            }
+
+    def _expire(self) -> None:
+        """清除超出时间窗口的条目."""
+        cutoff = time.monotonic() - self._window
+        while self._entries and self._entries[0][0] < cutoff:
+            _, tokens = self._entries.popleft()
+            self._total -= tokens
+
+    def _transition_to(self, new_state: QuotaState) -> None:
+        self._state = new_state
+        if new_state == QuotaState.WITHIN_QUOTA:
+            self._cap_error_active = False
+            self._effective_probe_interval = self._probe_interval
+        elif new_state == QuotaState.QUOTA_EXCEEDED:
+            self._last_probe = time.monotonic()

coding/proxy/routing/rate_limit.py

@@ -0,0 +1,159 @@
+"""速率限制信息解析 — 从 HTTP 响应头提取恢复时间."""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class RateLimitInfo:
+    """从 429 响应中提取的速率限制信息."""
+
+    retry_after_seconds: float | None = None
+    requests_reset_at: float | None = None  # monotonic timestamp
+    tokens_reset_at: float | None = None  # monotonic timestamp
+    is_cap_error: bool = False
+
+
+def parse_rate_limit_headers(
+    headers: Any,
+    status_code: int,
+    error_body: str | None = None,
+) -> RateLimitInfo:
+    """从 HTTP 响应头和状态码解析速率限制信息.
+
+    Args:
+        headers: httpx.Headers 或 dict-like 响应头
+        status_code: HTTP 状态码
+        error_body: 错误响应体文本（用于检测 cap error）
+
+    Returns:
+        RateLimitInfo 实例
+    """
+    info = RateLimitInfo()
+
+    if status_code not in (429, 403):
+        return info
+
+    # 检测 cap error
+    if error_body:
+        msg = error_body.lower()
+        info.is_cap_error = any(
+            p in msg for p in ("usage cap", "quota", "limit exceeded")
+        )
+
+    # 解析 retry-after (标准 HTTP header)
+    retry_after = _get_header(headers, "retry-after")
+    if retry_after:
+        info.retry_after_seconds = _parse_retry_after(retry_after)
+
+    # 解析 anthropic-ratelimit-requests-reset (ISO 8601 datetime)
+    requests_reset = _get_header(headers, "anthropic-ratelimit-requests-reset")
+    if requests_reset:
+        info.requests_reset_at = _parse_reset_time(requests_reset)
+
+    # 解析 anthropic-ratelimit-tokens-reset (ISO 8601 datetime)
+    tokens_reset = _get_header(headers, "anthropic-ratelimit-tokens-reset")
+    if tokens_reset:
+        info.tokens_reset_at = _parse_reset_time(tokens_reset)
+
+    return info
+
+
+def compute_effective_retry_seconds(info: RateLimitInfo) -> float | None:
+    """从 RateLimitInfo 中计算最保守的恢复等待时间.
+
+    取所有可用信号中的最大值，并加 10% 安全余量。
+    """
+    candidates: list[float] = []
+
+    if info.retry_after_seconds is not None:
+        candidates.append(info.retry_after_seconds * 1.1)
+
+    now = time.monotonic()
+    if info.requests_reset_at is not None:
+        remaining = info.requests_reset_at - now
+        if remaining > 0:
+            candidates.append(remaining * 1.1)
+
+    if info.tokens_reset_at is not None:
+        remaining = info.tokens_reset_at - now
+        if remaining > 0:
+            candidates.append(remaining * 1.1)
+
+    return max(candidates) if candidates else None
+
+
+def compute_rate_limit_deadline(info: RateLimitInfo) -> float | None:
+    """从 RateLimitInfo 中计算最保守的恢复截止 monotonic 时间戳.
+
+    与 compute_effective_retry_seconds() 互补:
+    - 后者返回相对秒数（给 CircuitBreaker 用于退避计算）
+    - 本函数返回绝对 monotonic 时间戳（给 VendorTier 用于精确门控）
+
+    取所有可用时间信号中的最大值，并加 10% 安全余量。
+    """
+    candidates: list[float] = []
+    now = time.monotonic()
+
+    if info.retry_after_seconds is not None:
+        candidates.append(now + info.retry_after_seconds * 1.1)
+
+    if info.requests_reset_at is not None and info.requests_reset_at > now:
+        remaining = info.requests_reset_at - now
+        candidates.append(now + remaining * 1.1)
+
+    if info.tokens_reset_at is not None and info.tokens_reset_at > now:
+        remaining = info.tokens_reset_at - now
+        candidates.append(now + remaining * 1.1)
+
+    return max(candidates) if candidates else None
+
+
+def _get_header(headers: Any, name: str) -> str | None:
+    """统一获取 header 值（兼容 httpx.Headers 和 dict）."""
+    if headers is None:
+        return None
+    if hasattr(headers, "get"):
+        val = headers.get(name)
+        return val if val else None
+    if isinstance(headers, dict):
+        lower_name = name.lower()
+        for k, v in headers.items():
+            if k.lower() == lower_name:
+                return v
+    return None
+
+
+def _parse_retry_after(value: str) -> float | None:
+    """解析 Retry-After header (秒数或 HTTP date)."""
+    try:
+        return float(value)
+    except ValueError:
+        pass
+    try:
+        dt = parsedate_to_datetime(value)
+        return max(0, (dt - datetime.now(timezone.utc)).total_seconds())
+    except (ValueError, TypeError):
+        logger.warning("Cannot parse retry-after header: %s", value)
+        return None
+
+
+def _parse_reset_time(value: str) -> float | None:
+    """解析 ISO 8601 datetime 为 monotonic timestamp."""
+    try:
+        dt = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        remaining = (dt - datetime.now(timezone.utc)).total_seconds()
+        return time.monotonic() + max(0, remaining)
+    except (ValueError, TypeError):
+        logger.warning("Cannot parse reset time: %s", value)
+        return None

coding/proxy/routing/retry.py

@@ -0,0 +1,82 @@
+"""传输层重试策略 — 指数退避与 Full Jitter.
+
+与 Circuit Breaker 正交互：
+- Retry 处理瞬态网络抖动（秒级恢复）
+- Circuit Breaker 处理持续故障（分钟级恢复）
+- Retry 失败仅向 Circuit Breaker 贡献 1 次失败计数
+
+参考:
+[1] M. Nygard, "Release It!," Pragmatic Bookshelf, 2nd ed., 2018.
+[2] AWS Architecture Center, "Retry Pattern," 2022.
+"""
+
+from __future__ import annotations
+
+import logging
+import random
+from dataclasses import dataclass
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class RetryConfig:
+    """传输层重试配置（运行时）."""
+
+    max_retries: int = 2            # 最大重试次数（0 = 禁用）
+    initial_delay_ms: int = 500     # 初始退避延迟（毫秒）
+    max_delay_ms: int = 5000        # 最大退避延迟（毫秒）
+    backoff_multiplier: float = 2.0 # 退避倍数
+    jitter: bool = True             # 是否添加随机抖动
+
+    @property
+    def enabled(self) -> bool:
+        return self.max_retries > 0
+
+    @property
+    def max_attempts(self) -> int:
+        return self.max_retries + 1
+
+
+def is_retryable_error(exc: Exception) -> bool:
+    """判断异常是否值得重试.
+
+    可重试:
+    - httpx.TimeoutException（瞬态超时）
+    - httpx.ConnectError（网络连接失败）
+    - httpx.HTTPStatusError with 5xx（服务端瞬时错误）
+
+    不可重试:
+    - httpx.HTTPStatusError with 4xx（客户端错误）
+    - TokenAcquireError（认证层错误）
+    - 其他异常
+    """
+    if isinstance(exc, httpx.TimeoutException):
+        return True
+    if isinstance(exc, httpx.ConnectError):
+        return True
+    if isinstance(exc, httpx.HTTPStatusError):
+        return exc.response.status_code >= 500
+    return False
+
+
+def is_retryable_status(status_code: int) -> bool:
+    """判断 HTTP 状态码是否值得重试（5xx）."""
+    return status_code >= 500
+
+
+def calculate_delay(attempt: int, cfg: RetryConfig) -> float:
+    """计算第 N 次重试的延迟（毫秒），含指数退避和 Full Jitter.
+
+    Full Jitter 策略: delay = random(0, min(initial * backoff^attempt, max))
+    参考: AWS "Exponential Backoff And Jitter" (Marc Brooker, 2015)
+    """
+    delay = cfg.initial_delay_ms * (cfg.backoff_multiplier ** attempt)
+    delay = min(delay, cfg.max_delay_ms)
+
+    if cfg.jitter:
+        delay = random.uniform(0, delay)
+
+    return delay

coding/proxy/routing/router.py

@@ -0,0 +1,84 @@
+"""请求路由器 — N-tier 链式路由与自动故障转移（薄代理层）.
+
+核心路由逻辑已正交分解至：
+- :mod:`.executor`      — 统一的 tier 迭代门控引擎 (_RouteExecutor)
+- :mod:`.usage_recorder`  — 用量记录、定价日志与证据构建 (UsageRecorder)
+- :mod:`.session_manager`— 兼容性会话生命周期管理 (RouteSessionManager)
+
+本文件保留 ``RequestRouter`` 公开接口，内部委托给上述模块。
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, AsyncIterator
+
+if TYPE_CHECKING:
+    from ..pricing import PricingTable
+
+from .executor import _RouteExecutor
+from .session_manager import RouteSessionManager
+from .tier import VendorTier
+
+# 向后兼容别名
+BackendTier = VendorTier
+from .usage_recorder import UsageRecorder
+from ..compat.session_store import CompatSessionStore
+from ..logging.db import TokenLogger
+
+
+class RequestRouter:
+    """路由请求到合适的供应商层级，按优先级链式故障转移."""
+
+    def __init__(
+        self,
+        tiers: list[VendorTier],
+        token_logger: TokenLogger | None = None,
+        reauth_coordinator: Any | None = None,
+        compat_session_store: CompatSessionStore | None = None,
+    ) -> None:
+        if not tiers:
+            raise ValueError("至少需要一个供应商层级")
+        self._tiers = tiers
+
+        # 正交分解的子组件
+        self._recorder = UsageRecorder(token_logger=token_logger)
+        self._session_mgr = RouteSessionManager(compat_session_store)
+        self._executor = _RouteExecutor(
+            tiers=tiers,
+            usage_recorder=self._recorder,
+            session_manager=self._session_mgr,
+            reauth_coordinator=reauth_coordinator,
+        )
+
+    def set_pricing_table(self, table: PricingTable) -> None:
+        """注入 PricingTable 实例（由 lifespan 在启动阶段调用）."""
+        self._recorder.set_pricing_table(table)
+
+    @property
+    def tiers(self) -> list[VendorTier]:
+        return self._tiers
+
+    # ── 公开路由接口（委托给 _RouteExecutor）───────────────
+
+    async def route_stream(
+        self,
+        body: dict[str, Any],
+        headers: dict[str, str],
+    ) -> AsyncIterator[tuple[bytes, str]]:
+        """路由流式请求，按优先级尝试各层级."""
+        async for chunk, vendor_name in self._executor.execute_stream(body, headers):
+            yield chunk, vendor_name
+
+    async def route_message(
+        self,
+        body: dict[str, Any],
+        headers: dict[str, str],
+    ) -> Any:
+        """路由非流式请求，按优先级尝试各层级."""
+        return await self._executor.execute_message(body, headers)
+
+    # ── 生命周期 ───────────────────────────────────────────
+
+    async def close(self) -> None:
+        for tier in self._tiers:
+            await tier.vendor.close()

coding/proxy/routing/session_manager.py

@@ -0,0 +1,62 @@
+"""路由会话管理器 — 封装兼容性会话的创建、上下文应用与持久化."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..compat.canonical import (
+    CompatibilityStatus,
+    CompatibilityTrace,
+)
+from ..compat.session_store import CompatSessionRecord, CompatSessionStore
+from .tier import VendorTier
+
+
+class RouteSessionManager:
+    """管理单次路由请求的兼容性会话生命周期."""
+
+    def __init__(self, compat_session_store: CompatSessionStore | None = None) -> None:
+        self._store = compat_session_store
+
+    async def get_or_create_record(self, session_key: str, trace_id: str) -> CompatSessionRecord | None:
+        if self._store is None:
+            return None
+        record = await self._store.get(session_key)
+        if record is not None:
+            return record
+        return CompatSessionRecord(session_key=session_key, trace_id=trace_id)
+
+    def apply_compat_context(
+        self,
+        *,
+        tier: VendorTier,
+        canonical_request: Any,
+        decision: Any,
+        session_record: CompatSessionRecord | None,
+    ) -> None:
+        provider_protocol = {
+            "copilot": "openai_chat_completions",
+            "antigravity": "gemini_generate_content",
+            "zhipu": "anthropic_messages",
+            "anthropic": "anthropic_messages",
+        }.get(tier.name, "unknown")
+        compat_trace = CompatibilityTrace(
+            trace_id=canonical_request.trace_id, vendor=tier.name,
+            session_key=canonical_request.session_key, provider_protocol=provider_protocol,
+            compat_mode=decision.status.value, simulation_actions=list(decision.simulation_actions),
+            unsupported_semantics=list(decision.unsupported_semantics),
+            session_state_hits=1 if session_record else 0, request_adaptations=[],
+        )
+        tier.vendor.set_compat_context(trace=compat_trace, session_record=session_record)
+
+    async def persist_session(self, trace: CompatibilityTrace | None, session_record: CompatSessionRecord | None) -> None:
+        if self._store is None or trace is None or session_record is None:
+            return
+        provider_states = dict(session_record.provider_state)
+        provider_states[trace.vendor] = {
+            "compat_mode": trace.compat_mode, "simulation_actions": trace.simulation_actions,
+            "unsupported_semantics": trace.unsupported_semantics, "trace_id": trace.trace_id,
+        }
+        session_record.trace_id = trace.trace_id
+        session_record.provider_state = provider_states
+        await self._store.upsert(session_record)