soulsync/core/torrent_clients/base.py

"""Torrent client adapter contract.

``TorrentClientAdapter`` is a structural Protocol — any class with
these method signatures is treated as a valid adapter. The download
plugin layer (built in a later commit) dispatches generically against
this surface so it doesn't have to know whether the user picked
qBittorrent, Transmission, or Deluge.

The contract intentionally hides protocol-specific details:
- qBittorrent uses cookie auth + multipart form uploads.
- Transmission uses an X-Transmission-Session-Id header + JSON RPC.
- Deluge 2.x uses /json with a session cookie.

All three converge on the same eight verbs below.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import List, Optional, Protocol, runtime_checkable


@dataclass
class TorrentStatus:
    """Adapter-uniform view of one torrent's live state.

    Field semantics:
    - ``state`` is one of: ``queued`` | ``downloading`` | ``seeding`` |
      ``paused`` | ``stalled`` | ``error`` | ``completed``. Each
      adapter maps its native state names to this set.
    - ``progress`` is 0.0–1.0.
    - ``save_path`` is where files land on the torrent client's host.
      For remote clients this is a path on the *remote* machine.
    - ``files`` is the list of relative paths inside the torrent. Empty
      until the client has finished fetching the metadata.
    """

    id: str                          # torrent hash (qBit, Deluge) or numeric id (Transmission)
    name: str
    state: str
    progress: float
    size: int                        # total size in bytes
    downloaded: int                  # bytes downloaded so far
    download_speed: int              # bytes/sec
    upload_speed: int                # bytes/sec
    seeders: int = 0
    peers: int = 0
    eta: Optional[int] = None        # seconds, None if unknown
    save_path: Optional[str] = None
    files: Optional[List[str]] = None
    error: Optional[str] = None


@runtime_checkable
class TorrentClientAdapter(Protocol):
    """Structural contract every torrent-client adapter implements."""

    def is_configured(self) -> bool:
        """True when the adapter has a URL and any credentials it
        needs. Reads from config_manager — never raises on missing
        config, just returns False so the orchestrator can dim the
        torrent download source in the UI."""
        ...

    async def check_connection(self) -> bool:
        """Probe the client over the network. Logs in if required."""
        ...

    async def add_torrent(
        self,
        url_or_magnet: str,
        category: str = "soulsync",
        save_path: Optional[str] = None,
    ) -> Optional[str]:
        """Hand the torrent client a HTTP/HTTPS URL pointing to a
        ``.torrent`` file or a ``magnet:`` URI. Returns the torrent's
        client-side identifier (info-hash for qBit / Deluge, numeric
        id for Transmission) or ``None`` on failure."""
        ...

    async def add_torrent_file(
        self,
        file_bytes: bytes,
        category: str = "soulsync",
        save_path: Optional[str] = None,
    ) -> Optional[str]:
        """Upload a raw ``.torrent`` payload. Same return as
        ``add_torrent``. Used when the indexer doesn't expose a
        direct download URL and SoulSync had to fetch the file
        itself first."""
        ...

    async def get_status(self, torrent_id: str) -> Optional[TorrentStatus]:
        """Return live status for one torrent, or ``None`` if the
        client doesn't know about it."""
        ...

    async def get_all(self) -> List[TorrentStatus]:
        """Return live status for every torrent the client currently
        tracks. Used by the global download list."""
        ...

    async def remove(self, torrent_id: str, delete_files: bool = False) -> bool:
        """Remove the torrent from the client. ``delete_files=True``
        also deletes the downloaded data on disk."""
        ...

    async def pause(self, torrent_id: str) -> bool: ...

    async def resume(self, torrent_id: str) -> bool: ...