cancan-microstack 0.0.1__py3-none-any.whl

cancan_microstack/services/infrasrv/interface/api/service_registry.py

@@ -0,0 +1,117 @@
+from typing import List
+import http
+
+from cancan_microstack.public.const.error import ErrorCode
+from cancan_microstack.public.schemas.common import (
+    APIResponse,
+    MessageResp,
+)
+from cancan_microstack.public.schemas.infra.enums import (
+    HookExecutionResult,
+    ServiceType,
+)
+from cancan_microstack.public.schemas.infra.service_registry import (
+    ServiceInstance,
+    ServiceInstanceList,
+    ServiceRegistryCreate,
+)
+from linglong_web import build_success_response
+from cancan_microstack.public.error import HTTPException
+from cancan_microstack.services.infrasrv.application.service_registry import ServiceRegistryApp
+from cancan_microstack.services.infrasrv.domain.hooks import get_hook_manager
+from cancan_microstack.public.schemas.hooks import HookContext
+from linglong_web.utils import logger
+
+_service_registry_app = ServiceRegistryApp()
+_hook_manager = get_hook_manager()
+
+SERVICE_NAME_TO_TYPE = {
+    "infrasrv": ServiceType.INFRASTRUCTURE,
+    "opsbffsrv": ServiceType.OPS,
+}
+
+# 内置校验类钩子：这些钩子的 FAILURE 视为"校验未通过"，必须真正拒绝注册（返回 400），
+# 否则空 host / 坏端口 / 非法服务名等明显非法注册会被放行，使"校验"名不副实。
+# 钩子名称见 domain/hooks/builtin_hooks.py。
+ENFORCING_VALIDATION_HOOKS = frozenset({
+    "service_name_validation",
+    "host_validation",
+    "port_range_validation",
+    "service_quota",
+})
+
+
+async def register_service_handler(
+        service: ServiceRegistryCreate,
+) -> APIResponse[MessageResp | None]:
+    """
+    注册服务
+    供业务服务启动时注册使用
+    """
+    logger.info(
+        f"Received registration request for service: {service.service_name}, host: '{service.host}', port: {service.port}")
+
+    # 推导服务类型
+    service_type = SERVICE_NAME_TO_TYPE.get(service.service_name, ServiceType.BUSINESS)
+
+    # 创建钩子执行上下文
+    hook_context = HookContext(
+        service_name=service.service_name,
+        service_type=service_type,
+        instance_id=service.instance_id,
+        host=service.host,
+        port=service.port,
+        metadata=service.service_metadata or {}
+    )
+
+    # 执行预注册钩子
+    hook_results = await _hook_manager.execute_hooks(hook_context)
+
+    # 检查钩子执行结果
+    for hook_result in hook_results:
+        if hook_result.result == HookExecutionResult.TERMINATE:  # 钩子主动中断整条链，拒绝注册
+            raise HTTPException(
+                status_code=http.HTTPStatus.BAD_REQUEST.value,
+                error_code=ErrorCode.REGISTRATION_REJECTED,
+                msg=f"Registration rejected by hook {hook_result.hook_name}: {hook_result.message}",
+            )
+        elif hook_result.result == HookExecutionResult.FAILURE:
+            # 内置校验类钩子失败 = 注册信息非法，真正拒绝注册（让"校验"名副其实）。
+            if hook_result.hook_name in ENFORCING_VALIDATION_HOOKS:
+                raise HTTPException(
+                    status_code=http.HTTPStatus.BAD_REQUEST.value,
+                    error_code=ErrorCode.REGISTRATION_REJECTED,
+                    msg=f"Registration rejected by validation hook {hook_result.hook_name}: {hook_result.message}",
+                )
+            # 其它（非内置校验）钩子失败维持原行为：仅告警、不拦截。
+            logger.warning(f"Hook {hook_result.hook_name} failed: {hook_result.message or hook_result.error}")
+
+    # 如果钩子修改了服务信息，使用修改后的信息
+    # 这里可以添加逻辑处理钩子对上下文的修改
+
+    await _service_registry_app.register_service(service)
+    return build_success_response(data=MessageResp(message="Service registered successfully"))
+
+
+async def deregister_service_handler(
+        service_name: str,
+        instance_id: str,
+) -> APIResponse[MessageResp]:
+    """
+    注销服务
+    供业务服务关闭时注销使用
+    """
+    await _service_registry_app.deregister_service(service_name, instance_id)
+    return build_success_response(data=MessageResp(message="Service deregistered successfully"))
+
+
+async def get_service_instances_handler(
+        service_name: str,
+        only_healthy: bool = True,
+) -> APIResponse[ServiceInstanceList]:
+    """
+    获取服务实例列表
+    供业务服务进行服务发现使用
+    """
+    instances: List[ServiceInstance] = await _service_registry_app.get_service_instances(service_name, only_healthy)
+    return build_success_response(data=ServiceInstanceList(instances=instances))

