linglong-web 0.0.1__py3-none-any.whl

linglong_web/__init__.py

@@ -0,0 +1,132 @@
+"""Linglong Web – 异步 FastAPI 工具集 / Asynchronous FastAPI toolkit."""
+from .__version__ import (
+    __author__,
+    __description__,
+    __license__,
+    __version__,
+)
+
+from .core.auth import login_required
+from .core.cacher import cacher
+from .core.cluster_lock import cluster_lock
+from .core.config import (
+    LinglongConfigBase,
+    LinglongConfig,
+    init_config,
+)
+from .core.constants import LinglongConst
+from .core.cors import allow_cors_specific
+from .core.db import TableBase
+from .core.ddl_manager import (
+    AutoDDLManager,
+    DDLManagerConfig,
+)
+from .core.http import (
+    HTTPClientConfig,
+    AsyncHTTPClient,
+    LinglongHTTPError,
+    http_client,
+)
+from .core.limiter import LimiterGuard, limiter
+from .core.limiter_local import (
+    limiter_local,
+    reset_limiter,
+    get_limiter_stats,
+)
+from .core.resource import (
+    ResourceManager,
+    Rmanager,
+    DEFAULT_DB_ALIAS,
+    init_resources,
+    close_resources,
+)
+from .core.response import (
+    APIError,
+    APIResponse,
+    build_api_response,
+    build_success_response,
+    build_error_response,
+)
+from .core.router import (
+    BaseRoute,
+    ServerRouter,
+)
+from .core.scheduler import (
+    BaseScheduler,
+    SchedulerGroup,
+    to_group,
+)
+from .core.server import LinglongAppServer
+from .core.server_extensions import BaseServerExtension
+from .core.schemas import (
+    PgsqlConfig,
+    RedisConfig,
+    RabbitMQConfig,
+    MongoConfig,
+    CeleryConfig,
+    ResourceInitConfig,
+)
+from .core.errors import (
+    ErrorCode,
+    ErrorMsg,
+    LinglongHTTPException,
+    LoginRequiredError,
+    LimiterError,
+    ClusterLockError,
+)
+
+__all__ = [
+    "login_required",
+    "cacher",
+    "cluster_lock",
+    "LinglongConfigBase",
+    "LinglongConfig",
+    "LinglongConst",
+    "init_config",
+    "allow_cors_specific",
+    "TableBase",
+    "AutoDDLManager",
+    "DDLManagerConfig",
+    "BaseRoute",
+    "ServerRouter",
+    "APIError",
+    "APIResponse",
+    "build_api_response",
+    "build_success_response",
+    "build_error_response",
+    "HTTPClientConfig",
+    "AsyncHTTPClient",
+    "LinglongHTTPError",
+    "http_client",
+    "LimiterGuard",
+    "limiter",
+    "limiter_local",
+    "reset_limiter",
+    "get_limiter_stats",
+    "ResourceManager",
+    "Rmanager",
+    "DEFAULT_DB_ALIAS",
+    "init_resources",
+    "close_resources",
+    "BaseScheduler",
+    "SchedulerGroup",
+    "to_group",
+    "LinglongAppServer",
+    "BaseServerExtension",
+    "PgsqlConfig",
+    "RedisConfig",
+    "RabbitMQConfig",
+    "MongoConfig",
+    "CeleryConfig",
+    "ResourceInitConfig",
+    "ErrorCode",
+    "ErrorMsg",
+    "LinglongHTTPException",
+    "LoginRequiredError",
+    "LimiterError",
+    "ClusterLockError",
+    "__version__",
+    "__author__",
+    "__license__",
+    "__description__",
+]

linglong_web/__version__.py

@@ -0,0 +1,9 @@
+"""Linglong Web metadata / 版本信息模块."""
+
+__version__ = "0.0.1"
+__author__ = "Victor Lai"
+__license__ = "MIT"
+__description__ = (
+    "Asynchronous FastAPI toolkit providing service bootstrap, registry hooks, resource orchestration, "
+    "and observability helpers"
+)

