fustor-common 0.2.1__tar.gz

fustor_common-0.2.1/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: fustor-common
+Version: 0.2.1
+Summary: Common utilities and models for Fustor services
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: colorlog>=6.10.1
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pydantic-settings>=2.3.4

fustor_common-0.2.1/README.md

@@ -0,0 +1,52 @@
+# fustor-common
+
+This package provides common utilities, configurations, exceptions, and data schemas shared across various Fustor services and packages within the monorepo. Its purpose is to promote code reusability and maintain consistency throughout the Fustor ecosystem.
+
+## Features
+
+*   **Logging Configuration**: Standardized logging setup for all Fustor components.
+*   **Exceptions**: Custom exception classes for consistent error handling.
+*   **Schemas**: Shared Pydantic models for common data structures, ensuring data validation and interoperability.
+*   **Enums**: Enumerations for common categorical data, such as user levels.
+
+## Contents
+
+*   `logging_config.py`: Contains the `setup_logging` function for configuring application-wide logging.
+*   `exceptions.py`: Defines `ConfigurationError` and other custom exceptions.
+*   `schemas.py`: Houses `ConfigCreateResponse` and other shared Pydantic schemas.
+*   `enums.py`: Contains `UserLevel` and other shared enumerations.
+
+## Installation
+
+This package is part of the Fustor monorepo and is typically installed in editable mode within the monorepo's development environment using `uv sync`.
+
+## Usage
+
+Components from `fustor-common` are imported and utilized by other Fustor services (e.g., `agent`, `registry`, `fusion`) and plugin packages to leverage shared functionalities and maintain consistency.
+
+Example:
+
+```python
+from fustor_common.logging_config import setup_logging
+from fustor_common.exceptions import ConfigurationError
+from fustor_common.enums import UserLevel
+
+# Setup logging
+setup_logging()
+
+# Raise a custom exception
+try:
+    raise ConfigurationError("Invalid configuration setting.")
+except ConfigurationError as e:
+    print(f"Error: {e}")
+
+# Use an enum
+if some_user.level == UserLevel.ADMIN:
+    print("Admin user detected.")
+```
+
+## Dependencies
+
+*   `colorlog`: For colored and formatted console output.
+*   `pydantic`: For data validation and settings management.
+*   `pydantic-settings`: For managing application settings.

