Kris
08617091dc
- 新增多个业务域的__init__.py模块文件，规范包导出结构 - 调整多个DTO文件的导入路径，统一模块组织方式 - 移除测试文件中多余的空行与导入语句 - 优化部分业务模块的包层级划分
91 lines
4.0 KiB
Python
91 lines
4.0 KiB
Python
"""控制面管道上下文。
|
||
|
||
定义控制面管道的可变局部上下文 ``ControlPlaneContext``，携带请求从 auth 到
|
||
audit 各阶段产生的状态。上下文为 ``@dataclass``（不 frozen），阶段直接修改
|
||
字段以推进管道状态。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from collections.abc import Awaitable, Callable
|
||
from dataclasses import dataclass, field
|
||
from typing import TYPE_CHECKING, Any
|
||
|
||
from yuxi.channels.contract.dtos.audit.audit import AuditTxStrategy
|
||
from yuxi.channels.contract.dtos.messaging.channel import ChannelType
|
||
from yuxi.channels.contract.dtos.messaging.common import Operator
|
||
from yuxi.channels.contract.dtos.shared.control import ControlPlaneResult
|
||
from yuxi.channels.contract.errors import Error
|
||
|
||
if TYPE_CHECKING:
|
||
from yuxi.channels.contract.ports.driven.shared.transaction_port import TransactionContext
|
||
|
||
|
||
@dataclass
|
||
class ControlPlaneContext:
|
||
"""控制面管道可变局部上下文。
|
||
|
||
携带控制面请求从 auth 到 audit 各阶段产生的状态，阶段按顺序填充字段。
|
||
字段按阶段分组，便于追溯状态来源。
|
||
|
||
事务边界（§10.1）：``tx`` 字段由 ``ChannelControlService`` 在管道
|
||
执行前通过 ``TransactionPort.begin()`` 开启，dispatch 与 audit 阶段
|
||
的写操作共享此事务上下文。``audit_tx_strategy`` 由 dispatch 阶段
|
||
根据操作副作用可回滚性设置：SHARED 策略下 audit 共享事务（fail-closed，
|
||
FR-34），INDEPENDENT 策略下 audit 使用独立事务（best-effort，适用于
|
||
已产生不可回滚外部副作用的操作）。
|
||
"""
|
||
|
||
# ---- 基础字段 ----
|
||
trace_id: str
|
||
request_id: str
|
||
operator: Operator
|
||
operation: str
|
||
params: dict[str, Any]
|
||
target_channel: ChannelType | None = None
|
||
|
||
# ---- 事务上下文（由 ChannelControlService 注入，dispatch/audit 共享）----
|
||
tx: TransactionContext | None = None
|
||
|
||
# ---- auth 阶段字段 ----
|
||
authenticated: bool = False
|
||
|
||
# ---- permission 阶段字段 ----
|
||
permission_granted: bool = False
|
||
required_permission: str | None = None
|
||
|
||
# ---- rate-limit 阶段字段 ----
|
||
rate_limit_passed: bool = False
|
||
|
||
# ---- dispatch 阶段字段 ----
|
||
dispatch_result: ControlPlaneResult | None = None
|
||
# dispatch 阶段幂等短路标记：当操作命中幂等条件（如 account/enable
|
||
# 对已启用账户）时，handler 未执行任何状态变更即提前返回，设置为 True
|
||
# 通知 audit 阶段跳过"状态变更类"审计写入，避免幂等请求被误记为
|
||
# 实际状态变更（§10.1 审计精确性）。
|
||
dispatch_skipped: bool = False
|
||
# dispatch 阶段部分成功标记：批量操作（如 message/batch_recall）中
|
||
# 部分目标成功、部分失败时由 handler 设置为 True，供
|
||
# ``ChannelControlService._executeControl`` 构造
|
||
# ``ControlResult(status="partial")``，使响应 envelope 能准确反映
|
||
# 部分成功语义，避免外层 ``success: True`` 误导客户端。
|
||
dispatch_partial: bool = False
|
||
|
||
# ---- audit 阶段字段 ----
|
||
audit_logged: bool = False
|
||
# dispatch 阶段根据操作副作用可回滚性设置（§10.1 事务边界）
|
||
audit_tx_strategy: AuditTxStrategy = AuditTxStrategy.SHARED
|
||
# INDEPENDENT 策略下 audit 写入失败时的错误（best-effort，由
|
||
# ChannelControlService 记录告警，不中止业务）
|
||
audit_error: Error | None = None
|
||
|
||
# ---- 降级标志字段 ----
|
||
degraded: bool = False
|
||
degraded_reason: Error | None = None
|
||
|
||
# ---- 事务后副作用钩子（dispatch 阶段注册，由 ChannelControlService
|
||
# 在事务提交成功后执行）。用于处理"DB 写入可回滚 + 外部副作用不可回滚"
|
||
# 混合场景：将不可回滚的外部副作用（如 ARQ 任务入队）推迟到事务提交后
|
||
# 执行，避免事务回滚时产生孤儿副作用（§10.1 事务边界）。
|
||
post_commit_hooks: list[Callable[[], Awaitable[None]]] = field(default_factory=list)
|