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

file_hub_client/rpc/sync_client.py

@@ -0,0 +1,313 @@
+"""
+同步gRPC客户端
+"""
+import threading
+from enum import Enum
+
+import grpc
+import time
+import uuid
+import platform
+import socket
+from typing import Optional, Dict, List, Tuple
+
+from ..enums import Role
+from ..errors import ConnectionError
+from ..schemas.context import UserContext, RequestContext, FullContext
+
+
+class SyncGrpcClient:
+    """同步gRPC客户端基类"""
+
+    def __init__(
+            self,
+            host: str = "localhost",
+            port: int = 50051,
+            secure: bool = False,
+            credentials: Optional[dict] = None,
+            options: Optional[list] = None,
+            retry_count: int = 3,
+            retry_delay: float = 1.0,
+            default_metadata: Optional[Dict[str, str]] = None,
+            user_context: Optional[UserContext] = None,
+            request_context: Optional[RequestContext] = None,
+    ):
+        """
+        初始化同步gRPC客户端
+        
+        Args:
+            host: 服务器地址
+            port: 服务器端口
+            secure: 是否使用安全连接（TLS）
+            credentials: 认证凭据字典（如 {'api_key': 'xxx'}）
+            options: gRPC通道选项
+            retry_count: 连接重试次数
+            retry_delay: 重试延迟（秒）
+            default_metadata: 默认的元数据（如 org_id, user_id 等）
+            user_context: 用户上下文
+            request_context: 请求上下文
+        """
+        self.host = host
+        self.port = port
+        self.address = f"{host}:{port}"
+        self.secure = secure
+        self.credentials = credentials
+        self.options = options or []
+        self.retry_count = retry_count
+        self.retry_delay = retry_delay
+        self.default_metadata = default_metadata or {}
+        self._channel: Optional[grpc.Channel] = None
+        self._stubs = {}
+        self._stub_lock = threading.Lock()
+
+        # 上下文管理
+        self._user_context = user_context
+        self._request_context = request_context or self._create_default_request_context()
+
+        # 如果提供了user_context，将其添加到default_metadata
+        if self._user_context:
+            self.default_metadata.update(self._user_context.to_metadata())
+
+        # 添加请求上下文到default_metadata
+        self.default_metadata.update(self._request_context.to_metadata())
+
+    def _create_default_request_context(self) -> RequestContext:
+        """创建默认的请求上下文"""
+        # 尝试获取客户端IP
+        client_ip = None
+        try:
+            # 获取本机IP（适用于内网环境）
+            hostname = socket.gethostname()
+            client_ip = socket.gethostbyname(hostname)
+        except:
+            pass
+
+        # 获取客户端信息
+        return RequestContext(
+            client_ip=client_ip,
+            client_type="python-sdk",
+            client_version="1.0.0",  # TODO: 从包版本获取
+            user_agent=f"FileHubClient/1.0.0 Python/{platform.python_version()} {platform.system()}/{platform.release()}"
+        )
+
+    def _create_channel_credentials(self) -> Optional[grpc.ChannelCredentials]:
+        """创建通道凭据"""
+        if not self.secure:
+            return None
+
+        # 使用默认的SSL凭据
+        channel_credentials = grpc.ssl_channel_credentials()
+
+        # 如果有API密钥，创建组合凭据
+        if self.credentials and 'api_key' in self.credentials:
+            # 创建元数据凭据
+            def metadata_callback(context, callback):
+                metadata = [('authorization', f"Bearer {self.credentials['api_key']}")]
+                callback(metadata, None)
+
+            call_credentials = grpc.metadata_call_credentials(metadata_callback)
+            channel_credentials = grpc.composite_channel_credentials(
+                channel_credentials,
+                call_credentials
+            )
+
+        return channel_credentials
+
+    def connect(self):
+        """连接到gRPC服务器（带重试）"""
+        if self._channel is not None:
+            return
+
+        last_error = None
+        for attempt in range(self.retry_count):
+            try:
+                if attempt > 0:
+                    time.sleep(self.retry_delay)
+
+                channel_credentials = self._create_channel_credentials()
+
+                if channel_credentials:
+                    self._channel = grpc.secure_channel(
+                        self.address,
+                        channel_credentials,
+                        options=self.options
+                    )
+                else:
+                    self._channel = grpc.insecure_channel(
+                        self.address,
+                        options=self.options
+                    )
+
+                # 连接
+                try:
+                    grpc.channel_ready_future(self._channel).result(timeout=5.0)
+                except grpc.FutureTimeoutError:
+                    raise ConnectionError(f"连接超时：{self.address}")
+
+                # 连接成功
+                return
+
+            except Exception as e:
+                last_error = e
+                if attempt < self.retry_count - 1:
+                    print(f"连接失败 (尝试 {attempt + 1}/{self.retry_count}): {str(e)}")
+                    if self._channel:
+                        self._channel.close()
+                        self._channel = None
+                else:
+                    # 最后一次尝试失败
+                    if self._channel:
+                        self._channel.close()
+                        self._channel = None
+
+        # 所有重试都失败
+        raise ConnectionError(
+            f"无法连接到gRPC服务器 {self.address} (尝试了 {self.retry_count} 次): {str(last_error)}"
+        )
+
+    def close(self):
+        """关闭连接"""
+        if self._channel:
+            self._channel.close()
+            self._channel = None
+            self._stubs.clear()
+
+    def get_stub(self, stub_class):
+        """
+        获取gRPC stub实例
+        
+        Args:
+            stub_class: Stub类
+            
+        Returns:
+            Stub实例
+        """
+        if not self._channel:
+            raise ConnectionError("未连接到gRPC服务器")
+
+        stub_name = stub_class.__name__
+        with self._stub_lock:
+            if stub_name not in self._stubs:
+                self._stubs[stub_name] = stub_class(self._channel)
+            return self._stubs[stub_name]
+
+    def build_metadata(self, **kwargs) -> List[Tuple[str, str]]:
+        """
+        构建请求元数据
+        
+        Args:
+            **kwargs: 要覆盖或添加的元数据
+            
+        Returns:
+            元数据列表
+        """
+        metadata = {}
+
+        # 添加默认元数据
+        metadata.update(self.default_metadata)
+
+        # 添加/覆盖传入的元数据
+        metadata.update(kwargs)
+
+        # 如果没有 request_id，自动生成一个
+        if 'x-request-id' not in metadata:
+            metadata['x-request-id'] = (
+                    self._request_context.extra.get("request_id") or str(uuid.uuid4())
+            )
+
+        # 转换为 gRPC 需要的格式
+        result = []
+        for k, v in metadata.items():
+            if v is None:
+                continue
+            if isinstance(v, Enum):
+                v = v.value
+            result.append((k, str(v)))
+
+        return result
+
+    def update_default_metadata(self, **kwargs):
+        """
+        更新默认元数据
+        
+        Args:
+            **kwargs: 要更新的元数据键值对
+        """
+        self.default_metadata.update(kwargs)
+
+    def set_user_context(self, org_id: str, user_id: str, role: Role = Role.ACCOUNT, actor_id: Optional[str] = None):
+        """
+        设置用户上下文信息
+        
+        Args:
+            org_id: 组织ID
+            user_id: 用户ID
+            role: 用户角色（默认为 ACCOUNT）
+            actor_id: 操作者ID（如果不同于 user_id）
+        """
+        self._user_context = UserContext(
+            org_id=org_id,
+            user_id=user_id,
+            role=role,
+            actor_id=actor_id
+        )
+        # 更新到默认元数据
+        self.update_default_metadata(**self._user_context.to_metadata())
+
+    def get_user_context(self) -> Optional[UserContext]:
+        """获取当前用户上下文"""
+        return self._user_context
+
+    def clear_user_context(self):
+        """清除用户上下文信息"""
+        self._user_context = None
+        for key in ['x-org-id', 'x-user-id', 'x-role', 'x-actor-id']:
+            self.default_metadata.pop(key, None)
+
+    def set_request_context(self, request_context: RequestContext):
+        """设置请求上下文"""
+        self._request_context = request_context
+        # 更新到默认元数据
+        self.update_default_metadata(**self._request_context.to_metadata())
+
+    def get_request_context(self) -> RequestContext:
+        """获取当前请求上下文"""
+        return self._request_context
+
+    def update_request_context(self, **kwargs):
+        """
+        更新请求上下文的部分字段
+        
+        Args:
+            **kwargs: 要更新的字段
+        """
+        if kwargs.get('client_ip'):
+            self._request_context.client_ip = kwargs['client_ip']
+        if kwargs.get('client_version'):
+            self._request_context.client_version = kwargs['client_version']
+        if kwargs.get('client_type'):
+            self._request_context.client_type = kwargs['client_type']
+        if kwargs.get('user_agent'):
+            self._request_context.user_agent = kwargs['user_agent']
+
+        # 处理extra字段
+        extra = kwargs.get('extra')
+        if extra and isinstance(extra, dict):
+            self._request_context.extra.update(extra)
+
+        # 更新到默认元数据
+        self.update_default_metadata(**self._request_context.to_metadata())
+
+    def get_full_context(self) -> FullContext:
+        """获取完整的上下文信息"""
+        return FullContext(
+            user_context=self._user_context,
+            request_context=self._request_context
+        )
+
+    def __enter__(self) -> "SyncGrpcClient":
+        self.connect()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()

