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

ccproxy/plugins/copilot/routes.py

@@ -0,0 +1,294 @@
+"CopilotEmbeddingRequestAPI routes for GitHub Copilot plugin."
+
+from typing import TYPE_CHECKING, Annotated, Any, Literal, cast
+
+from fastapi import APIRouter, Body, Depends, Request
+from fastapi.responses import JSONResponse, Response, StreamingResponse
+
+from ccproxy.api.decorators import with_format_chain
+from ccproxy.api.dependencies import (
+    get_plugin_adapter,
+    get_provider_config_dependency,
+)
+from ccproxy.core.constants import (
+    FORMAT_ANTHROPIC_MESSAGES,
+    FORMAT_OPENAI_CHAT,
+    FORMAT_OPENAI_RESPONSES,
+    UPSTREAM_ENDPOINT_COPILOT_INTERNAL_TOKEN,
+    UPSTREAM_ENDPOINT_COPILOT_INTERNAL_USER,
+    UPSTREAM_ENDPOINT_OPENAI_CHAT_COMPLETIONS,
+    UPSTREAM_ENDPOINT_OPENAI_EMBEDDINGS,
+    UPSTREAM_ENDPOINT_OPENAI_MODELS,
+)
+from ccproxy.core.logging import get_plugin_logger
+from ccproxy.llms.models import anthropic as anthropic_models
+from ccproxy.llms.models import openai as openai_models
+from ccproxy.streaming import DeferredStreaming
+
+from .config import CopilotProviderConfig
+from .models import (
+    CopilotHealthResponse,
+    CopilotTokenStatus,
+    CopilotUserInternalResponse,
+)
+
+
+if TYPE_CHECKING:
+    pass
+
+logger = get_plugin_logger()
+
+CopilotAdapterDep = Annotated[Any, Depends(get_plugin_adapter("copilot"))]
+CopilotConfigDep = Annotated[
+    CopilotProviderConfig,
+    Depends(get_provider_config_dependency("copilot", CopilotProviderConfig)),
+]
+
+APIResponse = Response | StreamingResponse | DeferredStreaming
+OpenAIResponse = APIResponse | openai_models.ErrorResponse
+
+# V1 API Router - OpenAI/Anthropic compatible endpoints
+router_v1 = APIRouter()
+
+# GitHub Copilot specific router - usage, token, health endpoints
+router_github = APIRouter()
+
+
+def _cast_result(result: object) -> OpenAIResponse:
+    return cast(APIResponse, result)
+
+
+async def _handle_adapter_request(
+    request: Request,
+    adapter: Any,
+) -> OpenAIResponse:
+    result = await adapter.handle_request(request)
+    return _cast_result(result)
+
+
+def _get_request_body(request: Request) -> Any:
+    """Hidden dependency to get raw body."""
+
+    async def _inner() -> Any:
+        return await request.json()
+
+    return _inner
+
+
+@router_v1.post(
+    "/chat/completions",
+    response_model=openai_models.ChatCompletionResponse,
+)
+async def create_openai_chat_completion(
+    request: Request,
+    adapter: CopilotAdapterDep,
+    _: openai_models.ChatCompletionRequest = Body(..., include_in_schema=True),
+    body: dict[str, Any] = Depends(_get_request_body, use_cache=False),
+) -> openai_models.ChatCompletionResponse | OpenAIResponse:
+    """Create a chat completion using Copilot with OpenAI-compatible format."""
+    request.state.context.metadata["endpoint"] = (
+        UPSTREAM_ENDPOINT_OPENAI_CHAT_COMPLETIONS
+    )
+    return await _handle_adapter_request(request, adapter)
+
+
+@router_v1.post(
+    "/messages",
+    response_model=anthropic_models.MessageResponse,
+)
+@with_format_chain(
+    [FORMAT_ANTHROPIC_MESSAGES, FORMAT_OPENAI_CHAT],
+    endpoint=UPSTREAM_ENDPOINT_OPENAI_CHAT_COMPLETIONS,
+)
+async def create_anthropic_message(
+    request: Request,
+    _: anthropic_models.CreateMessageRequest,
+    adapter: CopilotAdapterDep,
+) -> anthropic_models.MessageResponse | OpenAIResponse:
+    return await _handle_adapter_request(request, adapter)
+
+
+@with_format_chain(
+    [FORMAT_OPENAI_RESPONSES, FORMAT_OPENAI_CHAT],
+    endpoint=UPSTREAM_ENDPOINT_OPENAI_CHAT_COMPLETIONS,
+)
+@router_v1.post(
+    "/responses",
+    response_model=anthropic_models.MessageResponse,
+)
+async def create_responses_message(
+    request: Request,
+    _: openai_models.ResponseRequest,
+    adapter: CopilotAdapterDep,
+) -> anthropic_models.MessageResponse | OpenAIResponse:
+    """Create a message using Response API with OpenAI provider."""
+    # Ensure format chain is present in context even if decorator injection is bypassed
+    request.state.context.metadata["endpoint"] = (
+        UPSTREAM_ENDPOINT_OPENAI_CHAT_COMPLETIONS
+    )
+    # Explicitly set format_chain so BaseHTTPAdapter applies request conversion
+    try:
+        prev_chain = getattr(request.state.context, "format_chain", None)
+        new_chain = [FORMAT_OPENAI_RESPONSES, FORMAT_OPENAI_CHAT]
+        request.state.context.format_chain = new_chain
+        logger.debug(
+            "copilot_responses_route_enter",
+            prev_chain=prev_chain,
+            applied_chain=new_chain,
+            category="format",
+        )
+        # Peek at incoming body keys for debugging
+        try:
+            body_json = await request.json()
+            stream_flag = (
+                body_json.get("stream") if isinstance(body_json, dict) else None
+            )
+            logger.debug(
+                "copilot_responses_request_body_inspect",
+                keys=list(body_json.keys()) if isinstance(body_json, dict) else None,
+                stream=stream_flag,
+                category="format",
+            )
+        except Exception as exc:  # best-effort logging only
+            logger.debug("copilot_responses_request_body_parse_failed", error=str(exc))
+    except Exception as exc:  # defensive
+        logger.debug("copilot_responses_set_chain_failed", error=str(exc))
+    return await _handle_adapter_request(request, adapter)
+
+
+@router_v1.post(
+    "/embeddings",
+    response_model=openai_models.EmbeddingResponse,
+)
+async def create_embeddings(
+    request: Request, _: openai_models.EmbeddingRequest, adapter: CopilotAdapterDep
+) -> openai_models.EmbeddingResponse | OpenAIResponse:
+    request.state.context.metadata["endpoint"] = UPSTREAM_ENDPOINT_OPENAI_EMBEDDINGS
+    return await _handle_adapter_request(request, adapter)
+
+
+@router_v1.get("/models", response_model=openai_models.ModelList)
+async def list_models_v1(
+    request: Request,
+    adapter: CopilotAdapterDep,
+    config: CopilotConfigDep,
+) -> OpenAIResponse:
+    """List available Copilot models."""
+    # if config.models_endpoint:
+    #     models = [card.model_dump(mode="json") for card in config.models_endpoint]
+    #     return JSONResponse(content={"object": "list", "data": models})
+
+    # Forward request to upstream Copilot API when no override configured
+    request.state.context.metadata["endpoint"] = UPSTREAM_ENDPOINT_OPENAI_MODELS
+    return await _handle_adapter_request(request, adapter)
+
+
+@router_github.get("/usage", response_model=CopilotUserInternalResponse)
+async def get_usage_stats(adapter: CopilotAdapterDep, request: Request) -> Response:
+    """Get Copilot usage statistics."""
+    request.state.context.metadata["endpoint"] = UPSTREAM_ENDPOINT_COPILOT_INTERNAL_USER
+    request.state.context.metadata["method"] = "get"
+    result = await adapter.handle_request_gh_api(request)
+    return cast(Response, result)
+
+
+@router_github.get("/token", response_model=CopilotTokenStatus)
+async def get_token_status(adapter: CopilotAdapterDep, request: Request) -> Response:
+    """Get Copilot usage statistics."""
+    request.state.context.metadata["endpoint"] = (
+        UPSTREAM_ENDPOINT_COPILOT_INTERNAL_TOKEN
+    )
+    request.state.context.metadata["method"] = "get"
+    result = await adapter.handle_request_gh_api(request)
+    return cast(Response, result)
+
+
+@router_github.get("/health", response_model=CopilotHealthResponse)
+async def health_check(adapter: CopilotAdapterDep) -> JSONResponse:
+    """Check Copilot plugin health."""
+    try:
+        logger.debug("performing_health_check")
+
+        # Check components
+        details: dict[str, Any] = {}
+
+        # Check OAuth provider
+        oauth_healthy = True
+        if adapter.oauth_provider:
+            try:
+                oauth_healthy = await adapter.oauth_provider.is_authenticated()
+                details["oauth"] = {
+                    "authenticated": oauth_healthy,
+                    "provider": "github_copilot",
+                }
+            except Exception as e:
+                oauth_healthy = False
+                details["oauth"] = {
+                    "authenticated": False,
+                    "error": str(e),
+                }
+        else:
+            oauth_healthy = False
+            details["oauth"] = {"error": "OAuth provider not initialized"}
+
+        # Check detection service
+        detection_healthy = True
+        if adapter.detection_service:
+            try:
+                cli_info = adapter.detection_service.get_cli_health_info()
+                details["github_cli"] = {
+                    "available": cli_info.available,
+                    "version": cli_info.version,
+                    "authenticated": cli_info.authenticated,
+                    "username": cli_info.username,
+                    "error": cli_info.error,
+                }
+                detection_healthy = cli_info.available and cli_info.authenticated
+            except Exception as e:
+                detection_healthy = False
+                details["github_cli"] = {"error": str(e)}
+        else:
+            details["github_cli"] = {"error": "Detection service not initialized"}
+
+        # Overall health
+        overall_status: Literal["healthy", "unhealthy"] = (
+            "healthy" if oauth_healthy and detection_healthy else "unhealthy"
+        )
+
+        health_response = CopilotHealthResponse(
+            status=overall_status,
+            provider="copilot",
+            details=details,
+        )
+
+        status_code = 200 if overall_status == "healthy" else 503
+
+        logger.info(
+            "health_check_completed",
+            status=overall_status,
+            oauth_healthy=oauth_healthy,
+            detection_healthy=detection_healthy,
+        )
+
+        return JSONResponse(
+            content=health_response.model_dump(),
+            status_code=status_code,
+        )
+
+    except Exception as e:
+        logger.error(
+            "health_check_failed",
+            error=str(e),
+            exc_info=e,
+        )
+
+        health_response = CopilotHealthResponse(
+            status="unhealthy",
+            provider="copilot",
+            details={"error": str(e)},
+        )
+
+        return JSONResponse(
+            content=health_response.model_dump(),
+            status_code=503,
+        )

