hawkapi-storage 0.1.0__py3-none-any.whl

hawkapi_storage/__init__.py

@@ -0,0 +1,43 @@
+"""hawkapi-storage — pluggable file storage for HawkAPI.
+
+Backends: local filesystem, AWS S3 (extras ``[s3]``), Google Cloud Storage
+(extras ``[gcs]``), Azure Blob Storage (extras ``[azure]``). Single
+:class:`Storage` protocol — swap backends freely.
+"""
+
+from __future__ import annotations
+
+from ._azure import AzureConfig, AzureStorage
+from ._base import (
+    NotFoundError,
+    Storage,
+    StorageError,
+    StoredObject,
+    guess_content_type,
+)
+from ._gcs import GCSConfig, GCSStorage
+from ._local import LocalConfig, LocalStorage
+from ._plugin import get_storage, init_storage, resolve_storage
+from ._s3 import S3Config, S3Storage
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AzureConfig",
+    "AzureStorage",
+    "GCSConfig",
+    "GCSStorage",
+    "LocalConfig",
+    "LocalStorage",
+    "NotFoundError",
+    "S3Config",
+    "S3Storage",
+    "Storage",
+    "StorageError",
+    "StoredObject",
+    "__version__",
+    "get_storage",
+    "guess_content_type",
+    "init_storage",
+    "resolve_storage",
+]

hawkapi_storage/_azure.py

