from abc import ABC, abstractmethod from uuid import UUID from domain import ( AttachmentSchema, NewAttachmentSchema, StoredAttachmentSchema, UnfinishedUploadSchema, ) class AttachmentRepository(ABC): """ Слой абстракции метаданных вложений — источника истины о том, какие объекты S3 принадлежат приложению. Инвариант: у каждого объекта под ORIGINAL_OBJECT_PREFIX есть строка (pending, ready или deleting). Строка записывается до PUT в S3, а удаляется только после удаления объекта. """ @abstractmethod async def create_pending(self, attachment: NewAttachmentSchema) -> UUID: """ Намерение загрузки фиксируется до записи в S3: если процесс упадёт после PUT, объект не останется неучтённым. """ pass @abstractmethod async def mark_ready( self, attachment_id: UUID, grace_seconds: int ) -> AttachmentSchema | None: """ Подтверждение загрузки: pending → ready. None, если строка уже не pending или старше grace period: janitor мог забрать её на очистку, такая загрузка подтверждаться не должна. """ pass @abstractmethod async def claim_pending(self, attachment_id: UUID) -> UnfinishedUploadSchema | None: """ Компенсация неудачной загрузки: pending → deleting. None, если строка уже не pending (подтверждена или забрана janitor). """ pass @abstractmethod async def claim_unfinished( self, grace_seconds: int, limit: int ) -> list[UnfinishedUploadSchema]: """ Сверка: pending старше grace period переводятся в deleting; вместе с ними возвращаются ранее забранные deleting — их очистку повторяют. """ pass @abstractmethod async def list_unfinished( self, grace_seconds: int, limit: int ) -> list[UnfinishedUploadSchema]: """То же, что claim_unfinished, но без изменения строк (dry-run)""" pass @abstractmethod async def delete_claimed(self, attachment_ids: list[UUID]) -> int: """Удаление строк deleting, чьи объекты уже удалены из S3""" pass @abstractmethod async def get_for_member( self, attachment_id: UUID, member_id: UUID ) -> StoredAttachmentSchema | None: """ Готовое вложение, только если пользователь — участник его чата. """ pass @abstractmethod async def find_known_keys(self, object_keys: list[str]) -> set[str]: """Ключи из списка, у которых есть строка в любом состоянии""" pass