ccproxy/plugins/credential_balancer/README.md

@@ -0,0 +1,124 @@
+# Credential Balancer (system plugin)
+
+The credential balancer manages pools of upstream credentials (API keys, OAuth tokens, etc.) for a given provider and rotates between them based on health. It integrates as a system plugin and exposes a registry key (auth manager) that provider plugins can use to fetch a currently healthy credential at request time.
+
+- Balances across multiple credential files per provider.
+- Detects failures from HTTP responses and temporarily disables bad credentials with cooldowns.
+- Supports manual refresh, proportional selection, sticky-on-success, and backoff.
+- Exposes a named auth manager registry key (defaults to `<provider>_credential_balancer`).
+
+## When to use
+
+Use the balancer when you have multiple tokens for the same provider and want resilient failover and automatic rotation without changing application code or secrets storage.
+
+## Quick Start (minimal)
+
+The following minimal example configures CCproxy with the Codex provider to use a pool of Codex OAuth tokens.
+
+```toml
+[plugins]
+# Enable the credential balancer system plugin
+enabled_plugins = [
+   "codex",
+   "oauth_codex",
+   "credential_balancer"
+]
+
+# Point the codex provider at the balancer-managed auth manager
+[plugins.codex]
+auth_manager = "codex_credential_balancer"
+
+[[plugins.credential_balancer.providers]]
+provider = "codex"
+strategy = "round_robin" # or "failover"
+
+manager_class = "ccproxy.plugins.oauth_codex.manager.CodexTokenManager"
+storage_class = "ccproxy.plugins.oauth_codex.storage.CodexTokenStorage"
+
+credentials = [
+  { path = "~/.config/ccproxy/codex_plus.json" },
+  { path = "~/.config/ccproxy/codex_pro.json" },
+]
+
+```
+## Full Configuration Reference
+
+Enable the system plugin and define one or more provider pools. Each pool declares where to read credentials from and optional tuning parameters. See `config.example.toml` for full, commented examples.
+
+```toml
+[[plugins.credential_balancer.providers]]
+# Provider identifier, e.g. "claude-api", "openai", "codex".
+provider = "claude-api"
+strategy = "round_robin"             # or "failover"
+max_failures_before_disable = 2
+cooldown_seconds = 120.0
+failure_status_codes = [401, 403]
+
+# Pool defaults (example: Claude OAuth manager/storage)
+manager_class = "ccproxy.plugins.oauth_claude.manager.ClaudeApiTokenManager"
+storage_class = "ccproxy.plugins.oauth_claude.storage.ClaudeOAuthStorage"
+
+credentials = [
+  { type = "manager", file = "~/.config/ccproxy/claude_primary.json", label = "primary" },
+  { type = "manager", file = "~/.config/ccproxy/claude_backup.json", label = "backup" },
+]
+```
+
+After defining a pool, point the corresponding provider plugin at the balancer by overriding its auth manager to the registry key:
+
+```toml
+[plugins.claude-api]
+# Use the balancer-provided registry entry instead of a static key file
+auth_manager = "claude-api_credential_balancer"
+```
+
+If you set a custom `manager_name` in the balancer configuration, use that value for `auth_manager` instead.
+
+## How it works
+
+- Startup: for each entry in `[[plugins.credential_balancer.providers]]`, the plugin constructs a Manager that loads credentials from the declared files and registers it under `manager_name`.
+- Request path: provider adapters ask the registry for a credential via the `auth_manager` key; the balancer selects a currently healthy token.
+- Feedback loop: the `credential_balancer` hook observes provider HTTP responses and records failures/successes to update health, handle cooldowns, and trigger failover when necessary.
+
+## TODO
+
+- Extract cooldown period from provider error responses and apply dynamic per-credential cooldowns.
+  - Collect and parse HTTP error payloads/headers in the hook (e.g., Retry-After or equivalent fields).
+  - Pass an optional cooldown override with the failure event to the manager.
+  - Ensure logs include the derived cooldown value for observability.
+
+## Logs and observability
+
+The plugin emits structured events to aid troubleshooting, including (non-exhaustive):
+- `credential_balancer_manager_registered`
+- `credential_balancer_token_selected`
+- `credential_balancer_failure_detected`
+- `credential_balancer_failover`
+- `credential_balancer_manual_refresh_succeeded`
+
+During development, server logs stream to `/tmp/ccproxy/ccproxy.log` when running `ccproxy serve`.
+
+## Files and APIs
+
+- Runtime code: `ccproxy/plugins/credential_balancer/`
+  - `plugin.py`: plugin factory and lifecycle wiring
+  - `manager.py`: rotation, health, selection, and feedback processing
+  - `hook.py`: HTTP lifecycle hook that feeds response outcomes back to the manager
+  - `config.py`: Pydantic models for pool configuration and defaults
+- Enable via `pyproject.toml` entry point `credential_balancer` (already wired).
+
+## Testing
+
+- Unit tests: `tests/plugins/credential_balancer/unit/`
+- Run fast tests: `./Taskfile test-unit`
+- Full suite: `./Taskfile test`
+
+Follow the project’s testing markers and async patterns as described in `TESTING.md`.
+
+## Further reading
+
+- Authentication overview: `docs/user-guide/authentication.md`
+- Example configuration: `config.example.toml`
+
+Commands
+- `uv run ccproxy serve` (logs at `/tmp/ccproxy/ccproxy.log`)