linglong_web/core/__init__.py

@@ -0,0 +1,54 @@
+"""Linglong Web – 异步 FastAPI 工具集 / Asynchronous FastAPI toolkit."""
+from .auth import login_required
+from .cacher import cacher
+from .cluster_lock import cluster_lock
+from .config import (
+    LinglongConfigBase,
+    LinglongConfig,
+    LinglongConfigProxy,
+    init_config,
+)
+from .constants import LinglongConst
+from .cors import allow_cors_specific
+from .db import TableBase
+from .ddl_manager import (
+    AutoDDLManager,
+    DDLManagerConfig,
+)
+from .http import (
+    HTTPClientConfig,
+    AsyncHTTPClient,
+    LinglongHTTPError,
+    http_client,
+)
+from .limiter import (
+    LimiterGuard,
+    limiter,
+)
+from .limiter_local import (
+    limiter_local,
+    reset_limiter,
+    get_limiter_stats,
+)
+from .resource import (
+    ResourceManager,
+    Rmanager,
+    DEFAULT_DB_ALIAS,
+    init_resources,
+    close_resources,
+)
+from .response import (
+    APIError,
+    APIResponse,
+    build_api_response,
+    build_success_response,
+    build_error_response,
+)
+from .router import BaseRoute, ServerRouter
+from .scheduler import (
+    BaseScheduler,
+    SchedulerGroup,
+    to_group,
+)
+from .server import LinglongAppServer
+from .server_extensions import BaseServerExtension

linglong_web/core/auth.py

@@ -0,0 +1,31 @@
+"""Authentication helpers shared across Linglong services.
+
+提供 Linglong 服务统一的认证装饰器工具。
+"""
+from functools import wraps
+from typing import (
+    Awaitable,
+    Callable,
+)
+
+from .errors import LoginRequiredError
+from .types import P, R
+from ..utils.context import get_context_user_id
+from ..utils.log import logger
+
+
+def login_required(func: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[R]]:
+    """Ensure the current request has a valid login user id.
+
+    确保当前请求已经完成登录校验，如果缺少用户信息则抛出 ``LoginRequiredError``。
+    """
+
+    @wraps(func)
+    async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        user_id = get_context_user_id()
+        if user_id is not None and isinstance(user_id, int):
+            return await func(*args, **kwargs)
+        logger.warning("user is not login")
+        raise LoginRequiredError()
+
+    return wrapper

linglong_web/core/cacher.py

