add database inspect chunk and chunk group commands

Author: Fallen-Breath

lang/en_us.yml

@@ -213,14 +213,30 @@ prime_backup:
       title: 'Blob {}'
       id: 'ID: {}'
       storage_method: 'Storage method: {}'
-      hash: 'Hash: {}'
+      hash: 'Hash: {} ({})'
       compress: 'Compress: {}'
       raw_size: 'Raw size: {} ({})'
       stored_size: 'Stored size: {} ({})'
       chunk_count: 'Chunk group count: {}; Chunk count: {}, samples:'
       chunk_sample: 'offset={}, len={}, hash={}'
       used_by: 'Associated file count: {}. Samples:'
       file_sample: 'fileset {}, path: {}'
+    db_inspect_chunk:
+      name: inspect chunk
+      title: 'Chunk {}'
+      id: 'ID: {}'
+      hash: 'Hash: {} ({})'
+      compress: 'Compress: {}'
+      raw_size: 'Raw size: {} ({})'
+      stored_size: 'Stored size: {} ({})'
+    db_inspect_chunk_group:
+      name: inspect chunk group
+      title: 'Chunk group {}'
+      id: 'ID: {}'
+      hash: 'Hash: {} ({})'
+      chunk_count: 'Chunk count: {}'
+      chunk_raw_size_sum: 'Chunk raw size sum: {} ({})'
+      chunk_stored_size_sum: 'Chunk stored size sum: {} ({})'
     db_inspect_file:
       name: inspect file
       title: 'File {1} in fileset {0}'
@@ -258,6 +274,7 @@ prime_backup:
         fileset_id: Click to inspect fileset {}
         blob_hash: Click to inspect blob {}
         chunk_hash: Click to inspect chunk {}
+        chunk_group_hash: Click to inspect chunk group {}
     db_migrate_compress_method:
       name: migrate compress method
       missing_library:
@@ -456,7 +473,9 @@ prime_backup:
           §7{prefix} database inspect file §6<backup_id> §3<file_path>§r: Inspect the internal data of the given file
           §7{prefix} database inspect file2 §3<fileset_id> §3<file_path>§r: Inspect the internal data of the given file in fileset
           §7{prefix} database inspect fileset §3<fileset_id>§r: Inspect the internal data of the given fileset
-          §7{prefix} database inspect blob §d<blob_hash>§r: Inspect the internal data of the given blob
+          §7{prefix} database inspect blob §d<id_or_hash>§r: Inspect the internal data of the given blob
+          §7{prefix} database inspect chunk §d<id_or_hash>§r: Inspect the internal data of the given chunk
+          §7{prefix} database inspect chunk_group §d<id_or_hash>§r: Inspect the internal data of the given chunk group
           §7{prefix} database delete file §6<backup_id> §3<file_path> §7[--recursive]§r: Delete given file in the given backup. If §7[--recursive]§r and it's a directory, delete everything inside it
           §7{prefix} database validate §a<part>§r: Validate the correctness of contents in the database. Might take a long time
           §7{prefix} database vacuum§r: Compact the SQLite database manually, to reduce the size of the database file
@@ -466,7 +485,7 @@ prime_backup:
           {scheduled_compact_notes}
           §d[Arguments]§r
           §3<file_path>§r: Path of the file related to the backup source root
-          §d<blob_hash>§r: Hash value of the blob. Can be a prefix of the hash string as long as it's unique
+          §d<id_or_hash>§r: The ID of the object, or the hash of the object. It can be a prefix of the hash string as long as it's unique
           §d<compress_method>§r: Available options: {compress_methods}
           §d<hash_method>§r: Available options: {hash_methods}
           §a<part>§r: 
@@ -582,8 +601,12 @@ prime_backup:
     blob_hash_not_unique.candidates: 'Found at least {} candidates: {}'
     chunk_id_not_found: Chunk with id {} does not exist
     chunk_hash_not_found: Chunk with hash {} does not exist
