feat: local storage logic & endpoints

app/domain/ports.py

@@ -7,9 +7,13 @@ are bound to these ports at the composition root (``app.api.deps``).
 
 import datetime as dt
 import uuid
+from collections.abc import AsyncIterator
+from contextlib import AbstractAsyncContextManager
+from pathlib import Path
 from typing import Protocol
 
-from app.domain.entities import Credentials, User
+from app.domain.entities import Credentials, ObjectStat, User
+from app.domain.entities.track import Artist, Track
 from app.domain.tokens import IssuedToken, TokenClaims, TokenType
 
 
@@ -56,3 +60,38 @@ class TokenService(Protocol):
         """Verify signature + expiry and return claims. Raises
         :class:`~app.domain.errors.AuthenticationError` on any failure."""
         ...
+
+
+class FileStorage(Protocol):
+    async def save_file(self, key: str, src_path: Path) -> int: ...
+    async def open_range(
+        self, key: str, start: int, end: int | None
+    ) -> tuple[AsyncIterator[bytes], int]: ...
+    async def stat(self, key: str) -> ObjectStat: ...
+    async def exists(self, key: str) -> bool: ...
+    async def delete(self, key: str) -> None: ...
+    def as_local_path(self, key: str) -> AbstractAsyncContextManager[Path]: ...
+
+
+class ArtistRepository(Protocol):
+    async def get_or_create(self, name: str) -> Artist: ...
+
+
+class TrackRepository(Protocol):
+    async def get_by_id(self, track_id: uuid.UUID) -> Track | None: ...
+    async def get_by_source(self, source: str, source_id: str) -> Track | None: ...
+    async def add(
+        self,
+        *,
+        id: uuid.UUID,
+        title: str,
+        artist_id: uuid.UUID,
+        file_path: str,
+        file_format: str,
+        file_size: int,
+        source: str,
+        source_id: str,
+        metadata_status: str,
+        added_by: uuid.UUID | None,
+    ) -> Track: ...
+    async def delete(self, track_id: uuid.UUID) -> None: ...