@@ -0,0 +1,92 @@
+"""Redis based caching decorator for Linglong services.
+
+提供基于 Redis 的协程缓存装饰器，支持自定义键后缀与按用户隔离。
+"""
+import hashlib
+import inspect
+import os
+from functools import wraps
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+)
+
+import orjson
+from redis import asyncio as aioredis
+
+from .resource import Rmanager
+from .types import P, R
+from ..utils.context import get_context_user_id
+from ..utils.log import logger
+
+
+def _build_cache_key(
+        func: Callable[..., Any],
+        *,
+        add_str: str,
+        cache_by_user: bool,
+) -> str:
+    """Generate a stable cache key based on function source metadata.
+
+    结合函数文件路径、行号、模块与名称生成稳定的缓存键，可选追加自定义后缀与用户 ID。
+    """
+
+    source_file = inspect.getsourcefile(func)
+    filepath = os.path.abspath(source_file) if source_file else "N/A"
+    hash_hex = hashlib.md5(filepath.encode("utf-8"), usedforsecurity=False).hexdigest()
+
+    try:
+        _, line_no = inspect.getsourcelines(func)
+    except (TypeError, OSError):  # pragma: no cover - fallback when inspect fails
+        line_no = "N/A"
+
+    key_parts = [hash_hex, str(line_no), func.__module__, func.__name__]
+    if add_str:
+        key_parts.append(add_str)
+    if cache_by_user:
+        user_id = get_context_user_id()
+        if user_id:
+            key_parts.append(str(user_id))
+    return ":".join(key_parts)
+
+
+def cacher(
+        expire_time: int,
+        add_str: str = "",
+        cache_by_user: bool = False,
+) -> Callable[[Callable[P, Awaitable[R]]], Callable[P, Awaitable[R]]]:
+    """Cache coroutine results in Redis for a configurable TTL.
+
+    Args:
+        expire_time: 缓存秒数 / TTL in seconds.
+        add_str: 自定义键后缀 / Optional suffix for more granularity.
+        cache_by_user: 是否按用户区分缓存 / Split cache entries by user id.
+    """
+
+    def decorator(func: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[R]]:
+        @wraps(func)
+        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            if Rmanager.RedisPool is None:
+                logger.warning("redis cache is not available")
+                return await func(*args, **kwargs)
+
+            redis_client = aioredis.Redis(connection_pool=Rmanager.RedisPool)
+            cache_key = _build_cache_key(func, add_str=add_str, cache_by_user=cache_by_user)
+
+            try:
+                cached = await redis_client.get(cache_key)
+                if cached:
+                    logger.debug("redis cache hit: %s", cache_key)
+                    return orjson.loads(cached)
+
+                result = await func(*args, **kwargs)
+                await redis_client.setex(cache_key, expire_time, orjson.dumps(result))
+                return result
+            except Exception as exc:  # noqa: BLE001
+                logger.error("redis cache error: %s", exc, exc_info=True)
+                return await func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

linglong_web/core/cluster_lock.py

@@ -0,0 +1,128 @@
+"""Redis backed cluster wide lock helpers.
+
+提供依赖 Redis 的集群锁装饰器，防止分布式并发执行同一段逻辑。
+"""
+from functools import wraps
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+)
+
+import redis.asyncio as redis
+
+from .errors import ClusterLockError
+from .resource import Rmanager
+from .types import LockKeyBuilder, OnLockFail, P, R
+from ..utils.log import logger
+
+
+def _get_redis_client() -> redis.Redis | None:
+    """Lazily build Redis client from the global pool.
+
+    从 Rmanager 注入的连接池创建 Redis 实例，若池未初始化则返回 ``None``。
+    """
+
+    if not Rmanager.RedisPool:
+        return None
+    return redis.Redis(connection_pool=Rmanager.RedisPool)
+
+
+def _compose_lock_key(
+        lock_prefix: str,
+        func: Callable[..., Any],
+        include_func_name: bool,
+        extra_key: str,
+        key_builder: LockKeyBuilder | None,
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+) -> str:
+    """Build a stable lock key with optional custom suffixes.
+
+    将锁前缀、函数名、自定义 key 与用户提供的 ``key_builder`` 结果拼接为最终键。
+    """
+
+    key_parts: list[str] = [lock_prefix]
+    if include_func_name:
+        key_parts.append(func.__name__)
+    if extra_key:
+        key_parts.append(extra_key)
+    if key_builder:
+        custom = key_builder(func, args, kwargs)
+        if custom:
+            key_parts.append(custom)
+    return ":".join(key_parts)
+
+
+def cluster_lock(
+        lock_prefix: str,
+        *,
+        timeout_seconds: float = 60.0,
+        blocking_timeout_seconds: float | None = None,
+        extra_key: str = "",
+        include_func_name: bool = True,
+        key_builder: LockKeyBuilder | None = None,
+        error_message: str | None = None,
+        on_fail: OnLockFail | None = None,
+) -> Callable[[Callable[P, Awaitable[R]]], Callable[P, Awaitable[R]]]:
+    """Decorate a coroutine to enforce Redis distributed locking.
+
+    Args:
+        lock_prefix: 锁键前缀 / Prefix for Redis lock key.
+        timeout_seconds: 锁自动过期时间 / Lock expiration in seconds.
+        blocking_timeout_seconds: 获取锁的最大等待时间 / Max wait when acquiring.
+        extra_key: 自定义后缀 / Optional static suffix.
+        include_func_name: 是否包含函数名 / Append function name or not.
+        key_builder: 用户自定义键构造 / Custom builder for dynamic parts.
+        error_message: 获取失败提示 / Optional override error text.
+        on_fail: 获取失败回调 / Optional coroutine executed on contention.
+    """
+
+    if timeout_seconds <= 0:
+        raise ValueError("timeout_seconds must be positive")
+
+    def decorator(func: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[R]]:
+        @wraps(func)
+        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            redis_client = _get_redis_client()
+            if redis_client is None:
+                logger.warning("Redis pool is not initialized, skip cluster lock for %s", func.__name__)
+                return await func(*args, **kwargs)
+
+            lock_key = _compose_lock_key(
+                lock_prefix=lock_prefix,
+                func=func,
+                include_func_name=include_func_name,
+                extra_key=extra_key,
+                key_builder=key_builder,
+                args=args,
+                kwargs=kwargs,
+            )
+
+            wait_timeout = blocking_timeout_seconds if blocking_timeout_seconds is not None else timeout_seconds
+            lock = redis_client.lock(lock_key, timeout=timeout_seconds)
+
+            try:
+                acquired = await lock.acquire(blocking=True, blocking_timeout=wait_timeout)
+            except Exception as exc:  # noqa: BLE001
+                logger.error("Failed to acquire cluster lock %s: %s", lock_key, exc)
+                raise
+
+            if not acquired:
+                message = error_message or f"Resource is locked by another worker: {lock_key}"
+                if on_fail:
+                    return await on_fail(message, func, args, kwargs)
+                raise ClusterLockError(message)
+
+            try:
+                return await func(*args, **kwargs)
+            finally:
+                if lock.locked():
+                    try:
+                        await lock.release()
+                    except Exception as exc:  # noqa: BLE001
+                        logger.error("Failed to release cluster lock %s: %s", lock_key, exc)
+
+        return wrapper
+
+    return decorator