+    chunk_hash_not_unique: 'The given hash {} cannot uniquely identify a chunk'
+    chunk_hash_not_unique.candidates: 'Found at least {} candidates: {}'
     chunk_group_id_not_found: Chunk group with id {} does not exist
     chunk_group_hash_not_found: Chunk group with hash {} does not exist
+    chunk_group_hash_not_unique: 'The given hash {} cannot uniquely identify a chunk group'
+    chunk_group_hash_not_unique.candidates: 'Found at least {} candidates: {}'
     db_locked: Task {} execution error cuz the database is locked. Please retry later
     initializing: Plugin initializing
     disabled: Plugin disabled

lang/zh_cn.yml

@@ -213,14 +213,30 @@ prime_backup:
       title: '数据对象{}'
       id: 'ID: {}'
       storage_method: '存储方法: {}'
-      hash: '哈希: {}'
+      hash: '哈希: {} ({})'
       compress: '压缩方法: {}'
       raw_size: '原始大小: {} ({})'
       stored_size: '储存大小: {} ({})'
       chunk_count: '数据块组数: {}; 数据块数: {}, 样本：'
       chunk_sample: '偏移={}, 长度={}, 哈希={}'
       used_by: '关联文件数: {}。样本：'
       file_sample: '文件集{}, 路径: {}'
+    db_inspect_chunk:
+      name: 审查数据块
+      title: '数据块{}'
+      id: 'ID: {}'
+      hash: '哈希: {} ({})'
+      compress: '压缩方法: {}'
+      raw_size: '原始大小: {} ({})'
+      stored_size: '储存大小: {} ({})'
+    db_inspect_chunk_group:
+      name: 审查数据块组
+      title: '数据块组{}'
+      id: 'ID: {}'
+      hash: '哈希: {} ({})'
+      chunk_count: '数据块数: {}'
+      chunk_raw_size_sum: '数据块原始大小总和: {} ({})'
+      chunk_stored_size_sum: '数据块储存大小总和: {} ({})'
     db_inspect_file:
       name: 审查文件
       title: '文件集{0}的文件{1}'
@@ -257,7 +273,8 @@ prime_backup:
         backup_id: 点击以审查备份{}
         fileset_id: 点击以审查文件集{}
         blob_hash: 点击以审查数据对象{}
-        chunk_hash: 点击以审查数据块对象{}
+        chunk_hash: 点击以审查数据块{}
+        chunk_group_hash: 点击以审查数据块组{}
     db_migrate_compress_method:
       name: 压缩方法迁移
       missing_library:
@@ -456,7 +473,9 @@ prime_backup:
           §7{prefix} database inspect file §6<备份ID> §3<文件路径>§r: 审查给定文件的原始信息
           §7{prefix} database inspect file2 §3<文件集ID> §3<文件路径>§r: 审查给定文件集中文件的原始信息
           §7{prefix} database inspect fileset §3<文件集ID>§r: 审查给定文件集的原始信息
-          §7{prefix} database inspect blob §d<哈希值>§r: 审查给定数据对象的原始信息
+          §7{prefix} database inspect blob §d<ID或哈希>§r: 审查给定数据对象的原始信息
+          §7{prefix} database inspect chunk §d<ID或哈希>§r: 审查给定数据块的原始信息
+          §7{prefix} database inspect chunk_group §d<ID或哈希>§r: 审查给定数据块组的原始信息
           §7{prefix} database delete file §6<备份ID> §3<文件路径> §7[--recursive]§r: 删除给定备份中的某个文件。若带有§7--recursive§r且目标为文件夹，则递归删除其内部的所有内容
           §7{prefix} database validate §a<组件>§r: 验证数据库内容的正确性。耗时可能较长
           §7{prefix} database vacuum§r: 手动执行SQLite数据库的文件整理操作，减少数据库文件的体积
@@ -466,7 +485,7 @@ prime_backup:
           {scheduled_compact_notes}
           §d【参数帮助】§r
           §3<文件路径>§r: 要审查的文件的路径，相对备份根目录
