base.py 2.4 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667
  1. """Abstract base for proxy upstream adapters; the proxy server is otherwise provider-agnostic."""
  2. from __future__ import annotations
  3. from abc import ABC, abstractmethod
  4. from dataclasses import dataclass
  5. from typing import FrozenSet, Optional
  6. @dataclass(frozen=True)
  7. class UpstreamCredential:
  8. """A resolved bearer + base URL ready to forward to."""
  9. bearer: str # token only, no ``Bearer`` prefix
  10. base_url: str # e.g. ``https://inference-api.nousresearch.com/v1``
  11. token_type: str = "Bearer"
  12. expires_at: Optional[str] = None # ISO-8601, informational
  13. class UpstreamAdapter(ABC):
  14. """Contract for an upstream provider the proxy can forward to."""
  15. @property
  16. @abstractmethod
  17. def name(self) -> str:
  18. """Adapter key used on the CLI (e.g. ``"nous"``)."""
  19. @property
  20. @abstractmethod
  21. def display_name(self) -> str:
  22. """Human-readable provider name for logs and ``proxy status``."""
  23. @property
  24. @abstractmethod
  25. def allowed_paths(self) -> frozenset[str]:
  26. """Paths relative to the proxy's ``/v1`` mount (``"/chat/completions"`` ⇒
  27. ``/v1/chat/completions``); anything else gets a 404 with a helpful body."""
  28. @abstractmethod
  29. def is_authenticated(self) -> bool:
  30. """Cheap (no network) usable-credentials check; ``proxy start`` uses it for a clear
  31. up-front error before binding a port."""
  32. @abstractmethod
  33. def get_credential(self) -> UpstreamCredential:
  34. """Fresh credential (refreshing/rotating + persisting as needed). Raises RuntimeError when
  35. unauthenticated or refresh fails; the proxy then returns 401 to the client."""
  36. def get_retry_credential(
  37. self, *, failed_credential: UpstreamCredential, status_code: int
  38. ) -> Optional[UpstreamCredential]:
  39. """Alternate credential for a one-shot retry after the upstream rejects the first request;
  40. default is no retry."""
  41. _ = failed_credential, status_code
  42. return None
  43. def describe(self) -> str:
  44. """One-line status summary for ``proxy status``."""
  45. try:
  46. cred = self.get_credential()
  47. except Exception as exc: # pragma: no cover - defensive
  48. return f"{self.display_name}: not ready ({exc})"
  49. ttl = f" (expires {cred.expires_at})" if cred.expires_at else ""
  50. return f"{self.display_name}: {cred.base_url}{ttl}"
  51. __all__ = ["UpstreamAdapter", "UpstreamCredential"]