"""存储后端抽象接口。"""
from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import AsyncIterator, Optional


@dataclass
class StorageObject:
    key: str
    size: int
    last_modified: Optional[str] = None  # ISO 8601


class BaseStorage(ABC):
    """所有存储后端实现的统一接口。"""

    type: str = "base"

    def __init__(self, config: dict):
        self.config = config

    @abstractmethod
    async def test_connection(self) -> tuple[bool, str]:
        """测试连通性。返回 (ok, message)。"""

    @abstractmethod
    async def upload_stream(
        self,
        source: AsyncIterator[bytes],
        key: str,
        content_type: str = "application/octet-stream",
    ) -> tuple[int, str]:
        """流式上传。返回 (size_bytes, sha256_hex)。"""

    @abstractmethod
    async def download_stream(self, key: str) -> AsyncIterator[bytes]: ...

    @abstractmethod
    async def delete(self, key: str) -> None: ...

    @abstractmethod
    async def exists(self, key: str) -> bool: ...

    @abstractmethod
    async def list(self, prefix: str = "") -> list[StorageObject]: ...