isa-common 0.1.0__py3-none-any.whl

isa_common/__init__.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""
+gRPC Clients Package
+统一的 gRPC 客户端接口
+
+使用示例:
+    from core.clients import get_client, SupabaseClient, MinIOClient
+    
+    # 方式 1: 使用工厂函数
+    supabase = get_client('supabase', user_id='user_123')
+    
+    # 方式 2: 直接实例化
+    minio = MinIOClient(host='localhost', port=50051, user_id='user_123')
+    
+    # 方式 3: 使用 with 语句自动管理连接
+    with SupabaseClient() as client:
+        client.query('users', select='*')
+"""
+
+from typing import Optional, Dict
+from .base_client import BaseGRPCClient
+from .supabase_client import SupabaseClient
+from .minio_client import MinIOClient
+from .duckdb_client import DuckDBClient
+from .mqtt_client import MQTTClient
+from .nats_client import NATSClient
+
+# Import events module (but don't unpack, keep as submodule)
+from . import events
+
+# 导出所有客户端
+__all__ = [
+    'BaseGRPCClient',
+    'SupabaseClient',
+    'MinIOClient',
+    'DuckDBClient',
+    'MQTTClient',
+    'NATSClient',
+    'get_client',
+    'ClientFactory',
+    'events',  # Export events submodule
+]
+
+# 默认配置
+DEFAULT_PORTS: Dict[str, int] = {
+    'minio': 50051,
+    'duckdb': 50052,
+    'mqtt': 50053,
+    'loki': 50054,
+    'redis': 50055,
+    'nats': 50056,
+    'supabase': 50057,
+}
+
+DEFAULT_HOST = 'localhost'
+
+
+class ClientFactory:
+    """gRPC 客户端工厂"""
+    
+    # 客户端映射
+    _clients = {
+        'supabase': SupabaseClient,
+        'minio': MinIOClient,
+        'duckdb': DuckDBClient,
+        'mqtt': MQTTClient,
+        'nats': NATSClient,
+        # TODO: 添加其他客户端
+        # 'redis': RedisClient,
+        # 'loki': LokiClient,
+    }
+    
+    @classmethod
+    def create(cls, service_name: str, host: Optional[str] = None, 
+               port: Optional[int] = None, user_id: Optional[str] = None) -> BaseGRPCClient:
+        """
+        创建 gRPC 客户端
+        
+        Args:
+            service_name: 服务名称 (supabase, minio, duckdb, etc.)
+            host: 服务地址 (默认: localhost)
+            port: 服务端口 (默认: 根据服务自动选择)
+            user_id: 用户 ID
+        
+        Returns:
+            客户端实例
+        
+        Raises:
+            ValueError: 如果服务名称不支持
+        
+        示例:
+            client = ClientFactory.create('supabase', user_id='user_123')
+            client = ClientFactory.create('minio', host='192.168.1.100', port=50051)
+        """
+        service_name = service_name.lower()
+        
+        if service_name not in cls._clients:
+            available = ', '.join(cls._clients.keys())
+            raise ValueError(f"不支持的服务: {service_name}. 可用服务: {available}")
+        
+        # 使用默认值
+        if host is None:
+            host = DEFAULT_HOST
+        if port is None:
+            port = DEFAULT_PORTS.get(service_name, 50051)
+        
+        client_class = cls._clients[service_name]
+        return client_class(host=host, port=port, user_id=user_id)
+    
+    @classmethod
+    def register_client(cls, service_name: str, client_class):
+        """
+        注册新的客户端类
+        
+        Args:
+            service_name: 服务名称
+            client_class: 客户端类 (必须继承 BaseGRPCClient)
+        """
+        if not issubclass(client_class, BaseGRPCClient):
+            raise TypeError(f"{client_class} 必须继承 BaseGRPCClient")
+        
+        cls._clients[service_name.lower()] = client_class
+        print(f"✅ 注册客户端: {service_name} -> {client_class.__name__}")
+    
+    @classmethod
+    def list_services(cls) -> list:
+        """列出所有可用的服务"""
+        return list(cls._clients.keys())
+
+
+# 便捷函数
+def get_client(service_name: str, host: Optional[str] = None, 
+               port: Optional[int] = None, user_id: Optional[str] = None) -> BaseGRPCClient:
+    """
+    获取 gRPC 客户端 (便捷函数)
+    
+    Args:
+        service_name: 服务名称
+        host: 服务地址
+        port: 服务端口
+        user_id: 用户 ID
+    
+    Returns:
+        客户端实例
+    
+    示例:
+        from core.clients import get_client
+        
+        supabase = get_client('supabase', user_id='user_123')
+        minio = get_client('minio', host='192.168.1.100')
+    """
+    return ClientFactory.create(service_name, host, port, user_id)
+
+
+# 显示所有可用服务
+def show_available_services():
+    """显示所有可用的 gRPC 服务"""
+    print("📦 可用的 gRPC 服务:")
+    print()
+    for service in sorted(ClientFactory.list_services()):
+        port = DEFAULT_PORTS.get(service, 'N/A')
+        client_class = ClientFactory._clients[service]
+        print(f"  • {service:12} (端口: {port})  -> {client_class.__name__}")
+    print()
+
+
+if __name__ == '__main__':
+    # 显示可用服务
+    show_available_services()
+    
+    # 测试客户端创建
+    print("测试客户端创建:")
+    print("-" * 60)
+    
+    # 使用工厂创建客户端
+    with get_client('supabase', user_id='test_user') as supabase:
+        supabase.health_check()
+    
+    print()
+    
+    with get_client('minio', user_id='test_user') as minio:
+        minio.health_check()
+

isa_common/base_client.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""
+Base gRPC Client
+所有 gRPC 客户端的基类，提供统一的连接管理和错误处理
+"""
+
+import grpc
+import logging
+import threading
+from typing import Optional
+from abc import ABC, abstractmethod
+from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+
+class BaseGRPCClient(ABC):
+    """gRPC 客户端基类"""
+
+    def __init__(self, host: str = 'localhost', port: int = 50051, user_id: Optional[str] = None,
+                 lazy_connect: bool = True, enable_compression: bool = True, enable_retry: bool = True):
+        """
+        初始化 gRPC 客户端
+
+        Args:
+            host: 服务地址
+            port: 服务端口
+            user_id: 用户 ID (用于多租户隔离)
+            lazy_connect: 是否延迟连接 (默认: True, 更快的启动速度)
+            enable_compression: 是否启用 gRPC 压缩 (默认: True)
+            enable_retry: 是否启用重试逻辑 (默认: True)
+        """
+        self.host = host
+        self.port = port
+        self.user_id = user_id or 'default_user'
+        self.address = f'{host}:{port}'
+        self.enable_compression = enable_compression
+        self.enable_retry = enable_retry
+
+        # Lazy initialization
+        self.channel = None
+        self.stub = None
+        self._connect_lock = threading.Lock()
+        self._connected = False
+
+        # Connect immediately if not lazy
+        if not lazy_connect:
+            self._ensure_connected()
+    
+    def _ensure_connected(self):
+        """确保已连接（线程安全的延迟连接）"""
+        if self._connected and self.channel is not None:
+            return
+
+        with self._connect_lock:
+            # Double-check after acquiring lock
+            if self._connected and self.channel is not None:
+                return
+
+            logger.info(f"[{self.service_name()}] Connecting to {self.address}...")
+
+            # Build channel options
+            options = [
+                ('grpc.max_receive_message_length', 100 * 1024 * 1024),  # 100MB
+                ('grpc.max_send_message_length', 100 * 1024 * 1024),     # 100MB
+                ('grpc.keepalive_time_ms', 10000),
+                ('grpc.keepalive_timeout_ms', 5000),
+            ]
+
+            # Add compression if enabled
+            if self.enable_compression:
+                options.append(('grpc.default_compression_algorithm', grpc.Compression.Gzip))
+                options.append(('grpc.default_compression_level', grpc.Compression.Gzip))
+
+            # Create channel
+            self.channel = grpc.insecure_channel(self.address, options=options)
+
+            # Create stub
+            self.stub = self._create_stub()
+
+            # Mark as connected
+            self._connected = True
+            logger.info(f"[{self.service_name()}] Connected successfully to {self.address}")
+
+    @abstractmethod
+    def _create_stub(self):
+        """子类实现：创建特定服务的 stub"""
+        pass
+
+    @abstractmethod
+    def service_name(self) -> str:
+        """子类实现：返回服务名称"""
+        pass
+
+    def _call_with_retry(self, func, *args, **kwargs):
+        """带重试的 RPC 调用"""
+        if not self.enable_retry:
+            return func(*args, **kwargs)
+
+        @retry(
+            stop=stop_after_attempt(3),
+            wait=wait_exponential(multiplier=1, min=1, max=10),
+            retry=retry_if_exception_type(grpc.RpcError),
+            reraise=True
+        )
+        def _retry_wrapper():
+            self._ensure_connected()
+            return func(*args, **kwargs)
+
+        try:
+            return _retry_wrapper()
+        except grpc.RpcError as e:
+            logger.error(f"[{self.service_name()}] RPC failed after retries: {e.code()} - {e.details()}")
+            raise
+
+    def handle_error(self, e: Exception, operation: str = "操作"):
+        """统一错误处理"""
+        logger.error(f"[{self.service_name()}] {operation} 失败:")
+        if isinstance(e, grpc.RpcError):
+            logger.error(f"  错误代码: {e.code()}")
+            logger.error(f"  错误详情: {e.details()}")
+        else:
+            logger.error(f"  错误: {e}")
+        return None
+    
+    def close(self):
+        """关闭连接"""
+        if self.channel is not None:
+            self.channel.close()
+            self._connected = False
+            logger.info(f"[{self.service_name()}] Connection closed")
+    
+    def __enter__(self):
+        """支持 with 语句"""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """退出时自动关闭连接"""
+        self.close()
+