from abc import ABC, abstractmethod


class AbstractStorageBackend(ABC):
    """Common interface every storage backend must implement."""

    @property
    @abstractmethod
    def driver_name(self) -> str:
        """Short identifier returned in /health: 'local', 's3', or 'webdav'."""

    @abstractmethod
    async def put(self, bucket: str, key: str, data: bytes) -> None:
        """Store *data* under bucket/key. Creates bucket/intermediate dirs as needed."""

    @abstractmethod
    async def get(self, bucket: str, key: str) -> bytes:
        """Return the stored bytes. Raises KeyError if the object does not exist."""

    @abstractmethod
    async def delete(self, bucket: str, key: str) -> None:
        """Delete the object. No-op if it does not exist."""

    @abstractmethod
    async def list_keys(self, bucket: str) -> list[str]:
        """Return all keys stored in *bucket*. Returns [] if bucket is empty/absent."""

    @abstractmethod
    async def exists(self, bucket: str, key: str) -> bool:
        """Return True if the object exists."""

    @abstractmethod
    async def test_connection(self) -> None:
        """Verify the backend is reachable and writable. Raise on failure."""