From b02def0b9d1a7a457fd8fd5c772a12d76cc5b930 Mon Sep 17 00:00:00 2001 From: F18-Ray Date: Mon, 16 Nov 2026 12:59:49 +0800 Subject: [PATCH 01/19] refactor(connect_tcp): add transfer control parsing and identity foundations --- PyFlow/network_api/connect_tcp.py | 69 +++++- .../transfer-pause-start-direction-plan.md | 223 ++++++++++++++++++ .../transfer-pause-start-direction-report.md | 79 +++++++ docs/source/changes/transfer-fid-routes.md | 17 ++ .../unit/network_api/test_transfer_control.py | 109 +++++++++ 5 files changed, 487 insertions(+), 10 deletions(-) create mode 100644 docs/plans/transfer-pause-start-direction-plan.md create mode 100644 docs/plans/transfer-pause-start-direction-report.md create mode 100644 test/unit/network_api/test_transfer_control.py diff --git a/PyFlow/network_api/connect_tcp.py b/PyFlow/network_api/connect_tcp.py index 876f6c1..648ef73 100644 --- a/PyFlow/network_api/connect_tcp.py +++ b/PyFlow/network_api/connect_tcp.py @@ -747,6 +747,49 @@ def run(): return True +def _validate_transfer_control_identity(fid, trans_type, direction): + """Validate a file leg's id, transfer type and sender/receiver role.""" + if type(fid) is not int or fid < 0: + raise ValueError("fid must be a nonnegative integer") + if type(trans_type) is not int or trans_type not in (0, 1): + raise ValueError("trans_type must be 0 (ordinary) or 1 (forwarded)") + if type(direction) is not int or direction not in (0, 1): + raise ValueError("direction must be 0 (sender) or 1 (receiver)") + + +def _parse_transfer_control_command(command): + """Parse a four-token pause/start line, returning None for malformed input. + + Return ``(paused, fid, trans_type, direction)``. The wire direction is the + command issuer's role; the receiving side's local role is ``1 - direction``. + This parser does not resolve a peer, register state or send a response. + """ + if not isinstance(command, str): + return None + try: + parts = shlex.split(command) + if len(parts) != 4: + return None + name = parts[0].lower() + if name not in ("/pause_trans", "/start_trans"): + return None + fid, trans_type, direction = map(int, parts[1:]) + _validate_transfer_control_identity(fid, trans_type, direction) + return name == "/pause_trans", fid, trans_type, direction + except ValueError: + return None + + +def _transfer_control_key(peer, fid, trans_type, direction): + """Build a runtime control key from a resolved peer and the local leg role. + + Callers resolve configured/concrete endpoints before building the key and + invert incoming wire directions. Progress stores retain their existing keys. + """ + _validate_transfer_control_identity(fid, trans_type, direction) + return tuple(peer), fid, trans_type, direction + + def _pause_command_fid(command): """Return the fid of a ``/pause_trans``/``/start_trans`` line, or None. @@ -1065,6 +1108,19 @@ def _socket_peer_endpoint(sock): return (address[0], address[1]) if address else None +def _is_control_endpoint(endpoint, configured_endpoint, connected_endpoint): + """Match only the configured identity or this connection's actual endpoint. + + ``connected_endpoint`` comes from the appropriate local/peer socket helper; + None keeps only the configured fallback after a control socket is closed. + A wildcard configuration never makes unrelated same-port addresses match. + """ + endpoint = tuple(endpoint) + return endpoint == configured_endpoint or ( + connected_endpoint is not None and endpoint == connected_endpoint + ) + + class _FidAllocator: """Hand out transfer ids that never collide with a live one. @@ -6532,12 +6588,8 @@ def _is_control_local_endpoint(self, endpoint, sock): Returns: bool: True when the endpoint is this side of that connection. """ - endpoint = tuple(endpoint) - if endpoint == (self.host, self.port): - return True - if isinstance(sock, tuple): - return endpoint == tuple(sock) - return endpoint == _socket_local_endpoint(sock) + connected_endpoint = tuple(sock) if isinstance(sock, tuple) else _socket_local_endpoint(sock) + return _is_control_endpoint(endpoint, (self.host, self.port), connected_endpoint) def _control_local_endpoint(self, sock): """Return the endpoint this instance advertises on a control connection. @@ -10880,15 +10932,12 @@ def resume_trans(self, peer_addr, fid, offset): # connection; the configured address is accepted too so a peer using # either convention is recognised. The upload row key keeps the # configured namespace, so persisted rows are unchanged. - server_endpoints = {server_peer} connected_endpoint = _socket_peer_endpoint(control_socket) - if connected_endpoint is not None: - server_endpoints.add(connected_endpoint) target = tuple(peer_addr) if peer_addr is not None else ( connected_endpoint or server_peer ) key = (server_peer, fid) - is_direct = target in server_endpoints + is_direct = _is_control_endpoint(target, server_peer, connected_endpoint) def send(entry): if not is_direct: diff --git a/docs/plans/transfer-pause-start-direction-plan.md b/docs/plans/transfer-pause-start-direction-plan.md new file mode 100644 index 0000000..c459710 --- /dev/null +++ b/docs/plans/transfer-pause-start-direction-plan.md @@ -0,0 +1,223 @@ +# 双向文件暂停、继续与按对象恢复 — 需求卡与更改计划 + +状态:**需求卡和拆分已确认;C1 已实现并通过定向验证,待人工审查**。本文件替代本会话此前尚未落盘的 C1–C5 提案;不修改历史计划或报告的结论。本轮授权范围为 C1;C2a–C5 尚未开始,公共协议/API 变更仍须在 C2b 切换前单独取得许可。每个原子变更完成后另附验证报告并等待审查。不自行提交、合并或推送。C1 证据见[实施报告](transfer-pause-start-direction-report.md)。 + +## 1. 需求卡 + +### 目标 + +- 普通上传、下载和转发的每条数据 leg,均允许数据发送端或接收端发起 pause/start。 +- 用方向位区分同一控制 peer 下同 fid、同类型的反向传输;用数据发送端的串行决定解决双端控制命令交叉后的状态失配。 +- 暂停保留文件数据连接;继续沿同一流发送,不附 offset、不重新握手。接收端继续读取并写入在途数据。 +- `/resume_trans` 可在控制连接仍在线时使用:只恢复进度表中没有存活文件连接的对象,跳过仍连接的对象,包括暂停连接;不受其他文件传输影响。 +- 断线丢弃旧连接的暂停、请求和确认状态,保留已有进度和转发恢复路由;重建的 leg 不继承旧暂停。 +- pause/start 统一经过状态接口和现有安全发送路径;复用 resume 的端点识别和加密就绪逻辑。 + +### 非目标与固定边界 + +- 不兼容旧 pause/start 线格式或旧 API 调用形态,不引入能力协商或兼容分支。 +- 不增加 pause/start offset、文件回退、丢弃在途数据、活跃连接强制 teardown、自动重试或新的接收超时。 +- 不改变进度 JSON 的 upload/download 五字段、现有键格式及 relay 路由结构;方向、类型和控制状态只在运行时登记。 +- 不改变 `/resume_trans ` 线格式、稳定 fid 和落盘 offset 来源。 +- 不解决 NAT 身份、client 重连端口变化、跨进程共享进度文件;不重构整个 TCP、加密或持久化模块。 +- 不改 CI、依赖、覆盖率策略;不扩展 Web UI 或进度查询返回 schema。 + +### 受影响范围 + +- 实现:`PyFlow/network_api/connect_tcp.py`,包括协议解析、server/client 控制入口、文件 leg 登记与清理、普通收发循环、relay 路由/pump、恢复入口及进度查询的内部状态投影。 +- 现有测试:`test/unit/network_api/test_fid_routes.py`、`test_transfer_progress_query.py`、`test_transfer_handshakes.py`、`test_resume_matching.py`;`test/integration/network_api/test_tcp_file_transfer.py`、`test_tcp_transfer_resume.py`、`test_crypto_tcp.py`、`test_tcp_async_server.py`。 +- 新增必要契约测试:`test/unit/network_api/test_transfer_control.py`、`test/integration/network_api/test_tcp_transfer_control.py`。只覆盖下文不确定的协议/并发边界,已有路径复用既有测试。 +- 文档:`docs/source/File_Transfer/File_Transfer.rst`、`docs/source/Network_APIs/TCP_Server_APIs.rst`、`TCP_Client_APIs.rst`、`docs/source/changes/transfer-fid-routes.md`。 +- 任务载体:本计划;实施报告落入 `docs/plans/transfer-pause-start-direction-report.md`,实施前不创建完成报告。 + +### 安全与数据边界 + +- wire 不携带 peer;对端身份取自实际控制连接。运行时 key 使用该连接对应的规范命名空间;不能凭相同端口把不同地址当作同一 peer。 +- 所有控制帧经状态接口、控制通道加密就绪检查和现有 `send_message`;禁止业务调用裸 `send/sendall`,禁止用 raw/plaintext 绕过加密过滤。 +- 外部自行构造命令也必须实现相同的定位、状态与排序规则并走安全发送入口;直接调用通用 `send_message` 不会自动获得状态机语义。项目自身不保留这种旁路。 +- 不新增文件内容、密钥或明文 payload 日志;不放宽 resume 的 origin/target/控制 peer 路由校验。 +- `direction` 是定位字段,不是信任声明;还要验证该会话是否拥有对应 leg、类型及角色。 + +### 禁止事项与风险 + +- 禁止删/跳测试、弱化断言、降低 coverage、改 CI、伪造成功 ACK、用文件存在作为传输完成条件。 +- 禁止复制一套 peer 别名表、重复状态工具或保留旧协议 shim;所有内部调用点与状态读者一起迁移。 +- 禁止把“加了锁”当作双端一致性证明,或把“不持久化 pause”当作旧内存状态已清理的证明。 +- 风险等级:**高**,重点审查公共协议、交叉控制、同 fid 隔离、relay 背压和恢复占用竞争。 + +## 2. 四项问题的解决规则 + +### 2.1 问题 1:方向位与唯一定位 + +新线格式严格四 token: + +```text +/pause_trans +/start_trans +``` + +- `fid >= 0`;`trans_type` 仅允许 `0`(普通)或 `1`(转发);`direction` 仅允许 `0`(本命令由数据发送端发出)或 `1`(由数据接收端发出)。 +- direction 相对当前数据 leg,不相对 TCP client/server;收命令时本地角色为 `1 - direction`。 +- 本地控制 key:`(control_peer, fid, trans_type, local_direction)`。状态还绑定实际 control socket 和 leg owner,不能让旧会话清理或命令影响新会话。 +- 例:S 向 C 发送 `/pause_trans 42 0 1`,指 C→S 的上传;S 发送 `/pause_trans 42 0 0`,指 S→C 的下载。即使双向 fid 都是 42,也不互相暂停。 +- typed key 只改变控制命名空间,不迁移进度表。既有进度键仍不允许同一 upload `(peer,fid)` 被两个文件占用;type 位不授予覆盖进度行的能力。 +- 转发上下游分别登记类型与角色;server 在 source→server leg 上是接收端,在 server→target leg 上是发送端。 + +### 2.2 问题 2:数据发送端串行决定、接收端请求与确认 + +采用上一轮流程图中的方案,**替代更早“发送端 start 要等接收端回发 start”的方案**。不同时保留两套启动握手。 + +| 入口/消息 | 行为 | +|---|---| +| 发送端本地 pause/start | 进入该 leg 唯一串行入口,决定状态;发生变化后发 direction=0 状态通知 | +| 接收端本地 pause/start | 按 confirmed/last_requested 双条件去重,登记目标意图并发 direction=1 请求;不把希望的状态当作发送端已采用的状态 | +| 发送端收到 direction=1 | 与本地操作按进入串行入口的顺序处理,执行状态迁移,回 direction=0 的实际状态 | +| 接收端收到 direction=0 | 按该控制连接的消息顺序更新已确认状态,保留最后请求意图;不回发相同命令形成循环 | +| 发送端收到与当前状态相同的请求 | 不重复迁移,但仍回实际状态,以完成必要确认 | +| 已确认状态相同的通知 | 不重复迁移、不回包;必须继续处理本地尚未提交/尚待仲裁的相反意图 | + +- 每个 leg 只有一个状态决定者;S 的本地操作和 R 的请求以 S 的处理顺序为准,不以两端不可比较的调用时间为准。 +- 状态迁移与 direction=0 帧的发送顺序一致;不可先决定 P→R,却把 R→P 的通知顺序发出。复用既有 socket 写入排序,不新建每块数据的控制队列。 +- 本地确知重复的操作在统一入口中静默忽略;发送端以当前决定状态判断,接收端按下述 confirmed/last_requested 双条件判断。不能仅凭旧的已确认状态相同就丢掉新的反向操作。 +- 接收端记录 `confirmed_state` 和 `last_requested_state`,初始均为运行;收到 direction=0 只按序更新 confirmed,不把通知当作可精确计数的逐请求 ACK。调用 pause/start 时,仅当目标同时等于 confirmed 和 last_requested 才能忽略,否则按 FIFO 登记并发送,更新 last_requested。这样 confirmed 仍为运行时的 pause→start 不会丢掉 start;S 主动 start 后 R 也能再次请求 pause。尚未确认时重复的同目标请求允许作为幂等请求提交,避免为去重引入不可验证的 ACK 计数。接口不提供逐请求完成 future,也不新增 request id/generation;状态机契约覆盖主动通知与请求响应交错,证明有限输入排空后的收敛。 +- 收敛证据:任意有限本地操作结束、控制消息全部处理后,S 的决定状态与 R 的已确认状态相同。网络延迟期间允许观察值暂时不同,不承诺“pause 返回后对端已停止落盘”。 +- 发送端下一块前检查暂停;已交给 socket 的数据继续交付。接收端保持 recv/落盘/进度更新,start 不 seek/truncate,不新建数据连接。 +- 空文件、最后一块及最终 ACK 不能因重复控制卡住。控制状态确认不是文件传输成功 ACK。 +- 加密未就绪时,控制操作只登记/等待安全发送,不降级明文;控制接收线程不得阻塞等待它自己需要处理的密钥交换消息。 +- 发送失败沿用会话错误/关闭流程,不能把单次写入返回当作对端确认,也不添加自动重试。 + +### 2.3 问题 3:逐对象 resume 与断线重置 + +恢复资格按具体对象判断,不检查整个实例是否还有别的文件连接: + +1. 通过现有 progress、origin/target 和 relay 路由找到对象;不存在或已完成的不恢复。 +2. 仍有存活文件连接,或正在握手/登记恢复占用:静默跳过。暂停中的 socket 也是存活连接,不走 resume。 +3. 无存活连接、旧 owner 已完成退出并释放占用:允许从实际落盘大小恢复,即使控制连接从未断开。 +4. 检查和恢复占用登记在同一并发边界完成,避免两个请求同时建出新 leg。旧线程尚在清理或新恢复进行中时,不创建第二个 worker。 +5. 不关闭现有连接来满足资格;被跳过的活跃请求不排队等它日后结束,也不伪报“已恢复”。自动重连与手动调用共用同一判断。 +6. 转发中 target 的旧下游已断开,但同 upstream source leg/relay 仍在运行时,不启动该 source fid 的第二次重放;静默跳过该对象。其他独立 fid 的传输不阻挡恢复。没有活跃 leg、只是 source 离线的现有 pending-originator 请求仍按既有逻辑保留。 +7. 断线/自然结束清除该 owner 的暂停键、目标意图和待确认状态并唤醒等待者;进度和中断路由按既有规则保留。新 leg 默认运行,除非对新 owner 再次显式 pause。 + +先前会话已验证的基线,不再当成未修缺陷:普通上传/下载实际断线能关闭暂停 socket、结束线程并删除暂停键;关闭 progress tracking 时同样成立;单目标转发的 target 断线可退出 writer、移除 live relay 并保留恢复路由。C4 的工作是把新状态接入这些路径并补恢复资格,不重做已正常的清扫。 + +### 2.4 问题 4:端点复用、安全门槛和暂停键 + +- 复用 `_socket_local_endpoint`、`_socket_peer_endpoint`、`_is_control_local_endpoint` 与 client resume 的“配置端点/当前控制连接实际端点”识别,抽取共享判定,pause/start/resume 共用。归一化后映射到原有 peer 命名空间,不改变 persisted upload key。 +- `0.0.0.0:port` 作为本实例监听配置可与该连接的具体本地端点对应;不是任意地址通配规则。相同端口的无关地址仍拒绝。 +- 控制发送复用 `_wait_control_secure` 的就绪条件,复用后日志改为适用于控制操作;不扩大 `_PLAINTEXT_LINE_PREFIXES`。 +- `_transfer_pause` 只保存真实暂停标志:pause 写 True,start 移除对应 typed key,并唤醒发送等待者;不留下 False 暂停项。完整状态记录与暂停标志分开,运行状态记录存在不代表 fid 被占用。 +- `_register_fid_route` 区分真实活动 owner、同类型控制记录和无效残留;不再把 False 键或无关类型/方向的控制记录当作碰撞。合法预置暂停必须能被对应 leg 接管,不能阻挡它自己的建立;真正进度、socket、route 冲突仍拒绝。 +- relay 的 writer 暂停与上游背压分别维护。reader 的内存高水位等待是独立硬门槛,只有缓冲下降能解除;任何 start 都不能清掉它。server 作为上游 R 汇总本地用户暂停和自动背压意图,再经统一接口请求 source。source 本地操作仍按 source 的串行顺序决定控制状态;即使确认 start,relay 也可因硬门槛继续等待,数据最终由 socket 背压限制。状态确认不承诺下游具备持续消费能力。 + +## 3. 公共接口、运行时记录与数据流 + +### 3.1 拟定接口变更(仍待单独许可) + +```python +# server:peer 必填 +pause_trans(fid, peer, *, trans_type, direction) +start_trans(fid, peer, *, trans_type, direction) + +# client:省略 peer 表示当前 server +pause_trans(fid, peer=None, *, trans_type, direction) +start_trans(fid, peer=None, *, trans_type, direction) +``` + +- API 的 direction 是调用方在该文件 leg 中的本地角色;必填,不使用猜测或默认值。 +- 统一 API 自己完成校验、状态登记与协议发送;调用者不能先改状态再调用,以免首次操作被误判为重复。 +- 删除旧的纯发送 `pause_trans_remote`/`start_trans_remote` 入口,迁移所有调用、文档/API 列表;不保留转发别名。外部调用方须切换到上述 API。 +- bool 表示活跃 leg 的操作是否被登记;静默忽略返回 False,不代表文件成功/对端已确认。保留现有发送端预置暂停:未建立 leg 时记录精确 typed key、返回 False;匹配 leg 建立后接管,并在对端可定位后公布状态。start 清除预置项。 +- fid/type/direction 非法的本地参数抛 ValueError;wire 解析失败、错误 peer/role 或找不到 live owner 静默忽略,不创建未知 wire 请求的暂停项。 +- `resume_trans(peer_addr, fid, offset)` 保留签名;仍在线/正建连/无恢复资格时返回 False,不再把活跃 leg 当作已接受的恢复。 +- 内部 send/recv/pump 从入口显式传递 trans_type、控制 peer 与 local role;控制登记不依赖 progress bar 开关。key 和控制记录在 leg 建立时绑定,数据循环不逐块分配 key、复制状态表或重新路由。 +- `get_transfer_progress` 返回 schema 不变;其 upload `paused` 字段按实际活动 leg 的新控制记录投影,不能继续用旧 pair key 直接查 typed 表。 + +### 3.2 数据流 + +- 普通:API → peer 归一化 → typed leg 定位 → S 串行决定或 R 请求 → 安全控制发送 → 对端同一入口 → 状态确认;数据循环只读取自己的暂停开关。 +- 转发下游:target direction=1 请求 → server 用 `(target, child_fid)` 定位 writer → server 作为 S 决定 → direction=0 确认;不影响其他 writer 的控制状态。 +- 转发上游:server 作为 R 因背压请求 pause/start,使用 source upstream fid、type=1、direction=1 → source 作为 S 决定 → direction=0 确认 → server 更新上游已确认状态。 +- source 本地 pause/start:仅决定 source→server leg;relay 已排队数据可继续流向 target。target pause 初始只控制自身 writer;其积压达到整体高水位后可能间接停住 source 和其他目标的新数据。 +- 转发优先以 target child fid 定位;现有 upstream fid 别名仅在该 peer 的现有映射唯一匹配同一 writer 时接受。禁止只用全局 fid 猜 route,禁止 type=0 回退控制 relay。 +- resume:请求 → progress/route/peer 校验 → 对象级连接与占用门槛 → 保留 fid 的原有握手 → 从落盘 offset 重放 → 最终文件 ACK → 原有完成清理。 + +## 4. 路径全集与验收映射 + +以下 P01–P18 是本次增量必须覆盖的路径全集。复用既有测试时保留内容/事件断言;新增控制并发用例用屏障/事件控制顺序,不靠 sleep 碰运气。 + +| 路径 | 必须覆盖的入口/分支 | 验收证据 | 提交 | +|---|---|---|---| +| P01 | 四 token、非法/缺多 token、负 fid、越界 type/direction、旧两/三 token | 严格解析结果;非法输入不改变任何状态或发包 | C1、C2b | +| P02 | 同 peer/type/fid 双向普通收发;相同 fid 不同 peer/type | 暂停仅命中指定 leg;其他 leg 持续传输并内容一致 | C2a、C2b | +| P03 | 普通上传,S/R 各自 pause/start | 发送停止产生新块;在途落盘;同 socket 继续;最终内容/ACK | C2b | +| P04 | 普通下载,S/R 各自 pause/start | 同 P03,方向反转 | C2b | +| P05 | 重复操作、快速 pause→start、双方交叉、本地与远端竞争 | 确定性屏障枚举顺序;消息清空后 S/R 状态一致,无控制回包循环 | C2a、C2b | +| P06 | 空文件、尾块/EOF/最终 ACK、文件夹逐文件 leg | 不因控制状态死锁、重握手或重复确认文件成功;内容/ACK 正确 | C2b | +| P07 | 发送端预置 pause、解除预置、未知 wire 请求 | 对应 leg 接管;解除后不留 False 项;未知请求不占键 | C2a、C2b | +| P08 | 多目标 relay:目标 child fid、合法 upstream 别名、错误 peer/type/role | 指定 writer 暂停;其他 writer 独立;错误消息无效果 | C3 | +| P09 | relay 上游 source 本地操作、server 背压操作交叉 | source 不因控制交叉失配;reader 不绕过高水位;缓冲不持续增长 | C3 | +| P10 | target start 与背压未解除;其他目标变慢或断开 | 有限缓冲;不虚报文件成功;未完成 route 保留 | C3、C4b | +| P11 | 控制加密关闭/开启、握手切换窗口、密钥重新交换 | 控制帧走现有加密入口、不退回明文;最终状态与文件内容正确 | C2b、C3 | +| P12 | 同一连接配置别名/具体 IP、wildcard bind、已关闭控制 socket | 归一到同 key;无关地址不匹配;关闭时不泄漏旧 owner | C1、C2b、C4b | +| P13 | tracking off;线程式/async server 控制分派 | 运行时暂停及关闭仍有效;分派线程不阻塞密钥交换;不新增进度文件状态 | C2b、C3、C4b | +| P14 | 普通 progress 有行无连接,控制连接在线,手动恢复 | 只恢复指定对象;其他活跃传输不变;按落盘 offset 内容一致 | C4a | +| P15 | 普通对象仍运行/暂停/建连;重复恢复与清理竞争 | 静默跳过、不建第二个 socket/worker、不排队恢复活跃对象 | C4a | +| P16 | 转发无 live leg、source 在线/离线、零偏移/EOF、活跃共享 source leg | 无连接对象恢复;离线 pending 保留;活跃共享 leg 跳过;fid/route 稳定 | C4b | +| P17 | 普通双向、relay source/target 断线、旧会话迟到清理 | 旧线程退出、控制状态丢弃;重建不继承 pause;新 owner 不被清理 | C4a、C4b | +| P18 | 进度查询、持久化 reload、config 删除/stop 清理与新状态相交 | 查询契约不变;JSON 无控制字段;无残留线程、键或错误路由拒绝 | C2a、C2b、C3、C4b、C5 | + +relay 高水位证据按实际入队粒度计算:记录高水位、单次 enqueue 的扇出字节和峰值,允许既有阈值检测的有限单次超调;不把现有 `buffered > max_mem_buff` 的机制写成“绝不超出 max_mem_buff”。不扩大队列或改为无界缓冲。 + +## 5. 原子拆分(C1–C5 五阶段,七个原子变更) + +原 C2 拆为 C2a/C2b,原 C4 拆为 C4a/C4b,避免把状态机与全调用切换、普通与转发恢复各混成一个大提交。估计包含必要测试和局部说明;超过 500 行需回到本计划重拆,不能边写边临时拆分。 + +| 提交 | 单一意图、文件与边界 | 预计行数 | 局部验证/证据 | +|---|---|---:|---| +| C1 | 完成严格控制解析、typed identity、共用端点识别基础;`connect_tcp.py`、`test_transfer_control.py`、既有身份测试。只加入完整基础能力,尚不激活新协议;旧 parser 在 C2b 一次移除。复用抽取不改变既有 resume 行为。 | 150–250 | P01/P12 的解析、身份隔离测试;既有 resume 身份回归 | +| C2a | 完成 sender-authoritative 状态迁移、请求/通知排序、重复规则、预置暂停和暂停键生命周期;同上实现/单测。基础状态能力全部实现,不先改公开入口或留下空处理器。 | 200–350 | P02/P05/P07/P18 的确定性契约;遍历交叉顺序后最终状态一致 | +| C2b | 端到端切换普通收发控制和公共 API:server/client handler、leg 登记、sender loop、receiver 逻辑状态、安全发送、进度查询投影;删除旧 parser/remote API,迁移所有调用及 pump 命令格式。relay 同时绑定共享控制入口并保留完整的现有 writer/背压行为;C3 再完成复杂路由和硬门槛验收,不以空 handler 或功能开关跳过 relay。不留新解析器配旧发送点。 | 300–500 | P01–P07/P11–P13/P18;真实上传/下载同 socket,全部既有 pause 调用同步迁移后的相关回归 | +| C3 | 完整转发控制路径:精确角色/fid 路由、writer 状态、上游背压和生命周期接管;消除暂停键误占用路由;新增转发并发回归,迁移既有 route/progress 测试。C2b 已切换的协议与普通行为不另做第二套实现。 | 250–450 | P08–P13/P18;多目标真实流、背压交叉、峰值和内容/ACK;False 残键与真实 owner 碰撞对照 | +| C4a | 普通恢复资格和原子占用:进度有行无连接才恢复;活跃/暂停/建连跳过;双向及 tracking off 的新控制状态随旧 leg 清理。保留现有关闭机制。 | 180–300 | P14/P15/P17;在线控制链路手动恢复、另一活跃文件不中断、并发只建一条新 leg | +| C4b | 转发恢复与会话清理:共享 source/live relay 门槛,pending-originator 复用,新 owner 与旧状态隔离;source/target 断线及 stop/config 清理;不主动 teardown 活跃 relay。 | 180–350 | P10/P12/P13/P16–P18;真实 source/target 断线、source 离线后重连、稳定 fid 与未完成 route | +| C5 | 文档和报告收尾:RST、`transfer-fid-routes.md`、本计划状态与逐项证据、实施报告;移除旧 API 文档引用,更新运行时继续与对象级 resume 的边界。 | 100–200 | 路径表逐项有结论;相关集成回归一次;文档锚点/接口说明机械核对 | + +依赖顺序:`C1 → C2a → C2b → C3 → C4a → C4b → C5`。每项先完成局部运行证据和报告,等待人类放行再进入下一项。C1/C2a 是内部完整基础变更,不对外声称新功能可用;C2b 后所有协议生产者和消费者同版本一致,C3 完成复杂转发验收后才视为转发功能交付。 + +每项实施时查询公开符号引用再改签名;当前工作区语言服务只有 Ruff,不支持 references,故已通过调用搜索枚举已知消费者。实施时若有支持导航的服务则必须使用;不能声称 Ruff 做过引用分析。 + +## 6. 验收命令与报告要求 + +以下为各阶段的定向验收命令。C1 已运行新控制基础契约、既有 resume matching、伪造端点拒绝及真实连接身份回归,结果为 **81 passed in 17.77s**;实际命令和覆盖边界见实施报告。其余命令尚未运行,不作为已验证证据。每个原子变更结束运行对应最窄项一次,C5 再进行一次相关合并回归,不反复运行整个仓库。 + +```bash +# C1/C2a:实现后新增必要边界契约 +.venv/bin/python -m pytest test/unit/network_api/test_transfer_control.py -q + +# C2b/C3:实现后新增真实文件控制场景 +.venv/bin/python -m pytest test/integration/network_api/test_tcp_transfer_control.py -q + +# C4a/C4b:复用既有恢复覆盖并补对象级门槛 +.venv/bin/python -m pytest test/integration/network_api/test_tcp_transfer_resume.py -q + +# C5:相关合并回归,包含控制入口、转发与加密 +.venv/bin/python -m pytest test/unit/network_api test/integration/network_api/test_tcp_transfer_control.py test/integration/network_api/test_tcp_file_transfer.py test/integration/network_api/test_tcp_transfer_resume.py test/integration/network_api/test_crypto_tcp.py test/integration/network_api/test_tcp_async_server.py test/integration/test_forward_extension.py test/integration/test_forward_msg_attribution.py -q +``` + +运行证据至少包括: + +- P03/P04 在暂停前后记录同一数据 socket owner、无新 `/file`/port 握手、实际文件内容和最终 ACK。 +- P05 固定交叉顺序并排空消息后的 S/R 状态;不只断言“未抛异常”或发送了指定字符串。 +- P08–P10 记录各 target 的内容进度、writer 状态和 relay 峰值;受整体背压影响与误控其他 writer 分开说明。 +- P11 在真实加密连接上观测安全通道/帧和控制效果,证明未使用 raw/plaintext 旁路;不得 mock 掉加密或文件 socket。 +- P14–P17 记录恢复前后 owner、socket/worker 数、实际落盘 offset、恢复内容;覆盖在线控制连接和真实断线,不能只靠手动调用 sweep。 +- P18 核对 query schema、persisted JSON 无暂停字段、旧 owner 清理不影响新 owner;规则沉淀由上述方向隔离、交叉状态和恢复资格契约承担。 +- 单项报告列提交意图、文件/关键点、路径映射、已运行命令与输出、未覆盖项、风险。总报告逐条回答 P01–P18。 + +## 7. 影响与确认闸门 + +- **公共协议/接口有变化**:四 token;direction 的角色定义;pause/start 必填 type/direction;移除旧 remote API;控制确认语义改为发送端权威;resume 活跃对象返回 False。 +- **持久化数据模型不变**;运行时控制记录改变。查询返回 schema 不变。测试增加必要边界契约及迁移受影响断言,不降低验证强度。 +- **CI/依赖/覆盖率策略不变**。不宣称本计划覆盖未运行的多平台环境、NAT、多进程共享或任意网络中断组合。 +- 新功能依赖存活且可投递的控制连接;仅有数据 socket 存活但控制连接不可用时,不承诺远程 pause/start。自然关闭路径按既有机制结束旧 leg。 +- 需求卡、P01–P18 路径全集及七项原子拆分已确认,本轮仅授权并完成 C1。C1 审查通过后再授权 C2a;C2b 前仍需明确许可四 token 协议、pause/start 必填 type/direction、删除 remote API、返回值与预置暂停契约,以及 resume 活跃对象返回 False。C1 未切换生产 pause/start 解析器、协议或公共签名,未创建提交。 diff --git a/docs/plans/transfer-pause-start-direction-report.md b/docs/plans/transfer-pause-start-direction-report.md new file mode 100644 index 0000000..35aa939 --- /dev/null +++ b/docs/plans/transfer-pause-start-direction-report.md @@ -0,0 +1,79 @@ +# 双向文件暂停、继续与按对象恢复 — 实施报告 + +状态:需求卡和七项拆分已由用户确认,本轮明确授权 C1。**C1 已实现并通过定向验证,等待人工审查;C2a–C5 未开始。** 本报告随已完成的原子变更增补,不将未实现或未运行的路径标为完成。未创建提交、合并或推送。 + +## C1:严格解析、typed identity 与共享端点识别 + +### 提交意图与改动内容 + +建立后续控制状态机可复用的私有协议和身份基础,等价抽取既有 resume 的端点判定,不激活新 pause/start 协议。 + +| 文件 | 关键改动 | +|---|---| +| `PyFlow/network_api/connect_tcp.py` | 新增 `_validate_transfer_control_identity`、`_parse_transfer_control_command` 和 `_transfer_control_key`;新增 `_is_control_endpoint`,供 Server 本地端点判定及 Client `resume_trans` 的 direct 判定复用 | +| `test/unit/network_api/test_transfer_control.py` | 新增解析/本地参数边界、peer/fid/type/双向 key 隔离,以及真实 socket 的别名、wildcard、同端口异地址拒绝和关闭回退契约 | +| `docs/source/changes/transfer-fid-routes.md` | 追加 C1 私有基础和暂未切换生产入口的变更说明 | +| `docs/plans/transfer-pause-start-direction-plan.md` | 记录已确认拆分、C1 授权与验证状态、公共协议/API 的后续许可点 | +| 本报告 | 记录实际命令、路径覆盖边界和未覆盖项 | + +### 为什么这样改与数据流 + +- P01:新 parser 严格接收四 token 的 pause/start,输出 `(paused, fid, trans_type, direction)`;非法命令返回 None。`fid` 非负,type/direction 只能取 0 或 1;本地 identity 校验拒绝 bool、浮点和字符串强制转换,抛出 ValueError。 +- P02 的身份基础:经过现有 peer 归一化的地址 → `_transfer_control_key` → `(peer, fid, trans_type, local_direction)`。收到 wire 消息的调用方使用 `1 - direction` 作为本地角色;本阶段不登记实际 leg 或状态,不迁移 progress key。 +- P12:Server 的 origin 判定 / Client 的 resume target 判定 → 从当前 socket 获取 concrete endpoint → `_is_control_endpoint` 精确比较 configured 或 concrete endpoint → 继续原有 direct/relay 恢复逻辑。没有按端口匹配,也没有独立别名表;Client 仍以配置地址作为 upload 行 key。 +- `_pause_command_fid`、生产 handler、公开 pause/start/remote API 和现有控制消息保持原样;C2b 负责一次性移除旧 parser 并迁移生产者、消费者及调用点。 + +### 局部验证 + +执行一次: + +```bash +.venv/bin/python -m pytest test/unit/network_api/test_transfer_control.py test/unit/network_api/test_resume_matching.py test/unit/network_api/test_fid_routes.py::test_resume_uses_scoped_route_not_id_lowbit_and_rejects_forged_endpoints test/integration/network_api/test_tcp_transfer_resume.py::test_resume_identity_uses_the_connected_endpoint test/integration/network_api/test_tcp_transfer_resume.py::test_closed_control_socket_falls_back_to_the_configured_endpoint -q +``` + +实际结果:**81 passed in 17.77s**(命令墙钟 18.43s)。 + +运行时证据: + +- 新基础契约通过真实 IPv4 listener/client 连接获取 accepted socket 本地端点和 client peer 端点;配置 `localhost` 或 `0.0.0.0` 均与 concrete 地址匹配;同端口 `127.0.0.2` 被拒绝。关闭 socket 后仅配置地址仍可作为回退身份。 +- 复用既有 `test_resume_identity_uses_the_connected_endpoint` 四个场景:`localhost` / wildcard bind × configured / connected 旧行。每个场景在真实控制与文件 socket 上同时验证 Client→Server 和 Server→Client 从实际半文件 offset 续传;断言最终文件字节内容等于完整 payload,且原 fid 的双端进度行在完成后移除。 +- 既有闭合控制 socket 回归确认 Server 广告端点回退配置身份,其他端点被拒绝;既有 route 回归确认错误 peer/origin/target/fid 不改变 route 或生成恢复请求。 +- key 契约对相同 fid 的不同 peer/type/local role 分别读写,包含同端口异地址与不同 fid,确认只有选中项改变。它验证身份基础,尚不是生产暂停效果证据。 + +### 明确未覆盖 + +| 路径 | C1 结论 | +|---|---| +| P01 | 新 parser 和本地 identity 边界已覆盖;生产 handler 的严格切换留给 C2b | +| P02 | typed key 身份隔离已覆盖;活跃双向数据 leg 暂停隔离留给 C2a/C2b | +| P12 | 共享端点判定与既有真实双向 resume 身份回归已覆盖;pause/start 接入及旧 owner 清理留给 C2b/C4b | +| P03–P11、P13–P18 | 未在 C1 实现或验收;按原计划的状态机、普通/转发接入及对象级恢复阶段处理 | + +C1 没有改加密入口、安全就绪、数据循环、路由占用规则、恢复资格或持久化模型;因此本轮结果不作为这些属性的新验收证据。没有运行广泛套件、formatter、lint 或多平台验证。新增测试是基础契约,未删除或弱化既有测试。 + +### 风险与待确认 + +- 语言服务 references 请求返回 `-32601 Unknown request: textDocument/references`,不具备导航引用能力。已按已定位调用点做私有函数抽取;本阶段不修改公共签名,不能将该服务请求计作引用分析。 +- 新 parser 与旧 parser 暂时同时存在是获批 C1→C2b 拆分边界;新 parser 仅供后续基础接入及契约验证,未对外宣称新控制行为已可用。C2b 必须移除旧 parser,不留兼容分支。 +- 下一项为 C2a:发送端权威状态机与顺序、去重、预置暂停和暂停键生命周期;须待本 C1 审查放行及下一阶段授权。 + +## 公共协议/API 变更许可点 + +以下仍是拟定契约,C1 未实施;应在 C2b 生产切换前明确许可: + +```python +# Server +pause_trans(fid, peer, *, trans_type, direction) +start_trans(fid, peer, *, trans_type, direction) + +# Client +pause_trans(fid, peer=None, *, trans_type, direction) +start_trans(fid, peer=None, *, trans_type, direction) +``` + +- 四 token 的 `/pause_trans `、`/start_trans ` 替代旧 wire 格式;不保留兼容路径。direction 表示命令发起方在当前数据 leg 中的角色(0 发送,1 接收)。 +- 删除 `pause_trans_remote` / `start_trans_remote`,项目内调用与文档统一迁移到上述入口。 +- bool 表示活跃 leg 的操作是否登记,不表示已确认或文件成功。发送端未建连时允许精确 key 的预置 pause,返回 False;start 解除预置;非法本地 fid/type/direction 抛 ValueError。 +- `resume_trans(peer_addr, fid, offset)` 保留签名,但活跃、暂停或正建连对象静默跳过并返回 False;具体资格门槛在 C4a/C4b 实现。 + +需求卡和拆分的确认不在本报告中代替这一许可;未获许可前不修改公共协议/API。 diff --git a/docs/source/changes/transfer-fid-routes.md b/docs/source/changes/transfer-fid-routes.md index 779dd77..4d96eb0 100644 --- a/docs/source/changes/transfer-fid-routes.md +++ b/docs/source/changes/transfer-fid-routes.md @@ -318,3 +318,20 @@ file preservation. Runtime evidence and explicit exclusions are recorded in still consumed by the existing ACK wait. Wire commands, progress rows, public signatures and the pause/start semantics of a live session are unchanged. + +## Transfer control C1: typed identity and shared endpoint matching + +- Private foundations parse four-token pause/start commands and validate a + nonnegative integer FID, transfer type (ordinary/forwarded) and local role + (sender/receiver). Runtime keys include peer, FID, type and local direction; + progress keys and JSON remain unchanged. +- Server-local and Client resume identity checks share the same exact + configured-or-connected endpoint predicate. Wildcard configuration does not + admit unrelated addresses with the same port; closed sockets retain the + configured fallback. No additional endpoint alias table is introduced. +- The new parser is not yet used by production dispatch. Existing pause/start + wire messages and public APIs remain in use until the separately permitted + C2b cutover. C1's targeted run passed 81 tests, including real bidirectional + resume with configured aliases and wildcard binds. Evidence and exclusions + are in `docs/plans/transfer-pause-start-direction-report.md`. + diff --git a/test/unit/network_api/test_transfer_control.py b/test/unit/network_api/test_transfer_control.py new file mode 100644 index 0000000..b8b0315 --- /dev/null +++ b/test/unit/network_api/test_transfer_control.py @@ -0,0 +1,109 @@ +"""Contracts for typed transfer control and connection-scoped endpoint identity.""" + +import socket + +import pytest + +from PyFlow.network_api.connect_tcp import ( + _is_control_endpoint, + _parse_transfer_control_command, + _socket_local_endpoint, + _socket_peer_endpoint, + _transfer_control_key, +) + +PEER = ("127.0.0.1", 6000) + + +@pytest.mark.parametrize("name,paused", [("pause_trans", True), ("start_trans", False)]) +@pytest.mark.parametrize("fid", [0, (1 << 63) + 42]) +@pytest.mark.parametrize("trans_type", [0, 1]) +@pytest.mark.parametrize("direction", [0, 1]) +def test_control_parser_preserves_leg_identity(name, paused, fid, trans_type, direction): + parsed = _parse_transfer_control_command( + f"/{name.upper()} {fid} {trans_type} {direction}" + ) + assert parsed == (paused, fid, trans_type, direction) + # A received direction names the issuer's role, so the local leg is opposite. + _, parsed_fid, parsed_type, wire_direction = parsed + key = _transfer_control_key(PEER, parsed_fid, parsed_type, 1 - wire_direction) + assert key == (PEER, fid, trans_type, 1 - direction) + + +@pytest.mark.parametrize("line", [ + "", " ", "/pause_trans", "/pause_trans 42", "/start_trans 42 0", + "/pause_trans 42 0 1 extra", "/resume_trans 42 0 1", + "/pause_trans -1 0 0", "/pause_trans nope 0 0", "/pause_trans 1.5 0 0", + "/pause_trans 42 -1 0", "/pause_trans 42 2 0", "/pause_trans 42 normal 0", + "/start_trans 42 0 -1", "/start_trans 42 0 2", "/start_trans 42 0 sender", + "/pause_trans 42 0 'unterminated", None, b"/pause_trans 42 0 0", +]) +def test_control_parser_rejects_old_or_malformed_commands(line): + assert _parse_transfer_control_command(line) is None + + +@pytest.mark.parametrize("fid,trans_type,direction", [ + (-1, 0, 0), (True, 0, 0), (1.0, 0, 0), ("1", 0, 0), (None, 0, 0), + (42, -1, 0), (42, 2, 0), (42, False, 0), (42, 0.0, 0), (42, "0", 0), + (42, 0, -1), (42, 0, 2), (42, 0, True), (42, 0, 1.0), (42, 0, "1"), +]) +def test_local_control_identity_rejects_coercion_and_out_of_range_values( + fid, trans_type, direction +): + with pytest.raises(ValueError): + _transfer_control_key(PEER, fid, trans_type, direction) + + +def test_control_keys_isolate_peer_fid_type_and_both_local_roles(): + legs = { + _transfer_control_key(peer, fid, trans_type, direction): False + for peer in (PEER, ("127.0.0.2", PEER[1])) + for fid in (42, 43) + for trans_type in (0, 1) + for direction in (0, 1) + } + mutable_peer = list(PEER) + selected = _transfer_control_key(mutable_peer, 42, 1, 0) + mutable_peer[0] = "other-host" + legs[selected] = True + assert legs[(PEER, 42, 1, 0)] is True + assert all(not paused for key, paused in legs.items() if key != selected) + assert legs[(PEER, 42, 0, 0)] is False + assert legs[(PEER, 42, 1, 1)] is False + assert legs[(("127.0.0.2", PEER[1]), 42, 1, 0)] is False + assert legs[(PEER, 43, 1, 0)] is False + + +@pytest.mark.parametrize("bind_host,configured_host", [ + ("127.0.0.1", "localhost"), ("0.0.0.0", "0.0.0.0"), +], ids=["configured-alias", "wildcard-bind"]) +def test_control_endpoint_matches_only_this_connection_and_configuration( + bind_host, configured_host +): + with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as listener: + listener.settimeout(2) + listener.bind((bind_host, 0)) + listener.listen(1) + configured = (configured_host, listener.getsockname()[1]) + with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as client: + client.settimeout(2) + client.connect(("127.0.0.1", configured[1])) + accepted, _ = listener.accept() + with accepted: + local = _socket_local_endpoint(accepted) + remote = _socket_peer_endpoint(client) + assert local == remote == ("127.0.0.1", configured[1]) + for connected in (local, remote): + assert _is_control_endpoint(list(configured), configured, connected) + assert _is_control_endpoint(local, configured, connected) + assert not _is_control_endpoint( + ("127.0.0.2", configured[1]), configured, connected + ) + assert not _is_control_endpoint( + ("127.0.0.1", configured[1] + 1), configured, connected + ) + client.close() + assert _socket_local_endpoint(accepted) is None + assert _socket_peer_endpoint(client) is None + assert _is_control_endpoint(configured, configured, None) + assert not _is_control_endpoint(local, configured, None) From 01de6840ebf0443313312a084bc9bfacfa7b3c1a Mon Sep 17 00:00:00 2001 From: F18-Ray Date: Mon, 16 Nov 2026 13:25:35 +0800 Subject: [PATCH 02/19] refactor(connect_tcp): add sender-authoritative transfer control state --- PyFlow/network_api/connect_tcp.py | 138 ++++++++++ .../transfer-pause-start-direction-plan.md | 6 +- .../transfer-pause-start-direction-report.md | 72 ++++- docs/source/changes/transfer-fid-routes.md | 20 ++ .../unit/network_api/test_transfer_control.py | 260 ++++++++++++++++++ 5 files changed, 491 insertions(+), 5 deletions(-) diff --git a/PyFlow/network_api/connect_tcp.py b/PyFlow/network_api/connect_tcp.py index 648ef73..2b88e7a 100644 --- a/PyFlow/network_api/connect_tcp.py +++ b/PyFlow/network_api/connect_tcp.py @@ -790,6 +790,138 @@ def _transfer_control_key(peer, fid, trans_type, direction): return tuple(peer), fid, trans_type, direction +class _TransferControlRegistry: + """Serialize each leg's decisions and control writes without blocking other legs. + + Lock order is leg lock then pause condition; lookups release the condition + before taking a leg lock. ``send(socket, line)`` must use the secure control + gate and normal send_message path. It runs inside the leg lock so state and + wire order agree; callers must not wait for crypto on its receive thread. + """ + + def __init__(self, paused, condition): + self._paused = paused + self._condition = condition + self._legs = {} + + def register(self, key, control_socket, owner): + """Bind an unclaimed identity, adopting only its sender's preset pause.""" + if control_socket is None or owner is None: + raise ValueError("a control socket and leg owner are required") + with self._condition: + state = self._legs.get(key) + if state is not None: + return state if (state["control_socket"] is control_socket + and state["owner"] is owner) else None + paused = key[3] == 0 and self._paused.get(key, False) + state = { + "key": key, "control_socket": control_socket, "owner": owner, + "lock": threading.RLock(), "confirmed_state": paused, + "last_requested_state": False, "initial_notification": paused, + } + self._legs[key] = state + return state + + def _live(self, state): + with self._condition: + return self._legs.get(state["key"]) is state + + def _confirm(self, state, paused): + with self._condition: + state["confirmed_state"] = paused + if state["key"][3] == 0: + if paused: + self._paused[state["key"]] = True + else: + self._paused.pop(state["key"], None) + self._condition.notify_all() + + def _send(self, state, paused, send): + _, fid, trans_type, direction = state["key"] + name = "/pause_trans" if paused else "/start_trans" + try: + sent = send(state["control_socket"], f"{name} {fid} {trans_type} {direction}") + except Exception: + self.release(state) + raise + if not sent: + self.release(state) + return False + state["initial_notification"] = False + return True + + def announce(self, state, send): + """Publish an adopted pause once the peer can locate the new leg.""" + with state["lock"]: + if not self._live(state) or not state["initial_notification"]: + return False + return self._send(state, state["confirmed_state"], send) + + def local(self, key, paused, send): + """Decide a sender state or submit a receiver intent, deduplicating both.""" + with self._condition: + state = self._legs.get(key) + if state is None: + if key[3] == 0: + if paused: + self._paused[key] = True + else: + self._paused.pop(key, None) + self._condition.notify_all() + return False + with state["lock"]: + if not self._live(state): + return False + if key[3] == 0: + if state["confirmed_state"] == paused: + return False + self._confirm(state, paused) + else: + if (state["confirmed_state"] == paused + and state["last_requested_state"] == paused): + return False + state["last_requested_state"] = paused + return self._send(state, paused, send) + + def receive(self, key, control_socket, paused, send): + """Process a request at S or a notification at R; never create wire state.""" + with self._condition: + state = self._legs.get(key) + if state is None: + return False + with state["lock"]: + if not self._live(state) or state["control_socket"] is not control_socket: + return False + changed = state["confirmed_state"] != paused + self._confirm(state, paused) + if key[3] == 0: + # Even a same-state request needs the actual-state notification. + return self._send(state, paused, send) + return changed + + def release(self, state): + """Retire only this owner, clear control intent and wake paused senders.""" + with state["lock"]: + with self._condition: + key = state["key"] + if self._legs.get(key) is not state: + return False + del self._legs[key] + self._paused.pop(key, None) + state["confirmed_state"] = False + state["last_requested_state"] = False + state["initial_notification"] = False + self._condition.notify_all() + return True + + def discard_socket(self, control_socket): + """Discard one control session without touching a replacement owner.""" + with self._condition: + states = [state for state in self._legs.values() + if state["control_socket"] is control_socket] + return sum(self.release(state) for state in states) + + def _pause_command_fid(command): """Return the fid of a ``/pause_trans``/``/start_trans`` line, or None. @@ -2412,6 +2544,9 @@ def __init__( # (receiver, fid) -> bool; a pause never affects a different receiver. self._transfer_pause = {} self._transfer_pause_cond = threading.Condition() + self._transfer_controls = _TransferControlRegistry( + self._transfer_pause, self._transfer_pause_cond + ) self._active_transfer_fids = set() # fids of the legs running right now self._active_transfer_sockets = {} # receive fid / (receiver, fid) -> socket self.project_dir = os.path.dirname(os.path.abspath(__file__)) @@ -7675,6 +7810,9 @@ def __init__( # (receiver, fid) -> bool, including forwarded uploads to the server. self._transfer_pause = {} self._transfer_pause_cond = threading.Condition() + self._transfer_controls = _TransferControlRegistry( + self._transfer_pause, self._transfer_pause_cond + ) self._active_transfer_fids = set() # fids of the legs running right now self._active_transfer_sockets = {} # receive fid / (receiver, fid) -> socket self.project_dir = os.path.dirname(os.path.abspath(__file__)) diff --git a/docs/plans/transfer-pause-start-direction-plan.md b/docs/plans/transfer-pause-start-direction-plan.md index c459710..b7e4bf8 100644 --- a/docs/plans/transfer-pause-start-direction-plan.md +++ b/docs/plans/transfer-pause-start-direction-plan.md @@ -1,6 +1,6 @@ # 双向文件暂停、继续与按对象恢复 — 需求卡与更改计划 -状态:**需求卡和拆分已确认;C1 已实现并通过定向验证,待人工审查**。本文件替代本会话此前尚未落盘的 C1–C5 提案;不修改历史计划或报告的结论。本轮授权范围为 C1;C2a–C5 尚未开始,公共协议/API 变更仍须在 C2b 切换前单独取得许可。每个原子变更完成后另附验证报告并等待审查。不自行提交、合并或推送。C1 证据见[实施报告](transfer-pause-start-direction-report.md)。 +状态:**C1 已通过人工审查;C2a 已获授权、实现并通过定向验证,待人工审查**。需求卡和七项拆分已确认。本文件替代此前尚未落盘的 C1–C5 提案;不修改历史计划或报告的结论。C2b–C5 尚未开始,公共协议/API 变更仍须在 C2b 切换前单独取得许可。每个原子变更完成后另附验证报告并等待审查。不自行提交、合并或推送。证据见[实施报告](transfer-pause-start-direction-report.md)。 ## 1. 需求卡 @@ -188,7 +188,7 @@ relay 高水位证据按实际入队粒度计算:记录高水位、单次 enqu ## 6. 验收命令与报告要求 -以下为各阶段的定向验收命令。C1 已运行新控制基础契约、既有 resume matching、伪造端点拒绝及真实连接身份回归,结果为 **81 passed in 17.77s**;实际命令和覆盖边界见实施报告。其余命令尚未运行,不作为已验证证据。每个原子变更结束运行对应最窄项一次,C5 再进行一次相关合并回归,不反复运行整个仓库。 +以下为各阶段的定向验收命令。C1 定向回归为 **81 passed in 17.77s**。C2a 控制与进度查询回归为 **154 passed in 0.99s**,出现一项 pytest 参数化迭代器弃用告警;改为 tuple 后仅重跑受影响交叉调度用例,**64 passed in 0.62s**,无告警。另有四组真实控制 socket 的收敛证据。实际命令和覆盖边界见实施报告。其余阶段命令尚未运行,不作为已验证证据。每个原子变更运行对应最窄项,C5 再进行一次相关合并回归,不反复运行整个仓库。 ```bash # C1/C2a:实现后新增必要边界契约 @@ -220,4 +220,4 @@ relay 高水位证据按实际入队粒度计算:记录高水位、单次 enqu - **持久化数据模型不变**;运行时控制记录改变。查询返回 schema 不变。测试增加必要边界契约及迁移受影响断言,不降低验证强度。 - **CI/依赖/覆盖率策略不变**。不宣称本计划覆盖未运行的多平台环境、NAT、多进程共享或任意网络中断组合。 - 新功能依赖存活且可投递的控制连接;仅有数据 socket 存活但控制连接不可用时,不承诺远程 pause/start。自然关闭路径按既有机制结束旧 leg。 -- 需求卡、P01–P18 路径全集及七项原子拆分已确认,本轮仅授权并完成 C1。C1 审查通过后再授权 C2a;C2b 前仍需明确许可四 token 协议、pause/start 必填 type/direction、删除 remote API、返回值与预置暂停契约,以及 resume 活跃对象返回 False。C1 未切换生产 pause/start 解析器、协议或公共签名,未创建提交。 +- 需求卡、P01–P18 路径全集及七项原子拆分已确认;C1 已通过人工审查,C2a 已获授权并完成,待人工放行。C2b 前仍需明确许可四 token 协议、pause/start 必填 type/direction、删除 remote API、返回值与预置暂停契约,以及 resume 活跃对象返回 False。C1/C2a 均未切换生产 pause/start 解析器、协议或公共签名;本轮未创建提交。 diff --git a/docs/plans/transfer-pause-start-direction-report.md b/docs/plans/transfer-pause-start-direction-report.md index 35aa939..95eb467 100644 --- a/docs/plans/transfer-pause-start-direction-report.md +++ b/docs/plans/transfer-pause-start-direction-report.md @@ -1,6 +1,6 @@ # 双向文件暂停、继续与按对象恢复 — 实施报告 -状态:需求卡和七项拆分已由用户确认,本轮明确授权 C1。**C1 已实现并通过定向验证,等待人工审查;C2a–C5 未开始。** 本报告随已完成的原子变更增补,不将未实现或未运行的路径标为完成。未创建提交、合并或推送。 +状态:需求卡和七项拆分已确认。**C1 已通过人工审查;本轮获准完成的 C2a 已实现并通过定向验证,等待人工审查;C2b–C5 未开始。** 本报告随已完成的原子变更增补,不将未实现或未运行的路径标为完成。本轮未创建提交、合并或推送。 ## C1:严格解析、typed identity 与共享端点识别 @@ -55,7 +55,75 @@ C1 没有改加密入口、安全就绪、数据循环、路由占用规则、 - 语言服务 references 请求返回 `-32601 Unknown request: textDocument/references`,不具备导航引用能力。已按已定位调用点做私有函数抽取;本阶段不修改公共签名,不能将该服务请求计作引用分析。 - 新 parser 与旧 parser 暂时同时存在是获批 C1→C2b 拆分边界;新 parser 仅供后续基础接入及契约验证,未对外宣称新控制行为已可用。C2b 必须移除旧 parser,不留兼容分支。 -- 下一项为 C2a:发送端权威状态机与顺序、去重、预置暂停和暂停键生命周期;须待本 C1 审查放行及下一阶段授权。 +- C1 后续审查结论:用户已审计放行,并明确授权 C2a。C1 证据保留如上;C2a 实施及其独立待审事项见下节。 + +## C2a:发送端权威状态机与暂停键生命周期 + +### 提交意图与改动内容 + +为后续普通/转发数据 leg 共用一个私有控制登记表,完整实现串行决定、请求/通知语义及 owner 生命周期。C1 已由用户审查放行,本轮授权仅为 C2a。 + +| 文件 | 关键改动 | +|---|---| +| `PyFlow/network_api/connect_tcp.py` | 新增 `_TransferControlRegistry`,Server/Client 均初始化该登记表,共用实例现有的暂停表和 Condition;尚未注册生产 leg 或迁移公开入口 | +| `test/unit/network_api/test_transfer_control.py` | 补充可控 FIFO 双端调度、独立期望状态、阻塞写入排序/唤醒、预置暂停、身份与 owner 隔离、失败清理、真实持久化内容契约 | +| 计划、变更记录、本报告 | 记录 C1 放行、C2a 实施范围、命令结果及生产切换的后续许可点 | + +### 数据流与不变量 + +- 登记:规范 typed key + 实际 control socket + leg owner → `register` → 独立 leg 锁及运行状态。冲突 owner/socket 拒绝覆盖;同 owner 重复登记复用记录。只有发送角色接管该 key 的预置暂停;`announce` 在对端可定位后公布一次。 +- 发送端本地操作或收到接收端请求 → 同一 leg 锁 → 决定实际状态 → 更新暂停键 → 在锁内提交 direction=0 通知。对同状态远端请求仍发送确认;本地同状态操作忽略。 +- 接收端本地操作 → 仅当目标同时等于 `confirmed_state` 和 `last_requested_state` 时忽略,否则更新最后意图并按序提交 direction=1 请求。接收 direction=0 只更新确认值,不覆盖最后意图、不回包。 +- start 移除暂停键并唤醒等待者;完整运行记录与暂停标志分开。接收角色从不通过确认值阻止 recv。未知 wire key、错误会话均返回 False,不创建预置项。 +- `release` 仅释放该记录的 owner,清理暂停、确认/请求意图及初始通知标记并唤醒等待者;`discard_socket` 仅清理匹配实际 socket 的记录。旧记录再次清理不影响替换 owner。发送 False/抛异常会释放该记录;异常继续上抛,不重试、不伪造确认。 +- 锁序为 leg 锁 → pause Condition;定位阶段先释放 Condition 再等待 leg 锁。消息发送回调在 leg 锁内调用,因此同一 leg 状态决定与发送顺序一致;不同 leg 使用独立锁。回调契约要求安全就绪门槛 + 现有 `send_message`,C2b 才接入生产安全发送与接收线程调度,不能在接收线程阻塞其自身的密钥交换。 + +### 局部验证与运行证据 + +首次定向命令: + +```bash +.venv/bin/python -m pytest test/unit/network_api/test_transfer_control.py test/unit/network_api/test_transfer_progress_query.py -q +``` + +结果:**154 passed in 0.99s**(墙钟 1.32s),出现一项 `PytestRemovedIn10Warning`:参数化传入 `itertools.product` 迭代器。随后将参数化数据改为 tuple,仅重跑受影响用例: + +```bash +.venv/bin/python -m pytest test/unit/network_api/test_transfer_control.py::test_every_fifo_delivery_interleaving_converges_after_finite_input -q +``` + +结果:**64 passed in 0.62s**,无告警。 + +机械证据: + +- 枚举双方 pause/start 的全部 64 个三操作组合;每个组合递归枚举本地提交与双向 FIFO 消息的全部可达交错。每条终态均检查 S 决定值 = R 确认值 = 独立记录的最后一次 S 串行处理意图,并限制通知数量以捕获回包循环。另测重复请求必须确认及 R 快速 pause→start 不能丢 start。 +- 线程事件将第一个发送回调固定阻塞,另一个操作在尝试获得同一 leg 锁前发出事件。确认后续 start/释放不能抢先修改状态;解除阻塞后验证通知顺序、等待者确实收到 Condition 通知,以及线程全部结束。使用 Future 传播线程断言,不用 sleep 或仅检查线程存活。 +- 预置暂停接管/单次公布、公布前 start 取消、未建连 start 删除 key、错误 peer/socket/type/反向 role 隔离、重复旧 owner 清理及 False/异常写失败均有状态断言。 +- Server/Client 各写一次真实进度 JSON,完整内容等于控制操作前的 snapshot,确认新增运行时状态没有进入持久化文件;既有进度查询契约一并通过。 + +另运行一次标准输入临时脚本(未落盘),四组 `socket.socketpair()` 通过真实 `TCP_Server_Base` / `TCP_Client_Base.send_message` 传递新控制帧,再将 socket 读取结果交给新 parser 和 registry: + +| 发送端 | type | S→R 帧 | R→S 帧 | 排空后 S/R paused | 暂停键 | 同一 socket | +|---|---:|---:|---:|---|---:|---| +| Server | 0 | 5 | 2 | False / False | 0 | 是 | +| Server | 1 | 5 | 2 | False / False | 0 | 是 | +| Client | 0 | 5 | 2 | False / False | 0 | 是 | +| Client | 1 | 5 | 2 | False / False | 0 | 是 | + +每组实际经过预置暂停公布、S start、R 快速 pause→start、S 本地操作与远端请求交叉,以及同状态请求确认。最后检查消息已消费、双端状态一致、控制状态不在 progress snapshot,旧会话释放后新 owner 默认运行。脚本退出码为 0。这是明文真实控制写入证据,未经过生产 pause/start handler,也未传输文件 payload,不作为 P03/P04/P11 的验收。 + +### 路径覆盖、明确未覆盖与风险 + +| 路径 | C2a 结论 | +|---|---| +| P02 | 活跃状态记录按 peer/type/role 隔离;生产双向数据流隔离留给 C2b | +| P05 | 确定性交错、重复及阻塞发送排序已覆盖;生产 handler/真实文件并发仍需 C2b | +| P07 | 预置暂停接管/解除与未知 wire 不占键已覆盖;真实握手后公布时机在 C2b 接入 | +| P18 | registry 释放/唤醒与 JSON 不含控制状态已覆盖;路由冲突、query 新状态投影、stop/config 的生产清理仍属后续既定阶段 | + +本轮未改公开 API、生产 parser/协议、data loop、relay pump、加密门槛、恢复资格或 CI/依赖。新登记表已初始化,但生产 leg 和关闭路径尚未调用它,故不宣称暂停新行为已对外可用。C2b 必须将生产调用、发送调度与生命周期统一接入;不能保留旧控制状态或旁路。未运行 broad suite、formatter、lint 或加密/多平台验证。语言服务能力仍仅 Ruff,无 references 支持。 + +待 C2a 人工审查放行,以及下节公共协议/API 许可后,才能进入 C2b。 ## 公共协议/API 变更许可点 diff --git a/docs/source/changes/transfer-fid-routes.md b/docs/source/changes/transfer-fid-routes.md index 4d96eb0..82b8584 100644 --- a/docs/source/changes/transfer-fid-routes.md +++ b/docs/source/changes/transfer-fid-routes.md @@ -335,3 +335,23 @@ file preservation. Runtime evidence and explicit exclusions are recorded in resume with configured aliases and wildcard binds. Evidence and exclusions are in `docs/plans/transfer-pause-start-direction-report.md`. +## Transfer control C2a: sender-authoritative control state + +- Server and Client initialize a shared private control-registry implementation. + Each typed leg binds its control socket and owner; a per-leg lock serializes + state decisions and control writes. Same-state receiver requests still get + an actual-state notification; receivers track confirmed and last-requested + state separately and never echo notifications. +- Sender presets are adopted by the matching leg and published once when the + peer can locate it. Start removes the pause key. Owner/session release or a + failed write clears control intent and wakes waiting senders; stale owners + cannot remove a replacement record. Control state stays out of progress JSON. +- Deterministic FIFO interleavings, blocked-write ordering and lifecycle tests + passed with existing progress-query contracts (154 tests). A pytest iterable + deprecation was fixed; the affected 64 scheduling cases then passed without + warnings. Four plaintext socketpair runs exercised the real send_message + paths in both endpoint roles and both transfer types, converging with no + pause keys. The implementation report records evidence and limitations. +- Production leg registration, pause/start API and protocol cutover, secure + dispatch, data-loop integration and real-file control remain at the C2b gate. + diff --git a/test/unit/network_api/test_transfer_control.py b/test/unit/network_api/test_transfer_control.py index b8b0315..de3f4ef 100644 --- a/test/unit/network_api/test_transfer_control.py +++ b/test/unit/network_api/test_transfer_control.py @@ -1,10 +1,18 @@ """Contracts for typed transfer control and connection-scoped endpoint identity.""" +import json import socket +import threading +from collections import deque +from concurrent.futures import ThreadPoolExecutor +from itertools import product import pytest from PyFlow.network_api.connect_tcp import ( + TCP_Client_Base, + TCP_Server_Base, + _TransferControlRegistry, _is_control_endpoint, _parse_transfer_control_command, _socket_local_endpoint, @@ -107,3 +115,255 @@ def test_control_endpoint_matches_only_this_connection_and_configuration( assert _socket_peer_endpoint(client) is None assert _is_control_endpoint(configured, configured, None) assert not _is_control_endpoint(local, configured, None) + + +class _ControlPair: + def __init__(self): + self.paused = [{}, {}] + self.registries = [ + _TransferControlRegistry(flags, threading.Condition()) for flags in self.paused + ] + self.keys = [_transfer_control_key(PEER, 42, 0, role) for role in (0, 1)] + self.sockets = [object(), object()] + self.states = [registry.register(key, sock, object()) for registry, key, sock in zip( + self.registries, self.keys, self.sockets + )] + self.pending = [deque(), deque()] + + def send(self, side): + def enqueue(sock, line): + assert sock is self.sockets[side] + self.pending[1 - side].append(line) + return True + return enqueue + + def local(self, side, paused): + return self.registries[side].local(self.keys[side], paused, self.send(side)) + + def deliver(self, side): + paused, fid, trans_type, direction = _parse_transfer_control_command( + self.pending[side].popleft() + ) + key = _transfer_control_key(PEER, fid, trans_type, 1 - direction) + return self.registries[side].receive(key, self.sockets[side], paused, self.send(side)) + + def drain(self): + while any(self.pending): + for side in (0, 1): + if self.pending[side]: + self.deliver(side) + + +def test_duplicate_requests_still_confirm_and_receiver_preserves_its_last_intent(): + pair = _ControlPair() + assert not pair.local(0, False) and not pair.local(1, False) + assert pair.local(1, True) and pair.local(1, True) + assert pair.states[1]["confirmed_state"] is False + pair.deliver(0) + pair.deliver(0) + assert tuple(pair.pending[1]) == ("/pause_trans 42 0 0",) * 2 + pair.drain() + assert pair.states[0]["confirmed_state"] is pair.states[1]["confirmed_state"] is True + assert not pair.local(0, True) and not pair.local(1, True) + assert pair.local(0, False) + pair.drain() + assert pair.states[1]["last_requested_state"] is True + assert pair.local(1, True) # The sender's start must not suppress another pause. + assert pair.local(1, False) # An unconfirmed pause must not swallow the reverse intent. + pair.drain() + assert pair.states[0]["confirmed_state"] is pair.states[1]["confirmed_state"] is False + assert pair.paused == [{}, {}] and not any(pair.pending) + + +@pytest.mark.parametrize("operations", tuple(product(product((0, 1), (False, True)), repeat=3))) +def test_every_fifo_delivery_interleaving_converges_after_finite_input(operations): + def explore(schedule=()): + pair = _ControlPair() + submitted = 0 + expected = False + for action in schedule: + if action == "local": + if operations[submitted][0] == 0: + expected = operations[submitted][1] + pair.local(*operations[submitted]) + submitted += 1 + else: + if action == 0: + expected = _parse_transfer_control_command(pair.pending[0][0])[0] + pair.deliver(action) + actions = (["local"] if submitted < len(operations) else []) + [ + side for side in (0, 1) if pair.pending[side] + ] + if not actions: + sender, receiver = pair.states + assert sender["confirmed_state"] == receiver["confirmed_state"], schedule + assert sender["confirmed_state"] == expected, schedule + assert pair.paused[0].get(pair.keys[0], False) == sender["confirmed_state"] + assert pair.paused[1] == {} + return + assert len(schedule) <= 3 * len(operations), schedule # No notification loop. + for action in actions: + explore((*schedule, action)) + explore() + + +def test_preset_pause_is_adopted_once_and_start_never_leaves_a_false_entry(): + pair = _ControlPair() + registry, key, sock = pair.registries[0], pair.keys[0], pair.sockets[0] + assert registry.release(pair.states[0]) + assert not registry.local(key, True, pair.send(0)) + assert not registry.local(pair.keys[1], True, pair.send(0)) + assert pair.paused[0] == {key: True} and not any(pair.pending) + state = registry.register(key, sock, object()) + assert state["confirmed_state"] is True + assert registry.register(key, sock, state["owner"]) is state + assert registry.announce(state, pair.send(0)) + assert not registry.announce(state, pair.send(0)) + pair.drain() + assert pair.states[1]["confirmed_state"] is True + assert pair.local(0, False) + pair.drain() + assert pair.paused == [{}, {}] + assert registry.release(state) + assert not registry.local(key, True, pair.send(0)) + assert not registry.local(key, False, pair.send(0)) + fresh = registry.register(key, sock, object()) + assert fresh["confirmed_state"] is False and not registry.announce(fresh, pair.send(0)) + + +def test_control_namespace_and_session_ownership_isolate_active_legs(): + pair = _ControlPair() + registry, key, sock = pair.registries[0], pair.keys[0], pair.sockets[0] + unknown = _transfer_control_key(("127.0.0.2", 6000), 42, 0, 0) + relay = _transfer_control_key(PEER, 42, 1, 0) + reverse = _transfer_control_key(PEER, 42, 0, 1) + others = [registry.register(other, object(), object()) for other in (relay, reverse)] + assert not registry.receive(unknown, sock, True, pair.send(0)) + assert not registry.receive(key, object(), True, pair.send(0)) + others.append(registry.register(unknown, object(), object())) + assert registry.register(key, sock, object()) is None + assert registry.register(key, object(), pair.states[0]["owner"]) is None + assert pair.local(0, True) + assert all(state["confirmed_state"] is False for state in others) + assert pair.paused[0] == {key: True} + assert registry.discard_socket(sock) == 1 + new = registry.register(key, object(), object()) + assert not registry.release(pair.states[0]) and registry.discard_socket(sock) == 0 + assert new["confirmed_state"] is False and pair.paused[0] == {} + assert registry.receive(key, new["control_socket"], True, lambda *_: True) + assert new["confirmed_state"] is True and pair.paused[0] == {key: True} + + +@pytest.mark.parametrize("side", [0, 1]) +@pytest.mark.parametrize("raises", [False, True]) +def test_failed_control_write_retires_owner_without_retry(side, raises): + pair = _ControlPair() + def fail(sock, line): + if raises: + raise BrokenPipeError("closed control socket") + return False + registry, key, state = pair.registries[side], pair.keys[side], pair.states[side] + if raises: + with pytest.raises(BrokenPipeError): + registry.local(key, True, fail) + else: + assert registry.local(key, True, fail) is False + assert pair.paused[side] == {} and not any(pair.pending) + assert state["confirmed_state"] is state["last_requested_state"] is False + assert registry.register(key, object(), object())["confirmed_state"] is False + + + +def test_start_before_initial_publication_cancels_the_adopted_pause(): + pair = _ControlPair() + registry, key = pair.registries[0], pair.keys[0] + assert registry.release(pair.states[0]) + assert not registry.local(key, True, pair.send(0)) + state = registry.register(key, pair.sockets[0], object()) + assert pair.local(0, False) + assert not registry.announce(state, pair.send(0)) + pair.drain() + assert state["confirmed_state"] is pair.states[1]["confirmed_state"] is False + assert pair.paused == [{}, {}] + + +@pytest.mark.parametrize("sock,owner", [(None, object()), (object(), None)]) +def test_leg_registration_requires_both_session_and_owner(sock, owner): + registry = _TransferControlRegistry({}, threading.Condition()) + with pytest.raises(ValueError): + registry.register(_transfer_control_key(PEER, 42, 0, 0), sock, owner) + +@pytest.mark.parametrize("finish", ["start", "release"]) +def test_start_and_release_wake_a_sender_without_reordering_control_writes(finish): + pair = _ControlPair() + registry, state = pair.registries[0], pair.states[0] + entered, proceed, attempted, woke, ready = (threading.Event() for _ in range(5)) + class ObservedLock: + def __enter__(self): + if entered.is_set(): + attempted.set() + return self.lock.__enter__() + + def __exit__(self, *args): + return self.lock.__exit__(*args) + + observed = ObservedLock() + observed.lock = state["lock"] + state["lock"] = observed + condition, key = registry._condition, pair.keys[0] + def send(sock, line): + entered.set() + assert proceed.wait(2) + return pair.send(0)(sock, line) + def waiter(): + with condition: + ready.set() + assert condition.wait(timeout=2) + assert key not in pair.paused[0] + woke.set() + def complete(): + if finish == "start": + registry.receive(key, pair.sockets[0], False, pair.send(0)) + else: + registry.release(state) + with ThreadPoolExecutor(max_workers=3) as workers: + first = workers.submit(registry.local, key, True, send) + try: + assert entered.wait(2) + waiting = workers.submit(waiter) + assert ready.wait(2) + second = workers.submit(complete) + assert attempted.wait(2) + assert state["confirmed_state"] is True and pair.paused[0] == {key: True} + finally: + proceed.set() + for worker in (first, second, waiting): + worker.result(timeout=2) + assert woke.is_set() and pair.paused[0] == {} + if finish == "start": + pair.drain() + assert pair.states[1]["confirmed_state"] is False + else: + assert tuple(pair.pending[1]) == ("/pause_trans 42 0 0",) + + +@pytest.mark.parametrize("owner_type", [TCP_Server_Base, TCP_Client_Base]) +def test_control_state_never_enters_the_persisted_progress_snapshot(owner_type, tmp_path): + owner = owner_type(host="127.0.0.1", port=0, is_extend_command=True, + is_enable_encrypto=False, is_input_command_in_console=False, + is_print_log=False) + for attr in ("messages_log_file", "events_log_file", "sent_messages_log_file", + "sent_events_log_file", "file_trans_progress_file"): + setattr(owner, attr, str(tmp_path / f"{attr}.json")) + owner.file_upload_progress[(PEER, 42)] = [3, 10, None, "/send/file.bin", PEER] + before = owner._transfer_progress_snapshot() + try: + key = _transfer_control_key(PEER, 42, 0, 0) + controls = owner._transfer_controls + assert not controls.local(key, True, lambda *_: True) + controls.register(key, object(), object()) + owner._persist_transfer_progress() + with open(owner.file_trans_progress_file, encoding="utf-8") as stream: + assert json.load(stream) == before + finally: + owner.stop() if owner_type is TCP_Server_Base else owner.close() From fd189d13ce5bc4e0d42a347f8b18bebd7428da5e Mon Sep 17 00:00:00 2001 From: F18-Ray Date: Mon, 16 Nov 2026 17:45:18 +0800 Subject: [PATCH 03/19] feat(connect_tcp)!: integrate typed bidirectional transfer control --- PyFlow/network_api/connect_tcp.py | 635 ++++++++---------- .../transfer-pause-start-direction-plan.md | 8 +- .../transfer-pause-start-direction-report.md | 97 ++- docs/source/File_Transfer/File_Transfer.rst | 79 ++- docs/source/Network_APIs/TCP_Client_APIs.rst | 44 +- docs/source/Network_APIs/TCP_Server_APIs.rst | 21 +- docs/source/changes/transfer-fid-routes.md | 30 + .../network_api/test_tcp_file_transfer.py | 21 +- .../network_api/test_tcp_transfer_control.py | 387 +++++++++++ .../network_api/test_tcp_transfer_resume.py | 89 +-- test/unit/network_api/test_fid_routes.py | 12 +- .../unit/network_api/test_transfer_control.py | 35 + .../test_transfer_progress_query.py | 7 +- 13 files changed, 1006 insertions(+), 459 deletions(-) create mode 100644 test/integration/network_api/test_tcp_transfer_control.py diff --git a/PyFlow/network_api/connect_tcp.py b/PyFlow/network_api/connect_tcp.py index 2b88e7a..6682f83 100644 --- a/PyFlow/network_api/connect_tcp.py +++ b/PyFlow/network_api/connect_tcp.py @@ -522,8 +522,7 @@ def _get_transfer_progress(instance, *, include_persisted, server_routes=False): snapshot = instance._transfer_progress_snapshot() active = set(instance._active_transfer_fids) sockets = set(instance._active_transfer_sockets) - with instance._transfer_pause_cond: - paused = dict(instance._transfer_pause) + paused = instance._transfer_controls.upload_pauses() speed_enabled = bool(instance.is_enable_real_time_network_speed) persisted = { "path": os.fspath(instance.file_trans_progress_file), @@ -794,15 +793,16 @@ class _TransferControlRegistry: """Serialize each leg's decisions and control writes without blocking other legs. Lock order is leg lock then pause condition; lookups release the condition - before taking a leg lock. ``send(socket, line)`` must use the secure control - gate and normal send_message path. It runs inside the leg lock so state and - wire order agree; callers must not wait for crypto on its receive thread. + before taking a leg lock. Production operations append control frames under + that lock; one FIFO worker waits for leg/crypto readiness and sends them. + Explicit ``send(socket, line)`` callbacks are synchronous under the leg lock. """ - def __init__(self, paused, condition): + def __init__(self, paused, condition, instance=None): self._paused = paused self._condition = condition self._legs = {} + self._instance = instance def register(self, key, control_socket, owner): """Bind an unclaimed identity, adopting only its sender's preset pause.""" @@ -818,6 +818,7 @@ def register(self, key, control_socket, owner): "key": key, "control_socket": control_socket, "owner": owner, "lock": threading.RLock(), "confirmed_state": paused, "last_requested_state": False, "initial_notification": paused, + "ready": self._instance is None or key[3] == 1, } self._legs[key] = state return state @@ -840,7 +841,8 @@ def _send(self, state, paused, send): _, fid, trans_type, direction = state["key"] name = "/pause_trans" if paused else "/start_trans" try: - sent = send(state["control_socket"], f"{name} {fid} {trans_type} {direction}") + line = f"{name} {fid} {trans_type} {direction}" + sent = send(state["control_socket"], line) if send is not None else self._enqueue(state, line) except Exception: self.release(state) raise @@ -850,14 +852,17 @@ def _send(self, state, paused, send): state["initial_notification"] = False return True - def announce(self, state, send): + def announce(self, state, send=None): """Publish an adopted pause once the peer can locate the new leg.""" with state["lock"]: + with self._condition: + state["ready"] = True + self._condition.notify_all() if not self._live(state) or not state["initial_notification"]: return False return self._send(state, state["confirmed_state"], send) - def local(self, key, paused, send): + def local(self, key, paused, send=None): """Decide a sender state or submit a receiver intent, deduplicating both.""" with self._condition: state = self._legs.get(key) @@ -883,7 +888,7 @@ def local(self, key, paused, send): state["last_requested_state"] = paused return self._send(state, paused, send) - def receive(self, key, control_socket, paused, send): + def receive(self, key, control_socket, paused, send=None): """Process a request at S or a notification at R; never create wire state.""" with self._condition: state = self._legs.get(key) @@ -908,6 +913,8 @@ def release(self, state): return False del self._legs[key] self._paused.pop(key, None) + if "outbox" in state: + state["outbox"].clear() state["confirmed_state"] = False state["last_requested_state"] = False state["initial_notification"] = False @@ -921,20 +928,129 @@ def discard_socket(self, control_socket): if state["control_socket"] is control_socket] return sum(self.release(state) for state in states) + def _enqueue(self, state, line): + """Queue under the leg lock; crypto readiness never blocks its reader.""" + if "outbox" not in state: + state["outbox"] = collections.deque() + state["outbox"].append(line) + if not state.get("sending", False): + state["sending"] = True + threading.Thread(target=self._flush, args=(state,), daemon=True).start() + return True -def _pause_command_fid(command): - """Return the fid of a ``/pause_trans``/``/start_trans`` line, or None. + def _flush(self, state): + instance, sock = self._instance, state["control_socket"] + try: + while True: + with state["lock"]: + if not self._live(state) or not state["outbox"]: + state["sending"] = False + return + line = state["outbox"].popleft() + with self._condition: + self._condition.wait_for(lambda: state["ready"] or not self._live(state)) + if not self._live(state): + return + if not instance._wait_control_secure(sock): + raise ConnectionError("control channel unavailable") + with state["lock"]: + if not self._live(state): + return + if not instance.send_message(sock, line): + raise ConnectionError("control write failed") + except Exception as exc: + if not self._live(state): + return + if not _is_closed_socket_error(exc): + instance._log(f"transfer control: {exc}") + self.release(state) + instance._transfer_handshakes.cancel_socket(sock) + try: + sock.shutdown(socket.SHUT_RDWR) + except OSError: + pass + + def upload_pauses(self): + """Project only active sender control state onto existing progress keys.""" + with self._condition: + return {(peer, fid): True for (peer, fid, kind, role), state in self._legs.items() + if role == 0 and state["confirmed_state"]} + + def release_owner(self, owner): + with self._condition: + states = [state for state in self._legs.values() if state["owner"] is owner] + for state in states: + self.release(state) + + +def _control_peer(instance, peer): + """Resolve a public control peer into the existing connection namespace.""" + if isinstance(instance, TCP_Client_Base): + configured = (instance.host, instance.port) + return configured if peer is None or _is_control_endpoint( + peer, configured, _socket_peer_endpoint(instance.client_socket) + ) else None + if peer is None: + raise ValueError("control peer is required") + return tuple(peer) + + +def _control_key(instance, peer, fid, trans_type, direction): + if trans_type == 1 and direction == 0 and isinstance(instance, TCP_Server_Base): + with instance._forward_relays_lock: + relay = instance._forward_relays.get((peer, fid)) + if relay is not None: + fid = relay["route"]["targets"].get(peer, fid) + return _transfer_control_key(peer, fid, trans_type, direction) + + +def _set_transfer_control(instance, fid, peer, trans_type, direction, paused): + _validate_transfer_control_identity(fid, trans_type, direction) + peer = _control_peer(instance, peer) + if peer is None: + return False + return instance._transfer_controls.local( + _control_key(instance, peer, fid, trans_type, direction), paused + ) + + +def _receive_transfer_control(instance, sock, peer, command): + parsed = _parse_transfer_control_command(command) + if parsed is None: + return + paused, fid, trans_type, direction = parsed + key = _control_key(instance, peer, fid, trans_type, 1 - direction) + instance._transfer_controls.receive(key, sock, paused) + + +def _bind_transfer_control(instance, fid, sock, owner, trans_type, direction): + if fid is None or sock is None: + return None # public-key legs and standalone transfer sockets + peer = _control_peer(instance, _socket_peer_endpoint(sock)) + state = instance._transfer_controls.register( + _transfer_control_key(peer, fid, trans_type, direction), sock, owner + ) + if state is None: + raise RuntimeError("transfer control identity already owned") + return state + + +def _announce_transfer_control(instance, state): + if state is not None: + instance._transfer_controls.announce(state) + + +def _wait_transfer_control(instance, state, sock): + if state is None: + return + with instance._transfer_pause_cond: + while (instance._transfer_controls._legs.get(state["key"]) is state + and instance._transfer_pause.get(state["key"], False)): + if not instance.running or sock.fileno() < 0: + return + instance._transfer_pause_cond.wait(timeout=0.5) - Args: - command (object): Value used by the operation. - Returns: - NoneType | object: Result produced by the operation. - """ - try: - return int(shlex.split(command)[1]) - except (IndexError, ValueError): - return None def _open_transfer_target(path, offset): @@ -1999,7 +2115,7 @@ def claim_ecdh_pub_send(self): # -- send path ----------------------------------------------------------- - def send(self, payload, force_rsa=False): + def send(self, payload, force_rsa=False, *, require_secure=False): """Frame and send one payload (str or bytes) on this socket. ``force_rsa`` is used for the ECDH public-key line, which must travel @@ -2011,6 +2127,7 @@ def send(self, payload, force_rsa=False): Args: payload (bytes | str): Value used by the operation. force_rsa (bool): Value used by the operation. + require_secure (bool): Reject a control frame if re-exchange disabled framing. Raises: RuntimeError: When the operation cannot complete. @@ -2029,12 +2146,24 @@ def send(self, payload, force_rsa=False): raise RuntimeError("encrypted channel not ready (peer never allowed frames)") if use_rsa: with self._send_lock: - self._sendall(self._rsa_frame(data)) + if require_secure: + with self._lock: + if not self.secure or not self.frames_allowed.is_set(): + raise RuntimeError("control framing changed before write") + self._sendall(self._rsa_frame(data)) + else: + self._sendall(self._rsa_frame(data)) return for start in range(0, max(len(data), 1), MAX_FRAME_PLAINTEXT): chunk = data[start : start + MAX_FRAME_PLAINTEXT] with self._send_lock: - self._sendall(self._ecdh_frame(chunk, peer)) + if require_secure: + with self._lock: + if not self.secure or not self.frames_allowed.is_set(): + raise RuntimeError("control framing changed before write") + self._sendall(self._ecdh_frame(chunk, peer)) + else: + self._sendall(self._ecdh_frame(chunk, peer)) def _rsa_frame(self, text_bytes): """Handle the operation. @@ -2545,7 +2674,7 @@ def __init__( self._transfer_pause = {} self._transfer_pause_cond = threading.Condition() self._transfer_controls = _TransferControlRegistry( - self._transfer_pause, self._transfer_pause_cond + self._transfer_pause, self._transfer_pause_cond, self ) self._active_transfer_fids = set() # fids of the legs running right now self._active_transfer_sockets = {} # receive fid / (receiver, fid) -> socket @@ -2834,7 +2963,13 @@ def _register_fid_route(self, fid, originator, targets, completed=()): or any(key in self._active_transfer_sockets for key in upstream_leg_keys) ) with self._transfer_pause_cond: - paused_collision = any(key in self._transfer_pause for key in upstream_leg_keys) + paused_collision = any( + leg_fid == fid and ( + role == 0 and (peer, fid) in upstream_leg_keys + or role == 1 and peer == tuple(originator) + ) + for peer, leg_fid, kind, role in self._transfer_controls._legs + ) with self._forward_relays_lock: if ( not targets @@ -3060,87 +3195,33 @@ def _load_transfer_progress(self): restored += 1 return restored - def _forward_relay_targets(self, fid, peer=None): - """Live relay writers a pause/resume for ``fid`` addresses. - Args: - fid (int): Relay fid, or one of its per-target transfer ids. - peer (tuple | None): Restrict to the writer serving this peer; None addresses every writer of the relay. - - Returns: - tuple: ``(relay, [targets])``; ``(None, [])`` when no live relay - writer matches. - """ - with self._forward_relays_lock: - relay = self._forward_relays.get((tuple(peer), fid)) if peer is not None else None - if relay is None or not relay.get("writer_pause"): - return None, [] - for target in relay["writer_pause"]: - if tuple(target) == tuple(peer): - return relay, [target] - return None, [] - - def _mark_transfer_pause(self, fid, paused, peer): - """Set or clear one transfer's pause switch (see `pause_trans`). + def pause_trans(self, fid, peer, *, trans_type, direction): + """Register a pause decision (sender) or request (receiver) for one leg. Args: - fid (int): Value used by the operation. - paused (bool): Value used by the operation. - peer (tuple): Value used by the operation. + fid (int): Nonnegative transfer id. + peer (tuple): Control peer, required even for a preset sender pause. + trans_type (int): 0 ordinary, 1 forwarded. + direction (int): Local data role: 0 sender, 1 receiver. Returns: - bool: True when a live relay writer or outbound leg was found. - """ - if peer is None: - raise ValueError("receiver peer is required") - transfer_key = (tuple(peer), fid) - relay, targets = self._forward_relay_targets(fid, peer) - if targets: - with relay["cond"]: - for target in targets: - relay["writer_pause"][target] = paused - if not paused: - relay["cond"].notify_all() - return True - with self._transfer_progress_lock: - live = transfer_key in self._active_transfer_fids - with self._transfer_pause_cond: - self._transfer_pause[transfer_key] = paused - self._transfer_pause_cond.notify_all() - return live - - def pause_trans(self, fid, peer): - """Pause an outbound transfer of this instance. + bool: Operation registered on a live leg; False for duplicates or a + missing leg. A missing sender leg retains a preset pause. + Registration is not peer confirmation; in-flight data still lands. - The sending leg with this fid stops at its next chunk and stays open - until `start_trans` (or the peer's ``/start_trans``) resumes it. A - forward relay's writer toward ``peer`` is paused the same way the - ``/pause_trans`` line pauses it. - - Args: - fid (int): Transfer id the outbound leg is keyed by. - peer (tuple): Receiver ``(ip, port)`` identifying the outbound leg - or relay writer; required even before the leg starts. - - Returns: - bool: True when a running leg (or relay writer) was marked paused; - False when nothing matched — the switch is still armed, so a - leg later started under this fid starts paused. + Raises: + ValueError: Invalid fid/type/direction or missing peer. """ - return self._mark_transfer_pause(fid, True, peer) + return _set_transfer_control(self, fid, peer, trans_type, direction, True) - def start_trans(self, fid, peer): - """Resume an outbound transfer paused with `pause_trans`. + def start_trans(self, fid, peer, *, trans_type, direction): + """Continue the selected leg on its existing socket; clear preset pauses. - Args: - fid (int): Transfer id the outbound leg is keyed by. - peer (tuple): Receiver ``(ip, port)`` identifying the outbound leg - or relay writer. - - Returns: - bool: True when a live leg (or relay writer) was resumed. + Arguments and registration result match ``pause_trans``. No seek, + truncation or new handshake occurs; receivers continue reading throughout. """ - return self._mark_transfer_pause(fid, False, peer) + return _set_transfer_control(self, fid, peer, trans_type, direction, False) def _register_transfer_socket(self, fid, sock): """Record the socket of a leg, so a dead session can be cleared out. @@ -3161,6 +3242,7 @@ def _release_transfer_socket(self, fid, sock): fid (int | tuple): Receive fid or outgoing ``(receiver, fid)`` key. sock (object): Value used by the operation. """ + self._transfer_controls.release_owner(sock) if fid is None: return with self._transfer_progress_lock: @@ -3181,7 +3263,6 @@ def _drop_stale_transfers(self, peer=None): int: Number of legs closed. """ stale = [] - paused = [] for store in (self.file_upload_progress, self.file_recv_progress): for fid, entry in list(store.items()): owner = fid[0] if store is self.file_upload_progress else entry[4] @@ -3193,8 +3274,6 @@ def _drop_stale_transfers(self, peer=None): self._active_transfer_fids.discard(fid) if sock is not None: stale.append(sock) - if store is self.file_upload_progress: - paused.append(fid) for sock in stale: try: sock.shutdown(socket.SHUT_RDWR) @@ -3204,77 +3283,9 @@ def _drop_stale_transfers(self, peer=None): sock.close() except OSError: pass - if paused: - # The leg may be waiting on this fid's pause switch. Clearing it here - # (outside the progress lock) lets the swept leg exit and release the - # per-key send lock a queued resume is waiting for. - with self._transfer_pause_cond: - for key in paused: - self._transfer_pause.pop(key, None) - self._transfer_pause_cond.notify_all() + self._transfer_controls.release_owner(sock) return len(stale) - def pause_trans_remote(self, peer, fid): - """Ask a connected client to pause its transfer toward this server. - - Sends the ``/pause_trans `` line the peers use for transfer flow - control (see `pause_trans` on the receiving side). - - Args: - peer (tuple): Connected client ``(ip, port)``. - fid (int): Transfer id of that client's outbound leg. - - Returns: - bool: True when the line was written; False when ``peer`` is not - connected. - """ - info = self.clients.get(peer) if peer is not None else None - if info is None: - self._log(f"pause: {peer} is not a connected client") - return False - return self.send_message(info["socket"], f"/pause_trans {fid}") - - def start_trans_remote(self, peer, fid): - """Ask a connected client to resume a transfer paused earlier. - - Args: - peer (tuple): Connected client ``(ip, port)``. - fid (int): Transfer id of that client's outbound leg. - - Returns: - bool: True when the line was written; False when ``peer`` is not - connected. - """ - info = self.clients.get(peer) if peer is not None else None - if info is None: - self._log(f"start: {peer} is not a connected client") - return False - return self.send_message(info["socket"], f"/start_trans {fid}") - - def _wait_transfer_paused(self, fid, leg_socket=None): - """Block a sending leg while its fid is marked paused. - - Runs before every chunk so ``/pause_trans`` stops the stream without - closing the transfer; the wait ends when the leg is resumed, when the - instance stops, when the leg socket is closed, or when the fid is not - paused at all. ``leg_socket`` is the connection this leg writes to: - a reconnect sweep removes it from the registry before closing it, so - the registry alone cannot report the close. - - Args: - fid (int): Value used by the operation. - leg_socket (socket.socket | None): The leg's own transfer socket. - """ - if fid is None: - return - with self._transfer_pause_cond: - while self._transfer_pause.get(fid, False): - sock = self._active_transfer_sockets.get(fid) - if (not self.running - or (sock is not None and sock.fileno() < 0) - or (leg_socket is not None and leg_socket.fileno() < 0)): - return - self._transfer_pause_cond.wait(timeout=0.5) def _wait_control_secure(self, control_socket, timeout=RESUME_SECURE_TIMEOUT): """Wait until a control channel may carry framed protocol lines. @@ -3295,12 +3306,14 @@ def _wait_control_secure(self, control_socket, timeout=RESUME_SECURE_TIMEOUT): return True deadline = time.time() + timeout while time.time() < deadline: + if not self.running or control_socket.fileno() < 0: + return False with self._crypto_lock: channel = self._channels.get(control_socket) - if channel is not None and channel.secure: + if channel is not None and channel.secure and channel.frames_allowed.is_set(): return True time.sleep(0.05) - self._log("resume: control channel not framed yet, transfers kept for the next reconnect") + self._log("control channel not framed yet; transfer control was not sent") return False def alloc_port(self, port_add_step, port_range_num): @@ -4315,6 +4328,11 @@ def _write_message(self, client_socket, message): raise RuntimeError("connection error") with self._crypto_lock: channel = self._channels.get(client_socket) + control_frame = (self.is_enable_encrypto and self.crypto is not None + and isinstance(message, str) + and message.split(maxsplit=1)[:1] in (["/pause_trans"], ["/start_trans"])) + if control_frame and (channel is None or not channel.secure): + return False if channel is not None and channel.secure: try: if not isinstance(message, (str, bytes)): @@ -4323,7 +4341,7 @@ def _write_message(self, client_socket, message): payload = message if isinstance(message, str) and not message.strip().endswith("\n"): payload = message.strip() + "\n" # line framing for the control protocol - channel.send(payload) + channel.send(payload, require_secure=control_frame) self._measure_network_speed(payload, is_upload=True) return True except Exception as e: @@ -5219,6 +5237,7 @@ def _unregister_client(self, client_socket, client_address, client_id): client_id (str): Client id used in the console log. """ self._transfer_handshakes.cancel_socket(client_socket) + self._transfer_controls.discard_socket(client_socket) with self.client_lock: owns_peer = self.clients.get(client_address, {}).get("socket") is client_socket if owns_peer: @@ -5267,6 +5286,11 @@ def handle_command( self._debug(client_socket, client_address, command) client_id = f"{client_address[0]}:{client_address[1]}" send_str = None + if command.split(maxsplit=1)[:1] and command.split(maxsplit=1)[0].lower() in ( + "/pause_trans", "/start_trans" + ): + _receive_transfer_control(self, client_socket, tuple(client_address), command) + return None if command == "/help": help_text = [ "avalable commands:", @@ -5349,12 +5373,6 @@ def handle_command( daemon=True, ).start() return "Command received, processing in background.\n" - elif shlex.split(command.lower())[0] == "/pause_trans": - self._handle_pause_command(client_address, command, True) - return None - elif shlex.split(command.lower())[0] == "/start_trans": - self._handle_pause_command(client_address, command, False) - return None elif shlex.split(command.lower())[0] == RESUME_LINE: parsed = parse_resume_command(command) if parsed is not None: @@ -5746,6 +5764,7 @@ def close_socket(): file_running = False self._crypto_drop_channel(client_file_socket) if client_file_socket is not None: + self._transfer_controls.release_owner(client_file_socket) client_file_socket.close() self._transfer_handshakes.release_socket(client_socket, client_file_socket) if server_file_socket is not None: @@ -5886,6 +5905,8 @@ def file_transfer_client_recv(client_id): peer=peer, initial=resume_from, ) + if progress is None: + progress = resume_entry with _open_transfer_target(full_path, resume_from) as f: remaining = file_size - resume_from while remaining > 0: @@ -6006,6 +6027,7 @@ def file_transfer_client_recv(client_id): client_file_socket.settimeout(None) # the accept timeout is the listener's only self._crypto_attach_transfer_in(client_file_socket, client_socket, stamp) self._register_transfer_socket(progress_fid, client_file_socket) + _bind_transfer_control(self, progress_fid, client_socket, client_file_socket, 0, 1) if resume_entry is not None: threading.Thread( target=file_transfer_client_recv, args=(client_id,), daemon=True @@ -6371,6 +6393,7 @@ def file_transfer_mode( # noqa: PLR0911 - peer-close and timeout exits are dist fid=None, peer=None, resume_offset=0, + trans_type=0, ): """Send one file over a transfer sub-connection. @@ -6384,6 +6407,7 @@ def file_transfer_mode( # noqa: PLR0911 - peer-close and timeout exits are dist fid (int | None): Transfer ID used for progress and pause tracking. peer (tuple | None): Original receiver ``(ip, port)`` for resuming. resume_offset (int): Byte offset to resume from; defaults to zero. + trans_type (int): 0 ordinary, 1 forwarded. Returns: bool: True when the receiver acknowledges the file; otherwise False. @@ -6395,12 +6419,14 @@ def file_transfer_mode( # noqa: PLR0911 - peer-close and timeout exits are dist transfer_key = (receiver, fid) if fid is not None else None client_file_socket = None reset_time = 0 + control = None def close_socket(): """Handle the operation.""" nonlocal file_running nonlocal client_file_socket file_running = False + self._transfer_controls.release_owner(client_file_socket) self._crypto_drop_channel(client_file_socket) self._transfer_handshakes.release_socket(control_socket, client_file_socket) client_file_socket.close() @@ -6410,12 +6436,16 @@ def close_socket(): client_file_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM) if not self._transfer_handshakes.track_socket(control_socket, client_file_socket): return False + control = _bind_transfer_control( + self, fid, control_socket, client_file_socket, trans_type, 0 + ) client_file_socket.bind((self.host, client_port)) client_file_socket.connect((server_address, server_port)) break except Exception as e: self._transfer_handshakes.release_socket(control_socket, client_file_socket) client_file_socket.close() + self._transfer_controls.release_owner(client_file_socket) if _should_fallback_local_port(client_port, e): self._log( f"file transfer source port {client_port} is not available ({e}); " @@ -6491,6 +6521,7 @@ def receive_file_transfer_messages(): running = file_running start_seen, _, error_seen = transfer_signs.consume() if start_seen: + _announce_transfer_control(self, control) break if error_seen: close_socket() @@ -6529,9 +6560,9 @@ def receive_file_transfer_messages(): with open(filename, "rb") as f: if resume_offset: f.seek(resume_offset) - while True: + while f.tell() < file_size: transfer_signs.consume() - self._wait_transfer_paused(transfer_key, client_file_socket) + _wait_transfer_control(self, control, client_file_socket) file_data = f.read(self.file_transfer_chunk_len) if not file_data: break @@ -6610,8 +6641,6 @@ def receive_file_transfer_messages(): ), ) self._release_transfer_socket(transfer_key, client_file_socket) - with self._transfer_pause_cond: - self._transfer_pause.pop(transfer_key, None) # ---- transfer reconnect (server side) ---------------------------------- @@ -7005,25 +7034,6 @@ def _forward_recv_exact(self, sock, n): buf += data return buf - def _handle_pause_command(self, client_address, command, paused): - """Apply a client's ``/pause_trans``/``/start_trans`` on this side. - - A client throttles the writer that feeds it (a forward relay's writer - for its target) or, without a relay, this server's own outbound leg to - that client (see `pause_trans`). - - Args: - client_address (tuple): Value used by the operation. - command (object): Value used by the operation. - paused (bool): Value used by the operation. - - Returns: - NoneType | object: Result produced by the operation. - """ - fid = _pause_command_fid(command) - if fid is None: - return None - return self._mark_transfer_pause(fid, paused, tuple(client_address)) def _forward_relay( self, @@ -7084,7 +7094,7 @@ def _forward_relay( return relay = { "cond": threading.Condition(), - "writer_pause": {target: False for target in targets}, + "controls": {}, "route": route, } relay_keys = [(target, leg_fid) for target, tfid in zip(targets, tfids) for leg_fid in (fid, tfid)] @@ -7170,6 +7180,9 @@ def own(control, transfer): sock.close() continue target_conns.append((tfid, target, sock)) + control = _bind_transfer_control(self, tfid, target_control, sock, 1, 0) + relay["controls"][target] = control + _announce_transfer_control(self, control) if not target_conns: fail("no target accepted the transfer") return @@ -7199,6 +7212,9 @@ def own(control, transfer): if not own(forwarder_sock, up_client): return self._crypto_attach_transfer_in(up_client, forwarder_sock, up_stamp) + relay["upstream"] = _bind_transfer_control( + self, fid, forwarder_sock, up_client, 1, 1 + ) self.send_message(up_client, self.server_start_file_transfer_sign) self._forward_pump( up_client, target_conns, forwarder_sock, fid, fname, relay, resume_offset @@ -7208,6 +7224,7 @@ def own(control, transfer): fail(f"relay setup interrupted: {exc}") finally: for control, transfer in owned_sockets: + self._transfer_controls.release_owner(transfer) self._transfer_handshakes.release_socket(control, transfer) for transfer_socket in [up_client, up_sock, *(sock for _, _, sock in target_conns)]: if transfer_socket is not None: @@ -7227,11 +7244,8 @@ def _forward_pump( ): """Pump the uploader's byte stream to every target from memory. - The total bytes held in the per-target queues never exceeds - ``max_mem_buff``: once it does, the uploader is told to pause - (``/pause_trans``) and the reader stops pulling; as the writers - drain below the low-water mark the uploader is resumed - (``/start_trans``). + Queue high/low-water marks bound buffered data, allowing a finite enqueue + overshoot. Control start cannot clear the reader's high-water gate. Args: up_sock (object): Value used by the operation. @@ -7249,7 +7263,7 @@ def _forward_pump( max_bytes = max(1, self.max_mem_buff) low_water = max(1, max_bytes // 2) cond = relay["cond"] - writer_pause = relay["writer_pause"] + controls = relay["controls"] state = {"buffered": 0, "paused": False, "complete": False, "failed": False} queues = {(target, tfid): queue.Queue() for tfid, target, _ in target_conns} END = object() @@ -7261,7 +7275,7 @@ def release_buffered(byte_count): if state["paused"] and state["buffered"] <= low_water: state["paused"] = False try: - self.send_message(forwarder_sock, f"/start_trans {fid}") + self.start_trans(fid, _socket_peer_endpoint(forwarder_sock), trans_type=1, direction=1) except Exception: pass cond.notify_all() @@ -7273,18 +7287,14 @@ def enqueue(chunk): pending.put(chunk) if not state["paused"] and state["buffered"] > max_bytes: state["paused"] = True - self.send_message(forwarder_sock, f"/pause_trans {fid}") + self.pause_trans(fid, _socket_peer_endpoint(forwarder_sock), trans_type=1, direction=1) def writer(tfid, target, sock): key = (target, tfid) pending = queues[key] try: while True: - with cond: - while writer_pause.get(target, False) and not state["failed"]: - if sock.fileno() < 0: - return - cond.wait(timeout=0.5) + _wait_transfer_control(self, controls[target], sock) item = pending.get() if item is END: break @@ -7305,6 +7315,7 @@ def writer(tfid, target, sock): except Exception as exc: self._log(f"forward: target {target} interrupted: {exc}") finally: + self._transfer_controls.release_owner(sock) with cond: queues.pop(key, None) while not pending.empty(): @@ -7343,6 +7354,9 @@ def reader(): finally: with cond: state["failed"] = not state["complete"] + if state["failed"]: + for control in controls.values(): + self._transfer_controls.release(control) for pending in queues.values(): pending.put(END) cond.notify_all() @@ -7617,6 +7631,7 @@ def stop(self): # shutting down the server with self.client_lock: # close all clients connections for client_info in self.clients.values(): self._transfer_handshakes.cancel_socket(client_info["socket"]) + self._transfer_controls.discard_socket(client_info["socket"]) try: # a client thread blocked in recv() keeps the connection half # open past close(): the shutdown sends its FIN and wakes it @@ -7811,7 +7826,7 @@ def __init__( self._transfer_pause = {} self._transfer_pause_cond = threading.Condition() self._transfer_controls = _TransferControlRegistry( - self._transfer_pause, self._transfer_pause_cond + self._transfer_pause, self._transfer_pause_cond, self ) self._active_transfer_fids = set() # fids of the legs running right now self._active_transfer_sockets = {} # receive fid / (receiver, fid) -> socket @@ -8762,96 +8777,33 @@ def _load_transfer_progress(self): restored += 1 return restored - def _mark_transfer_pause(self, fid, paused, peer=None): - """Set or clear one transfer's pause switch (see `pause_trans`). - - Args: - fid (int): Value used by the operation. - paused (bool): Value used by the operation. - peer (tuple): Value used by the operation. - - Returns: - bool: True when a running outbound leg was found. - """ - receiver = (self.host, self.port) - if peer is not None and tuple(peer) != receiver: - return False - transfer_key = (receiver, fid) - with self._transfer_progress_lock: - live = transfer_key in self._active_transfer_fids - with self._transfer_pause_cond: - self._transfer_pause[transfer_key] = paused - self._transfer_pause_cond.notify_all() - return live - - def pause_trans(self, fid, peer=None): - """Pause an outbound transfer of this instance. - The sending leg with this fid stops at its next chunk and stays open - until `start_trans` (or the peer's ``/start_trans``) resumes it. This - covers every outgoing transfer — a plain upload as much as a forward - upload — and is what the ``/pause_trans`` line does when it arrives - from a peer. + def pause_trans(self, fid, peer=None, *, trans_type, direction): + """Register a pause decision/request for one ordinary or forwarded leg. Args: - fid (int): Transfer id the outbound leg is keyed by. - peer (tuple | None): Actual receiving server ``(ip, port)``; - None uses ``(self.host, self.port)``. A different peer is rejected. + fid (int): Nonnegative transfer id. + peer (tuple | None): Configured or connected server; None selects it. + trans_type (int): 0 ordinary, 1 forwarded. + direction (int): Local data role: 0 sender, 1 receiver. Returns: - bool: True when a running leg was marked paused; False when - nothing matched — the switch is still armed, so a leg started - later under this fid starts paused. - """ - return self._mark_transfer_pause(fid, True, peer) - - def start_trans(self, fid, peer=None): - """Resume an outbound transfer paused with `pause_trans`. + bool: Operation registered on a live leg, not peer confirmation. + False for duplicates, wrong peers or missing legs; a missing + sender leg retains a preset pause. In-flight data still lands. - Args: - fid (int): Transfer id the outbound leg is keyed by. - peer (tuple | None): Actual receiving server ``(ip, port)``; - None uses ``(self.host, self.port)``. - - Returns: - bool: True when a running leg was resumed. + Raises: + ValueError: Invalid fid, transfer type or direction. """ - return self._mark_transfer_pause(fid, False, peer) - - def pause_trans_remote(self, peer, fid): - """Ask the server to pause its transfer toward this client. + return _set_transfer_control(self, fid, peer, trans_type, direction, True) - Sends the ``/pause_trans `` line the peers use for transfer flow - control (a forwarded upload this client relays is throttled this way). + def start_trans(self, fid, peer=None, *, trans_type, direction): + """Continue the selected leg on its existing socket; clear preset pauses. - Args: - peer (tuple | None): The server's ``(ip, port)``; None accepts the - connected server. - fid (int): Transfer id of the server's outbound leg. - - Returns: - bool: True when the line was written. + Arguments and registration result match ``pause_trans``. No seek, + truncation or new handshake occurs; receivers continue reading throughout. """ - if peer is not None and tuple(peer) != (self.host, self.port): - self._log(f"pause: {peer} is not the server this client is connected to") - return False - return self.send_message(self.client_socket, f"/pause_trans {fid}") - - def start_trans_remote(self, peer, fid): - """Ask the server to resume a transfer paused earlier. - - Args: - peer (tuple | None): The server's ``(ip, port)``; None accepts the - connected server. - fid (int): Transfer id of the server's outbound leg. - - Returns: - bool: True when the line was written. - """ - if peer is not None and tuple(peer) != (self.host, self.port): - self._log(f"start: {peer} is not the server this client is connected to") - return False - return self.send_message(self.client_socket, f"/start_trans {fid}") + return _set_transfer_control(self, fid, peer, trans_type, direction, False) def _register_transfer_socket(self, fid, sock): """Record the socket of a leg, so a dead session can be cleared out. @@ -8872,6 +8824,7 @@ def _release_transfer_socket(self, fid, sock): fid (int | tuple): Receive fid or outgoing ``(receiver, fid)`` key. sock (object): Value used by the operation. """ + self._transfer_controls.release_owner(sock) if fid is None: return with self._transfer_progress_lock: @@ -8892,7 +8845,6 @@ def _drop_stale_transfers(self, peer=None): int: Number of legs closed. """ stale = [] - paused = [] for store in (self.file_upload_progress, self.file_recv_progress): for fid, entry in list(store.items()): owner = fid[0] if store is self.file_upload_progress else entry[4] @@ -8904,8 +8856,6 @@ def _drop_stale_transfers(self, peer=None): self._active_transfer_fids.discard(fid) if sock is not None: stale.append(sock) - if store is self.file_upload_progress: - paused.append(fid) for sock in stale: try: sock.shutdown(socket.SHUT_RDWR) @@ -8915,40 +8865,9 @@ def _drop_stale_transfers(self, peer=None): sock.close() except OSError: pass - if paused: - # The leg may be waiting on this fid's pause switch. Clearing it here - # (outside the progress lock) lets the swept leg exit and release the - # per-key send lock a queued resume is waiting for. - with self._transfer_pause_cond: - for key in paused: - self._transfer_pause.pop(key, None) - self._transfer_pause_cond.notify_all() + self._transfer_controls.release_owner(sock) return len(stale) - def _wait_transfer_paused(self, fid, leg_socket=None): - """Block a sending leg while its fid is marked paused. - - Runs before every chunk so ``/pause_trans`` stops the stream without - closing the transfer; the wait ends when the leg is resumed, when the - instance stops, when the leg socket is closed, or when the fid is not - paused at all. ``leg_socket`` is the connection this leg writes to: - a reconnect sweep removes it from the registry before closing it, so - the registry alone cannot report the close. - - Args: - fid (int): Value used by the operation. - leg_socket (socket.socket | None): The leg's own transfer socket. - """ - if fid is None: - return - with self._transfer_pause_cond: - while self._transfer_pause.get(fid, False): - sock = self._active_transfer_sockets.get(fid) - if (not self.running - or (sock is not None and sock.fileno() < 0) - or (leg_socket is not None and leg_socket.fileno() < 0)): - return - self._transfer_pause_cond.wait(timeout=0.5) def _wait_control_secure(self, control_socket, timeout=RESUME_SECURE_TIMEOUT): """Wait until a control channel may carry framed protocol lines. @@ -8969,12 +8888,14 @@ def _wait_control_secure(self, control_socket, timeout=RESUME_SECURE_TIMEOUT): return True deadline = time.time() + timeout while time.time() < deadline: + if not self.running or control_socket.fileno() < 0: + return False with self._crypto_lock: channel = self._channels.get(control_socket) - if channel is not None and channel.secure: + if channel is not None and channel.secure and channel.frames_allowed.is_set(): return True time.sleep(0.05) - self._log("resume: control channel not framed yet, transfers kept for the next reconnect") + self._log("control channel not framed yet; transfer control was not sent") return False def alloc_port(self, port_add_step, port_range_num): @@ -9557,6 +9478,7 @@ def receive_messages(self): # get server msg self._persist_transfer_progress() break self._transfer_handshakes.cancel_socket(control_socket) + self._transfer_controls.discard_socket(control_socket) def send_message(self, client_socket, message, is_send_raw=False): # send msg to server @@ -9599,13 +9521,18 @@ def _write_message(self, client_socket, message): # noqa: PLR0911 - same exits return False with self._crypto_lock: channel = self._channels.get(client_socket) + control_frame = (self.is_enable_encrypto and self.crypto is not None + and isinstance(message, str) + and message.split(maxsplit=1)[:1] in (["/pause_trans"], ["/start_trans"])) + if control_frame and (channel is None or not channel.secure): + return False if channel is not None and channel.secure: try: if not isinstance(message, (str, bytes)): self._log(f"Unsupported message type: {type(message)}") return False payload = message.strip() + "\n" if isinstance(message, str) else message - channel.send(payload) + channel.send(payload, require_secure=control_frame) self._measure_network_speed(payload, is_upload=True) return True except Exception as e: @@ -10232,6 +10159,11 @@ def handle_server_command(self, command, control_socket=None): control_socket = self.client_socket if control_socket is not self.client_socket: return # a replaced control session cannot dispatch into the new one + if command.split(maxsplit=1)[:1] and command.split(maxsplit=1)[0].lower() in ( + "/pause_trans", "/start_trans" + ): + _receive_transfer_control(self, control_socket, (self.host, self.port), command) + return client_id = f"{self.client_host}:{self.client_port}" if command.lower().split(" ")[0] == "/crypto_mode": try: @@ -10344,14 +10276,6 @@ def handle_server_command(self, command, control_socket=None): self.file_folder_transfer_client_recv_server_start_thread( command, client_id, self.client_socket ) - elif shlex.split(command.lower())[0] == "/pause_trans": - fid = _pause_command_fid(command) - if fid is not None: - self.pause_trans(fid) - elif shlex.split(command.lower())[0] == "/start_trans": - fid = _pause_command_fid(command) - if fid is not None: - self.start_trans(fid) elif shlex.split(command.lower())[0] == RESUME_LINE: parsed = parse_resume_command(command) if parsed is not None and self.client_socket is not None: @@ -10765,6 +10689,7 @@ def file_transfer_mode( # noqa: PLR0911 - peer-close and timeout exits are dist fid=None, peer=None, resume_offset=0, + trans_type=0, ): """Send one file over a transfer sub-connection. @@ -10778,6 +10703,7 @@ def file_transfer_mode( # noqa: PLR0911 - peer-close and timeout exits are dist fid (int | None): Transfer ID used for progress and pause tracking. peer (tuple | None): Original receiver ``(ip, port)`` for resuming. resume_offset (int): Byte offset to resume from; defaults to zero. + trans_type (int): 0 ordinary, 1 forwarded. Returns: bool: True only after the receiver's final data ACK; otherwise False. @@ -10786,12 +10712,14 @@ def file_transfer_mode( # noqa: PLR0911 - peer-close and timeout exits are dist transfer_key = ((self.host, self.port), fid) if fid is not None else None client_file_socket = None reset_time = 0 + control = None def close_socket(): """Handle the operation.""" nonlocal file_running nonlocal client_file_socket file_running = False + self._transfer_controls.release_owner(client_file_socket) self._crypto_drop_channel(client_file_socket) self._transfer_handshakes.release_socket(control_socket, client_file_socket) client_file_socket.close() @@ -10801,12 +10729,16 @@ def close_socket(): client_file_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM) if not self._transfer_handshakes.track_socket(control_socket, client_file_socket): return False + control = _bind_transfer_control( + self, fid, control_socket, client_file_socket, trans_type, 0 + ) client_file_socket.bind((self.client_host, client_port)) client_file_socket.connect((server_address, server_port)) break except Exception as e: self._transfer_handshakes.release_socket(control_socket, client_file_socket) client_file_socket.close() + self._transfer_controls.release_owner(client_file_socket) if _should_fallback_local_port(client_port, e): self._log( f"file transfer source port {client_port} is not available ({e}); " @@ -10880,6 +10812,7 @@ def receive_file_transfer_messages(): running = file_running start_seen, _, error_seen = transfer_signs.consume() if start_seen: + _announce_transfer_control(self, control) break if error_seen: close_socket() @@ -10918,9 +10851,9 @@ def receive_file_transfer_messages(): with open(filename, "rb") as f: if resume_offset: f.seek(resume_offset) - while True: + while f.tell() < file_size: transfer_signs.consume() - self._wait_transfer_paused(transfer_key, client_file_socket) + _wait_transfer_control(self, control, client_file_socket) file_data = f.read(self.file_transfer_chunk_len) if not file_data: break @@ -10999,8 +10932,6 @@ def receive_file_transfer_messages(): ), ) self._release_transfer_socket(transfer_key, client_file_socket) - with self._transfer_pause_cond: - self._transfer_pause.pop(transfer_key, None) # ---- transfer reconnect (client side) ---------------------------------- @@ -11328,11 +11259,10 @@ def _forward_one( fid=fid, peer=targets[0] if targets else None, resume_offset=resume_offset, + trans_type=1, ) finally: self.pfree(client_port) - with self._transfer_pause_cond: - self._transfer_pause.pop((server_peer, fid), None) def file_folder_transfer_client_recv_server_start_thread( self, command, client_id, client_socket @@ -11485,6 +11415,7 @@ def close_socket(): file_running = False self._crypto_drop_channel(client_file_socket) if client_file_socket is not None: + self._transfer_controls.release_owner(client_file_socket) client_file_socket.close() self._transfer_handshakes.release_socket(client_socket, client_file_socket) if server_file_socket is not None: @@ -11623,6 +11554,8 @@ def file_transfer_client_recv(client_id): peer=peer, initial=resume_from, ) + if progress is None: + progress = resume_entry with _open_transfer_target(full_path, resume_from) as f: remaining = file_size - resume_from while remaining > 0: @@ -11733,6 +11666,10 @@ def file_transfer_client_recv(client_id): client_file_socket.settimeout(None) # the accept timeout is the listener's only self._crypto_attach_transfer_in(client_file_socket, client_socket, stamp) self._register_transfer_socket(progress_fid, client_file_socket) + trans_type = int(parse_forward_originator(command, self._own_address_text()) is not None) + _bind_transfer_control( + self, progress_fid, client_socket, client_file_socket, trans_type, 1 + ) if resume_entry is not None: threading.Thread( target=file_transfer_client_recv, args=(client_id,), daemon=True @@ -11771,6 +11708,7 @@ def close(self): # close connection self._stop_listeners() if self.client_socket: self._transfer_handshakes.cancel_socket(self.client_socket) + self._transfer_controls.discard_socket(self.client_socket) try: # the receive thread may be blocked in recv() on this socket: # close() alone sends no FIN and leaves that read waiting for its @@ -11819,6 +11757,7 @@ def _release_client_socket(self): if sock is None: return self._transfer_handshakes.cancel_socket(sock) + self._transfer_controls.discard_socket(sock) try: sock.setsockopt(socket.SOL_SOCKET, socket.SO_LINGER, struct.pack("ii", 1, 0)) except OSError: diff --git a/docs/plans/transfer-pause-start-direction-plan.md b/docs/plans/transfer-pause-start-direction-plan.md index b7e4bf8..2b955f2 100644 --- a/docs/plans/transfer-pause-start-direction-plan.md +++ b/docs/plans/transfer-pause-start-direction-plan.md @@ -1,6 +1,6 @@ # 双向文件暂停、继续与按对象恢复 — 需求卡与更改计划 -状态:**C1 已通过人工审查;C2a 已获授权、实现并通过定向验证,待人工审查**。需求卡和七项拆分已确认。本文件替代此前尚未落盘的 C1–C5 提案;不修改历史计划或报告的结论。C2b–C5 尚未开始,公共协议/API 变更仍须在 C2b 切换前单独取得许可。每个原子变更完成后另附验证报告并等待审查。不自行提交、合并或推送。证据见[实施报告](transfer-pause-start-direction-report.md)。 +状态:**C1、C2a 已通过人工审查;C2b 已实现并完成局部验证,待人工审查**。需求卡和七项拆分已确认;本轮“开始 C2b”的授权包括第 3.1 节列明的协议/API 切换,恢复资格的后续实现仍按 C4a/C4b。C3–C5 尚未开始。每个原子变更完成后另附验证报告并等待审查。不自行提交、合并或推送。实际结果、首轮失败修复及规模偏差见[实施报告](transfer-pause-start-direction-report.md)。 ## 1. 需求卡 @@ -111,7 +111,7 @@ ## 3. 公共接口、运行时记录与数据流 -### 3.1 拟定接口变更(仍待单独许可) +### 3.1 接口变更(C2b 已获许可) ```python # server:peer 必填 @@ -188,7 +188,7 @@ relay 高水位证据按实际入队粒度计算:记录高水位、单次 enqu ## 6. 验收命令与报告要求 -以下为各阶段的定向验收命令。C1 定向回归为 **81 passed in 17.77s**。C2a 控制与进度查询回归为 **154 passed in 0.99s**,出现一项 pytest 参数化迭代器弃用告警;改为 tuple 后仅重跑受影响交叉调度用例,**64 passed in 0.62s**,无告警。另有四组真实控制 socket 的收敛证据。实际命令和覆盖边界见实施报告。其余阶段命令尚未运行,不作为已验证证据。每个原子变更运行对应最窄项,C5 再进行一次相关合并回归,不反复运行整个仓库。 +各阶段定向证据见实施报告。C1:81 passed;C2a:154 passed,修复参数化告警后受影响 64 项通过。C2b 首轮 223 passed、2 failed、1 skipped;tracking off EOF 旧行清理修复后原失败两项通过,owner 等待隔离的基础/实际连接定向检查 134 passed,既有文件/relay/恢复/crypto/async/握手/wire 回归 159 passed。另有真实逐文件夹 leg 与重新交换窗口证据。没有将单项重跑标作全量复跑;C3–C5 命令尚未运行。C5 再进行一次相关合并回归,不反复运行整个仓库。 ```bash # C1/C2a:实现后新增必要边界契约 @@ -220,4 +220,4 @@ relay 高水位证据按实际入队粒度计算:记录高水位、单次 enqu - **持久化数据模型不变**;运行时控制记录改变。查询返回 schema 不变。测试增加必要边界契约及迁移受影响断言,不降低验证强度。 - **CI/依赖/覆盖率策略不变**。不宣称本计划覆盖未运行的多平台环境、NAT、多进程共享或任意网络中断组合。 - 新功能依赖存活且可投递的控制连接;仅有数据 socket 存活但控制连接不可用时,不承诺远程 pause/start。自然关闭路径按既有机制结束旧 leg。 -- 需求卡、P01–P18 路径全集及七项原子拆分已确认;C1 已通过人工审查,C2a 已获授权并完成,待人工放行。C2b 前仍需明确许可四 token 协议、pause/start 必填 type/direction、删除 remote API、返回值与预置暂停契约,以及 resume 活跃对象返回 False。C1/C2a 均未切换生产 pause/start 解析器、协议或公共签名;本轮未创建提交。 +- 需求卡、P01–P18 路径全集及七项原子拆分已确认;C1、C2a 已通过人工审查,C2b 已按本轮授权完成协议/API 切换并完成局部验证,待人工审查。resume 活跃对象返回 False 的资格门槛仍在 C4a/C4b 实施。C2b 实际规模超出原预估,已在报告明确列为需人工接受或退回计划重拆的偏差,不自行进入 C3。本轮未创建提交。 diff --git a/docs/plans/transfer-pause-start-direction-report.md b/docs/plans/transfer-pause-start-direction-report.md index 95eb467..41866da 100644 --- a/docs/plans/transfer-pause-start-direction-report.md +++ b/docs/plans/transfer-pause-start-direction-report.md @@ -1,6 +1,6 @@ # 双向文件暂停、继续与按对象恢复 — 实施报告 -状态:需求卡和七项拆分已确认。**C1 已通过人工审查;本轮获准完成的 C2a 已实现并通过定向验证,等待人工审查;C2b–C5 未开始。** 本报告随已完成的原子变更增补,不将未实现或未运行的路径标为完成。本轮未创建提交、合并或推送。 +状态:需求卡和七项拆分已确认。**C1、C2a 已通过人工审查;C2b 已实现并完成局部验证,待人工审查;C3–C5 未开始。** 本报告随已完成的原子变更增补,不将未实现或未运行的路径标为完成。本轮未创建提交、合并或推送。 ## C1:严格解析、typed identity 与共享端点识别 @@ -123,11 +123,98 @@ C1 没有改加密入口、安全就绪、数据循环、路由占用规则、 本轮未改公开 API、生产 parser/协议、data loop、relay pump、加密门槛、恢复资格或 CI/依赖。新登记表已初始化,但生产 leg 和关闭路径尚未调用它,故不宣称暂停新行为已对外可用。C2b 必须将生产调用、发送调度与生命周期统一接入;不能保留旧控制状态或旁路。未运行 broad suite、formatter、lint 或加密/多平台验证。语言服务能力仍仅 Ruff,无 references 支持。 -待 C2a 人工审查放行,以及下节公共协议/API 许可后,才能进入 C2b。 +C2a 后续审查结论:用户已审计放行,并明确授权开始 C2b,包括下节列明的公共协议/API 切换。 -## 公共协议/API 变更许可点 +## C2b:普通收发端到端接入与协议/API 切换 -以下仍是拟定契约,C1 未实施;应在 C2b 生产切换前明确许可: +### 提交意图、接口与数据流 + +将已审查的控制状态机接入普通收发和 relay 的全部生产控制入口。本轮“开始 C2b”的授权包含计划第 3.1 节的公共协议/API 变更;旧 remote API、旧 fid parser 和独立 writer_pause 状态均移除。 + +- API → fid/type/本地角色校验 → 配置/当前控制端点归一化 → 精确 typed key(relay 使用该 peer 对应的 child fid)→ registry 串行登记 → per-leg FIFO worker → 等待对端 leg 可定位与既有安全就绪门槛 → 正常 `send_message`。接收线程只分派,不等待密钥交换。 +- S 决定与通知保持 FIFO;R 请求与确认值分开。数据 socket 建立前 S 绑定 owner,对端 R 在 startup sign 前登记;S 观察 startup 后释放初始通知门槛。普通/转发、上传/下载与 tracking off 共用入口。 +- sender loop 每个新数据块前读取预绑定状态;R 持续 recv/落盘。在途块不丢弃;start 无 seek/truncate/重建。空文件、EOF 恢复与最终 ACK 不等待不存在的下一块。 +- 加密开启时,控制发送先等待 framed readiness,再在写入入口拒绝无 framed channel 的控制帧;帧创建阶段检查 secure/frames_allowed,防止重新交换窗口回退明文。未改 plaintext allowlist,未新增 raw send 旁路。 +- relay writer 直接等待自己的控制记录,上游高/低水位请求携带 type=1、direction=1;reader 的高水位硬门槛独立保留。活动 owner 冲突仍拒绝,纯预置暂停不作为路由占用。复杂多目标路由/背压的完整验收仍属 C3。 +- 数据 owner/实际控制 socket 关闭、stale sweep 或发送失败释放记录和等待者。进度查询从活动 typed sender 记录投影到旧 upload key;持久化字段不变。 + +### 变更文件与局部止血 + +实现位于 `PyFlow/network_api/connect_tcp.py`。新增真实控制契约位于 `test/integration/network_api/test_tcp_transfer_control.py`;迁移 `test_transfer_control.py`、`test_transfer_progress_query.py`、`test_fid_routes.py`、`test_tcp_file_transfer.py` 与 `test_tcp_transfer_resume.py` 的调用/状态契约。三份 File_Transfer/TCP_Server_APIs/TCP_Client_APIs RST、变更记录、计划及本报告同步更新。 + +旧测试中直接构造 pair 暂停键/把活跃 progress 当控制 leg 的样板改为真实 typed owner;断言保留内容、最终 ACK 和清理。首次新场景发现 tracking off 的 EOF 接收恢复已成功但保留旧进度行:让接收 leg 持有既有 resume_entry 供现有完成清理,不为未跟踪的新传输创建进度行。原失败断言未放宽。 + +### 实际命令、结果与运行证据 + +首轮: + +```bash +.venv/bin/python -m pytest test/unit/network_api/test_transfer_control.py test/unit/network_api/test_transfer_progress_query.py test/unit/network_api/test_fid_routes.py test/integration/network_api/test_tcp_transfer_control.py -q +``` + +**223 passed、2 failed、1 skipped in 180.92s**。失败仅为 encrypted/async/tracking off 的 EOF 上传和下载:文件内容及最终 ACK 成功,但旧 receive progress 行未删除。plain fixture 的 re-key 用例被跳过,encrypted 两组实际运行。 + +修复旧 receive 行所有权后仅重跑失败项: + +```bash +.venv/bin/python -m pytest 'test/integration/network_api/test_tcp_transfer_control.py::test_empty_and_eof_progress_complete_with_real_ack[encrypted-async-untracked-wildcard-eof-upload]' 'test/integration/network_api/test_tcp_transfer_control.py::test_empty_and_eof_progress_complete_with_real_ack[encrypted-async-untracked-wildcard-eof-download]' -q +``` + +**2 passed in 9.19s**。不将首轮失败抹去或标成全量复跑成功。 + +已观察运行证据: + +- 真实文件 socket:普通上传/下载 × S/R 本地控制,确认后同一 socket 继续,最终 sender 返回真实 ACK 成功且文件字节一致,owner/进度/暂停键清理。 +- 同 fid 双向传输分别绑定角色;对一边 start 不影响另一边。非法/旧/缺多 token、错误 type、未知 fid 输入通过真实控制通道送达后不改变活动状态。client 配置别名与实际 peer 地址归一到同 key,含 wildcard bind。 +- receiver 快速 pause→start 在首个请求实际发送前登记相反意图;排空通知后 S/R 运行状态一致。另一个真实在途块在 pause 确认后才交给发送调用,接收端仍写入该块。 +- Plain、encrypted、encrypted+async+tracking off 三种实际配置执行控制;两组 encrypted 配置触发真实强制重新交换并持有 key publication。R pause→start 仍返回、读线程继续接受真实对端 key,安全门槛打开后 FIFO 请求/通知收敛。观测帧均含 FRAME_MAGIC 且无控制明文片段,未使用 raw 控制写入。 +- 临时标准输入脚本通过正式文件夹入口上传/下载各两项,每条在数据循环观察点执行 S pause、R start;四份文件内容一致,四条 leg 的 owner/socket 均保持,最终进度行、控制 owner 和暂停键为零。脚本退出码 0,未落盘。 + +其后为 owner 隔离补强发送等待条件:仅当前 registry 仍持有同一 state 时等待暂停键,防止旧等待者观察同 key 新 owner 的暂停。执行控制基础及 plain 同 fid 双向实际传输用例: + +```bash +.venv/bin/python -m pytest test/unit/network_api/test_transfer_control.py 'test/integration/network_api/test_tcp_transfer_control.py::test_same_fid_opposite_directions_and_invalid_wire_are_isolated[plain-alias]' -q +``` + +**134 passed in 4.12s**。 + +既有受影响路径一次相关回归: + +```bash +.venv/bin/python -m pytest test/integration/network_api/test_tcp_file_transfer.py test/integration/network_api/test_tcp_transfer_resume.py test/integration/network_api/test_crypto_tcp.py test/integration/network_api/test_tcp_async_server.py test/unit/network_api/test_transfer_handshakes.py test/unit/network_api/test_wire_lines.py -q +``` + +**159 passed in 358.02s**。包含普通文件/文件夹、relay 背压与多目标 ACK、原有断线恢复、实际控制端点识别、加密重新交换、async server、socket/FID handshake 和 wire buffer;不替代 C3/C4 新契约的路径验收。 + +### 路径对照与明确未覆盖 + +| 路径 | C2b 结论与证据边界 | +|---|---| +| P01 | 生产分派已严格使用四 token parser;真实控制连接的旧/非法/type/fid 输入及基础参数边界通过,不创建未知 wire 状态 | +| P02 | 真实同 peer/type/fid 反向普通传输独立暂停;纯状态契约覆盖不同 peer/type。复杂 relay 身份全集仍在 C3 | +| P03/P04 | 真实上传/下载,S/R 均能 pause/start,同 data socket 完成内容及最终 ACK;接收在途块继续落盘 | +| P05 | C2a 全部有限三操作 FIFO 交错契约通过;生产连接补充 R 未确认 pause→start 和 S/R 交叉,消息排空后状态一致 | +| P06 | 空文件、EOF 恢复、最终 ACK 及逐文件夹 leg 的真实内容/owner 清理证据通过 | +| P07 | 预置发送暂停在对端登记后公布;start 删除键;未知 wire 不产生预置状态,基础和实际连接均有证据 | +| P11 | 明文及实际加密、重新交换窗口通过;控制写入走安全门槛和 send_message,帧无控制明文片段。加密 relay 的复杂交叉验收仍属 C3 | +| P12 | 配置别名、concrete endpoint、wildcard 以及既有关闭 socket 身份回归通过;旧 source/target owner 全部恢复竞争仍属 C4b | +| P13 | 新控制场景覆盖 tracking off 和 encrypted async 分派,重新交换时读线程继续处理 key;原有线程式/async 回归通过 | +| P18 | 查询 schema 及活动 typed pause 投影、JSON 无控制字段、完成/关闭释放均通过;stop/config 与转发恢复竞争的完整验收在 C4b/C5 | +| P08–P10、P14–P17 | 仅复用既有相关回归,不标为新增契约已全验收;分别按 C3 和 C4a/C4b 路径清单继续 | + +没有改 CI、依赖、coverage 策略或 progress JSON schema;没有删除/跳过既有测试或放宽失败断言。本轮唯一 skip 是纯明文 fixture 不适用重新交换场景,两组加密场景均实际运行。未运行 repo-wide suite、formatter、lint、文档构建或多平台检查。 + +### 风险与审查注意 + +- **变更规模超出计划预估的 300–500 行**:单是新集成契约文件为 387 行,此外还有生产接入、旧入口删除、既有调用迁移和接口文档。此次保持一次协议生产者/消费者同步切换,未擅自拆成混用新旧协议的中间阶段。该规模偏差必须在 C2b 人工审查中明确接受,或按仓库流程退回计划重拆;不以测试通过代替放行。 +- 状态登记成功仅表示已进入控制 FIFO,不代表对端确认。控制发送失败沿既有错误/关闭机制终止会话,不重试、不降级;不承诺仅有 data socket、控制连接不可用时仍可远程控制。 +- 生产控制 FIFO 只排控制消息,不排每块文件数据。活动记录与暂停键分离;路由冲突仍检查真实 owner,复杂 relay 路由/背压、共享 source 门槛及恢复资格没有在本轮提前宣称交付。 +- 语言服务仍只有 Ruff、无 referencesProvider;公开符号引用请求返回 `-32601`,随后按调用枚举迁移。不能将该请求计为成功引用分析。 +- **C2b 待人工审查,未创建提交**。C3 及后续阶段未获本轮执行授权。 + +## 公共协议/API 变更许可记录 + +用户审查放行 C2a 并授权开始 C2b;下列协议/API 按已确认计划执行切换。恢复资格的新语义按 C4a/C4b 后续实施。 ```python # Server @@ -144,4 +231,4 @@ start_trans(fid, peer=None, *, trans_type, direction) - bool 表示活跃 leg 的操作是否登记,不表示已确认或文件成功。发送端未建连时允许精确 key 的预置 pause,返回 False;start 解除预置;非法本地 fid/type/direction 抛 ValueError。 - `resume_trans(peer_addr, fid, offset)` 保留签名,但活跃、暂停或正建连对象静默跳过并返回 False;具体资格门槛在 C4a/C4b 实现。 -需求卡和拆分的确认不在本报告中代替这一许可;未获许可前不修改公共协议/API。 +本轮 C2b 授权包含上述 pause/start 协议/API 的切换;C3–C5 保持原定分阶段审查闸门。 diff --git a/docs/source/File_Transfer/File_Transfer.rst b/docs/source/File_Transfer/File_Transfer.rst index 750d2c5..727b31e 100644 --- a/docs/source/File_Transfer/File_Transfer.rst +++ b/docs/source/File_Transfer/File_Transfer.rst @@ -537,18 +537,14 @@ i.e. 2 GB) that bounds the memory the forwarding machinery may hold in that process. When the server's buffered bytes exceed ``max_mem_buff`` it sends -``/pause_trans`` to the -forwarding client, which stops reading the source file; -once the writers drain -the buffers below the low-water mark (half the limit) the -server sends -``/start_trans`` and the upload resumes. Receiving clients -drain each chunk to -disk synchronously, so their buffered memory stays bounded -by a single chunk; -the ``/pause_trans``/``/start_trans`` handlers exist on -both sides so any side -can throttle a transfer when it buffers data. +``/pause_trans 1 1`` to the forwarding client: the server is the local +receiver of this relay leg, and the client stops reading the source file. +Once the writers drain the buffers below the low-water mark (half the limit), +the server sends ``/start_trans 1 1`` and the upload resumes on the same +socket. Receiving clients drain each chunk to disk synchronously, so their +buffered memory stays bounded by a single chunk. Ordinary and relay legs use +the same typed control handlers on both sides; an in-flight receive and write +continues while a receiver waits for sender confirmation. .. _concurrency-and-threading: @@ -763,8 +759,9 @@ The result contains ``progress_enabled`` and ``speed_enabled`` flags, a ``memory`` section, and a separate ``persisted`` section. Memory rows include the integer ``fid``, the complete upload ``receiver`` scope when applicable, the logical ``peer``, path/name, byte counts, speed, local ``active`` and -``socket_registered`` observations, and upload ``paused`` state. Uploads with -the same numeric fid but different receivers remain separate. Server relay +``socket_registered`` observations, and upload ``paused`` state projected from +the live typed sender control state. The progress schema is unchanged. Uploads +with the same numeric fid but different receivers remain separate. Server relay rows show ``originator``, all accepted ``targets`` and ``completed`` targets. Clients expose forwarded uploads through their existing upload rows; their ``relays`` section is empty, with no second recovery-metadata table. @@ -829,20 +826,40 @@ or isolation is provided. This is a local Python API, not a console/HTTP command Pausing, Reconnecting and Resuming Transfers -------------------------------------------- -An outbound transfer can be held and released with the server methods -``pause_trans(fid, peer)`` / ``start_trans(fid, peer)``; the receiving peer is -required, including when arming a transfer that has not started. The client -methods default to its connected server and reject a different explicit peer. -Remote ``/pause_trans `` / ``/start_trans `` lines use their requesting -control peer as the scope; ``pause_trans_remote(peer, fid)`` / -``start_trans_remote(peer, fid)`` send them. Their wire format is unchanged. -The leg stops before its next chunk and stays open; a leg that is paused -keeps its socket, so nothing is torn down. Every outbound transfer honours -its own fid — a plain upload as much as the upload leg of a forwarded file — -so the flow control the server uses on a relay works on any transfer. -A paused leg that belongs to a session swept at reconnect is released by -that sweep: its pause switch is cleared, its socket is closed, and the leg -ends, so a resume request queued behind its per-fid send lock can run. +The server exposes ``pause_trans(fid, peer, *, trans_type, direction)`` and +``start_trans(fid, peer, *, trans_type, direction)``. The client exposes the +same methods with ``peer=None`` defaulting to its current server; an explicit +peer may be the configured server address or its concrete control endpoint. +``trans_type`` is required: ``0`` selects an ordinary transfer and ``1`` a +relay leg. ``direction`` is also required and always describes the caller's +local role: ``0`` is the data sender and ``1`` the data receiver. The server +requires ``peer`` even when presetting a sender pause before registration. +The control identity is ``(control_peer, fid, trans_type, local_role)``; +client control peers are canonicalized to ``(client.host, client.port)`` even +when the logical forwarded target differs. + +Both methods apply the local operation and notify the peer through the existing +secure control connection. The wire commands have exactly four tokens: +``/pause_trans `` and +``/start_trans ``. The type and role use the same +values as the API; the issuer's role is opposite the receiving endpoint's +local role. There are no separate remote-control methods or one-argument wire +forms. Ordinary and relay legs use this same control path. + +The sender owns the confirmed pause state and stops before its next chunk. +A receiver's local call records a request; its confirmed state changes only +when the sender's notification arrives. Secure control sends are asynchronous +and ordered per leg, so confirmation is eventual. A receiver continues any +in-flight receive and disk write: pause does not promise an immediate freeze +of the receiving file. Start releases the same open data socket without a new +handshake, offset or seek. + +A real state change on a registered leg returns ``True``; this reports the +local operation, not a peer acknowledgement. Duplicate operations return +``False``. Presetting a pause for an exact, not-yet-active sender identity +also returns ``False`` while retaining that pause for registration. Pause state +is runtime-only and is never persisted. Reconnect cleanup releases paused +waiters, clears their state and closes the old sockets before replay. The temporary connections of a transfer are resumed after a disconnect: @@ -1120,8 +1137,7 @@ reference. - ``multiple_file_multiple_client_transfer_server_recv_client_start`` - ``diff_multiple_file_diff_multiple_client_transfer_server_recv_client_start`` - ``file_folder_transfer_server_recv_server_start_thread`` (folder receiving) -- ``pause_trans`` / ``start_trans`` (hold and release an outbound transfer) -- ``pause_trans_remote`` / ``start_trans_remote`` (ask a client to do it) +- ``pause_trans`` / ``start_trans`` (control a typed local sender or receiver leg) - ``resume_trans`` (continue one interrupted transfer, sender side) (The low-level helpers @@ -1140,8 +1156,7 @@ public but are documented for completeness.) - ``file_transfer_client_recv_server_start`` - ``file_transfer_client_recv_server_start_thread`` - ``file_folder_transfer_client_recv_server_start_thread`` -- ``pause_trans`` / ``start_trans`` (hold and release an outbound transfer) -- ``pause_trans_remote`` / ``start_trans_remote`` (ask the server to do it) +- ``pause_trans`` / ``start_trans`` (control a typed local sender or receiver leg) - ``resume_trans`` (continue one interrupted transfer, sender side) (The low-level helpers are documented but not part of the diff --git a/docs/source/Network_APIs/TCP_Client_APIs.rst b/docs/source/Network_APIs/TCP_Client_APIs.rst index 19d65be..9128ffc 100644 --- a/docs/source/Network_APIs/TCP_Client_APIs.rst +++ b/docs/source/Network_APIs/TCP_Client_APIs.rst @@ -297,9 +297,13 @@ commands sent by the server, such as: ``/crypto_key_exchange_ack``, ``/crypto_reject``, ``/crypto_pub_key``, ``/crypto_ready``: the encrypted-channel handshake messages; a ``/crypto_mode`` mismatch closes the connection. -- ``/pause_trans``, ``/start_trans`` and ``/forward_error ``: - transfer control and FID-scoped forwarding failures. Forward uploads use - the common ``/server_file_transfer_port`` reply; no ``/forward_upload`` line. +- ``/pause_trans ``, + ``/start_trans `` and + ``/forward_error ``: typed transfer control and FID-scoped + forwarding failures. The control lines require exactly four tokens. Type is + ``0`` for ordinary transfers or ``1`` for relay legs; issuer role is ``0`` + for the data sender or ``1`` for the data receiver. Forward uploads use the + common ``/server_file_transfer_port`` reply; no ``/forward_upload`` line. - ``/resume_trans ``: the sole resume command, with shell-quoted tuple endpoints. Only an origin matching this control connection's own identity may resume a local upload. The existing upload row @@ -840,13 +844,29 @@ And the low-level send mode function is: def file_transfer_mode( self, filename, server_address, server_port, client_port, - control_socket=None, crypto=None, fid=None, peer=None, resume_offset=0) - -``((host, port), fid)`` keys the leg in ``file_upload_progress``. The -``/pause_trans`` / ``/start_trans`` lines and local methods address that server -scope; an explicit local ``peer`` must be the server, not the logical target. -The value's ``peer`` is the original receiver; ``resume_offset`` continues -the interrupted file from the byte the receiver already holds. + control_socket=None, crypto=None, fid=None, peer=None, resume_offset=0, + trans_type=0) + +``((host, port), fid)`` keys the leg in ``file_upload_progress``. Ordinary +senders use ``trans_type=0``; forwarding callers pass ``trans_type=1``. +``pause_trans(fid, peer=None, *, trans_type, direction)`` and +``start_trans(fid, peer=None, *, trans_type, direction)`` require both keyword +arguments. ``direction`` describes the local data role: ``0`` sender or ``1`` +receiver. These methods apply local control and notify the server. An omitted +``peer`` selects the current server; an explicit peer may use its configured +address or concrete control endpoint, not the logical forwarded target. Control +identity is canonicalized to ``((client.host, client.port), fid, trans_type, +local_role)`` independently of the progress row's logical receiver. + +The sender owns confirmed pause state. A receiver records its local request +and waits for an eventual sender notification; secure sends are asynchronous +and ordered per leg. In-flight receives and disk writes continue. Start uses +the same data socket without a new handshake or seek. A changed registered +operation returns ``True``, not a peer ACK; duplicates and preset sender pauses +before registration return ``False``. Pause is runtime-only. See +:ref:`transfer-pause-and-reconnect` for details. The upload value's ``peer`` +is the original receiver; ``resume_offset`` continues the interrupted file from +the byte the receiver already holds. For a forwarded upload, the server forwards the existing final data-ACK marker after the full input stream and all accepted target ACKs complete. The source @@ -992,8 +1012,8 @@ is as follows: 5.1. The transfer pause and reconnect APIs (see :ref:`transfer-pause-and-reconnect`): - - `pause_trans` / `start_trans` - - `pause_trans_remote` / `start_trans_remote` + - `pause_trans(fid, peer=None, *, trans_type, direction)` / + `start_trans(fid, peer=None, *, trans_type, direction)` - `resume_trans` 6. The client console commands (interactive mode): diff --git a/docs/source/Network_APIs/TCP_Server_APIs.rst b/docs/source/Network_APIs/TCP_Server_APIs.rst index 6b8e837..dbe164d 100644 --- a/docs/source/Network_APIs/TCP_Server_APIs.rst +++ b/docs/source/Network_APIs/TCP_Server_APIs.rst @@ -672,10 +672,19 @@ Built-in client commands include: - ``/crypto_mode <0|1>``, ``/crypto_pub_key``, ``/crypto_pub_key_request``: internal handshake messages of the encrypted channel. - ``/forward_item``, ``/forward_send_msg``, ``/pause_trans``, ``/start_trans``: - internal forwarding/transfer-control messages. ``/pause_trans `` and - ``/start_trans `` hold and release the outbound transfer to the requesting - peer. Local calls require ``pause_trans(fid, peer)`` / ``start_trans(fid, peer)``; - the receiver scope is required even when arming a future transfer. + internal forwarding/transfer-control messages. Control lines are strictly + ``/pause_trans `` and + ``/start_trans ``. Local calls require + ``pause_trans(fid, peer, *, trans_type, direction)`` / + ``start_trans(fid, peer, *, trans_type, direction)``. ``trans_type`` is + ``0`` for ordinary transfers or ``1`` for relay legs; ``direction`` is the + local data role (``0`` sender, ``1`` receiver). The wire role describes the + issuer. Both methods update local control and notify the peer; sender state + is authoritative and receiver confirmation is eventual. An in-flight receive + and write continues, and start uses the same data socket. A changed registered + operation returns ``True``, not a peer ACK; duplicates and a preset sender + pause before registration return ``False``. ``peer`` is always required. + See :ref:`transfer-pause-and-reconnect` for control identity and cleanup. Forwarded requests carry a source-allocated ``fid=``. A new upload omits ``resume=``; replay includes ``resume=``, including zero, and must match an existing route before the Server reuses its upstream and @@ -1175,8 +1184,8 @@ are as follows: 5.1. The transfer pause and reconnect APIs (see :ref:`transfer-pause-and-reconnect`): - - `pause_trans` / `start_trans` - - `pause_trans_remote` / `start_trans_remote` + - `pause_trans(fid, peer, *, trans_type, direction)` / + `start_trans(fid, peer, *, trans_type, direction)` - `resume_trans` 6. The server console commands: diff --git a/docs/source/changes/transfer-fid-routes.md b/docs/source/changes/transfer-fid-routes.md index 82b8584..1e6f2a6 100644 --- a/docs/source/changes/transfer-fid-routes.md +++ b/docs/source/changes/transfer-fid-routes.md @@ -355,3 +355,33 @@ file preservation. Runtime evidence and explicit exclusions are recorded in - Production leg registration, pause/start API and protocol cutover, secure dispatch, data-loop integration and real-file control remain at the C2b gate. +## Transfer control C2b: unified bidirectional production control + +- Public pause/start now require keyword-only `trans_type` (0 ordinary, + 1 forwarded) and `direction` (0 local sender, 1 local receiver). The wire is + strictly `/pause_trans ` or its start equivalent. + The old remote-only APIs and fid-only parser are removed; all production + callers and API documentation use the unified entry. +- Ordinary and relay legs bind actual control sockets and data-socket owners + to typed control records independently of progress tracking. Per-leg FIFO + control workers wait for peer leg registration and existing crypto readiness + before calling `send_message`; control readers never wait for their own key + exchange. Control frames cannot fall back to plaintext while encryption is + unavailable, including a re-exchange between readiness and frame creation. +- Send loops inspect their bound pause state before each new block. Receivers + continue draining and writing in-flight data. Start retains the same socket; + empty files, EOF replay and final ACKs do not wait on a nonexistent next block. + Disabled tracking creates no new progress rows; a resumed receiver retains + ownership of its existing row so successful EOF confirmation removes it. +- Relay writers use the same control registry; high/low-water requests use + type 1 and the local receiver role. The reader's buffer gate stays separate + from control state. Progress queries project active typed sender records onto + the existing upload rows, and owner/session cleanup releases controls. +- Runtime verification covered real upload/download control and encrypted + re-exchange. The first targeted run found two untracked EOF cleanup failures; + both passed after the ownership fix. Existing affected regressions passed + 159 tests, and the owner-isolation check passed 134. Full commands, the one + plaintext re-key skip and review-size deviation are in the implementation + report. Complex multi-target routing/backpressure acceptance and object-level + resume eligibility retain their C3/C4 review gates. + diff --git a/test/integration/network_api/test_tcp_file_transfer.py b/test/integration/network_api/test_tcp_file_transfer.py index 0e39754..d1b2420 100644 --- a/test/integration/network_api/test_tcp_file_transfer.py +++ b/test/integration/network_api/test_tcp_file_transfer.py @@ -904,11 +904,12 @@ def test_file_progress_and_speed_are_tracked(pair, tmp_path): server_port, _stamp = request_transfer_listener(client, server, f"/file {src} {fid}") - assert client.pause_trans(fid) is False # armed before the leg exists + assert client.pause_trans(fid, trans_type=0, direction=0) is False # armed before the leg exists sender = threading.Thread( target=client.file_transfer_mode, args=(str(src), "127.0.0.1", server_port, 0), - kwargs={"fid": fid, "peer": (server.host, server.port)}, + kwargs={"fid": fid, "peer": (server.host, server.port), + "control_socket": client.client_socket, "crypto": _stamp}, daemon=True, ) sender.start() @@ -929,7 +930,7 @@ def test_file_progress_and_speed_are_tracked(pair, tmp_path): assert recv_entry[4] == client.client_socket.getsockname() assert upload_entry[4] == (server.host, server.port) finally: - client.start_trans(fid) + client.start_trans(fid, trans_type=0, direction=0) sender.join(timeout=15) assert not sender.is_alive(), "the upload did not finish" @@ -966,11 +967,12 @@ def test_download_progress_and_speed_are_tracked(pair, tmp_path): server_port, _stamp = request_transfer_listener(server, client, f"/file {src} {fid}") - assert server.pause_trans(fid, receiver) is False # armed before the leg exists + assert server.pause_trans(fid, receiver, trans_type=0, direction=0) is False # armed before the leg exists sender = threading.Thread( target=server.file_transfer_mode, args=(str(src), "127.0.0.1", server_port, 0), - kwargs={"fid": fid, "peer": receiver}, + kwargs={"fid": fid, "peer": receiver, + "control_socket": server.clients[receiver]["socket"], "crypto": _stamp}, daemon=True, ) sender.start() @@ -990,7 +992,7 @@ def test_download_progress_and_speed_are_tracked(pair, tmp_path): assert recv_entry[4] == (server.host, server.port) assert upload_entry[4] == client.client_socket.getsockname() finally: - server.start_trans(fid, receiver) + server.start_trans(fid, receiver, trans_type=0, direction=0) sender.join(timeout=15) assert not sender.is_alive(), "the download did not finish" @@ -1047,11 +1049,12 @@ def test_file_progress_and_speed_can_be_disabled(tmp_path): server_port, _stamp = request_transfer_listener(client, server, f"/file {src} {fid}") - client.pause_trans(fid) # the pause works with tracking off too + client.pause_trans(fid, trans_type=0, direction=0) # the pause works with tracking off too sender = threading.Thread( target=client.file_transfer_mode, args=(str(src), "127.0.0.1", server_port, 0), - kwargs={"fid": fid, "peer": (server.host, server.port)}, + kwargs={"fid": fid, "peer": (server.host, server.port), + "control_socket": client.client_socket, "crypto": _stamp}, daemon=True, ) sender.start() @@ -1064,7 +1067,7 @@ def test_file_progress_and_speed_can_be_disabled(tmp_path): assert server.file_recv_progress == {} assert client.file_upload_progress == {} finally: - client.start_trans(fid) + client.start_trans(fid, trans_type=0, direction=0) sender.join(timeout=15) assert not sender.is_alive(), "the upload did not finish" diff --git a/test/integration/network_api/test_tcp_transfer_control.py b/test/integration/network_api/test_tcp_transfer_control.py new file mode 100644 index 0000000..b3d1449 --- /dev/null +++ b/test/integration/network_api/test_tcp_transfer_control.py @@ -0,0 +1,387 @@ +"""Typed live control over real ordinary transfer sockets and secure channels.""" + +import os +import shlex +import threading +from pathlib import Path + +import pytest +from helpers import free_port, isolate_instance_files, request_transfer_listener, server_ready, wait_until + +from PyFlow.network_api import connect_tcp +from PyFlow.network_api.connect_tcp import TCP_Client_Base, TCP_Server_Base + + +@pytest.fixture(params=[ + (False, False, True, "127.0.0.1", "localhost"), + (True, False, True, "127.0.0.1", "127.0.0.1"), + (True, True, False, "0.0.0.0", "0.0.0.0"), +], ids=["plain-alias", "encrypted", "encrypted-async-untracked-wildcard"]) +def channel(request, tmp_path, monkeypatch): + encrypted, asynchronous, tracked, bind_host, configured_host = request.param + if encrypted: + from PyFlow.network_api import rsa_crypto + try: + rsa_crypto.load_library() + except rsa_crypto.CryptoLibraryError: + pytest.skip("crypto library unavailable") + options = dict(is_extend_command=True, is_input_command_in_console=False, + is_enable_encrypto=encrypted, is_print_log=False, + is_enable_file_transfer_progress_bar=tracked) + server = TCP_Server_Base(host=bind_host, port=free_port(), + is_asynic_clients_io=asynchronous, **options) + client = TCP_Client_Base(host=configured_host, port=server.port, + client_host="127.0.0.1", **options) + workers, releases = [], [] + real_start = threading.Thread.start + + def start(worker, *args, **kwargs): + result = real_start(worker, *args, **kwargs) + workers.append(worker) + return result + + monkeypatch.setattr(threading.Thread, "start", start) + for name, owner in (("server", server), ("client", client)): + isolate_instance_files(owner, tmp_path, name) + destination = tmp_path / name + destination.mkdir() + owner.file_transfer_dir = str(destination) + if encrypted: + crypto = owner.crypto + crypto.pvt_key_dir = str(tmp_path / f"{name}_private") + crypto.pub_key_dir = str(tmp_path / f"{name}_public") + crypto.ssh_dir = str(tmp_path / "ssh") + crypto.registry_path = os.path.join(crypto.pub_key_dir, "pub_key.json") + for directory in (crypto.pvt_key_dir, crypto.pub_key_dir, crypto.ssh_dir): + os.makedirs(directory, exist_ok=True) + try: + threading.Thread(target=server.start_TCP_Server, daemon=True).start() + assert server_ready(server) + assert client.connect() + peer = client.client_socket.getsockname() + assert wait_until(lambda: peer in server.clients) + if encrypted: + assert wait_until(lambda: client.client_socket in client._encrypted_sockets + and server.clients[peer]["socket"] in server._encrypted_sockets, + timeout=20) + yield server, client, releases + finally: + for release in releases: + release.set() + client.close() + server.stop() + for worker in workers: + worker.join(timeout=10) + assert not any(worker.is_alive() for worker in workers) + + +def _leg(channel, tmp_path, monkeypatch, server_sends, *, fid=720, offset=0, payload=None): + server, client, releases = channel + sender, receiver = (server, client) if server_sends else (client, server) + peer = client.client_socket.getsockname() + control_peer = peer if server_sends else (client.host, client.port) + receiver_peer = (client.host, client.port) if server_sends else peer + control = server.clients[peer]["socket"] if server_sends else client.client_socket + source = tmp_path / ("download.bin" if server_sends else "upload.bin") + payload = os.urandom(128 * 1024 + 13) if payload is None else payload + source.write_bytes(payload) + output = Path(receiver.file_transfer_dir) / source.name + if offset: + output.write_bytes(payload[:offset]) + origin = client.client_socket.getpeername() if server_sends else peer + receiver.file_recv_progress[fid] = [offset, len(payload), None, str(output), origin] + sender_key, receiver_key = (control_peer, fid, 0, 0), (receiver_peer, fid, 0, 1) + assert sender.pause_trans(fid, control_peer, trans_type=0, direction=0) is False + port, stamp = request_transfer_listener(sender, receiver, f"/file {shlex.quote(str(source))} {fid}") + entered, release = threading.Event(), threading.Event() + releases.append(release) + real_wait = connect_tcp._wait_transfer_control + + def hold(instance, state, leg_socket): + if instance is sender and state is not None and state["key"] == sender_key: + entered.set() + assert release.wait(timeout=20), "body gate was not released" + return real_wait(instance, state, leg_socket) + + monkeypatch.setattr(connect_tcp, "_wait_transfer_control", hold) + if offset == len(payload): + real_send = receiver.send_message + + def hold_ack(sock, message, is_send_raw=False): + if message == receiver.server_received_file_data_sign: + entered.set() + assert release.wait(timeout=20), "final ACK gate was not released" + return real_send(sock, message, is_send_raw=is_send_raw) + + monkeypatch.setattr(receiver, "send_message", hold_ack) + result = {} + + def send(): + result["ack"] = sender.file_transfer_mode( + str(source), "127.0.0.1", port, 0, control_socket=control, + crypto=stamp, fid=fid, peer=control_peer, resume_offset=offset, + ) + + worker = threading.Thread(target=send, daemon=True) + worker.start() + assert wait_until(lambda: sender_key in sender._transfer_controls._legs + and receiver_key in receiver._transfer_controls._legs, timeout=15) + states = (sender._transfer_controls._legs[sender_key], receiver._transfer_controls._legs[receiver_key]) + assert wait_until(lambda: all(state["confirmed_state"] for state in states)) + assert entered.wait(timeout=10) + return sender, receiver, states, release, worker, result, output, payload + + +def _control(owner, state, paused): + peer, fid, trans_type, direction = state["key"] + return (owner.pause_trans if paused else owner.start_trans)( + fid, peer, trans_type=trans_type, direction=direction, + ) + + +def _confirmed(states, paused): + assert wait_until(lambda: all(state["confirmed_state"] is paused for state in states), timeout=10) + + +def _complete(leg): + sender, receiver, states, release, worker, result, output, payload = leg + release.set() + worker.join(timeout=15) + assert not worker.is_alive() + assert result == {"ack": True}, "sender must consume the real final ACK" + assert output.read_bytes() == payload + assert wait_until(lambda: all(state["key"] not in owner._transfer_controls._legs + for owner, state in zip((sender, receiver), states))) + fid = states[0]["key"][1] + assert (states[0]["key"][0], fid) not in sender.file_upload_progress + assert fid not in receiver.file_recv_progress + assert states[0]["key"] not in sender._transfer_pause + assert states[1]["key"] not in receiver._transfer_pause + + +@pytest.mark.parametrize("server_sends", [False, True], ids=["upload", "download"]) +@pytest.mark.parametrize("receiver_initiates", [False, True], ids=["sender", "receiver"]) +def test_pause_start_preserves_the_data_socket_and_final_ack( + channel, tmp_path, monkeypatch, server_sends, receiver_initiates +): + leg = _leg(channel, tmp_path, monkeypatch, server_sends) + sender, receiver, states, release, worker, result, output, payload = leg + data_key = states[0]["key"][:2] + data_socket = sender._active_transfer_sockets[data_key] + owner, state = (receiver, states[1]) if receiver_initiates else (sender, states[0]) + assert _control(owner, state, False) is True + _confirmed(states, False) + assert _control(owner, state, False) is False + assert _control(owner, state, True) is True + _confirmed(states, True) + assert _control(owner, state, True) is False + assert sender._transfer_pause == {states[0]["key"]: True} + assert not receiver._transfer_pause + assert sender._active_transfer_sockets[data_key] is data_socket + assert worker.is_alive() and result == {} + assert not output.exists() or output.stat().st_size == 0 + rows = sender.get_transfer_progress(include_persisted=False)["memory"]["uploading"] + if sender.is_enable_file_transfer_progress_bar: + assert len(rows) == 1 and rows[0]["paused"] is True + else: + assert rows == [] and receiver.file_recv_progress == {} + # Release the observer gate while the actual sender pause remains asserted. + release.set() + assert _control(owner, state, False) is True + _complete(leg) + + +@pytest.mark.parametrize("server_sends", [False, True], ids=["upload", "download"]) +def test_receiver_unconfirmed_reverse_intent_and_cross_commands( + channel, tmp_path, monkeypatch, server_sends +): + leg = _leg(channel, tmp_path, monkeypatch, server_sends) + sender, receiver, states, release, *_ = leg + assert _control(sender, states[0], False) + _confirmed(states, False) + wire_entered, wire_release = threading.Event(), threading.Event() + channel[2].append(wire_release) + real_send = receiver.send_message + pause = f"/pause_trans {states[1]['key'][1]} 0 1" + + def hold_request(sock, message, is_send_raw=False): + if message == pause: + wire_entered.set() + assert wire_release.wait(timeout=10) + return real_send(sock, message, is_send_raw=is_send_raw) + + monkeypatch.setattr(receiver, "send_message", hold_request) + assert _control(receiver, states[1], True) + assert wire_entered.wait(timeout=10) + assert states[1]["confirmed_state"] is False + assert states[1]["last_requested_state"] is True + assert _control(receiver, states[1], False) + assert states[1]["last_requested_state"] is False + notifications = [] + sender.add_send_message_listener(lambda _peer, message: notifications.append(message)) + wire_release.set() + # The last sender notification proves both receiver requests were processed. + assert wait_until(lambda: f"/start_trans {states[0]['key'][1]} 0 0" in notifications) + _confirmed(states, False) + assert _control(sender, states[0], True) + _confirmed(states, True) + assert states[1]["last_requested_state"] is False + assert _control(receiver, states[1], False) + _confirmed(states, False) + _complete(leg) + + +def test_same_fid_opposite_directions_and_invalid_wire_are_isolated(channel, tmp_path, monkeypatch): + upload = _leg(channel, tmp_path, monkeypatch, False) + download = _leg(channel, tmp_path, monkeypatch, True) + server, client, _ = channel + peer = client.client_socket.getsockname() + for owner, sock, states in ((client, client.client_socket, download[2]), + (server, server.clients[peer]["socket"], upload[2])): + keys = set(owner._transfer_controls._legs) + for command in ("/pause_trans 720", "/start_trans 720 0", "/start_trans 720 0 0 extra", + "/start_trans 720 2 1", "/start_trans -1 0 1", "/start_trans 720 1 1", + "/start_trans 999 0 1"): + assert owner.send_message(sock, command) + remote = server if owner is client else client + barrier = threading.Event() + marker = "/control_test_barrier" + remote.add_message_listener(lambda _peer, message: barrier.set() if message == marker else None) + assert owner.send_message(sock, marker) + assert barrier.wait(timeout=10) + assert set(owner._transfer_controls._legs) == keys + assert all(state["confirmed_state"] for state in states) + assert _control(upload[0], upload[2][0], False) + _complete(upload) + assert all(state["confirmed_state"] for state in download[2]) + assert download[4].is_alive() + # Both configured aliases and the concrete control endpoint address one key. + concrete = client.client_socket.getpeername() + assert client.start_trans(720, concrete, trans_type=0, direction=1) + _complete(download) + + +@pytest.mark.parametrize("server_sends", [False, True], ids=["upload", "download"]) +@pytest.mark.parametrize("payload", [b"", b"already received"], ids=["empty", "eof"]) +def test_empty_and_eof_progress_complete_with_real_ack(channel, tmp_path, monkeypatch, server_sends, payload): + # EOF resume needs its durable receiver row even when tracking is disabled. + leg = _leg(channel, tmp_path, monkeypatch, server_sends, offset=len(payload), payload=payload) + sender, receiver, states, _, worker, result, *_ = leg + assert worker.is_alive() and result == {} + if sender.is_enable_file_transfer_progress_bar: + row = sender.file_upload_progress[states[0]["key"][:2]] + assert row[:2] == [len(payload), len(payload)] + assert receiver.file_recv_progress[states[1]["key"][1]][:2] == [len(payload), len(payload)] + assert _control(sender, states[0], False) + _confirmed(states, False) + _complete(leg) + + +@pytest.mark.parametrize("server_sends", [False, True], ids=["upload", "download"]) +def test_receiver_keeps_writing_inflight_data_after_confirmed_pause( + channel, tmp_path, monkeypatch, server_sends +): + leg = _leg(channel, tmp_path, monkeypatch, server_sends) + sender, receiver, states, body_release, _, _, output, _ = leg + inflight, send_release = threading.Event(), threading.Event() + channel[2].append(send_release) + real_send = sender.send_message + + def hold_first_chunk(sock, message, is_send_raw=False): + if sock is states[0]["owner"] and isinstance(message, bytes) and not inflight.is_set(): + inflight.set() + assert send_release.wait(timeout=10) + return real_send(sock, message, is_send_raw=is_send_raw) + + monkeypatch.setattr(sender, "send_message", hold_first_chunk) + assert _control(sender, states[0], False) + _confirmed(states, False) + body_release.set() + assert inflight.wait(timeout=10) + assert _control(receiver, states[1], True) + _confirmed(states, True) + send_release.set() + assert wait_until(lambda: output.exists() and output.stat().st_size > 0), ( + "receiver pause blocked a chunk already admitted by the sender" + ) + assert sender._transfer_pause == {states[0]["key"]: True} + assert states[1]["key"] not in receiver._transfer_pause + assert _control(receiver, states[1], False) + _complete(leg) + + +def test_receiver_pause_start_waits_for_real_rekey_without_blocking_key_reader( + channel, tmp_path, monkeypatch +): + server, client, releases = channel + if not client.is_enable_encrypto: + pytest.skip("re-key requires the encrypted fixture variants") + leg = _leg(channel, tmp_path, monkeypatch, False) + sender, receiver, states, *_ = leg + assert _control(sender, states[0], False) + _confirmed(states, False) + peer = client.client_socket.getsockname() + control = server.clients[peer]["socket"] + channels = (client._channels[client.client_socket], server._channels[control]) + nonce = client._crypto_my_nonce + key_held, key_release, requested = (threading.Event() for _ in range(3)) + releases.append(key_release) + real_push = server._crypto_push_pub_to_client + wire, control_writes, notifications = [], [], [] + + def hold_key(sock, address): + key_held.set() + assert key_release.wait(timeout=20), "re-key publication was not released" + return real_push(sock, address) + + monkeypatch.setattr(server, "_crypto_push_pub_to_client", hold_key) + for secure in channels: + real_sendall = secure._sendall + + def observe_frame(data, sendall=real_sendall): + wire.append(bytes(data)) + return sendall(data) + + monkeypatch.setattr(secure, "_sendall", observe_frame) + for owner in (server, client): + real_send = owner.send_message + + def observe_control(sock, message, is_send_raw=False, send=real_send): + if isinstance(message, str) and message.startswith(("/pause_trans ", "/start_trans ")): + control_writes.append((message, is_send_raw)) + return send(sock, message, is_send_raw=is_send_raw) + + monkeypatch.setattr(owner, "send_message", observe_control) + receiver.add_message_listener(lambda _peer, message: notifications.append(message)) + exchange = threading.Thread(target=client._crypto_exchange_thread, + kwargs={"force": True}, daemon=True) + exchange.start() + assert key_held.wait(timeout=10) + assert wait_until(lambda: all(not secure.frames_allowed.is_set() for secure in channels)) + results = [] + + def request_both(): + results.extend((_control(receiver, states[1], True), _control(receiver, states[1], False))) + requested.set() + + threading.Thread(target=request_both, daemon=True).start() + assert requested.wait(timeout=5), "public controls blocked on re-key readiness" + assert results == [True, True] + assert states[1]["confirmed_state"] is False and states[1]["last_requested_state"] is False + # The reader must still accept the client's real key while control writes wait. + assert wait_until(lambda: server._crypto_state[peer].get("peer_pub_ok") is True, timeout=15) + assert not control_writes + key_release.set() + exchange.join(timeout=20) + assert not exchange.is_alive() and client.running + assert client._crypto_my_nonce != nonce + assert wait_until(lambda: all(secure.frames_allowed.is_set() for secure in channels), timeout=15) + assert wait_until(lambda: f"/start_trans {states[0]['key'][1]} 0 0" in notifications) + _confirmed(states, False) + assert [line for line, _raw in control_writes if line.endswith(" 0 1")] == [ + f"/pause_trans {states[1]['key'][1]} 0 1", f"/start_trans {states[1]['key'][1]} 0 1", + ] + assert control_writes and not any(raw for _line, raw in control_writes) + assert wire and all(data.startswith(connect_tcp.FRAME_MAGIC) for data in wire) + assert not any(b"/pause_trans" in data or b"/start_trans" in data for data in wire) + _complete(leg) diff --git a/test/integration/network_api/test_tcp_transfer_resume.py b/test/integration/network_api/test_tcp_transfer_resume.py index 7bde561..f4e34e4 100644 --- a/test/integration/network_api/test_tcp_transfer_resume.py +++ b/test/integration/network_api/test_tcp_transfer_resume.py @@ -26,6 +26,7 @@ wait_until, ) +from PyFlow.network_api import connect_tcp from PyFlow.network_api.connect_tcp import ( TRANSFER_SIGN_BUFFER_LIMIT, TCP_Client_Base, @@ -272,7 +273,7 @@ def test_equal_server_upload_fids_are_isolated_by_receiver(tmp_path): sources.append(src) payloads.append(payload) outputs.append(recv_dir / src.name) - assert server.pause_trans(fid, receiver) is False + assert server.pause_trans(fid, receiver, trans_type=0, direction=0) is False results[receiver] = request_transfer_listener( server, client, f"/file {shlex.quote(str(src))} {fid}" ) @@ -308,7 +309,7 @@ def send(receiver, src): sockets = [server._active_transfer_sockets[key] for key in keys] assert sockets[0] is not sockets[1] assert all(key in server._active_transfer_fids for key in keys) - assert server.pause_trans(fid, receivers[0]) is True + assert server.pause_trans(fid, receivers[0], trans_type=0, direction=0) is False assert server._drop_stale_transfers(receivers[0]) == 1 assert sockets[0].fileno() == -1 @@ -319,18 +320,18 @@ def send(receiver, src): # Release only the dead leg's waiter and let its real cleanup finish. # If start/pause or cleanup is fid-only, the other leg now sends or dies. - server.start_trans(fid, receivers[0]) + server.start_trans(fid, receivers[0], trans_type=0, direction=0) senders[0].join(timeout=15) assert not senders[0].is_alive(), "the cleared upload did not stop" assert results[receivers[0]] is False assert server.file_upload_progress[keys[1]] is rows[1] assert rows[1][0] == 0 assert clients[1].file_recv_progress[fid][0] == 0 - assert server._transfer_pause[keys[1]] is True + assert server._transfer_pause[(*keys[1], 0, 0)] is True assert server._active_transfer_sockets[keys[1]] is sockets[1] assert senders[1].is_alive() - assert server.start_trans(fid, receivers[1]) is True + assert server.start_trans(fid, receivers[1], trans_type=0, direction=0) is True senders[1].join(timeout=20) assert not senders[1].is_alive(), "the unaffected receiver did not finish" assert results[receivers[1]] is True @@ -342,7 +343,7 @@ def send(receiver, src): assert keys[1] not in server._active_transfer_fids finally: for receiver in receivers: - server.start_trans(fid, receiver) + server.start_trans(fid, receiver, trans_type=0, direction=0) for client in clients: client.close() server.stop() @@ -423,7 +424,12 @@ def test_equal_inbound_and_outbound_fids_cleanup_only_their_own_sockets(tmp_path ) instance._register_transfer_socket(fid, inbound) instance._register_transfer_socket(upload_key, outbound) - assert instance.pause_trans(fid, receiver) is True + control = (instance.clients[receiver]["socket"] if instance is server + else client.client_socket) + control_key = (receiver, fid, 1, 0) + state = instance._transfer_controls.register(control_key, control, outbound) + assert state is not None + assert instance.pause_trans(fid, receiver, trans_type=1, direction=0) is True assert len(recv_entry) == len(upload_entry) == 5 assert upload_entry[4] == logical_peer @@ -437,7 +443,8 @@ def test_equal_inbound_and_outbound_fids_cleanup_only_their_own_sockets(tmp_path assert instance.file_upload_progress[upload_key] is upload_entry assert upload_key in instance._active_transfer_fids assert instance._active_transfer_sockets[upload_key] is outbound - assert instance._transfer_pause[upload_key] is True + assert instance._transfer_pause[control_key] is True + assert instance._transfer_controls._legs[control_key] is state outbound.sendall(b"x") assert outbound_remote.recv(1) == b"x" @@ -452,7 +459,8 @@ def test_equal_inbound_and_outbound_fids_cleanup_only_their_own_sockets(tmp_path ) instance._release_transfer_socket(upload_key, outbound) assert upload_key not in instance.file_upload_progress - instance.start_trans(fid, receiver) + instance.start_trans(fid, receiver, trans_type=1, direction=0) + instance._transfer_controls.release(state) finally: for sock in sockets: sock.close() @@ -485,11 +493,12 @@ def test_paused_transfer_is_persisted_when_the_connection_drops(tmp_path): transfer_port, _stamp = request_transfer_listener(client, server, f"/file {src} {fid}") - client.pause_trans(fid) # hold the leg before its first chunk + client.pause_trans(fid, trans_type=0, direction=0) # hold the leg before its first chunk sender = threading.Thread( target=client.file_transfer_mode, args=(str(src), "127.0.0.1", transfer_port, 0), - kwargs={"fid": fid, "peer": (server.host, server.port)}, + kwargs={"fid": fid, "peer": (server.host, server.port), + "control_socket": client.client_socket, "crypto": _stamp}, daemon=True, ) sender.start() @@ -519,7 +528,7 @@ def test_paused_transfer_is_persisted_when_the_connection_drops(tmp_path): assert entry[3] == str(server_recv / "payload.bin") assert entry[4] == list(client.client_socket.getsockname()) - client.start_trans(fid) # release the paused leg so the test can end + client.start_trans(fid, trans_type=0, direction=0) # release the paused leg so the test can end sender.join(timeout=10) finally: if client is not None: @@ -571,11 +580,12 @@ def test_upload_resumes_after_a_reconnect(tmp_path): client, server, f"/file {shlex.quote(str(src))} {fid}" ) - client.pause_trans(fid) # freeze the leg, then give it a partial file + client.pause_trans(fid, trans_type=0, direction=0) # freeze the leg, then give it a partial file sender = threading.Thread( target=client.file_transfer_mode, args=(str(src), "127.0.0.1", transfer_port, 0), - kwargs={"fid": fid, "peer": (server.host, server.port)}, + kwargs={"fid": fid, "peer": (server.host, server.port), + "control_socket": client.client_socket, "crypto": _stamp}, daemon=True, ) sender.start() @@ -617,7 +627,7 @@ def got(): lambda: ((client.host, client.port), fid) not in client.file_upload_progress, timeout=10, ) - client.start_trans(fid) + client.start_trans(fid, trans_type=0, direction=0) sender.join(timeout=10) finally: if client is not None: @@ -937,6 +947,7 @@ def _watch_sign_capacity(monkeypatch, sender, receiver, overflow, capacity_handl errors = [] compactions = [] real_feed = _TransferSignBuffer.feed + real_wait = connect_tcp._wait_transfer_control real_scan = _TransferSignBuffer._scan_pending_locked real_send = receiver.send_message @@ -972,14 +983,16 @@ def inject_after_header(sock, message, is_send_raw=False): pass # the sender may already have rejected an overlong line return written - def hold_body(_key, leg_socket=None): - body_held.set() - assert capacity_handled.wait(timeout=10), "the buffer never reached or rejected its limit" + def hold_body(instance, state, leg_socket): + if instance is sender: + body_held.set() + assert capacity_handled.wait(timeout=10), "the buffer never reached or rejected its limit" + return real_wait(instance, state, leg_socket) monkeypatch.setattr(_TransferSignBuffer, "feed", observe_feed) monkeypatch.setattr(_TransferSignBuffer, "_scan_pending_locked", observe_scan) monkeypatch.setattr(receiver, "send_message", inject_after_header) - monkeypatch.setattr(sender, "_wait_transfer_paused", hold_body) + monkeypatch.setattr(connect_tcp, "_wait_transfer_control", hold_body) return retained, errors, compactions @pytest.mark.parametrize("server_sends", [False, True], ids=["upload", "download"]) @@ -1999,7 +2012,7 @@ def hold_second_writer(target, kind, rel_dir, fname, originator_addr, tfid, destination_path=None): if target == targets[1]: held["fid"] = tfid - held["paused"] = server.pause_trans(tfid, target) + held["paused"] = server.pause_trans(tfid, target, trans_type=1, direction=0) return real_forward_item_to( target, kind, rel_dir, fname, originator_addr, tfid, destination_path ) @@ -2019,7 +2032,7 @@ def hold_second_writer(target, kind, rel_dir, fname, originator_addr, tfid, ), "the unpaused target did not finish" assert outputs[0].read_bytes() == payload assert wait_until(lambda: not clients[1].file_recv_progress, timeout=10) - assert held["paused"] is True + assert held["paused"] is False # preset before the relay writer registers assert not outputs[1].exists() or outputs[1].stat().st_size == 0 assert len(server._fid_routes) == 1 fid, route = next(iter(server._fid_routes.items())) @@ -2030,7 +2043,7 @@ def hold_second_writer(target, kind, rel_dir, fname, originator_addr, tfid, assert server._lookup_fid_route(targets[0], route["targets"][targets[0]]) is None assert server._lookup_fid_route(targets[1], route["targets"][targets[1]])[1] is route - assert server.start_trans(held["fid"], targets[1]) is True + assert server.start_trans(held["fid"], targets[1], trans_type=1, direction=0) is True assert wait_until( lambda: outputs[1].exists() and outputs[1].stat().st_size == len(payload), timeout=20, @@ -2047,17 +2060,12 @@ def hold_second_writer(target, kind, rel_dir, fname, originator_addr, tfid, assert server._lookup_fid_route(target, tfid) is None finally: if held: - server.start_trans(held["fid"], targets[1]) + server.start_trans(held["fid"], targets[1], trans_type=1, direction=0) _close_socket_workers(server, clients, workers) def test_pause_and_start_trans_control_a_plain_transfer(tmp_path): - """``pause_trans``/``start_trans`` hold and release any outbound leg. - - The receiver stops reading until the sender is released, so the pause - works on a plain (non-forwarded) transfer: nothing arrives while the leg - is held, and the file completes after ``start_trans``. - """ + """A sender preset holds the body until start releases the same data leg.""" server = _start_server(tmp_path) server_recv = tmp_path / "server_recv" server_recv.mkdir() @@ -2072,11 +2080,12 @@ def test_pause_and_start_trans_control_a_plain_transfer(tmp_path): transfer_port, _stamp = request_transfer_listener(client, server, f"/file {src} {fid}") - assert client.pause_trans(fid) is False # armed before the leg starts + assert client.pause_trans(fid, trans_type=0, direction=0) is False # armed before the leg starts sender = threading.Thread( target=client.file_transfer_mode, args=(str(src), "127.0.0.1", transfer_port, 0), - kwargs={"fid": fid, "peer": (server.host, server.port)}, + kwargs={"fid": fid, "peer": (server.host, server.port), + "control_socket": client.client_socket, "crypto": _stamp}, daemon=True, ) sender.start() @@ -2084,11 +2093,12 @@ def test_pause_and_start_trans_control_a_plain_transfer(tmp_path): assert wait_until(lambda: client.file_upload_progress.get(upload_key)), ( "the uploader never registered the transfer" ) - time.sleep(0.5) + control_key = ((client.host, client.port), fid, 0, 0) + assert wait_until(lambda: control_key in client._transfer_controls._legs) output = server_recv / "payload.bin" assert not output.exists() or output.stat().st_size == 0, "the paused leg sent data" - assert client.start_trans(fid) is True # a live leg is released + assert client.start_trans(fid, trans_type=0, direction=0) is True # a live leg is released assert wait_until( lambda: output.exists() and output.stat().st_size == len(payload), timeout=20 ), "the released transfer did not finish" @@ -2392,7 +2402,7 @@ def test_download_resumes_after_connect_without_a_manual_call(tmp_path): with alloc._lock: fid = ((alloc._counter + 1) << 32) | (alloc._epoch << 1) upload_key = (client_addr, fid) - assert server.pause_trans(fid, client_addr) is False, "the leg was already running" + assert server.pause_trans(fid, client_addr, trans_type=0, direction=0) is False, "the leg was already running" # the server pushes the file: the client opens its listener and the # server connects from a send leg @@ -2431,7 +2441,7 @@ def test_download_resumes_after_connect_without_a_manual_call(tmp_path): assert wait_until( lambda: server._active_transfer_sockets.get(upload_key) is not dead_leg, timeout=20 ), "the dead session's leg was never cleared" - server.start_trans(fid, client_addr) # the test, not the protocol, parked this leg + server.start_trans(fid, client_addr, trans_type=0, direction=0) # the test, not the protocol, parked this leg assert wait_until(lambda: server.clients.get(client_addr) is not None, timeout=20), ( "the client did not come back" ) @@ -2937,13 +2947,13 @@ def test_paused_leg_is_released_by_stale_sweep(tmp_path, monkeypatch, sender_sid ) key = (peer, fid) target = peer - assert sender.pause_trans(fid, peer) is False + assert sender.pause_trans(fid, peer, trans_type=0, direction=0) is False else: sender, receiver = client, server command = f"/file {shlex.quote(str(src))} {fid}" key = ((client.host, client.port), fid) target = (client.host, client.port) - assert sender.pause_trans(fid) is False + assert sender.pause_trans(fid, trans_type=0, direction=0) is False port, stamp = request_transfer_listener(sender, receiver, command) control = ( server.clients[peer]["socket"] if sender is server else client.client_socket @@ -2974,14 +2984,15 @@ def send_leg(): and key in sender.file_upload_progress, timeout=10, ), "the paused leg never registered" - assert sender._transfer_pause.get(key) is True + control_key = (*key, 0, 0) + assert sender._transfer_pause.get(control_key) is True swept = sender._drop_stale_transfers(peer=peer if sender is server else None) assert swept == 1 assert wait_until(lambda: not leg.is_alive(), timeout=10), ( "the swept leg stayed paused" ) assert result.get("value") is False - assert key not in sender._transfer_pause + assert control_key not in sender._transfer_pause assert key in sender.file_upload_progress calls = [] diff --git a/test/unit/network_api/test_fid_routes.py b/test/unit/network_api/test_fid_routes.py index 88d99b5..01e500a 100644 --- a/test/unit/network_api/test_fid_routes.py +++ b/test/unit/network_api/test_fid_routes.py @@ -127,7 +127,7 @@ def test_registration_collision_is_atomic_for_primary_and_downstream_indexes(ser "owner", [ "receive", "upload", "active_fid", "active_receive_fid", - "active_socket", "active_receive_socket", "pause", "relay", "route_index", + "active_socket", "active_receive_socket", "control", "relay", "route_index", ], ) def test_registration_rejects_upstream_fid_that_collides_with_live_transfer_identity( @@ -147,8 +147,14 @@ def test_registration_rejects_upstream_fid_that_collides_with_live_transfer_iden server._active_transfer_sockets[target_key] = object() elif owner == "active_receive_socket": server._active_transfer_sockets[fid] = object() - elif owner == "pause": - server._transfer_pause[target_key] = True + elif owner == "control": + data_socket = object() + server._register_transfer_socket(target_key, data_socket) + state = server._transfer_controls.register( + (TARGET_1, fid, 1, 0), object(), data_socket, + ) + assert state is not None + server._transfer_controls.local(state["key"], True, lambda *_: True) elif owner == "relay": server._forward_relays[target_key] = object() else: diff --git a/test/unit/network_api/test_transfer_control.py b/test/unit/network_api/test_transfer_control.py index de3f4ef..975b4df 100644 --- a/test/unit/network_api/test_transfer_control.py +++ b/test/unit/network_api/test_transfer_control.py @@ -367,3 +367,38 @@ def test_control_state_never_enters_the_persisted_progress_snapshot(owner_type, assert json.load(stream) == before finally: owner.stop() if owner_type is TCP_Server_Base else owner.close() + + +@pytest.mark.parametrize("owner_type", [TCP_Server_Base, TCP_Client_Base]) +def test_public_control_requires_typed_keywords_and_presets_only_exact_senders(owner_type, tmp_path): + owner = owner_type(host=PEER[0], port=PEER[1], is_extend_command=True, + is_enable_encrypto=False, is_input_command_in_console=False, + is_print_log=False) + for attr in ("messages_log_file", "events_log_file", "sent_messages_log_file", + "sent_events_log_file", "file_trans_progress_file"): + setattr(owner, attr, str(tmp_path / f"{attr}.json")) + try: + for operation in (owner.pause_trans, owner.start_trans): + with pytest.raises(TypeError): + operation(42, PEER) + with pytest.raises(TypeError): + operation(42, PEER, 0, 0) + with pytest.raises(ValueError): + operation(42, PEER, trans_type=2, direction=0) + if owner_type is TCP_Server_Base: + with pytest.raises(ValueError): + owner.pause_trans(42, None, trans_type=0, direction=0) + else: + assert not owner.pause_trans(42, ("127.0.0.2", 6000), trans_type=0, direction=0) + assert not owner.pause_trans(42, PEER, trans_type=0, direction=1) + assert not owner.pause_trans(42, PEER, trans_type=1, direction=1) + assert owner._transfer_pause == {} + for kind in (0, 1): + assert not owner.pause_trans(42, PEER, trans_type=kind, direction=0) + assert owner._transfer_pause == {(PEER, 42, kind, 0): True for kind in (0, 1)} + assert not owner.start_trans(42, PEER, trans_type=0, direction=0) + assert owner._transfer_pause == {(PEER, 42, 1, 0): True} + assert not owner.start_trans(42, PEER, trans_type=1, direction=0) + assert owner._transfer_pause == {} and owner._transfer_controls._legs == {} + finally: + owner.stop() if owner_type is TCP_Server_Base else owner.close() diff --git a/test/unit/network_api/test_transfer_progress_query.py b/test/unit/network_api/test_transfer_progress_query.py index 452b21a..40a318b 100644 --- a/test/unit/network_api/test_transfer_progress_query.py +++ b/test/unit/network_api/test_transfer_progress_query.py @@ -29,6 +29,8 @@ def instance(request, tmp_path): def test_scoped_rows_keep_all_local_states_separate(instance): + if isinstance(instance, TCP_Client_Base): + instance.host, instance.port = PEER_A instance.file_upload_progress.update({ (PEER_A, 8): [4, 10, 2.0, "/send/a.bin", ORIGIN], (PEER_B, 8): [10, 10, None, "/send/b.bin", PEER_B], @@ -36,7 +38,10 @@ def test_scoped_rows_keep_all_local_states_separate(instance): instance.file_recv_progress[8] = [3, 20, None, "/recv/a.bin", PEER_A] instance._active_transfer_fids.add((PEER_A, 8)) instance._active_transfer_sockets[8] = object() - instance._transfer_pause[(PEER_A, 8)] = True + control_peer = PEER_A if isinstance(instance, TCP_Server_Base) else (instance.host, instance.port) + control_key = (control_peer, 8, 0, 0) + instance._transfer_controls.local(control_key, True, lambda *_: True) + instance._transfer_controls.register(control_key, object(), object()) view = instance.get_transfer_progress(include_persisted=False) rows = {tuple(row["receiver"]): row for row in view["memory"]["uploading"]} assert set(rows) == {PEER_A, PEER_B} From 86223f1c4dc60740823ec002859a95becc65da71 Mon Sep 17 00:00:00 2001 From: F18-Ray Date: Mon, 16 Nov 2026 18:21:15 +0800 Subject: [PATCH 04/19] fix(tcp): isolate relay control and preserve upstream pause intent --- PyFlow/network_api/connect_tcp.py | 97 ++++--- .../transfer-pause-start-direction-plan.md | 6 +- .../transfer-pause-start-direction-report.md | 73 +++++- docs/source/File_Transfer/File_Transfer.rst | 18 +- docs/source/changes/transfer-fid-routes.md | 26 ++ .../network_api/test_tcp_transfer_control.py | 241 ++++++++++++++++++ test/unit/network_api/test_fid_routes.py | 31 +++ .../unit/network_api/test_transfer_control.py | 74 ++++++ 8 files changed, 527 insertions(+), 39 deletions(-) diff --git a/PyFlow/network_api/connect_tcp.py b/PyFlow/network_api/connect_tcp.py index 6682f83..3bd4919 100644 --- a/PyFlow/network_api/connect_tcp.py +++ b/PyFlow/network_api/connect_tcp.py @@ -819,6 +819,7 @@ def register(self, key, control_socket, owner): "lock": threading.RLock(), "confirmed_state": paused, "last_requested_state": False, "initial_notification": paused, "ready": self._instance is None or key[3] == 1, + "user_paused": False, "backpressure": False, } self._legs[key] = state return state @@ -862,10 +863,12 @@ def announce(self, state, send=None): return False return self._send(state, state["confirmed_state"], send) - def local(self, key, paused, send=None): + def local(self, key, paused, send=None, *, backpressure=False, owner=None): """Decide a sender state or submit a receiver intent, deduplicating both.""" with self._condition: state = self._legs.get(key) + if owner is not None and (state is None or state["owner"] is not owner): + return False if state is None: if key[3] == 0: if paused: @@ -877,6 +880,11 @@ def local(self, key, paused, send=None): with state["lock"]: if not self._live(state): return False + if owner is not None and state["owner"] is not owner: + return False + if key[3] == 1: + state["backpressure" if backpressure else "user_paused"] = paused + paused = state["user_paused"] or state["backpressure"] if key[3] == 0: if state["confirmed_state"] == paused: return False @@ -918,6 +926,7 @@ def release(self, state): state["confirmed_state"] = False state["last_requested_state"] = False state["initial_notification"] = False + state["user_paused"] = state["backpressure"] = False self._condition.notify_all() return True @@ -996,12 +1005,24 @@ def _control_peer(instance, peer): def _control_key(instance, peer, fid, trans_type, direction): + key = _transfer_control_key(peer, fid, trans_type, direction) if trans_type == 1 and direction == 0 and isinstance(instance, TCP_Server_Base): with instance._forward_relays_lock: - relay = instance._forward_relays.get((peer, fid)) - if relay is not None: - fid = relay["route"]["targets"].get(peer, fid) - return _transfer_control_key(peer, fid, trans_type, direction) + if (peer, fid) in instance._forward_relays or (peer, fid) in instance._fid_route_index: + return key + candidates = [relay["controls"].get(peer) + for (target, child), relay in instance._forward_relays.items() + if target == peer and relay["fid"] == fid] + with instance._transfer_pause_cond: + if key in instance._transfer_controls._legs: + return key + matches = [state for state in candidates if state is not None + and instance._transfer_controls._legs.get(state["key"]) is state] + if len(matches) > 1: + return None + if matches: + return matches[0]["key"] + return key def _set_transfer_control(instance, fid, peer, trans_type, direction, paused): @@ -1009,9 +1030,8 @@ def _set_transfer_control(instance, fid, peer, trans_type, direction, paused): peer = _control_peer(instance, peer) if peer is None: return False - return instance._transfer_controls.local( - _control_key(instance, peer, fid, trans_type, direction), paused - ) + key = _control_key(instance, peer, fid, trans_type, direction) + return instance._transfer_controls.local(key, paused) if key is not None else False def _receive_transfer_control(instance, sock, peer, command): @@ -1020,7 +1040,8 @@ def _receive_transfer_control(instance, sock, peer, command): return paused, fid, trans_type, direction = parsed key = _control_key(instance, peer, fid, trans_type, 1 - direction) - instance._transfer_controls.receive(key, sock, paused) + if key is not None: + instance._transfer_controls.receive(key, sock, paused) def _bind_transfer_control(instance, fid, sock, owner, trans_type, direction): @@ -2963,12 +2984,13 @@ def _register_fid_route(self, fid, originator, targets, completed=()): or any(key in self._active_transfer_sockets for key in upstream_leg_keys) ) with self._transfer_pause_cond: - paused_collision = any( - leg_fid == fid and ( + control_collision = any( + leg_fid == fid and isinstance(state["owner"], socket.socket) + and state["owner"].fileno() >= 0 and ( role == 0 and (peer, fid) in upstream_leg_keys or role == 1 and peer == tuple(originator) ) - for peer, leg_fid, kind, role in self._transfer_controls._legs + for (peer, leg_fid, kind, role), state in self._transfer_controls._legs.items() ) with self._forward_relays_lock: if ( @@ -2978,7 +3000,7 @@ def _register_fid_route(self, fid, originator, targets, completed=()): or fid in self.file_recv_progress or any(key in self.file_upload_progress for key in upstream_leg_keys) or active_collision - or paused_collision + or control_collision or any(key in self._forward_relays for key in upstream_leg_keys) or any(key in self._fid_route_index for key in upstream_leg_keys) or any( @@ -7096,8 +7118,9 @@ def _forward_relay( "cond": threading.Condition(), "controls": {}, "route": route, + "fid": fid, } - relay_keys = [(target, leg_fid) for target, tfid in zip(targets, tfids) for leg_fid in (fid, tfid)] + relay_keys = [(target, tfid) for target, tfid in zip(targets, tfids)] with self._forward_relays_lock: if any(key in self._forward_relays for key in relay_keys): self._forward_notify_error( @@ -7163,25 +7186,29 @@ def own(control, transfer): target_control = target_handshakes[(target, tfid)]["key"][0] if not own(target_control, sock) or not own(forwarder_sock, sock): return + control = _bind_transfer_control(self, tfid, target_control, sock, 1, 0) + relay["controls"][target] = control try: sock.connect((target[0], tport)) except Exception as e: self._log(f"forward: cannot connect to target {target}: {e}") + self._transfer_controls.release_owner(sock) sock.close() continue try: self._crypto_attach_transfer_out(sock, target_control, stamp) except _CryptoUnavailable as exc: self._log(f"forward: target {target} transfer aborted: {exc}") + self._transfer_controls.release_owner(sock) sock.close() continue if not self._forward_read_sign(sock, self.server_start_file_transfer_sign): self._log(f"forward: target {target} did not start, skipped") + self._transfer_controls.release_owner(sock) sock.close() continue target_conns.append((tfid, target, sock)) - control = _bind_transfer_control(self, tfid, target_control, sock, 1, 0) - relay["controls"][target] = control + # The target's start sign proves its receiving leg is registered. _announce_transfer_control(self, control) if not target_conns: fail("no target accepted the transfer") @@ -7264,7 +7291,11 @@ def _forward_pump( low_water = max(1, max_bytes // 2) cond = relay["cond"] controls = relay["controls"] - state = {"buffered": 0, "paused": False, "complete": False, "failed": False} + state = relay["buffer"] = { + "buffered": 0, "backpressured": False, "complete": False, "failed": False, + "high_water": max_bytes, "peak": 0, "max_enqueue": 0, + } + upstream = relay["upstream"] queues = {(target, tfid): queue.Queue() for tfid, target, _ in target_conns} END = object() result = {"ok": 0, "ack": None} @@ -7272,32 +7303,40 @@ def _forward_pump( def release_buffered(byte_count): """Called under cond; failed writers also release upstream backpressure.""" state["buffered"] -= byte_count - if state["paused"] and state["buffered"] <= low_water: - state["paused"] = False - try: - self.start_trans(fid, _socket_peer_endpoint(forwarder_sock), trans_type=1, direction=1) - except Exception: - pass + if state["backpressured"] and state["buffered"] <= low_water: + state["backpressured"] = False + self._transfer_controls.local( + upstream["key"], False, backpressure=True, owner=upstream["owner"] + ) cond.notify_all() def enqueue(chunk): with cond: - state["buffered"] += len(chunk) * len(queues) + while state["backpressured"]: + if up_sock.fileno() < 0: + raise ConnectionError("uploader control session closed") + cond.wait(timeout=0.5) + added = len(chunk) * len(queues) + state["buffered"] += added + state["peak"] = max(state["peak"], state["buffered"]) + state["max_enqueue"] = max(state["max_enqueue"], added) for pending in queues.values(): pending.put(chunk) - if not state["paused"] and state["buffered"] > max_bytes: - state["paused"] = True - self.pause_trans(fid, _socket_peer_endpoint(forwarder_sock), trans_type=1, direction=1) + if not state["backpressured"] and state["buffered"] > max_bytes: + state["backpressured"] = True + self._transfer_controls.local( + upstream["key"], True, backpressure=True, owner=upstream["owner"] + ) def writer(tfid, target, sock): key = (target, tfid) pending = queues[key] try: while True: - _wait_transfer_control(self, controls[target], sock) item = pending.get() if item is END: break + _wait_transfer_control(self, controls[target], sock) try: if not self.send_message(sock, item): return @@ -7339,7 +7378,7 @@ def reader(): remaining = file_size - resume_offset while remaining > 0: with cond: - while state["paused"]: + while state["backpressured"]: if up_sock.fileno() < 0: raise ConnectionError("uploader control session closed") cond.wait(timeout=0.5) diff --git a/docs/plans/transfer-pause-start-direction-plan.md b/docs/plans/transfer-pause-start-direction-plan.md index 2b955f2..e74b750 100644 --- a/docs/plans/transfer-pause-start-direction-plan.md +++ b/docs/plans/transfer-pause-start-direction-plan.md @@ -1,6 +1,6 @@ # 双向文件暂停、继续与按对象恢复 — 需求卡与更改计划 -状态:**C1、C2a 已通过人工审查;C2b 已实现并完成局部验证,待人工审查**。需求卡和七项拆分已确认;本轮“开始 C2b”的授权包括第 3.1 节列明的协议/API 切换,恢复资格的后续实现仍按 C4a/C4b。C3–C5 尚未开始。每个原子变更完成后另附验证报告并等待审查。不自行提交、合并或推送。实际结果、首轮失败修复及规模偏差见[实施报告](transfer-pause-start-direction-report.md)。 +状态:**C1–C2b 已通过人工放行;C3 已实现并完成局部验证,待人工审查**。需求卡和七项拆分已确认。C3 完成转发精确控制与共享上游背压验收;恢复资格仍按 C4a/C4b。C4–C5 尚未开始。每个原子变更完成后另附验证报告并等待审查。不自行提交、合并或推送。证据见[实施报告](transfer-pause-start-direction-report.md)。 ## 1. 需求卡 @@ -188,7 +188,7 @@ relay 高水位证据按实际入队粒度计算:记录高水位、单次 enqu ## 6. 验收命令与报告要求 -各阶段定向证据见实施报告。C1:81 passed;C2a:154 passed,修复参数化告警后受影响 64 项通过。C2b 首轮 223 passed、2 failed、1 skipped;tracking off EOF 旧行清理修复后原失败两项通过,owner 等待隔离的基础/实际连接定向检查 134 passed,既有文件/relay/恢复/crypto/async/握手/wire 回归 159 passed。另有真实逐文件夹 leg 与重新交换窗口证据。没有将单项重跑标作全量复跑;C3–C5 命令尚未运行。C5 再进行一次相关合并回归,不反复运行整个仓库。 +各阶段定向证据见实施报告。C1:81 passed;C2a:154 passed,修复参数化告警后受影响 64 项通过。C2b 首轮 223 passed、2 failed、1 skipped;tracking off EOF 旧行清理修复后原失败两项通过,owner 等待隔离检查 134 passed,既有受影响回归 159 passed。C3 控制/路由/实际连接验证 217 passed、3 deselected;既有转发/恢复回归 20 passed、73 deselected。实际命令与证据边界见报告,不将 deselected 计为已运行。C4–C5 命令尚未运行;C5 再进行一次相关合并回归,不反复运行整个仓库。 ```bash # C1/C2a:实现后新增必要边界契约 @@ -220,4 +220,4 @@ relay 高水位证据按实际入队粒度计算:记录高水位、单次 enqu - **持久化数据模型不变**;运行时控制记录改变。查询返回 schema 不变。测试增加必要边界契约及迁移受影响断言,不降低验证强度。 - **CI/依赖/覆盖率策略不变**。不宣称本计划覆盖未运行的多平台环境、NAT、多进程共享或任意网络中断组合。 - 新功能依赖存活且可投递的控制连接;仅有数据 socket 存活但控制连接不可用时,不承诺远程 pause/start。自然关闭路径按既有机制结束旧 leg。 -- 需求卡、P01–P18 路径全集及七项原子拆分已确认;C1、C2a 已通过人工审查,C2b 已按本轮授权完成协议/API 切换并完成局部验证,待人工审查。resume 活跃对象返回 False 的资格门槛仍在 C4a/C4b 实施。C2b 实际规模超出原预估,已在报告明确列为需人工接受或退回计划重拆的偏差,不自行进入 C3。本轮未创建提交。 +- 用户已放行 C3;本阶段已完成转发控制与背压实现、定向验证和局部报告,待人工审查。resume 活跃对象返回 False 的资格门槛仍在 C4a/C4b 实施,不自行进入 C4。本轮未创建提交、合并或推送。 diff --git a/docs/plans/transfer-pause-start-direction-report.md b/docs/plans/transfer-pause-start-direction-report.md index 41866da..37c9f88 100644 --- a/docs/plans/transfer-pause-start-direction-report.md +++ b/docs/plans/transfer-pause-start-direction-report.md @@ -1,6 +1,6 @@ # 双向文件暂停、继续与按对象恢复 — 实施报告 -状态:需求卡和七项拆分已确认。**C1、C2a 已通过人工审查;C2b 已实现并完成局部验证,待人工审查;C3–C5 未开始。** 本报告随已完成的原子变更增补,不将未实现或未运行的路径标为完成。本轮未创建提交、合并或推送。 +状态:需求卡和七项拆分已确认。**C1–C2b 已通过人工放行;C3 已实现并完成局部验证,待人工审查;C4–C5 未开始。** 本报告随已完成的原子变更增补,不将未实现或未运行的路径标为完成。本轮未创建提交、合并或推送。 ## C1:严格解析、typed identity 与共享端点识别 @@ -210,7 +210,76 @@ C2a 后续审查结论:用户已审计放行,并明确授权开始 C2b,包 - 状态登记成功仅表示已进入控制 FIFO,不代表对端确认。控制发送失败沿既有错误/关闭机制终止会话,不重试、不降级;不承诺仅有 data socket、控制连接不可用时仍可远程控制。 - 生产控制 FIFO 只排控制消息,不排每块文件数据。活动记录与暂停键分离;路由冲突仍检查真实 owner,复杂 relay 路由/背压、共享 source 门槛及恢复资格没有在本轮提前宣称交付。 - 语言服务仍只有 Ruff、无 referencesProvider;公开符号引用请求返回 `-32601`,随后按调用枚举迁移。不能将该请求计为成功引用分析。 -- **C2b 待人工审查,未创建提交**。C3 及后续阶段未获本轮执行授权。 +- C2b 后续结论:用户已放行 C3,本阶段的协议/API 切换及规模偏差随该放行进入下一阶段。C3 实施及其独立待审事项见下节。 + +## C3:转发精确控制、用户意图与共享背压 + +### 提交意图与改动内容 + +完成 P08–P10 的转发控制:每条 downstream leg 独立定位并沿同一 socket 继续,shared upstream 的用户暂停和自动背压互不覆盖;reader 通过独立高水位门槛保持有限缓冲。本轮不改 resume 资格。 + +| 文件 | 关键改动 | +|---|---| +| `PyFlow/network_api/connect_tcp.py` | registry 为 receiver 分开记录 user_paused/backpressure 并汇总请求;转发索引仅存 canonical child;唯一活跃同 peer alias 查找;writer 在 connect 前绑定控制并在失败时释放;END 不等待数据暂停;reader/header enqueue 硬门槛与有限缓冲观测;真实 setup socket 占用保护 | +| `test/unit/network_api/test_transfer_control.py` | 精确 child 优先、同 peer 唯一活跃 alias、错误类型/角色/peer、陈旧映射与 owner、用户/压力 OR 和通知意图隔离 | +| `test/unit/network_api/test_fid_routes.py` | 预置/False/无数据 owner 的控制记录不预占路由;真实 setup socket 在 active index 尚未登记时拒绝覆盖 | +| `test/integration/network_api/test_tcp_transfer_control.py` | 两目标真实 relay 控制、错误命令隔离、未暂停 target 的真实 ACK、用户/压力交叉、source start 不开读门、关闭 target 及峰值上界证据 | +| File_Transfer RST、计划、变更记录、本报告 | 同步 upstream OR 语义、child 优先、缓冲边界及实际验收记录 | + +### 数据流与不变量 + +- public 或 wire 控制 → peer/type/local role → exact child key 优先 → 仅在无 exact child 时接受同 peer 唯一活跃 writer 的 upstream alias → 原有 per-leg 串行决定/FIFO → 对应 target。索引不再同时写 child/upstream 别名,避免两个 route 的数字交叉时覆盖。 +- server 用户对 upstream receiver 的 pause/start 更新 user_paused;buffer high/low 更新 backpressure,均提交 `user_paused OR backpressure`。收到 source 的权威通知只改 confirmed,不清理任一意图。背压操作携带 upstream owner,旧 pump 无法改新记录。 +- source 本地 start 仍是发送端权威决定,允许暂时确认 running;relay reader 的独立 backpressured 门槛不会因此打开。只有 buffered 降到 low water 才解除该门槛。header enqueue 同样经过门槛,峰值必须小于等于 high_water + max_enqueue,后者为实际最大单次 fan-out 入队字节数。 +- writer 先取 item,END 直接进入最终 ACK;仅真实数据发送前等待暂停。数据 connect 前登记 writer,让 receiver startup 之后立刻发来的请求可定位;connect/安全握手/startup 失败立即释放绑定。 +- 无真实数据 owner 的记录、False 残留及精确预置暂停不独立阻挡路由;真实 socket/setup owner、active socket/progress/route 冲突仍原子拒绝,不授予覆盖进度行的能力。 + +### 局部验证 + +主定向验证: + +```bash +.venv/bin/python -m pytest test/unit/network_api/test_transfer_control.py test/unit/network_api/test_fid_routes.py test/integration/network_api/test_tcp_transfer_control.py -k 'not receiver_pause_start_waits_for_real_rekey_without_blocking_key_reader' -q +``` + +**217 passed、3 deselected in 274.44s**(墙钟 276.27s)。三项 deselected 为本轮未重复运行的 C2b 普通连接重新交换用例,不是新增 skip;两组加密配置下的新转发用例实际运行。 + +运行时证据: + +- 两个真实 target 连接和实际 relay 文件流;target child 控制与 server upstream alias 均只改变指定 writer。错误 peer/type/role 控制通过真实连接送达并用后续消息屏障确认已处理,其他 writer/upstream 状态保持。 +- 一个 writer 暂停期间,另一个 target 收到完整内容并返回真实最终 ACK;指定 writer 沿原 data socket 继续后,全部目标完成,source 获得成功 ACK,route/index/control/pause 均清理。 +- tiny high water、writer 事件屏障及真实 source pause/start 交叉;buffer pressure 触发后,source 本地 start 虽可确认运行,reader 被唤醒后仍重新等待高水位门槛,实际读取计数不增加。峰值大于阈值但不超过 `high_water + max_enqueue`。 +- 用户 pause 在自动 pressure 释放后仍保留;用户 start 在 pressure 存在时仍请求 pause。源端权威通知只更新确认状态,不清除 user/pressure 意图,最终解除用户 pause 后实际流排空。 +- 一个 target 在背压期间关闭:剩余 target 的文件内容完整,source 获得失败结果,不伪造全目标成功;仅真实完成 target 写入 completed,未完成 route 保留,control owner 与暂停键释放。 +- plain、encrypted、encrypted+async+tracking off 配置全部执行上述场景。加密配置观察真实控制通道帧:含 FRAME_MAGIC、无 pause/start 明文片段,未 raw 发送;未替换加密或实际传输。 + +既有受影响的转发与恢复回归: + +```bash +.venv/bin/python -m pytest test/integration/network_api/test_tcp_file_transfer.py test/integration/network_api/test_tcp_transfer_resume.py -k forward -q +``` + +**20 passed、73 deselected in 65.45s**(墙钟 66.20s)。覆盖既有多目标文件/文件夹、背压、目标不可达、ACK 丢失/写失败、最后目标 ACK、路由 reload、零偏移恢复和并发转发握手;未将这些旧路径回归计作 C4 新恢复资格契约的验收。 + +### 路径对照与明确未覆盖 + +| 路径 | C3 结论与证据边界 | +|---|---| +| P08 | 真实 target child 与 server upstream alias 精确命中,错误 peer/type/role 无效果,另一 target 独立完成;单位契约覆盖数字交叉时 child 优先、唯一活跃 alias 与陈旧映射 | +| P09 | source 本地操作、server 用户意图及自动背压交叉后可继续;reader 不受 source start 绕过,实际读取计数与有界峰值通过 | +| P10 | 另一 target 被事件屏障放慢或关闭时,解除控制不解除 reader 高水位门槛;正常流内容/真实 ACK 成功,关闭分支仅记录真实完成目标、上游失败且保留未完成 route。无 live leg 后的恢复资格仍属 C4b | +| P11 | 新 relay 场景在真实加密连接中执行,帧无控制明文且未 raw 写入;C2b 已有重新交换窗口证据,本轮未重复执行那三项普通连接用例,不声称新增 relay 专用 re-key 交错全集 | +| P13 | plain、encrypted、encrypted async/tracking off 三组配置运行全部新增多目标场景;未跟踪场景仍由运行时记录控制 | +| P18 | 完成/target 关闭均释放控制 owner 和暂停键;active socket/setup owner 冲突拒绝,而 False/预置/无数据 owner 记录不单独阻挡路由。config 删除、stop 竞争及 reload 与新恢复资格的总验收仍在 C4b/C5 | +| P14–P17 | 本轮不实现新恢复资格或跨会话恢复竞争;仅记录既有相关回归结果,按 C4a/C4b 继续 | + +### 风险与审查注意 + +- 下游控制保持独立,但慢 target 的积压达到共享阈值后会间接阻止 source 和其他 target 获得新数据,这是共享上游的既定背压语义。缓冲上界包含一次 enqueue 的 fan-out 超调,不承诺绝不超过 max_mem_buff。 +- 自动请求与用户意图汇总不改变发送端权威规则:source 本地 start 可暂时确认运行,reader 仍自行守住高水位;后续请求按 source 处理顺序决定状态。返回 True 仍只表示控制操作登记,非逐请求 ACK。 +- 本轮未改公共签名、wire 格式、持久化 schema、CI、依赖或覆盖率策略;未删除或弱化既有测试。新测试使用真实 socket/加密、事件屏障和实际内容/ACK,未运行 formatter、lint、文档构建、repo-wide suite 或多平台验证。 +- C3 保留小范围生产修改并补充两目标契约(集成新增 241 行);文档/报告与测试也是本次审查的一部分。完成范围仅为上表证据,不宣称所有断线/网络时序组合已枚举。 +- **C3 待人工审查,未创建提交**。C4a/C4b 与 C5 未开始。 ## 公共协议/API 变更许可记录 diff --git a/docs/source/File_Transfer/File_Transfer.rst b/docs/source/File_Transfer/File_Transfer.rst index 727b31e..73ff9c3 100644 --- a/docs/source/File_Transfer/File_Transfer.rst +++ b/docs/source/File_Transfer/File_Transfer.rst @@ -540,11 +540,13 @@ buffered bytes exceed ``max_mem_buff`` it sends ``/pause_trans 1 1`` to the forwarding client: the server is the local receiver of this relay leg, and the client stops reading the source file. Once the writers drain the buffers below the low-water mark (half the limit), -the server sends ``/start_trans 1 1`` and the upload resumes on the same -socket. Receiving clients drain each chunk to disk synchronously, so their -buffered memory stays bounded by a single chunk. Ordinary and relay legs use -the same typed control handlers on both sides; an in-flight receive and write -continues while a receiver waits for sender confirmation. +the server releases its automatic pause request. This is combined with the +server user's upstream pause using OR: draining cannot cancel a user pause, +and a user start cannot cancel pressure. The reader independently waits at the +high-water gate, even if the source locally starts. Buffering can exceed the +threshold by one enqueue's fan-out bytes; it does not grow without bound. +Receiving clients continue in-flight writes; ordinary and relay legs share +the typed secure control path and retain the same data sockets. .. _concurrency-and-threading: @@ -838,6 +840,12 @@ The control identity is ``(control_peer, fid, trans_type, local_role)``; client control peers are canonicalized to ``(client.host, client.port)`` even when the logical forwarded target differs. +Relay downstream control uses the target's child fid. An upstream fid alias +is accepted only when that control peer has one matching live writer; an exact +child match takes precedence. Each target pauses independently, although its +backlog can eventually apply shared upstream pressure. Runtime control records +without a live data owner do not reserve a route. + Both methods apply the local operation and notify the peer through the existing secure control connection. The wire commands have exactly four tokens: ``/pause_trans `` and diff --git a/docs/source/changes/transfer-fid-routes.md b/docs/source/changes/transfer-fid-routes.md index 1e6f2a6..61b9d6d 100644 --- a/docs/source/changes/transfer-fid-routes.md +++ b/docs/source/changes/transfer-fid-routes.md @@ -385,3 +385,29 @@ file preservation. Runtime evidence and explicit exclusions are recorded in report. Complex multi-target routing/backpressure acceptance and object-level resume eligibility retain their C3/C4 review gates. +## Transfer control C3: scoped relay control and independent backpressure + +- Relay control indexes contain only canonical target/child-FID pairs. An + exact child takes precedence; an upstream alias resolves only to one live + writer for that control peer. Wrong peers, types and roles never fall back + to a global FID match. Writer controls are registered before data connect + and released on setup failure. +- Relay receiver state keeps user pause and automatic backpressure as separate + intents. Their OR determines upstream requests; low-water release cannot + cancel a user pause. Notifications preserve both intents, and an old pump + cannot mutate a replacement owner. +- The reader's high-water gate remains independent of source pause/start. + Headers also obey the gate; queued bytes are bounded by the threshold plus + one enqueue's fan-out bytes. Each writer pauses before real data, while END + and final ACK handling do not wait for a nonexistent next block. +- Presets, False flags and records without a live data owner do not reserve + routes. Actual setup sockets and existing active/progress/route ownership + still refuse replacement. Runtime acceptance and remaining limitations are + recorded in the C3 implementation report. +- C3 verification passed 217 control/routing tests (three existing re-key + cases deselected) and 20 affected forwarding/resume regressions (73 unrelated + cases deselected). New real two-target scenarios cover independent writers, + user/pressure crossings, encrypted frames, bounded buffering and target-close + failure without a false upstream success ACK. C4 resume eligibility remains + outside this change. + diff --git a/test/integration/network_api/test_tcp_transfer_control.py b/test/integration/network_api/test_tcp_transfer_control.py index b3d1449..60fdcca 100644 --- a/test/integration/network_api/test_tcp_transfer_control.py +++ b/test/integration/network_api/test_tcp_transfer_control.py @@ -385,3 +385,244 @@ def request_both(): assert wire and all(data.startswith(connect_tcp.FRAME_MAGIC) for data in wire) assert not any(b"/pause_trans" in data or b"/start_trans" in data for data in wire) _complete(leg) + + +@pytest.fixture +def relay_clients(channel, tmp_path): + server, source, releases = channel + targets = [] + try: + for name in ("target_a", "target_b"): + target = TCP_Client_Base( + host=source.host, port=source.port, client_host="127.0.0.1", + is_extend_command=True, is_input_command_in_console=False, + is_enable_encrypto=source.is_enable_encrypto, is_print_log=False, + is_enable_file_transfer_progress_bar=source.is_enable_file_transfer_progress_bar, + ) + targets.append(target) + isolate_instance_files(target, tmp_path, name) + destination = tmp_path / name + destination.mkdir() + target.file_transfer_dir = str(destination) + if target.is_enable_encrypto: + crypto = target.crypto + crypto.pvt_key_dir = str(tmp_path / f"{name}_private") + crypto.pub_key_dir = str(tmp_path / f"{name}_public") + crypto.ssh_dir = str(tmp_path / "ssh") + crypto.registry_path = os.path.join(crypto.pub_key_dir, "pub_key.json") + for directory in (crypto.pvt_key_dir, crypto.pub_key_dir, crypto.ssh_dir): + os.makedirs(directory, exist_ok=True) + assert target.connect() + peer = target.client_socket.getsockname() + assert wait_until(lambda: peer in server.clients) + if target.is_enable_encrypto: + assert wait_until(lambda: target.client_socket in target._encrypted_sockets + and server.clients[peer]["socket"] in server._encrypted_sockets, + timeout=20) + yield server, source, targets, releases + finally: + for release in releases: + release.set() + for target in targets: + target.close() + + +def _relay(relay_clients, tmp_path, monkeypatch, *, pressure=False): + server, source, targets, releases = relay_clients + addresses = [target.client_socket.getsockname() for target in targets] + payload = os.urandom(16 * 1024 + 7) + path = tmp_path / "relay.bin" + path.write_bytes(payload) + server.max_mem_buff = 64 if pressure else len(payload) * 4 + server.file_transfer_chunk_len = source.file_transfer_chunk_len = 1024 + entered = [threading.Event() for _ in range(3)] + gates = [threading.Event() for _ in range(3)] + releases.extend(gates) + observed = {"reads": 0, "waits": 0, "controls": [], "frames": []} + tail = threading.Event() + releases.append(tail) + observed["tail"] = tail + waiting = threading.Event() + real_wait, real_pump = connect_tcp._wait_transfer_control, server._forward_pump + real_read = server._forward_recv_exact + + def hold(instance, state, sock): + if state is not None and state["key"][2:] == (1, 0): + index = 0 if instance is source else ( + 1 + addresses.index(state["key"][0]) if instance is server else None) + if index is not None: + entered[index].set() + assert gates[index].wait(timeout=30), "relay body gate was not released" + if index == 0 and pressure and observed.get("source_entered"): + assert tail.wait(timeout=30), "source tail gate was not released" + if index == 0: + observed["source_entered"] = True + return real_wait(instance, state, sock) + + def pump(up, connections, control, fid, name, relay, offset=0): + observed["relay"] = relay + real_condition_wait = relay["cond"].wait + + def pressure_wait(timeout=None): + if relay["buffer"]["backpressured"]: + observed["waits"] += 1 + waiting.set() + return real_condition_wait(timeout) + + monkeypatch.setattr(relay["cond"], "wait", pressure_wait) + return real_pump(up, connections, control, fid, name, relay, offset) + + def read(sock, count): + observed["reads"] += 1 + return real_read(sock, count) + + monkeypatch.setattr(connect_tcp, "_wait_transfer_control", hold) + monkeypatch.setattr(server, "_forward_pump", pump) + monkeypatch.setattr(server, "_forward_recv_exact", read) + for owner in (server, source, *targets): + real_send = owner.send_message + + def send(sock, message, is_send_raw=False, send=real_send): + if isinstance(message, str) and message.startswith(("/pause_trans ", "/start_trans ")): + observed["controls"].append((message, is_send_raw)) + return send(sock, message, is_send_raw=is_send_raw) + + monkeypatch.setattr(owner, "send_message", send) + if owner.is_enable_encrypto: + for secure in list(owner._channels.values()): + real_sendall = secure._sendall + + def frame(data, sendall=real_sendall): + observed["frames"].append(bytes(data)) + return sendall(data) + + monkeypatch.setattr(secure, "_sendall", frame) + result = {} + worker = threading.Thread(target=lambda: result.update(ack=source._forward_one( + "file", "", path.name, str(path), addresses)), daemon=True) + worker.start() + assert all(event.wait(timeout=20) for event in entered) + relay = observed["relay"] + upstream = relay["upstream"] + sender = source._transfer_controls._legs[((source.host, source.port), relay["fid"], 1, 0)] + _confirmed((sender, upstream), False) + return relay, sender, gates, worker, result, payload, observed, waiting + + +def _relay_done(relay_clients, run, *, failed=False): + server, source, targets, _ = relay_clients + relay, sender, gates, worker, result, payload, observed, _ = run + for gate in gates: + gate.set() + observed["tail"].set() + worker.join(timeout=20) + assert not worker.is_alive() and result == {"ack": not failed} + buffer = relay["buffer"] + assert buffer["complete"] and not buffer["failed"] and buffer["buffered"] == 0 + assert buffer["peak"] <= buffer["high_water"] + buffer["max_enqueue"] + assert wait_until(lambda: not server._forward_relays) + for target in targets[1:] if failed else targets: + assert (Path(target.file_transfer_dir) / "relay.bin").read_bytes() == payload + assert wait_until(lambda: all(not owner._transfer_controls._legs + and not owner._transfer_pause + for owner in (server, source, *targets))) + assert observed["controls"] and not any(raw for _, raw in observed["controls"]) + if source.is_enable_encrypto: + assert observed["frames"] and all(frame.startswith(connect_tcp.FRAME_MAGIC) + for frame in observed["frames"]) + assert not any(b"/pause_trans" in frame or b"/start_trans" in frame + for frame in observed["frames"]) + if failed: + assert server._fid_routes[relay["fid"]] is relay["route"] + else: + assert not server._fid_routes and not server._fid_route_index + + +def test_relay_child_and_upstream_alias_control_only_the_selected_writer( + relay_clients, tmp_path, monkeypatch +): + run = _relay(relay_clients, tmp_path, monkeypatch) + server, source, targets, _ = relay_clients + relay, sender, gates, _, result, _, _, _ = run + first, second = [relay["controls"][target.client_socket.getsockname()] for target in targets] + receiver = targets[0]._transfer_controls._legs[ + ((source.host, source.port), first["key"][1], 1, 1)] + data_socket = first["owner"] + assert _control(targets[0], receiver, True) + _confirmed((first, receiver), True) + assert server.start_trans(relay["fid"], first["key"][0], trans_type=1, direction=0) + _confirmed((first, receiver), False) + assert server.pause_trans(relay["fid"], first["key"][0], trans_type=1, direction=0) + _confirmed((first, receiver), True) + for owner, command in ( + (source, f"/start_trans {first['key'][1]} 1 1"), + (targets[1], f"/start_trans {first['key'][1]} 1 1"), + (targets[0], f"/start_trans {first['key'][1]} 0 1"), + (targets[0], f"/start_trans {first['key'][1]} 1 0"), + ): + barrier = threading.Event() + marker = f"/relay_barrier_{id(barrier)}" + server.add_message_listener(lambda _peer, line, marker=marker, event=barrier: + event.set() if line == marker else None) + assert owner.send_message(owner.client_socket, command) + assert owner.send_message(owner.client_socket, marker) + assert barrier.wait(timeout=10) + assert first["confirmed_state"] and not second["confirmed_state"] + assert not sender["confirmed_state"] and not relay["upstream"]["confirmed_state"] + gates[0].set() + gates[2].set() + second_peer = targets[1].client_socket.getsockname() + assert wait_until(lambda: second_peer in relay["route"]["completed"], timeout=15) + assert (Path(targets[1].file_transfer_dir) / "relay.bin").read_bytes() == run[5] + assert result == {} and first["owner"] is data_socket and data_socket.fileno() >= 0 + assert _control(targets[0], receiver, False) + _relay_done(relay_clients, run) + + +@pytest.mark.parametrize("close_target", [False, True], ids=["drain", "target-close"]) +def test_relay_pressure_preserves_user_intent_and_source_start_cannot_open_reader( + relay_clients, tmp_path, monkeypatch, close_target +): + run = _relay(relay_clients, tmp_path, monkeypatch, pressure=True) + server, source, targets, _ = relay_clients + relay, sender, gates, _, _, _, observed, waiting = run + upstream, buffer = relay["upstream"], relay["buffer"] + sockets = [state["owner"] for state in relay["controls"].values()] + gates[0].set() + assert waiting.wait(timeout=10) + _confirmed((sender, upstream), True) + assert buffer["backpressured"] and upstream["backpressure"] + assert _control(server, upstream, True) is False + assert upstream["user_paused"] + assert _control(source, sender, False) + _confirmed((sender, upstream), False) + assert _control(server, upstream, False) + assert not upstream["user_paused"] and upstream["last_requested_state"] + _confirmed((sender, upstream), True) + assert _control(source, sender, False) + _confirmed((sender, upstream), False) + with relay["cond"]: + reads = observed["reads"] + waiting.clear() + relay["cond"].notify_all() + assert waiting.wait(timeout=10), "reader did not re-enter its pressure gate" + assert observed["reads"] == reads and buffer["backpressured"] + assert _control(source, sender, True) + _confirmed((sender, upstream), True) + assert _control(server, upstream, True) is False + if close_target: + targets[0].close() + gates[1].set() + gates[2].set() + assert wait_until(lambda: not buffer["backpressured"], timeout=10) + assert upstream["user_paused"] and not upstream["backpressure"] + assert upstream["last_requested_state"] and sender["confirmed_state"] + assert buffer["peak"] <= buffer["high_water"] + buffer["max_enqueue"] + assert buffer["peak"] > buffer["high_water"] + assert all(state["owner"] is sock for state, sock in zip(relay["controls"].values(), sockets)) + assert _control(server, upstream, False) + _relay_done(relay_clients, run, failed=close_target) + if close_target: + route = relay["route"] + assert route["completed"] == {targets[1].client_socket.getsockname()} + assert set(route["targets"]) - route["completed"] diff --git a/test/unit/network_api/test_fid_routes.py b/test/unit/network_api/test_fid_routes.py index 01e500a..e5baf41 100644 --- a/test/unit/network_api/test_fid_routes.py +++ b/test/unit/network_api/test_fid_routes.py @@ -168,6 +168,37 @@ def test_registration_rejects_upstream_fid_that_collides_with_live_transfer_iden assert server._fid_route_index == indexes_before +@pytest.mark.parametrize("record", ["false", "preset", "sender", "other_type", "other_direction"]) +def test_route_registration_ignores_control_records_without_live_data_ownership(server, record): + key = (TARGET_1, 303, 0 if record == "other_type" else 1, 0) + if record == "other_direction": + key = (ORIGINATOR, 303, 1, 1) + if record in ("false", "preset"): + server._transfer_pause[key] = record == "preset" + else: + state = server._transfer_controls.register(key, object(), object()) + assert state is not None and not state["confirmed_state"] + paused_before = dict(server._transfer_pause) + controls_before = dict(server._transfer_controls._legs) + + route = server._register_fid_route(303, ORIGINATOR, {TARGET_1: 305}) + + assert route is not None and server._lookup_fid_route(TARGET_1, 305) == (303, route) + assert server._fid_route_index == {(TARGET_1, 305): 303} + assert server._transfer_pause == paused_before + assert server._transfer_controls._legs == controls_before + + +def test_route_registration_refuses_a_live_setup_owner_before_socket_indexing(server): + with socket.socket() as owner: + state = server._transfer_controls.register((TARGET_1, 303, 1, 0), object(), owner) + assert state is not None and server._active_transfer_sockets == {} + routes_before, indexes_before = dict(server._fid_routes), dict(server._fid_route_index) + assert server._register_fid_route(303, ORIGINATOR, {TARGET_1: 305}) is None + assert server._fid_routes == routes_before and server._fid_route_index == indexes_before + assert server._transfer_controls._legs[state["key"]] is state + + def test_registration_scopes_live_downstream_upload_conflicts_by_receiver(server): fid = 303 server.file_upload_progress[(TARGET_2, fid)] = [0, 1, None, "/tmp/live", TARGET_2] diff --git a/test/unit/network_api/test_transfer_control.py b/test/unit/network_api/test_transfer_control.py index 975b4df..a3755ea 100644 --- a/test/unit/network_api/test_transfer_control.py +++ b/test/unit/network_api/test_transfer_control.py @@ -13,6 +13,7 @@ TCP_Client_Base, TCP_Server_Base, _TransferControlRegistry, + _control_key, _is_control_endpoint, _parse_transfer_control_command, _socket_local_endpoint, @@ -402,3 +403,76 @@ def test_public_control_requires_typed_keywords_and_presets_only_exact_senders(o assert owner._transfer_pause == {} and owner._transfer_controls._legs == {} finally: owner.stop() if owner_type is TCP_Server_Base else owner.close() + + +def test_relay_control_prefers_exact_child_and_requires_one_live_same_peer_alias(): + server = TCP_Server_Base.__new__(TCP_Server_Base) + server._forward_relays, server._forward_relays_lock = {}, threading.Lock() + server._fid_route_index = {} + server._transfer_pause_cond = threading.Condition() + registry = _TransferControlRegistry({}, server._transfer_pause_cond) + server._transfer_controls = registry + sock = object() + keys = [(PEER, child, 1, 0) for child in (42, 100, 43)] + states = [registry.register(key, sock, object()) for key in keys] + relays = [{"fid": fid, "route": {"targets": {PEER: key[1]}}, + "controls": {PEER: state}} + for fid, key, state in zip((100, 200, 200), keys, states)] + server._forward_relays.update(zip(((PEER, 42), (PEER, 100)), relays)) + + assert _control_key(server, PEER, 100, 1, 0) == keys[1] + assert _control_key(server, PEER, 200, 1, 0) == keys[1] + assert registry.receive(_control_key(server, PEER, 100, 1, 0), sock, True, + lambda *_: True) + assert [state["confirmed_state"] for state in states] == [False, True, False] + for peer, fid, kind, role in [(("127.0.0.2", 6000), 200, 1, 0), + (PEER, 200, 0, 0), (PEER, 200, 1, 1), + (PEER, 999, 1, 0)]: + assert _control_key(server, peer, fid, kind, role) == (peer, fid, kind, role) + assert not registry.receive(_control_key(server, peer, fid, kind, role), + sock, True, lambda *_: True) + server._forward_relays[(PEER, 43)] = relays[2] + assert not registry.receive(_control_key(server, PEER, 200, 1, 0), sock, True, + lambda *_: True) # Ambiguous upstream alias. + assert registry.release(states[2]) + assert _control_key(server, PEER, 200, 1, 0) == keys[1] + assert registry.release(states[1]) + assert _control_key(server, PEER, 200, 1, 0) == (PEER, 200, 1, 0) + assert not registry.receive(_control_key(server, PEER, 200, 1, 0), sock, True, + lambda *_: True) # Stale relay mappings cannot route. + assert states[0]["confirmed_state"] is False + + +def test_receiver_pressure_and_user_intents_survive_notifications_and_stale_owner(): + pair = _ControlPair() + registry, key, state = pair.registries[1], pair.keys[1], pair.states[1] + pressure = lambda paused: registry.local( + key, paused, pair.send(1), backpressure=True, owner=state["owner"]) + assert pressure(True) + pair.drain() + pair.local(1, True) + pressure(False) + pair.drain() + assert state["user_paused"] and not state["backpressure"] + assert state["confirmed_state"] and state["last_requested_state"] + assert pair.local(0, False) + pair.drain() + assert state["user_paused"] and not state["backpressure"] + assert state["last_requested_state"] and not state["confirmed_state"] + pressure(True) + pair.local(1, False) + pair.drain() + assert not state["user_paused"] and state["backpressure"] + assert state["confirmed_state"] and state["last_requested_state"] + assert pair.local(0, False) + pair.drain() + assert not state["confirmed_state"] and state["backpressure"] + assert state["last_requested_state"] and not state["user_paused"] + pressure(False) + pair.drain() + assert not state["last_requested_state"] and pair.paused == [{}, {}] + assert registry.release(state) + replacement = registry.register(key, pair.sockets[1], object()) + assert not pressure(True) + assert not replacement["backpressure"] and not replacement["user_paused"] + assert not replacement["last_requested_state"] and not any(pair.pending) From 11ba6abd9ee479afdbaceab7bc50d92fb9921a3a Mon Sep 17 00:00:00 2001 From: F18-Ray Date: Mon, 16 Nov 2026 22:17:45 +0800 Subject: [PATCH 05/19] fix(connect_tcp)!: gate ordinary resume on per-object ownership --- PyFlow/network_api/connect_tcp.py | 239 ++++++++++++++---- .../transfer-pause-start-direction-plan.md | 6 +- .../transfer-pause-start-direction-report.md | 86 ++++++- docs/source/File_Transfer/File_Transfer.rst | 13 + docs/source/Network_APIs/TCP_Client_APIs.rst | 5 + docs/source/Network_APIs/TCP_Server_APIs.rst | 5 + docs/source/changes/transfer-fid-routes.md | 21 ++ .../network_api/test_tcp_transfer_control.py | 160 ++++++++++++ .../network_api/test_tcp_transfer_resume.py | 23 +- test/unit/network_api/test_resume_matching.py | 130 +++++++++- .../network_api/test_transfer_handshakes.py | 5 + 11 files changed, 631 insertions(+), 62 deletions(-) diff --git a/PyFlow/network_api/connect_tcp.py b/PyFlow/network_api/connect_tcp.py index 3bd4919..9b6a59c 100644 --- a/PyFlow/network_api/connect_tcp.py +++ b/PyFlow/network_api/connect_tcp.py @@ -620,7 +620,7 @@ def regular_file(path): if (instance.running or instance._config_busy or (instance._config_started and not instance._config_closed) or instance._active_transfer_fids or instance._active_transfer_sockets - or instance._resume_sends): + or instance._resume_sends or instance._receive_transfers): raise RuntimeError("stop the instance and finish active transfers before deletion") if hasattr(instance, "_forward_relays"): with instance._forward_relays_lock: @@ -709,17 +709,89 @@ def _sending_transfer(instance, key): with state["lock"]: yield state finally: - with instance._transfer_progress_lock: + with instance._transfer_progress_changed: state["users"] -= 1 if not state["users"] and not state["targets"]: instance._resume_sends.pop(key, None) + instance._transfer_progress_changed.notify_all() -def _start_resume_send(instance, key, target, send): - """Reserve a target before starting its worker; duplicates join that request.""" +def _ordinary_transfer_busy(instance, key, control_socket): + """Called under the progress lock; closed owners still own final cleanup.""" + if key in instance._active_transfer_fids or key in instance._active_transfer_sockets: + return True + if isinstance(key, tuple): + state = instance._resume_sends.get(key) + if state is not None and (state["users"] or state["targets"]): + return True + peer, fid = key + with instance._transfer_pause_cond: + if (peer, fid, 0, 0) in instance._transfer_controls._legs: + return True + return instance._transfer_handshakes.occupied(control_socket, fid) + return False + + +def _claim_receive(instance, fid, control_socket, owner=None): + """Reserve a resume request or adopt it into its sole receive listener.""" + if fid is None: + return None + with instance._transfer_progress_lock: + if instance._progress_discarded or _ordinary_transfer_busy(instance, fid, control_socket): + return None + record = instance._receive_transfers.get(fid) + if record is not None: + if record["owner"] is not None: + return None + if owner is not None and record["control_socket"] is control_socket: + record["owner"] = owner + return record + if record["deadline"] > time.monotonic(): + return None + record = {"control_socket": control_socket, "owner": owner, + "deadline": time.monotonic() + RESUME_ACCEPT_TIMEOUT} + instance._receive_transfers[fid] = record + return record + + +def _release_receive(instance, fid, record): + with instance._transfer_progress_changed: + if instance._receive_transfers.get(fid) is record: + instance._receive_transfers.pop(fid, None) + instance._transfer_progress_changed.notify_all() + + +def _request_receive_resume(instance, fid, entry, control_socket, origin, target): + record = _claim_receive(instance, fid, control_socket) + if record is None: + return False + sent = False + try: + entry[0] = _resume_offset_for(entry) + sent = instance.send_message(control_socket, format_resume_line(fid, entry[0], origin, target)) + return bool(sent) + finally: + if not sent or not instance.running or control_socket.fileno() < 0: + _release_receive(instance, fid, record) + + +def _discard_receive_requests(instance, control_socket): + with instance._transfer_progress_changed: + for fid, record in list(instance._receive_transfers.items()): + if record["control_socket"] is control_socket and record["owner"] is None: + del instance._receive_transfers[fid] + instance._transfer_progress_changed.notify_all() + + +def _start_resume_send(instance, key, target, send, *, control_socket=None): + """Reserve ordinary recovery once; relay target coalescing is kept separate.""" with instance._transfer_progress_lock: if instance._progress_discarded or key not in instance.file_upload_progress: return False + if control_socket is not None and ( + control_socket.fileno() < 0 or _ordinary_transfer_busy(instance, key, control_socket) + ): + return False state = instance._resume_sends.get(key) if state is None and key in instance._active_transfer_fids: return True # an initial ordinary send already owns this upload @@ -737,10 +809,11 @@ def run(): if entry is not None: send(entry) finally: - with instance._transfer_progress_lock: + with instance._transfer_progress_changed: state["targets"].discard(target) if not state["users"] and not state["targets"]: instance._resume_sends.pop(key, None) + instance._transfer_progress_changed.notify_all() threading.Thread(target=run, daemon=True).start() return True @@ -1743,6 +1816,12 @@ def release_socket(self, control_socket, transfer_socket): if not resources: del self._resources[control_socket] + def occupied(self, control_socket, fid): + """Pending and uncertain negotiations both prevent a second same-FID leg.""" + with self._changed: + key = (control_socket, fid) + return key in self._pending or key in self._unresolved + @staticmethod def _close_socket(sock): try: @@ -2716,6 +2795,8 @@ def __init__( ) self._transfer_progress_lock = threading.RLock() # serialises the persist/load pair self._resume_sends = {} # transient locks and request sets; no file metadata + self._transfer_progress_changed = threading.Condition(self._transfer_progress_lock) + self._receive_transfers = {} # request/listener/data owner until final cleanup self._progress_discarded = False self._config_started = False self._config_closed = False @@ -3267,11 +3348,16 @@ def _release_transfer_socket(self, fid, sock): self._transfer_controls.release_owner(sock) if fid is None: return - with self._transfer_progress_lock: + with self._transfer_progress_changed: if self._active_transfer_sockets.get(fid) is sock: del self._active_transfer_sockets[fid] + self._active_transfer_fids.discard(fid) + record = self._receive_transfers.get(fid) + if record is not None and record["owner"] is sock: + del self._receive_transfers[fid] + self._transfer_progress_changed.notify_all() - def _drop_stale_transfers(self, peer=None): + def _drop_stale_transfers(self, peer=None, *, wait=False): """Close the legs a peer's previous session left behind. A peer that (re)connects proves that the legs of its earlier session @@ -3280,23 +3366,25 @@ def _drop_stale_transfers(self, peer=None): Args: peer (tuple | None): Match the outgoing receiver namespace or incoming progress peer; None clears all tracked legs. + wait (bool): During reconnect only, wait for old worker cleanup. Returns: int: Number of legs closed. """ stale = [] + with self._transfer_progress_lock: + sends = [(key, state) for key, state in self._resume_sends.items() + if peer is None or key[0] == tuple(peer)] if wait else [] for store in (self.file_upload_progress, self.file_recv_progress): for fid, entry in list(store.items()): owner = fid[0] if store is self.file_upload_progress else entry[4] if peer is not None and (owner is None or tuple(owner) != tuple(peer)): continue with self._transfer_progress_lock: - sock = self._active_transfer_sockets.pop(fid, None) - if sock is not None: - self._active_transfer_fids.discard(fid) + sock = self._active_transfer_sockets.get(fid) if sock is not None: - stale.append(sock) - for sock in stale: + stale.append((fid, sock)) + for fid, sock in stale: try: sock.shutdown(socket.SHUT_RDWR) except OSError: @@ -3306,6 +3394,11 @@ def _drop_stale_transfers(self, peer=None): except OSError: pass self._transfer_controls.release_owner(sock) + if wait: + with self._transfer_progress_changed: + self._transfer_progress_changed.wait_for(lambda: all( + self._active_transfer_sockets.get(key) is not sock for key, sock in stale + ) and all(self._resume_sends.get(key) is not state for key, state in sends)) return len(stale) @@ -5260,6 +5353,7 @@ def _unregister_client(self, client_socket, client_address, client_id): """ self._transfer_handshakes.cancel_socket(client_socket) self._transfer_controls.discard_socket(client_socket) + _discard_receive_requests(self, client_socket) with self.client_lock: owns_peer = self.clients.get(client_address, {}).get("socket") is client_socket if owns_peer: @@ -5832,6 +5926,7 @@ def file_transfer_client_recv(client_id): self._log(f"error while starting the file transfer: {e}") self._log_exc() close_socket() + self._release_transfer_socket(progress_fid, client_file_socket) return False try: name_len_bytes = b"" @@ -6037,6 +6132,11 @@ def file_transfer_client_recv(client_id): if resume_entry is not None: # the sender answers this resume with /file; its connection is the continued leg server_file_socket.settimeout(RESUME_ACCEPT_TIMEOUT) + receive_record = _claim_receive(self, progress_fid, client_socket, server_file_socket) + if progress_fid is not None and receive_record is None: + server_file_socket.close() + return + handed_off = False try: if not self._transfer_handshakes.track_socket(client_socket, server_file_socket): return @@ -6045,12 +6145,15 @@ def file_transfer_client_recv(client_id): client_file_socket, client_file_address = server_file_socket.accept() if not self._transfer_handshakes.track_socket(client_socket, client_file_socket): return + if receive_record is not None: + receive_record["owner"] = client_file_socket if resume_entry is not None: client_file_socket.settimeout(None) # the accept timeout is the listener's only self._crypto_attach_transfer_in(client_file_socket, client_socket, stamp) self._register_transfer_socket(progress_fid, client_file_socket) _bind_transfer_control(self, progress_fid, client_socket, client_file_socket, 0, 1) if resume_entry is not None: + handed_off = True threading.Thread( target=file_transfer_client_recv, args=(client_id,), daemon=True ).start() @@ -6059,6 +6162,7 @@ def file_transfer_client_recv(client_id): if is_open_file_transfer == None: pass else: + handed_off = True threading.Thread( target=file_transfer_client_recv, args=(client_id,), daemon=True ).start() @@ -6074,6 +6178,10 @@ def file_transfer_client_recv(client_id): finally: server_file_socket.close() self._transfer_handshakes.release_socket(client_socket, server_file_socket) + if not handed_off: + if client_file_socket is not None: + self._release_transfer_socket(progress_fid, client_file_socket) + _release_receive(self, progress_fid, receive_record) def diff_multiple_file_diff_multiple_client_transfer_server_recv_client_start(self, message): """Send grouped files and folders to their listed clients. @@ -6579,6 +6687,10 @@ def receive_file_transfer_messages(): self.file_upload_progress, transfer_key, file_size, filename, peer=peer, initial=resume_offset, ) + if progress is None: + progress = self.file_upload_progress.get(transfer_key) + if progress is not None: + progress[0] = resume_offset with open(filename, "rb") as f: if resume_offset: f.seek(resume_offset) @@ -6696,13 +6808,7 @@ def _request_resumes(self, peer): continue # not a download from this peer if self._lookup_fid_route(None, fid) is not None: continue # a forwarded transfer: its target drives the resume - with self._transfer_progress_lock: - if fid in self._active_transfer_fids: - continue # a leg is already running for this fid - entry[0] = _resume_offset_for(entry) - if self.send_message( - info["socket"], format_resume_line(fid, entry[0], peer, target) - ): + if _request_receive_resume(self, fid, entry, info["socket"], peer, target): started += 1 return started @@ -6720,7 +6826,7 @@ def resume_trans(self, peer_addr, fid, offset): offset (int): Byte offset the receiver already holds. Returns: - bool: True when the request was queued or joined in flight. + bool: True only for a newly reserved ordinary recovery worker. """ if peer_addr is None: return False @@ -6755,7 +6861,7 @@ def send(entry): finally: self.pfree(client_port) - return _start_resume_send(self, key, peer_addr, send) + return _start_resume_send(self, key, peer_addr, send, control_socket=info["socket"]) def _is_control_local_endpoint(self, endpoint, sock): @@ -6867,7 +6973,7 @@ def _resume_after_connect(self, client_address): Args: client_address (tuple): Value used by the operation. """ - self._drop_stale_transfers(peer=tuple(client_address)) + self._drop_stale_transfers(peer=tuple(client_address), wait=True) self._request_resumes(tuple(client_address)) self._flush_pending_originator_resumes(tuple(client_address)) @@ -7671,6 +7777,7 @@ def stop(self): # shutting down the server for client_info in self.clients.values(): self._transfer_handshakes.cancel_socket(client_info["socket"]) self._transfer_controls.discard_socket(client_info["socket"]) + _discard_receive_requests(self, client_info["socket"]) try: # a client thread blocked in recv() keeps the connection half # open past close(): the shutdown sends its FIN and wakes it @@ -7888,6 +7995,8 @@ def __init__( ) self._transfer_progress_lock = threading.RLock() # serialises the persist/load pair self._resume_sends = {} # transient locks and request sets; no file metadata + self._transfer_progress_changed = threading.Condition(self._transfer_progress_lock) + self._receive_transfers = {} # request/listener/data owner until final cleanup self._progress_discarded = False self._config_started = False self._config_closed = False @@ -8866,11 +8975,16 @@ def _release_transfer_socket(self, fid, sock): self._transfer_controls.release_owner(sock) if fid is None: return - with self._transfer_progress_lock: + with self._transfer_progress_changed: if self._active_transfer_sockets.get(fid) is sock: del self._active_transfer_sockets[fid] + self._active_transfer_fids.discard(fid) + record = self._receive_transfers.get(fid) + if record is not None and record["owner"] is sock: + del self._receive_transfers[fid] + self._transfer_progress_changed.notify_all() - def _drop_stale_transfers(self, peer=None): + def _drop_stale_transfers(self, peer=None, *, wait=False): """Close the legs a peer's previous session left behind. A peer that (re)connects proves that the legs of its earlier session @@ -8879,23 +8993,25 @@ def _drop_stale_transfers(self, peer=None): Args: peer (tuple | None): Match the outgoing receiver namespace or incoming progress peer; None clears all tracked legs. + wait (bool): During reconnect only, wait for old worker cleanup. Returns: int: Number of legs closed. """ stale = [] + with self._transfer_progress_lock: + sends = [(key, state) for key, state in self._resume_sends.items() + if peer is None or key[0] == tuple(peer)] if wait else [] for store in (self.file_upload_progress, self.file_recv_progress): for fid, entry in list(store.items()): owner = fid[0] if store is self.file_upload_progress else entry[4] if peer is not None and (owner is None or tuple(owner) != tuple(peer)): continue with self._transfer_progress_lock: - sock = self._active_transfer_sockets.pop(fid, None) - if sock is not None: - self._active_transfer_fids.discard(fid) + sock = self._active_transfer_sockets.get(fid) if sock is not None: - stale.append(sock) - for sock in stale: + stale.append((fid, sock)) + for fid, sock in stale: try: sock.shutdown(socket.SHUT_RDWR) except OSError: @@ -8905,6 +9021,11 @@ def _drop_stale_transfers(self, peer=None): except OSError: pass self._transfer_controls.release_owner(sock) + if wait: + with self._transfer_progress_changed: + self._transfer_progress_changed.wait_for(lambda: all( + self._active_transfer_sockets.get(key) is not sock for key, sock in stale + ) and all(self._resume_sends.get(key) is not state for key, state in sends)) return len(stale) @@ -9379,7 +9500,7 @@ def connect(self): # connect to server # session and is over. The sweep runs before the receive thread # starts, so a resume request of the new session cannot be # affected by it. - self._drop_stale_transfers() + self._drop_stale_transfers(wait=True) self.receive_thread = threading.Thread( target=self.receive_messages ) # set up get msg thread @@ -9518,6 +9639,7 @@ def receive_messages(self): # get server msg break self._transfer_handshakes.cancel_socket(control_socket) self._transfer_controls.discard_socket(control_socket) + _discard_receive_requests(self, control_socket) def send_message(self, client_socket, message, is_send_raw=False): # send msg to server @@ -10887,6 +11009,10 @@ def receive_file_transfer_messages(): self.file_upload_progress, transfer_key, file_size, filename, peer=peer, initial=resume_offset, ) + if progress is None: + progress = self.file_upload_progress.get(transfer_key) + if progress is not None: + progress[0] = resume_offset with open(filename, "rb") as f: if resume_offset: f.seek(resume_offset) @@ -11001,17 +11127,23 @@ def _request_resumes(self): for fid, entry in list(self.file_recv_progress.items()): if entry[4] is None: continue # without a peer there is nobody to continue with - with self._transfer_progress_lock: - if fid in self._active_transfer_fids: - continue # a leg is already running for this fid + is_direct = _is_control_endpoint(entry[4], configured_peer, connected_peer) if connected_peer is not None and tuple(entry[4]) == configured_peer: entry[4] = connected_peer - entry[0] = _resume_offset_for(entry) - if self.send_message( - self.client_socket, - format_resume_line(fid, entry[0], entry[4], self.client_socket.getsockname()), - ): - started += 1 + if is_direct: + started += _request_receive_resume( + self, fid, entry, self.client_socket, entry[4], self.client_socket.getsockname() + ) + else: + with self._transfer_progress_lock: + if fid in self._active_transfer_fids: + continue # relay eligibility is handled separately + entry[0] = _resume_offset_for(entry) + if self.send_message( + self.client_socket, + format_resume_line(fid, entry[0], entry[4], self.client_socket.getsockname()), + ): + started += 1 return started @@ -11021,8 +11153,8 @@ def resume_trans(self, peer_addr, fid, offset): Server-bound uploads answer with ``/file``; other final targets replay through the server with the stable upstream fid. The retained upload path is sufficient because the receiver owns its full destination path. - Runtime locks coalesce duplicate targets and serialize different - targets without persisting file metadata. + Ordinary recovery skips any live, paused, negotiating or finalizing owner. + Relay target serialization remains separate from ordinary recovery. Args: peer_addr (tuple | None): Final receiver; None selects the server. @@ -11030,7 +11162,7 @@ def resume_trans(self, peer_addr, fid, offset): offset (int): Byte offset the receiver already holds. Returns: - bool: True when the request was queued or joined in flight. + bool: True for newly reserved ordinary recovery; False when busy. """ server_peer = (self.host, self.port) control_socket = self.client_socket @@ -11075,7 +11207,9 @@ def send(entry): finally: self.pfree(client_port) - return _start_resume_send(self, key, target, send) + return _start_resume_send( + self, key, target, send, control_socket=control_socket if is_direct else None + ) # ---- native in-memory forward (client side) ---------------------------- @@ -11498,6 +11632,7 @@ def file_transfer_client_recv(client_id): self._log(f"error while starting the file transfer: {e}") self._log_exc() close_socket() + self._release_transfer_socket(progress_fid, client_file_socket) return False try: name_len_bytes = b"" @@ -11681,6 +11816,7 @@ def file_transfer_client_recv(client_id): server_file_socket.close() return progress_fid = _transfer_fid(command_part) # keys this leg in file_recv_progress + is_direct = parse_forward_originator(command, self._own_address_text()) is None resume_entry = _resumable_entry(self.file_recv_progress, progress_fid, peer, command_part) destination_path = _parse_destination_path(command_part) stamp = self._crypto_transfer_stamp( @@ -11693,6 +11829,13 @@ def file_transfer_client_recv(client_id): if resume_entry is not None: # the sender answers this resume with /file; its connection is the continued leg server_file_socket.settimeout(RESUME_ACCEPT_TIMEOUT) + receive_record = _claim_receive( + self, progress_fid, client_socket, server_file_socket + ) if is_direct else None + if is_direct and progress_fid is not None and receive_record is None: + server_file_socket.close() + return + handed_off = False try: if not self._transfer_handshakes.track_socket(client_socket, server_file_socket): return @@ -11701,6 +11844,8 @@ def file_transfer_client_recv(client_id): client_file_socket, client_file_address = server_file_socket.accept() if not self._transfer_handshakes.track_socket(client_socket, client_file_socket): return + if receive_record is not None: + receive_record["owner"] = client_file_socket if resume_entry is not None: client_file_socket.settimeout(None) # the accept timeout is the listener's only self._crypto_attach_transfer_in(client_file_socket, client_socket, stamp) @@ -11710,6 +11855,7 @@ def file_transfer_client_recv(client_id): self, progress_fid, client_socket, client_file_socket, trans_type, 1 ) if resume_entry is not None: + handed_off = True threading.Thread( target=file_transfer_client_recv, args=(client_id,), daemon=True ).start() @@ -11718,6 +11864,7 @@ def file_transfer_client_recv(client_id): if is_open_file_transfer == None: pass else: + handed_off = True threading.Thread( target=file_transfer_client_recv, args=(client_id,), daemon=True ).start() @@ -11733,6 +11880,10 @@ def file_transfer_client_recv(client_id): finally: server_file_socket.close() self._transfer_handshakes.release_socket(client_socket, server_file_socket) + if not handed_off: + if client_file_socket is not None: + self._release_transfer_socket(progress_fid, client_file_socket) + _release_receive(self, progress_fid, receive_record) @_config_lifecycle(starting=False) def close(self): # close connection @@ -11748,6 +11899,7 @@ def close(self): # close connection if self.client_socket: self._transfer_handshakes.cancel_socket(self.client_socket) self._transfer_controls.discard_socket(self.client_socket) + _discard_receive_requests(self, self.client_socket) try: # the receive thread may be blocked in recv() on this socket: # close() alone sends no FIN and leaves that read waiting for its @@ -11797,6 +11949,7 @@ def _release_client_socket(self): return self._transfer_handshakes.cancel_socket(sock) self._transfer_controls.discard_socket(sock) + _discard_receive_requests(self, sock) try: sock.setsockopt(socket.SOL_SOCKET, socket.SO_LINGER, struct.pack("ii", 1, 0)) except OSError: diff --git a/docs/plans/transfer-pause-start-direction-plan.md b/docs/plans/transfer-pause-start-direction-plan.md index e74b750..bc72b5f 100644 --- a/docs/plans/transfer-pause-start-direction-plan.md +++ b/docs/plans/transfer-pause-start-direction-plan.md @@ -1,6 +1,6 @@ # 双向文件暂停、继续与按对象恢复 — 需求卡与更改计划 -状态:**C1–C2b 已通过人工放行;C3 已实现并完成局部验证,待人工审查**。需求卡和七项拆分已确认。C3 完成转发精确控制与共享上游背压验收;恢复资格仍按 C4a/C4b。C4–C5 尚未开始。每个原子变更完成后另附验证报告并等待审查。不自行提交、合并或推送。证据见[实施报告](transfer-pause-start-direction-report.md)。 +状态:**C1–C3 已通过人工放行;C4a 已实现并完成局部验证,待人工审查**。需求卡和七项拆分已确认。C4a 完成普通对象级恢复资格与原子占用,转发共享 source 恢复仍按 C4b。C4b、C5 尚未开始。每个原子变更完成后另附验证报告并等待审查。不自行提交、合并或推送。证据见[实施报告](transfer-pause-start-direction-report.md)。 ## 1. 需求卡 @@ -188,7 +188,7 @@ relay 高水位证据按实际入队粒度计算:记录高水位、单次 enqu ## 6. 验收命令与报告要求 -各阶段定向证据见实施报告。C1:81 passed;C2a:154 passed,修复参数化告警后受影响 64 项通过。C2b 首轮 223 passed、2 failed、1 skipped;tracking off EOF 旧行清理修复后原失败两项通过,owner 等待隔离检查 134 passed,既有受影响回归 159 passed。C3 控制/路由/实际连接验证 217 passed、3 deselected;既有转发/恢复回归 20 passed、73 deselected。实际命令与证据边界见报告,不将 deselected 计为已运行。C4–C5 命令尚未运行;C5 再进行一次相关合并回归,不反复运行整个仓库。 +各阶段定向证据见实施报告。C1:81 passed;C2a:154 passed,修复参数化告警后受影响 64 项通过。C2b 首轮 223 passed、2 failed、1 skipped;修复后原失败两项通过,owner 定向检查 134 passed,既有受影响回归 159 passed。C3 主验证 217 passed、3 deselected;既有转发/恢复 20 passed、73 deselected。C4a 新资格/实际连接 42 passed、66 deselected;既有受影响首轮 139 passed、2 failed、14 deselected,旧清扫契约迁移后两项通过;重连最终占用检查 34 passed,最后监听交接双向场景 2 passed。实际命令和边界见报告,不将定向重跑计作全量复跑;C4b/C5 命令尚未运行。 ```bash # C1/C2a:实现后新增必要边界契约 @@ -220,4 +220,4 @@ relay 高水位证据按实际入队粒度计算:记录高水位、单次 enqu - **持久化数据模型不变**;运行时控制记录改变。查询返回 schema 不变。测试增加必要边界契约及迁移受影响断言,不降低验证强度。 - **CI/依赖/覆盖率策略不变**。不宣称本计划覆盖未运行的多平台环境、NAT、多进程共享或任意网络中断组合。 - 新功能依赖存活且可投递的控制连接;仅有数据 socket 存活但控制连接不可用时,不承诺远程 pause/start。自然关闭路径按既有机制结束旧 leg。 -- 用户已放行 C3;本阶段已完成转发控制与背压实现、定向验证和局部报告,待人工审查。resume 活跃对象返回 False 的资格门槛仍在 C4a/C4b 实施,不自行进入 C4。本轮未创建提交、合并或推送。 +- 用户已授权开始 C4a,C3 随该放行进入下一阶段。C4a 已完成普通恢复资格、原子占用、旧 leg 控制清理及局部验证/报告,待人工审查。实际范围超出原预估,原因与审查注意已列报告。转发共享 source/pending 资格和最终总验收仍在 C4b/C5,不自行进入下一阶段。本轮未创建提交、合并或推送。 diff --git a/docs/plans/transfer-pause-start-direction-report.md b/docs/plans/transfer-pause-start-direction-report.md index 37c9f88..7b7b617 100644 --- a/docs/plans/transfer-pause-start-direction-report.md +++ b/docs/plans/transfer-pause-start-direction-report.md @@ -1,6 +1,6 @@ # 双向文件暂停、继续与按对象恢复 — 实施报告 -状态:需求卡和七项拆分已确认。**C1–C2b 已通过人工放行;C3 已实现并完成局部验证,待人工审查;C4–C5 未开始。** 本报告随已完成的原子变更增补,不将未实现或未运行的路径标为完成。本轮未创建提交、合并或推送。 +状态:需求卡和七项拆分已确认。**C1–C3 已通过人工放行;C4a 已实现并完成局部验证,待人工审查;C4b、C5 未开始。** 本报告随已完成的原子变更增补,不将未实现或未运行的路径标为完成。本轮未创建提交、合并或推送。 ## C1:严格解析、typed identity 与共享端点识别 @@ -279,7 +279,89 @@ C2a 后续审查结论:用户已审计放行,并明确授权开始 C2b,包 - 自动请求与用户意图汇总不改变发送端权威规则:source 本地 start 可暂时确认运行,reader 仍自行守住高水位;后续请求按 source 处理顺序决定状态。返回 True 仍只表示控制操作登记,非逐请求 ACK。 - 本轮未改公共签名、wire 格式、持久化 schema、CI、依赖或覆盖率策略;未删除或弱化既有测试。新测试使用真实 socket/加密、事件屏障和实际内容/ACK,未运行 formatter、lint、文档构建、repo-wide suite 或多平台验证。 - C3 保留小范围生产修改并补充两目标契约(集成新增 241 行);文档/报告与测试也是本次审查的一部分。完成范围仅为上表证据,不宣称所有断线/网络时序组合已枚举。 -- **C3 待人工审查,未创建提交**。C4a/C4b 与 C5 未开始。 +- C3 后续结论:用户已授权开始 C4a,C3 随该放行进入下一阶段。C4a 实施与独立待审事项见下节。 + +## C4a:普通对象级恢复资格与原子占用 + +### 提交意图与数据流 + +让普通恢复仅接纳已中断、无活动 owner 的具体文件对象;活跃、暂停、建连、重复恢复及仍在最终清理的对象静默返回 False,不关闭或排队等待。其他 fid 和相反方向不阻挡该对象。公共签名和 resume wire 不变。 + +- Server/Client 普通 `resume_trans` → 既有 peer/进度行匹配 → progress lock 内检查 scoped active socket/fid、发送 worker、typed sender owner 和同 socket/FID 的 pending/unresolved 握手 → 原子登记一个恢复 worker → 原有安全握手和 file_transfer_mode → 真实内容/最终 ACK → owner 释放。 +- 接收端 `_request_resumes` → 同一个 per-fid 资格边界 → 请求占用 → 收到 `/file` 时同会话 listener 接管 → accept 后数据 owner 接管 → 最终进度清理后释放。重复请求/监听不能创建第二条 leg;发送失败释放请求,未回应请求按既有 accept 超时期限允许重新申请,会话结束清理无 owner 请求。 +- 数据 socket 关闭不会立即抹掉 registry 所有权;旧 worker 的最终清理仍阻挡恢复。重连 sweep 关闭旧 socket 并等待其 owner/外层发送记录结束,然后沿现有自动恢复流程继续;手动活跃请求不进入等待。 +- tracking off 不创建新进度行;恢复已有上传/下载行时,该 leg 持有旧行完成清理。暂停/断线清除旧控制状态,新恢复 leg 默认 running,fid 和接收完整路径保持。 + +### 变更范围与局部止血 + +实现集中在 `PyFlow/network_api/connect_tcp.py`。新增普通接收请求/监听占用与 progress Condition、握手 occupied 判定;普通发送恢复使用原子占用,转发 target 合并/共享 source 资格留给 C4b。现有 socket shutdown、加密和文件 ACK 机制继续使用。 + +测试修改位于 `test_resume_matching.py`、`test_transfer_handshakes.py`、`test_tcp_transfer_control.py`、`test_tcp_transfer_resume.py`。旧清扫断言从“close 即释放”迁移为“worker 最终释放”,保留不同 receiver/方向隔离及最终清理断言。补充控制在线、双向恢复、tracking off、建连前/清理中拒绝,以及旧 socket 已移除但外层发送 owner 仍在的重连等待契约。三份 File_Transfer/TCP API RST、变更记录、计划和本报告同步更新。 + +### 局部验证与运行证据 + +新资格、握手及实际连接场景: + +```bash +.venv/bin/python -m pytest test/unit/network_api/test_resume_matching.py test/unit/network_api/test_transfer_handshakes.py test/integration/network_api/test_tcp_transfer_control.py -k 'resume or control_disconnect_releases' -q +``` + +**42 passed、66 deselected in 75.32s**(墙钟 76.40s)。实际上传/下载各覆盖 plain alias、encrypted、encrypted async/tracking off wildcard: + +- 中断真实 data socket,control socket 始终在线;落盘 partial 内容先核对。旧 sender/receiver 完成退出后,两个并发恢复调用只有一个 True;活动、暂停、pending handshake、接收 listener 及旧 finally 屏障期间均拒绝第二次恢复。 +- sender bookkeeping 与 receiver 行值被刻意设成不同于实际磁盘长度;接收请求使用磁盘 offset,恢复 worker 实际参数保留原 fid/offset,接收完整文件等于 payload,sender 得到真实最终 ACK。 +- 另一条相反方向传输在整个恢复期间保持原 socket 和暂停状态;随后可独立完成。新 owner 不继承旧 pause,结束时进度、控制记录、socket 和恢复占用清理。 +- 真实 control shutdown 唤醒双向暂停 leg;旧线程退出,所有新控制意图/暂停键及对象占用释放,包含 tracking off。未用人工 sweep 替代断线证据。 + +受影响既有普通恢复/配置/查询契约: + +```bash +.venv/bin/python -m pytest test/integration/network_api/test_tcp_transfer_resume.py test/unit/network_api/test_transfer_handshakes.py test/unit/network_api/test_delete_config.py test/unit/network_api/test_transfer_progress_query.py -k 'not forward and not unified_resume_serializes' -q +``` + +首轮 **139 passed、2 failed、14 deselected in 151.66s**。两项失败均为旧清扫契约要求 socket 关闭立即删除 active 索引,与本次保留 owner 到最终清理的契约冲突。迁移断言位置/增加关闭后 owner 仍保留的断言,未弱化隔离、内容、ACK 或最终释放: + +```bash +.venv/bin/python -m pytest test/integration/network_api/test_tcp_transfer_resume.py::test_equal_server_upload_fids_are_isolated_by_receiver test/integration/network_api/test_tcp_transfer_resume.py::test_equal_inbound_and_outbound_fids_cleanup_only_their_own_sockets -q +``` + +**2 passed in 4.92s**。不将定向重跑记作全量复跑成功。 + +自动重连等待补强后,执行实际 upload/download 自动重连及恢复单位契约: + +```bash +.venv/bin/python -m pytest test/unit/network_api/test_resume_matching.py test/integration/network_api/test_tcp_transfer_resume.py::test_upload_resumes_after_a_reconnect test/integration/network_api/test_tcp_transfer_resume.py::test_download_resumes_after_connect_without_a_manual_call -q +``` + +**34 passed in 12.05s**。新增事件屏障契约确认:即使 data socket 已释放,外层旧发送记录退出之前,重连清扫仍等待;记录退出的 Condition 通知使等待结束。 + +接收 claim 调整至安全/listener 初始化后、首次公告前,避免初始化失败残留占用。仅重跑受影响的 plain 双向实际恢复场景: + +```bash +.venv/bin/python -m pytest 'test/integration/network_api/test_tcp_transfer_control.py::test_online_resume_reserves_one_owner_and_uses_receiver_disk_offset[plain-alias-upload]' 'test/integration/network_api/test_tcp_transfer_control.py::test_online_resume_reserves_one_owner_and_uses_receiver_disk_offset[plain-alias-download]' -q +``` + +**2 passed in 13.33s**。 + +### 路径对照与明确未覆盖 + +| 路径 | C4a 结论与证据边界 | +|---|---| +| P14 | 控制连接在线、进度有行但无数据 owner 时,普通上传/下载可以恢复;receiver 实际落盘 offset、原 fid、最终内容/ACK 均有真实证据,另一活跃反向文件保留原 socket | +| P15 | 运行、暂停、握手、重复恢复、接收 request/listener 和旧 owner 最终清理期间拒绝恢复;屏障并发只接纳一个 worker,不排队、不关闭活跃对象 | +| P17 | 普通双向真实 control shutdown 清理新控制记录、暂停键、数据 socket 和 worker;数据中断后新 owner 默认 running;最终清理中恢复被拒绝。转发 source/target 与跨会话迟到清理的完整验收在 C4b | +| P12/P13 | 新普通恢复场景含配置别名、encrypted async/tracking off wildcard;保留 control socket 身份,不新增未跟踪进度行。转发会话身份仍按 C4b 验收 | +| P18 | 受影响 query/config 契约通过;接收占用纳入配置删除门槛,恢复完成和会话关闭清理占用,持久化 schema 不变。新增接收占用与 stop/config 删除的专门交叉验收仍在 C4b/C5 | +| P10/P16 | 本轮未切换 relay 共享 source/live leg/pending-originator 资格;既有 relay target 合并行为保留,由 C4b 统一处理 | + +### 风险与审查注意 + +- `True` 仅表示普通恢复 worker 已原子预留,不表示恢复已成功;最终文件 ACK 才是完成证据。完整但未确认的 EOF 行仍可恢复,以完成确认。 +- 重连流程等待已结束会话的 owner 最终清理,不通过先删索引抢占资格;等待使用 Condition,无新增自动重试。手动请求遇到占用直接 False。 +- 未应答 receive 请求保留无数据 owner 的短期占用,按 RESUME_ACCEPT_TIMEOUT 期限在后续请求时允许替换;实际 listener/data owner 不按时钟强制替换。失败发送/会话关闭立即清理请求;这不是逐请求完成 future。 +- 实际范围比原 180–300 行预估更大,原因是发送资格之外必须同时覆盖接收请求、监听交接和自动重连清理。审查应连同新增契约与报告评估该规模偏差;未擅自增加 C4b 的转发资格或拆出混用新旧资格的中间阶段。 +- 本轮未改公共签名、wire、progress JSON schema、CI、依赖或覆盖率策略;没有删除测试或弱化内容/ACK/隔离断言。未执行 repo-wide suite、formatter、lint、文档构建或多平台检查。语言服务仅 Ruff,references 请求返回 -32601,不能记作成功的引用分析。 +- **C4a 待人工审查,未创建提交**。C4b 与 C5 未开始。 ## 公共协议/API 变更许可记录 diff --git a/docs/source/File_Transfer/File_Transfer.rst b/docs/source/File_Transfer/File_Transfer.rst index 73ff9c3..f623dd6 100644 --- a/docs/source/File_Transfer/File_Transfer.rst +++ b/docs/source/File_Transfer/File_Transfer.rst @@ -869,6 +869,19 @@ also returns ``False`` while retaining that pause for registration. Pause state is runtime-only and is never persisted. Reconnect cleanup releases paused waiters, clears their state and closes the old sockets before replay. +Ordinary recovery is per object: ``resume_trans(peer_addr, fid, offset)`` +returns ``True`` only when a new recovery worker is reserved. A running, +paused, negotiating or still-finalizing owner returns ``False`` without closing +its socket or queueing another attempt. Use ``start_trans`` for a paused live +leg. Other files and opposite-direction legs do not block an interrupted file. +The control connection may stay online while a failed data connection is +replaced; the receiver requests its actual disk size, retaining the same fid. +Concurrent requests share one eligibility/reservation boundary. Receive +requests and listeners also reserve that object until handoff or failure. +Old workers release ownership only after progress cleanup; a new leg starts +running rather than inheriting the old pause. Existing retained rows can be +recovered with tracking disabled without creating new progress rows. + The temporary connections of a transfer are resumed after a disconnect: - when a connection drops, both sides write their transfer stores to diff --git a/docs/source/Network_APIs/TCP_Client_APIs.rst b/docs/source/Network_APIs/TCP_Client_APIs.rst index 9128ffc..81119e3 100644 --- a/docs/source/Network_APIs/TCP_Client_APIs.rst +++ b/docs/source/Network_APIs/TCP_Client_APIs.rst @@ -310,6 +310,11 @@ commands sent by the server, such as: supplies the source path; a non-server target is replayed through the server with its stable upstream fid. The receiver's retained full path handles folder items without copying directory or destination metadata at the source. + Direct uploads recover only when no live, paused, negotiating or finalizing + owner holds that object. ``resume_trans`` returns ``True`` for a newly reserved + worker; busy and duplicate calls return ``False`` without closing or queueing. + Another file or opposite direction does not prevent recovery. A paused live + connection continues through ``start_trans`` instead. For a new relay upload, the source client allocates the upstream FID before it sends ``/forward_item ... fid=``. The server returns that same upstream FID diff --git a/docs/source/Network_APIs/TCP_Server_APIs.rst b/docs/source/Network_APIs/TCP_Server_APIs.rst index dbe164d..4868c39 100644 --- a/docs/source/Network_APIs/TCP_Server_APIs.rst +++ b/docs/source/Network_APIs/TCP_Server_APIs.rst @@ -697,6 +697,11 @@ Built-in client commands include: sender, translates to the stable upstream fid, and forwards the same command. Unknown or mismatched identities never fall back to another route (see :ref:`transfer-pause-and-reconnect`). No fid kind selects this branch. + Ordinary local uploads recover only when no live, paused, negotiating or + finalizing owner holds that scoped object. ``resume_trans`` returns ``True`` + for a newly reserved worker; busy and duplicate calls return ``False`` without + closing or queueing. Other objects remain independent. Use ``start_trans`` + to continue an existing paused connection. - Forwarded transfers return the existing final data-ACK marker upstream only after the current input stream is complete and every accepted target has acknowledged. The normal send path reframes the marker for the upstream hop; diff --git a/docs/source/changes/transfer-fid-routes.md b/docs/source/changes/transfer-fid-routes.md index 61b9d6d..4c32a85 100644 --- a/docs/source/changes/transfer-fid-routes.md +++ b/docs/source/changes/transfer-fid-routes.md @@ -411,3 +411,24 @@ file preservation. Runtime evidence and explicit exclusions are recorded in failure without a false upstream success ACK. C4 resume eligibility remains outside this change. +## Transfer control C4a: ordinary per-object resume eligibility + +- Ordinary resume atomically reserves one recovery worker only after the + scoped data owner, negotiation and prior cleanup have finished. Running, + paused, negotiating and duplicate requests return False without closing or + queueing. Independent files and opposite directions do not block recovery. +- Receive requests reserve the object before sending; the same session's + listener and data owner adopt the reservation. Failed sends, listener + failures and session closure release it; pending unanswered requests use the + existing accept-timeout window. Reconnect waits for old owner cleanup, while + manual busy requests return immediately. +- A failed data connection can recover on the same live control connection + from the receiver's disk offset and original FID. New owners do not inherit + pause state. Tracking-off recovery adopts retained progress rows for final + cleanup without creating new tracked rows. +- New eligibility/real-connection checks passed 42 tests; the affected existing + run had 139 passes and two obsolete immediate-sweep-release assertions, both + passing after migration to final owner release. Reconnect ownership checks + passed 34 tests, and the final listener-handoff check passed both directions. + Full commands and exclusions are in the C4a report. Relay recovery remains C4b. + diff --git a/test/integration/network_api/test_tcp_transfer_control.py b/test/integration/network_api/test_tcp_transfer_control.py index 60fdcca..1797179 100644 --- a/test/integration/network_api/test_tcp_transfer_control.py +++ b/test/integration/network_api/test_tcp_transfer_control.py @@ -2,6 +2,7 @@ import os import shlex +import socket import threading from pathlib import Path @@ -626,3 +627,162 @@ def test_relay_pressure_preserves_user_intent_and_source_start_cannot_open_reade route = relay["route"] assert route["completed"] == {targets[1].client_socket.getsockname()} assert set(route["targets"]) - route["completed"] + + +@pytest.mark.parametrize("server_sends", [False, True], ids=["upload", "download"]) +def test_online_resume_reserves_one_owner_and_uses_receiver_disk_offset( + channel, tmp_path, monkeypatch, server_sends +): + other = _leg(channel, tmp_path, monkeypatch, not server_sends) + leg = _leg(channel, tmp_path, monkeypatch, server_sends, offset=1) + sender, receiver, states, body_release, worker, result, output, payload = leg + peer, fid = key = states[0]["key"][:2] + old_socket, control = states[0]["owner"], states[0]["control_socket"] + old_other_socket = other[2][0]["owner"] + # Retained rows remain resumable with tracking off; no new tracked leg is invented. + old_progress = sender.file_upload_progress.setdefault( + key, [1, len(payload), None, str(tmp_path / output.name), peer], + ) + partial, interrupt, cleaning, cleaned, negotiating, negotiated, listening, announced, resumed, finish = ( + threading.Event() for _ in range(10) + ) + channel[2].extend((interrupt, cleaned, negotiated, announced, finish)) + real_wait, real_release = connect_tcp._wait_transfer_control, sender._release_transfer_socket + + def hold_body(instance, state, sock): + if instance is sender and state is not None and state["key"] == states[0]["key"]: + entered, release = (partial, interrupt) if state is states[0] else (resumed, finish) + entered.set() + assert release.wait(timeout=20) + return real_wait(instance, state, sock) + + def hold_cleanup(transfer_key, sock): + if transfer_key == key and sock is old_socket: + cleaning.set() + assert cleaned.wait(timeout=20) + return real_release(transfer_key, sock) + + monkeypatch.setattr(connect_tcp, "_wait_transfer_control", hold_body) + monkeypatch.setattr(sender, "_release_transfer_socket", hold_cleanup) + assert sender.resume_trans(peer, fid, 0) is False # paused live owner + assert _control(sender, states[0], False) + _confirmed(states, False) + assert sender.resume_trans(peer, fid, 0) is False # running, before first body write + body_release.set() + assert partial.wait(timeout=10) # the second wait follows one real chunk + disk = 1 + sender.file_transfer_chunk_len + assert wait_until(lambda: output.stat().st_size == disk) + assert _control(sender, states[0], True) + _confirmed(states, True) + old_socket.shutdown(socket.SHUT_RDWR) # keep the existing control session + interrupt.set() + assert cleaning.wait(timeout=10) + assert old_socket.fileno() < 0 and sender._active_transfer_sockets[key] is old_socket + assert sender.resume_trans(peer, fid, disk) is False # closed, but old finally still owns it + cleaned.set() + worker.join(timeout=10) + assert not worker.is_alive() and result == {"ack": False} + assert wait_until(lambda: fid not in receiver._active_transfer_sockets + and fid not in receiver._receive_transfers) + assert sender.file_upload_progress[key] is old_progress + assert output.read_bytes() == payload[:disk] + old_progress[0] = len(payload) - 1 # sender bookkeeping cannot choose the receiver's seek + receiver.file_recv_progress[fid][0] = 1 + requests, calls, resumed_result = [], [], {} + real_request = connect_tcp._send_transfer_request + real_send, real_mode = receiver.send_message, sender.file_transfer_mode + + def hold_request(instance, record, command): + if instance is sender and record["key"] == (control, fid): + requests.append(command) + negotiating.set() + assert negotiated.wait(timeout=20) + return real_request(instance, record, command) + + def hold_listener(sock, message, is_send_raw=False): + port = connect_tcp._parse_transfer_port_announcement(message) if isinstance(message, str) else None + if port is not None and port[1] == fid: + listening.set() + assert announced.wait(timeout=20) + return real_send(sock, message, is_send_raw=is_send_raw) + + def observe_mode(*args, **kwargs): + calls.append((kwargs["fid"], kwargs["resume_offset"], threading.current_thread())) + resumed_result["ack"] = real_mode(*args, **kwargs) + return resumed_result["ack"] + + monkeypatch.setattr(connect_tcp, "_send_transfer_request", hold_request) + monkeypatch.setattr(receiver, "send_message", hold_listener) + monkeypatch.setattr(sender, "file_transfer_mode", observe_mode) + barrier, accepted = threading.Barrier(3), [] + + def resume(): + barrier.wait(timeout=10) + accepted.append(sender.resume_trans(peer, fid, disk)) + + contenders = [threading.Thread(target=resume, daemon=True) for _ in range(2)] + for contender in contenders: + contender.start() + barrier.wait(timeout=10) + for contender in contenders: + contender.join(timeout=10) + assert not contender.is_alive() + assert sorted(accepted) == [False, True] + assert negotiating.wait(timeout=10) + assert sender._transfer_handshakes.occupied(control, fid) + assert sender.resume_trans(peer, fid, disk) is False + request_resumes = (lambda: receiver._request_resumes(states[1]["key"][0])) if receiver is channel[0] else receiver._request_resumes + assert request_resumes() == 1 + assert receiver.file_recv_progress[fid][0] == disk + assert request_resumes() == 0 # pending receiver request + negotiated.set() + assert listening.wait(timeout=10) + assert request_resumes() == 0 # existing listener, before its real announcement + assert sender.resume_trans(peer, fid, disk) is False + announced.set() + assert resumed.wait(timeout=15) + assert wait_until(lambda: all(state["key"] in owner._transfer_controls._legs + for owner, state in zip((sender, receiver), states))) + new_states = tuple(owner._transfer_controls._legs[state["key"]] + for owner, state in zip((sender, receiver), states)) + _confirmed(new_states, False) # the interrupted owner's pause was discarded + assert all(new["owner"] is not old["owner"] and new["control_socket"] is old["control_socket"] + for new, old in zip(new_states, states)) + assert sender._active_transfer_sockets[key] is new_states[0]["owner"] + assert len(calls) == 1 and calls[0][:2] == (fid, disk) + assert sender.resume_trans(peer, fid, disk) is False + assert _control(sender, new_states[0], True) + _confirmed(new_states, True) + assert sender.resume_trans(peer, fid, disk) is False + assert request_resumes() == 0 + assert len(requests) == 1 and shlex.split(requests[0])[-1] == str(fid) + assert all(state["confirmed_state"] for state in other[2]) + assert other[0]._active_transfer_sockets[other[2][0]["key"][:2]] is old_other_socket + assert _control(sender, new_states[0], False) + _complete((sender, receiver, new_states, finish, calls[0][2], resumed_result, output, payload)) + assert wait_until(lambda: key not in sender._resume_sends + and key not in sender._active_transfer_sockets + and fid not in receiver._receive_transfers) + assert len(requests) == len(calls) == 1 + assert _control(other[0], other[2][0], False) + _complete(other) + + +@pytest.mark.parametrize("server_sends", [False, True], ids=["upload", "download"]) +def test_control_disconnect_releases_paused_ordinary_workers(channel, tmp_path, monkeypatch, server_sends): + leg = _leg(channel, tmp_path, monkeypatch, server_sends) + sender, receiver, states, release, worker, result, *_ = leg + server, client, _ = channel + peer = client.client_socket.getsockname() + client.client_socket.shutdown(socket.SHUT_RDWR) + assert wait_until(lambda: not client.running and peer not in server.clients) + assert wait_until(lambda: all(state["key"] not in owner._transfer_controls._legs + for owner, state in zip((sender, receiver), states))) + release.set() + worker.join(timeout=15) + assert not worker.is_alive() and result == {"ack": False} + assert wait_until(lambda: all(not owner._active_transfer_sockets and not owner._receive_transfers + and not owner._transfer_controls._legs and not owner._resume_sends + and not owner._transfer_pause for owner in (sender, receiver))) + assert all(state["owner"].fileno() < 0 and not state["confirmed_state"] + and not state["last_requested_state"] for state in states) diff --git a/test/integration/network_api/test_tcp_transfer_resume.py b/test/integration/network_api/test_tcp_transfer_resume.py index f4e34e4..ac779b0 100644 --- a/test/integration/network_api/test_tcp_transfer_resume.py +++ b/test/integration/network_api/test_tcp_transfer_resume.py @@ -313,8 +313,6 @@ def send(receiver, src): assert server._drop_stale_transfers(receivers[0]) == 1 assert sockets[0].fileno() == -1 - assert keys[0] not in server._active_transfer_sockets - assert keys[0] not in server._active_transfer_fids assert server._active_transfer_sockets[keys[1]] is sockets[1] assert keys[1] in server._active_transfer_fids @@ -323,6 +321,8 @@ def send(receiver, src): server.start_trans(fid, receivers[0], trans_type=0, direction=0) senders[0].join(timeout=15) assert not senders[0].is_alive(), "the cleared upload did not stop" + assert keys[0] not in server._active_transfer_sockets + assert keys[0] not in server._active_transfer_fids assert results[receivers[0]] is False assert server.file_upload_progress[keys[1]] is rows[1] assert rows[1][0] == 0 @@ -435,10 +435,12 @@ def test_equal_inbound_and_outbound_fids_cleanup_only_their_own_sockets(tmp_path assert instance._drop_stale_transfers(inbound_peer) == 1 assert inbound_remote.recv(1) == b"" - assert fid not in instance._active_transfer_sockets - assert fid not in instance._active_transfer_fids + assert instance._active_transfer_sockets[fid] is inbound + assert fid in instance._active_transfer_fids instance._file_progress_finish(instance.file_recv_progress, fid, recv_entry) instance._release_transfer_socket(fid, inbound) + assert fid not in instance._active_transfer_sockets + assert fid not in instance._active_transfer_fids assert fid not in instance.file_recv_progress assert instance.file_upload_progress[upload_key] is upload_entry assert upload_key in instance._active_transfer_fids @@ -452,12 +454,14 @@ def test_equal_inbound_and_outbound_fids_cleanup_only_their_own_sockets(tmp_path # logical forward target; cleanup must use the scoped namespace. assert instance._drop_stale_transfers(receiver) == 1 assert outbound_remote.recv(1) == b"" - assert upload_key not in instance._active_transfer_sockets - assert upload_key not in instance._active_transfer_fids + assert instance._active_transfer_sockets[upload_key] is outbound + assert upload_key in instance._active_transfer_fids instance._file_progress_finish( instance.file_upload_progress, upload_key, upload_entry ) instance._release_transfer_socket(upload_key, outbound) + assert upload_key not in instance._active_transfer_sockets + assert upload_key not in instance._active_transfer_fids assert upload_key not in instance.file_upload_progress instance.start_trans(fid, receiver, trans_type=1, direction=0) instance._transfer_controls.release(state) @@ -2917,11 +2921,10 @@ def test_closed_control_socket_falls_back_to_the_configured_endpoint(tmp_path): @pytest.mark.parametrize("sender_side", ["server", "client"]) def test_paused_leg_is_released_by_stale_sweep(tmp_path, monkeypatch, sender_side): - """A reconnect sweep releases a paused leg and unblocks its queued resume. + """A reconnect sweep releases the paused owner before recovery starts. - The sweep removes the leg's socket from the registry before closing it, so - the pause wait must also observe the leg's own socket; otherwise the leg - keeps the per-fid send lock and a resume request never runs. + Closing wakes the pause wait; the owner keeps its socket index until final + cleanup, then releases the per-fid send lock and permits a new resume. """ workers = _track_socket_workers(monkeypatch) server = _start_server(tmp_path) diff --git a/test/unit/network_api/test_resume_matching.py b/test/unit/network_api/test_resume_matching.py index 588feb4..6a63b7c 100644 --- a/test/unit/network_api/test_resume_matching.py +++ b/test/unit/network_api/test_resume_matching.py @@ -1,13 +1,23 @@ -"""Unit tests for the receiver's ``/file`` resume matching (``_resumable_entry``). +"""Resume matching and atomic ownership contracts for ordinary file recovery. -A ``/file `` line continues an interrupted download only when the -fid, the sender and the file name all match the progress entry. Anything else is -a new transfer and must never be matched to an existing partial file. +An interrupted download matches its fid, sender and file name. An ordinary +upload can reserve recovery only after its previous per-object owner exits. """ +import socket +import threading +from concurrent.futures import ThreadPoolExecutor +from types import SimpleNamespace + import pytest from PyFlow.network_api.connect_tcp import ( + TCP_Client_Base, + TCP_Server_Base, + _sending_transfer, + _TransferControlRegistry, + _TransferHandshakeRegistry, + _start_resume_send, _resumable_entry, format_resume_line, parse_resume_command, @@ -80,3 +90,115 @@ def test_resume_command_preserves_shell_quoted_endpoint_identity(): ]) def test_resume_command_rejects_ambiguous_or_malformed_identity(line): assert parse_resume_command(line) is None + + +@pytest.fixture +def ordinary_resume(): + control, wire = socket.socketpair() + paused, condition = {}, threading.Condition() + key = (PEER, 7) + owner = SimpleNamespace( + _transfer_progress_lock=threading.RLock(), _progress_discarded=False, + file_upload_progress={key: [100, 100, None, "/send/eof.bin", PEER]}, + _resume_sends={}, _active_transfer_fids=set(), _active_transfer_sockets={}, + _transfer_pause=paused, _transfer_pause_cond=condition, + _transfer_controls=_TransferControlRegistry(paused, condition), + _transfer_handshakes=_TransferHandshakeRegistry(), + ) + owner._transfer_progress_changed = threading.Condition(owner._transfer_progress_lock) + try: + yield owner, key, control, wire + finally: + control.close() + wire.close() + + +@pytest.mark.parametrize("busy", ["active", "paused", "bound", "closed", "pending", "unresolved", "owner", "dead-control"]) +def test_ordinary_resume_refuses_an_owned_object_without_queuing(ordinary_resume, busy): + owner, key, control, wire = ordinary_resume + if busy == "active": + owner._active_transfer_fids.add(key) + elif busy == "paused": + owner._transfer_pause[(*key, 0, 0)] = True + owner._transfer_controls.register((*key, 0, 0), control, wire) + elif busy in ("bound", "closed"): + owner._active_transfer_sockets[key] = wire + if busy == "closed": + wire.close() + elif busy in ("pending", "unresolved"): + record = owner._transfer_handshakes.register(control, key[1]) + if busy == "unresolved": + assert owner._transfer_handshakes.mark_sent(record) + assert owner._transfer_handshakes.wait(record, 0) is None + elif busy == "dead-control": + control.close() + else: + owner._resume_sends[key] = {"lock": threading.RLock(), "users": 1, "targets": set()} + assert _start_resume_send(owner, key, PEER, lambda row: control.sendall(b"unexpected"), + control_socket=control) is False + assert not owner._resume_sends.get(key, {}).get("targets") + if busy != "dead-control": + assert control.fileno() >= 0 + + +def test_ordinary_resume_atomically_reserves_eof_without_blocking_other_roles(ordinary_resume): + owner, key, control, wire = ordinary_resume + owner._transfer_pause[(*key, 0, 0)] = True + owner._active_transfer_fids.add((PEER, 8)) + owner._active_transfer_sockets[7] = wire + owner._transfer_controls.register((*key, 0, 1), control, wire) + barrier, entered, release = threading.Barrier(2), threading.Event(), threading.Event() + workers, rows = [], [] + + def send(row): + workers.append(threading.current_thread()) + rows.append(row) + control.sendall(b"resume") + entered.set() + assert release.wait(5) + + def request(): + barrier.wait(timeout=5) + return _start_resume_send(owner, key, PEER, send, control_socket=control) + + try: + with ThreadPoolExecutor(max_workers=2) as pool: + results = [pool.submit(request) for _ in range(2)] + outcomes = [result.result(timeout=5) for result in results] + assert entered.wait(5) + assert sorted(outcomes) == [False, True] + wire.settimeout(5) + with wire.makefile("rb") as stream: + assert stream.read(6) == b"resume" + assert rows == [owner.file_upload_progress[key]] + assert _start_resume_send(owner, key, PEER, send, control_socket=control) is False + finally: + release.set() + for worker in workers: + worker.join(timeout=5) + assert not worker.is_alive() + assert owner._resume_sends == {} + assert len(rows) == 1 + + +@pytest.mark.parametrize("owner_type", [TCP_Server_Base, TCP_Client_Base]) +def test_reconnect_waits_for_final_send_owner_after_its_socket_is_released( + ordinary_resume, owner_type, monkeypatch +): + owner, key, _, _ = ordinary_resume + owner.file_recv_progress = {} + waiting = threading.Event() + real_wait = owner._transfer_progress_changed.wait + + def observe_wait(timeout=None): + waiting.set() + return real_wait(timeout) + + monkeypatch.setattr(owner._transfer_progress_changed, "wait", observe_wait) + with ThreadPoolExecutor(max_workers=1) as pool: + with _sending_transfer(owner, key): + reconnect = pool.submit(owner_type._drop_stale_transfers, owner, PEER, wait=True) + assert waiting.wait(5) + assert not reconnect.done() + assert reconnect.result(timeout=5) == 0 + assert not owner._resume_sends diff --git a/test/unit/network_api/test_transfer_handshakes.py b/test/unit/network_api/test_transfer_handshakes.py index b93d7b0..f53e7de 100644 --- a/test/unit/network_api/test_transfer_handshakes.py +++ b/test/unit/network_api/test_transfer_handshakes.py @@ -21,6 +21,8 @@ def test_port_replies_match_socket_and_fid_independently_of_order(): control, other_control = _Control(), _Control() first, second = registry.register(control, 17), registry.register(control, 18) assert first["key"] == (control, 17) + assert registry.occupied(control, 17) + assert not registry.occupied(other_control, 17) assert second["key"] == (control, 18) assert registry.mark_sent(first) assert not registry.mark_sent(first) @@ -36,6 +38,7 @@ def test_port_replies_match_socket_and_fid_independently_of_order(): } assert not registry.resolve_port(control, 17, 41003, "enc:late") assert registry._pending == {} + assert not registry.occupied(control, 17) def test_pre_send_cancellation_does_not_make_fid_unresolved(): @@ -58,6 +61,7 @@ def test_sent_cancellation_and_timeout_leave_fid_unresolved_until_disconnect(): assert registry.mark_sent(cancelled) registry.cancel(cancelled) assert registry.register(control, 17) is None + assert registry.occupied(control, 17) assert not registry.resolve_port(control, 17, 42001, "plain") timed_out = registry.register(control, 18) @@ -68,6 +72,7 @@ def test_sent_cancellation_and_timeout_leave_fid_unresolved_until_disconnect(): registry.cancel_socket(control) assert (control, 17) not in registry._unresolved assert (control, 18) not in registry._unresolved + assert not registry.occupied(control, 17) assert registry.register(control, 17) is None From 25aac75abc71c1475672e36ccfeba74fad60736f Mon Sep 17 00:00:00 2001 From: F18-Ray Date: Mon, 16 Nov 2026 23:04:55 +0800 Subject: [PATCH 06/19] fix(connect_tcp)!: gate relay recovery on shared source ownership --- PyFlow/network_api/connect_tcp.py | 147 +++++++-------- .../transfer-pause-start-direction-plan.md | 6 +- .../transfer-pause-start-direction-report.md | 64 ++++++- docs/source/File_Transfer/File_Transfer.rst | 18 +- docs/source/Network_APIs/TCP_Client_APIs.rst | 8 +- docs/source/Network_APIs/TCP_Server_APIs.rst | 5 + docs/source/changes/transfer-fid-routes.md | 22 +++ .../network_api/test_tcp_transfer_control.py | 168 ++++++++++++++++++ .../network_api/test_tcp_transfer_resume.py | 50 ++++-- test/unit/network_api/test_delete_config.py | 36 ++++ test/unit/network_api/test_fid_routes.py | 76 +++++++- 11 files changed, 495 insertions(+), 105 deletions(-) diff --git a/PyFlow/network_api/connect_tcp.py b/PyFlow/network_api/connect_tcp.py index 9b6a59c..48aa5ed 100644 --- a/PyFlow/network_api/connect_tcp.py +++ b/PyFlow/network_api/connect_tcp.py @@ -716,7 +716,7 @@ def _sending_transfer(instance, key): instance._transfer_progress_changed.notify_all() -def _ordinary_transfer_busy(instance, key, control_socket): +def _transfer_busy(instance, key, control_socket): """Called under the progress lock; closed owners still own final cleanup.""" if key in instance._active_transfer_fids or key in instance._active_transfer_sockets: return True @@ -726,7 +726,7 @@ def _ordinary_transfer_busy(instance, key, control_socket): return True peer, fid = key with instance._transfer_pause_cond: - if (peer, fid, 0, 0) in instance._transfer_controls._legs: + if any((peer, fid, kind, 0) in instance._transfer_controls._legs for kind in (0, 1)): return True return instance._transfer_handshakes.occupied(control_socket, fid) return False @@ -737,7 +737,7 @@ def _claim_receive(instance, fid, control_socket, owner=None): if fid is None: return None with instance._transfer_progress_lock: - if instance._progress_discarded or _ordinary_transfer_busy(instance, fid, control_socket): + if instance._progress_discarded or _transfer_busy(instance, fid, control_socket): return None record = instance._receive_transfers.get(fid) if record is not None: @@ -783,23 +783,17 @@ def _discard_receive_requests(instance, control_socket): instance._transfer_progress_changed.notify_all() -def _start_resume_send(instance, key, target, send, *, control_socket=None): - """Reserve ordinary recovery once; relay target coalescing is kept separate.""" +def _start_resume_send(instance, key, target, send, *, control_socket): + """Atomically reserve one recovery worker; busy objects are never queued.""" with instance._transfer_progress_lock: if instance._progress_discarded or key not in instance.file_upload_progress: return False - if control_socket is not None and ( - control_socket.fileno() < 0 or _ordinary_transfer_busy(instance, key, control_socket) - ): + if control_socket.fileno() < 0 or _transfer_busy(instance, key, control_socket): return False state = instance._resume_sends.get(key) - if state is None and key in instance._active_transfer_fids: - return True # an initial ordinary send already owns this upload if state is None: state = {"lock": threading.RLock(), "users": 0, "targets": set()} instance._resume_sends[key] = state - if target in state["targets"]: - return True state["targets"].add(target) def run(): @@ -6919,12 +6913,22 @@ def _resume_request(self, client_socket, client_address, fid, offset, origin, ta self._log(f"resume: transfer {format_fid(fid)} has no matching origin/target route") return False + def _relay_resume_busy(self, fid): + """Called under progress/route locks; include setup and finalizing owners.""" + record = self._receive_transfers.get(fid) + return (_transfer_busy(self, fid, None) + or any(relay["fid"] == fid for relay in self._forward_relays.values()) + or record is not None and ( + record["owner"] is not None or record["deadline"] > time.monotonic() + )) + def _queue_resume_to_originator(self, originator_fid, route, target_addr, offset): """Keep the latest target offset until its originator accepts the request.""" originator, target = route["originator"], tuple(target_addr) - with self._forward_relays_lock: + with self._transfer_progress_lock, self._forward_relays_lock: if (self._fid_routes.get(originator_fid) is not route - or target not in route["targets"] or target in route["completed"]): + or target not in route["targets"] or target in route["completed"] + or self._relay_resume_busy(originator_fid)): return False self._pending_originator_resumes.setdefault(originator, {})[ (originator_fid, target) @@ -6942,37 +6946,46 @@ def _flush_pending_originator_resumes(self, client_address): return 0 sent = 0 for (fid, target), offset in pending: - with _sending_transfer(self, (client_address, fid)): - with self._forward_relays_lock: - waiting = self._pending_originator_resumes.get(client_address, {}) - if waiting.get((fid, target)) != offset: - continue # another flush sent it, or a newer offset replaced it - route = self._fid_routes.get(fid) - valid = (route is not None and route["originator"] == client_address - and target in route["targets"] and target not in route["completed"]) - if valid: - try: - if not self.send_message( - info["socket"], format_resume_line(fid, offset, client_address, target) - ): - continue - except OSError: - continue - sent += 1 - with self._forward_relays_lock: - waiting = self._pending_originator_resumes.get(client_address, {}) - if waiting.get((fid, target)) == offset: - waiting.pop((fid, target), None) + with self._transfer_progress_lock, self._forward_relays_lock: + waiting = self._pending_originator_resumes.get(client_address, {}) + if waiting.get((fid, target)) != offset: + continue + route = self._fid_routes.get(fid) + valid = (route is not None and route["originator"] == client_address + and target in route["targets"] and target not in route["completed"]) + if not valid: + waiting.pop((fid, target), None) if not waiting: self._pending_originator_resumes.pop(client_address, None) + continue + if self._relay_resume_busy(fid): + continue + record = _claim_receive(self, fid, info["socket"]) + if record is None: + continue + sent_request = False + try: + sent_request = self.send_message( + info["socket"], format_resume_line(fid, offset, client_address, target) + ) + except OSError: + pass + finally: + if not sent_request: + _release_receive(self, fid, record) + if not sent_request: + continue + sent += 1 + with self._forward_relays_lock: + waiting = self._pending_originator_resumes.get(client_address, {}) + if waiting.get((fid, target)) == offset: + waiting.pop((fid, target), None) + if not waiting: + self._pending_originator_resumes.pop(client_address, None) return sent def _resume_after_connect(self, client_address): - """Continue this peer's interrupted transfers after it (re)connected. - - Args: - client_address (tuple): Value used by the operation. - """ + """Resume eligible objects after this control peer reconnects.""" self._drop_stale_transfers(peer=tuple(client_address), wait=True) self._request_resumes(tuple(client_address)) self._flush_pending_originator_resumes(tuple(client_address)) @@ -7227,14 +7240,18 @@ def _forward_relay( "fid": fid, } relay_keys = [(target, tfid) for target, tfid in zip(targets, tfids)] - with self._forward_relays_lock: - if any(key in self._forward_relays for key in relay_keys): - self._forward_notify_error( - forwarder_sock, "relay target is already active", fid - ) - return - for key in relay_keys: - self._forward_relays[key] = relay + receive_record = None + with self._transfer_progress_lock, self._forward_relays_lock: + if (self._fid_routes.get(fid) is route + and not any(relay["fid"] == fid for relay in self._forward_relays.values()) + and not any(key in self._forward_relays for key in relay_keys)): + receive_record = _claim_receive(self, fid, forwarder_sock, relay) + if receive_record is not None: + for key in relay_keys: + self._forward_relays[key] = relay + if receive_record is None: + self._forward_notify_error(forwarder_sock, "relay source is already active", fid) + return if os.path.exists(self.file_trans_progress_file): self._persist_transfer_progress() target_conns = [] @@ -7371,6 +7388,7 @@ def own(control, transfer): for key in relay_keys: if self._forward_relays.get(key) is relay: del self._forward_relays[key] + _release_receive(self, fid, receive_record) def _forward_pump( self, up_sock, target_conns, forwarder_sock, fid, fname, relay, resume_offset=0 @@ -11127,23 +11145,11 @@ def _request_resumes(self): for fid, entry in list(self.file_recv_progress.items()): if entry[4] is None: continue # without a peer there is nobody to continue with - is_direct = _is_control_endpoint(entry[4], configured_peer, connected_peer) if connected_peer is not None and tuple(entry[4]) == configured_peer: entry[4] = connected_peer - if is_direct: - started += _request_receive_resume( - self, fid, entry, self.client_socket, entry[4], self.client_socket.getsockname() - ) - else: - with self._transfer_progress_lock: - if fid in self._active_transfer_fids: - continue # relay eligibility is handled separately - entry[0] = _resume_offset_for(entry) - if self.send_message( - self.client_socket, - format_resume_line(fid, entry[0], entry[4], self.client_socket.getsockname()), - ): - started += 1 + started += _request_receive_resume( + self, fid, entry, self.client_socket, entry[4], self.client_socket.getsockname() + ) return started @@ -11153,8 +11159,8 @@ def resume_trans(self, peer_addr, fid, offset): Server-bound uploads answer with ``/file``; other final targets replay through the server with the stable upstream fid. The retained upload path is sufficient because the receiver owns its full destination path. - Ordinary recovery skips any live, paused, negotiating or finalizing owner. - Relay target serialization remains separate from ordinary recovery. + Recovery skips any live, paused, negotiating or finalizing source owner, + including a relay upstream shared by several final targets. Args: peer_addr (tuple | None): Final receiver; None selects the server. @@ -11162,7 +11168,7 @@ def resume_trans(self, peer_addr, fid, offset): offset (int): Byte offset the receiver already holds. Returns: - bool: True for newly reserved ordinary recovery; False when busy. + bool: True for a newly reserved recovery worker; False when busy. """ server_peer = (self.host, self.port) control_socket = self.client_socket @@ -11208,7 +11214,7 @@ def send(entry): self.pfree(client_port) return _start_resume_send( - self, key, target, send, control_socket=control_socket if is_direct else None + self, key, target, send, control_socket=control_socket ) @@ -11816,7 +11822,6 @@ def file_transfer_client_recv(client_id): server_file_socket.close() return progress_fid = _transfer_fid(command_part) # keys this leg in file_recv_progress - is_direct = parse_forward_originator(command, self._own_address_text()) is None resume_entry = _resumable_entry(self.file_recv_progress, progress_fid, peer, command_part) destination_path = _parse_destination_path(command_part) stamp = self._crypto_transfer_stamp( @@ -11829,10 +11834,8 @@ def file_transfer_client_recv(client_id): if resume_entry is not None: # the sender answers this resume with /file; its connection is the continued leg server_file_socket.settimeout(RESUME_ACCEPT_TIMEOUT) - receive_record = _claim_receive( - self, progress_fid, client_socket, server_file_socket - ) if is_direct else None - if is_direct and progress_fid is not None and receive_record is None: + receive_record = _claim_receive(self, progress_fid, client_socket, server_file_socket) + if progress_fid is not None and receive_record is None: server_file_socket.close() return handed_off = False diff --git a/docs/plans/transfer-pause-start-direction-plan.md b/docs/plans/transfer-pause-start-direction-plan.md index bc72b5f..b94e6d0 100644 --- a/docs/plans/transfer-pause-start-direction-plan.md +++ b/docs/plans/transfer-pause-start-direction-plan.md @@ -1,6 +1,6 @@ # 双向文件暂停、继续与按对象恢复 — 需求卡与更改计划 -状态:**C1–C3 已通过人工放行;C4a 已实现并完成局部验证,待人工审查**。需求卡和七项拆分已确认。C4a 完成普通对象级恢复资格与原子占用,转发共享 source 恢复仍按 C4b。C4b、C5 尚未开始。每个原子变更完成后另附验证报告并等待审查。不自行提交、合并或推送。证据见[实施报告](transfer-pause-start-direction-report.md)。 +状态:**C1–C4a 已通过人工放行;C4b 已实现并完成局部验证,待人工审查**。需求卡和七项拆分已确认。C4b 完成共享 source/live relay 门槛、离线 pending 和会话清理;活跃请求跳过且不排队,单次跳过不保证稍后自动恢复。C5 尚未开始。每个原子变更完成后另附验证报告并等待审查。不自行提交、合并或推送。证据见[实施报告](transfer-pause-start-direction-report.md)。 ## 1. 需求卡 @@ -188,7 +188,7 @@ relay 高水位证据按实际入队粒度计算:记录高水位、单次 enqu ## 6. 验收命令与报告要求 -各阶段定向证据见实施报告。C1:81 passed;C2a:154 passed,修复参数化告警后受影响 64 项通过。C2b 首轮 223 passed、2 failed、1 skipped;修复后原失败两项通过,owner 定向检查 134 passed,既有受影响回归 159 passed。C3 主验证 217 passed、3 deselected;既有转发/恢复 20 passed、73 deselected。C4a 新资格/实际连接 42 passed、66 deselected;既有受影响首轮 139 passed、2 failed、14 deselected,旧清扫契约迁移后两项通过;重连最终占用检查 34 passed,最后监听交接双向场景 2 passed。实际命令和边界见报告,不将定向重跑计作全量复跑;C4b/C5 命令尚未运行。 +各阶段实际命令与边界见实施报告。C1:81 passed;C2a:154 passed,告警修复后受影响 64 项通过。C2b 首轮 223 passed、2 failed、1 skipped,修复后两项通过;owner 检查 134 passed,既有回归 159 passed。C3 主验证 217 passed、3 deselected,既有转发/恢复 20 passed、73 deselected。C4a 主验证 42 passed、66 deselected;既有首轮 139 passed、2 failed、14 deselected,契约迁移后两项通过;重连检查 34 passed,最终监听交接 2 passed。C4b 首轮 137 passed、6 failed、63 deselected,测试断点屏障修正后六项通过;既有转发/恢复/握手 39 passed、69 deselected。不将定向重跑计作全量复跑;C5 尚未运行。 ```bash # C1/C2a:实现后新增必要边界契约 @@ -220,4 +220,4 @@ relay 高水位证据按实际入队粒度计算:记录高水位、单次 enqu - **持久化数据模型不变**;运行时控制记录改变。查询返回 schema 不变。测试增加必要边界契约及迁移受影响断言,不降低验证强度。 - **CI/依赖/覆盖率策略不变**。不宣称本计划覆盖未运行的多平台环境、NAT、多进程共享或任意网络中断组合。 - 新功能依赖存活且可投递的控制连接;仅有数据 socket 存活但控制连接不可用时,不承诺远程 pause/start。自然关闭路径按既有机制结束旧 leg。 -- 用户已授权开始 C4a,C3 随该放行进入下一阶段。C4a 已完成普通恢复资格、原子占用、旧 leg 控制清理及局部验证/报告,待人工审查。实际范围超出原预估,原因与审查注意已列报告。转发共享 source/pending 资格和最终总验收仍在 C4b/C5,不自行进入下一阶段。本轮未创建提交、合并或推送。 +- 用户已授权开始 C4b,C4a 随该放行进入下一阶段。C4b 已完成转发资格和清理、定向验证及局部报告,待人工审查,详见[实施报告 C4b](transfer-pause-start-direction-report.md#c4b转发共享-source-恢复门槛与会话清理)。复用既有状态,不改变活跃请求不排队的约束,单次跳过不保证最终自动恢复。C5 尚未开始。本轮未创建提交、合并或推送。 diff --git a/docs/plans/transfer-pause-start-direction-report.md b/docs/plans/transfer-pause-start-direction-report.md index 7b7b617..61641c5 100644 --- a/docs/plans/transfer-pause-start-direction-report.md +++ b/docs/plans/transfer-pause-start-direction-report.md @@ -1,6 +1,6 @@ # 双向文件暂停、继续与按对象恢复 — 实施报告 -状态:需求卡和七项拆分已确认。**C1–C3 已通过人工放行;C4a 已实现并完成局部验证,待人工审查;C4b、C5 未开始。** 本报告随已完成的原子变更增补,不将未实现或未运行的路径标为完成。本轮未创建提交、合并或推送。 +状态:需求卡和七项拆分已确认。**C1–C4a 已通过人工放行;C4b 已实现并完成局部验证,待人工审查;C5 未开始。** 本报告随已完成的原子变更增补,不将未实现或未运行的路径标为完成。本轮未创建提交、合并或推送。 ## C1:严格解析、typed identity 与共享端点识别 @@ -361,7 +361,67 @@ C2a 后续审查结论:用户已审计放行,并明确授权开始 C2b,包 - 未应答 receive 请求保留无数据 owner 的短期占用,按 RESUME_ACCEPT_TIMEOUT 期限在后续请求时允许替换;实际 listener/data owner 不按时钟强制替换。失败发送/会话关闭立即清理请求;这不是逐请求完成 future。 - 实际范围比原 180–300 行预估更大,原因是发送资格之外必须同时覆盖接收请求、监听交接和自动重连清理。审查应连同新增契约与报告评估该规模偏差;未擅自增加 C4b 的转发资格或拆出混用新旧资格的中间阶段。 - 本轮未改公共签名、wire、progress JSON schema、CI、依赖或覆盖率策略;没有删除测试或弱化内容/ACK/隔离断言。未执行 repo-wide suite、formatter、lint、文档构建或多平台检查。语言服务仅 Ruff,references 请求返回 -32601,不能记作成功的引用分析。 -- **C4a 待人工审查,未创建提交**。C4b 与 C5 未开始。 +- C4a 后续结论:用户已放行 C4b,C4a 随该放行进入下一阶段。C4b 实施与独立待审事项见下节。 + +## C4b:转发共享 source 恢复门槛与会话清理 + +### 提交意图与数据流 + +一个 upstream fid 同时只允许一个 source/relay owner。即使请求 target 已断开,运行、暂停、建连或清理中的共享 source/relay 仍使本次请求返回 False,不排队、不主动 teardown。只有无活动对象且 source 离线时保留现有 pending;单次活跃请求被跳过不保证稍后自动补传,需重新发起。 + +- source 普通/转发 `resume_trans` 共用 `_transfer_busy` 和 `_start_resume_send`,在 progress lock 内检查两种 typed sender、active socket/fid、发送占用和 pending/unresolved 握手,再登记唯一 worker。删除旧的重复合并、不同 target 排队路径,不留无 control socket 的兼容分支。 +- target 请求和转发 listener 复用 C4a `_claim_receive`,沿请求→监听→数据 owner 保持占用,最终按 owner 清理;tracking off 同样生效。 +- Server 验证 origin/target/child route → progress/route 锁内检查共享 upstream 占用 → 忙碌则不写 pending;无活动且 source 离线则保留最新 offset。在线 flush 在同一边界预留 upstream 请求,释放锁后通过既有安全门槛和 `send_message` 投递。失败写释放预留、保留 pending。 +- `/forward_item` 校验原 route/未完成 target → 原子接管同会话 upstream 请求记录、登记 canonical child keys → 原有文件/ACK 路径 → 最终清理释放预留。旧记录的迟到释放不能删除替换 owner。未新增状态表、持久化字段、重试协议或文件成功标记。 + +### 变更范围 + +生产改动集中于 `connect_tcp.py` 的恢复资格、pending 投递、relay 登记和 target 接收占用。测试位于 `test_fid_routes.py`、`test_delete_config.py`、`test_tcp_transfer_resume.py`、`test_tcp_transfer_control.py`。旧的“活动 source 后排队”契约迁移为“拒绝、owner 退出后显式重试”,保留不同 offset、稳定 fid、目标路径、内容及最终 ACK 断言。三份 RST、变更记录、计划和本报告同步更新。现有断线 shutdown、加密、路由持久化与配置删除契约保留。 + +### 局部验证与实际结果 + +首轮门槛、生命周期及真实连接检查: + +```bash +.venv/bin/python -m pytest test/unit/network_api/test_fid_routes.py test/unit/network_api/test_delete_config.py test/unit/network_api/test_resume_matching.py test/integration/network_api/test_tcp_transfer_control.py -k 'not pause_start_preserves and not receiver_unconfirmed and not same_fid and not empty_and_eof and not receiver_keeps and not receiver_pause_start_waits and not relay_child_and_upstream and not relay_pressure and not online_resume and not control_disconnect_releases' -q +``` + +**137 passed、6 failed、63 deselected in 87.46s**。六项失败均停在新增 source/stop 用例的 1 KiB 断点:按 writer 等待调用次数定位无法固定预期 payload 进度。改为首个真实 payload 块实际发送后设置事件屏障,保留真实 send/crypto 和 receiver 进度断言;未改生产代码或放宽落盘/ACK 断言。 + +仅重跑六个受影响场景: + +```bash +.venv/bin/python -m pytest test/integration/network_api/test_tcp_transfer_control.py::test_relay_offline_source_replays_stable_route_or_stops_cleanly -q +``` + +**6 passed in 47.99s**。不将定向重跑记作全量复跑。 + +受影响既有转发、零偏移/EOF、恢复及握手回归: + +```bash +.venv/bin/python -m pytest test/integration/network_api/test_tcp_transfer_resume.py test/integration/network_api/test_tcp_file_transfer.py test/unit/network_api/test_transfer_handshakes.py -k 'forward or stale_sweep or handshake or port_replies or pre_send_cancellation or sent_cancellation or terminal_reply or old_record or wait_many or disconnect_cancels or reconnect_socket or port_announcement or old_or_malformed' -q +``` + +**39 passed、69 deselected in 58.59s**。 + +### 路径对照与运行证据 + +| 路径 | C4b 结论与证据边界 | +|---|---| +| P10 | 实际关闭 target 控制/data socket,共享 source 仍活跃时两端拒绝恢复、不增加 pending/worker;另一 target 保留原 socket 并完成内容/ACK,上游失败且未完成 route 保留 | +| P12/P13 | plain alias、encrypted、encrypted async/tracking off wildcard 均运行新增场景;旧 control/receive 记录迟到清理不影响新 owner;未改变端点命名空间或加密入口 | +| P16 | source 断线且旧 relay 全部退出后,离线请求从 offset 0 更新为实际 1 KiB;原 client 端点重连后单次重放复用 upstream/child fid、同 route/completed,已完成 target 不重发。零偏移/空文件/EOF 由既有真实回归覆盖;单位契约覆盖不同 fid 独立及并发 flush 只发送一次 | +| P17 | source/target 真实断线释放旧 worker、socket 和暂停状态;新 owner 默认 running。保留旧记录执行迟到清理后,新 owner 仍有效,重复恢复 False;最终内容等于 payload、source 得到真实成功 ACK、状态清空 | +| P18 | 同一实际断点执行 stop,transfer/control worker 退出、占用释放、route 快照保留;随后可删除 progress 文件,重复 stop 不重新生成文件,内存 route 按原契约保留。单位契约覆盖失败写/关闭请求释放和配置删除门槛;合并总验收仍在 C5 | + +### 风险与明确未覆盖 + +- 活跃请求不排队:target 重连时若只发起一次请求而 source 仍活跃,需要稍后重新请求。未新增 timer、自动重试或 wire 拒绝确认,不能宣称最终自动补传。 +- 离线已有多个 target pending 时,同 upstream 一次只预留一个;剩余项等待后续合格 flush/请求/重连触发,不在活动对象后建立 worker 队列。 +- 控制写入不是逐请求恢复确认;未回应请求按现有接收预留期限处理,实际 relay owner 不按时钟强制替换。 +- 新场景验证 source 断线重连和 target 断线拒绝;未另加 target 同端点重连补传场景,不宣称网络时序全集已枚举。配置/持久化与加密的相关合并验收留在 C5。 +- 本轮未改公共签名、wire、持久化 schema、CI、依赖或 coverage 策略;未删除测试或弱化内容/ACK/稳定身份断言。未运行 formatter、lint、文档构建、repo-wide suite 或多平台验证;Ruff 不支持 references,不能记作成功引用分析。 +- **C4b 待人工审查,未创建提交**。C5 未开始。 ## 公共协议/API 变更许可记录 diff --git a/docs/source/File_Transfer/File_Transfer.rst b/docs/source/File_Transfer/File_Transfer.rst index f623dd6..1a34180 100644 --- a/docs/source/File_Transfer/File_Transfer.rst +++ b/docs/source/File_Transfer/File_Transfer.rst @@ -963,13 +963,17 @@ timeout or a lost ACK conservatively retains the source upload progress, even if the server completed delivery. No separate receipt or retry protocol is used. If a target cannot send its final ACK, its receive entry survives even when the disk file is complete; an EOF replay with the same fid -can confirm it without retransmitting the body. Retries for different targets -of one upstream fid are serialized at the source, concurrent duplicate requests -for the same target are coalesced, and completed targets are not replayed. -Ordinary resumes share the same in-flight coalescing. Offline-source requests -are kept on the server per upstream fid/target, retaining the latest offset. -Reconnect sends through the same secure control path; a failed send keeps the -request, and completed or missing routes are never replayed. +can confirm it without retransmitting the body. A shared upstream fid admits +one recovery owner at a time. Running, paused, negotiating or finalizing +source/relay owners reject another request without queueing or tearing down +the live relay. A disconnected target must request again after that owner +exits; one skipped request does not promise eventual automatic replay. +Completed targets are not replayed. If the source is offline and no relay is +live, the server retains the latest offset per upstream fid/target. Reconnect +revalidates and reserves one eligible replay through the secure control path; +failed writes retain pending requests, and completed or missing routes are +pruned. Other independent fids remain eligible. Receive requests/listeners +retain per-object ownership through final cleanup, including tracking off. Fids no longer encode a plain/relay kind: the reserved low bit is always zero, and diagnostics use ``e.``. Ordinary senders own their FIDs; the relay source owns the upstream FID and the Server allocates one child FID diff --git a/docs/source/Network_APIs/TCP_Client_APIs.rst b/docs/source/Network_APIs/TCP_Client_APIs.rst index 81119e3..4f0cd5a 100644 --- a/docs/source/Network_APIs/TCP_Client_APIs.rst +++ b/docs/source/Network_APIs/TCP_Client_APIs.rst @@ -310,9 +310,11 @@ commands sent by the server, such as: supplies the source path; a non-server target is replayed through the server with its stable upstream fid. The receiver's retained full path handles folder items without copying directory or destination metadata at the source. - Direct uploads recover only when no live, paused, negotiating or finalizing - owner holds that object. ``resume_trans`` returns ``True`` for a newly reserved - worker; busy and duplicate calls return ``False`` without closing or queueing. + Both direct and relay uploads recover only when no live, paused, negotiating + or finalizing source owner holds that object. ``resume_trans`` returns ``True`` + for a newly reserved worker; busy and duplicate calls return ``False`` without + closing or queueing. A shared upstream FID cannot replay for a second target + until its previous owner exits; the skipped request must be issued again. Another file or opposite direction does not prevent recovery. A paused live connection continues through ``start_trans`` instead. diff --git a/docs/source/Network_APIs/TCP_Server_APIs.rst b/docs/source/Network_APIs/TCP_Server_APIs.rst index 4868c39..e005156 100644 --- a/docs/source/Network_APIs/TCP_Server_APIs.rst +++ b/docs/source/Network_APIs/TCP_Server_APIs.rst @@ -702,6 +702,11 @@ Built-in client commands include: for a newly reserved worker; busy and duplicate calls return ``False`` without closing or queueing. Other objects remain independent. Use ``start_trans`` to continue an existing paused connection. + Forwarded recovery also requires its shared source/relay owner to be idle, + even when the requesting target has disconnected. Busy requests are skipped, + not queued; the target must request again after cleanup. An offline source's + existing pending requests are retained and revalidated at reconnect, with + one upstream reservation. No active relay is torn down to make it eligible. - Forwarded transfers return the existing final data-ACK marker upstream only after the current input stream is complete and every accepted target has acknowledged. The normal send path reframes the marker for the upstream hop; diff --git a/docs/source/changes/transfer-fid-routes.md b/docs/source/changes/transfer-fid-routes.md index 4c32a85..3d5c631 100644 --- a/docs/source/changes/transfer-fid-routes.md +++ b/docs/source/changes/transfer-fid-routes.md @@ -432,3 +432,25 @@ file preservation. Runtime evidence and explicit exclusions are recorded in passed 34 tests, and the final listener-handoff check passed both directions. Full commands and exclusions are in the C4a report. Relay recovery remains C4b. +## Transfer control C4b: shared-source relay resume eligibility + +- Direct and relay recovery share the existing per-object reservation gate. + Active, paused, negotiating or finalizing upstream owners reject recovery + for any target without queueing or tearing down the live relay. A skipped + target request must be issued again after that owner exits; it does not + promise eventual automatic replay. +- Server pending delivery reserves the upstream object before control writes; + relay setup adopts that record and releases it after final cleanup. Target + receive requests/listeners reuse the same ownership mechanism. Offline-source + pending offsets are retained, failed writes release reservations without + dropping pending work, and completed/missing routes are revalidated. +- Real source reconnect reuses upstream/child FIDs and retained route completion, + starts new owners running, and ignores late cleanup of old records. Stop + releases active ownership before configuration deletion while preserving the + existing route snapshot and in-memory deletion semantics. +- The first targeted run passed 137 tests and found six test-barrier failures; + all six passed after placing the barrier after the real first payload write. + Existing forwarding/recovery/handshake checks passed 39 tests. Full commands, + exclusions and runtime evidence are in the C4b report; combined acceptance + remains the C5 review stage. + diff --git a/test/integration/network_api/test_tcp_transfer_control.py b/test/integration/network_api/test_tcp_transfer_control.py index 1797179..6c0375d 100644 --- a/test/integration/network_api/test_tcp_transfer_control.py +++ b/test/integration/network_api/test_tcp_transfer_control.py @@ -1,5 +1,6 @@ """Typed live control over real ordinary transfer sockets and secure channels.""" +import json import os import shlex import socket @@ -786,3 +787,170 @@ def test_control_disconnect_releases_paused_ordinary_workers(channel, tmp_path, and not owner._transfer_pause for owner in (sender, receiver))) assert all(state["owner"].fileno() < 0 and not state["confirmed_state"] and not state["last_requested_state"] for state in states) + + +def test_disconnected_relay_target_cannot_queue_behind_live_source(relay_clients, tmp_path, monkeypatch): + run = _relay(relay_clients, tmp_path, monkeypatch) + server, source, targets, _ = relay_clients + relay, sender, gates, worker, result, payload, _, _ = run + fid, route = relay["fid"], relay["route"] + origin = source.client_socket.getsockname() + first, second = [target.client_socket.getsockname() for target in targets] + control = server.clients[first]["socket"] + sockets = [state["owner"] for state in (sender, relay["upstream"], *relay["controls"].values())] + source.file_upload_progress.setdefault(sender["key"][:2], + [0, len(payload), None, str(tmp_path / "relay.bin"), first]) + assert _control(source, sender, True) + _confirmed((sender, relay["upstream"]), True) + assert source.resume_trans(second, fid, 0) is False + targets[0].close() + assert wait_until(lambda: first not in server.clients and relay["controls"][first]["owner"].fileno() < 0) + assert server._resume_request(control, first, route["targets"][first], 0, origin, first) is False + assert server._queue_resume_to_originator(fid, route, first, 1) is False + assert source.resume_trans(first, fid, 0) is False + assert not server._pending_originator_resumes + assert server._receive_transfers[fid]["owner"] is relay + assert sender["owner"] is sockets[0] and sockets[0].fileno() >= 0 + assert relay["controls"][second]["owner"] is sockets[-1] and sockets[-1].fileno() >= 0 + assert worker.is_alive() and result == {} and not source._resume_sends.get(sender["key"][:2], {}).get("targets") + assert _control(source, sender, False) + _relay_done(relay_clients, run, failed=True) + assert all(sock.fileno() < 0 for sock in sockets) + assert wait_until(lambda: all(not owner._receive_transfers and not owner._active_transfer_sockets + and not owner._resume_sends for owner in (server, source, *targets))) + + +@pytest.mark.parametrize("fault", ["source", "stop"]) +def test_relay_offline_source_replays_stable_route_or_stops_cleanly( + relay_clients, tmp_path, monkeypatch, fault +): + workers, real_start = [], threading.Thread.start + + def start(worker, *args, **kwargs): + if getattr(getattr(worker, "_target", None), "__name__", "") in { + "_forward_relay", "writer", "file_transfer_client_recv", + "file_transfer_client_recv_server_start", "receive_file_transfer_messages", "_flush", + }: + workers.append(worker) + return real_start(worker, *args, **kwargs) + + monkeypatch.setattr(threading.Thread, "start", start) + run = _relay(relay_clients, tmp_path, monkeypatch) + server, source, targets, releases = relay_clients + relay, sender, gates, worker, result, payload, observed, _ = run + fid, route = relay["fid"], relay["route"] + origin = source.client_socket.getsockname() + first, second = [target.client_socket.getsockname() for target in targets] + child = route["targets"][first] + output = Path(targets[0].file_transfer_dir) / "relay.bin" + source.file_upload_progress.setdefault(sender["key"][:2], + [0, len(payload), None, str(tmp_path / "relay.bin"), first]) + partial, interrupt, resumed, finish = (threading.Event() for _ in range(4)) + releases.extend((interrupt, finish)) + real_wait, real_send = connect_tcp._wait_transfer_control, server.send_message + real_progress = targets[0]._file_progress_start + + def retain_progress(store, transfer_id, size, path, peer=None, initial=0): + return real_progress(store, transfer_id, size, path, peer, initial) or store.setdefault( + transfer_id, [initial, size, None, str(path), peer]) + + monkeypatch.setattr(targets[0], "_file_progress_start", retain_progress) + + def hold_payload(sock, message, is_send_raw=False): + written = real_send(sock, message, is_send_raw=is_send_raw) + if sock is relay["controls"][first]["owner"] and message == payload[:1024]: + partial.set() + assert interrupt.wait(timeout=30) + return written + + monkeypatch.setattr(server, "send_message", hold_payload) + + def hold(instance, state, sock): + if instance is source and state is not None and state["key"] == sender["key"] and state is not sender: + resumed.set() + assert finish.wait(timeout=30) + return real_wait(instance, state, sock) + + monkeypatch.setattr(connect_tcp, "_wait_transfer_control", hold) + for gate in gates: + gate.set() + assert partial.wait(timeout=15) + assert wait_until(lambda: targets[0].file_recv_progress.get(child, [None])[0] == 1024) + assert wait_until(lambda: second in route["completed"], timeout=15) + assert (Path(targets[1].file_transfer_dir) / "relay.bin").read_bytes() == payload + receiver = targets[0]._transfer_controls._legs[((source.host, source.port), child, 1, 1)] + assert _control(targets[0], receiver, True) + _confirmed((receiver, relay["controls"][first]), True) + old_states = [(owner, state) for owner in (server, source, *targets) + for state in owner._transfer_controls._legs.values()] + old_receive = server._receive_transfers[fid] + old_target_receive = targets[0]._receive_transfers[child] + snapshot = server._transfer_progress_snapshot()["relays"] + old_client, old_server = source.client_socket, server.clients[origin]["socket"] + if fault == "stop": + server.stop() + else: + old_server.shutdown(socket.SHUT_RDWR) + assert wait_until(lambda: not source.running and origin not in server.clients) + source.receive_thread.join(timeout=10) + source._release_client_socket() + interrupt.set() + worker.join(timeout=20) + for old_worker in tuple(workers): + old_worker.join(timeout=10) + assert not old_worker.is_alive() + assert not worker.is_alive() and result == {"ack": False} + assert all(state["owner"].fileno() < 0 and not state["confirmed_state"] for _, state in old_states) + assert wait_until(lambda: not server._forward_relays and all( + not owner._transfer_controls._legs and not owner._transfer_pause + and not owner._active_transfer_sockets and not owner._receive_transfers + and not owner._resume_sends for owner in (server, source, *targets))) + assert server._transfer_progress_snapshot()["relays"] == snapshot + if fault == "stop": + assert json.loads(Path(server.file_trans_progress_file).read_text())["relays"] == snapshot + assert server.delete_config(Path(server.file_trans_progress_file).name) + assert not Path(server.file_trans_progress_file).exists() + assert server._transfer_progress_snapshot()["relays"] == snapshot + server.stop() + assert not Path(server.file_trans_progress_file).exists() + return + assert output.read_bytes() == payload[:1024] + request_control = server.clients[first]["socket"] + assert server._resume_request(request_control, first, child, 0, origin, first) is False + assert server._resume_request(request_control, first, child, 1024, origin, first) is False + assert server._pending_originator_resumes == {origin: {(fid, first): 1024}} + calls, real_forward = [], source._forward_one + + def forward(*args, **kwargs): + ack = real_forward(*args, **kwargs) + calls.append((kwargs["upstream_fid"], kwargs["resume_offset"], ack)) + return ack + + monkeypatch.setattr(source, "_forward_one", forward) + source.client_port = origin[1] + assert source.connect() and source.client_socket.getsockname() == origin + assert resumed.wait(timeout=20) + replacement = observed["relay"] + assert replacement is not relay and replacement["route"] is route + assert replacement["fid"] == fid and replacement["controls"][first]["key"][1] == child + assert set(replacement["controls"]) == {first} and route["completed"] == {second} + new_sender = source._transfer_controls._legs[sender["key"]] + assert new_sender["owner"] is not sender["owner"] and new_sender["control_socket"] is source.client_socket + _confirmed((new_sender, replacement["upstream"], replacement["controls"][first]), False) + assert source._transfer_controls.release(sender) is False + source._transfer_controls.discard_socket(old_client) + server._transfer_controls.discard_socket(old_server) + connect_tcp._release_receive(server, fid, old_receive) + connect_tcp._release_receive(targets[0], child, old_target_receive) + assert server._receive_transfers[fid]["owner"] is replacement + assert child in targets[0]._receive_transfers and source._transfer_controls._legs[sender["key"]] is new_sender + assert server._flush_pending_originator_resumes(origin) == 0 + assert source.resume_trans(first, fid, 1024) is False + finish.set() + assert wait_until(lambda: calls == [(fid, 1024, True)], timeout=20) + assert output.read_bytes() == payload and not server._fid_routes and not server._fid_route_index + assert wait_until(lambda: not server._forward_relays and all( + not owner._transfer_controls._legs and not owner._transfer_pause + and not owner._active_transfer_sockets and not owner._receive_transfers + and not owner._resume_sends for owner in (server, source, *targets))) + assert not server._pending_originator_resumes diff --git a/test/integration/network_api/test_tcp_transfer_resume.py b/test/integration/network_api/test_tcp_transfer_resume.py index ac779b0..2089786 100644 --- a/test/integration/network_api/test_tcp_transfer_resume.py +++ b/test/integration/network_api/test_tcp_transfer_resume.py @@ -1590,7 +1590,7 @@ def observe_upstream_ack(sock, message, is_send_raw=False): sender.join(timeout=20) assert not sender.is_alive(), "the source attempt did not finish" assert outcomes == [False] - assert wait_until(lambda: not server._forward_relays, timeout=10) + assert wait_until(lambda: not server._forward_relays and not server._receive_transfers, timeout=10) assert len(server._fid_routes) == 1 fid, route = next(iter(server._fid_routes.items())) original_targets = dict(route["targets"]) @@ -1626,23 +1626,23 @@ def observe_upstream_ack(sock, message, is_send_raw=False): child_fid = original_targets[addr] losing_ack[addr] = False # The receiver discovers the disk offset using its normal reconnect - # path. A second request while its ACK is held must be coalesced. + # path. Its live receive owner rejects another request at the ACK gate. assert target._request_resumes() == 1 if index == 0: assert resume_ack.wait(timeout=10) assert len(calls) == 2 assert source.file_upload_progress[upload_key][0:2] == [len(payload), len(payload)] assert source.file_upload_progress[upload_key][3:] == [str(src), addr] - # The first request's data socket is still registered. Replay - # the reconnect request after clearing that stale session marker. + # Removing a stale active marker cannot bypass the listener owner. target._active_transfer_fids.discard(child_fid) - assert target._request_resumes() == 1 - assert wait_until(lambda: len(resume_requests) == 2, timeout=10) - assert resume_requests == [(addr, fid, len(payload))] * 2 + assert target._request_resumes() == 0 + assert resume_requests == [(addr, fid, len(payload))] assert len(calls) == 2, "a duplicate resume started another upload" + assert source._resume_sends[upload_key]["targets"] == {addr} release_ack.set() assert wait_until(lambda: len(outcomes) == index + 2, timeout=10) - assert wait_until(lambda: not server._forward_relays, timeout=10) + assert wait_until(lambda: not server._forward_relays and not server._receive_transfers + and not source._resume_sends, timeout=10) assert outcomes[-1] is (index == len(failed) - 1) assert len(upstream_acks) == (1 if index == len(failed) - 1 else 0) assert terminal_controls == ["/server_file_transfer_port"] * (index + 2) @@ -2464,7 +2464,7 @@ def test_download_resumes_after_connect_without_a_manual_call(tmp_path): def test_unified_resume_serializes_distinct_offsets_without_local_fid_fallback(tmp_path, monkeypatch): - """One upload serves queued targets once, preserving paths and endpoint scope.""" + """Busy recovery skips targets until the old source owner fully exits.""" workers = _track_socket_workers(monkeypatch) server = _start_server(tmp_path) clients = [] @@ -2521,15 +2521,33 @@ def observe_mode(*args, **kwargs): monkeypatch.setattr(source, "file_transfer_mode", observe_mode) assert first._request_resumes() == 1 assert held.wait(timeout=10), "the first target never reached its ACK barrier" + rejected = threading.Event() + original_queue = server._queue_resume_to_originator + + def observe_rejection(fid, route, target, offset): + accepted = original_queue(fid, route, target, offset) + if target == second_addr: + assert accepted is False + rejected.set() + return accepted + + monkeypatch.setattr(server, "_queue_resume_to_originator", observe_rejection) assert second._request_resumes() == 1 - assert first.send_message( - first.client_socket, format_resume_line(502, 999, source_addr, first_addr) - ) - assert wait_until( - lambda: source._resume_sends.get(key, {}).get("targets") == {first_addr, second_addr} + assert rejected.wait(timeout=10) + assert not server._resume_request( + server.clients[first_addr]["socket"], first_addr, 502, 999, source_addr, first_addr ) - assert wait_until(lambda: transfers == [(500, offsets[0])]) + assert source.resume_trans(second_addr, 500, offsets[1]) is False + assert source.resume_trans(first_addr, 500, 999) is False + assert server._pending_originator_resumes == {} + assert source._resume_sends[key]["targets"] == {first_addr} + assert transfers == [(500, offsets[0])] release.set() + assert wait_until(lambda: not source._resume_sends and not server._forward_relays + and 500 not in server._receive_transfers + and key not in source._active_transfer_sockets) + assert route["completed"] == {first_addr} + assert source.resume_trans(second_addr, 500, offsets[1]) is True assert wait_until(lambda: key not in source.file_upload_progress, timeout=15) assert wait_until(lambda: not source._resume_sends and not server._fid_routes) assert transfers == [(500, offset) for offset in offsets] @@ -2999,7 +3017,7 @@ def send_leg(): assert key in sender.file_upload_progress calls = [] - assert _start_resume_send(sender, key, target, calls.append) + assert _start_resume_send(sender, key, target, calls.append, control_socket=control) assert wait_until(lambda: calls, timeout=10), "the queued resume never ran" assert calls[0] is sender.file_upload_progress[key] finally: diff --git a/test/unit/network_api/test_delete_config.py b/test/unit/network_api/test_delete_config.py index d1d0d17..ac1de76 100644 --- a/test/unit/network_api/test_delete_config.py +++ b/test/unit/network_api/test_delete_config.py @@ -1,6 +1,7 @@ """Contracts for named local state deletion and discarded-progress lifetime.""" import json +import socket import threading from pathlib import Path @@ -251,6 +252,41 @@ def test_transient_resume_state_prevents_deletion_until_released(instance, users assert instance.delete_config(path.name) is True +@pytest.mark.parametrize("cleanup", ["release", "failed", "closed"]) +def test_receive_owner_blocks_deletion_until_request_cleanup(instance, cleanup, tmp_path): + populate(instance) + close(instance) + control, peer = socket.socketpair() + with control, peer: + record = connect_tcp._claim_receive(instance, 6, control, owner=control) + assert record is not None + path = Path(instance.file_trans_progress_file) + with pytest.raises(RuntimeError): + instance.delete_config(path.name) + assert instance._receive_transfers[6] is record + connect_tcp._release_receive(instance, 6, record) + if cleanup != "release": + partial = tmp_path / "partial.bin" + partial.write_bytes(b"partial") + entry = [7, 10, None, str(partial), PEER] + instance.running = True + if isinstance(instance, TCP_Client_Base): + instance.client_socket = control + control.shutdown(socket.SHUT_WR) + if cleanup == "closed": + control.close() + try: + try: + sent = connect_tcp._request_receive_resume(instance, 6, entry, control, PEER, PEER) + except OSError: + sent = False + assert sent is False + finally: + instance.running = False + assert instance._receive_transfers == {} + assert instance.delete_config(path.name) is True + + def test_delete_waits_for_inflight_progress_publication(instance, monkeypatch): instance.file_recv_progress[6] = [3, 10, None, "/recv/partial.bin", PEER] close(instance) diff --git a/test/unit/network_api/test_fid_routes.py b/test/unit/network_api/test_fid_routes.py index e5baf41..12dfbc3 100644 --- a/test/unit/network_api/test_fid_routes.py +++ b/test/unit/network_api/test_fid_routes.py @@ -2,10 +2,13 @@ import json import socket +import threading import pytest -from PyFlow.network_api.connect_tcp import TCP_Server_Base, parse_resume_command +from PyFlow.network_api.connect_tcp import ( + TCP_Server_Base, _claim_receive, _release_receive, parse_resume_command, +) # The server's control side as the unit tests drive `_resume_request` by hand. @@ -420,6 +423,7 @@ def test_pending_resume_survives_failed_send_and_prunes_completed_or_missing_rou ORIGINATOR: {(302, TARGET_1): 13, (302, TARGET_2): 13} } finally: + assert server._receive_transfers == {} broken.close() assert server._complete_fid_target(302, route, TARGET_1, 304) writer, reader = socket.socketpair() @@ -433,9 +437,11 @@ def test_pending_resume_survives_failed_send_and_prunes_completed_or_missing_rou assert server._pending_originator_resumes == {} assert not server._resume_request(SERVER_LOCAL, TARGET_1, 304, 0, ORIGINATOR, TARGET_1) # An accepted request must not outlive its owning route. + _release_receive(server, 302, server._receive_transfers[302]) assert server._queue_resume_to_originator(302, route, TARGET_2, 29) reader.recv(4096) server.clients.pop(ORIGINATOR) + _release_receive(server, 302, server._receive_transfers[302]) assert not server._queue_resume_to_originator(302, route, TARGET_2, 31) assert server._drop_fid_route(302, route) server.clients[ORIGINATOR] = {"socket": writer} @@ -445,4 +451,70 @@ def test_pending_resume_survives_failed_send_and_prunes_completed_or_missing_rou server.running = False server.clients.clear() writer.close() - reader.close() \ No newline at end of file + reader.close() + + +@pytest.mark.parametrize("owner", ["request", "receiver", "relay"]) +def test_live_upstream_refuses_recovery_without_pending_other_fids_remain_eligible(server, owner): + route = server._register_fid_route(302, ORIGINATOR, {TARGET_1: 304, TARGET_2: 306}) + server._register_fid_route(402, ORIGINATOR, {TARGET_3: 404}) + control, peer = socket.socketpair() + with control, peer: + record = None + if owner == "relay": + server._forward_relays[(TARGET_1, 304)] = {"fid": 302, "route": route, "upstream": control} + else: + record = _claim_receive(server, 302, control, None if owner == "request" else control) + assert record is not None + try: + for target, child in route["targets"].items(): + assert not server._resume_request(SERVER_LOCAL, target, child, 13, ORIGINATOR, target) + assert server._pending_originator_resumes == {} + assert not server._resume_request(SERVER_LOCAL, TARGET_3, 404, 19, ORIGINATOR, TARGET_3) + assert server._pending_originator_resumes == {ORIGINATOR: {(402, TARGET_3): 19}} + finally: + server._forward_relays.clear() + if record is not None: + _release_receive(server, 302, record) + + +def test_concurrent_pending_flushes_send_one_real_control_request(server, monkeypatch): + server._register_fid_route(302, ORIGINATOR, {TARGET_1: 304, TARGET_2: 306}) + for target, child in ((TARGET_1, 304), (TARGET_2, 306)): + assert not server._resume_request(SERVER_LOCAL, target, child, 13, ORIGINATOR, target) + entered, release = threading.Event(), threading.Event() + real_send = server.send_message + + def held_send(*args, **kwargs): + entered.set() + assert release.wait(timeout=5) + return real_send(*args, **kwargs) + + monkeypatch.setattr(server, "send_message", held_send) + writer, reader = socket.socketpair() + with writer, reader: + server.running = True + server.clients[ORIGINATOR] = {"socket": writer} + results = [] + workers = [threading.Thread(target=lambda: results.append( + server._flush_pending_originator_resumes(ORIGINATOR))) for _ in range(2)] + try: + workers[0].start() + assert entered.wait(timeout=5) + workers[1].start() + workers[1].join(timeout=1) + finally: + release.set() + for worker in workers: + if worker.ident is not None: + worker.join(timeout=5) + server.running = False + server.clients.clear() + assert not any(worker.is_alive() for worker in workers) + assert sorted(results) == [0, 1] + reader.settimeout(1) + assert parse_resume_command(reader.recv(4096).decode()) == (302, 13, ORIGINATOR, TARGET_1) + with pytest.raises(socket.timeout): + reader.recv(4096) + assert server._pending_originator_resumes == {ORIGINATOR: {(302, TARGET_2): 13}} + _release_receive(server, 302, server._receive_transfers[302]) \ No newline at end of file From a7ffd796dea5f8ca01088af548d91987c90ec999 Mon Sep 17 00:00:00 2001 From: F18-Ray Date: Mon, 16 Nov 2026 23:30:24 +0800 Subject: [PATCH 07/19] Docs: updating docs --- .github/workflows/ci.yml | 2 +- .../transfer-pause-start-direction-plan.md | 8 +- .../transfer-pause-start-direction-report.md | 89 ++++++++++++++++++- docs/source/File_Transfer/File_Transfer.rst | 23 ++--- docs/source/Network_APIs/TCP_Client_APIs.rst | 13 +-- docs/source/Network_APIs/TCP_Server_APIs.rst | 7 +- docs/source/changes/transfer-fid-routes.md | 41 +++++++-- 7 files changed, 150 insertions(+), 33 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c8e0f21..81ab6f7 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -74,7 +74,7 @@ jobs: os: [ubuntu-latest, windows-latest] python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"] runs-on: ${{ matrix.os }} - timeout-minutes: 10 + timeout-minutes: 30 steps: - name: Checkout code uses: actions/checkout@v7 diff --git a/docs/plans/transfer-pause-start-direction-plan.md b/docs/plans/transfer-pause-start-direction-plan.md index b94e6d0..709970e 100644 --- a/docs/plans/transfer-pause-start-direction-plan.md +++ b/docs/plans/transfer-pause-start-direction-plan.md @@ -1,6 +1,6 @@ # 双向文件暂停、继续与按对象恢复 — 需求卡与更改计划 -状态:**C1–C4a 已通过人工放行;C4b 已实现并完成局部验证,待人工审查**。需求卡和七项拆分已确认。C4b 完成共享 source/live relay 门槛、离线 pending 和会话清理;活跃请求跳过且不排队,单次跳过不保证稍后自动恢复。C5 尚未开始。每个原子变更完成后另附验证报告并等待审查。不自行提交、合并或推送。证据见[实施报告](transfer-pause-start-direction-report.md)。 +状态:**C1–C4b 已提交并通过人工放行;C5 文档和相关合并验收已完成,待人工最终审查**。需求卡和七项拆分已确认。活跃恢复请求跳过且不排队,单次跳过不保证稍后自动恢复。C5 已汇总 P01–P18 证据、完成一次约定的相关合并回归和接口文档核对;未覆盖项与构建警告保留在报告,不以测试通过代替人工验收。不自行提交、合并或推送。证据见[实施报告](transfer-pause-start-direction-report.md)。 ## 1. 需求卡 @@ -188,7 +188,7 @@ relay 高水位证据按实际入队粒度计算:记录高水位、单次 enqu ## 6. 验收命令与报告要求 -各阶段实际命令与边界见实施报告。C1:81 passed;C2a:154 passed,告警修复后受影响 64 项通过。C2b 首轮 223 passed、2 failed、1 skipped,修复后两项通过;owner 检查 134 passed,既有回归 159 passed。C3 主验证 217 passed、3 deselected,既有转发/恢复 20 passed、73 deselected。C4a 主验证 42 passed、66 deselected;既有首轮 139 passed、2 failed、14 deselected,契约迁移后两项通过;重连检查 34 passed,最终监听交接 2 passed。C4b 首轮 137 passed、6 failed、63 deselected,测试断点屏障修正后六项通过;既有转发/恢复/握手 39 passed、69 deselected。不将定向重跑计作全量复跑;C5 尚未运行。 +各阶段实际命令与边界见实施报告。C1:81 passed;C2a:154 passed,告警修复后受影响 64 项通过。C2b 首轮 223 passed、2 failed、1 skipped,修复后两项通过;owner 检查 134 passed,既有回归 159 passed。C3 主验证 217 passed、3 deselected,既有转发/恢复 20 passed、73 deselected。C4a 主验证 42 passed、66 deselected;既有首轮 139 passed、2 failed、14 deselected,契约迁移后两项通过;重连检查 34 passed,最终监听交接 2 passed。C4b 首轮 137 passed、6 failed、63 deselected,测试断点屏障修正后六项通过;既有转发/恢复/握手 39 passed、69 deselected。不将定向重跑计作全量复跑。C5 一次相关合并回归为 **640 passed、1 skipped in 761.28s**;唯一 skip 为明文配置不适用重新交换。六个公开签名与 23 个 RST 锚点机械核对通过,Sphinx 构建退出 0 且已浏览实际页面;警告与未覆盖项见报告。 ```bash # C1/C2a:实现后新增必要边界契约 @@ -218,6 +218,6 @@ relay 高水位证据按实际入队粒度计算:记录高水位、单次 enqu - **公共协议/接口有变化**:四 token;direction 的角色定义;pause/start 必填 type/direction;移除旧 remote API;控制确认语义改为发送端权威;resume 活跃对象返回 False。 - **持久化数据模型不变**;运行时控制记录改变。查询返回 schema 不变。测试增加必要边界契约及迁移受影响断言,不降低验证强度。 -- **CI/依赖/覆盖率策略不变**。不宣称本计划覆盖未运行的多平台环境、NAT、多进程共享或任意网络中断组合。 +- **依赖/覆盖率策略不变**。C5 验证后用户单独授权将 CI Test job 的 timeout-minutes 从 10 调至 30;测试命令与矩阵不变。不宣称本计划覆盖未运行的多平台环境、NAT、多进程共享或任意网络中断组合。 - 新功能依赖存活且可投递的控制连接;仅有数据 socket 存活但控制连接不可用时,不承诺远程 pause/start。自然关闭路径按既有机制结束旧 leg。 -- 用户已授权开始 C4b,C4a 随该放行进入下一阶段。C4b 已完成转发资格和清理、定向验证及局部报告,待人工审查,详见[实施报告 C4b](transfer-pause-start-direction-report.md#c4b转发共享-source-恢复门槛与会话清理)。复用既有状态,不改变活跃请求不排队的约束,单次跳过不保证最终自动恢复。C5 尚未开始。本轮未创建提交、合并或推送。 +- 用户已授权开始 C5,C4b 随该放行进入收尾阶段。全部七项计划阶段已交付,C5 文档、逐路径总表和相关合并验收完成,待人工最终审查;本轮未修改生产代码或测试,未新增自动重试或活跃恢复队列。未覆盖项须由人类明确接受,测试通过不代替放行。本轮未创建提交、合并或推送。 diff --git a/docs/plans/transfer-pause-start-direction-report.md b/docs/plans/transfer-pause-start-direction-report.md index 61641c5..27a82c8 100644 --- a/docs/plans/transfer-pause-start-direction-report.md +++ b/docs/plans/transfer-pause-start-direction-report.md @@ -1,6 +1,6 @@ # 双向文件暂停、继续与按对象恢复 — 实施报告 -状态:需求卡和七项拆分已确认。**C1–C4a 已通过人工放行;C4b 已实现并完成局部验证,待人工审查;C5 未开始。** 本报告随已完成的原子变更增补,不将未实现或未运行的路径标为完成。本轮未创建提交、合并或推送。 +状态:需求卡和七项拆分已确认。**C1–C4b 已提交并通过人工放行;C5 文档与相关合并验收已完成,待人工最终审查。** 各阶段记录保留实际失败及定向重跑,不将未运行或未覆盖的场景标为完成。本轮未创建提交、合并或推送。 ## C1:严格解析、typed identity 与共享端点识别 @@ -421,7 +421,92 @@ C2a 后续审查结论:用户已审计放行,并明确授权开始 C2b,包 - 控制写入不是逐请求恢复确认;未回应请求按现有接收预留期限处理,实际 relay owner 不按时钟强制替换。 - 新场景验证 source 断线重连和 target 断线拒绝;未另加 target 同端点重连补传场景,不宣称网络时序全集已枚举。配置/持久化与加密的相关合并验收留在 C5。 - 本轮未改公共签名、wire、持久化 schema、CI、依赖或 coverage 策略;未删除测试或弱化内容/ACK/稳定身份断言。未运行 formatter、lint、文档构建、repo-wide suite 或多平台验证;Ruff 不支持 references,不能记作成功引用分析。 -- **C4b 待人工审查,未创建提交**。C5 未开始。 +- C4b 后续结论:用户已授权开始 C5,C4b 随该放行进入收尾阶段;C5 总表和合并回归见下节。 + +## C5:总体报告与合并验收 + +### 原子提交汇总 + +| 阶段 | 已观察提交 | 意图与审查状态 | +|---|---|---| +| C1 | `b02def0` | 严格 parser、typed identity、共享端点基础;已放行 | +| C2a | `01de684` | 发送端权威状态、FIFO、意图/确认分离、预置暂停;已放行 | +| C2b | `fd189d1` | 普通收发与 relay 生产接入、breaking API/wire 切换;已放行 | +| C3 | `86223f1` | child 定位、writer 隔离、用户/压力 OR、高水位门槛;已放行 | +| C4a | `11ba6ab` | 普通对象级恢复资格和原子占用;已放行 | +| C4b | `25aac75` | 共享 source 恢复资格、pending 接管和会话清理;已放行 | +| C5 | 本轮未提交 | 接口文档/逐路径总表完成;合并回归 640 passed、1 skipped;待人工最终验收 | + +### 总体数据流与架构影响 + +pause/start:公开 API 校验 fid/type/本地角色并归一 control peer → 精确 typed leg 与实际 socket/owner → S 决定状态或 R 登记意图 → per-leg FIFO 等待对端登记和安全通道 → 现有 send_message → 对端按实际会话验证、反转角色并处理 → S 通知确认。发送循环在新块之前读暂停状态;接收与在途落盘持续进行,start 不重建/seek/truncate。relay 每个 writer 独立控制,upstream 用户暂停与背压取 OR;source start 不解除 reader 独立高水位门槛。 + +resume:保留的进度/route 与 origin/target 校验 → 对象级资格和原子占用 → 原有 listener/port/安全握手 → 从 receiver 磁盘 offset、原 fid/路径继续 → 实际文件 ACK → 完成/保留中断状态并释放 owner。活跃/暂停/建连/清理对象返回 False,不关闭、不排队。离线 source 的 pending 保留最新 target offset,投递与 relay 复用同一 upstream 占用;未完成 route 仍由真实 ACK 决定。 + +公共变化:四 token pause/start、不兼容旧 remote API、必填 type/direction、异步登记不等于确认;resume 签名及五 token wire 保持,忙碌改为 False。持久化五字段、upload key、relay targets/completed 与 query schema 保持;typed 控制、FIFO、意图及恢复占用仅存内存。未改变 CI、依赖或覆盖率策略。 + +### P01–P18 逐路径对照 + +以下“覆盖”指已定义路径有运行/机械证据,非对任意网络时序或环境的穷举。合并回归结果在下节单列;各阶段的失败与修复记录保留在前文。 + +| 路径 | 结论 | 主要证据与边界 | +|---|---|---| +| P01 | 覆盖 | 单元 parser/本地参数拒绝;same_fid 实际连接输入旧/非法/type/fid 命令后经消息屏障检查状态不变 | +| P02 | 覆盖 | same_fid 双向普通实际内容/ACK、独立 socket;不同 peer 的真实同 fid 上传隔离、typed type/role key 契约;不授予进度行覆盖能力 | +| P03 | 覆盖 | pause_start 上传参数组:S/R 控制、同 socket 完成;receiver_keeps 验证已确认暂停后在途块仍落盘 | +| P04 | 覆盖 | 同 P03 的下载参数组,方向反转,真实最终 ACK 与内容 | +| P05 | 覆盖 | 全部三操作 FIFO 交错的确定性枚举;unconfirmed_reverse 与阻塞发送屏障验证本地/远端交叉、反向意图和排空收敛 | +| P06 | 覆盖 | empty_and_eof 真实最终 ACK;既有文件夹回归;C2b 临时脚本四个实际文件夹 leg 的 S pause/R start、内容和清理证据 | +| P07 | 覆盖 | 精确预置暂停接管/单次公布/解除;实际注册后通知;未知 wire 不建立控制状态;start 不留 False key | +| P08 | 覆盖 | 两 target 实际 child/合法 alias 控制、错误 peer/type/role 屏障;另一 writer 内容/ACK 完成;exact child 数字交叉和陈旧 alias 单元契约 | +| P09 | 覆盖 | relay_pressure 固定 source/用户/背压交叉,reader 被唤醒仍回到压力门槛、读取计数不增;peak ≤ high_water + max_enqueue | +| P10 | 覆盖 | 慢/断 target 的有界缓冲、其他目标完成、上游失败及未完成 route 保留;disconnected_target 验证活跃共享 source 不重放 | +| P11 | 覆盖,有限交错 | plain/encrypted 配置实际控制;真实强制 re-key 持有 key publication,reader 继续处理 key、控制帧无明文;relay 实际 encrypted 帧。未另跑 relay 专用 re-key 组合全集 | +| P12 | 覆盖 | localhost/concrete/wildcard 的普通与转发场景,真实 socket 关闭回退与同端口异地址拒绝;source 原端点重连和旧 control 迟到清理 | +| P13 | 覆盖 | 三组实际 channel:plain、encrypted、encrypted async/tracking off;运行控制/恢复/关闭不依赖新增进度行,receiver 未阻塞密钥交换 | +| P14 | 覆盖 | online_resume 上传/下载:control 在线、真实 partial offset、唯一新 owner、独立反向 leg 原 socket 保持、内容/ACK | +| P15 | 覆盖 | 活跃/暂停/协商/接收监听/旧 finally 屏障拒绝;并发只有一次 True/worker,busy 不关闭或排队;EOF 行仍可补最终确认 | +| P16 | 覆盖 | shared source 活跃拒绝、离线 pending 最新 offset、重连稳定 fid/route/completed;零偏移、空文件与 EOF 真实恢复,完成 sibling 不重放 | +| P17 | 覆盖定义分支 | 普通双向及 relay source/target 实际断线均退出旧 worker/清控制;source 重连新 owner 默认运行,旧记录迟到释放无效。未另跑 target 同端点重连补传组合 | +| P18 | 覆盖定义分支 | query schema/typed paused 投影、实际 JSON 无控制字段、route reload、预置不挡路由/真 owner 冲突、真实 stop 后清理及配置删除/重复 stop 契约 | + +### C5 当前文档与机械核对 + +修正 Client API 仍描述 target 排队/重复合并的段落;历史 changelog 标明其已被 C4a/C4b 替代。三份 RST 明确 receiver 的未确认重复请求可能再次登记并返回 True、控制登记不等于 ACK、同 socket start、对象级恢复、无 wildcard/resume-all、data-only failure 不新增自动重试,以及活跃共享 source 被跳过后需重新请求。 + +临时标准输入脚本通过 inspect.signature 核对六个公开方法:四个 pause/start 都要求 keyword-only type/direction;Server peer 必填,Client peer=None;两个 resume 均为 `(self, peer_addr, fid, offset)`;旧 remote 符号不存在。三份 RST 共检查 23 个显式锚点,transfer 引用全部解析,未保留旧 remote 或当前 coalescing 说明。结果 PASS,未落盘脚本。 + +文档完整构建: + +```bash +.venv/bin/python -m sphinx -b html -q -w /tmp/pyflow-c5-docs-ihOz0C/warnings.log docs/source /tmp/pyflow-c5-docs-ihOz0C/html +``` + +退出码 **0**,墙钟 **14.54s**;两项警告为 `html_static_path` 的 `_static` 不存在,以及 `command_control_extension_tcp` 模块 docstring 第 23 行 definition list 缩进。完成最终措辞后对同一输出目录增量构建,退出码 **0**、墙钟 **2.30s**,仅 `_static` 警告;不把增量构建未重读的 docstring 警告记为已修复。未改 Sphinx 配置或无关 docstring。 + +通过真实浏览器打开构建的 File_Transfer 页面和控制章节锚点,观察并截取当前签名、typed 角色、wire 与返回值说明;Client API 页面文本确认包含共享 upstream 的拒绝规则和未确认请求说明,不再包含重复合并旧规则。浏览器页已关闭。构建输出位于 `/tmp/pyflow-c5-docs-ihOz0C/html`,没有写入仓库。 + +### C5 相关合并回归 + +执行一次计划中的相关合并回归,不含 repo-wide suite: + +```bash +.venv/bin/python -m pytest test/unit/network_api test/integration/network_api/test_tcp_transfer_control.py test/integration/network_api/test_tcp_file_transfer.py test/integration/network_api/test_tcp_transfer_resume.py test/integration/network_api/test_crypto_tcp.py test/integration/network_api/test_tcp_async_server.py test/integration/test_forward_extension.py test/integration/test_forward_msg_attribution.py -q +``` + +**640 passed、1 skipped in 761.28s(12 分 41 秒)**,墙钟 **761.77s**。该命令执行一次,无失败、无 deselected;本轮未因结果通过而重复或扩大套件。唯一 skip 是 plain fixture 不适用的重新交换场景(`test_receiver_pause_start_waits_for_real_rekey_without_blocking_key_reader`),两组加密配置实际运行。原始输出见本会话 `artifact://70`。 + +C5 本轮只修改三份接口 RST、变更记录、计划和本报告,未修改生产实现或测试。总体数据流、六个实现提交、P01–P18 路径结论、实际文档构建及浏览器证据已汇总;上述合并回归是本次最终代码状态的相关验证,不替代逐路径运行证据或人工审查。已完成全部七项计划阶段的交付,最终人工验收、提交/合并和远端操作尚未批准。 + +C5 验证后,用户单独授权将 `.github/workflows/ci.yml` 的 Test job 超时从 10 分钟调至 30 分钟。测试命令、OS/Python 矩阵和覆盖率策略不变;未改其他 job。仅核对工作流配置,不为时限调整重复运行测试,也未触发远端 Actions。 + +### 明确限制与最终人工闸门 + +- 活跃恢复不排队、无逐请求 wire 拒绝 ACK;target 单次重连请求被跳过后需再次发起。离线已有多 target pending 同 upstream 一次只投递一个,余项等待后续合格 flush/请求/重连触发;未增加最终自动补传保证。 +- 单元状态契约加实际路径证据不等于任意调度穷举。未覆盖 relay 专用 re-key 全组合、target 同端点重连补传、NAT/端口改变、多进程进度共享、多平台和所有网络中断组合;已按各阶段报告边界披露,最终需人工接受。 +- 最终 ACK 超时仍保守保留进度;控制可用且可投递是远程 pause/start 前提。缓冲允许一次 enqueue fan-out 的有限超调,不承诺绝不超过阈值。 +- 规则沉淀为 typed 双向隔离、FIFO 收敛、对象原子恢复与 owner 清理契约;未删除测试或降 coverage。C5 验证后仅按用户单独授权延长 Test job 时限,未改测试命令与矩阵。阶段 C2b/C4a 规模偏差已随后续放行记录保留;C5 以文档与合并验证收尾。 +- 本轮不创建提交、合并或推送。最终报告须由人类审查放行;合并/远端提交另需明确授权。 ## 公共协议/API 变更许可记录 diff --git a/docs/source/File_Transfer/File_Transfer.rst b/docs/source/File_Transfer/File_Transfer.rst index 1a34180..669b26f 100644 --- a/docs/source/File_Transfer/File_Transfer.rst +++ b/docs/source/File_Transfer/File_Transfer.rst @@ -862,12 +862,13 @@ in-flight receive and disk write: pause does not promise an immediate freeze of the receiving file. Start releases the same open data socket without a new handshake, offset or seek. -A real state change on a registered leg returns ``True``; this reports the -local operation, not a peer acknowledgement. Duplicate operations return -``False``. Presetting a pause for an exact, not-yet-active sender identity -also returns ``False`` while retaining that pause for registration. Pause state -is runtime-only and is never persisted. Reconnect cleanup releases paused -waiters, clears their state and closes the old sockets before replay. +A registered sender state change or receiver request returns ``True``; this +reports local registration, not peer acknowledgement. A sender's same-state +operation returns ``False``. A receiver ignores an operation only when its +target equals both confirmed and last-requested state; unconfirmed duplicates +may therefore return ``True``. Presetting an exact, not-yet-active sender pause +returns ``False`` while retaining it for registration. Pause state is never +persisted. Reconnect clears old control state and closes sockets before replay. Ordinary recovery is per object: ``resume_trans(peer_addr, fid, offset)`` returns ``True`` only when a new recovery worker is reserved. A running, @@ -981,10 +982,12 @@ per target. Resumes reuse the existing upstream and child FIDs. Public-key pushes remain untracked and TOFU verification still precedes their ACK. -The server requests a peer's interrupted downloads when that peer reconnects, -and a client with ``is_auto_reconnect=True`` does the same after every connect, -so no separate call is needed. Legs the previous session left behind are closed -before the resume runs, so two legs never write the same transfer. +After reconnect, the server requests that peer's eligible interrupted downloads, +and the client runs the same per-object request pass. Manual recovery can use +the existing control connection; a data-only failure does not start a new retry +loop. There is no wildcard-FID or public resume-all command. Existing owners +finish cleanup before automatic recovery; busy shared relays follow the skip +rule above rather than promising completion from one reconnect request. .. _related-apis: diff --git a/docs/source/Network_APIs/TCP_Client_APIs.rst b/docs/source/Network_APIs/TCP_Client_APIs.rst index 4f0cd5a..cf84ad6 100644 --- a/docs/source/Network_APIs/TCP_Client_APIs.rst +++ b/docs/source/Network_APIs/TCP_Client_APIs.rst @@ -868,9 +868,10 @@ local_role)`` independently of the progress row's logical receiver. The sender owns confirmed pause state. A receiver records its local request and waits for an eventual sender notification; secure sends are asynchronous and ordered per leg. In-flight receives and disk writes continue. Start uses -the same data socket without a new handshake or seek. A changed registered -operation returns ``True``, not a peer ACK; duplicates and preset sender pauses -before registration return ``False``. Pause is runtime-only. See +the same data socket without a new handshake or seek. A registered sender +change or receiver request returns ``True``, not a peer ACK. Known duplicates +return ``False``; an unconfirmed receiver request may be sent again. A preset +sender pause returns ``False`` before registration. Pause is runtime-only. See :ref:`transfer-pause-and-reconnect` for details. The upload value's ``peer`` is the original receiver; ``resume_offset`` continues the interrupted file from the byte the receiver already holds. @@ -882,9 +883,9 @@ marker. The wait is 30 seconds plus 10 seconds per 100 MiB; a long pause or slow delivery can outlast it, and a lost ACK conservatively retains state. No separate receipt or retry protocol is used. Direct transfer and public-key confirmation remain data-ACK based. The server retains the upstream/child IDs -and full target mapping. Transient source locks serialize different target -requests on one upload and coalesce concurrent duplicates; they hold no file -metadata and are released after the last in-flight request. +and full target mapping. Transient ownership admits one recovery per upstream +FID; another target's request is rejected while that source is live or reserved. +After cleanup it must be requested again; no active-source queue is retained. We recommend that for client-to-server file transfers, you use the console commands (``/file``, ``/file_folder``, diff --git a/docs/source/Network_APIs/TCP_Server_APIs.rst b/docs/source/Network_APIs/TCP_Server_APIs.rst index e005156..6bb59b3 100644 --- a/docs/source/Network_APIs/TCP_Server_APIs.rst +++ b/docs/source/Network_APIs/TCP_Server_APIs.rst @@ -681,9 +681,10 @@ Built-in client commands include: local data role (``0`` sender, ``1`` receiver). The wire role describes the issuer. Both methods update local control and notify the peer; sender state is authoritative and receiver confirmation is eventual. An in-flight receive - and write continues, and start uses the same data socket. A changed registered - operation returns ``True``, not a peer ACK; duplicates and a preset sender - pause before registration return ``False``. ``peer`` is always required. + and write continues, and start uses the same data socket. A registered sender + change or receiver request returns ``True``, not a peer ACK. Known duplicates + return ``False``; an unconfirmed receiver request may be sent again. A preset + sender pause returns ``False`` before registration. ``peer`` is required. See :ref:`transfer-pause-and-reconnect` for control identity and cleanup. Forwarded requests carry a source-allocated ``fid=``. A new upload omits ``resume=``; replay includes ``resume=``, including zero, diff --git a/docs/source/changes/transfer-fid-routes.md b/docs/source/changes/transfer-fid-routes.md index 3d5c631..f27a61b 100644 --- a/docs/source/changes/transfer-fid-routes.md +++ b/docs/source/changes/transfer-fid-routes.md @@ -1,11 +1,13 @@ # Change note: server FID routes, sender ownership and socket/FID recovery -> Atomic changes 1–4 and supplemental O1–O4 passed human review; their historical -> reports remain unchanged. Sender-ownership revision R1 and socket/FID revision -> R2 are implemented and verified, awaiting human review. The final affected suite -> passed 434 tests; independent plaintext/encrypted runs and the documentation -> build passed. Known lint/doc warnings and earlier failed runs are disclosed in -> `docs/plans/transfer-sender-fid-r2-report.md`. No commit, merge or push. +> Current transfer-control contract: C1–C4b are committed and have passed their +> stage review gates; C5 documentation and combined acceptance are complete, +> pending final human review. +> The chronological entries below preserve earlier implementation history; +> C2b supersedes the old pause/start API and wire format, and C4a/C4b supersede +> queued/coalesced active recovery and immediate sweep ownership release. +> Current behavior and evidence are in +> `docs/plans/transfer-pause-start-direction-report.md`. ## Revision R1: sender-owned relay upstream FID @@ -73,7 +75,7 @@ R1 behavior evidence and remaining review items are in regeneration or replacement translations are supplied; new source text uses English fallback pending translation. -## Atomic change 4: one recovery command and one source of file metadata +## Historical atomic change 4: one recovery command and one source of file metadata - The sole resume wire is `/resume_trans `, with shell-quoted tuple endpoints. Server checks target against the actual requester, @@ -304,6 +306,9 @@ file preservation. Runtime evidence and explicit exclusions are recorded in ## Follow-up: reconnect sweep releases paused legs +This describes the pre-control-registry sweep. C2b replaces its wait helper; +C4a retains ownership until final cleanup and rejects active resume requests. + - `_drop_stale_transfers` now clears the pause switch of every upload leg it sweeps (after closing the socket, outside the progress lock) and wakes the pause condition. `_wait_transfer_paused` also takes the leg's own transfer @@ -454,3 +459,25 @@ file preservation. Runtime evidence and explicit exclusions are recorded in exclusions and runtime evidence are in the C4b report; combined acceptance remains the C5 review stage. +## Transfer control C5: current contract and combined acceptance + +- Current File_Transfer and TCP API documentation now distinguishes sender + changes from receiver requests, including unconfirmed duplicate requests. + Recovery documentation states the per-object busy rule, no active-source + queue, no wildcard resume-all command and no new data-only retry loop. +- Historical queued/coalesced recovery and immediate sweep-release notes are + explicitly superseded by C4a/C4b. The implementation report maps P01–P18 to + runtime evidence, records the six implementation commits and retains known + limitations rather than treating unit passes as global-property proof. +- Public signatures and RST transfer targets passed mechanical checks. Sphinx + generated the HTML documentation successfully, and the actual control/API + pages were inspected in a browser. Existing static-path and docstring + warnings are retained in the report; no unrelated configuration was changed. +- The planned combined regression ran once: 640 passed and one skipped in + 761.28 seconds. The skip is the plaintext fixture's inapplicable re-key case; + encrypted variants ran. C5 changes documentation only; final human acceptance + and any commit, merge or push remain separate gates. +- After C5 verification, the user separately authorized increasing the CI Test + job timeout from 10 to 30 minutes. Test commands, matrix and coverage policy + are unchanged. + From 5f7357b55b0e4d764f8da4e00bf3d1eae523e05a Mon Sep 17 00:00:00 2001 From: F18-Ray Date: Tue, 17 Nov 2026 08:54:20 +0800 Subject: [PATCH 08/19] test(connect_tcp): fix cross-version and Windows transfer control fixtures --- .../transfer-pause-start-direction-plan.md | 4 +- .../transfer-pause-start-direction-report.md | 40 ++++++++++++++++- docs/source/changes/transfer-fid-routes.md | 18 ++++++++ .../network_api/test_tcp_transfer_control.py | 44 ++++++++++++++++--- 4 files changed, 98 insertions(+), 8 deletions(-) diff --git a/docs/plans/transfer-pause-start-direction-plan.md b/docs/plans/transfer-pause-start-direction-plan.md index 709970e..4064eb3 100644 --- a/docs/plans/transfer-pause-start-direction-plan.md +++ b/docs/plans/transfer-pause-start-direction-plan.md @@ -1,6 +1,6 @@ # 双向文件暂停、继续与按对象恢复 — 需求卡与更改计划 -状态:**C1–C4b 已提交并通过人工放行;C5 文档和相关合并验收已完成,待人工最终审查**。需求卡和七项拆分已确认。活跃恢复请求跳过且不排队,单次跳过不保证稍后自动恢复。C5 已汇总 P01–P18 证据、完成一次约定的相关合并回归和接口文档核对;未覆盖项与构建警告保留在报告,不以测试通过代替人工验收。不自行提交、合并或推送。证据见[实施报告](transfer-pause-start-direction-report.md)。 +状态:**C1–C5 已交付;后续跨平台测试屏障修复已完成,Linux CPython 3.14.4 带 coverage 的完整控制文件通过,native Windows 仍待 CI 验证及人工审查**。历史 C5 与用户提供的 CI 失败均保留,不将 Linux 通过等同于 Windows 通过。恢复语义、依赖和 CI 检查策略不变;修复范围与平台边界见[实施报告](transfer-pause-start-direction-report.md#后续-ci-修复python-314-文件缓冲与-windows-连接断线注入)。不自行提交、合并或推送。 ## 1. 需求卡 @@ -220,4 +220,4 @@ relay 高水位证据按实际入队粒度计算:记录高水位、单次 enqu - **持久化数据模型不变**;运行时控制记录改变。查询返回 schema 不变。测试增加必要边界契约及迁移受影响断言,不降低验证强度。 - **依赖/覆盖率策略不变**。C5 验证后用户单独授权将 CI Test job 的 timeout-minutes 从 10 调至 30;测试命令与矩阵不变。不宣称本计划覆盖未运行的多平台环境、NAT、多进程共享或任意网络中断组合。 - 新功能依赖存活且可投递的控制连接;仅有数据 socket 存活但控制连接不可用时,不承诺远程 pause/start。自然关闭路径按既有机制结束旧 leg。 -- 用户已授权开始 C5,C4b 随该放行进入收尾阶段。全部七项计划阶段已交付,C5 文档、逐路径总表和相关合并验收完成,待人工最终审查;本轮未修改生产代码或测试,未新增自动重试或活跃恢复队列。未覆盖项须由人类明确接受,测试通过不代替放行。本轮未创建提交、合并或推送。 +- C1–C5 已交付,后续按用户提供的 Linux/Windows CI 错误修复测试的真实写入观察、wildcard 连接目的地址和 source 断线注入;不改生产控制/恢复语义或放宽内容/ACK 断言。Python 3.10 定向 18 项通过;Linux CPython 3.14.4 带 coverage 的完整控制文件 71 passed、1 skipped(明文 re-key 不适用)。native Windows 仍需后续 CI 结果,修复及报告待人工审查。本轮未创建提交、合并或推送。 diff --git a/docs/plans/transfer-pause-start-direction-report.md b/docs/plans/transfer-pause-start-direction-report.md index 27a82c8..7606935 100644 --- a/docs/plans/transfer-pause-start-direction-report.md +++ b/docs/plans/transfer-pause-start-direction-report.md @@ -1,6 +1,6 @@ # 双向文件暂停、继续与按对象恢复 — 实施报告 -状态:需求卡和七项拆分已确认。**C1–C4b 已提交并通过人工放行;C5 文档与相关合并验收已完成,待人工最终审查。** 各阶段记录保留实际失败及定向重跑,不将未运行或未覆盖的场景标为完成。本轮未创建提交、合并或推送。 +状态:需求卡和七项拆分已确认。**C1–C5 已交付;后续跨平台测试屏障修复已完成,Linux CPython 3.14.4 带 coverage 的完整控制文件通过,native Windows 仍待 CI 验证及人工审查。** 保留先前 Python 3.10 验收和用户提供的 CI 失败记录,不将 Linux 通过等同于 Windows 已通过。本轮未创建提交、合并或推送。 ## C1:严格解析、typed identity 与共享端点识别 @@ -508,6 +508,44 @@ C5 验证后,用户单独授权将 `.github/workflows/ci.yml` 的 Test job 超 - 规则沉淀为 typed 双向隔离、FIFO 收敛、对象原子恢复与 owner 清理契约;未删除测试或降 coverage。C5 验证后仅按用户单独授权延长 Test job 时限,未改测试命令与矩阵。阶段 C2b/C4a 规模偏差已随后续放行记录保留;C5 以文档与合并验证收尾。 - 本轮不创建提交、合并或推送。最终报告须由人类审查放行;合并/远端提交另需明确授权。 +## 后续 CI 修复:Python 3.14 文件缓冲与 Windows 连接/断线注入 + +### 用户报告与定位 + +- Linux GitHub Actions(Python 3.14.4、coverage)实际结果:12 failed、930 passed、1 skipped,647.97s;失败为 in-flight 写入和在线恢复的双向三配置用例,各六项。 +- Windows GitHub Actions(Python 3.14.10)实际结果:10 failed、906 passed、3 skipped、24 setup errors,602.29s。除相同写入屏障外,24 项 async/wildcard 夹具均无法 connect,另两项 source 断线注入未到达预期断线状态。报告是本轮复现依据,未先重跑旧测试确认。 +- 本机解释器输出:Python 3.10 的 `io.DEFAULT_BUFFER_SIZE=8192`,标准 CPython 3.14.4 为 `131072`。生产接收循环通过正常 buffered file 的 write 写入,progress 在 write 返回后更新,文件退出上下文后关闭。64 KiB 首块在 3.14 可留在用户态缓冲,暂停期间 stat 大小不等同于 write 未执行;旧测试把这两者混为一谈。 +- wildcard 夹具将 `0.0.0.0` 同时用于 server bind 和 client connect;Windows 不接受这个远端目的地址。既有跨平台身份测试采用 wildcard bind + loopback connect。 +- source 断线用例原从 server accepted socket 调用 shutdown,并依赖同一 socket 上阻塞的服务端 recv 同时退出;Windows 日志显示该状态未到达。本轮从 source client socket 注入 shutdown,与既有实际会话断线测试一致,仍等待双端真实退出,不直接删除 registry 代替断线。 + +### 修改与不变量 + +仅修改 `test/integration/network_api/test_tcp_transfer_control.py` 的夹具/观察屏障:新增小型 `_observe_target_writes`,包裹实际目标文件的 write,真实调用返回后累计字节并在指定块完整写入后发 Event。两组失败场景检查完整首块等于 payload 对应 slice;在线恢复仍在旧接收 owner 退出、文件关闭后检查 partial 的磁盘内容和恢复 offset,完整文件内容、实际最终 ACK、socket/owner 清理断言全部保留。 + +Server 继续 wildcard bind,Client 连接 loopback,async/encrypted/tracking off 三项配置保持;source 故障从 Client 端注入真实 shutdown。没有 flush 每块文件来迎合测试、缩小缓冲、禁用加密/async、延长等待、增加 retry/skip 或修改生产暂停/恢复语义;CI 命令、矩阵和 coverage 策略未改。 + +### 验证 + +Python 3.10 受影响场景: + +```bash +.venv/bin/python -m pytest test/integration/network_api/test_tcp_transfer_control.py::test_receiver_keeps_writing_inflight_data_after_confirmed_pause test/integration/network_api/test_tcp_transfer_control.py::test_online_resume_reserves_one_owner_and_uses_receiver_disk_offset test/integration/network_api/test_tcp_transfer_control.py::test_relay_offline_source_replays_stable_route_or_stops_cleanly -q +``` + +**18 passed in 108.23s**(墙钟 108.56s)。 + +标准 CPython 3.14.4 带覆盖率的完整控制文件: + +```bash +COVERAGE_FILE=/tmp/pyflow-ci-fix-314.coverage uv run --isolated --no-project --python cpython-3.14.4-linux-x86_64-gnu --with pytest --with pytest-cov --with flask python -m pytest test/integration/network_api/test_tcp_transfer_control.py --cov=PyFlow.network_api.connect_tcp --cov-report=term -q +``` + +**71 passed、1 skipped in 331.25s**(墙钟 335.09s),平台 linux、CPython 3.14.4。唯一 skip 为 plain 配置不适用重新交换,两组 encrypted 实际运行;没有新增 skip。该控制文件单独执行时 connect_tcp.py 覆盖率为 **62%**,不是全套覆盖率结果,不与用户 CI 全套的 81% 混同。临时隔离 uv 环境使用 pytest/pytest-cov/flask,未修改项目依赖或锁文件;coverage 数据写入 `/tmp`。 + +本轮修复仅涉及一个测试文件及现有计划/报告/变更记录,Python 3.10 和 3.14 的定向检查完成,不重复运行全仓库套件。当前无 native Windows 运行环境,通配绑定/loopback 连接与 source Client shutdown 的修复仍需后续 Windows Actions 确认;没有把 Linux 结果记成 Windows 通过,也未触发远端工作流。 + +Windows 原日志中的 `WinError 995` 出现在夹具连接失败后的 Proactor accept 清理阶段;本轮未屏蔽异常或改事件循环。loopback 连接修复后该清理警告是否仍出现,必须由 native Windows CI 确认,不能依据 Linux 结果推定已消失。 + ## 公共协议/API 变更许可记录 用户审查放行 C2a 并授权开始 C2b;下列协议/API 按已确认计划执行切换。恢复资格的新语义按 C4a/C4b 后续实施。 diff --git a/docs/source/changes/transfer-fid-routes.md b/docs/source/changes/transfer-fid-routes.md index f27a61b..4075e7c 100644 --- a/docs/source/changes/transfer-fid-routes.md +++ b/docs/source/changes/transfer-fid-routes.md @@ -481,3 +481,21 @@ C4a retains ownership until final cleanup and rejects active resume requests. job timeout from 10 to 30 minutes. Test commands, matrix and coverage policy are unchanged. +## Transfer control CI follow-up: portable write and connection barriers + +- Live receive tests observe the real target write and verify admitted payload + bytes instead of treating stat growth on an open buffered file as completion. + Python 3.14's larger default buffer can retain the first 64 KiB chunk until + close; resumed partial-file contents and offsets are still checked after the + old receiver exits, and final content/ACK assertions remain intact. +- Wildcard scenarios retain the server's 0.0.0.0 bind while clients connect to + loopback, which is also valid on Windows. Source-disconnect injection shuts + down the actual client socket and still waits for both ends to exit. +- Production control and persistence behavior, test timeouts, crypto/async + coverage, CI configuration and skip policy are unchanged. Native Windows + results must come from a subsequent CI run; Linux is not Windows evidence. +- Verification passed 18 affected cases on Python 3.10 and the full control + file on Linux CPython 3.14.4 with coverage: 71 passed, one existing plaintext + re-key skip in 331.25 seconds. The subset's coverage is not a full-suite + measurement. Native Windows still requires a subsequent Actions run. + diff --git a/test/integration/network_api/test_tcp_transfer_control.py b/test/integration/network_api/test_tcp_transfer_control.py index 6c0375d..e825b7d 100644 --- a/test/integration/network_api/test_tcp_transfer_control.py +++ b/test/integration/network_api/test_tcp_transfer_control.py @@ -17,7 +17,7 @@ @pytest.fixture(params=[ (False, False, True, "127.0.0.1", "localhost"), (True, False, True, "127.0.0.1", "127.0.0.1"), - (True, True, False, "0.0.0.0", "0.0.0.0"), + (True, True, False, "0.0.0.0", "127.0.0.1"), ], ids=["plain-alias", "encrypted", "encrypted-async-untracked-wildcard"]) def channel(request, tmp_path, monkeypatch): encrypted, asynchronous, tracked, bind_host, configured_host = request.param @@ -77,6 +77,30 @@ def start(worker, *args, **kwargs): assert not any(worker.is_alive() for worker in workers) +def _observe_target_writes(monkeypatch, output, byte_count): + """Observe real writes without assuming buffered bytes are visible to stat.""" + written, received = bytearray(), threading.Event() + real_open = connect_tcp._open_transfer_target + + def open_target(path, offset): + target = real_open(path, offset) + if Path(path) == output: + real_write = target.write + + def write(data): + count = real_write(data) + written.extend(data[:count]) + if len(written) >= byte_count: + received.set() + return count + + monkeypatch.setattr(target, "write", write) + return target + + monkeypatch.setattr(connect_tcp, "_open_transfer_target", open_target) + return written, received + + def _leg(channel, tmp_path, monkeypatch, server_sends, *, fid=720, offset=0, payload=None): server, client, releases = channel sender, receiver = (server, client) if server_sends else (client, server) @@ -283,8 +307,12 @@ def test_empty_and_eof_progress_complete_with_real_ack(channel, tmp_path, monkey def test_receiver_keeps_writing_inflight_data_after_confirmed_pause( channel, tmp_path, monkeypatch, server_sends ): + receiver = channel[1] if server_sends else channel[0] + output = Path(receiver.file_transfer_dir) / ("download.bin" if server_sends else "upload.bin") + sender = channel[0] if server_sends else channel[1] + written, received = _observe_target_writes(monkeypatch, output, sender.file_transfer_chunk_len) leg = _leg(channel, tmp_path, monkeypatch, server_sends) - sender, receiver, states, body_release, _, _, output, _ = leg + sender, receiver, states, body_release, _, _, output, payload = leg inflight, send_release = threading.Event(), threading.Event() channel[2].append(send_release) real_send = sender.send_message @@ -303,9 +331,10 @@ def hold_first_chunk(sock, message, is_send_raw=False): assert _control(receiver, states[1], True) _confirmed(states, True) send_release.set() - assert wait_until(lambda: output.exists() and output.stat().st_size > 0), ( + assert received.wait(timeout=10), ( "receiver pause blocked a chunk already admitted by the sender" ) + assert written == payload[:sender.file_transfer_chunk_len] assert sender._transfer_pause == {states[0]["key"]: True} assert states[1]["key"] not in receiver._transfer_pause assert _control(receiver, states[1], False) @@ -635,6 +664,10 @@ def test_online_resume_reserves_one_owner_and_uses_receiver_disk_offset( channel, tmp_path, monkeypatch, server_sends ): other = _leg(channel, tmp_path, monkeypatch, not server_sends) + receiver = channel[1] if server_sends else channel[0] + output = Path(receiver.file_transfer_dir) / ("download.bin" if server_sends else "upload.bin") + sender = channel[0] if server_sends else channel[1] + written, received = _observe_target_writes(monkeypatch, output, sender.file_transfer_chunk_len) leg = _leg(channel, tmp_path, monkeypatch, server_sends, offset=1) sender, receiver, states, body_release, worker, result, output, payload = leg peer, fid = key = states[0]["key"][:2] @@ -672,7 +705,8 @@ def hold_cleanup(transfer_key, sock): body_release.set() assert partial.wait(timeout=10) # the second wait follows one real chunk disk = 1 + sender.file_transfer_chunk_len - assert wait_until(lambda: output.stat().st_size == disk) + assert received.wait(timeout=10) + assert written == payload[1:disk] assert _control(sender, states[0], True) _confirmed(states, True) old_socket.shutdown(socket.SHUT_RDWR) # keep the existing control session @@ -890,7 +924,7 @@ def hold(instance, state, sock): if fault == "stop": server.stop() else: - old_server.shutdown(socket.SHUT_RDWR) + old_client.shutdown(socket.SHUT_RDWR) assert wait_until(lambda: not source.running and origin not in server.clients) source.receive_thread.join(timeout=10) source._release_client_socket() From d4cb4ab5ce0023d6ba971a80626d6c4193c759e4 Mon Sep 17 00:00:00 2001 From: F18-Ray Date: Tue, 17 Nov 2026 09:20:53 +0800 Subject: [PATCH 09/19] test(connect_tcp): preserve source identity in relay reconnect scenarios --- .../transfer-pause-start-direction-plan.md | 4 +-- .../transfer-pause-start-direction-report.md | 28 ++++++++++++++++++- docs/source/changes/transfer-fid-routes.md | 19 +++++++++++++ .../network_api/test_tcp_transfer_control.py | 11 ++++++-- 4 files changed, 56 insertions(+), 6 deletions(-) diff --git a/docs/plans/transfer-pause-start-direction-plan.md b/docs/plans/transfer-pause-start-direction-plan.md index 4064eb3..237cb69 100644 --- a/docs/plans/transfer-pause-start-direction-plan.md +++ b/docs/plans/transfer-pause-start-direction-plan.md @@ -1,6 +1,6 @@ # 双向文件暂停、继续与按对象恢复 — 需求卡与更改计划 -状态:**C1–C5 已交付;后续跨平台测试屏障修复已完成,Linux CPython 3.14.4 带 coverage 的完整控制文件通过,native Windows 仍待 CI 验证及人工审查**。历史 C5 与用户提供的 CI 失败均保留,不将 Linux 通过等同于 Windows 通过。恢复语义、依赖和 CI 检查策略不变;修复范围与平台边界见[实施报告](transfer-pause-start-direction-report.md#后续-ci-修复python-314-文件缓冲与-windows-连接断线注入)。不自行提交、合并或推送。 +状态:**C1–C5 已交付;Windows 原端点重连故障的测试关闭顺序已修正,Linux CPython 3.14.4 带 coverage 的三个受影响参数组通过,native Windows 仍待 Actions 验证及人工审查**。历史结果与本轮中间失败保留;不将 Linux 通过等同于 Windows 通过。生产恢复语义、依赖和 CI 检查策略不变,证据及平台边界见[实施报告](transfer-pause-start-direction-report.md)。不自行提交、合并或推送。 ## 1. 需求卡 @@ -220,4 +220,4 @@ relay 高水位证据按实际入队粒度计算:记录高水位、单次 enqu - **持久化数据模型不变**;运行时控制记录改变。查询返回 schema 不变。测试增加必要边界契约及迁移受影响断言,不降低验证强度。 - **依赖/覆盖率策略不变**。C5 验证后用户单独授权将 CI Test job 的 timeout-minutes 从 10 调至 30;测试命令与矩阵不变。不宣称本计划覆盖未运行的多平台环境、NAT、多进程共享或任意网络中断组合。 - 新功能依赖存活且可投递的控制连接;仅有数据 socket 存活但控制连接不可用时,不承诺远程 pause/start。自然关闭路径按既有机制结束旧 leg。 -- C1–C5 已交付,后续按用户提供的 Linux/Windows CI 错误修复测试的真实写入观察、wildcard 连接目的地址和 source 断线注入;不改生产控制/恢复语义或放宽内容/ACK 断言。Python 3.10 定向 18 项通过;Linux CPython 3.14.4 带 coverage 的完整控制文件 71 passed、1 skipped(明文 re-key 不适用)。native Windows 仍需后续 CI 结果,修复及报告待人工审查。本轮未创建提交、合并或推送。 +- 首轮跨版本修复的 Linux CPython 3.14.4 完整控制文件为 71 passed、1 skipped;后续 Windows 报告 source 原端点重连 3 failed、2 teardown errors。本轮修正为 Server `SHUT_WR` 半关闭、source EOF 后释放 Client socket、最后等待 Server 自行注销;直接 close 的中间尝试在 Linux async 复验失败,记录保留。半关闭最终方案在 Linux CPython 3.14.4 带 coverage 的三个受影响参数组全部通过(27.90s),原端点/内容/ACK/清理断言不变,并增加残留线程名称诊断。native Windows 的端口复用、加密 teardown 和 WinError 995 仍需后续 Actions 确认。未创建提交、合并或推送。 diff --git a/docs/plans/transfer-pause-start-direction-report.md b/docs/plans/transfer-pause-start-direction-report.md index 7606935..b9d4b0d 100644 --- a/docs/plans/transfer-pause-start-direction-report.md +++ b/docs/plans/transfer-pause-start-direction-report.md @@ -1,6 +1,6 @@ # 双向文件暂停、继续与按对象恢复 — 实施报告 -状态:需求卡和七项拆分已确认。**C1–C5 已交付;后续跨平台测试屏障修复已完成,Linux CPython 3.14.4 带 coverage 的完整控制文件通过,native Windows 仍待 CI 验证及人工审查。** 保留先前 Python 3.10 验收和用户提供的 CI 失败记录,不将 Linux 通过等同于 Windows 已通过。本轮未创建提交、合并或推送。 +状态:需求卡和七项拆分已确认。**C1–C5 已交付;Windows 原端点重连故障的测试关闭顺序已修正,Linux CPython 3.14.4 带 coverage 的三个受影响参数组通过,native Windows 仍待 Actions 验证及人工审查。** 历史 Linux 结果、两轮 Windows 失败及本轮中间失败均保留,不将 Linux 验证等同于 Windows 通过。本轮未创建提交、合并或推送。 ## C1:严格解析、typed identity 与共享端点识别 @@ -546,6 +546,32 @@ COVERAGE_FILE=/tmp/pyflow-ci-fix-314.coverage uv run --isolated --no-project --p Windows 原日志中的 `WinError 995` 出现在夹具连接失败后的 Proactor accept 清理阶段;本轮未屏蔽异常或改事件循环。loopback 连接修复后该清理警告是否仍出现,必须由 native Windows CI 确认,不能依据 Linux 结果推定已消失。 +## Windows CI 二次修复:保留 source 的被动关闭角色 + +### 实际失败与修复范围 + +用户提供的第二轮 Windows Actions:**3 failed、937 passed、3 skipped、2 teardown errors in 748.98s**。三项失败都发生在 source 重连:connect 返回 True,但端口已随机回退,无法匹配原 source 路由;其余旧写入/连接失败未在该次结果出现。两个 teardown 错误出现在加密参数组,原断言未列出残留线程身份,不能仅凭日志认定具体加密线程或 Proactor 是独立根因。 + +前次将故障注入改为 source Client 主动 shutdown,遗漏了关闭角色对 TCP TIME_WAIT 的影响:主动发送 FIN 后再等待双端退出、最后设置 linger-0,不能保证撤销已发生的关闭序列或立即复用原四元组。Windows 实际端口回退证明原测试顺序不满足其稳定身份前提。参考 [Microsoft graceful shutdown/close 说明](https://learn.microsoft.com/en-us/windows/win32/winsock/graceful-shutdown-linger-options-and-socket-closure-2)和 [closesocket/linger 行为](https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-closesocket)。本轮不修改生产连接回退、SO_LINGER 编码或身份匹配规则。 + +初次尝试复用普通恢复测试的 server shutdown 后立即 close,在本轮 Linux 定向检查出现 async 参数组无法注销(见下方结果);该写法跨线程使 asyncio 正在等待的 read 句柄失效,不作为最终修复。最终故障顺序为:server accepted socket `shutdown(SHUT_WR)` 仅发送 FIN,保留 reader 的句柄;source 收到 EOF 后退出接收线程,再调用原 `_release_client_socket` 关闭 Client 端,最后等待 Server 读循环注销。source 保持被动关闭,Server 由原有 reader/finally 关闭实际句柄。原端点、fid/route、partial 内容、最终 ACK、迟到 owner 清理和全部线程退出断言保留。 + +夹具仍断言零存活线程,只把失败信息改为列出线程名;不延长 join、不忽略 daemon、不新增 skip/retry、不改生产加密或事件循环。端点变化后加密线程未完成是本次 teardown 错误的可能后果,尚不能代替 native Windows 复验。 + +### 验证 + +首次 Linux CPython 3.14.4 带 coverage 定向检查(六项 relay source/stop、普通自动重连及两项旧 control callback 隔离)为 **8 passed、1 failed in 51.11s**(墙钟 51.88s)。失败发生在 encrypted async source 组的 Server 注销等待,暴露立即 close 与 pending async read 的冲突;未把该结果计为通过。 + +改为 `SHUT_WR` 半关闭后,仅重跑受影响的三个 relay source 参数组: + +```bash +COVERAGE_FILE=/tmp/pyflow-passive-close-314.coverage uv run --isolated --no-project --python cpython-3.14.4-linux-x86_64-gnu --with pytest --with pytest-cov --with flask python -m pytest 'test/integration/network_api/test_tcp_transfer_control.py::test_relay_offline_source_replays_stable_route_or_stops_cleanly[plain-alias-source]' 'test/integration/network_api/test_tcp_transfer_control.py::test_relay_offline_source_replays_stable_route_or_stops_cleanly[encrypted-source]' 'test/integration/network_api/test_tcp_transfer_control.py::test_relay_offline_source_replays_stable_route_or_stops_cleanly[encrypted-async-untracked-wildcard-source]' --cov=PyFlow.network_api.connect_tcp --cov-report=term -q +``` + +**3 passed in 27.90s**(墙钟 28.21s),Linux CPython 3.14.4、coverage 开启。三组均完成原 source 端点重用、稳定 fid/route 恢复、真实内容/最终 ACK、迟到 owner 隔离及全部已跟踪 worker 退出。该小范围执行的 connect_tcp.py 覆盖率为 57%,不是全套覆盖率,也未改 coverage 策略。 + +本轮仅修改同一测试文件的故障关闭顺序和线程泄漏诊断,以及现有文档记录。没有延长等待、放宽原端点或清理断言,也未屏蔽 Proactor 异常。当前没有 native Windows 执行环境;后续 Windows Actions 仍是端口复用、加密 teardown 和 WinError 995 是否消失的最终验证。不将本机 Linux 的 3 passed 宣称为 Windows 已通过。 + ## 公共协议/API 变更许可记录 用户审查放行 C2a 并授权开始 C2b;下列协议/API 按已确认计划执行切换。恢复资格的新语义按 C4a/C4b 后续实施。 diff --git a/docs/source/changes/transfer-fid-routes.md b/docs/source/changes/transfer-fid-routes.md index 4075e7c..403f325 100644 --- a/docs/source/changes/transfer-fid-routes.md +++ b/docs/source/changes/transfer-fid-routes.md @@ -499,3 +499,22 @@ C4a retains ownership until final cleanup and rejects active resume requests. re-key skip in 331.25 seconds. The subset's coverage is not a full-suite measurement. Native Windows still requires a subsequent Actions run. +## Windows reconnect follow-up: preserve the source's passive close + +- The first CI follow-up's client-side shutdown let the source initiate FIN; + the next Windows run connected from a fallback port instead of the retained + route identity. The relay fault now half-closes the server's write side, + waits for source EOF/receive-loop exit, releases the client socket normally, + then waits for server unregister. The server reader keeps its own socket + until its finally block, including asyncio/Proactor reads. +- Original endpoint, FID/route, content, ACK and worker-exit checks remain. + Teardown failures now name surviving workers instead of reporting a bare + boolean. No longer joins, retries, skips or production behavior changes. +- Linux verification cannot establish Windows port reuse or Proactor cleanup; + native Windows Actions must confirm both after this change. +- Linux CPython 3.14.4 with coverage passed all three affected source-reconnect + variants in 27.90 seconds, retaining original endpoint, content/ACK and + worker-exit assertions. An intermediate immediate-close attempt failed the + async unregister check; that result remains in the report. Windows native + verification is still pending. + diff --git a/test/integration/network_api/test_tcp_transfer_control.py b/test/integration/network_api/test_tcp_transfer_control.py index e825b7d..34bf700 100644 --- a/test/integration/network_api/test_tcp_transfer_control.py +++ b/test/integration/network_api/test_tcp_transfer_control.py @@ -74,7 +74,8 @@ def start(worker, *args, **kwargs): server.stop() for worker in workers: worker.join(timeout=10) - assert not any(worker.is_alive() for worker in workers) + alive = [worker.name for worker in workers if worker.is_alive()] + assert not alive, f"control fixture leaked workers: {alive}" def _observe_target_writes(monkeypatch, output, byte_count): @@ -924,10 +925,14 @@ def hold(instance, state, sock): if fault == "stop": server.stop() else: - old_client.shutdown(socket.SHUT_RDWR) - assert wait_until(lambda: not source.running and origin not in server.clients) + # Peer FIN leaves source passive-close without invalidating the socket + # owned by the server's pending recv (including asyncio/Proactor reads). + old_server.shutdown(socket.SHUT_WR) + assert wait_until(lambda: not source.running) source.receive_thread.join(timeout=10) + assert not source.receive_thread.is_alive() source._release_client_socket() + assert wait_until(lambda: origin not in server.clients) interrupt.set() worker.join(timeout=20) for old_worker in tuple(workers): From 3b438af86395ba0026b4dec5d34838598c0bd9c8 Mon Sep 17 00:00:00 2001 From: F18-Ray Date: Tue, 17 Nov 2026 23:21:04 +0800 Subject: [PATCH 10/19] fix(connect_tcp)!: bind transfer cleanup to control sessions --- PyFlow/network_api/connect_tcp.py | 327 +++++++++--------- docs/plans/transfer-control-lifecycle-plan.md | 257 ++++++++++++++ .../transfer-control-lifecycle-report.md | 51 +++ ...transfer-control-lifecycle-requirements.md | 105 ++++++ .../transfer-pause-start-direction-plan.md | 2 + docs/source/changes/transfer-fid-routes.md | 15 +- .../network_api/test_tcp_transfer_control.py | 46 +++ .../network_api/test_tcp_transfer_resume.py | 49 ++- test/unit/network_api/test_resume_matching.py | 15 +- .../network_api/test_transfer_handshakes.py | 13 + 10 files changed, 685 insertions(+), 195 deletions(-) create mode 100644 docs/plans/transfer-control-lifecycle-plan.md create mode 100644 docs/plans/transfer-control-lifecycle-report.md create mode 100644 docs/plans/transfer-control-lifecycle-requirements.md diff --git a/PyFlow/network_api/connect_tcp.py b/PyFlow/network_api/connect_tcp.py index 48aa5ed..e26fd21 100644 --- a/PyFlow/network_api/connect_tcp.py +++ b/PyFlow/network_api/connect_tcp.py @@ -697,12 +697,13 @@ def format_resume_line(fid, offset, origin, target): @contextmanager -def _sending_transfer(instance, key): +def _sending_transfer(instance, key, *, control_socket=None): """Serialize sends for one scoped fid; release after the last in-flight user.""" with instance._transfer_progress_lock: state = instance._resume_sends.get(key) if state is None: - state = {"lock": threading.RLock(), "users": 0, "targets": set()} + state = {"lock": threading.RLock(), "users": 0, "targets": set(), + "control_socket": control_socket} instance._resume_sends[key] = state state["users"] += 1 try: @@ -737,7 +738,8 @@ def _claim_receive(instance, fid, control_socket, owner=None): if fid is None: return None with instance._transfer_progress_lock: - if instance._progress_discarded or _transfer_busy(instance, fid, control_socket): + if (instance._progress_discarded or instance._transfer_handshakes.closed(control_socket) + or _transfer_busy(instance, fid, control_socket)): return None record = instance._receive_transfers.get(fid) if record is not None: @@ -783,22 +785,50 @@ def _discard_receive_requests(instance, control_socket): instance._transfer_progress_changed.notify_all() +def _retire_transfer_session(instance, control_socket): + """Cancel only this socket's resources and capture its finalizing owners.""" + instance._transfer_handshakes.cancel_socket(control_socket) + instance._transfer_controls.discard_socket(control_socket) + _discard_receive_requests(instance, control_socket) + with instance._transfer_progress_lock: + sends = [(key, state) for key, state in instance._resume_sends.items() + if state.get("control_socket") is control_socket] + receives = [(fid, record) for fid, record in instance._receive_transfers.items() + if record["control_socket"] is control_socket] + return control_socket, sends, receives + + +def _wait_transfer_session(instance, retired): + """Drain captured old owners off the control reader and outside global locks.""" + if retired is None: + return + control_socket, sends, receives = retired + instance._transfer_handshakes.wait_socket(control_socket) + with instance._transfer_progress_changed: + instance._transfer_progress_changed.wait_for(lambda: all( + instance._resume_sends.get(key) is not state for key, state in sends + ) and all(instance._receive_transfers.get(fid) is not record + for fid, record in receives)) + + def _start_resume_send(instance, key, target, send, *, control_socket): """Atomically reserve one recovery worker; busy objects are never queued.""" with instance._transfer_progress_lock: if instance._progress_discarded or key not in instance.file_upload_progress: return False - if control_socket.fileno() < 0 or _transfer_busy(instance, key, control_socket): + if (control_socket.fileno() < 0 or instance._transfer_handshakes.closed(control_socket) + or _transfer_busy(instance, key, control_socket)): return False state = instance._resume_sends.get(key) if state is None: - state = {"lock": threading.RLock(), "users": 0, "targets": set()} + state = {"lock": threading.RLock(), "users": 0, "targets": set(), + "control_socket": control_socket} instance._resume_sends[key] = state state["targets"].add(target) def run(): try: - with _sending_transfer(instance, key): + with _sending_transfer(instance, key, control_socket=control_socket): entry = instance.file_upload_progress.get(key) if entry is not None: send(entry) @@ -1039,8 +1069,7 @@ def _flush(self, state): return if not _is_closed_socket_error(exc): instance._log(f"transfer control: {exc}") - self.release(state) - instance._transfer_handshakes.cancel_socket(sock) + _retire_transfer_session(instance, sock) try: sock.shutdown(socket.SHUT_RDWR) except OSError: @@ -1791,16 +1820,20 @@ def cancel(self, record): record["cancelled"] = True self._changed.notify_all() + def closed(self, control_socket): + with self._changed: + return control_socket in self._closed + def track_socket(self, control_socket, transfer_socket): """Register listeners before announcing them, and accepted/data sockets.""" if control_socket is None: return True with self._changed: - if control_socket in self._closed: - self._close_socket(transfer_socket) - return False - self._resources.setdefault(control_socket, set()).add(transfer_socket) - return True + if control_socket not in self._closed: + self._resources.setdefault(control_socket, set()).add(transfer_socket) + return True + self._close_socket(transfer_socket) + return False def release_socket(self, control_socket, transfer_socket): with self._changed: @@ -1809,6 +1842,12 @@ def release_socket(self, control_socket, transfer_socket): resources.discard(transfer_socket) if not resources: del self._resources[control_socket] + self._changed.notify_all() + + def wait_socket(self, control_socket): + """Wait for the retired session's workers to release their resources.""" + with self._changed: + self._changed.wait_for(lambda: not self._resources.get(control_socket)) def occupied(self, control_socket, fid): """Pending and uncertain negotiations both prevent a second same-FID leg.""" @@ -1834,7 +1873,7 @@ def cancel_socket(self, control_socket): self._unresolved.difference_update( key for key in tuple(self._unresolved) if key[0] is control_socket ) - resources = self._resources.pop(control_socket, ()) + resources = tuple(self._resources.get(control_socket, ())) self._changed.notify_all() for sock in resources: self._close_socket(sock) @@ -2789,6 +2828,7 @@ def __init__( ) self._transfer_progress_lock = threading.RLock() # serialises the persist/load pair self._resume_sends = {} # transient locks and request sets; no file metadata + self._retired_transfer_sessions = {} # peer -> captured old session owners self._transfer_progress_changed = threading.Condition(self._transfer_progress_lock) self._receive_transfers = {} # request/listener/data owner until final cleanup self._progress_discarded = False @@ -3351,50 +3391,6 @@ def _release_transfer_socket(self, fid, sock): del self._receive_transfers[fid] self._transfer_progress_changed.notify_all() - def _drop_stale_transfers(self, peer=None, *, wait=False): - """Close the legs a peer's previous session left behind. - - A peer that (re)connects proves that the legs of its earlier session - are over: their sockets are shut down so the stored transfers can be - resumed without two legs writing the same transfer. - - Args: - peer (tuple | None): Match the outgoing receiver namespace or incoming progress peer; None clears all tracked legs. - wait (bool): During reconnect only, wait for old worker cleanup. - - Returns: - int: Number of legs closed. - """ - stale = [] - with self._transfer_progress_lock: - sends = [(key, state) for key, state in self._resume_sends.items() - if peer is None or key[0] == tuple(peer)] if wait else [] - for store in (self.file_upload_progress, self.file_recv_progress): - for fid, entry in list(store.items()): - owner = fid[0] if store is self.file_upload_progress else entry[4] - if peer is not None and (owner is None or tuple(owner) != tuple(peer)): - continue - with self._transfer_progress_lock: - sock = self._active_transfer_sockets.get(fid) - if sock is not None: - stale.append((fid, sock)) - for fid, sock in stale: - try: - sock.shutdown(socket.SHUT_RDWR) - except OSError: - pass # already gone - try: - sock.close() - except OSError: - pass - self._transfer_controls.release_owner(sock) - if wait: - with self._transfer_progress_changed: - self._transfer_progress_changed.wait_for(lambda: all( - self._active_transfer_sockets.get(key) is not sock for key, sock in stale - ) and all(self._resume_sends.get(key) is not state for key, state in sends)) - return len(stale) - def _wait_control_secure(self, control_socket, timeout=RESUME_SECURE_TIMEOUT): """Wait until a control channel may carry framed protocol lines. @@ -5227,6 +5223,7 @@ def _register_client(self, client_socket, client_address): """ client_id = f"{client_address[0]}:{client_address[1]}" with self.client_lock: # add new client + previous = self.clients.get(client_address, {}).get("socket") self._control_sockets.add(client_socket) self.clients[client_address] = { "socket": client_socket, @@ -5234,6 +5231,11 @@ def _register_client(self, client_socket, client_address): "id": client_id, "connected_time": datetime.now().strftime("%Y-%m-%d %H:%M:%S"), } + if previous is not None and previous is not client_socket: + self._retire_client_transfers(previous, client_address) + _TransferHandshakeRegistry._close_socket(previous) + with self.client_lock: + retired = tuple(self._retired_transfer_sessions.get(client_address, ())) if self.is_enable_encrypto and self.crypto is not None: session = self._crypto_session_for(client_address) channel = _SecureChannel( @@ -5254,7 +5256,8 @@ def _register_client(self, client_socket, client_address): # (and wake the forwarded-resume requests that waited for it) off the # accept path, because the resume may need this peer's handshake first threading.Thread( - target=self._resume_after_connect, args=(client_address,), daemon=True + target=self._resume_after_connect, + args=(client_address, client_socket, retired), daemon=True ).start() return client_id @@ -5337,6 +5340,21 @@ def _process_client_line(self, client_socket, client_address, client_id, message self._log(log_msg) return f"msg send: {message}" + def _retire_client_transfers(self, control_socket, peer): + retired = _retire_transfer_session(self, control_socket) + with self.client_lock: + self._retired_transfer_sessions.setdefault(peer, []).append(retired) + + def drain(): + _wait_transfer_session(self, retired) + with self.client_lock: + pending = self._retired_transfer_sessions.get(peer, []) + pending[:] = [item for item in pending if item is not retired] + if not pending: + self._retired_transfer_sessions.pop(peer, None) + + threading.Thread(target=drain, daemon=True).start() + def _unregister_client(self, client_socket, client_address, client_id): """Drop one client's state and close its socket. @@ -5345,9 +5363,7 @@ def _unregister_client(self, client_socket, client_address, client_id): client_address (tuple): Peer ``(ip, port)``. client_id (str): Client id used in the console log. """ - self._transfer_handshakes.cancel_socket(client_socket) - self._transfer_controls.discard_socket(client_socket) - _discard_receive_requests(self, client_socket) + self._retire_client_transfers(client_socket, client_address) with self.client_lock: owns_peer = self.clients.get(client_address, {}).get("socket") is client_socket if owns_peer: @@ -5876,7 +5892,6 @@ def close_socket(): if client_file_socket is not None: self._transfer_controls.release_owner(client_file_socket) client_file_socket.close() - self._transfer_handshakes.release_socket(client_socket, client_file_socket) if server_file_socket is not None: server_file_socket.close() self._transfer_handshakes.release_socket(client_socket, server_file_socket) @@ -5921,6 +5936,7 @@ def file_transfer_client_recv(client_id): self._log_exc() close_socket() self._release_transfer_socket(progress_fid, client_file_socket) + self._transfer_handshakes.release_socket(client_socket, client_file_socket) return False try: name_len_bytes = b"" @@ -6096,6 +6112,7 @@ def file_transfer_client_recv(client_id): ), ) self._release_transfer_socket(progress_fid, client_file_socket) + self._transfer_handshakes.release_socket(client_socket, client_file_socket) server_file_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM) server_file_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) @@ -6176,6 +6193,7 @@ def file_transfer_client_recv(client_id): if client_file_socket is not None: self._release_transfer_socket(progress_fid, client_file_socket) _release_receive(self, progress_fid, receive_record) + self._transfer_handshakes.release_socket(client_socket, client_file_socket) def diff_multiple_file_diff_multiple_client_transfer_server_recv_client_start(self, message): """Send grouped files and folders to their listed clients. @@ -6483,7 +6501,7 @@ def file_transfer_server_recv_client_start(self, message, file_folder_abspath): filename = os.path.join(file_folder_abspath, shlex.split(message)[2]) else: filename = shlex.split(message)[1] - with _sending_transfer(self, (tuple(client_ip), client_id)), \ + with _sending_transfer(self, (tuple(client_ip), client_id), control_socket=client_socket), \ _transfer_handshake(self, client_socket, client_id) as handshake: send_msg = f"{message.strip()} {client_id}\n" if not _send_transfer_request(self, handshake, send_msg): @@ -6552,7 +6570,6 @@ def close_socket(): file_running = False self._transfer_controls.release_owner(client_file_socket) self._crypto_drop_channel(client_file_socket) - self._transfer_handshakes.release_socket(control_socket, client_file_socket) client_file_socket.close() while True: @@ -6591,6 +6608,7 @@ def close_socket(): except _CryptoUnavailable as exc: self._log(f"crypto: file transfer aborted: {exc}") close_socket() + self._transfer_handshakes.release_socket(control_socket, client_file_socket) return False file_running = True self._register_transfer_socket(transfer_key, client_file_socket) @@ -6769,10 +6787,11 @@ def receive_file_transfer_messages(): ), ) self._release_transfer_socket(transfer_key, client_file_socket) + self._transfer_handshakes.release_socket(control_socket, client_file_socket) # ---- transfer reconnect (server side) ---------------------------------- - def _request_resumes(self, peer): + def _request_resumes(self, peer, *, control_socket=None): """Ask a peer that just connected to continue this side's interrupted downloads. Reads the persisted stores back (`_load_transfer_progress`). Every download @@ -6793,7 +6812,8 @@ def _request_resumes(self, peer): peer = tuple(peer) with self.client_lock: info = self.clients.get(peer) - if info is None or not self._wait_control_secure(info["socket"]): + if (info is None or control_socket is not None and info["socket"] is not control_socket + or not self._wait_control_secure(info["socket"])): return 0 target = self._control_local_endpoint(info["socket"]) started = 0 @@ -6935,14 +6955,16 @@ def _queue_resume_to_originator(self, originator_fid, route, target_addr, offset ] = offset return self._flush_pending_originator_resumes(originator) > 0 - def _flush_pending_originator_resumes(self, client_address): + def _flush_pending_originator_resumes(self, client_address, *, control_socket=None): """Send queued requests through the secure control path without early removal.""" client_address = tuple(client_address) with self._forward_relays_lock: pending = list(self._pending_originator_resumes.get(client_address, {}).items()) with self.client_lock: info = self.clients.get(client_address) - if not pending or info is None or not self._wait_control_secure(info["socket"]): + if (not pending or info is None + or control_socket is not None and info["socket"] is not control_socket + or not self._wait_control_secure(info["socket"])): return 0 sent = 0 for (fid, target), offset in pending: @@ -6984,11 +7006,12 @@ def _flush_pending_originator_resumes(self, client_address): self._pending_originator_resumes.pop(client_address, None) return sent - def _resume_after_connect(self, client_address): - """Resume eligible objects after this control peer reconnects.""" - self._drop_stale_transfers(peer=tuple(client_address), wait=True) - self._request_resumes(tuple(client_address)) - self._flush_pending_originator_resumes(tuple(client_address)) + def _resume_after_connect(self, client_address, control_socket, retired): + """Drain only captured old owners, then resume through the admitted socket.""" + for session in retired: + _wait_transfer_session(self, session) + self._request_resumes(tuple(client_address), control_socket=control_socket) + self._flush_pending_originator_resumes(tuple(client_address), control_socket=control_socket) # ---- native in-memory forward relay (server side) ---------------------- @@ -7375,7 +7398,6 @@ def own(control, transfer): finally: for control, transfer in owned_sockets: self._transfer_controls.release_owner(transfer) - self._transfer_handshakes.release_socket(control, transfer) for transfer_socket in [up_client, up_sock, *(sock for _, _, sock in target_conns)]: if transfer_socket is not None: self._crypto_drop_channel(transfer_socket) @@ -7389,6 +7411,8 @@ def own(control, transfer): if self._forward_relays.get(key) is relay: del self._forward_relays[key] _release_receive(self, fid, receive_record) + for control, transfer in owned_sockets: + self._transfer_handshakes.release_socket(control, transfer) def _forward_pump( self, up_sock, target_conns, forwarder_sock, fid, fname, relay, resume_offset=0 @@ -7791,23 +7815,20 @@ def stop(self): # shutting down the server self._flush_record_stores() # in-flight transfers die with the server: persist them for the next run self._persist_transfer_progress() - with self.client_lock: # close all clients connections - for client_info in self.clients.values(): - self._transfer_handshakes.cancel_socket(client_info["socket"]) - self._transfer_controls.discard_socket(client_info["socket"]) - _discard_receive_requests(self, client_info["socket"]) - try: - # a client thread blocked in recv() keeps the connection half - # open past close(): the shutdown sends its FIN and wakes it - client_info["socket"].shutdown(socket.SHUT_RDWR) - except OSError: - pass # already disconnected - try: - client_info["socket"].close() - except: - self._log_exc() - pass + with self.client_lock: + clients = list(self.clients.values()) self.clients.clear() + for client_info in clients: + _retire_transfer_session(self, client_info["socket"]) + try: + # Wake the control reader as well as its cancelled data legs. + client_info["socket"].shutdown(socket.SHUT_RDWR) + except OSError: + pass # already disconnected + try: + client_info["socket"].close() + except OSError: + self._log_exc() if self.server_socket: # close server socket try: # close() alone does not release the port: a thread blocked in @@ -8036,6 +8057,7 @@ def __init__( self.running = False self._stopped = False # a close() before connect() must stick self.receive_thread = None + self._resume_thread = None self.command_decode_table_str = None self.max_thread_num = max_thread_num self.is_input_command_in_console = is_input_command_in_console @@ -9002,50 +9024,6 @@ def _release_transfer_socket(self, fid, sock): del self._receive_transfers[fid] self._transfer_progress_changed.notify_all() - def _drop_stale_transfers(self, peer=None, *, wait=False): - """Close the legs a peer's previous session left behind. - - A peer that (re)connects proves that the legs of its earlier session - are over: their sockets are shut down so the stored transfers can be - resumed without two legs writing the same transfer. - - Args: - peer (tuple | None): Match the outgoing receiver namespace or incoming progress peer; None clears all tracked legs. - wait (bool): During reconnect only, wait for old worker cleanup. - - Returns: - int: Number of legs closed. - """ - stale = [] - with self._transfer_progress_lock: - sends = [(key, state) for key, state in self._resume_sends.items() - if peer is None or key[0] == tuple(peer)] if wait else [] - for store in (self.file_upload_progress, self.file_recv_progress): - for fid, entry in list(store.items()): - owner = fid[0] if store is self.file_upload_progress else entry[4] - if peer is not None and (owner is None or tuple(owner) != tuple(peer)): - continue - with self._transfer_progress_lock: - sock = self._active_transfer_sockets.get(fid) - if sock is not None: - stale.append((fid, sock)) - for fid, sock in stale: - try: - sock.shutdown(socket.SHUT_RDWR) - except OSError: - pass # already gone - try: - sock.close() - except OSError: - pass - self._transfer_controls.release_owner(sock) - if wait: - with self._transfer_progress_changed: - self._transfer_progress_changed.wait_for(lambda: all( - self._active_transfer_sockets.get(key) is not sock for key, sock in stale - ) and all(self._resume_sends.get(key) is not state for key, state in sends)) - return len(stale) - def _wait_control_secure(self, control_socket, timeout=RESUME_SECURE_TIMEOUT): """Wait until a control channel may carry framed protocol lines. @@ -9469,6 +9447,8 @@ def connect(self): # connect to server enabled, the key exchange has been started); False when the attempt failed or the mode negotiation closed the connection. """ + retired = self._release_client_socket() + previous_resume = self._resume_thread while True: try: local_address = ( @@ -9513,12 +9493,7 @@ def connect(self): # connect to server return False self.running = True self._control_sockets.add(self.client_socket) - # this client's only control link is the server: the socket is - # up, so every leg still registered belongs to the previous - # session and is over. The sweep runs before the receive thread - # starts, so a resume request of the new session cannot be - # affected by it. - self._drop_stale_transfers(wait=True) + control_socket = self.client_socket self.receive_thread = threading.Thread( target=self.receive_messages ) # set up get msg thread @@ -9534,7 +9509,7 @@ def connect(self): # connect to server self._log, self._debug, send_lock=self._crypto_send_lock, - on_disable=lambda: self._crypto_drop_secure(self.client_socket), + on_disable=lambda: self._crypto_drop_secure(control_socket), ) with self._crypto_lock: self._channels[self.client_socket] = channel @@ -9546,11 +9521,14 @@ def connect(self): # connect to server self._crypto_decode_failures = 0 # fresh connection, fresh breaker self._crypto_start_exchange() self._log("connect success! type '/help' to get help.\n") - # a (re)connected session carries the transfers that died with - # the previous one: continue them from what is already on disk - threading.Thread( - target=self._request_resumes, daemon=True - ).start() + def resume(): + if previous_resume is not None: + previous_resume.join() + _wait_transfer_session(self, retired) + self._request_resumes(control_socket=control_socket) + + self._resume_thread = threading.Thread(target=resume, daemon=True) + self._resume_thread.start() return True except socket.timeout: if self.is_wait_server: @@ -9655,9 +9633,7 @@ def receive_messages(self): # get server msg self.free_port() self._persist_transfer_progress() break - self._transfer_handshakes.cancel_socket(control_socket) - self._transfer_controls.discard_socket(control_socket) - _discard_receive_requests(self, control_socket) + _retire_transfer_session(self, control_socket) def send_message(self, client_socket, message, is_send_raw=False): # send msg to server @@ -10834,7 +10810,7 @@ def file_transfer_client_recv_client_start(self, message, file_folder_abspath): filename = os.path.join(file_folder_abspath, shlex.split(message)[2]) else: filename = shlex.split(message)[1] - with _sending_transfer(self, (peer, client_id)), \ + with _sending_transfer(self, (peer, client_id), control_socket=control_socket), \ _transfer_handshake(self, control_socket, client_id) as handshake: send_msg = f"{message.strip()} {client_id}" if not _send_transfer_request(self, handshake, send_msg): @@ -10900,7 +10876,6 @@ def close_socket(): file_running = False self._transfer_controls.release_owner(client_file_socket) self._crypto_drop_channel(client_file_socket) - self._transfer_handshakes.release_socket(control_socket, client_file_socket) client_file_socket.close() while True: @@ -10939,6 +10914,7 @@ def close_socket(): except _CryptoUnavailable as exc: self._log(f"crypto: file transfer aborted: {exc}") close_socket() + self._transfer_handshakes.release_socket(control_socket, client_file_socket) return False file_running = True self._register_transfer_socket(transfer_key, client_file_socket) @@ -11115,10 +11091,11 @@ def receive_file_transfer_messages(): ), ) self._release_transfer_socket(transfer_key, client_file_socket) + self._transfer_handshakes.release_socket(control_socket, client_file_socket) # ---- transfer reconnect (client side) ---------------------------------- - def _request_resumes(self): + def _request_resumes(self, *, control_socket=None): """Continue this client's interrupted downloads after it (re)connected. Loads the existing receive rows and sends their stable fid, disk offset, @@ -11131,16 +11108,18 @@ def _request_resumes(self): restored = self._load_transfer_progress() if restored: self._log(f"transfer reconnect: restored {restored} interrupted transfer(s)") - if not self.running or self.client_socket is None: + if control_socket is None: + control_socket = self.client_socket + if not self.running or control_socket is None or self.client_socket is not control_socket: return 0 - if not self._wait_control_secure(self.client_socket): + if not self._wait_control_secure(control_socket): return 0 # A direct row recorded before the identity change names the configured # server address; the concrete peer of this connection is what the # server recognises as itself, so migrate the row in memory (the # progress file keeps its format). configured_peer = (self.host, self.port) - connected_peer = _socket_peer_endpoint(self.client_socket) + connected_peer = _socket_peer_endpoint(control_socket) started = 0 for fid, entry in list(self.file_recv_progress.items()): if entry[4] is None: @@ -11148,7 +11127,7 @@ def _request_resumes(self): if connected_peer is not None and tuple(entry[4]) == configured_peer: entry[4] = connected_peer started += _request_receive_resume( - self, fid, entry, self.client_socket, entry[4], self.client_socket.getsockname() + self, fid, entry, control_socket, entry[4], control_socket.getsockname() ) return started @@ -11189,7 +11168,7 @@ def send(entry): if not is_direct: self._forward_one( "file", "", os.path.basename(str(entry[3])), entry[3], [target], - resume_offset=offset, upstream_fid=fid, + resume_offset=offset, upstream_fid=fid, control_socket=control_socket, ) return if entry[4] is None or tuple(entry[4]) != server_peer: @@ -11376,13 +11355,16 @@ def _forward_one( destination_path=None, resume_offset=0, upstream_fid=None, + *, + control_socket=None, ): """Forward one item using a source-owned upstream FID.""" if not os.path.isfile(abspath): self._log(f"forward: {abspath} is not a valid file, skipped") return False server_peer = (self.host, self.port) - control_socket = self.client_socket + if control_socket is None: + control_socket = self.client_socket is_resume = upstream_fid is not None if is_resume: key = (server_peer, upstream_fid) @@ -11397,7 +11379,7 @@ def _forward_one( (_peer_from_json(addrs[0]) or tuple(addrs[0])) if addrs else None, ] self._persist_transfer_progress() - with _sending_transfer(self, key): + with _sending_transfer(self, key, control_socket=control_socket): with _transfer_handshake(self, control_socket, upstream_fid) as handshake: msg = f"/forward_item {kind} fid={int(upstream_fid)}" if is_resume: @@ -11596,7 +11578,6 @@ def close_socket(): if client_file_socket is not None: self._transfer_controls.release_owner(client_file_socket) client_file_socket.close() - self._transfer_handshakes.release_socket(client_socket, client_file_socket) if server_file_socket is not None: server_file_socket.close() self._transfer_handshakes.release_socket(client_socket, server_file_socket) @@ -11639,6 +11620,7 @@ def file_transfer_client_recv(client_id): self._log_exc() close_socket() self._release_transfer_socket(progress_fid, client_file_socket) + self._transfer_handshakes.release_socket(client_socket, client_file_socket) return False try: name_len_bytes = b"" @@ -11804,6 +11786,7 @@ def file_transfer_client_recv(client_id): ), ) self._release_transfer_socket(progress_fid, client_file_socket) + self._transfer_handshakes.release_socket(client_socket, client_file_socket) server_file_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM) server_file_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) @@ -11887,6 +11870,7 @@ def file_transfer_client_recv(client_id): if client_file_socket is not None: self._release_transfer_socket(progress_fid, client_file_socket) _release_receive(self, progress_fid, receive_record) + self._transfer_handshakes.release_socket(client_socket, client_file_socket) @_config_lifecycle(starting=False) def close(self): # close connection @@ -11900,9 +11884,7 @@ def close(self): # close connection self._stopped = True # also cancels a connect() still in flight self._stop_listeners() if self.client_socket: - self._transfer_handshakes.cancel_socket(self.client_socket) - self._transfer_controls.discard_socket(self.client_socket) - _discard_receive_requests(self, self.client_socket) + _retire_transfer_session(self, self.client_socket) try: # the receive thread may be blocked in recv() on this socket: # close() alone sends no FIN and leaves that read waiting for its @@ -11934,7 +11916,7 @@ def close(self): # close connection self._log("connection closed") def _release_client_socket(self): - """Close the socket a finished session left behind. + """Retire the captured control session and release its local port. An auto-reconnect binds the configured ``client_port`` again, so the dead session's socket must go away completely: it is closed abortively @@ -11944,15 +11926,17 @@ def _release_client_socket(self): in ``TIME_WAIT`` — Windows then refuses to bind or connect from it again (``WSAEADDRINUSE``) for the whole two-minute delay. - The receive thread of that session has already ended when this runs, so - nothing needs the shutdown a graceful close would perform. + Shutdown wakes a reader still exiting this socket. New control reception + starts before background recovery waits for the captured transfer owners. """ sock = self.client_socket if sock is None: - return - self._transfer_handshakes.cancel_socket(sock) - self._transfer_controls.discard_socket(sock) - _discard_receive_requests(self, sock) + return None + retired = _retire_transfer_session(self, sock) + try: + sock.shutdown(socket.SHUT_RDWR) + except OSError: + pass try: sock.setsockopt(socket.SOL_SOCKET, socket.SO_LINGER, struct.pack("ii", 1, 0)) except OSError: @@ -11965,6 +11949,7 @@ def _release_client_socket(self): self._channels.pop(sock, None) self._encrypted_sockets.discard(sock) self._control_sockets.discard(sock) + return retired def start_TCP_client(self): # start client """Connect to the server and start the client loop. diff --git a/docs/plans/transfer-control-lifecycle-plan.md b/docs/plans/transfer-control-lifecycle-plan.md new file mode 100644 index 0000000..3110faa --- /dev/null +++ b/docs/plans/transfer-control-lifecycle-plan.md @@ -0,0 +1,257 @@ +# 传输控制生命周期、全局转发暂停与顺序恢复 — 更改计划 + +状态:**用户已授权按最后拆分开始 C1;C1 实现及局部验收完成,等待人工审查;C2–C6 未开始**。保持原 upstream fid/child fid,不引入 leg_id,不修改 pause/start 和端口响应格式;本轮仅实施实际控制会话清理、旧 owner 收尾及旧 worker 固定 socket,不自动创建 git 提交、合并或推送。后续阶段仍逐项等待人工放行;本轮证据见[实施报告](transfer-control-lifecycle-report.md)。 + +需求依据:[需求卡](transfer-control-lifecycle-requirements.md)。历史实现依据:[上一轮计划](transfer-pause-start-direction-plan.md)及其报告;它们的历史验证结果不作为本轮验证结果。 + +## 1. 本轮范围与替代关系 + +### 1.1 保留的四组修改 + +1. **问题四/五**:按实际控制 socket 管理旧会话资源,删除按 peer 扫描进度表关闭当前 socket 的重复机制;旧 worker 不借用新控制连接。 +2. **问题六**:Client 统一转发入口拒绝自身完整控制端点;同 host 不同端口仍可互传。 +3. **问题七**:Source 是 route 的唯一用户控制仲裁者;任意端 pause/start 控制整个转发任务。暂停源端新增块,已有字节继续排空,数据 socket 不断开。 +4. **问题八**:8A 验证恢复请求后结束旧 relay 的上下游数据腿,等待收尾并清掉旧内存,按各 Target 实际 offset 顺序重放;8B 保留所有 Target 已完成但上游 ACK 明确失败的 EOF 再确认。两者保持原 fid,分别实施和验收。 + +### 1.2 明确排除 + +- 撤回问题一“正常恢复流程已证明导致内容损坏”的结论;不以此另开修复。 +- **问题二暂缓**:不为旧 pause/start 与同一控制会话、同 fid 数据腿重建的交叉窗口增加 leg_id、换新 fid 或其他代次隔离。控制发送失败沿用现有失败/关闭路径,允许人工重新操作或结束控制会话后恢复;不承诺该窗口自动无缝收敛。问题四/五的断线清理与其余恢复方案不因此取消。 +- 问题三是已确认语义,不改为各端独立持有暂停锁。 +- 问题九(超长文件名)、十(控制队列增长)、十一(无 owner 预置暂停)暂不处理。 +- 不增加内存/磁盘回放缓存、不同 offset 的并行范围过滤、第二结果通道、ACK-of-ACK、能力协商或旧 wire 兼容分支。 +- 不重构整个 TCP/加密/日志系统,不改 CI、依赖和覆盖率策略,不扩展 Web UI。 +- 不承诺 NAT、控制端点变化后的身份迁移、跨进程同时写进度文件、同尺寸源文件内容变化或断电耐久性。 + +### 1.3 对旧契约的明确替代 + +- **保留**恢复时稳定 upstream fid/child fid、原接收路径、pause/start 及端口响应格式;不实现 leg_id、old/new fid 关联、恢复身份 rekey 或持久化迁移记录。 +- **废弃**“Target 只暂停自己的 writer”;替换为 Source 仲裁全 route 停止新增源数据。 +- **替换转发恢复**的 live upstream busy 静默跳过:有效恢复请求可触发该 route 的定向 teardown;重复请求只登记,不反复打断新重放。 +- **普通传输**的 live/paused/negotiating/finalizing busy 静默跳过仍保留;暂停用 start,不因此扩大成任意普通传输强制重启。 +- 用户 API 的 bool 仍表示登记/预留,不表示远端确认、恢复完成或文件成功。 + +## 2. 变更文件清单 + +| 类型 | 文件 | 关键内容 | +|---|---|---| +| 修改生产代码 | `PyFlow/network_api/connect_tcp.py` | 实际会话资源、固定 worker 控制 socket、relay 全局控制/恢复调度、自目标校验及完成清理;不改端口/控制帧字段 | +| 修改单测 | `test/unit/network_api/test_resume_matching.py` | 保留普通恢复 busy、稳定 fid/原路径/总长/offset 及收尾;覆盖恢复入口与会话生命周期交叉 | +| 修改单测 | `test/unit/network_api/test_transfer_handshakes.py` | 实际会话取消、listener/data owner 退役及旧 owner 排空;不增加代次字段 | +| 修改单测 | `test/unit/network_api/test_transfer_control.py` | Source 仲裁、全局状态转发、交叉意图和背压独立;不新增跨腿旧控制隔离保证 | +| 修改单测 | `test/unit/network_api/test_fid_routes.py` | 稳定 route/child、已完成集合、顺序调度、伪造请求不 teardown | +| 修改单测 | `test/unit/network_api/test_transfer_progress_query.py`、`test_delete_config.py` | 保持既有查询/快照 schema,关闭/删除与恢复占用 | +| 修改单测 | `test/unit/network_api/test_TCP_client.py`、`test_TCP_server.py` | 控制会话替换及资源生命周期必要回归 | +| 修改集成测试 | `test/integration/network_api/test_tcp_transfer_control.py` | 普通双端控制回归、全局暂停、旧清扫/旧 worker、强制恢复及自目标拒绝 | +| 修改集成测试 | `test/integration/network_api/test_tcp_transfer_resume.py` | 普通/转发同 fid 新数据腿、不同 offset 顺序恢复、部分完成、EOF/最终 ACK、重连和持久化 | +| 迁移受影响断言 | `test/integration/network_api/test_tcp_file_transfer.py`、`test_crypto_tcp.py`、`test_tcp_async_server.py`、`test/integration/test_forward_extension.py`、`test_forward_msg_attribution.py` | 只更新全局暂停、恢复和自目标语义触及的真实消费者;不做端口或 pause/start parser/helper 的协议迁移 | +| 修改使用文档 | `docs/source/File_Transfer/File_Transfer.rst`、`docs/source/Network_APIs/TCP_Server_APIs.rst`、`TCP_Client_APIs.rst` | API 结果、稳定 fid、全局暂停、offset 查询、恢复及暂缓边界 | +| 修改变更记录 | `docs/source/changes/transfer-fid-routes.md` | 保留稳定恢复 fid,取代独立 writer 暂停及 busy 恢复等旧契约;明确问题二暂缓 | +| 计划载体 | 本文件、`transfer-control-lifecycle-requirements.md`、旧计划的后续链接 | 本轮决策和审批状态,不改写历史通过记录 | +| 实施后新增报告 | `docs/plans/transfer-control-lifecycle-report.md` | 逐原子变更报告、路径证据、失败及未覆盖项;现在不创建完成报告 | + +Web 的 `client_backend.py` 已知通过 Client 的文件/文件夹转发入口调用,不直接构造恢复消息;计划不修改该文件,统一入口必须覆盖 Web 调用。若实施发现额外真实消费者须修改,先更新文件清单,不扩大成 UI 功能。 + +当前 LSP 只有 Ruff,不支持 definition/references;本轮按现有声明和文本调用点定位。实施前重新检查导航能力;支持 references 时,改公开符号前必须查询引用,不声称 Ruff 已完成引用分析。 + +## 3. 接口与线上契约(拟定,随本计划确认) + +### 3.1 保持不变的部分 + +- Server/Client 的 pause/start Python 签名不变;调用方仍传 fid/type/direction,不增加数据腿编号或代次参数。 +- fid 始终标识原文件/route 的对应腿。`resume_trans(peer_addr, fid, offset)` 保留签名和 bool 登记语义,恢复后仍使用同一 fid。 +- `/file`、`/file_folder`、`/forward_item ... fid= resume=` 保持现有形式;数值恢复请求保持五 token;文件数据头、文件块和最终 ACK 不增加字段。 +- fid 分配和原进度/route/child 键不迁移,不新增恢复版本、old/new 映射或迁移日志。 +- 公钥和独立传输不因此获得用户 pause/start 能力;端口解析结果、握手 port 结果、file_transfer_mode 签名及测试 helper 的端口返回值不因问题二而改变。 + +### 3.2 恢复请求与各目标 offset 收集 + +数值恢复请求保持五 token: + +```text +/resume_trans +``` + +为在强制关闭共享 relay 后取得各 Target 的**最终落盘**位置,扩展同一命令的查询形式,不增加新命令名: + +```text +/resume_trans ? +``` + +- `?` 仅为 Server 向该 route Target 发出的 offset 查询。Client 校验当前 Server 控制会话、target 为自身、download fid 与 origin 匹配,随后在后台等待该旧接收 owner 收尾/文件关闭,再用既有数值形式回复。 +- Server 不用发送字节计数猜 Target 落盘进度;首次请求也可能早于其他在途字节落盘,teardown 后以查询回复为准。 +- 查询只登记一次,回包不重复 teardown;离线/无保留接收记录的目标不虚构 offset,不阻塞可服务目标。未完成项保留,等待合法后续恢复/重连。 +- 不增加定时重试循环,不让控制接收线程阻塞等待自己需要分派的消息。 +- `parse_resume_command` 数值分支返回值不变;查询分支 tuple 的 offset 用 `None` 表示,`format_resume_line(..., offset=None, ...)` 生成 `?`。这是输入/输出值域扩展,全部消费者区分请求和查询。 + +### 3.3 保持控制/端口格式,明确暂缓边界 + +以下保持现有四 token 格式,不新增字段或确认轮次: + +```text +/server_file_transfer_port +/pause_trans +/start_trans +``` + +- 继续校验实际控制 socket、fid/type/role 及当前 owner,不因转发路由而绕过现有控制入口。 +- Server 跨腿转发请求或状态时,映射所属 route 的 upstream/child fid;Source 串行仲裁,Server 不成为第二决定者。 +- 保留 pending/unresolved 握手隔离、同 fid 占用、ready 条件及旧 owner 排空。旧 owner 退役时释放所属控制状态和未发帧,旧 finally 仍按对象身份释放。 +- **不承诺同一控制会话内,已发出的旧 pause/start 一定不能影响重建后的同 fid 数据腿。**这是本轮接受的问题二边界,不以新的分配器、消息字段或隐含重试机制替代。 +- 控制命令的 True 仍只表示登记,不等于对端确认或断线后成功;失败沿用现有失败/关闭路径,可人工重新操作或结束控制会话后恢复。 + +## 4. 保留既有恢复记录与持久化模型 + +### 4.1 不做身份与持久化扩展 + +- 不实现 leg_id、old/new fid 迁移、恢复关联链、route rekey 或 `/file resume=:`。 +- 不新增 `resume_from_fid`、数据腿代次参数或专门的身份迁移测试文件;不为暂缓的问题二迁移端口及控制消息消费者。 +- 不新增快照根 version/rebinds,不为本轮扩展 route total,不改变五项进度值、scoped key、originator/targets/completed 结构。 +- socket、owner、锁和用户暂停仍只存在运行时。重启读回仍用原 fid 和原路径,按原文件/端口握手重新建连。 + +### 4.2 同 fid 恢复的收尾与失败规则 + +1. 原拥有者真正退出并释放 active socket/发送占用/接收占用后,才能在同 fid 上建立新数据腿;检查与恢复预留在同一并发边界。 +2. Receiver 从关闭后的原文件实际大小取 offset,按原 fid/peer/basename/total 校验继续使用原完整路径;不建立同名文件桥接或删除旧字节。 +3. 握手中断时按原规则释放所属控制状态,保留允许恢复的文件/进度;不得绕过 pending/unresolved 握手或建立第二个数据 owner。 +4. 新 owner 默认运行,不继承退役 owner 的用户暂停/请求/确认。无 owner 的预置暂停继续遵守既有规则,问题十一仍不在本轮。 +5. 进程重启不恢复旧控制运行时状态;保留行继续从同 fid、原路径恢复,不增加数据腿计数或持久化版本。 +6. 最终 ACK 明确失败保留原记录,成功只清理 owning 记录。ACK 写成功但对端应用是否收到的不确定窗口不以新增 ACK-of-ACK 解决。 + +普通恢复不因其他 fid 活跃而阻塞。tracking off 不凭空建立新可持久化文件行,但已有保留行仍可按原 fid 恢复;运行时控制和会话关闭不依赖进度开关。 + +## 5. 会话清理与全局暂停 + +### 5.1 会话清理(问题四/五) + +- 复用 `_TransferHandshakeRegistry.track_socket/cancel_socket`,listener/data socket、握手和 worker 绑定实际控制会话;旧会话退出只取消自己的资源。 +- 去掉两份 `_drop_stale_transfers` 及 peer-scoped 新连接 sweep。新会话需要等待的是事先捕获的旧 owner,而不是扫描时刚出现的当前 socket。 +- 旧恢复闭包固定使用创建时的控制 socket;`_forward_one` 可由内部传入捕获的 control_socket,不能在旧 worker 内重新取得新 `self.client_socket`。 +- 关闭资源、等待 worker 和持久化 I/O 不在全局锁或控制 reader 内执行;旧 finally 按 socket/entry/record 身份释放。 +- route 强制重建是**另一个定向动作**:只关闭该 route 数据腿,不调用整个控制会话的 cancel_socket,不影响其他 fid。 + +### 5.2 全局用户控制(问题七) + +- 普通传输保留当前 sender-authoritative 规则。 +- 转发的 Target 请求/Server 本地操作先经实际控制会话、稳定 child/upstream、peer/type/role 和当前 owner 校验定位 route,再作为请求送到 Source 的同一 upstream fid。 +- Source 的本地操作与这些请求在一个串行入口决定状态;Server 校验上游通知后,用各 Target 自己的 child fid 投影状态,不自行成为第二决定者。 +- Server 下游控制记录是 Source 决定的投影;其暂停字段不能再阻塞 writer。移除 relay writer 的独立用户暂停门槛,继续排空既有字节;Source 下一块前才等待。 +- 用户 start 不要求所有参与方逐个解锁。保留 confirmed/last_requested 以免未确认 pause→start 丢失,不把它改成请求 ACK 计数器。 +- 自动背压请求与用户意图分开;高水位 reader 门槛仍独立,只有缓冲下降才能解除。记录实际峰值和一次扇出超调,不宣称 total RAM 的严格上限。 +- 暂停不撤回最后一块,不阻止已完成文件的真实 ACK,也不把暂停计作传输失败。数据已全部发出时不凭暂停伪造完成;原有 ACK 成功条件不变,不另外设计新的全局超时策略。 + +## 6. 强制重建与逐 Target 调度(问题八) + +```mermaid +flowchart TD + A[数值恢复请求及身份校验] --> B[登记一个 route 重建 owner] + B --> C[结束该旧 route 上下游数据腿] + C --> D[等待旧 reader/writer 及接收端收尾] + D --> E[释放旧内存 查询各未完成 Target 的实际 offset] + E --> F[选一个可服务 Target 保持原 fid 重放] + F --> G{全部 Target 已有真实完成 ACK?} + G -->|否| H[保留任务 结束本轮上游 再服务下一 Target] + H --> F + G -->|是| I[回原有最终 ACK 成功后清理所属任务] +``` + +- route 按原任务对象和稳定 fid 串行登记;重建期间到达的合法请求合并为待恢复目标,不反复 teardown。请求者仍有自己的活跃接收腿时继续按接收占用规则拒绝重复登记;不把 pause 当 resume。 +- 强制关闭先停止旧读写,唤醒 pause/queue/pressure 等待,再释放内存。禁止边清旧队列边让旧 reader 入队,也禁止新流接到旧下游 socket。 +- 每个未完成 Target 的 offset 从其旧文件关闭后的实际大小取得。按 FIFO 服务已经拿到合法 offset 且 Source/Target 在线的目标;每轮只建立一个上游和一个下游,保持原 fid 并使用既有数据握手。 +- 一轮结束更新该 Target 完成集合。还有其他目标未完成时不向 Source 回整体成功 ACK;结束这一轮上游、保留 Source 上传和 Server route,旧发送 owner 收尾后再请求下一轮,不新增中间结果通道。 +- Source 离线保留 pending,重连后继续;Target 离线不阻塞已可服务目标。每目标单轮失败保留恢复依据,不无间隔循环自动重试;后续合法请求/重连可再次触发。 +- `offset=0` 是恢复而不是全新转发;空文件及 `offset==total` 走零正文,仍要求真实 ACK。 +- 所有 Target 已完成、仅上游 ACK 明确失败时,允许原 Source/route 的 EOF 再确认:保持原 upstream fid,核对数据头总长和 offset,只回有完成记录支撑的最终 ACK,不重开 Target、不重发正文。 +- 不新增 route total 字段。原 Source 从同 fid 保留上传行核对本地文件总长,Server 校验恢复头与 EOF offset,以及原 Source/route 的全 completed 证据;不能仅凭 offset==size 或未知 route 发送成功 ACK。 + +## 7. 数据流与所有路径验收映射 + +普通恢复:实际 Receiver → 原 fid/磁盘 offset → 同 fid 独占恢复预留 → 原文件命令和完整路径匹配 → 原端口握手建立新数据腿 → 实际内容/ACK → owning 清理。 + +转发控制:任意参与者 fid/type/role → Server 校验实际控制会话/peer/route/当前 owner → Source upstream 串行决定 → Server 按各 child fid 投影状态;文件循环只有 Source 停止新增块。 + +转发恢复:Target 请求 → route 校验/独占重建 → 旧数据腿退出及内存释放 → 逐目标 offset 回复 → 稳定 upstream/child、每轮重建数据连接 → 保留完成集合 → 所有真实 ACK 后终态清理。 + +| 路径 | 必须观察的证据 | 原子阶段/验证 | +|---|---|---| +| P01 普通上传恢复 | fid/原路径保持,实际 offset/内容/真实 ACK 正确 | C1;V1/V6,S1 | +| P02 普通下载恢复 | 同 P01,方向反转 | C1;V1/V6,S1 | +| P03 文件夹/同 basename 不同目录 | 原完整嵌套路径继续;不新建同名桥接文件 | C1/C3;V1/V3/V6,S1/S2 | +| P04 live/paused/握手/finalizing 普通对象 | 仍静默跳过,无第二 worker;保留未决握手隔离;其他 fid 独立 | C1;V1,S1 | +| P05 换腿期间再次断线/重启 | 原 fid/路径/进度仍可恢复;旧资源释放,不恢复旧运行时控制状态 | C1/C3;V1/V3,S1/S2 | +| P06 旧控制会话关闭/迟到 finally/延迟清理 | 只关闭旧资源;新 socket 保留;不依赖进度开关 | C1;V1,S1/S2 | +| P07 旧转发 worker 与 connect 交叉 | worker 不在新 socket 发握手,无 30s 等待环;旧占用退出 | C1;V1,S2 | +| P08 Source/Server/每个 Target 用户操作 | 同一 live route 的有限消息排空后确认值一致,只有 Source 决定;各端 start 可解除 | C2;V2,S3 | +| P09 交叉/重复/未确认 pause→start | 无换腿交叉时固定顺序证明不丢反向意图,无通知回包循环 | C2;V2,S3 | +| P10 暂停有在途/排队数据 | Source 下一块前等待;全部 Target 排空落盘;同 socket start;内容正确 | C2;V2,S3 | +| P11 背压和 start 交叉 | 本地 reader 硬门槛仍有效,内存不持续增长;不能放大成严格总内存上限声明 | C2;V2,S3 | +| P12 live/paused/EOF 上游收到合法转发恢复 | 旧上下游关闭、旧 worker 退出后内存清零;保持 fid;控制/其他 fid 不受影响 | C3;V3,S4 | +| P13 错 peer/origin/target/fid/重复恢复 | 非法无 teardown;合法重复只登记一个重建 owner,不中断新重放 | C3;V3,S4 | +| P14 多 Target 不同 offset/部分已完成 | 顺序重放各自字节;稳定 route/child 和完成集合不丢;完成目标不重传 | C3;V3,S4 | +| P15 Source/Target 离线和重连 | pending 保留、可服务目标继续、无忙重试;回连后同 fid 恢复 | C3;V3,S4 | +| P16 零 offset/空文件/EOF | 不新建全目标任务;不重发已收正文;必须真实 ACK | C1/C3/C4;V1/V3/V4,S1/S4/S5 | +| P17 所有目标完成、上游 ACK False/异常 | 保留可确认终态;同 fid EOF 补 ACK;不重开 Target;再次失败仍可确认 | C4;V4,S5 | +| P18 Client 自目标/混合目标/同机不同端口 | 自目标不建腿、不建行;混合只拒自身;其他合法目标内容/ACK 正确 | C5;V5,S6 | +| P19 tracking off/原保留行/query/delete/stop | 无凭空新进度;原 fid/query/快照 schema 不变;关闭后才能删 | C1/C3;V1/V3/V6,S1/S4 | +| P20 加密开关/rekey/线程式及 async/别名和 wildcard | 统一安全 I/O、不明文降级、不阻塞密钥接收;真实内容/ACK/owner 清理 | C1–C5;相应 V/S 的参数矩阵,V6 | + +问题二不属于上述验收目标:删除此前专门要求同 fid 新旧 leg_id 隔离及错误 leg_id 校验的两项,现按 P01–P20 重新编号。保留原有测试,不为缩小本轮范围删除或跳过既有用例;不得把会话清理通过表述为跨腿旧控制问题已解决。 + +## 8. 原子拆分(固定次序,逐项人工审查) + +预计行数包含必要回归和局部文档,不含本次计划文件;实际超过 500 行或混入独立意图必须先修订拆分,不在实现中自行扩大。每阶段完成一条可运行的行为路径及局部证据;不加占位分支、feature flag 或生产 no-op。 + +| 阶段 | 单一意图、必须修改点 | 文件与预计 diff | 局部验收 | +|---|---|---|---| +| C1 | 实际控制会话统一资源取消、旧 owner 收尾;删除 peer sweep;旧恢复固定 socket | connect_tcp;handshake/TCP lifecycle 与 control/resume 必要回归;250–450 行 | V1,S1/S2;P01–P07/P16/P19/P20 | +| C2 | 全局暂停,所有参与者请求交 Source 决定、Server 用各 child fid fanout;writer 排空,保留硬背压 | connect_tcp;transfer_control 单测及真实 control/转发用例;250–450 行 | V2,S3;P08–P11/P20 | +| C3 | 问题 8A:完整 route 定向 teardown/offset 查询/单 owner 调度,逐 Target 推进可服务请求;同 fid、无内存复用 | connect_tcp;fid_routes、control/resume 故障场景;300–500 行 | V3,S4;P03/P05/P12–P16/P19/P20 | +| C4 | 问题 8B:已完成 route 的上游 ACK 明确失败后,同 fid 做 EOF 再确认;不扩展 route schema | connect_tcp;既有 resume/control EOF 回归;180–300 行 | V4,S5;P16/P17/P20 | +| C5 | Client 统一入口拒绝自身目标,不误拒同机不同端口及其他目标 | connect_tcp;file_transfer/control 必要契约;60–150 行 | V5,S6;P18/P20 | +| C6 | 文档/变更记录/最终报告、规则沉淀、更新所有受影响契约描述;明确暂缓问题二 | 说明文档、变更记录、计划状态、实施报告;150–300 行 | V6;P01–P20 逐项列结论,不以通过数代替运行证据 | + +顺序:`C1 → C2 → C3 → C4 → C5 → C6`。删除原 leg_id 分配/解析基础与端口/控制 wire 切换两个阶段,其余按原意图顺延编号。每项完成窄验证、运行证据和报告后等待人工放行;本计划确认不等于自动创建这些 git 提交。 + +## 9. 验收命令和证据格式(计划约定;实际执行见实施报告) + +每个阶段完成代码/测试后运行一次本阶段窄验证,不在编辑中途反复跑检查。以下 `V` 是约定命令编号;既有稳定 fid、控制/端口字段保证保留,只更新全局暂停和恢复等已变更契约断言,不删路径、不降低内容/ACK/所有权保证。 + +```bash +# V1 — C1 会话生命周期 +.venv/bin/python -m pytest test/unit/network_api/test_transfer_handshakes.py test/unit/network_api/test_TCP_client.py test/unit/network_api/test_TCP_server.py test/unit/network_api/test_resume_matching.py test/integration/network_api/test_tcp_transfer_control.py test/integration/network_api/test_tcp_transfer_resume.py -k 'disconnect or reconnect or session or owner or stale or cleanup or resume' -q +# V2 — C2 全局控制和背压 +.venv/bin/python -m pytest test/unit/network_api/test_transfer_control.py test/integration/network_api/test_tcp_transfer_control.py -q +# V3 — C3 定向重建与顺序恢复 +.venv/bin/python -m pytest test/unit/network_api/test_fid_routes.py test/integration/network_api/test_tcp_transfer_resume.py test/integration/network_api/test_tcp_transfer_control.py -k 'forward or relay' -q +# V4 — C4 EOF 与最终 ACK +.venv/bin/python -m pytest test/unit/network_api/test_resume_matching.py test/integration/network_api/test_tcp_transfer_resume.py -k 'ack or eof' -q +# V5 — C5 转发入口 +.venv/bin/python -m pytest test/integration/network_api/test_tcp_file_transfer.py test/integration/test_forward_extension.py test/integration/test_forward_msg_attribution.py test/integration/network_api/test_tcp_transfer_control.py -k 'forward or relay or self_target' -q +# V6 — 最终一次受影响范围合并回归,不扩为项目全套 +.venv/bin/python -m pytest test/unit/network_api test/integration/network_api/test_tcp_transfer_control.py test/integration/network_api/test_tcp_file_transfer.py test/integration/network_api/test_tcp_transfer_resume.py test/integration/network_api/test_crypto_tcp.py test/integration/network_api/test_tcp_async_server.py test/integration/test_forward_extension.py test/integration/test_forward_msg_attribution.py -q +``` + +实施阶段另建并在结束后删除一次性真实程序 `/tmp/pyflow-transfer-lifecycle-smoke.py`,不调用 pytest 测试函数、不 mock 文件/网络/加密主路径,固定 `--case` 入口: + +- **S1** `--case direct-leg`:双向普通文件/目录、稳定 fid/原路径、旧会话 owner 清理、换腿中断/重启及 tracking off 原保留行;不加入同会话旧控制帧跨腿隔离保证。 +- **S2** `--case relay-leg`:稳定 upstream/child、完成集合及旧 worker/旧控制会话交叉;证明旧任务不借新控制 socket。 +- **S3** `--case global-pause`:至少两个 Target,逐一发请求,确认后 Source 不新增块、旧块排空、同 socket start、压力硬门槛。 +- **S4** `--case serial-recovery`:不同落盘 offset、上游在线/暂停/EOF、多请求、离线目标及无关 fid;记录旧队列释放和每轮一个目标。 +- **S5** `--case eof-confirm`:真实目标 ACK 后定向注入上游 ACK False/异常,再做同 fid 零正文确认,验证再次失败和重启。 +- **S6** `--case self-target`:自身、混合目标和本机不同端口,保留合法目标传输结果。 + +每个 case 参数矩阵覆盖明文/加密,以及 thread/async 的对应实际分派;原端点重连覆盖配置别名、wildcard。用 Event/Barrier 固定顺序,计时只用于失败截止,不靠 sleep 碰运气。 + +证据每条包含:阶段/路径编号、实际命令与退出码、稳定 fid、实际控制/data socket owner、原路径和实际落盘 offset、完整内容比较/必要 hash、真正 ACK 结果、队列/worker/索引最终状态。快照沿用既有 schema,无新增身份迁移字段;问题二列“暂缓”,未运行参数组列“未覆盖”,不借历史结果充数。本节是批准前的验收约定,各阶段实际执行情况和失败记录见实施报告。 + +## 10. 影响、风险与人工确认闸门 + +- **公共契约/协议影响**:fid、原文件/转发命令、pause/start 及端口响应格式、端口解析/握手结果、file_transfer_mode 签名保持不变;不为问题二迁移消费者。全局暂停、强制转发恢复和 `/resume_trans ... ? ...` 查询仍改变契约;查询扩展 parser/formatter 的 offset 值域,必须同步所有消费者,不声称全部向后兼容。 +- **持久化模型不变**:保留五项文件行、scoped key 和 relay schema;不新增版本、恢复绑定、route total 或数据腿编号。EOF 再确认依赖原 Source 上传行与真实 completed 记录,不把 offset 相等单独当成功证据。 +- **并发风险**:不得持 progress/route/leg 全局锁等待 I/O 或线程;Source 旧 owner 退出前不得开下一轮;身份及 route 校验必须先于 teardown;同 fid 的旧 finally 不得清理新 owner。问题二的跨腿迟到控制窗口明确接受,不纳入自动收敛承诺。 +- **完成语义**:已完成 Target 只保留证据,不重传;中间轮不得伪造整体成功;最后的 ACK 明确失败必须保留可确认状态。用户不接受的新结果通道和 ACK-of-ACK 不引入。 +- **平台边界**:运行环境能验证的 Linux 结果不代替 native Windows;Windows/其他 Python 版本如未实际运行,报告明确未覆盖。不得通过改 CI 或阈值规避。 +- **规则沉淀**:真实会话资源取消、不同 offset 顺序内容恢复、末次 ACK 再失败/成功三类消费者可见回归成为检查项,不新增源码字符串断言,也不为暂缓的问题二增加新测试约束。 +- **文档/报告**:最终报告逐 P01–P20 给结论,单列问题二暂缓;每个原子变更含意图、范围、数据流、局部命令、未覆盖项、风险;文档随变更完成,不留“以后补”。 + +本轮用户已明确要求开始 C1,作为 C1 的实施授权;不再重复索取同一确认。C1 完成后提交局部证据与报告,等待人工审查,不因此自动进入 C2–C6。 diff --git a/docs/plans/transfer-control-lifecycle-report.md b/docs/plans/transfer-control-lifecycle-report.md new file mode 100644 index 0000000..7dfeaeb --- /dev/null +++ b/docs/plans/transfer-control-lifecycle-report.md @@ -0,0 +1,51 @@ +# 传输控制生命周期实施报告 + +## C1:实际控制会话取消与旧 owner 收尾 + +状态:**C1 实现及局部验收完成,等待人工审查**。V1 最终通过,独立真实 socket 场景通过;此前失败及修正记录保留在下文。C2–C6 未开始,未创建 git 提交、合并或推送。依据:[需求卡](transfer-control-lifecycle-requirements.md)、[计划 C1](transfer-control-lifecycle-plan.md#8-原子拆分固定次序逐项人工审查)。 + +### 意图、更改路径与解决的问题 + +- `PyFlow/network_api/connect_tcp.py`:删除 Server/Client 两份 `_drop_stale_transfers`。重连不再按 peer 扫描进度表并关闭扫描时的当前 socket,避免迟到清扫误伤新会话。 +- `_retire_transfer_session` 统一取消实际控制 socket 的握手、listener/data socket、控制状态及未绑定接收请求;资源登记保留至 worker 真正收尾,`wait_socket` 等待所属资源释放。关闭 socket 在 registry 锁外执行。 +- `_sending_transfer`、`_start_resume_send` 保存准入时控制 socket;`_wait_transfer_session` 仅等待捕获的原 send state/receive record。旧 finally 继续按对象身份释放,不删除替换后的 owner。 +- Server 在会话退役时保存旧 owner 快照,后台排空后删除快照;重连 worker 固定新准入 socket,旧 worker 不再按 peer 取得后来替换的连接。`stop` 在 client 锁外取消和关闭连接。 +- Client 先退役原 socket,再启动新控制 reader;后台恢复等待原 owner,不再在 reader 启动前等待。连续重连的恢复 worker 按原线程链排空。转发恢复显式传入捕获的 `control_socket` 到 `_forward_one`,避免旧任务借新 socket 发握手并形成等待环。 +- `test/unit/network_api/test_transfer_handshakes.py`、`test_resume_matching.py`:保留实际会话取消、同 fid 占用和旧 owner 等待契约,增加旧清理后新 socket 仍可收发及迟到释放不删新 owner 的断言。 +- `test/integration/network_api/test_tcp_transfer_resume.py`:将原 sweep 用例迁移为实际控制会话退役;相同 fid 的不同会话保持独立;暂停腿退役后用原 fid 真实恢复,比较内容并确认发送端成功清理。 +- `test/integration/network_api/test_tcp_transfer_control.py`:事件固定“旧转发恢复 worker 已准入但尚未执行 → 新 connect → 放行旧 worker”,覆盖明文别名、加密 thread、加密 async/wildcard/tracking off。断言旧任务仅使用原 socket、失败保留原上传行、新会话可继续收消息。 + +数据流:实际控制会话退役 → registry 标记关闭并取消所属资源/握手 → 清除所属运行时控制状态 → 捕获旧 owner → 后台等原资源及 owner 收尾 → 经固定的新会话发恢复请求 → 原 fid/路径恢复 → 真实最终 ACK → owning 清理。 + +### 局部验证 + +V1 最终结果:**112 passed、97 deselected,240.29 秒,退出码 0**(Linux、Python 3.10.20)。筛选范围与计划相同;97 项为既定 `-k` 未选中,不是新增 skip,也不代表全套通过。 + +失败记录:首轮输出包含 2 个 fixture 错误,300 秒超时,不能记为通过。窄定位运行得到 17 passed、1 error:新增加密重连用例未等待新握手完成便结束,teardown 发现 `_crypto_exchange_thread`、`_crypto_wait_server_ready` 尚未退出。为新控制连接双方补上真实 `_wait_control_secure` 就绪前提,保留原零存活 worker 断言;随后执行下面完整 V1 选择并通过,未修改生产加密流程或延长 fixture join 来掩盖错误。 + +```bash +.venv/bin/python -m pytest test/unit/network_api/test_transfer_handshakes.py test/unit/network_api/test_TCP_client.py test/unit/network_api/test_TCP_server.py test/unit/network_api/test_resume_matching.py test/integration/network_api/test_tcp_transfer_control.py test/integration/network_api/test_tcp_transfer_resume.py -k 'disconnect or reconnect or session or owner or stale or cleanup or resume' -x -vv --tb=short +``` + +独立程序不调用 pytest 测试函数,使用真实控制/data socket、加密、文件 I/O 和最终 ACK;Event 固定交叉时序,方法包装仅观察真实执行或设置旧 worker 放行点。临时脚本 `/tmp/pyflow-transfer-lifecycle-smoke.py` 已在验证后删除,运行时临时文件与密钥目录也已清理。 + +```bash +# 每项分别运行 --alias、--encrypted、--encrypted --async-server --untracked +PYTHONPATH="$PWD" .venv/bin/python /tmp/pyflow-transfer-lifecycle-smoke.py --case direct-leg <参数> +PYTHONPATH="$PWD" .venv/bin/python /tmp/pyflow-transfer-lifecycle-smoke.py --case relay-leg <参数> +``` + +- S1 会话部分:3 组参数各完成上传、下载,共 6 次同 fid 恢复。fid 为 810/811;实际原文件 offset=0,原完整路径保持,旧 control/data socket 均已关闭,新控制端点保持,发送端实际最终 ACK=True,成功后所属进度行删除。加密 async 使用 wildcard 绑定,并在产生保留行后关闭 tracking 再断线/恢复。 +- S1 完整内容 SHA-256:`f2a6736d846749945c57b953b657f9b483c8c4e842b590e00a0cdd0574c20c33`。明文、加密 thread、加密 async 的独立程序退出码均为 0;各自 35、74、73 个观察到的 worker 最终存活数为 0。 +- S2 会话部分:3 组参数均证明旧转发恢复 fid=820 的 worker 固定原 socket、返回 False、原上传行保持且不建立伪 route;新控制连接继续完成一次真实转发,最终 ACK=True、内容一致。新转发按原规则分配自己的 fid,不把该新任务报告为 fid=820 的恢复成功。 +- S2 内容 SHA-256:`5bc85cfbbe30eb61c8fcbbacdd78975ce49973c0fbf69771c03258ac793c7c03`。3 组程序退出码均为 0;各自 23、62、62 个 worker 最终存活数为 0。 +- 独立程序首轮加密 S1 的观察器误将公钥传输(fid=None)的 ACK 计为业务恢复结果,断言失败、退出码 1;按业务 fid 过滤观察后,只重跑受影响的加密 S1 参数组并通过,未以此修改或绕过生产传输/加密路径。 + +### 范围、不变量与未覆盖项 + +- C1 对应 P01–P07、P16/P19/P20 的会话生命周期和回归保护。独立程序不穷举全部组合;V1 实际通过了 online resume 的各方向/加密/async/tracking off、文件/文件夹失败后恢复、实际落盘 offset、进度保存/重载、EOF/ACK、稳定转发 route/child、旧 socket 握手隔离及 localhost/wildcard 身份回归。不能把持久化重载用例说成已完成独立多进程重启矩阵,也不将零 offset 独立程序当作所有恢复路径的替代证据。 +- 不改变稳定 upstream/child fid、pause/start 四 token、端口响应、`file_transfer_mode` 签名、进度/快照 schema、普通 busy 规则或真实 ACK 判成功规则。未改 CI、依赖、coverage 策略,未删用例、跳过路径或弱化断言。 +- 问题二继续暂缓:同一控制 socket、同 fid 换腿时迟到 pause/start 的严格代次隔离未实现;未新增 leg_id、换新 fid、协议字段或自动重试。 +- C2 全局暂停、C3 route 定向重建/offset 查询/逐 Target 顺序恢复、C4 EOF 补确认、C5 自转发拒绝、C6 总体验收未实施,不能据 C1 结果宣称这些行为已完成。 +- 未运行 native Windows、其他 Python 版本或跨进程并发进度写入验收;本轮未做抓包,不将加密真实传输等同于全协议安全审计。 +- 本轮会话生命周期契约回归作为规则沉淀;变更记录见 `docs/source/changes/transfer-fid-routes.md`。C1 现等待人工审查,不自动进入 C2。 diff --git a/docs/plans/transfer-control-lifecycle-requirements.md b/docs/plans/transfer-control-lifecycle-requirements.md new file mode 100644 index 0000000..0f9624d --- /dev/null +++ b/docs/plans/transfer-control-lifecycle-requirements.md @@ -0,0 +1,105 @@ +# 传输控制生命周期与转发恢复 — 需求卡 + +状态:用户已选择暂缓问题二,并已明确授权按最后计划拆分开始 C1。C1 实现及局部验收完成,等待人工审查。保持原 upstream fid/child fid,不引入 leg_id,不修改 pause/start 或端口响应格式;当前只实施实际会话清理、旧 owner 收尾及旧 worker 固定 socket,其余行为留在后续阶段。实施与验证证据见[实施报告](transfer-control-lifecycle-report.md),不自动提交、合并或推送。 + +计划编写阶段没有运行 pytest、构建或实现烟测;此前文档一致性检查不等于功能验收。当前 C1 实际执行的命令、运行证据和失败记录统一见实施报告;此前换新 fid 或 leg_id 方案的检查记录不作为本轮验证结果。 + +计划编写阶段的文档机械检查通过:3 份文档、6 个相对链接、21 个计划涉及的既有文件路径、14 个验收命令引用路径、20 条验收路径、6 个原子阶段及命令组、6 个拟定运行场景,错误数为 0。当时实施报告尚未创建;这份历史检查不代表功能验收通过,当前实现证据另见实施报告。 + +## 审计结论的使用边界 + +- 此前问题一“正常恢复流程导致内容损坏”的结论已撤回:人工构造旧 offset / 新进度的实验不能证明正常协议生命周期会产生该状态,不再作为本轮修复项。 +- 任意端可请求暂停/开始、由数据发送端仲裁,是已确认特性,不是缺陷。 +- 问题二暂缓:不解决旧 pause/start 与同一控制会话、同 fid 数据腿重建交叉时的严格代次隔离。控制发送失败沿用现有失败/关闭路径,允许人工重新操作或结束控制会话后恢复;不承诺该窗口自动无缝收敛。断线资源清理和已商议的恢复能力仍在范围内。 +- 此前问题九(超长文件名)、十(控制队列增长)、十一(无 owner 的预置暂停)暂不处理。 +- 本轮文档只约定目标和待确认机制。此前真实 socket 复现是问题证据,不是尚未实现方案的验证结果。 + +## 目标与非目标 + +### 已确认目标 + +1. 普通上传/下载及转发恢复保持原 upstream fid/child fid、完整接收路径及进度记录;不为问题二增加数据腿编号、握手字段或持久化身份迁移。 +2. 会话关闭只处理该实际控制 socket 拥有的资源;不再让重连任务按 peer 扫描并关闭后来建立的新数据 socket。 +3. 流式转发采用全 route 的用户暂停:任意 Source、Server、Target 可请求 pause/start,Source 作最终仲裁。一个 Target 暂停,所有 Target 停止获得新的源数据。Server 已接收的数据继续排空到 Target;保留数据 socket,不做 seek 或重握手。 +4. 不采用“每个 Target 持有独立暂停锁、必须本人解除”的规则。任意端的 start 仍可经 Source 仲裁解除用户暂停。自动背压的内存硬门槛不被用户 start 清除。 +5. 有效的转发恢复请求到达 Server 后,不复用旧 relay 内存内容。若旧上游数据腿仍在,关闭该旧上游及依赖它的未完成下游,丢弃对应内存,再按接收端 offset 从 Source 重放。保留控制连接、稳定 upstream fid/child fid、已落盘文件及已确认目标集合;旧 owner 收尾后再用原握手重建数据腿。 +6. Client 发起转发时拒绝目标等于其自身控制端点的目标。不把“同机不同端口”或“连接 localhost Server”误当成自转发。 +7. 保留发送端以真实最终 ACK 判成功的规则。EOF 再确认不重传正文;所有 Target 已确认、仅上游 ACK 失败的终态必须能重新确认,不伪造未完成目标的 ACK。单个 Target 的完成只更新该目标,不能把部分完成当作整个任务成功。 +8. 正常发送仍可多目标并行;同一 route 的恢复阶段逐 Target 顺序重放,各用自己的实际落盘 offset,已完成目标不重传。 + +### 非目标 + +- 问题一不再列为待修缺陷;问题二暂缓,不增加 leg_id、恢复换新 fid 或 pause/start 代次字段;问题三是已确认特性;问题九、十、十一继续暂不处理。 +- 不增加内存回放缓存、磁盘中转缓存、目标断点范围过滤或新的传输结果通道。 +- 不改 CI、依赖、coverage 策略;不删或弱化测试。 +- 不解决 NAT、控制端点改变后身份迁移、多进程共享进度文件及同尺寸源文件内容改变。 +- 不把 pause 返回 True 当作对端确认或立即停止落盘;不保证撤回已经交给 socket 的字节。 +- 不用某一个 Target 的 offset 替代其他 Target 的 offset;不为恢复阶段增加并行重放及字节范围过滤机制。 + +## 修改思路与确认状态 + +### D2:暂缓旧控制命令跨腿隔离(本轮不修) + +- fid 继续表示原文件/转发任务,恢复不重分配;原接收记录、完整路径、route 和 child 映射继续使用现有 fid。 +- 不实现 leg_id 分配器、端口字段、控制帧字段、file_transfer_mode 新关键字或相关测试/helper 的协议迁移;不建立其他代次隔离机制替代它。 +- pause/start 和端口响应保持现有四 token 格式;原 `/file`、`/file_folder`、`/forward_item ... resume=` 及持久化模型不变。此前换新 fid 所需的 old/new 映射、rebinds、快照 version 也不实施。 +- 保留现有实际控制 socket 校验、pending/unresolved 握手隔离、同 fid 占用及旧 owner 收尾;这不能被表述为已经解决同一控制会话内迟到控制消息的问题。 +- 暂缓只针对问题二,不取消问题四/五的重连安全修复,也不取消问题七和八的正常控制及恢复方案。 + +### D4:统一为实际控制会话所有权(拟定机制,随更改计划审查) + +- 复用 `_TransferHandshakeRegistry.track_socket/cancel_socket`,让会话资源只有一个登记及取消入口。 +- 已知的旧控制会话退役时,取消它自己的 listener/data socket/握手及控制状态;新会话不得借 peer 地址取得旧会话之外的资源。 +- 旧 worker 固定使用创建/准入时的控制 socket,不在后台重新读取全局 `self.client_socket` 或按 peer 获取替换后的 socket。这也避免旧转发恢复 worker 误用新连接。 +- 拆除 `_drop_stale_transfers` 按进度表找 socket 并关闭的重复职责。保留基于旧 owner 快照的必要收尾等待;等待不得持有全局锁或阻塞需要处理握手的控制接收线程。 +- 旧 finally 按原 socket、entry、record 身份释放,不能删新 owner;失败进度继续按原规则保留。 + +### D8:强制重建的多目标调度(已选择顺序恢复) + +当前 route 的上游被多个 Target 共享。重建上游并清空旧内存时,也必须结束依赖该旧字节流的未完成下游数据腿,等待接收端收尾、落盘;保留原 fid,不能把新 offset 字节直接接到旧下游 socket。 + +按已选择的简化方向,恢复流程约束如下: + +1. Server 对同 route 串行登记一个重建操作。先验证请求的实际会话、原始 Source、Target、fid 和 offset,再做 teardown;无效请求不得中断任何传输。 +2. 关闭旧上下游数据腿、唤醒暂停/队列等待者并等待旧 owner 收尾;旧 reader/writer 不再活动后,释放该旧 relay 的内存和运行时控制状态。 +3. 保留全部已完成 Target;它们不参与重传。对其他未完成 Target,分别从各自收尾后的实际文件大小取得恢复请求,不使用 Server 的发送计数猜落盘位置。 +4. 一轮只服务一个 Target 的恢复请求:Source 从该 Target 的 offset 发送到 EOF;随后按已有 route 继续下一个未完成 Target 的恢复。离线 Target 保留未完成,不阻塞可服务目标,不虚报全文件成功。 +5. 同 route 恢复请求在一个调度入口登记,重建中收到的请求不重复 teardown、不创建第二个 Source sender;Source 接受重放前也必须完成旧发送 owner 的收尾,不能沿用 busy 静默忽略而丢掉已触发的恢复。 +6. offset == size 且仍需目标确认时走零正文 EOF 确认;所有 Target 已确认时只恢复上游完成确认,不重发已完成目标。 + +强制结束共享 relay 后,计划由 Server 用 `/resume_trans ? ` 查询各未完成 Target 收尾后的落盘 offset,Client 用原数值恢复形式回复;避免猜测已发出但未落盘的字节,也不增加定时重试。该查询语义与具体切换时机均随更改计划等待确认。 + +已确认取舍:正常发送仍可多目标并行;同 route 的恢复阶段改为逐 Target 顺序重放,换取无需共享字节范围过滤、无需内存缓存复用。用户已明确选择该调度方式;具体实现仍需另走计划与审查。 + +## 路径全集与验收证据要求 + +| 路径 | 必须证明的行为 | +|---|---| +| 普通上传/下载,稳定 fid 换新数据腿 | 原 fid/路径保持,实际 offset、内容及真实 ACK 正确;保留原普通恢复语义,不验收问题二的跨腿旧控制隔离 | +| 普通/转发控制连接重连 | 只关闭旧会话资源;新腿不被旧清理或旧 finally 删除 | +| 暂停中断线、tracking off、listener/建连中退出 | 线程和 owner 结束;保留允许恢复的文件与进度;清理不依赖进度开关 | +| 旧恢复 worker 与新 connect 交叉 | worker 不在新 socket 上发送;接收线程启动不依赖误用新 socket 的旧任务 | +| Source、Server、任一 Target 发 pause/start | 有限输入排空后所有参与方的逻辑确认状态一致;由 Source 排序决定 | +| 两个 Target 相反请求、未确认 pause→start | 不吞掉反向意图、不回包循环;不是独立端点暂停锁 | +| 全局 pause,存在在途块/Server 排队块 | Source 下一块前停止;已有字节继续到达并落盘;同 socket start;最终内容和真实 ACK 正确 | +| 高水位与用户 start 交叉 | 不越过本地内存硬门槛,不误将自动背压释放当用户 start | +| 转发 resume 到达时上游仍在线/暂停/EOF等待 | 安全 teardown 原 route 数据腿、清空旧内存、旧 owner 完成后重建;无双 sender/双 writer | +| 多目标 offset 不同 | 各目标从各自实际落盘 offset 恢复,内容一致;完成目标不重传;失败/离线目标不被标成功 | +| offset 为零/EOF、最终 ACK 再次失败 | 不误清恢复记录;确认失败可再次恢复;成功清理所属记录 | +| Client 自转发与本机不同 Client | 拒绝自身完整控制端点,允许同 host 不同端口;统一入口覆盖 console/Web/文件夹/恢复 | +| 加密、密钥交换窗口、线程式/async Server | 统一 send/receive 路径;无明文降级;不阻塞密钥接收线程;真实内容、ACK、资源收尾 | + +验收须使用事件固定时序的真实本机 socket 传输,记录稳定 fid、实际 owner/socket、文件内容和最终 ACK;不能仅断言文件存在或测试没有抛错。问题二明确列为暂缓,不计入覆盖或通过声明。具体文件、协议、原子拆分及每条路径的验收命令见更改计划,均为待执行而非通过声明。 + +## 数据、安全和范围约束 + +- 所有 peer 身份由实际控制会话及现有端点规则确定,不按 fid 全局猜路由。 +- 校验在 teardown 前完成;控制请求走现有加密就绪及 send_message 入口。 +- 只清理所属 route 的内存和数据 socket,不关闭无关控制连接、其他 fid 或删除已落盘字节。 +- 不把 socket 仍打开或 offset 等于 size 单独作为成功证据。 +- pause/start 和端口响应格式、Python pause/start 签名及持久化模型不变;不新增 leg_id 或恢复换新 fid。全局暂停、转发强制恢复及 offset 查询仍改变原契约,不能声称全部向后兼容。 +- 风险等级:高(协议、并发、文件恢复完整性)。当前仅授权 C1 实施;后续阶段仍须逐项人工放行,不自动提交、合并或推送。 + +## 下一阶段闸门 + +行为选择保持不变:暂缓问题二,保持稳定 fid 和既有控制/端口格式。用户已授权开始 C1;C1 完成后交付代码路径、运行证据和局部报告供人工审查,未经后续放行不开始 C2–C6。 diff --git a/docs/plans/transfer-pause-start-direction-plan.md b/docs/plans/transfer-pause-start-direction-plan.md index 237cb69..295af70 100644 --- a/docs/plans/transfer-pause-start-direction-plan.md +++ b/docs/plans/transfer-pause-start-direction-plan.md @@ -2,6 +2,8 @@ 状态:**C1–C5 已交付;Windows 原端点重连故障的测试关闭顺序已修正,Linux CPython 3.14.4 带 coverage 的三个受影响参数组通过,native Windows 仍待 Actions 验证及人工审查**。历史结果与本轮中间失败保留;不将 Linux 通过等同于 Windows 通过。生产恢复语义、依赖和 CI 检查策略不变,证据及平台边界见[实施报告](transfer-pause-start-direction-report.md)。不自行提交、合并或推送。 +后续需求已收敛为“暂缓问题二,保持稳定 fid 和既有控制/端口格式;保留实际会话清理、旧 worker 固定 socket、自转发拒绝、全局转发暂停、结束旧 relay 后逐 Target 重放及 EOF 再确认”,见[传输控制生命周期更改计划](transfer-control-lifecycle-plan.md)(待人工确认,未实现)。此前恢复换新 fid 的提案已撤回,临时 leg_id 方案本轮不实施;本文保留上一轮历史设计和验证,独立下游 writer 暂停、live relay 恢复静默跳过等旧约束不作为后续方案的要求。 + ## 1. 需求卡 ### 目标 diff --git a/docs/source/changes/transfer-fid-routes.md b/docs/source/changes/transfer-fid-routes.md index 403f325..67d9755 100644 --- a/docs/source/changes/transfer-fid-routes.md +++ b/docs/source/changes/transfer-fid-routes.md @@ -1,6 +1,6 @@ # Change note: server FID routes, sender ownership and socket/FID recovery -> Current transfer-control contract: C1–C4b are committed and have passed their +> Previous transfer-control revision: C1–C4b are committed and have passed their > stage review gates; C5 documentation and combined acceptance are complete, > pending final human review. > The chronological entries below preserve earlier implementation history; @@ -9,6 +9,19 @@ > Current behavior and evidence are in > `docs/plans/transfer-pause-start-direction-report.md`. +## Lifecycle revision C1: retire actual control sessions + +- Session cancellation owns listeners, data sockets and negotiations by actual + control socket, independently of progress tracking. Reconnect no longer scans + peer progress to close whichever sockets happen to be current. +- Resource registration remains until worker cleanup; recovery waits for captured + old owners off the control reader. Delayed cleanup cannot close a newer session. +- Recovery workers keep their admitted control socket, including forwarded uploads. + Stable FIDs, original paths, wire fields, persistence and real final ACKs remain. +- This does not isolate delayed pause/start across same-socket, same-FID data-leg + replacement (deferred issue 2). Later lifecycle stages are not implemented here. +- Evidence: `docs/plans/transfer-control-lifecycle-report.md`. + ## Revision R1: sender-owned relay upstream FID - A relay source allocates and binds a fresh upstream FID before `/forward_item`. diff --git a/test/integration/network_api/test_tcp_transfer_control.py b/test/integration/network_api/test_tcp_transfer_control.py index 34bf700..3d504d1 100644 --- a/test/integration/network_api/test_tcp_transfer_control.py +++ b/test/integration/network_api/test_tcp_transfer_control.py @@ -993,3 +993,49 @@ def forward(*args, **kwargs): and not owner._active_transfer_sockets and not owner._receive_transfers and not owner._resume_sends for owner in (server, source, *targets))) assert not server._pending_originator_resumes + + +def test_reconnect_keeps_delayed_forward_resume_on_its_old_session(channel, tmp_path, monkeypatch): + server, client, releases = channel + source = tmp_path / "old-session.bin" + source.write_bytes(b"retained forward source") + fid, target = 734, ("127.0.0.1", free_port()) + key = ((client.host, client.port), fid) + row = [0, source.stat().st_size, None, str(source), target] + client.file_upload_progress[key] = row + old_control = client.client_socket + entered, release, done = threading.Event(), threading.Event(), threading.Event() + releases.append(release) + original, result = client._forward_one, {} + + def delayed(*args, **kwargs): + entered.set() + assert release.wait(20), "old worker was not released" + result["socket"] = kwargs.get("control_socket") + result["sent"] = original(*args, **kwargs) + done.set() + + monkeypatch.setattr(client, "_forward_one", delayed) + assert client.resume_trans(target, fid, 0) + assert entered.wait(10) + assert client.connect(), "new control reader must not wait for the old worker" + new_control = client.client_socket + assert new_control is not old_control + release.set() + assert done.wait(10) + assert result == {"socket": old_control, "sent": False} + assert wait_until(lambda: not client._resume_sends) + assert client.file_upload_progress[key] is row + assert fid not in server._fid_routes + peer = new_control.getsockname() + assert wait_until(lambda: peer in server.clients) + assert client._wait_control_secure(new_control) + assert server._wait_control_secure(server.clients[peer]["socket"]) + # A delayed reconnect task must not sweep or adopt the current session. + server._resume_after_connect(peer, old_control, ()) + received = threading.Event() + client.add_message_listener(lambda sender, message: received.set() + if message == "session-still-live" else None) + assert server.send_message(server.clients[peer]["socket"], "session-still-live") + assert received.wait(10) + assert client.client_socket is new_control and new_control.fileno() >= 0 diff --git a/test/integration/network_api/test_tcp_transfer_resume.py b/test/integration/network_api/test_tcp_transfer_resume.py index 2089786..1945b74 100644 --- a/test/integration/network_api/test_tcp_transfer_resume.py +++ b/test/integration/network_api/test_tcp_transfer_resume.py @@ -36,6 +36,7 @@ _socket_local_endpoint, _socket_peer_endpoint, _start_resume_send, + _retire_transfer_session, _transfer_handshake, format_resume_line, ) @@ -311,7 +312,7 @@ def send(receiver, src): assert all(key in server._active_transfer_fids for key in keys) assert server.pause_trans(fid, receivers[0], trans_type=0, direction=0) is False - assert server._drop_stale_transfers(receivers[0]) == 1 + _retire_transfer_session(server, server.clients[receivers[0]]["socket"]) assert sockets[0].fileno() == -1 assert server._active_transfer_sockets[keys[1]] is sockets[1] assert keys[1] in server._active_transfer_fids @@ -391,7 +392,7 @@ def test_equal_upload_fids_persist_and_reload_per_receiver(tmp_path): def test_equal_inbound_and_outbound_fids_cleanup_only_their_own_sockets(tmp_path): - """Receive cleanup cannot close an equal-id upload, including a client forward.""" + """Actual old-session cleanup cannot close an equal-id new-session upload.""" server = _start_server(tmp_path) client = None other = None @@ -410,6 +411,8 @@ def test_equal_inbound_and_outbound_fids_cleanup_only_their_own_sockets(tmp_path inbound, inbound_remote = socket.socketpair() outbound, outbound_remote = socket.socketpair() sockets.extend((inbound, inbound_remote, outbound, outbound_remote)) + inbound_control, inbound_wire = socket.socketpair() + sockets.extend((inbound_control, inbound_wire)) inbound_remote.settimeout(2) outbound_remote.settimeout(2) fid = 606 @@ -427,18 +430,21 @@ def test_equal_inbound_and_outbound_fids_cleanup_only_their_own_sockets(tmp_path control = (instance.clients[receiver]["socket"] if instance is server else client.client_socket) control_key = (receiver, fid, 1, 0) + assert instance._transfer_handshakes.track_socket(inbound_control, inbound) + assert instance._transfer_handshakes.track_socket(control, outbound) state = instance._transfer_controls.register(control_key, control, outbound) assert state is not None assert instance.pause_trans(fid, receiver, trans_type=1, direction=0) is True assert len(recv_entry) == len(upload_entry) == 5 assert upload_entry[4] == logical_peer - assert instance._drop_stale_transfers(inbound_peer) == 1 + _retire_transfer_session(instance, inbound_control) assert inbound_remote.recv(1) == b"" assert instance._active_transfer_sockets[fid] is inbound assert fid in instance._active_transfer_fids instance._file_progress_finish(instance.file_recv_progress, fid, recv_entry) instance._release_transfer_socket(fid, inbound) + instance._transfer_handshakes.release_socket(inbound_control, inbound) assert fid not in instance._active_transfer_sockets assert fid not in instance._active_transfer_fids assert fid not in instance.file_recv_progress @@ -450,9 +456,8 @@ def test_equal_inbound_and_outbound_fids_cleanup_only_their_own_sockets(tmp_path outbound.sendall(b"x") assert outbound_remote.recv(1) == b"x" - # The client's receiver is its server even when row[4] names the - # logical forward target; cleanup must use the scoped namespace. - assert instance._drop_stale_transfers(receiver) == 1 + # Retire the actual control owner, not the logical target in row[4]. + _retire_transfer_session(instance, control) assert outbound_remote.recv(1) == b"" assert instance._active_transfer_sockets[upload_key] is outbound assert upload_key in instance._active_transfer_fids @@ -460,6 +465,7 @@ def test_equal_inbound_and_outbound_fids_cleanup_only_their_own_sockets(tmp_path instance.file_upload_progress, upload_key, upload_entry ) instance._release_transfer_socket(upload_key, outbound) + instance._transfer_handshakes.release_socket(control, outbound) assert upload_key not in instance._active_transfer_sockets assert upload_key not in instance._active_transfer_fids assert upload_key not in instance.file_upload_progress @@ -2938,11 +2944,11 @@ def test_closed_control_socket_falls_back_to_the_configured_endpoint(tmp_path): @pytest.mark.parametrize("sender_side", ["server", "client"]) -def test_paused_leg_is_released_by_stale_sweep(tmp_path, monkeypatch, sender_side): - """A reconnect sweep releases the paused owner before recovery starts. +def test_paused_leg_is_released_by_session_retirement(tmp_path, monkeypatch, sender_side): + """Retire the actual session, then recover stable IDs with a real final ACK. - Closing wakes the pause wait; the owner keeps its socket index until final - cleanup, then releases the per-fid send lock and permits a new resume. + Closing wakes the pause wait; reconnect must wait for the original owner + without closing a replacement session's data sockets. """ workers = _track_socket_workers(monkeypatch) server = _start_server(tmp_path) @@ -2953,7 +2959,8 @@ def test_paused_leg_is_released_by_stale_sweep(tmp_path, monkeypatch, sender_sid server.file_transfer_dir = str(server_recv) client_recv = tmp_path / "client_recv" client_recv.mkdir() - client = _start_client(tmp_path, server, name="client", recv_dir=client_recv) + client = _start_client(tmp_path, server, name="client", recv_dir=client_recv, + client_port=free_port()) clients.append(client) peer = client.client_socket.getsockname() assert wait_until(lambda: peer in server.clients) @@ -2982,7 +2989,7 @@ def test_paused_leg_is_released_by_stale_sweep(tmp_path, monkeypatch, sender_sid result = {} def send_leg(): - with _sending_transfer(sender, key), _transfer_handshake( + with _sending_transfer(sender, key, control_socket=control), _transfer_handshake( sender, control, fid ): return sender.file_transfer_mode( @@ -3007,18 +3014,22 @@ def send_leg(): ), "the paused leg never registered" control_key = (*key, 0, 0) assert sender._transfer_pause.get(control_key) is True - swept = sender._drop_stale_transfers(peer=peer if sender is server else None) - assert swept == 1 + _retire_transfer_session(sender, control) assert wait_until(lambda: not leg.is_alive(), timeout=10), ( - "the swept leg stayed paused" + "the retired leg stayed paused" ) assert result.get("value") is False assert control_key not in sender._transfer_pause assert key in sender.file_upload_progress - calls = [] - assert _start_resume_send(sender, key, target, calls.append, control_socket=control) - assert wait_until(lambda: calls, timeout=10), "the queued resume never ran" - assert calls[0] is sender.file_upload_progress[key] + assert not _start_resume_send(sender, key, target, lambda row: pytest.fail("retired owner"), + control_socket=control) + client.client_socket.shutdown(socket.SHUT_RDWR) + assert wait_until(lambda: not client.running and peer not in server.clients) + assert client.connect() + output = (client_recv if receiver is client else server_recv) / src.name + assert wait_until(lambda: key not in sender.file_upload_progress + and fid not in receiver.file_recv_progress, timeout=20) + assert output.read_bytes() == src.read_bytes() finally: _close_socket_workers(server, clients, workers) \ No newline at end of file diff --git a/test/unit/network_api/test_resume_matching.py b/test/unit/network_api/test_resume_matching.py index 6a63b7c..3c63df5 100644 --- a/test/unit/network_api/test_resume_matching.py +++ b/test/unit/network_api/test_resume_matching.py @@ -19,6 +19,8 @@ _TransferHandshakeRegistry, _start_resume_send, _resumable_entry, + _retire_transfer_session, + _wait_transfer_session, format_resume_line, parse_resume_command, ) @@ -101,6 +103,7 @@ def ordinary_resume(): _transfer_progress_lock=threading.RLock(), _progress_discarded=False, file_upload_progress={key: [100, 100, None, "/send/eof.bin", PEER]}, _resume_sends={}, _active_transfer_fids=set(), _active_transfer_sockets={}, + _receive_transfers={}, _transfer_pause=paused, _transfer_pause_cond=condition, _transfer_controls=_TransferControlRegistry(paused, condition), _transfer_handshakes=_TransferHandshakeRegistry(), @@ -185,7 +188,7 @@ def request(): def test_reconnect_waits_for_final_send_owner_after_its_socket_is_released( ordinary_resume, owner_type, monkeypatch ): - owner, key, _, _ = ordinary_resume + owner, key, control, wire = ordinary_resume owner.file_recv_progress = {} waiting = threading.Event() real_wait = owner._transfer_progress_changed.wait @@ -196,9 +199,13 @@ def observe_wait(timeout=None): monkeypatch.setattr(owner._transfer_progress_changed, "wait", observe_wait) with ThreadPoolExecutor(max_workers=1) as pool: - with _sending_transfer(owner, key): - reconnect = pool.submit(owner_type._drop_stale_transfers, owner, PEER, wait=True) + with _sending_transfer(owner, key, control_socket=control): + retired = _retire_transfer_session(owner, control) + reconnect = pool.submit(_wait_transfer_session, owner, retired) assert waiting.wait(5) assert not reconnect.done() - assert reconnect.result(timeout=5) == 0 + owner._active_transfer_sockets[key] = wire + owner_type._release_transfer_socket(owner, key, control) + assert owner._active_transfer_sockets[key] is wire + assert reconnect.result(timeout=5) is None assert not owner._resume_sends diff --git a/test/unit/network_api/test_transfer_handshakes.py b/test/unit/network_api/test_transfer_handshakes.py index f53e7de..5fd9176 100644 --- a/test/unit/network_api/test_transfer_handshakes.py +++ b/test/unit/network_api/test_transfer_handshakes.py @@ -129,6 +129,19 @@ def test_disconnect_cancels_only_its_socket_requests_and_resources(): assert registry.resolve_port(new_control, 17, 43002, "plain") assert registry.wait(first, 0) is None assert registry.wait(second, 0) == ("port", 17, 43002, "plain") + replacement, replacement_wire = socket.socketpair() + try: + assert registry.track_socket(new_control, replacement) + registry.release_socket(old_control, left) + registry.cancel_socket(old_control) # delayed teardown, after new ownership + registry.wait_socket(old_control) + replacement.sendall(b"new session survives") + assert replacement_wire.recv(64) == b"new session survives" + assert registry.closed(old_control) and not registry.closed(new_control) + finally: + registry.release_socket(new_control, replacement) + replacement.close() + replacement_wire.close() def test_reconnect_socket_allows_same_fid_after_old_session_is_retired(): From d1900e79ab9f9542a29a06b93f6b6b601e3437f8 Mon Sep 17 00:00:00 2001 From: F18-Ray Date: Wed, 18 Nov 2026 10:48:29 +0800 Subject: [PATCH 11/19] fix(connect_tcp): arbitrate relay-wide pause and start at the source --- PyFlow/network_api/connect_tcp.py | 96 ++++++++---- docs/plans/transfer-control-lifecycle-plan.md | 6 +- .../transfer-control-lifecycle-report.md | 47 +++++- ...transfer-control-lifecycle-requirements.md | 8 +- docs/source/File_Transfer/File_Transfer.rst | 42 +++--- docs/source/Network_APIs/TCP_Client_APIs.rst | 11 +- docs/source/Network_APIs/TCP_Server_APIs.rst | 18 ++- docs/source/changes/transfer-fid-routes.md | 13 ++ .../network_api/test_tcp_transfer_control.py | 142 ++++++++++++------ .../network_api/test_tcp_transfer_resume.py | 51 +++---- .../unit/network_api/test_transfer_control.py | 88 ++++++----- 11 files changed, 330 insertions(+), 192 deletions(-) diff --git a/PyFlow/network_api/connect_tcp.py b/PyFlow/network_api/connect_tcp.py index e26fd21..6afaca4 100644 --- a/PyFlow/network_api/connect_tcp.py +++ b/PyFlow/network_api/connect_tcp.py @@ -901,7 +901,7 @@ def __init__(self, paused, condition, instance=None): self._legs = {} self._instance = instance - def register(self, key, control_socket, owner): + def register(self, key, control_socket, owner, *, relay=None): """Bind an unclaimed identity, adopting only its sender's preset pause.""" if control_socket is None or owner is None: raise ValueError("a control socket and leg owner are required") @@ -911,13 +911,19 @@ def register(self, key, control_socket, owner): return state if (state["control_socket"] is control_socket and state["owner"] is owner) else None paused = key[3] == 0 and self._paused.get(key, False) + if relay is not None and key[3] == 0: + if paused: + relay["requested"] = True + paused = False + self._paused.pop(key, None) state = { "key": key, "control_socket": control_socket, "owner": owner, "lock": threading.RLock(), "confirmed_state": paused, "last_requested_state": False, "initial_notification": paused, "ready": self._instance is None or key[3] == 1, - "user_paused": False, "backpressure": False, } + if relay is not None: + state["relay"] = relay self._legs[key] = state return state @@ -960,7 +966,7 @@ def announce(self, state, send=None): return False return self._send(state, state["confirmed_state"], send) - def local(self, key, paused, send=None, *, backpressure=False, owner=None): + def local(self, key, paused, send=None, *, owner=None): """Decide a sender state or submit a receiver intent, deduplicating both.""" with self._condition: state = self._legs.get(key) @@ -974,20 +980,20 @@ def local(self, key, paused, send=None, *, backpressure=False, owner=None): self._paused.pop(key, None) self._condition.notify_all() return False + if "relay" in state: + return self._relay_control(state, paused, send, owner=owner) with state["lock"]: if not self._live(state): return False if owner is not None and state["owner"] is not owner: return False - if key[3] == 1: - state["backpressure" if backpressure else "user_paused"] = paused - paused = state["user_paused"] or state["backpressure"] if key[3] == 0: if state["confirmed_state"] == paused: return False self._confirm(state, paused) else: - if (state["confirmed_state"] == paused + # Other relay participants may have an in-flight opposite intent. + if (key[2] != 1 and state["confirmed_state"] == paused and state["last_requested_state"] == paused): return False state["last_requested_state"] = paused @@ -999,6 +1005,8 @@ def receive(self, key, control_socket, paused, send=None): state = self._legs.get(key) if state is None: return False + if "relay" in state: + return self._relay_control(state, paused, send, control_socket=control_socket) with state["lock"]: if not self._live(state) or state["control_socket"] is not control_socket: return False @@ -1009,6 +1017,37 @@ def receive(self, key, control_socket, paused, send=None): return self._send(state, paused, send) return changed + + def _relay_control(self, state, paused, send, *, control_socket=None, owner=None): + relay = state["relay"] + # Serialize request translation and notification fanout, not network I/O. + with relay["control_lock"]: + with state["lock"]: + if (not self._live(state) + or control_socket is not None and state["control_socket"] is not control_socket + or owner is not None and state["owner"] is not owner): + return False + if control_socket is None or state["key"][3] == 0: + state["last_requested_state"] = paused + upstream = relay.get("upstream") + if upstream is None: + relay["requested"] = paused + return True + with upstream["lock"]: + if not self._live(upstream): + return False + upstream["last_requested_state"] = paused + return self._send(upstream, paused, send) + # Only a notification on the actual upstream session confirms state. + with state["lock"]: + self._confirm(state, paused) + for child in relay["controls"].values(): + with child["lock"]: + if self._live(child): + self._confirm(child, paused) + self._send(child, paused, send) + return True + def release(self, state): """Retire only this owner, clear control intent and wake paused senders.""" with state["lock"]: @@ -1023,7 +1062,6 @@ def release(self, state): state["confirmed_state"] = False state["last_requested_state"] = False state["initial_notification"] = False - state["user_paused"] = state["backpressure"] = False self._condition.notify_all() return True @@ -1140,12 +1178,12 @@ def _receive_transfer_control(instance, sock, peer, command): instance._transfer_controls.receive(key, sock, paused) -def _bind_transfer_control(instance, fid, sock, owner, trans_type, direction): +def _bind_transfer_control(instance, fid, sock, owner, trans_type, direction, *, relay=None): if fid is None or sock is None: return None # public-key legs and standalone transfer sockets peer = _control_peer(instance, _socket_peer_endpoint(sock)) state = instance._transfer_controls.register( - _transfer_control_key(peer, fid, trans_type, direction), sock, owner + _transfer_control_key(peer, fid, trans_type, direction), sock, owner, relay=relay ) if state is None: raise RuntimeError("transfer control identity already owned") @@ -3334,7 +3372,7 @@ def _load_transfer_progress(self): def pause_trans(self, fid, peer, *, trans_type, direction): - """Register a pause decision (sender) or request (receiver) for one leg. + """Request an ordinary leg pause or a Source-arbitrated relay-wide pause. Args: fid (int): Nonnegative transfer id. @@ -3343,9 +3381,9 @@ def pause_trans(self, fid, peer, *, trans_type, direction): direction (int): Local data role: 0 sender, 1 receiver. Returns: - bool: Operation registered on a live leg; False for duplicates or a - missing leg. A missing sender leg retains a preset pause. - Registration is not peer confirmation; in-flight data still lands. + bool: Operation registered, not peer confirmation. Relay operations + are requests to Source; buffered bytes continue to all Targets. + A missing sender leg retains a preset pause and returns False. Raises: ValueError: Invalid fid/type/direction or missing peer. @@ -3353,7 +3391,7 @@ def pause_trans(self, fid, peer, *, trans_type, direction): return _set_transfer_control(self, fid, peer, trans_type, direction, True) def start_trans(self, fid, peer, *, trans_type, direction): - """Continue the selected leg on its existing socket; clear preset pauses. + """Continue the ordinary leg or whole relay on its existing data sockets. Arguments and registration result match ``pause_trans``. No seek, truncation or new handshake occurs; receivers continue reading throughout. @@ -7258,6 +7296,7 @@ def _forward_relay( return relay = { "cond": threading.Condition(), + "control_lock": threading.RLock(), "requested": None, "controls": {}, "route": route, "fid": fid, @@ -7332,7 +7371,7 @@ def own(control, transfer): target_control = target_handshakes[(target, tfid)]["key"][0] if not own(target_control, sock) or not own(forwarder_sock, sock): return - control = _bind_transfer_control(self, tfid, target_control, sock, 1, 0) + control = _bind_transfer_control(self, tfid, target_control, sock, 1, 0, relay=relay) relay["controls"][target] = control try: sock.connect((target[0], tport)) @@ -7385,9 +7424,12 @@ def own(control, transfer): if not own(forwarder_sock, up_client): return self._crypto_attach_transfer_in(up_client, forwarder_sock, up_stamp) - relay["upstream"] = _bind_transfer_control( - self, fid, forwarder_sock, up_client, 1, 1 - ) + with relay["control_lock"]: + relay["upstream"] = _bind_transfer_control( + self, fid, forwarder_sock, up_client, 1, 1, relay=relay + ) + if relay["requested"] is not None: + self._transfer_controls.local(relay["upstream"]["key"], relay.pop("requested")) self.send_message(up_client, self.server_start_file_transfer_sign) self._forward_pump( up_client, target_conns, forwarder_sock, fid, fname, relay, resume_offset @@ -7443,7 +7485,6 @@ def _forward_pump( "buffered": 0, "backpressured": False, "complete": False, "failed": False, "high_water": max_bytes, "peak": 0, "max_enqueue": 0, } - upstream = relay["upstream"] queues = {(target, tfid): queue.Queue() for tfid, target, _ in target_conns} END = object() result = {"ok": 0, "ack": None} @@ -7453,9 +7494,6 @@ def release_buffered(byte_count): state["buffered"] -= byte_count if state["backpressured"] and state["buffered"] <= low_water: state["backpressured"] = False - self._transfer_controls.local( - upstream["key"], False, backpressure=True, owner=upstream["owner"] - ) cond.notify_all() def enqueue(chunk): @@ -7472,9 +7510,6 @@ def enqueue(chunk): pending.put(chunk) if not state["backpressured"] and state["buffered"] > max_bytes: state["backpressured"] = True - self._transfer_controls.local( - upstream["key"], True, backpressure=True, owner=upstream["owner"] - ) def writer(tfid, target, sock): key = (target, tfid) @@ -7484,7 +7519,6 @@ def writer(tfid, target, sock): item = pending.get() if item is END: break - _wait_transfer_control(self, controls[target], sock) try: if not self.send_message(sock, item): return @@ -8967,7 +9001,7 @@ def _load_transfer_progress(self): def pause_trans(self, fid, peer=None, *, trans_type, direction): - """Register a pause decision/request for one ordinary or forwarded leg. + """Pause an ordinary leg or request Source-arbitrated relay-wide pause. Args: fid (int): Nonnegative transfer id. @@ -8976,9 +9010,9 @@ def pause_trans(self, fid, peer=None, *, trans_type, direction): direction (int): Local data role: 0 sender, 1 receiver. Returns: - bool: Operation registered on a live leg, not peer confirmation. - False for duplicates, wrong peers or missing legs; a missing - sender leg retains a preset pause. In-flight data still lands. + bool: Operation registered, not peer confirmation. Source decides + relay state; Target requests may repeat to preserve cross-peer + intent. A missing sender retains a preset pause and returns False. Raises: ValueError: Invalid fid, transfer type or direction. diff --git a/docs/plans/transfer-control-lifecycle-plan.md b/docs/plans/transfer-control-lifecycle-plan.md index 3110faa..2d588f6 100644 --- a/docs/plans/transfer-control-lifecycle-plan.md +++ b/docs/plans/transfer-control-lifecycle-plan.md @@ -1,6 +1,6 @@ # 传输控制生命周期、全局转发暂停与顺序恢复 — 更改计划 -状态:**用户已授权按最后拆分开始 C1;C1 实现及局部验收完成,等待人工审查;C2–C6 未开始**。保持原 upstream fid/child fid,不引入 leg_id,不修改 pause/start 和端口响应格式;本轮仅实施实际控制会话清理、旧 owner 收尾及旧 worker 固定 socket,不自动创建 git 提交、合并或推送。后续阶段仍逐项等待人工放行;本轮证据见[实施报告](transfer-control-lifecycle-report.md)。 +状态:**C1 已获阶段推进;C2 实现及局部验收完成,等待人工审查;C3–C6 未开始**。保持原 fid、pause/start 和端口响应格式。本轮实施 Source 仲裁的全局转发暂停、child 状态投影及 writer 排空;自动背压仅使用既有 reader 高/低水位门槛与 TCP 流控,不再混入用户 pause/start。实际证据见[实施报告](transfer-control-lifecycle-report.md),不自动提交、合并或推送。 需求依据:[需求卡](transfer-control-lifecycle-requirements.md)。历史实现依据:[上一轮计划](transfer-pause-start-direction-plan.md)及其报告;它们的历史验证结果不作为本轮验证结果。 @@ -137,7 +137,7 @@ Web 的 `client_backend.py` 已知通过 Client 的文件/文件夹转发入口 - Source 的本地操作与这些请求在一个串行入口决定状态;Server 校验上游通知后,用各 Target 自己的 child fid 投影状态,不自行成为第二决定者。 - Server 下游控制记录是 Source 决定的投影;其暂停字段不能再阻塞 writer。移除 relay writer 的独立用户暂停门槛,继续排空既有字节;Source 下一块前才等待。 - 用户 start 不要求所有参与方逐个解锁。保留 confirmed/last_requested 以免未确认 pause→start 丢失,不把它改成请求 ACK 计数器。 -- 自动背压请求与用户意图分开;高水位 reader 门槛仍独立,只有缓冲下降才能解除。记录实际峰值和一次扇出超调,不宣称 total RAM 的严格上限。 +- 自动背压与用户意图分开:保留 reader 高/低水位门槛,缓冲下降才能解除;通过 TCP 流控传递压力,不再发送无法区分意图的自动 pause/start,避免低水位 start 覆盖 Source 或 Target 的用户暂停。用户 start 不能打开 reader 门槛。记录实际峰值和一次扇出超调,不宣称 total RAM 的严格上限。 - 暂停不撤回最后一块,不阻止已完成文件的真实 ACK,也不把暂停计作传输失败。数据已全部发出时不凭暂停伪造完成;原有 ACK 成功条件不变,不另外设计新的全局超时策略。 ## 6. 强制重建与逐 Target 调度(问题八) @@ -254,4 +254,4 @@ flowchart TD - **规则沉淀**:真实会话资源取消、不同 offset 顺序内容恢复、末次 ACK 再失败/成功三类消费者可见回归成为检查项,不新增源码字符串断言,也不为暂缓的问题二增加新测试约束。 - **文档/报告**:最终报告逐 P01–P20 给结论,单列问题二暂缓;每个原子变更含意图、范围、数据流、局部命令、未覆盖项、风险;文档随变更完成,不留“以后补”。 -本轮用户已明确要求开始 C1,作为 C1 的实施授权;不再重复索取同一确认。C1 完成后提交局部证据与报告,等待人工审查,不因此自动进入 C2–C6。 +用户已明确要求开始 C2,作为本阶段实施授权;C1 已获阶段推进。C2 完成后提交局部证据与报告供人工审查,不自动进入 C3–C6,不自动提交、合并或推送。 diff --git a/docs/plans/transfer-control-lifecycle-report.md b/docs/plans/transfer-control-lifecycle-report.md index 7dfeaeb..531a3a0 100644 --- a/docs/plans/transfer-control-lifecycle-report.md +++ b/docs/plans/transfer-control-lifecycle-report.md @@ -2,7 +2,7 @@ ## C1:实际控制会话取消与旧 owner 收尾 -状态:**C1 实现及局部验收完成,等待人工审查**。V1 最终通过,独立真实 socket 场景通过;此前失败及修正记录保留在下文。C2–C6 未开始,未创建 git 提交、合并或推送。依据:[需求卡](transfer-control-lifecycle-requirements.md)、[计划 C1](transfer-control-lifecycle-plan.md#8-原子拆分固定次序逐项人工审查)。 +状态:**C1 实现及局部验收完成;用户已要求开始 C2,C1 获阶段推进**。下述记录是 C1 的局部证据;当前 C2 状态见后续章节,未创建 git 提交、合并或推送。依据:[需求卡](transfer-control-lifecycle-requirements.md)、[计划 C1](transfer-control-lifecycle-plan.md#8-原子拆分固定次序逐项人工审查)。 ### 意图、更改路径与解决的问题 @@ -46,6 +46,47 @@ PYTHONPATH="$PWD" .venv/bin/python /tmp/pyflow-transfer-lifecycle-smoke.py --cas - C1 对应 P01–P07、P16/P19/P20 的会话生命周期和回归保护。独立程序不穷举全部组合;V1 实际通过了 online resume 的各方向/加密/async/tracking off、文件/文件夹失败后恢复、实际落盘 offset、进度保存/重载、EOF/ACK、稳定转发 route/child、旧 socket 握手隔离及 localhost/wildcard 身份回归。不能把持久化重载用例说成已完成独立多进程重启矩阵,也不将零 offset 独立程序当作所有恢复路径的替代证据。 - 不改变稳定 upstream/child fid、pause/start 四 token、端口响应、`file_transfer_mode` 签名、进度/快照 schema、普通 busy 规则或真实 ACK 判成功规则。未改 CI、依赖、coverage 策略,未删用例、跳过路径或弱化断言。 - 问题二继续暂缓:同一控制 socket、同 fid 换腿时迟到 pause/start 的严格代次隔离未实现;未新增 leg_id、换新 fid、协议字段或自动重试。 -- C2 全局暂停、C3 route 定向重建/offset 查询/逐 Target 顺序恢复、C4 EOF 补确认、C5 自转发拒绝、C6 总体验收未实施,不能据 C1 结果宣称这些行为已完成。 +- C1 交付时未实施 C2 全局暂停、C3 route 定向重建/offset 查询/逐 Target 顺序恢复、C4 EOF 补确认、C5 自转发拒绝、C6 总体验收,不能据 C1 结果宣称这些行为已完成;C2 的后续结果另列。 - 未运行 native Windows、其他 Python 版本或跨进程并发进度写入验收;本轮未做抓包,不将加密真实传输等同于全协议安全审计。 -- 本轮会话生命周期契约回归作为规则沉淀;变更记录见 `docs/source/changes/transfer-fid-routes.md`。C1 现等待人工审查,不自动进入 C2。 +- C1 会话生命周期契约回归作为规则沉淀;变更记录见 `docs/source/changes/transfer-fid-routes.md`。本轮用户明确要求开始 C2,作为阶段推进授权。 + +## C2:Source 仲裁全局暂停、writer 排空与独立背压 + +状态:**C2 实现及局部验收完成,等待人工审查**。V2 本体通过,迁移的单个完成契约用例修正观察时序后通过;S3 独立真实多目标程序通过。C3–C6 未开始,不自动提交、合并或推送。 + +### 更改路径、问题与数据流 + +- `PyFlow/network_api/connect_tcp.py`:relay 控制状态注册时绑定运行时 route;实际会话/owner 校验后,Server 将本地或 Target 请求按 upstream fid 转交 Source,而不自行确认。Source 的既有串行 sender 决策入口决定最终状态;Server 再按各 child fid 投影通知,Target 不回送通知,避免回包循环。 +- relay 请求不按当前确认值静默去重:另一 Target 的相反请求可能仍在途;保留 confirmed/last_requested,覆盖未确认 pause→start。握手完成前的请求与预置暂停先登记,Source 就绪后再发送;不增加协议字段或持久化状态。 +- 删除 relay writer 的用户暂停等待;暂停只让 Source 下一块前等待,Server 已收正文继续排空。删除自动背压伪装成用户 pause/start 的发送,保留原 reader 高/低水位硬门槛与 TCP 流控;低水位不再意外解除 Source/Target 的用户暂停。 +- `test/unit/network_api/test_transfer_control.py`:验证 Source 决定前 Server 不确认、相反请求有序裁决、child 映射、通知不回包、旧 owner/错误 socket 拒绝及握手前反向意图。 +- `test/integration/network_api/test_tcp_transfer_control.py`:用真实 socket 固定在途块、writer 队列、迟到通知和压力时序;覆盖 Source/Server upstream/Server alias/两个 Target、异端 start、未确认反向请求、错误 peer/type/role、加密帧、目标退出及资源收尾。 +- `test/integration/network_api/test_tcp_transfer_resume.py`:原部分完成用例不再用已废弃的独立 Target pause 卡 writer;改为用事件延迟第二 Target 的真实最终 ACK,仍验证完整内容、完成集合、route/index 保留,以及最后真实 ACK 后 Source 成功。未弱化成功条件。 +- `docs/source/File_Transfer/File_Transfer.rst`、`Network_APIs/TCP_Server_APIs.rst`、`TCP_Client_APIs.rst`、`changes/transfer-fid-routes.md`:同步全 route 用户控制、重复登记语义、排空行为和背压边界。 + +数据流:参与者 API/控制帧 → 实际会话及当前 owner → Server upstream 请求队列 → Source 串行决定 → Server child 通知队列 → 各参与者确认;数据流只有 Source 等待用户暂停,Server writers 持续排空,reader 独立受本地压力门槛约束。 + +### 局部验证与真实运行证据 + +V2 本体实际结果:**225 passed、1 skipped**(Linux、Python 3.10.20);skip 是既有明文 fixture 下不适用的 rekey 用例,两个加密 rekey 分支通过,未新增 skip。首次将下述单个迁移用例一并运行,总结果为 225 passed、1 skipped、1 failed,458.43 秒、退出码 1;失败是用例在第二 Target 到 ACK 时过早读第一个 Target 的文件。把完整内容断言移到第一个 Target 的真实 ACK 更新 completed 集合后,原内容/完成集合/最终 ACK 断言全部保留;仅重跑该用例,**1 passed,2.74 秒,退出码 0**。生产代码不因该测试时序问题修改。以下列出实际命令,不将分次验证声称为一次全绿组合运行: + +```bash +.venv/bin/python -m pytest test/unit/network_api/test_transfer_control.py test/integration/network_api/test_tcp_transfer_control.py test/integration/network_api/test_tcp_transfer_resume.py::test_forward_route_is_removed_only_after_all_real_targets_complete -x -vv --tb=short +.venv/bin/python -m pytest test/integration/network_api/test_tcp_transfer_resume.py::test_forward_route_is_removed_only_after_all_real_targets_complete -q +PYTHONPATH="$PWD" .venv/bin/python /tmp/pyflow-transfer-lifecycle-smoke.py --case global-pause <参数> +``` + +S3 不调用 pytest 测试函数,不替换文件/网络/加密主路径;事件只固定真实执行顺序,分别运行 `--alias`、`--encrypted`、`--encrypted --async-server --untracked`,退出码均为 0。每组有两个 Target,逐个由 Source、Server upstream、Server child、Target A/B 发 pause,再由另一 Target start;所有活跃逻辑确认最终一致、data socket 身份不变。临时脚本已删除,运行时临时文件与密钥目录已清理。 + +| 参数 | upstream fid | 两个 child fid | 观察到的 worker / 最终存活 | +|---|---:|---|---| +| 明文、localhost 别名 | 7352661538 | 7098315376 / 11393282672 | 80 / 0 | +| 加密、thread | 9451137674 | 18717822684 / 23012789980 | 119 / 0 | +| 加密、async、wildcard、tracking off | 11093087600 | 21104272900 / 25399240196 | 118 / 0 | + +每组在暂停期间均向两个 Target 排空实际在途正文 1024 字节;Source 在下一块等待。压力 high-water=64、实际 peak=2094、单次 max_enqueue=2048,满足 peak≤high-water+max_enqueue;用户 start 后 reader 仍重入压力等待,读次数不变。排空解除压力后,用户暂停仍保持。最终两个文件完整一致、Source 实际最终 ACK=True、所属 route/index 清理。内容 SHA-256:`9a727e7d8b144a2f9ce213746ccc0fbcee65e58cd86c80b43607464789440ee6`。 + +### 风险、范围与规则沉淀 + +本阶段覆盖 P08–P11 及 P20 的对应控制矩阵;不改 fid、四 token、端口消息、公开方法签名、进度 schema、普通 busy 或真实 ACK 规则。自动压力不再投影为用户 paused;不宣称阈值约束全部进程 RAM,也不承诺撤回 socket 在途字节。问题二继续暂缓;C3 重建/顺序恢复、C4 EOF 补确认、C5 自转发和 C6 总体验收未实施。native Windows、其他 Python 版本、relay 中途 rekey 的独立场景未验证。测试保留普通控制/rekey、失败/收尾回归;未改 CI、依赖、coverage。全局确认、暂停排空、背压释放不清用户暂停成为永久契约检查。 + diff --git a/docs/plans/transfer-control-lifecycle-requirements.md b/docs/plans/transfer-control-lifecycle-requirements.md index 0f9624d..016949f 100644 --- a/docs/plans/transfer-control-lifecycle-requirements.md +++ b/docs/plans/transfer-control-lifecycle-requirements.md @@ -1,8 +1,8 @@ # 传输控制生命周期与转发恢复 — 需求卡 -状态:用户已选择暂缓问题二,并已明确授权按最后计划拆分开始 C1。C1 实现及局部验收完成,等待人工审查。保持原 upstream fid/child fid,不引入 leg_id,不修改 pause/start 或端口响应格式;当前只实施实际会话清理、旧 owner 收尾及旧 worker 固定 socket,其余行为留在后续阶段。实施与验证证据见[实施报告](transfer-control-lifecycle-report.md),不自动提交、合并或推送。 +状态:用户已选择暂缓问题二;C1 已获阶段推进,C2 实现及局部验收完成,等待人工审查。当前已实施 Source 仲裁的全局转发暂停、child 状态投影、writer 排空及独立的本地背压门槛;保持原 fid、pause/start 和端口响应格式。实际证据见[实施报告](transfer-control-lifecycle-report.md),不自动进入 C3–C6,不自动提交、合并或推送。 -计划编写阶段没有运行 pytest、构建或实现烟测;此前文档一致性检查不等于功能验收。当前 C1 实际执行的命令、运行证据和失败记录统一见实施报告;此前换新 fid 或 leg_id 方案的检查记录不作为本轮验证结果。 +计划编写阶段没有运行 pytest、构建或实现烟测;此前文档一致性检查不等于功能验收。C1/C2 实际执行的命令、运行证据和失败记录统一见实施报告;此前换新 fid 或 leg_id 方案的检查记录不作为本轮验证结果。 计划编写阶段的文档机械检查通过:3 份文档、6 个相对链接、21 个计划涉及的既有文件路径、14 个验收命令引用路径、20 条验收路径、6 个原子阶段及命令组、6 个拟定运行场景,错误数为 0。当时实施报告尚未创建;这份历史检查不代表功能验收通过,当前实现证据另见实施报告。 @@ -98,8 +98,8 @@ - 只清理所属 route 的内存和数据 socket,不关闭无关控制连接、其他 fid 或删除已落盘字节。 - 不把 socket 仍打开或 offset 等于 size 单独作为成功证据。 - pause/start 和端口响应格式、Python pause/start 签名及持久化模型不变;不新增 leg_id 或恢复换新 fid。全局暂停、转发强制恢复及 offset 查询仍改变原契约,不能声称全部向后兼容。 -- 风险等级:高(协议、并发、文件恢复完整性)。当前仅授权 C1 实施;后续阶段仍须逐项人工放行,不自动提交、合并或推送。 +- 风险等级:高(协议、并发、文件恢复完整性)。当前仅授权推进至 C2;后续阶段仍须逐项人工放行,不自动提交、合并或推送。 ## 下一阶段闸门 -行为选择保持不变:暂缓问题二,保持稳定 fid 和既有控制/端口格式。用户已授权开始 C1;C1 完成后交付代码路径、运行证据和局部报告供人工审查,未经后续放行不开始 C2–C6。 +行为选择保持不变:暂缓问题二,保持稳定 fid 和既有控制/端口格式。用户已授权开始 C2;本阶段完成后交付运行证据和局部报告供人工审查,未经后续放行不开始 C3–C6。 diff --git a/docs/source/File_Transfer/File_Transfer.rst b/docs/source/File_Transfer/File_Transfer.rst index 669b26f..881d44f 100644 --- a/docs/source/File_Transfer/File_Transfer.rst +++ b/docs/source/File_Transfer/File_Transfer.rst @@ -532,21 +532,13 @@ machinery: Because uploader, server and targets may have different bandwidths, data can pile up in the server's memory. ``TCP_Server_Base`` -takes a ``max_mem_buff`` parameter (in MiB, default 2048, -i.e. 2 GB) that bounds -the memory the forwarding machinery may hold in that -process. When the server's -buffered bytes exceed ``max_mem_buff`` it sends -``/pause_trans 1 1`` to the forwarding client: the server is the local -receiver of this relay leg, and the client stops reading the source file. -Once the writers drain the buffers below the low-water mark (half the limit), -the server releases its automatic pause request. This is combined with the -server user's upstream pause using OR: draining cannot cancel a user pause, -and a user start cannot cancel pressure. The reader independently waits at the -high-water gate, even if the source locally starts. Buffering can exceed the -threshold by one enqueue's fan-out bytes; it does not grow without bound. -Receiving clients continue in-flight writes; ordinary and relay legs share -the typed secure control path and retain the same data sockets. +takes a ``max_mem_buff`` parameter (in MiB, default 2048) for the pump's +accounted queued bytes. Above the high-water mark, its reader waits until +writers drain to the low-water mark (half the limit); TCP flow control carries +the pressure upstream. Automatic pressure does not send user pause/start lines, +so draining cannot cancel a user pause and user start cannot bypass the gate. +One enqueue can overshoot by its fan-out bytes. This is not a total process RAM +ceiling; socket, crypto and in-flight writer buffers are separate. .. _concurrency-and-threading: @@ -842,9 +834,11 @@ when the logical forwarded target differs. Relay downstream control uses the target's child fid. An upstream fid alias is accepted only when that control peer has one matching live writer; an exact -child match takes precedence. Each target pauses independently, although its -backlog can eventually apply shared upstream pressure. Runtime control records -without a live data owner do not reserve a route. +child match takes precedence. Source arbitrates user pause/start for the whole +route. Server and Target operations request its decision; Server projects each +notification using the corresponding child fid. Pausing stops Source before +its next block, while every Server writer drains bytes already received. +Runtime control records without a live data owner do not reserve a route. Both methods apply the local operation and notify the peer through the existing secure control connection. The wire commands have exactly four tokens: @@ -854,9 +848,9 @@ values as the API; the issuer's role is opposite the receiving endpoint's local role. There are no separate remote-control methods or one-argument wire forms. Ordinary and relay legs use this same control path. -The sender owns the confirmed pause state and stops before its next chunk. +The ordinary sender, or the relay Source, owns confirmed pause state. A receiver's local call records a request; its confirmed state changes only -when the sender's notification arrives. Secure control sends are asynchronous +when the authoritative notification arrives. Secure control sends are asynchronous and ordered per leg, so confirmation is eventual. A receiver continues any in-flight receive and disk write: pause does not promise an immediate freeze of the receiving file. Start releases the same open data socket without a new @@ -864,9 +858,11 @@ handshake, offset or seek. A registered sender state change or receiver request returns ``True``; this reports local registration, not peer acknowledgement. A sender's same-state -operation returns ``False``. A receiver ignores an operation only when its -target equals both confirmed and last-requested state; unconfirmed duplicates -may therefore return ``True``. Presetting an exact, not-yet-active sender pause +operation returns ``False``. Ordinary receivers ignore an operation only when +it equals both confirmed and last-requested state. Relay requests may repeat +even at the confirmed value: another participant's opposite request may still +be in flight. Any participant can request start; no per-Target pause lock must +be individually cleared. Presetting an exact, not-yet-active sender pause returns ``False`` while retaining it for registration. Pause state is never persisted. Reconnect clears old control state and closes sockets before replay. diff --git a/docs/source/Network_APIs/TCP_Client_APIs.rst b/docs/source/Network_APIs/TCP_Client_APIs.rst index cf84ad6..d87295d 100644 --- a/docs/source/Network_APIs/TCP_Client_APIs.rst +++ b/docs/source/Network_APIs/TCP_Client_APIs.rst @@ -865,12 +865,15 @@ address or concrete control endpoint, not the logical forwarded target. Control identity is canonicalized to ``((client.host, client.port), fid, trans_type, local_role)`` independently of the progress row's logical receiver. -The sender owns confirmed pause state. A receiver records its local request -and waits for an eventual sender notification; secure sends are asynchronous -and ordered per leg. In-flight receives and disk writes continue. Start uses +The ordinary sender, or the relay Source, owns confirmed pause state. Target +requests travel through Server to Source and affect the whole route; any +participant can request start. Notifications are asynchronous and ordered per +leg. Server-buffered bytes and Target disk writes continue while user-paused. +Start cannot bypass Server's pressure gate and uses the same data socket without a new handshake or seek. A registered sender change or receiver request returns ``True``, not a peer ACK. Known duplicates -return ``False``; an unconfirmed receiver request may be sent again. A preset +return ``False`` for ordinary legs; relay receiver requests may repeat because +another participant's opposite request can still be in flight. A preset sender pause returns ``False`` before registration. Pause is runtime-only. See :ref:`transfer-pause-and-reconnect` for details. The upload value's ``peer`` is the original receiver; ``resume_offset`` continues the interrupted file from diff --git a/docs/source/Network_APIs/TCP_Server_APIs.rst b/docs/source/Network_APIs/TCP_Server_APIs.rst index 6bb59b3..680e984 100644 --- a/docs/source/Network_APIs/TCP_Server_APIs.rst +++ b/docs/source/Network_APIs/TCP_Server_APIs.rst @@ -59,9 +59,10 @@ The parameters of the ``__init__`` method are as follows: user-supplied RSA keys. Both files must exist, parse as PEM, and pair with each other; an invalid pair is silently ignored and the default key lookup is used instead (``None`` keeps the default lookup). -- ``max_mem_buff``: The in-memory buffering ceiling of the forward pump, - given in MiB and stored as bytes (``self.max_mem_buff``); past it the - uploading peer is told to pause. The default is 2048. +- ``max_mem_buff``: The forward pump's queued-byte high-water mark, in MiB and + stored as bytes. The reader waits for low-water drain, applying TCP flow + control independently of user pause/start. One fan-out enqueue may overshoot; + it is not a total process RAM ceiling. The default is 2048. - ``recv_messages_chunk_len``: The number of bytes read per receive on the control connection, covering commands and messages. The default is 4096. - ``file_transfer_chunk_len``: The chunk size in bytes for streaming a file @@ -679,11 +680,12 @@ Built-in client commands include: ``start_trans(fid, peer, *, trans_type, direction)``. ``trans_type`` is ``0`` for ordinary transfers or ``1`` for relay legs; ``direction`` is the local data role (``0`` sender, ``1`` receiver). The wire role describes the - issuer. Both methods update local control and notify the peer; sender state - is authoritative and receiver confirmation is eventual. An in-flight receive - and write continues, and start uses the same data socket. A registered sender - change or receiver request returns ``True``, not a peer ACK. Known duplicates - return ``False``; an unconfirmed receiver request may be sent again. A preset + issuer. Ordinary senders decide their leg state; relay Source decides the + whole route. Server calls are requests, and Source notifications are projected + onto child fids. Buffered bytes keep draining to Targets during user pause. + Start uses the same sockets and cannot bypass the local pressure gate. + ``True`` means registration, not peer ACK; relay requests may repeat. + Known duplicates on ordinary legs return ``False``. A preset sender pause returns ``False`` before registration. ``peer`` is required. See :ref:`transfer-pause-and-reconnect` for control identity and cleanup. Forwarded requests carry a source-allocated ``fid=``. A new diff --git a/docs/source/changes/transfer-fid-routes.md b/docs/source/changes/transfer-fid-routes.md index 67d9755..3e51886 100644 --- a/docs/source/changes/transfer-fid-routes.md +++ b/docs/source/changes/transfer-fid-routes.md @@ -9,6 +9,19 @@ > Current behavior and evidence are in > `docs/plans/transfer-pause-start-direction-report.md`. +## Lifecycle revision C2: Source-arbitrated global relay pause + +- Source serializes all user decisions. Server translates validated requests + to upstream fid and projects Source notifications onto each live child fid. + Relay requests may repeat so an unseen opposite intent is not swallowed. +- Server writers no longer wait on per-Target user pauses; queued bytes drain + on the existing sockets. Source alone stops before its next body block. +- Backpressure uses the local reader high/low-water gate and TCP flow control, + not automatic user pause/start messages. Drain cannot cancel user pause. +- Stable FIDs, wire fields and real final ACKs remain unchanged. Issue 2 is + deferred; route reconstruction and EOF reconfirmation remain later stages. +- Evidence: `docs/plans/transfer-control-lifecycle-report.md`. + ## Lifecycle revision C1: retire actual control sessions - Session cancellation owns listeners, data sockets and negotiations by actual diff --git a/test/integration/network_api/test_tcp_transfer_control.py b/test/integration/network_api/test_tcp_transfer_control.py index 3d504d1..33ad697 100644 --- a/test/integration/network_api/test_tcp_transfer_control.py +++ b/test/integration/network_api/test_tcp_transfer_control.py @@ -474,21 +474,21 @@ def _relay(relay_clients, tmp_path, monkeypatch, *, pressure=False): tail = threading.Event() releases.append(tail) observed["tail"] = tail + observed["tail_waiting"], observed["pause_waiting"] = threading.Event(), threading.Event() waiting = threading.Event() real_wait, real_pump = connect_tcp._wait_transfer_control, server._forward_pump real_read = server._forward_recv_exact def hold(instance, state, sock): - if state is not None and state["key"][2:] == (1, 0): - index = 0 if instance is source else ( - 1 + addresses.index(state["key"][0]) if instance is server else None) - if index is not None: - entered[index].set() - assert gates[index].wait(timeout=30), "relay body gate was not released" - if index == 0 and pressure and observed.get("source_entered"): - assert tail.wait(timeout=30), "source tail gate was not released" - if index == 0: - observed["source_entered"] = True + if instance is source and state is not None and state["key"][2:] == (1, 0): + entered[0].set() + assert gates[0].wait(timeout=30), "source body gate was not released" + if observed.get("source_entered"): + observed["tail_waiting"].set() + assert tail.wait(timeout=30), "source tail gate was not released" + observed["source_entered"] = True + if state["confirmed_state"]: + observed["pause_waiting"].set() return real_wait(instance, state, sock) def pump(up, connections, control, fid, name, relay, offset=0): @@ -514,9 +514,14 @@ def read(sock, count): for owner in (server, source, *targets): real_send = owner.send_message - def send(sock, message, is_send_raw=False, send=real_send): + def send(sock, message, is_send_raw=False, send=real_send, instance=owner): if isinstance(message, str) and message.startswith(("/pause_trans ", "/start_trans ")): observed["controls"].append((message, is_send_raw)) + if instance is server and isinstance(message, bytes) and "relay" in observed: + for index, child in enumerate(observed["relay"]["controls"].values(), 1): + if sock is child["owner"]: + entered[index].set() + assert gates[index].wait(timeout=30), "target writer gate was not released" return send(sock, message, is_send_raw=is_send_raw) monkeypatch.setattr(owner, "send_message", send) @@ -570,44 +575,86 @@ def _relay_done(relay_clients, run, *, failed=False): assert not server._fid_routes and not server._fid_route_index -def test_relay_child_and_upstream_alias_control_only_the_selected_writer( - relay_clients, tmp_path, monkeypatch +@pytest.mark.parametrize("issuer", ["source", "server-upstream", "server-alias", "target-a", "target-b"]) +def test_relay_global_pause_drains_queued_bytes_and_any_target_can_start( + relay_clients, tmp_path, monkeypatch, issuer ): + writes = [_observe_target_writes(monkeypatch, tmp_path / name / "relay.bin", 1024) + for name in ("target_a", "target_b")] run = _relay(relay_clients, tmp_path, monkeypatch) server, source, targets, _ = relay_clients - relay, sender, gates, _, result, _, _, _ = run - first, second = [relay["controls"][target.client_socket.getsockname()] for target in targets] - receiver = targets[0]._transfer_controls._legs[ - ((source.host, source.port), first["key"][1], 1, 1)] - data_socket = first["owner"] - assert _control(targets[0], receiver, True) - _confirmed((first, receiver), True) - assert server.start_trans(relay["fid"], first["key"][0], trans_type=1, direction=0) - _confirmed((first, receiver), False) - assert server.pause_trans(relay["fid"], first["key"][0], trans_type=1, direction=0) - _confirmed((first, receiver), True) + relay, sender, gates, _, _, payload, observed, _ = run + children = list(relay["controls"].values()) + receivers = [target._transfer_controls._legs[ + ((source.host, source.port), child["key"][1], 1, 1)] + for target, child in zip(targets, children)] + states = [sender, relay["upstream"], *children, *receivers] + sockets = [state["owner"] for state in states] + gates[0].set() + assert observed["tail_waiting"].wait(10) # Exactly one real source block is in flight. + if issuer == "server-alias": + assert server.pause_trans(relay["fid"], children[0]["key"][0], trans_type=1, direction=0) + else: + owner, state = {"source": (source, sender), "server-upstream": (server, relay["upstream"]), + "target-a": (targets[0], receivers[0]), "target-b": (targets[1], receivers[1])}[issuer] + assert _control(owner, state, True) + _confirmed(states, True) for owner, command in ( - (source, f"/start_trans {first['key'][1]} 1 1"), - (targets[1], f"/start_trans {first['key'][1]} 1 1"), - (targets[0], f"/start_trans {first['key'][1]} 0 1"), - (targets[0], f"/start_trans {first['key'][1]} 1 0"), + (source, f"/start_trans {children[0]['key'][1]} 1 1"), + (targets[1], f"/start_trans {children[0]['key'][1]} 1 1"), + (targets[0], f"/start_trans {children[0]['key'][1]} 0 1"), + (targets[0], f"/start_trans {children[0]['key'][1]} 1 0"), ): - barrier = threading.Event() - marker = f"/relay_barrier_{id(barrier)}" - server.add_message_listener(lambda _peer, line, marker=marker, event=barrier: + processed = threading.Event() + marker = f"/relay_barrier_{id(processed)}" + server.add_message_listener(lambda peer, line, marker=marker, event=processed: event.set() if line == marker else None) assert owner.send_message(owner.client_socket, command) assert owner.send_message(owner.client_socket, marker) - assert barrier.wait(timeout=10) - assert first["confirmed_state"] and not second["confirmed_state"] - assert not sender["confirmed_state"] and not relay["upstream"]["confirmed_state"] - gates[0].set() + assert processed.wait(10) + assert all(state["confirmed_state"] for state in states) + gates[1].set() gates[2].set() - second_peer = targets[1].client_socket.getsockname() - assert wait_until(lambda: second_peer in relay["route"]["completed"], timeout=15) - assert (Path(targets[1].file_transfer_dir) / "relay.bin").read_bytes() == run[5] - assert result == {} and first["owner"] is data_socket and data_socket.fileno() >= 0 - assert _control(targets[0], receiver, False) + for written, received in writes: + assert received.wait(10) + assert written == payload[:1024] # Paused writers must still drain queued bytes. + observed["tail"].set() + assert observed["pause_waiting"].wait(10) + assert all(state["owner"] is sock and sock.fileno() >= 0 for state, sock in zip(states, sockets)) + assert _control(targets[1], receivers[1], False) + _confirmed(states, False) + _relay_done(relay_clients, run) + + +def test_relay_cross_target_start_and_unconfirmed_reverse_intent_reach_source( + relay_clients, tmp_path, monkeypatch +): + run = _relay(relay_clients, tmp_path, monkeypatch) + server, source, targets, releases = relay_clients + relay, sender = run[:2] + children = list(relay["controls"].values()) + receivers = [target._transfer_controls._legs[ + ((source.host, source.port), child["key"][1], 1, 1)] + for target, child in zip(targets, children)] + entered, release = threading.Event(), threading.Event() + releases.append(release) + real_send = source.send_message + + def delay(sock, message, is_send_raw=False): + if isinstance(message, str) and message.startswith("/pause_trans "): + entered.set() + assert release.wait(20) + return real_send(sock, message, is_send_raw=is_send_raw) + + monkeypatch.setattr(source, "send_message", delay) + assert _control(targets[0], receivers[0], True) + assert entered.wait(10) + assert not receivers[1]["confirmed_state"] + assert _control(targets[1], receivers[1], False) # Must not deduplicate an unseen opposite request. + assert _control(targets[0], receivers[0], False) + assert wait_until(lambda: not sender["confirmed_state"]) + release.set() + _confirmed([sender, relay["upstream"], *children, *receivers], False) _relay_done(relay_clients, run) @@ -622,14 +669,9 @@ def test_relay_pressure_preserves_user_intent_and_source_start_cannot_open_reade sockets = [state["owner"] for state in relay["controls"].values()] gates[0].set() assert waiting.wait(timeout=10) - _confirmed((sender, upstream), True) - assert buffer["backpressured"] and upstream["backpressure"] - assert _control(server, upstream, True) is False - assert upstream["user_paused"] - assert _control(source, sender, False) _confirmed((sender, upstream), False) - assert _control(server, upstream, False) - assert not upstream["user_paused"] and upstream["last_requested_state"] + assert buffer["backpressured"] + assert _control(server, upstream, True) _confirmed((sender, upstream), True) assert _control(source, sender, False) _confirmed((sender, upstream), False) @@ -641,14 +683,13 @@ def test_relay_pressure_preserves_user_intent_and_source_start_cannot_open_reade assert observed["reads"] == reads and buffer["backpressured"] assert _control(source, sender, True) _confirmed((sender, upstream), True) - assert _control(server, upstream, True) is False + assert _control(server, upstream, True) if close_target: targets[0].close() gates[1].set() gates[2].set() assert wait_until(lambda: not buffer["backpressured"], timeout=10) - assert upstream["user_paused"] and not upstream["backpressure"] - assert upstream["last_requested_state"] and sender["confirmed_state"] + assert sender["confirmed_state"] and upstream["confirmed_state"] assert buffer["peak"] <= buffer["high_water"] + buffer["max_enqueue"] assert buffer["peak"] > buffer["high_water"] assert all(state["owner"] is sock for state, sock in zip(relay["controls"].values(), sockets)) @@ -907,6 +948,7 @@ def hold(instance, state, sock): return real_wait(instance, state, sock) monkeypatch.setattr(connect_tcp, "_wait_transfer_control", hold) + observed["tail"].set() for gate in gates: gate.set() assert partial.wait(timeout=15) diff --git a/test/integration/network_api/test_tcp_transfer_resume.py b/test/integration/network_api/test_tcp_transfer_resume.py index 1945b74..effac22 100644 --- a/test/integration/network_api/test_tcp_transfer_resume.py +++ b/test/integration/network_api/test_tcp_transfer_resume.py @@ -1996,11 +1996,11 @@ def observe_resume(client_socket, peer, requested_fid, offset, origin, target): def test_forward_route_is_removed_only_after_all_real_targets_complete(tmp_path, monkeypatch): - """A completed sibling leaves the route live until the held writer finishes.""" + """A completed sibling leaves the route live until the other real ACK arrives.""" workers = _track_socket_workers(monkeypatch) server = _start_server(tmp_path) clients = [] - held = {} + held, release = threading.Event(), threading.Event() try: source = _start_client(tmp_path, server, name="source") clients.append(source) @@ -2016,51 +2016,41 @@ def test_forward_route_is_removed_only_after_all_real_targets_complete(tmp_path, targets.append(target.client_socket.getsockname()) outputs.append(recv_dir / "complete_forward.bin") assert wait_until(lambda: all(target in server.clients for target in targets)) - real_forward_item_to = server.forward_item_to - - def hold_second_writer(target, kind, rel_dir, fname, originator_addr, tfid, - destination_path=None): - if target == targets[1]: - held["fid"] = tfid - held["paused"] = server.pause_trans(tfid, target, trans_type=1, direction=0) - return real_forward_item_to( - target, kind, rel_dir, fname, originator_addr, tfid, destination_path - ) + real_send = clients[2].send_message + + def hold_second_ack(sock, message, is_send_raw=False): + if message == clients[2].server_received_file_data_sign: + held.set() + assert release.wait(20), "second Target ACK was not released" + return real_send(sock, message, is_send_raw=is_send_raw) - monkeypatch.setattr(server, "forward_item_to", hold_second_writer) + monkeypatch.setattr(clients[2], "send_message", hold_second_ack) src = tmp_path / "complete_forward.bin" payload = os.urandom(96 * 1024) src.write_bytes(payload) + result = {} sender = threading.Thread( - target=source._forward_one, - args=("file", "", src.name, str(src), targets), daemon=True, + target=lambda: result.update(ack=source._forward_one( + "file", "", src.name, str(src), targets)), daemon=True, ) sender.start() - assert wait_until( - lambda: outputs[0].exists() and outputs[0].stat().st_size == len(payload), - timeout=20, - ), "the unpaused target did not finish" - assert outputs[0].read_bytes() == payload - assert wait_until(lambda: not clients[1].file_recv_progress, timeout=10) - assert held["paused"] is False # preset before the relay writer registers - assert not outputs[1].exists() or outputs[1].stat().st_size == 0 + assert held.wait(15), "the second Target never reached its final ACK" + assert sender.is_alive() and result == {} assert len(server._fid_routes) == 1 fid, route = next(iter(server._fid_routes.items())) assert set(route["targets"]) == set(targets) assert wait_until(lambda: route["completed"] == {targets[0]}, timeout=10) + assert outputs[0].read_bytes() == outputs[1].read_bytes() == payload + assert wait_until(lambda: not clients[1].file_recv_progress, timeout=10) expected_index = {(targets[1], route["targets"][targets[1]]): fid} assert server._fid_route_index == expected_index assert server._lookup_fid_route(targets[0], route["targets"][targets[0]]) is None assert server._lookup_fid_route(targets[1], route["targets"][targets[1]])[1] is route - assert server.start_trans(held["fid"], targets[1], trans_type=1, direction=0) is True - assert wait_until( - lambda: outputs[1].exists() and outputs[1].stat().st_size == len(payload), - timeout=20, - ), "the released target did not finish" - assert outputs[1].read_bytes() == payload + release.set() sender.join(timeout=20) assert not sender.is_alive(), "the real source transfer did not finish" + assert result == {"ack": True} assert wait_until(lambda: not server._forward_relays, timeout=10) assert wait_until(lambda: not clients[2].file_recv_progress, timeout=10) assert server._fid_routes == {} @@ -2069,8 +2059,7 @@ def hold_second_writer(target, kind, rel_dir, fname, originator_addr, tfid, for target, tfid in route["targets"].items(): assert server._lookup_fid_route(target, tfid) is None finally: - if held: - server.start_trans(held["fid"], targets[1], trans_type=1, direction=0) + release.set() _close_socket_workers(server, clients, workers) diff --git a/test/unit/network_api/test_transfer_control.py b/test/unit/network_api/test_transfer_control.py index a3755ea..9e9c901 100644 --- a/test/unit/network_api/test_transfer_control.py +++ b/test/unit/network_api/test_transfer_control.py @@ -119,12 +119,12 @@ def test_control_endpoint_matches_only_this_connection_and_configuration( class _ControlPair: - def __init__(self): + def __init__(self, trans_type=0): self.paused = [{}, {}] self.registries = [ _TransferControlRegistry(flags, threading.Condition()) for flags in self.paused ] - self.keys = [_transfer_control_key(PEER, 42, 0, role) for role in (0, 1)] + self.keys = [_transfer_control_key(PEER, 42, trans_type, role) for role in (0, 1)] self.sockets = [object(), object()] self.states = [registry.register(key, sock, object()) for registry, key, sock in zip( self.registries, self.keys, self.sockets @@ -443,36 +443,54 @@ def test_relay_control_prefers_exact_child_and_requires_one_live_same_peer_alias assert states[0]["confirmed_state"] is False -def test_receiver_pressure_and_user_intents_survive_notifications_and_stale_owner(): - pair = _ControlPair() - registry, key, state = pair.registries[1], pair.keys[1], pair.states[1] - pressure = lambda paused: registry.local( - key, paused, pair.send(1), backpressure=True, owner=state["owner"]) - assert pressure(True) - pair.drain() - pair.local(1, True) - pressure(False) - pair.drain() - assert state["user_paused"] and not state["backpressure"] - assert state["confirmed_state"] and state["last_requested_state"] - assert pair.local(0, False) - pair.drain() - assert state["user_paused"] and not state["backpressure"] - assert state["last_requested_state"] and not state["confirmed_state"] - pressure(True) - pair.local(1, False) - pair.drain() - assert not state["user_paused"] and state["backpressure"] - assert state["confirmed_state"] and state["last_requested_state"] - assert pair.local(0, False) - pair.drain() - assert not state["confirmed_state"] and state["backpressure"] - assert state["last_requested_state"] and not state["user_paused"] - pressure(False) - pair.drain() - assert not state["last_requested_state"] and pair.paused == [{}, {}] - assert registry.release(state) - replacement = registry.register(key, pair.sockets[1], object()) - assert not pressure(True) - assert not replacement["backpressure"] and not replacement["user_paused"] - assert not replacement["last_requested_state"] and not any(pair.pending) +def test_relay_requests_wait_for_source_and_fan_out_without_echoing_notifications(): + pair = _ControlPair(trans_type=1) + registry, upstream = pair.registries[1], pair.states[1] + relay = {"control_lock": threading.RLock(), "upstream": upstream, "controls": {}} + upstream["relay"] = relay + children = [registry.register((PEER, fid, 1, 0), object(), object(), relay=relay) + for fid in (100, 102)] + relay["controls"].update(enumerate(children)) + frames = [] + + def send(sock, line): + if sock is upstream["control_socket"]: + return pair.send(1)(sock, line) + frames.append((sock, line)) + return True + + assert not registry.receive(children[0]["key"], object(), True, send) + for child, paused in zip(children, (True, False)): + assert registry.receive(child["key"], child["control_socket"], paused, send) + assert not any(state["confirmed_state"] for state in [upstream, *children]) + assert not frames # A Target request is not a Server decision. + pair.deliver(0) + assert pair.states[0]["confirmed_state"] + pair.deliver(0) + assert not pair.states[0]["confirmed_state"] + for paused in (True, False): + line = pair.pending[1].popleft() + assert _parse_transfer_control_command(line)[0] is paused + assert registry.receive(upstream["key"], upstream["control_socket"], paused, send) + assert all(state["confirmed_state"] is paused for state in [upstream, *children]) + assert [line for _, line in frames] == [ + "/pause_trans 100 1 0", "/pause_trans 102 1 0", + "/start_trans 100 1 0", "/start_trans 102 1 0", + ] + assert not any(pair.pending) + assert not registry.receive(upstream["key"], object(), True, send) + old_owner = children[0]["owner"] + assert registry.release(children[0]) + replacement = registry.register(children[0]["key"], object(), object(), relay=relay) + assert not registry.local(replacement["key"], True, send, owner=old_owner) + + +def test_relay_start_before_upstream_exists_overrides_a_preset_pause(): + registry = _TransferControlRegistry({}, threading.Condition()) + key = (PEER, 100, 1, 0) + assert not registry.local(key, True) + relay = {"control_lock": threading.RLock(), "controls": {}} + child = registry.register(key, object(), object(), relay=relay) + assert relay["requested"] is True and not child["confirmed_state"] + assert registry.local(key, False) + assert relay["requested"] is False and not child["confirmed_state"] From 1e4b622102df3fdbfd904572f423d8b8f6832d2a Mon Sep 17 00:00:00 2001 From: F18-Ray Date: Wed, 18 Nov 2026 22:38:58 +0800 Subject: [PATCH 12/19] fix(tcp)!: restore numeric resume requests and parallelize target recover --- PyFlow/network_api/connect_tcp.py | 541 ++++++++++++------ docs/plans/transfer-control-lifecycle-plan.md | 142 +++-- .../transfer-control-lifecycle-report.md | 169 ++++++ ...transfer-control-lifecycle-requirements.md | 61 +- docs/source/File_Transfer/File_Transfer.rst | 65 ++- docs/source/Network_APIs/TCP_Client_APIs.rst | 31 +- docs/source/Network_APIs/TCP_Server_APIs.rst | 29 +- docs/source/changes/transfer-fid-routes.md | 50 +- .../network_api/test_tcp_transfer_control.py | 217 ++++++- .../network_api/test_tcp_transfer_resume.py | 388 ++++++++++--- test/unit/network_api/test_fid_routes.py | 326 +++++++---- test/unit/network_api/test_resume_matching.py | 25 + 12 files changed, 1490 insertions(+), 554 deletions(-) diff --git a/PyFlow/network_api/connect_tcp.py b/PyFlow/network_api/connect_tcp.py index 6afaca4..09d1ccd 100644 --- a/PyFlow/network_api/connect_tcp.py +++ b/PyFlow/network_api/connect_tcp.py @@ -624,7 +624,9 @@ def regular_file(path): raise RuntimeError("stop the instance and finish active transfers before deletion") if hasattr(instance, "_forward_relays"): with instance._forward_relays_lock: - if instance._forward_relays: + if instance._forward_relays or any( + state["active"] for state in instance._relay_recoveries.values() + ): raise RuntimeError("finish active relays before deletion") with ExitStack() as locks: for store in stores: @@ -668,11 +670,7 @@ def _resume_offset_for(entry): def parse_resume_command(command): - """Parse ``/resume_trans `` or return None. - - Addresses are shell-quoted two-item tuple literals. Return the integer - fid/offset and two endpoint tuples; routing validates their actual owners. - """ + """Parse the numeric-offset resume command, or return None.""" try: parts = shlex.split(command) if len(parts) != 5 or parts[0].lower() != RESUME_LINE: @@ -747,12 +745,14 @@ def _claim_receive(instance, fid, control_socket, owner=None): return None if owner is not None and record["control_socket"] is control_socket: record["owner"] = owner + instance._transfer_progress_changed.notify_all() return record if record["deadline"] > time.monotonic(): return None record = {"control_socket": control_socket, "owner": owner, "deadline": time.monotonic() + RESUME_ACCEPT_TIMEOUT} instance._receive_transfers[fid] = record + instance._transfer_progress_changed.notify_all() return record @@ -790,6 +790,17 @@ def _retire_transfer_session(instance, control_socket): instance._transfer_handshakes.cancel_socket(control_socket) instance._transfer_controls.discard_socket(control_socket) _discard_receive_requests(instance, control_socket) + if hasattr(instance, "_relay_recoveries"): + with instance._transfer_progress_changed, instance._forward_relays_lock: + for fid, state in instance._relay_recoveries.items(): + for target, (sock, _) in list(state["pending"].items()): + if sock is control_socket: + del state["pending"][target] + for target, reservation in state["active"].items(): + record = reservation["record"] + if reservation["target_socket"] is control_socket and record["owner"] is None: + _release_receive(instance, (target, fid), record) + instance._transfer_progress_changed.notify_all() with instance._transfer_progress_lock: sends = [(key, state) for key, state in instance._resume_sends.items() if state.get("control_socket") is control_socket] @@ -811,24 +822,36 @@ def _wait_transfer_session(instance, retired): for fid, record in receives)) -def _start_resume_send(instance, key, target, send, *, control_socket): - """Atomically reserve one recovery worker; busy objects are never queued.""" +def _start_resume_send(instance, key, target, send, *, control_socket, forward=False): + """Reserve one ordinary owner or an independent forwarded Target owner.""" + owner_key = (target, key[1]) if forward else key with instance._transfer_progress_lock: if instance._progress_discarded or key not in instance.file_upload_progress: return False if (control_socket.fileno() < 0 or instance._transfer_handshakes.closed(control_socket) - or _transfer_busy(instance, key, control_socket)): + or not forward and _transfer_busy(instance, key, control_socket)): return False - state = instance._resume_sends.get(key) + state = instance._resume_sends.get(owner_key) if state is None: state = {"lock": threading.RLock(), "users": 0, "targets": set(), "control_socket": control_socket} - instance._resume_sends[key] = state + instance._resume_sends[owner_key] = state + if target in state["targets"] or state["control_socket"] is not control_socket: + return False state["targets"].add(target) def run(): try: - with _sending_transfer(instance, key, control_socket=control_socket): + with _sending_transfer(instance, owner_key, control_socket=control_socket): + if forward: + with instance._transfer_progress_changed: + instance._transfer_progress_changed.wait_for(lambda: + (key not in instance._active_transfer_sockets + and key not in instance._active_transfer_fids + and key not in instance._resume_sends) + or instance._transfer_handshakes.closed(control_socket)) + if instance._transfer_handshakes.closed(control_socket): + return entry = instance.file_upload_progress.get(key) if entry is not None: send(entry) @@ -836,7 +859,7 @@ def run(): with instance._transfer_progress_changed: state["targets"].discard(target) if not state["users"] and not state["targets"]: - instance._resume_sends.pop(key, None) + instance._resume_sends.pop(owner_key, None) instance._transfer_progress_changed.notify_all() threading.Thread(target=run, daemon=True).start() @@ -901,15 +924,19 @@ def __init__(self, paused, condition, instance=None): self._legs = {} self._instance = instance - def register(self, key, control_socket, owner, *, relay=None): + def register(self, key, control_socket, owner, *, relay=None, shared=False): """Bind an unclaimed identity, adopting only its sender's preset pause.""" if control_socket is None or owner is None: raise ValueError("a control socket and leg owner are required") with self._condition: state = self._legs.get(key) if state is not None: - return state if (state["control_socket"] is control_socket - and state["owner"] is owner) else None + if state["control_socket"] is not control_socket: + return None + if owner not in state["owners"] and not (shared and state["shared"]): + return None + state["owners"].add(owner) + return state paused = key[3] == 0 and self._paused.get(key, False) if relay is not None and key[3] == 0: if paused: @@ -918,6 +945,7 @@ def register(self, key, control_socket, owner, *, relay=None): self._paused.pop(key, None) state = { "key": key, "control_socket": control_socket, "owner": owner, + "owners": {owner}, "shared": shared, "lock": threading.RLock(), "confirmed_state": paused, "last_requested_state": False, "initial_notification": paused, "ready": self._instance is None or key[3] == 1, @@ -970,7 +998,7 @@ def local(self, key, paused, send=None, *, owner=None): """Decide a sender state or submit a receiver intent, deduplicating both.""" with self._condition: state = self._legs.get(key) - if owner is not None and (state is None or state["owner"] is not owner): + if owner is not None and (state is None or owner not in state["owners"]): return False if state is None: if key[3] == 0: @@ -985,7 +1013,7 @@ def local(self, key, paused, send=None, *, owner=None): with state["lock"]: if not self._live(state): return False - if owner is not None and state["owner"] is not owner: + if owner is not None and owner not in state["owners"]: return False if key[3] == 0: if state["confirmed_state"] == paused: @@ -1025,17 +1053,15 @@ def _relay_control(self, state, paused, send, *, control_socket=None, owner=None with state["lock"]: if (not self._live(state) or control_socket is not None and state["control_socket"] is not control_socket - or owner is not None and state["owner"] is not owner): + or owner is not None and owner not in state["owners"]): return False if control_socket is None or state["key"][3] == 0: state["last_requested_state"] = paused upstream = relay.get("upstream") - if upstream is None: + if upstream is None or not self._live(upstream): relay["requested"] = paused return True with upstream["lock"]: - if not self._live(upstream): - return False upstream["last_requested_state"] = paused return self._send(upstream, paused, send) # Only a notification on the actual upstream session confirms state. @@ -1048,13 +1074,21 @@ def _relay_control(self, state, paused, send, *, control_socket=None, owner=None self._send(child, paused, send) return True - def release(self, state): - """Retire only this owner, clear control intent and wake paused senders.""" + def release(self, state, *, owner=None): + """Release one data owner; the last one retires shared task control.""" with state["lock"]: with self._condition: key = state["key"] if self._legs.get(key) is not state: return False + if owner is not None: + if owner not in state["owners"]: + return False + state["owners"].remove(owner) + if state["owners"]: + state["owner"] = next(iter(state["owners"])) + return True + state["owners"].clear() del self._legs[key] self._paused.pop(key, None) if "outbox" in state: @@ -1121,9 +1155,9 @@ def upload_pauses(self): def release_owner(self, owner): with self._condition: - states = [state for state in self._legs.values() if state["owner"] is owner] + states = [state for state in self._legs.values() if owner in state["owners"]] for state in states: - self.release(state) + self.release(state, owner=owner) def _control_peer(instance, peer): @@ -1178,12 +1212,13 @@ def _receive_transfer_control(instance, sock, peer, command): instance._transfer_controls.receive(key, sock, paused) -def _bind_transfer_control(instance, fid, sock, owner, trans_type, direction, *, relay=None): +def _bind_transfer_control(instance, fid, sock, owner, trans_type, direction, *, relay=None, shared=False): if fid is None or sock is None: return None # public-key legs and standalone transfer sockets peer = _control_peer(instance, _socket_peer_endpoint(sock)) state = instance._transfer_controls.register( - _transfer_control_key(peer, fid, trans_type, direction), sock, owner, relay=relay + _transfer_control_key(peer, fid, trans_type, direction), sock, owner, + relay=relay, shared=shared, ) if state is None: raise RuntimeError("transfer control identity already owned") @@ -1782,6 +1817,21 @@ def __init__(self): self._unresolved = set() self._closed = weakref.WeakSet() self._resources = {} + self._negotiating = set() + + @contextmanager + def serialized(self, control_socket, fid): + """Serialize only request/port pairs, not their data or ACK lifetimes.""" + key = (control_socket, fid) + with self._changed: + self._changed.wait_for(lambda: key not in self._negotiating) + self._negotiating.add(key) + try: + yield + finally: + with self._changed: + self._negotiating.remove(key) + self._changed.notify_all() def register(self, control_socket, fid): key = (control_socket, fid) @@ -2830,9 +2880,7 @@ def __init__( # One route per local upstream fid; downstream keys point to that fid. self._fid_routes = {} self._fid_route_index = {} # (receiver, downstream fid) -> upstream fid - # Resume requests that arrived before the originator reconnected: - # originator -> {(upstream fid, target): latest disk offset}. - self._pending_originator_resumes = {} + self._relay_recoveries = {} # route requests and independent Target owners # Transfer ids for the legs this instance sends (see `_FidAllocator`). # Inbound ids use local integer keys; outbound ids use (receiver, fid). # Equal numbers cannot share progress, pause state or sockets. @@ -3181,6 +3229,7 @@ def _drop_fid_route(self, fid, route): if self._fid_routes.get(fid) is not route: return False del self._fid_routes[fid] + self._relay_recoveries.pop(fid, None) for target, child in route["targets"].items(): key = (target, child) if self._fid_route_index.get(key) == fid: @@ -5540,11 +5589,7 @@ def handle_command( elif shlex.split(command.lower())[0] == RESUME_LINE: parsed = parse_resume_command(command) if parsed is not None: - threading.Thread( - target=self._resume_request, - args=(client_socket, client_address, *parsed), - daemon=True, - ).start() + self._resume_request(client_socket, client_address, *parsed) return None elif ( self.is_enable_encrypto @@ -6865,12 +6910,7 @@ def _request_resumes(self, peer, *, control_socket=None): return started def resume_trans(self, peer_addr, fid, offset): - """Queue direct or forwarded recovery from the existing upload row. - - The unified request has validated origin, target and route before this - method. Direct recovery sends ``/file``; forwarded replay keeps the - stable upstream fid and uses ``/forward_item`` with ``fid=`` and - ``resume=``. + """Reserve ordinary recovery from this receiver's existing upload row. Args: peer_addr (tuple | None): Receiver ``(ip, port)`` for this upload. @@ -6883,6 +6923,14 @@ def resume_trans(self, peer_addr, fid, offset): if peer_addr is None: return False peer_addr = tuple(peer_addr) + with self.client_lock: + info = self.clients.get(peer_addr) + if info is None: + return False + return self._resume_on_socket(peer_addr, fid, offset, info["socket"]) + + def _resume_on_socket(self, peer_addr, fid, offset, control_socket): + """Use the validated receiver session, not a replacement at the same peer.""" key = (peer_addr, fid) entry = self.file_upload_progress.get(key) if entry is None or entry[4] is None or tuple(entry[4]) != peer_addr: @@ -6890,11 +6938,11 @@ def resume_trans(self, peer_addr, fid, offset): return False with self.client_lock: info = self.clients.get(peer_addr) - if info is None: + if info is None or info["socket"] is not control_socket: return False def send(entry): - with _transfer_handshake(self, info["socket"], fid) as handshake: + with _transfer_handshake(self, control_socket, fid) as handshake: command = f"/file {shlex.quote(os.path.basename(str(entry[3])))} {fid}" if not _send_transfer_request(self, handshake, command): return @@ -6907,13 +6955,13 @@ def send(entry): try: self.file_transfer_mode( entry[3], peer_addr[0], port, client_port, - control_socket=info["socket"], crypto=stamp, fid=fid, + control_socket=control_socket, crypto=stamp, fid=fid, peer=peer_addr, resume_offset=offset, ) finally: self.pfree(client_port) - return _start_resume_send(self, key, peer_addr, send, control_socket=info["socket"]) + return _start_resume_send(self, key, peer_addr, send, control_socket=control_socket) def _is_control_local_endpoint(self, endpoint, sock): @@ -6951,98 +6999,123 @@ def _control_local_endpoint(self, sock): return _socket_local_endpoint(sock) or (self.host, self.port) def _resume_request(self, client_socket, client_address, fid, offset, origin, target): - """Validate requester, origin, target and scoped route before recovery. - - ``client_socket`` is the requester's control socket (or its peer address - when a caller drives the method directly); it names the local side the - origin must match. - """ + """Validate the actual requester before registering background recovery.""" client_address, origin, target = tuple(client_address), tuple(origin), tuple(target) - if target != client_address: + with self.client_lock: + info = self.clients.get(client_address) + if (target != client_address or type(offset) is not int or offset < 0 + or info is None or info["socket"] is not client_socket): return False if self._is_control_local_endpoint(origin, client_socket): - return self.resume_trans(client_address, fid, offset) + return self._resume_on_socket(client_address, fid, offset, client_socket) found = self._lookup_fid_route(client_address, fid) if found is not None: upstream, route = found if route["originator"] == origin: - return self._queue_resume_to_originator(upstream, route, target, offset) + return self._queue_resume_to_originator( + upstream, route, target, offset, control_socket=client_socket) return False self._log(f"resume: transfer {format_fid(fid)} has no matching origin/target route") return False - def _relay_resume_busy(self, fid): - """Called under progress/route locks; include setup and finalizing owners.""" - record = self._receive_transfers.get(fid) - return (_transfer_busy(self, fid, None) - or any(relay["fid"] == fid for relay in self._forward_relays.values()) - or record is not None and ( - record["owner"] is not None or record["deadline"] > time.monotonic() - )) - - def _queue_resume_to_originator(self, originator_fid, route, target_addr, offset): - """Keep the latest target offset until its originator accepts the request.""" - originator, target = route["originator"], tuple(target_addr) + def _queue_resume_to_originator(self, fid, route, target_addr, offset, *, control_socket): + """Retain one receiver's numeric request without interrupting its route.""" + target = tuple(target_addr) + with self.client_lock: + info = self.clients.get(target) with self._transfer_progress_lock, self._forward_relays_lock: - if (self._fid_routes.get(originator_fid) is not route + if (self._progress_discarded or self._fid_routes.get(fid) is not route or target not in route["targets"] or target in route["completed"] - or self._relay_resume_busy(originator_fid)): + or type(offset) is not int or offset < 0 or info is None + or info["socket"] is not control_socket): return False - self._pending_originator_resumes.setdefault(originator, {})[ - (originator_fid, target) - ] = offset - return self._flush_pending_originator_resumes(originator) > 0 - - def _flush_pending_originator_resumes(self, client_address, *, control_socket=None): - """Send queued requests through the secure control path without early removal.""" - client_address = tuple(client_address) - with self._forward_relays_lock: - pending = list(self._pending_originator_resumes.get(client_address, {}).items()) + state = self._relay_recoveries.get(fid) + if state is None: + state = {"route": route, "pending": {}, "active": {}, + "control": {"control_lock": threading.RLock(), + "requested": None, "controls": {}}} + self._relay_recoveries[fid] = state + active = state["active"].get(target) + if (active is not None and active["target_socket"] is control_socket + or state["pending"].get(target) == (control_socket, offset)): + return False + state["pending"][target] = (control_socket, offset) + self._flush_pending_originator_resumes(route["originator"]) + return True + + def _flush_pending_originator_resumes(self, peer, *, control_socket=None): + """Admit every ready Target after the original route's last owner exits.""" + peer = tuple(peer) with self.client_lock: - info = self.clients.get(client_address) - if (not pending or info is None - or control_socket is not None and info["socket"] is not control_socket - or not self._wait_control_secure(info["socket"])): + online = dict(self.clients) + if control_socket is not None and online.get(peer, {}).get("socket") is not control_socket: return 0 - sent = 0 - for (fid, target), offset in pending: - with self._transfer_progress_lock, self._forward_relays_lock: - waiting = self._pending_originator_resumes.get(client_address, {}) - if waiting.get((fid, target)) != offset: - continue - route = self._fid_routes.get(fid) - valid = (route is not None and route["originator"] == client_address - and target in route["targets"] and target not in route["completed"]) - if not valid: - waiting.pop((fid, target), None) - if not waiting: - self._pending_originator_resumes.pop(client_address, None) - continue - if self._relay_resume_busy(fid): - continue - record = _claim_receive(self, fid, info["socket"]) - if record is None: + workers = [] + with self._transfer_progress_lock, self._forward_relays_lock: + if not self.running or self._progress_discarded: + return 0 + for fid, state in self._relay_recoveries.items(): + route = state["route"] + if (self._fid_routes.get(fid) is not route + or peer != route["originator"] and peer not in route["targets"] + or fid in self._receive_transfers): continue - sent_request = False - try: - sent_request = self.send_message( - info["socket"], format_resume_line(fid, offset, client_address, target) - ) - except OSError: - pass - finally: - if not sent_request: - _release_receive(self, fid, record) - if not sent_request: - continue - sent += 1 - with self._forward_relays_lock: - waiting = self._pending_originator_resumes.get(client_address, {}) - if waiting.get((fid, target)) == offset: - waiting.pop((fid, target), None) - if not waiting: - self._pending_originator_resumes.pop(client_address, None) - return sent + source = online.get(route["originator"]) + for target, (sock, offset) in list(state["pending"].items()): + if (target in route["completed"] + or online.get(target, {}).get("socket") is not sock + or sock.fileno() < 0 or self._transfer_handshakes.closed(sock)): + del state["pending"][target] + continue + if (target in state["active"] or source is None + or self._transfer_handshakes.closed(source["socket"])): + continue + record = _claim_receive(self, (target, fid), source["socket"]) + if record is None: + continue + reservation = {"record": record, "source_socket": source["socket"], + "target_socket": sock, "offset": offset} + state["active"][target] = reservation + del state["pending"][target] + workers.append((fid, state, target, reservation)) + for args in workers: + threading.Thread(target=self._run_relay_recovery, args=args, daemon=True).start() + return len(workers) + + def _run_relay_recovery(self, fid, state, target, reservation): + """One Target's port setup/cleanup cannot wait for a sibling's body.""" + source, target_socket = reservation["source_socket"], reservation["target_socket"] + record, key = reservation["record"], (target, fid) + try: + if not self._wait_control_secure(source) or not self._wait_control_secure(target_socket): + return + with self.client_lock: + if (self.clients.get(state["route"]["originator"], {}).get("socket") is not source + or self.clients.get(target, {}).get("socket") is not target_socket): + return + if not self.send_message(source, format_resume_line( + fid, reservation["offset"], state["route"]["originator"], target + )): + return + with self._transfer_progress_changed: + self._transfer_progress_changed.wait_for(lambda: + self._receive_transfers.get(key) is not record or record["owner"] is not None + or not self.running or self._transfer_handshakes.closed(source) + or self._transfer_handshakes.closed(target_socket), + timeout=RESUME_ACCEPT_TIMEOUT) + except (OSError, RuntimeError) as exc: + self._log(f"forward: recovery {fid} to {target} interrupted: {exc}") + finally: + with self._transfer_progress_changed: + if record["owner"] is not None: + self._transfer_progress_changed.wait_for(lambda: + self._receive_transfers.get(key) is not record) + _release_receive(self, key, record) + with self._transfer_progress_lock, self._forward_relays_lock: + if state["active"].get(target) is reservation: + del state["active"][target] + self._transfer_progress_changed.notify_all() + self._flush_pending_originator_resumes(state["route"]["originator"]) def _resume_after_connect(self, client_address, control_socket, retired): """Drain only captured old owners, then resume through the admitted socket.""" @@ -7273,12 +7346,18 @@ def _forward_relay( if fid is None: self._log("forward: rejected relay without an upstream FID") return + recovery = reservation = None if resume_requested: with self._forward_relays_lock: route = self._fid_routes.get(fid) + recovery = self._relay_recoveries.get(fid) + reservation = recovery["active"].get(targets[0]) if recovery and len(targets) == 1 else None if (route is None or route["originator"] != tuple(originator_addr) - or not targets or any(target not in route["targets"] for target in targets) - or any(target in route["completed"] for target in targets)): + or len(targets) != 1 or targets[0] not in route["targets"] + or targets[0] in route["completed"] + or reservation is not None and ( + reservation["offset"] != resume_offset + or reservation["source_socket"] is not forwarder_sock)): self._forward_notify_error( forwarder_sock, "no pending relay target for this sender", fid ) @@ -7294,34 +7373,53 @@ def _forward_relay( forwarder_sock, "relay fid is already in use", fid ) return + manual_recovery = resume_requested and reservation is None relay = { "cond": threading.Condition(), "control_lock": threading.RLock(), "requested": None, + "done": threading.Event(), + "sockets": [], "handshakes": {}, "controls": {}, "route": route, "fid": fid, } relay_keys = [(target, tfid) for target, tfid in zip(targets, tfids)] + receive_key = (targets[0], fid) if resume_requested else fid receive_record = None with self._transfer_progress_lock, self._forward_relays_lock: if (self._fid_routes.get(fid) is route - and not any(relay["fid"] == fid for relay in self._forward_relays.values()) + and (resume_requested and fid not in self._receive_transfers + or not resume_requested and not any( + candidate["fid"] == fid for candidate in self._forward_relays.values())) + and (reservation is None + or self._receive_transfers.get(receive_key) is reservation["record"]) and not any(key in self._forward_relays for key in relay_keys)): - receive_record = _claim_receive(self, fid, forwarder_sock, relay) + receive_record = _claim_receive(self, receive_key, forwarder_sock, relay) if receive_record is not None: for key in relay_keys: self._forward_relays[key] = relay + if resume_requested and recovery is None: + recovery = {"route": route, "pending": {}, "active": {}, + "control": {"control_lock": threading.RLock(), + "requested": None, "controls": {}}} + self._relay_recoveries[fid] = recovery + if manual_recovery: + reservation = {"record": receive_record, "source_socket": forwarder_sock, + "target_socket": self.clients.get(targets[0], {}).get("socket"), + "offset": resume_offset} + recovery["active"][targets[0]] = reservation if receive_record is None: self._forward_notify_error(forwarder_sock, "relay source is already active", fid) return + control_group = recovery["control"] if resume_requested else relay if os.path.exists(self.file_trans_progress_file): self._persist_transfer_progress() target_conns = [] up_sock = up_client = None sport = None allocated_sport = None - target_handshakes = {} - owned_sockets = [] + target_handshakes = relay["handshakes"] + owned_sockets = relay["sockets"] terminal_sent = False def fail(message): @@ -7331,24 +7429,35 @@ def fail(message): self._forward_notify_error(forwarder_sock, message, fid) def own(control, transfer): - if not self._transfer_handshakes.track_socket(control, transfer): - return False - owned_sockets.append((control, transfer)) - return True + with relay["cond"]: + if not self._transfer_handshakes.track_socket(control, transfer): + return False + owned_sockets.append((control, transfer)) + if (reservation is not None and control is forwarder_sock + and reservation["target_socket"] is not control): + target_control = reservation["target_socket"] + if not self._transfer_handshakes.track_socket(target_control, transfer): + return False + owned_sockets.append((target_control, transfer)) + return True try: for target, tfid in zip(targets, tfids): - target_control = self.clients.get(target, {}).get("socket") - handshake = (self._transfer_handshakes.register(target_control, tfid) - if target_control is not None else None) + with relay["cond"]: + target_control = (reservation["target_socket"] if reservation is not None + else self.clients.get(target, {}).get("socket")) + handshake = (self._transfer_handshakes.register(target_control, tfid) + if target_control is not None else None) + if handshake is not None: + target_handshakes[(target, tfid)] = handshake if handshake is None: fail(f"target {target} has no available listener negotiation") return - target_handshakes[(target, tfid)] = handshake for target, tfid in zip(targets, tfids): - if not self.forward_item_to( - target, kind, rel_dir, fname, originator_addr, tfid, destination_path, - ): + with relay["cond"]: + sent = self.forward_item_to( + target, kind, rel_dir, fname, originator_addr, tfid, destination_path) + if not sent: fail(f"could not request a listener from {target}") return results = self._transfer_handshakes.wait_many( @@ -7371,8 +7480,10 @@ def own(control, transfer): target_control = target_handshakes[(target, tfid)]["key"][0] if not own(target_control, sock) or not own(forwarder_sock, sock): return - control = _bind_transfer_control(self, tfid, target_control, sock, 1, 0, relay=relay) - relay["controls"][target] = control + with control_group["control_lock"]: + control = _bind_transfer_control(self, tfid, target_control, sock, 1, 0, relay=control_group) + relay["controls"][target] = control + control_group["controls"][target] = control try: sock.connect((target[0], tport)) except Exception as e: @@ -7395,6 +7506,13 @@ def own(control, transfer): target_conns.append((tfid, target, sock)) # The target's start sign proves its receiving leg is registered. _announce_transfer_control(self, control) + with control_group["control_lock"]: + upstream = control_group.get("upstream") + if upstream is not None and self._transfer_controls._live(upstream): + with control["lock"]: + paused = upstream["confirmed_state"] + self._transfer_controls._confirm(control, paused) + self._transfer_controls._send(control, paused, None) if not target_conns: fail("no target accepted the transfer") return @@ -7424,12 +7542,14 @@ def own(control, transfer): if not own(forwarder_sock, up_client): return self._crypto_attach_transfer_in(up_client, forwarder_sock, up_stamp) - with relay["control_lock"]: + with control_group["control_lock"]: relay["upstream"] = _bind_transfer_control( - self, fid, forwarder_sock, up_client, 1, 1, relay=relay + self, fid, forwarder_sock, up_client, 1, 1, + relay=control_group, shared=resume_requested, ) - if relay["requested"] is not None: - self._transfer_controls.local(relay["upstream"]["key"], relay.pop("requested")) + control_group["upstream"] = relay["upstream"] + if control_group.get("requested") is not None: + self._transfer_controls.local(relay["upstream"]["key"], control_group.pop("requested")) self.send_message(up_client, self.server_start_file_transfer_sign) self._forward_pump( up_client, target_conns, forwarder_sock, fid, fname, relay, resume_offset @@ -7452,9 +7572,24 @@ def own(control, transfer): for key in relay_keys: if self._forward_relays.get(key) is relay: del self._forward_relays[key] - _release_receive(self, fid, receive_record) for control, transfer in owned_sockets: self._transfer_handshakes.release_socket(control, transfer) + with relay["cond"]: + owned_sockets.clear() + target_handshakes.clear() + relay["done"].set() + if resume_requested: + with control_group["control_lock"]: + for target, control in relay["controls"].items(): + if control_group["controls"].get(target) is control: + del control_group["controls"][target] + _release_receive(self, receive_key, receive_record) + if manual_recovery: + with self._transfer_progress_lock, self._forward_relays_lock: + if recovery["active"].get(targets[0]) is reservation: + del recovery["active"][targets[0]] + self._transfer_progress_changed.notify_all() + self._flush_pending_originator_resumes(tuple(originator_addr)) def _forward_pump( self, up_sock, target_conns, forwarder_sock, fid, fname, relay, resume_offset=0 @@ -10467,10 +10602,10 @@ def handle_server_command(self, command, control_socket=None): ) elif shlex.split(command.lower())[0] == RESUME_LINE: parsed = parse_resume_command(command) - if parsed is not None and self.client_socket is not None: + if parsed is not None and control_socket is not None: fid, offset, origin, target = parsed - if origin == self.client_socket.getsockname(): - self.resume_trans(target, fid, offset) + if origin == control_socket.getsockname(): + self._resume_on_socket(target, fid, offset, control_socket, forward_request=True) elif shlex.split(command.lower())[0] == "/forward_error": try: parts = shlex.split(command) @@ -10867,7 +11002,7 @@ def file_transfer_client_recv_client_start(self, message, file_folder_abspath): self._log_exc() self._log("invalid command, please use '/file '") - def file_transfer_mode( # noqa: PLR0911 - peer-close and timeout exits are distinct outcomes + def file_transfer_mode( self, filename, server_address, @@ -10897,8 +11032,19 @@ def file_transfer_mode( # noqa: PLR0911 - peer-close and timeout exits are dist Returns: bool: True only after the receiver's final data ACK; otherwise False. """ + return self._send_file( + filename, server_address, server_port, client_port, control_socket, + crypto, fid, peer, resume_offset, trans_type, + ) + + def _send_file( # noqa: PLR0911 - peer-close and timeout exits are distinct outcomes + self, filename, server_address, server_port, client_port, + control_socket=None, crypto=None, fid=None, peer=None, resume_offset=0, + trans_type=0, *, forward_stream=None, + ): + """Send a file with either ordinary progress or independent relay progress.""" self._log(f"start to send file: {filename}") - transfer_key = ((self.host, self.port), fid) if fid is not None else None + transfer_key = ((peer if forward_stream is not None else (self.host, self.port)), fid) if fid is not None else None client_file_socket = None reset_time = 0 control = None @@ -10918,7 +11064,8 @@ def close_socket(): if not self._transfer_handshakes.track_socket(control_socket, client_file_socket): return False control = _bind_transfer_control( - self, fid, control_socket, client_file_socket, trans_type, 0 + self, fid, control_socket, client_file_socket, trans_type, 0, + shared=forward_stream is not None, ) client_file_socket.bind((self.client_host, client_port)) client_file_socket.connect((server_address, server_port)) @@ -11033,14 +11180,18 @@ def receive_file_transfer_messages(): self.send_message(client_file_socket, file_size.to_bytes(8, "big")) if resume_offset < 0 or resume_offset > file_size: resume_offset = 0 # not this file's offset any more: send it whole - progress = self._file_progress_start( - self.file_upload_progress, transfer_key, file_size, filename, - peer=peer, initial=resume_offset, - ) - if progress is None: - progress = self.file_upload_progress.get(transfer_key) - if progress is not None: - progress[0] = resume_offset + if forward_stream is not None: + progress = [resume_offset, file_size, None, str(filename), peer] + forward_stream["progress"] = progress + else: + progress = self._file_progress_start( + self.file_upload_progress, transfer_key, file_size, filename, + peer=peer, initial=resume_offset, + ) + if progress is None: + progress = self.file_upload_progress.get(transfer_key) + if progress is not None: + progress[0] = resume_offset with open(filename, "rb") as f: if resume_offset: f.seek(resume_offset) @@ -11115,15 +11266,17 @@ def receive_file_transfer_messages(): self._log(f"send error: {e}") return False finally: - self._file_progress_finish( - self.file_upload_progress, transfer_key, progress, - keep=( - not file_sent - and not source_missing - and progress is not None - and progress[4] is not None - ), - ) + if forward_stream is None: + self._file_progress_finish( + self.file_upload_progress, transfer_key, progress, + keep=(not file_sent and not source_missing and progress is not None + and progress[4] is not None), + ) + elif file_sent: + self._file_progress_finish( + self.file_upload_progress, forward_stream["task_key"], + forward_stream["task_entry"], + ) self._release_transfer_socket(transfer_key, client_file_socket) self._transfer_handshakes.release_socket(control_socket, client_file_socket) @@ -11172,8 +11325,8 @@ def resume_trans(self, peer_addr, fid, offset): Server-bound uploads answer with ``/file``; other final targets replay through the server with the stable upstream fid. The retained upload path is sufficient because the receiver owns its full destination path. - Recovery skips any live, paused, negotiating or finalizing source owner, - including a relay upstream shared by several final targets. + Live, negotiating and finalizing owners remain busy for public calls. + Only a Server-directed relay replay waits for the old sender's cleanup. Args: peer_addr (tuple | None): Final receiver; None selects the server. @@ -11183,9 +11336,12 @@ def resume_trans(self, peer_addr, fid, offset): Returns: bool: True for a newly reserved recovery worker; False when busy. """ + return self._resume_on_socket(peer_addr, fid, offset, self.client_socket) + + def _resume_on_socket(self, peer_addr, fid, offset, control_socket, *, forward_request=False): + """Pin a recovery to its admitted Server session, never a replacement.""" server_peer = (self.host, self.port) - control_socket = self.client_socket - if not self.running or control_socket is None: + if not self.running or control_socket is None or self.client_socket is not control_socket: return False # The server names itself with the concrete endpoint of this control # connection; the configured address is accepted too so a peer using @@ -11226,8 +11382,13 @@ def send(entry): finally: self.pfree(client_port) + if not is_direct and not forward_request: + with self._transfer_progress_lock: + if (_transfer_busy(self, key, control_socket) + or any(owner_key[1] == fid for owner_key in self._resume_sends)): + return False return _start_resume_send( - self, key, target, send, control_socket=control_socket + self, key, target, send, control_socket=control_socket, forward=not is_direct, ) @@ -11400,9 +11561,10 @@ def _forward_one( if control_socket is None: control_socket = self.client_socket is_resume = upstream_fid is not None + targets = [(_peer_from_json(target) or (target[0], int(target[1]))) for target in addrs] if is_resume: key = (server_peer, upstream_fid) - if key not in self.file_upload_progress: + if len(targets) != 1 or key not in self.file_upload_progress: return False else: upstream_fid = self._fid_alloc.alloc(receiver=server_peer) @@ -11413,8 +11575,12 @@ def _forward_one( (_peer_from_json(addrs[0]) or tuple(addrs[0])) if addrs else None, ] self._persist_transfer_progress() - with _sending_transfer(self, key, control_socket=control_socket): - with _transfer_handshake(self, control_socket, upstream_fid) as handshake: + owner_key = (targets[0], upstream_fid) if is_resume else key + with _sending_transfer(self, owner_key, control_socket=control_socket) as stream: + if is_resume: + stream["task_key"], stream["task_entry"] = key, self.file_upload_progress[key] + with self._transfer_handshakes.serialized(control_socket, upstream_fid), \ + _transfer_handshake(self, control_socket, upstream_fid) as handshake: msg = f"/forward_item {kind} fid={int(upstream_fid)}" if is_resume: msg += f" resume={int(resume_offset)}" @@ -11438,23 +11604,18 @@ def _forward_one( self._log(f"forward: server changed upstream fid for {fname}") return False _, fid, sport, stamp = result - targets = [ - (_peer_from_json(target) or (target[0], int(target[1]))) - for target in addrs - ] client_port = self.palloc() try: + if is_resume: + return self._send_file( + abspath, self.host, sport, client_port, + control_socket=control_socket, crypto=stamp, fid=fid, peer=targets[0], + resume_offset=resume_offset, trans_type=1, forward_stream=stream, + ) return self.file_transfer_mode( - abspath, - self.host, - sport, - client_port, - control_socket=control_socket, - crypto=stamp, - fid=fid, - peer=targets[0] if targets else None, - resume_offset=resume_offset, - trans_type=1, + abspath, self.host, sport, client_port, + control_socket=control_socket, crypto=stamp, fid=fid, + peer=targets[0] if targets else None, resume_offset=resume_offset, trans_type=1, ) finally: self.pfree(client_port) diff --git a/docs/plans/transfer-control-lifecycle-plan.md b/docs/plans/transfer-control-lifecycle-plan.md index 2d588f6..7d12654 100644 --- a/docs/plans/transfer-control-lifecycle-plan.md +++ b/docs/plans/transfer-control-lifecycle-plan.md @@ -1,17 +1,17 @@ -# 传输控制生命周期、全局转发暂停与顺序恢复 — 更改计划 +# 传输控制生命周期、全局转发暂停与独立并行恢复 — 更改计划 -状态:**C1 已获阶段推进;C2 实现及局部验收完成,等待人工审查;C3–C6 未开始**。保持原 fid、pause/start 和端口响应格式。本轮实施 Source 仲裁的全局转发暂停、child 状态投影及 writer 排空;自动背压仅使用既有 reader 高/低水位门槛与 TCP 流控,不再混入用户 pause/start。实际证据见[实施报告](transfer-control-lifecycle-report.md),不自动提交、合并或推送。 +状态:**用户批准的数值 offset、原 route 旧 owner 全收尾、每 Target 独立并行恢复已实现;本轮局部验证和真实传输证据已记录,待人工审查**。旧 C3a/C3b 的查询/强制 teardown/单活跃轮次仅作撤回历史。C1/C2 保留;C4–C6 未实现,不自动推进,不自动提交、合并或推送。 需求依据:[需求卡](transfer-control-lifecycle-requirements.md)。历史实现依据:[上一轮计划](transfer-pause-start-direction-plan.md)及其报告;它们的历史验证结果不作为本轮验证结果。 ## 1. 本轮范围与替代关系 -### 1.1 保留的四组修改 +### 1.1 本轮范围与保留/后续边界 1. **问题四/五**:按实际控制 socket 管理旧会话资源,删除按 peer 扫描进度表关闭当前 socket 的重复机制;旧 worker 不借用新控制连接。 -2. **问题六**:Client 统一转发入口拒绝自身完整控制端点;同 host 不同端口仍可互传。 +2. **问题六**:自身完整控制端点拒绝为后续 C5 目标,同 host 不同端口仍可互传;C5 未实现,不混入本轮 C3。 3. **问题七**:Source 是 route 的唯一用户控制仲裁者;任意端 pause/start 控制整个转发任务。暂停源端新增块,已有字节继续排空,数据 socket 不断开。 -4. **问题八**:8A 验证恢复请求后结束旧 relay 的上下游数据腿,等待收尾并清掉旧内存,按各 Target 实际 offset 顺序重放;8B 保留所有 Target 已完成但上游 ACK 明确失败的 EOF 再确认。两者保持原 fid,分别实施和验收。 +4. **问题八**:本轮 8A 撤回 offset 查询、强制 teardown 及 FIFO 单轮调度;Receiver 提交实际数值 offset,Server 等原 route 全部旧 owner(含 finally)自然收尾,再按 Target 独立建流,正文并行。8B 全 Target 已完成后的上游 EOF 再确认仍为未实现 C4,不顺带实施。 ### 1.2 明确排除 @@ -27,7 +27,7 @@ - **保留**恢复时稳定 upstream fid/child fid、原接收路径、pause/start 及端口响应格式;不实现 leg_id、old/new fid 关联、恢复身份 rekey 或持久化迁移记录。 - **废弃**“Target 只暂停自己的 writer”;替换为 Source 仲裁全 route 停止新增源数据。 -- **替换转发恢复**的 live upstream busy 静默跳过:有效恢复请求可触发该 route 的定向 teardown;重复请求只登记,不反复打断新重放。 +- **替换转发恢复**的 live upstream busy 静默跳过及旧 C3 强制重建:合法请求仅入队,等原 route 全部旧 owner(含 finally)自然收尾;随后每 Target 独立 Source→Server→Target 恢复,不将一个恢复流的正文/ACK 变成另一个 Target 的 barrier。 - **普通传输**的 live/paused/negotiating/finalizing busy 静默跳过仍保留;暂停用 start,不因此扩大成任意普通传输强制重启。 - 用户 API 的 bool 仍表示登记/预留,不表示远端确认、恢复完成或文件成功。 @@ -39,22 +39,22 @@ | 修改单测 | `test/unit/network_api/test_resume_matching.py` | 保留普通恢复 busy、稳定 fid/原路径/总长/offset 及收尾;覆盖恢复入口与会话生命周期交叉 | | 修改单测 | `test/unit/network_api/test_transfer_handshakes.py` | 实际会话取消、listener/data owner 退役及旧 owner 排空;不增加代次字段 | | 修改单测 | `test/unit/network_api/test_transfer_control.py` | Source 仲裁、全局状态转发、交叉意图和背压独立;不新增跨腿旧控制隔离保证 | -| 修改单测 | `test/unit/network_api/test_fid_routes.py` | 稳定 route/child、已完成集合、顺序调度、伪造请求不 teardown | +| 修改单测 | `test/unit/network_api/test_fid_routes.py` | 稳定 route/child、原 owner 全收尾、pending/active 每 Target 隔离、真实 completed、错误实际会话无副作用 | | 修改单测 | `test/unit/network_api/test_transfer_progress_query.py`、`test_delete_config.py` | 保持既有查询/快照 schema,关闭/删除与恢复占用 | | 修改单测 | `test/unit/network_api/test_TCP_client.py`、`test_TCP_server.py` | 控制会话替换及资源生命周期必要回归 | -| 修改集成测试 | `test/integration/network_api/test_tcp_transfer_control.py` | 普通双端控制回归、全局暂停、旧清扫/旧 worker、强制恢复及自目标拒绝 | -| 修改集成测试 | `test/integration/network_api/test_tcp_transfer_resume.py` | 普通/转发同 fid 新数据腿、不同 offset 顺序恢复、部分完成、EOF/最终 ACK、重连和持久化 | -| 迁移受影响断言 | `test/integration/network_api/test_tcp_file_transfer.py`、`test_crypto_tcp.py`、`test_tcp_async_server.py`、`test/integration/test_forward_extension.py`、`test_forward_msg_attribution.py` | 只更新全局暂停、恢复和自目标语义触及的真实消费者;不做端口或 pause/start parser/helper 的协议迁移 | -| 修改使用文档 | `docs/source/File_Transfer/File_Transfer.rst`、`docs/source/Network_APIs/TCP_Server_APIs.rst`、`TCP_Client_APIs.rst` | API 结果、稳定 fid、全局暂停、offset 查询、恢复及暂缓边界 | +| 修改集成测试 | `test/integration/network_api/test_tcp_transfer_control.py` | 普通双端控制回归、全局暂停、旧会话清理及多恢复 owner 的共享控制 | +| 修改集成测试 | `test/integration/network_api/test_tcp_transfer_resume.py` | 普通/转发同 fid、新旧 owner 边界、不同 offset 并行恢复、晚来目标、单流失败、真实 ACK、重连与持久化 | +| 迁移受影响断言 | `test/integration/network_api/test_tcp_file_transfer.py`、`test_crypto_tcp.py`、`test_tcp_async_server.py`、`test/integration/test_forward_extension.py`、`test_forward_msg_attribution.py` | 仅涉及现有恢复/全局暂停的真实消费者;C5 自目标路径仍为未实现后续阶段,不做端口或控制协议迁移 | +| 修改使用文档 | `docs/source/File_Transfer/File_Transfer.rst`、`docs/source/Network_APIs/TCP_Server_APIs.rst`、`TCP_Client_APIs.rst` | 数值 offset、原 route 收尾、独立流、全局暂停及暂缓边界 | | 修改变更记录 | `docs/source/changes/transfer-fid-routes.md` | 保留稳定恢复 fid,取代独立 writer 暂停及 busy 恢复等旧契约;明确问题二暂缓 | -| 计划载体 | 本文件、`transfer-control-lifecycle-requirements.md`、旧计划的后续链接 | 本轮决策和审批状态,不改写历史通过记录 | -| 实施后新增报告 | `docs/plans/transfer-control-lifecycle-report.md` | 逐原子变更报告、路径证据、失败及未覆盖项;现在不创建完成报告 | +| 计划载体 | 本文件、`transfer-control-lifecycle-requirements.md` | 已批准的新方案与旧 C3 撤回边界 | +| 更新既有报告 | `docs/plans/transfer-control-lifecycle-report.md` | 保留旧证据;本轮独立列路径、失败、风险和待验证项,不编造通过 | Web 的 `client_backend.py` 已知通过 Client 的文件/文件夹转发入口调用,不直接构造恢复消息;计划不修改该文件,统一入口必须覆盖 Web 调用。若实施发现额外真实消费者须修改,先更新文件清单,不扩大成 UI 功能。 当前 LSP 只有 Ruff,不支持 definition/references;本轮按现有声明和文本调用点定位。实施前重新检查导航能力;支持 references 时,改公开符号前必须查询引用,不声称 Ruff 已完成引用分析。 -## 3. 接口与线上契约(拟定,随本计划确认) +## 3. 接口与线上契约(用户已批准) ### 3.1 保持不变的部分 @@ -64,25 +64,17 @@ Web 的 `client_backend.py` 已知通过 Client 的文件/文件夹转发入口 - fid 分配和原进度/route/child 键不迁移,不新增恢复版本、old/new 映射或迁移日志。 - 公钥和独立传输不因此获得用户 pause/start 能力;端口解析结果、握手 port 结果、file_transfer_mode 签名及测试 helper 的端口返回值不因问题二而改变。 -### 3.2 恢复请求与各目标 offset 收集 - -数值恢复请求保持五 token: +### 3.2 仅数值恢复请求 ```text /resume_trans ``` -为在强制关闭共享 relay 后取得各 Target 的**最终落盘**位置,扩展同一命令的查询形式,不增加新命令名: - -```text -/resume_trans ? -``` - -- `?` 仅为 Server 向该 route Target 发出的 offset 查询。Client 校验当前 Server 控制会话、target 为自身、download fid 与 origin 匹配,随后在后台等待该旧接收 owner 收尾/文件关闭,再用既有数值形式回复。 -- Server 不用发送字节计数猜 Target 落盘进度;首次请求也可能早于其他在途字节落盘,teardown 后以查询回复为准。 -- 查询只登记一次,回包不重复 teardown;离线/无保留接收记录的目标不虚构 offset,不阻塞可服务目标。未完成项保留,等待合法后续恢复/重连。 -- 不增加定时重试循环,不让控制接收线程阻塞等待自己需要分派的消息。 -- `parse_resume_command` 数值分支返回值不变;查询分支 tuple 的 offset 用 `None` 表示,`format_resume_line(..., offset=None, ...)` 生成 `?`。这是输入/输出值域扩展,全部消费者区分请求和查询。 +- 仅保留五 token 数值形式,offset 是非负整数;删除 `?`/`None` 查询分支、查询线程/状态和所有查询消费者,不新增替代 wire。 +- Receiver 等自己的旧接收 owner(含 finally)退出、文件关闭,读取原完整路径的实际大小;按现有显式/重连入口提交,不因任意失败启动自动恢复循环。 +- Server 校验实际请求 socket、origin、target、child fid、未完成 route,保存实际 Target socket 与原值 offset;向 Source 转交时只把 child fid 映射为稳定 upstream fid。 +- Source 离线保留 pending;Target 断线丢弃该旧 socket 的 pending,重连后 Receiver 以新实际 offset 重发。不得把旧请求迁到替换后的 Target socket。 +- parser/formatter 只处理数值 offset;稳定 fid/child、原路径、文件头、端口/控制帧及持久化 schema 不变。 ### 3.3 保持控制/端口格式,明确暂缓边界 @@ -111,10 +103,10 @@ Web 的 `client_backend.py` 已知通过 Client 的文件/文件夹转发入口 ### 4.2 同 fid 恢复的收尾与失败规则 -1. 原拥有者真正退出并释放 active socket/发送占用/接收占用后,才能在同 fid 上建立新数据腿;检查与恢复预留在同一并发边界。 +1. 原 route 全部旧资源/发送/接收 owner(含 finally)真正退出后,才启动独立恢复流。每 Target 仍独占自身恢复 owner;不同 Target 共享稳定 upstream fid,但不共享数据流、瞬时进度或资源。 2. Receiver 从关闭后的原文件实际大小取 offset,按原 fid/peer/basename/total 校验继续使用原完整路径;不建立同名文件桥接或删除旧字节。 3. 握手中断时按原规则释放所属控制状态,保留允许恢复的文件/进度;不得绕过 pending/unresolved 握手或建立第二个数据 owner。 -4. 新 owner 默认运行,不继承退役 owner 的用户暂停/请求/确认。无 owner 的预置暂停继续遵守既有规则,问题十一仍不在本轮。 +4. 退役会话的控制状态不被新会话继承。独立恢复流共享当前任务的 Source 仲裁状态,不能因某一个恢复 owner 退出而清掉其他 live owner 的用户暂停/请求/确认;最后一个 owner 退出才释放。 5. 进程重启不恢复旧控制运行时状态;保留行继续从同 fid、原路径恢复,不增加数据腿计数或持久化版本。 6. 最终 ACK 明确失败保留原记录,成功只清理 owning 记录。ACK 写成功但对端应用是否收到的不确定窗口不以新增 ACK-of-ACK 解决。 @@ -128,7 +120,7 @@ Web 的 `client_backend.py` 已知通过 Client 的文件/文件夹转发入口 - 去掉两份 `_drop_stale_transfers` 及 peer-scoped 新连接 sweep。新会话需要等待的是事先捕获的旧 owner,而不是扫描时刚出现的当前 socket。 - 旧恢复闭包固定使用创建时的控制 socket;`_forward_one` 可由内部传入捕获的 control_socket,不能在旧 worker 内重新取得新 `self.client_socket`。 - 关闭资源、等待 worker 和持久化 I/O 不在全局锁或控制 reader 内执行;旧 finally 按 socket/entry/record 身份释放。 -- route 强制重建是**另一个定向动作**:只关闭该 route 数据腿,不调用整个控制会话的 cancel_socket,不影响其他 fid。 +- 转发恢复不调用 route teardown 或健康控制会话的 cancel_socket;仅会话退役及自然失败沿既有 owning 路径释放其资源。原 route 收尾等待不扩成 peer 全局等待。 ### 5.2 全局用户控制(问题七) @@ -140,29 +132,30 @@ Web 的 `client_backend.py` 已知通过 Client 的文件/文件夹转发入口 - 自动背压与用户意图分开:保留 reader 高/低水位门槛,缓冲下降才能解除;通过 TCP 流控传递压力,不再发送无法区分意图的自动 pause/start,避免低水位 start 覆盖 Source 或 Target 的用户暂停。用户 start 不能打开 reader 门槛。记录实际峰值和一次扇出超调,不宣称 total RAM 的严格上限。 - 暂停不撤回最后一块,不阻止已完成文件的真实 ACK,也不把暂停计作传输失败。数据已全部发出时不凭暂停伪造完成;原有 ACK 成功条件不变,不另外设计新的全局超时策略。 -## 6. 强制重建与逐 Target 调度(问题八) +## 6. 等待原 route 收尾与每 Target 独立建流(问题八,本轮) ```mermaid flowchart TD - A[数值恢复请求及身份校验] --> B[登记一个 route 重建 owner] - B --> C[结束该旧 route 上下游数据腿] - C --> D[等待旧 reader/writer 及接收端收尾] - D --> E[释放旧内存 查询各未完成 Target 的实际 offset] - E --> F[选一个可服务 Target 保持原 fid 重放] - F --> G{全部 Target 已有真实完成 ACK?} - G -->|否| H[保留任务 结束本轮上游 再服务下一 Target] - H --> F - G -->|是| I[回原有最终 ACK 成功后清理所属任务] + A[Receiver 等旧文件关闭 读取实际数值 offset] --> B[校验实际 socket 与稳定 child route] + B --> C[保存每 Target pending] + C --> D[等待原 route 全部旧 owner 含 finally 自然结束] + D --> E[每 Target 独立转交 Source 并建流] + E --> F[独立正文与 ACK 资源及失败处理] + F --> G[仅真实 Target ACK 更新 completed] + G --> H{累计全部 accepted Target ACK?} + H -->|否| I[保留整任务 不伪造 route ACK] + H -->|是| J[按既有最终 ACK 规则完成清理] ``` -- route 按原任务对象和稳定 fid 串行登记;重建期间到达的合法请求合并为待恢复目标,不反复 teardown。请求者仍有自己的活跃接收腿时继续按接收占用规则拒绝重复登记;不把 pause 当 resume。 -- 强制关闭先停止旧读写,唤醒 pause/queue/pressure 等待,再释放内存。禁止边清旧队列边让旧 reader 入队,也禁止新流接到旧下游 socket。 -- 每个未完成 Target 的 offset 从其旧文件关闭后的实际大小取得。按 FIFO 服务已经拿到合法 offset 且 Source/Target 在线的目标;每轮只建立一个上游和一个下游,保持原 fid 并使用既有数据握手。 -- 一轮结束更新该 Target 完成集合。还有其他目标未完成时不向 Source 回整体成功 ACK;结束这一轮上游、保留 Source 上传和 Server route,旧发送 owner 收尾后再请求下一轮,不新增中间结果通道。 -- Source 离线保留 pending,重连后继续;Target 离线不阻塞已可服务目标。每目标单轮失败保留恢复依据,不无间隔循环自动重试;后续合法请求/重连可再次触发。 -- `offset=0` 是恢复而不是全新转发;空文件及 `offset==total` 走零正文,仍要求真实 ACK。 -- 所有 Target 已完成、仅上游 ACK 明确失败时,允许原 Source/route 的 EOF 再确认:保持原 upstream fid,核对数据头总长和 offset,只回有完成记录支撑的最终 ACK,不重开 Target、不重发正文。 -- 不新增 route total 字段。原 Source 从同 fid 保留上传行核对本地文件总长,Server 校验恢复头与 EOF offset,以及原 Source/route 的全 completed 证据;不能仅凭 offset==size 或未知 route 发送成功 ACK。 +- 运行时 `_relay_recoveries[fid]` 保存 `route/pending/active/control`;`pending[target]` 保存实际 Target 控制 socket 和数值 offset,`active[target]` 保存自身 record、Source/Target socket、offset。不保留查询/ready/FIFO running 轮次状态,不扩持久化 schema。 +- 原 route 的 listener、上/下游数据腿、握手、reader/writer 以及 finally 均为首次恢复的 barrier;`fileno()<0` 不代表完成。不能主动中断原 route、自动 start 暂停、持全局锁或阻塞控制 reader/event loop 等待。其他 route/fid 不受此等待影响。 +- 原 route 全收尾后,为每个合法可服务 Target 独立建立 Source→Server→Target 流;接收 owner 的原始 key 为 fid,独立恢复 key 为 `(target, fid)`,relay 仍按 `(target, child)` 定位。旧队列不复用,迟到 finally 只能删除自身对象。 +- Source 独立恢复 owner 使用 `(target, fid)`,整任务持久进度仍为 `((server_host, server_port), fid)`。公开 `file_transfer_mode` 签名不变,内部发送路径为各恢复流持有独立瞬时进度;一条流不能覆盖兄弟进度或提前删除整任务上传行。 +- 同一实际 socket+fid 只在端口握手登记/发送/取结果期间短串行,得到端口后释放;不得锁正文、最终 ACK 或整次恢复。A 的正文或 ACK 被阻塞时,B(含晚到 Target)仍可握手、建流和传输,不等待 A 收尾。 +- Source 多 sender 共享 upstream 任务控制状态和 owners 集合,`owner` 始终指向 live owner;仅最后一个 owner 退出才释放。任意参与者 pause/start 仍由 Source 仲裁,作用于所有恢复正文流;Server writers 继续排空,用户 start 不清本地背压。 +- pending Source 离线时保留,合法回连/后续触发再处理;Target 断线则丢旧 socket 请求,等待新实际会话和新实际 offset 重发。每 Target 请求去重,单流失败仅收尾该流并保留恢复依据,不打断兄弟、不自动重试。 +- 单 Target 真实 ACK 仅更新该 Target completed;中间成功不得伪造整 route ACK,Source 上传行/Server route 保留。累计全部 accepted Target 的真实 ACK 才能经既有最终 ACK 使整任务成功。零 offset、空文件、Target EOF 恢复仍需真实 ACK。 +- C4 全 Target 已完成、仅上游 ACK 明确失败的 EOF 再确认未实现;不借本轮数值 EOF 路径声称已完成 C4,不新增 ACK-of-ACK 或结果通道。 ## 7. 数据流与所有路径验收映射 @@ -170,7 +163,7 @@ flowchart TD 转发控制:任意参与者 fid/type/role → Server 校验实际控制会话/peer/route/当前 owner → Source upstream 串行决定 → Server 按各 child fid 投影状态;文件循环只有 Source 停止新增块。 -转发恢复:Target 请求 → route 校验/独占重建 → 旧数据腿退出及内存释放 → 逐目标 offset 回复 → 稳定 upstream/child、每轮重建数据连接 → 保留完成集合 → 所有真实 ACK 后终态清理。 +转发恢复:Receiver 关闭旧文件后实际数值请求 → 实际会话/route 校验与每 Target pending → 原 route 全部旧 owner/finally 自然结束 → 各 Target 独立 Source→Server→Target 流、offset/进度/资源/失败 → 累计真实 Target ACK → 全任务真实最终 ACK 后 owning 清理。 | 路径 | 必须观察的证据 | 原子阶段/验证 | |---|---|---| @@ -185,10 +178,10 @@ flowchart TD | P09 交叉/重复/未确认 pause→start | 无换腿交叉时固定顺序证明不丢反向意图,无通知回包循环 | C2;V2,S3 | | P10 暂停有在途/排队数据 | Source 下一块前等待;全部 Target 排空落盘;同 socket start;内容正确 | C2;V2,S3 | | P11 背压和 start 交叉 | 本地 reader 硬门槛仍有效,内存不持续增长;不能放大成严格总内存上限声明 | C2;V2,S3 | -| P12 live/paused/EOF 上游收到合法转发恢复 | 旧上下游关闭、旧 worker 退出后内存清零;保持 fid;控制/其他 fid 不受影响 | C3;V3,S4 | -| P13 错 peer/origin/target/fid/重复恢复 | 非法无 teardown;合法重复只登记一个重建 owner,不中断新重放 | C3;V3,S4 | -| P14 多 Target 不同 offset/部分已完成 | 顺序重放各自字节;稳定 route/child 和完成集合不丢;完成目标不重传 | C3;V3,S4 | -| P15 Source/Target 离线和重连 | pending 保留、可服务目标继续、无忙重试;回连后同 fid 恢复 | C3;V3,S4 | +| P12 原上游 live/paused/EOF/握手/finalizing 时恢复到达 | 请求仅保存;原上下游不关闭;最后一个旧 owner 含 finally 后才恢复;控制/其他 fid 不受影响 | 本轮 C3;V3b,S4 | +| P13 错 peer/origin/target/fid/重复请求 | 非法无副作用;每 Target 请求去重;旧 socket 请求不借给新会话 | 本轮 C3;V3a/V3b,S4 | +| P14 多 Target 不同 offset/部分完成/晚到目标 | 独立流/进度/资源;A 正文或 ACK 阻塞时 B 可传输;仅端口短串行;已完成目标不重传 | 本轮 C3;V3b,S4 | +| P15 Source/Target 离线及单流失败 | Source pending 保留;Target 旧 socket pending 丢弃,新会话新 offset 重发;兄弟继续,无自动重试 | 本轮 C3;V3b,S4 | | P16 零 offset/空文件/EOF | 不新建全目标任务;不重发已收正文;必须真实 ACK | C1/C3/C4;V1/V3/V4,S1/S4/S5 | | P17 所有目标完成、上游 ACK False/异常 | 保留可确认终态;同 fid EOF 补 ACK;不重开 Target;再次失败仍可确认 | C4;V4,S5 | | P18 Client 自目标/混合目标/同机不同端口 | 自目标不建腿、不建行;混合只拒自身;其他合法目标内容/ACK 正确 | C5;V5,S6 | @@ -199,18 +192,17 @@ flowchart TD ## 8. 原子拆分(固定次序,逐项人工审查) -预计行数包含必要回归和局部文档,不含本次计划文件;实际超过 500 行或混入独立意图必须先修订拆分,不在实现中自行扩大。每阶段完成一条可运行的行为路径及局部证据;不加占位分支、feature flag 或生产 no-op。 - -| 阶段 | 单一意图、必须修改点 | 文件与预计 diff | 局部验收 | -|---|---|---|---| -| C1 | 实际控制会话统一资源取消、旧 owner 收尾;删除 peer sweep;旧恢复固定 socket | connect_tcp;handshake/TCP lifecycle 与 control/resume 必要回归;250–450 行 | V1,S1/S2;P01–P07/P16/P19/P20 | -| C2 | 全局暂停,所有参与者请求交 Source 决定、Server 用各 child fid fanout;writer 排空,保留硬背压 | connect_tcp;transfer_control 单测及真实 control/转发用例;250–450 行 | V2,S3;P08–P11/P20 | -| C3 | 问题 8A:完整 route 定向 teardown/offset 查询/单 owner 调度,逐 Target 推进可服务请求;同 fid、无内存复用 | connect_tcp;fid_routes、control/resume 故障场景;300–500 行 | V3,S4;P03/P05/P12–P16/P19/P20 | -| C4 | 问题 8B:已完成 route 的上游 ACK 明确失败后,同 fid 做 EOF 再确认;不扩展 route schema | connect_tcp;既有 resume/control EOF 回归;180–300 行 | V4,S5;P16/P17/P20 | -| C5 | Client 统一入口拒绝自身目标,不误拒同机不同端口及其他目标 | connect_tcp;file_transfer/control 必要契约;60–150 行 | V5,S6;P18/P20 | -| C6 | 文档/变更记录/最终报告、规则沉淀、更新所有受影响契约描述;明确暂缓问题二 | 说明文档、变更记录、计划状态、实施报告;150–300 行 | V6;P01–P20 逐项列结论,不以通过数代替运行证据 | +| 阶段 | 意图与状态 | 局部验收 | +|---|---|---| +| C1 | 已保留:实际控制会话取消及旧 owner 收尾,不借用新 socket | V1,S1/S2;历史证据见报告 | +| C2 | 已保留:Source 仲裁全局暂停、writer 排空与独立背压 | V2,S3;历史证据见报告 | +| 旧 C3a/C3b | 已撤回历史:offset 查询、强制 teardown、单活跃 FIFO 轮次,不再实施或验收该契约 | 旧结果不作为本轮证据 | +| 本轮 C3 | 已实现:仅数值请求;原 route 旧 owner 全收尾;每 Target 独立流/进度/资源/失败,正文并行;socket+fid 仅端口短串行;保留 C1/C2 和累计真实 ACK | 分次局部回归与 3 组独立程序实际结果见实施报告;未扩大为 V6/C6 总验收 | +| C4 | 未实现:所有 Target 已完成、上游 ACK 明确失败后的 EOF 再确认 | V4,S5;须单独推进 | +| C5 | 未实现:Client 自身完整控制端点拒绝 | V5,S6;须单独推进 | +| C6 | 未实现:合并回归、全路径总体验收与最终报告 | V6;须单独推进 | -顺序:`C1 → C2 → C3 → C4 → C5 → C6`。删除原 leg_id 分配/解析基础与端口/控制 wire 切换两个阶段,其余按原意图顺延编号。每项完成窄验证、运行证据和报告后等待人工放行;本计划确认不等于自动创建这些 git 提交。 +本轮文档同步不是 C6 完成声明。实施不新增 wire、依赖、CI、自动重试或身份迁移;不创建 git 提交。旧 C3 的历史拆分及授权不作为新实现通过证据。 ## 9. 验收命令和证据格式(计划约定;实际执行见实施报告) @@ -221,7 +213,9 @@ flowchart TD .venv/bin/python -m pytest test/unit/network_api/test_transfer_handshakes.py test/unit/network_api/test_TCP_client.py test/unit/network_api/test_TCP_server.py test/unit/network_api/test_resume_matching.py test/integration/network_api/test_tcp_transfer_control.py test/integration/network_api/test_tcp_transfer_resume.py -k 'disconnect or reconnect or session or owner or stale or cleanup or resume' -q # V2 — C2 全局控制和背压 .venv/bin/python -m pytest test/unit/network_api/test_transfer_control.py test/integration/network_api/test_tcp_transfer_control.py -q -# V3 — C3 定向重建与顺序恢复 +# V3a — 本轮 C3 数值解析、Receiver 实际 offset 与旧 owner 边界 +.venv/bin/python -m pytest test/unit/network_api/test_resume_matching.py -q +# V3b — 本轮 C3 原 route 收尾及独立并行恢复(非旧查询/串行契约) .venv/bin/python -m pytest test/unit/network_api/test_fid_routes.py test/integration/network_api/test_tcp_transfer_resume.py test/integration/network_api/test_tcp_transfer_control.py -k 'forward or relay' -q # V4 — C4 EOF 与最终 ACK .venv/bin/python -m pytest test/unit/network_api/test_resume_matching.py test/integration/network_api/test_tcp_transfer_resume.py -k 'ack or eof' -q @@ -236,22 +230,22 @@ flowchart TD - **S1** `--case direct-leg`:双向普通文件/目录、稳定 fid/原路径、旧会话 owner 清理、换腿中断/重启及 tracking off 原保留行;不加入同会话旧控制帧跨腿隔离保证。 - **S2** `--case relay-leg`:稳定 upstream/child、完成集合及旧 worker/旧控制会话交叉;证明旧任务不借新控制 socket。 - **S3** `--case global-pause`:至少两个 Target,逐一发请求,确认后 Source 不新增块、旧块排空、同 socket start、压力硬门槛。 -- **S4** `--case serial-recovery`:不同落盘 offset、上游在线/暂停/EOF、多请求、离线目标及无关 fid;记录旧队列释放和每轮一个目标。 +- **S4** `--case parallel-recovery`:不同实际 offset;原 route 在线/暂停/EOF/握手/finally barrier;A 正文与 ACK 分别阻塞时 B 及晚到 Target 仍建流并传输;Source 离线排队、Target 断线丢旧请求并以新 offset 重发、单流失败与无关 fid。观察每流内容/资源、共享全局 pause、累计真实 ACK;不复用旧 serial-recovery 结论。 - **S5** `--case eof-confirm`:真实目标 ACK 后定向注入上游 ACK False/异常,再做同 fid 零正文确认,验证再次失败和重启。 - **S6** `--case self-target`:自身、混合目标和本机不同端口,保留合法目标传输结果。 每个 case 参数矩阵覆盖明文/加密,以及 thread/async 的对应实际分派;原端点重连覆盖配置别名、wildcard。用 Event/Barrier 固定顺序,计时只用于失败截止,不靠 sleep 碰运气。 -证据每条包含:阶段/路径编号、实际命令与退出码、稳定 fid、实际控制/data socket owner、原路径和实际落盘 offset、完整内容比较/必要 hash、真正 ACK 结果、队列/worker/索引最终状态。快照沿用既有 schema,无新增身份迁移字段;问题二列“暂缓”,未运行参数组列“未覆盖”,不借历史结果充数。本节是批准前的验收约定,各阶段实际执行情况和失败记录见实施报告。 +证据每条包含:阶段/路径编号、实际命令与退出码、稳定 fid、实际控制/data socket owner、原路径及每 Target 实际 offset、完整内容比较/必要 hash、真实 ACK、队列/worker/索引最终状态。固定 A 正文/ACK 阻塞时观察 B 建流及正文,不能只断言最终都成功。快照 schema 不变;问题二列“暂缓”,未运行参数组列“未覆盖”。本轮待统一验证,不借历史结果充数。 ## 10. 影响、风险与人工确认闸门 -- **公共契约/协议影响**:fid、原文件/转发命令、pause/start 及端口响应格式、端口解析/握手结果、file_transfer_mode 签名保持不变;不为问题二迁移消费者。全局暂停、强制转发恢复和 `/resume_trans ... ? ...` 查询仍改变契约;查询扩展 parser/formatter 的 offset 值域,必须同步所有消费者,不声称全部向后兼容。 -- **持久化模型不变**:保留五项文件行、scoped key 和 relay schema;不新增版本、恢复绑定、route total 或数据腿编号。EOF 再确认依赖原 Source 上传行与真实 completed 记录,不把 offset 相等单独当成功证据。 -- **并发风险**:不得持 progress/route/leg 全局锁等待 I/O 或线程;Source 旧 owner 退出前不得开下一轮;身份及 route 校验必须先于 teardown;同 fid 的旧 finally 不得清理新 owner。问题二的跨腿迟到控制窗口明确接受,不纳入自动收敛承诺。 -- **完成语义**:已完成 Target 只保留证据,不重传;中间轮不得伪造整体成功;最后的 ACK 明确失败必须保留可确认状态。用户不接受的新结果通道和 ACK-of-ACK 不引入。 +- **公共契约/协议影响**:公开签名、稳定 fid/child、文件/转发命令、pause/start、端口响应及持久化 schema 不变,不新增 wire。撤回 `?`/`None` 查询;恢复行为改为数值请求等待原 route 全收尾,再每 Target 独立并行流。 +- **持久化模型不变**:保留五项文件行、scoped key 和 relay schema,不新增版本、route total 或腿编号;独立流进度只在运行时,整任务行不得被单流提前清理。 +- **并发风险**:禁止持全局锁等 I/O/线程;原 route barrier 必须涵盖 finally,后续独立恢复流不相互充当 barrier;端口短锁不得覆盖正文/ACK。共享控制 owners 最后释放、旧 finally 按身份清理。问题二严格代次隔离继续暂缓。 +- **完成/失败语义**:单 Target 真实 ACK 不伪造整体成功;累计全部真实 Target ACK 后才整任务成功。单流失败不得取消兄弟或自动重试;Source 离线保留请求,Target 断线丢旧 socket 请求并等待新 offset。C4 全完成后的上游 EOF 再确认未实现。 - **平台边界**:运行环境能验证的 Linux 结果不代替 native Windows;Windows/其他 Python 版本如未实际运行,报告明确未覆盖。不得通过改 CI 或阈值规避。 -- **规则沉淀**:真实会话资源取消、不同 offset 顺序内容恢复、末次 ACK 再失败/成功三类消费者可见回归成为检查项,不新增源码字符串断言,也不为暂缓的问题二增加新测试约束。 +- **规则沉淀**:实际会话取消、数值实际 offset、原 owner/finally barrier、不同 offset 独立并行、晚来目标不等正文/ACK、全局 pause 与真实 ACK 聚合成为本轮回归路径;不新增源码字符串断言或严格代次隔离承诺。 - **文档/报告**:最终报告逐 P01–P20 给结论,单列问题二暂缓;每个原子变更含意图、范围、数据流、局部命令、未覆盖项、风险;文档随变更完成,不留“以后补”。 -用户已明确要求开始 C2,作为本阶段实施授权;C1 已获阶段推进。C2 完成后提交局部证据与报告供人工审查,不自动进入 C3–C6,不自动提交、合并或推送。 +本轮实现和局部证据已交付[实施报告](transfer-control-lifecycle-report.md),等待人工审查。旧 C3a/C3b 查询/强制 teardown/串行轮次及其结果仅保留为撤回历史。C4–C6 未实现,不自动推进,不自动提交、合并或推送。 diff --git a/docs/plans/transfer-control-lifecycle-report.md b/docs/plans/transfer-control-lifecycle-report.md index 531a3a0..1ae719f 100644 --- a/docs/plans/transfer-control-lifecycle-report.md +++ b/docs/plans/transfer-control-lifecycle-report.md @@ -1,5 +1,87 @@ # 传输控制生命周期实施报告 +## 本轮 C3 替代方案:已实现,局部运行证据如下 + +**当前状态:用户批准的数值请求、原 owner 收尾、独立并行恢复已实现并取得局部运行证据。** C1/C2 保留。最终四份 unit 文件 228 passed;转发集成整批 52 passed、3 个旧内部断言失败,迁移后专项 3 passed;新全局控制专项 3 passed,独立程序 3 组真实传输通过。上述是分次运行,不伪称最终单次整批全绿,不声明全部矩阵或 C6 总验收通过。旧 C3a/C3b 查询/强制 teardown/串行轮次仅为撤回历史;C4–C6 未实现。 + +### 本轮契约与更改路径 + +- `PyFlow/network_api/connect_tcp.py`:仅数值 `/resume_trans`,已删除 `?`/`None` 查询及其消费者。Receiver 旧接收 owner 和文件关闭后读取实际落盘 offset;Server 校验实际 Target socket、child/origin/target/route,原值登记,不查询兄弟目标、不用发送计数代替。 +- Server 等同一原 route 全部旧 listener、握手、上/下游、reader/writer 和 finalizing owner 自然收尾,包含 finally;不因请求强制 teardown 或自动 start。等待不持全局锁、不阻塞控制 reader/event loop,不影响其他 route/fid。 +- 此后按每 Target 独立 Source→Server→Target 流、实际 offset、运行时进度、资源和失败处理并行恢复;稳定 upstream/child fid、原完整路径、五项进度行及 relay schema 不变。同实际 socket+fid 仅端口握手短串行,绝不锁正文或最终 ACK;晚来 Target 不等已有大文件正文/ACK。 +- C1 实际会话 owner 和 C2 Source 全局 pause/start 仲裁及本地背压保留;共享控制状态有多个 live owners,最后一个退出才释放。中间 Target 的真实 ACK 仅更新自身 completed,不伪造整个 route ACK;累计全部 accepted Target 真实 ACK 才能整任务成功,Source 整任务上传行不得被单流提前删除。 +- Source 离线保留 pending。Target 断线丢弃旧实际 socket 的 pending,不借给替换会话;重连等旧接收 owner 收尾后读新实际 offset 重发。单 Target 失败不取消兄弟、不自动重试。 +- 本轮运行的回归路径:`test/unit/network_api/test_resume_matching.py`、`test_fid_routes.py`、`test_transfer_control.py`、`test_transfer_handshakes.py`,以及 `test/integration/network_api/test_tcp_transfer_resume.py`、`test_tcp_transfer_control.py`;具体选择器与分次结果如下。 +- 文档范围仅七份既有文件:`docs/plans/transfer-control-lifecycle-requirements.md`、`transfer-control-lifecycle-plan.md`、本报告;`docs/source/File_Transfer/File_Transfer.rst`、`docs/source/Network_APIs/TCP_Client_APIs.rst`、`TCP_Server_APIs.rst`、`docs/source/changes/transfer-fid-routes.md`。未创建文档。 +- 最终 owner 边界:发送恢复指令返回 False/异常时,若 Source 已经消费指令并使 relay 绑定 receive record,调度 worker 仍等该 owner 的 finally,不提前释放占用;迟到握手不能采用已被释放的 reservation。Target 重连的新实际 socket 可以保存新数值 offset 等旧 Target owner 退出,同一会话的 active 重复请求仍拒绝;退出后只消费已收到的 pending,不生成重试。 +- 显式 Source 发起的恢复也登记独立 active Target owner,失败后可再次合法发起;恢复 Target 握手使用准入 reservation 的实际控制 socket,不按 peer 借替换连接。 + +### 本轮路径证据与未覆盖边界 + +| 路径 | 必须取得的证据 | 本轮状态 | +|---|---|---| +| Receiver 数值 offset、零/空文件/Target EOF | 实际 offset、原路径、内容及真实 Target ACK | 数值解析、零 offset、不同落盘 offset、file/folder 的 Target ACK-loss EOF 零正文恢复已验证;全 Target 完成后的上游 EOF 再确认 C4 未实现 | +| 原 route live/paused/finally | 不拆活跃腿,原 owner 完整收尾前不建恢复流 | 四组独立正文 + 三组全局控制事件已验证 live/paused/finally;其他握手/EOF 窗口不扩大声明 | +| 不同 offset、部分完成及晚到 Target | A 正文或 ACK 被阻塞时 B 可建流并取得真实 ACK | 四参数真实集成与三组独立程序覆盖,A 再失败不取消 B | +| 多 owner 全局 pause/start/背压 | 所有 Source 流受统一仲裁,单 owner 退出不清共享状态 | 三参数全局控制通过;本轮未单独扩大到全部流量压力矩阵 | +| Source 离线、Target 会话更新及单流失败 | pending、旧 owner、新数值请求、兄弟继续,无自动重试 | Source 离线/原端点回连、stop、旧会话交叉、A 再失败/B 完成已通过;新 Target 会话 pending 另有单测,未扩大到多进程重启完整矩阵 | +| ACK 聚合及资源身份 | 单 Target 不伪造整任务成功,旧 finally 不删新 owner | 四参数正文、三参数全局控制与独立程序均保留真实 ACK/资源断言 | +| 明文/加密、thread/async、tracking off/持久化 | 真实 I/O、稳定 fid/path/schema;既有行恢复 | 三组独立程序、三组全局控制以及 route 持久化单测;不宣称所有参数笛卡尔积 | + +实现后运行的命令与结果见下节。以上结论来自本轮记录,不借旧 C3a/C3b 或 C1/C2 历史通过数。 + +### 本轮 S4 独立程序证据 + +一次性程序从真实保留进度行和已落盘的部分文件发起恢复,不调用 pytest 测试函数。Source、Server、两个 Target 均为真实 TCP 实例;只用事件固定 A 的正文或 ACK 门槛,文件、socket、加密和实际 ACK 均走生产实现。B 在 A 尚未放行时才提交请求,先完成文件与真实 Target ACK。该程序验证独立恢复流;原活跃 route/finally barrier 由本轮集成契约验证,不以预置的保留行冒充断线运行证据。 + +| 实际参数 | A 被阻塞的位置 | upstream fid | 稳定 child fid(A / B) | workers / 最终存活 | +|---|---|---:|---|---| +| 明文 thread、localhost 别名 | 正文首次读取前 | 5942851624 | 4697782172 / 8992749468 | 33 / 0 | +| 加密 thread | Target 最终 ACK 写入前 | 12672816124 | 19156548134 / 23451515430 | 72 / 0 | +| 加密 async、wildcard、tracking off 既有保留行 | 正文首次读取前 | 10342202172 | 20511536392 / 24806503688 | 72 / 0 | + +三组实际 offset 都是 A=8192、B=98304;目标沿用各自 `original/nested/payload.bin`。每份完整文件为 262307 字节,SHA-256 均为 `8fb29a369e87c3654ab4e692caabad6a31ac611dda80b64ee1e04819e022812b`。B 实际 ACK 后 A owner/socket 仍活跃、Source 原任务行对象仍保留;Source 两条恢复流使用不同 socket,运行时进度不覆写任务行。最终 Target ACK 次序 B→A,Source 结果 False→True:中间流不伪造整任务成功,全部真实 ACK 后清理 route/index/recovery/进度。实际控制 socket 未替换,所有 worker 收尾。 + +```bash +export PYTHONPATH="$PWD:$PWD/test/integration" +.venv/bin/python /tmp/pyflow-transfer-lifecycle-smoke.py --case parallel-recovery --gate body --alias +.venv/bin/python /tmp/pyflow-transfer-lifecycle-smoke.py --case parallel-recovery --gate ack --encrypted +.venv/bin/python /tmp/pyflow-transfer-lifecycle-smoke.py --case parallel-recovery --gate body --encrypted --async-server --wildcard --untracked +``` + +上述三条以 `&&` 顺序执行,整体退出 0,31.69 秒。临时实例、文件和密钥目录由 TemporaryDirectory 清理;一次性程序已删除。不抓包,不扩称所有连接的安全属性已审计。局部 pytest 结果另列,不借历史通过数。此程序先于最后的异常 owning 清理/新 Target 会话 pending 修正运行;最终修正由后续窄回归验证,不把程序结果冒充该错误交叉的运行证据。 + +### 本轮局部回归记录 + +- 最终 owner / 手动零 offset / 独立正文 / 全局控制的组合命令实际结果:**45 passed、2 failed,78.37 秒,退出 1**。`test_fid_routes.py` 的请求发送失败后 owner 保留、同/新 Target 会话 pending,以及独立正文的四参数组合、零 offset 路径通过;失败均在新全局控制场景。 +- 明文场景在关闭旧 Source data socket 后才等待其 start 通知,关闭线程可先释放旧控制 owner、清掉发送队列。修正为真实 start 通知确认后再 shutdown,再放正文门;不弱化通知断言。 +- async/untracked 场景在接收 worker 已选定 `progress=None` 后才塞进字典的行,不是该 worker 持有的旧行;异常路径会按未跟踪传输删除部分文件,Server 注入的 offset 与 Receiver 行不一致。修正场景初始化为接收注册时就保留真实五字段行,关闭后同时核对实际部分内容和行 offset=1024;继续验证 tracking off 恢复既有行,不把无保留依据的任务冒充可恢复。 +- 上述场景修正后,仅运行该函数的三个参数:**3 passed,30.20 秒,退出 0**。保留真实 pause condition wait、不同 socket、各自正文、B 先 ACK、最后 owner 释放、最终内容和资源清理断言;未删/skip 用例或降低阈值。组合失败记录保留,不伪称组合整批通过。 +- 文档机械检查:七份现有文档、六个相对文件链接、零缺失目标;该检查不替代运行验证。 +- 最终四份 unit 文件命令:**228 passed,0.78 秒,退出 0**。随后的转发/relay/并行选择器整批:**52 passed、3 failed、100 deselected,337.40 秒,退出 1**。失败全部是 `test_disconnected_relay_target_cannot_queue_behind_live_source` 的三参数场景:错误要求原始活跃 Source 的 `_resume_sends` 为空,但该表也持有原始发送 owner。 +- 移除该实现细节断言,改为核验原 Source、Server upstream 和存活 Target 的实际 pause 状态仍为 True;保留错误/断线请求拒绝、无 Server recovery、原 socket/owner 不变、原 worker 仍运行、start 后存活 Target 完整内容及最终资源清理。只运行修正场景:**3 passed,19.54 秒,退出 0**。未再次运行整批,故不写“最终整批全绿”。 +- 最早启动的六文件完整回归在运行时重置后无法取回 job/输出,不作为任何通过数来源。一次专项通过后的输出展示曾误用 Python `await sh(...)`,宿主报 TypeError;随后同步保留输出如上,不把宿主错误冒充产品失败或虚构统计。 + +```bash +.venv/bin/python -m pytest test/unit/network_api/test_fid_routes.py test/integration/network_api/test_tcp_transfer_resume.py::test_forward_recovery_waits_for_old_finally_and_runs_targets_independently test/integration/network_api/test_tcp_transfer_resume.py::test_forward_resume_with_zero_offset_reuses_existing_route test/integration/network_api/test_tcp_transfer_control.py::test_parallel_recoveries_wait_for_old_owner_and_share_source_pause -q --tb=short +.venv/bin/python -m pytest test/integration/network_api/test_tcp_transfer_control.py::test_parallel_recoveries_wait_for_old_owner_and_share_source_pause -q --tb=short +.venv/bin/python -m pytest test/unit/network_api/test_resume_matching.py test/unit/network_api/test_fid_routes.py test/unit/network_api/test_transfer_control.py test/unit/network_api/test_transfer_handshakes.py -q --tb=short +.venv/bin/python -m pytest test/integration/network_api/test_tcp_transfer_resume.py test/integration/network_api/test_tcp_transfer_control.py -k 'forward or relay or parallel_recoveries' -q --tb=short +.venv/bin/python -m pytest test/integration/network_api/test_tcp_transfer_control.py::test_disconnected_relay_target_cannot_queue_behind_live_source -q --tb=short +``` + +### 当前风险与未实现边界 + +- 高风险路径是原 route 最后一个 owner 的 finally barrier、多 Target 同 upstream fid 的端口结果关联、独立进度与 owning 清理、共享全局控制最后释放及累计真实 ACK。必须以事件固定正文/ACK 阻塞交叉,不能只看最终文件存在。 +- 原 route 暂停、旧 ACK 等待或 finally 未结束会延迟首次恢复;这是批准的自然收尾边界,不用超时抢占/强制拆腿掩盖。该 barrier 不得再次挡住后续独立恢复流或晚到 Target。 +- 同控制会话、同 fid 换腿时迟到 pause/start 的严格代次隔离仍暂缓;不新增 leg_id、换 fid、wire 字段、schema、重试、CI 或依赖。 +- ACK 本地写成功与对端应用已收到之间的不确定窗口不以新结果通道或 ACK-of-ACK 解决。C4 全 Target 完成后的上游 EOF 再确认、C5 自目标拒绝、C6 总体验收未实现。 +- 本轮运行平台为 Linux、Python 3.10;native Windows、其他 Python 版本、多进程重启的完整矩阵及转发中途 rekey 未覆盖。具体明文/加密/thread/async 参数见本轮输出,历史平台结果不充数。 + +--- + +以下 C1/C2 及旧 C3a/C3b 保留其交付时状态与真实历史输出;旧 C3 的现行授权及验收状态以上节为准。 + ## C1:实际控制会话取消与旧 owner 收尾 状态:**C1 实现及局部验收完成;用户已要求开始 C2,C1 获阶段推进**。下述记录是 C1 的局部证据;当前 C2 状态见后续章节,未创建 git 提交、合并或推送。依据:[需求卡](transfer-control-lifecycle-requirements.md)、[计划 C1](transfer-control-lifecycle-plan.md#8-原子拆分固定次序逐项人工审查)。 @@ -90,3 +172,90 @@ S3 不调用 pytest 测试函数,不替换文件/网络/加密主路径;事 本阶段覆盖 P08–P11 及 P20 的对应控制矩阵;不改 fid、四 token、端口消息、公开方法签名、进度 schema、普通 busy 或真实 ACK 规则。自动压力不再投影为用户 paused;不宣称阈值约束全部进程 RAM,也不承诺撤回 socket 在途字节。问题二继续暂缓;C3 重建/顺序恢复、C4 EOF 补确认、C5 自转发和 C6 总体验收未实施。native Windows、其他 Python 版本、relay 中途 rekey 的独立场景未验证。测试保留普通控制/rekey、失败/收尾回归;未改 CI、依赖、coverage。全局确认、暂停排空、背压释放不清用户暂停成为永久契约检查。 + +## 旧 C3a / C3b(已撤回历史):收尾后 offset 查询与 route 定向顺序恢复 + +用户授权推进 C3 后,因原阶段超过 500 行警戒线,选择拆成 C3a(查询协议及接收端收尾后回复)和 C3b(route 定向重建/顺序调度),授权本轮实现和局部验收。两个单元按意图审查,共用查询契约;未创建 git 提交,不自动进入 C4–C6。必要回归迁移使总差异仍大于 500 行,不将两个名称冒充两个已审查的小提交;最终规模及提交划分仍需人工审查。 + +状态:**旧 C3a/C3b 查询、强制 teardown 和串行活跃方案已撤回,不是当前契约或本轮完成结论**。下列仅保留旧方案当时的真实实现与输出。用户现已批准数值 offset、原 route 全旧 owner 含 finally 自然收尾、每 Target 独立并行流的新需求和计划;本轮状态见报告首节,尚待统一验证,不借以下历史结果声明通过。 + +### C3a:更改路径、解决的问题、数据流 + +- `PyFlow/network_api/connect_tcp.py`:`parse_resume_command` 查询分支返回 `(fid, None, origin, target)`,`format_resume_line` 将 `None` 格式化为 `?`;数值五 token 格式不变。Server 拒绝收到的查询作为 Receiver 恢复请求;Client 查询分派与数值发送分派分开,全部消费者区分 offset 值域。 +- `TCP_Client_Base._query_resume_offset` 校验实际 Server socket、自身 target、保留 download fid/origin;后台等待旧接收 owner 与实际文件关闭,再经既有 secure/send 路径按磁盘大小回复数值 offset。未知/已移除的接收行不虚构零 offset,持久化模型不加字段。 +- `test/unit/network_api/test_resume_matching.py` 保留数值、shell-quoted endpoint、边界和错误格式回归,并增加 `?` / `None` round-trip 与非法查询。真实查询/文件收尾证据来自下述 C3b 消费者场景,而不是源码/调用次数断言。 + +数据流:Server 定向查询 → Client 实际会话与保留身份校验 → 后台等待旧文件关闭 → 读原完整路径的实际大小 → 既有数值回复。控制 reader 不等待自己需要分派的握手/加密消息。 + +### C3b:更改路径、解决的问题、数据流 + +- `connect_tcp.py` 用 `_relay_recoveries[fid]` 保存一个运行时重建 owner:`route/old/queried/ready/active/running/wake`;替代旧 `_pending_originator_resumes`。实际控制 socket、原 Source、Target、child fid 和 route 先校验,再登记动作;重复请求不重复 teardown,active Target 拒绝重复。 +- `_cancel_relay` 只取消捕获的该 route listener/data socket 与握手,不取消健康控制会话。旧 reader 停止入队,writers 退出/排空,最终关闭数据资源、清空捕获引用并置 `done` 后才释放 receive reservation,避免新轮越过旧 finally。队列不复用,不删除 Target 已落盘文件。 +- `_run_relay_recovery` 查询在线未完成 Target;查询发送失败回滚 queried 标记,以便下一次合法触发重查。按合法 offset 回复的 FIFO 选择在线 Target;每轮仅一个上游和一个下游,保留原 upstream/child fid、route 完成集合和完整目标映射。 +- 协议驱动的 Client 恢复经 `_resume_on_socket(..., drain_forward=True)` 固定实际准入 socket,并等待旧 Source sender 收尾;公开 `resume_trans` 的普通/忙对象拒绝语义保留。Server 也把实际 socket 传至直接恢复和 route 登记边界,不在后续后台工作里重新按 peer 借新控制连接。 +- 中间轮只完成该 Target;其他 Target 未完成时沿用原 error/结束语义,不回整体成功 ACK,保留 Source 上传行和 route。Source 离线保留 ready;Target 离线不阻塞可服务兄弟目标;合法请求/重连重新触发,不增加定时或忙重试循环。 +- `test/unit/network_api/test_fid_routes.py` 迁移旧 pending 内部断言,覆盖错误/旧实际 socket、origin/target/fid、单重建 owner、离线保留、并发回复仅一次真实 Source 请求,以及查询发送 False 后同 socket 合法重查。 +- `test/integration/network_api/test_tcp_transfer_resume.py` 将已废弃的 busy-skip 恢复用例迁移为真实共享 relay 中断:A 实际写入 8192 字节后仅断数据 socket,B 实际写入 24576 字节,Source 活跃并确认暂停;A 的恢复触发旧 route teardown。A 真正 ACK 门槛内放行 B 的查询回复,证明 B 已 ready 但未启动;随后只按 A→B 重放,检查两份完整内容、稳定 child、`False/False/True` 原尝试/中间轮/最终轮结果及资源清理。 +- 原 ACK-loss file/folder 用例保留异常/False 两种首次 ACK 故障、EOF 零正文、完成集合、原嵌套路径和真实终态 ACK。用事件固定查询回复顺序,不再假定最初请求者天然优先、也不要求对每个兄弟目标手动再次请求。refused-listener/reload 用例保留未完成索引和持久化证据,不将触发请求的 0 冒充已确认 disk offset。 +- `test/integration/network_api/test_tcp_transfer_control.py` 同步离线 Source、完成兄弟、旧 owner 释放和新恢复的契约。`File_Transfer.rst`、`TCP_Server_APIs.rst`、`TCP_Client_APIs.rst` 和 `changes/transfer-fid-routes.md` 同步新行为和边界。 + +数据流:合法 Receiver 数值请求 → 单 route 重建登记 → 旧 data legs/队列/worker 完整收尾 → 各 Target 关闭文件后 offset 回复 → FIFO 单 Target 新数据腿 → 更新真实 completed → 下一轮或最终真实 ACK 后 owning 清理。独立 fid 不参与 teardown。 + +### 实际局部验证与失败处理 + +运行环境:Linux,Python 3.10.20。以下是分次运行,不声称一次完整 V3/V6 全绿,也不相加成唯一用例总数: + +| 实际命令/范围 | 结果 | +|---|---| +| 原 V3 `fid_routes + resume + control -k 'forward or relay'` | 48 passed、4 failed、133 deselected,270.62 秒;退出 1 | +| `test/unit/network_api/test_fid_routes.py -q`(新查询失败用例添加前) | 36 passed,0.14 秒;退出 0 | +| `test_tcp_transfer_control.py -k 'forward or relay' -x -vv --tb=short` | 36 passed、54 deselected,233.88 秒;退出 0 | +| 两份 unit(resume_matching、fid_routes)加 ACK-loss、refused-listener、serial-recovery 三个函数 | 81 passed,28.22 秒;退出 0 | +| `test_tcp_transfer_resume.py -k 'forward or relay' -q --tb=short` | 13 passed、46 deselected,46.22 秒;退出 0 | +| `test_tcp_transfer_control.py -k 'relay_offline or reconnect_keeps' -q --tb=short` | 9 passed、81 deselected,59.86 秒;退出 0 | +| 新 `failed_offset_query...` 与真实 serial-recovery 两个函数 | 2 passed,6.72 秒;退出 0 | +| 最终 socket 固定边界:fid_routes/control 的 forged/stale/query-failure/online-resume/disconnected-Target/old-session 子集 | 15 passed、112 deselected,70.72 秒;退出 0 | + +原 4 个失败:零 ACK file/folder 两个用例仍按旧手动调度契约计数,实际合法 B 回复可先于 A,不能由 calls=3 推断双 sender;一个 refused-listener 用例引用已删字段;新顺序恢复用例缺事件屏障,取 route 前文件已完成。迁移契约和真实事件顺序后通过,未删除路径、弱化内容/ACK 断言、修改 CI 或 coverage。另修复 review 发现的 receive reservation 早于 relay `done` 释放,以及失败查询残留标记;检查 Python 引用的 LSP 仅有 Ruff、`textDocument/references` 不可用,已报告工具限制,消费者由仓库调用点和运行验证覆盖。 + +精确重跑命令: + +```bash +.venv/bin/python -m pytest test/unit/network_api/test_resume_matching.py test/unit/network_api/test_fid_routes.py test/integration/network_api/test_tcp_transfer_resume.py::test_forward_ack_loss_retains_state_and_resumes_original_ids test/integration/network_api/test_tcp_transfer_resume.py::test_forward_route_survives_a_refused_target_listener_and_reload test/integration/network_api/test_tcp_transfer_resume.py::test_forward_resume_tears_down_live_route_and_replays_targets_serially -q --tb=short +.venv/bin/python -m pytest test/integration/network_api/test_tcp_transfer_resume.py -k 'forward or relay' -q --tb=short +.venv/bin/python -m pytest test/integration/network_api/test_tcp_transfer_control.py -k 'relay_offline or reconnect_keeps' -q --tb=short +.venv/bin/python -m pytest test/unit/network_api/test_fid_routes.py::test_failed_offset_query_can_be_requested_again_on_the_same_session test/integration/network_api/test_tcp_transfer_resume.py::test_forward_resume_tears_down_live_route_and_replays_targets_serially -q --tb=short +.venv/bin/python -m pytest test/unit/network_api/test_fid_routes.py test/integration/network_api/test_tcp_transfer_control.py -k 'forged or stale or failed_offset_query or online_resume or disconnected_relay_target or reconnect_keeps' -q --tb=short +``` + +### S4 独立真实程序:已取得的运行证据 + +不调用 pytest 测试函数,不 mock 文件/网络/加密主路径;仅用 Event 固定真实写入、ACK 与发送 owner 时序,并真实关闭故障数据 socket。Source 同时有另一个普通上传 fid 在正文门槛内保持活跃;恢复期间该 socket 仍打开,最后取得其真实 ACK 且内容一致。 + +| 场景 | upstream fid | 两个稳定 child fid | 恢复 offset | workers / 最终存活 | +|---|---:|---|---|---| +| 明文 live、localhost 别名 | 10865447346 | 6493365684 / 10788332980 | 8192 → 24576 | 48 / 0 | +| 加密 thread、Source paused、Target B 离线再原端点回连 | 15823586500 | 17644686304 / 21939653600 | 8192 → 24576 | 110 / 0 | +| 加密 async、wildcard、EOF 等待、保留行 tracking off | 15091650932 | 18378608972 / 22673576268 | 8192 → 150851(EOF 零正文) | 90 / 0 | + +每组 Source 原尝试/中间轮/最终轮实际 ACK 结果为 `False/False/True`;两份文件 byte-for-byte 等于 150851 字节原内容,SHA-256 均为 `0a45ceaa5fac82dd386c144b9985cd3985b91a76aba8e5fbac335315c9459f14`。原 relay 捕获的 6 个 socket 登记全部关闭,原 Source owner 已退出;route/index/recovery 清理,Source 与未断线 Target 的实际控制 socket 保持。无关 fid 依次为 6570480050、11528619204、10796683636,最终 ACK=True。EOF 组实际以保留行完成恢复,不在 tracking off 时创建新行;B 从 total=150851 恢复,仍经原真实 header/ACK,而不是因大小相等跳过确认。 + +```bash +PYTHONPATH="$PWD" .venv/bin/python /tmp/pyflow-transfer-lifecycle-smoke.py --case serial-recovery --mode live --alias +PYTHONPATH="$PWD" .venv/bin/python /tmp/pyflow-transfer-lifecycle-smoke.py --case serial-recovery --mode paused --encrypted --offline-target +PYTHONPATH="$PWD" .venv/bin/python /tmp/pyflow-transfer-lifecycle-smoke.py --case serial-recovery --mode eof --encrypted --async-server --untracked +``` + +独立程序的首次 live 运行因测试注入只 shutdown 而未 close 接收 data socket,仍可读到内核已排队字节,固定 8192 的断言失败;改为真实 shutdown+close 后通过。首次主动关闭 B 控制 socket 的重连没有保持原本地端点;改为由 Server 发 FIN、Client 被动退出并释放旧 socket 后,原端点回连通过。它们是程序时序/断线注入修正,不修改生产内容或网络算法。 + +首次 EOF 独立程序等待 B 的 offset 回复超时:旧 B ACK 的本地 write 可能成功、但 Server teardown 已不再收它,B 因而不再保留 receive entry。这属于原 ACK 写成功/接收不确定窗口,不伪称生产代码已修复。最终 EOF 场景在放行旧 ACK 前真实关闭其接收 data socket,使旧 ACK **明确失败**后再查询,验证同 fid 零正文恢复;退出 0,10.88 秒。前述两组成功程序亦退出 0;批命令中的后续场景失败不否认已打印并完成的前一组结果。 + +一次性程序已删除;它的临时目录、传输文件和隔离密钥目录均由 TemporaryDirectory 清理。未抓包;加密结果是现有 framed channel 实际传输的内容/ACK 证据,不扩大成所有连接安全属性的全量审计结论。 + +### 旧方案当时的范围、风险与规则(历史,非现行契约) + +- C3 对应 P03/P05/P12–P16/P19/P20 的本阶段路径;完成目标保留、离线 Source、文件夹原完整路径、数值零/EOF 回归由局部测试提供。多进程重启的独立完整矩阵、native Windows、其他 Python 版本、转发中途 rekey 不列为本次通过项。 +- 未知/没有保留 receive entry 的 Target 不返回虚构 offset;可能包括尚未接收文件头或 tracking off 未产生行的任务。它们保留 Server 未完成 route,不承诺自动补齐缺失的接收恢复依据。查询成功发送但无合法回复不新增定时重试;Source 接受/端口/ACK 超时仍沿用现有失败路径,可再次合法操作或结束控制会话后恢复。 +- ACK 本地写成功不等于对端应用已收到;不增加 ACK-of-ACK。旧目标 ACK 写成功但 Server teardown 未收到的歧义窗口不承诺自动收敛;EOF 场景必须区分“明确失败”与“写成功但未收到”。本轮不声称修复该协议不确定性。 +- 问题二(同控制会话、同 fid 换腿交叉的旧 pause/start 严格代次隔离)继续暂缓。C4 全 Target 已完成后的 EOF 再确认、C5 自转发拒绝、C6 合并回归与总验收未实施;不把 Target 自身 EOF ACK-loss 恢复说成已完成 C4。 +- 规则沉淀为真实 socket 契约:错误实际会话无 teardown、query 后实测落盘 offset、FIFO 一目标一轮、旧 finally 后再释放占用、中间轮无整体成功、query False 后同 socket 可重新触发。无新增依赖、CI 修改、skip 或 coverage 放宽;进度 JSON、原 fid、pause/start 签名/四 token 与端口格式保持。 diff --git a/docs/plans/transfer-control-lifecycle-requirements.md b/docs/plans/transfer-control-lifecycle-requirements.md index 016949f..6328599 100644 --- a/docs/plans/transfer-control-lifecycle-requirements.md +++ b/docs/plans/transfer-control-lifecycle-requirements.md @@ -1,8 +1,8 @@ # 传输控制生命周期与转发恢复 — 需求卡 -状态:用户已选择暂缓问题二;C1 已获阶段推进,C2 实现及局部验收完成,等待人工审查。当前已实施 Source 仲裁的全局转发暂停、child 状态投影、writer 排空及独立的本地背压门槛;保持原 fid、pause/start 和端口响应格式。实际证据见[实施报告](transfer-control-lifecycle-report.md),不自动进入 C3–C6,不自动提交、合并或推送。 +状态:**用户批准的数值 offset、每 Target 独立并行恢复已实现并取得局部运行证据,详见实施报告**。已撤回旧 C3 的 `/resume_trans ... ? ...`、`offset=None`、强制 teardown 和单活跃 Target/FIFO 轮次。Receiver 提交实际落盘数值 offset;Server 等同一原 route 的旧 owner(含 finally)全部收尾后,为每个 Target 独立建立 Source→Server→Target 流,正文并行。C1/C2 保留;C4–C6 未实现,不自动推进。 -计划编写阶段没有运行 pytest、构建或实现烟测;此前文档一致性检查不等于功能验收。C1/C2 实际执行的命令、运行证据和失败记录统一见实施报告;此前换新 fid 或 leg_id 方案的检查记录不作为本轮验证结果。 +本轮命令、实际结果、失败修正及明确未覆盖项见[实施报告](transfer-control-lifecycle-report.md)。旧 C3a/C3b 仅为已撤回方案的历史证据,不作为本轮通过结果;不自动提交、合并或推送。 计划编写阶段的文档机械检查通过:3 份文档、6 个相对链接、21 个计划涉及的既有文件路径、14 个验收命令引用路径、20 条验收路径、6 个原子阶段及命令组、6 个拟定运行场景,错误数为 0。当时实施报告尚未创建;这份历史检查不代表功能验收通过,当前实现证据另见实施报告。 @@ -12,7 +12,7 @@ - 任意端可请求暂停/开始、由数据发送端仲裁,是已确认特性,不是缺陷。 - 问题二暂缓:不解决旧 pause/start 与同一控制会话、同 fid 数据腿重建交叉时的严格代次隔离。控制发送失败沿用现有失败/关闭路径,允许人工重新操作或结束控制会话后恢复;不承诺该窗口自动无缝收敛。断线资源清理和已商议的恢复能力仍在范围内。 - 此前问题九(超长文件名)、十(控制队列增长)、十一(无 owner 的预置暂停)暂不处理。 -- 本轮文档只约定目标和待确认机制。此前真实 socket 复现是问题证据,不是尚未实现方案的验证结果。 +- 用户已批准撤回旧 C3 的查询、强制重建及串行活跃契约,并批准本需求卡和对应更改计划;保留历史输出,不将其冒充本轮验收。 ## 目标与非目标 @@ -22,10 +22,10 @@ 2. 会话关闭只处理该实际控制 socket 拥有的资源;不再让重连任务按 peer 扫描并关闭后来建立的新数据 socket。 3. 流式转发采用全 route 的用户暂停:任意 Source、Server、Target 可请求 pause/start,Source 作最终仲裁。一个 Target 暂停,所有 Target 停止获得新的源数据。Server 已接收的数据继续排空到 Target;保留数据 socket,不做 seek 或重握手。 4. 不采用“每个 Target 持有独立暂停锁、必须本人解除”的规则。任意端的 start 仍可经 Source 仲裁解除用户暂停。自动背压的内存硬门槛不被用户 start 清除。 -5. 有效的转发恢复请求到达 Server 后,不复用旧 relay 内存内容。若旧上游数据腿仍在,关闭该旧上游及依赖它的未完成下游,丢弃对应内存,再按接收端 offset 从 Source 重放。保留控制连接、稳定 upstream fid/child fid、已落盘文件及已确认目标集合;旧 owner 收尾后再用原握手重建数据腿。 -6. Client 发起转发时拒绝目标等于其自身控制端点的目标。不把“同机不同端口”或“连接 localhost Server”误当成自转发。 -7. 保留发送端以真实最终 ACK 判成功的规则。EOF 再确认不重传正文;所有 Target 已确认、仅上游 ACK 失败的终态必须能重新确认,不伪造未完成目标的 ACK。单个 Target 的完成只更新该目标,不能把部分完成当作整个任务成功。 -8. 正常发送仍可多目标并行;同一 route 的恢复阶段逐 Target 顺序重放,各用自己的实际落盘 offset,已完成目标不重传。 +5. 有效转发恢复请求由 Receiver 在其旧接收 owner/文件收尾后,带实际数值 offset 提交 Server。Server 按 child fid/实际会话定位原 route;原 route 的数据腿、listener、握手、reader/writer 或 finalizing owner 尚未全部结束时只保存请求,不主动中断。全部旧 owner(含 finally)收尾后,按每个 Target 自己的 offset 独立转交 Source、建流;不复用旧 relay 内存、不更换 fid、不查询其他 Target 的 offset。 +6. 后续 C5 目标为 Client 转发入口拒绝自身完整控制端点、允许同 host 不同端口;C5 本轮未实现,不作本轮完成项。 +7. 保留真实最终 ACK 判成功规则:每个 Target 的真实 ACK 只更新其完成集合,累计所有 accepted Target 的真实 ACK 才能使整任务成功;中间 Target 成功不伪造整 route ACK,Source 上传行及未完成 route 继续保留。Target 的数值 EOF 恢复仍需真实 ACK;C4“所有 Target 已完成、仅上游 ACK 明确失败”的再确认未实现。 +8. 多个 Target 恢复各有独立 offset、Source→Server→Target 数据流、进度、资源及失败结果,正文并行。晚到 Target 不等待已有恢复流的大文件正文或 ACK;同一实际控制 socket+fid 仅端口握手短串行,不锁正文或最终 ACK。 ### 非目标 @@ -34,7 +34,9 @@ - 不改 CI、依赖、coverage 策略;不删或弱化测试。 - 不解决 NAT、控制端点改变后身份迁移、多进程共享进度文件及同尺寸源文件内容改变。 - 不把 pause 返回 True 当作对端确认或立即停止落盘;不保证撤回已经交给 socket 的字节。 -- 不用某一个 Target 的 offset 替代其他 Target 的 offset;不为恢复阶段增加并行重放及字节范围过滤机制。 +- 不用一个 Target 的 offset、运行时进度或失败替代其他 Target;并行恢复采用独立流,不增加共享正文的字节范围过滤机制。 +- 不增加 Server→Target 的 offset 查询、`?`/`None` offset、恢复状态消息或能力协商;不把所有数据失败改成自动发起恢复/循环重试。 +- 不因恢复请求主动关闭上游或其他 Target 的活跃数据腿,也不自动 start 用户暂停;等待只针对同一 upstream route,不等待整个 peer 或其他 fid。 ## 修改思路与确认状态 @@ -46,7 +48,7 @@ - 保留现有实际控制 socket 校验、pending/unresolved 握手隔离、同 fid 占用及旧 owner 收尾;这不能被表述为已经解决同一控制会话内迟到控制消息的问题。 - 暂缓只针对问题二,不取消问题四/五的重连安全修复,也不取消问题七和八的正常控制及恢复方案。 -### D4:统一为实际控制会话所有权(拟定机制,随更改计划审查) +### D4:统一为实际控制会话所有权(C1 保留) - 复用 `_TransferHandshakeRegistry.track_socket/cancel_socket`,让会话资源只有一个登记及取消入口。 - 已知的旧控制会话退役时,取消它自己的 listener/data socket/握手及控制状态;新会话不得借 peer 地址取得旧会话之外的资源。 @@ -54,22 +56,20 @@ - 拆除 `_drop_stale_transfers` 按进度表找 socket 并关闭的重复职责。保留基于旧 owner 快照的必要收尾等待;等待不得持有全局锁或阻塞需要处理握手的控制接收线程。 - 旧 finally 按原 socket、entry、record 身份释放,不能删新 owner;失败进度继续按原规则保留。 -### D8:强制重建的多目标调度(已选择顺序恢复) +### D8:数值 offset、原 route 旧 owner 收尾与每 Target 独立恢复(用户已批准) -当前 route 的上游被多个 Target 共享。重建上游并清空旧内存时,也必须结束依赖该旧字节流的未完成下游数据腿,等待接收端收尾、落盘;保留原 fid,不能把新 offset 字节直接接到旧下游 socket。 +1. `/resume_trans ` 仅保留原五 token 数值形式,offset 是非负整数;`0` 表示从头恢复。删除 `?` 查询、`offset=None`、查询线程/状态及查询专用消费者,不另增替代命令。 +2. Receiver 等自己的旧接收 owner(含 finally)退出、原文件关闭后,读取实际文件大小提交请求。沿用显式/重连恢复入口,不新增失败自动请求循环。Server 原样保存数值 offset,不用发送计数或其他 Target 的 offset 替换。 +3. Server 入队前校验实际控制 socket、origin、target、child fid 及未完成 route;将 child fid 映射为稳定 upstream fid 后转交 Source,保留数值 offset 与端点身份,不按 fid 全局猜 route。 +4. 首次恢复建流必须等同一原 route 的上游、全部下游及 listener/握手/reader/writer/资源 owner(包括 finally)全部自然收尾;socket 已关闭不代表 owner 已退出。不主动 teardown、不自动 start 暂停;不等待健康控制连接断开,也不等待其他 fid/route。 +5. 等待采用 route-scoped 运行时 pending,不阻塞控制 reader、异步 event loop 或持全局锁等待。旧 owner 完成后,所有合法可服务 Target 可独立进入恢复;不把随后活跃的独立恢复流重新当成整 route barrier。 +6. 每个 Target 最多一个待处理请求和一个活跃恢复 owner,重复请求合并。各 Target 各有实际 offset、独立 Source→Server→Target 流、运行时进度、资源及失败结果;稳定 upstream/child fid、完整路径和持久化 schema 不变。Source 整任务上传行仍是恢复依据,不被某条独立流的瞬时进度覆盖或提前删除。 +7. 同一实际控制 socket+fid 的端口握手短串行以关联既有四 token 回复;锁只覆盖登记/发送/取得端口结果,不覆盖正文、最终 ACK 或整任务。A 已开始正文或等待 ACK 时,B(含晚到 Target)可独立建流和传输,不等 A 完成;不同 offset 不共享正文过滤或旧队列。 +8. Source 离线时保留 pending,合法回连/后续触发后处理。Target 断线即丢弃绑定旧实际 socket 的 pending 请求;不把旧请求借给新 socket,重连后由 Receiver 等旧 owner 收尾、读取新实际 offset 重新请求。离线/失败 Target 不阻塞可服务兄弟目标,活跃流失败仅收尾自身,不启动自动重试。 +9. Source 仍仲裁全 route 用户 pause/start;多个恢复 sender 共享该任务控制状态,最后一个 owner 退出才释放,任一 Target 的 pause 使所有 Source 流停止新增正文。Server 已收字节继续排空,本地背压与用户 start 独立。 +10. 每个真实 Target ACK 只记该 Target 完成;其他 Target 未完成时不发整 route 成功 ACK,Source 上传行及 Server route 保留。offset 为零、空文件和 EOF 均沿用数值恢复;offset==size 不等于成功。C4 全完成后的上游 EOF 再确认仍未实现。 -按已选择的简化方向,恢复流程约束如下: - -1. Server 对同 route 串行登记一个重建操作。先验证请求的实际会话、原始 Source、Target、fid 和 offset,再做 teardown;无效请求不得中断任何传输。 -2. 关闭旧上下游数据腿、唤醒暂停/队列等待者并等待旧 owner 收尾;旧 reader/writer 不再活动后,释放该旧 relay 的内存和运行时控制状态。 -3. 保留全部已完成 Target;它们不参与重传。对其他未完成 Target,分别从各自收尾后的实际文件大小取得恢复请求,不使用 Server 的发送计数猜落盘位置。 -4. 一轮只服务一个 Target 的恢复请求:Source 从该 Target 的 offset 发送到 EOF;随后按已有 route 继续下一个未完成 Target 的恢复。离线 Target 保留未完成,不阻塞可服务目标,不虚报全文件成功。 -5. 同 route 恢复请求在一个调度入口登记,重建中收到的请求不重复 teardown、不创建第二个 Source sender;Source 接受重放前也必须完成旧发送 owner 的收尾,不能沿用 busy 静默忽略而丢掉已触发的恢复。 -6. offset == size 且仍需目标确认时走零正文 EOF 确认;所有 Target 已确认时只恢复上游完成确认,不重发已完成目标。 - -强制结束共享 relay 后,计划由 Server 用 `/resume_trans ? ` 查询各未完成 Target 收尾后的落盘 offset,Client 用原数值恢复形式回复;避免猜测已发出但未落盘的字节,也不增加定时重试。该查询语义与具体切换时机均随更改计划等待确认。 - -已确认取舍:正常发送仍可多目标并行;同 route 的恢复阶段改为逐 Target 顺序重放,换取无需共享字节范围过滤、无需内存缓存复用。用户已明确选择该调度方式;具体实现仍需另走计划与审查。 +代价与风险:原 route 尚有活跃传输、用户暂停或未结束的 ACK/finally 时,首次恢复继续等,不增加强制关闭、超时抢占或自动重试。旧 owner 全部收尾后的独立恢复流不互相等待正文/ACK。运行时 pending/active 不扩展持久化 schema,重启后仍由原接收记录重新请求;同 socket+fid 迟到控制消息的严格代次隔离仍暂缓。 ## 路径全集与验收证据要求 @@ -83,8 +83,9 @@ | 两个 Target 相反请求、未确认 pause→start | 不吞掉反向意图、不回包循环;不是独立端点暂停锁 | | 全局 pause,存在在途块/Server 排队块 | Source 下一块前停止;已有字节继续到达并落盘;同 socket start;最终内容和真实 ACK 正确 | | 高水位与用户 start 交叉 | 不越过本地内存硬门槛,不误将自动背压释放当用户 start | -| 转发 resume 到达时上游仍在线/暂停/EOF等待 | 安全 teardown 原 route 数据腿、清空旧内存、旧 owner 完成后重建;无双 sender/双 writer | -| 多目标 offset 不同 | 各目标从各自实际落盘 offset 恢复,内容一致;完成目标不重传;失败/离线目标不被标成功 | +| 转发 resume 到达时原上游/兄弟仍在线、暂停、握手、EOF/ACK等待或 finalizing | 原活跃 socket/owner 不被中断;最后一个原 owner 含 finally 收尾后才建恢复流;控制线程仍可处理消息 | +| 多 Target 不同 offset、部分完成、晚到请求、A 正文/ACK 阻塞 | 各自实际 offset、独立流/进度/资源;B 在 A 正文/ACK 未完成时可建流并传输;仅 socket+fid 端口握手短串行;完成目标不重传 | +| Source/Target 断线及单 Target 失败 | Source 离线保留 pending;Target 断线丢旧 socket pending,新会话用新实际 offset 重发;单流失败不打断兄弟、不自动重试 | | offset 为零/EOF、最终 ACK 再次失败 | 不误清恢复记录;确认失败可再次恢复;成功清理所属记录 | | Client 自转发与本机不同 Client | 拒绝自身完整控制端点,允许同 host 不同端口;统一入口覆盖 console/Web/文件夹/恢复 | | 加密、密钥交换窗口、线程式/async Server | 统一 send/receive 路径;无明文降级;不阻塞密钥接收线程;真实内容、ACK、资源收尾 | @@ -94,12 +95,12 @@ ## 数据、安全和范围约束 - 所有 peer 身份由实际控制会话及现有端点规则确定,不按 fid 全局猜路由。 -- 校验在 teardown 前完成;控制请求走现有加密就绪及 send_message 入口。 -- 只清理所属 route 的内存和数据 socket,不关闭无关控制连接、其他 fid 或删除已落盘字节。 +- 入队前校验实际会话和 route;控制请求走现有加密就绪及 send_message 入口,不靠 fid 全局猜路由,不把旧待处理请求借给新 Target socket。 +- 恢复入队不关闭任何活跃数据腿、健康控制连接或其他 fid,不删除接收文件;仅自然结束的旧 owner 做原有定向收尾。 - 不把 socket 仍打开或 offset 等于 size 单独作为成功证据。 -- pause/start 和端口响应格式、Python pause/start 签名及持久化模型不变;不新增 leg_id 或恢复换新 fid。全局暂停、转发强制恢复及 offset 查询仍改变原契约,不能声称全部向后兼容。 -- 风险等级:高(协议、并发、文件恢复完整性)。当前仅授权推进至 C2;后续阶段仍须逐项人工放行,不自动提交、合并或推送。 +- pause/start、端口响应、公开 Python 签名及持久化模型不变;不新增 wire 字段、leg_id 或恢复换新 fid。恢复 parser/formatter 只接受数值 offset;调度改为等待原 route 旧 owner 全收尾、每 Target 独立并行恢复。 +- 风险等级:高(多 owner 并发、全局控制共享、文件完整性和真实 ACK 聚合)。本轮实施及分次局部验证已记录;不宣称 C6 总验收通过,不自动提交、合并或推送。 ## 下一阶段闸门 -行为选择保持不变:暂缓问题二,保持稳定 fid 和既有控制/端口格式。用户已授权开始 C2;本阶段完成后交付运行证据和局部报告供人工审查,未经后续放行不开始 C3–C6。 +本轮 C3 替代方案的实现、局部命令及真实传输证据已交付[实施报告](transfer-control-lifecycle-report.md),等待人工审查。C1/C2 保留;旧 C3a/C3b 查询/强制 teardown/串行轮次仅作撤回历史。C4 EOF 再确认、C5 自目标拒绝及 C6 总体验收未实现,不因本轮完成自动推进。 diff --git a/docs/source/File_Transfer/File_Transfer.rst b/docs/source/File_Transfer/File_Transfer.rst index 881d44f..19ec730 100644 --- a/docs/source/File_Transfer/File_Transfer.rst +++ b/docs/source/File_Transfer/File_Transfer.rst @@ -944,8 +944,8 @@ keep ``relays`` empty; nonempty older client relay metadata is rejected and its file preserved, including on shutdown. Five-item upload/download values remain unchanged. The source recovers a forwarded file from its upload path alone; directory/destination metadata is not duplicated because the target retains -its full receive path. Per-upload locks and in-flight target sets are transient -and released after use, not persisted. +its full receive path. Per-Target recovery owners and stream progress are +transient; the task upload row and relay snapshot schema remain unchanged. Targets accepted after reachability filtering remain in the mapping even if their listener or start handshake fails. A successful target loses its reverse @@ -960,17 +960,50 @@ timeout or a lost ACK conservatively retains the source upload progress, even if the server completed delivery. No separate receipt or retry protocol is used. If a target cannot send its final ACK, its receive entry survives even when the disk file is complete; an EOF replay with the same fid -can confirm it without retransmitting the body. A shared upstream fid admits -one recovery owner at a time. Running, paused, negotiating or finalizing -source/relay owners reject another request without queueing or tearing down -the live relay. A disconnected target must request again after that owner -exits; one skipped request does not promise eventual automatic replay. -Completed targets are not replayed. If the source is offline and no relay is -live, the server retains the latest offset per upstream fid/target. Reconnect -revalidates and reserves one eligible replay through the secure control path; -failed writes retain pending requests, and completed or missing routes are -pruned. Other independent fids remain eligible. Receive requests/listeners -retain per-object ownership through final cleanup, including tracking off. +can confirm it without retransmitting the body. + +A validated forwarded receive request carries a nonnegative numeric offset +read from the actual file after its old receive owner, including ``finally``, +has exited and closed the file. Server validates the actual Target control +socket, origin, target and child route, and retains that socket and offset. +There is no Server offset query, ``?`` offset or ``offset=None`` value. + +If the original route still has an upstream/downstream data leg, listener, +negotiation, reader/writer or finalizing owner, Server only queues the request. +It does not tear down live legs or release user pause. Recovery starts after +all original route owners, including final resource cleanup, have naturally +finished; a closed socket alone is not that boundary. The wait is route-scoped +and off the control reader/event loop, without holding a global lock. Healthy +control sessions and unrelated fids continue. + +After that boundary, each unfinished Target has its own numeric offset, +Source-to-Server-to-Target stream, runtime progress, resource ownership and +failure handling. Original upstream/child fids and full receive paths stay +stable; old relay queues are not reused. Recovery bodies run concurrently: +a late Target can start while another is sending a large body or waiting for +its final ACK. Only port negotiation on the same actual control socket plus +fid is briefly serialized; that lock never covers body transfer or final ACK. +Duplicate requests cannot create two active owners for the same Target. + +Source remains the global user pause/start arbiter across these streams. +Their task control state stays alive until its last owner exits. Server +writers drain buffered bytes during pause, and user start cannot bypass local +backpressure. A Target's real final ACK updates only that Target's completion; +it cannot synthesize a whole-route ACK. The Source upload row and Server route +remain until all accepted Targets have real ACK evidence and the existing +final upstream ACK succeeds. Already-confirmed Targets are not replayed. + +An offline Source leaves valid requests pending. A disconnected Target loses +requests bound to its old control socket; after reconnect it waits for old +receive cleanup and submits a fresh actual disk offset on its new socket. +No stale request is borrowed by a replacement session. One stream's failure +does not cancel siblings or start an automatic retry loop. Existing retained +rows can recover with tracking off, but no new recovery rows are fabricated. + +All-Target completion followed by a failed upstream ACK remains retained; +the separate EOF reconfirmation lifecycle stage is not implemented here. +Delayed pause/start across same-session, same-fid data-leg replacement is +also explicitly deferred; no generation-isolation guarantee is added. Fids no longer encode a plain/relay kind: the reserved low bit is always zero, and diagnostics use ``e.``. Ordinary senders own their FIDs; the relay source owns the upstream FID and the Server allocates one child FID @@ -981,9 +1014,9 @@ ACK. After reconnect, the server requests that peer's eligible interrupted downloads, and the client runs the same per-object request pass. Manual recovery can use the existing control connection; a data-only failure does not start a new retry -loop. There is no wildcard-FID or public resume-all command. Existing owners -finish cleanup before automatic recovery; busy shared relays follow the skip -rule above rather than promising completion from one reconnect request. +loop. There is no wildcard-FID or public resume-all command. Ordinary owners +must finish cleanup before recovery; forwarded requests wait for the original +route's complete old-owner cleanup, then use independent parallel streams above. .. _related-apis: diff --git a/docs/source/Network_APIs/TCP_Client_APIs.rst b/docs/source/Network_APIs/TCP_Client_APIs.rst index d87295d..d3640c7 100644 --- a/docs/source/Network_APIs/TCP_Client_APIs.rst +++ b/docs/source/Network_APIs/TCP_Client_APIs.rst @@ -310,13 +310,30 @@ commands sent by the server, such as: supplies the source path; a non-server target is replayed through the server with its stable upstream fid. The receiver's retained full path handles folder items without copying directory or destination metadata at the source. - Both direct and relay uploads recover only when no live, paused, negotiating - or finalizing source owner holds that object. ``resume_trans`` returns ``True`` - for a newly reserved worker; busy and duplicate calls return ``False`` without - closing or queueing. A shared upstream FID cannot replay for a second target - until its previous owner exits; the skipped request must be issued again. - Another file or opposite direction does not prevent recovery. A paused live - connection continues through ``start_trans`` instead. + Public ``resume_trans`` calls return ``True`` for a newly reserved worker; + busy and duplicate calls return ``False`` without closing the owner. Use + ``start_trans`` for a paused live connection. Receiver requests wait for old + receive cleanup, including ``finally`` and file closure, then read the actual + disk size. Offsets are nonnegative integers only; there is no ``?`` query or + ``None`` parser/formatter offset. + For forwarded recovery, Server first waits for every old owner of the + original route to finish naturally, without forced teardown. It then directs + independent per-Target Source-to-Server-to-Target streams using each actual + offset. Each has its own progress, resources and failure handling; one body + or final ACK cannot block another Target, including a late arrival. Only + port negotiation on the same actual Server socket plus fid is briefly + serialized, not body transfer or final ACK. Workers retain their admitted + control socket; stable fids, paths and persistence schema do not change. + Source arbitrates global pause/start for all live task owners; the final + owner releases shared control state. A real Target ACK marks only that + Target; no intermediate stream fabricates a whole-route ACK or deletes the + Source task row. All accepted Targets must really acknowledge for task + success. Source disconnection leaves requests queued at Server; Target + disconnection discards its old-socket request and requires a new actual disk + offset after reconnect. There is no automatic retry, and one Target's failure + does not cancel siblings. Strict same-session/fid generation isolation is + deferred; all-Target upstream EOF reconfirmation (C4), self-target rejection + (C5) and combined acceptance (C6) are not implemented by this revision. For a new relay upload, the source client allocates the upstream FID before it sends ``/forward_item ... fid=``. The server returns that same upstream FID diff --git a/docs/source/Network_APIs/TCP_Server_APIs.rst b/docs/source/Network_APIs/TCP_Server_APIs.rst index 680e984..a2ba70e 100644 --- a/docs/source/Network_APIs/TCP_Server_APIs.rst +++ b/docs/source/Network_APIs/TCP_Server_APIs.rst @@ -705,11 +705,30 @@ Built-in client commands include: for a newly reserved worker; busy and duplicate calls return ``False`` without closing or queueing. Other objects remain independent. Use ``start_trans`` to continue an existing paused connection. - Forwarded recovery also requires its shared source/relay owner to be idle, - even when the requesting target has disconnected. Busy requests are skipped, - not queued; the target must request again after cleanup. An offline source's - existing pending requests are retained and revalidated at reconnect, with - one upstream reservation. No active relay is torn down to make it eligible. + A valid forwarded receive request instead records the actual Target control + socket and nonnegative numeric disk offset, read after its old receive owner + and file have closed. No ``?`` query or ``None`` offset is supported. + Server waits for all old owners of that original route, including listeners, + negotiations, reader/writers and ``finally``, to finish naturally. It does + not force teardown, start a paused route, wait on unrelated fids or block the + control reader/event loop while holding a global lock. + It then opens an independent Source-to-Server-to-Target stream per Target, + preserving upstream/child fids, full paths and persistence schema. Offsets, + runtime progress, resources and failures are independent. Bodies run in + parallel; a late Target does not wait for another body or final ACK. Only + port negotiation on the same actual control socket plus fid is briefly + serialized, never the body or ACK wait. One Target has at most one active + recovery owner; completed Targets are not resent. + Source remains the global pause/start arbiter; shared control state is + released only by its last owner. Backpressure remains independent of user + start. Offline Source requests stay pending. A Target disconnect drops its + old-socket pending request; its new session must submit a fresh actual disk + offset after old receive cleanup. One stream's failure does not cancel + siblings or automatically retry. A real Target ACK updates only its own + completion; intermediate success cannot fabricate an overall route ACK. + Strict same-session/fid generation isolation remains deferred. C4 all-Target + upstream EOF reconfirmation, C5 self-target rejection and C6 combined + acceptance are not implemented by this revision. - Forwarded transfers return the existing final data-ACK marker upstream only after the current input stream is complete and every accepted target has acknowledged. The normal send path reframes the marker for the upstream hop; diff --git a/docs/source/changes/transfer-fid-routes.md b/docs/source/changes/transfer-fid-routes.md index 3e51886..ec7ee7b 100644 --- a/docs/source/changes/transfer-fid-routes.md +++ b/docs/source/changes/transfer-fid-routes.md @@ -1,13 +1,47 @@ # Change note: server FID routes, sender ownership and socket/FID recovery -> Previous transfer-control revision: C1–C4b are committed and have passed their -> stage review gates; C5 documentation and combined acceptance are complete, -> pending final human review. -> The chronological entries below preserve earlier implementation history; -> C2b supersedes the old pause/start API and wire format, and C4a/C4b supersede -> queued/coalesced active recovery and immediate sweep ownership release. -> Current behavior and evidence are in -> `docs/plans/transfer-pause-start-direction-report.md`. +> Current lifecycle revision evidence is in +> `docs/plans/transfer-control-lifecycle-report.md`. +> The chronological entries below preserve earlier implementation history. +> Previous transfer-control C1–C4b commits and C5 acceptance are documented in +> `docs/plans/transfer-pause-start-direction-report.md`; those historical +> results are not verification of the current lifecycle revision. + +## Lifecycle revision C3: numeric offsets and independent parallel recovery + +- The user approved the revised requirements and plan. Old C3a/C3b offset + queries, forced route teardown and one-active-Target/FIFO rounds are withdrawn + history, not the current contract or current verification evidence. +- Receiver waits for its old owner, including final cleanup and file closure, + then sends its actual nonnegative numeric disk offset. The sole resume line + remains `/resume_trans `; remove `?` queries, + `offset=None` and query state/consumers without adding wire fields or commands. +- Server validates the actual Target socket and stable child route, queues the + numeric request and waits for every old owner of the original route, including + listeners, negotiations, reader/writers and `finally`, to finish naturally. + No forced teardown, automatic start, global-lock wait or control-reader/event- + loop blocking; healthy control and unrelated fids continue. +- Then each Target gets its own offset, Source→Server→Target stream, runtime + progress, resources and failure handling. Original upstream/child fids, full + paths and persistence schema remain. Bodies run in parallel: late Targets do + not wait for an existing large body or ACK. The same actual socket+fid only + serializes short port negotiation, never body transfer or final ACK. +- C1 actual-session ownership and C2 Source-arbitrated global pause/start remain. + Shared task control state lives until its last owner exits; buffered bytes + drain and user start cannot bypass local backpressure. One stream cannot + overwrite sibling progress or prematurely delete the task upload row. +- Only real Target ACKs update `completed`. All accepted Targets must really + acknowledge before task success; an intermediate Target cannot fabricate a + whole-route ACK. Completed siblings are not replayed. +- Offline Source requests stay pending. Target disconnection discards old-socket + requests; reconnect requires a fresh actual disk offset on the new session. + Individual failure does not cancel siblings or start automatic retries. +- Strict same-session/fid generation isolation remains deferred. C4 all-Target + upstream EOF reconfirmation, C5 self-target rejection and C6 combined acceptance + are not implemented. No new wire, schema, dependencies or CI changes. +- This round is **pending unified verification**. Old C3a/C3b pass counts do not + verify this replacement. Paths, risks and historical evidence are recorded in + `docs/plans/transfer-control-lifecycle-report.md`. ## Lifecycle revision C2: Source-arbitrated global relay pause diff --git a/test/integration/network_api/test_tcp_transfer_control.py b/test/integration/network_api/test_tcp_transfer_control.py index 33ad697..b912d97 100644 --- a/test/integration/network_api/test_tcp_transfer_control.py +++ b/test/integration/network_api/test_tcp_transfer_control.py @@ -878,17 +878,18 @@ def test_disconnected_relay_target_cannot_queue_behind_live_source(relay_clients [0, len(payload), None, str(tmp_path / "relay.bin"), first]) assert _control(source, sender, True) _confirmed((sender, relay["upstream"]), True) - assert source.resume_trans(second, fid, 0) is False + assert targets[1]._request_resumes() == 0 # A live local receiver cannot request recovery. targets[0].close() assert wait_until(lambda: first not in server.clients and relay["controls"][first]["owner"].fileno() < 0) assert server._resume_request(control, first, route["targets"][first], 0, origin, first) is False - assert server._queue_resume_to_originator(fid, route, first, 1) is False - assert source.resume_trans(first, fid, 0) is False - assert not server._pending_originator_resumes + assert server._queue_resume_to_originator(fid, route, first, 1, control_socket=control) is False + assert targets[1]._request_resumes() == 0 + assert not server._relay_recoveries assert server._receive_transfers[fid]["owner"] is relay assert sender["owner"] is sockets[0] and sockets[0].fileno() >= 0 assert relay["controls"][second]["owner"] is sockets[-1] and sockets[-1].fileno() >= 0 - assert worker.is_alive() and result == {} and not source._resume_sends.get(sender["key"][:2], {}).get("targets") + assert worker.is_alive() and result == {} + _confirmed((sender, relay["upstream"], relay["controls"][second]), True) assert _control(source, sender, False) _relay_done(relay_clients, run, failed=True) assert all(sock.fileno() < 0 for sock in sockets) @@ -896,6 +897,198 @@ def test_disconnected_relay_target_cannot_queue_behind_live_source(relay_clients and not owner._resume_sends for owner in (server, source, *targets))) +def test_parallel_recoveries_wait_for_old_owner_and_share_source_pause( + relay_clients, tmp_path, monkeypatch +): + server, source, targets, releases = relay_clients + # The untracked variant starts with legacy receive rows; retaining the same + # real row lets the original receiver own and update its partial file. + for target in targets: + real_progress = target._file_progress_start + + def progress(store, transfer_id, size, path, peer=None, initial=0, + start=real_progress): + return start(store, transfer_id, size, path, peer, initial) or store.setdefault( + transfer_id, [initial, size, None, str(path), peer]) + + monkeypatch.setattr(target, "_file_progress_start", progress) + writes = [_observe_target_writes(monkeypatch, Path(target.file_transfer_dir) / "relay.bin", 1024) + for target in targets] + raw_wait = connect_tcp._wait_transfer_control + run = _relay(relay_clients, tmp_path, monkeypatch) + relay, sender, gates, worker, result, payload, observed, _ = run + fid, route = relay["fid"], relay["route"] + origin = source.client_socket.getsockname() + addresses = [target.client_socket.getsockname() for target in targets] + old_receive = server._receive_transfers[fid] + old_sockets = [sender["owner"], relay["upstream"]["owner"], + *(relay["controls"][address]["owner"] for address in addresses)] + source.file_upload_progress.setdefault(sender["key"][:2], + [0, len(payload), None, str(tmp_path / "relay.bin"), addresses[0]]) + for target, address in zip(targets, addresses): + target.file_recv_progress.setdefault(route["targets"][address], + [0, len(payload), None, str(Path(target.file_transfer_dir) / "relay.bin"), origin]) + partial = [threading.Event() for _ in targets] + interrupt, cleaning, cleaned = (threading.Event() for _ in range(3)) + releases.extend((interrupt, cleaned)) + real_send, real_release = server.send_message, connect_tcp._release_receive + + def hold_payload(sock, message, is_send_raw=False): + sent = real_send(sock, message, is_send_raw=is_send_raw) + for index, address in enumerate(addresses): + if sock is relay["controls"][address]["owner"] and message == payload[:1024]: + partial[index].set() + assert interrupt.wait(timeout=30), "old target writer was not released" + return sent + + def hold_cleanup(instance, key, record): + if instance is server and key == fid and record is old_receive: + cleaning.set() + assert cleaned.wait(timeout=30), "old route cleanup was not released" + return real_release(instance, key, record) + + monkeypatch.setattr(server, "send_message", hold_payload) + monkeypatch.setattr(connect_tcp, "_release_receive", hold_cleanup) + for gate in gates: + gate.set() + assert all(event.wait(timeout=15) for event in partial) + assert all(event.wait(timeout=10) for _, event in writes) + assert all(written == payload[:1024] for written, _ in writes) + controls = [server.clients[address]["socket"] for address in addresses] + first, second = addresses + assert server._resume_request(controls[0], first, route["targets"][first], 1024, origin, first) + recovery = server._relay_recoveries[fid] + assert recovery["pending"] == {first: (controls[0], 1024)} and not recovery["active"] + assert server._receive_transfers[fid] is old_receive and old_receive["owner"] is relay + assert all(sock.fileno() >= 0 for sock in old_sockets) + assert worker.is_alive() and result == {} + receiver = targets[0]._transfer_controls._legs[((source.host, source.port), route["targets"][first], 1, 1)] + assert _control(targets[0], receiver, True) + _confirmed((sender, relay["upstream"], *relay["controls"].values()), True) + assert server._resume_request(controls[1], second, route["targets"][second], 1024, origin, second) + assert recovery["pending"] == dict(zip(addresses, ((control, 1024) for control in controls))) + assert not recovery["active"] + assert server._receive_transfers[fid] is old_receive + assert all(sock.fileno() >= 0 for sock in old_sockets) + _confirmed((sender, relay["upstream"], *relay["controls"].values()), True) + + streams, local = {}, threading.local() + inherited_wait = connect_tcp._wait_transfer_control + real_condition_wait = source._transfer_pause_cond.wait + real_source_send = source.send_message + + def hold_recovery(instance, state, sock): + if instance is source and state is not None and state["key"] == sender["key"] and state is not sender: + stream = streams.get(sock) + if stream is None: + stream = {name: threading.Event() for name in ("entered", "gate", "blocked", "passed", "written")} + stream["writes"] = [] + streams[sock] = stream + releases.append(stream["gate"]) + stream["entered"].set() + assert stream["gate"].wait(timeout=30), "recovery body gate was not released" + local.socket = sock + try: + raw_wait(instance, state, sock) + finally: + del local.socket + stream["passed"].set() + return + return inherited_wait(instance, state, sock) + + def observe_pause_wait(timeout=None): + sock = getattr(local, "socket", None) + if sock is not None: + streams[sock]["blocked"].set() + return real_condition_wait(timeout) + + slow = {"socket": None} + slow_entered, slow_release = threading.Event(), threading.Event() + releases.append(slow_release) + + def observe_source_write(sock, message, is_send_raw=False): + if sock is slow["socket"] and message == payload[1024:2048]: + slow_entered.set() + assert slow_release.wait(timeout=30), "slow recovery writer was not released" + sent = real_source_send(sock, message, is_send_raw=is_send_raw) + if sock in streams and isinstance(message, bytes) and sent: + streams[sock]["writes"].append(message) + streams[sock]["written"].set() + return sent + + monkeypatch.setattr(connect_tcp, "_wait_transfer_control", hold_recovery) + monkeypatch.setattr(source._transfer_pause_cond, "wait", observe_pause_wait) + monkeypatch.setattr(source, "send_message", observe_source_write) + assert _control(source, sender, False) + _confirmed((sender, relay["upstream"]), False) + sender["owner"].shutdown(socket.SHUT_RDWR) + observed["tail"].set() + interrupt.set() + assert cleaning.wait(timeout=15) + worker.join(timeout=10) + assert not worker.is_alive() and result == {"ack": False} + assert wait_until(lambda: all(not target._receive_transfers for target in targets)) + assert all(target.file_recv_progress[route["targets"][address]][0] == 1024 + and (Path(target.file_transfer_dir) / "relay.bin").read_bytes() == payload[:1024] + for target, address in zip(targets, addresses)) + assert server._receive_transfers[fid] is old_receive + assert not recovery["active"] and set(recovery["pending"]) == set(addresses) + assert not streams + cleaned.set() + assert wait_until(lambda: len(streams) == 2 and all(stream["entered"].is_set() for stream in streams.values()), + timeout=20) + assert set(recovery["active"]) == set(addresses) and not recovery["pending"] + assert fid not in server._receive_transfers + replacements = [server._receive_transfers[(address, fid)]["owner"] for address in addresses] + assert replacements[0] is not replacements[1] + assert all(replacement["route"] is route and set(replacement["controls"]) == {address} + for address, replacement in zip(addresses, replacements)) + new_sender = source._transfer_controls._legs[sender["key"]] + assert set(new_sender["owners"]) == set(streams) + assert replacements[0]["upstream"] is replacements[1]["upstream"] + assert len(replacements[0]["upstream"]["owners"]) == 2 + slow["socket"] = source._active_transfer_sockets[(first, fid)] + assert source._transfer_controls.release(sender) is False + connect_tcp._release_receive(server, fid, old_receive) + assert all(server._receive_transfers[(address, fid)]["owner"] is replacement + for address, replacement in zip(addresses, replacements)) + receiver_states = [target._transfer_controls._legs[ + ((source.host, source.port), route["targets"][address], 1, 1)] + for target, address in zip(targets, addresses)] + states = (new_sender, *(replacement["upstream"] for replacement in replacements), + *(replacement["controls"][address] for address, replacement in zip(addresses, replacements)), + *receiver_states) + _confirmed(states, False) + assert _control(targets[0], receiver_states[0], True) + _confirmed(states, True) + for stream in streams.values(): + stream["gate"].set() + assert all(stream["blocked"].wait(timeout=10) for stream in streams.values()) + assert all(not stream["passed"].is_set() and not stream["writes"] for stream in streams.values()) + assert _control(targets[1], receiver_states[1], False) + assert slow_entered.wait(timeout=15) + assert wait_until(lambda: second in route["completed"] + and (second, fid) not in source._active_transfer_sockets + and (second, fid) not in source._resume_sends + and (second, fid) not in server._receive_transfers, timeout=20) + assert first not in route["completed"] + assert source._transfer_controls._legs[sender["key"]] is new_sender + assert new_sender["owners"] == {slow["socket"]} and new_sender["owner"] is slow["socket"] + assert server._receive_transfers[(first, fid)]["owner"] is replacements[0] + assert server._transfer_controls._legs[replacements[0]["upstream"]["key"]] is replacements[0]["upstream"] + assert len(replacements[0]["upstream"]["owners"]) == 1 + slow_release.set() + assert all(stream["written"].wait(timeout=15) for stream in streams.values()) + assert all(stream["passed"].is_set() and stream["writes"][0] == payload[1024:2048] + for stream in streams.values()) + assert wait_until(lambda: not server._relay_recoveries and not server._forward_relays and all( + not owner._transfer_controls._legs and not owner._transfer_pause + and not owner._active_transfer_sockets and not owner._receive_transfers + and not owner._resume_sends for owner in (server, source, *targets)), timeout=20) + assert not server._fid_routes and not server._fid_route_index + assert all((Path(target.file_transfer_dir) / "relay.bin").read_bytes() == payload for target in targets) + + @pytest.mark.parametrize("fault", ["source", "stop"]) def test_relay_offline_source_replays_stable_route_or_stops_cleanly( relay_clients, tmp_path, monkeypatch, fault @@ -997,9 +1190,10 @@ def hold(instance, state, sock): return assert output.read_bytes() == payload[:1024] request_control = server.clients[first]["socket"] - assert server._resume_request(request_control, first, child, 0, origin, first) is False - assert server._resume_request(request_control, first, child, 1024, origin, first) is False - assert server._pending_originator_resumes == {origin: {(fid, first): 1024}} + assert server._resume_request(request_control, first, child, 1024, origin, first) is True + recovery = server._relay_recoveries[fid] + assert recovery["pending"] == {first: (request_control, 1024)} + assert recovery["route"] is route and not recovery["active"] calls, real_forward = [], source._forward_one def forward(*args, **kwargs): @@ -1023,10 +1217,11 @@ def forward(*args, **kwargs): server._transfer_controls.discard_socket(old_server) connect_tcp._release_receive(server, fid, old_receive) connect_tcp._release_receive(targets[0], child, old_target_receive) - assert server._receive_transfers[fid]["owner"] is replacement + assert server._receive_transfers[(first, fid)]["owner"] is replacement assert child in targets[0]._receive_transfers and source._transfer_controls._legs[sender["key"]] is new_sender assert server._flush_pending_originator_resumes(origin) == 0 assert source.resume_trans(first, fid, 1024) is False + assert first in recovery["active"] and not recovery["pending"] finish.set() assert wait_until(lambda: calls == [(fid, 1024, True)], timeout=20) assert output.read_bytes() == payload and not server._fid_routes and not server._fid_route_index @@ -1034,7 +1229,7 @@ def forward(*args, **kwargs): not owner._transfer_controls._legs and not owner._transfer_pause and not owner._active_transfer_sockets and not owner._receive_transfers and not owner._resume_sends for owner in (server, source, *targets))) - assert not server._pending_originator_resumes + assert not server._relay_recoveries def test_reconnect_keeps_delayed_forward_resume_on_its_old_session(channel, tmp_path, monkeypatch): @@ -1060,6 +1255,8 @@ def delayed(*args, **kwargs): monkeypatch.setattr(client, "_forward_one", delayed) assert client.resume_trans(target, fid, 0) assert entered.wait(10) + assert set(client._resume_sends) == {(target, fid)} + assert client._resume_sends[(target, fid)]["control_socket"] is old_control assert client.connect(), "new control reader must not wait for the old worker" new_control = client.client_socket assert new_control is not old_control diff --git a/test/integration/network_api/test_tcp_transfer_resume.py b/test/integration/network_api/test_tcp_transfer_resume.py index effac22..31c4c37 100644 --- a/test/integration/network_api/test_tcp_transfer_resume.py +++ b/test/integration/network_api/test_tcp_transfer_resume.py @@ -8,6 +8,8 @@ session or loaded from the persisted file exactly as a disconnect leaves it. """ +import builtins +import hashlib import json import os import shlex @@ -1480,6 +1482,7 @@ def test_forward_ack_loss_retains_state_and_resumes_original_ids( clients = [] release_ack = threading.Event() resume_ack = threading.Event() + resume_requests = [] try: source = _start_client(tmp_path, server, name="source") clients.append(source) @@ -1563,15 +1566,14 @@ def observe_forward(*args, **kwargs): return result monkeypatch.setattr(source, "_forward_one", observe_forward) - resume_requests = [] - real_resume = source.resume_trans + real_resume = source._resume_on_socket - def observe_resume(target, fid, offset): - result = real_resume(target, fid, offset) + def observe_resume(target, fid, offset, control_socket, **kwargs): + result = real_resume(target, fid, offset, control_socket, **kwargs) resume_requests.append((target, fid, offset)) return result - monkeypatch.setattr(source, "resume_trans", observe_resume) + monkeypatch.setattr(source, "_resume_on_socket", observe_resume) upstream_acks = [] terminal_controls = [] source_control = server.clients[source_addr]["socket"] @@ -1627,24 +1629,23 @@ def observe_upstream_ack(sock, message, is_send_raw=False): assert target.file_recv_progress == {} assert dispatches == [(addr, original_targets[addr]) for addr in target_addrs] + for addr in failed: + losing_ack[addr] = False for index, addr in enumerate(failed): target = receivers[target_addrs.index(addr)] child_fid = original_targets[addr] - losing_ack[addr] = False - # The receiver discovers the disk offset using its normal reconnect - # path. Its live receive owner rejects another request at the ACK gate. assert target._request_resumes() == 1 if index == 0: assert resume_ack.wait(timeout=10) assert len(calls) == 2 assert source.file_upload_progress[upload_key][0:2] == [len(payload), len(payload)] - assert source.file_upload_progress[upload_key][3:] == [str(src), addr] + assert source.file_upload_progress[upload_key][3:] == [str(src), target_addrs[0]] # Removing a stale active marker cannot bypass the listener owner. target._active_transfer_fids.discard(child_fid) assert target._request_resumes() == 0 assert resume_requests == [(addr, fid, len(payload))] assert len(calls) == 2, "a duplicate resume started another upload" - assert source._resume_sends[upload_key]["targets"] == {addr} + assert source._resume_sends[(addr, fid)]["targets"] == {addr} release_ack.set() assert wait_until(lambda: len(outcomes) == index + 2, timeout=10) assert wait_until(lambda: not server._forward_relays and not server._receive_transfers @@ -1981,12 +1982,16 @@ def observe_resume(client_socket, peer, requested_fid, offset, origin, target): ) assert wait_until(lambda: len(handled) == 2, timeout=10) assert set(handled) == {(good_addr, bad_fid, 0), (bad_addr, unknown_fid, 0)} - assert server._pending_originator_resumes == {} + assert server._relay_recoveries == {} assert bad.send_message( bad.client_socket, format_resume_line(bad_fid, 0, source_addr, bad_addr) ) assert wait_until(lambda: len(handled) == 3, timeout=10) - assert server._pending_originator_resumes == {source_addr: {(fid, bad_addr): 0}} + recovery = server._relay_recoveries[fid] + assert recovery["route"] is route and recovery["active"] == {} + assert recovery["pending"] == {bad_addr: (server.clients[bad_addr]["socket"], 0)} + assert server._fid_route_index == expected_index + assert route["completed"] == {good_addr} assert server._fid_routes[fid] is route finally: refused_listener.close() @@ -2458,106 +2463,299 @@ def test_download_resumes_after_connect_without_a_manual_call(tmp_path): server.stop() -def test_unified_resume_serializes_distinct_offsets_without_local_fid_fallback(tmp_path, monkeypatch): - """Busy recovery skips targets until the old source owner fully exits.""" +@pytest.mark.parametrize("late_second_request", [False, True], ids=["queued-together", "late-target"]) +@pytest.mark.parametrize("fail_first_again", [False, True], ids=["both-finish", "first-fails-again"]) +def test_forward_recovery_waits_for_old_finally_and_runs_targets_independently( + tmp_path, monkeypatch, late_second_request, fail_first_again +): + """Real independent bodies/ACKs survive a held or failed sibling and old cleanup.""" workers = _track_socket_workers(monkeypatch) server = _start_server(tmp_path) clients = [] - held = threading.Event() - release = threading.Event() + original_held, original_release = threading.Event(), threading.Event() + finally_held, finally_release = threading.Event(), threading.Event() + first_held, first_release = threading.Event(), threading.Event() + second_written, second_ack = threading.Event(), threading.Event() + second_body_held, second_body_release = threading.Event(), threading.Event() + local = threading.local() try: - source = _start_client(tmp_path, server, name="queued_source") + source = _start_client(tmp_path, server, name="parallel_source") clients.append(source) - receivers, outputs = [], [] - payload = os.urandom(96 * 1024 + 19) - src = tmp_path / "queued.bin" + source.file_transfer_chunk_len = server.file_transfer_chunk_len = 8192 + payload = os.urandom(128 * 1024 + 29) + digest = hashlib.sha256(payload).digest() + src = tmp_path / "parallel_recovery.bin" src.write_bytes(payload) - source_addr = source.client_socket.getsockname() - offsets = [12345, 54321] - for index, offset in enumerate(offsets): - recv_dir = tmp_path / f"queued_{index}" - recv_dir.mkdir() - target = _start_client(tmp_path, server, name=f"queued_{index}", recv_dir=recv_dir) + receivers, outputs = [], [] + for index in range(2): + directory = tmp_path / f"parallel_target_{index}" + directory.mkdir() + target = _start_client( + tmp_path, server, name=f"parallel_target_{index}", recv_dir=directory + ) + target.file_transfer_chunk_len = 8192 clients.append(target) receivers.append(target) - output = recv_dir / "original/nested" / src.name - output.parent.mkdir(parents=True) - output.write_bytes(payload[:offset]) - target.file_recv_progress[502 + index * 2] = [ - offset, len(payload), None, str(output), source_addr, - ] - outputs.append(output) - first, second = receivers - first_addr, second_addr = [target.client_socket.getsockname() for target in receivers] - assert wait_until(lambda: all(peer in server.clients for peer in ( - source_addr, first_addr, second_addr - ))) - route = server._register_fid_route(500, source_addr, {first_addr: 502, second_addr: 504}) - key = ((source.host, source.port), 500) - source.file_upload_progress[key] = [0, len(payload), None, str(src), first_addr] - local_path = tmp_path / "unrelated.bin" - local_path.write_bytes(b"unrelated local upload") - local_row = [0, local_path.stat().st_size, None, str(local_path), first_addr] - server.file_upload_progress[(first_addr, 502)] = local_row - original_send = first.send_message - original_mode = source.file_transfer_mode - transfers = [] - def hold_ack(sock, message, is_send_raw=False): - if message == first.server_received_file_data_sign: - held.set() - assert release.wait(timeout=10) - return original_send(sock, message, is_send_raw=is_send_raw) + outputs.append(directory / "original/nested" / src.name) + origin = source.client_socket.getsockname() + targets = [target.client_socket.getsockname() for target in receivers] + assert wait_until(lambda: all(peer in server.clients for peer in [origin, *targets])) + controls = {peer: server.clients[peer]["socket"] for peer in [origin, *targets]} + client_controls = [owner.client_socket for owner in (source, *receivers)] + forwards, outcomes, dispatches, opened, reads, source_files = [], [], [], [], [], [] + source_sockets, handled, target_acks, upstream_acks = {}, [], [], [] + initial = {} + offsets = [8192, 3 * 8192] + real_wait = connect_tcp._wait_transfer_control + real_open_target = connect_tcp._open_transfer_target + real_release = connect_tcp._release_receive + real_forward, real_dispatch = source._forward_one, server.forward_item_to + real_resume_request = server._resume_request + real_server_send = server.send_message - def observe_mode(*args, **kwargs): - transfers.append((kwargs.get("fid"), kwargs.get("resume_offset", 0))) - return original_mode(*args, **kwargs) + def hold_body(instance, state, sock): + if instance is source: + peer, offset = getattr(local, "stream", (None, 0)) + if peer is None: + initial.setdefault("socket", sock) + initial["waits"] = initial.get("waits", 0) + 1 + if initial["waits"] == 4: + original_held.set() + assert original_release.wait(timeout=30) + else: + source_sockets.setdefault((peer, offset), sock) + if peer == targets[0] and offset == offsets[0]: + first_held.set() + assert first_release.wait(timeout=30) + if fail_first_again: + sock.shutdown(socket.SHUT_RDWR) + sock.close() + raise ConnectionError("the first recovery data connection failed again") + if peer == targets[1] and fail_first_again: + second_body_held.set() + assert second_body_release.wait(timeout=30) + return real_wait(instance, state, sock) + + def source_open(path, mode="r", *args, **kwargs): + file = builtins.open(path, mode, *args, **kwargs) + if str(path) == str(src) and mode == "rb": + stream = getattr(local, "stream", (None, 0)) + source_files.append((stream, file)) + real_read = file.read + + def read(size=-1): + start = file.tell() + data = real_read(size) + reads.append((stream, start, len(data))) + return data + + monkeypatch.setattr(file, "read", read) + return file + + def open_target(path, offset): + file = real_open_target(path, offset) + names = [str(output) for output in outputs] + if str(path) not in names: + return file + index = names.index(str(path)) + opened.append((index, offset)) + real_write, received = file.write, 0 + + def write(data): + nonlocal received + count = real_write(data) + received += count + file.flush() + if offset == 0 and received == offsets[index]: + child = next(iter(receivers[index]._active_transfer_sockets)) + sock = receivers[index]._active_transfer_sockets[child] + sock.shutdown(socket.SHUT_RDWR) + sock.close() + if index == 1: + second_written.set() + return count + + monkeypatch.setattr(file, "write", write) + return file + + def release_receive(instance, key, record): + if instance is server and key == initial.get("fid"): + finally_held.set() + assert finally_release.wait(timeout=30) + return real_release(instance, key, record) + + def forward(*args, **kwargs): + resumed = kwargs.get("upstream_fid") + peer = args[4][0] if resumed is not None else None + offset = kwargs.get("resume_offset", 0) + local.stream = (peer, offset) + forwards.append((list(args[4]), resumed, offset)) + try: + result = real_forward(*args, **kwargs) + outcomes.append((peer, offset, result)) + return result + finally: + del local.stream - monkeypatch.setattr(first, "send_message", hold_ack) - monkeypatch.setattr(source, "file_transfer_mode", observe_mode) - assert first._request_resumes() == 1 - assert held.wait(timeout=10), "the first target never reached its ACK barrier" - rejected = threading.Event() - original_queue = server._queue_resume_to_originator + def dispatch(target, kind, rel_dir, fname, originator, child, destination=None): + dispatches.append((target, child)) + return real_dispatch(target, kind, rel_dir, fname, originator, child, destination) - def observe_rejection(fid, route, target, offset): - accepted = original_queue(fid, route, target, offset) - if target == second_addr: - assert accepted is False - rejected.set() - return accepted + def resume_request(sock, peer, child, offset, originator, target): + result = real_resume_request(sock, peer, child, offset, originator, target) + handled.append((peer, child, offset, result)) + return result - monkeypatch.setattr(server, "_queue_resume_to_originator", observe_rejection) - assert second._request_resumes() == 1 - assert rejected.wait(timeout=10) - assert not server._resume_request( - server.clients[first_addr]["socket"], first_addr, 502, 999, source_addr, first_addr + def server_send(sock, message, is_send_raw=False): + result = real_server_send(sock, message, is_send_raw=is_send_raw) + if result and message == server.server_received_file_data_sign: + upstream_acks.append(sock) + return result + + monkeypatch.setattr(connect_tcp, "_wait_transfer_control", hold_body) + monkeypatch.setattr(connect_tcp, "_open_transfer_target", open_target) + monkeypatch.setattr(connect_tcp, "_release_receive", release_receive) + monkeypatch.setattr(connect_tcp, "open", source_open, raising=False) + monkeypatch.setattr(source, "_forward_one", forward) + monkeypatch.setattr(server, "forward_item_to", dispatch) + monkeypatch.setattr(server, "_resume_request", resume_request) + monkeypatch.setattr(server, "send_message", server_send) + for index, target in enumerate(receivers): + real_send = target.send_message + + def send(sock, message, is_send_raw=False, *, index=index, real_send=real_send): + written = real_send(sock, message, is_send_raw=is_send_raw) + if written and message == receivers[index].server_received_file_data_sign: + target_acks.append(index) + if index == 1: + second_ack.set() + return written + + monkeypatch.setattr(target, "send_message", send) + + sender = threading.Thread( + target=source._forward_one, + args=("folder", "original/nested", src.name, str(src), targets), daemon=True, ) - assert source.resume_trans(second_addr, 500, offsets[1]) is False - assert source.resume_trans(first_addr, 500, 999) is False - assert server._pending_originator_resumes == {} - assert source._resume_sends[key]["targets"] == {first_addr} - assert transfers == [(500, offsets[0])] - release.set() - assert wait_until(lambda: not source._resume_sends and not server._forward_relays - and 500 not in server._receive_transfers - and key not in source._active_transfer_sockets) - assert route["completed"] == {first_addr} - assert source.resume_trans(second_addr, 500, offsets[1]) is True - assert wait_until(lambda: key not in source.file_upload_progress, timeout=15) - assert wait_until(lambda: not source._resume_sends and not server._fid_routes) - assert transfers == [(500, offset) for offset in offsets] - assert route["targets"] == {first_addr: 502, second_addr: 504} - assert route["completed"] == {first_addr, second_addr} - assert server.file_upload_progress[(first_addr, 502)] == local_row - assert source._transfer_progress_snapshot()["relays"] == {} - for target, child, output in zip(receivers, (502, 504), outputs): - assert wait_until(lambda: child not in target.file_recv_progress) + sender.start() + assert original_held.wait(timeout=15) and second_written.wait(timeout=15) + fid, route = next(iter(server._fid_routes.items())) + initial["fid"] = fid + old = next(iter(server._forward_relays.values())) + children = dict(route["targets"]) + upload_key = ((source.host, source.port), fid) + assert wait_until(lambda: all( + children[peer] not in target._receive_transfers + for peer, target in zip(targets, receivers) + )) + assert [output.read_bytes() for output in outputs] == [payload[:offset] for offset in offsets] + # The wire carries the receiver's disk offset, not an offset query. The + # live shared route must not be cancelled merely because A asks again. + assert receivers[0]._request_resumes() == 1 + assert wait_until(lambda: len(handled) == 1) + assert handled[0] == (targets[0], children[targets[0]], offsets[0], True) + recovery = server._relay_recoveries[fid] + assert recovery["pending"][targets[0]] == (controls[targets[0]], offsets[0]) + assert recovery["active"] == {} + assert not old["done"].is_set() + assert old["sockets"] and initial["socket"].fileno() >= 0 + assert forwards == [(targets, None, 0)] + if not late_second_request: + assert receivers[1]._request_resumes() == 1 + assert wait_until(lambda: len(handled) == 2) + assert recovery["pending"][targets[1]] == (controls[targets[1]], offsets[1]) + original_release.set() + assert finally_held.wait(timeout=15) + assert server._receive_transfers[fid]["owner"] is old + assert forwards == [(targets, None, 0)], "recovery raced the old owner's finally" + assert recovery["active"] == {} + finally_release.set() + assert first_held.wait(timeout=15) + assert wait_until(lambda: (None, 0, False) in outcomes) + assert fid not in server._receive_transfers + assert server._receive_transfers[(targets[0], fid)]["owner"] is not old + assert not first_release.is_set() + # A is blocked before its first resumed source read. A late B must still + # obtain its own source file/socket and complete a real Target ACK now. + if late_second_request: + assert receivers[1]._request_resumes() == 1 + # Both receiver ownership and Server admission reject an active duplicate. + assert receivers[0]._request_resumes() == 0 + assert not server._resume_request( + controls[targets[0]], targets[0], children[targets[0]], offsets[0], origin, targets[0] + ) + assert forwards.count(([targets[0]], fid, offsets[0])) == 1 + if fail_first_again: + assert second_body_held.wait(timeout=15) + first_release.set() + assert wait_until(lambda: (targets[0], offsets[0], False) in outcomes) + assert upload_key in source.file_upload_progress and not route["completed"] + second_body_release.set() + assert second_ack.wait(timeout=15) + assert wait_until(lambda: route["completed"] == {targets[1]}) + assert wait_until(lambda: (targets[1], offsets[1], False) in outcomes) + assert first_release.is_set() is fail_first_again + assert target_acks == [1] + assert upstream_acks == [] + assert outputs[1].read_bytes() == payload + assert hashlib.sha256(outputs[1].read_bytes()).digest() == digest + assert outputs[0].read_bytes() == payload[:offsets[0]] + assert children[targets[1]] not in receivers[1].file_recv_progress + assert server._fid_routes[fid] is route and route["targets"] == children + assert server._fid_route_index == {(targets[0], children[targets[0]]): fid} + upload = source.file_upload_progress[upload_key] + assert len(upload) == 5 and upload[1] == len(payload) + assert upload[3:] == [str(src), targets[0]] + assert set(source.file_upload_progress) == {upload_key} + assert source_sockets[(targets[0], offsets[0])] is not source_sockets[(targets[1], offsets[1])] + resumed_files = [(stream, file) for stream, file in source_files if stream[0] is not None] + assert {stream for stream, _ in resumed_files} == {(targets[0], offsets[0]), (targets[1], offsets[1])} + assert len({id(file) for _, file in resumed_files}) == 2 + assert not any(stream == (targets[0], offsets[0]) for stream, _, _ in reads) + assert next(start for stream, start, _ in reads if stream == (targets[1], offsets[1])) == offsets[1] + assert sum(count for stream, _, count in reads if stream == (targets[1], offsets[1])) == len(payload) - offsets[1] + first_release.set() + if fail_first_again: + assert wait_until(lambda: (targets[0], offsets[0], False) in outcomes) + assert wait_until(lambda: not server._forward_relays and not source._resume_sends + and not recovery["active"]) + assert route["completed"] == {targets[1]} and target_acks == [1] + assert server._fid_routes[fid] is route + assert upload_key in source.file_upload_progress + assert outputs[0].read_bytes() == payload[:offsets[0]] + assert wait_until(lambda: children[targets[0]] not in receivers[0]._receive_transfers) + # A's explicit later retry cannot replay already-ACKed B. + fail_first_again = False + assert receivers[0]._request_resumes() == 1 + assert wait_until(lambda: route["completed"] == set(targets), timeout=20) + assert wait_until(lambda: (targets[0], offsets[0], True) in outcomes, timeout=15) + assert next(start for stream, start, _ in reads if stream == (targets[0], offsets[0])) == offsets[0] + assert sum(count for stream, _, count in reads if stream == (targets[0], offsets[0])) == len(payload) - offsets[0] + assert target_acks == [1, 0] + assert len(upstream_acks) == 1 + assert wait_until(lambda: not server._forward_relays and not server._receive_transfers + and not server._relay_recoveries and not source._resume_sends) + assert not server._fid_routes and not server._fid_route_index and not source.file_upload_progress + assert route["targets"] == children + assert all(not target.file_recv_progress for target in receivers) + for output in outputs: assert output.read_bytes() == payload - assert not (output.parents[2] / src.name).exists() + assert hashlib.sha256(output.read_bytes()).digest() == digest + assert set(opened) == {(0, 0), (0, offsets[0]), (1, 0), (1, offsets[1])} + assert dispatches.count((targets[1], children[targets[1]])) == 2 + assert all(child == children[peer] for peer, child in dispatches) + assert [owner.client_socket for owner in (source, *receivers)] == client_controls + assert all(server.clients[peer]["socket"] is sock and sock.fileno() >= 0 + for peer, sock in controls.items()) finally: - release.set() + original_release.set() + finally_release.set() + first_release.set() + second_body_release.set() _close_socket_workers(server, clients, workers) + + def test_concurrent_forward_upload_handshakes_match_out_of_order_replies(tmp_path, monkeypatch): """A later relay reply cannot hand its port/FID to the first waiting upload.""" workers = _track_socket_workers(monkeypatch) diff --git a/test/unit/network_api/test_fid_routes.py b/test/unit/network_api/test_fid_routes.py index 12dfbc3..695b279 100644 --- a/test/unit/network_api/test_fid_routes.py +++ b/test/unit/network_api/test_fid_routes.py @@ -46,6 +46,13 @@ def server(tmp_path): instance.stop() +def _install_client(server, address): + """Install a real control owner while retaining its peer for cleanup.""" + control, peer = socket.socketpair() + server.clients[address] = {"socket": control} + return control, peer + + def test_lookup_returns_the_same_authoritative_route_from_upstream_and_targets(server): route = server._register_fid_route( 303, @@ -386,135 +393,216 @@ def test_canonical_snapshot_without_completed_has_no_acknowledged_targets(tmp_pa @pytest.mark.parametrize("downstream", [304, 305]) -def test_resume_uses_scoped_route_not_id_lowbit_and_rejects_forged_endpoints(server, downstream): +def test_resume_rejects_forged_or_stale_requesters_before_registration( + server, downstream +): route = server._register_fid_route(302, ORIGINATOR, {TARGET_1: downstream}) - for peer, origin, target, fid in ( - (TARGET_1, TARGET_2, TARGET_1, downstream), - (TARGET_1, ORIGINATOR, TARGET_2, downstream), - (TARGET_2, ORIGINATOR, TARGET_2, downstream), - (TARGET_1, ORIGINATOR, TARGET_1, downstream + 2), - ): - assert not server._resume_request(SERVER_LOCAL, peer, fid, 7, origin, target) - assert server._pending_originator_resumes == {} + current, current_peer = _install_client(server, TARGET_1) + stale, stale_peer = socket.socketpair() + try: + for sock in (stale, current): + for origin, target, fid in ( + (TARGET_2, TARGET_1, downstream), + (ORIGINATOR, TARGET_2, downstream), + (ORIGINATOR, TARGET_1, downstream + 2), + (ORIGINATOR, TARGET_1, downstream), + ): + if sock is current and (origin, target, fid) == (ORIGINATOR, TARGET_1, downstream): + continue + assert not server._resume_request(sock, TARGET_1, fid, 7, origin, target) + assert server._relay_recoveries == {} + assert server._fid_routes[302] is route + assert server._resume_request( + current, TARGET_1, downstream, 7, ORIGINATOR, TARGET_1 + ) + state = server._relay_recoveries[302] + assert state["route"] is route + assert state["active"] == {} + assert state["pending"] == {TARGET_1: (current, 7)} + finally: + server.clients.pop(TARGET_1, None) + current.close() + current_peer.close() + stale.close() + stale_peer.close() + + +def test_duplicate_registration_keeps_only_the_latest_pending_offset(server): + route = server._register_fid_route(302, ORIGINATOR, {TARGET_1: 304}) + current, peer = _install_client(server, TARGET_1) + try: + assert server._resume_request( + current, TARGET_1, 304, 7, ORIGINATOR, TARGET_1 + ) + state = server._relay_recoveries[302] + assert server._resume_request( + current, TARGET_1, 304, 19, ORIGINATOR, TARGET_1 + ) + assert server._relay_recoveries[302] is state + assert state["active"] == {} + assert state["pending"] == {TARGET_1: (current, 19)} + assert not server._resume_request(current, TARGET_1, 304, 19, ORIGINATOR, TARGET_1) assert server._fid_routes[302] is route - # Offline is not success, but a verified receiver's request is retained. - assert not server._resume_request(SERVER_LOCAL, TARGET_1, downstream, 7, ORIGINATOR, TARGET_1) - assert not server._resume_request(SERVER_LOCAL, TARGET_1, downstream, 19, ORIGINATOR, TARGET_1) - assert server._pending_originator_resumes == {ORIGINATOR: {(302, TARGET_1): 19}} - assert server._fid_route_index == {(TARGET_1, downstream): 302} + finally: + server.clients.pop(TARGET_1, None) + current.close() + peer.close() -def test_pending_resume_survives_failed_send_and_prunes_completed_or_missing_routes(server): +def test_recovery_registration_is_retained_when_source_is_offline(server): route = server._register_fid_route(302, ORIGINATOR, {TARGET_1: 304, TARGET_2: 306}) - for target, child in route["targets"].items(): - assert not server._resume_request(SERVER_LOCAL, target, child, 13, ORIGINATOR, target) - broken, peer = socket.socketpair() - peer.close() - # A closed peer does not make the next write fail on every platform: Windows - # accepts the first send into the local buffer and only reports the reset - # later. Shut the writing half down as well, so "the send failed" is a - # property of the socket here, not of the platform's timing. - broken.shutdown(socket.SHUT_WR) - server.running = True - server.clients[ORIGINATOR] = {"socket": broken} + controls = [] try: - assert server._flush_pending_originator_resumes(ORIGINATOR) == 0 - assert server._pending_originator_resumes == { - ORIGINATOR: {(302, TARGET_1): 13, (302, TARGET_2): 13} + for target, child in route["targets"].items(): + control, peer = _install_client(server, target) + controls.extend((control, peer)) + assert server._resume_request( + control, target, child, 13, ORIGINATOR, target + ) + state = server._relay_recoveries[302] + assert state["route"] is route + assert state["active"] == {} + assert state["pending"] == { + target: (server.clients[target]["socket"], 13) for target in route["targets"] + } + assert server._fid_route_index == { + (TARGET_1, 304): 302, (TARGET_2, 306): 302 } finally: - assert server._receive_transfers == {} - broken.close() - assert server._complete_fid_target(302, route, TARGET_1, 304) - writer, reader = socket.socketpair() - reader.settimeout(2) - server.clients[ORIGINATOR] = {"socket": writer} + server.clients.clear() + for control in controls: + control.close() + + +def test_concurrent_relay_requests_reserve_one_real_source_request(server): + route = server._register_fid_route(302, ORIGINATOR, {TARGET_1: 304}) + target, target_peer = _install_client(server, TARGET_1) + source, source_peer = _install_client(server, ORIGINATOR) + target_peer.settimeout(5) + source_peer.settimeout(5) + server.running = True + barrier, accepted = threading.Barrier(3), [] + + def reply(): + barrier.wait(timeout=5) + accepted.append(server._resume_request(target, TARGET_1, 304, 13, ORIGINATOR, TARGET_1)) + + contenders = [threading.Thread(target=reply) for _ in range(2)] + try: + for contender in contenders: + contender.start() + barrier.wait(timeout=5) + for contender in contenders: + contender.join(timeout=5) + assert not contender.is_alive() + assert sorted(accepted) == [False, True] + with source_peer.makefile("r") as stream: + assert parse_resume_command(stream.readline()) == (302, 13, ORIGINATOR, TARGET_1) + record = server._receive_transfers[(TARGET_1, 302)] + assert record["control_socket"] is source + assert server._relay_recoveries[302]["active"][TARGET_1]["record"] is record + assert server._fid_routes[302] is route and not route["completed"] + finally: + server.stop() + with server._transfer_progress_changed: + assert server._transfer_progress_changed.wait_for( + lambda: not server._relay_recoveries[302]["active"], timeout=5) + target_peer.close() + source_peer.close() + + +def test_failed_source_request_allows_a_new_explicit_numeric_request(server, monkeypatch): + route = server._register_fid_route(302, ORIGINATOR, {TARGET_1: 304}) + target, target_peer = _install_client(server, TARGET_1) + source, source_peer = _install_client(server, ORIGINATOR) + source_peer.settimeout(5) + server.running = True + attempts, real_send = [], server.send_message + + def send(sock, message, is_send_raw=False): + attempts.append(message) + return False if len(attempts) == 1 else real_send(sock, message, is_send_raw=is_send_raw) + + monkeypatch.setattr(server, "send_message", send) try: - assert server._flush_pending_originator_resumes(ORIGINATOR) == 1 - assert parse_resume_command(reader.recv(4096).decode()) == ( - 302, 13, ORIGINATOR, TARGET_2 - ) - assert server._pending_originator_resumes == {} - assert not server._resume_request(SERVER_LOCAL, TARGET_1, 304, 0, ORIGINATOR, TARGET_1) - # An accepted request must not outlive its owning route. - _release_receive(server, 302, server._receive_transfers[302]) - assert server._queue_resume_to_originator(302, route, TARGET_2, 29) - reader.recv(4096) - server.clients.pop(ORIGINATOR) - _release_receive(server, 302, server._receive_transfers[302]) - assert not server._queue_resume_to_originator(302, route, TARGET_2, 31) - assert server._drop_fid_route(302, route) - server.clients[ORIGINATOR] = {"socket": writer} - assert server._flush_pending_originator_resumes(ORIGINATOR) == 0 - assert server._pending_originator_resumes == {} + assert server._resume_request(target, TARGET_1, 304, 1, ORIGINATOR, TARGET_1) + state = server._relay_recoveries[302] + with server._transfer_progress_changed: + assert server._transfer_progress_changed.wait_for(lambda: not state["active"], timeout=5) + assert state["pending"] == {} and state["route"] is route + assert server._resume_request(target, TARGET_1, 304, 17, ORIGINATOR, TARGET_1) + with source_peer.makefile("r") as stream: + assert parse_resume_command(stream.readline()) == (302, 17, ORIGINATOR, TARGET_1) + assert server._receive_transfers[(TARGET_1, 302)]["control_socket"] is source + assert state["active"][TARGET_1]["offset"] == 17 + assert server._fid_routes[302] is route and len(attempts) == 2 finally: - server.running = False - server.clients.clear() - writer.close() - reader.close() + server.stop() + with server._transfer_progress_changed: + assert server._transfer_progress_changed.wait_for(lambda: not state["active"], timeout=5) + target_peer.close() + source_peer.close() -@pytest.mark.parametrize("owner", ["request", "receiver", "relay"]) -def test_live_upstream_refuses_recovery_without_pending_other_fids_remain_eligible(server, owner): - route = server._register_fid_route(302, ORIGINATOR, {TARGET_1: 304, TARGET_2: 306}) - server._register_fid_route(402, ORIGINATOR, {TARGET_3: 404}) - control, peer = socket.socketpair() - with control, peer: - record = None - if owner == "relay": - server._forward_relays[(TARGET_1, 304)] = {"fid": 302, "route": route, "upstream": control} - else: - record = _claim_receive(server, 302, control, None if owner == "request" else control) +@pytest.mark.parametrize("replace_session", [False, True], ids=["same-session", "new-target-session"]) +def test_failed_source_write_cannot_release_an_already_adopted_receive_owner( + server, monkeypatch, replace_session +): + route = server._register_fid_route(302, ORIGINATOR, {TARGET_1: 304}) + target, target_peer = _install_client(server, TARGET_1) + source, source_peer = _install_client(server, ORIGINATOR) + data, data_peer = socket.socketpair() + replacement_peer = None + source_peer.settimeout(5) + server.running = True + waiting, adopted = threading.Event(), [] + real_send, real_wait = server.send_message, server._transfer_progress_changed.wait + + def send(sock, message, is_send_raw=False): + sent = real_send(sock, message, is_send_raw=is_send_raw) + if not adopted: + record = _claim_receive(server, (TARGET_1, 302), source, data) assert record is not None - try: - for target, child in route["targets"].items(): - assert not server._resume_request(SERVER_LOCAL, target, child, 13, ORIGINATOR, target) - assert server._pending_originator_resumes == {} - assert not server._resume_request(SERVER_LOCAL, TARGET_3, 404, 19, ORIGINATOR, TARGET_3) - assert server._pending_originator_resumes == {ORIGINATOR: {(402, TARGET_3): 19}} - finally: - server._forward_relays.clear() - if record is not None: - _release_receive(server, 302, record) - - -def test_concurrent_pending_flushes_send_one_real_control_request(server, monkeypatch): - server._register_fid_route(302, ORIGINATOR, {TARGET_1: 304, TARGET_2: 306}) - for target, child in ((TARGET_1, 304), (TARGET_2, 306)): - assert not server._resume_request(SERVER_LOCAL, target, child, 13, ORIGINATOR, target) - entered, release = threading.Event(), threading.Event() - real_send = server.send_message - - def held_send(*args, **kwargs): - entered.set() - assert release.wait(timeout=5) - return real_send(*args, **kwargs) - - monkeypatch.setattr(server, "send_message", held_send) - writer, reader = socket.socketpair() - with writer, reader: - server.running = True - server.clients[ORIGINATOR] = {"socket": writer} - results = [] - workers = [threading.Thread(target=lambda: results.append( - server._flush_pending_originator_resumes(ORIGINATOR))) for _ in range(2)] - try: - workers[0].start() - assert entered.wait(timeout=5) - workers[1].start() - workers[1].join(timeout=1) - finally: - release.set() - for worker in workers: - if worker.ident is not None: - worker.join(timeout=5) - server.running = False - server.clients.clear() - assert not any(worker.is_alive() for worker in workers) - assert sorted(results) == [0, 1] - reader.settimeout(1) - assert parse_resume_command(reader.recv(4096).decode()) == (302, 13, ORIGINATOR, TARGET_1) - with pytest.raises(socket.timeout): - reader.recv(4096) - assert server._pending_originator_resumes == {ORIGINATOR: {(302, TARGET_2): 13}} - _release_receive(server, 302, server._receive_transfers[302]) \ No newline at end of file + adopted.append(record) + return False # A peer may consume a request before local write failure is reported. + return sent + + def wait(timeout=None): + if adopted and adopted[0]["owner"] is data: + waiting.set() + return real_wait(timeout) + + monkeypatch.setattr(server, "send_message", send) + monkeypatch.setattr(server._transfer_progress_changed, "wait", wait) + try: + assert server._resume_request(target, TARGET_1, 304, 7, ORIGINATOR, TARGET_1) + assert waiting.wait(timeout=5) + with source_peer.makefile("r") as stream: + assert parse_resume_command(stream.readline()) == (302, 7, ORIGINATOR, TARGET_1) + assert server._receive_transfers[(TARGET_1, 302)] is adopted[0] + assert not server._resume_request(target, TARGET_1, 304, 19, ORIGINATOR, TARGET_1) + if replace_session: + replacement, replacement_peer = _install_client(server, TARGET_1) + assert server._resume_request(replacement, TARGET_1, 304, 19, ORIGINATOR, TARGET_1) + state = server._relay_recoveries[302] + assert state["pending"] == {TARGET_1: (replacement, 19)} + assert state["active"][TARGET_1]["record"] is adopted[0] + _release_receive(server, (TARGET_1, 302), adopted[0]) + if not replace_session: + with server._transfer_progress_changed: + assert server._transfer_progress_changed.wait_for( + lambda: not server._relay_recoveries[302]["active"], timeout=5) + assert server._resume_request(target, TARGET_1, 304, 19, ORIGINATOR, TARGET_1) + assert parse_resume_command(stream.readline()) == (302, 19, ORIGINATOR, TARGET_1) + assert server._fid_routes[302] is route and not route["completed"] + finally: + if adopted: + _release_receive(server, (TARGET_1, 302), adopted[0]) + server.stop() + with server._transfer_progress_changed: + assert server._transfer_progress_changed.wait_for( + lambda: not server._relay_recoveries[302]["active"], timeout=5) + if replacement_peer is not None: + replacement_peer.close() + for sock in (target, target_peer, source_peer, data, data_peer): + sock.close() \ No newline at end of file diff --git a/test/unit/network_api/test_resume_matching.py b/test/unit/network_api/test_resume_matching.py index 3c63df5..762f99a 100644 --- a/test/unit/network_api/test_resume_matching.py +++ b/test/unit/network_api/test_resume_matching.py @@ -79,6 +79,31 @@ def test_resume_command_preserves_shell_quoted_endpoint_identity(): assert parse_resume_command(line) == (304, 12345, origin, target) +@pytest.mark.parametrize("line", [ + "/resume_trans 304 ? '(\"host\", 5)' '(\"target\", 6)'", + "/resume_trans 304 ? '(\"host\", 5)' '(\"target\", 6)' extra", + "/resume_trans 304 ?? '(\"host\", 5)' '(\"target\", 6)'", +]) +def test_resume_rejects_non_numeric_or_ambiguous_offsets(line): + assert parse_resume_command(line) is None + + +def test_resume_formatter_preserves_zero_and_numeric_offsets(): + origin, target = ("source", 1), ("target", 2) + assert parse_resume_command(format_resume_line(0, 0, origin, target)) == ( + 0, 0, origin, target + ) + + +@pytest.mark.parametrize("line", [ + "/resume_trans -1 0 '(\"host\", 5)' '(\"target\", 6)'", + "/resume_trans 304 -1 '(\"host\", 5)' '(\"target\", 6)'", +]) +def test_resume_numeric_bounds_remain_rejected(line): + assert parse_resume_command(line) is None + + + @pytest.mark.parametrize("line", [ "/resume_trans 304 1", "/forward_resume '(\"host\", 5)' 304 1", From 12b0cccbed1617b1d371528f438e4f126e2bbfee Mon Sep 17 00:00:00 2001 From: F18-Ray Date: Thu, 19 Nov 2026 13:20:41 +0800 Subject: [PATCH 13/19] fix(tcp): reconfirm completed relay uploads at EOF - Reuse the existing completed fid route for explicit Source EOF reconfirmation; validate the current session, original target, complete header, and exact EOF without reopening Targets. - Preserve route and shared upload state on failed ACK writes; clean only owning records after the real final ACK, and limit scoped receive-owner conflicts to the current route targets. - Add real-socket regressions for repeated ACK failure, offline Targets, malformed headers, finalizing owners, independent recovery, and same-FID reuse across different Targets. - Migrate the obsolete automatic pause/start backpressure test after explicit user approval; retain actual reader gating, queue bounds, contents, and final ACK checks. - Verification: final targeted combination 58 passed; eight standalone transport scenarios passed. The one full run had 984 passed, 1 failed, 1 skipped before the approved legacy-test migration; no second full run. Typecheck retains 37 diagnostics outside the changed production ranges. - Record C4 paths, runtime evidence, review findings, and limitations in transfer-control-lifecycle-report.md. No public signature, wire, persistence schema, CI, dependency, merge, or push changes. --- GLOSSARY.md | 29 ++ PyFlow/network_api/connect_tcp.py | 112 +++++--- docs/plans/transfer-control-lifecycle-plan.md | 91 ++++++- .../transfer-control-lifecycle-report.md | 97 +++++++ ...transfer-control-lifecycle-requirements.md | 27 +- docs/source/File_Transfer/File_Transfer.rst | 55 +++- docs/source/Network_APIs/TCP_Client_APIs.rst | 24 +- docs/source/Network_APIs/TCP_Server_APIs.rst | 29 +- docs/source/changes/transfer-fid-routes.md | 31 ++- .../network_api/test_tcp_file_transfer.py | 82 ++++-- .../network_api/test_tcp_transfer_resume.py | 247 +++++++++++++++++- test/unit/network_api/test_fid_routes.py | 68 +++++ 12 files changed, 775 insertions(+), 117 deletions(-) create mode 100644 GLOSSARY.md diff --git a/GLOSSARY.md b/GLOSSARY.md new file mode 100644 index 0000000..2e0f3f6 --- /dev/null +++ b/GLOSSARY.md @@ -0,0 +1,29 @@ +# 文件转发 + +本词汇表区分转发任务的交付结果与单条数据流的传输位置。 + +## Language + +**转发任务**:将一个文件或文件夹条目交付给一组已接受目标的整体工作;单个目标完成不等于整个任务完成。 +_Avoid_:将单条数据流称为整个任务 + +**任务交付完成**:转发任务的所有已接受目标均已真实确认收到完整文件的状态。 +_Avoid_:发送完毕、单目标完成、仅凭文件大小认定成功 + +**零正文恢复**:恢复位置等于文件总大小、没有剩余文件正文需要发送的恢复;它本身不是任务交付完成的证据。 +_Avoid_:把 EOF 等同于全部目标成功 + +**最终确认**:向源端确认整个转发任务已交付完成的确认,而非只确认某条数据流结束。 +_Avoid_:把单流结束称为整任务成功 + +**补最终确认**:任务已经交付完成、源端尚未获得最终确认时,再次确认原任务完成的过程。 +_Avoid_:重新交付、重新传输正文 + +**转发任务路由**:关联任务源端与各目标接收身份的任务关系;任务已交付但尚未最终确认时仍可保留。 +_Avoid_:磁盘文件路径、另一份字节进度 + +**任务上传进度**:源端为整个转发任务保留的文件发送与恢复依据;它不是某一个目标的独立收件进度。 +_Avoid_:仅凭记录中的一个目标身份认定为该目标专属任务 + +**目标完成集合**:原转发任务中已经真实确认收到完整文件的已接受目标集合。 +_Avoid_:已发送字节、零正文恢复请求 diff --git a/PyFlow/network_api/connect_tcp.py b/PyFlow/network_api/connect_tcp.py index 09d1ccd..fdb6f52 100644 --- a/PyFlow/network_api/connect_tcp.py +++ b/PyFlow/network_api/connect_tcp.py @@ -7203,18 +7203,33 @@ def _forward_item_handler(self, sock, addr, cmd): destination_path = rest[-1] rest = rest[:-1] items, addrs = self._forward_parse_items_addrs(rest) - valid_targets = [] - for target in addrs: - if target == (self.host, self.port): - self._log(f"forward: target {target} is the server itself, skipped") - continue - if target not in self.clients: - self._log(f"forward: target {target} is unreachable, skipped") - continue - valid_targets.append(target) - if not valid_targets: - self._forward_notify_error(sock, "no reachable targets to forward to", upstream_fid) - return + confirmation_route = None + with self._forward_relays_lock: + route = self._fid_routes.get(upstream_fid) + if (resume_requested and route is not None and route["targets"] + and route["completed"] == route["targets"].keys()): + confirmation_route = route + if confirmation_route is not None: + with self.client_lock: + current = self.clients.get(tuple(addr), {}).get("socket") is sock + if (not current or confirmation_route["originator"] != tuple(addr) + or len(addrs) != 1 or addrs[0] not in confirmation_route["targets"]): + self._forward_notify_error(sock, "invalid completed relay owner or target", upstream_fid) + return + valid_targets = addrs # Completed Targets need not still be connected. + else: + valid_targets = [] + for target in addrs: + if target == (self.host, self.port): + self._log(f"forward: target {target} is the server itself, skipped") + continue + if target not in self.clients: + self._log(f"forward: target {target} is unreachable, skipped") + continue + valid_targets.append(target) + if not valid_targets: + self._forward_notify_error(sock, "no reachable targets to forward to", upstream_fid) + return if kind == "file": if not items: self._forward_notify_error(sock, "missing file name", upstream_fid) @@ -7234,6 +7249,7 @@ def _forward_item_handler(self, sock, addr, cmd): kwargs={ "upstream_fid": upstream_fid, "resume_requested": resume_requested, + "expected_route": confirmation_route, }, daemon=True, ).start() @@ -7322,6 +7338,7 @@ def _forward_relay( resume_offset=0, upstream_fid=None, resume_requested=False, + expected_route=None, ): """Relay one file/folder item to every target, streaming from the @@ -7346,15 +7363,23 @@ def _forward_relay( if fid is None: self._log("forward: rejected relay without an upstream FID") return - recovery = reservation = None + recovery: dict | None = None + reservation = None + eof_confirmation = False + with self.client_lock: + current_source = self.clients.get(tuple(originator_addr), {}).get("socket") is forwarder_sock if resume_requested: with self._forward_relays_lock: route = self._fid_routes.get(fid) recovery = self._relay_recoveries.get(fid) reservation = recovery["active"].get(targets[0]) if recovery and len(targets) == 1 else None + eof_confirmation = bool(route and route["targets"] + and route["completed"] == route["targets"].keys()) if (route is None or route["originator"] != tuple(originator_addr) or len(targets) != 1 or targets[0] not in route["targets"] - or targets[0] in route["completed"] + or targets[0] in route["completed"] and not eof_confirmation + or expected_route is not None and route is not expected_route + or eof_confirmation and not current_source or reservation is not None and ( reservation["offset"] != resume_offset or reservation["source_socket"] is not forwarder_sock)): @@ -7373,8 +7398,8 @@ def _forward_relay( forwarder_sock, "relay fid is already in use", fid ) return - manual_recovery = resume_requested and reservation is None - relay = { + manual_recovery = resume_requested and reservation is None and not eof_confirmation + relay: dict = { "cond": threading.Condition(), "control_lock": threading.RLock(), "requested": None, "done": threading.Event(), @@ -7382,12 +7407,20 @@ def _forward_relay( "controls": {}, "route": route, "fid": fid, + "confirm_eof": eof_confirmation, } relay_keys = [(target, tfid) for target, tfid in zip(targets, tfids)] - receive_key = (targets[0], fid) if resume_requested else fid + receive_key = (targets[0], fid) if resume_requested and not eof_confirmation else fid receive_record = None with self._transfer_progress_lock, self._forward_relays_lock: + confirmation_busy = eof_confirmation and ( + any(key == fid or isinstance(key, tuple) and key[1] == fid + and key[0] in route["targets"] for key in self._receive_transfers) + or any(candidate["fid"] == fid for candidate in self._forward_relays.values()) + or recovery is not None and bool(recovery["active"]) + ) if (self._fid_routes.get(fid) is route + and not confirmation_busy and (resume_requested and fid not in self._receive_transfers or not resume_requested and not any( candidate["fid"] == fid for candidate in self._forward_relays.values())) @@ -7398,12 +7431,12 @@ def _forward_relay( if receive_record is not None: for key in relay_keys: self._forward_relays[key] = relay - if resume_requested and recovery is None: + if resume_requested and recovery is None and not eof_confirmation: recovery = {"route": route, "pending": {}, "active": {}, "control": {"control_lock": threading.RLock(), "requested": None, "controls": {}}} self._relay_recoveries[fid] = recovery - if manual_recovery: + if manual_recovery and recovery is not None: reservation = {"record": receive_record, "source_socket": forwarder_sock, "target_socket": self.clients.get(targets[0], {}).get("socket"), "offset": resume_offset} @@ -7411,7 +7444,7 @@ def _forward_relay( if receive_record is None: self._forward_notify_error(forwarder_sock, "relay source is already active", fid) return - control_group = recovery["control"] if resume_requested else relay + control_group: dict = recovery["control"] if recovery is not None and not eof_confirmation else relay if os.path.exists(self.file_trans_progress_file): self._persist_transfer_progress() target_conns = [] @@ -7421,6 +7454,7 @@ def _forward_relay( target_handshakes = relay["handshakes"] owned_sockets = relay["sockets"] terminal_sent = False + relay_targets = [] if eof_confirmation else list(zip(targets, tfids)) def fail(message): nonlocal terminal_sent @@ -7442,7 +7476,7 @@ def own(control, transfer): return True try: - for target, tfid in zip(targets, tfids): + for target, tfid in relay_targets: with relay["cond"]: target_control = (reservation["target_socket"] if reservation is not None else self.clients.get(target, {}).get("socket")) @@ -7453,7 +7487,7 @@ def own(control, transfer): if handshake is None: fail(f"target {target} has no available listener negotiation") return - for target, tfid in zip(targets, tfids): + for target, tfid in relay_targets: with relay["cond"]: sent = self.forward_item_to( target, kind, rel_dir, fname, originator_addr, tfid, destination_path) @@ -7467,14 +7501,14 @@ def own(control, transfer): fail("target port setup timed out") return ports = {} - for target, tfid in zip(targets, tfids): + for target, tfid in relay_targets: result = results[target_handshakes[(target, tfid)]["key"]] if result[0] != "port": fail(f"target {target} rejected its listener") return ports[(target, tfid)] = (result[2], result[3]) # connect to each target and wait for its start sign - for target, tfid in zip(targets, tfids): + for target, tfid in relay_targets: tport, stamp = ports[(target, tfid)] sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) target_control = target_handshakes[(target, tfid)]["key"][0] @@ -7513,7 +7547,7 @@ def own(control, transfer): paused = upstream["confirmed_state"] self._transfer_controls._confirm(control, paused) self._transfer_controls._send(control, paused, None) - if not target_conns: + if not target_conns and not eof_confirmation: fail("no target accepted the transfer") return # open the upload listener and hand it to the forwarder @@ -7578,13 +7612,13 @@ def own(control, transfer): owned_sockets.clear() target_handshakes.clear() relay["done"].set() - if resume_requested: + if resume_requested and not eof_confirmation: with control_group["control_lock"]: for target, control in relay["controls"].items(): if control_group["controls"].get(target) is control: del control_group["controls"][target] _release_receive(self, receive_key, receive_record) - if manual_recovery: + if manual_recovery and recovery is not None: with self._transfer_progress_lock, self._forward_relays_lock: if recovery["active"].get(targets[0]) is reservation: del recovery["active"][targets[0]] @@ -7622,7 +7656,7 @@ def _forward_pump( } queues = {(target, tfid): queue.Queue() for tfid, target, _ in target_conns} END = object() - result = {"ok": 0, "ack": None} + result: dict = {"ok": 0, "ack": None} def release_buffered(byte_count): """Called under cond; failed writers also release upstream backpressure.""" @@ -7690,6 +7724,8 @@ def reader(): file_size = int.from_bytes(size_b, "big") if not 0 <= resume_offset <= file_size: raise ValueError("resume offset exceeds the forwarded file") + if relay.get("confirm_eof") and resume_offset != file_size: + raise ValueError("completed relay confirmation requires an EOF offset") for chunk in (name_len_b, name_b, size_b): enqueue(chunk) remaining = file_size - resume_offset @@ -7732,16 +7768,22 @@ def reader(): state["complete"] and self._fid_routes.get(fid) is route and route["completed"] == route["targets"].keys() - and result["ack"] is not None + and (result["ack"] is not None or relay.get("confirm_eof", False)) ) + if relay.get("confirm_eof"): + with self.client_lock: + complete = complete and self.clients.get(tuple(route["originator"]), {}).get("socket") is forwarder_sock + complete = complete and not self._transfer_handshakes.closed(forwarder_sock) try: - # A target's existing ACK is the only success marker. Never confirm - # upstream receipt independently of the full accepted target set. + # Live delivery forwards a real Target ACK. EOF reconfirmation uses + # that route's retained, entirely acknowledged completion set. # Send it as a protocol line: send_message adds no newline to bytes. - written = self.send_message( - up_sock, - result["ack"].decode("ascii") if complete else self.error_sign, - ) + ack = result["ack"] + if relay.get("confirm_eof"): + ack = self.server_received_file_data_sign + elif ack is not None: + ack = ack.decode("ascii") + written = self.send_message(up_sock, ack if complete else self.error_sign) if complete and written: self._drop_fid_route(fid, route) except Exception as exc: diff --git a/docs/plans/transfer-control-lifecycle-plan.md b/docs/plans/transfer-control-lifecycle-plan.md index 7d12654..dfad9aa 100644 --- a/docs/plans/transfer-control-lifecycle-plan.md +++ b/docs/plans/transfer-control-lifecycle-plan.md @@ -1,6 +1,6 @@ # 传输控制生命周期、全局转发暂停与独立并行恢复 — 更改计划 -状态:**用户批准的数值 offset、原 route 旧 owner 全收尾、每 Target 独立并行恢复已实现;本轮局部验证和真实传输证据已记录,待人工审查**。旧 C3a/C3b 的查询/强制 teardown/单活跃轮次仅作撤回历史。C1/C2 保留;C4–C6 未实现,不自动推进,不自动提交、合并或推送。 +状态:**C4 实现、局部验收与双轴审查完成:核心六组及两组边界真实程序通过,最后窄组合 58 passed;完整测试曾 984 passed/1 failed/1 skipped,唯一旧契约失败按用户批准迁移后窄重验通过;类型检查仍有 37 条改动范围外诊断**。复用既有 fid route/completed 和 Source 任务上传行,不新增完成表、完成位、Server 转发字节进度行或快照格式;不拆改 Source 发送函数。C1/C2/C3 保留,C5/C6 未实施;本轮提交当前分支,不合并或推送,完整证据与限制见报告。 需求依据:[需求卡](transfer-control-lifecycle-requirements.md)。历史实现依据:[上一轮计划](transfer-pause-start-direction-plan.md)及其报告;它们的历史验证结果不作为本轮验证结果。 @@ -11,7 +11,7 @@ 1. **问题四/五**:按实际控制 socket 管理旧会话资源,删除按 peer 扫描进度表关闭当前 socket 的重复机制;旧 worker 不借用新控制连接。 2. **问题六**:自身完整控制端点拒绝为后续 C5 目标,同 host 不同端口仍可互传;C5 未实现,不混入本轮 C3。 3. **问题七**:Source 是 route 的唯一用户控制仲裁者;任意端 pause/start 控制整个转发任务。暂停源端新增块,已有字节继续排空,数据 socket 不断开。 -4. **问题八**:本轮 8A 撤回 offset 查询、强制 teardown 及 FIFO 单轮调度;Receiver 提交实际数值 offset,Server 等原 route 全部旧 owner(含 finally)自然收尾,再按 Target 独立建流,正文并行。8B 全 Target 已完成后的上游 EOF 再确认仍为未实现 C4,不顺带实施。 +4. **问题八**:8A 的 C3 独立并行恢复已实现,查询/强制 teardown/FIFO 单轮方案已撤回。8B 的 C4 已实现复用原 fid route/completed 和 Source 共享上传行,补全目标完成后的显式 EOF 最终确认;路径与边界见 6.1,实际证据见报告。 ### 1.2 明确排除 @@ -54,6 +54,26 @@ Web 的 `client_backend.py` 已知通过 Client 的文件/文件夹转发入口 当前 LSP 只有 Ruff,不支持 definition/references;本轮按现有声明和文本调用点定位。实施前重新检查导航能力;支持 references 时,改公开符号前必须查询引用,不声称 Ruff 已完成引用分析。 +### 2.1 本次 C4 限定文件(已获实施批准) + +上表为整个生命周期任务的总清单,不代表 C4 可以顺带修改所有文件。本次仅限下列文件,不新增生产模块或测试文件,不删除文件: + +| 文件 | C4 修改点 | +|---|---| +| `PyFlow/network_api/connect_tcp.py` | Server `_forward_item_handler` 的终态准入、`_forward_relay` 的仅上游建流、`_forward_pump` 的 EOF/最终 ACK 分支;复用资源 registry、握手和 `_drop_fid_route`,不另写发送协议 | +| `test/unit/network_api/test_fid_routes.py` | 既有完成集合、原目标成员、实际 Source 会话、原 route 对象、重载与同任务 owner 排他契约 | +| `test/integration/network_api/test_tcp_transfer_resume.py` | 扩展既有 `test_forward_ack_write_failure_retains_source_and_completed_route` 等真实 ACK 测试;补重复失败、显式成功、Target 离线、零正文、错误请求及 finally 交叉 | +| `test/integration/network_api/test_tcp_file_transfer.py` | 用户在完整测试出现唯一旧契约失败后明确批准:仅迁移背压测试,从旧自动 pause/start 消息计数改为本地 reader 阻塞/释放、完整内容和真实 ACK;不改生产背压 | +| `docs/source/File_Transfer/File_Transfer.rst` | 记录所属端、EOF 与交付完成的区别、显式触发和清理时点 | +| `docs/source/Network_APIs/TCP_Server_APIs.rst`、`TCP_Client_APIs.rst` | C4 支持范围、`resume_trans` 登记语义、Target 离线及失败保留边界 | +| `docs/source/changes/transfer-fid-routes.md` | 本次行为变化及保留契约 | +| `docs/plans/transfer-control-lifecycle-requirements.md`、本计划、`transfer-control-lifecycle-report.md` | 需求/计划状态、逐路径实际证据、风险与人工审查;历史结果不覆盖 C4 | + +`GLOSSARY.md` 已在本轮澄清领域术语,不定义新的实现记录;C4 实施不以此为新增表的依据。`test_resume_matching.py`、`test_transfer_control.py`、`test_transfer_handshakes.py` 仅作为既有契约回归,不计划修改。若必须扩大文件或 Source 发送实现范围,先修订计划并获批准,不在实现中顺手扩展。 + +完整 pytest 实际为 984 passed、1 failed、1 skipped;唯一失败仍要求旧自动背压控制帧。用户已选择 `migrate_contract`,批准上述单函数迁移及窄重验,不再次运行全套。C4 审查另定位到旧恢复 tuple owner 在 route 已删除后的 finally 窗口:不同 Target 的新 route 复用同值 fid 时,不应被该旧 Target owner 误判 busy;修正限于既定 C4 准入及同文件真实恢复回归,不改 Source 或扩大生产范围。 + + ## 3. 接口与线上契约(用户已批准) ### 3.1 保持不变的部分 @@ -155,7 +175,55 @@ flowchart TD - Source 多 sender 共享 upstream 任务控制状态和 owners 集合,`owner` 始终指向 live owner;仅最后一个 owner 退出才释放。任意参与者 pause/start 仍由 Source 仲裁,作用于所有恢复正文流;Server writers 继续排空,用户 start 不清本地背压。 - pending Source 离线时保留,合法回连/后续触发再处理;Target 断线则丢旧 socket 请求,等待新实际会话和新实际 offset 重发。每 Target 请求去重,单流失败仅收尾该流并保留恢复依据,不打断兄弟、不自动重试。 - 单 Target 真实 ACK 仅更新该 Target completed;中间成功不得伪造整 route ACK,Source 上传行/Server route 保留。累计全部 accepted Target 的真实 ACK 才能经既有最终 ACK 使整任务成功。零 offset、空文件、Target EOF 恢复仍需真实 ACK。 -- C4 全 Target 已完成、仅上游 ACK 明确失败的 EOF 再确认未实现;不借本轮数值 EOF 路径声称已完成 C4,不新增 ACK-of-ACK 或结果通道。 +- C4 已实现全 Target 完成、仅上游 ACK 明确失败后的显式 EOF 补确认,复用下节既有 route/completed;不新增终态表、ACK-of-ACK 或结果通道。 + +### 6.1 C4:既有 fid 路由上的显式 EOF 补最终确认 + +#### 6.1.1 意图、现状与不变量 + +- **单一意图**:所有原 accepted Target 已真实确认、Server 向 Source 写最终 ACK 返回 False/异常时,允许 Source 显式零正文再确认并完成所属记录清理;不是重新交付文件。 +- **记录所属端**:Source 以 `(Server, upstream_fid)` 保存一条共享任务上传行;Target 各自保存接收行;Server 原生流式转发没有逐目标 upload/download 字节进度行,已有 `_fid_routes[fid]` 持有 `originator/targets/completed`,快照写入 `relays`。 +- **部分完成不变**:A 成功后清 A 的接收行、反向 child 索引和数据资源;B 未完成时保留其恢复关联和 Source 共享上传行。原 `targets` 中保留 A 属于任务成员证据,不等于仍向 A 传输。不因 Source 已发送到 total 就删共享恢复依据。 +- **判成功的两个条件分开**:原 route 的 `completed` 完整覆盖非空 `targets` 证明任务交付完成;`resume_offset == 本次文件头 size` 只证明零正文。缺少任一条件都不能通过 C4 回成功 ACK。 +- **记录格式不变**:不新增完成表、完成位、Server 字节进度、route total、文件名/hash、快照 version 或迁移器;不把任务元数据迁到 Source。终态直接复用原 route,补确认成功后删除,无第二份成功历史。 + +#### 6.1.2 入口 → 准入 → 文件头 → ACK → 清理 + +1. **Source 显式入口**:原上传行仍存在时调用 `resume_trans(原 Target, upstream_fid, 原上传行 total)`。仍只预留 worker,不把返回 True 当作完成;原文件存在且未改变是既有恢复前提。普通传输、Target 驱动的未完成恢复和 C3 并行模型不变。 +2. **既有线上请求**:复用 Source `_forward_one` 发出的 `/forward_item ... fid= resume=`,不新增终态标志或完成消息。一次请求只选择一个原 Target,沿用 Source 现有 EOF 文件发送;不拆改 `file_transfer_mode/_send_file`,不新增绕过现有公开入口的调用。 +3. **Server 先判合法终态,再做在线过滤**:`_forward_item_handler` 校验实际 Source socket 仍是当前会话、originator、原 upstream fid、请求目标成员及完整完成集合。只有这一分支允许目标离线;不能先把离线但已完成的 Target 过滤掉。未知/旧 Source、错误 fid/成员/多目标请求无终态副作用;普通及未完成转发保持既有在线目标处理。 +4. **所有权准入**:`_forward_relay` 复核同一 route 对象与会话;原始及各独立恢复的 receive/data/listener/握手/finalizing owner 未全部退出时不准入。该显式终态路径不排自动重试队列,忙/重复按既有占用/失败规则拒绝;不得只检查 socket 已关闭。复用现有接收预留,使同一 upstream 任务最多一个确认 owner;不持全局锁等待网络,不阻塞控制 reader/event loop。 +5. **仅建立上游数据腿**:复用原端口回复、listener、加密 stamp、track_socket、控制登记和 owning finally。终态分支不分配 child fid、不调用 `forward_item_to`,不创建 Target 握手或数据连接;Target 无须在线,原目标文件不读取、不重开、不改写。未完成 route 仍走 C3,不以空 Target 列表模拟完成。 +6. **完整文件头与严格 EOF**:读取现有 name-length/name/size 头,不增加字段。只有请求 offset 与该 size 相等才按 C4 完成;合法空文件为 offset=size=0。头截断、offset 小于/大于 size 均失败,不吞正文、不把非法 offset 重置成零后补成功 ACK。有效 EOF 路径的正文读写均为零。 +7. **最终 ACK**:在本次头完整、会话/route 对象仍有效、原完成集合仍完整的条件下,通过既有 `send_message` 发送原最终数据 ACK 标记。它确认已由 Target 真实 ACK 证明的任务,不由 EOF 请求虚构成功;复用既有最终 ACK 成功/失败和 `_drop_fid_route` 清理入口,不新增 receipt/ACK-of-ACK。 +8. **各端 owning 清理**:ACK 写入成功后 Server 才按原 route 对象清 route/index/recovery;Source 只有实际消费最终 ACK 才通过现有路径清自己的共享上传行。端口/连接/文件头/ACK False 或异常均清本次资源、保留原任务依据;旧 finally 不删新 owner/无关 fid。Source 或 Server 的记录重载后仍由 Source 显式操作,不从 connect 自动发起 C4。 + +#### 6.1.3 C4 路径全集与验收证据 + +| 编号 | 执行路径 | 必须观察的证据 | +|---|---|---| +| C4-P01 | 原始扇出全部 Target ACK;上游 ACK False/异常 | 所有目标真实内容/ACK,Source 返回失败并保留共享行,原 route 完整 completed 保留,目标反向索引已清 | +| C4-P02 | C3 最后一条独立恢复完成后,上游最终 ACK 失败 | 不重发此前已完成目标,任务行仍在;同一 C4 路径可补确认,不只支持首次扇出 | +| C4-P03 | Source 显式同 fid EOF;文件/文件夹条目/空文件 | 原 port/header/ACK 流,Source 真实消费成功;零正文、无 Target 命令/新 socket/新 fid,原完整路径内容/hash 不变 | +| C4-P04 | 补确认的 ACK 再次 False/异常后显式重做 | 每次失败保留原 route/行并清本次 owner;最终成功只清所属记录,不伪造自动重试 | +| C4-P05 | 一个或全部原 Target 已离线 | 正确 Source 可确认,Target 不在线不阻止终态;未完成离线目标不可借此跳过 | +| C4-P06 | 完成 route + Source 行从旧规范快照重载、原端点回连 | 无新字段/迁移器;Server 不自动触发 C4;显式再确认后快照 owning 清理,Target 无须回连 | +| C4-P07 | 部分完成、未知/错误 fid、Source/成员、旧 socket、多目标、缺失/截断头、非 EOF | 不得仅凭 EOF 直接回 C4 成功或清共享行/route;非法请求不触碰目标文件。合法未完成目标仍可按 C3 真实恢复,实际全部 ACK 后的正常成功不受限制 | +| C4-P08 | 原 owner 仍在 finally、两个并发确认、迟到旧清理 | 不出现第二 owner,不抢占;旧资源和握手均收尾后可再次显式操作,新 owner/无关任务保留 | +| C4-P09 | 控制或数据连接中断、stop、加密就绪窗口 | 沿统一安全 I/O 失败关闭,不明文回退;无死锁或 worker 泄漏,保留可恢复依据 | +| C4-P10 | tracking off 的既有保留行、别名/wildcard、无关普通 fid 活跃 | 不凭空造行、不改变五字段/scoped key;实际 owner 会话正确、其他 fid 仍有内容/真实 ACK | + +明文/加密、thread/async 为对应路径参数;文件/文件夹、零长/非零长、False/异常与同会话/原端点重连需要在报告逐项注明实际运行组合,未跑项不能称覆盖。已有普通 EOF 和 Target ACK-loss EOF 测试继续保留,不把它们等同于 C4。 + +#### 6.1.4 单一原子变更、验证与风险 + +- **拆分固定**:一个 C4 原子变更“复用既有路由的显式终态 EOF 补确认”,包含 Server 分支、对应 unit/真实 socket 测试和使用文档,不再分 C4a/C4b,不混 C5/C6。计划总变更约 300–500 行;这只是审查规模预估,不是硬凑行数。若实现必须超出该规模/文件范围或触碰 Source 发送函数,先回计划阶段,不边写边拆。 +- **局部命令**:完成该变更后一次运行下节 V4;失败以输出定位后只重验修正路径,不靠重复尝试碰通过。集成测试优先扩展既有上游 ACK 失败场景,补充能捕获真实错误的准入/错误路径,不添加源码字符串、wiring 或只看文件存在的断言。 +- **独立运行证据**:实施完成后创建并删除临时 `/tmp/pyflow-transfer-lifecycle-smoke.py --case eof-confirm`,不调用 pytest 测试函数,不 mock 文件/网络/加密主路径;只在最终 ACK 发送点注入 False/异常、用事件固定时序。记录稳定 fid、实际 socket owner、零正文/无 Target 建连、内容/hash、ACK、失败后快照及最终 worker 数;不留永久验收脚本或新协议。 +- **资源代价**:失败且未再操作的原 route 仍可长期保留;本次不增加 TTL/后台清理或有界存储保证。ACK 本地 write 成功后 Server 删除,但对端应用是否收到仍不确定;不以永久成功历史或 ACK-of-ACK 掩盖。 +- **元数据限制**:旧 route 不保存历史 name/size/hash;本次 EOF 只与本次头比较,不证明源文件未改变,不把原文件缺失或修改问题纳入本次修复。 +- **接口/安全影响**:不改公开签名、wire、Source 行或 Server 快照格式;所有新分支走既有 secure/send/receive/owner 入口。高风险审查聚焦实际会话、已完成集合、旧 finally 和清理身份;native Windows、其他 Python 版本及未运行矩阵明确未覆盖。无 CI、依赖、测试策略或阈值修改。 + ## 7. 数据流与所有路径验收映射 @@ -183,7 +251,7 @@ flowchart TD | P14 多 Target 不同 offset/部分完成/晚到目标 | 独立流/进度/资源;A 正文或 ACK 阻塞时 B 可传输;仅端口短串行;已完成目标不重传 | 本轮 C3;V3b,S4 | | P15 Source/Target 离线及单流失败 | Source pending 保留;Target 旧 socket pending 丢弃,新会话新 offset 重发;兄弟继续,无自动重试 | 本轮 C3;V3b,S4 | | P16 零 offset/空文件/EOF | 不新建全目标任务;不重发已收正文;必须真实 ACK | C1/C3/C4;V1/V3/V4,S1/S4/S5 | -| P17 所有目标完成、上游 ACK False/异常 | 保留可确认终态;同 fid EOF 补 ACK;不重开 Target;再次失败仍可确认 | C4;V4,S5 | +| P17 所有目标完成、上游 ACK False/异常 | 复用原 route/completed;Source 显式同 fid EOF;无 Target 重开/正文;再次失败保留,收到真实 ACK 后清所属共享行;详见 C4-P01–P10 | C4;V4,S5 | | P18 Client 自目标/混合目标/同机不同端口 | 自目标不建腿、不建行;混合只拒自身;其他合法目标内容/ACK 正确 | C5;V5,S6 | | P19 tracking off/原保留行/query/delete/stop | 无凭空新进度;原 fid/query/快照 schema 不变;关闭后才能删 | C1/C3;V1/V3/V6,S1/S4 | | P20 加密开关/rekey/线程式及 async/别名和 wildcard | 统一安全 I/O、不明文降级、不阻塞密钥接收;真实内容/ACK/owner 清理 | C1–C5;相应 V/S 的参数矩阵,V6 | @@ -198,11 +266,11 @@ flowchart TD | C2 | 已保留:Source 仲裁全局暂停、writer 排空与独立背压 | V2,S3;历史证据见报告 | | 旧 C3a/C3b | 已撤回历史:offset 查询、强制 teardown、单活跃 FIFO 轮次,不再实施或验收该契约 | 旧结果不作为本轮证据 | | 本轮 C3 | 已实现:仅数值请求;原 route 旧 owner 全收尾;每 Target 独立流/进度/资源/失败,正文并行;socket+fid 仅端口短串行;保留 C1/C2 和累计真实 ACK | 分次局部回归与 3 组独立程序实际结果见实施报告;未扩大为 V6/C6 总验收 | -| C4 | 未实现:所有 Target 已完成、上游 ACK 明确失败后的 EOF 再确认 | V4,S5;须单独推进 | +| C4 | 已批准并实现:复用既有 fid route/completed,不新增记录/字段;Source 显式 EOF 补最终确认,单一原子变更 | C4-P01–P10;实际运行矩阵、局部与完整测试及未覆盖项见报告,不把计划命令当运行结果 | | C5 | 未实现:Client 自身完整控制端点拒绝 | V5,S6;须单独推进 | | C6 | 未实现:合并回归、全路径总体验收与最终报告 | V6;须单独推进 | -本轮文档同步不是 C6 完成声明。实施不新增 wire、依赖、CI、自动重试或身份迁移;不创建 git 提交。旧 C3 的历史拆分及授权不作为新实现通过证据。 +本轮不是 C6 总验收声明。实施不新增 wire、依赖、CI、自动重试或身份迁移;用户实施指令授权提交当前分支,不授权合并或推送。旧 C3 历史拆分及授权不作为新实现通过证据。 ## 9. 验收命令和证据格式(计划约定;实际执行见实施报告) @@ -217,8 +285,9 @@ flowchart TD .venv/bin/python -m pytest test/unit/network_api/test_resume_matching.py -q # V3b — 本轮 C3 原 route 收尾及独立并行恢复(非旧查询/串行契约) .venv/bin/python -m pytest test/unit/network_api/test_fid_routes.py test/integration/network_api/test_tcp_transfer_resume.py test/integration/network_api/test_tcp_transfer_control.py -k 'forward or relay' -q -# V4 — C4 EOF 与最终 ACK -.venv/bin/python -m pytest test/unit/network_api/test_resume_matching.py test/integration/network_api/test_tcp_transfer_resume.py -k 'ack or eof' -q +# V4 — C4 已有路由与显式 EOF 最终确认;实际执行结果见报告 +.venv/bin/python -m pytest test/unit/network_api/test_fid_routes.py test/unit/network_api/test_resume_matching.py test/unit/network_api/test_transfer_control.py test/unit/network_api/test_transfer_handshakes.py -q +.venv/bin/python -m pytest test/integration/network_api/test_tcp_transfer_resume.py test/integration/network_api/test_tcp_transfer_control.py -k 'ack or eof or forward or relay or parallel_recoveries' -q # V5 — C5 转发入口 .venv/bin/python -m pytest test/integration/network_api/test_tcp_file_transfer.py test/integration/test_forward_extension.py test/integration/test_forward_msg_attribution.py test/integration/network_api/test_tcp_transfer_control.py -k 'forward or relay or self_target' -q # V6 — 最终一次受影响范围合并回归,不扩为项目全套 @@ -231,7 +300,7 @@ flowchart TD - **S2** `--case relay-leg`:稳定 upstream/child、完成集合及旧 worker/旧控制会话交叉;证明旧任务不借新控制 socket。 - **S3** `--case global-pause`:至少两个 Target,逐一发请求,确认后 Source 不新增块、旧块排空、同 socket start、压力硬门槛。 - **S4** `--case parallel-recovery`:不同实际 offset;原 route 在线/暂停/EOF/握手/finally barrier;A 正文与 ACK 分别阻塞时 B 及晚到 Target 仍建流并传输;Source 离线排队、Target 断线丢旧请求并以新 offset 重发、单流失败与无关 fid。观察每流内容/资源、共享全局 pause、累计真实 ACK;不复用旧 serial-recovery 结论。 -- **S5** `--case eof-confirm`:真实目标 ACK 后定向注入上游 ACK False/异常,再做同 fid 零正文确认,验证再次失败和重启。 +- **S5** `--case eof-confirm`:复用原 route/completed,真实 Target ACK 后注入上游 ACK False/异常,再由 Source 显式同 fid 零正文确认;证明 Target 离线也无需重开、重复失败保留、旧规范记录重载后仍可显式确认,最终 ACK/内容/owner 清理符合 C4-P01–P10。 - **S6** `--case self-target`:自身、混合目标和本机不同端口,保留合法目标传输结果。 每个 case 参数矩阵覆盖明文/加密,以及 thread/async 的对应实际分派;原端点重连覆盖配置别名、wildcard。用 Event/Barrier 固定顺序,计时只用于失败截止,不靠 sleep 碰运气。 @@ -243,9 +312,9 @@ flowchart TD - **公共契约/协议影响**:公开签名、稳定 fid/child、文件/转发命令、pause/start、端口响应及持久化 schema 不变,不新增 wire。撤回 `?`/`None` 查询;恢复行为改为数值请求等待原 route 全收尾,再每 Target 独立并行流。 - **持久化模型不变**:保留五项文件行、scoped key 和 relay schema,不新增版本、route total 或腿编号;独立流进度只在运行时,整任务行不得被单流提前清理。 - **并发风险**:禁止持全局锁等 I/O/线程;原 route barrier 必须涵盖 finally,后续独立恢复流不相互充当 barrier;端口短锁不得覆盖正文/ACK。共享控制 owners 最后释放、旧 finally 按身份清理。问题二严格代次隔离继续暂缓。 -- **完成/失败语义**:单 Target 真实 ACK 不伪造整体成功;累计全部真实 Target ACK 后才整任务成功。单流失败不得取消兄弟或自动重试;Source 离线保留请求,Target 断线丢旧 socket 请求并等待新 offset。C4 全完成后的上游 EOF 再确认未实现。 +- **完成/失败语义**:单 Target 真实 ACK 不伪造整体成功;A 成功清 A 所属接收行/反向索引/资源,B 未完成保留 B 恢复关联和 Source 共享上传行。C4 只在已有完整完成集合上显式 EOF 补 ACK,复用原记录;不新增终态表/完成位/Server 字节进度,不更改 C3 并行模型。ACK 写成功与对端收到的不确定性仍不解决。 - **平台边界**:运行环境能验证的 Linux 结果不代替 native Windows;Windows/其他 Python 版本如未实际运行,报告明确未覆盖。不得通过改 CI 或阈值规避。 - **规则沉淀**:实际会话取消、数值实际 offset、原 owner/finally barrier、不同 offset 独立并行、晚来目标不等正文/ACK、全局 pause 与真实 ACK 聚合成为本轮回归路径;不新增源码字符串断言或严格代次隔离承诺。 - **文档/报告**:最终报告逐 P01–P20 给结论,单列问题二暂缓;每个原子变更含意图、范围、数据流、局部命令、未覆盖项、风险;文档随变更完成,不留“以后补”。 -本轮实现和局部证据已交付[实施报告](transfer-control-lifecycle-report.md),等待人工审查。旧 C3a/C3b 查询/强制 teardown/串行轮次及其结果仅保留为撤回历史。C4–C6 未实现,不自动推进,不自动提交、合并或推送。 +C3/C4 实现与实际证据见[实施报告](transfer-control-lifecycle-report.md)。C4 保持已批准的路径、文件范围、单原子拆分及记录模型;未执行参数不列覆盖。C5/C6 不自动推进,合并与推送仍须人工确认。 diff --git a/docs/plans/transfer-control-lifecycle-report.md b/docs/plans/transfer-control-lifecycle-report.md index 1ae719f..59f89bc 100644 --- a/docs/plans/transfer-control-lifecycle-report.md +++ b/docs/plans/transfer-control-lifecycle-report.md @@ -1,5 +1,102 @@ # 传输控制生命周期实施报告 +## C4:复用既有 route 的显式 EOF 补最终确认 + +**提交意图**:全部 accepted Target 已真实 ACK、上游最终 ACK 明确 False/异常后,由 Source 显式补最终确认,不重新交付文件。用户 `/skill:implement` 已授权本单一原子变更、验证、审查及提交当前分支;不推进 C5/C6,不合并或推送。此前任务迁移、独立终态表及 C4a/C4b 拆分均撤回。 + +### 更改路径、解决的问题与数据流 + +- `PyFlow/network_api/connect_tcp.py`:`_forward_item_handler` 在在线目标过滤前识别既有完整 completed route,校验当前实际 Source socket、originator 和单个原目标;`_forward_relay` 复核 route 对象并复用 receive reservation,原始/独立恢复 owner 或 finally 仍在时拒绝,终态仅建上游数据腿;`_forward_pump` 完整读取既有头、严格要求 offset=size,零正文后按完整完成集合发原最终 ACK,写成功才调用 `_drop_fid_route`。 +- `test/unit/network_api/test_fid_routes.py`:旧 schema 完整完成快照重载、无反向索引/字节进度行;实际控制分派拒绝错误 Source、旧 socket、错误成员、多目标及部分完成伪终态。 +- `test/integration/network_api/test_tcp_transfer_resume.py`:扩展原上游 ACK 失败场景到 file/folder/empty、False/异常、目标离线、再次失败与显式成功;加入非法头/非 EOF/finally busy;扩展 C3 独立恢复最后一流 ACK 失败后的补确认,保留兄弟内容、独立 offset、真实 ACK 与 owning 清理断言。 +- 四份使用/变更文档、需求卡、计划、本报告同步;`GLOSSARY.md` 为用户规划阶段已澄清的领域术语。Source `file_transfer_mode/_send_file`、公开签名、wire、五项行、scoped key、relay schema、依赖、CI、coverage 均不变。 + +数据流:`Source.resume_trans(原 Target, fid, total)` 预留 worker → 原 `/forward_item ... fid=... resume=...` → 实际会话/成员/完整完成集合/owner 准入 → 原 port/stamp/Source→Server 数据连接 → 完整 name-length/name/size 且 offset=size → 原最终 ACK → Server 按 route 身份删除,Source 实际消费 ACK 后清共享上传行。任一失败只收尾本次资源并保留原依据;bool=True 不是完成证据。 + +### 本轮实际检查(不借 C1–C3 历史通过数) + +| 实际命令/范围 | 结果 | +|---|---| +| `test_fid_routes.py` + 上游 ACK 失败及非法头/finally 两个集成函数 | 52 passed,32.23 秒,退出 0 | +| `test_forward_recovery_waits_for_old_finally_and_runs_targets_independently` 四参数 | 4 passed,23.51 秒,退出 0 | +| `uv tool run ty check PyFlow/network_api/connect_tcp.py --output-format concise` | 退出 1,最终 37 条诊断,全部位于本次生产修改范围外;不声明类型检查通过 | +| 完整 `.venv/bin/python -m pytest -q --tb=short`,仅一次 | 984 passed、1 failed、1 skipped,1369.13 秒,退出 1;唯一失败为旧自动背压消息契约 | +| 新 scoped-owner 真实复现 + 获批背压迁移(修复前) | 1 failed、1 passed,11.55 秒;前者实际 `/forward_error ... 'relay source is already active'`、Source False,证实审查 P2 | +| 最后窄组合:fid_routes、上游 ACK/非法头/finally、独立恢复、scoped owner、背压 | **58 passed,72.94 秒,退出 0**;包含最后生产修正与迁移测试 | + +```bash +.venv/bin/python -m pytest test/unit/network_api/test_fid_routes.py test/integration/network_api/test_tcp_transfer_resume.py::test_forward_ack_write_failure_retains_source_and_completed_route test/integration/network_api/test_tcp_transfer_resume.py::test_eof_confirmation_ignores_old_recovery_owner_for_another_target test/integration/network_api/test_tcp_transfer_resume.py::test_eof_confirmation_rejects_bad_headers_and_waits_for_finally test/integration/network_api/test_tcp_transfer_resume.py::test_forward_recovery_waits_for_old_finally_and_runs_targets_independently test/integration/network_api/test_tcp_file_transfer.py::test_forward_flow_control_pauses_uploader -q --tb=short +``` + +完整 pytest 的唯一失败 `test_tcp_file_transfer.py::test_forward_flow_control_pauses_uploader` 仍要求自动 `/pause_trans`、`/start_trans`,与已批准 C2 的本地 reader 高低水位门槛相反。用户已明确选择 `migrate_contract`,扩大计划仅迁移该函数:Event 固定慢 writer,证明 reader 真正等待、峰值不超过 high_water+单次扇出、排空解除、真实 Source ACK=True 及完整内容;不改生产背压。修正后按批准仅运行上述 58 项窄组合,**没有重跑完整套件,不能写最终全套全绿**。V4 启动作业在宿主重置后无可取回结果,不计通过数;完整 pytest 也不等于 C6 路径总验收。 + +最初 EOF 专项的五个拒绝案例因 Server 夹具未标 `running=True` 而不分派;非法头案例误用 `_forward_read_sign(error_sign)`,该 helper 对错误标记本就返回 None。修正夹具并实读精确 `/FER\n` 后,6 passed;随后上述 52 passed。未删/skip 用例、弱化内容/ACK/所有权断言或修改阈值。类型检查的新增 `None.decode` 诊断通过局部 ACK 变量显式收窄消除,不压制诊断或修改配置。 + +### S5:独立真实程序核心六组与边界补充 + +一次性 `/tmp/pyflow-transfer-lifecycle-smoke.py --case eof-confirm` 不调用 pytest 函数、不 mock 文件/socket/加密主路径。仅在最终 ACK 发送点注入 False/异常,其他钩子透传观测;无关普通 fid 在自己的最终 ACK Event 内保持活跃。每组先有两个真实 Target ACK,再失败一次补确认,最后显式成功;重载组使用原进度快照和同一 Source 实际控制端点,Target 不必回连。 + +| 实际参数 | upstream fid | 原 child fid(A / B) | workers / 最终存活 | +|---|---:|---|---| +| 明文 thread、localhost、folder、一个 Target 离线 | 7921691084 | 8074621898 / 12369589194 | 37 / 0 | +| 加密 thread、ACK 异常、Server/Source 快照重载、全部 Target 离线 | 11969814140 | 20188156416 / 24483123712 | 91 / 0 | +| 加密 async、wildcard、tracking off 既有行、空文件 | 8971573408 | 19441350896 / 23736318192 | 77 / 0 | +| 加密 thread、补确认头中断 data socket | 11110766478 | 18854031844 / 23148999140 | 74 / 0 | +| 加密 async、补确认头中断 control socket、原端点重载 | 8664377964 | 19983341822 / 24278309118 | 94 / 0 | +| 加密 async、补确认头中 stop、原端点重载 | 11276679026 | 19617231540 / 23912198836 | 96 / 0 | +| 加密 thread、一个有效确认等头时另一个同 fid 有效请求被拒,再中断/显式完成 | 9056271540 | 19920162170 / 24215129466 | 76 / 0 | +| 加密 thread、原端点重载后 ECDH 公钥发布延迟、前置确认 ACK False 后继续显式完成 | 10989437228 | 20366252022 / 24661219318 | 95 / 0 | + +六组各退出 0;前三组批命令 34.42 秒,后三组 39.23 秒。上游 ACK 尝试均为 False→False→True,两个显式 Source 结果 False→True。两次确认逐字节仅发送原三段文件头,正文为 0;Target 命令/数据建连仍只有最初两份,原 child fid 不变,目标 inode/mtime/完整内容不变。非空内容为 131335 字节,SHA-256 `8dd07ed5180fd145d6805a4c2e20aa622b00a18770417c0c5372cc31c6f7fff9`;空文件 SHA-256 `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`。两个无关普通传输均在补确认后才放行,实际 ACK=True、内容一致。 + +每组记录两条不同数据 socket 与同一实际控制 owner;加密组真实 channel.secure=True,明文组无加密 channel。失败快照只有原 `upload/download/relays` 类别和 `originator/targets/completed` 字段;最终 route/index/recovery/所属行及快照清空。未抓包,不扩大为全部加密连接安全审计。首次明文程序在已完成传输后因仅观测 `_crypto_attach_transfer_out`(明文不会调用)失败;改在通用 socket 登记边界透传观测后通过,未修改生产实现。 + +另两组边界程序分别验证同 fid 有效确认竞争(表第七行)与密钥窗口(第八行,`PYTHONPATH="$PWD" .venv/bin/python /tmp/pyflow-c4-ready-window.py`,17.35 秒,退出 0)。密钥窗口用 Event 延迟真实 ECDH 公钥发布;此时 RSA 控制通道已安全发送请求,实际 request_secure=[True],上游 stamp 为加密,Source owner 仍在、未收到 ACK;放行密钥后真实数据通道完成,额外注入 ACK False 仍保留原行,再走显式 False→True。该窗口不要求错误地等待 `_wait_control_secure` 调用次数。该程序曾在旧实例停机顺序、重复加载返回计数及错误的 RSA/ECDH 阶段假设处失败;改为显式关闭待重载实例、核验真实行及实际加密通道后通过,没有改生产握手、放行明文或压制异常。密钥未就绪窗口为 thread 组,未扩大为 async/rekey 全矩阵。 + +两个一次性程序均已删除;所有传输文件、隔离进度与密钥目录由 TemporaryDirectory 清理。上述独立程序先于最后的 scoped-owner 范围修正;最终修正以 58 项窄组合中的真实新旧 route/finally 回归为证据,不冒充之后重跑过全部独立程序。 + +```bash +export PYTHONPATH="$PWD" +.venv/bin/python /tmp/pyflow-transfer-lifecycle-smoke.py --case eof-confirm --alias --kind folder --offline one +.venv/bin/python /tmp/pyflow-transfer-lifecycle-smoke.py --case eof-confirm --encrypted --ack-failure exception --reload +.venv/bin/python /tmp/pyflow-transfer-lifecycle-smoke.py --case eof-confirm --encrypted --async-server --wildcard --untracked --empty +.venv/bin/python /tmp/pyflow-transfer-lifecycle-smoke.py --case eof-confirm --encrypted --fault-path data +.venv/bin/python /tmp/pyflow-transfer-lifecycle-smoke.py --case eof-confirm --encrypted --async-server --fault-path control +.venv/bin/python /tmp/pyflow-transfer-lifecycle-smoke.py --case eof-confirm --encrypted --async-server --fault-path stop +``` + +### C4 路径逐项对照及风险 + +| 路径 | 实际覆盖 / 明确限制 | +|---|---| +| C4-P01 原始全部 ACK 后上游失败 | 专项 file/folder/empty × False/异常及六组双 Target 真实内容/ACK/保留证据 | +| C4-P02 最后一条 C3 恢复流失败 | 四参数独立恢复,late-target 两参数注入最后 ACK False,再显式 EOF;已完成兄弟不重放 | +| C4-P03 零正文/无 Target 重开 | 专项三种条目及六组 header/内容/hash/Target 命令/实际数据连接观测 | +| C4-P04 再失败、显式重做 | False 与异常两种专项、六组 False→False→True;每次失败保留原对象/快照 | +| C4-P05 一个/全部 Target 离线 | 明文一目标离线,其余组全部离线;部分完成不能借 EOF 成功另有拒绝案例 | +| C4-P06 旧规范快照重载 | unit 完整完成 route、Source 行重载;加密 thread 同实际端点重建 Server/Source 后显式成功 | +| C4-P07 非法请求/头/非 EOF | 实际控制五种身份/成员拒绝,offset 小/大于 size、截断头;中断程序只发送两字节头,失败保留 | +| C4-P08 独占和 finally | 同任务 finalizing owner 与有效确认竞争均拒绝;新增同值 fid、不同 Source/Target 的真实新旧 route/finally 交叉,新任务在旧 finally 未放行时补确认成功、旧 record 身份保持;未专门强制同 key 对象被替换后的 C4 清理交叉 | +| C4-P09 中断/stop/安全入口 | 三组真实 data/control/stop 中断后清本次资源并显式完成;另有 RSA 控制已安全/ECDH 尚未发布的 thread 窗口,加密 stamp 与 ACK 失败保留;不声明 async/rekey 完整矩阵 | +| C4-P10 tracking off/别名/wildcard/无关 fid | 两组无关普通 fid 保持活跃并最终真实 ACK;tracking off 只复用既有行,别名及 wildcard 分组运行,不声称全部组合 | + +高风险审查关注实际会话、已完成集合、finally barrier 和对象身份清理。未运行 native Windows、其他 Python 版本、完整参数笛卡尔积、NAT/端点迁移或断电耐久性。失败且未再操作的原 route 可长期保留,本次不加 TTL;ACK 本地写成功但 Source 未收到的歧义不解决;本次 EOF 头不验证历史 name/size/hash,源文件须保持可用且未变。问题二严格代次隔离继续暂缓,C5/C6 未实施。 + +文档机械检查:上述八份需求/计划/报告/术语及使用文档,9 个相对文件链接,缺失目标 0;仅检查链接,不代替功能验收。 + +规则沉淀为真实消费者契约:EOF 不等于交付完成、完整 Target 完成集合与严格 EOF 缺一不可、busy/finally 不抢占、ACK 失败保留且显式成功 owning 清理。工具限制:Python LSP 仍仅 Ruff,definition 请求返回 Unknown request,未声称已完成符号引用分析。 + +### Standards + +发现 1 个 P2,已复现并修复:旧 route 在真实 ACK 成功后已删除,但独立恢复的 `(旧 Target, fid)` 接收 owner 尚在 finally;另一 Source/Target 此时合法复用同值 fid,其 C4 被全表 fid 扫描误拒。`confirmation_busy` 现只将当前 route Target 集合内的 tuple key 计为冲突,整型任务 key 仍排他。回归通过真实两条 route 和 Event 固定旧 finally,修复前 Source False、修复后 True;最终 58 项组合通过。未发现删减/跳过测试、安全 I/O 旁路、非 owning 清理、未经批准扩围等硬规则违规;Fowler 独立启发式 0 项。 + +### Spec + +实现缺陷 0 项、生产越界 0 项。审查时提示的多 Target、全部离线、两端快照重载、再次失败、有效确认竞争、无关 fid 及密钥窗口证据,已由上表和逐路径记录分别补齐或注明实际运行范围;未把全部参数笛卡尔积、未知 fid 的专用 S5 场景、native Windows 或所有 rekey 交叉冒充已验证。用户批准的单函数测试迁移不恢复旧自动控制协议。 + +本次保留一个 C4 原子提交,不拆 C4a/C4b。生产与测试之外同步了较长的需求/计划/报告及先前术语澄清,整体审查规模超过最初 300–500 行预估;不将文档拆名冒充多个已审的小提交。提交仅包括本代理与子代理的选定行,分支提交不等于人工合并批准,不推送。 + + ## 本轮 C3 替代方案:已实现,局部运行证据如下 **当前状态:用户批准的数值请求、原 owner 收尾、独立并行恢复已实现并取得局部运行证据。** C1/C2 保留。最终四份 unit 文件 228 passed;转发集成整批 52 passed、3 个旧内部断言失败,迁移后专项 3 passed;新全局控制专项 3 passed,独立程序 3 组真实传输通过。上述是分次运行,不伪称最终单次整批全绿,不声明全部矩阵或 C6 总验收通过。旧 C3a/C3b 查询/强制 teardown/串行轮次仅为撤回历史;C4–C6 未实现。 diff --git a/docs/plans/transfer-control-lifecycle-requirements.md b/docs/plans/transfer-control-lifecycle-requirements.md index 6328599..3fa1a22 100644 --- a/docs/plans/transfer-control-lifecycle-requirements.md +++ b/docs/plans/transfer-control-lifecycle-requirements.md @@ -1,8 +1,8 @@ # 传输控制生命周期与转发恢复 — 需求卡 -状态:**用户批准的数值 offset、每 Target 独立并行恢复已实现并取得局部运行证据,详见实施报告**。已撤回旧 C3 的 `/resume_trans ... ? ...`、`offset=None`、强制 teardown 和单活跃 Target/FIFO 轮次。Receiver 提交实际落盘数值 offset;Server 等同一原 route 的旧 owner(含 finally)全部收尾后,为每个 Target 独立建立 Source→Server→Target 流,正文并行。C1/C2 保留;C4–C6 未实现,不自动推进。 +状态:**C4 实现、局部验收与双轴审查完成;最终窄组合 58 passed,完整测试及类型检查限制见报告**。复用既有 fid route/completed 和 Source 共享任务上传行,仅补全部 Target 已完成后的显式 EOF 最终确认;不新增完成表、完成字段、Server 转发字节进度行或快照格式。C1/C2/C3 保留,撤回的查询/强制 teardown/串行恢复不恢复;C5/C6 不自动推进。 -本轮命令、实际结果、失败修正及明确未覆盖项见[实施报告](transfer-control-lifecycle-report.md)。旧 C3a/C3b 仅为已撤回方案的历史证据,不作为本轮通过结果;不自动提交、合并或推送。 +本轮命令、实际结果、失败修正及明确未覆盖项见[实施报告](transfer-control-lifecycle-report.md)。旧历史结果不作为 C4 通过证据。用户通过 `/skill:implement` 授权实现、检查、审查及提交当前分支;不合并或推送。 计划编写阶段的文档机械检查通过:3 份文档、6 个相对链接、21 个计划涉及的既有文件路径、14 个验收命令引用路径、20 条验收路径、6 个原子阶段及命令组、6 个拟定运行场景,错误数为 0。当时实施报告尚未创建;这份历史检查不代表功能验收通过,当前实现证据另见实施报告。 @@ -24,7 +24,7 @@ 4. 不采用“每个 Target 持有独立暂停锁、必须本人解除”的规则。任意端的 start 仍可经 Source 仲裁解除用户暂停。自动背压的内存硬门槛不被用户 start 清除。 5. 有效转发恢复请求由 Receiver 在其旧接收 owner/文件收尾后,带实际数值 offset 提交 Server。Server 按 child fid/实际会话定位原 route;原 route 的数据腿、listener、握手、reader/writer 或 finalizing owner 尚未全部结束时只保存请求,不主动中断。全部旧 owner(含 finally)收尾后,按每个 Target 自己的 offset 独立转交 Source、建流;不复用旧 relay 内存、不更换 fid、不查询其他 Target 的 offset。 6. 后续 C5 目标为 Client 转发入口拒绝自身完整控制端点、允许同 host 不同端口;C5 本轮未实现,不作本轮完成项。 -7. 保留真实最终 ACK 判成功规则:每个 Target 的真实 ACK 只更新其完成集合,累计所有 accepted Target 的真实 ACK 才能使整任务成功;中间 Target 成功不伪造整 route ACK,Source 上传行及未完成 route 继续保留。Target 的数值 EOF 恢复仍需真实 ACK;C4“所有 Target 已完成、仅上游 ACK 明确失败”的再确认未实现。 +7. 保留真实最终 ACK 判成功规则:每个 Target 的真实 ACK 只更新其完成集合,累计所有 accepted Target 的真实 ACK 才能使整任务成功;中间 Target 成功不伪造整 route ACK。Source 的共享上传行保留到全部目标完成且收到最终 ACK。C4 已实现复用已有完整完成集合补最终确认,不将 offset==size 单独当作任务完成证据;运行证据与限制见实施报告。 8. 多个 Target 恢复各有独立 offset、Source→Server→Target 数据流、进度、资源及失败结果,正文并行。晚到 Target 不等待已有恢复流的大文件正文或 ACK;同一实际控制 socket+fid 仅端口握手短串行,不锁正文或最终 ACK。 ### 非目标 @@ -71,6 +71,21 @@ 代价与风险:原 route 尚有活跃传输、用户暂停或未结束的 ACK/finally 时,首次恢复继续等,不增加强制关闭、超时抢占或自动重试。旧 owner 全部收尾后的独立恢复流不互相等待正文/ACK。运行时 pending/active 不扩展持久化 schema,重启后仍由原接收记录重新请求;同 socket+fid 迟到控制消息的严格代次隔离仍暂缓。 +### D9:C4 复用现有 fid 路由与共享上传行(已批准并实现) + +- **目标**:所有已接受 Target 均已真实 ACK、Server 上游最终 ACK 返回 False/异常后,允许 Source 以原 upstream fid 和 EOF offset 显式再确认;不重发正文、不重开 Target,成功后清理所属记录,再次失败仍可显式操作。 +- **当前记录职责**:Source 只有一条以 `(Server, upstream_fid)` 为键的共享任务上传行;Target 各有接收进度;原生流式转发的 Server 不创建逐 Target upload/download 字节进度行,持久化的是 `relays` 下的 fid route。A 成功时其接收行、反向 child 索引和数据资源可清理,但 B 尚未完成时不能删 Source 共享上传行。 +- **完成依据**:复用 `_fid_routes[fid]` 的原 Source、完整目标映射及 `completed`;只在已接受目标非空且全部真实确认时允许终态分支。`offset == 本次文件头 size` 只判定零正文,不能生成缺失的目标完成事实。 +- **准入**:校验当前实际 Source 控制 socket、原 originator/upstream fid、请求目标属于原映射及当前 route 对象;不依赖已完成目标的反向索引。只在同任务旧 owner(含 finally)已退出后准入,忙/重复沿既有失败或占用规则拒绝,不抢占、不阻塞控制 reader/event loop。 +- **触发与路径**:仅 Source 显式 `resume_trans(原 Target, upstream_fid, 原上传记录 total)`;公开 bool 仍只是 worker 预留。重载原记录/原端点回连后仍显式发起;不增加重连自动补发或失败重试循环。Server 只开 Source→Server 数据腿,仍读取现有完整文件头并校验 EOF,不连接 Target、不要求其在线、不改写目标文件。 +- **清理与重启**:Server 仅在现有最终 ACK 写入成功后按 route 对象身份删除;Source 仅在实际消费该 ACK 后清所属共享行。失败保留原 route 和上传行,旧规范快照可直接按既有格式重载;不增加新的迁移器或持久化类别。 +- **影响范围**:生产仅调整 `connect_tcp.py` 的 Server 转发分派/建流/最终 ACK 分支,复用 Source 现有 EOF 发送及 owning 清理。对应测试、文档、路径全集和命令见[更改计划](transfer-control-lifecycle-plan.md)的 C4 章节。 +- **非目标/禁止项**:不把任务信息迁到 Source,不改五字段上传/下载行、route schema、公开签名或 wire;不新增完成表/完成位/Server 逐目标字节进度,不再拆 `file_transfer_mode/_send_file`,不混 C5/C6、CI、依赖或测试策略修改。 +- **风险与上限**:待补确认的旧 route 可能长期保留,本轮不增加 TTL 或自动清理;不承诺有界待确认任务数。上游本地 ACK 写成功但对端是否收到的歧义、源文件改变后的内容复核、NAT/端点迁移及断电耐久性仍不在保证内。风险等级高,必须真实 socket 与事件证明。 + +此前讨论的“取消所有 Server route、迁移到 Source”“新增 completed_relays 小终态表”“按 C4a/C4b 分拆压缩与确认”均已撤回;不进入当前实施清单。[术语表](../../GLOSSARY.md)只定义领域概念,不作为新增数据结构的授权。 + + ## 路径全集与验收证据要求 | 路径 | 必须证明的行为 | @@ -90,7 +105,7 @@ | Client 自转发与本机不同 Client | 拒绝自身完整控制端点,允许同 host 不同端口;统一入口覆盖 console/Web/文件夹/恢复 | | 加密、密钥交换窗口、线程式/async Server | 统一 send/receive 路径;无明文降级;不阻塞密钥接收线程;真实内容、ACK、资源收尾 | -验收须使用事件固定时序的真实本机 socket 传输,记录稳定 fid、实际 owner/socket、文件内容和最终 ACK;不能仅断言文件存在或测试没有抛错。问题二明确列为暂缓,不计入覆盖或通过声明。具体文件、协议、原子拆分及每条路径的验收命令见更改计划,均为待执行而非通过声明。 +验收须使用真实本机 socket 传输,记录稳定 fid、实际 owner/socket、文件内容和最终 ACK;交叉时序用事件固定,不能仅断言文件存在或测试没有抛错。问题二明确列为暂缓,不计入覆盖或通过声明。约定命令见更改计划,已执行结果仅以实施报告为准。 ## 数据、安全和范围约束 @@ -99,8 +114,8 @@ - 恢复入队不关闭任何活跃数据腿、健康控制连接或其他 fid,不删除接收文件;仅自然结束的旧 owner 做原有定向收尾。 - 不把 socket 仍打开或 offset 等于 size 单独作为成功证据。 - pause/start、端口响应、公开 Python 签名及持久化模型不变;不新增 wire 字段、leg_id 或恢复换新 fid。恢复 parser/formatter 只接受数值 offset;调度改为等待原 route 旧 owner 全收尾、每 Target 独立并行恢复。 -- 风险等级:高(多 owner 并发、全局控制共享、文件完整性和真实 ACK 聚合)。本轮实施及分次局部验证已记录;不宣称 C6 总验收通过,不自动提交、合并或推送。 +- 风险等级:高(多 owner 并发、全局控制共享、文件完整性和真实 ACK 聚合)。本轮实施及局部验证单列;不宣称 C6 总验收通过。按用户实施指令提交当前分支,不合并或推送。 ## 下一阶段闸门 -本轮 C3 替代方案的实现、局部命令及真实传输证据已交付[实施报告](transfer-control-lifecycle-report.md),等待人工审查。C1/C2 保留;旧 C3a/C3b 查询/强制 teardown/串行轮次仅作撤回历史。C4 EOF 再确认、C5 自目标拒绝及 C6 总体验收未实现,不因本轮完成自动推进。 +C4 已按用户 `/skill:implement` 指令完成实现、局部验收与审查,模型及单一原子拆分不变;用户另批准唯一旧背压测试的契约迁移。证据与未覆盖项见[报告](transfer-control-lifecycle-report.md)。本轮提交当前分支,不合并或推送;C5/C6 须另获批准。 diff --git a/docs/source/File_Transfer/File_Transfer.rst b/docs/source/File_Transfer/File_Transfer.rst index 19ec730..6b4b1e7 100644 --- a/docs/source/File_Transfer/File_Transfer.rst +++ b/docs/source/File_Transfer/File_Transfer.rst @@ -919,8 +919,9 @@ The temporary connections of a transfer are resumed after a disconnect: zero. The source owns the upstream FID and the Server allocates one child FID per target. Every listener replies through the same four-token ``/server_file_transfer_port `` line; the server validates - the sender and unresolved target and reuses the upstream and child FIDs. Stale - or mismatched responses cannot satisfy another request. The receiver matches + the original sender and accepted target and reuses the upstream and child FIDs. + Completed targets are eligible only for the all-Target reconfirmation below. + Stale or mismatched responses cannot satisfy another request. The receiver matches fid, original sender, basename and total size, then writes its retained full path, including nested folder items. A size mismatch preserves the partial file. No new-ID/path alias or old @@ -952,13 +953,13 @@ their listener or start handshake fails. A successful target loses its reverse index immediately, but the accepted mapping remains until the current input stream is fully read and every accepted target has acknowledged. The server then forwards the existing final data-ACK marker upstream using the normal -per-hop send path (encrypted when enabled). It drops the route only after that -ACK write succeeds; an unsuccessful write leaves the completed route available -for recovery. The source's original final-ACK wait is 30 seconds plus 10 seconds -per 100 MiB. A long pause or slow downstream delivery can outlast that wait; -timeout or a lost ACK conservatively retains the source upload progress, -even if the server completed delivery. No separate receipt or retry -protocol is used. If a target cannot send its final ACK, its receive entry +per-hop send path (encrypted when enabled). Only the owning route is removed +after that ACK write succeeds; a ``False`` result or exception retains it. +The source's original final-ACK wait is 30 seconds plus 10 seconds per 100 MiB. +A long pause or slow downstream delivery can outlast that wait; timeout or a +lost ACK conservatively retains the shared source upload row even if delivery +completed. No separate receipt or automatic retry protocol is used. +If a target cannot send its final ACK, its receive entry survives even when the disk file is complete; an EOF replay with the same fid can confirm it without retransmitting the body. @@ -1000,10 +1001,38 @@ No stale request is borrowed by a replacement session. One stream's failure does not cancel siblings or start an automatic retry loop. Existing retained rows can recover with tracking off, but no new recovery rows are fabricated. -All-Target completion followed by a failed upstream ACK remains retained; -the separate EOF reconfirmation lifecycle stage is not implemented here. -Delayed pause/start across same-session, same-fid data-leg replacement is -also explicitly deferred; no generation-isolation guarantee is added. +When every accepted Target has really ACKed but the upstream ACK write returned +``False`` or raised, Source can explicitly call +``resume_trans(original_target, upstream_fid, total)`` (C4). Use an original +accepted Target and the existing shared Source upload row; ``True`` means only +worker registration, not completion. A live, paused, negotiating or finalizing +owner, including ``finally`` cleanup, rejects the explicit operation as busy +without closing or queueing it; it can be repeated after owners finish. + +This opens only a Source-to-Server data connection using the existing port +reply and complete filename/size header. The requested offset must equal the +size in this attempt's header exactly. It sends zero body bytes and waits for +the existing final ACK; no Target connection, new Target leg or body replay is +needed, so Targets may be offline. Server validates the original Source and +accepted Target against the existing route's ``originator``/``targets`` and +requires all its ``completed`` evidence. It does not validate historical +filename, size or hash. No Server byte-progress or terminal-state table, field, +snapshot schema or wire change is introduced. + +Another ``False``/exception leaves the route and Source row for another explicit +attempt. Success removes only the owning route after its ACK write succeeds; +Source removes its shared row only after observing the final ACK. Existing +route/completion and upload snapshots reload with the same explicit recovery +requirement, not an automatic retry or TTL. This cannot resolve a successful +Server ACK write that Source never receives: the route may already be gone. +Ordinary transfers, C3 unfinished-Target recovery and global pause/start are +unchanged. These are control-layer extension points; Source +``file_transfer_mode`` and ``_send_file`` are unchanged. + +Delayed pause/start across same-session, same-fid data-leg replacement remains +deferred; no generation-isolation guarantee is added. Self-target rejection +(C5) and combined acceptance (C6) remain later stages. + Fids no longer encode a plain/relay kind: the reserved low bit is always zero, and diagnostics use ``e.``. Ordinary senders own their FIDs; the relay source owns the upstream FID and the Server allocates one child FID diff --git a/docs/source/Network_APIs/TCP_Client_APIs.rst b/docs/source/Network_APIs/TCP_Client_APIs.rst index d3640c7..cdc144f 100644 --- a/docs/source/Network_APIs/TCP_Client_APIs.rst +++ b/docs/source/Network_APIs/TCP_Client_APIs.rst @@ -331,9 +331,27 @@ commands sent by the server, such as: success. Source disconnection leaves requests queued at Server; Target disconnection discards its old-socket request and requires a new actual disk offset after reconnect. There is no automatic retry, and one Target's failure - does not cancel siblings. Strict same-session/fid generation isolation is - deferred; all-Target upstream EOF reconfirmation (C4), self-target rejection - (C5) and combined acceptance (C6) are not implemented by this revision. + does not cancel siblings. Strict same-session/fid generation isolation remains + deferred; C5 self-target rejection and C6 combined acceptance are later stages. + +After all Targets really ACK, a ``False``/exception writing the upstream ACK +retains the Server route and Source's shared upload row. For C4, Source calls +``resume_trans(original_target, upstream_fid, total)`` explicitly. ``True`` means +worker registration, not completion; a live owner, including ``finally`` cleanup, +returns busy without closing or queueing, so repeat explicitly after it exits. +Only Source connects to Server, exchanging the existing port reply, complete +filename/size header and final ACK with zero body bytes. Offset must equal the +size in this attempt's header exactly. No Target leg or body replay is created; +the original Target may be offline. Server uses its existing +``originator``/``targets``/``completed`` route, not historical name/size/hash +validation or a new byte-progress/terminal-state table. False/exception retains +state; successful ACK write removes only the owning route, and Source removes +its shared row only when it observes that ACK. Reloading existing snapshots +still requires this explicit action, without automatic retry, TTL or schema/wire +changes. A successful Server ACK write lost before Source receives it remains +ambiguous. Ordinary transfers, C3 and global pause/start are unchanged. The +control-layer extension leaves Source ``file_transfer_mode`` and ``_send_file`` +unchanged; see :ref:`transfer-pause-and-reconnect`. For a new relay upload, the source client allocates the upstream FID before it sends ``/forward_item ... fid=``. The server returns that same upstream FID diff --git a/docs/source/Network_APIs/TCP_Server_APIs.rst b/docs/source/Network_APIs/TCP_Server_APIs.rst index a2ba70e..12c4d26 100644 --- a/docs/source/Network_APIs/TCP_Server_APIs.rst +++ b/docs/source/Network_APIs/TCP_Server_APIs.rst @@ -726,15 +726,26 @@ Built-in client commands include: offset after old receive cleanup. One stream's failure does not cancel siblings or automatically retry. A real Target ACK updates only its own completion; intermediate success cannot fabricate an overall route ACK. - Strict same-session/fid generation isolation remains deferred. C4 all-Target - upstream EOF reconfirmation, C5 self-target rejection and C6 combined - acceptance are not implemented by this revision. -- Forwarded transfers return the existing final data-ACK marker upstream only - after the current input stream is complete and every accepted target has - acknowledged. The normal send path reframes the marker for the upstream hop; - the route is dropped only after the ACK write succeeds. A failed write keeps - the completed route for recovery. This does not change ordinary sender or - server receive-ACK behavior. + Strict same-session/fid generation isolation remains deferred; C5 self-target + rejection and C6 combined acceptance remain later stages. +- After all accepted Targets really ACK, a ``False``/exception writing the + upstream final ACK retains the existing route for C4 reconfirmation. Source + explicitly calls ``resume_trans(original_target, upstream_fid, total)``; + ``True`` reserves a worker, not completion. Live owners, including ``finally``, + reject this explicit operation as busy; retry explicitly after cleanup. + Server validates the original Source and accepted Target using the existing + ``originator``/``targets``/``completed`` route. Only a Source-to-Server data + connection is opened: the normal port reply and full header are required, + with offset exactly equal to this header's size, zero body bytes and the + existing final ACK. No new Target leg is opened; Targets may be offline. + Another false/exception retains route and Source shared upload row. Success + removes only the owning route after the ACK write; Source removes its row + only on observing the ACK. Existing snapshots still require explicit recovery, + without automatic retry, TTL, new Server byte-progress/terminal table or + schema/wire fields. Historical name/size/hash are not validated; a successful + ACK write lost before Source receives it remains ambiguous. Ordinary transfers, C3 + and global pause/start are unchanged, as are Source ``file_transfer_mode`` + and ``_send_file``. See :ref:`transfer-pause-and-reconnect` for details. - ``/server_file_transfer_port ``: the four-token listener reply for ordinary, public-key and relay legs. Replies match the actual control socket and FID (the source-provided upstream FID for relay upload). Each diff --git a/docs/source/changes/transfer-fid-routes.md b/docs/source/changes/transfer-fid-routes.md index ec7ee7b..050669d 100644 --- a/docs/source/changes/transfer-fid-routes.md +++ b/docs/source/changes/transfer-fid-routes.md @@ -7,6 +7,32 @@ > `docs/plans/transfer-pause-start-direction-report.md`; those historical > results are not verification of the current lifecycle revision. +## Lifecycle revision C4: explicit all-Target EOF reconfirmation + +- After every accepted Target's real ACK, an upstream final-ACK write returning + `False` or raising retains the existing Server route and Source shared upload + row. Source explicitly calls `resume_trans(original_target, upstream_fid, total)`; + its boolean reports worker registration, not completion. Live owners, including + `finally`, reject this explicit operation as busy without closing or queueing; + it can be repeated after cleanup. +- Reuse `_fid_routes[fid]` with `originator`, full `targets` and `completed`, and + Source's existing upload row. Only Source→Server port negotiation, the complete + existing filename/size header and final ACK are exchanged. Offset must equal + this header's size exactly; there are zero body bytes, no new Target leg and + no retransmission. Targets may be offline. No Server byte-progress or terminal + table, field, snapshot schema or wire change is added. +- Another false/exception retains state. Only the owning route is removed after + its successful ACK write; Source removes its shared row only on observing the + ACK. Existing route/completion and upload snapshots reload with the same + explicit recovery requirement, not automatic retries or TTL. This does not + resolve a successful Server ACK write lost before Source receives it, and + does not validate historical name/size/hash. +- Ordinary transfers, C3 unfinished-Target recovery and global pause/start stay + unchanged. This extends transfer control without changing Source + `file_transfer_mode` or `_send_file`. Strict same-session/fid generation + isolation remains deferred; C5 self-target rejection and C6 combined acceptance + remain later stages. No verification results are claimed in this entry. + ## Lifecycle revision C3: numeric offsets and independent parallel recovery - The user approved the revised requirements and plan. Old C3a/C3b offset @@ -37,8 +63,9 @@ requests; reconnect requires a fresh actual disk offset on the new session. Individual failure does not cancel siblings or start automatic retries. - Strict same-session/fid generation isolation remains deferred. C4 all-Target - upstream EOF reconfirmation, C5 self-target rejection and C6 combined acceptance - are not implemented. No new wire, schema, dependencies or CI changes. + upstream EOF reconfirmation is documented above; C5 self-target rejection and + C6 combined acceptance remain later stages. No new wire, schema, dependencies + or CI changes. - This round is **pending unified verification**. Old C3a/C3b pass counts do not verify this replacement. Paths, risks and historical evidence are recorded in `docs/plans/transfer-control-lifecycle-report.md`. diff --git a/test/integration/network_api/test_tcp_file_transfer.py b/test/integration/network_api/test_tcp_file_transfer.py index d1b2420..e84cb46 100644 --- a/test/integration/network_api/test_tcp_file_transfer.py +++ b/test/integration/network_api/test_tcp_file_transfer.py @@ -751,42 +751,68 @@ def got(path): def test_forward_flow_control_pauses_uploader(pair, tmp_path, monkeypatch): - """When the server's in-memory buffer exceeds max_mem_buff it pauses the - uploader with /pause_trans and resumes it with /start_trans; the file is - still delivered intact.""" + """Local backpressure bounds queued bytes without changing user pause state.""" server, target, recv_dir = pair - # strictly below one 64 KiB relay chunk, so every chunk overflows the - # buffer and a /pause_trans -> /start_trans cycle is guaranteed (a limit - # of exactly one chunk sits at the > comparison boundary and makes the - # pause depend on thread scheduling) server.max_mem_buff = 32 * 1024 src = tmp_path / "big.bin" payload = os.urandom(300 * 1024) src.write_bytes(payload) forwarder = _forward_client(server, tmp_path / "fwd") - - sent = [] - real_send = server.send_message - - def spy(sock, message, is_send_raw=False): - sent.append(message if isinstance(message, str) else "") + writer_held, release_writer, reader_waiting = ( + threading.Event(), threading.Event(), threading.Event() + ) + relays, controls, acknowledgements = [], [], [] + real_send, real_pump = server.send_message, server._forward_pump + real_wait = threading.Condition.wait + real_transfer = forwarder.file_transfer_mode + + def pump(up_sock, target_conns, control, fid, fname, relay, resume_offset=0): + relays.append(relay) + return real_pump(up_sock, target_conns, control, fid, fname, relay, resume_offset) + + def send(sock, message, is_send_raw=False): + if isinstance(message, bytes) and len(message) > server.max_mem_buff: + writer_held.set() + assert release_writer.wait(timeout=15) + if isinstance(message, str) and message.startswith(("/pause_trans", "/start_trans")): + controls.append(message) return real_send(sock, message, is_send_raw=is_send_raw) - monkeypatch.setattr(server, "send_message", spy) - a = target.client_socket.getsockname() - cmd = '/forward_file "{}" "({}, {})"'.format(src, repr(a[0]), a[1]) - forwarder.forward_file_console(cmd) - - def got(path): - return path.exists() and path.stat().st_size == len(payload) - - assert wait_until(lambda: got(recv_dir / "big.bin"), timeout=25), ( - "forwarded file was not received" - ) - assert (recv_dir / "big.bin").read_bytes() == payload - assert any(str(m).startswith("/pause_trans") for m in sent), "expected a /pause_trans" - assert any(str(m).startswith("/start_trans") for m in sent), "expected a /start_trans" - forwarder.close() + def wait(condition, *args, **kwargs): + if (relays and condition is relays[0]["cond"] + and relays[0]["buffer"]["backpressured"]): + reader_waiting.set() + return real_wait(condition, *args, **kwargs) + + def transfer(*args, **kwargs): + result = real_transfer(*args, **kwargs) + acknowledgements.append(result) + return result + + monkeypatch.setattr(server, "_forward_pump", pump) + monkeypatch.setattr(server, "send_message", send) + monkeypatch.setattr(threading.Condition, "wait", wait) + monkeypatch.setattr(forwarder, "file_transfer_mode", transfer) + try: + peer = target.client_socket.getsockname() + cmd = '/forward_file "{}" "({}, {})"'.format(src, repr(peer[0]), peer[1]) + forwarder.forward_file_console(cmd) + assert writer_held.wait(timeout=10) and reader_waiting.wait(timeout=10) + state = relays[0]["buffer"] + with relays[0]["cond"]: + assert state["backpressured"] and state["buffered"] > state["high_water"] + assert state["peak"] <= state["high_water"] + state["max_enqueue"] + assert acknowledgements == [] + release_writer.set() + assert wait_until(lambda: acknowledgements == [True], timeout=15) + assert (recv_dir / "big.bin").read_bytes() == payload + assert wait_until(lambda: not server._forward_relays and not server._receive_transfers) + assert not state["backpressured"] and state["buffered"] == 0 + assert state["peak"] <= state["high_water"] + state["max_enqueue"] + assert controls == [], "automatic pressure must not send user pause/start" + finally: + release_writer.set() + forwarder.close() def test_forward_file_with_destination(pair, tmp_path): diff --git a/test/integration/network_api/test_tcp_transfer_resume.py b/test/integration/network_api/test_tcp_transfer_resume.py index 31c4c37..bc7aace 100644 --- a/test/integration/network_api/test_tcp_transfer_resume.py +++ b/test/integration/network_api/test_tcp_transfer_resume.py @@ -1699,11 +1699,13 @@ def observe_upstream_ack(sock, message, is_send_raw=False): _close_socket_workers(server, clients, workers) +@pytest.mark.parametrize("kind,empty", [("file", False), ("folder", False), ("file", True)], + ids=["file", "folder", "empty"]) @pytest.mark.parametrize("ack_failure", ["false", "exception"]) def test_forward_ack_write_failure_retains_source_and_completed_route( - tmp_path, monkeypatch, ack_failure + tmp_path, monkeypatch, ack_failure, kind, empty ): - """A failed original ACK write keeps the source upload and the Server route.""" + """Failed upstream ACKs can be explicitly reconfirmed without reopening Targets.""" workers = _track_socket_workers(monkeypatch) server = _start_server(tmp_path) clients = [] @@ -1717,8 +1719,10 @@ def test_forward_ack_write_failure_retains_source_and_completed_route( target_addr = target.client_socket.getsockname() assert wait_until(lambda: target_addr in server.clients) src = tmp_path / "ack_write_failure.bin" - payload = os.urandom(64 * 1024 + 37) + payload = b"" if empty else os.urandom(64 * 1024 + 37) src.write_bytes(payload) + rel_dir = "bundle/nested" if kind == "folder" else "" + output = recv_dir / rel_dir / src.name failed_writes = [] real_send = server.send_message @@ -1726,16 +1730,17 @@ def fail_upstream_ack(sock, message, is_send_raw=False): marker = message.encode("utf-8") if isinstance(message, str) else message if marker == server.server_received_file_data_sign.encode("utf-8"): failed_writes.append(sock) - if ack_failure == "exception": - raise ConnectionError("injected upstream final ACK write failure") - return False + if len(failed_writes) <= 2: + if ack_failure == "exception": + raise ConnectionError("injected upstream final ACK write failure") + return False return real_send(sock, message, is_send_raw=is_send_raw) monkeypatch.setattr(server, "send_message", fail_upstream_ack) - assert source._forward_one("file", "", src.name, str(src), [target_addr]) is False + assert source._forward_one(kind, rel_dir, src.name, str(src), [target_addr]) is False assert len(failed_writes) == 1 - assert wait_until(lambda: not server._forward_relays, timeout=10) - assert (recv_dir / src.name).read_bytes() == payload + assert wait_until(lambda: not server._forward_relays and not server._receive_transfers, timeout=10) + assert output.read_bytes() == payload assert wait_until(lambda: not target.file_recv_progress, timeout=10) assert len(source.file_upload_progress) == 1 upload_key, upload = next(iter(source.file_upload_progress.items())) @@ -1768,10 +1773,218 @@ def fail_upstream_ack(sock, message, is_send_raw=False): finally: reloaded.file_trans_progress_file = str(tmp_path / "inspection_progress.json") reloaded.close() + + target.close() + assert wait_until(lambda: target_addr not in server.clients) + outcomes, headers = [], [] + real_forward, real_source_send = source._forward_one, source.send_message + + def forward(*args, **kwargs): + result = real_forward(*args, **kwargs) + outcomes.append(result) + return result + + def observe_header(sock, message, is_send_raw=False): + if isinstance(message, bytes): + headers.append(message) + return real_source_send(sock, message, is_send_raw=is_send_raw) + + monkeypatch.setattr(source, "_forward_one", forward) + monkeypatch.setattr(source, "send_message", observe_header) + assert source.resume_trans(target_addr, fid, len(payload)) is True + assert wait_until(lambda: outcomes == [False] and not source._resume_sends, timeout=15) + assert len(failed_writes) == 2 + assert server._fid_routes[fid] is route + assert source.file_upload_progress[upload_key] is upload + assert source.resume_trans(target_addr, fid, len(payload)) is True + assert wait_until(lambda: outcomes == [False, True] and not source._resume_sends, timeout=15) + assert len(failed_writes) == 3 + expected = [len(src.name.encode()).to_bytes(4, "big"), src.name.encode(), + len(payload).to_bytes(8, "big")] + assert headers == expected * 2 # Both attempts sent a header and zero body bytes. + assert output.read_bytes() == payload + if kind == "folder": + assert not (recv_dir / src.name).exists() + assert not server._fid_routes and not server._fid_route_index + assert not source.file_upload_progress + assert wait_until(lambda: not server._receive_transfers and not server._forward_relays) + with open(server.file_trans_progress_file, encoding="utf-8") as stream: + assert json.load(stream)["relays"] == {} + with open(source.file_trans_progress_file, encoding="utf-8") as stream: + assert json.load(stream)["upload"] == {} + finally: + _close_socket_workers(server, clients, workers) + + +def test_eof_confirmation_ignores_old_recovery_owner_for_another_target(tmp_path, monkeypatch): + """A completed prior route's scoped finally cannot block a different Target.""" + workers = _track_socket_workers(monkeypatch) + server = _start_server(tmp_path) + clients = [] + held, release = threading.Event(), threading.Event() + try: + old_source = _start_client(tmp_path, server, name="old_source") + clients.append(old_source) + old_dir = tmp_path / "old_target" + old_dir.mkdir() + old_target = _start_client(tmp_path, server, name="old_target", recv_dir=old_dir) + clients.append(old_target) + old_peer = old_target.client_socket.getsockname() + path = tmp_path / "scoped_confirmation.bin" + payload = b"confirmed by two separate routes" + path.write_bytes(payload) + target_acks = [] + real_target_send = old_target.send_message + + def target_send(sock, message, is_send_raw=False): + if message == old_target.server_received_file_data_sign: + target_acks.append(sock) + if len(target_acks) == 1: + return False + return real_target_send(sock, message, is_send_raw=is_send_raw) + + monkeypatch.setattr(old_target, "send_message", target_send) + assert old_source._forward_one("file", "", path.name, str(path), [old_peer]) is False + fid = next(iter(server._fid_routes)) + assert wait_until(lambda: not server._forward_relays and not server._receive_transfers) + assert wait_until(lambda: not old_target._receive_transfers) + real_release = connect_tcp._release_receive + + def release_receive(instance, key, record): + if instance is server and key == (old_peer, fid): + held.set() + assert release.wait(timeout=30) + return real_release(instance, key, record) + + monkeypatch.setattr(connect_tcp, "_release_receive", release_receive) + assert old_target._request_resumes() == 1 + assert held.wait(timeout=15) + assert fid not in server._fid_routes + old_record = server._receive_transfers[(old_peer, fid)] + assert wait_until(lambda: not old_source._resume_sends) + + source = _start_client(tmp_path, server, name="new_source") + clients.append(source) + new_dir = tmp_path / "new_target" + new_dir.mkdir() + target = _start_client(tmp_path, server, name="new_target", recv_dir=new_dir) + clients.append(target) + peer = target.client_socket.getsockname() + control = server.clients[source.client_socket.getsockname()]["socket"] + # Independent Source allocators can choose the same value after the + # previous route has been dropped; the live key is still Target-scoped. + monkeypatch.setattr(source._fid_alloc, "alloc", lambda **kwargs: fid) + failures = [] + real_send = server.send_message + + def server_send(sock, message, is_send_raw=False): + record = server._receive_transfers.get(fid) + if (message == server.server_received_file_data_sign and not failures + and record is not None and record["control_socket"] is control): + failures.append(sock) + return False + return real_send(sock, message, is_send_raw=is_send_raw) + + monkeypatch.setattr(server, "send_message", server_send) + assert source._forward_one("file", "", path.name, str(path), [peer]) is False + assert len(failures) == 1 + assert wait_until(lambda: fid not in server._receive_transfers and not server._forward_relays) + assert server._fid_routes[fid]["completed"] == {peer} + outcomes = [] + real_forward = source._forward_one + + def forward(*args, **kwargs): + result = real_forward(*args, **kwargs) + outcomes.append(result) + return result + + monkeypatch.setattr(source, "_forward_one", forward) + assert source.resume_trans(peer, fid, len(payload)) + assert wait_until(lambda: not source._resume_sends, timeout=10) + assert outcomes == [True] + assert server._receive_transfers[(old_peer, fid)] is old_record + assert not release.is_set(), "unrelated finally was needed for confirmation" + assert fid not in server._fid_routes and not server._fid_route_index + assert not source.file_upload_progress and not old_source.file_upload_progress + assert (old_dir / path.name).read_bytes() == payload + assert (new_dir / path.name).read_bytes() == payload + release.set() + assert wait_until(lambda: not server._receive_transfers) finally: + release.set() _close_socket_workers(server, clients, workers) +def test_eof_confirmation_rejects_bad_headers_and_waits_for_finally(tmp_path, monkeypatch): + """An EOF request cannot bypass header validation or a finalizing owner.""" + from PyFlow.network_api.connect_tcp import _send_transfer_request + + workers = _track_socket_workers(monkeypatch) + server = _start_server(tmp_path) + source = _start_client(tmp_path, server) + released, cleaning = threading.Event(), threading.Event() + sockets = [] + fid, target = 713, ("127.0.0.1", free_port()) + try: + source._resume_thread.join(timeout=10) + origin, control = source.client_socket.getsockname(), source.client_socket + route = server._register_fid_route(fid, origin, {target: 714}, (target,)) + path = tmp_path / "confirmed.bin" + path.write_bytes(b"abc") + key = ((source.host, source.port), fid) + row = source.file_upload_progress[key] = [3, 3, None, str(path), target] + source._persist_transfer_progress() + real_release = connect_tcp._release_receive + + def release(instance, identity, record): + if instance is server and identity == fid and not released.is_set(): + cleaning.set() + assert released.wait(timeout=20) + return real_release(instance, identity, record) + + def request(offset): + with _transfer_handshake(source, control, fid) as handshake: + command = (f"/forward_item file fid={fid} resume={offset} " + f"confirmed.bin {shlex.quote(repr(target))}") + assert _send_transfer_request(source, handshake, command) + return source._transfer_handshakes.wait(handshake, 5) + + header = (len(path.name).to_bytes(4, "big") + path.name.encode() + + (3).to_bytes(8, "big")) + for offset, body in [(2, header), (4, header), (3, header[:-1])]: + result = request(offset) + assert result is not None and result[0] == "port" + data = socket.create_connection((source.host, result[2]), timeout=5) + sockets.append(data) + assert server._forward_read_sign(data, server.server_start_file_transfer_sign) + if not cleaning.is_set(): + monkeypatch.setattr(connect_tcp, "_release_receive", release) + data.sendall(body) + data.shutdown(socket.SHUT_WR) + with data.makefile("rb") as stream: + reply = stream.read() + assert reply == (server.error_sign + "\n").encode() + if not released.is_set(): + assert cleaning.wait(timeout=5) + blocked = request(3) + assert blocked is not None and blocked[0] == "error" + assert server._receive_transfers[fid]["owner"] is not None + released.set() + assert wait_until(lambda: not server._receive_transfers and not server._forward_relays) + assert server._fid_routes[fid] is route and route["completed"] == {target} + assert source.file_upload_progress[key] is row + data.close() + assert source.resume_trans(target, fid, 3) + assert wait_until(lambda: key not in source.file_upload_progress, timeout=10) + assert wait_until(lambda: not server._fid_routes and not server._receive_transfers) + assert not server.file_upload_progress and not server.file_recv_progress + finally: + released.set() + for data in sockets: + data.close() + _close_socket_workers(server, [source], workers) + + def test_forward_waits_for_last_target_ack_before_upstream_ack(tmp_path, monkeypatch): """The source remains pending until the last real target ACK is released.""" workers = _track_socket_workers(monkeypatch) @@ -2606,7 +2819,13 @@ def resume_request(sock, peer, child, offset, originator, target): handled.append((peer, child, offset, result)) return result + final_ack_failed = [] + def server_send(sock, message, is_send_raw=False): + if (late_second_request and message == server.server_received_file_data_sign + and not final_ack_failed): + final_ack_failed.append(sock) + return False result = real_server_send(sock, message, is_send_raw=is_send_raw) if result and message == server.server_received_file_data_sign: upstream_acks.append(sock) @@ -2728,7 +2947,15 @@ def send(sock, message, is_send_raw=False, *, index=index, real_send=real_send): fail_first_again = False assert receivers[0]._request_resumes() == 1 assert wait_until(lambda: route["completed"] == set(targets), timeout=20) - assert wait_until(lambda: (targets[0], offsets[0], True) in outcomes, timeout=15) + if late_second_request: + assert wait_until(lambda: final_ack_failed and not server._forward_relays + and not server._receive_transfers and not source._resume_sends) + assert (targets[0], offsets[0], False) in outcomes + assert upstream_acks == [] and source.file_upload_progress[upload_key] is upload + assert server._fid_routes[fid] is route + assert source.resume_trans(targets[0], fid, len(payload)) + assert wait_until(lambda: (targets[0], len(payload) if late_second_request else offsets[0], True) + in outcomes, timeout=15) assert next(start for stream, start, _ in reads if stream == (targets[0], offsets[0])) == offsets[0] assert sum(count for stream, _, count in reads if stream == (targets[0], offsets[0])) == len(payload) - offsets[0] assert target_acks == [1, 0] diff --git a/test/unit/network_api/test_fid_routes.py b/test/unit/network_api/test_fid_routes.py index 695b279..6383ba3 100644 --- a/test/unit/network_api/test_fid_routes.py +++ b/test/unit/network_api/test_fid_routes.py @@ -354,6 +354,74 @@ def test_completed_targets_survive_reload_without_recreating_their_indexes(tmp_p second.stop() +def test_fully_completed_snapshot_restores_route_without_indexes_or_progress_rows(tmp_path): + instance = _server(tmp_path) + snapshot = {"upload": {}, "download": {}, "relays": {"303": { + "originator": list(ORIGINATOR), + "targets": [[list(TARGET_1), 305], [list(TARGET_2), 306]], + "completed": [list(TARGET_1), list(TARGET_2)], + }}} + with open(instance.file_trans_progress_file, "w", encoding="utf-8") as stream: + json.dump(snapshot, stream) + try: + assert instance._load_transfer_progress() == 1 + route = instance._lookup_fid_route(None, 303)[1] + assert route["originator"] == ORIGINATOR + assert route["targets"] == {TARGET_1: 305, TARGET_2: 306} + assert route["completed"] == {TARGET_1, TARGET_2} + assert instance._fid_route_index == {} + assert instance._lookup_fid_route(TARGET_1, 305) is None + assert instance._lookup_fid_route(TARGET_2, 306) is None + assert instance.file_upload_progress == {} + assert instance.file_recv_progress == {} + finally: + instance.stop() + + +@pytest.mark.parametrize("case", [ + "wrong-source-address", "stale-source-socket", "wrong-member", + "multiple-targets", "partially-completed", +]) +def test_terminal_resume_rejects_invalid_source_or_target_on_control_socket(server, case): + completed = {TARGET_1} if case == "partially-completed" else {TARGET_1, TARGET_2} + route = server._register_fid_route( + 303, ORIGINATOR, {TARGET_1: 305, TARGET_2: 306}, completed, + ) + assert route is not None + server.running = True + sockets = [] + try: + for address in (ORIGINATOR, TARGET_1, TARGET_2, TARGET_3): + sockets.extend(_install_client(server, address)) + control, peer = sockets[:2] + requester = ORIGINATOR + if case == "wrong-source-address": + control, peer = sockets[-2:] + requester = TARGET_3 + elif case == "stale-source-socket": + control, peer = socket.socketpair() + sockets.extend((control, peer)) + targets = [TARGET_3] if case == "wrong-member" else [TARGET_1] + if case == "multiple-targets": + targets.append(TARGET_2) + target_tokens = " ".join(f'"{target!r}"' for target in targets) + peer.settimeout(5) + server.handle_command( + control, requester, + f"/forward_item file fid=303 resume=7 payload.bin {target_tokens}", + ) + with peer.makefile("r") as stream: + assert stream.readline().startswith("/forward_error 303 ") + assert server._lookup_fid_route(None, 303) == (303, route) + assert route["completed"] == completed + assert server.file_upload_progress == {} + assert server.file_recv_progress == {} + finally: + server.clients.clear() + for sock in sockets: + sock.close() + + @pytest.mark.parametrize("completed", [None, [list(TARGET_2)], [list(TARGET_1)] * 2]) def test_invalid_completed_snapshot_is_preserved_on_load_write_and_stop(tmp_path, completed): instance = _server(tmp_path) From b0e278300867d0f725b620aa3cee7b531dc1a199 Mon Sep 17 00:00:00 2001 From: F18-Ray Date: Thu, 19 Nov 2026 14:09:28 +0800 Subject: [PATCH 14/19] fix(tcp): reject native file forwarding to self - Filter self targets in the shared Client forwarding entry before allocating a FID, creating upload state, or negotiating listeners; use the filtered peers consistently for progress and wire targets. - Identify self from the captured control socket. Accept configured host aliases only when they resolve to its actual local IP, preserving different-IP/same-port targets after no bind or source-port fallback. - Cover console files, nested folders, mixed targets, retained-row rejection, wildcard/hostname binds, unbound clients, and real bind-conflict fallback with consumer-visible socket regressions. - Verification: final full pytest 994 passed, 1 skipped; final self-target regressions 8 passed; V5 66 passed and resume subset 32 passed before the final alias refinement; three standalone transport/Web scenarios passed with zero remaining workers. - Typecheck retains 37 diagnostics outside changed production ranges. Record runtime evidence, the resolved Spec P2, platform limits, and unchanged Web asynchronous registration behavior in the lifecycle report. - No public signature, wire, persistence schema, Source sending algorithm, CI, dependency, merge, or push changes; C6 remains unimplemented. --- PyFlow/network_api/connect_tcp.py | 22 ++- docs/plans/transfer-control-lifecycle-plan.md | 19 ++- .../transfer-control-lifecycle-report.md | 81 +++++++++ ...transfer-control-lifecycle-requirements.md | 6 +- docs/source/File_Transfer/File_Transfer.rst | 16 ++ docs/source/Network_APIs/TCP_Client_APIs.rst | 15 +- docs/source/changes/transfer-fid-routes.md | 18 ++ .../network_api/test_tcp_transfer_resume.py | 158 ++++++++++++++++++ 8 files changed, 321 insertions(+), 14 deletions(-) diff --git a/PyFlow/network_api/connect_tcp.py b/PyFlow/network_api/connect_tcp.py index fdb6f52..b9ef555 100644 --- a/PyFlow/network_api/connect_tcp.py +++ b/PyFlow/network_api/connect_tcp.py @@ -11603,7 +11603,23 @@ def _forward_one( if control_socket is None: control_socket = self.client_socket is_resume = upstream_fid is not None - targets = [(_peer_from_json(target) or (target[0], int(target[1]))) for target in addrs] + local_endpoint = _socket_local_endpoint(control_socket) or (self.client_host, self.client_port) + configured_endpoint = (self.client_host, local_endpoint[1]) + targets = [] + for address in addrs: + target = _peer_from_json(address) or (address[0], int(address[1])) + is_self = _is_control_endpoint(target, configured_endpoint, local_endpoint) + if is_self and target != local_endpoint and self.client_host != "0.0.0.0": + try: + is_self = socket.gethostbyname(self.client_host) == local_endpoint[0] + except OSError: + is_self = False + if is_self: + self._log(f"forward: refusing own control endpoint {target}, skipped") + else: + targets.append(target) + if not targets: + return False if is_resume: key = (server_peer, upstream_fid) if len(targets) != 1 or key not in self.file_upload_progress: @@ -11614,7 +11630,7 @@ def _forward_one( if self.is_enable_file_transfer_progress_bar: self.file_upload_progress[key] = [ 0, os.path.getsize(abspath), None, str(abspath), - (_peer_from_json(addrs[0]) or tuple(addrs[0])) if addrs else None, + targets[0], ] self._persist_transfer_progress() owner_key = (targets[0], upstream_fid) if is_resume else key @@ -11629,7 +11645,7 @@ def _forward_one( if kind == "folder": msg += f" {shlex.quote(rel_dir)}" msg += f" {shlex.quote(fname)} " + " ".join( - shlex.quote(str(address)) for address in addrs + shlex.quote(str(address)) for address in targets ) if destination_path: msg += f" {shlex.quote(destination_path)}" diff --git a/docs/plans/transfer-control-lifecycle-plan.md b/docs/plans/transfer-control-lifecycle-plan.md index dfad9aa..bf11d76 100644 --- a/docs/plans/transfer-control-lifecycle-plan.md +++ b/docs/plans/transfer-control-lifecycle-plan.md @@ -1,6 +1,6 @@ # 传输控制生命周期、全局转发暂停与独立并行恢复 — 更改计划 -状态:**C4 实现、局部验收与双轴审查完成:核心六组及两组边界真实程序通过,最后窄组合 58 passed;完整测试曾 984 passed/1 failed/1 skipped,唯一旧契约失败按用户批准迁移后窄重验通过;类型检查仍有 37 条改动范围外诊断**。复用既有 fid route/completed 和 Source 任务上传行,不新增完成表、完成位、Server 转发字节进度行或快照格式;不拆改 Source 发送函数。C1/C2/C3 保留,C5/C6 未实施;本轮提交当前分支,不合并或推送,完整证据与限制见报告。 +状态:**C5 实现、局部/完整验证与双轴审查完成:最终 pytest 994 passed、1 skipped;最终八项专项、V5 和三组 S6 程序的证据见报告**。已关闭配置 IP 与实际源 IP 不同时误拒合法目标的 P2。C1–C4 保留;C5 仅在 Client 原生转发入口拒绝自身,不改协议、进度模型或 Source 发送算法。类型检查仍有 37 条改动范围外诊断;C6 未实施,仅提交当前分支,不合并或推送。 需求依据:[需求卡](transfer-control-lifecycle-requirements.md)。历史实现依据:[上一轮计划](transfer-pause-start-direction-plan.md)及其报告;它们的历史验证结果不作为本轮验证结果。 @@ -9,7 +9,7 @@ ### 1.1 本轮范围与保留/后续边界 1. **问题四/五**:按实际控制 socket 管理旧会话资源,删除按 peer 扫描进度表关闭当前 socket 的重复机制;旧 worker 不借用新控制连接。 -2. **问题六**:自身完整控制端点拒绝为后续 C5 目标,同 host 不同端口仍可互传;C5 未实现,不混入本轮 C3。 +2. **问题六**:C5 拒绝 Client 自身完整控制端点(同 IP 且同端口),混合只剔除自身,其他合法目标仍传输;已获本轮实施批准,不混 C6。 3. **问题七**:Source 是 route 的唯一用户控制仲裁者;任意端 pause/start 控制整个转发任务。暂停源端新增块,已有字节继续排空,数据 socket 不断开。 4. **问题八**:8A 的 C3 独立并行恢复已实现,查询/强制 teardown/FIFO 单轮方案已撤回。8B 的 C4 已实现复用原 fid route/completed 和 Source 共享上传行,补全目标完成后的显式 EOF 最终确认;路径与边界见 6.1,实际证据见报告。 @@ -44,7 +44,7 @@ | 修改单测 | `test/unit/network_api/test_TCP_client.py`、`test_TCP_server.py` | 控制会话替换及资源生命周期必要回归 | | 修改集成测试 | `test/integration/network_api/test_tcp_transfer_control.py` | 普通双端控制回归、全局暂停、旧会话清理及多恢复 owner 的共享控制 | | 修改集成测试 | `test/integration/network_api/test_tcp_transfer_resume.py` | 普通/转发同 fid、新旧 owner 边界、不同 offset 并行恢复、晚来目标、单流失败、真实 ACK、重连与持久化 | -| 迁移受影响断言 | `test/integration/network_api/test_tcp_file_transfer.py`、`test_crypto_tcp.py`、`test_tcp_async_server.py`、`test/integration/test_forward_extension.py`、`test_forward_msg_attribution.py` | 仅涉及现有恢复/全局暂停的真实消费者;C5 自目标路径仍为未实现后续阶段,不做端口或控制协议迁移 | +| 迁移受影响断言 | `test/integration/network_api/test_tcp_file_transfer.py`、`test_crypto_tcp.py`、`test_tcp_async_server.py`、`test/integration/test_forward_extension.py`、`test_forward_msg_attribution.py` | 保留既有恢复/全局暂停消费者;C5 自目标回归另见第 2.2 节,不做端口或控制协议迁移 | | 修改使用文档 | `docs/source/File_Transfer/File_Transfer.rst`、`docs/source/Network_APIs/TCP_Server_APIs.rst`、`TCP_Client_APIs.rst` | 数值 offset、原 route 收尾、独立流、全局暂停及暂缓边界 | | 修改变更记录 | `docs/source/changes/transfer-fid-routes.md` | 保留稳定恢复 fid,取代独立 writer 暂停及 busy 恢复等旧契约;明确问题二暂缓 | | 计划载体 | 本文件、`transfer-control-lifecycle-requirements.md` | 已批准的新方案与旧 C3 撤回边界 | @@ -73,6 +73,15 @@ Web 的 `client_backend.py` 已知通过 Client 的文件/文件夹转发入口 完整 pytest 实际为 984 passed、1 failed、1 skipped;唯一失败仍要求旧自动背压控制帧。用户已选择 `migrate_contract`,批准上述单函数迁移及窄重验,不再次运行全套。C4 审查另定位到旧恢复 tuple owner 在 route 已删除后的 finally 窗口:不同 Target 的新 route 复用同值 fid 时,不应被该旧 Target owner 误判 busy;修正限于既定 C4 准入及同文件真实恢复回归,不改 Source 或扩大生产范围。 +### 2.2 本次 C5 实施清单(用户已批准开始) + +- **单一意图**:原生 Client 文件/目录转发拒绝自身完整控制端点;混合目标只剔除自身,保留同 IP 不同端口及同端口不同 IP 的合法目标。自身比较使用 worker 捕获的实际控制 socket;配置主机仅在解析为实际 IP 时作为别名,wildcard 仅别名实际端口。未绑定/本地端口回退后未使用的配置 IP 不能被拼接为自身身份。 +- **文件**:生产仅改 `connect_tcp.py::_forward_one`,在 fid/上传行/握手创建之前统一筛选目标;同一筛选结果用于进度 peer、线上目标及最终发送。`test_tcp_transfer_resume.py` 补 self-only/mixed/恢复的真实 socket 契约;既有 Web 与 console/driver 适配调用同一入口,Web 后端不改。使用文档限 File_Transfer、TCP_Client_APIs 和变更记录,需求/本计划/本报告同步。 +- **数据流/全集**:console file、console folder(含各嵌套条目)、Web file/folder、已有行显式恢复 → 原 driver/`_forward_one` → 目标规范化/自身过滤 → 无目标则记录拒绝并返回 False,不发请求/不分配 fid/不建新进度;有合法目标则走原 port/header/body/真实 ACK。恢复公开 bool 仍表示 worker 预留,拒绝保留旧行,不伪造完成或删除既有数据。 +- **验收**:窄真实消费者回归检查拒绝文本、无新增 route/child/进度/握手及恢复旧行不变;mixed 路径完整内容与 Source 实际 ACK、进度 peer 不能残留自身。S6 另用一次性真实程序验证明文/加密、thread/async、别名/wildcard、实际同机不同端口、Web 适配、恢复与资源收尾,结束删除。V5 受影响回归只运行一次;不把未运行的参数笛卡尔积或 C6 算通过。 +- **提交**:一个 C5 原子变更,预计生产约 20 行、回归约 150 行及必要文档;不混 C6,不改公开签名/wire/schema/CI/依赖/Source 发送算法。仅原生文件/目录转发,不改变消息转发、独立磁盘转发扩展或 Server 自地址跳过的既有契约,不将手工绕过 Client 构造命令当作鉴权问题一并处理。 + + ## 3. 接口与线上契约(用户已批准) @@ -267,7 +276,7 @@ flowchart TD | 旧 C3a/C3b | 已撤回历史:offset 查询、强制 teardown、单活跃 FIFO 轮次,不再实施或验收该契约 | 旧结果不作为本轮证据 | | 本轮 C3 | 已实现:仅数值请求;原 route 旧 owner 全收尾;每 Target 独立流/进度/资源/失败,正文并行;socket+fid 仅端口短串行;保留 C1/C2 和累计真实 ACK | 分次局部回归与 3 组独立程序实际结果见实施报告;未扩大为 V6/C6 总验收 | | C4 | 已批准并实现:复用既有 fid route/completed,不新增记录/字段;Source 显式 EOF 补最终确认,单一原子变更 | C4-P01–P10;实际运行矩阵、局部与完整测试及未覆盖项见报告,不把计划命令当运行结果 | -| C5 | 未实现:Client 自身完整控制端点拒绝 | V5,S6;须单独推进 | +| C5 | 已批准并实现:Client 原生文件/目录在统一入口拒绝自身完整控制端点,合法目标照常传输,拒绝恢复保留旧行 | 六参数回归通过;V5、S6、审查及未跑矩阵以报告实际证据为准 | | C6 | 未实现:合并回归、全路径总体验收与最终报告 | V6;须单独推进 | 本轮不是 C6 总验收声明。实施不新增 wire、依赖、CI、自动重试或身份迁移;用户实施指令授权提交当前分支,不授权合并或推送。旧 C3 历史拆分及授权不作为新实现通过证据。 @@ -317,4 +326,4 @@ flowchart TD - **规则沉淀**:实际会话取消、数值实际 offset、原 owner/finally barrier、不同 offset 独立并行、晚来目标不等正文/ACK、全局 pause 与真实 ACK 聚合成为本轮回归路径;不新增源码字符串断言或严格代次隔离承诺。 - **文档/报告**:最终报告逐 P01–P20 给结论,单列问题二暂缓;每个原子变更含意图、范围、数据流、局部命令、未覆盖项、风险;文档随变更完成,不留“以后补”。 -C3/C4 实现与实际证据见[实施报告](transfer-control-lifecycle-report.md)。C4 保持已批准的路径、文件范围、单原子拆分及记录模型;未执行参数不列覆盖。C5/C6 不自动推进,合并与推送仍须人工确认。 +C3/C4 历史实现与本轮 C5 实际证据见[实施报告](transfer-control-lifecycle-report.md)。C5 保持第 2.2 节的单原子意图、文件范围及原生转发边界;不修改独立磁盘扩展/消息转发契约。C6、合并与推送仍须人工确认。 diff --git a/docs/plans/transfer-control-lifecycle-report.md b/docs/plans/transfer-control-lifecycle-report.md index 59f89bc..1b472c8 100644 --- a/docs/plans/transfer-control-lifecycle-report.md +++ b/docs/plans/transfer-control-lifecycle-report.md @@ -1,5 +1,86 @@ # 传输控制生命周期实施报告 +## C5:原生文件与目录转发自拒绝 + +**意图与授权**:用户确认“同 IP 且同端口”属于自身,并明确要求开始 C5。混合列表只剔除自身,同 IP 不同端口及不同 IP 同端口仍合法。本次单原子变更不推进 C6,不合并或推送;C1–C4 的历史输出不作为本轮证据。 + +### 更改路径与数据流 + +- `PyFlow/network_api/connect_tcp.py::_forward_one`:复用 `_socket_local_endpoint` 和 `_is_control_endpoint`,使用准入 worker 捕获的实际控制 socket。配置主机仅在确实解析为该实际 IP 时匹配,wildcard 仅别名实际端口;不会把未绑定/端口回退后未使用的配置 IP 拼成自身。仅命中配置候选才做解析,实际端点及普通不同目标无需解析。过滤在新 fid、上传行和握手之前;纯自身记录拒绝并返回 False。有合法目标时,进度 peer、wire 和发送路径共用过滤后的规范化列表。 +- `test/integration/network_api/test_tcp_transfer_resume.py`:六参数(file/folder × 127.0.0.1/localhost/0.0.0.0)真实 console 回归,证明无分配/新记录/请求/回环文件、mixed 的 Source ACK=True、保留行自恢复失败且原对象仍在;另加两参数,实际无 bind 和 EADDRINUSE 回退后,其他 IP/同端口目标仍真实收到,实际自身仍拒绝。 +- File_Transfer、TCP_Client_APIs、变更记录和既有需求/计划/本报告同步。Web 适配和 Server 未改;沿用原安全发送、port/header/body/ACK、owning 清理,不新增协议、接口、schema、CI、依赖或抽象。 + +数据流:console/Web file/folder/保留行恢复 → 原 driver 或恢复 worker → `_forward_one` 规范化与自目标过滤 → 无合法目标则拒绝并停止;否则原流式转发 → 全部合法 Target 真实 ACK → 既有成功清理。目录逐文件检查,恢复公开 bool 仍是 worker 预留,拒绝不等于自动删除原恢复记录。 + +### 已执行检查与错误处理 + +| 实际命令/范围 | 结果 | +|---|---| +| 新测试 `[127.0.0.1-file]`,实现前 | 1 failed,4.87 秒,退出 1;实际转发自身并返回 True,期望 False,精确复现缺失的拒绝 | +| `test_forward_self_target_is_rejected_but_other_ports_still_receive` | **6 passed,18.85 秒,退出 0** | +| 审查 P2 未绑定/端口冲突回退的真实复现,修复前 | 2 failed,1.89 秒;合法 127.0.0.2:same-port 被配置主机误判自身,均返回 False | +| 上述两参数 + 原六参数,最终实现 | **8 passed,29.70 秒,退出 0** | +| V5 四份集成文件 `-k 'forward or relay or self_target'` | **66 passed、83 deselected,299.37 秒,退出 0** | +| resume 集成 `-k 'forward or eof_confirmation'` | **32 passed、42 deselected,147.14 秒,退出 0** | +| `uv tool run ty check PyFlow/network_api/connect_tcp.py --output-format concise` | 退出 1,37 条诊断,均在本次生产修改范围外;不声称通过 | +| 六份相关文档的相对文件链接 | 9 个链接、0 缺失,仅机械检查 | +| 最终完整 `.venv/bin/python -m pytest -q --tb=short`,仅一次 | **994 passed、1 skipped,1209.22 秒,退出 0**;运行版本包含最后的配置别名收窄与八项新增回归 | + +```bash +.venv/bin/python -m pytest test/integration/network_api/test_tcp_file_transfer.py test/integration/test_forward_extension.py test/integration/test_forward_msg_attribution.py test/integration/network_api/test_tcp_transfer_control.py -k 'forward or relay or self_target' -q --tb=short +.venv/bin/python -m pytest test/integration/network_api/test_tcp_transfer_resume.py -k 'forward or eof_confirmation' -q --tb=short +.venv/bin/python -m pytest test/integration/network_api/test_tcp_transfer_resume.py::test_forward_different_ip_same_port_survives_a_different_configured_host test/integration/network_api/test_tcp_transfer_resume.py::test_forward_self_target_is_rejected_but_other_ports_still_receive -q --tb=short +``` + +V5/resume 批次与三组独立程序先于配置别名的最后收窄;该收窄由上述 8 项最终回归及最后完整 pytest 验证,不冒充之后重跑过独立程序。完整 pytest 仅运行一次,994 passed、1 skipped,无失败;不以 C4 历史结果替代。最终类型检查仍有 37 条改动范围外诊断,不能宣称所有检查全绿。完整套件通过不替代 C6 的全路径总验收,C6 未自动推进。 + +### S6:独立真实运行证据 + +一次性 `/tmp/pyflow-transfer-lifecycle-smoke.py --case self-target` 不调用 pytest 测试函数,不 mock 文件、网络或加密。仅透传记录日志、原发送结果与 socket owner。每组验证 console 文件、含非空/空文件的嵌套目录、真实 Flask `/api/send_file` 和 `/api/send_folder` 到原 TCP 路径,以及保留行恢复;Web HTTP 200/ok 仍表示异步受理,**不是成功送达或 UI 拒绝状态**,本次不改变 HTTP/UI 契约。 + +| 实际参数 | Source 控制端点 | 合法目标端点 | workers / 最终存活 | +|---|---|---|---| +| 明文 thread、localhost、Server wildcard 双 IP 监听 | 127.0.0.1:40233 | 127.0.0.1:44151;127.0.0.2:40233 | 68 / 0 | +| 加密 thread | 127.0.0.1:43811 | 127.0.0.1:38663 | 80 / 0 | +| 加密 async、wildcard、tracking off | 127.0.0.1:35589 | 127.0.0.1:41345 | 81 / 0 | + +三组以 `&&` 执行,批命令退出 0,42.18 秒。每组 5 个自身文件条目结果均 False,且不分配新 fid、无上传行/Server route/握手/数据连接或回环文件;显式恢复 fid=591 结果 False,原五项上传行对象及快照仍在。mixed 和 Web 合法投递各组共 5 个真实 Source ACK=True;仅发送 5 条合法 `/forward_item`,其中不再带自身,跟踪开启时新上传 peer 只指合法目标。未删除手动保留的旧行,完成后 Server route/index 与合法 Target 接收进度均清空。 + +非空文件 65806 字节,目标及 Source 原文件 byte-for-byte 一致,SHA-256 `d844b5d8544c48d85fb6b05a2bbf1a9538c88deb1b96b913024edce44acf0296`;目录中的零长文件也取得真实 ACK。每组五条上游数据 socket 都记录实际控制 owner;加密组 channel.secure=True,明文组无加密 channel。Source 实际控制 socket 全程保持。观察到拒绝日志 `forward: refusing own control endpoint ('127.0.0.1', 40233), skipped`,别名与 wildcard 亦有对应拒绝。 + +```bash +PYTHONPATH="$PWD" .venv/bin/python /tmp/pyflow-transfer-lifecycle-smoke.py --case self-target --alias --same-port-target +PYTHONPATH="$PWD" .venv/bin/python /tmp/pyflow-transfer-lifecycle-smoke.py --case self-target --encrypted +PYTHONPATH="$PWD" .venv/bin/python /tmp/pyflow-transfer-lifecycle-smoke.py --case self-target --encrypted --async-server --wildcard --untracked +``` + +首次双 IP 程序为 127.0.0.2 Target 仍配置 127.0.0.1 Server 接口,既有 Client 数据 listener 使用其配置 host,故无法在 .2 接收,目标内容断言失败。程序改为 Server wildcard 监听、该 Target 通过 .2 接口连接并监听,生产收发未改;最终上述双 IP/同端口真实内容与 ACK 通过,不把地址不通的首次结果冒充自拒绝缺陷。 + +一次性程序已删除,真实传输文件、上传暂存及隔离日志/进度/密钥目录均由 TemporaryDirectory 清理;未遗留永久验收脚本。 + +### 路径对照与边界 + +| C5 路径 | 实际证据 / 未覆盖 | +|---|---| +| 自身 same-IP/port、mixed、合法 same-IP/different-port | 六参数 console 回归与三组独立真实程序,合法目标内容/真实 ACK | +| 不同 IP/同端口 | 明文真实双接口程序,127.0.0.2:40233 完整收到且 Source ACK=True;不是只按端口拒绝 | +| console file/folder/嵌套/空文件 | 六参数回归及每组独立程序的非空/空条目,逐条真实结果 | +| Web 文件/目录 | 真实 Flask multipart 请求沿原 adapter 到 TCP,self False、合法 True;未更改或验证浏览器拒绝提示 | +| 恢复旧行、tracking off | self 恢复 worker 退出、旧行/快照保留、无新请求;async 程序在 tracking off 下完成合法投递 | +| 别名/wildcard、实际 socket | localhost、0.0.0.0、动态端口已验证;最终两参数额外覆盖无 bind 和真实 EADDRINUSE 取消 bind 后仍允许不同 IP/同端口;EACCES、重连中的地址变化未单独验证 | +| C1–C4、消息与磁盘扩展 | 既有受影响回归结果单列,不将 C5 扩为 Server 鉴权或磁盘扩展自拒绝;旧会话及中途 rekey 不扩大声明 | + +只保证原生 Client 文件/目录入口,不阻止手工构造 wire 绕过 Client,不是新增 Server 鉴权策略。NAT/身份迁移、native Windows、其他 Python 版本及全部参数笛卡尔积未覆盖。问题二严格代次隔离继续暂缓,C6 未实施。规则沉淀为上述真实消费者回归;Python LSP capabilities 仍仅 Ruff,不支持 references/definition,未虚称符号引用分析完成。 + +### Standards + +发现 0 项。未发现削弱既有测试、重复实现、安全 I/O 旁路、非 owning 清理或未经批准扩围;Fowler 独立启发式 0 项。生产仅统一入口,未改 Server、Web UI 或 Source 文件发送算法。 + +### Spec + +发现 1 个 P2,已真实复现并修复:`client_host=127.0.0.2` 但未绑定或配置端口冲突后,实际 Source 为 `127.0.0.1:q`,另一 Client `127.0.0.2:q` 是合法目标;最初无条件配置别名会误拒。修正为配置候选仅在解析为实际 IP 时才认作自身(wildcard 除外);两条真实路径修复前失败,最终八参数通过。无生产越界;无未修复的实现发现。审查未运行检查,运行结果均由父代理记录。 + + ## C4:复用既有 route 的显式 EOF 补最终确认 **提交意图**:全部 accepted Target 已真实 ACK、上游最终 ACK 明确 False/异常后,由 Source 显式补最终确认,不重新交付文件。用户 `/skill:implement` 已授权本单一原子变更、验证、审查及提交当前分支;不推进 C5/C6,不合并或推送。此前任务迁移、独立终态表及 C4a/C4b 拆分均撤回。 diff --git a/docs/plans/transfer-control-lifecycle-requirements.md b/docs/plans/transfer-control-lifecycle-requirements.md index 3fa1a22..978432c 100644 --- a/docs/plans/transfer-control-lifecycle-requirements.md +++ b/docs/plans/transfer-control-lifecycle-requirements.md @@ -1,6 +1,6 @@ # 传输控制生命周期与转发恢复 — 需求卡 -状态:**C4 实现、局部验收与双轴审查完成;最终窄组合 58 passed,完整测试及类型检查限制见报告**。复用既有 fid route/completed 和 Source 共享任务上传行,仅补全部 Target 已完成后的显式 EOF 最终确认;不新增完成表、完成字段、Server 转发字节进度行或快照格式。C1/C2/C3 保留,撤回的查询/强制 teardown/串行恢复不恢复;C5/C6 不自动推进。 +状态:**C5 实现、真实运行验证与双轴审查完成:最终完整 pytest 994 passed、1 skipped,八项专项及三组独立程序通过**。拒绝同 IP 且同端口的自身目标,合法目标仍传输;审查发现的配置 IP 与实际源 IP 不同时误拒已修复。C1–C4 保留,不改 fid、wire、公开签名或持久化模型;类型检查仍有 37 条改动范围外诊断,C6 不自动推进。 本轮命令、实际结果、失败修正及明确未覆盖项见[实施报告](transfer-control-lifecycle-report.md)。旧历史结果不作为 C4 通过证据。用户通过 `/skill:implement` 授权实现、检查、审查及提交当前分支;不合并或推送。 @@ -23,7 +23,7 @@ 3. 流式转发采用全 route 的用户暂停:任意 Source、Server、Target 可请求 pause/start,Source 作最终仲裁。一个 Target 暂停,所有 Target 停止获得新的源数据。Server 已接收的数据继续排空到 Target;保留数据 socket,不做 seek 或重握手。 4. 不采用“每个 Target 持有独立暂停锁、必须本人解除”的规则。任意端的 start 仍可经 Source 仲裁解除用户暂停。自动背压的内存硬门槛不被用户 start 清除。 5. 有效转发恢复请求由 Receiver 在其旧接收 owner/文件收尾后,带实际数值 offset 提交 Server。Server 按 child fid/实际会话定位原 route;原 route 的数据腿、listener、握手、reader/writer 或 finalizing owner 尚未全部结束时只保存请求,不主动中断。全部旧 owner(含 finally)收尾后,按每个 Target 自己的 offset 独立转交 Source、建流;不复用旧 relay 内存、不更换 fid、不查询其他 Target 的 offset。 -6. 后续 C5 目标为 Client 转发入口拒绝自身完整控制端点、允许同 host 不同端口;C5 本轮未实现,不作本轮完成项。 +6. C5 在 Client 原生文件/目录统一入口拒绝自身完整控制端点;同 IP 不同端口和不同 IP 同端口仍允许,混合列表只剔除自身。拒绝先于 fid/新进度/握手,console、Web、目录条目和保留行恢复共用;拒绝恢复不删旧行。配置主机必须解析为捕获 socket 的实际 IP 才作为别名,wildcard 仅别名实际端口;未绑定/端口回退后未使用的配置 IP 不能认作自身。 7. 保留真实最终 ACK 判成功规则:每个 Target 的真实 ACK 只更新其完成集合,累计所有 accepted Target 的真实 ACK 才能使整任务成功;中间 Target 成功不伪造整 route ACK。Source 的共享上传行保留到全部目标完成且收到最终 ACK。C4 已实现复用已有完整完成集合补最终确认,不将 offset==size 单独当作任务完成证据;运行证据与限制见实施报告。 8. 多个 Target 恢复各有独立 offset、Source→Server→Target 数据流、进度、资源及失败结果,正文并行。晚到 Target 不等待已有恢复流的大文件正文或 ACK;同一实际控制 socket+fid 仅端口握手短串行,不锁正文或最终 ACK。 @@ -118,4 +118,4 @@ ## 下一阶段闸门 -C4 已按用户 `/skill:implement` 指令完成实现、局部验收与审查,模型及单一原子拆分不变;用户另批准唯一旧背压测试的契约迁移。证据与未覆盖项见[报告](transfer-control-lifecycle-report.md)。本轮提交当前分支,不合并或推送;C5/C6 须另获批准。 +C4 的实现、验收与旧背压迁移已提交。用户已明确批准 C5 开始,实施及验证严格对照[计划](transfer-control-lifecycle-plan.md) 2.2 节,实际证据见[报告](transfer-control-lifecycle-report.md)。C5 仅提交当前分支,不合并或推送;C6 须另获批准。 diff --git a/docs/source/File_Transfer/File_Transfer.rst b/docs/source/File_Transfer/File_Transfer.rst index 6b4b1e7..01ace17 100644 --- a/docs/source/File_Transfer/File_Transfer.rst +++ b/docs/source/File_Transfer/File_Transfer.rst @@ -494,6 +494,22 @@ are unreachable itself are skipped and the remaining targets are still served. +The native Client also refuses its own complete control endpoint: both IP +and port must match. Same-IP Clients on different ports, and different-IP +Clients on the same port, remain valid destinations. Comparison uses the +captured control socket's actual local endpoint; a configured hostname is +accepted only when it resolves to that actual IP, and a wildcard host aliases +the actual port. An unused configured IP after no bind or source-port fallback +cannot identify self. OS-assigned ports do not make other local Clients self. + +Self-only requests log a refusal before allocating a FID, creating upload +progress or contacting the Server. Mixed requests remove only self, and use +the remaining targets for both the wire command and the retained upload peer. +Console files, nested folder entries, Web forwarding and retained-row replay +share this check. A rejected replay preserves its old row; ``resume_trans`` +still reports worker reservation, not successful delivery. This rule does not +change message forwarding or the separate disk-based forwarding extension. + Like every transfer family, both commands accept an optional trailing ``destination_file_path`` that replaces the default save diff --git a/docs/source/Network_APIs/TCP_Client_APIs.rst b/docs/source/Network_APIs/TCP_Client_APIs.rst index cdc144f..a37622f 100644 --- a/docs/source/Network_APIs/TCP_Client_APIs.rst +++ b/docs/source/Network_APIs/TCP_Client_APIs.rst @@ -675,9 +675,18 @@ Built-in client console commands (user-typed) include: client to server, preserving the directory structure. - ``/multiple_file_folder ...``: sends multiple folders from client to server. -- ``/forward_file``, ``/forward_folder``, ``/forward_send_msg``: the - forwarding extension's console commands (client-only; the server refuses - them). +- ``/forward_file``, ``/forward_folder``: native Client-only streamed forwarding. + Their shared per-file entry refuses the Client's own complete control + endpoint before creating an upload row, allocating a FID or sending a relay + request. Mixed lists skip only self; same IP/different port and different + IP/same port remain valid. The actual control socket identifies self; a + configured host alias must resolve to that IP (wildcard aliases its actual + port). A configured IP not used after no bind or bind fallback is not self. + Web file/folder forwarding and retained-row replay use the same check; + rejected replay keeps the existing row, and a resume boolean remains worker + registration rather than success. Server console use is refused. +- ``/forward_send_msg``: native Client-only message forwarding; its existing + target rules are unchanged by the file/folder self-target guard. Ctrl-C and EOF close the connection, send a final ``/quit`` and wait 0.5 seconds before the process ends. diff --git a/docs/source/changes/transfer-fid-routes.md b/docs/source/changes/transfer-fid-routes.md index 050669d..13925fe 100644 --- a/docs/source/changes/transfer-fid-routes.md +++ b/docs/source/changes/transfer-fid-routes.md @@ -7,6 +7,24 @@ > `docs/plans/transfer-pause-start-direction-report.md`; those historical > results are not verification of the current lifecycle revision. +## Lifecycle revision C5: refuse native self-target file forwarding + +- Filter the Source's complete control endpoint in the shared Client per-file + entry before FID allocation, progress creation or relay negotiation. Match + the captured socket's actual IP/port; configured hosts must resolve to that + IP, except wildcard, which aliases the actual port. + An unused configured source IP after no bind or port fallback is not self. +- Self-only forwarding logs a refusal and returns no delivery. Mixed lists + retain only legal peers, including same-IP/different-port and + different-IP/same-port Clients; the upload row and wire use that same list. +- Native console, nested folder entries, Web forwarding and retained-row + replay share the check. Rejected replay preserves its existing recovery row; + the public resume boolean still reports worker reservation, not delivery. +- No signature, wire, persistence schema, dependency or CI changes. Message + forwarding and the separate disk-forward extension retain their contracts. + C6 combined acceptance and strict same-session/FID generation isolation are + not implemented here. Actual evidence is in the lifecycle report. + ## Lifecycle revision C4: explicit all-Target EOF reconfirmation - After every accepted Target's real ACK, an upstream final-ACK write returning diff --git a/test/integration/network_api/test_tcp_transfer_resume.py b/test/integration/network_api/test_tcp_transfer_resume.py index bc7aace..e637620 100644 --- a/test/integration/network_api/test_tcp_transfer_resume.py +++ b/test/integration/network_api/test_tcp_transfer_resume.py @@ -121,6 +121,164 @@ def _close_socket_workers(server, clients, workers): ) +@pytest.mark.parametrize("kind", ["file", "folder"]) +@pytest.mark.parametrize("bind_host", ["127.0.0.1", "localhost", "0.0.0.0"]) +def test_forward_self_target_is_rejected_but_other_ports_still_receive( + tmp_path, monkeypatch, kind, bind_host +): + """Console forwarding rejects itself before allocation and keeps legal peers.""" + workers = _track_socket_workers(monkeypatch) + server = _start_server(tmp_path) + clients = [] + try: + source = TCP_Client_Base( + host="127.0.0.1", port=server.port, client_host=bind_host, client_port=0, + is_extend_command=True, is_input_command_in_console=False, + is_enable_encrypto=False, + ) + _isolate(source, tmp_path, "self_source") + source_dir = tmp_path / "self_receive" + source_dir.mkdir() + source.file_transfer_dir = str(source_dir) + clients.append(source) + assert source.connect() + peer = source.client_socket.getsockname() + assert wait_until(lambda: peer in server.clients) + source._resume_thread.join(timeout=10) + directory = tmp_path / "bundle" / "nested" + directory.mkdir(parents=True) + path = directory / "payload.bin" + payload = os.urandom(8192 + 17) + path.write_bytes(payload) + item = directory.parent if kind == "folder" else path + command = source.forward_folder_console if kind == "folder" else source.forward_file_console + outcomes, sent, rows = [], [], [] + real_forward, real_send = source._forward_one, source.send_message + source_counter = source._fid_alloc._counter + server_counter = server._fid_alloc._counter + + def forward(*args, **kwargs): + result = real_forward(*args, **kwargs) + outcomes.append(result) + return result + + def send(sock, message, is_send_raw=False): + if isinstance(message, str) and message.startswith("/forward_item "): + sent.append(message) + rows.append([list(row) for row in source.file_upload_progress.values()]) + return real_send(sock, message, is_send_raw=is_send_raw) + + monkeypatch.setattr(source, "_forward_one", forward) + monkeypatch.setattr(source, "send_message", send) + own_alias = (bind_host, peer[1]) + command(f"/forward_{kind} {shlex.quote(str(item))} {shlex.quote(str(own_alias))}") + assert wait_until(lambda: outcomes, timeout=15) + assert outcomes == [False] + assert sent == [] + assert source._fid_alloc._counter == source_counter + assert server._fid_alloc._counter == server_counter + assert not source.file_upload_progress and not source.file_recv_progress + assert not server._fid_routes and not server._fid_route_index + assert not server._forward_relays and not server._receive_transfers + assert list(source_dir.rglob("*")) == [] + + target_dir = tmp_path / "other_receive" + target_dir.mkdir() + target = _start_client(tmp_path, server, name="other_target", recv_dir=target_dir) + clients.append(target) + target_peer = target.client_socket.getsockname() + assert target_peer[0] == peer[0] and target_peer[1] != peer[1] + assert wait_until(lambda: target_peer in server.clients) + command(f"/forward_{kind} {shlex.quote(str(item))} " + f"{shlex.quote(str(peer))} {shlex.quote(str(target_peer))}") + assert wait_until(lambda: len(outcomes) == 2, timeout=15) + assert outcomes == [False, True] + assert len(sent) == 1 + assert rows[0][0][4] == target_peer + tokens = shlex.split(sent[0]) + assert str(target_peer) in tokens and str(peer) not in tokens + output = target_dir / ("bundle/nested/payload.bin" if kind == "folder" else path.name) + assert output.read_bytes() == payload + assert list(source_dir.rglob("*")) == [] + assert path.read_bytes() == payload + assert wait_until(lambda: not server._forward_relays and not server._receive_transfers) + assert not source.file_upload_progress and not target.file_recv_progress + assert not server._fid_routes and not server._fid_route_index + + # A retained row from an older self-forward remains available; rejecting + # its replay must neither contact the Server nor mark it complete. + fid = 531 + key = ((source.host, source.port), fid) + row = source.file_upload_progress[key] = [len(payload), len(payload), None, str(path), peer] + source._persist_transfer_progress() + assert source.resume_trans(peer, fid, len(payload)) + assert wait_until(lambda: len(outcomes) == 3 and not source._resume_sends) + assert outcomes[-1] is False and len(sent) == 1 + assert source.file_upload_progress[key] is row + assert source._fid_alloc._counter == source_counter + 1 + assert server._fid_alloc._counter == server_counter + 1 + assert not server._fid_routes and not server._receive_transfers + finally: + _close_socket_workers(server, clients, workers) + + +@pytest.mark.parametrize("occupied_port", [False, True], ids=["unbound", "bind-fallback"]) +def test_forward_different_ip_same_port_survives_a_different_configured_host( + tmp_path, monkeypatch, occupied_port +): + """An unused configured IP is not an alias for the actual control socket.""" + workers = _track_socket_workers(monkeypatch) + server = TCP_Server_Base( + host="0.0.0.0", port=free_port(), is_extend_command=True, + is_input_command_in_console=False, is_enable_encrypto=False, + ) + _isolate(server, tmp_path, "wildcard_server") + clients = [] + blocker = socket.socket() + try: + threading.Thread(target=server.start_TCP_Server, daemon=True).start() + assert server_ready(server) + blocker.bind(("127.0.0.2", 0)) + source = TCP_Client_Base( + host="127.0.0.1", port=server.port, client_host="127.0.0.2", + client_port=blocker.getsockname()[1] if occupied_port else None, + is_extend_command=True, is_input_command_in_console=False, + is_enable_encrypto=False, + ) + _isolate(source, tmp_path, "unbound_source") + clients.append(source) + assert source.connect() + actual = source.client_socket.getsockname() + assert actual[0] == "127.0.0.1" and source.local_address is None + blocker.close() + directory = tmp_path / "other_ip" + directory.mkdir() + target = TCP_Client_Base( + host="127.0.0.2", port=server.port, client_host="127.0.0.2", + client_port=actual[1], is_extend_command=True, + is_input_command_in_console=False, is_enable_encrypto=False, + ) + _isolate(target, tmp_path, "other_ip_target") + target.file_transfer_dir = str(directory) + clients.append(target) + assert target.connect() + peer = target.client_socket.getsockname() + assert peer == ("127.0.0.2", actual[1]) + assert wait_until(lambda: actual in server.clients and peer in server.clients) + source._resume_thread.join(timeout=10) + path = tmp_path / "same_port.bin" + payload = b"different actual IP, same actual port" + path.write_bytes(payload) + assert source._forward_one("file", "", path.name, str(path), [peer]) is True + assert (directory / path.name).read_bytes() == payload + assert source._forward_one("file", "", path.name, str(path), [actual]) is False + assert wait_until(lambda: not server._forward_relays and not server._receive_transfers) + assert not source.file_upload_progress and not target.file_recv_progress + finally: + blocker.close() + _close_socket_workers(server, clients, workers) + + def test_progress_entries_round_trip_through_the_progress_file(tmp_path): """Both stores are written with their peer tuples and read back intact.""" server = _start_server(tmp_path) From 8b389f0fe1513f6bc209718e6f0395d436acffdd Mon Sep 17 00:00:00 2001 From: F18-Ray Date: Thu, 19 Nov 2026 18:44:39 +0800 Subject: [PATCH 15/19] docs(transfer): close C6 lifecycle acceptance evidence - Record the single affected-scope V6 run: 692 passed, 1 skipped on Linux/Python 3.10.20. - Map P01-P20 to actual socket/content/ACK/owner evidence; retain five partial-coverage paths and explicit platform/protocol limits. - Reconcile requirements, plan, current report and change note; record observer corrections and both read-only reviews. - Acceptance documents only: no production, tests, wire/schema, dependencies or CI changes; no merge or push. --- docs/plans/transfer-control-lifecycle-plan.md | 18 +- .../transfer-control-lifecycle-report.md | 156 ++++++++++++++++++ ...transfer-control-lifecycle-requirements.md | 10 +- docs/source/changes/transfer-fid-routes.md | 19 +++ 4 files changed, 193 insertions(+), 10 deletions(-) diff --git a/docs/plans/transfer-control-lifecycle-plan.md b/docs/plans/transfer-control-lifecycle-plan.md index bf11d76..bac73e7 100644 --- a/docs/plans/transfer-control-lifecycle-plan.md +++ b/docs/plans/transfer-control-lifecycle-plan.md @@ -1,6 +1,6 @@ # 传输控制生命周期、全局转发暂停与独立并行恢复 — 更改计划 -状态:**C5 实现、局部/完整验证与双轴审查完成:最终 pytest 994 passed、1 skipped;最终八项专项、V5 和三组 S6 程序的证据见报告**。已关闭配置 IP 与实际源 IP 不同时误拒合法目标的 P2。C1–C4 保留;C5 仅在 Client 原生转发入口拒绝自身,不改协议、进度模型或 Source 发送算法。类型检查仍有 37 条改动范围外诊断;C6 未实施,仅提交当前分支,不合并或推送。 +状态:**C6 本轮验收与文档收尾完成,待人工接受明确边界**。基于 C5 的 `b0e2783008`,V6 实际 **692 passed、1 skipped**;真实内容/ACK/owner 及 P01–P20 覆盖/部分覆盖见[总体报告](transfer-control-lifecycle-report.md#c6总体报告与总验收)。未以 C5 全套或撤回旧方案的结果替代;本轮仅验收文档,不改生产契约、测试、CI 或依赖。已知 37 条类型诊断未重跑、未计通过;仅提交当前分支,不合并或推送,不声明人工总验收通过。 需求依据:[需求卡](transfer-control-lifecycle-requirements.md)。历史实现依据:[上一轮计划](transfer-pause-start-direction-plan.md)及其报告;它们的历史验证结果不作为本轮验证结果。 @@ -83,6 +83,14 @@ Web 的 `client_backend.py` 已知通过 Client 的文件/文件夹转发入口 +### 2.3 本次 C6 收尾清单(用户已批准开始) + +- **意图/拆分**:一个 C6 原子变更,汇总 C1–C5 当前实现的 P01–P20 覆盖、真实运行证据、合并回归及最终风险;不另加协议或新功能。基线为 C5 提交 `b0e2783008`。默认只修改本计划、需求卡、既有实施报告及使用变更记录;如真实验收暴露行为缺陷,先记录最小复现与所属路径,再修既定实现并补消费者契约,不借 C6 扩围。 +- **路径与证据**:P01–P07/P19 对照普通双向恢复及实际会话;P08–P11 对照 Source 仲裁/排空/背压;P12–P16 对照原 owner barrier、独立并行、数值 offset、错误/离线与 ACK;P17 对照已完成任务 EOF 补确认;P18 对照自目标与混合目标;P20 按实际明文/加密、thread/async、别名/wildcard 组合逐项注明,不声称所有笛卡尔积。运行入口为原 file/forward/resume/pause/start 与实际 socket;观察实际内容、ACK、owner/finally、快照和收尾,不以文件存在或测试总数代替。 +- **临时验收程序**:一次性 `/tmp/pyflow-transfer-lifecycle-smoke.py --case `,可由独立临时模块承载六类场景,共用隔离实例/密钥和 worker 收尾设施;不调用 pytest 测试函数、不替换文件/网络/加密主路径。事件固定交叉与明确故障,完成后全部删除。每类运行明文 thread/alias、加密 thread、加密 async/wildcard,tracking off 只验证真实既有保留行;未跑错误窗口明确列出。 +- **机械检查**:本轮只运行一次第 9 节 V6 受影响范围合并回归,不重复 C5 已完成的项目全套、不额外扩大测试策略;失败按真实输出定位后仅重验修正路径。已知类型检查 37 条存量诊断不靠重复运行确认,不扩为清理任务;无生产代码变化则保留其已知状态。 +- **交付/闸门**:报告逐 P01–P20 给覆盖/部分覆盖/未覆盖、当前证据与历史证据区分、C1–C6 提交意图及接口/依赖/CI 影响;对真实错误、重连、并发和未覆盖窗口不隐瞒。路径已覆盖不等于人工最终接受;native Windows/其他 Python/NAT/端点迁移、ACK 写成功但对端未收到及问题二继续单列边界。仅当前分支提交,不合并、不推送,不改保护策略。 + ## 3. 接口与线上契约(用户已批准) ### 3.1 保持不变的部分 @@ -277,9 +285,9 @@ flowchart TD | 本轮 C3 | 已实现:仅数值请求;原 route 旧 owner 全收尾;每 Target 独立流/进度/资源/失败,正文并行;socket+fid 仅端口短串行;保留 C1/C2 和累计真实 ACK | 分次局部回归与 3 组独立程序实际结果见实施报告;未扩大为 V6/C6 总验收 | | C4 | 已批准并实现:复用既有 fid route/completed,不新增记录/字段;Source 显式 EOF 补最终确认,单一原子变更 | C4-P01–P10;实际运行矩阵、局部与完整测试及未覆盖项见报告,不把计划命令当运行结果 | | C5 | 已批准并实现:Client 原生文件/目录在统一入口拒绝自身完整控制端点,合法目标照常传输,拒绝恢复保留旧行 | 六参数回归通过;V5、S6、审查及未跑矩阵以报告实际证据为准 | -| C6 | 未实现:合并回归、全路径总体验收与最终报告 | V6;须单独推进 | +| C6 | 本轮验收与总体报告完成,待人工接受部分覆盖与明确边界 | 唯一一次 V6:692 passed、1 skipped;S1–S6 及补充窗口见当前实施报告,不冒称全平台/全排列 | -本轮不是 C6 总验收声明。实施不新增 wire、依赖、CI、自动重试或身份迁移;用户实施指令授权提交当前分支,不授权合并或推送。旧 C3 历史拆分及授权不作为新实现通过证据。 +C1–C5 现行实现已做本轮 C6 证据汇总;P05/P11/P13/P17/P20 的部分覆盖及协议/平台边界保持明确。本轮不新增 wire、依赖、CI、自动重试或身份迁移;用户实施指令仅授权提交当前分支,不授权合并或推送。旧 C3 历史拆分及授权不作为新实现通过证据。 ## 9. 验收命令和证据格式(计划约定;实际执行见实施报告) @@ -314,7 +322,7 @@ flowchart TD 每个 case 参数矩阵覆盖明文/加密,以及 thread/async 的对应实际分派;原端点重连覆盖配置别名、wildcard。用 Event/Barrier 固定顺序,计时只用于失败截止,不靠 sleep 碰运气。 -证据每条包含:阶段/路径编号、实际命令与退出码、稳定 fid、实际控制/data socket owner、原路径及每 Target 实际 offset、完整内容比较/必要 hash、真实 ACK、队列/worker/索引最终状态。固定 A 正文/ACK 阻塞时观察 B 建流及正文,不能只断言最终都成功。快照 schema 不变;问题二列“暂缓”,未运行参数组列“未覆盖”。本轮待统一验证,不借历史结果充数。 +证据每条包含:阶段/路径编号、实际命令与退出码、稳定 fid、实际控制/data socket owner、原路径及每 Target 实际 offset、完整内容比较/必要 hash、真实 ACK、队列/worker/索引最终状态。固定 A 正文/ACK 阻塞时观察 B 建流及正文,不能只断言最终都成功。快照 schema 不变;问题二列“暂缓”,未运行参数组列“未覆盖”。C6 已按实际输出交付总体报告,未借历史结果充数;证据缺口和未保留端点的观察器限制已单列。 ## 10. 影响、风险与人工确认闸门 @@ -326,4 +334,4 @@ flowchart TD - **规则沉淀**:实际会话取消、数值实际 offset、原 owner/finally barrier、不同 offset 独立并行、晚来目标不等正文/ACK、全局 pause 与真实 ACK 聚合成为本轮回归路径;不新增源码字符串断言或严格代次隔离承诺。 - **文档/报告**:最终报告逐 P01–P20 给结论,单列问题二暂缓;每个原子变更含意图、范围、数据流、局部命令、未覆盖项、风险;文档随变更完成,不留“以后补”。 -C3/C4 历史实现与本轮 C5 实际证据见[实施报告](transfer-control-lifecycle-report.md)。C5 保持第 2.2 节的单原子意图、文件范围及原生转发边界;不修改独立磁盘扩展/消息转发契约。C6、合并与推送仍须人工确认。 +C1–C6 现行结果及逐路径限制见[实施报告](transfer-control-lifecycle-report.md#c6总体报告与总验收)。本轮仅四份既有验收文档收尾;不改变独立磁盘扩展/消息转发契约。部分覆盖与平台/协议边界仍须人工接受,合并及推送仍须另获人工明确批准。 diff --git a/docs/plans/transfer-control-lifecycle-report.md b/docs/plans/transfer-control-lifecycle-report.md index 1b472c8..873fef5 100644 --- a/docs/plans/transfer-control-lifecycle-report.md +++ b/docs/plans/transfer-control-lifecycle-report.md @@ -1,5 +1,161 @@ # 传输控制生命周期实施报告 +## C6:总体报告与总验收 + +**当前状态**:用户已批准 C6;本轮首次 V6 合并回归实际为 **692 passed、1 skipped,1028.13s**,退出 0。独立真实场景按下文记录。以下 C1–C5 章节是各阶段交付时的历史记录,不代表其旧“未实现/待验证”文字仍为当前状态;撤回的旧 C3a/C3b 不作为当前验收依据。本节只统计本轮实际输出,不借 C5 的 994 passed 冒充 C6 结果。 + +### Standards + +**硬违规 0、阻塞 0、Fowler 判断项 0;correct,置信度 0.96。** 只读审查确认逐路径内容/ACK/owner 与测试数分开、五项部分覆盖清楚,四文档单原子范围与候选一致,未修改生产/测试/CI/依赖/公共接口;当前 C6 入口与历史状态、人工接受/合并/推送闸门明确。未编辑、运行 git 或执行检查。 + +### Spec + +**0 个阻塞,correct,置信度 0.94。** 只读审查确认 C6 保持四文档范围,本轮结果与历史结果分开;P05/P11/P13/P17/P20 部分覆盖已披露,与独立运行证据及抽查消费者契约相符。tracking-off 实际组合、owner 样本、实例重建/手工 self 行/Flask test client 和人工闸门未冒称额外覆盖。未运行 git、测试或其他检查。 + +### 范围与总体数据流 + +- 基线 `b0e2783008`;C6 仅修改需求卡、计划、当前总体报告和变更记录。本轮未修改生产代码、测试或 CI,不增加 wire、公开签名、依赖、五项进度行或 relay 快照字段。 +- 普通恢复仍由实际 Receiver 在旧文件关闭后请求磁盘 offset,同 fid/原路径建新数据腿;运行/暂停/握手/finally 占用不能被恢复抢占。资源由实际控制 socket 的 registry 所有,旧清理不按 peer 扫新连接。 +- 转发由 Source 仲裁全任务用户 pause/start;Server writers 排空在途/已收字节,reader 高低水位仅由本地缓冲变化解除,不把自动背压变成用户 start。 +- 恢复请求经过实际会话/route/child 校验,仅登记每 Target 数值 offset;等原 route 全部旧 owner(含 finally),再各自独立数据流/进度/失败。单 Target ACK 只完成该 Target,累计真实 ACK 后才允许整任务成功。 +- 全目标完成后的显式 EOF 仅复用原 completed 证据,无正文、无 Target 重开;原最终 ACK 写成功后 Server 按 route 身份清理,Source 实际收到 ACK 后清所属上传行。原生自目标拒绝位于 Client 统一入口;mixed 合法目标仍走同一真实传输链。 + +### 当前完成的独立运行证据 + +下面参数缩写只用于本节:**M**=明文 thread/localhost;**E**=加密 thread;**A**=加密 async/wildcard。A 中 S1/S2/S4/S5 的恢复组合在真实保留行产生后关闭 tracking;无恢复的 S3 及普通边界补充仍开启 tracking,S6 replay 是手工构造的旧规范 self 行,均不能冒称真实 tracking-off 恢复证据。临时程序不调用 pytest 测试函数,不替换文件/网络/加密主路径;Event 仅固定交叉或明确 ACK 故障。worker 计数含本程序记录到的控制/加密/数据线程,0 存活来自实际 owning 收尾和 join。 + +| 场景/组合 | fid / 控制身份 | 实际证据 | worker / 最终存活 | +|---|---|---|---| +| S1 双向普通恢复 M | upload=802、download=804 | 双向实际 offset=65536,原嵌套路径、完整内容/hash、真实 Source ACK=True、所属进度清空 | 22 / 0 | +| S1 双向普通恢复 E | 同上稳定 fid | 同上,两条加密业务腿 | 35 / 0 | +| S1 双向普通恢复 A | 同上稳定 fid | 同上,保留行 tracking off 恢复 | 37 / 0 | +| 普通握手/finally/空文件 M | 1802/1806;EOF=4112/0 | 同 fid 握手预留及 socket 已释放的 finally 仍拒绝第二恢复;另一 fid 实际 ACK;显式再做才清原行 | 36 / 0 | +| 普通握手/finally/空文件 E | 同上稳定 fid | 两次明确业务 ACK False 后一次 True;真实内容/hash,不凭 size 或文件存在认定完成 | 49 / 0 | +| 普通握手/finally/空文件 A | 同上稳定 fid | async/wildcard,tracking 仍开启;该程序 JSON 的 untracked 仅参数回显,不算关闭 tracking | 50 / 0 | +| S2 旧 worker/新会话 M | 4493891096→新普通 4494091096 | 原 ACK False 留行;旧 worker 仍用旧 control 并返回 False;新连接实际消息/新文件 ACK True,旧行同对象 | 26 / 0 | +| S2 旧 worker/新会话 E | 10125171026→10125371026 | 同上,按实际业务 upstream socket 注入 ACK False | 65 / 0 | +| S2 旧 worker/新会话 A | 10265569570→10265769570 | 同上,tracking off 后保留旧 forward 行,旧 worker 收尾 | 65 / 0 | +| S3 全局暂停 M | 8531060282 | Source/Server upstream/每 Target 操作后状态收敛;两 Target 排空 1024 字节;同 socket start | 80 / 0 | +| S3 全局暂停 E | 9463323652 | 同上,reader 重入压力门无新增读取,排空不撤用户 pause | 119 / 0 | +| S3 全局暂停 A | 10419783064 | 再覆盖 Server child;队列 peak=2090≤64+2048,buffer 最终 0,完整内容及真实 ACK | 129 / 0 | +| S4 不同 offset/晚到目标 M | 8567571254;8192/24576 | A 正文门阻塞时 B 晚到、独立 socket/正文/Target ACK;此前无整任务 ACK,A 后完成 | 49 / 0 | +| S4 不同 offset/晚到目标 E | 11740498306;8192/24576 | A Target ACK 门阻塞时 B 完成;累计 B、A 真实 ACK 后整任务才 ACK | 88 / 0 | +| S4 不同 offset/晚到目标 A | 12248869122;8192/24576 | 原 live/paused/finally 只 pending;最后旧 owner 退出后建独立流;实际保留行 tracking off | 88 / 0 | +| S4 离线/新会话/单流失败 M | 4429802526;初始 16384/8192→A 新 24576 | Source 离线 pending 保留;A 断线丢旧请求,原端点新会话重发;A 再断腿不动 B,另 fid 真 ACK,显式 A 再恢复才整体 ACK | 64 / 0 | +| S4 离线/新会话/单流失败 E | 10150322048;8192/8192→A 新 16384 | 同上,真实加密与新实际 control socket;未自动重试 A | 129 / 0 | +| S4 离线/新会话/单流失败 A | 12168513906;8192/8192→A 新 16384 | 同上,原始保留行 tracking off,兄弟 owner 原对象保留,最终内容/hash/索引归零 | 128 / 0 | +| S5 终态再确认 M | 4799102086 | 两 Target 真实 ACK 后首次最终 ACK False;双端实际实例重建/原端点回连;再次异常保留、显式成功,零正文 | 59 / 0 | +| S5 终态再确认 E | 11454431374 | 同上,加密实际数据 channel;9 类错误/并发/坏头请求拒绝 | 124 / 0 | +| S5 终态再确认 A | 10253682156 | 同上,快照原 schema、保留行 tracking off;query 无行、运行时删除拒绝、关闭后删除不被再次 close 重建 | 126 / 0 | +| S6 自目标 M | Source=127.0.0.1:38647 | 6 次 self/replay False,5 次合法 Source ACK=True;另目标 127.0.0.2:38647 同端口不同 IP 真实收件 | 68 / 0 | +| S6 自目标 E | Source=127.0.0.1:44199 | console/Web file/folder、嵌套空文件,合法内容和 ACK;旧 self 上传行保留 | 80 / 0 | +| S6 自目标 A | Source=127.0.0.1:42569 | 同上,wildcard、tracking off;拒绝前无 fid/新行/请求/数据腿 | 80 / 0 | +| 原 route 握手期 M | 7504141324 | Target 实际控制会话发 child/offset=0 请求,只 pending、不拆原握手;原任务完成后无重复重放 | 26 / 0 | +| 原 route 握手期 E | 9342026838 | 同上,控制 reader 在握手 Event 中仍接收实际消息 | 65 / 0 | +| 原 route 握手期 A | 12610350206 | 同上,资源/final owner 全结束、真实 Target 内容与整任务 ACK | 66 / 0 | +| 原 route EOF 等待 M | 7844326422 | A 最终 ACK 明确失败,B ACK 被 Event 挂起时 A 请求 offset=65802,只 pending;旧 owner 结束后 A 零正文恢复 | 34 / 0 | +| 原 route EOF 等待 E | 10035117130 | 同上,原尝试 False→同 fid 恢复 True;完成 B 不重传 | 73 / 0 | +| 原 route EOF 等待 A | 11256552678 | 同上,旧 owner 保持到放行;pending 期间控制消息仍送达 | 73 / 0 | + +S5 三组实际 child fid 分别为 `8383925712/12678893008`、`19702615484/23997582780`、`17607792216/21902759512`;全部 Target 已离线仍可确认。非空文件 65802 字节,SHA-256 `e0d362d4ab08c66b550e9ba59b456d2dd652e987d0f5921a94ad4acdb342bfa2`,两次确认仅三段原头;原目标 inode/mtime/内容不变。实际拒绝 unknown fid、错误成员、多目标、错误 Source、有效确认重复、finally 重复、非 EOF、offset 过大及截断头;失败保留同一原 route/行,最终 route/index/recovery/快照清空。 + +S6 文件 33031 字节,SHA-256 `52c984d43140724ae6a08aee355df7bd6a5f92e1d389eb299e731c21d1b46038`;自拒绝日志可见,每组仅 5 条合法请求,手工构造的旧 self 恢复 fid=619 行对象保留。Web 使用 Flask **test client** multipart `/api/send_file`/`/api/send_folder` 驱动真实后端与 TCP,不是监听 HTTP 端口或浏览器/UI 验收;HTTP 200 仍是异步受理,不是完成或新增 UI 拒绝提示。握手/EOF 窗口内容 SHA-256 `60fc47cfdeb525fd8cbe7a8226c3f7472c645a086e9dbfad195d9c1af4d5c736`,EOF 等待场景保持稳定 child 与原 offset,原尝试 False、后续 True;不把协议零 offset 请求说成已落盘非零恢复。 + +S1 Advanced 另跑明文 alias 与加密 async/wildcard/tracking-off 两组:同一接收根的 `bundle/a/same.bin`、`bundle/b/same.bin` 内容/hash 均正确;fid=902 两次真实断腿的实际 offset 为 65536、131072,paused busy 返回 False 并保留原 socket,另一 fid=904 独立完成真实 ACK。五字段快照关闭并重建 Server **实例**后从 131072 恢复到最终 ACK;worker 分别 29/59,最终存活均 0。不是进程重启。S2 Advanced 同两组在新会话另完成原生 forward 新 fid `10457927960`、`19838860184`,Target 完整 hash、Source 返回 True,worker 32/71、最终 0;不是把新普通文件误称成新 forward。 + +S3 首两组在 socket 收尾后才采端点,JSON `owners=[]`,不作为已记录端点声明;socket 身份保持、内容、暂停和 ACK 断言确实通过,第三组记录实际双向端点。S4 三组真正重建各 Target 原 child、保留 `original/nested/relay.bin`,原 Target 请求通过 Receiver 的 `_request_resumes()` 发送;原 Server finally 挂起时没有 active,A 阻塞时 B 先确认不清共享 Source 行。非最后恢复流的返回 False 表示整任务未完成,不是 Target 内容失败。 + +S4 故障补充不是预置恢复行:原两 Target 首次真实落盘后关数据腿;Source 实际离线,Receiver 原入口发送数值请求。A 实际控制连接关闭会删除只绑定旧 socket 的 pending,B 不丢;Source 原端点回连先服务 B,A 原端点新会话自动从磁盘重发。A 第一次恢复新增一块后再次关自身数据腿,Source 返回 False;共享控制仅留下 B owner,B 与无关普通 fid=1702 的内容/真实 ACK 不受影响。A 无自动重发;B 已完成仍保留 route/Source 共享行,A 显式以新实际 offset 重做后才有一个上游成功 ACK。三组 Source 结果均为原任务 False、A 失败 False、B 整体未完成 False、最后 A True;末尾 route/index/recoveries/进度清理,并由 owning cleanup 收尾所有 worker。 + +实际 owner 记录样本(同一行左右为该 socket 的 local/peer,均为 `127.0.0.1`;只列输出中取得的样本,不补猜已关闭 socket 端点):S1 M control `34107↔37493`,上传旧 data `58711↔37559`、下载旧 data `44867↔45505`;S2 M 旧 control `43143↔51703`、新 `33079↔51703`;S3 A Source data `40375↔45897`、两 child data `37856↔40149`/`50458↔43689`;S4 M 原 Source data `48709↔42993`,独立 A/B data `60813↔38531`/`56751↔37819`,Target control 为 `34655`/`39629`。S4 故障 A 的 Source control 对象 `134456782269856→134456782271008`、Target control `134456772529120→134456772811104`,新请求按实际新 socket 被接纳,B receive owner 全程同对象;不是只比较 peer 端点猜 owner。 + +### 已记录的验收程序修正 + +- 两条加密 S1 的首轮失败来自临时跨方向 gate 未恢复,旧闭包影响第二方向;恢复原透传方法后只重跑失败参数通过,不修改生产发送。 +- 初次加密 S5 的 ACK 观测仅按标记计数,误把密钥传输 ACK 当业务 ACK,实际显式确认先成功;诊断输出 `expected=[False], observed=[True], ack_attempts=3`。改为同时匹配原 route originator 与实际业务数据 socket 后,仅重跑受影响的加密参数通过,不修改生产加密或 ACK 协议。 +- 原 EOF 窗口首轮已取得 False→True,但临时程序硬钉两个并发 Target ACK 回调的先后顺序;改为每 Target 的真实尝试次数和最后 A 恢复 ACK,保留全部内容、pending、owning 及结果断言,仅重验失败场景。握手已通过参数未重跑碰数。 +- S2 初次三组 ACK 观察只按消息内容筛选,存在误命中公钥传输的风险;不计入有效 S2。修为同时限定业务 fid、实际 control 和 upstream data socket 后重验三组通过。Advanced 首轮 gate 把同一已关闭 socket 的尾部发送误当第二条腿而阻塞;改为仅不同 socket 固定事件后只重验失败两组通过。 +- S3/S4 临时程序在批次运行期间被编辑导致四组 IndentationError,修复后只重验失败四组。S4 透传闭包晚绑定,明文一次表面 exit 0 也不计有效,加密两组等待正文门失败;固定 Server 原方法绑定并按业务 fid/socket 记录 ACK 后仅重验无效/失败三组通过。未修改产品 I/O、加密或协议。 +- S4 故障补充的两次明文首轮失败来自临时程序硬钉 `file.write` 必须恰好 8192;诊断实际两文件为 24576/8192,TCP 接收允许合并写块。改为首个真实正写入后固定 Event、从已关闭文件/保留行读取各自实际 offset,不手工截断或改内容,再运行失败明文及此前未运行的两组加密均通过。未把正文发送块边界当接收写边界。 +- 普通边界补充首轮临时观察器读取不存在的握手 `fid` 字段,尚未发业务就 KeyError;移除字段假设后又发现直接调用 `file_transfer_mode` 不经过外层 `_sending_transfer`,因此 finally Event 不到。改为观察真实 `resume_trans` worker 的外层 finally,只重验失败明文及未运行加密组合通过:业务 ACK 序列 False、False、True,busy 阶段无第二 worker。这里不是新增产品修复。 + +### P01–P20 本轮对照 + +“覆盖”只表示所列路径和实际参数有运行时/机械证据,不表示所有平台或所有排列已验收;“部分”列出本轮未独立证明的窗口。V6 集成路径是真实 socket 消费者,unit 的预置 registry/进度不是独立端到端场景。以下引用的测试均包含在本轮唯一一次 V6 中,未为填表重跑。 + +| 路径 | 结论 | 本轮证据与限制 | +|---|---|---| +| P01 普通上传 | 覆盖 | S1 双向中的上传;关闭文件后实际 offset、同 fid、原路径/hash/真实 ACK,M/E/A | +| P02 普通下载 | 覆盖 | S1 双向中的下载,M/E/A;不把上传证据代替下载 | +| P03 文件夹/同名不同目录 | 覆盖 | S1 Advanced 同接收根 `bundle/a`/`bundle/b`;S6 原生 folder 枚举、嵌套空文件及 Web 文件夹适配 | +| P04 普通 live/paused/握手/finally | 覆盖 | S1 Advanced paused/live busy、其他 fid;普通边界补充握手及 socket 已释放 finally 保留同 owner、`resume_trans=False`,后续真 ACK;独立程序后两窗口为上传方向 | +| P05 换腿再断线/重启 | 部分 | S1 Advanced 同 fid 两次断线、实际 65536→131072、Server 实例重建/原端点回连;未运行独立进程重启 | +| P06 实际会话/迟到清理 | 覆盖 | S2 旧 worker 固定旧 control/new 可用;V6 `test_relay_offline_source_replays_stable_route_or_stops_cleanly` 在新 owner 活跃时再次释放旧资源,原对象仍在且有最终内容/ACK | +| P07 旧 worker/connect | 覆盖 | S2 挂起 worker 与 connect 交叉,旧 socket False、旧行同对象、新消息/普通新 fid/原生新 forward 真 ACK;不是靠等待 30s 判定 | +| P08 各参与者 pause/start | 覆盖 | S3 + V6 五 issuer 参数(Source、Server upstream/alias、两个 Target);已确认状态收敛、另一端 start、完整内容 | +| P09 未确认反向/交叉/重复 | 覆盖 | V6 `test_relay_cross_target_start_and_unconfirmed_reverse_intent_reach_source` 用 Event 固定 Source pause 通知,未确认时两 Target 反向 start,最后全状态 False/内容 ACK;普通双向亦有对应交叉契约 | +| P10 在途/排队排空 | 覆盖 | S3 两 Target 在 pause 时各写入 1024 字节,Source 下一块等待、同 socket start,真实 ACK;V6 双向普通排空 | +| P11 本地压力与 start | 部分 | S3/V6 reader 重入时读数不变、用户 start 不开压力门、drain 不撤用户 pause、peak≤high+max;未独立负断言自动压力绝不发送控制帧,不声明进程总内存上限 | +| P12 原 route 各 owner 窗口 | 覆盖 | S4 live/paused/finally、六组握手/EOF 等待补充:只 pending、不关旧 owner、结束后才恢复;控制消息和另一 fid 仍实际完成 | +| P13 错路由/去重/旧会话 | 部分 | V6 `test_resume_rejects_forged_or_stale_requesters_before_registration`、`test_duplicate_registration_keeps_only_the_latest_pending_offset` 为 unit 准入/去重;S4 故障为真实旧 socket pending 丢弃/新会话重发;未把所有非法 wire 请求独立透过控制 reader 重放 | +| P14 不同 offset/独立并行 | 覆盖 | S4 8192/24576、晚到 B;A 正文门/Target ACK 门各一种组合时 B 真实完成,最后累计 Target ACK 才整任务 ACK;V6 多 owner 共享 pause 与迟到旧释放 | +| P15 离线/单流失败 | 覆盖 | S4 故障三组:离线 Source pending,Target 旧请求丢弃、新 socket 重发,A 新实际 offset 重做;B owner/内容/ACK 和无关 fid=1702 保留,无自动重试;V6 Source/stop 两分支 | +| P16 零 offset/空文件/EOF | 覆盖 | 普通边界补充真实空文件 offset=0/EOF=4112,S4 Target EOF、S5 终态 EOF;V6 `test_forward_resume_with_zero_offset_reuses_existing_route` 通过真实原 wire/ACK 验证预置空文件 route 无新分配,明确它不是实际断腿产生的行 | +| P17 全目标完成补最终确认 | 部分 | S5 三组 Target 已真实 ACK、首上游 False、再次异常、显式成功、原记录重载、目标离线、坏头/并发/finally、零正文/无 Target 新命令;V6 C4 契约补充最后独立恢复后的 ACK 失败;未独立对 C4 组合 stop/中途 rekey/无关活跃 fid 全部交叉 | +| P18 自目标/混合/同机端点 | 覆盖 | S6 三组 self/replay False 且无新 fid/行/腿,mixed 真内容/ACK;M 另运行同端口不同 IP;Web 只验后端适配,非 UI | +| P19 tracking/query/delete/stop | 覆盖 | S1/S4 真实保留行后关闭 tracking;S5 query detached、运行删除拒绝、关闭删除后再次 close 不重建,原五字段行及 upload/download/relays schema;V6 删除/快照契约,无凭空新进度 | +| P20 安全 I/O/模式矩阵 | 部分 | M/E/A 各有真实内容、ACK、安全 channel/owner;V6 两个加密 rekey 参数实际 key reader 继续接收,帧有 FRAME_MAGIC、无明文 pause/start、无 raw 绕过;未覆盖 relay/终态中途 rekey、完整笛卡尔积及其他平台 | + +### 本轮命令与机械结果 + +运行平台:Linux x86_64,`.venv/bin/python` **3.10.20**。合并回归仅执行下面一次,未重新执行 C5 项目全套、未重跑已知 37 条类型诊断。 + +```bash +set -o pipefail +.venv/bin/python -m pytest test/unit/network_api test/integration/network_api/test_tcp_transfer_control.py test/integration/network_api/test_tcp_file_transfer.py test/integration/network_api/test_tcp_transfer_resume.py test/integration/network_api/test_crypto_tcp.py test/integration/network_api/test_tcp_async_server.py test/integration/test_forward_extension.py test/integration/test_forward_msg_attribution.py -q --tb=short 2>&1 | tee local://c6-v6-pytest.log +``` + +实际:**692 passed、1 skipped,1028.13s,exit 0**。明文 rekey 参数在测试中显式 skip(`re-key requires the encrypted fixture variants`),本轮未新增 skip;不把 skip 或已知类型诊断计通过。 + +独立程序下列参数组均实际 exit 0;表中 `M/E/A` 分别展开为 `--alias`、`--encrypted`、`--encrypted --async-server --wildcard --untracked`,均使用前缀 `PYTHONPATH="$PWD:/tmp" .venv/bin/python`。命令是本轮历史执行记录,不作为删除临时程序后的长期入口;可持续复验入口是 V6 内已有契约测试。 + +| 程序 | 实际参数组 | +|---|---| +| `/tmp/pyflow_c6_direct.py` | `--case direct-leg` M/E/A;`--case relay-leg` M/E/A | +| 同上 Advanced | `--case direct-leg --gate ack` M/A;`--case relay-leg --gate ack` M/A(此处 ack 是 Advanced 选择,不是 ACK 注入) | +| `/tmp/pyflow_c6_relay.py` | `--case global-pause` M/E/A;`--case parallel-recovery --gate body` M/A;`--case parallel-recovery --gate ack` E | +| `/tmp/pyflow-transfer-lifecycle-smoke.py` | `--case parallel-recovery --window handshake` M/E/A;`--case parallel-recovery --window eof` M/E/A | +| 同上终态/自拒绝 | `--case eof-confirm` M/E/A;`--case self-target` M/E/A | +| `/tmp/pyflow_c6_faults.py` | `--case parallel-recovery` M/E/A | +| `/tmp/pyflow_c6_edges.py` | `--case direct-leg` M/E/A;该 A 的 tracking 参数未应用,不能据 JSON 参数回显声称 tracking off | + +文档机械检查另实际运行一次:**4 份文档、11 个相对链接、P01–P20 恰好 20 行且顺序一致,15 项覆盖/5 项部分,错误 0,exit 0**。这只证明文档路径/链接和矩阵完整,不增加功能或全局属性通过声明。 + +本节结果来自实际独立程序输出与 V6 日志;八个临时程序/辅助模块均已删除,不保留第二套永久测试框架。没有新增或删除测试、放松断言、coverage、CI 或依赖;新采集过程只修临时观察器,不更改已验证的产品路径。 + +### 原子变更与影响 + +| 阶段 | 原子意图/当前状态 | 主要更改路径与公共影响 | +|---|---|---| +| C1 | 实际控制会话取消及旧 owner 收尾,已实现 | `connect_tcp.py` registry、会话定向取消、worker 固定 control;同 fid/进度格式不变 | +| C2 | Source 仲裁任务级控制、排空与本地背压,已实现 | 同模块控制 registry/relay readers/writers;pause/start 原签名/wire,转发语义改为任务级 | +| 旧 C3a/C3b | 已撤回,不作为现行方案 | `?`/None 查询、强制拆腿及单活跃 FIFO 是历史,不作为本轮契约或通过依据 | +| 本轮 C3 | 数值 offset + 原 owner barrier + 每 Target 独立恢复,已实现 | 同模块 parser/Receiver/route/调度;移除查询,不加 wire/schema 字段,各流正文/ACK 可并行 | +| C4 | 原 route/completed 上显式 EOF 补最终确认,已实现 | 同模块准入/header/最终 ACK/owning 清理;无新 Target 正文、终态表或 Source 行字段 | +| C5 | Client 原生统一入口拒绝自身完整控制端点,已实现 | `_forward_one` 及对应使用文档/契约;console/folder/Web 后端复用,消息/独立扩展不改 | +| C6 | 本次单原子验收与报告收尾 | 仅本报告、需求卡、计划及 `docs/source/changes/transfer-fid-routes.md`;未改生产/测试策略/CI/依赖/公开签名 | + +### 明确边界与人工闸门 + +- native Windows、其他 Python、IPv6/NAT/端点迁移、独立进程重启、全部参数排列均未运行;实例重建不等于进程重启,Flask test client 不等于浏览器验收。 +- 同一控制会话/同 fid 新旧数据腿迟到 pause/start 的严格代次隔离(问题二)继续暂缓;本轮会话定向清理不解决它。不引入 leg_id、换新 fid、自动重试或超时抢占。 +- Server ACK 写成功但 Source 未收到的不确定性继续存在;不新增 ACK-of-ACK、终态证明或自动补偿。EOF 只在已完成集合上补确认,不证明历史文件名/大小/hash。 +- 全局属性的覆盖依据是上述具体 socket 路径、帧检查和 owner/内容/ACK,不把“692 passed”单独当作全局安全证明;P05/P11/P13/P17/P20 的部分覆盖不隐藏。 +- 已知 37 条类型诊断仍保留,未重复运行、未修或计通过。未改 CI、coverage、依赖、wire/schema,未合并、推送或变更保护策略。 +- 规则沉淀复用已存在的消费者契约和本节路径矩阵:实际 socket ownership、finally barrier、每 Target 独立流/实际 offset、累计真实 ACK 和 self 统一入口。C6 没有以新增源码字符串断言替代运行证据。 +- C6 可作为当前分支的验收文档提交;**不声明人工总验收已通过**。人工仍须接受本节部分覆盖与平台/协议边界后决定合并/远端;未接受项保持明确未覆盖,不借历史通过数覆盖。 + + ## C5:原生文件与目录转发自拒绝 **意图与授权**:用户确认“同 IP 且同端口”属于自身,并明确要求开始 C5。混合列表只剔除自身,同 IP 不同端口及不同 IP 同端口仍合法。本次单原子变更不推进 C6,不合并或推送;C1–C4 的历史输出不作为本轮证据。 diff --git a/docs/plans/transfer-control-lifecycle-requirements.md b/docs/plans/transfer-control-lifecycle-requirements.md index 978432c..46c9c05 100644 --- a/docs/plans/transfer-control-lifecycle-requirements.md +++ b/docs/plans/transfer-control-lifecycle-requirements.md @@ -1,8 +1,8 @@ # 传输控制生命周期与转发恢复 — 需求卡 -状态:**C5 实现、真实运行验证与双轴审查完成:最终完整 pytest 994 passed、1 skipped,八项专项及三组独立程序通过**。拒绝同 IP 且同端口的自身目标,合法目标仍传输;审查发现的配置 IP 与实际源 IP 不同时误拒已修复。C1–C4 保留,不改 fid、wire、公开签名或持久化模型;类型检查仍有 37 条改动范围外诊断,C6 不自动推进。 +状态:**C6 本轮验收与总体报告已交付,待人工接受部分覆盖和明确边界**。唯一一次 V6 实际 **692 passed、1 skipped**;P01–P20 当前证据、失败观察器修正和未覆盖项见报告,不以 C5 的 994 passed 或旧阶段结果替代。本轮仅修改四份验收文档,未改生产行为、测试、协议/公开签名/持久化模型、CI 或依赖;已知 37 条类型诊断未重跑、未计通过。 -本轮命令、实际结果、失败修正及明确未覆盖项见[实施报告](transfer-control-lifecycle-report.md)。旧历史结果不作为 C4 通过证据。用户通过 `/skill:implement` 授权实现、检查、审查及提交当前分支;不合并或推送。 +本轮命令、实际结果、验收程序修正及明确未覆盖项见[实施报告 C6](transfer-control-lifecycle-report.md#c6总体报告与总验收)。旧历史结果不作为当前通过证据。用户通过 `/skill:implement` 授权检查、审查及提交当前分支;不合并或推送,不代表人工总验收已通过。 计划编写阶段的文档机械检查通过:3 份文档、6 个相对链接、21 个计划涉及的既有文件路径、14 个验收命令引用路径、20 条验收路径、6 个原子阶段及命令组、6 个拟定运行场景,错误数为 0。当时实施报告尚未创建;这份历史检查不代表功能验收通过,当前实现证据另见实施报告。 @@ -67,7 +67,7 @@ 7. 同一实际控制 socket+fid 的端口握手短串行以关联既有四 token 回复;锁只覆盖登记/发送/取得端口结果,不覆盖正文、最终 ACK 或整任务。A 已开始正文或等待 ACK 时,B(含晚到 Target)可独立建流和传输,不等 A 完成;不同 offset 不共享正文过滤或旧队列。 8. Source 离线时保留 pending,合法回连/后续触发后处理。Target 断线即丢弃绑定旧实际 socket 的 pending 请求;不把旧请求借给新 socket,重连后由 Receiver 等旧 owner 收尾、读取新实际 offset 重新请求。离线/失败 Target 不阻塞可服务兄弟目标,活跃流失败仅收尾自身,不启动自动重试。 9. Source 仍仲裁全 route 用户 pause/start;多个恢复 sender 共享该任务控制状态,最后一个 owner 退出才释放,任一 Target 的 pause 使所有 Source 流停止新增正文。Server 已收字节继续排空,本地背压与用户 start 独立。 -10. 每个真实 Target ACK 只记该 Target 完成;其他 Target 未完成时不发整 route 成功 ACK,Source 上传行及 Server route 保留。offset 为零、空文件和 EOF 均沿用数值恢复;offset==size 不等于成功。C4 全完成后的上游 EOF 再确认仍未实现。 +10. 每个真实 Target ACK 只记该 Target 完成;其他 Target 未完成时不发整 route 成功 ACK,Source 上传行及 Server route 保留。offset 为零、空文件和 EOF 均沿用数值恢复;offset==size 不等于成功。全部 Target 完成后的上游 EOF 再确认已由 C4 实现,验收必须区分 Target EOF 恢复与该终态补确认。 代价与风险:原 route 尚有活跃传输、用户暂停或未结束的 ACK/finally 时,首次恢复继续等,不增加强制关闭、超时抢占或自动重试。旧 owner 全部收尾后的独立恢复流不互相等待正文/ACK。运行时 pending/active 不扩展持久化 schema,重启后仍由原接收记录重新请求;同 socket+fid 迟到控制消息的严格代次隔离仍暂缓。 @@ -114,8 +114,8 @@ - 恢复入队不关闭任何活跃数据腿、健康控制连接或其他 fid,不删除接收文件;仅自然结束的旧 owner 做原有定向收尾。 - 不把 socket 仍打开或 offset 等于 size 单独作为成功证据。 - pause/start、端口响应、公开 Python 签名及持久化模型不变;不新增 wire 字段、leg_id 或恢复换新 fid。恢复 parser/formatter 只接受数值 offset;调度改为等待原 route 旧 owner 全收尾、每 Target 独立并行恢复。 -- 风险等级:高(多 owner 并发、全局控制共享、文件完整性和真实 ACK 聚合)。本轮实施及局部验证单列;不宣称 C6 总验收通过。按用户实施指令提交当前分支,不合并或推送。 +- 风险等级:高(多 owner 并发、全局控制共享、文件完整性和真实 ACK 聚合)。本轮证据与限制已交付;P05/P11/P13/P17/P20 仍有部分覆盖,人工接受前不宣称人工总验收通过;仅提交当前分支,不合并或推送。 ## 下一阶段闸门 -C4 的实现、验收与旧背压迁移已提交。用户已明确批准 C5 开始,实施及验证严格对照[计划](transfer-control-lifecycle-plan.md) 2.2 节,实际证据见[报告](transfer-control-lifecycle-report.md)。C5 仅提交当前分支,不合并或推送;C6 须另获批准。 +C1–C5 现行实现与本轮 C6 证据已汇总,按[计划](transfer-control-lifecycle-plan.md) 2.3 节单原子收尾和第 9 节完成一次 V6。[总体报告](transfer-control-lifecycle-report.md#c6总体报告与总验收)列明实际覆盖与部分覆盖,旧阶段记录保留其历史状态。下一闸门是人工接受明确边界并决定合并/远端;最终确认前不合并或推送。 diff --git a/docs/source/changes/transfer-fid-routes.md b/docs/source/changes/transfer-fid-routes.md index 13925fe..eab03ca 100644 --- a/docs/source/changes/transfer-fid-routes.md +++ b/docs/source/changes/transfer-fid-routes.md @@ -7,6 +7,25 @@ > `docs/plans/transfer-pause-start-direction-report.md`; those historical > results are not verification of the current lifecycle revision. +## Lifecycle revision C6: combined acceptance evidence + +- The affected-scope V6 run completed with **692 passed, 1 skipped** on Linux + x86_64 / Python 3.10.20. The skip is the plaintext rekey variant; encrypted + rekey variants exercised the real key reader and framed control channel. +- Independent real-socket scenarios cover ordinary bidirectional recovery, + old-session ownership, global pause/drain/pressure, independent Target flows, + offline/new-session recovery, per-stream failure, explicit EOF confirmation + and native self-target rejection. Content, actual ACKs and owner cleanup are + recorded per scenario in the current report, not inferred from test counts. +- P05/P11/P13/P17/P20 retain explicit partial coverage. Native Windows, other + Python versions, process restart, relay/terminal rekey and browser UI were + not verified. Flask test-client requests exercised the Web backend and TCP, + not a listening HTTP server or browser. Same-session/FID generation isolation + and a successful final-ACK write lost before Source receives it stay deferred. +- This stage changes acceptance documents only: no production, tests, protocol, + schema, dependencies or CI changes. Known 37 type diagnostics remain unrerun; + results do not imply human final acceptance, merge or push approval. + ## Lifecycle revision C5: refuse native self-target file forwarding - Filter the Source's complete control endpoint in the shared Client per-file From 23cbc5773fa28671140cf151338d7a84e3651ffc Mon Sep 17 00:00:00 2001 From: F18-Ray Date: Sat, 21 Nov 2026 14:53:19 +0800 Subject: [PATCH 16/19] fix(tcp): reserve the receive FID before publishing a relay route - Claim a fresh upstream receive slot before publishing a new relay. Check reservation identity at publication and release only that claim if registration fails. Leave existing-route recovery and the wire format unchanged. - Cover listener-first and relay-first admission, competing relays, and a real interrupted ordinary upload that resumes from its 22-byte prefix through the final ACK. - Verification: test_fid_routes.py (48 passed); test_tcp_transfer_resume.py -k "fid_collision or resume" (78 passed). --- PyFlow/network_api/connect_tcp.py | 109 +++++++----- docs/source/changes/transfer-fid-routes.md | 17 ++ .../network_api/test_tcp_transfer_resume.py | 157 +++++++++++++++++- test/unit/network_api/test_fid_routes.py | 34 ++++ 4 files changed, 274 insertions(+), 43 deletions(-) diff --git a/PyFlow/network_api/connect_tcp.py b/PyFlow/network_api/connect_tcp.py index b9ef555..9f42591 100644 --- a/PyFlow/network_api/connect_tcp.py +++ b/PyFlow/network_api/connect_tcp.py @@ -3171,13 +3171,15 @@ def _file_progress_finish(self, progress_dict, fid, entry, keep=False): # a transfer that ended must not be resumed on a later reconnect self._persist_transfer_progress() - def _register_fid_route(self, fid, originator, targets, completed=()): - """Register a route only when its upstream and target legs are unclaimed.""" + def _register_fid_route(self, fid, originator, targets, completed=(), *, receive_record=None): + """Publish a route for a free FID (restore) or its exact receive reservation.""" targets = {tuple(target): child for target, child in targets.items()} completed = {tuple(target) for target in completed} route = {"originator": tuple(originator), "targets": targets, "completed": completed} upstream_leg_keys = {(target, fid) for target in targets} with self._transfer_progress_lock: + if self._receive_transfers.get(fid) is not receive_record: + return None active_collision = ( fid in self._active_transfer_fids or fid in self._active_transfer_sockets @@ -3210,12 +3212,42 @@ def _register_fid_route(self, fid, originator, targets, completed=()): ) ): return None + if receive_record is not None and ( + any(key in self._forward_relays for key in targets.items()) + or any(leg["fid"] == fid for leg in self._forward_relays.values()) + ): + return None self._fid_routes[fid] = route for target, child in targets.items(): if target not in completed: self._fid_route_index[(target, child)] = fid return route + def _admit_new_relay(self, relay, control_socket, originator, target_fids): + """Reserve the upstream FID before making the new relay discoverable.""" + fid = relay["fid"] + with self._transfer_progress_lock: + # Unlike recovery, a new relay must not adopt an ordinary resume + # request even if it came from the same control socket. + if fid in self._receive_transfers: + return None + record = _claim_receive(self, fid, control_socket, owner=relay) + if record is None: + return None + try: + relay["route"] = self._register_fid_route( + fid, originator, target_fids, receive_record=record + ) + finally: + if relay["route"] is None: + _release_receive(self, fid, record) + if relay["route"] is None: + return None + with self._forward_relays_lock: + for key in target_fids.items(): + self._forward_relays[key] = relay + return record + def _lookup_fid_route(self, peer, fid): """Find a local upstream or an exactly scoped downstream relay leg.""" with self._forward_relays_lock: @@ -7390,14 +7422,7 @@ def _forward_relay( tfids = [route["targets"][target] for target in targets] else: tfids = [self._fid_alloc.alloc(receiver=target) for target in targets] - route = self._register_fid_route( - fid, originator_addr, dict(zip(targets, tfids)) - ) - if route is None: - self._forward_notify_error( - forwarder_sock, "relay fid is already in use", fid - ) - return + route = None # assigned to the relay only after receive admission manual_recovery = resume_requested and reservation is None and not eof_confirmation relay: dict = { "cond": threading.Condition(), @@ -7412,37 +7437,43 @@ def _forward_relay( relay_keys = [(target, tfid) for target, tfid in zip(targets, tfids)] receive_key = (targets[0], fid) if resume_requested and not eof_confirmation else fid receive_record = None - with self._transfer_progress_lock, self._forward_relays_lock: - confirmation_busy = eof_confirmation and ( - any(key == fid or isinstance(key, tuple) and key[1] == fid - and key[0] in route["targets"] for key in self._receive_transfers) - or any(candidate["fid"] == fid for candidate in self._forward_relays.values()) - or recovery is not None and bool(recovery["active"]) + if route is None: # only new relays reach admission without a route + receive_record = self._admit_new_relay( + relay, forwarder_sock, originator_addr, dict(relay_keys) ) - if (self._fid_routes.get(fid) is route - and not confirmation_busy - and (resume_requested and fid not in self._receive_transfers - or not resume_requested and not any( - candidate["fid"] == fid for candidate in self._forward_relays.values())) - and (reservation is None - or self._receive_transfers.get(receive_key) is reservation["record"]) - and not any(key in self._forward_relays for key in relay_keys)): - receive_record = _claim_receive(self, receive_key, forwarder_sock, relay) - if receive_record is not None: - for key in relay_keys: - self._forward_relays[key] = relay - if resume_requested and recovery is None and not eof_confirmation: - recovery = {"route": route, "pending": {}, "active": {}, - "control": {"control_lock": threading.RLock(), - "requested": None, "controls": {}}} - self._relay_recoveries[fid] = recovery - if manual_recovery and recovery is not None: - reservation = {"record": receive_record, "source_socket": forwarder_sock, - "target_socket": self.clients.get(targets[0], {}).get("socket"), - "offset": resume_offset} - recovery["active"][targets[0]] = reservation + else: + with self._transfer_progress_lock, self._forward_relays_lock: + confirmation_busy = eof_confirmation and ( + any(key == fid or isinstance(key, tuple) and key[1] == fid + and key[0] in route["targets"] for key in self._receive_transfers) + or any(candidate["fid"] == fid for candidate in self._forward_relays.values()) + or recovery is not None and bool(recovery["active"]) + ) + if (self._fid_routes.get(fid) is route + and not confirmation_busy and fid not in self._receive_transfers + and (reservation is None + or self._receive_transfers.get(receive_key) is reservation["record"]) + and not any(key in self._forward_relays for key in relay_keys)): + receive_record = _claim_receive(self, receive_key, forwarder_sock, relay) + if receive_record is not None: + for key in relay_keys: + self._forward_relays[key] = relay + if recovery is None and not eof_confirmation: + recovery = {"route": route, "pending": {}, "active": {}, + "control": {"control_lock": threading.RLock(), + "requested": None, "controls": {}}} + self._relay_recoveries[fid] = recovery + if manual_recovery and recovery is not None: + reservation = { + "record": receive_record, "source_socket": forwarder_sock, + "target_socket": self.clients.get(targets[0], {}).get("socket"), + "offset": resume_offset, + } + recovery["active"][targets[0]] = reservation if receive_record is None: - self._forward_notify_error(forwarder_sock, "relay source is already active", fid) + reason = ("relay source is already active" if resume_requested + else "relay fid is already in use") + self._forward_notify_error(forwarder_sock, reason, fid) return control_group: dict = recovery["control"] if recovery is not None and not eof_confirmation else relay if os.path.exists(self.file_trans_progress_file): diff --git a/docs/source/changes/transfer-fid-routes.md b/docs/source/changes/transfer-fid-routes.md index eab03ca..1639674 100644 --- a/docs/source/changes/transfer-fid-routes.md +++ b/docs/source/changes/transfer-fid-routes.md @@ -7,6 +7,23 @@ > `docs/plans/transfer-pause-start-direction-report.md`; those historical > results are not verification of the current lifecycle revision. +## New relay admission: reserve the upstream FID before publishing a route + +- **Core logic:** A waiting ordinary listener owns its FID even before it has + a progress row or data socket. A new relay must win a fresh receive + reservation; it cannot adopt a pending ordinary request on the same session. +- **Modules and interactions:** Server `_forward_relay` claims the FID, then + `_register_fid_route` checks the exact reservation before publishing the route + and child indexes. Snapshot restore has no reservation and requires a free + receive slot. Existing-route recovery still adopts its own reserved leg. +- **Assumptions:** Child FIDs are allocated outside the progress lock. Fresh + admission holds that lock through live-leg registration, not through target + negotiation or I/O. A rejected registration releases only its own record. +- **Maintenance:** Do not publish and then roll back: reconnect can observe a + transient route and skip an ordinary partial file. Failure *after* admission + (e.g. a refused target listener) still retains a recoverable route. The + listener-first and competing-relay cases live in `test_tcp_transfer_resume.py`. + ## Lifecycle revision C6: combined acceptance evidence - The affected-scope V6 run completed with **692 passed, 1 skipped** on Linux diff --git a/test/integration/network_api/test_tcp_transfer_resume.py b/test/integration/network_api/test_tcp_transfer_resume.py index e637620..e02feee 100644 --- a/test/integration/network_api/test_tcp_transfer_resume.py +++ b/test/integration/network_api/test_tcp_transfer_resume.py @@ -1370,9 +1370,9 @@ def observe_wait(record, timeout): monkeypatch.setattr(source._transfer_handshakes, "wait", observe_wait) real_register = server._register_fid_route - def capture_route(fid, originator, route_targets, completed=()): + def capture_route(fid, originator, route_targets, completed=(), **kwargs): route_registrations.append((fid, tuple(originator), dict(route_targets))) - return real_register(fid, originator, route_targets, completed) + return real_register(fid, originator, route_targets, completed, **kwargs) monkeypatch.setattr(server, "_register_fid_route", capture_route) real_allocate = server._fid_alloc.alloc @@ -1516,9 +1516,9 @@ def capture_command(sock, message, is_send_raw=False): registrations = [] real_register = server._register_fid_route - def observe_registration(fid, originator, route_targets, completed=()): + def observe_registration(fid, originator, route_targets, completed=(), **kwargs): registrations.append(fid) - return real_register(fid, originator, route_targets, completed) + return real_register(fid, originator, route_targets, completed, **kwargs) monkeypatch.setattr(server, "_register_fid_route", observe_registration) dropped_routes = [] @@ -1557,6 +1557,154 @@ def observe_allocation(*, receiver=None): _close_socket_workers(server, clients, workers) +def test_waiting_ordinary_listener_keeps_its_fid_and_resumes_after_relay_collision( + tmp_path, monkeypatch +): + workers = _track_socket_workers(monkeypatch) + server = _start_server(tmp_path) + clients = [] + try: + recv_dir = tmp_path / "ordinary_receive" + recv_dir.mkdir() + server.file_transfer_dir = str(recv_dir) + prefix, tail = b"A partial file prefix\n", b"remaining body\n" + src = tmp_path / "ordinary.bin" + src.write_bytes(prefix + tail) + uploader = _start_client(tmp_path, server, file_transfer_chunk_len=len(prefix)) + clients.append(uploader) + forwarder = _start_client(tmp_path, server, name="forwarder") + clients.append(forwarder) + peer = uploader.client_socket.getsockname() + server_peer = (server.host, server.port) + fid = 606 + + port, stamp = request_transfer_listener(uploader, server, f"/file {src.name} {fid}") + record = server._receive_transfers[fid] + assert record["owner"].getsockname()[1] == port + assert fid not in server.file_recv_progress and fid not in server._active_transfer_sockets + monkeypatch.setattr(forwarder._fid_alloc, "alloc", lambda *, receiver: fid) + assert not forwarder._forward_one("file", "", src.name, str(src), [peer]) + assert server._receive_transfers[fid] is record and record["owner"].fileno() >= 0 + assert not server._fid_routes and not server._fid_route_index and not server._forward_relays + + # Use that same listener. Close just the data leg after the first chunk, + # so the real receiver (rather than the test) creates the partial row. + send = uploader.send_message + + def interrupt_tail(sock, message, is_send_raw=False): + if message == tail: + sock.shutdown(socket.SHUT_WR) + return False + return send(sock, message, is_send_raw=is_send_raw) + + with monkeypatch.context() as fault: + fault.setattr(uploader, "send_message", interrupt_tail) + assert not uploader.file_transfer_mode( + str(src), server.host, port, 0, control_socket=uploader.client_socket, + crypto=stamp, fid=fid, peer=server_peer, + ) + assert wait_until(lambda: fid not in server._receive_transfers) + output = recv_dir / src.name + assert output.read_bytes() == prefix + assert server.file_recv_progress[fid][0] == len(prefix) + assert (server_peer, fid) in uploader.file_upload_progress + + completed = [] + transfer = uploader.file_transfer_mode + + def observe_ack(*args, **kwargs): + result = transfer(*args, **kwargs) # True only after consuming the final ACK + completed.append((kwargs["fid"], kwargs["resume_offset"], result)) + return result + + monkeypatch.setattr(uploader, "file_transfer_mode", observe_ack) + assert server._request_resumes(peer) == 1 + assert wait_until(lambda: completed, timeout=15) + assert completed == [(fid, len(prefix), True)] + assert output.read_bytes() == prefix + tail + assert wait_until(lambda: not server.file_recv_progress and not server._receive_transfers) + assert (server_peer, fid) not in uploader.file_upload_progress + finally: + _close_socket_workers(server, clients, workers) + + +def test_concurrent_new_relays_keep_one_owner_and_exclude_a_late_listener(tmp_path, monkeypatch): + workers = _track_socket_workers(monkeypatch) + server = _start_server(tmp_path) + clients = [] + release = threading.Event() + try: + recv_dir = tmp_path / "target_receive" + recv_dir.mkdir() + target = _start_client(tmp_path, server, name="target", recv_dir=recv_dir) + clients.append(target) + target_peer = target.client_socket.getsockname() + fid = 606 + src = tmp_path / "relay.bin" + src.write_bytes(b"only the admitted relay reaches the target") + ready, refused = threading.Event(), threading.Event() + start = threading.Barrier(2) + outcomes = {} + push = server.forward_item_to + + def hold_before_target_request(*args, **kwargs): + ready.set() + assert release.wait(timeout=15) + return push(*args, **kwargs) + + def forward(source): + start.wait(timeout=10) + result = source._forward_one("file", "", src.name, str(src), [target_peer]) + outcomes[source.client_socket.getsockname()] = result + if not result: + refused.set() + + monkeypatch.setattr(server, "forward_item_to", hold_before_target_request) + for name in ("first", "second"): + source = _start_client(tmp_path, server, name=name) + clients.append(source) + monkeypatch.setattr(source._fid_alloc, "alloc", lambda *, receiver: fid) + peers = {client.client_socket.getsockname() for client in clients} + assert wait_until(lambda: peers.issubset(server.clients)) + for source in clients[1:]: + threading.Thread(target=forward, args=(source,), daemon=True).start() + assert ready.wait(timeout=10) and refused.wait(timeout=10) + assert set(server._fid_routes) == set(server._receive_transfers) == {fid} + route, record = server._fid_routes[fid], server._receive_transfers[fid] + child = (target_peer, route["targets"][target_peer]) + assert server._fid_route_index == {child: fid} + assert set(server._forward_relays) == {child} + assert server._forward_relays[child] is record["owner"] + assert record["control_socket"] is server.clients[route["originator"]]["socket"] + + # Drive the ordinary command while the relay still owns the FID. Its + # listener setup must return without advertising a port or handing off. + returned = threading.Event() + receive = server.file_transfer_mode_recv + + def observe_listener(*args, **kwargs): + receive(*args, **kwargs) + returned.set() + + monkeypatch.setattr(server, "file_transfer_mode_recv", observe_listener) + with _transfer_handshake(target, target.client_socket, fid) as request: + assert connect_tcp._send_transfer_request(target, request, f"/file ordinary.bin {fid}") + assert returned.wait(timeout=5) + assert target._transfer_handshakes.wait(request, 0) is None + assert server._receive_transfers[fid] is record and server._fid_routes[fid] is route + assert fid not in server._active_transfer_sockets and not server.file_recv_progress + + release.set() + assert wait_until(lambda: len(outcomes) == 2, timeout=15) + assert sorted(outcomes.values()) == [False, True] and outcomes[route["originator"]] + assert (recv_dir / src.name).read_bytes() == src.read_bytes() + assert wait_until(lambda: not server._receive_transfers and not server._forward_relays) + assert not server._fid_routes and not server._fid_route_index + finally: + release.set() + _close_socket_workers(server, clients, workers) + + def test_duplicate_upstream_fid_is_rejected_without_replacing_existing_route( tmp_path, monkeypatch ): @@ -1624,6 +1772,7 @@ def observe_error(sock, message, is_send_raw=False): ] assert target.file_recv_progress == {} assert not server._forward_relays + assert not server._receive_transfers # failed registration released only its fresh claim assert duplicate_addr != source_addr finally: _close_socket_workers(server, clients, workers) diff --git a/test/unit/network_api/test_fid_routes.py b/test/unit/network_api/test_fid_routes.py index 6383ba3..7852099 100644 --- a/test/unit/network_api/test_fid_routes.py +++ b/test/unit/network_api/test_fid_routes.py @@ -3,6 +3,7 @@ import json import socket import threading +from unittest.mock import Mock import pytest @@ -133,6 +134,39 @@ def test_registration_collision_is_atomic_for_primary_and_downstream_indexes(ser assert server._fid_route_index == index_before +def test_route_publication_requires_the_current_receive_reservation(server): + fid, targets = 303, {TARGET_1: 305} + record = _claim_receive(server, fid, object(), owner={}) + assert record is not None + + # Snapshot reload has no reservation; an equal copy is not the owner either. + assert server._register_fid_route(fid, ORIGINATOR, targets) is None + assert server._register_fid_route(fid, ORIGINATOR, targets, receive_record=dict(record)) is None + assert not server._fid_routes and not server._fid_route_index + assert server._receive_transfers[fid] is record + + route = server._register_fid_route(fid, ORIGINATOR, targets, receive_record=record) + assert route is not None and server._lookup_fid_route(TARGET_1, 305) == (fid, route) + + +@pytest.mark.parametrize("prior_request", [False, True], ids=["retired-session", "pending-resume"]) +def test_new_relay_cannot_publish_without_a_fresh_receive_claim(server, prior_request): + fid, control = 303, Mock(spec=socket.socket) + if prior_request: + record = _claim_receive(server, fid, control) + assert record is not None + else: + server._transfer_handshakes.cancel_socket(control) + + server._forward_relay(control, ORIGINATOR, "file", "", "new.bin", [TARGET_1], upstream_fid=fid) + + assert not server._fid_routes and not server._fid_route_index and not server._forward_relays + if prior_request: + assert server._receive_transfers[fid] is record and record["owner"] is None + else: + assert not server._receive_transfers + + @pytest.mark.parametrize( "owner", [ From c161ae470a3b3f77d19ccd9cd7403d114b50c11b Mon Sep 17 00:00:00 2001 From: F18-Ray Date: Sat, 21 Nov 2026 15:27:48 +0800 Subject: [PATCH 17/19] fix(tcp): require framed writes for resume controls - Treat /resume_trans as a secure transfer control on both Client and Server. Reject it before plaintext fallback and keep the existing raw handshake/coordination exceptions unchanged. - Regress missing/non-secure channels and a framing change at the final write lock. Exercise ordinary and relay recovery on encrypted sockets, confirm decoded FID/offset, ciphertext-only wire and final ACK; verify resume writes fail during real rekey. - Verification: test_transfer_handshakes.py (23 passed); test_tcp_transfer_control.py and test_tcp_transfer_resume.py -k "encrypted or rekey or resume" (144 passed, 1 skipped, 27 deselected). --- PyFlow/network_api/connect_tcp.py | 54 ++++---- docs/source/changes/transfer-fid-routes.md | 18 +++ .../network_api/test_tcp_transfer_control.py | 21 ++- .../network_api/test_tcp_transfer_resume.py | 121 ++++++++++++------ .../network_api/test_transfer_handshakes.py | 75 +++++++++++ 5 files changed, 221 insertions(+), 68 deletions(-) diff --git a/PyFlow/network_api/connect_tcp.py b/PyFlow/network_api/connect_tcp.py index 9f42591..fd2b959 100644 --- a/PyFlow/network_api/connect_tcp.py +++ b/PyFlow/network_api/connect_tcp.py @@ -196,12 +196,21 @@ def _bind_local_port_with_fallback(sock, local_address, log, port_label): # drops (see _persist_transfer_progress). After a reconnect the receiver asks # the sender to continue from the bytes it already holds (/resume_trans). RESUME_LINE = "/resume_trans" # receiver -> sender: continue this transfer from an offset +_SECURE_TRANSFER_COMMANDS = ("/pause_trans", "/start_trans", RESUME_LINE) RESUME_ACCEPT_TIMEOUT = 20.0 # seconds a resumed transfer waits for the sender to connect RESUME_PORT_TIMEOUT = 20.0 # seconds a resumed sender waits for the receiver's transfer port RESUME_SECURE_TIMEOUT = 10.0 # seconds a resume drive waits for the framed control channel FILE_COMMAND_TOKENS = 3 # a ``/file `` line carries this many tokens +def _requires_secure_transfer_frame(message): + """Identify transfer-control text, not transfer body bytes or same-prefix commands.""" + if not isinstance(message, str): + return False + parts = message.split(maxsplit=1) + return bool(parts) and parts[0].lower() in _SECURE_TRANSFER_COMMANDS + + def _wait_writable(client_socket, timeout): """Wait until a non-blocking socket accepts more data. @@ -3514,10 +3523,8 @@ def _release_transfer_socket(self, fid, sock): def _wait_control_secure(self, control_socket, timeout=RESUME_SECURE_TIMEOUT): """Wait until a control channel may carry framed protocol lines. - The reconnect flows run right after a session is established, when the - crypto handshake may still be completing; a resume line sent then would - travel plaintext and be dropped by the peer's framing guard. Without - encryption there is nothing to wait for. + A reconnect may precede the end of the handshake. Wait before issuing + the request; the writer still enforces framing if rekey begins later. Args: control_socket (socket.socket): Value used by the operation. @@ -4521,8 +4528,8 @@ def send_message(self, client_socket, message, is_send_raw=False): is encrypted; only for the crypto handshake and transfer coordination lines. Returns: - bool: True when the payload was written, False for an unsupported - payload type. + bool: True when written; False for an unsupported payload or a transfer + control line with no secure channel while encryption is enabled. Raises: RuntimeError: If the server is not running or no socket was passed. @@ -4542,21 +4549,17 @@ def send_message(self, client_socket, message, is_send_raw=False): return written def _write_message(self, client_socket, message): - """Write one payload: encrypted when the channel is up, plaintext otherwise. + """Write one payload; protected transfer commands may not fall back to plaintext. Returns: - bool: True when written, False for an unsupported payload type. + bool: True when written, False if unsupported or required framing is unavailable. """ if not self.running or not client_socket: self._log("disable the connect to server") raise RuntimeError("connection error") with self._crypto_lock: channel = self._channels.get(client_socket) - control_frame = (self.is_enable_encrypto and self.crypto is not None - and isinstance(message, str) - and message.split(maxsplit=1)[:1] in (["/pause_trans"], ["/start_trans"])) - if control_frame and (channel is None or not channel.secure): - return False + control_frame = self.is_enable_encrypto and _requires_secure_transfer_frame(message) if channel is not None and channel.secure: try: if not isinstance(message, (str, bytes)): @@ -4573,6 +4576,8 @@ def _write_message(self, client_socket, message): self._log(f"send msg error: {e}") self._log_exc() raise + if control_frame: + return False # never enter the plaintext writer, including during rekey with self._crypto_get_send_lock(client_socket): # plaintext writes stay ordered per socket try: # add newline character for server to distinguish messages if isinstance(message, str): @@ -9270,10 +9275,8 @@ def _release_transfer_socket(self, fid, sock): def _wait_control_secure(self, control_socket, timeout=RESUME_SECURE_TIMEOUT): """Wait until a control channel may carry framed protocol lines. - The reconnect flows run right after a session is established, when the - crypto handshake may still be completing; a resume line sent then would - travel plaintext and be dropped by the peer's framing guard. Without - encryption there is nothing to wait for. + A reconnect may precede the end of the handshake. Wait before issuing + the request; the writer still enforces framing if rekey begins later. Args: control_socket (socket.socket): Value used by the operation. @@ -9890,8 +9893,8 @@ def send_message(self, client_socket, message, is_send_raw=False): is encrypted; only for the crypto handshake and transfer coordination lines. Returns: - bool: True when the payload was written; False when the client is not - running, no socket was passed, or the payload type is unsupported. + bool: True when written; False if the client is disconnected, the payload + is unsupported, or required transfer-control framing is unavailable. """ if is_send_raw: deal_msg = message.strip() @@ -9907,22 +9910,17 @@ def send_message(self, client_socket, message, is_send_raw=False): return written def _write_message(self, client_socket, message): # noqa: PLR0911 - same exits as the old send_message body - """Write one line: encrypted when the channel is up, plaintext otherwise. + """Write one payload; protected transfer commands may not fall back to plaintext. Returns: - bool: True when written; False when the client is not running, no - socket was passed, or the payload type is unsupported. + bool: True when written; False if disconnected, unsupported, or unable to frame. """ if not self.running or not self.client_socket: self._log("disable the connect to server") return False with self._crypto_lock: channel = self._channels.get(client_socket) - control_frame = (self.is_enable_encrypto and self.crypto is not None - and isinstance(message, str) - and message.split(maxsplit=1)[:1] in (["/pause_trans"], ["/start_trans"])) - if control_frame and (channel is None or not channel.secure): - return False + control_frame = self.is_enable_encrypto and _requires_secure_transfer_frame(message) if channel is not None and channel.secure: try: if not isinstance(message, (str, bytes)): @@ -9937,6 +9935,8 @@ def _write_message(self, client_socket, message): # noqa: PLR0911 - same exits self._log(f"send msg error: {e}") self._log_exc() return False + if control_frame: + return False # never enter the plaintext writer, including during rekey with self._crypto_send_lock: # plaintext writes stay ordered (no-GIL safe) try: # add newline character for server to distinguish messages if isinstance(message, str): diff --git a/docs/source/changes/transfer-fid-routes.md b/docs/source/changes/transfer-fid-routes.md index 1639674..36ef58a 100644 --- a/docs/source/changes/transfer-fid-routes.md +++ b/docs/source/changes/transfer-fid-routes.md @@ -7,6 +7,24 @@ > `docs/plans/transfer-pause-start-direction-report.md`; those historical > results are not verification of the current lifecycle revision. +## Resume requests require framing when encryption is enabled + +- **Core logic:** The normal Client and Server `send_message` path treats + `/resume_trans` like `/pause_trans` and `/start_trans`. If no secure channel + is available, the write fails without entering the plaintext writer or + reporting a sent message. With encryption disabled the wire is unchanged. +- **Modules and interactions:** Ordinary receivers and Server relay recovery + still use `format_resume_line` and the same send path. After selecting a + framed channel, `require_secure=True` rechecks framing under the channel's + final write lock; a write error keeps its existing Client/Server behavior. +- **Assumptions:** A successful `_wait_control_secure` is not a reservation: + rekey can start before the write. Keep the rejection on the plaintext path, + not before a second, independently changing `channel.secure` check. +- **Maintenance:** This does not change the raw handshake/port announcements, + the receive-side plaintext whitelist, other business commands or the retry + policy. The recovery tests observe incoming control bytes, decoded offsets + and final ACKs; the rekey test also covers the async Server. + ## New relay admission: reserve the upstream FID before publishing a route - **Core logic:** A waiting ordinary listener owns its FID even before it has diff --git a/test/integration/network_api/test_tcp_transfer_control.py b/test/integration/network_api/test_tcp_transfer_control.py index b912d97..5759882 100644 --- a/test/integration/network_api/test_tcp_transfer_control.py +++ b/test/integration/network_api/test_tcp_transfer_control.py @@ -360,6 +360,7 @@ def test_receiver_pause_start_waits_for_real_rekey_without_blocking_key_reader( releases.append(key_release) real_push = server._crypto_push_pub_to_client wire, control_writes, notifications = [], [], [] + incoming = [bytearray() for _ in channels] def hold_key(sock, address): key_held.set() @@ -367,7 +368,7 @@ def hold_key(sock, address): return real_push(sock, address) monkeypatch.setattr(server, "_crypto_push_pub_to_client", hold_key) - for secure in channels: + for secure, raw in zip(channels, incoming): real_sendall = secure._sendall def observe_frame(data, sendall=real_sendall): @@ -375,6 +376,12 @@ def observe_frame(data, sendall=real_sendall): return sendall(data) monkeypatch.setattr(secure, "_sendall", observe_frame) + + def observe_input(data, feed=secure.feed, capture=raw): + capture.extend(data) # actual incoming bytes, including any unframed writes + return feed(data) + + monkeypatch.setattr(secure, "feed", observe_input) for owner in (server, client): real_send = owner.send_message @@ -385,11 +392,20 @@ def observe_control(sock, message, is_send_raw=False, send=real_send): monkeypatch.setattr(owner, "send_message", observe_control) receiver.add_message_listener(lambda _peer, message: notifications.append(message)) + assert client._wait_control_secure(client.client_socket) and server._wait_control_secure(control) exchange = threading.Thread(target=client._crypto_exchange_thread, kwargs={"force": True}, daemon=True) exchange.start() assert key_held.wait(timeout=10) - assert wait_until(lambda: all(not secure.frames_allowed.is_set() for secure in channels)) + assert wait_until(lambda: all(not ch.secure and not ch.frames_allowed.is_set() + for ch in channels)) + # Both readiness checks passed before rekey. A resume write on either + # control socket must now fail rather than report a plaintext send. + server_peer = client.client_socket.getpeername() + download = connect_tcp.format_resume_line(808, 7, server_peer, peer) + upload = connect_tcp.format_resume_line(810, 9, peer, server_peer) + assert client.send_message(client.client_socket, download) is False + assert server.send_message(control, upload) is False results = [] def request_both(): @@ -416,6 +432,7 @@ def request_both(): assert control_writes and not any(raw for _line, raw in control_writes) assert wire and all(data.startswith(connect_tcp.FRAME_MAGIC) for data in wire) assert not any(b"/pause_trans" in data or b"/start_trans" in data for data in wire) + assert all(data and b"/resume_trans" not in data for data in incoming) _complete(leg) diff --git a/test/integration/network_api/test_tcp_transfer_resume.py b/test/integration/network_api/test_tcp_transfer_resume.py index e02feee..3e62602 100644 --- a/test/integration/network_api/test_tcp_transfer_resume.py +++ b/test/integration/network_api/test_tcp_transfer_resume.py @@ -2634,13 +2634,29 @@ def test_pause_and_start_trans_control_a_plain_transfer(tmp_path): server.stop() -def test_download_resumes_over_the_encrypted_channel(tmp_path): - """The resume exchange travels on the framed channel like any transfer line. +def _watch_resume_request(monkeypatch, receiver, control): + """Observe the bytes entering this control decoder and the resulting resume line.""" + wire, requests = bytearray(), [] + channel = receiver._channels[control] + feed = channel.feed - With encryption enabled the resume drive waits for the handshake to finish - before it writes ``/resume_trans``, so the request and the resumed leg - both speak frames. - """ + def observe_bytes(data): + wire.extend(data) + return feed(data) + + def observe_line(_peer, message): + if isinstance(message, str) and message.startswith("/resume_trans "): + requests.append(connect_tcp.parse_resume_command(message)) + + monkeypatch.setattr(channel, "feed", observe_bytes) + receiver.add_message_listener(observe_line) + return wire, requests + + +@pytest.mark.parametrize("forwarded", [False, True], ids=["ordinary", "relay"]) +def test_download_resumes_over_the_encrypted_channel(tmp_path, monkeypatch, forwarded): + """Each hop delivers the exact numeric request in a frame, through the final ACK.""" + workers = _track_socket_workers(monkeypatch) ssh_dir = tmp_path / "ssh" ssh_dir.mkdir() port = free_port() @@ -2653,13 +2669,15 @@ def test_download_resumes_over_the_encrypted_channel(tmp_path): ) _isolate(server, tmp_path, "server") _redirect_crypto(server.crypto, tmp_path, ssh_dir, "pub_key") + server_recv = tmp_path / "server_recv" + server_recv.mkdir() + server.file_transfer_dir = str(server_recv) threading.Thread(target=server.start_TCP_Server, daemon=True).start() assert server_ready(server), "server did not start" - client = None - try: - recv_dir = tmp_path / "client_recv" - recv_dir.mkdir() - client = TCP_Client_Base( + clients = [] + + def connect_peer(name, recv_dir): + peer = TCP_Client_Base( host="127.0.0.1", port=port, client_host="127.0.0.1", @@ -2667,48 +2685,73 @@ def test_download_resumes_over_the_encrypted_channel(tmp_path): is_input_command_in_console=False, is_enable_encrypto=True, ) - _isolate(client, tmp_path, "client") - _redirect_crypto(client.crypto, tmp_path, ssh_dir, "pub_key_client") - client.file_transfer_dir = str(recv_dir) - assert client.connect() - assert wait_until(lambda: client.client_socket in client._encrypted_sockets, timeout=15), ( - "the channel never flipped to frames" - ) + clients.append(peer) + _isolate(peer, tmp_path, name) + _redirect_crypto(peer.crypto, tmp_path / name, ssh_dir) + recv_dir.mkdir() + peer.file_transfer_dir = str(recv_dir) + assert peer.connect() + peer._resume_thread.join(timeout=20) # finish the initial empty reconnect scan + assert not peer._resume_thread.is_alive() + control = peer.client_socket + assert wait_until(lambda: control in peer._encrypted_sockets, timeout=15) + assert peer._wait_control_secure(control) + assert server._wait_control_secure(server.clients[control.getsockname()]["socket"]) + return peer + + try: + recv_dir = tmp_path / "client_recv" + client = connect_peer("receiver", recv_dir) + target = client.client_socket.getsockname() + sender = connect_peer("source", tmp_path / "source_recv") if forwarded else server + server_peer = (server.host, server.port) + origin = sender.client_socket.getsockname() if forwarded else server_peer src = tmp_path / "download.bin" payload = os.urandom(64 * 1024) src.write_bytes(payload) - fid = 908 # even low bit: a plain leg's id + fid = 908 # ID on the receiver's leg partial = recv_dir / "download.bin" with open(partial, "wb") as f: f.write(payload[:1024]) - client.file_recv_progress[fid] = [ - 1024, - len(payload), - None, - str(partial), - (server.host, server.port), - ] - upload_key = (client.client_socket.getsockname(), fid) - server.file_upload_progress[upload_key] = [ - 0, - len(payload), - None, - str(src), - client.client_socket.getsockname(), - ] + client.file_recv_progress[fid] = [1024, len(payload), None, str(partial), origin] + downstream = _watch_resume_request(monkeypatch, server, server.clients[target]["socket"]) + probes = [(downstream, fid)] + if forwarded: + upstream = 906 + assert server._register_fid_route(upstream, origin, {target: fid}) is not None + source_probe = _watch_resume_request(monkeypatch, sender, sender.client_socket) + probes.append((source_probe, upstream)) + upload_key = (server_peer, upstream) + send_method = "_forward_one" + else: + upload_key = (target, fid) + send_method = "file_transfer_mode" + sender.file_upload_progress[upload_key] = [0, len(payload), None, str(src), target] - client._request_resumes() # the same call connect() dispatches on reconnect + send = getattr(sender, send_method) + completed = [] + + def observe_ack(*args, **kwargs): + result = send(*args, **kwargs) + completed.append((kwargs["resume_offset"], result)) + return result + + monkeypatch.setattr(sender, send_method, observe_ack) + assert client._request_resumes() == 1 assert wait_until(lambda: partial.stat().st_size == len(payload), timeout=20), ( "the encrypted resume did not finish" ) assert partial.read_bytes() == payload assert wait_until(lambda: fid not in client.file_recv_progress, timeout=10) - assert wait_until(lambda: upload_key not in server.file_upload_progress, timeout=10) + assert wait_until(lambda: upload_key not in sender.file_upload_progress, timeout=10) + assert wait_until(lambda: completed, timeout=10) + assert completed == [(1024, True)] + for (wire, requests), request_fid in probes: + assert requests == [(request_fid, 1024, origin, target)] + assert connect_tcp.FRAME_MAGIC in wire and b"/resume_trans" not in wire finally: - if client is not None: - client.close() - server.stop() + _close_socket_workers(server, clients, workers) def test_client_connects_when_its_configured_port_is_taken(tmp_path): diff --git a/test/unit/network_api/test_transfer_handshakes.py b/test/unit/network_api/test_transfer_handshakes.py index 5fd9176..842d0ff 100644 --- a/test/unit/network_api/test_transfer_handshakes.py +++ b/test/unit/network_api/test_transfer_handshakes.py @@ -1,12 +1,19 @@ """Contract tests for transient transfer-handshake correlation.""" import socket +from contextlib import contextmanager +from types import SimpleNamespace +from unittest.mock import Mock, PropertyMock import pytest from PyFlow.network_api.connect_tcp import ( + TCP_Client_Base, + TCP_Server_Base, + _SecureChannel, _TransferHandshakeRegistry, _parse_transfer_port_announcement, + format_resume_line, ) @@ -174,3 +181,71 @@ def test_port_announcement_keeps_port_and_stamp_pair(): ]) def test_old_or_malformed_listener_replies_are_rejected(line): assert _parse_transfer_port_announcement(line) is None + + +@pytest.fixture(params=[TCP_Client_Base, TCP_Server_Base], ids=["client", "server"]) +def encrypted_writer(request): + endpoint = request.param( + host="127.0.0.1", is_extend_command=True, is_enable_encrypto=True, is_print_log=False, + ) + sock = Mock(spec=socket.socket) + sock.getpeername.return_value = ("127.0.0.1", 5000) + if isinstance(endpoint, TCP_Client_Base): + endpoint.client_socket = sock + endpoint.running = True + return endpoint, sock + + +@pytest.mark.parametrize("has_channel", [False, True], ids=["no-channel", "not-secure"]) +def test_resume_is_not_written_or_reported_without_a_secure_channel(encrypted_writer, has_channel): + endpoint, sock = encrypted_writer + if has_channel: + endpoint._channels[sock] = SimpleNamespace(secure=False) + notifications = [] + endpoint.add_send_message_listener(lambda peer, message: notifications.append(message)) + line = format_resume_line(17, 7, ("source", 1), ("target", 2)) + + assert endpoint.send_message(sock, line) is False + sock.sendall.assert_not_called() + assert not notifications + + +def test_rekey_after_framing_selection_cannot_reenter_plaintext(encrypted_writer): + endpoint, sock = encrypted_writer + # The selected channel stops being secure before the writer can use it. + channel = Mock() + readiness = iter([True]) + type(channel).secure = PropertyMock(side_effect=lambda: next(readiness, False)) + channel.send.side_effect = RuntimeError("channel rekeyed") + endpoint._channels[sock] = channel + line = format_resume_line(17, 7, ("source", 1), ("target", 2)) + + try: + assert endpoint.send_message(sock, line) is False + except RuntimeError: + assert isinstance(endpoint, TCP_Server_Base) # server preserves write exceptions + sock.sendall.assert_not_called() + + +def test_resume_rechecks_framing_at_the_final_write_lock(encrypted_writer): + endpoint, sock = encrypted_writer + session = Mock() + session.rsa.encrypt_for_peer.return_value = "test-ciphertext" + + @contextmanager + def rekey_before_write(): + channel.disable() # readiness passed, but the writer has only just acquired the lock + yield + + channel = _SecureChannel(sock, session, log=None, debug=None, send_lock=rekey_before_write()) + channel.enable("local", "peer") + channel.note_peer_frames_ready() + endpoint._channels[sock] = channel + line = format_resume_line(17, 7, ("source", 1), ("target", 2)) + + if isinstance(endpoint, TCP_Server_Base): + with pytest.raises(RuntimeError, match="framing changed"): + endpoint.send_message(sock, line) + else: + assert endpoint.send_message(sock, line) is False + sock.sendall.assert_not_called() From dfe0c4fdb6e2a81d3f268293beef51b688c8397d Mon Sep 17 00:00:00 2001 From: F18-Ray Date: Sat, 21 Nov 2026 15:34:37 +0800 Subject: [PATCH 18/19] fix(tcp): reject invalid resume formatter offsets - Enforce the numeric resume contract at format_resume_line: accept only a nonnegative integer, including zero, and raise ValueError before rendering any wire command for invalid offsets. - Cover None, query marker, numeric text, negative, boolean and float inputs; preserve existing valid zero/positive round trips. Document that parser, wire identities and persistence remain unchanged. - Verification: .venv/bin/python -m pytest -q test/unit/network_api/test_resume_matching.py (44 passed). Ruff was unavailable at .venv/bin/ruff; the targeted pytest suite passed. --- PyFlow/network_api/connect_tcp.py | 17 ++++++++++++++++- docs/source/changes/transfer-fid-routes.md | 14 ++++++++++++++ test/unit/network_api/test_resume_matching.py | 6 ++++++ 3 files changed, 36 insertions(+), 1 deletion(-) diff --git a/PyFlow/network_api/connect_tcp.py b/PyFlow/network_api/connect_tcp.py index fd2b959..acadf29 100644 --- a/PyFlow/network_api/connect_tcp.py +++ b/PyFlow/network_api/connect_tcp.py @@ -698,7 +698,22 @@ def parse_resume_command(command): def format_resume_line(fid, offset, origin, target): - """Format the only resume wire command, preserving both endpoint identities.""" + """Format a resume command with the required nonnegative integer offset. + + Args: + fid (int): Stable transfer identifier. + offset (int): Bytes already present at the receiver; must be a nonnegative integer. + origin (tuple): Source endpoint identity. + target (tuple): Receiver endpoint identity. + + Returns: + str: The five-token numeric resume command. + + Raises: + ValueError: If ``offset`` is not an integer or is negative. + """ + if type(offset) is not int or offset < 0: + raise ValueError("resume offset must be a nonnegative integer") return (f"{RESUME_LINE} {fid} {offset} " f"{shlex.quote(repr(tuple(origin)))} {shlex.quote(repr(tuple(target)))}") diff --git a/docs/source/changes/transfer-fid-routes.md b/docs/source/changes/transfer-fid-routes.md index 36ef58a..0e40890 100644 --- a/docs/source/changes/transfer-fid-routes.md +++ b/docs/source/changes/transfer-fid-routes.md @@ -7,6 +7,20 @@ > `docs/plans/transfer-pause-start-direction-report.md`; those historical > results are not verification of the current lifecycle revision. +## Resume formatter rejects invalid offsets + +- **Core logic:** `format_resume_line()` accepts only a nonnegative Python + integer offset, including zero. It raises `ValueError` before producing wire + text for `None`, query markers, numeric strings, booleans, floats or negatives. +- **Modules and interactions:** Ordinary and relay recovery still format the + same five-token `/resume_trans` line and use their existing `send_message` + path. The parser, endpoint identities, FIDs and serialized progress are + unchanged. +- **Assumptions:** The formatter must not silently coerce its argument: its + output must be accepted by the numeric-offset parser. +- **Maintenance:** Resume offset validation belongs at the formatter boundary; + no recovery retry, wire migration or sender/file-transfer behavior is added. + ## Resume requests require framing when encryption is enabled - **Core logic:** The normal Client and Server `send_message` path treats diff --git a/test/unit/network_api/test_resume_matching.py b/test/unit/network_api/test_resume_matching.py index 762f99a..e5f4377 100644 --- a/test/unit/network_api/test_resume_matching.py +++ b/test/unit/network_api/test_resume_matching.py @@ -95,6 +95,12 @@ def test_resume_formatter_preserves_zero_and_numeric_offsets(): ) +@pytest.mark.parametrize("offset", [None, "?", "7", -1, True, 1.5]) +def test_resume_formatter_rejects_offsets_outside_the_nonnegative_integer_contract(offset): + with pytest.raises(ValueError, match="offset"): + format_resume_line(304, offset, ("source", 1), ("target", 2)) + + @pytest.mark.parametrize("line", [ "/resume_trans -1 0 '(\"host\", 5)' '(\"target\", 6)'", "/resume_trans 304 -1 '(\"host\", 5)' '(\"target\", 6)'", From b2889b856b55deb6a619798a61e683e5eaa81da2 Mon Sep 17 00:00:00 2001 From: F18-Ray Date: Sat, 21 Nov 2026 16:46:13 +0800 Subject: [PATCH 19/19] test(tcp): the test port unchanged when the resume connect completed --- docs/source/changes/transfer-fid-routes.md | 5 +++++ .../network_api/test_tcp_transfer_resume.py | 11 +++++++++-- 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/source/changes/transfer-fid-routes.md b/docs/source/changes/transfer-fid-routes.md index 0e40890..0a44425 100644 --- a/docs/source/changes/transfer-fid-routes.md +++ b/docs/source/changes/transfer-fid-routes.md @@ -690,4 +690,9 @@ C4a retains ownership until final cleanup and rejects active resume requests. worker-exit assertions. An intermediate immediate-close attempt failed the async unregister check; that result remains in the report. Windows native verification is still pending. +- The ordinary paused-leg retirement test now uses the same server-first FIN + for either sender and checks the client's original endpoint before waiting + for final ACK cleanup. A fallback port is valid for a new connection but + does not identify the old transfer. Both directions passed on Linux CPython + 3.10.20; Windows port reuse still needs native CI verification. diff --git a/test/integration/network_api/test_tcp_transfer_resume.py b/test/integration/network_api/test_tcp_transfer_resume.py index 3e62602..22e0743 100644 --- a/test/integration/network_api/test_tcp_transfer_resume.py +++ b/test/integration/network_api/test_tcp_transfer_resume.py @@ -3788,9 +3788,16 @@ def send_leg(): assert not _start_resume_send(sender, key, target, lambda row: pytest.fail("retired owner"), control_socket=control) - client.client_socket.shutdown(socket.SHUT_RDWR) - assert wait_until(lambda: not client.running and peer not in server.clients) + # Let the server send FIN first: an active close on the client can leave + # its fixed port in TIME_WAIT on Windows, changing the resume identity. + server.clients[peer]["socket"].shutdown(socket.SHUT_WR) + client.receive_thread.join(timeout=10) + assert not client.receive_thread.is_alive() + assert not client.running + client._release_client_socket() + assert wait_until(lambda: peer not in server.clients) assert client.connect() + assert client.client_socket.getsockname() == peer, "client endpoint changed on reconnect" output = (client_recv if receiver is client else server_recv) / src.name assert wait_until(lambda: key not in sender.file_upload_progress and fid not in receiver.file_recv_progress, timeout=20)