coding-proxy 0.1.0__py3-none-any.whl

coding/proxy/routing/__init__.py

@@ -0,0 +1,47 @@
+"""路由模块."""
+
+from .circuit_breaker import CircuitBreaker, CircuitState
+from .error_classifier import (
+    build_request_capabilities,
+    extract_error_payload_from_http_status,
+    is_semantic_rejection,
+)
+from .executor import _RouteExecutor
+from .model_mapper import ModelMapper
+from .quota_guard import QuotaGuard, QuotaState
+from .rate_limit import RateLimitInfo
+from .rate_limit import (
+    compute_effective_retry_seconds,
+    compute_rate_limit_deadline,
+    parse_rate_limit_headers,
+)
+from .retry import RetryConfig, calculate_delay, is_retryable_error
+from .router import RequestRouter
+from .session_manager import RouteSessionManager
+from .tier import BackendTier
+from .usage_parser import (
+    build_usage_evidence_records,
+    has_missing_input_usage_signals,
+    parse_usage_from_chunk,
+)
+from .usage_recorder import UsageRecorder
+
+__all__ = [
+    # Core routing
+    "CircuitBreaker", "CircuitState",
+    "ModelMapper", "RequestRouter", "BackendTier",
+    # Decomposed components (internal use)
+    "_RouteExecutor", "UsageRecorder", "RouteSessionManager",
+    # Resiliency
+    "QuotaGuard", "QuotaState", "RateLimitInfo",
+    "RetryConfig",
+    "parse_rate_limit_headers", "compute_effective_retry_seconds",
+    "compute_rate_limit_deadline",
+    "is_retryable_error", "calculate_delay",
+    # Error classification
+    "build_request_capabilities", "is_semantic_rejection",
+    "extract_error_payload_from_http_status",
+    # Usage parsing
+    "build_usage_evidence_records", "has_missing_input_usage_signals",
+    "parse_usage_from_chunk",
+]

coding/proxy/routing/circuit_breaker.py

