feat(file-storage): add storage backend contract

surfsense_backend/app/file_storage/backends/__init__.py

@@ -0,0 +1,7 @@
+"""Storage backend implementations behind the shared :class:`StorageBackend`."""
+
+from __future__ import annotations
+
+from app.file_storage.backends.base import StorageBackend
+
+__all__ = ["StorageBackend"]

surfsense_backend/app/file_storage/backends/base.py

@@ -0,0 +1,31 @@
+"""The storage backend contract: the minimal object-store surface we depend on."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+
+
+class StorageBackend(ABC):
+    """Maps an opaque object key to durable bytes."""
+
+    #: Identifier stored on each row to record which backend holds the bytes.
+    backend_name: str
+
+    @abstractmethod
+    async def put(
+        self, key: str, data: bytes, *, content_type: str | None = None
+    ) -> None:
+        """Store ``data`` at ``key``, overwriting any existing object."""
+
+    @abstractmethod
+    def open_stream(self, key: str) -> AsyncIterator[bytes]:
+        """Yield the object's bytes in chunks. Raises if the key is absent."""
+
+    @abstractmethod
+    async def delete(self, key: str) -> None:
+        """Remove the object at ``key``; a missing key is not an error."""
+
+    @abstractmethod
+    async def exists(self, key: str) -> bool:
+        """Return whether an object is stored at ``key``."""