-          §d<哈希值>§r: 要审查的数据对象的哈希值。可以是哈希串的前缀，只要唯一即可
+          §d<ID或哈希>§r: 要审查的对象的ID或哈希值。也可谓哈希串的前缀，只要确保唯一即可
           §d<压缩方法>§r: 可用选项: {compress_methods}
           §d<哈希算法>§r: 可用选项: {hash_methods}
           §a<组件>§r:
@@ -582,8 +601,12 @@ prime_backup:
     blob_hash_not_unique.candidates: '找到了至少{}个可能的数据对象: {}'
     chunk_id_not_found: ID为{}的数据块不存在
     chunk_hash_not_found: 哈希值为{}的数据块不存在
+    chunk_hash_not_unique: '给定的哈希值{}无法唯一确定一个数据块'
+    chunk_hash_not_unique.candidates: '找到了至少{}个可能的数据块: {}'
     chunk_group_id_not_found: ID为{}的数据块组不存在
     chunk_group_hash_not_found: 哈希值为{}的数据块组不存在
+    chunk_group_hash_not_unique: '给定的哈希值{}无法唯一确定一个数据块组'
+    chunk_group_hash_not_unique.candidates: '找到了至少{}个可能的数据块组: {}'
     db_locked: 任务{}执行失败, 数据库已被锁定。请稍候再试
     initializing: 插件初始化中
     disabled: 插件已禁用

prime_backup/action/get_blob_action.py

@@ -71,5 +71,7 @@ def _do_get_blob(self, session: DbSession) -> schema.Blob:
 		if len(blobs) == 0:
 			raise BlobHashNotFound(self.blob_hash_prefix)
 		elif len(blobs) > 1:
-			raise BlobHashNotUnique(self.blob_hash_prefix, list(sorted(map(BlobInfo.of, blobs))))
+			def get_hash_for_sort(b: 'BlobInfo'):
+				return b.hash
+			raise BlobHashNotUnique(self.blob_hash_prefix, sorted(map(BlobInfo.of, blobs), key=get_hash_for_sort))
 		return blobs[0]

prime_backup/action/get_chunk_action.py

@@ -5,6 +5,7 @@
 
 from prime_backup.action import Action
 from prime_backup.db.access import DbAccess
+from prime_backup.exceptions import ChunkHashNotFound, ChunkHashNotUnique
 from prime_backup.types.chunk_info import OffsetChunkInfo, ChunkInfo
 
 
@@ -38,6 +39,27 @@ def run(self) -> ChunkInfo:
 			return ChunkInfo.of(chunk)
 
 
+class GetChunkByHashPrefixAction(Action[ChunkInfo]):
+	def __init__(self, chunk_hash_prefix: str):
+		super().__init__()
+		self.chunk_hash_prefix = chunk_hash_prefix
+
+	@override
+	def run(self) -> ChunkInfo:
+		"""
+		:raise: ChunkHashNotFound or ChunkHashNotUnique
+		"""
+		with DbAccess.open_session() as session:
+			chunks = session.list_chunk_with_hash_prefix(self.chunk_hash_prefix, limit=3)
+			if len(chunks) == 0:
+				raise ChunkHashNotFound(self.chunk_hash_prefix)
+			elif len(chunks) > 1:
+				def get_hash_for_sort(b: 'ChunkInfo'):
+					return b.hash
+				raise ChunkHashNotUnique(self.chunk_hash_prefix, sorted(map(ChunkInfo.of, chunks), key=get_hash_for_sort))
+			return ChunkInfo.of(chunks[0])
+
+
 class GetBlobChunksAction(Action[List[OffsetChunkInfo]]):
 	def __init__(self, blob_id: int, *, limit: Optional[int] = None):
 		super().__init__()

prime_backup/action/get_chunk_group_action.py

