ccproxy-api 0.1.6__py3-none-any.whl → 0.2.0__py3-none-any.whl

ccproxy/utils/version_checker.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import json
+import os
+import re
 from datetime import datetime
 from pathlib import Path
 from typing import Any
@@ -13,18 +15,26 @@ import structlog
 from packaging import version as pkg_version
 from pydantic import BaseModel
 
-from ccproxy._version import __version__
-from ccproxy.config.discovery import get_ccproxy_config_dir
+from ccproxy.config.utils import get_ccproxy_config_dir
+from ccproxy.core._version import __version__
 
 
 logger = structlog.get_logger(__name__)
 
 
+BRANCH_OVERRIDE_ENV_VAR = "CCPROXY_VERSION_BRANCH"
+GITHUB_API_BASE = "https://api.github.com/repos/CaddyGlow/ccproxy-api"
+
+
 class VersionCheckState(BaseModel):
     """State tracking for version checks."""
 
     last_check_at: datetime
     latest_version_found: str | None = None
+    latest_branch_name: str | None = None
+    latest_branch_commit: str | None = None
+    running_version: str | None = None
+    running_commit: str | None = None
 
 
 async def fetch_latest_github_version() -> str | None:
@@ -61,9 +71,23 @@ async def fetch_latest_github_version() -> str | None:
     except httpx.HTTPStatusError as e:
         logger.warning("github_version_http_error", status_code=e.response.status_code)
         return None
+    except httpx.RequestError as e:
+        logger.warning(
+            "github_version_fetch_http_error",
+            error=str(e),
+            error_type=type(e).__name__,
+        )
+        return None
+    except (json.JSONDecodeError, KeyError, TypeError) as e:
+        logger.warning(
+            "github_version_parse_error",
+            error=str(e),
+            error_type=type(e).__name__,
+        )
+        return None
     except Exception as e:
         logger.warning(
-            "github_version_fetch_failed",
+            "github_version_fetch_unexpected_error",
             error=str(e),
             error_type=type(e).__name__,
         )
@@ -80,6 +104,38 @@ def get_current_version() -> str:
     return __version__
 
 