@@ -0,0 +1,195 @@
+"""Azure Blob Storage backend."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from typing import Any, BinaryIO
+
+from ._base import NotFoundError, StorageError, StoredObject, guess_content_type, to_bytes
+
+
+@dataclass(slots=True)
+class AzureConfig:
+    container: str
+    connection_string: str = ""
+    account_url: str = ""
+    """e.g. https://myaccount.blob.core.windows.net — used with ``credential``."""
+
+    account_name: str = ""
+    account_key: str = ""
+
+
+@dataclass
+class AzureStorage:
+    config: AzureConfig
+    name: str = "azure"
+    _service: Any = field(default=None, init=False)
+    _container: Any = field(default=None, init=False)
+
+    def _get_container(self) -> Any:
+        if self._container is not None:
+            return self._container
+        try:
+            from azure.storage.blob import BlobServiceClient  # type: ignore[import-not-found]
+        except ImportError as exc:  # pragma: no cover
+            raise StorageError(
+                "azure-storage-blob not installed; pip install 'hawkapi-storage[azure]'"
+            ) from exc
+        if self.config.connection_string:
+            self._service = BlobServiceClient.from_connection_string(self.config.connection_string)
+        elif self.config.account_url and self.config.account_key:
+            self._service = BlobServiceClient(
+                account_url=self.config.account_url, credential=self.config.account_key
+            )
+        else:
+            raise StorageError("AzureConfig requires connection_string or account_url+account_key")
+        self._container = self._service.get_container_client(self.config.container)
+        return self._container
+
+    async def put(
+        self,
+        key: str,
+        data: bytes | BinaryIO | AsyncIterator[bytes],
+        *,
+        content_type: str | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> StoredObject:
+        if not isinstance(data, (bytes, bytearray)) and not hasattr(data, "read"):
+            chunks: list[bytes] = []
+            async for chunk in data:
+                chunks.append(chunk)
+            data = b"".join(chunks)
+        body = to_bytes(data)  # type: ignore[arg-type]
+        container = self._get_container()
+
+        def _upload() -> None:
+            from azure.storage.blob import ContentSettings  # type: ignore[import-not-found]
+
+            blob = container.get_blob_client(key)
+            blob.upload_blob(
+                body,
+                overwrite=True,
+                content_settings=ContentSettings(
+                    content_type=content_type or guess_content_type(key)
+                ),
+                metadata={k: str(v) for k, v in (metadata or {}).items()} or None,
+            )
+
+        await asyncio.to_thread(_upload)
+        return StoredObject(
+            key=key,
+            size=len(body),
+            content_type=content_type or guess_content_type(key),
+            metadata=dict(metadata or {}),
+        )
+
+    async def get(self, key: str) -> bytes:
+        container = self._get_container()
+
+        def _download() -> bytes:
+            blob = container.get_blob_client(key)
+            try:
+                stream = blob.download_blob()
+            except Exception as exc:
+                raise NotFoundError(key) from exc
+            return stream.readall()
+
+        return await asyncio.to_thread(_download)
+
+    async def stream(self, key: str, *, chunk_size: int = 65536) -> AsyncIterator[bytes]:
+        data = await self.get(key)
+        for i in range(0, len(data), chunk_size):
+            yield data[i : i + chunk_size]
+
+    async def exists(self, key: str) -> bool:
+        container = self._get_container()
+        return await asyncio.to_thread(container.get_blob_client(key).exists)
+
+    async def delete(self, key: str) -> None:
+        container = self._get_container()
+        try:
+            await asyncio.to_thread(container.delete_blob, key)
+        except Exception:
+            pass
+
+    async def head(self, key: str) -> StoredObject:
+        container = self._get_container()
+
+        def _props() -> StoredObject:
+            blob = container.get_blob_client(key)
+            try:
+                props = blob.get_blob_properties()
+            except Exception as exc:
+                raise NotFoundError(key) from exc
+            return StoredObject(
+                key=key,
+                size=props.size or 0,
+                content_type=(
+                    props.content_settings.content_type if props.content_settings else None
+                )
+                or guess_content_type(key),
+                last_modified=props.last_modified,
+                etag=str(props.etag or "").strip('"'),
+                metadata=dict(props.metadata or {}),
+            )
+
+        return await asyncio.to_thread(_props)
+
+    async def list(self, prefix: str = "", *, limit: int = 1000) -> AsyncIterator[StoredObject]:
+        container = self._get_container()
+
+        def _list() -> list[Any]:
+            return list(
+                container.list_blobs(name_starts_with=prefix or None, results_per_page=limit)
+            )
+
+        emitted = 0
+        for item in await asyncio.to_thread(_list):
+            yield StoredObject(
+                key=item.name,
+                size=item.size or 0,
+                content_type=(item.content_settings.content_type if item.content_settings else None)
+                or guess_content_type(item.name),
+                last_modified=item.last_modified,
+            )
+            emitted += 1
+            if emitted >= limit:
+                return
+
+    async def signed_url(
+        self,
+        key: str,
+        *,
+        expires_in: int = 3600,
+        method: str = "GET",
+        content_type: str | None = None,
+    ) -> str:
+        _ = content_type
+        try:
+            from azure.storage.blob import (  # type: ignore[import-not-found]
+                BlobSasPermissions,
+                generate_blob_sas,
+            )
+        except ImportError as exc:  # pragma: no cover
+            raise StorageError("azure-storage-blob not installed") from exc
+        container = self._get_container()
+        account_name = container.account_name
+        permissions = BlobSasPermissions(
+            read=method.upper() == "GET", write=method.upper() == "PUT"
+        )
+        token = await asyncio.to_thread(
+            generate_blob_sas,
+            account_name=account_name,
+            container_name=self.config.container,
+            blob_name=key,
+            account_key=self.config.account_key or None,
+            permission=permissions,
+            expiry=datetime.now(UTC) + timedelta(seconds=expires_in),
+        )
+        return f"{container.url}/{key}?{token}"
+
+
+__all__ = ["AzureConfig", "AzureStorage"]

hawkapi_storage/_base.py

@@ -0,0 +1,88 @@
+"""Storage backend abstraction."""
+
+from __future__ import annotations
+
+import io
+import mimetypes
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import BinaryIO, Protocol
+
+
+@dataclass(slots=True)
+class StoredObject:
+    key: str
+    size: int = 0
+    content_type: str = "application/octet-stream"
+    last_modified: datetime | None = None
+    etag: str = ""
+    metadata: dict[str, str] = field(default_factory=dict)
+
+
+class StorageError(Exception):
+    """Raised by every backend when a primitive fails."""
+
+
+class NotFoundError(StorageError):
+    """Raised when a key does not exist."""
+
+
+class Storage(Protocol):
+    """The minimal contract every backend implements."""
+
+    name: str
+
+    async def put(
+        self,
+        key: str,
+        data: bytes | BinaryIO | AsyncIterator[bytes],
+        *,
+        content_type: str | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> StoredObject: ...
+
+    async def get(self, key: str) -> bytes: ...
+
+    async def stream(self, key: str, *, chunk_size: int = 65536) -> AsyncIterator[bytes]: ...
+
+    async def exists(self, key: str) -> bool: ...
+
+    async def delete(self, key: str) -> None: ...
+
+    async def head(self, key: str) -> StoredObject: ...
+
+    async def list(self, prefix: str = "", *, limit: int = 1000) -> AsyncIterator[StoredObject]: ...
+
+    async def signed_url(
+        self,
+        key: str,
+        *,
+        expires_in: int = 3600,
+        method: str = "GET",
+        content_type: str | None = None,
+    ) -> str: ...
+
+
+def guess_content_type(key: str) -> str:
+    """Best-effort MIME guess from the key/filename."""
+    return mimetypes.guess_type(key)[0] or "application/octet-stream"
+
+
+def to_bytes(data: bytes | BinaryIO) -> bytes:
+    """Read a bytes/file-like into memory. Used by backends that need a single buffer."""
+    if isinstance(data, bytes):
+        return data
+    if isinstance(data, io.IOBase) or hasattr(data, "read"):
+        return data.read()
+    raise TypeError(f"unsupported data type: {type(data).__name__}")
+
+
+__all__ = [
+    "NotFoundError",
+    "Storage",
+    "StorageError",
+    "StoredObject",
+    "guess_content_type",
+    "to_bytes",
+]

hawkapi_storage/_gcs.py

@@ -0,0 +1,154 @@
+"""Google Cloud Storage backend (sync API offloaded to a thread)."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from datetime import timedelta
+from typing import Any, BinaryIO
+
+from ._base import NotFoundError, StorageError, StoredObject, guess_content_type, to_bytes
+
+
+@dataclass(slots=True)
+class GCSConfig:
+    bucket: str
+    project: str = ""
+    credentials_path: str = ""
+
+
+@dataclass
+class GCSStorage:
+    config: GCSConfig
+    name: str = "gcs"
+    _client: Any = field(default=None, init=False)
+    _bucket: Any = field(default=None, init=False)
+
+    def _get_bucket(self) -> Any:
+        if self._bucket is not None:
+            return self._bucket
+        try:
+            from google.cloud import storage  # type: ignore[import-not-found]
+        except ImportError as exc:  # pragma: no cover
+            raise StorageError(
+                "google-cloud-storage not installed; pip install 'hawkapi-storage[gcs]'"
+            ) from exc
+        if self.config.credentials_path:
+            self._client = storage.Client.from_service_account_json(self.config.credentials_path)
+        else:
+            self._client = storage.Client(project=self.config.project or None)
+        self._bucket = self._client.bucket(self.config.bucket)
+        return self._bucket
+
+    async def put(
+        self,
+        key: str,
+        data: bytes | BinaryIO | AsyncIterator[bytes],
+        *,
+        content_type: str | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> StoredObject:
+        if not isinstance(data, (bytes, bytearray)) and not hasattr(data, "read"):
+            chunks: list[bytes] = []
+            async for chunk in data:
+                chunks.append(chunk)
+            data = b"".join(chunks)
+        body = to_bytes(data)  # type: ignore[arg-type]
+        bucket = self._get_bucket()
+        blob = bucket.blob(key)
+        if metadata:
+            blob.metadata = {k: str(v) for k, v in metadata.items()}
+
+        def _upload() -> None:
+            blob.upload_from_string(body, content_type=content_type or guess_content_type(key))
+
+        await asyncio.to_thread(_upload)
+        return StoredObject(
+            key=key,
+            size=len(body),
+            content_type=content_type or guess_content_type(key),
+            metadata=dict(metadata or {}),
+        )
+
+    async def get(self, key: str) -> bytes:
+        bucket = self._get_bucket()
+        blob = bucket.blob(key)
+
+        def _download() -> bytes:
+            if not blob.exists():
+                raise NotFoundError(key)
+            return blob.download_as_bytes()
+
+        return await asyncio.to_thread(_download)
+
+    async def stream(self, key: str, *, chunk_size: int = 65536) -> AsyncIterator[bytes]:
+        # The GCS SDK does not expose a true streaming reader for blobs; we
+        # download once and re-yield in chunks, which is fine for the typical
+        # API-served-file size and keeps memory bounded for callers.
+        data = await self.get(key)
+        for i in range(0, len(data), chunk_size):
+            yield data[i : i + chunk_size]
+
+    async def exists(self, key: str) -> bool:
+        bucket = self._get_bucket()
+        return await asyncio.to_thread(bucket.blob(key).exists)
+
+    async def delete(self, key: str) -> None:
+        bucket = self._get_bucket()
+        await asyncio.to_thread(bucket.blob(key).delete)
+
+    async def head(self, key: str) -> StoredObject:
+        bucket = self._get_bucket()
+        blob = bucket.blob(key)
+
+        def _reload() -> StoredObject:
+            if not blob.exists():
+                raise NotFoundError(key)
+            blob.reload()
+            return StoredObject(
+                key=key,
+                size=blob.size or 0,
+                content_type=blob.content_type or guess_content_type(key),
+                last_modified=blob.updated,
+                etag=str(blob.etag or "").strip('"'),
+                metadata=dict(blob.metadata or {}),
+            )
+
+        return await asyncio.to_thread(_reload)
+
+    async def list(self, prefix: str = "", *, limit: int = 1000) -> AsyncIterator[StoredObject]:
+        bucket = self._get_bucket()
+
+        def _enumerate() -> list[Any]:
+            return list(bucket.list_blobs(prefix=prefix or None, max_results=limit))
+
+        for blob in await asyncio.to_thread(_enumerate):
+            yield StoredObject(
+                key=blob.name,
+                size=blob.size or 0,
+                content_type=blob.content_type or guess_content_type(blob.name),
+                last_modified=blob.updated,
+                etag=str(blob.etag or "").strip('"'),
+            )
+
+    async def signed_url(
+        self,
+        key: str,
+        *,
+        expires_in: int = 3600,
+        method: str = "GET",
+        content_type: str | None = None,
+    ) -> str:
+        bucket = self._get_bucket()
+        blob = bucket.blob(key)
+        return await asyncio.to_thread(
+            blob.generate_signed_url,
+            expiration=timedelta(seconds=expires_in),
+            method=method.upper(),
+            content_type=content_type,
+            version="v4",
+        )
+
+
+__all__ = ["GCSConfig", "GCSStorage"]

hawkapi_storage/_local.py

@@ -0,0 +1,185 @@
+"""Local filesystem backend — useful for dev + tests."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import hmac
+import os
+import shutil
+import time
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import BinaryIO
+from urllib.parse import quote, urlencode
+
+from ._base import (
+    NotFoundError,
+    StorageError,
+    StoredObject,
+    guess_content_type,
+    to_bytes,
+)
+
+
+@dataclass(slots=True)
+class LocalConfig:
+    root: str
+    """Filesystem directory that holds the objects."""
+
+    base_url: str = ""
+    """Public base URL prefix used by :meth:`signed_url`. Leave empty to return a
+    ``file://`` URL (only meaningful for tests)."""
+
+    signing_secret: str = ""
+    """HMAC secret for short-lived download URLs. Generated lazily if unset."""
+
+
+@dataclass
+class LocalStorage:
+    config: LocalConfig
+    name: str = "local"
+    _secret: str = field(default="", init=False)
+
+    def __post_init__(self) -> None:
+        os.makedirs(self.config.root, exist_ok=True)
+        self._secret = (
+            self.config.signing_secret or base64.urlsafe_b64encode(os.urandom(32)).decode()
+        )
+
+    def _path(self, key: str) -> Path:
+        safe = key.lstrip("/")
+        if ".." in Path(safe).parts:
+            raise StorageError("invalid key (path traversal)")
+        return Path(self.config.root, safe)
+
+    async def put(
+        self,
+        key: str,
+        data: bytes | BinaryIO | AsyncIterator[bytes],
+        *,
+        content_type: str | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> StoredObject:
+        path = self._path(key)
+        await asyncio.to_thread(path.parent.mkdir, parents=True, exist_ok=True)
+        if isinstance(data, (bytes, bytearray)) or hasattr(data, "read"):
+            buf = to_bytes(data)  # type: ignore[arg-type]
+            await asyncio.to_thread(path.write_bytes, buf)
+        else:
+            chunks: list[bytes] = []
+            async for chunk in data:
+                chunks.append(chunk)
+            await asyncio.to_thread(path.write_bytes, b"".join(chunks))
+        stat = await asyncio.to_thread(path.stat)
+        return StoredObject(
+            key=key,
+            size=stat.st_size,
+            content_type=content_type or guess_content_type(key),
+            last_modified=datetime.fromtimestamp(stat.st_mtime, tz=UTC),
+            metadata=dict(metadata or {}),
+        )
+
+    async def get(self, key: str) -> bytes:
+        path = self._path(key)
+        if not path.exists():
+            raise NotFoundError(key)
+        return await asyncio.to_thread(path.read_bytes)
+
+    async def stream(self, key: str, *, chunk_size: int = 65536) -> AsyncIterator[bytes]:
+        path = self._path(key)
+        if not path.exists():
+            raise NotFoundError(key)
+
+        def _chunks() -> list[bytes]:
+            out: list[bytes] = []
+            with path.open("rb") as fh:
+                while True:
+                    chunk = fh.read(chunk_size)
+                    if not chunk:
+                        break
+                    out.append(chunk)
+            return out
+
+        for chunk in await asyncio.to_thread(_chunks):
+            yield chunk
+
+    async def exists(self, key: str) -> bool:
+        return self._path(key).exists()
+
+    async def delete(self, key: str) -> None:
+        path = self._path(key)
+        if path.is_dir():
+            await asyncio.to_thread(shutil.rmtree, str(path))
+        elif path.exists():
+            await asyncio.to_thread(path.unlink)
+
+    async def head(self, key: str) -> StoredObject:
+        path = self._path(key)
+        if not path.exists():
+            raise NotFoundError(key)
+        stat = await asyncio.to_thread(path.stat)
+        return StoredObject(
+            key=key,
+            size=stat.st_size,
+            content_type=guess_content_type(key),
+            last_modified=datetime.fromtimestamp(stat.st_mtime, tz=UTC),
+        )
+
+    async def list(self, prefix: str = "", *, limit: int = 1000) -> AsyncIterator[StoredObject]:
+        root = Path(self.config.root)
+        target = root / prefix.lstrip("/") if prefix else root
+        if not root.exists():
+            return
+        count = 0
+        for path in sorted(root.rglob("*")):
+            if not path.is_file():
+                continue
+            rel = path.relative_to(root).as_posix()
+            if prefix and not rel.startswith(prefix.lstrip("/")):
+                continue
+            if not str(path).startswith(str(target)) and prefix:
+                continue
+            stat = await asyncio.to_thread(path.stat)
+            yield StoredObject(
+                key=rel,
+                size=stat.st_size,
+                content_type=guess_content_type(rel),
+                last_modified=datetime.fromtimestamp(stat.st_mtime, tz=UTC),
+            )
+            count += 1
+            if count >= limit:
+                return
+
+    async def signed_url(
+        self,
+        key: str,
+        *,
+        expires_in: int = 3600,
+        method: str = "GET",
+        content_type: str | None = None,
+    ) -> str:
+        _ = content_type
+        if method.upper() not in {"GET", "PUT"}:
+            raise StorageError("LocalStorage only signs GET / PUT")
+        expires = int(time.time()) + max(1, expires_in)
+        msg = f"{method.upper()}:{key}:{expires}".encode()
+        sig = hmac.new(self._secret.encode(), msg, hashlib.sha256).hexdigest()
+        query = urlencode({"expires": expires, "sig": sig, "method": method.upper()})
+        if self.config.base_url:
+            base = self.config.base_url.rstrip("/")
+            return f"{base}/{quote(key)}?{query}"
+        return f"file://{self._path(key)}?{query}"
+
+    def verify_signed_url(self, key: str, expires: int, sig: str, *, method: str = "GET") -> bool:
+        if expires < int(time.time()):
+            return False
+        msg = f"{method.upper()}:{key}:{expires}".encode()
+        expected = hmac.new(self._secret.encode(), msg, hashlib.sha256).hexdigest()
+        return hmac.compare_digest(expected, sig)
+
+
+__all__ = ["LocalConfig", "LocalStorage"]

hawkapi_storage/_plugin.py

@@ -0,0 +1,49 @@
+"""Plugin entry point + DI helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from hawkapi import HTTPException, Request
+
+from ._base import Storage
+
+
+class _StateNamespace:
+    storage: Any
+
+
+_ACTIVE: dict[int, Storage] = {}
+_LAST: list[Storage | None] = [None]
+
+
+def init_storage(app: Any, *, storage: Storage) -> Storage:
+    """Attach a :class:`Storage` to ``app.state.storage`` and register it for DI lookup."""
+    if getattr(app, "state", None) is None:
+        app.state = _StateNamespace()
+    app.state.storage = storage
+    _ACTIVE[id(app)] = storage
+    _LAST[0] = storage
+    return storage
+
+
+def resolve_storage(app: Any) -> Storage | None:
+    if app is None:
+        return _LAST[0]
+    found = _ACTIVE.get(id(app))
+    if found is not None:
+        return found
+    state = getattr(app, "state", None)
+    if state is not None and hasattr(state, "storage"):
+        return state.storage  # type: ignore[no-any-return]
+    return _LAST[0]
+
+
+def get_storage(request: Request) -> Storage:
+    found = resolve_storage(request.scope.get("app"))
+    if found is None:
+        raise HTTPException(500, detail="Storage not configured — call init_storage(app, ...)")
+    return found
+
+
+__all__ = ["get_storage", "init_storage", "resolve_storage"]

hawkapi_storage/_s3.py

@@ -0,0 +1,180 @@
+"""AWS S3 backend (boto3, sync API offloaded to a thread)."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Any, BinaryIO
+
+from ._base import NotFoundError, StorageError, StoredObject, guess_content_type, to_bytes
+
+
+@dataclass(slots=True)
+class S3Config:
+    bucket: str
+    region: str = "us-east-1"
+    aws_access_key_id: str = ""
+    aws_secret_access_key: str = ""
+    endpoint_url: str = ""
+    """Set to a non-AWS S3-compatible endpoint (MinIO, Wasabi, …)."""
+
+    use_path_style: bool = False
+    """Path-style addressing for MinIO and friends."""
+
+
+@dataclass
+class S3Storage:
+    config: S3Config
+    name: str = "s3"
+    _client: Any = field(default=None, init=False)
+
+    def _get_client(self) -> Any:
+        if self._client is not None:
+            return self._client
+        try:
+            import boto3
+            from botocore.config import Config
+        except ImportError as exc:  # pragma: no cover
+            raise StorageError("boto3 not installed; pip install 'hawkapi-storage[s3]'") from exc
+        kwargs: dict[str, Any] = {"region_name": self.config.region}
+        if self.config.aws_access_key_id:
+            kwargs["aws_access_key_id"] = self.config.aws_access_key_id
+            kwargs["aws_secret_access_key"] = self.config.aws_secret_access_key
+        if self.config.endpoint_url:
+            kwargs["endpoint_url"] = self.config.endpoint_url
+        if self.config.use_path_style:
+            kwargs["config"] = Config(s3={"addressing_style": "path"})
+        self._client = boto3.client("s3", **kwargs)
+        return self._client
+
+    async def put(
+        self,
+        key: str,
+        data: bytes | BinaryIO | AsyncIterator[bytes],
+        *,
+        content_type: str | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> StoredObject:
+        if not isinstance(data, (bytes, bytearray)) and not hasattr(data, "read"):
+            chunks: list[bytes] = []
+            async for chunk in data:
+                chunks.append(chunk)
+            data = b"".join(chunks)
+        body = to_bytes(data)  # type: ignore[arg-type]
+        client = self._get_client()
+        kwargs: dict[str, Any] = {
+            "Bucket": self.config.bucket,
+            "Key": key,
+            "Body": body,
+            "ContentType": content_type or guess_content_type(key),
+        }
+        if metadata:
+            kwargs["Metadata"] = {k: str(v) for k, v in metadata.items()}
+        await asyncio.to_thread(client.put_object, **kwargs)
+        return StoredObject(
+            key=key,
+            size=len(body),
+            content_type=kwargs["ContentType"],
+            metadata=dict(metadata or {}),
+        )
+
+    async def get(self, key: str) -> bytes:
+        client = self._get_client()
+        try:
+            obj = await asyncio.to_thread(client.get_object, Bucket=self.config.bucket, Key=key)
+        except Exception as exc:
+            raise NotFoundError(key) from exc
+        return await asyncio.to_thread(obj["Body"].read)
+
+    async def stream(self, key: str, *, chunk_size: int = 65536) -> AsyncIterator[bytes]:
+        client = self._get_client()
+        try:
+            obj = await asyncio.to_thread(client.get_object, Bucket=self.config.bucket, Key=key)
+        except Exception as exc:
+            raise NotFoundError(key) from exc
+        stream = obj["Body"]
+        while True:
+            chunk = await asyncio.to_thread(stream.read, chunk_size)
+            if not chunk:
+                break
+            yield chunk
+
+    async def exists(self, key: str) -> bool:
+        client = self._get_client()
+        try:
+            await asyncio.to_thread(client.head_object, Bucket=self.config.bucket, Key=key)
+            return True
+        except Exception:
+            return False
+
+    async def delete(self, key: str) -> None:
+        client = self._get_client()
+        await asyncio.to_thread(client.delete_object, Bucket=self.config.bucket, Key=key)
+
+    async def head(self, key: str) -> StoredObject:
+        client = self._get_client()
+        try:
+            meta = await asyncio.to_thread(client.head_object, Bucket=self.config.bucket, Key=key)
+        except Exception as exc:
+            raise NotFoundError(key) from exc
+        return StoredObject(
+            key=key,
+            size=meta.get("ContentLength", 0),
+            content_type=meta.get("ContentType", guess_content_type(key)),
+            last_modified=meta.get("LastModified"),
+            etag=str(meta.get("ETag", "")).strip('"'),
+            metadata=dict(meta.get("Metadata", {})),
+        )
+
+    async def list(self, prefix: str = "", *, limit: int = 1000) -> AsyncIterator[StoredObject]:
+        client = self._get_client()
+        token: str | None = None
+        emitted = 0
+        while True:
+            kwargs: dict[str, Any] = {
+                "Bucket": self.config.bucket,
+                "Prefix": prefix,
+                "MaxKeys": min(limit - emitted, 1000),
+            }
+            if token:
+                kwargs["ContinuationToken"] = token
+            resp = await asyncio.to_thread(client.list_objects_v2, **kwargs)
+            for obj in resp.get("Contents", []):
+                yield StoredObject(
+                    key=obj["Key"],
+                    size=obj.get("Size", 0),
+                    content_type=guess_content_type(obj["Key"]),
+                    last_modified=obj.get("LastModified"),
+                    etag=str(obj.get("ETag", "")).strip('"'),
+                )
+                emitted += 1
+                if emitted >= limit:
+                    return
+            if not resp.get("IsTruncated"):
+                return
+            token = resp.get("NextContinuationToken")
+
+    async def signed_url(
+        self,
+        key: str,
+        *,
+        expires_in: int = 3600,
+        method: str = "GET",
+        content_type: str | None = None,
+    ) -> str:
+        client = self._get_client()
+        op = {"GET": "get_object", "PUT": "put_object", "DELETE": "delete_object"}.get(
+            method.upper()
+        )
+        if op is None:
+            raise StorageError(f"unsupported signed URL method {method!r}")
+        params: dict[str, Any] = {"Bucket": self.config.bucket, "Key": key}
+        if method.upper() == "PUT" and content_type:
+            params["ContentType"] = content_type
+        return await asyncio.to_thread(
+            client.generate_presigned_url, op, Params=params, ExpiresIn=expires_in
+        )
+
+
+__all__ = ["S3Config", "S3Storage"]

hawkapi_storage-0.1.0.dist-info/METADATA

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: hawkapi-storage
+Version: 0.1.0
+Summary: File storage for HawkAPI — local, S3, GCS, Azure backends, pre-signed URLs, streaming uploads
+Project-URL: Homepage, https://pypi.org/project/hawkapi-storage/
+Project-URL: Repository, https://github.com/ashimov/hawkapi-storage
+Project-URL: Issues, https://github.com/ashimov/hawkapi-storage/issues
+Author-email: HawkAPI Contributors <hawkapi@users.noreply.github.com>
+License: MIT License
+        
+        Copyright (c) 2026 HawkAPI Contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: azure,files,gcs,hawkapi,s3,storage,upload
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Filesystems
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: hawkapi>=0.1.7
+Provides-Extra: azure
+Requires-Dist: azure-storage-blob>=12.19; extra == 'azure'
+Provides-Extra: dev
+Requires-Dist: boto3>=1.34; extra == 'dev'
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: gcs
+Requires-Dist: google-cloud-storage>=2.14; extra == 'gcs'
+Provides-Extra: s3
+Requires-Dist: boto3>=1.34; extra == 's3'
+Description-Content-Type: text/markdown
+
+# hawkapi-storage
+
+Pluggable file storage for [HawkAPI](https://github.com/ashimov/HawkAPI). One `Storage` protocol, four backends: local filesystem, AWS S3 (and S3-compatible — MinIO, Wasabi, R2), Google Cloud Storage, Azure Blob Storage. Pre-signed URLs and streaming on all of them.
+
+## Install
+
+```bash
+pip install hawkapi-storage                  # local filesystem only
+pip install 'hawkapi-storage[s3]'            # + AWS S3
+pip install 'hawkapi-storage[gcs]'           # + Google Cloud Storage
+pip install 'hawkapi-storage[azure]'         # + Azure Blob Storage
+```
+
+## Quickstart
+
+```python
+from hawkapi import Depends, HawkAPI
+from hawkapi_storage import LocalConfig, LocalStorage, Storage, get_storage, init_storage
+
+app = HawkAPI()
+init_storage(app, storage=LocalStorage(LocalConfig(root="/var/data", base_url="https://cdn.example")))
+
+
+@app.put("/files/{key}")
+async def upload(key: str, body: bytes, s: Storage = Depends(get_storage)):
+    obj = await s.put(key, body, content_type="application/octet-stream")
+    return {"key": obj.key, "size": obj.size}
+
+
+@app.get("/files/{key}/url")
+async def signed(key: str, s: Storage = Depends(get_storage)):
+    return {"url": await s.signed_url(key, expires_in=300)}
+```
+
+Swap `LocalStorage` for any other backend — every primitive is identical.
+
+## Backends
+
+```python
+from hawkapi_storage import (
+    LocalStorage, LocalConfig,
+    S3Storage,    S3Config,        # extras: [s3]
+    GCSStorage,   GCSConfig,       # extras: [gcs]
+    AzureStorage, AzureConfig,     # extras: [azure]
+)
+
+local = LocalStorage(LocalConfig(root="/var/data"))
+s3    = S3Storage(S3Config(bucket="my-bucket", region="eu-west-1"))
+minio = S3Storage(S3Config(bucket="mb", endpoint_url="https://minio.example", use_path_style=True))
+gcs   = GCSStorage(GCSConfig(bucket="my-bucket", project="my-project"))
+azure = AzureStorage(AzureConfig(container="files", connection_string="..."))
+```
+
+## The `Storage` protocol
+
+```python
+class Storage(Protocol):
+    name: str
+
+    async def put(self, key, data, *, content_type=None, metadata=None) -> StoredObject: ...
+    async def get(self, key) -> bytes: ...
+    async def stream(self, key, *, chunk_size=65536) -> AsyncIterator[bytes]: ...
+    async def exists(self, key) -> bool: ...
+    async def delete(self, key) -> None: ...
+    async def head(self, key) -> StoredObject: ...
+    async def list(self, prefix="", *, limit=1000) -> AsyncIterator[StoredObject]: ...
+    async def signed_url(self, key, *, expires_in=3600, method="GET", content_type=None) -> str: ...
+```
+
+`put()` accepts `bytes`, a file-like object, or an `AsyncIterator[bytes]` (for streaming uploads).
+
+## Streaming downloads
+
+```python
+@app.get("/download/{key}")
+async def download(key: str, s: Storage = Depends(get_storage)):
+    return StreamingResponse(s.stream(key, chunk_size=65536),
+                             media_type=(await s.head(key)).content_type)
+```
+
+## Pre-signed URLs
+
+Every backend supports `signed_url(key, expires_in=..., method="GET" | "PUT")`. For PUT/upload pre-signs, pass `content_type=` so the client must send the matching `Content-Type` header.
+
+`LocalStorage` produces HMAC-signed URLs that you verify on download with `local.verify_signed_url(key, expires, sig, method="GET")` — useful when serving downloads through your own handler.
+
+## Local filesystem details
+
+- Path traversal (`..`) is rejected at `put`/`get` time.
+- `LocalConfig(base_url=...)` sets the prefix used by `signed_url()` — pair it with a Nginx alias or a HawkAPI download handler.
+- `LocalConfig(signing_secret=...)` lets you pin the HMAC secret (otherwise generated once at startup).
+
+## Errors
+
+- `StorageError` — base class.
+- `NotFoundError(key)` — `get` / `head` / `stream` on a missing key.
+
+## Development
+
+```bash
+git clone https://github.com/ashimov/hawkapi-storage.git
+cd hawkapi-storage
+uv sync --extra dev
+uv run pytest -q
+uv run ruff check . && uv run ruff format --check .
+uv run pyright src/
+```
+
+## License
+
+MIT.

hawkapi_storage-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+hawkapi_storage/__init__.py,sha256=ukibo0at4kQOe4Y-cdXPZDW8iHuAh0TB1DBt9p3ClEU,1011
+hawkapi_storage/_azure.py,sha256=TEfDNCUyhxAV01LlsKujehxOoXOldSI72c5DTOjFjs0,6895
+hawkapi_storage/_base.py,sha256=5K5ss1NnT0msyT1ZAFFKifzee83omhv7EDoa1dG583k,2248
+hawkapi_storage/_gcs.py,sha256=3t135cpqZ0bQsSX9ojNT4vBAQnQKwflxiNeQ2JQRk60,5245
+hawkapi_storage/_local.py,sha256=iZRUvWVNw7SFgEDWgY6IKqsMsAO4ZCfpDGKx6165rcA,6209
+hawkapi_storage/_plugin.py,sha256=R4bUKGd5qRDyi1LSkkn7FPG-rm6Q7Cu_qWe2y2jLE1U,1279
+hawkapi_storage/_s3.py,sha256=ArPoI30R9XCFhTEUDnMFZSGPQvWT21R_NF7M16PhB0w,6590
+hawkapi_storage/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hawkapi_storage-0.1.0.dist-info/METADATA,sha256=5K6Ig2cT1iD8yV8b-r_c5m4ZHLpBRsSnqOjwFU6UO7g,6713
+hawkapi_storage-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+hawkapi_storage-0.1.0.dist-info/licenses/LICENSE,sha256=_RpjhvsfLqqeG_gv2cRatjIxCTGXTpXhKU9jqLZXYa4,1077
+hawkapi_storage-0.1.0.dist-info/RECORD,,

hawkapi_storage-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hawkapi_storage-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HawkAPI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.