cancan_microstack/services/infrasrv/interface/api/workflow_api.py

@@ -0,0 +1,303 @@
+"""
+工作流引擎 API 接口层
+Workflow Engine API Interface Layer
+"""
+from datetime import datetime
+from typing import (
+    Dict,
+    Any,
+    Optional,
+)
+
+from fastapi import Query
+
+from linglong_web import build_success_response
+from cancan_microstack.public.schemas.common import APIResponse
+from cancan_microstack.public.schemas.infra import workflow as workflow_types
+from cancan_microstack.services.infrasrv.application.workflow.workflow_app import workflow_app
+
+
+async def create_workflow_handler(
+        payload: workflow_types.WorkflowDefinitionCreate,
+) -> APIResponse[workflow_types.WorkflowDefinition]:
+    """
+    创建一个新的工作流定义
+    Create a new workflow definition.
+
+    Args:
+        payload: 工作流定义数据
+                 Workflow definition data.
+
+    Returns:
+        已创建的工作流定义
+        The created workflow definition.
+    """
+    result = await workflow_app.create_workflow_definition(payload)
+    return build_success_response(data=result)
+
+
+async def list_workflows_handler(
+        page: int = Query(1, ge=1, description="页码"),
+        page_size: int = Query(20, ge=1, le=100, description="每页大小"),
+) -> APIResponse[workflow_types.WorkflowListResponse]:
+    """
+    列出所有工作流定义
+    List all workflow definitions.
+
+    Returns:
+        工作流定义列表
+        A list of workflow definitions.
+    """
+    result = await workflow_app.list_workflow_definitions(page, page_size)
+    return build_success_response(data=result)
+
+
+async def get_workflow_handler(
+        workflow_id: str,
+) -> APIResponse[workflow_types.WorkflowDefinition]:
+    """
+    根据 ID 获取指定的工作流定义
+    Get a specific workflow definition by ID.
+
+    Args:
+        workflow_id: 工作流定义的唯一标识符
+                     The unique identifier of the workflow definition.
+
+    Returns:
+        工作流定义
+        The workflow definition.
+    """
+    result = await workflow_app.get_workflow_definition(workflow_id)
+    return build_success_response(data=result)
+
+
+async def list_workflow_versions_handler(
+        workflow_id: str,
+        limit: int = Query(50, ge=1, le=200, description="返回的版本数量限制"),
+) -> APIResponse[workflow_types.WorkflowVersionListResponse]:
+    """列出指定工作流的版本历史
+    List workflow definition versions for the given workflow."""
+
+    result = await workflow_app.list_workflow_versions(workflow_id, limit)
+    return build_success_response(data=result)
+
+
+async def list_runs_handler(
+        workflow_id: Optional[str] = Query(None, description="按工作流ID过滤"),
+        reqid: Optional[str] = Query(None, description="按请求追踪 ID 过滤"),
+        status: Optional[str] = Query(None, description="运行状态过滤"),
+        date_from: Optional[datetime] = Query(None, description="开始时间过滤"),
+        date_to: Optional[datetime] = Query(None, description="结束时间过滤"),
+        page: int = Query(1, ge=1, description="页码"),
+        page_size: int = Query(20, ge=1, le=100, description="每页数量"),
+) -> APIResponse[workflow_types.WorkflowRunListResponse]:
+    """
+    列出工作流的运行实例
+    List workflow runs.
+
+    Args:
+        workflow_id: (可选) 按工作流 ID 过滤
+                     (Optional) Filter by workflow ID.
+        page: 页码
+              Page number.
+          page_size: 每页大小
+                 Size per page.
+
+    Returns:
+        工作流运行实例列表
+        A list of workflow runs.
+    """
+    query = workflow_types.WorkflowRunQuery(
+        workflow_id=workflow_id,
+        reqid=reqid,
+        status=status,
+        date_from=date_from,
+        date_to=date_to,
+        page=page,
+        page_size=page_size,
+    )
+    result = await workflow_app.list_workflow_runs(query)
+    return build_success_response(data=result)
+
+
+async def trigger_workflow_handler(
+        workflow_id: str, payload: workflow_types.WorkflowTriggerRequest,
+) -> APIResponse[workflow_types.WorkflowTriggerResponse]:
+    """
+    触发一次工作流运行
+    Trigger a workflow run.
+
+    Args:
+        workflow_id: 要触发的工作流的 ID
+                     The ID of the workflow to trigger.
+        payload: 触发工作流的上下文数据
+                 The context data for triggering the workflow.
+
+    Returns:
+        包含运行 ID 和状态的字典
+        A dictionary containing the run ID and status.
+    """
+    result = await workflow_app.trigger_workflow(workflow_id, payload)
+    return build_success_response(data=result)
+
+
+async def get_run_graph_status_handler(
+        run_id: str,
+) -> APIResponse[workflow_types.RunGraphResponse]:
+    """
+    获取工作流运行实例中所有节点的状态
+    Get the status of all nodes in a workflow run graph.
+
+    Args:
+        run_id: 工作流运行实例的 ID
+                The ID of the workflow run instance.
+
+    Returns:
+        节点状态列表
+        A list of node statuses.
+    """
+
+    result = await workflow_app.get_run_graph_status(run_id)
+    return build_success_response(data=result)
+
+
+async def get_node_history_handler(
+        run_id: str, node_id: str,
+) -> APIResponse[workflow_types.NodeExecutionHistoryResponse]:
+    """
+    获取运行实例中特定节点的执行历史
+    Get the execution history of a specific node in a run.
+
+    Args:
+        run_id: 工作流运行实例的 ID
+                The ID of the workflow run instance.
+        node_id: 节点的 ID
+                 The ID of the node.
+
+    Returns:
+        节点的执行历史列表
+        A list of execution history for the node.
+    """
+    result = await workflow_app.get_node_history(run_id, node_id)
+    return build_success_response(data=result)
+
+
+async def external_callback_handler(
+        node_instance_id: str, payload: Dict[str, Any],
+) -> APIResponse[workflow_types.CallbackAckResponse]:
+    """
+    处理等待外部回调的节点的恢复操作
+    Handle external callbacks for suspended nodes.
+
+    Args:
+        node_instance_id: 节点实例的唯一标识符
+                          The unique identifier of the node instance.
+        payload: 外部服务返回的数据
+                 Data returned from the external service.
+
+    Returns:
+        确认接受回调的状态
+        A status confirming acceptance of the callback.
+    """
+    result = await workflow_app.handle_external_callback(node_instance_id, payload)
+    return build_success_response(data=result)
+
+
+async def get_workflow_stats_handler() -> APIResponse[workflow_types.WorkflowStats]:
+    """
+    获取工作流统计信息
+    Get workflow statistics.
+
+    Returns:
+        工作流统计信息
+        Workflow statistics.
+    """
+    result = await workflow_app.get_workflow_stats()
+    return build_success_response(data=result)
+
+
+async def update_workflow_handler(
+        workflow_id: str,
+        payload: workflow_types.WorkflowDefinitionUpdate,
+) -> APIResponse[workflow_types.WorkflowDefinition]:
+    """
+    更新工作流定义
+    Update workflow definition.
+
+    Args:
+        workflow_id: 工作流唯一标识符 / Workflow unique identifier.
+        payload: 更新数据 / Update data.
+
+    Returns:
+        更新后的工作流定义 / The updated workflow definition.
+    """
+    result = await workflow_app.update_workflow_definition(workflow_id, payload)
+    return build_success_response(data=result)
+
+
+async def delete_workflow_handler(
+        workflow_id: str,
+) -> APIResponse[Dict[str, str]]:
+    """
+    删除工作流定义
+    Delete workflow definition.
+
+    Args:
+        workflow_id: 工作流唯一标识符 / Workflow unique identifier.
+
+    Returns:
+        删除确认消息 / Deletion confirmation message.
+    """
+    await workflow_app.delete_workflow_definition(workflow_id)
+    return build_success_response(data={"message": "Workflow deleted successfully"})
+
+
+async def rollback_workflow_handler(
+        workflow_id: str,
+        payload: workflow_types.WorkflowRollbackRequest,
+) -> APIResponse[workflow_types.WorkflowDefinition]:
+    """回滚工作流定义到指定版本
+    Roll back workflow definition to a historical version."""
+
+    result = await workflow_app.rollback_workflow_definition(workflow_id, payload)
+    return build_success_response(data=result)
+
+
+async def list_engine_alerts_handler(
+        status: Optional[workflow_types.WorkflowEngineAlertStatus] = Query(None, description="按状态过滤"),
+        severity: Optional[workflow_types.WorkflowEngineAlertSeverity] = Query(None, description="按严重程度过滤"),
+        run_id: Optional[str] = Query(None, description="按运行 ID 过滤"),
+        page: int = Query(1, ge=1, description="页码"),
+        page_size: int = Query(20, ge=1, le=200, description="每页大小"),
+) -> APIResponse[workflow_types.WorkflowEngineAlertListResponse]:
+    """列出工作流引擎告警"""
+
+    query = workflow_types.WorkflowEngineAlertQuery(
+        status=status,
+        severity=severity,
+        run_id=run_id,
+        page=page,
+        page_size=page_size,
+    )
+    result = await workflow_app.list_engine_alerts(query)
+    return build_success_response(data=result)
+
+
+async def acknowledge_engine_alert_handler(
+        alert_id: str,
+        payload: workflow_types.WorkflowEngineAlertAckRequest,
+) -> APIResponse[workflow_types.WorkflowEngineAlert]:
+    """标记引擎告警为已知晓"""
+
+    result = await workflow_app.acknowledge_engine_alert(alert_id, payload)
+    return build_success_response(data=result)
+
+
+async def resolve_engine_alert_handler(
+        alert_id: str,
+        payload: workflow_types.WorkflowEngineAlertAckRequest,
+) -> APIResponse[workflow_types.WorkflowEngineAlert]:
+    """标记引擎告警为已解决"""
+
+    result = await workflow_app.resolve_engine_alert(alert_id, payload)
+    return build_success_response(data=result)

