feat(backend): storage trash with seven day retention, trashed files are not fetched again automatically

backend/src/utils/storage.py

@@ -1,6 +1,8 @@
 import hashlib
 from pathlib import Path
 
+TRASH_DIR = ".trash"
+
 
 class ContentAddressedStorage:
     def __init__(self, root: str | Path, shard_depth: int = 2) -> None:
@@ -27,3 +29,29 @@ class ContentAddressedStorage:
 
     def url(self, key: str) -> str:
         return str(self._path(key))
+
+    def _trash_path(self, key: str) -> Path:
+        return self._root / TRASH_DIR / key
+
+    def trash(self, key: str) -> None:
+        target = self._trash_path(key)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        self._path(key).replace(target)
+
+    def restore(self, key: str) -> bool:
+        source = self._trash_path(key)
+        target = self._path(key)
+        if not source.exists():
+            return target.exists()
+        if target.exists():
+            source.unlink()
+        else:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            source.replace(target)
+        return True
+
+    def purge(self, key: str) -> None:
+        self._trash_path(key).unlink(missing_ok=True)
+
+    def trash_url(self, key: str) -> str:
+        return str(self._trash_path(key))