ErisPulse ErisPulse
インタラクティブ版で開く →
このページのセクション
静的ミラーです。内容はインタラクティブ版が正となります インタラクティブ版で開く →

ErisPulse.Core.shadow 模块


模块概述

ErisPulse 影子模块(方向十一:Shadow Modules & Canary Promote)

影子 = 同一模块的新版本,以独立 owner(如 roll_shadow)与线上 旧版并存试运行:它收到真实事件的副本、其出站被拦截记账而非真正 发出——确认无害后 promote 一键转正,dismiss 随时放弃。模块代码 零改动,全程 API 驱动(运行时操作,与 load / unload / reload 同类; Dashboard / 自定义管理模块调用这些 API,无需用户手写任何配置)。

  • 机制与诚实边界:docs/zh-CN/advanced/shadow.md

提示

  1. sdk.module.shadow_start("roll", source="路径/到/v2") 启动影子: source 为新版代码的目录或单文件路径(建议放在 plugins 目录之外, 避免被普通发现机制装载);影子 owner 名默认取路径名
  2. 出站拦截覆盖 Send DSL 与 Api DSL;绕过框架的裸 call_api / aiohttp / 线程拦不住;ORM 读写不进存储覆盖层
  3. 转正永远由人确认:await sdk.module.promote_shadow("roll"),失败 自动回滚旧实例继续服务;dismiss_shadow 随时放弃

函数列表

_source_in_plugin_dirs(plugin_loader: Any, source: Path) -> bool

内部方法 判断影子源路径是否位于插件发现目录内(位于其内时才需要写 status 禁用, 防止下次启动被普通发现机制当作独立模块装载)

  • plugin_loader: 插件加载器(提供 get_plugins_dirs())
  • source: 影子源路径

返回值: 源位于任一插件目录内时 True(判定失败按 False 处理——宁可不

写配置也不误禁同名真实插件)

类列表

class ShadowLedger

影子账本:影子 owner 的意向出站记录(内存环形,按 owner 分桶)

记录来源:出站闸(Send DSL / Api DSL)在 owner 属影子时写入。 每条含 kind(send/api)/ platform / method / target / trace_id / preview。

方法列表

record(owner: str, entry: 'dict[str, Any]') -> None

记录一条影子意向出站

  • owner: 影子 owner 名
  • entry: 出站条目(kind/platform/method/target/trace_id/preview 等)

entries(owner: str) -> 'list[dict[str, Any]]'

读取影子 owner 的全部在账条目(时间序)

  • owner: 影子 owner 名

返回值: 条目列表(无在账条目时为空列表)


clear(owner: str) -> None

清空影子 owner 的账本

  • owner: 影子 owner 名

class ShadowOverlay

存储内存覆盖层:影子 owner 的 KV 写隔离

语义:写进覆盖层(不落库)、删为墓碑、读先查覆盖层——命中返回影子值, 命中墓碑视为"已删除"(回退默认值),未命中透传真库。ORM 读写不在 覆盖层语义内(文档声明)。

方法列表

write(key: str, value: Any) -> None

写入覆盖层


delete(key: str) -> None

写入墓碑(影子视角的删除)


read(key: str) -> 'tuple[str, Any]'

查询覆盖层

  • key: 存储键(含嵌套路径原样匹配)

返回值: (状态, 值);状态 "hit"(影子值)/ "tombstone"(影子已删除,

     不应透传真库)/ "miss"(未命中,透传真库)

class ShadowManager

影子模块管理器(单例)

维护 原模块名 → 影子实例 的绑定、影子账本与存储覆盖层,并提供 start(启动影子)/ promote(转正)/ dismiss(放弃)/ diff(对比)。 子系统八道闸只依赖 ownership.is_shadow 与 :data:shadow_ledger / :func:shadow_overlay,不反向依赖本管理器。

方法列表

shadow_owner_of(real_name: str) -> 'str | None'

查询原模块当前绑定的影子 owner 名

  • real_name: 原模块名

返回值: 影子 owner 名(未绑定为 None)


real_name_of(shadow_owner: str) -> 'str | None'

查询影子 owner 对应的原模块名

  • shadow_owner: 影子 owner 名

返回值: 原模块名(非影子为 None)


bindings() -> 'dict[str, str]'

当前全部影子绑定(只读视图)

返回值: {原模块名: 影子 owner 名}


ingest_whl(module_name: str, data: bytes, filename: str) -> 'dict[str, str]'

摄取 whl 作为影子源:校验 → 原件落盘 → 解包 → 推导 source

原件与解包目录同级(shadows/<module>/<时间戳>/):解包目录供 :meth:~ShadowManager.start 装载,原件供「转正并持久化」pip 安装。 影子期只解包不安装(pip 排他),避免覆盖已装包。

  • module_name: 被影子测试的模块名(仅作落盘目录段)
  • data (whl): 文件字节
  • filename (whl): 文件名(PEP 427:name-version-...whl)

返回值: {"source": 解包源目录, "whl_path": 原件路径}

异常: ShadowSourceError - 文件名/大小非法、zip 非法或无法推导源目录

示例:

sdk.module.shadow_ingest_whl("roll", data=whl_bytes, filename="roll-2.0-py3-none-any.whl")
{'source': '.../shadows/roll/2026.../roll', 'whl_path': '.../shadows/roll/2026.../roll-2.0-py3-none-any.whl'}

validate_persist_whl(module_name: str, whl_path: 'str | Path') -> Path