cancan_microstack/services/infrasrv/interface/schedule/cleanup.py

@@ -0,0 +1,13 @@
+from linglong_web.utils import logger
+from cancan_microstack.services.infrasrv.application.service_registry import ServiceRegistryApp
+
+_service_registry_app = ServiceRegistryApp()
+
+
+async def cleanup_dead_instances_task():
+    """定期清理已下线的服务实例"""
+    try:
+        logger.info("Running scheduled cleanup of dead service instances...")
+        await _service_registry_app.cleanup_dead_instances()
+    except Exception as e:
+        logger.error(f"Error in cleanup task: {e}", exc_info=True)

cancan_microstack/services/infrasrv/interface/schedule/health_check.py

@@ -0,0 +1,27 @@
+from linglong_web.utils import logger
+from cancan_microstack.services.infrasrv.application.health_check_app import HealthCheckApp
+
+_health_check_app = HealthCheckApp()
+
+
+async def health_check_task():
+    """
+    定期健康检查任务
+    
+    支持：
+    - 多实例健康检查
+    - 操作窗口期豁免
+    - 区分正常/异常关闭
+    - 自动重启不健康实例
+    """
+    try:
+        logger.info("Running scheduled health check (multi-instance)...")
+        result = await _health_check_app.check_all_instances()
+
+        logger.info(
+            f"Health check completed: {result.healthy} healthy, "
+            f"{result.degraded} degraded, {result.unhealthy} unhealthy, "
+            f"{result.exempted} exempted, {result.expected_stopped} expected_stopped"
+        )
+    except Exception as e:
+        logger.error(f"Error in health check task: {e}", exc_info=True)