ccproxy/plugins/credential_balancer/__init__.py

@@ -0,0 +1,6 @@
+"""Credential balancer plugin."""
+
+from .plugin import factory
+
+
+__all__ = ["factory"]

ccproxy/plugins/credential_balancer/config.py

@@ -0,0 +1,270 @@
+"""Configuration models for the credential balancer plugin."""
+
+from __future__ import annotations
+
+import os
+from enum import Enum
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, ValidationInfo, field_validator, model_validator
+
+
+class RotationStrategy(str, Enum):
+    """Supported credential selection strategies."""
+
+    ROUND_ROBIN = "round_robin"
+    FAILOVER = "failover"
+
+
+class CredentialSource(BaseModel):
+    """Base model for credential sources."""
+
+    type: Literal["manager"] = Field(
+        default="manager", description="Type of credential source"
+    )
+    label: str | None = Field(
+        default=None,
+        description="Optional friendly name used for logging and metrics",
+    )
+
+    @property
+    def resolved_label(self) -> str:
+        """Return a non-empty label for this credential source."""
+        return self.label or "unlabeled"
+
+
+class CredentialManager(CredentialSource):
+    """Configuration for a manager-based credential source with provider-specific logic.
+
+    Specify either manager_key (registry lookup) or manager_class (direct import).
+
+    The config dict supports additional options:
+
+    **Storage options:**
+    - `enable_backups` (bool): Create timestamped backups before overwriting credentials (default: True)
+
+    **Manager options:**
+    - `credentials_ttl` (float): Seconds to cache credentials before rechecking storage (default: 30.0)
+    - `refresh_grace_seconds` (float): Seconds before expiry to trigger proactive token refresh (default: 120.0)
+
+    Example:
+        ```toml
+        { type = "manager",
+          file = "~/.config/ccproxy/codex_pro.json",
+          config = {
+            enable_backups = true,
+            credentials_ttl = 60.0,
+            refresh_grace_seconds = 300.0
+          }
+        }
+        ```
+    """
+
+    type: Literal["manager"] = "manager"
+    file: Path | None = Field(
+        default=None,
+        description="Path to custom credential file (overrides default storage location)",
+    )
+    manager_key: str | None = Field(
+        default=None,
+        description="Auth manager registry key (e.g., 'codex', 'claude-api'). Mutually exclusive with manager_class.",
+    )
+    manager_class: str | None = Field(
+        default=None,
+        description="Fully qualified manager class name (e.g., 'ccproxy.plugins.oauth_codex.manager.CodexTokenManager'). Mutually exclusive with manager_key.",
+    )
+    storage_class: str | None = Field(
+        default=None,
+        description="Fully qualified storage class name (e.g., 'ccproxy.plugins.oauth_codex.storage.CodexTokenStorage'). Required when using manager_class with custom file.",
+    )
+    config: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional manager and storage configuration options (see class docstring for supported keys)",
+    )
+    label: str | None = Field(
+        default=None,
+        description="Optional friendly name used for logging and metrics",
+    )
+
+    @field_validator("file", mode="before")
+    @classmethod
+    def _expand_file_path(cls, value: Path | str | None) -> Path | None:
+        """Expand environment variables and user home directory in file path."""
+        if value is None:
+            return None
+        raw_value = str(value)
+        expanded = os.path.expandvars(raw_value)
+        return Path(expanded).expanduser()
+
+    @model_validator(mode="after")
+    def _validate_manager_specification(self) -> CredentialManager:
+        # Allow both to be None - they may be inherited from pool-level defaults
+        # But if both are specified, that's an error
+        if self.manager_key and self.manager_class:
+            raise ValueError(
+                "manager_key and manager_class are mutually exclusive, specify only one"
+            )
+        # If using manager_class with custom file, storage_class is required
+        # (unless it will be inherited from pool defaults)
+        if self.manager_class and self.file and not self.storage_class:
+            raise ValueError(
+                "storage_class is required when using manager_class with custom file path"
+            )
+        return self
+
+    @model_validator(mode="after")
+    def _populate_default_label(self) -> CredentialManager:
+        if self.label is None:
+            if self.manager_key:
+                self.label = self.manager_key
+            elif self.manager_class:
+                # Extract class name from fully qualified path
+                self.label = self.manager_class.rsplit(".", 1)[-1]
+            else:
+                self.label = "unlabeled"
+        return self
+
+    @property
+    def resolved_label(self) -> str:
+        """Return a non-empty label for this credential manager."""
+        if self.label:
+            return self.label
+        if self.manager_key:
+            return self.manager_key
+        if self.manager_class:
+            return self.manager_class.rsplit(".", 1)[-1]
+        return "unlabeled"
+
+
+class CredentialPoolConfig(BaseModel):
+    """Configuration for an individual credential pool."""
+
+    provider: str = Field(..., description="Internal provider identifier")
+    manager_name: str | None = Field(
+        default=None,
+        description="Registry key to expose this balancer (defaults to '<provider>_credential_balancer')",
+    )
+    strategy: RotationStrategy = Field(
+        default=RotationStrategy.FAILOVER,
+        description="How credentials are selected for new requests",
+    )
+    manager_class: str | None = Field(
+        default=None,
+        description="Default manager class for all credentials in this pool (can be overridden per credential)",
+    )
+    storage_class: str | None = Field(
+        default=None,
+        description="Default storage class for all credentials in this pool (can be overridden per credential)",
+    )
+    credentials: list[CredentialManager] = Field(
+        default_factory=list,
+        description="Ordered list of manager-based credential sources participating in the pool",
+    )
+    max_failures_before_disable: int = Field(
+        default=2,
+        ge=1,
+        description="Number of failed responses tolerated before disabling a credential",
+    )
+    cooldown_seconds: float = Field(
+        default=60.0,
+        ge=0.0,
+        description="Cooldown window before a failed credential becomes eligible again",
+    )
+    failure_status_codes: list[int] = Field(
+        default_factory=lambda: [401, 403],
+        description="HTTP status codes that indicate credential failure",
+    )
+
+    @field_validator("credentials")
+    @classmethod
+    def _ensure_credentials_present(
+        cls, value: list[CredentialManager], _info: ValidationInfo
+    ) -> list[CredentialManager]:
+        if not value:
+            raise ValueError(
+                "credential pool must contain at least one credential file"
+            )
+        return value
+
+    @field_validator("failure_status_codes")
+    @classmethod
+    def _validate_status_codes(cls, codes: list[int]) -> list[int]:
+        normalised = sorted({code for code in codes if code >= 400})
+        if not normalised:
+            raise ValueError("at least one failure status code is required")
+        return normalised
+
+    @model_validator(mode="after")
+    def _apply_default_manager_name(self) -> CredentialPoolConfig:
+        if not self.manager_name:
+            self.manager_name = f"{self.provider}_credential_balancer"
+        return self
+
+    @model_validator(mode="after")
+    def _apply_pool_defaults_to_credentials(self) -> CredentialPoolConfig:
+        """Apply pool-level manager_class and storage_class to credentials that don't specify them."""
+        if not self.manager_class and not self.storage_class:
+            # No pool-level defaults to apply
+            return self
+
+        for cred in self.credentials:
+            # Only apply to CredentialManager type
+            if isinstance(cred, CredentialManager):
+                # Apply pool-level manager_class if credential doesn't specify one
+                if (
+                    self.manager_class
+                    and not cred.manager_class
+                    and not cred.manager_key
+                ):
+                    cred.manager_class = self.manager_class
+
+                # Apply pool-level storage_class if credential doesn't specify one
+                if self.storage_class and not cred.storage_class:
+                    cred.storage_class = self.storage_class
+
+        return self
+
+    @model_validator(mode="after")
+    def _validate_credentials_after_defaults(self) -> CredentialPoolConfig:
+        """Validate that all credentials have required manager information after applying defaults."""
+        for idx, cred in enumerate(self.credentials):
+            if isinstance(cred, CredentialManager):
+                # After applying defaults, each credential must have either manager_key or manager_class
+                if not cred.manager_key and not cred.manager_class:
+                    raise ValueError(
+                        f"Credential at index {idx} missing manager specification. "
+                        f"Either set manager_key/manager_class on the credential, "
+                        f"or set manager_class at pool level."
+                    )
+                # If using manager_class with file, storage_class is required
+                if cred.manager_class and cred.file and not cred.storage_class:
+                    raise ValueError(
+                        f"Credential at index {idx} with manager_class and file path "
+                        f"requires storage_class (either on credential or at pool level)"
+                    )
+        return self
+
+
+class CredentialBalancerSettings(BaseModel):
+    """Top-level plugin settings."""
+
+    enabled: bool = Field(default=True, description="Enable credential balancer")
+    providers: list[CredentialPoolConfig] = Field(
+        default_factory=list, description="Pools managed by the balancer"
+    )
+
+    @field_validator("providers")
+    @classmethod
+    def _ensure_unique_manager_names(
+        cls, value: list[CredentialPoolConfig]
+    ) -> list[CredentialPoolConfig]:
+        seen: set[str] = set()
+        for pool in value:
+            manager_name = pool.manager_name
+            if manager_name is None:
+                raise ValueError("manager name resolution failed")
+            if manager_name in seen:
+                raise ValueError(f"duplicate manager name detected: {manager_name}")
+            seen.add(manager_name)
+        return value