+def extract_commit_from_version(version: str) -> str | None:
+    """Extract a git commit SHA from a setuptools-scm formatted version."""
+
+    match = re.search(r"\+g(?P<sha>[0-9a-f]{7,40})", version)
+    if match:
+        return match.group("sha")
+    return None
+
+
+def commit_refs_match(current: str | None, latest: str | None) -> bool:
+    """Return True when two commit references identify the same commit."""
+
+    if not current or not latest:
+        return current == latest
+
+    current_lower = current.lower()
+    latest_lower = latest.lower()
+
+    # Normalize shorter/longer pair for prefix comparison
+    if len(current_lower) <= len(latest_lower):
+        return latest_lower.startswith(current_lower)
+
+    return current_lower.startswith(latest_lower)
+
+
+def get_branch_override() -> str | None:
+    """Return branch override from environment if provided."""
+
+    env_branch = os.getenv(BRANCH_OVERRIDE_ENV_VAR, "").strip()
+    return env_branch or None
+
+
 def compare_versions(current: str, latest: str) -> bool:
     """
     Compare version strings to determine if an update is available.
@@ -94,10 +150,25 @@ def compare_versions(current: str, latest: str) -> bool:
     try:
         current_parsed = pkg_version.parse(current)
         latest_parsed = pkg_version.parse(latest)
+
+        # For dev versions, compare base version instead
+        if current_parsed.is_devrelease:
+            current_base = pkg_version.parse(current_parsed.base_version)
+            return latest_parsed > current_base
+
         return latest_parsed > current_parsed
+    except (ValueError, TypeError, AttributeError) as e:
+        logger.error(
+            "version_comparison_parse_error",
+            current=current,
+            latest=latest,
+            error=str(e),
+            error_type=type(e).__name__,
+        )
+        return False
     except Exception as e:
         logger.error(
-            "version_comparison_failed",
+            "version_comparison_unexpected_error",
             current=current,
             latest=latest,
             error=str(e),
@@ -106,6 +177,172 @@ def compare_versions(current: str, latest: str) -> bool:
         return False
 
 
+async def fetch_latest_branch_commit(branch: str) -> str | None:
+    """Fetch the latest commit SHA for a given branch from GitHub."""
+
+    url = f"{GITHUB_API_BASE}/branches/{branch}"
+    headers = {
+        "User-Agent": f"ccproxy-api/{__version__}",
+        "Accept": "application/vnd.github.v3+json",
+    }
+
+    try:
+        async with httpx.AsyncClient(timeout=15.0) as client:
+            response = await client.get(url, headers=headers)
+            response.raise_for_status()
+
+            data: dict[str, Any] = response.json()
+            commit_info = data.get("commit", {})
+            latest_sha = commit_info.get("sha")
+
+            if isinstance(latest_sha, str) and latest_sha:
+                logger.debug(
+                    "github_branch_commit_fetched",
+                    branch=branch,
+                    latest_sha=latest_sha,
+                )
+                return latest_sha
+
+            logger.warning(
+                "github_branch_commit_missing_sha",
+                branch=branch,
+            )
+            return None
+
+    except httpx.TimeoutException:
+        logger.warning("github_branch_commit_timeout", branch=branch)
+        return None
+    except httpx.HTTPStatusError as e:
+        logger.warning(
+            "github_branch_commit_http_error",
+            branch=branch,
+            status_code=e.response.status_code,
+        )
+        return None
+    except httpx.RequestError as e:
+        logger.warning(
+            "github_branch_commit_http_request_error",
+            branch=branch,
+            error=str(e),
+            error_type=type(e).__name__,
+        )
+        return None
+    except (json.JSONDecodeError, KeyError, TypeError) as e:
+        logger.warning(
+            "github_branch_commit_parse_error",
+            branch=branch,
+            error=str(e),
+            error_type=type(e).__name__,
+        )
+        return None
+    except Exception as e:
+        logger.warning(
+            "github_branch_commit_unexpected_error",
+            branch=branch,
+            error=str(e),
+            error_type=type(e).__name__,
+        )
+        return None
+
+
+async def fetch_branch_names_for_commit(commit: str) -> list[str]:
+    """Fetch branch names for which the given commit is the HEAD."""
+
+    url = f"{GITHUB_API_BASE}/commits/{commit}/branches-where-head"
+    headers = {
+        "User-Agent": f"ccproxy-api/{__version__}",
+        "Accept": "application/vnd.github.v3+json",
+    }
+
+    try:
+        async with httpx.AsyncClient(timeout=15.0) as client:
+            response = await client.get(url, headers=headers)
+            response.raise_for_status()
+
+            data = response.json()
+            if not isinstance(data, list):
+                logger.warning(
+                    "github_commit_branches_unexpected_payload",
+                    commit=commit,
+                    payload_type=type(data).__name__,
+                )
+                return []
+
+            branch_names: list[str] = []
+            for entry in data:
+                if not isinstance(entry, dict):
+                    continue
+                name = entry.get("name")
+                if isinstance(name, str) and name:
+                    branch_names.append(name)
+
+            logger.debug(
+                "github_commit_branches_fetched",
+                commit=commit,
+                branch_count=len(branch_names),
+            )
+            return branch_names
+
+    except httpx.TimeoutException:
+        logger.warning("github_commit_branches_timeout", commit=commit)
+        return []
+    except httpx.HTTPStatusError as e:
+        logger.warning(
+            "github_commit_branches_http_error",
+            commit=commit,
+            status_code=e.response.status_code,
+        )
+        return []
+    except httpx.RequestError as e:
+        logger.warning(
+            "github_commit_branches_http_request_error",
+            commit=commit,
+            error=str(e),
+            error_type=type(e).__name__,
+        )
+        return []
+    except (json.JSONDecodeError, ValueError, TypeError) as e:
+        logger.warning(
+            "github_commit_branches_parse_error",
+            commit=commit,
+            error=str(e),
+            error_type=type(e).__name__,
+        )
+        return []
+    except Exception as e:
+        logger.warning(
+            "github_commit_branches_unexpected_error",
+            commit=commit,
+            error=str(e),
+            error_type=type(e).__name__,
+        )
+        return []
+
+
+async def resolve_branch_for_commit(commit: str) -> str | None:
+    """Resolve the branch name associated with the provided commit hash."""
+
+    override = get_branch_override()
+    if override:
+        return override
+
+    if not commit:
+        return None
+
+    branch_candidates = await fetch_branch_names_for_commit(commit)
+    if not branch_candidates:
+        return None
+
+    # Prefer mainline branches if available
+    preferred_order = ("main", "master", "develop", "dev")
+    for preferred in preferred_order:
+        if preferred in branch_candidates:
+            return preferred
+
+    # Otherwise return the first branch reported by GitHub
+    return branch_candidates[0]
+
+
 async def load_check_state(path: Path) -> VersionCheckState | None:
     """
     Load version check state from file.