cancan_microstack/services/infrasrv/interface/schedule/log_cleanup.py

@@ -0,0 +1,26 @@
+"""日志清理定时任务 / Scheduled task for log retention."""
+from datetime import datetime, timedelta, timezone
+
+from linglong_web import LinglongConfig
+from linglong_web.utils import logger
+
+from cancan_microstack.services.infrasrv.application.logging.log_ingestion_service import get_log_ingestion_service
+
+
+async def cleanup_expired_logs_task() -> None:
+    """删除超过保留期的日志 / Delete logs that exceed retention."""
+    # 从运行时配置读取日志保留策略，提供安全默认值。
+    # Read retention policy from runtime config with safe defaults.
+    retention_days = int(LinglongConfig.LOG_RETENTION_DAYS)
+    batch_limit = int(LinglongConfig.LOG_RETENTION_BATCH_LIMIT)
+    cutoff = datetime.now(timezone.utc) - timedelta(days=retention_days)
+
+    repo = get_log_ingestion_service().get_repository()
+    if repo is None:
+        logger.warning("Log repository not available, skipping cleanup task")
+        return
+
+    deleted = await repo.cleanup_older_than(cutoff, batch_limit)
+    logger.info(
+        "Log retention cleanup finished: deleted=%s cutoff=%s", deleted, cutoff.isoformat()
+    )

