stash

backend/files/models.py

@@ -43,15 +43,7 @@ class FileManager(models.Manager):
         else:
             raise ValueError('data must be a base64 encoded string or file and hash must be provided')
         if not self.filter(hash=kwargs['hash']).exists():
-            # The upload path is derived entirely from the hash (hash_upload, above), and hash
-            # is DB-unique - so if no File row owns this hash yet, anything already sitting at
-            # its computed path is necessarily a stale orphan (e.g. left behind by a bug in
-            # cleanup code that deleted a File row without removing its stored bytes, or a
-            # crashed upload). Clear it before saving instead of letting Django's storage layer
-            # invent an alternate filename to avoid the "collision" - a suffixed name would
-            # silently break every part of the app that derives this file's URL purely from its
-            # hash (media serving, thumbnail generation, item/avatar attachment), and no future
-            # caller could ever discover it again.
+            # Clears a stale orphan already at this hash's canonical path before saving. See docs/implementation.md#stale-orphan-cleanup-at-the-canonical-hash-path.
             expected_path = hash_upload(SimpleNamespace(hash=kwargs['hash']), '')
             if default_storage.exists(expected_path):
                 default_storage.delete(expected_path)