linglong_web/core/config.py

@@ -0,0 +1,196 @@
+"""Linglong Web 配置代理 / Configuration proxy."""
+
+import logging
+import os
+from typing import (
+    Any,
+    Dict,
+)
+
+from ..utils.pj_struct import Singleton
+from ..utils.async_read_write_lock import AsyncReadWriteLock
+from ..utils.log import logger
+
+
+class LinglongConfigBase:
+    """框架默认配置 / Default Linglong configuration."""
+
+    DEBUG = False
+    ENV_MODE = "prod"
+
+    PGSQL_USER = "postgres"
+    PGSQL_PASSWORD = "postgres123"
+    PGSQL_DB = ""
+    PGSQL_HOST = "postgres.internal"
+    PGSQL_PORT = "5432"
+    PGSQL_POOL_SIZE = 1
+    PGSQL_MAX_OVERFLOW = 5
+    PGSQL_DATABASES: Dict[str, Dict[str, Any]] | None = None
+    DDL_REQUIRED_EXTENSIONS = ("pgcrypto",)
+
+    MONGODB_URI = ""
+    MONGODB_DB = ""
+    MONGODB_COLLECTION = ""
+
+    REDIS_HOST = "redis.internal"
+    REDIS_PORT = 6379
+    REDIS_PASSWORD = ""
+    REDIS_MAXSIZE = None
+
+    ENABLE_WORKFLOW_CELERY = False
+    CELERY_BROKER_URL = None
+    CELERY_RESULT_BACKEND = None
+    CELERY_RESULT_BACKEND_DB = 0
+    CELERY_APP_NAME = "linglong_app"
+    CELERY_TASK_SERIALIZER = "json"
+    CELERY_ACCEPT_CONTENT = ["json"]
+    CELERY_RESULT_SERIALIZER = "json"
+    CELERY_TIMEZONE = "UTC"
+    CELERY_ENABLE_UTC = True
+    CELERY_WORKER_LOG_FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    CELERY_WORKER_TASK_LOG_FORMAT = (
+        "%(asctime)s - %(name)s - %(levelname)s - task_id=%(task_id)s task_name=%(task_name)s - %(message)s"
+    )
+
+    LOGGING_LEVEL = logging.DEBUG
+    LOGGING_ENABLE_FILE_HANDLER = False
+    LOGGING_FILE_ADDR_FORMAT = "/opt/logs/server_app/app-{}.log"
+    LOGGING_FILE_MAX_BYTES = 10 * 1024 * 1024
+    LOGGING_FILE_BACKUP_COUNT = 10
+    LOG_CONFIG = {"exchange_name": "log.topic.exchange"}
+
+    LOG_PIPELINE_ENABLED = None
+    LOG_PIPELINE_IGNORE_LEVELS = []
+    LOG_RETENTION_DAYS = 7
+    LOG_RETENTION_BATCH_LIMIT = 2000
+
+    RABBITMQ_HOST = ""
+    RABBITMQ_PORT = 5672
+    RABBITMQ_VHOST = "/"
+    RABBITMQ_USERNAME = ""
+    RABBITMQ_PASSWORD = ""
+    RABBITMQ_LOG_EXCHANGE = "logs.topic.exchange"
+    RABBITMQ_LOG_QUEUE = "logs.business.infra.q"
+    RABBITMQ_LOG_BINDING_KEY = "logs.business.#"
+    RABBITMQ_LOG_PREFETCH = 200
+    RABBITMQ_LOG_ROUTING_TEMPLATE = "logs.business.{service}.{level}"
+    RABBITMQ_LOG_CONNECTION_NAME = ""
+
+    CORS_ALLOWED_ORIGINS = ["http://localhost"]
+
+    CELERY_WORKER_AUTOSTART = True
+    CELERY_WORKER_LOG_LEVEL = "INFO"
+    CELERY_WORKER_CONCURRENCY = 4
+    CELERY_WORKER_POOL = None
+    CELERY_WORKER_ENABLE_BEAT = True
+    CELERY_WORKER_HOSTNAME_SUFFIX = ".inline"
+    WORKFLOW_INLINE_MAX_CONCURRENCY = 4
+    WORKFLOW_INLINE_QUEUE_LIMIT = 1024
+
+    GRACEFUL_SHUTDOWN_TIMEOUT = 30
+
+
+class LinglongConfigProxy(Singleton):
+    """配置代理，支持线程安全读写 / Config proxy with thread-safe caching."""
+
+    def __init__(self) -> None:
+        self._active_config_class: type[LinglongConfigBase] = LinglongConfigBase
+        self._lock = AsyncReadWriteLock()
+        self._config_cache: Dict[str, Any] = {}
+        self._cache_initialized = False
+
+    def _ensure_cache_initialized(self) -> None:
+        if self._cache_initialized:
+            return
+        with self._lock.write_locked():
+            if self._cache_initialized:
+                return
+            for key in dir(self._active_config_class):
+                if not key.startswith('_') and key.isupper():
+                    self._config_cache[key] = getattr(self._active_config_class, key)
+            self._cache_initialized = True
+
+    def _set_active_config_class(self, config_class: type[LinglongConfigBase]) -> None:
+        with self._lock.write_locked():
+            self._active_config_class = config_class
+            self._config_cache.clear()
+            self._cache_initialized = False
+            self._ensure_cache_initialized()
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith('_'):
+            return object.__getattribute__(self, name)
+        self._ensure_cache_initialized()
+        with self._lock.read_locked():
+            if name in self._config_cache:
+                return self._config_cache[name]
+        if hasattr(self._active_config_class, name):
+            value = getattr(self._active_config_class, name)
+            with self._lock.write_locked():
+                self._config_cache[name] = value
+            return value
+        raise AttributeError(f"Config has no attribute '{name}'")
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name.startswith('_'):
+            object.__setattr__(self, name, value)
+            return
+        self._ensure_cache_initialized()
+        with self._lock.write_locked():
+            self._config_cache[name] = value
+            setattr(self._active_config_class, name, value)
+
+    def apply_updates(self, updates: Dict[str, Any]) -> None:
+        """批量更新配置值 / Apply a batch of configuration updates."""
+
+        if not updates:
+            return
+
+        self._ensure_cache_initialized()
+        with self._lock.write_locked():
+            for key, value in updates.items():
+                self._config_cache[key] = value
+                setattr(self._active_config_class, key, value)
+
+    def snapshot(self) -> Dict[str, Any]:
+        self._ensure_cache_initialized()
+        with self._lock.read_locked():
+            return self._config_cache.copy()
+
+    def reset(self) -> None:
+        with self._lock.write_locked():
+            self._config_cache.clear()
+            self._cache_initialized = False
+            self._ensure_cache_initialized()
+
+    def load_from_dict(self, config_dict: Dict[str, Any]) -> None:
+        """从字典批量加载配置 / Load all config values from a dict."""
+
+        with self._lock.write_locked():
+            self._config_cache.clear()
+            self._config_cache.update(config_dict)
+            for key, value in config_dict.items():
+                setattr(self._active_config_class, key, value)
+            self._cache_initialized = True
+        self._ensure_cache_initialized()
+
+
+LinglongConfig = LinglongConfigProxy()
+
+
+def init_config(config_dict: Dict[str, type[LinglongConfigBase]], mode_name: str | None = None) -> LinglongConfigProxy:
+    """初始化配置 / Initialize config based on NE_CONFIG or provided mode."""
+
+    if mode_name is None:
+        mode_name = os.getenv('LINGLONG_CONFIG', 'prod')
+        logger.info("Linglong config mode not specified, using NE_CONFIG: %s", mode_name)
+
+    config_cls = config_dict.get(mode_name)
+    if config_cls is None:
+        raise ValueError(
+            f"Config mode '{mode_name}' not found in config_dict. Available: {list(config_dict.keys())}"
+        )
+
+    LinglongConfig._set_active_config_class(config_cls)
+    logger.info("Linglong Config initialized with mode: %s, class: %s", mode_name, config_cls.__name__)
+    return LinglongConfig