cancan_microstack/services/infrasrv/interface/schedule/operation_tracker.py

@@ -0,0 +1,25 @@
+"""定时同步 controllersrv 任务状态 / Periodic controllersrv task synchronisation"""
+import asyncio
+
+from linglong_web.utils import logger
+
+from cancan_microstack.services.infrasrv.application.service_operation_tracker import (
+    ServiceOperationTrackerApp,
+)
+
+_tracker_app = ServiceOperationTrackerApp()
+_poll_lock = asyncio.Lock()
+
+
+async def operation_tracker_task() -> None:
+    """每次执行时轮询 controllersrv 并刷新操作状态 / Poll controllersrv and refresh operation states"""
+
+    if _poll_lock.locked():
+        logger.warning("Operation tracker still running, skipping this tick")
+        return
+
+    async with _poll_lock:
+        try:
+            await _tracker_app.run_once()
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Operation tracker failed: %s", exc, exc_info=True)

cancan_microstack/services/infrasrv/interface/schedule/scheduler.py

@@ -0,0 +1,39 @@
+from aioclock import Every
+
+from linglong_web import (
+    BaseScheduler,
+    to_group,
+)
+from cancan_microstack.services.infrasrv.interface.schedule.health_check import health_check_task
+from cancan_microstack.services.infrasrv.interface.schedule.cleanup import cleanup_dead_instances_task
+from cancan_microstack.services.infrasrv.interface.schedule.log_cleanup import cleanup_expired_logs_task
+from cancan_microstack.services.infrasrv.interface.schedule.workflow_scheduler import workflow_scheduler_task
+from cancan_microstack.services.infrasrv.interface.schedule.operation_tracker import operation_tracker_task
+
+scheduler_group = to_group([
+    BaseScheduler(
+        name="service_health_check",
+        trigger=Every(seconds=30, first_run_strategy="wait"),
+        func=health_check_task,
+    ),
+    BaseScheduler(
+        name="operation_tracker",
+        trigger=Every(seconds=10, first_run_strategy="wait"),
+        func=operation_tracker_task,
+    ),
+    BaseScheduler(
+        name="cleanup_dead_instances",
+        trigger=Every(minutes=5, first_run_strategy="wait"),
+        func=cleanup_dead_instances_task,
+    ),
+    BaseScheduler(
+        name="cleanup_log_documents",
+        trigger=Every(hours=24, first_run_strategy="immediate"),
+        func=cleanup_expired_logs_task,
+    ),
+    BaseScheduler(
+        name="workflow_scheduler",
+        trigger=Every(minutes=1, first_run_strategy="immediate"),
+        func=workflow_scheduler_task,
+    ),
+])

cancan_microstack/services/infrasrv/interface/schedule/workflow_scheduler.py