fustor_common-0.2.1/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "fustor-common"
+dynamic = ["version"]
+description = "Common utilities and models for Fustor services"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = [ "colorlog>=6.10.1", "pydantic>=2.11.7", "pydantic-settings>=2.3.4",]
+
+[build-system]
+requires = [ "setuptools>=61.0", "setuptools-scm>=8.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools_scm]
+root = "../.."
+version_scheme = "post-release"
+local_scheme = "dirty-tag"
+
+["project.urls"]
+Homepage = "https://github.com/excelwang/fustor/tree/master/packages/fustor_common"
+"Bug Tracker" = "https://github.com/excelwang/fustor/issues"
+
+[tool.setuptools.packages.find]
+where = [ "src",]

fustor_common-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fustor_common-0.2.1/src/fustor_common/__init__.py

@@ -0,0 +1,4 @@
+from .logging_config import setup_logging
+from .exceptions import ConfigurationError
+from .schemas import ConfigCreateResponse
+from .enums import UserLevel

fustor_common-0.2.1/src/fustor_common/daemon.py

@@ -0,0 +1,52 @@
+"""
+Common daemon functionality for Fustor services.
+This module provides a generic daemon launcher that can be used by
+any Fustor service without knowing implementation details.
+"""
+import os
+import sys
+import subprocess
+from fustor_common.paths import get_fustor_home_dir
+
+
+def start_daemon(service_module_path, app_var_name, pid_file_name, log_file_name, display_name, port, host='127.0.0.1', verbose=False, reload=False):
+    """
+    Start a Fustor service as a daemon process.
+
+    Args:
+        service_module_path (str): The Python module path to import (e.g., 'fustor_registry.main')
+        app_var_name (str): The name of the application variable in the module (e.g., 'app')
+        pid_file_name (str): The name of the PID file (e.g., 'registry.pid')
+        log_file_name (str): The name of the log file (e.g., 'registry.log')
+        display_name (str): The display name for the service (e.g., 'Fustor Registry')
+        port (int): The port to run the service on
+        verbose (bool): Whether to enable verbose logging
+    """
+    # Use the generic daemon launcher script
+    daemon_script_path = os.path.join(os.path.dirname(__file__), 'daemon_launcher.py')
+
+    # Create the command to execute the generic daemon launcher
+    command = [
+        sys.executable,
+        daemon_script_path,
+        service_module_path,
+        app_var_name,
+        pid_file_name,
+        log_file_name,
+        display_name,
+        str(port),
+        host
+    ]
+
+    if verbose:
+        command.append('--verbose')
+
+    if reload:
+        command.append('--reload')
+
+    # Set up the environment to ensure the subprocess has correct paths
+    env = os.environ.copy()
+    # Ensure PYTHONPATH includes the current directory for development
+    env['PYTHONPATH'] = os.getcwd() + ':' + env.get('PYTHONPATH', '')
+
+    subprocess.Popen(command, stdout=None, stderr=None, stdin=None, close_fds=True, env=env)

fustor_common-0.2.1/src/fustor_common/daemon_launcher.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python
+"""
+Generic daemon launcher for Fustor services.
+This script is used to launch any Fustor service as a daemon.
+It receives service parameters via command line arguments.
+"""
+import sys
+import os
+import logging
+import importlib
+import argparse
+from fustor_common.paths import get_fustor_home_dir
+from fustor_common.logging_config import setup_logging
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Generic Fustor Service Daemon Launcher')
+    parser.add_argument('module_path', help='Module path to import (e.g., fustor_registry.main)')
+    parser.add_argument('app_var', help='Application variable name (e.g., app)')
+    parser.add_argument('pid_file', help='PID file name (e.g., registry.pid)')
+    parser.add_argument('log_file', help='Log file name (e.g., registry.log)')
+    parser.add_argument('display_name', help='Display name for the service')
+    parser.add_argument('port', type=int, help='Port to run the service on')
+    parser.add_argument('host', nargs='?', default='127.0.0.1', help='Host to bind the service to (default: 127.0.0.1)')
+    parser.add_argument('--reload', action='store_true', help='Enable auto-reloading for development')
+    parser.add_argument('--verbose', action='store_true', help='Enable verbose logging')
+    
+    args = parser.parse_args()
+    
+    # Setup paths
+    HOME_FUSTOR_DIR = get_fustor_home_dir()
+    PID_FILE = os.path.join(HOME_FUSTOR_DIR, args.pid_file)
+    LOG_FILE = os.path.join(HOME_FUSTOR_DIR, args.log_file)
+    
+    # Setup logging
+    log_level = "DEBUG" if args.verbose else "INFO"
+    setup_logging(
+        log_file_path=LOG_FILE,
+        base_logger_name=args.display_name.lower().replace(' ', '_') + '_daemon',
+        level=log_level,
+        console_output=False  # No console output for daemon
+    )
+    logger = logging.getLogger(args.display_name.lower().replace(' ', '_') + '_daemon')
+
+    try:
+        # Import the service module
+        service_module = importlib.import_module(args.module_path)
+        app = getattr(service_module, args.app_var)
+        
+        # Ensure directory exists and create PID file
+        os.makedirs(HOME_FUSTOR_DIR, exist_ok=True)
+        with open(PID_FILE, 'w') as f:
+            f.write(str(os.getpid()))
+
+        print()
+        print("="*60)
+        print(f"{args.display_name} (Daemon)")
+        print(f"Web : http://{args.host}:{args.port}")
+        print("="*60)
+        print()
+        
+        logger.info(f"{args.display_name} daemon starting on {args.host}:{args.port}")
+        
+        # Import and run uvicorn
+        import uvicorn
+        # Configure uvicorn to use DEBUG level for access logs to reduce verbosity
+        # Need to set this after import but before run, and ensure it persists
+        uvicorn_logger = logging.getLogger("uvicorn.access")
+        uvicorn_logger.setLevel(logging.DEBUG)
+
+        app_to_run = app
+        if args.reload:
+            app_to_run = f"{args.module_path}:{args.app_var}"
+
+        uvicorn.run(
+            app_to_run,
+            host=args.host,
+            port=args.port,
+            log_config=None,  # Logging handled separately
+            access_log=True,
+            reload=args.reload,
+        )
+    except KeyboardInterrupt:
+        logger.info(f"{args.display_name} daemon interrupted")
+    except Exception as e:
+        logger.critical(f"{args.display_name} daemon error: {e}", exc_info=True)
+        print(f"{args.display_name} daemon error: {e}")
+    finally:
+        # Clean up PID file
+        if os.path.exists(PID_FILE):
+            os.remove(PID_FILE)
+            logger.info("PID file removed")
+
+
+if __name__ == "__main__":
+    main()

fustor_common-0.2.1/src/fustor_common/enums.py

@@ -0,0 +1,5 @@
+from enum import Enum
+
+class UserLevel(str, Enum):
+    NORMAL = "normal"
+    ADMIN = "admin"

fustor_common-0.2.1/src/fustor_common/exceptions.py

@@ -0,0 +1,3 @@
+class ConfigurationError(Exception):
+    """自定义配置错误异常"""
+    pass

fustor_common-0.2.1/src/fustor_common/logging_config.py

@@ -0,0 +1,161 @@
+# src/fustor_common/logging_config.py
+
+import logging
+import logging.config
+import os
+import sys
+
+class UvicornAccessFilter(logging.Filter):
+    """
+    Filter to suppress uvicorn.access logs when system level is INFO,
+    but allow them when system level is DEBUG.
+    """
+    def __init__(self, normal_level: int = logging.INFO):
+        super().__init__()
+        self.normal_level = normal_level
+
+    def filter(self, record):
+        # If it's a uvicorn.access log, only allow it through if system level is DEBUG
+        if record.name.startswith('uvicorn.access'):
+            return self.normal_level <= logging.DEBUG
+        # For other logs, apply normal level filtering
+        else:
+            return record.levelno >= self.normal_level
+
+def setup_logging(
+    log_file_path: str, # Now accepts full path
+    base_logger_name: str,
+    level: int = logging.INFO,
+    console_output: bool = True
+):
+    """
+    通用日志配置函数。
+
+    Args:
+        log_file_path (str): 日志文件存放的完整路径。
+        base_logger_name (str): 您的应用程序的基础logger名称（例如，"fustor_agent"或"fustor_fusion"）。
+        level (int): 控制台和文件处理程序的最低日志级别。
+        console_output (bool): 是否将日志输出到控制台。
+    """
+    # 确保日志文件所在的目录存在
+    log_directory = os.path.dirname(log_file_path)
+    os.makedirs(log_directory, exist_ok=True)
+    
+    # Truncate the log file at startup
+    if os.path.exists(log_file_path):
+        try:
+            with open(log_file_path, 'w', encoding='utf8'):
+                pass  # Open and immediately close to truncate
+        except IOError as e:
+            # Log the error, but don't prevent further logging
+            logging.getLogger(base_logger_name).error(f"Failed to truncate log file {log_file_path}: {e}")
+
+
+    if isinstance(level, str):
+        numeric_level = getattr(logging, level.upper(), logging.INFO)
+    else:
+        numeric_level = level
+
+    LOGGING_CONFIG = {
+        'version': 1,
+        'disable_existing_loggers': False,
+        'formatters': {
+            'standard': {
+                'format': '%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+                'datefmt': '%Y-%m-%d %H:%M:%S'
+            },
+            'color_console': {
+                '()': 'colorlog.ColoredFormatter',
+                'format': '%(log_color)s%(asctime)s - %(name)s - %(levelname)s - %(message)s%(reset)s',
+                'datefmt': '%Y-%m-%d %H:%M:%S',
+                'log_colors': {
+                    'DEBUG':    'cyan',
+                    'INFO':     'green',
+                    'WARNING':  'yellow',
+                    'ERROR':    'red',
+                    'CRITICAL': 'bold_red',
+                }
+            },
+            'json': {
+                '()': 'pythonjsonlogger.jsonlogger.JsonFormatter',
+                'format': '%(asctime)s %(levelname)s %(name)s %(message)s'
+            }
+        },
+        'handlers': {
+            'file': {
+                'class': 'logging.handlers.RotatingFileHandler',
+                'level': logging.DEBUG,  # Set to DEBUG so it can catch DEBUG level logs
+                'formatter': 'standard',
+                'filename': log_file_path,
+                'maxBytes': 10485760, # 10MB
+                'backupCount': 5,
+                'encoding': 'utf8',
+                'filters': ['uvicorn_access_filter']  # Add the custom filter
+            },
+            'console': {
+                'class': 'logging.StreamHandler',
+                'level': logging.DEBUG,  # Set to DEBUG for the same reason
+                'formatter': 'color_console',
+                'stream': sys.stdout,
+                'filters': ['uvicorn_access_filter']  # Add the custom filter
+            }
+        },
+        'filters': {
+            'uvicorn_access_filter': {
+                '()': UvicornAccessFilter,
+                'normal_level': numeric_level
+            }
+        },
+        'loggers': {
+            base_logger_name: {
+                'handlers': ['file'],
+                'level': numeric_level,
+                'propagate': False
+            },
+            'uvicorn': {
+                'handlers': ['file'],
+                'level': numeric_level,
+                'propagate': False
+            },
+            'uvicorn.error': {
+                'handlers': ['file'],
+                'level': numeric_level,
+                'propagate': False
+            },
+            'uvicorn.access': {
+                'handlers': ['file'],
+                'level': logging.INFO,  # Standard level for access logs
+                'propagate': False
+            }
+        },
+        'root': {
+            'handlers': ['file'],
+            'level': logging.ERROR, # Keep root at ERROR to avoid noise
+            'propagate': True, # Allow root to emit to its handlers for unhandled exceptions
+        }
+    }
+
+    if console_output:
+        LOGGING_CONFIG['loggers'][base_logger_name]['handlers'].append('console')
+        LOGGING_CONFIG['loggers']['uvicorn']['handlers'].append('console')
+        LOGGING_CONFIG['loggers']['uvicorn.error']['handlers'].append('console')
+        LOGGING_CONFIG['loggers']['uvicorn.access']['handlers'].append('console')
+        LOGGING_CONFIG['root']['handlers'].append('console')
+
+    logging.config.dictConfig(LOGGING_CONFIG)
+
+    # --- START: Silence Third-Party Loggers (more selectively) ---
+    # Only silence if the specified level is not DEBUG, to allow debugging when needed
+    if numeric_level > logging.DEBUG:
+        third_party_loggers = [
+            'httpx', 'asyncio', 'watchdog', 'sqlalchemy',
+            'alembic', 'requests', 'urllib3', 'multipart' # Add other chatty libraries here
+        ]
+        for logger_name in third_party_loggers:
+            logging.getLogger(logger_name).setLevel(logging.WARNING)
+    # --- END: Silence Third-Party Loggers ---
+
+    # Ensure main logger is available for immediate use
+    main_logger = logging.getLogger(base_logger_name)
+    main_logger.info(f"Logging configured successfully. Level: {logging.getLevelName(numeric_level)}")
+    main_logger.debug(f"Log file: {log_file_path}")

fustor_common-0.2.1/src/fustor_common/models.py

@@ -0,0 +1,75 @@
+from pydantic import BaseModel, Field, ConfigDict, field_validator
+from typing import Optional, Dict, List
+
+class ResponseBase(BaseModel):
+    # Base model for API responses, can include common fields like status, message
+    pass
+
+class ApiKeyBase(BaseModel):
+    id: Optional[int] = None
+    name: str = Field(..., min_length=3, max_length=50)
+    key: Optional[str] = None
+    datastore_id: int = Field(..., description="关联的存储库ID")
+
+class MessageResponse(BaseModel):
+    """A simple response model for messages."""
+    message: str
+
+
+class DatastoreBase(BaseModel):
+    id: Optional[int] = None
+    name: str = Field(..., description="存储库名称")
+    visible: bool = Field(False, description="是否对公众可见")
+    meta: Optional[Dict] = Field(None, description="存储库描述")
+    allow_concurrent_push: bool = Field(False, description="是否允许并发推送")
+    session_timeout_seconds: int = Field(30, description="会话超时秒数")
+
+class TokenResponse(BaseModel):
+    access_token: str
+    token_type: str
+    refresh_token: str | None = None
+
+class LogoutResponse(BaseModel):
+    detail: str = Field("注销成功", description="注销操作结果消息")
+
+class Password(BaseModel):
+    password: str = Field(
+        ..., 
+        min_length=8, 
+        max_length=64,
+        pattern=r'^[A-Za-z\d@$!%*#?&]+$',
+        description="8-64位字符，必须包含至少1字母和1数字，允许特殊字符 @$!%*#?&"
+    )
+
+    @field_validator('password')
+    @classmethod
+    def validate_password_chars(cls, v: str) -> str:
+        if not any(c.isalpha() for c in v):
+            raise ValueError("必须包含至少一个字母")
+        if not any(c.isdigit() for c in v):
+            raise ValueError("必须包含至少一个数字")
+        return v
+
+class ValidationResponse(BaseModel):
+    """A standard response model for validation actions."""
+    success: bool
+    message: str
+
+class CleanupResponse(BaseModel):
+    """A standard response model for cleanup actions."""
+    message: str
+    deleted_count: int
+    deleted_ids: List[str]
+
+class AdminCredentials(BaseModel):
+    user: str
+    passwd: str
+
+class LoginRequest(BaseModel):
+    username: str
+    password: str
+
+class DatastoreConfig(BaseModel):
+    datastore_id: int
+    allow_concurrent_push: bool
+    session_timeout_seconds: int

fustor_common-0.2.1/src/fustor_common/paths.py

@@ -0,0 +1,13 @@
+import os
+from pathlib import Path
+
+def get_fustor_home_dir() -> Path:
+    """
+    Determines the FUSTOR home directory.
+    Checks the FUSTOR_HOME environment variable first,
+    then defaults to ~/.fustor.
+    """
+    fustor_home = os.getenv("FUSTOR_HOME")
+    if fustor_home:
+        return Path(fustor_home).expanduser().resolve()
+    return Path.home() / ".fustor"

fustor_common-0.2.1/src/fustor_common/schemas.py

@@ -0,0 +1,9 @@
+from pydantic import BaseModel
+from typing import Generic, TypeVar
+
+T = TypeVar('T')
+
+class ConfigCreateResponse(BaseModel, Generic[T]):
+    """A standard response for successfully creating a new configuration."""
+    id: str
+    config: T

fustor_common-0.2.1/src/fustor_common.egg-info/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: fustor-common
+Version: 0.2.1
+Summary: Common utilities and models for Fustor services
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: colorlog>=6.10.1
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pydantic-settings>=2.3.4

fustor_common-0.2.1/src/fustor_common.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+src/fustor_common/__init__.py
+src/fustor_common/daemon.py
+src/fustor_common/daemon_launcher.py
+src/fustor_common/enums.py
+src/fustor_common/exceptions.py
+src/fustor_common/logging_config.py
+src/fustor_common/models.py
+src/fustor_common/paths.py
+src/fustor_common/schemas.py
+src/fustor_common.egg-info/PKG-INFO
+src/fustor_common.egg-info/SOURCES.txt
+src/fustor_common.egg-info/dependency_links.txt
+src/fustor_common.egg-info/requires.txt
+src/fustor_common.egg-info/top_level.txt
+tests/test_common_models.py

fustor_common-0.2.1/src/fustor_common.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fustor_common-0.2.1/src/fustor_common.egg-info/requires.txt

@@ -0,0 +1,3 @@
+colorlog>=6.10.1
+pydantic>=2.11.7
+pydantic-settings>=2.3.4

fustor_common-0.2.1/src/fustor_common.egg-info/top_level.txt

@@ -0,0 +1 @@
+fustor_common

fustor_common-0.2.1/tests/test_common_models.py

@@ -0,0 +1,95 @@
+import pytest
+from pydantic import ValidationError
+from fustor_common.models import (
+    ResponseBase,
+    ApiKeyBase,
+    MessageResponse,
+    DatastoreBase,
+    TokenResponse,
+    LogoutResponse,
+    Password,
+    ValidationResponse,
+    CleanupResponse,
+    AdminCredentials,
+    DatastoreConfig,
+)
+
+def test_response_base():
+    response = ResponseBase()
+    assert isinstance(response, ResponseBase)
+
+def test_api_key_base():
+    api_key = ApiKeyBase(name="test_key", datastore_id=1)
+    assert api_key.name == "test_key"
+    assert api_key.datastore_id == 1
+    with pytest.raises(ValidationError):
+        ApiKeyBase(name="a", datastore_id=1) # Too short
+    with pytest.raises(ValidationError):
+        ApiKeyBase(name="a"*51, datastore_id=1) # Too long
+
+def test_message_response():
+    message = MessageResponse(message="Success")
+    assert message.message == "Success"
+
+def test_datastore_base():
+    datastore = DatastoreBase(name="my_datastore")
+    assert datastore.name == "my_datastore"
+    assert datastore.visible == False
+    assert datastore.allow_concurrent_push == False
+    assert datastore.session_timeout_seconds == 30
+
+def test_token_response():
+    token = TokenResponse(access_token="abc", token_type="bearer")
+    assert token.access_token == "abc"
+    assert token.token_type == "bearer"
+
+def test_logout_response():
+    logout = LogoutResponse(detail="注销成功")
+    assert logout.detail == "注销成功"
+
+def test_password_model():
+    # Valid password
+    password = Password(password="Password123!")
+    assert password.password == "Password123!"
+
+    # Invalid password - too short
+    with pytest.raises(ValidationError):
+        Password(password="Short1!")
+
+    # Invalid password - too long
+    with pytest.raises(ValidationError):
+        Password(password="a"*65)
+
+    # Invalid password - no letter
+    with pytest.raises(ValidationError, match="必须包含至少一个字母"):
+        Password(password="12345678!")
+
+    # Invalid password - no digit
+    with pytest.raises(ValidationError, match="必须包含至少一个数字"):
+        Password(password="Password!!")
+
+    # Invalid password - invalid characters
+    with pytest.raises(ValidationError):
+        Password(password="Password123^") # ^ is not in allowed pattern
+
+def test_validation_response():
+    response = ValidationResponse(success=True, message="Valid")
+    assert response.success == True
+    assert response.message == "Valid"
+
+def test_cleanup_response():
+    response = CleanupResponse(message="Cleaned", deleted_count=5, deleted_ids=["id1", "id2"])
+    assert response.message == "Cleaned"
+    assert response.deleted_count == 5
+    assert response.deleted_ids == ["id1", "id2"]
+
+def test_admin_credentials():
+    creds = AdminCredentials(user="admin", passwd="password")
+    assert creds.user == "admin"
+    assert creds.passwd == "password"
+
+def test_datastore_config():
+    config = DatastoreConfig(datastore_id=1, allow_concurrent_push=True, session_timeout_seconds=60)
+    assert config.datastore_id == 1
+    assert config.allow_concurrent_push == True
+    assert config.session_timeout_seconds == 60