校验「转正并持久化」的 whl 原件路径

路径必须存在、是 .whl,且位于本模块的 shadows/<module>/ 目录内。

  • module_name: 模块名
  • whl_path: 待校验路径

返回值: 规范化后的路径

异常: ShadowSourceError - 路径缺失 / 非法 / 越界


persist_status(task_id: str) -> 'dict[str, Any] | None'

查询「转正并持久化」后台 pip 任务状态

  • task_id: :meth:start_persist 返回的任务 ID

返回值: {"status": running/success/error, "output": [...], ...};未知任务为 None


start_persist(whl_path: 'str | Path') -> 'dict[str, Any]'

后台 pip 安装 whl 原件(转正成功后调用;进程内 fire-and-forget)

  • whl_path: 经 :meth:validate_persist_whl 校验的 whl 路径

返回值: {"task_id": str}


_record_persist_task(task_id: str, entry: 'dict[str, Any]') -> None

内部方法 记录持久化任务状态(环形上限)


_run_pip_persist(task_id: str, whl_path: Path) -> None

内部方法 执行 pip install 并回写任务状态


_extract_shadow_whl(data: bytes, dest: Path, dist_name: str) -> Path

内部方法 解包 whl(zip)到 dest 并推导影子源目录

安全限制:条目数 / 解包总大小上限、拒绝绝对路径 / 盘符 / .. (防 ZipSlip)。source 推导:唯一含 __init__.py 的顶层包目录优先 (发行名匹配者优先),其次扁平 wheel 解包根,最后唯一同名单文件模块。


_norm_wheel_dist_name(name: str) -> str(staticmethod)

内部方法 wheel 发行名归一化(PEP 503)


_derive_shadow_source(dest: Path, dist_name: str) -> Path

内部方法 从解包结果推导 shadow_start 可用的 source


bind(real_name: str, shadow_owner: str) -> None

登记 绑定关系(影子启动成功后调用;同时向归属权登记影子状态)

  • real_name: 原模块名
  • shadow_owner: 影子 owner 名

unbind(shadow_owner: str) -> 'str | None'

解除影子绑定(dismiss / 转正后调用;同步移除归属权影子状态)

  • shadow_owner: 影子 owner 名

返回值: 对应原模块名(未绑定为 None)


overlay(shadow_owner: str) -> ShadowOverlay

获取影子 owner 的存储覆盖层(惰性创建)

  • shadow_owner: 影子 owner 名

返回值: 覆盖层实例


_cleanup_sdk_attr(sdk: Any, owner: str) -> None(staticmethod)

内部方法 清理 start 时挂在 sdk 上的影子实例属性(转正 / 放弃后残留会指向已回收实例)

  • sdk (SDK): 实例(None 时跳过)
  • owner: 影子 owner 名

async start(real_name: str, source: 'str | Path', manager: Any, sdk: Any, owner: 'str | None' = None, loader: 'Any | None' = None) -> str

启动影子:把新版代码以独立 owner 装载为 real_name 的影子实例

source 为新版代码的目录或单 .py 文件路径(推荐放在 plugins 目录 之外,避免被普通发现机制当作独立模块装载)。影子以独立 owner 运行: 收到真实事件副本、出站被拦截记账、配置继承原模块配置节。

  • real_name: 被 shadow 的已加载模块名

  • source: 新版代码路径(目录含 __init__.py 或单 .py 文件)

  • manager: 模块管理器实例

  • sdk (SDK): 实例

  • owner: 影子 owner 名(默认取路径名,非法时回退

            ``f"{real_name}_shadow"``)
    
  • loader: 模块加载器实例(None 时自动取 sdk._module_loader)

返回值: 影子 owner 名

异常: ShadowStateError - 原模块未加载 / 影子已存在

异常: ShadowSourceError - 源路径无效 / 加载器缺失 / 影子装载失败

示例:

await sdk.module.shadow_start("roll", source="downloads/roll_v2")
'roll_shadow'

async promote(real_name: str, manager: Any, sdk: Any, loader: 'Any | None' = None) -> bool

转正:卸载当前版本 → 影子以真名注册加载 → 失败自动回滚继续服务

复用方向 10 的重载快照机制(当前版本与级联依赖者先行快照)。 转正后建议尽快把新版本持久化安装(pip 升级 / 替换插件文件), 使重启后仍然生效——运行时切换不会替你完成包管理。

  • real_name: 原模块名
  • manager: 模块管理器实例
  • sdk (SDK): 实例
  • loader: 模块加载器实例(None 时自动取 sdk._module_loader)

返回值: 是否转正成功


async dismiss(real_name: str, manager: Any, sdk: 'Any | None' = None) -> bool

放弃影子:回收影子资源、解除绑定、清空账本与命令目录

  • real_name: 原模块名
  • manager: 模块管理器实例
  • sdk (SDK): 实例(可选;传入时清理挂在 sdk 上的影子实例属性残留)

返回值: 是否成功


diff(real_name: str, transcript: 'Any | None' = None) -> 'dict[str, Any]'

行为对比:影子意向出站 × 真实发送时间线(按 trace_id 对齐)

内容保真度受 transcript 出站 preview(50 字符截断)限制——逐字段 对比以影子账本为准,transcript 仅作"实际发送发生"的佐证源。

  • real_name: 原模块名
  • transcript: 收件箱单例(None 时惰性导入)

返回值: {"shadow_owner", "count", "aligned": [{"shadow", "actual"}]}