feat: harden file sharing and integrity

src/govoplan_files/backend/storage/backends.py

@@ -17,6 +17,22 @@ class StorageBackendError(RuntimeError):
     pass
 
 
+class StorageObjectMissing(StorageBackendError):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class StorageObjectInfo:
+    key: str
+    size_bytes: int
+
+
+@dataclass(frozen=True, slots=True)
+class StorageObjectPage:
+    objects: tuple[StorageObjectInfo, ...]
+    next_cursor: str | None = None
+
+
 class StorageBackend(Protocol):
     name: str
 
@@ -25,6 +41,14 @@ class StorageBackend(Protocol):
     def iter_bytes(self, key: str, *, chunk_size: int = 1024 * 1024) -> Iterable[bytes]: ...
     def delete(self, key: str) -> None: ...
     def exists(self, key: str) -> bool: ...
+    def stat(self, key: str) -> StorageObjectInfo: ...
+    def list_objects(
+        self,
+        *,
+        prefix: str,
+        after: str | None = None,
+        limit: int = 500,
+    ) -> StorageObjectPage: ...
 
 
 @dataclass(slots=True)
@@ -55,7 +79,7 @@ class LocalFilesystemStorageBackend:
             candidate = self._path_for_root(root, key)
             if candidate.exists() and candidate.is_file():
                 return candidate
-        raise StorageBackendError("Stored object does not exist")
+        raise StorageObjectMissing("Stored object does not exist")
 
     def put_bytes(self, key: str, data: bytes, *, content_type: str | None = None) -> None:
         path = self._path(key)
@@ -86,6 +110,33 @@ class LocalFilesystemStorageBackend:
             return False
         return True
 
+    def stat(self, key: str) -> StorageObjectInfo:
+        path = self._readable_path(key)
+        return StorageObjectInfo(key=key, size_bytes=path.stat().st_size)
+
+    def list_objects(
+        self,
+        *,
+        prefix: str,
+        after: str | None = None,
+        limit: int = 500,
+    ) -> StorageObjectPage:
+        normalized_limit = max(1, min(int(limit), 5000))
+        candidates: list[StorageObjectInfo] = []
+        for path in _iter_local_files(self.root):
+            key = path.relative_to(self.root).as_posix()
+            if not key.startswith(prefix) or (after is not None and key <= after):
+                continue
+            candidates.append(StorageObjectInfo(key=key, size_bytes=path.stat().st_size))
+            if len(candidates) > normalized_limit:
+                break
+        has_more = len(candidates) > normalized_limit
+        page = tuple(candidates[:normalized_limit])
+        return StorageObjectPage(
+            objects=page,
+            next_cursor=page[-1].key if has_more and page else None,
+        )
+
 
 @dataclass(slots=True)
 class S3StorageBackend:
@@ -175,6 +226,52 @@ class S3StorageBackend:
         except Exception:
             return False
 
+    def stat(self, key: str) -> StorageObjectInfo:
+        try:
+            response = self.client.head_object(Bucket=self.bucket, Key=key)
+        except Exception as exc:  # pragma: no cover - depends on S3 backend
+            if _s3_missing_error(exc):
+                raise StorageObjectMissing("Stored object does not exist") from exc
+            raise StorageBackendError(str(exc)) from exc
+        try:
+            size = int(response.get("ContentLength"))
+        except (AttributeError, TypeError, ValueError) as exc:
+            raise StorageBackendError("S3 object metadata did not include a valid size") from exc
+        return StorageObjectInfo(key=key, size_bytes=size)
+
+    def list_objects(
+        self,
+        *,
+        prefix: str,
+        after: str | None = None,
+        limit: int = 500,
+    ) -> StorageObjectPage:
+        normalized_limit = max(1, min(int(limit), 1000))
+        kwargs: dict[str, object] = {
+            "Bucket": self.bucket,
+            "Prefix": prefix,
+            "MaxKeys": normalized_limit,
+        }
+        if after:
+            kwargs["StartAfter"] = after
+        try:
+            response = self.client.list_objects_v2(**kwargs)
+        except Exception as exc:  # pragma: no cover - depends on S3 backend
+            raise StorageBackendError(str(exc)) from exc
+        objects = tuple(
+            StorageObjectInfo(
+                key=str(item["Key"]),
+                size_bytes=int(item.get("Size") or 0),
+            )
+            for item in response.get("Contents", ())
+            if isinstance(item, dict) and item.get("Key")
+        )
+        has_more = bool(response.get("IsTruncated"))
+        return StorageObjectPage(
+            objects=objects,
+            next_cursor=objects[-1].key if has_more and objects else None,
+        )
+
 
 def _reject_declared_object_size(obj: object, *, max_bytes: int) -> None:
     if not isinstance(obj, dict):
@@ -187,6 +284,25 @@ def _reject_declared_object_size(obj: object, *, max_bytes: int) -> None:
         raise StorageBackendError(f"Stored object exceeds the deployment limit of {max_bytes} bytes")
 
 
+def _iter_local_files(root: Path):
+    for entry in sorted(root.iterdir(), key=lambda item: item.name):
+        if entry.is_dir():
+            yield from _iter_local_files(entry)
+        elif entry.is_file():
+            yield entry
+
+
+def _s3_missing_error(exc: Exception) -> bool:
+    response = getattr(exc, "response", None)
+    if not isinstance(response, dict):
+        return False
+    error = response.get("Error")
+    metadata = response.get("ResponseMetadata")
+    code = str(error.get("Code") if isinstance(error, dict) else "")
+    status_code = metadata.get("HTTPStatusCode") if isinstance(metadata, dict) else None
+    return code in {"404", "NoSuchKey", "NotFound"} or status_code == 404
+
+
 def _fallback_roots() -> tuple[Path, ...]:
     raw = getattr(settings, "file_storage_local_fallback_roots", "") or ""
     return tuple(Path(item.strip()) for item in str(raw).split(",") if item.strip())