tamar-file-hub-client 0.0.1__py3-none-any.whl

file_hub_client/services/file/async_blob_service.py

@@ -0,0 +1,482 @@
+"""
+异步二进制大对象服务
+"""
+import asyncio
+
+from pathlib import Path
+from typing import Optional, Union, BinaryIO, AsyncIterator
+
+from .base_file_service import BaseFileService
+from ...enums import UploadMode
+from ...errors import ValidationError
+from ...rpc import AsyncGrpcClient
+from ...schemas import FileUploadResponse, UploadUrlResponse
+from ...utils import AsyncHttpUploader, AsyncHttpDownloader, retry_with_backoff, get_file_mime_type
+
+
+class AsyncBlobService(BaseFileService):
+    """异步文件（二进制大对象）服务"""
+
+    def __init__(self, client: AsyncGrpcClient):
+        """
+        初始化文件（二进制大对象）服务
+
+        Args:
+            client: 异步gRPC客户端
+        """
+        self.client = client
+        self.http_uploader = AsyncHttpUploader()
+        self.http_downloader = AsyncHttpDownloader()
+
+    async def _generate_resumable_upload_url(
+            self,
+            file_name: str,
+            file_size: int,
+            folder_id: Optional[str] = None,
+            file_type: str = "file",
+            mime_type: Optional[str] = None,
+            file_hash: Optional[str] = None,
+            is_temporary: Optional[bool] = False,
+            expire_seconds: Optional[int] = None,
+            **metadata
+    ) -> UploadUrlResponse:
+        """
+        生成断点续传URL
+
+        Args:
+            file_name: 文件名
+            file_size: 文件大小
+            folder_id: 文件夹ID
+            file_type: 文件类型
+            mime_type: MIME类型
+            file_hash: 文件哈希
+            is_temporary: 是否为临时文件
+            expire_seconds: 过期秒数
+            **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
+
+        Returns:
+            上传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.UploadUrlRequest(
+            file_name=file_name,
+            file_size=file_size,
+            file_type=file_type,
+            mime_type=mime_type or "application/octet-stream",
+            file_hash=file_hash,
+            is_temporary=is_temporary,
+            expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
+        )
+
+        if folder_id:
+            request.folder_id = folder_id
+
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(**metadata)
+
+        response = await stub.GenerateResumableUploadUrl(request, metadata=grpc_metadata)
+
+        return UploadUrlResponse(
+            file=self._convert_file_info(response.file),
+            upload_file=self._convert_upload_file_info(response.upload_file),
+            upload_url=response.url
+        )
+
+    async def _confirm_upload_completed(self, file_id: str, **metadata) -> None:
+        """
+        确认上传完成
+
+        Args:
+            file_id: 文件ID
+            **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
+        """
+        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.UploadCompletedRequest(file_id=file_id)
+
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(**metadata)
+
+        await stub.ConfirmUploadCompleted(request, metadata=grpc_metadata)
+
+    @retry_with_backoff(max_retries=3)
+    async def _upload_file(
+            self,
+            file_name: str,
+            content: Union[bytes, BinaryIO, Path],
+            folder_id: Optional[str] = None,
+            file_type: str = "file",
+            mime_type: Optional[str] = None,
+            is_temporary: Optional[bool] = False,
+            expire_seconds: Optional[int] = None,
+            **metadata
+    ) -> FileUploadResponse:
+        """
+        普通上传
+
+        Args:
+            file_name: 文件名
+            content: 文件内容（字节、文件对象或路径）
+            folder_id: 文件夹ID
+            file_type: 文件类型
+            mime_type: MIME类型
+            is_temporary: 是否为临时文件
+            expire_seconds: 过期秒数
+            **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
+
+        Returns:
+            文件信息
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+
+        stub = await self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+
+        # 处理不同类型的内容
+        if isinstance(content, Path):
+            if not content.exists():
+                raise ValidationError(f"文件不存在: {content}")
+            with open(content, "rb") as f:
+                file_bytes = f.read()
+            if not mime_type:
+                mime_type = get_file_mime_type(content)
+        elif isinstance(content, bytes):
+            file_bytes = content
+        elif hasattr(content, 'read'):
+            file_bytes = content.read()
+        else:
+            raise ValidationError("不支持的内容类型")
+
+        # 构建请求
+        request = file_service_pb2.UploadFileRequest(
+            file_name=file_name,
+            content=file_bytes,
+            file_type=file_type,
+            mime_type=mime_type or "application/octet-stream",
+            is_temporary=is_temporary,
+            expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
+        )
+
+        if folder_id:
+            request.folder_id = folder_id
+
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(**metadata)
+
+        # 发送请求
+        response = await stub.UploadFile(request, metadata=grpc_metadata)
+
+        # 转换响应
+        return FileUploadResponse(
+            file=self._convert_file_info(response.file),
+            upload_file=self._convert_upload_file_info(response.upload_file),
+        )
+
+    async def _upload_stream(
+            self,
+            file_name: str,
+            content: Union[bytes, BinaryIO, Path],
+            file_size: int,
+            folder_id: Optional[str],
+            file_type: str,
+            mime_type: str,
+            file_hash: str,
+            is_temporary: Optional[bool] = False,
+            expire_seconds: Optional[int] = None,
+            **metadata
+    ) -> FileUploadResponse:
+        """流式上传"""
+
+        # 获取上传URL，以及对应的文件和上传文件信息
+        upload_url_resp = await self.generate_upload_url(
+            file_name=file_name,
+            file_size=file_size,
+            folder_id=folder_id,
+            file_type=file_type,
+            mime_type=mime_type,
+            file_hash=file_hash,
+            is_temporary=is_temporary,
+            expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
+            **metadata
+        )
+
+        # 上传文件到对象存储
+        await self.http_uploader.upload(
+            url=upload_url_resp.upload_url,
+            content=content,
+            headers={"Content-Type": mime_type},
+            total_size=file_size,
+        )
+
+        # 确认上传完成
+        await self._confirm_upload_completed(
+            file_id=upload_url_resp.file.id,
+            **metadata
+        )
+
+        # 返回文件信息
+        return FileUploadResponse(
+            file=upload_url_resp.file,
+            upload_file=upload_url_resp.upload_file
+        )
+
+    async def _upload_resumable(
+            self,
+            file_name: str,
+            content: Union[bytes, BinaryIO, Path],
+            file_size: int,
+            folder_id: Optional[str],
+            file_type: str,
+            mime_type: str,
+            file_hash: str,
+            is_temporary: Optional[bool] = False,
+            expire_seconds: Optional[int] = None,
+            **metadata
+    ) -> FileUploadResponse:
+        """断点续传实现"""
+        # 获取断点续传URL，以及对应的文件和上传文件信息
+        upload_url_resp = await self._generate_resumable_upload_url(
+            file_name=file_name,
+            file_size=file_size,
+            folder_id=folder_id,
+            file_type=file_type,
+            mime_type=mime_type,
+            file_hash=file_hash,
+            is_temporary=is_temporary,
+            expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
+            **metadata
+        )
+
+        # 开启断点续传
+        upload_url = await self.http_uploader.start_resumable_session(
+            url=upload_url_resp.upload_url,
+            total_file_size=file_size,
+            mine_type=mime_type,
+        )
+
+        # 上传文件到对象存储
+        await self.http_uploader.upload(
+            url=upload_url,
+            content=content,
+            headers={"Content-Type": mime_type},
+            total_size=file_size,
+        )
+
+        # 确认上传完成
+        await self._confirm_upload_completed(
+            file_id=upload_url_resp.file.id,
+            **metadata
+        )
+
+        # 获取文件信息
+        return FileUploadResponse(
+            file=upload_url_resp.file,
+            upload_file=upload_url_resp.upload_file
+        )
+
+    async def generate_upload_url(
+            self,
+            file_name: str,
+            file_size: int,
+            folder_id: str = None,
+            file_type: str = "file",
+            mime_type: str = None,
+            file_hash: str = None,
+            is_temporary: Optional[bool] = False,
+            expire_seconds: Optional[int] = None,
+            **metadata
+    ) -> UploadUrlResponse:
+        """
+        生成上传URL（用于客户端直传）
+
+        Args:
+            file_name: 文件名
+            file_size: 文件大小
+            folder_id: 文件夹ID
+            file_type: 文件类型
+            mime_type: MIME类型
+            file_hash: 文件哈希
+            is_temporary: 是否为临时文件
+            expire_seconds: 过期秒数
+            **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
+
+        Returns:
+            上传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.UploadUrlRequest(
+            file_name=file_name,
+            file_size=file_size,
+            file_type=file_type,
+            mime_type=mime_type or "application/octet-stream",
+            file_hash=file_hash,
+            is_temporary=is_temporary,
+            expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
+        )
+
+        if folder_id:
+            request.folder_id = folder_id
+
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(**metadata)
+
+        response = await stub.GenerateUploadUrl(request, metadata=grpc_metadata)
+
+        return UploadUrlResponse(
+            file=self._convert_file_info(response.file),
+            upload_file=self._convert_upload_file_info(response.upload_file),
+            upload_url=response.url
+        )
+
+    async def upload(
+            self,
+            file: Union[str, Path, BinaryIO, bytes],
+            *,
+            folder_id: Optional[str] = None,
+            mode: Optional[UploadMode] = UploadMode.NORMAL,
+            is_temporary: Optional[bool] = False,
+            expire_seconds: Optional[int] = None,
+            **metadata
+    ) -> FileUploadResponse:
+        """
+        统一的文件上传接口
+
+        Args:
+            file: 文件路径、Path对象、文件对象或字节数据
+            folder_id: 目标文件夹ID（可选）
+            mode: 上传模式（NORMAL/DIRECT/RESUMABLE/STREAM）
+            is_temporary: 是否为临时文件
+            expire_seconds: 过期秒数
+            **metadata: 额外的元数据
+
+        Returns:
+            文件信息
+        """
+        # 解析文件参数，提取文件信息
+        file_name, content, file_size, mime_type, file_type, file_hash = self._extract_file_info(file)
+
+        # 根据文件大小自动选择上传模式
+        if mode == UploadMode.NORMAL:
+            ten_mb = 1024 * 1024 * 10
+            hundred_mb = 1024 * 1024 * 100
+            if file_size >= ten_mb and file_size < hundred_mb:  # 10MB
+                mode = UploadMode.STREAM  # 大文件自动使用流式上传模式
+            elif file_size > hundred_mb:
+                mode = UploadMode.RESUMABLE  # 特大文件自动使用断点续传模式
+
+        # 根据上传模式执行不同的上传逻辑
+        if mode == UploadMode.NORMAL:
+            # 普通上传（通过gRPC）
+            return await self._upload_file(
+                file_name=file_name,
+                content=content,
+                folder_id=folder_id,
+                file_type=file_type,
+                mime_type=mime_type,
+                is_temporary=is_temporary,
+                expire_seconds=expire_seconds,
+                **metadata
+            )
+
+        elif mode == UploadMode.STREAM:
+            # 流式上传（目前使用直传实现）
+            return await self._upload_stream(
+                file_name=file_name,
+                content=content,
+                file_size=file_size,
+                folder_id=folder_id,
+                file_type=file_type,
+                mime_type=mime_type,
+                file_hash=file_hash,
+                is_temporary=is_temporary,
+                expire_seconds=expire_seconds,
+                **metadata
+            )
+
+        elif mode == UploadMode.RESUMABLE:
+            # 断点续传
+            return await self._upload_resumable(
+                file_name=file_name,
+                content=content,
+                file_size=file_size,
+                folder_id=folder_id,
+                file_type=file_type,
+                mime_type=mime_type,
+                file_hash=file_hash,
+                is_temporary=is_temporary,
+                expire_seconds=expire_seconds,
+                **metadata
+            )
+
+        else:
+            raise ValidationError(f"不支持的上传模式: {mode}")
+
+    async def generate_download_url(
+            self,
+            file_id: str,
+            *,
+            expire_seconds: Optional[int] = None,
+            **metadata
+    ) -> str:
+        """
+        生成下载信息
+
+        Args:
+            file_id: 文件ID
+            expire_seconds: 过期时间（秒）
+            **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
+
+        Returns:
+            下载信息
+        """
+        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.DownloadUrlRequest(file_id=file_id,
+                                                      expire_seconds=expire_seconds if expire_seconds else None)
+
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(**metadata)
+
+        download_url_resp = await stub.GenerateDownloadUrl(request, metadata=grpc_metadata)
+
+        return download_url_resp.url
+
+    async def download(
+            self,
+            file_id: str,
+            *,
+            save_path: Optional[Union[str, Path]] = None,
+            chunk_size: Optional[int] = None,
+            **metadata
+    ) -> Union[bytes, Path, AsyncIterator[bytes]]:
+        """
+        统一的文件下载接口
+
+        Args:
+            file_id: 文件ID
+            save_path: 保存路径（如果为None，返回字节数据）
+            chunk_size: 分片大小（用于流式下载）
+            **metadata: 额外的元数据
+
+        Returns:
+            - NORMAL模式：下载的内容（字节）或保存的文件路径
+            - STREAM模式：返回异步迭代器，逐块返回数据
+        """
+
+        # 获取下载URL
+        download_url = await self.generate_download_url(file_id, **metadata)
+
+        return await self.http_downloader.download(
+            url=download_url,
+            save_path=save_path,
+            chunk_size=chunk_size,
+        )