fastapi-authly 0.1.28__tar.gz → 0.1.30__tar.gz

{fastapi_authly-0.1.28 → fastapi_authly-0.1.30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-authly
-Version: 0.1.28
+Version: 0.1.30
 Summary: A modular authentication system for FastAPI with OAuth2, JWT, and password recovery
 Project-URL: Homepage, https://github.com/yourusername/fastapi-auth-module
 Project-URL: Documentation, https://yourusername.github.io/fastapi-auth-module/
@@ -32,6 +32,7 @@ Requires-Dist: fastapi>=0.100.0
 Requires-Dist: jinja2>=3.0.0
 Requires-Dist: loguru>=0.7.3
 Requires-Dist: passlib[bcrypt]>=1.7.4
+Requires-Dist: prefect>=3.8.6
 Requires-Dist: pydantic-settings>=2.1.0
 Requires-Dist: pydantic[email]>=2.0.0
 Requires-Dist: pyjwt>=2.12.1

{fastapi_authly-0.1.28 → fastapi_authly-0.1.30}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fastapi-authly"
-version = "0.1.28"
+version = "0.1.30"
 description = "A modular authentication system for FastAPI with OAuth2, JWT, and password recovery"
 readme = "README.md"
 license = {text = "MIT"}
@@ -57,6 +57,7 @@ dependencies = [
     "loguru>=0.7.3",
     "tenacity>=9.1.4",
     "rich>=15.0.0",
+    "prefect>=3.8.6",
 ]
 
 [project.optional-dependencies]

{fastapi_authly-0.1.28 → fastapi_authly-0.1.30}/src/fastapi_authly/__about__.py

@@ -1,3 +1,3 @@
 """Version information."""
 
-__version__ = "0.1.28"
+__version__ = "0.1.30"

{fastapi_authly-0.1.28 → fastapi_authly-0.1.30}/src/fastapi_authly/core/config/__init__.py

@@ -1,6 +1,7 @@
 from .database import DatabaseConfig
 from .auth import AuthConfig, AuthDependencyConfig, JwtConfig
-from .base import BaseBackendModel, EmbeddingConfig, RedisConfig, MinioConfig, LoggingConfig
+from .base import BaseBackendModel, EmbeddingConfig, RedisConfig, MinioConfig, LoggingConfig, ServerConfig
+from fastapi_authly.schedule import ScheduleConfig
 from pathlib import Path
 from typing import Any, Iterable
 
@@ -38,6 +39,13 @@ class BaseAppConfig(BaseModel):
     redis: RedisConfig | None = None
     minio: MinioConfig | None = None
     logging: LoggingConfig = Field(default_factory=LoggingConfig)
+    server: ServerConfig = Field(default_factory=ServerConfig)
+
+    schedules: dict[str, ScheduleConfig] = Field(
+        default_factory=dict,
+        description="任务标识与调度配置",
+    )
+
 
 
     @staticmethod

{fastapi_authly-0.1.28 → fastapi_authly-0.1.30}/src/fastapi_authly/core/config/base.py

@@ -41,4 +41,10 @@ class LoggingFileConfig(BaseModel):
 class LoggingConfig(BaseModel):
     level: Literal["DEBUG","INFO","WARNING","ERROR","CRITICAL"] = "INFO"
     format: Literal["console", "rich"] = "console"
-    file: LoggingFileConfig = Field(default_factory=LoggingFileConfig)
+    file: LoggingFileConfig = Field(default_factory=LoggingFileConfig)
+
+
+class ServerConfig(BaseModel):
+    host: str = "0.0.0.0"
+    port: int = Field(default=4040, ge=1, le=65535)
+    reload: bool = False

fastapi_authly-0.1.30/src/fastapi_authly/schedule/__init__.py

@@ -0,0 +1,13 @@
+from .config import (
+    CronScheduleConfig,
+    IntervalScheduleConfig,
+    ScheduleConfig,
+)
+from .manager import PrefectDeploymentManager
+
+__all__ = [
+    "CronScheduleConfig",
+    "IntervalScheduleConfig",
+    "ScheduleConfig",
+    "PrefectDeploymentManager",
+]

fastapi_authly-0.1.30/src/fastapi_authly/schedule/config.py

@@ -0,0 +1,80 @@
+from typing import Annotated, Literal
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from prefect.client.schemas.schedules import CronSchedule
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+class CronScheduleConfig(BaseModel):
+    """按五段 Cron 表达式调度。
+
+    Attributes:
+        type: 固定为 cron。
+        cron: 分钟、小时、日、月、星期组成的表达式。
+        timezone: 调度时区，默认 Asia/Shanghai。
+    """
+
+    model_config = ConfigDict(extra="forbid", validate_default=True)
+
+    type: Literal["cron"]
+    cron: str = Field(min_length=1, description="五段 Cron 表达式")
+    timezone: str = Field(
+        default="Asia/Shanghai",
+        description="调度时区",
+    )
+
+    max_instances: int = Field(
+        default=1,
+        gt=0,
+        strict=True,
+        description="同一部署的最大并发实例数，满额时取消新运行",
+    )
+
+    @field_validator("cron")
+    @classmethod
+    def validate_cron(cls, value: str) -> str:
+        """规范化表达式，并使用 Prefect 校验合法性。"""
+        parts = value.split()
+        if len(parts) != 5:
+            raise ValueError("cron 必须是五段表达式：分钟 小时 日 月 星期")
+
+        expression = " ".join(parts)
+        CronSchedule(cron=expression, timezone="UTC")
+        return expression
+
+    @field_validator("timezone")
+    @classmethod
+    def validate_timezone(cls, value: str) -> str:
+        """检查时区名称是否有效。"""
+        try:
+            ZoneInfo(value)
+        except (ZoneInfoNotFoundError, ValueError) as exc:
+            raise ValueError(f"无效时区：{value}") from exc
+        return value
+
+class IntervalScheduleConfig(BaseModel):
+    """按固定时间间隔调度。
+
+    Attributes:
+        type: 固定为 interval。
+        seconds: 间隔秒数，必须是正整数。
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["interval"]
+    seconds: int = Field(
+        gt=0,
+        strict=True,
+        description="执行间隔，单位为秒",
+    )
+    max_instances: int = Field(
+        default=1,
+        gt=0,
+        strict=True,
+        description="同一部署的最大并发实例数，满额时取消新运行",
+    )
+
+ScheduleConfig = Annotated[
+    CronScheduleConfig | IntervalScheduleConfig,
+    Field(discriminator="type"),
+]

fastapi_authly-0.1.30/src/fastapi_authly/schedule/manager.py

@@ -0,0 +1,277 @@
+from dataclasses import dataclass
+from datetime import timedelta
+
+from prefect import Flow, aserve
+from prefect.client.schemas.schedules import CronSchedule, IntervalSchedule
+from prefect.deployments.runner import RunnerDeployment
+from prefect.client.schemas.objects import (
+    ConcurrencyLimitConfig,
+    ConcurrencyLimitStrategy,
+)
+from .config import (
+    CronScheduleConfig,
+    IntervalScheduleConfig,
+    ScheduleConfig,
+)
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+
+@dataclass(frozen=True)
+class _DeploymentBinding:
+    key: str
+    flow: Flow
+    config: ScheduleConfig
+
+
+class PrefectDeploymentManager:
+    """管理 Flow 与调度配置的绑定、部署构建及运行服务。
+
+    Args:
+        namespace: 项目或环境命名空间，例如 complaint-hb。
+
+    Examples:
+        manager = PrefectDeploymentManager(namespace="complaint-hb")
+        manager.add(
+            key="cluster",
+            flow=cluster_flow,
+            config=app_config.schedules["cluster"],
+        )
+        await manager.serve()
+    """
+
+    def __init__(self, namespace: str) -> None:
+        self.namespace = self._validate_name(namespace, "namespace")
+        self._bindings: dict[str, _DeploymentBinding] = {}
+        self._serving = False
+
+    def add(
+            self,
+            key: str,
+            flow: Flow,
+            config: ScheduleConfig,
+    ) -> None:
+        """绑定一个 Flow 与调度配置，不连接 Prefect 服务端。
+
+        Args:
+            key: 当前管理实例中唯一的任务标识，例如 cluster。
+            flow: 使用 Prefect @flow 装饰的工作流对象。
+            config: Cron 或固定间隔调度配置。
+
+        Raises:
+            ValueError: 任务标识非法或重复。
+            TypeError: flow 或 config 类型不正确。
+            RuntimeError: 服务运行期间尝试添加绑定。
+
+        Examples:
+            manager.add(
+                key="cluster",
+                flow=cluster_flow,
+                config=CronScheduleConfig(
+                    type="cron",
+                    cron="30 0 1,7,14,21 * *",
+                    timezone="Asia/Shanghai",
+                ),
+            )
+        """
+        if self._serving:
+            raise RuntimeError("服务运行期间不能添加任务")
+
+        key = self._validate_name(key, "key")
+
+        if key in self._bindings:
+            raise ValueError(f"任务标识重复：{key}")
+
+        if not isinstance(flow, Flow):
+            raise TypeError("flow 必须是使用 @flow 装饰的 Prefect Flow")
+
+        if not isinstance(
+                config,
+                (CronScheduleConfig, IntervalScheduleConfig),
+        ):
+            raise TypeError(
+                "config 必须是 CronScheduleConfig 或 IntervalScheduleConfig"
+            )
+
+        config_copy = type(config).model_validate(
+            config.model_dump(mode="python")
+        )
+
+        self._bindings[key] = _DeploymentBinding(
+            key=key,
+            flow=flow,
+            config=config_copy,
+        )
+
+    async def build_deployments(self) -> list[RunnerDeployment]:
+        """校验所有调度并构建 Deployment 对象，不启动运行服务。
+
+        Returns:
+            按添加顺序排列的 Deployment 对象列表。
+
+        Raises:
+            ValueError: 未添加任务或调度配置无效。
+            Exception: Prefect 部署构建异常原样向上传播。
+
+        Examples:
+            deployments = await manager.build_deployments()
+            await aserve(*deployments)
+
+        Notes:
+            部署名称为 namespace-key，不包含调度表达式或运行时间。
+            不设置业务参数，定时运行使用 Flow 自身的默认参数。
+        """
+        bindings = tuple(self._bindings.values())
+
+        if not bindings:
+            raise ValueError("没有可构建的任务，请先调用 add()")
+
+        schedules = [
+            self._build_schedule(binding.config)
+            for binding in bindings
+        ]
+
+        deployments: list[RunnerDeployment] = []
+
+        for binding, schedule in zip(bindings, schedules, strict=True):
+            deployment = await binding.flow.ato_deployment(
+                name=f"{self.namespace}-{binding.key}",
+                schedules=[schedule],
+                concurrency_limit=ConcurrencyLimitConfig(
+                    limit=binding.config.max_instances,
+                    collision_strategy=ConcurrencyLimitStrategy.CANCEL_NEW,
+                ),
+            )
+            deployments.append(deployment)
+
+        return deployments
+
+    async def serve(self) -> None:
+        """打印部署配置，注册部署并持续运行本地 Runner。
+
+        Raises:
+            RuntimeError: 同一管理实例已经在运行服务。
+            ValueError: 未添加任务。
+            Exception: 构建、注册或运行服务的异常原样向上传播。
+
+        Examples:
+            await manager.serve()
+
+        Notes:
+            表格展示的是待注册配置，不代表远程注册成功。
+            此方法持续运行，正常停止后才返回。
+            正常关闭时请求暂停所服务部署的调度，不删除部署。
+            强制终止或网络故障时，暂停操作可能无法完成。
+        """
+        if self._serving:
+            raise RuntimeError("当前管理实例已经在运行服务")
+
+        self._serving = True
+
+        try:
+            deployments = await self.build_deployments()
+
+            self._print_task_table()
+
+            await aserve(
+                *deployments,
+                pause_on_shutdown=True,
+                print_starting_message=True,
+            )
+        finally:
+            self._serving = False
+
+    @staticmethod
+    def _validate_name(value: str, field: str) -> str:
+        if not isinstance(value, str):
+            raise TypeError(f"{field} 必须是字符串")
+
+        if not value or value != value.strip():
+            raise ValueError(f"{field} 不能为空或包含首尾空白")
+
+        if not all(
+                character.isascii()
+                and (character.isalnum() or character in "-_")
+                for character in value
+        ):
+            raise ValueError(
+                f"{field} 只能包含英文字母、数字、短横线和下划线"
+            )
+
+        return value
+
+    @staticmethod
+    def _build_schedule(
+            config: ScheduleConfig,
+    ) -> CronSchedule | IntervalSchedule:
+        if isinstance(config, CronScheduleConfig):
+            return CronSchedule(
+                cron=config.cron,
+                timezone=config.timezone,
+            )
+
+        if isinstance(config, IntervalScheduleConfig):
+            return IntervalSchedule(
+                interval=timedelta(seconds=config.seconds),
+            )
+
+        raise TypeError(f"不支持的调度配置类型：{type(config).__name__}")
+
+
+    def _print_task_table(self) -> None:
+        """打印已构建、待注册的部署配置。
+
+        Notes:
+            本表不代表服务端注册成功，也不代表 Runner 已启动。
+            满额策略统一为 CANCEL_NEW。
+        """
+        if not self._bindings:
+            return
+
+        table = Table(
+            box=box.SIMPLE,
+            show_header=True,
+            header_style="bold",
+            expand=False,
+            padding=(0, 1),
+        )
+        table.add_column("部署名称", style="cyan")
+        table.add_column("Flow")
+        table.add_column("调度计划", style="green")
+        table.add_column("时区")
+        table.add_column("最大实例", justify="right")
+        table.add_column("满额策略", style="yellow")
+
+        for binding in self._bindings.values():
+            config = binding.config
+
+            if isinstance(config, CronScheduleConfig):
+                schedule_text = f"Cron：{config.cron}"
+                timezone_text = config.timezone
+            else:
+                schedule_text = f"间隔：{config.seconds} 秒"
+                timezone_text = "—"
+
+            table.add_row(
+                Text(f"{self.namespace}-{binding.key}"),
+                Text(binding.flow.name),
+                Text(schedule_text),
+                Text(timezone_text),
+                str(config.max_instances),
+                "取消新运行",
+            )
+
+        panel = Panel(
+            table,
+            title=Text(f"待注册部署 · {len(self._bindings)} 个"),
+            subtitle=Text("配置构建完成，尚未确认远程注册成功"),
+            border_style="cyan",
+            title_align="left",
+            subtitle_align="left",
+            expand=False,
+        )
+
+        Console().print(panel)

fastapi_authly-0.1.30/src/fastapi_authly/schedule.py

@@ -0,0 +1,202 @@
+from dataclasses import dataclass
+from datetime import timedelta
+
+from prefect import Flow, aserve
+from prefect.client.schemas.schedules import CronSchedule, IntervalSchedule
+from prefect.deployments.runner import RunnerDeployment
+
+from .config import (
+    CronScheduleConfig,
+    IntervalScheduleConfig,
+    ScheduleConfig,
+)
+
+@dataclass(frozen=True)
+class _DeploymentBinding:
+    key: str
+    flow: Flow
+    config: ScheduleConfig
+
+class PrefectDeploymentManager:
+    """管理 Flow 与调度配置的绑定、部署构建及运行服务。
+
+    Args:
+        namespace: 项目或环境命名空间，例如 complaint-hb。
+
+    Examples:
+        manager = PrefectDeploymentManager(namespace="complaint-hb")
+        manager.add(
+            key="cluster",
+            flow=cluster_flow,
+            config=app_config.schedules["cluster"],
+        )
+        await manager.serve()
+    """
+
+    def __init__(self, namespace: str) -> None:
+        self.namespace = self._validate_name(namespace, "namespace")
+        self._bindings: dict[str, _DeploymentBinding] = {}
+        self._serving = False
+
+    def add(
+            self,
+            key: str,
+            flow: Flow,
+            config: ScheduleConfig,
+    ) -> None:
+        """绑定一个 Flow 与调度配置，不连接 Prefect 服务端。
+
+        Args:
+            key: 当前管理实例中唯一的任务标识，例如 cluster。
+            flow: 使用 Prefect @flow 装饰的工作流对象。
+            config: Cron 或固定间隔调度配置。
+
+        Raises:
+            ValueError: 任务标识非法或重复。
+            TypeError: flow 或 config 类型不正确。
+            RuntimeError: 服务运行期间尝试添加绑定。
+
+        Examples:
+            manager.add(
+                key="cluster",
+                flow=cluster_flow,
+                config=CronScheduleConfig(
+                    type="cron",
+                    cron="30 0 1,7,14,21 * *",
+                    timezone="Asia/Shanghai",
+                ),
+            )
+        """
+        if self._serving:
+            raise RuntimeError("服务运行期间不能添加任务")
+
+        key = self._validate_name(key, "key")
+
+        if key in self._bindings:
+            raise ValueError(f"任务标识重复：{key}")
+
+        if not isinstance(flow, Flow):
+            raise TypeError("flow 必须是使用 @flow 装饰的 Prefect Flow")
+
+        if not isinstance(
+                config,
+                (CronScheduleConfig, IntervalScheduleConfig),
+        ):
+            raise TypeError(
+                "config 必须是 CronScheduleConfig 或 IntervalScheduleConfig"
+            )
+
+        config_copy = type(config).model_validate(
+            config.model_dump(mode="python")
+        )
+
+        self._bindings[key] = _DeploymentBinding(
+            key=key,
+            flow=flow,
+            config=config_copy,
+        )
+
+    async def build_deployments(self) -> list[RunnerDeployment]:
+        """校验所有调度并构建 Deployment 对象，不启动运行服务。
+
+        Returns:
+            按添加顺序排列的 Deployment 对象列表。
+
+        Raises:
+            ValueError: 未添加任务或调度配置无效。
+            Exception: Prefect 部署构建异常原样向上传播。
+
+        Examples:
+            deployments = await manager.build_deployments()
+            await aserve(*deployments)
+
+        Notes:
+            部署名称为 namespace-key，不包含调度表达式或运行时间。
+            不设置业务参数，定时运行使用 Flow 自身的默认参数。
+        """
+        bindings = tuple(self._bindings.values())
+
+        if not bindings:
+            raise ValueError("没有可构建的任务，请先调用 add()")
+
+        schedules = [
+            self._build_schedule(binding.config)
+            for binding in bindings
+        ]
+
+        deployments: list[RunnerDeployment] = []
+
+        for binding, schedule in zip(bindings, schedules, strict=True):
+            deployment = await binding.flow.ato_deployment(
+                name=f"{self.namespace}-{binding.key}",
+                schedules=[schedule],
+            )
+            deployments.append(deployment)
+
+        return deployments
+
+    async def serve(self) -> None:
+        """注册部署并持续运行本地 Runner。
+
+        Raises:
+            RuntimeError: 同一管理实例已经在运行服务。
+            ValueError: 未添加任务。
+            Exception: 构建、注册或运行服务的异常原样向上传播。
+
+        Examples:
+            await manager.serve()
+
+        Notes:
+            此方法持续运行，正常停止后才返回。
+            正常关闭时请求暂停所服务部署的调度，不删除部署。
+            强制终止或网络故障时，暂停操作可能无法完成。
+        """
+        if self._serving:
+            raise RuntimeError("当前管理实例已经在运行服务")
+
+        self._serving = True
+
+        try:
+            deployments = await self.build_deployments()
+            await aserve(
+                *deployments,
+                pause_on_shutdown=True,
+            )
+        finally:
+            self._serving = False
+
+    @staticmethod
+    def _validate_name(value: str, field: str) -> str:
+        if not isinstance(value, str):
+            raise TypeError(f"{field} 必须是字符串")
+
+        if not value or value != value.strip():
+            raise ValueError(f"{field} 不能为空或包含首尾空白")
+
+        if not all(
+                character.isascii()
+                and (character.isalnum() or character in "-_")
+                for character in value
+        ):
+            raise ValueError(
+                f"{field} 只能包含英文字母、数字、短横线和下划线"
+            )
+
+        return value
+
+    @staticmethod
+    def _build_schedule(
+            config: ScheduleConfig,
+    ) -> CronSchedule | IntervalSchedule:
+        if isinstance(config, CronScheduleConfig):
+            return CronSchedule(
+                cron=config.cron,
+                timezone=config.timezone,
+            )
+
+        if isinstance(config, IntervalScheduleConfig):
+            return IntervalSchedule(
+                interval=timedelta(seconds=config.seconds),
+            )
+
+        raise TypeError(f"不支持的调度配置类型：{type(config).__name__}")