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

file_hub_client/schemas/file.py

@@ -1,126 +1,171 @@
-"""
-文件相关数据模型
-"""
-from datetime import datetime
-from typing import Optional, Dict, List, Any
-from pydantic import BaseModel, Field
-
-
-class File(BaseModel):
-    """文件信息模型"""
-    id: str = Field(..., description="文件ID")
-    folder_id: str = Field(..., description="所属文件夹ID")
-    file_name: str = Field(..., description="原始文件名")
-    file_type: str = Field(..., description="文件类型")
-    created_at: datetime = Field(..., description="创建时间")
-    updated_at: datetime = Field(..., description="更新时间")
-
-    class Config:
-        json_encoders = {
-            datetime: lambda v: v.isoformat()
-        }
-
-
-class UploadFile(BaseModel):
-    """上传文件信息模型"""
-    id: str = Field(..., description="上传文件ID")
-    folder_id: str = Field(..., description="所属文件夹ID")
-    storage_type: str = Field(..., description="存储类型")
-    stored_name: str = Field(..., description="存储文件名")
-    stored_path: str = Field(..., description="存储路径")
-    file_id: str = Field(..., description="所属文件ID")
-    file_name: str = Field(..., description="原始文件名")
-    file_size: int = Field(0, description="文件大小（字节）")
-    file_ext: str = Field(..., description="文件后缀")
-    mime_type: str = Field(..., description="MIME类型")
-    created_at: datetime = Field(..., description="创建时间")
-    updated_at: datetime = Field(..., description="更新时间")
-
-    class Config:
-        json_encoders = {
-            datetime: lambda v: v.isoformat()
-        }
-
-
-class FileUploadResponse(BaseModel):
-    """文件上传返回"""
-    file: File = Field(..., description="文件信息")
-    upload_file: UploadFile = Field(..., description="上传文件信息")
-
-
-class UploadUrlResponse(BaseModel):
-    """上传URL响应"""
-    file: File = Field(..., description="文件信息")
-    upload_file: UploadFile = Field(..., description="上传文件信息")
-    upload_url: str = Field(..., description="上传URL")
-
-
-class ShareLinkRequest(BaseModel):
-    """生成分享链接请求"""
-    file_id: str = Field(..., description="文件ID")
-    is_public: bool = Field(True, description="是否公开")
-    access_scope: str = Field("view", description="访问范围")
-    expire_seconds: int = Field(86400, description="过期时间（秒）")
-    max_access: Optional[int] = Field(None, description="最大访问次数")
-    password: Optional[str] = Field(None, description="访问密码")
-
-
-class FileVisitRequest(BaseModel):
-    """文件访问请求"""
-    file_share_id: str = Field(..., description="分享ID")
-    access_type: str = Field(..., description="访问类型")
-    access_duration: int = Field(..., description="访问时长")
-    metadata: Dict[str, Any] = Field(default_factory=dict, description="元数据")
-
-
-class FileListRequest(BaseModel):
-    """文件列表请求"""
-    folder_id: str = Field(..., description="文件夹ID")
-    file_name: Optional[str] = Field(None, description="文件名")
-    file_type: Optional[List[str]] = Field(None, description="文件类型")
-    created_by_role: Optional[str] = Field(None, description="创建者角色")
-    created_by: Optional[str] = Field(None, description="创建者")
-    page_size: int = Field(20, description="每页大小")
-    page: int = Field(1, description="页码")
-
-
-class FileListResponse(BaseModel):
-    """文件列表响应"""
-    files: List[File] = Field(default_factory=list, description="文件列表")
-
-
-class GetFileResponse(BaseModel):
-    """获取文件响应"""
-    file: File = Field(..., description="文件信息")
-    upload_file: Optional[UploadFile] = Field(None, description="上传文件信息")
-
-
-class DownloadUrlInfo(BaseModel):
-    """下载URL信息"""
-    file_id: str = Field(..., description="文件ID")
-    url: str = Field(..., description="下载URL")
-    error: Optional[str] = Field(None, description="错误信息")
-
-
-class BatchDownloadUrlResponse(BaseModel):
-    """批量下载URL响应"""
-    download_urls: List[DownloadUrlInfo] = Field(default_factory=list, description="下载URL列表")
-
-
-class GcsUrlInfo(BaseModel):
-    """GCS URL信息"""
-    file_id: str = Field(..., description="文件ID")
-    gcs_url: str = Field(..., description="GCS URL")
-    mime_type: str = Field(..., description="MIME类型")
-    error: Optional[str] = Field(None, description="错误信息")
-
-
-class GetGcsUrlResponse(BaseModel):
-    """获取GCS URL响应"""
-    gcs_url: str = Field(..., description="GCS URL")
-    mime_type: str = Field(..., description="MIME类型")
-
-
-class BatchGcsUrlResponse(BaseModel):
-    """批量GCS URL响应"""
-    gcs_urls: List[GcsUrlInfo] = Field(default_factory=list, description="GCS URL列表")
+"""
+文件相关数据模型
+"""
+from datetime import datetime
+from typing import Optional, Dict, List, Any
+from pydantic import BaseModel, Field
+
+
+class File(BaseModel):
+    """文件信息模型"""
+    id: str = Field(..., description="文件ID")
+    folder_id: str = Field(..., description="所属文件夹ID")
+    file_name: str = Field(..., description="原始文件名")
+    file_type: str = Field(..., description="文件类型")
+    created_at: datetime = Field(..., description="创建时间")
+    updated_at: datetime = Field(..., description="更新时间")
+
+    class Config:
+        json_encoders = {
+            datetime: lambda v: v.isoformat()
+        }
+
+
+class UploadFile(BaseModel):
+    """上传文件信息模型"""
+    id: str = Field(..., description="上传文件ID")
+    folder_id: str = Field(..., description="所属文件夹ID")
+    storage_type: str = Field(..., description="存储类型")
+    stored_name: str = Field(..., description="存储文件名")
+    stored_path: str = Field(..., description="存储路径")
+    file_id: str = Field(..., description="所属文件ID")
+    file_name: str = Field(..., description="原始文件名")
+    file_size: int = Field(0, description="文件大小（字节）")
+    file_ext: str = Field(..., description="文件后缀")
+    mime_type: str = Field(..., description="MIME类型")
+    created_at: datetime = Field(..., description="创建时间")
+    updated_at: datetime = Field(..., description="更新时间")
+
+    class Config:
+        json_encoders = {
+            datetime: lambda v: v.isoformat()
+        }
+
+
+class FileUploadResponse(BaseModel):
+    """文件上传返回"""
+    file: File = Field(..., description="文件信息")
+    upload_file: UploadFile = Field(..., description="上传文件信息")
+
+
+class UploadUrlResponse(BaseModel):
+    """上传URL响应"""
+    file: File = Field(..., description="文件信息")
+    upload_file: UploadFile = Field(..., description="上传文件信息")
+    upload_url: str = Field(..., description="上传URL")
+
+
+class ShareLinkRequest(BaseModel):
+    """生成分享链接请求"""
+    file_id: str = Field(..., description="文件ID")
+    is_public: bool = Field(True, description="是否公开")
+    access_scope: str = Field("view", description="访问范围")
+    expire_seconds: int = Field(86400, description="过期时间（秒）")
+    max_access: Optional[int] = Field(None, description="最大访问次数")
+    password: Optional[str] = Field(None, description="访问密码")
+
+
+class FileVisitRequest(BaseModel):
+    """文件访问请求"""
+    file_share_id: str = Field(..., description="分享ID")
+    access_type: str = Field(..., description="访问类型")
+    access_duration: int = Field(..., description="访问时长")
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="元数据")
+
+
+class FileListRequest(BaseModel):
+    """文件列表请求"""
+    folder_id: str = Field(..., description="文件夹ID")
+    file_name: Optional[str] = Field(None, description="文件名")
+    file_type: Optional[List[str]] = Field(None, description="文件类型")
+    created_by_role: Optional[str] = Field(None, description="创建者角色")
+    created_by: Optional[str] = Field(None, description="创建者")
+    page_size: int = Field(20, description="每页大小")
+    page: int = Field(1, description="页码")
+
+
+class FileListResponse(BaseModel):
+    """文件列表响应"""
+    files: List[File] = Field(default_factory=list, description="文件列表")
+
+
+class GetFileResponse(BaseModel):
+    """获取文件响应"""
+    file: File = Field(..., description="文件信息")
+    upload_file: Optional[UploadFile] = Field(None, description="上传文件信息")
+
+
+class DownloadUrlInfo(BaseModel):
+    """下载URL信息"""
+    file_id: str = Field(..., description="文件ID")
+    url: str = Field(..., description="下载URL")
+    mime_type: str = Field(..., description="MIME类型")
+    error: Optional[str] = Field(None, description="错误信息")
+
+
+class BatchDownloadUrlResponse(BaseModel):
+    """批量下载URL响应"""
+    download_urls: List[DownloadUrlInfo] = Field(default_factory=list, description="下载URL列表")
+
+
+class GcsUrlInfo(BaseModel):
+    """GCS URL信息"""
+    file_id: str = Field(..., description="文件ID")
+    gcs_url: str = Field(..., description="GCS URL")
+    mime_type: str = Field(..., description="MIME类型")
+    error: Optional[str] = Field(None, description="错误信息")
+
+
+class GetGcsUrlResponse(BaseModel):
+    """获取GCS URL响应"""
+    gcs_url: str = Field(..., description="GCS URL")
+    mime_type: str = Field(..., description="MIME类型")
+
+
+class BatchGcsUrlResponse(BaseModel):
+    """批量GCS URL响应"""
+    gcs_urls: List[GcsUrlInfo] = Field(default_factory=list, description="GCS URL列表")
+
+
+# ========= 压缩服务相关模型 =========
+
+class CompressedVariant(BaseModel):
+    """压缩变体信息"""
+    variant_name: str = Field(..., description="变体名称")
+    variant_type: str = Field(..., description="变体类型")
+    media_type: str = Field(..., description="媒体类型")
+    width: int = Field(..., description="宽度")
+    height: int = Field(..., description="高度")
+    file_size: int = Field(..., description="文件大小")
+    format: str = Field(..., description="格式")
+    quality: Optional[int] = Field(None, description="质量")
+    duration: Optional[float] = Field(None, description="时长")
+    bitrate: Optional[int] = Field(None, description="比特率")
+    fps: Optional[int] = Field(None, description="帧率")
+    compression_ratio: float = Field(..., description="压缩比")
+    stored_path: str = Field(..., description="存储路径")
+
+
+class CompressionStatusResponse(BaseModel):
+    """压缩状态响应"""
+    status: str = Field(..., description="状态: pending, processing, completed, failed")
+    error_message: Optional[str] = Field(None, description="错误信息")
+    variants: List[CompressedVariant] = Field(default_factory=list, description="压缩变体列表")
+
+
+class GetVariantsResponse(BaseModel):
+    """获取变体响应"""
+    variants: List[CompressedVariant] = Field(default_factory=list, description="压缩变体列表")
+
+
+class RecompressionResponse(BaseModel):
+    """重新压缩响应"""
+    task_id: str = Field(..., description="任务ID")
+    status: str = Field(..., description="状态")
+
+
+class VariantDownloadUrlResponse(BaseModel):
+    """变体下载URL响应"""
+    url: str = Field(..., description="下载URL")
+    error: Optional[str] = Field(None, description="错误信息")
+    variant_info: Optional[CompressedVariant] = Field(None, description="变体详细信息")

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],
@@ -631,6 +670,7 @@ class AsyncBlobService(BaseFileService):
             download_urls.append(DownloadUrlInfo(
                 file_id=url_info.file_id,
                 url=url_info.url,
+                mime_type=url_info.mime_type,
                 error=url_info.error if url_info.HasField('error') else None
             ))
 
@@ -710,3 +750,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
+        )