@@ -0,0 +1,152 @@
+"""熔断器 (Circuit Breaker) — 状态机实现."""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from enum import Enum
+
+logger = logging.getLogger(__name__)
+
+
+class CircuitState(Enum):
+    CLOSED = "closed"           # 正常：使用主后端
+    OPEN = "open"               # 故障：使用备选后端
+    HALF_OPEN = "half_open"     # 试探：测试主后端是否恢复
+
+
+class CircuitBreaker:
+    """线程安全的熔断器.
+
+    状态转换:
+    - CLOSED → OPEN: 连续 failure_threshold 次失败
+    - OPEN → HALF_OPEN: recovery_timeout 后
+    - HALF_OPEN → CLOSED: 连续 success_threshold 次成功
+    - HALF_OPEN → OPEN: 任意一次失败（指数退避）
+    """
+
+    def __init__(
+        self,
+        failure_threshold: int = 3,
+        recovery_timeout_seconds: int = 300,
+        success_threshold: int = 2,
+        max_recovery_seconds: int = 3600,
+    ) -> None:
+        self._failure_threshold = failure_threshold
+        self._recovery_timeout = recovery_timeout_seconds
+        self._success_threshold = success_threshold
+        self._max_recovery = max_recovery_seconds
+
+        self._state = CircuitState.CLOSED
+        self._failure_count = 0
+        self._success_count = 0
+        self._last_failure_time: float | None = None
+        self._current_recovery = recovery_timeout_seconds
+        self._lock = threading.Lock()
+
+    @property
+    def state(self) -> CircuitState:
+        with self._lock:
+            self._check_recovery()
+            return self._state
+
+    def can_execute(self) -> bool:
+        """判断是否可以在主后端上执行请求."""
+        with self._lock:
+            self._check_recovery()
+            return self._state in (CircuitState.CLOSED, CircuitState.HALF_OPEN)
+
+    def record_success(self) -> None:
+        """记录一次成功调用."""
+        with self._lock:
+            self._failure_count = 0
+            if self._state == CircuitState.HALF_OPEN:
+                self._success_count += 1
+                if self._success_count >= self._success_threshold:
+                    self._transition_to(CircuitState.CLOSED)
+                    logger.info("Circuit breaker: HALF_OPEN → CLOSED (recovered)")
+            elif self._state == CircuitState.CLOSED:
+                # 正常状态下成功，无需操作
+                pass
+
+    def record_failure(self, retry_after_seconds: float | None = None) -> None:
+        """记录一次失败调用.
+
+        Args:
+            retry_after_seconds: 从响应头解析出的建议恢复时间（秒）。
+                若提供且大于当前指数退避值，将覆盖以避免过早探测。
+        """
+        with self._lock:
+            self._failure_count += 1
+            self._success_count = 0
+            self._last_failure_time = time.monotonic()
+
+            if self._state == CircuitState.HALF_OPEN:
+                self._transition_to(CircuitState.OPEN)
+                self._backoff_recovery(hint_seconds=retry_after_seconds)
+                logger.warning(
+                    "Circuit breaker: HALF_OPEN → OPEN (recovery failed, next retry in %ds)",
+                    self._current_recovery,
+                )
+            elif self._state == CircuitState.CLOSED:
+                if self._failure_count >= self._failure_threshold:
+                    self._transition_to(CircuitState.OPEN)
+                    if retry_after_seconds and retry_after_seconds > self._current_recovery:
+                        self._current_recovery = min(
+                            retry_after_seconds, self._max_recovery,
+                        )
+                    logger.warning(
+                        "Circuit breaker: CLOSED → OPEN (%d consecutive failures, next retry in %ds)",
+                        self._failure_count,
+                        self._current_recovery,
+                    )
+
+    def reset(self) -> None:
+        """手动重置熔断器为 CLOSED 状态."""
+        with self._lock:
+            self._transition_to(CircuitState.CLOSED)
+            self._current_recovery = self._recovery_timeout
+            logger.info("Circuit breaker: manually reset to CLOSED")
+
+    def get_info(self) -> dict:
+        """获取熔断器状态信息."""
+        with self._lock:
+            self._check_recovery()
+            return {
+                "state": self._state.value,
+                "failure_count": self._failure_count,
+                "success_count": self._success_count,
+                "current_recovery_seconds": self._current_recovery,
+                "last_failure_time": self._last_failure_time,
+            }
+
+    def _check_recovery(self) -> None:
+        """检查是否应从 OPEN 转为 HALF_OPEN."""
+        if self._state != CircuitState.OPEN:
+            return
+        if self._last_failure_time is None:
+            return
+        elapsed = time.monotonic() - self._last_failure_time
+        if elapsed >= self._current_recovery:
+            self._transition_to(CircuitState.HALF_OPEN)
+            logger.info("Circuit breaker: OPEN → HALF_OPEN (recovery timeout)")
+
+    def _transition_to(self, new_state: CircuitState) -> None:
+        old = self._state
+        self._state = new_state
+        if new_state == CircuitState.CLOSED:
+            self._failure_count = 0
+            self._success_count = 0
+            self._current_recovery = self._recovery_timeout
+        elif new_state == CircuitState.HALF_OPEN:
+            self._success_count = 0
+
+    def _backoff_recovery(self, hint_seconds: float | None = None) -> None:
+        """指数退避恢复超时，支持 server-hinted 覆盖."""
+        exponential = min(self._current_recovery * 2, self._max_recovery)
+        if hint_seconds is not None and hint_seconds > exponential:
+            # Server 告知的恢复时间优先于指数退避
+            self._current_recovery = min(hint_seconds, self._max_recovery)
+        else:
+            self._current_recovery = exponential

coding/proxy/routing/error_classifier.py

@@ -0,0 +1,67 @@
+"""HTTP 错误分类与请求能力画像提取."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+
+from ..vendors.base import RequestCapabilities
+
+
+def extract_error_payload_from_http_status(exc: httpx.HTTPStatusError) -> dict[str, Any] | None:
+    response = exc.response
+    if response is None or not response.content:
+        return None
+    try:
+        payload = response.json()
+    except (json.JSONDecodeError, UnicodeDecodeError, TypeError, ValueError):
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def is_semantic_rejection(
+    *,
+    status_code: int,
+    error_type: str | None = None,
+    error_message: str | None = None,
+) -> bool:
+    if status_code != 400:
+        return False
+    normalized_type = (error_type or "").strip().lower()
+    if normalized_type == "invalid_request_error":
+        return True
+    normalized_message = (error_message or "").lower()
+    return any(
+        marker in normalized_message
+        for marker in (
+            "invalid_request_error",
+            "should match pattern",
+            "validation",
+            "tool_use_id",
+            "server_tool_use",
+        )
+    )
+
+
+def build_request_capabilities(body: dict[str, Any]) -> RequestCapabilities:
+    """从请求体提取能力画像."""
+    has_images = False
+    for msg in body.get("messages", []):
+        content = msg.get("content")
+        if not isinstance(content, list):
+            continue
+        if any(
+            isinstance(block, dict) and block.get("type") == "image"
+            for block in content
+        ):
+            has_images = True
+            break
+
+    return RequestCapabilities(
+        has_tools=bool(body.get("tools") or body.get("tool_choice")),
+        has_thinking=bool(body.get("thinking") or body.get("extended_thinking")),
+        has_images=has_images,
+        has_metadata=bool(body.get("metadata")),
+    )