file_hub_client/schemas/__init__.py

@@ -0,0 +1,43 @@
+"""
+数据模型定义
+"""
+from .file import (
+    File,
+    UploadFile,
+    FileUploadResponse,
+    UploadUrlResponse,
+    ShareLinkRequest,
+    FileVisitRequest,
+    FileListRequest,
+    FileListResponse,
+)
+from .folder import (
+    FolderInfo,
+    FolderListResponse,
+)
+from .context import (
+    UserContext,
+    RequestContext,
+    FullContext,
+)
+
+__all__ = [
+    # 文件相关
+    "File",
+    "UploadFile",
+    "FileUploadResponse",
+    "UploadUrlResponse",
+    "ShareLinkRequest",
+    "FileVisitRequest",
+    "FileListRequest",
+    "FileListResponse",
+
+    # 文件夹相关
+    "FolderInfo",
+    "FolderListResponse",
+
+    # 上下文相关
+    "UserContext",
+    "RequestContext",
+    "FullContext",
+]

file_hub_client/schemas/context.py

@@ -0,0 +1,160 @@
+"""
+用户上下文和请求上下文相关的Schema定义
+"""
+from dataclasses import dataclass, field
+from typing import Optional, Dict, Any
+from datetime import datetime
+
+from file_hub_client.enums import Role
+
+
+@dataclass
+class UserContext:
+    """
+    用户上下文信息
+    
+    包含两大类信息：
+    1. ownership（所有权）: org_id, user_id - 表示资源归属
+    2. operator（操作者）: actor_id, role - 表示实际操作者（可能是用户、agent或系统）
+    """
+    # Ownership - 资源所有权信息
+    org_id: str  # 组织ID
+    user_id: str  # 用户ID
+
+    # Operator - 操作者信息
+    actor_id: Optional[str] = None  # 实际操作者ID（如果为空，默认使用user_id）
+    role: Role = Role.ACCOUNT  # 操作者角色（ACCOUNT, AGENT, SYSTEM等）
+
+    def __post_init__(self):
+        """初始化后处理，如果actor_id为空，默认使用user_id"""
+        if self.actor_id is None:
+            self.actor_id = self.user_id
+
+    def to_metadata(self) -> Dict[str, str]:
+        """转换为gRPC metadata格式"""
+        return {
+            'x-org-id': self.org_id,
+            'x-user-id': self.user_id,
+            'x-actor-id': self.actor_id,
+            'x-role': self.role,
+        }
+
+    @classmethod
+    def from_metadata(cls, metadata: Dict[str, str]) -> Optional['UserContext']:
+        """从metadata中解析用户上下文"""
+        org_id = metadata.get('x-org-id')
+        user_id = metadata.get('x-user-id')
+
+        if not org_id or not user_id:
+            return None
+
+        return cls(
+            org_id=org_id,
+            user_id=user_id,
+            actor_id=metadata.get('x-actor-id'),
+            role=Role(metadata.get('x-role', Role.ACCOUNT))
+        )
+
+
+@dataclass
+class RequestContext:
+    """
+    请求上下文信息
+    
+    包含请求相关的元数据，如客户端信息、请求追踪等
+    """
+    request_id: Optional[str] = None  # 请求ID，用于追踪
+    client_ip: Optional[str] = None  # 客户端IP地址
+    client_version: Optional[str] = None  # 客户端版本
+    client_type: Optional[str] = None  # 客户端类型（web, mobile, desktop, cli等）
+    user_agent: Optional[str] = None  # User-Agent信息
+    timestamp: Optional[datetime] = field(default_factory=datetime.now)  # 请求时间戳
+    extra: Dict[str, Any] = field(default_factory=dict)  # 其他扩展信息
+
+    def to_metadata(self) -> Dict[str, str]:
+        """转换为gRPC metadata格式"""
+        metadata = {}
+
+        if self.request_id:
+            metadata['x-request-id'] = self.request_id
+        if self.client_ip:
+            metadata['x-client-ip'] = self.client_ip
+        if self.client_version:
+            metadata['x-client-version'] = self.client_version
+        if self.client_type:
+            metadata['x-client-type'] = self.client_type
+        if self.user_agent:
+            metadata['x-user-agent'] = self.user_agent
+        if self.timestamp:
+            metadata['x-timestamp'] = self.timestamp.isoformat()
+
+        # 添加扩展信息
+        for key, value in self.extra.items():
+            metadata[f'x-{key}'] = str(value)
+
+        return metadata
+
+    @classmethod
+    def from_metadata(cls, metadata: Dict[str, str]) -> 'RequestContext':
+        """从metadata中解析请求上下文"""
+        # 提取标准字段
+        request_id = metadata.get('x-request-id')
+        client_ip = metadata.get('x-client-ip')
+        client_version = metadata.get('x-client-version')
+        client_type = metadata.get('x-client-type')
+        user_agent = metadata.get('x-user-agent')
+
+        # 解析时间戳
+        timestamp = None
+        if 'x-timestamp' in metadata:
+            try:
+                timestamp = datetime.fromisoformat(metadata['x-timestamp'])
+            except:
+                pass
+
+        # 提取扩展字段
+        extra = {}
+        for key, value in metadata.items():
+            if key.startswith('x-') and key not in [
+                'x-request-id', 'x-client-ip', 'x-client-version',
+                'x-client-type', 'x-user-agent', 'x-timestamp',
+                'x-org-id', 'x-user-id', 'x-actor-id', 'x-role'
+            ]:
+                extra[key[2:]] = value  # 去掉 'x-' 前缀
+
+        return cls(
+            request_id=request_id,
+            client_ip=client_ip,
+            client_version=client_version,
+            client_type=client_type,
+            user_agent=user_agent,
+            timestamp=timestamp,
+            extra=extra
+        )
+
+
+@dataclass
+class FullContext:
+    """完整的上下文信息，包含用户上下文和请求上下文"""
+    user_context: Optional[UserContext] = None
+    request_context: Optional[RequestContext] = None
+
+    def to_metadata(self) -> Dict[str, str]:
+        """转换为gRPC metadata格式"""
+        metadata = {}
+
+        if self.user_context:
+            metadata.update(self.user_context.to_metadata())
+
+        if self.request_context:
+            metadata.update(self.request_context.to_metadata())
+
+        return metadata
+
+    @classmethod
+    def from_metadata(cls, metadata: Dict[str, str]) -> 'FullContext':
+        """从metadata中解析完整上下文"""
+        return cls(
+            user_context=UserContext.from_metadata(metadata),
+            request_context=RequestContext.from_metadata(metadata)
+        )