@@ -124,9 +361,25 @@ async def load_check_state(path: Path) -> VersionCheckState | None:
             content = await f.read()
             data = json.loads(content)
             return VersionCheckState(**data)
+    except (OSError, FileNotFoundError, PermissionError) as e:
+        logger.warning(
+            "version_check_state_load_file_error",
+            path=str(path),
+            error=str(e),
+            error_type=type(e).__name__,
+        )
+        return None
+    except (json.JSONDecodeError, ValueError, TypeError) as e:
+        logger.warning(
+            "version_check_state_load_parse_error",
+            path=str(path),
+            error=str(e),
+            error_type=type(e).__name__,
+        )
+        return None
     except Exception as e:
         logger.warning(
-            "version_check_state_load_failed",
+            "version_check_state_load_unexpected_error",
             path=str(path),
             error=str(e),
             error_type=type(e).__name__,
@@ -154,9 +407,23 @@ async def save_check_state(path: Path, state: VersionCheckState) -> None:
             await f.write(json.dumps(state_dict, indent=2))
 
         logger.debug("version_check_state_saved", path=str(path))
+    except (OSError, FileNotFoundError, PermissionError) as e:
+        logger.warning(
+            "version_check_state_save_file_error",
+            path=str(path),
+            error=str(e),
+            error_type=type(e).__name__,
+        )
+    except (TypeError, ValueError) as e:
+        logger.warning(
+            "version_check_state_save_serialize_error",
+            path=str(path),
+            error=str(e),
+            error_type=type(e).__name__,
+        )
     except Exception as e:
         logger.warning(
-            "version_check_state_save_failed",
+            "version_check_state_save_unexpected_error",
             path=str(path),
             error=str(e),
             error_type=type(e).__name__,
@@ -176,7 +443,13 @@ def get_version_check_state_path() -> Path:
 __all__ = [
     "VersionCheckState",
     "fetch_latest_github_version",
+    "fetch_latest_branch_commit",
+    "fetch_branch_names_for_commit",
+    "resolve_branch_for_commit",
     "get_current_version",
+    "extract_commit_from_version",
+    "commit_refs_match",
+    "get_branch_override",
     "compare_versions",
     "load_check_state",
     "save_check_state",

ccproxy_api-0.2.0.dist-info/METADATA

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: ccproxy-api
+Version: 0.2.0
+Summary: API server that provides an Anthropic and OpenAI compatible interface over Claude Code, allowing to use your Claude OAuth account or over the API.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: fastapi[standard]>=0.115.14
+Requires-Dist: httpx[http2]>=0.28.1
+Requires-Dist: packaging>=25.0
+Requires-Dist: pydantic-settings>=2.4.0
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: pyjwt>=2.10.1
+Requires-Dist: rich-toolkit>=0.14.8
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sortedcontainers>=2.4.0
+Requires-Dist: structlog>=25.4.0
+Requires-Dist: typer>=0.16.0
+Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: uvicorn>=0.34.0
+Provides-Extra: plugins-claude
+Requires-Dist: claude-agent-sdk>=0.1.0; extra == 'plugins-claude'
+Requires-Dist: qrcode>=8.2; extra == 'plugins-claude'
+Provides-Extra: plugins-codex
+Requires-Dist: pyjwt>=2.10.1; extra == 'plugins-codex'
+Requires-Dist: qrcode>=8.2; extra == 'plugins-codex'
+Provides-Extra: plugins-mcp
+Requires-Dist: fastapi-mcp>=0.3.7; extra == 'plugins-mcp'
+Provides-Extra: plugins-metrics
+Requires-Dist: prometheus-client>=0.22.1; extra == 'plugins-metrics'
+Provides-Extra: plugins-storage
+Requires-Dist: duckdb-engine>=0.17.0; extra == 'plugins-storage'
+Requires-Dist: duckdb<1.4.0,>=1.1.0; extra == 'plugins-storage'
+Requires-Dist: sqlalchemy>=2.0.0; extra == 'plugins-storage'
+Requires-Dist: sqlmodel>=0.0.24; extra == 'plugins-storage'
+Provides-Extra: plugins-tui
+Requires-Dist: aioconsole>=0.8.1; extra == 'plugins-tui'
+Requires-Dist: textual>=3.7.1; extra == 'plugins-tui'
+Description-Content-Type: text/markdown
+
+# CCProxy API Server
+
+CCProxy is a local, plugin-based reverse proxy that unifies access to
+multiple AI providers (e.g., Claude SDK/API and OpenAI Codex) behind a
+consistent API. It ships with bundled plugins for providers, logging,
+tracing, metrics, analytics, and more.
+
+## Supported Providers
+
+- Anthropic Claude API/SDK (OAuth2 flow or Claude CLI/SDK token files)
+- OpenAI Codex (ChatGPT backend Responses API using OAuth for paid/pro accounts)
+- GitHub Copilot (chat and completions for free, paid, or business accounts)
+
+Each provider adapter exposes the same surface area: OpenAI Chat
+Completions, OpenAI Responses, and Anthropic Messages. The proxy maintains a
+shared model-mapping layer so you can reuse the same `model` identifier
+across providers without rewriting client code.
+
+Authentication can reuse existing provider files (e.g., Claude CLI SDK
+tokens and the Codex CLI credential store), or you can run
+`ccproxy auth login <provider>` to complete the OAuth flow from the CLI;
+stored secrets are picked up automatically by the proxy.
+
+## Extensibility
+
+CCProxy's plugin system lets you add instrumentation and storage layers
+without patching the core server. Bundled plugins currently include:
+
+- [`access_log`](ccproxy/plugins/access_log/README.md): structured access
+  logging for client and provider traffic
+- [`analytics`](ccproxy/plugins/analytics/README.md): DuckDB-backed analytics
+  APIs for captured request logs
+- [`claude_api`](ccproxy/plugins/claude_api/README.md): Anthropic Claude HTTP
+  API adapter with health and metrics
+- [`claude_sdk`](ccproxy/plugins/claude_sdk/README.md): local Claude CLI/SDK
+  adapter with session pooling
+- [`codex`](ccproxy/plugins/codex/README.md): OpenAI Codex provider adapter
+  with OAuth support
+- [`command_replay`](ccproxy/plugins/command_replay/README.md): generates
+  `curl`/`xh` commands for captured requests
+- [`copilot`](ccproxy/plugins/copilot/README.md): GitHub Copilot provider
+  adapter with OAuth token management
+- [`credential_balancer`](ccproxy/plugins/credential_balancer/README.md):
+  rotates upstream credentials based on health
+- [`dashboard`](ccproxy/plugins/dashboard/README.md): serves the CCProxy
+  dashboard SPA and APIs
+- [`docker`](ccproxy/plugins/docker/README.md): runs providers inside Docker via
+  CLI extensions
+- [`duckdb_storage`](ccproxy/plugins/duckdb_storage/README.md): exposes
+  DuckDB-backed storage for logs and analytics
+- [`max_tokens`](ccproxy/plugins/max_tokens/README.md): normalizes
+  `max_tokens` fields to provider limits
+- [`metrics`](ccproxy/plugins/metrics/README.md): Prometheus-compatible metrics
+  with optional Pushgateway
+- [`oauth_claude`](ccproxy/plugins/oauth_claude/README.md): standalone OAuth
+  provider for Claude integrations
+- [`oauth_codex`](ccproxy/plugins/oauth_codex/README.md): standalone OAuth
+  provider for Codex integrations
+- [`permissions`](ccproxy/plugins/permissions/README.md): interactive approval
+  flow for privileged tool actions
+- [`pricing`](ccproxy/plugins/pricing/README.md): caches model pricing data for
+  cost-aware features
+- [`request_tracer`](ccproxy/plugins/request_tracer/README.md): detailed
+  request/response tracing for debugging
+
+Shared helpers such as
+[`claude_shared`](ccproxy/plugins/claude_shared/README.md) provide metadata
+consumed by the Claude plugins. Each plugin directory contains its own README
+with configuration examples.
+
+## Quick Links
+
+- Docs site entry: `docs/index.md`
+- Getting started: `docs/getting-started/quickstart.md`
+- Configuration reference: `docs/getting-started/configuration.md`
+- Examples: `docs/examples.md`
+- Migration (0.2): `docs/migration/0.2-plugin-first.md`
+
+## Plugin Config Quickstart
+
+The plugin system is enabled by default (`enable_plugins = true`), and all
+discovered plugins load automatically when no additional filters are set. Use
+these knobs to adjust what runs:
+
+- `enabled_plugins`: optional allow list; when set, only the listed plugins run.
+- `disabled_plugins`: optional block list applied when `enabled_plugins` is not
+  set.
+- `plugins.<name>.enabled`: per-plugin flag (defaults to `true`) that you can
+  override in TOML or environment variables. Any plugin set to `false` is added
+  to the deny list alongside `disabled_plugins` during startup.
+
+During startup we merge `disabled_plugins` and any `plugins.<name>.enabled = false`
+entries into a single deny list. At runtime the loader checks the allow list
+first and then confirms the plugin is not deny listed. Configure plugins under
+`plugins.<name>` in TOML or via nested environment variables.
+
+Use `ccproxy plugins list` to inspect discovered plugins and
+`ccproxy plugins settings <name>` to review configuration fields.
+
+### TOML example (`.ccproxy.toml`)
+
+```toml
+enable_plugins = true
+# enabled_plugins = ["metrics", "analytics"]  # Optional allow list
+disabled_plugins = ["duckdb_storage"]          # Optional block list
+
+[plugins.access_log]
+client_enabled = true
+client_format = "structured"
+client_log_file = "/tmp/ccproxy/access.log"
+
+[plugins.request_tracer]
+json_logs_enabled = true
+raw_http_enabled = true
+log_dir = "/tmp/ccproxy/traces"
+
+[plugins.duckdb_storage]
+enabled = false
+
+[plugins.analytics]
+enabled = true
+
+# Metrics plugin
+[plugins.metrics]
+enabled = true
+# pushgateway_enabled = true
+# pushgateway_url = "http://localhost:9091"
+# pushgateway_job = "ccproxy"
+# pushgateway_push_interval = 60
+```
+
+### Environment variables (nested with `__`)
+
+```bash
+export DISABLED_PLUGINS="duckdb_storage"      # Optional block list
+export PLUGINS__ACCESS_LOG__ENABLED=true
+export PLUGINS__ACCESS_LOG__CLIENT_ENABLED=true
+export PLUGINS__ACCESS_LOG__CLIENT_FORMAT=structured
+export PLUGINS__ACCESS_LOG__CLIENT_LOG_FILE=/tmp/ccproxy/access.log
+
+export PLUGINS__REQUEST_TRACER__ENABLED=true
+export PLUGINS__REQUEST_TRACER__JSON_LOGS_ENABLED=true
+export PLUGINS__REQUEST_TRACER__RAW_HTTP_ENABLED=true
+export PLUGINS__REQUEST_TRACER__LOG_DIR=/tmp/ccproxy/traces
+
+export PLUGINS__DUCKDB_STORAGE__ENABLED=true
+export PLUGINS__ANALYTICS__ENABLED=true
+export PLUGINS__METRICS__ENABLED=true
+# export PLUGINS__METRICS__PUSHGATEWAY_ENABLED=true
+# export PLUGINS__METRICS__PUSHGATEWAY_URL=http://localhost:9091
+```
+
+## Running
+
+To install the latest stable release without cloning the repository, use `uvx`
+to grab the published wheel and launch the CLI:
+
+```bash
+uvx --with "ccproxy-api[all]" ccproxy serve --port 8000
+```
+
+If you prefer `pipx`, install the package (optionally with extras) and use the
+local shim:
+
+```bash
+pipx install "ccproxy-api[all]"
+ccproxy serve  # default on localhost:8000
+```
+
+## License
+
+See `LICENSE`.