@@ -0,0 +1,57 @@
+from typing_extensions import override
+
+from prime_backup.action import Action
+from prime_backup.db.access import DbAccess
+from prime_backup.exceptions import ChunkHashNotFound, ChunkGroupHashNotUnique
+from prime_backup.types.chunk_group_info import ChunkGroupInfo
+
+
+class GetChunkGroupByIdAction(Action[ChunkGroupInfo]):
+	def __init__(self, chunk_group_id: int):
+		super().__init__()
+		self.chunk_group_id = chunk_group_id
+
+	@override
+	def run(self) -> ChunkGroupInfo:
+		"""
+		:raise: ChunkIdNotFound
+		"""
+		with DbAccess.open_session() as session:
+			chunk_group = session.get_chunk_group_by_id(self.chunk_group_id)
+			return ChunkGroupInfo.of(chunk_group)
+
+
+class GetChunkGroupByHashAction(Action[ChunkGroupInfo]):
+	def __init__(self, chunk_group_hash: str):
+		super().__init__()
+		self.chunk_group_hash = chunk_group_hash
+
+	@override
+	def run(self) -> ChunkGroupInfo:
+		"""
+		:raise: ChunkHashNotFound
+		"""
+		with DbAccess.open_session() as session:
+			chunk_group = session.get_chunk_group_by_hash(self.chunk_group_hash)
+			return ChunkGroupInfo.of(chunk_group)
+
+
+class GetChunkGroupByHashPrefixAction(Action[ChunkGroupInfo]):
+	def __init__(self, chunk_group_hash_prefix: str):
+		super().__init__()
+		self.chunk_group_hash_prefix = chunk_group_hash_prefix
+
+	@override
+	def run(self) -> ChunkGroupInfo:
+		"""
+		:raise: ChunkHashNotFound or ChunkHashNotUnique
+		"""
+		with DbAccess.open_session() as session:
+			chunk_groups = session.list_chunk_group_with_hash_prefix(self.chunk_group_hash_prefix, limit=3)
+			if len(chunk_groups) == 0:
+				raise ChunkHashNotFound(self.chunk_group_hash_prefix)
+			elif len(chunk_groups) > 1:
+				def get_hash_for_sort(b: 'ChunkGroupInfo'):
+					return b.hash
+				raise ChunkGroupHashNotUnique(self.chunk_group_hash_prefix, sorted(map(ChunkGroupInfo.of, chunk_groups), key=get_hash_for_sort))
+			return ChunkGroupInfo.of(chunk_groups[0])

prime_backup/db/session.py

@@ -14,7 +14,7 @@
 
 from prime_backup.db import schema, db_constants
 from prime_backup.db.values import FileRole, BackupTagDict, OffsetChunk, OffsetChunkGroup, BlobStorageMethod, ChunkGroupChunkBindingIdentifier, BlobChunkGroupBindingIdentifier, FileIdentifier
-from prime_backup.exceptions import BackupNotFound, BackupFileNotFound, BlobHashNotFound, PrimeBackupError, FilesetNotFound, FilesetFileNotFound, BlobIdNotFound, ChunkHashNotFound, ChunkIdNotFound, ChunkGroupChunkBindingNotFound, BlobChunkGroupBindingNotFound
+from prime_backup.exceptions import BackupNotFound, BackupFileNotFound, BlobHashNotFound, PrimeBackupError, FilesetNotFound, FilesetFileNotFound, BlobIdNotFound, ChunkHashNotFound, ChunkIdNotFound, ChunkGroupChunkBindingNotFound, BlobChunkGroupBindingNotFound, ChunkGroupIdNotFound, ChunkGroupHashNotFound
 from prime_backup.types.backup_filter import BackupFilter, BackupTagFilter, BackupSortOrder
 from prime_backup.utils import collection_utils, db_utils, validation_utils
 
@@ -380,6 +380,10 @@ def list_chunks(self, limit: Optional[int] = None, offset: Optional[int] = None)
 			s = s.offset(offset)
 		return _list_it(self.session.execute(s).scalars().all())
 
+	def list_chunk_with_hash_prefix(self, hash_prefix: str, limit: int) -> List[schema.Chunk]:
+		s = select(schema.Chunk).where(schema.Chunk.hash.startswith(hash_prefix, autoescape=True)).limit(limit)
+		return _list_it(self.session.execute(s).scalars().all())
+
 	def iterate_chunk_batch(self, *, batch_size: int) -> Iterator[List[schema.Chunk]]:
 		limit, offset = batch_size, 0
 		while True:
@@ -430,11 +434,26 @@ def create_and_add_chunk_group(self, **kwargs: Unpack[CreateChunkGroupKwargs]) -
 	def get_chunk_group_count(self) -> int:
 		return _int_or_0(self.session.execute(select(func.count()).select_from(schema.ChunkGroup)).scalar_one())
 
-	def get_chunk_group_opt(self, h: str) -> Optional[schema.ChunkGroup]:
+	def get_chunk_group_by_id_opt(self, chunk_group_id: int) -> Optional[schema.ChunkGroup]:
+		return self.session.get(schema.ChunkGroup, chunk_group_id)
+
+	def get_chunk_group_by_id(self, chunk_group_id: int) -> schema.ChunkGroup:
+		chunk_group = self.get_chunk_group_by_id_opt(chunk_group_id)
+		if chunk_group is None:
+			raise ChunkGroupIdNotFound(chunk_group_id)
+		return chunk_group
+
+	def get_chunk_group_by_hash_opt(self, h: str) -> Optional[schema.ChunkGroup]:
 		return self.session.execute(
 	        select(schema.ChunkGroup).where(schema.ChunkGroup.hash == h)
 	    ).scalars().one_or_none()
 
+	def get_chunk_group_by_hash(self, h: str) -> schema.ChunkGroup:
+		chunk_group = self.get_chunk_group_by_hash_opt(h)
+		if chunk_group is None:
+			raise ChunkGroupHashNotFound(h)
+		return chunk_group
+
 	def get_chunk_groups_by_ids(self, chunk_group_ids: List[int]) -> Dict[int, Optional[schema.ChunkGroup]]:
 		"""
 		:return: a dict, id -> optional chunk group. All given ids are in the dict
@@ -463,6 +482,10 @@ def list_chunk_groups(self, limit: Optional[int] = None, offset: Optional[int] =
 			s = s.offset(offset)
 		return _list_it(self.session.execute(s).scalars().all())
 
+	def list_chunk_group_with_hash_prefix(self, hash_prefix: str, limit: int) -> List[schema.ChunkGroup]:
+		s = select(schema.ChunkGroup).where(schema.ChunkGroup.hash.startswith(hash_prefix, autoescape=True)).limit(limit)
+		return _list_it(self.session.execute(s).scalars().all())
+
 	def iterate_chunk_group_batch(self, *, batch_size: int) -> Iterator[List[schema.ChunkGroup]]:
 		limit, offset = batch_size, 0
 		while True:

prime_backup/exceptions.py

@@ -2,6 +2,8 @@
 
 if TYPE_CHECKING:
 	from prime_backup.types.blob_info import BlobInfo
+	from prime_backup.types.chunk_group_info import ChunkGroupInfo
+	from prime_backup.types.chunk_info import ChunkInfo
 
 
 class PrimeBackupError(Exception):
@@ -81,6 +83,13 @@ def __init__(self, chunk_hash: str):
 		self.chunk_hash = chunk_hash
 
 
+class ChunkHashNotUnique(PrimeBackupError):
+	def __init__(self, chunk_hash_prefix: str, candidates: List['ChunkInfo']):
+		super().__init__()
+		self.chunk_hash_prefix = chunk_hash_prefix
+		self.candidates = candidates
+
+
 class ChunkGroupNotFound(PrimeBackupError):
 	pass
 
@@ -97,6 +106,13 @@ def __init__(self, chunk_group_hash: str):
 		self.chunk_group_hash = chunk_group_hash
 
 
+class ChunkGroupHashNotUnique(PrimeBackupError):
+	def __init__(self, chunk_group_hash_prefix: str, candidates: List['ChunkGroupInfo']):
+		super().__init__()
+		self.chunk_group_hash_prefix = chunk_group_hash_prefix
+		self.candidates = candidates
+
+
 class ChunkGroupChunkBindingNotFound(PrimeBackupError):
 	def __init__(self, chunk_group_id: int, chunk_offset: int):
 		super().__init__()