file_hub_client/schemas/file.py

@@ -0,0 +1,89 @@
+"""
+文件相关数据模型
+"""
+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="文件列表")

file_hub_client/schemas/folder.py

@@ -0,0 +1,29 @@
+"""
+文件夹相关数据模型
+"""
+from datetime import datetime
+from typing import List
+from pydantic import BaseModel, Field
+
+
+class FolderInfo(BaseModel):
+    """文件夹信息模型"""
+    id: str = Field(..., description="文件夹ID")
+    org_id: str = Field(..., description="组织ID")
+    user_id: str = Field(..., description="用户ID")
+    folder_name: str = Field(..., description="文件夹名称")
+    parent_id: str = Field(..., description="父文件夹ID")
+    created_by: str = Field(..., description="创建者")
+    created_by_role: str = Field(..., description="创建者角色")
+    created_at: datetime = Field(..., description="创建时间")
+    updated_at: datetime = Field(..., description="更新时间")
+
+    class Config:
+        json_encoders = {
+            datetime: lambda v: v.isoformat()
+        }
+
+
+class FolderListResponse(BaseModel):
+    """文件夹列表响应"""
+    items: List[FolderInfo] = Field(default_factory=list, description="文件夹列表")

file_hub_client/services/__init__.py

@@ -0,0 +1,17 @@
+"""
+服务模块
+"""
+from .file import AsyncBlobService, AsyncFileService, SyncBlobService, SyncFileService
+from .folder import AsyncFolderService, SyncFolderService
+
+__all__ = [
+    # 文件服务
+    "AsyncBlobService",
+    "AsyncFileService",
+    "SyncBlobService",
+    "SyncFileService",
+
+    # 文件夹服务
+    "AsyncFolderService",
+    "SyncFolderService",
+]

file_hub_client/services/file/__init__.py

@@ -0,0 +1,14 @@
+"""
+文件服务模块
+"""
+from .async_blob_service import AsyncBlobService
+from .async_file_service import AsyncFileService
+from .sync_blob_service import SyncBlobService
+from .sync_file_service import SyncFileService
+
+__all__ = [
+    "AsyncBlobService",
+    "AsyncFileService",
+    "SyncBlobService",
+    "SyncFileService",
+]