linglong_web/core/constants.py

@@ -0,0 +1,38 @@
+"""Linglong Web 常量定义 / Linglong Web constants."""
+import http
+from enum import StrEnum
+
+
+DEFAULT_DB_ALIAS = "default"
+
+class HeaderKey(StrEnum):
+    """请求头键常量 / HTTP header keys"""
+
+    REQUEST_ID = "x-linglong-reqid"
+
+
+class Environment(StrEnum):
+    """运行环境常量 / Deployment environment constants"""
+
+    DEVELOPMENT = "development"
+    PRODUCTION = "production"
+
+
+class LinglongConst:
+    """框架级别常量集合 / Framework-wide constants."""
+
+    OID_HEADER_KEY = HeaderKey.REQUEST_ID
+    HTTP_METHODS = tuple(method.value for method in http.HTTPMethod)
+    ENVIRONMENT = Environment
+
+    @classmethod
+    def is_http_method_supported(cls, method: str) -> bool:
+        """判断 HTTP Method 是否被支持 / Check if HTTP method is allowed."""
+
+        return method in cls.HTTP_METHODS
+
+    # 注意：linglong 只维护与 Web 框架基础能力相关的常量。
+    # Note: linglong keeps only core web-framework constants.
+    #
+    # 类似“服务注册 / 健康检查 / 远端配置 / 容器 hostname 判定”等微服务框架能力
+    # 应由 cancan 统一内聚管理，禁止通过调用方反向注入到 linglong。