@@ -0,0 +1,115 @@
+"""
+Workflow Scheduler Task
+"""
+from datetime import (
+    datetime,
+    timedelta,
+)
+from typing import Optional
+
+from croniter import croniter
+
+from cancan_microstack.public.schemas.infra import workflow as workflow_types
+from linglong_web.utils import (
+    get_request_id,
+    logger,
+    set_request_id,
+)
+
+from cancan_microstack.services.infrasrv.application.workflow.workflow_app import workflow_app
+
+
+async def workflow_scheduler_task():
+    """扫描并触发需要调度的工作流
+    Scan for due workflows and trigger them via the workflow app.
+    """
+    logger.info("Workflow scheduler task started.")
+    try:
+        await scan_and_trigger_workflows()
+    except Exception as exc:
+        logger.error(f"Error in workflow scheduler: {exc}", exc_info=True)
+
+
+async def scan_and_trigger_workflows(reference_time: Optional[datetime] = None):
+    """Scan registered definitions and trigger due workflows.
+    扫描已注册的工作流定义并触发符合条件的调度。
+    """
+
+    now = (reference_time or datetime.now()).replace(microsecond=0)
+    scheduled_workflows = await workflow_app.get_scheduled_workflows()
+
+    if not scheduled_workflows:
+        logger.info("No scheduled workflows found.")
+        return
+
+    triggered_count = 0
+    for workflow in scheduled_workflows:
+        cron_expr = (workflow.schedule or "").strip()
+        if not cron_expr:
+            logger.warning(f"Empty cron string for workflow {workflow.id}")
+            continue
+
+        second_at_beginning = _cron_has_seconds(cron_expr)
+        if not croniter.is_valid(cron_expr, second_at_beginning=second_at_beginning):
+            logger.warning(f"Invalid cron string for workflow {workflow.id}: {workflow.schedule}")
+            continue
+
+        base_time = _normalize_base_time(cron_expr, now)
+        if not _cron_due(cron_expr, base_time):
+            continue
+
+        logger.info(f"Triggering scheduled workflow: {workflow.name} ({workflow.id})")
+        try:
+            # 每个调度触发分配独立 reqid，便于全链路检索
+            # Allocate dedicated reqid per scheduled trigger for end-to-end traceability
+            set_request_id(None)
+            scheduled_reqid = get_request_id()
+            await workflow_app.trigger_workflow(
+                workflow_id_str=str(workflow.id),
+                payload=workflow_types.WorkflowTriggerRequest(
+                    trigger_context={
+                        "scheduled_time": base_time.isoformat(),
+                        "reqid": scheduled_reqid,
+                    }
+                ),
+                trigger_type=workflow_types.TriggerType.SCHEDULE,
+            )
+            triggered_count += 1
+        except Exception as e:
+            logger.error(f"Failed to trigger workflow {workflow.id}: {e}", exc_info=True)
+
+    logger.info(f"Workflow scheduler task finished. Triggered {triggered_count} workflows.")
+
+
+def _cron_due(expression: str, base_time: datetime) -> bool:
+    """Return True when the cron expression fires near *base_time*.
+    当 cron 表达式在基准时间附近触发时返回 True。
+    """
+
+    try:
+        second_at_beginning = _cron_has_seconds(expression)
+        cron = croniter(
+            expression,
+            base_time + timedelta(seconds=1),
+            second_at_beginning=second_at_beginning,
+        )
+        prev_fire = cron.get_prev(datetime)
+    except Exception as exc:  # noqa: BLE001 - croniter raises generic exceptions
+        logger.warning("Failed to iterate cron '%s': %s", expression, exc)
+        return False
+
+    tolerance_seconds = 1 if _cron_has_seconds(expression) else 60
+    delta = (base_time - prev_fire).total_seconds()
+    return 0 <= delta <= tolerance_seconds
+
+
+def _cron_has_seconds(expression: str) -> bool:
+    parts = [part for part in expression.split() if part]
+    return len(parts) >= 6
+
+
+def _normalize_base_time(expression: str, reference_time: datetime) -> datetime:
+    normalized = reference_time.replace(microsecond=0)
+    if _cron_has_seconds(expression):
+        return normalized
+    return normalized.replace(second=0)