tamar-file-hub-client 0.1.3__py3-none-any.whl → 0.1.4__py3-none-any.whl

file_hub_client/services/file/async_blob_service.py

@@ -11,7 +11,7 @@ from .base_file_service import BaseFileService
 from ...enums import UploadMode
 from ...errors import ValidationError
 from ...rpc import AsyncGrpcClient
-from ...schemas import FileUploadResponse, UploadUrlResponse, BatchDownloadUrlResponse, DownloadUrlInfo, GcsUrlInfo, GetGcsUrlResponse, BatchGcsUrlResponse
+from ...schemas import FileUploadResponse, UploadUrlResponse, BatchDownloadUrlResponse, DownloadUrlInfo, GcsUrlInfo, GetGcsUrlResponse, BatchGcsUrlResponse, CompressionStatusResponse, GetVariantsResponse, RecompressionResponse, VariantDownloadUrlResponse, CompressedVariant
 from ...utils import AsyncHttpUploader, AsyncHttpDownloader, retry_with_backoff, get_file_mime_type
 
 
@@ -121,7 +121,7 @@ class AsyncBlobService(BaseFileService):
             request_id: Optional[str] = None,
             **metadata
     ) -> FileUploadResponse:
-        """流式上传"""
+        """流式上传（GCS 直传）"""
 
         # 获取上传URL，以及对应的文件和上传文件信息
         upload_url_resp = await self.generate_upload_url(
@@ -145,11 +145,17 @@ class AsyncBlobService(BaseFileService):
                 upload_file=upload_url_resp.upload_file
             )
 
+        # 构建HTTP头，包含Content-Type和固定的Cache-Control
+        headers = {
+            "Content-Type": mime_type,
+            "Cache-Control": "public, max-age=86400"  # 24小时公共缓存
+        }
+
         # 上传文件到对象存储
         await self.http_uploader.upload(
             url=upload_url_resp.upload_url,
             content=content,
-            headers={"Content-Type": mime_type},
+            headers=headers,
             total_size=file_size,
         )
 
@@ -181,7 +187,8 @@ class AsyncBlobService(BaseFileService):
             request_id: Optional[str] = None,
             **metadata
     ) -> FileUploadResponse:
-        """断点续传实现"""
+        """断点续传实现（GCS 直传）"""
+        
         # 获取断点续传URL，以及对应的文件和上传文件信息
         upload_url_resp = await self.generate_resumable_upload_url(
             file_name=file_name,
@@ -204,6 +211,12 @@ class AsyncBlobService(BaseFileService):
                 upload_file=upload_url_resp.upload_file
             )
 
+        # 构建HTTP头，包含Content-Type和固定的Cache-Control
+        headers = {
+            "Content-Type": mime_type,
+            "Cache-Control": "public, max-age=86400"  # 24小时公共缓存
+        }
+
         # 开启断点续传
         upload_url = await self.http_uploader.start_resumable_session(
             url=upload_url_resp.upload_url,
@@ -215,7 +228,7 @@ class AsyncBlobService(BaseFileService):
         await self.http_uploader.upload(
             url=upload_url,
             content=content,
-            headers={"Content-Type": mime_type},
+            headers=headers,
             total_size=file_size,
         )
 
@@ -413,6 +426,8 @@ class AsyncBlobService(BaseFileService):
             
         Note:
             必须提供 file 或 url 参数之一
+            
+            Cache-Control 头在 GCS 直传模式（STREAM/RESUMABLE）下自动设置为 "public, max-age=86400"
         """
         # 参数验证：必须提供 file 或 url 之一
         if file is None and not url:
@@ -468,7 +483,7 @@ class AsyncBlobService(BaseFileService):
 
         # 根据上传模式执行不同的上传逻辑
         if mode == UploadMode.NORMAL:
-            # 普通上传（通过gRPC）
+            # 普通上传（通过gRPC）- 不需要 Cache-Control
             return await self._upload_file(
                 file_name=extracted_file_name,
                 content=content,
@@ -483,7 +498,7 @@ class AsyncBlobService(BaseFileService):
             )
 
         elif mode == UploadMode.STREAM:
-            # 流式上传（目前使用直传实现）
+            # 流式上传（目前使用直传实现）- 需要 Cache-Control
             return await self._upload_stream(
                 file_name=extracted_file_name,
                 content=content,
@@ -500,7 +515,7 @@ class AsyncBlobService(BaseFileService):
             )
 
         elif mode == UploadMode.RESUMABLE:
-            # 断点续传
+            # 断点续传 - 需要 Cache-Control
             return await self._upload_resumable(
                 file_name=extracted_file_name,
                 content=content,
@@ -588,6 +603,30 @@ class AsyncBlobService(BaseFileService):
             chunk_size=chunk_size,
         )
 
+    async def download_to_bytes(
+            self,
+            file_id: str,
+            *,
+            request_id: Optional[str] = None,
+            **metadata
+    ) -> bytes:
+        """
+        下载文件并返回字节数据
+
+        Args:
+            file_id: 文件ID
+            request_id: 请求ID（可选，如果不提供则自动生成）
+            **metadata: 额外的元数据
+
+        Returns:
+            文件的字节数据
+        """
+        # 获取下载URL
+        download_url = await self.generate_download_url(file_id, request_id=request_id, **metadata)
+
+        # 下载到内存并返回字节数据
+        return await self.http_downloader.download(url=download_url, save_path=None)
+
     async def batch_generate_download_url(
             self,
             file_ids: List[str],
@@ -710,3 +749,215 @@ class AsyncBlobService(BaseFileService):
             ))
 
         return BatchGcsUrlResponse(gcs_urls=gcs_urls)
+
+    async def get_compression_status(
+            self,
+            file_id: str,
+            *,
+            request_id: Optional[str] = None,
+            **metadata
+    ) -> CompressionStatusResponse:
+        """
+        获取文件压缩状态
+        
+        Args:
+            file_id: 文件ID
+            request_id: 请求ID，用于追踪
+            **metadata: 额外的gRPC元数据
+            
+        Returns:
+            CompressionStatusResponse: 压缩状态响应
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+        
+        stub = await self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+        
+        request = file_service_pb2.CompressionStatusRequest(file_id=file_id)
+        
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(request_id=request_id, **metadata)
+        
+        response = await stub.GetCompressionStatus(request, metadata=grpc_metadata)
+        
+        # 转换压缩变体
+        variants = []
+        for variant in response.variants:
+            variants.append(CompressedVariant(
+                variant_name=variant.variant_name,
+                variant_type=variant.variant_type,
+                media_type=variant.media_type,
+                width=variant.width,
+                height=variant.height,
+                file_size=variant.file_size,
+                format=variant.format,
+                quality=variant.quality if variant.quality else None,
+                duration=variant.duration if variant.duration else None,
+                bitrate=variant.bitrate if variant.bitrate else None,
+                fps=variant.fps if variant.fps else None,
+                compression_ratio=variant.compression_ratio,
+                stored_path=variant.stored_path
+            ))
+        
+        return CompressionStatusResponse(
+            status=response.status,
+            error_message=response.error_message if response.error_message else None,
+            variants=variants
+        )
+
+    async def get_compressed_variants(
+            self,
+            file_id: str,
+            *,
+            variant_type: Optional[str] = None,
+            request_id: Optional[str] = None,
+            **metadata
+    ) -> GetVariantsResponse:
+        """
+        获取文件的压缩变体
+        
+        Args:
+            file_id: 文件ID
+            variant_type: 变体类型(image, video, thumbnail)
+            request_id: 请求ID，用于追踪
+            **metadata: 额外的gRPC元数据
+            
+        Returns:
+            GetVariantsResponse: 压缩变体响应
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+        
+        stub = await self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+        
+        request = file_service_pb2.GetVariantsRequest(file_id=file_id)
+        if variant_type:
+            request.variant_type = variant_type
+        
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(request_id=request_id, **metadata)
+        
+        response = await stub.GetCompressedVariants(request, metadata=grpc_metadata)
+        
+        # 转换压缩变体
+        variants = []
+        for variant in response.variants:
+            variants.append(CompressedVariant(
+                variant_name=variant.variant_name,
+                variant_type=variant.variant_type,
+                media_type=variant.media_type,
+                width=variant.width,
+                height=variant.height,
+                file_size=variant.file_size,
+                format=variant.format,
+                quality=variant.quality if variant.quality else None,
+                duration=variant.duration if variant.duration else None,
+                bitrate=variant.bitrate if variant.bitrate else None,
+                fps=variant.fps if variant.fps else None,
+                compression_ratio=variant.compression_ratio,
+                stored_path=variant.stored_path
+            ))
+        
+        return GetVariantsResponse(variants=variants)
+
+    async def trigger_recompression(
+            self,
+            file_id: str,
+            *,
+            force_reprocess: bool = False,
+            request_id: Optional[str] = None,
+            **metadata
+    ) -> RecompressionResponse:
+        """
+        触发文件重新压缩
+        
+        Args:
+            file_id: 文件ID
+            force_reprocess: 是否强制重新处理
+            request_id: 请求ID，用于追踪
+            **metadata: 额外的gRPC元数据
+            
+        Returns:
+            RecompressionResponse: 重新压缩响应
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+        
+        stub = await self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+        
+        request = file_service_pb2.RecompressionRequest(
+            file_id=file_id,
+            force_reprocess=force_reprocess
+        )
+        
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(request_id=request_id, **metadata)
+        
+        response = await stub.TriggerRecompression(request, metadata=grpc_metadata)
+        
+        return RecompressionResponse(
+            task_id=response.task_id,
+            status=response.status
+        )
+
+    async def generate_variant_download_url(
+            self,
+            file_id: str,
+            variant_name: str,
+            *,
+            expire_seconds: int = 3600,
+            is_cdn: bool = False,
+            request_id: Optional[str] = None,
+            **metadata
+    ) -> VariantDownloadUrlResponse:
+        """
+        生成变体下载URL
+        
+        Args:
+            file_id: 文件ID
+            variant_name: 变体名称(large/medium/small/thumbnail)
+            expire_seconds: 过期时间（秒）
+            is_cdn: 是否使用CDN
+            request_id: 请求ID，用于追踪
+            **metadata: 额外的gRPC元数据
+            
+        Returns:
+            VariantDownloadUrlResponse: 变体下载URL响应
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+        
+        stub = await self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+        
+        request = file_service_pb2.VariantDownloadUrlRequest(
+            file_id=file_id,
+            variant_name=variant_name,
+            expire_seconds=expire_seconds,
+            is_cdn=is_cdn
+        )
+        
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(request_id=request_id, **metadata)
+        
+        response = await stub.GenerateVariantDownloadUrl(request, metadata=grpc_metadata)
+        
+        # 转换变体信息
+        variant_info = None
+        if response.variant_info:
+            variant_info = CompressedVariant(
+                variant_name=response.variant_info.variant_name,
+                variant_type=response.variant_info.variant_type,
+                media_type=response.variant_info.media_type,
+                width=response.variant_info.width,
+                height=response.variant_info.height,
+                file_size=response.variant_info.file_size,
+                format=response.variant_info.format,
+                quality=response.variant_info.quality if response.variant_info.quality else None,
+                duration=response.variant_info.duration if response.variant_info.duration else None,
+                bitrate=response.variant_info.bitrate if response.variant_info.bitrate else None,
+                fps=response.variant_info.fps if response.variant_info.fps else None,
+                compression_ratio=response.variant_info.compression_ratio,
+                stored_path=response.variant_info.stored_path
+            )
+        
+        return VariantDownloadUrlResponse(
+            url=response.url,
+            error=response.error if response.error else None,
+            variant_info=variant_info
+        )

file_hub_client/services/file/async_file_service.py

@@ -12,6 +12,11 @@ from ...schemas import (
     File,
     FileListResponse,
     GetFileResponse,
+    CompressionStatusResponse,
+    GetVariantsResponse,
+    RecompressionResponse,
+    VariantDownloadUrlResponse,
+    CompressedVariant,
 )
 from ...errors import FileNotFoundError
 
@@ -275,3 +280,215 @@ class AsyncFileService(BaseFileService):
         files = [self._convert_file_info(f) for f in response.files]
 
         return FileListResponse(files=files)
+
+    async def get_compression_status(
+            self,
+            file_id: str,
+            *,
+            request_id: Optional[str] = None,
+            **metadata
+    ) -> CompressionStatusResponse:
+        """
+        获取文件压缩状态
+        
+        Args:
+            file_id: 文件ID
+            request_id: 请求ID，用于追踪
+            **metadata: 额外的gRPC元数据
+            
+        Returns:
+            CompressionStatusResponse: 压缩状态响应
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+        
+        stub = await self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+        
+        request = file_service_pb2.CompressionStatusRequest(file_id=file_id)
+        
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(request_id=request_id, **metadata)
+        
+        response = await stub.GetCompressionStatus(request, metadata=grpc_metadata)
+        
+        # 转换压缩变体
+        variants = []
+        for variant in response.variants:
+            variants.append(CompressedVariant(
+                variant_name=variant.variant_name,
+                variant_type=variant.variant_type,
+                media_type=variant.media_type,
+                width=variant.width,
+                height=variant.height,
+                file_size=variant.file_size,
+                format=variant.format,
+                quality=variant.quality if variant.quality else None,
+                duration=variant.duration if variant.duration else None,
+                bitrate=variant.bitrate if variant.bitrate else None,
+                fps=variant.fps if variant.fps else None,
+                compression_ratio=variant.compression_ratio,
+                stored_path=variant.stored_path
+            ))
+        
+        return CompressionStatusResponse(
+            status=response.status,
+            error_message=response.error_message if response.error_message else None,
+            variants=variants
+        )
+
+    async def get_compressed_variants(
+            self,
+            file_id: str,
+            *,
+            variant_type: Optional[str] = None,
+            request_id: Optional[str] = None,
+            **metadata
+    ) -> GetVariantsResponse:
+        """
+        获取文件的压缩变体
+        
+        Args:
+            file_id: 文件ID
+            variant_type: 变体类型(image, video, thumbnail)
+            request_id: 请求ID，用于追踪
+            **metadata: 额外的gRPC元数据
+            
+        Returns:
+            GetVariantsResponse: 压缩变体响应
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+        
+        stub = await self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+        
+        request = file_service_pb2.GetVariantsRequest(file_id=file_id)
+        if variant_type:
+            request.variant_type = variant_type
+        
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(request_id=request_id, **metadata)
+        
+        response = await stub.GetCompressedVariants(request, metadata=grpc_metadata)
+        
+        # 转换压缩变体
+        variants = []
+        for variant in response.variants:
+            variants.append(CompressedVariant(
+                variant_name=variant.variant_name,
+                variant_type=variant.variant_type,
+                media_type=variant.media_type,
+                width=variant.width,
+                height=variant.height,
+                file_size=variant.file_size,
+                format=variant.format,
+                quality=variant.quality if variant.quality else None,
+                duration=variant.duration if variant.duration else None,
+                bitrate=variant.bitrate if variant.bitrate else None,
+                fps=variant.fps if variant.fps else None,
+                compression_ratio=variant.compression_ratio,
+                stored_path=variant.stored_path
+            ))
+        
+        return GetVariantsResponse(variants=variants)
+
+    async def trigger_recompression(
+            self,
+            file_id: str,
+            *,
+            force_reprocess: bool = False,
+            request_id: Optional[str] = None,
+            **metadata
+    ) -> RecompressionResponse:
+        """
+        触发文件重新压缩
+        
+        Args:
+            file_id: 文件ID
+            force_reprocess: 是否强制重新处理
+            request_id: 请求ID，用于追踪
+            **metadata: 额外的gRPC元数据
+            
+        Returns:
+            RecompressionResponse: 重新压缩响应
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+        
+        stub = await self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+        
+        request = file_service_pb2.RecompressionRequest(
+            file_id=file_id,
+            force_reprocess=force_reprocess
+        )
+        
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(request_id=request_id, **metadata)
+        
+        response = await stub.TriggerRecompression(request, metadata=grpc_metadata)
+        
+        return RecompressionResponse(
+            task_id=response.task_id,
+            status=response.status
+        )
+
+    async def generate_variant_download_url(
+            self,
+            file_id: str,
+            variant_name: str,
+            *,
+            expire_seconds: int = 3600,
+            is_cdn: bool = False,
+            request_id: Optional[str] = None,
+            **metadata
+    ) -> VariantDownloadUrlResponse:
+        """
+        生成变体下载URL
+        
+        Args:
+            file_id: 文件ID
+            variant_name: 变体名称(large/medium/small/thumbnail)
+            expire_seconds: 过期时间（秒）
+            is_cdn: 是否使用CDN
+            request_id: 请求ID，用于追踪
+            **metadata: 额外的gRPC元数据
+            
+        Returns:
+            VariantDownloadUrlResponse: 变体下载URL响应
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+        
+        stub = await self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+        
+        request = file_service_pb2.VariantDownloadUrlRequest(
+            file_id=file_id,
+            variant_name=variant_name,
+            expire_seconds=expire_seconds,
+            is_cdn=is_cdn
+        )
+        
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(request_id=request_id, **metadata)
+        
+        response = await stub.GenerateVariantDownloadUrl(request, metadata=grpc_metadata)
+        
+        # 转换变体信息
+        variant_info = None
+        if response.variant_info:
+            variant_info = CompressedVariant(
+                variant_name=response.variant_info.variant_name,
+                variant_type=response.variant_info.variant_type,
+                media_type=response.variant_info.media_type,
+                width=response.variant_info.width,
+                height=response.variant_info.height,
+                file_size=response.variant_info.file_size,
+                format=response.variant_info.format,
+                quality=response.variant_info.quality if response.variant_info.quality else None,
+                duration=response.variant_info.duration if response.variant_info.duration else None,
+                bitrate=response.variant_info.bitrate if response.variant_info.bitrate else None,
+                fps=response.variant_info.fps if response.variant_info.fps else None,
+                compression_ratio=response.variant_info.compression_ratio,
+                stored_path=response.variant_info.stored_path
+            )
+        
+        return VariantDownloadUrlResponse(
+            url=response.url,
+            error=response.error if response.error else None,
+            variant_info=variant_info
+        )