diff --git a/GLOSSARY.md b/GLOSSARY.md index 2e0f3f6..800ba4e 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -7,6 +7,15 @@ **转发任务**:将一个文件或文件夹条目交付给一组已接受目标的整体工作;单个目标完成不等于整个任务完成。 _Avoid_:将单条数据流称为整个任务 +**共享上行转发**:同一条目的各已接受目标属于同一个转发任务,共享源端的发送进度和用户暂停状态。 +_Avoid_:把一个目标的数据流当作可独立暂停的任务 + +**一对一转发**:一个转发任务只面向一个目标;同一条目发往多个目标时,各目标的任务可分别暂停和继续。 +_Avoid_:把共享上行转发的一条下游数据流称为一对一转发任务 + +**转发队列预算**:同一中转服务的所有转发任务合计可积压的待下发数据额度,不是预先占用的内存,也不是服务的全部内存用量。 +_Avoid_:把队列预算称作进程内存上限 + **任务交付完成**:转发任务的所有已接受目标均已真实确认收到完整文件的状态。 _Avoid_:发送完毕、单目标完成、仅凭文件大小认定成功 diff --git a/PyFlow/flow_setup.py b/PyFlow/flow_setup.py index 03908dc..5ed4324 100644 --- a/PyFlow/flow_setup.py +++ b/PyFlow/flow_setup.py @@ -78,6 +78,7 @@ "file_transfer_chunk_len": 65536, "is_debug": False, "is_print_log": True, + "is_forward_one_to_one": False, } diff --git a/PyFlow/network_api/connect_tcp.py b/PyFlow/network_api/connect_tcp.py index acadf29..212165b 100644 --- a/PyFlow/network_api/connect_tcp.py +++ b/PyFlow/network_api/connect_tcp.py @@ -812,6 +812,11 @@ def _discard_receive_requests(instance, control_socket): 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) + if hasattr(instance, "_forward_budget"): + # cancel_socket closed the owned data sockets. Readers waiting behind + # another route must recheck them even if no writer returns credit. + with instance._forward_budget.cond: + instance._forward_budget.cond.notify_all() instance._transfer_controls.discard_socket(control_socket) _discard_receive_requests(instance, control_socket) if hasattr(instance, "_relay_recoveries"): @@ -2754,6 +2759,41 @@ def _custom_handler_for(command, handlers): return handler +class _ForwardBudget: + """Plaintext bytes owed to downstream writers across one server's relays. + + The caller holds ``cond`` for publication, return and queue retirement; + taking an item out of a queue does not release its credit. + """ + + def __init__(self): + self.cond = threading.Condition() + self.used = 0 + self.peak = 0 + + def publish(self, pending, chunk, offset, limit, state): + """Publish the prefix that fits to one live queue; zero means wait.""" + space = max(1, int(limit)) - self.used + if space <= 0: + return 0 + part = chunk[offset:offset + space] + size = len(part) + self.used += size + state["buffered"] += size + self.peak = max(self.peak, self.used) + try: + pending.put_nowait(part) + except BaseException: + self.release(state, size) # ownership never passed to a writer + raise + return size + + def release(self, state, size): + self.used -= size + state["buffered"] -= size + self.cond.notify_all() + + class TCP_Server_Base: # TCP server class """TCP server: accept clients, dispatch commands, relay messages and files. @@ -2845,8 +2885,8 @@ def __init__( every connection. Defaults to True. is_custom_keys (list | None): ``[pub_key_path, pvt_key_path]`` pair used instead of the default key lookup; an invalid pair is ignored. - max_mem_buff (int): Buffering ceiling in MiB for the in-memory forward - pump; past it the uploader is told to pause. Defaults to 2048. + max_mem_buff (int): Shared budget in MiB for queued and in-flight + downstream bytes of all native relays. Defaults to 2048. recv_messages_chunk_len (int): Bytes read per receive on the control connection, covering commands and messages. Defaults to 4096. file_transfer_chunk_len (int): Chunk size in bytes streamed when @@ -2899,6 +2939,7 @@ def __init__( self._recv_speed_samples = collections.deque() self._upload_speed_total = 0 # bytes held in the sample windows self._recv_speed_total = 0 + self._forward_budget = _ForwardBudget() self._forward_relays = {} self._forward_relays_lock = threading.Lock() # One route per local upstream fid; downstream keys point to that fid. @@ -7681,8 +7722,8 @@ def _forward_pump( ): """Pump the uploader's byte stream to every target from memory. - Queue high/low-water marks bound buffered data, allowing a finite enqueue - overshoot. Control start cannot clear the reader's high-water gate. + Each downstream copy, including its header, owns server-wide credit + until the writer returns from send_message or discards that copy. Args: up_sock (object): Value used by the operation. @@ -7697,43 +7738,39 @@ def _forward_pump( int: Targets that acknowledged the whole item (they are the ones the relay's resume record can be dropped for). """ - max_bytes = max(1, self.max_mem_buff) - low_water = max(1, max_bytes // 2) - cond = relay["cond"] + budget = self._forward_budget + cond = budget.cond controls = relay["controls"] state = relay["buffer"] = { "buffered": 0, "backpressured": False, "complete": False, "failed": False, - "high_water": max_bytes, "peak": 0, "max_enqueue": 0, } - queues = {(target, tfid): queue.Queue() for tfid, target, _ in target_conns} + queues = {sock: queue.Queue() for _, _, sock in target_conns} END = object() result: dict = {"ok": 0, "ack": None} - def release_buffered(byte_count): - """Called under cond; failed writers also release upstream backpressure.""" - state["buffered"] -= byte_count - if state["backpressured"] and state["buffered"] <= low_water: - state["backpressured"] = False - cond.notify_all() - def enqueue(chunk): - with cond: - 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["backpressured"] and state["buffered"] > max_bytes: - state["backpressured"] = True + # Never reserve while reading the uploader. Split by both target + # and available bytes; even a one-byte budget admits a fan-out. + for _, _, sock in target_conns: + offset = 0 + with cond: + while offset < len(chunk): + if self._stopped or up_sock.fileno() < 0: + raise ConnectionError("uploader control session closed") + if sock not in queues or sock.fileno() < 0: + break + count = budget.publish(queues[sock], chunk, offset, self.max_mem_buff, state) + if count: + offset += count + else: + state["backpressured"] = True + try: + cond.wait() + finally: + state["backpressured"] = False def writer(tfid, target, sock): - key = (target, tfid) - pending = queues[key] + pending = queues[sock] try: while True: item = pending.get() @@ -7744,7 +7781,7 @@ def writer(tfid, target, sock): return finally: with cond: - release_buffered(len(item)) + budget.release(state, len(item)) if state["complete"]: ack = self._forward_read_sign(sock, self.server_received_file_data_sign) if ack is not None and self._complete_fid_target( @@ -7756,13 +7793,18 @@ def writer(tfid, target, sock): except Exception as exc: self._log(f"forward: target {target} interrupted: {exc}") finally: - self._transfer_controls.release_owner(sock) + # Detach before draining: a woken reader cannot publish here + # again, and no other consumer can take the discarded items. with cond: - queues.pop(key, None) - while not pending.empty(): - item = pending.get_nowait() - if item is not END: - release_buffered(len(item)) + del queues[sock] + discarded = 0 + while not pending.empty(): + item = pending.get_nowait() + if item is not END: + discarded += len(item) + with cond: + budget.release(state, discarded) + self._transfer_controls.release_owner(sock) self._crypto_drop_channel(sock) sock.close() @@ -7781,11 +7823,6 @@ def reader(): enqueue(chunk) remaining = file_size - resume_offset while remaining > 0: - with cond: - while state["backpressured"]: - if up_sock.fileno() < 0: - raise ConnectionError("uploader control session closed") - cond.wait(timeout=0.5) chunk = self._forward_recv_exact( up_sock, min(self.file_transfer_chunk_len, remaining) ) @@ -7795,24 +7832,26 @@ def reader(): except Exception as exc: self._log(f"forward: uploader stream interrupted: {exc}") 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() + state["failed"] = not state["complete"] + if state["failed"]: + for control in controls.values(): + self._transfer_controls.release(control) threads = [ threading.Thread(target=writer, args=(tfid, target, sock), daemon=True) for tfid, target, sock in target_conns ] - for t in threads: - t.start() - reader() - for t in threads: - t.join() + try: + for t in threads: + t.start() + reader() + finally: + with cond: + for pending in queues.values(): + pending.put_nowait(END) + for t in threads: + if t.ident is not None: + t.join() route = relay["route"] with self._forward_relays_lock: complete = ( @@ -8184,6 +8223,7 @@ def __init__( is_enable_file_transfer_progress_bar=True, is_enable_real_time_network_speed=True, is_auto_reconnect=False, + is_forward_one_to_one=False, ): """Create the client and, unless extended, connect and start reading. @@ -8243,6 +8283,9 @@ def __init__( the connection are persisted to the protocol's ``.Flow`` directory and read back on the next connect. Defaults to False: a dropped connection ends the client. + is_forward_one_to_one (bool): Send each native file/target pair as + an independent transfer using a shared file slot. False (the + default) keeps one upload per item for all its targets. Raises: ValueError: If ``is_wait_server`` is True and ``timeout`` is not None. @@ -8325,6 +8368,7 @@ def __init__( self.is_input_command_in_console = is_input_command_in_console self.is_wait_server = is_wait_server self.is_auto_reconnect = is_auto_reconnect + self.is_forward_one_to_one = is_forward_one_to_one if self.is_wait_server and self.timeout != None: error_msg = [ "wait_server_timeout is not applicable when is_wait_server is True,", @@ -9036,8 +9080,8 @@ def _file_progress_start(self, progress_dict, fid, total_bytes, path, peer=None, if fid is None or not self.is_enable_file_transfer_progress_bar: return None entry = [initial, total_bytes, None, path, _peer_from_json(peer) if peer else None] - progress_dict[fid] = entry with self._transfer_progress_lock: + progress_dict[fid] = entry self._active_transfer_fids.add(fid) return entry @@ -9074,13 +9118,11 @@ def _file_progress_finish(self, progress_dict, fid, entry, keep=False): # a leg of an earlier session may finish after a newer leg # took the fid over: only the owner releases it self._active_transfer_fids.discard(fid) - if keep: - entry[2] = None # a stopped transfer has no live speed any more - self._persist_transfer_progress() - return - if progress_dict.get(fid) is entry: - del progress_dict[fid] - if os.path.exists(self.file_trans_progress_file): + if not keep: + del progress_dict[fid] + if keep: + entry[2] = None # a stopped transfer has no live speed any more + if keep or os.path.exists(self.file_trans_progress_file): # the persisted stores are only kept up to date while they exist: # a transfer that ended must not be resumed on a later reconnect self._persist_transfer_progress() @@ -11444,10 +11486,19 @@ def _resume_on_socket(self, peer_addr, fid, offset, control_socket, *, forward_r 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, control_socket=control_socket, - ) + # The existing resume worker already coalesced the request + # and drained its old owner. Only the actual replay takes a slot. + limited = self.is_forward_one_to_one + if limited and not self._acquire_forward_slot(control_socket): + return + try: + self._forward_one( + "file", "", os.path.basename(str(entry[3])), entry[3], [target], + resume_offset=offset, upstream_fid=fid, control_socket=control_socket, + ) + finally: + if limited: + self.file_semaphore.release() return if entry[4] is None or tuple(entry[4]) != server_peer: return @@ -11534,22 +11585,7 @@ def forward_file_console(self, message): message (str): ``/forward_file`` command with file paths, target address tuples, and an optional destination directory. """ - parts = shlex.split(message) - items, addrs, destination_path = self._forward_parse_command(parts[1:]) - files = [p for p in items if os.path.isfile(p)] - for p in items: - if not os.path.isfile(p): - self._log(f"forward: {p} is not a valid file, skipped") - if not files: - return - if not addrs: - self._log("forward: no target clients given") - return - threading.Thread( - target=self._forward_driver, - args=(files, addrs, False, destination_path), - daemon=True, - ).start() + self._forward_console(message, folder_mode=False) def forward_folder_console(self, message): """Parse a client command and forward its folders. @@ -11558,54 +11594,100 @@ def forward_folder_console(self, message): message (str): ``/forward_folder`` command with folder paths, target address tuples, and an optional destination directory. """ - parts = shlex.split(message) - items, addrs, destination_path = self._forward_parse_command(parts[1:]) - folders = [p for p in items if os.path.isdir(p)] - for p in items: - if not os.path.isdir(p): - self._log(f"forward: {p} is not a valid folder, skipped") - if not folders: + self._forward_console(message, folder_mode=True) + + def _forward_console(self, message, *, folder_mode): + # Capture at submission, not when the background driver gets to run. + control_socket = None + if self.is_forward_one_to_one: + control_socket = self.client_socket + if not self._forward_session_live(control_socket): + self._log("forward: cancelled; no active control session") + return + items, addrs, destination = self._forward_parse_command(shlex.split(message)[1:]) + valid = [] + accepts = os.path.isdir if folder_mode else os.path.isfile + cwd = os.getcwd() if control_socket is not None else None + for path in items: + if accepts(path): + valid.append(os.path.join(cwd, path) if cwd is not None else path) + else: + self._log(f"forward: {path} is not a valid {'folder' if folder_mode else 'file'}, skipped") + if not valid: return if not addrs: self._log("forward: no target clients given") return - threading.Thread( - target=self._forward_driver, - args=(folders, addrs, True, destination_path), - daemon=True, - ).start() + threading.Thread(target=self._forward_driver, daemon=True, + args=(valid, addrs, folder_mode, destination, control_socket)).start() - def _forward_driver(self, items, addrs, folder_mode, destination_path=None): - """Handle the operation. + def _forward_entries(self, paths, folder_mode): + for path in paths: + if not folder_mode: + yield "file", "", os.path.basename(path), path + continue + base = os.path.dirname(path) + for root, _, files in os.walk(path): + rel_dir = self._forward_rel_path(base, root) + for name in files: + yield "folder", rel_dir, name, os.path.join(root, name) + + def _forward_session_live(self, sock): + return (self.running and sock is not None and self.client_socket is sock + and sock.fileno() >= 0 and not self._transfer_handshakes.closed(sock)) + + def _acquire_forward_slot(self, sock): + # Ordinary sends use the same semaphore. Recheck the captured session + # even if all of its slots are occupied indefinitely (e.g. user pause). + while self._forward_session_live(sock): + if self.file_semaphore.acquire(timeout=0.2): + if self._forward_session_live(sock): + return True + self.file_semaphore.release() + break + self._log("forward: cancelled pending sends; original control session ended") + return False - Args: - items (list | dict): Value used by the operation. - addrs (list | dict): Value used by the operation. - folder_mode (bool): Value used by the operation. - destination_path (str): Value used by the operation. - """ + def _forward_driver(self, items, addrs, folder_mode, destination, control_socket): try: - if not folder_mode: - for path in items: - self._forward_one( - "file", "", os.path.basename(path), path, addrs, destination_path - ) - else: - for folder in items: - base_path = os.path.dirname(folder) - for root, _dirs, files in os.walk(folder): - rel_dir = self._forward_rel_path(base_path, root) - for file in files: - self._forward_one( - "folder", - rel_dir, - file, - os.path.join(root, file), - addrs, - destination_path, - ) - except Exception as e: - self._log(f"forward error: {e}") + if control_socket is None: # Legacy: one shared upload per entry. + for entry in self._forward_entries(items, folder_mode): + self._forward_one(*entry, addrs, destination) + return + + targets = tuple(dict.fromkeys(self._forward_targets(addrs, control_socket))) + if not targets: + return + + def send(entry, target): + try: + self._forward_one(*entry, [target], destination, control_socket=control_socket) + except Exception as exc: + self._log(f"forward: {entry[3]} to {target} failed: {exc}") + finally: + self.file_semaphore.release() + + # One destination set for this command: detect collisions before + # multiplying entries by targets. Keep no task list or waiting workers. + seen = set() + for entry in self._forward_entries(items, folder_mode): + _, rel_dir, name, path = entry + directory = _receive_dir_for("", rel_dir, destination) + landing = os.path.normpath(os.path.join(directory, name.strip())) + if landing in seen: + self._log(f"forward: skipped {path}: duplicate destination {landing}") + continue + seen.add(landing) + for target in targets: + if not self._acquire_forward_slot(control_socket): + return + try: + threading.Thread(target=send, args=(entry, target), daemon=True).start() + except Exception as exc: + self.file_semaphore.release() # Ownership never passed to send. + self._log(f"forward: could not start {path} to {target}: {exc}") + except Exception as exc: + self._log(f"forward error: {exc}") self._log_exc() def _forward_rel_path(self, base_path, abs_path): @@ -11628,6 +11710,26 @@ def _forward_rel_path(self, base_path, abs_path): return "" return "/" + rel.replace(os.sep, "/") + def _forward_targets(self, addrs, control_socket): + """Normalize targets and exclude only this actual/configured sender.""" + local_endpoint = _socket_local_endpoint(control_socket) or (self.client_host, self.client_port) + configured_endpoint = (self.client_host, local_endpoint[1]) + for address in addrs: + target = _peer_from_json(address) + if target is None: + self._log(f"forward: invalid target {address!r}, skipped") + continue + 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: + yield target + def _forward_one( self, kind, @@ -11646,45 +11748,39 @@ def _forward_one( self._log(f"forward: {abspath} is not a valid file, skipped") return False server_peer = (self.host, self.port) + pinned = control_socket is not None if control_socket is None: control_socket = self.client_socket + elif not self._forward_session_live(control_socket): + self._log(f"forward: cancelled {fname}; original control session ended") + return False is_resume = upstream_fid is not None - 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) + targets = list(self._forward_targets(addrs, control_socket)) 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: - return False - else: + if is_resume and len(targets) != 1: + return False + if not is_resume: upstream_fid = self._fid_alloc.alloc(receiver=server_peer) - key = (server_peer, upstream_fid) - if self.is_enable_file_transfer_progress_bar: - self.file_upload_progress[key] = [ - 0, os.path.getsize(abspath), None, str(abspath), - targets[0], - ] - self._persist_transfer_progress() + key = (server_peer, upstream_fid) 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_progress_lock: + entry = self.file_upload_progress.get(key) + if entry is None: # Another replay completed while waiting for a slot. + return False + stream["task_key"], stream["task_entry"] = key, entry + elif self.is_enable_file_transfer_progress_bar: + entry = [0, os.path.getsize(abspath), None, str(abspath), targets[0]] + with self._transfer_progress_lock: + self.file_upload_progress[key] = entry + self._persist_transfer_progress() # An admitted owner survives an uncertain request. with self._transfer_handshakes.serialized(control_socket, upstream_fid), \ _transfer_handshake(self, control_socket, upstream_fid) as handshake: + if handshake is None or (pinned and not self._forward_session_live(control_socket)): + self._log(f"forward: cancelled {fname}; control handshake unavailable") + return False msg = f"/forward_item {kind} fid={int(upstream_fid)}" if is_resume: msg += f" resume={int(resume_offset)}" diff --git a/docs/plans/forward-one-to-one-plan.md b/docs/plans/forward-one-to-one-plan.md new file mode 100644 index 0000000..dc8a67b --- /dev/null +++ b/docs/plans/forward-one-to-one-plan.md @@ -0,0 +1,107 @@ +# connect_tcp 原生一对一转发 — 更改计划 + +状态:**A1–A3 已审计放行,A4 已完成计划内的本机总验收,待人工最终确认**。依据:[需求卡与 P1–P8](forward-one-to-one-requirements.md)、[文件转发词汇表](../../GLOSSARY.md)。[总体报告](forward-one-to-one-report.md#a4总体报告与最终验收)记录实际结果、存量风险及未覆盖项。 + +## 1. 决策与接口 + +- 在 `TCP_Client_Base.__init__` 的 `is_auto_reconnect` **之后**追加 `is_forward_one_to_one=False`,保留所有旧位置参数。只在原生文件/文件夹发送端选择首次转发的组织方式;接收端不需要启用它。`flow_setup` 只补 Client 的默认配置,原 `TCP_Client_Base(**config)` 透传入口不变,不新增 CLI 命令或 Web 开关。 +- `False`:一个文件条目一次上传,一条路由覆盖全部已接受目标,用户暂停、继续与最终确认仍以整个转发任务为单位。`True`:一个文件条目 × 一个目标是一个独立任务,复用现有单目标发送。多个文件不会与目标按位置配对,也没有“这一批文件全部完成才能发下一批”的屏障。 +- Server 不辨识配置,也无须识别哪些请求来自同一条用户命令。继续按每条 `/forward_item` 自带的目标集合创建路由。无新 wire 字段、握手、ACK、进度格式、父任务或模式迁移。同一文件发两份会产生两次独立上行读/传,**不是**在上行数据连接内复用一次文件内容。 +- **唯一跨模式的资源变化**:更新后的 Server 对所有原生转发共用一份严格的 `max_mem_buff` 字节预算。旧 Client 的两个同时运行的转发也会争这份额度。协议格式保持不等于旧 Server 会凭空获得总额保证:依赖该保证的部署应更新 Server。Client 上已有的同名参数不作中转服务的配置来源。 + +## 2. 现状、入口和拟改数据流 + +依据为当前 `PyFlow/network_api/connect_tcp.py`:Client 构造器 8164–8187、文件信号量 8340–8341、命令解析/driver 11511–11609、单条握手与发送 11631–11725;Server 目标筛选 7253–7307、去重/路由准入 7413–7463、pump 7679–7843。Web 的 `client_backend.py:454–468` 已调用同一原生入口。普通 `/multiple_file` 是每文件一个等待线程,取得信号量后才读当前 socket(11029–11075);**复用其名额,不复制其等待线程模型**。 + +```mermaid +flowchart TD + input["原生文件或文件夹命令"] --> parse["解析条目、目标和目的目录"] + parse --> mode{"is_forward_one_to_one"} + mode -->|False| shared["每个条目带全部目标:一条共享路由"] + mode -->|True| pairs["绑定原会话,按需枚举条目 × 唯一目标"] + pairs --> slot["取得 Client 文件名额:每对一条单目标路由"] + shared --> upstream["原端口与加密握手,上行数据连接"] + slot --> upstream + upstream --> budget["Server 统一计账,各下游分别发送"] + budget --> ack["所属路由全部真实确认后才收尾"] +``` + +### 2.1 发送端:先限流,再开连接 + +1. 不重拼或重新切割用户命令文本。在结构化参数层保留含空格路径、`kind`、`rel_dir`、文件名、目的目录;沿用当前目录遍历(不增加空目录交付)。新模式先按原有端点规则规范化地址、过滤自身、保持首次出现顺序去除重复目标。自身过滤复用 `_forward_one` 的规则,不造第二套 DNS/端口别名逻辑。目标是否在线仍由 Server 校验;单项拒绝或异常不结束其他项的枚举。 +2. 在一条命令内按目标和**请求能确定的目的路径**判冲突:普通文件用 destination 下的文件名,目录条目再计入相对目录。先列入调度的保留,后来的跳过并提示,早于 FID/握手;不能用源绝对路径或只用 basename 来判目录冲突。同一命令目标列表相同,可对条目落点先去冲突再与目标相乘,不需存储整个乘积。不改接收端既有的文件覆盖策略。 +3. 沿用后台 driver,按需产生下一项;在有界的发送准入处复用 `file_semaphore`,**取到名额才启动单目标发送**,不为全部组合创建线程、Future、端口或进度行。已获准任务不在循环内逐个 `join`。所有命令共享该实例现有名额,单目标也不绕过。等待时能感知原会话关闭;获准后、发请求前再校验实际 socket,显式传给 `_forward_one`。正常、异常、线程未能启动、取消均有唯一的名额归还者;不在持全局锁时等待名额、网络或最终 ACK。 +4. 暂停中的任务保留原数据连接和名额。`max_thread_num=1` 时没有空位的 C 自然要等;这不代表 C 收到了 B 的用户暂停。关闭/替换控制会话取消未发起项并提示,不用新连接继续旧队列;受 `max_thread_num` 限制的是发送名额,不是整个进程的线程总数。 +5. 新任务用 `_forward_one` 原有分配器分配新 upstream FID,跟踪开启时在握手前预绑定 `(server_peer, fid)` 和逻辑目标;Server 仍分配 child FID。同路径不同目标有独立键。响应照旧按实际控制 socket + FID 匹配;显式错误、结果未决、保留进度与最终 ACK 按现有规则处理。不因字节走到 EOF 就报成功,不增加重试或批量失败回滚。 +6. 恢复走 `_resume_on_socket` → 原单目标重放,以旧 FID、旧路由、实际 offset、接收端保留路径为准;**不经首次枚举、冲突跳过或新 FID 分配**。开启模式的 Client 让实际开始的转发重放也遵守同一份发送名额,只取一次;利用现有按 owner 合并/收尾机制,不阻塞控制 reader、不让忙于等待旧 owner 的请求占死名额。切换开关不得拆已存的一对多 route 或合并已存的单目标 route。跟踪关闭不新建持久行;已有记录和运行时控制仍遵守原契约。 + +### 2.2 Server:只共享额度,不共享文件 + +现在每次 `_forward_pump` 独立建立 `relay["buffer"]`,按 `len(chunk) × 活跃队列数` 记账,入队后才检查高水位;writer 的当前项在 `send_message` 返回后才还账,异常还要清空自己的队列。拆分后若不改此处,配置值不变但多个 pump 可以分别积压到该值。 + +- 在 **Server 实例**内维护唯一总账和等待/唤醒条件;每个 pump 保留自己的队列、目标和控制状态。对每份下游待交付字节,先预留额度再发布;已预留/已排队/已取出但 writer 发送尚未返回的同一份字节只计一次。正值配置下任何时刻都有 `0 <= 已计费总量 <= max_mem_buff`(以字节计);沿用现有 MiB 入参及最小有效字节约定,不预分配一大块内存。 +- 计费包含转发的元信息和正文;共享上行的同一分块按实际接收队列份数计费,即使各队列引用同一 bytes。分块大于额度时按可容纳的段发送;若一次扇出的份额比总预算还大,按目标分批预留/入队,不等待一个永远不可能满足的整组请求。每条下游看到的字节顺序和内容不变。零正文仍走正确的头和确认;没有下游的终态补确认不虚占队列额度。 +- 容量耗尽时让后台 reader 等,writer、控制 reader 和 asyncio loop 仍可继续。不得持预算锁做网络 I/O 或等待 route 锁;不要在等一个空闲/暂停上游送下一块时替它预占整份额度。writer 成功或失败归还当前项,清空未发队列、目标退出、发布失败或停服也须退还所属余额并唤醒等待者。等待期间若目标/会话退出,重新核对归属,不能入已销毁队列或重复归还。 +- 足够额度释放后其他任务可继续,不必等占用者的整文件完成。资源等待**不发送** `/pause_trans` 或 `/start_trans`,用户 start 不释放额度。此上限不是 RSS:读头/读块临时对象、线程、系统 socket、加密层等不在上述队列计费内;不承诺最低带宽、严格公平或运行中缩小配置的即时效果。 + +## 3. 文件范围 + +| 类型 | 路径 | 意图 | +|---|---|---| +| 修改生产代码 | `PyFlow/network_api/connect_tcp.py` | Client 构造、原生命令/driver、单目标发送/恢复准入和会话收尾;Server 实例预算、`_forward_pump` 与释放/唤醒。不复制 relay 协议状态机。 | +| 修改 Client 配置 | `PyFlow/flow_setup.py` | `CLIENT_DEFAULTS` 暴露同名布尔值;不改 `SERVER_DEFAULTS` 或用户已有 `setup.json`。 | +| 修改契约测试 | `test/unit/test_flow_setup.py`、`test/unit/network_api/test_TCP_client.py`、`test/unit/network_api/test_transfer_control.py` | Client 配置透传、输入/准入与预算边界;复用现有 fixture,新增断言针对可见行为。 | +| 修改真实网络测试 | `test/integration/network_api/test_tcp_file_transfer.py`、`test/integration/network_api/test_tcp_transfer_control.py`、`test/integration/network_api/test_tcp_transfer_resume.py` | 多目标/目录、全局预算、用户控制隔离、失败及重连;保留原共享路由回归。 | +| 修改使用说明 | `docs/source/File_Transfer/File_Transfer.rst`、`docs/source/Network_APIs/TCP_Client_APIs.rst`、`docs/source/Network_APIs/TCP_Server_APIs.rst`、`docs/source/Instance_Setup/Instance_Setup.rst` | 开关与例子、资源作用域、一对多/一对一的进度和收尾差异。 | +| 拟新增(实施时) | `docs/source/changes/forward-one-to-one.md`、`docs/plans/forward-one-to-one-report.md` | 对外变更说明;分阶段及总体验收的实际证据,未运行前不写通过报告。 | +| 本规划阶段 | `GLOSSARY.md`、`docs/plans/forward-one-to-one-requirements.md`、本计划 | 词汇、已选需求与待审方案。 | + +不删除文件,不修改消息转发、`PyFlow/forward_extension_tcp.py` 落盘扩展、Web UI、CI、依赖或覆盖率策略。不新增传输结果 API、持久化待发清单或自行分配端口的旁路。 + +## 4. 原子拆分与审查顺序 + +行数为预估改动行(含测试和相关说明),不是代码配额。各阶段须局部证据和人工审查;超出可审范围就退回改计划,不顺手扩项。 + +| 阶段 | 单一意图、涉及范围 | 路径与局部验证 | 预估行 | +|---|---|---|---:| +| A1 | 使所有原生 pump 共用严格字节预算:Server 与现有压力用例/资源说明一起迁移。先保证多路并行不会把预算乘大。 | P5、P4 的背压分支、P8;V1、S-pressure | 180–360 | +| A2 | 交付 Client 可选按条目×目标调度:开关/配置、结构化拆分、共享准入、等待项取消与原重放入口接入;附局部文件/目录、名额和会话测试、Client 说明。 | P1–P3、P6、P7 准入;V2、S-split、S-session | 220–420 | +| A3 | 固化真实交付/恢复隔离证据:同一源路径的两个独立 FID 与默认共享 route 对照,覆盖用户控制、单项失败、断点和最终确认。主要是现有集成测试与使用/变更说明,不另造生产状态机。 | P1、P3、P4、P6、P7;V3、S-split、S-session | 140–300 | +| A4 | 逐路径汇总与总验收:回归旧模式与非目标消费者,记录平台、未覆盖项和实际输出。 | P1–P8;V4 及四个运行场景 | 50–150(报告) | + +## 5. 可执行验收与证据 + +下列 V1–V4 已分阶段执行,实际命令与退出状态见[阶段报告](forward-one-to-one-report.md)。V4 为受影响范围合并回归,不是全仓测试或跨平台认证。 + +```bash +P=.venv/bin/python +U=test/unit/network_api +I=test/integration/network_api +# V1:真实慢 writer、跨 route 竞争、压力与用户意图相互独立 +$P -m pytest -q "$U/test_transfer_control.py" "$I/test_tcp_file_transfer.py::test_forward_flow_control_pauses_uploader" "$I/test_tcp_file_transfer.py::test_forward_shared_budget_across_routes" "$I/test_tcp_transfer_control.py::test_relay_pressure_preserves_user_intent_and_source_start_cannot_open_reader" +# V2:配置、输入、共享名额、目录与旧模式 +$P -m pytest -q test/unit/test_flow_setup.py "$U/test_TCP_client.py" "$I/test_tcp_file_transfer.py::test_forward_file_to_multiple_clients" "$I/test_tcp_file_transfer.py::test_forward_one_to_one_item_target_admission" "$I/test_tcp_file_transfer.py::test_forward_one_to_one_folder_destinations" +# V3:真实暂停、乱序握手、单路恢复及旧路由的全目标 ACK +$P -m pytest -q "$I/test_tcp_transfer_control.py::test_forward_one_to_one_pause_isolation" "$I/test_tcp_transfer_resume.py::test_forward_one_to_one_session_recovery" "$I/test_tcp_transfer_resume.py::test_concurrent_forward_upload_handshakes_match_out_of_order_replies" "$I/test_tcp_transfer_resume.py::test_forward_route_is_removed_only_after_all_real_targets_complete" +# V4:最终一次受影响范围合并回归;不改既有 CI 或测试阈值 +$P -m pytest -q test/unit/test_flow_setup.py "$U" test/unit/transfer_web/test_web_transfers.py test/unit/transfer_web/test_file_location.py "$I/test_tcp_file_transfer.py" "$I/test_tcp_transfer_control.py" "$I/test_tcp_transfer_resume.py" "$I/test_crypto_tcp.py" "$I/test_tcp_async_server.py" "$I/test_tcp_broadcast_alloc.py" test/integration/test_forward_extension.py test/integration/test_forward_msg_attribution.py +``` + +规划时的两处压力测试**要求旧行为越界**:`test_tcp_file_transfer.py:773–804` 用“写出块大于上限”阻塞并断言超水位;`test_tcp_transfer_control.py:679–711` 也要求 `peak > high_water`(均为规划时行号)。A1 已将阻塞点改成指定下游 writer 实际尚未完成的发送;保留“确实等额度、控制状态不变、释放后继续、真实内容、ACK、资源归零”证据,并把界限加强为**全实例采样峰值不越界**。 + +实施时用隔离临时目录和本机真实 TCP 实例编写一次性 `/tmp/pyflow-forward-one-to-one-smoke.py`;命令 ` .venv/bin/python /tmp/pyflow-forward-one-to-one-smoke.py --case `(case 取下表名称)。脚本不用 pytest 用例作入口,不 mock 掉握手、加密、文件、端口、数据或 ACK。可用同步闸门稳定安排慢写/乱序并记录计数;超时只用于判失败。实施报告记录实际命令、退出码和所跑环境,再清理临时脚本。 + +| case | 路径/关键断言 | +|---|---| +| `baseline`(S-baseline) | P1/P2/P8:缺省/False 一次上行、两条下游、B 用户暂停时 C 同属该任务、最终等两个真实 ACK。单目标、Web 原入口、嵌套 destination、重复/自身/同 IP 不同端口和不可达目标,逐一核对请求、内容和清理。普通、消息、扩展由 V4 对应真实调用回归。 | +| `split`(S-split) | P2/P3/P4/P7:x、y 发 B、C,同一个 x 对应不同 upstream FID 和数据 socket;B 确认暂停 x **期间**,C 的 x 和有空位的 y→B 能完成并单独收尾。C 的控制不解除 B 的暂停;B 沿原 socket 继续,最终内容逐字节相符。覆盖同名不同目录、路径冲突跳过、多条命令与普通批量共用名额。 | +| `pressure`(S-pressure) | P4/P5/P8:不同源、不同文件、共享和单目标路由同服,预算小于分块及单次扇出需要的量。扣住 writer 让总账确实满,采样预留/归还和峰值;释放、writer 失败、源断线、停服分别证明不会死等/漏还。显式 start 不能开预算闸,自动排空也不替用户 start。 | +| `session`(S-session) | P3/P6/P7/P8:阻住端口应答或 ACK,单项拒绝/断线不影响其他 FID;旧会话的待发项无 FID/持久行/新 socket,新会话仅按原记录恢复。比对 `(server_peer,fid)`、child、原路径、数值 offset、五字段快照读回、零文件与 EOF 补确认;不同流收尾不互删。 | + +矩阵取真实明文/加密、线程/async Server、跟踪开/关、自动/手动端口和原端点重连(含已支持的别名/通配绑定)。保留可核对的控制/数据连接数量、FID→目标、发送名额峰值、计费峰值、暂停期间谁完成、内容一致性、真实 ACK 和最后剩余 owner/端口/队列;不记录密钥或正文。不以文件出现、进度等于大小、RSS 或历史测试数代替以上任一结论。没有实际跑过的平台/组合注明未覆盖,不推断 Windows 等同 Linux。 + +## 6. 本轮界限和下一闸门 + +风险集中在:锁顺序与配额归还、同路径不同 FID 的并发快照、突然关闭/重连时的所有权。优先复用 `_transfer_handshakes`、进度锁/原子写入、`palloc/pfree` 和现有加密读写;核对注册/删除与快照的一致性,不借此重构整套 TCP。源文件发送途中被修改、跨进程写同一进度文件、不同命令/不同发送者在接收盘上写到同一实际路径、NAT 或端点变更、同 FID 旧控制消息的代次隔离,均不作新增保证。 + +实施闸门:A4 的 V4 及四个独立场景已完成,结果只覆盖报告列明的环境与路径。是否接受未覆盖项、存量风险及是否合并/推送,仍由需求方最终确认;不自动提交、合并或推送。 diff --git a/docs/plans/forward-one-to-one-report.md b/docs/plans/forward-one-to-one-report.md new file mode 100644 index 0000000..b11598e --- /dev/null +++ b/docs/plans/forward-one-to-one-report.md @@ -0,0 +1,223 @@ +# 原生 TCP 文件转发 — 分阶段实施报告 + +**状态:A1–A3 已审计放行;A4 已完成计划内的 Linux 总验收,待人工最终确认。** [A4 总体报告与实测证据](#a4总体报告与最终验收) · [更改计划](forward-one-to-one-plan.md) · [需求卡](forward-one-to-one-requirements.md) + +## A1:Server 共享字节预算 + +让同一 Server 上所有原生转发(首次或恢复,单目标或多目标)共用一个严格的待下发字节上限。改变的是既有 `max_mem_buff` 的作用域,不是转发任务的身份、协议或用户暂停状态。 + +| 文件 | 本阶段改动 | +|---|---| +| `PyFlow/network_api/connect_tcp.py` | 在 Server 实例上创建 `_ForwardBudget`;`_forward_pump` 改为先计费再发布、逐下游归还。实际控制会话退役关闭所属数据 socket 后唤醒等待额度的 reader。 | +| `test/unit/network_api/test_transfer_control.py` | 用已满队列触发发布失败:只退本次预留,不退其他发送持有的字节;空出的额度可再用。 | +| `test/integration/network_api/test_tcp_file_transfer.py`、`test/integration/network_api/test_tcp_transfer_control.py` | 将两处要求越过水位的压力断言改为实际扣住 writer、证明 reader 等待且总账不越界;增加跨源、跨路由测试,保留控制状态、真实内容、ACK 和清理断言。 | +| `docs/source/File_Transfer/File_Transfer.rst`、`docs/source/Network_APIs/TCP_Server_APIs.rst`、`docs/source/changes/forward-one-to-one.md` | 说明按下游份数计费、适用的 Server 版本和非 RSS 边界。计划中更新了授权闸门。 | + +**数据流(P5、P4 的资源分支):** reader 从原上传连接读文件头和正文,不预占下一次读取的额度。对于每个下游,只在总账有空间时发布容得下的字节;一块或一次扇出的总量大于上限也可分段推进。writer 出队不退账,沿原 `send_message` 发送,返回或抛错才归还当前项。失败的 writer 先在预算锁下摘除自己的队列,再在锁外排空并归还剩余字节。没有下游的 EOF 补确认仍校验头,但不入队、不争额度。 + +队列成员检查、预留与发布受同一个 Condition 保护;每次被唤醒都重新核对 socket 和队列。预算锁不跨网络读写、用户控制或路由锁。用户 start 不能制造额度,退还额度也不发 start。任务仍须得到所属目标的真实确认;活跃 pump 清理与失败路由保留用于恢复是两件事。 + +## 局部验证与实际证据 + +环境:Linux x86-64,CPython 3.10.20,pytest 9.1.1,本机 IPv4 TCP。 + +**先红后绿。** 旧实现执行 `.venv/bin/python -m pytest -q test/integration/network_api/test_tcp_file_transfer.py::test_forward_flow_control_pauses_uploader`,退出 1:限制 **32,768 B**,一个真实 writer 尚未返回时已计费 **65,555 B**。实施后执行计划 V1: + +```bash +P=.venv/bin/python; U=test/unit/network_api; I=test/integration/network_api +"$P" -m pytest -q "$U/test_transfer_control.py" "$I/test_tcp_file_transfer.py::test_forward_flow_control_pauses_uploader" "$I/test_tcp_file_transfer.py::test_forward_shared_budget_across_routes" "$I/test_tcp_transfer_control.py::test_relay_pressure_preserves_user_intent_and_source_start_cannot_open_reader" +``` + +退出 **0:145 passed in 64.08s**。32 KiB 用例保留了 300 KiB 正文;跨路由用例还将额度压到 1 B:双目标路由的 writer 持有这一字节时,另一源的单目标路由连头都不能发布。释放 writer、仍扣住第一源的正文时,另一源收到最终 ACK;第一条路由随后向两个真实目标完成交付。 + +**独立 S-pressure。** 执行 `.venv/bin/python /tmp/pyflow-forward-one-to-one-smoke.py --case pressure`,退出 **0**。每组使用两个不同来源、两个文件、一个单目标和一个双目标路由;5 条控制连接,2 条上行、3 条下行数据连接。在真实 `send_message` 边界保持 writer 未完成,不替换握手、加密、文件、端口、数据或 ACK。表中峰值为运行时采样和预留总账峰值,两者相等;正文仅做逐字节比较,不写入日志。 + +| 路径(Server / 通道 / 端口) | 上限 / 峰值 B | 两条 reader 进入额度等待的次数 | 两源获最终 ACK | 真实目标 ACK 数 | 核对成功正文 B | +|---|---:|---:|---|---:|---:| +| 放开 writer(线程 / 明文 / 系统) | 1 / 1 | 342、653 | 是、是 | 3 | 805 | +| 目标断线、实际下游写失败(asyncio / 加密 / 系统) | 512 / 512 | 3、1199 | 否、是 | 2 | 614460 | +| 等额度的源控制会话断开(线程 / 明文 / 手动) | 256 / 256 | 1144、1 | 是、否 | 1 | 307203 | +| 两条路由受压时停服(asyncio / 明文 / 系统) | 128 / 128 | 1、1 | 否、否 | 0 | 0 | + +- 放开组发送的计费数据为 **856 B = 805 B 正文 + 51 B 文件头**。满额时显式 start 后 reader 再次进入等待,读取数不变;排空后被用户暂停的源仍未发下一块,另一源已完成。其他三组没有自动 pause/start。 +- 源断线组:占满 256 B 的另一 writer 尚未放行,等待中的源已失败并退出 pump。停服组两个源都没有假成功。四组结束时总账、各 pump 余额、活跃 relay、额外分配端口均为 **0**,临时 socket/握手及传输 owner 登记已清理。失败任务不要求删除恢复路由。 +- 脚本首次退出 1,未进入计费路径:测试把目标控制连接绑到另一个回环 IP,而文件 listener 未监听该 IP,真实连接返回 `Connection refused`。仅将测试拓扑改为同一回环地址、不同端口后执行上述四组,未绕过连接或改生产监听逻辑。 + +**P5 恢复补证。** `.venv/bin/python /tmp/pyflow-forward-one-to-one-smoke.py --case pressure --recovery-only`,退出 **0**。先真实断开下游数据 socket,97 B 文件仅落盘 11 B;随后从实际 offset 11、原 upstream FID `8171444276` 和 child `6337585112` 重放。另一来源持有全部 1 B 时,该恢复连文件头都在等额度。另一空文件的目标此前已真实 ACK、源漏收最终 ACK;其原 FID `12466411572` 在同一满额期间以 **0 下游、0 新计费**完成补确认。释放 writer 后两个剩余文件内容均一致,峰值 1 B,最后余额及活跃 relay 均为 0。一次性脚本不入库。 + +## 未覆盖与风险 + +- P5 和 P4 背压分支有上述证据;P8 只覆盖表中的配置及本机端口/临时资源。未运行 Windows、macOS、自由线程 Python 或所有配置的笛卡尔积,不把这些结果外推到其他平台。 +- A1 不实现 Client 拆分、发送名额、排队项取消或一对一任务控制隔离;未执行 V2–V4 或全项目回归,未改 CI、依赖、配置格式、普通直传、消息、Web 或落盘扩展。 +- 严格上限针对队列和 writer 手中的待交付字节,不覆盖 reader 当前块、加密临时对象或 OS 缓冲。没有带宽公平保证。部署依赖总额保护须更新 Server;只更新 Client 无效。A1 后续审查结论:已放行,已授权 A2。 + +## A2:发送端按文件条目与目标调度 + +**意图:** 新增可选 `TCP_Client_Base(..., is_forward_one_to_one=False)`。缺省仍是一个条目一份上行、全部目标共享;开启后每个条目与每个唯一目标独立上传、独立收最终 ACK。参数追加在 `is_auto_reconnect` 后。不增加父任务、不改 Server、线上命令或五字段进度格式。 + +| 文件 | 改动与审查点 | +|---|---| +| `PyFlow/network_api/connect_tcp.py` | Client 原生文件、目录入口共用结构化解析和遍历。开启时提交即捕获控制 socket,去重目标、排除自身,按目的目录/相对目录/文件名保留第一个落点;每个 driver 先取实例 `file_semaphore`,才启动一个 `_forward_one`。归还由启动失败的 driver 或已启动的 worker 负责,不提前分配等待项的 FID、记录或数据端口。 | +| 同上,Client 恢复与进度 | `_resume_on_socket` 仍交给原 owner 合并机制;旧 owner 排空后才在后台取同一份名额,使用旧 FID 和指定 offset 重放一次,不经过首次枚举。首次五字段行在握手发送前登记;登记和按 owner 删除与快照使用同一把进度锁。持锁时不等名额、网络或 ACK。 | +| `PyFlow/flow_setup.py`、`test/unit/test_flow_setup.py`、`test/unit/network_api/test_TCP_client.py` | 只补 `CLIENT_DEFAULTS`,测试缺省及显式开启的配置落盘、读回和构造器透传;实际 socket 替换发生在 driver 开始前或等名额时,均不得分 FID、建快照或发命令。没有修改用户 `setup.json`。 | +| `test/integration/network_api/test_tcp_file_transfer.py` | 两个 V2 节点:扣住真实目标 ACK 检验有界并行;用带空格的目录、重复/自身/拒绝目标、冲突落点和不同相对目录核对 wire、内容及最终行。拒绝目标保留原协议要求的进度,不误删兄弟任务。 | +| 文档 | `docs/source/Network_APIs/TCP_Client_APIs.rst`、`docs/source/Instance_Setup/Instance_Setup.rst`、`docs/source/File_Transfer/File_Transfer.rst`、`docs/source/changes/forward-one-to-one.md`、本计划及报告。 | + +### 局部验证 + +Linux x86-64,CPython 3.10.20,pytest 9.1.1。配置用例在改动前运行 `.venv/bin/python -m pytest -q test/unit/test_flow_setup.py::test_one_to_one_round_trips_only_in_client_config`,退出 1:旧的缺省配置读回无 `is_forward_one_to_one` 键。实施后执行: + +```bash +P=.venv/bin/python; U=test/unit/network_api; I=test/integration/network_api +"$P" -m pytest -q test/unit/test_flow_setup.py "$U/test_TCP_client.py" "$I/test_tcp_file_transfer.py::test_forward_file_to_multiple_clients" "$I/test_tcp_file_transfer.py::test_forward_one_to_one_item_target_admission" "$I/test_tcp_file_transfer.py::test_forward_one_to_one_folder_destinations" +"$P" /tmp/pyflow-forward-one-to-one-smoke.py --case split +"$P" /tmp/pyflow-forward-one-to-one-smoke.py --case session +"$P" -B /tmp/pyflow-a2-history.py +``` + +最终四条命令均退出 **0**,V2 **101 passed in 9.10s**。三个临时验证脚本(含 session 子脚本)只用本机隔离目录与真实 TCP;同步闸门安排时序,不替代握手、文件、加密、端口应答或最终 ACK。运行结束后删除,不入库。 + +| 路径 | 实际观察 | +|---|---| +| P1–P3,首次准入 | V2 扣住三个目标 ACK 时仅 3 条上传记录、3 个 FID 和 3 次源端数据端口分配;释放一个 ACK 即准入第四对。四对最终 FID 不同、单目标路由独立,目标文件内容与预期相同。目标或落点重复不多分 FID;相同 basename 在不同子目录均交付。 | +| S-split,P3/P4 | 明文、asyncio Server,源配置 `localhost`。`x→B`、`x→C` 的 upstream FID 分别为 `6976803528`、`11271770824`,数据端口分别为 `42121`、`46501`。B 的 `x` 在 1,024 B 处确认暂停期间,`x→C`、`y→B`、`y→C` 都收到最终 ACK;C 自己暂停/继续也未解除 B 的暂停。B 沿原 socket 继续。另一次目录转发与普通 `/multiple_file` 共用同一名额,峰值 **3/3**。共 6 个转发子 ACK、8 个成功发送(含 2 个普通文件),最后 owner、额外端口均为 0。 | +| S-session,P3/P6/P7 | 明文、线程 Server、`localhost` + 通配绑定,1 个名额。真实控制断开并以原端点重连:未发起的文件无 FID、数据 socket 或五字段行,新会话未收到旧队列命令。在途任务接收端已落盘 **8,192 B**(源已发 **24,576 B**);源快照经独立实例读回。原 upstream `8354677942`、child `6833030408` 及原嵌套路径保留。恢复等普通发送的真实 ACK 让位;期间控制 reader 处理了重复请求,接受结果依次 `True`、`False`。真正重放只取一次名额,按落盘位置交付余下正文,内容一致。 | +| S-session,零正文与失败 | 空文件的目标已 ACK、源最终 ACK 写失败;原 FID `16944612534` 补确认,不再开下游。跟踪关闭时不可达目标收到拒绝,下一健康目标成功;显式 `close()` 取消排队项,未产生新数据连接或持久行。收尾后活跃 owner、路由、数据 socket 和占用名额均为 0。 | +| 开关切换与启动失败 | 加密、线程 Server、手动端口。在两个目标中令 B 的真实 ACK 写失败、C 成功。原共享 route 从 False 切到 True 重放时仍为原两目标 route;原独立 route 从 True 切到 False 时也未合并。两种情况下只重新握手 B,使用原 child、原 upstream FID,offset **8,201 B**,C 没有重新收件;检查了上/下行加密通道和端口归还。另让第一个 worker 的系统启动调用抛错:失败项无 FID,另一个目标得到真实最终 ACK,名额无泄漏。 | + +补验历史路由的脚本首次退出 1:同机隔离实例在加密握手阶段选到冲突的手动端口,文件 listener 的 `listen()` 返回 `EADDRINUSE`,未进入待验转发路径。给临时实例配置不同的既有 `port_add_step` 后通过;没有改端口分配器或用假端口绕过此错误。此结果不证明默认手动端口在同机没有冲突。 + +### 范围与下一闸门 + +- 同一请求可推导的目的路径冲突只在本次命令内跳过;不承诺远端文件系统别名或跨命令互斥。暂停任务仍占名额;`max_thread_num=1` 下等待不表示任务间共享暂停状态。 +- 未运行 V3、V4 或全量回归,未运行 Windows、macOS、自由线程 Python;未单独启动 Web UI、消息转发或落盘扩展。未改这些模块、CI、依赖或 A1 的 Server 预算。本轮的加密观测是转发数据通道,不是全协议抓包审计。 +- A2 后续审查结论:已放行,已授权 A3。A4 总验收未开始。 + +## A3:同一路径的独立交付、暂停与恢复 + +**意图:** 用真实控制连接、数据连接、文件和最终 ACK 固化区分两种模式的回归。只改集成测试、使用说明、变更记录和计划/报告;没有改生产代码、配置、依赖或 CI。 + +| 文件 | 要防止的回归 | +|---|---| +| `test/integration/network_api/test_tcp_transfer_control.py` | `test_forward_one_to_one_pause_isolation` 从原生控制台同时发 x、y 给 B、C。真实首块写出后暂停 x→B,放开测试闸门,等发送线程确实进入原生暂停等待。C 自行暂停再继续;必须在 B 仍停着时得到另外三对的源端成功结果,再让 B 沿原 socket 完成。 | +| `test/integration/network_api/test_tcp_transfer_resume.py` | `test_forward_one_to_one_session_recovery` 扣住 B 的 ACK,在 C 只写入前缀或已写完但尚未 ACK 时真实断开 C 的控制连接。B 成功收尾后,源快照和服务端 route/index 只能剩 C;C 原端点重连时检查 replay 的 FID、child、原嵌套路径、实际偏移及发送字节数。原共享路由的全目标 ACK 用例改从**缺省控制台命令**进入,同时保留此前的断言。 | +| 使用说明及变更记录 | `docs/source/File_Transfer/File_Transfer.rst`、`docs/source/changes/forward-one-to-one.md` 说明同源路径可有两行、如何区分,以及为何进度到 EOF 不等于交付成功。 | + +### V3 局部验证 + +```bash +P=.venv/bin/python; I=test/integration/network_api +"$P" -m pytest -q "$I/test_tcp_transfer_control.py::test_forward_one_to_one_pause_isolation" "$I/test_tcp_transfer_resume.py::test_forward_one_to_one_session_recovery" "$I/test_tcp_transfer_resume.py::test_concurrent_forward_upload_handshakes_match_out_of_order_replies" "$I/test_tcp_transfer_resume.py::test_forward_route_is_removed_only_after_all_real_targets_complete" +``` + +退出 **0:7 passed in 44.63s**,无跳过。7 项分别为暂停隔离的 3 种配置、单目标重连的 2 个中断点、已有的乱序握手和默认共享路由对照: + +- **P3/P4:** 明文线程(配置别名)、加密线程、加密 asyncio(关闭跟踪、通配绑定)均观察到 x→B 在真实暂停等待中,三个兄弟任务已由源端收到最终 ACK 并单独清理;B 继续后所有文件逐字节相符。关闭跟踪不生成上传行,控制仍可用。 +- **P6/P7:** 同一份 **32,785 B** 文件发往 B、C,源端实际有两个不同的 `(server_peer, fid)`。C 断线和 B 的真实 ACK 只留下 C 的五字段上传记录和原路由。两种情况下都从同一端点重连,只向 C 的原 child 重新发起请求,恢复沿用同一 upstream FID 和原嵌套路径。部分文件仅补剩余字节;文件已全但 C 尚未发 ACK 的分支只发头、不发正文,扣住重放 ACK 时路由和源记录都还在。核对接收内容、成功写入的头/正文长度、重复派发次数和源端最终结果。 +- **P1/P6 对照:** 默认控制台请求只建立一条上行和一条双目标 route。第二个目标的 ACK 没发出时,两个文件虽然均已写完,源端仍未成功;放行 ACK 后才收尾。已有乱序端口应答测试仍通过。 + +### 本轮独立场景(非 pytest 入口) + +Linux x86-64,CPython 3.10.20,隔离临时目录。本轮实际重新执行,两条命令最终均退出 **0**: + +```bash +.venv/bin/python /tmp/pyflow-forward-one-to-one-smoke.py --case split +.venv/bin/python /tmp/pyflow-forward-one-to-one-smoke.py --case session +``` + +- **S-split(P3/P4):** 明文、asyncio Server、配置别名;同一个 x 的 upstream FID/数据端口分别是 `8131132158:59997`(B)及 `12426099454:34509`(C)。x→B 在 1,024 B 确认暂停,另外三对完成,B 在原 socket 继续;连同另一条目录转发及普通批量发送,实测发送名额峰值 3/3,转发子 ACK 6、成功发送 8,最终活跃 owner 和额外端口均为 0。 +- **S-session(P6/P7):** 明文、线程 Server,原控制端点重连,等名额的首次发送未跨会话。原 upstream `8404201258`、child `7397563762` 在普通发送占用唯一名额时等待,重复恢复请求未多开流;源五字段快照独立读回,释放名额后从接收盘实际的 8,192 B 续传。空文件在目标已 ACK、最终 ACK 写失败之后补确认,未增加下游。关闭跟踪时拒绝目标/健康目标 FID 为 `7823031870` / `12117999166`;显式关闭后 owner、路由、数据 socket、占用名额均为 0。 +- 初次运行两条命令均退出 1:临时 smoke 入口少一个右括号,Python 在解析阶段报 `SyntaxError`,未建立连接。仅修正临时脚本后重跑,没有以先前阶段结果代替本轮验证。 + +### 范围与下一闸门 + +临时脚本已删除。A3 只验本机 Linux 的上述路径;未跑 Windows、macOS、自由线程 Python、手动端口矩阵、Web/消息/落盘扩展或全项目回归。加密配置参与功能验证,不替代抓包审计;A3 未修改加密或资源计账契约。后续审查结论:A3 已放行,已授权 A4。 + +## A4:总体报告与最终验收 + +### 验收前交付:基线、边界和逐路径清单 + +验收对象为已放行的 `521361e`(A1:Server 统一额度)、`3e4fa9d`(A2:Client 调度/配置)和 `d219be8`(A3:控制与恢复集成证据)。A4 本身只汇总报告,不调整生产代码、测试、超时、依赖、coverage 或 CI 策略。 + +原生文件/目录命令(含既有 Web 后端单目标入口)→ 结构化条目和目标 → 缺省每条目一次上行,或在 `is_forward_one_to_one=True` 时按唯一目标取得 Client 文件名额 → 原控制 socket/FID/端口和原数据通道 → 同一 Server 严格计费各下游副本 → 原路由的真实目标 ACK → 源端确认/按所属任务清理。只有发送端公开构造器和 Client 配置增加了末尾可选参数;Server 配置单位、wire、五字段进度和其他传输族保持原有接口。 + +| 需求路径 | 此前局部证据 / 本轮机械验收点(不是本轮结果) | +|---|---| +| P1 缺省、False、单目标 | A2/A3 已见缺省共享 ACK;baseline 直接对照缺省和 False 的上/下行数、子 ACK 和源 ACK。 | +| P2 输入、目标、目的路径 | A2 已验结构化拆分/落点;baseline 走真实 Web 后端、重复/自身/不可达及嵌套目录;split 复验一对一落点。 | +| P3 有界并行 | A2/A3 已见独立 FID 和名额;split、session 检查同时在途、等名额无行/端口,以及普通批量共享名额。 | +| P4 用户控制 | A1–A3 已见资源等待与用户意图独立;baseline/shared 与 split/independent 对照实际暂停等待、兄弟交付和原 socket 继续。 | +| P5 Server 额度 | A1 已见跨路由、含恢复计费;pressure 检查元信息/正文、在写份额、失败与停服的峰值、等待、归零。 | +| P6 错误与会话更替 | A2/A3 已验单项断线和乱序;V4 与 session 检查拒绝不串 FID、原会话取消和失去 owner 后的收尾。 | +| P7 交付与恢复 | A2/A3 已验原路径、原 upstream/child、零正文、切换开关;session 和 V4 对照实际磁盘 offset、五字段快照读回和真实最终确认。 | +| P8 环境与非目标消费者 | 历史部分覆盖;V4 合并运行普通直传、Web、消息、落盘扩展、线程/asyncio、加密和端口用例;四场景检查内容、临时资源、退出状态。 | + +本轮应执行[计划 §5](forward-one-to-one-plan.md#5-可执行验收与证据)的完整 V4(不改选择集)和 `--case baseline|split|pressure|session` 四个独立入口。保留失败/跳过、实测平台及路径边界。全实例队列限额不是 RSS,暂停不等于取消;不保证公平、源文件变更一致性、跨命令目的路径互斥或变更 NAT/端点的恢复。不将 Linux 结果当作其他 OS 通过;合并、提交、推送均需另行人工决定。 + +### 本轮执行记录 + +环境:Linux x86-64(内核 `7.0.0-43-generic`)、CPython 3.10.20、pytest 9.1.1。工作树起始干净。为避免测试改写使用者的 `.Flow`、密钥或进度文件,从 `git archive d219be8` 解出私有临时源码目录,复制当前 CPython 3.10 的本地 `_crypto_api` 和 CMake 共享库,使用同一 `.venv` 解释器;V4 的 HOME、TMPDIR 均隔离。运行前确认 `connect_tcp` 来自该目录、原生加密库确实可加载。未重建或升级依赖。 + +在临时源码根目录执行(`P` 为原工作树 `.venv/bin/python` 的绝对路径,`RUN` 为私有临时目录)。`-ra` 和 JUnit 只用于取证;选择集与 V4 一致,不加重试或失败豁免。 + +```bash +U=test/unit/network_api; I=test/integration/network_api +"$P" -m pytest -q -ra --show-capture=no --tb=short --junitxml="$RUN/v4.xml" \ + test/unit/test_flow_setup.py "$U" test/unit/transfer_web/test_web_transfers.py \ + test/unit/transfer_web/test_file_location.py "$I/test_tcp_file_transfer.py" \ + "$I/test_tcp_transfer_control.py" "$I/test_tcp_transfer_resume.py" "$I/test_crypto_tcp.py" \ + "$I/test_tcp_async_server.py" "$I/test_tcp_broadcast_alloc.py" \ + test/integration/test_forward_extension.py test/integration/test_forward_msg_attribution.py +``` + +**V4 退出 0:`847 passed, 1 skipped in 847.25s (0:14:07)`**。JUnit 848 项,0 失败、0 错误。唯一跳过:`test_receiver_pause_start_waits_for_real_rekey_without_blocking_key_reader[plain-alias]`,明文配置不适用 re-key;同一用例的 `encrypted`、`encrypted-async-untracked-wildcard` 两组均实际通过,不是缺少加密库。这是计划中的受影响范围合并回归,不是整个仓库的所有测试。 + +| V4 范围 | 通过 / 跳过 | +|---|---:| +| `test_flow_setup`、`unit/network_api` | 85 + 457 / 0 | +| Web `test_web_transfers`、`test_file_location` | 11 + 10 / 0 | +| `test_tcp_file_transfer`、`test_tcp_transfer_control`、`test_tcp_transfer_resume` | 37 + 95 + 81 / 1 | +| `test_crypto_tcp`、`test_tcp_async_server`、`test_tcp_broadcast_alloc` | 22 + 9 + 18 / 0 | +| `test_forward_extension`、`test_forward_msg_attribution` | 15 + 7 / 0 | + +**独立 TCP 场景**:分别执行 `"$P" /tmp/pyflow-forward-one-to-one-smoke.py --case baseline`、`--case split`、`--case pressure`、`--case session`,最终各退出 **0**。不调用 pytest 入口,不代答握手、端口或 ACK;同步闸门只安排真实 I/O 时序,断线通过关闭实际 socket 触发。 + +| 路径 | 本轮结论与可定位证据 | +|---|---| +| P1 覆盖 | `baseline`:缺省和显式 False 分别只产生一个 upstream FID `6396275316`、`6592669000`;每组 1 上行 / 2 下行。B/C 文件均已完整但扣住 C 的 ACK 时,完成集合只有 B,源未成功;放开后各组均为 2 个真实子 ACK、1 个最终 ACK。 | +| P2 覆盖 | 自身唯一目标未分 FID;混合自身、重复、未连接、Server、同 IP 不同端口和无效文件后只向 B、C 交付。真实回环 HTTP multipart `POST /api/send_file`(False)、`POST /api/send_folder`(True)及 `GET /api/transfers` 均返回 200;扣住 ACK 时 Web 读到对应 FID,收尾后核对嵌套目的路径、4,011 / 9,023 B 内容。HTTP 接单不作为交付成功;未测试浏览器交互。V4 另验目录冲突首项保留及不同相对目录。 | +| P3 覆盖 | `split`:x→B、x→C 的 upstream FID/数据端口分别为 `8577173170:52143`、`12872140466:34987`。普通批量、目录和另一条转发共用 3 个名额,使用峰值 **3/3**。V4 的第四对在等待时没有 FID、进度行或数据端口。 | +| P4 覆盖 | `baseline` 中 B 暂停后共享 route 的 6 个角色均确认,源确实进入暂停等待,C 可以继续该任务;`split` 中 x→B 在 1,024 B 确认暂停时另三对均有最终 ACK,B 在原 socket 继续。`pressure` 中显式 start 不能开满额闸门,释放额度未取消用户暂停。 | +| P5 覆盖 | 见下表。另执行 `"$P" -B /tmp/pyflow-a4-replay-budget.py`(退出 0):首次共享路由先由 E 确认、D 断线;切换发送端开关后 D 从落盘 **6 B**、原 FID `7388771744` / child `5088227418` 恢复。它与新的单目标及双目标路由**同时**有 3 条上行、4 条下行,在同一预算上等待,各 pump 占用 **0 / 8 / 0 B**,峰值 8/8 B;最终 5 份接收内容相符、3 个源端最终 ACK、余额 0,E 未重新收件。 | +| P6 覆盖 | V4 对乱序端口应答按实际 socket + FID 匹配。`session` 中等名额的旧命令未借新控制连接;跟踪关闭时拒绝 FID `4466522086`,健康 FID `8761489382` 正常完成。显式关闭时未发起项未建持久行、未开新数据连接。 | +| P7 覆盖 | 同一文件两份在途,V4 观察 B 的成功不清掉 C 的五字段行,部分文件与 EOF 未确认均按原 child/路径只重放 C。`session` 独立读回快照:原 upstream `5829132394`、child `8229536116` 恢复偏移 8,192 B,不用源已发送的 24,576 B;普通发送占用名额时回复重复请求不多占,完成后余额归零。空文件 FID `14419066986` 的目标已 ACK、源漏最终 ACK 时,仅补最终确认,不多开下游。 | +| P8 本机范围覆盖,跨平台未验 | V4 及四场景含线程/asyncio、明文/加密、跟踪开/关、系统/手动端口、别名及通配绑定。实际普通直传收到 1 个 ACK;消息由原发送者身份到达;落盘扩展真实上传一次、Server 从磁盘向两个目标推送各获 ACK,三者均未增原生 pump。原生转发时 Server 接收目录无文件。检查了内容、端口、owner、预算和线程;扩展通用线程池在 `stop()` 后的例外见下。 | + +**S-pressure 明细(字节)**:每行 2 个不同源、1 单目标和 1 双目标路由,5 个控制连接、5 个数据连接;实测 2 个 reader 均曾等额度。计费含队列及 writer 已取出但未返回的份额。峰值由预留时累计峰值和独立采样核对,所有组最终余额、等待者、活跃 relay、额外端口均为 0。 + +| 场景 | 限额 / 实测峰值 | 累计预留 / 归还 | 源最终 ACK(两源) | 真实子 ACK | +|---|---:|---:|---|---:| +| 用户暂停后排空 | 1 / 1 | 856 / 856 | 是 / 是 | 3 | +| 加密、asyncio、下游 writer 实际失败 | 512 / 512 | 615023 / 615023 | 否 / 是 | 2 | +| 手动端口、等额度的源断线 | 256 / 256 | 307220 / 307220 | 是 / 否 | 1 | +| asyncio、满额停服 | 128 / 128 | 145 / 145 | 否 / 否 | 0 | + +**加密与日志边界抽查(P6–P8):** `"$P" -B /tmp/pyflow-a4-wire.py` 退出 0。手动端口(沿用 A2 隔离实例的不同 `port_add_step`)、加密、两个并发单目标任务;扣住 C 的最终 ACK 并真实断开 C 的控制 socket,原端点重连,再以 EOF **36,867 B** 重放。首发两条 `/forward_item` 和一条恢复请求在控制通道实际写出 3 个完整帧。接收解码边界的首发/重放原始字节流中,三条上行分别解析出 **6、6、3** 个完整帧,对应下行也是 **6、6、3**;未观察到测试正文标记。原 FID/child、内容、ACK 和手动端口归还均核对。普通日志开启、debug 关闭时,在 stdout/stderr 及实际生成的 14 份收发消息/事件日志与进度快照中未检出测试正文标记或两种 PEM 私钥头。没有打印密钥、正文或密文。此证据不等于审计了所有日志字段、debug 模式、握手引导流量、外部代理或 Web 鉴权。 + +### 中间失败、存量风险及合并前闸门 + +- `session` 首次退出 1:临时子脚本误把启动器的两行放在目标地址初始化处,解析报 `SyntaxError`,尚未运行协议。恢复初始化语句后原断言通过;未改仓库测试或生产代码。 +- `baseline` 首次退出 1:真实 Web、普通直传、消息、扩展 ACK 和文件均已核对,但将“所有新增进程线程”都当作原生传输线程,停服后断言失败。复测保留传输和最终线程清理断言,并记录扩展任务的真实 `Future`、线程归属和栈:`stop()` 后 **0 个原生传输线程,1 个空闲 Server 通用线程池 worker**,对应扩展任务已成功返回。临时实例的 executor 显式 `shutdown(wait=True)` 后才达到整个 fixture 零新增线程,**不归功于 `stop()`**。 +- 溯源:另从改前 `ddb71c9` 解出 `PyFlow`,真实 Server 调用 `submit_task(threading.current_thread).result()` 后 `stop()`;同样得到 `finished_future=True post_stop_pool_thread_alive=True stack=concurrent.futures.thread._worker`。不是本次转发的在途 owner 泄漏;反复创建/销毁扩展实例的线程池生命周期仍是存量风险,未越权修改。 +- 范围复查(`ddb71c9..d219be8`):变动 17 个文件;生产仅 `connect_tcp.py` 与 `flow_setup.py`,无 CI、依赖、coverage、Web UI、消息或落盘扩展实现变动。比较两个构造器 AST,旧位置参数及缺省值均保留;只有 Client 追加 `is_forward_one_to_one=False`。6 个已改测试文件的既有 `test_*` 名称无删除、新增 8 个,增量中无新增 skip/xfail/ignore 或容错退出标记;旧压力断言改为真实扣住 writer、严格不越界,不是删背压测试。 +- 规则沉淀:P1–P8 路径清单、V1–V4 精确节点和真实 TCP 回归已入库;双模式 FID/ACK、跨路由严格预算、旧会话取消和按真实 offset 恢复可机械重验。文件传输指南、Client/Server API、实例配置和变更记录已在 A1–A3 随实现更新。`max_mem_buff` 的严格总额保证须升级 Server;不是 `max_thread_num`、带宽或进程内存保证。 + +**最终结论:** P1–P7 及 P8 的上述 Linux 组合有运行证据;保留唯一的明文 re-key 不适用项、扩展通用线程池退出行为,以及 A2 报告的同机手动端口冲突边界。未运行原生 Windows、macOS、自由线程解释器、全部配置笛卡尔积或全仓测试;模拟的 Windows 端口异常不算 Windows 验证。没有把这些边界视为已获人工豁免。 + +A4 工作树交付仅为本报告与计划状态。临时验收脚本、源码副本、测试日志/XML、测试密钥与传输文件已清理。**未创建提交、合并或推送;合并前最后一项为人类接受上述结果与边界。** + +### Windows Actions 后续:接收路径断言 + +Windows Actions 报告 `2 failed, 1022 passed, 3 skipped`:`test_forward_one_to_one_session_recovery` 的 `partial` 与 `before-final-ack` 均已核对落盘内容,失败在接收进度行第 4 个字段的字符串比较。命令中的 `original/nested path` 保留 `/`,而 `str(c_output)` 在 Windows 输出 `\`。测试现按本机路径规则比较完整路径,其余四字段仍精确匹配;未更改持久化格式、传输逻辑、重连断言或 CI。 + +修正后执行 `.venv/bin/python -m pytest -q test/integration/network_api/test_tcp_transfer_resume.py::test_forward_one_to_one_session_recovery`,Linux 上 `2 passed in 12.48s`。另以 `ntpath` 验证混合分隔符匹配、不同目录不匹配。原生 Windows 修正结果待 Actions 重跑。 diff --git a/docs/plans/forward-one-to-one-requirements.md b/docs/plans/forward-one-to-one-requirements.md new file mode 100644 index 0000000..dbdec1d --- /dev/null +++ b/docs/plans/forward-one-to-one-requirements.md @@ -0,0 +1,44 @@ +# 原生 TCP 一对一文件转发 — 需求卡 + +状态:**需求方已确认本卡,仅授权编写[更改计划](forward-one-to-one-plan.md),未批准实施**。沿用[文件转发词汇表](../../GLOSSARY.md)。 + +## 已明确的目标 + +- 在发送端 `TCP_Client_Base` 新增可选参数 `is_forward_one_to_one=False`,现有调用保持共享上行拓扑、控制和交付语义。同一条目向多个目标仍只上传一份,用户暂停/继续仍作用于整个转发任务。 +- 开启时,由发送端将同一条目的多目标请求拆为逐目标的单目标转发。已获准使用资源的任务可并行传输;不得等前一个目标传完整个文件才启动下一个。B 的用户暂停或继续不改变 C 的用户暂停状态。 +- Q3 已选:并发单位是「文件条目 × 去重后的目标」,不是每个目标一条串行文件队列。x、y 同时发往 B、C 会产生四个单目标任务;即便 x→B 正暂停,只要有名额,y→B 也可开始。 +- Q4 已选:开启模式的发送端复用现有 `max_thread_num`/文件发送名额,与同一实例内已受该限制的普通批量发送共同限流;多次转发命令不各自乘一份额度。满额等待,不提前开数据连接、占数据端口或给每个等待项都起线程;活跃但暂停的任务不释放仍在占用的资源和名额。 +- Q5 已选:同一新模式命令中,若可从请求判定两个条目会写同一目标的同一目的路径,则保留第一次、跳过后者并给可定位提示;不更名、不并发写同一路径。不同目标或不同相对目录不构成此冲突。 +- Q6 已选:没有命令级父任务、总进度或整批 ACK。每个获准单目标任务沿用自己的 upstream FID、child FID、进度、用户控制和最终确认;B 的成功清理不能删除 C 的失败/恢复依据。已有公开入口的返回值、查询和五字段进度格式不改。 +- Q7 澄清已选:排队项仅属于提交命令时的实际控制会话;未调度不分 FID、不开数据端口、不建进度行、不持久化。旧会话结束就取消尚未发起的项并提示,不能借用重连后的 socket;不自动重发等待项。已在途的中断传输走既有进度恢复。 +- Q8 已选:获准进入既有单目标握手即按在途处理,可在首条 `/forward_item` 发出前绑定 FID 和已有五字段上传行(跟踪关闭不新建行)。不要因没有正文或握手结果不确定而删掉已成立任务的恢复依据。只拆首次请求,不因重连或构造参数变化重新拆分历史 route。 +- Server 不接收新的模式参数或模式标记。交给它的仍是既有单目标或多目标转发请求;不另造一套文件传输协议。 +- 沿用原生流式转发的资源保护、控制会话、握手与真实收件确认,不用取消背压或提前报成功换取独立性。 + +## 范围与数据边界 + +- 范围是 `PyFlow/network_api/connect_tcp.py` 的原生 `/forward_file`、`/forward_folder`(文件夹内实际文件)和共用入口,包括现有 Web 单目标调用;不扩展 Web 选目标界面。构造参数置于现有可选参数末尾;普通配置沿用 Client 构造入口,不新增线上字段。 +- 原生转发不在 Server 落文件;不绕过统一控制消息和文件数据加密路径,不新增文件正文、密钥或完整负载日志。普通直传、消息转发、独立落盘扩展均不是本次新数据通路。 +- 不改 CI、依赖、覆盖率策略;不删或弱化既有测试。风险较高的部分是多任务并存时的资源计账、传输身份和清理。 +- 不承诺不同进程/发送者在接收盘上的写路径互斥、远端文件系统别名识别、源文件传输中变更的快照一致性、进程内存硬限或带宽公平。不会把 Server 的普通文件发送名额说成现存的原生中转任务数上限。 + +## 资源口径:配置值、计账范围、实际用量分开 + +现有[传输说明](../source/File_Transfer/File_Transfer.rst)和 `_forward_pump` 的实现是每次中转各有队列计数,允许一次入队超出水位;这既不是预分配,也不是进程 RAM 上限。 + +Q1 澄清和 Q2 已确认:同一 Server 实例中所有并发原生转发(不同文件、目标、命令或源端,含旧模式)共用既有 `max_mem_buff` **一份严格的待下发字节额度**。例如 64 MiB 已由 x→B 用满,即使 y→C 的队列为空,也须等待有足够额度才入队。不乘大配置值、不预分配、不跨任务共享正文;只协调计账、等待和释放。用户暂停/继续只改变所属任务状态,不能越过资源等待。Server 因此要改通用背压,不增模式参数。 + +## 执行路径与验收证据(均未执行) + +| 路径 | 必须实际观察的结果 | +|---|---| +| P1 默认、显式 False、原本就只有一个目标 | 同一文件的默认多目标仍只有一次上行、一个原任务;全部已接受目标真实 ACK 才收尾。单目标复用原握手,无模式字段。 | +| P2 输入和落点:原生文件/目录、多条目、目标列表、destination、Web 既有入口 | 引号/空格和嵌套相对目录保留;重复目标只交付一次,自己不分 FID,不同端口的合法目标照常;同命令目的路径冲突跳过后者。不可达/Server 目标及无效文件不妨碍其他项。 | +| P3 一对一命令、多个文件/目标、并发名额 | x、y 发 B、C 是四个独立任务;受限时不超同一 Client 现有名额。阻住 x→B 的正文或 ACK 后 C 能完成,有空位时 y→B 不等 x→B。未调度不占数据端口/进度行。 | +| P4 用户暂停与继续 | 源端、Server、目标端仍沿原 FID 和角色路由,由源端仲裁;B 的暂停/继续不改变独立 C 的状态,同一 B 数据连接可继续。在途字节可排空。False 模式按原任务联动。 | +| P5 Server 内存预算 | 同一 Server 上来自不同请求/源的单目标、多目标及恢复并存时,所有排队/writer 未交付的计费字节之和始终不超过额度。块大于预算、扇出大于预算、元信息、慢 writer、失败/取消/停止都要有界、有进展、最终归零;自动背压不发用户控制。 | +| P6 错误、握手和控制会话更替 | 乱序端口、单项协商拒绝或数据失败不串 FID、不取消健康任务;旧会话的等待项撤销、已准入 owner 收尾,不能借新 socket。用户手动关闭同样释放等待和名额。 | +| P7 真实交付与恢复 | B 完成只清 B;C 中断/重连按原 upstream/child FID、实际文件 offset 和原路径重放。空文件、offset=0/EOF、最终 ACK 丢失沿既有规则;跟踪关闭不伪造持久进度;旧多目标 route 不迁移成多条新 route。 | +| P8 环境和回归 | 明文/加密、线程/异步 Server、系统端口/手动端口生命周期;普通直传、消息、落盘扩展不进入新分支。检查临时连接/端口、线程、路由、预算归属和真实内容,不以文件存在或一次 pytest 通过代替证据。 | + +高风险:跨中转的严格预算、并发握手/快照和会话取消。文件、阶段、逐路径机械验收命令见[更改计划](forward-one-to-one-plan.md);本阶段不实施、不提交。 diff --git a/docs/source/File_Transfer/File_Transfer.rst b/docs/source/File_Transfer/File_Transfer.rst index 01ace17..854a788 100644 --- a/docs/source/File_Transfer/File_Transfer.rst +++ b/docs/source/File_Transfer/File_Transfer.rst @@ -521,6 +521,29 @@ its structure under omitted the targets write to their default ``file_transfer_dir``. +By default a file entry is uploaded once for all accepted targets; it has +one user pause state and waits for all their final acknowledgements. To send +independent copies, set ``is_forward_one_to_one=True`` on the **sending +client**. For example, forwarding ``x`` and ``y`` to B and C schedules +``x → B``, ``x → C``, ``y → B`` and ``y → C``. Each pair has its own data +connection, FID and final ACK. Pausing ``x → B`` does not pause the others. + +Repeated targets are used once. If two entries in the same command name the +same destination file, the first wins; different relative directories do not +collide. A pair waits for one of the client's existing ``max_thread_num`` +file slots **before** opening a connection or recording progress. A paused +pair keeps its slot. Disconnect cancels pairs still waiting; it does not move +them to the new session. An interrupted upload with retained progress replays +the original FID and route, not a new batch. There is no batch ACK. + +When tracking is enabled, forwarding ``x`` to B and C in one-to-one mode +creates two upload rows with the same source path. Use the **FID and logical +target**, not the pathname, to distinguish them. If B confirms delivery and +C disconnects, only B's row is removed. On reconnect C keeps its child FID +and destination path; the source resumes its original upload from C's disk +offset. Even if C already has every byte, reaching EOF is not a final ACK. +With the default shared upload, B's ACK alone does not retire the route. + The data path reuses the protocol's own transfer machinery: @@ -545,16 +568,20 @@ machinery: ### Memory Bounding and Flow Control -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) 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. +``TCP_Server_Base.max_mem_buff`` is one queue budget for **all native forwards +on that server**, including resumed transfers. The constructor takes MiB +(default 2048); the effective limit is at least one byte. Each downstream copy +of the file header and body is charged before it enters its queue and stays +charged until the writer returns from sending it or discards it. A large +chunk or fan-out is sent in parts rather than exceeding the limit. + +When the budget is full, relay readers wait. Returning credit lets another +route proceed without waiting for the whole file to finish. TCP carries this +pressure upstream without sending user pause/start commands: draining a queue +cannot cancel a user pause, and user start cannot bypass the budget. This is +not preallocated memory or a process RAM limit. Temporary reads, encryption +buffers and OS socket buffers are outside the budget. The guarantee requires +an updated server; the client's setting does not set the server's limit. .. _concurrency-and-threading: diff --git a/docs/source/Instance_Setup/Instance_Setup.rst b/docs/source/Instance_Setup/Instance_Setup.rst index 9a61fe4..8a29cbf 100644 --- a/docs/source/Instance_Setup/Instance_Setup.rst +++ b/docs/source/Instance_Setup/Instance_Setup.rst @@ -246,7 +246,11 @@ the client entry carries ``host``, ``client_host``, ``port``, ``is_wait_server``, ``max_custom_workers``, ``is_extend_command``, ``is_enable_encrypto``, ``is_custom_keys``, ``max_mem_buff``, ``recv_messages_chunk_len``, -``file_transfer_chunk_len``, ``is_debug`` and ``is_print_log``. +``file_transfer_chunk_len``, ``is_debug``, ``is_print_log`` and +``is_forward_one_to_one``. Set ``"is_forward_one_to_one": true`` on a +sending client to forward each file entry separately to each target. Omit +it or use ``false`` to keep the default shared upload. No server or target +setting is required. Custom Parameters ----------------- diff --git a/docs/source/Network_APIs/TCP_Client_APIs.rst b/docs/source/Network_APIs/TCP_Client_APIs.rst index a37622f..9b8a6e9 100644 --- a/docs/source/Network_APIs/TCP_Client_APIs.rst +++ b/docs/source/Network_APIs/TCP_Client_APIs.rst @@ -32,7 +32,9 @@ the TCP server and exchange data with the server. is_debug: Any=False, is_print_log: Any=True, is_enable_file_transfer_progress_bar: Any=True, - is_enable_real_time_network_speed: Any=True) -> None: + is_enable_real_time_network_speed: Any=True, + is_auto_reconnect: Any=False, + is_forward_one_to_one: Any=False) -> None: ... The TCP Client Setup API is defined in the ``TCP_Client_Base`` class. @@ -44,7 +46,8 @@ The parameters of the ``__init__`` method are as follows: - ``client_port``: The local port number to bind the client socket to (``None`` means let the OS choose). - ``timeout``: The socket timeout in seconds for connection and receive operations. ``None`` (the default) is not "no timeout": the socket then uses a fixed 5-second timeout, and receive timeouts are swallowed by the receive loop (it simply continues). - ``port_add_step``: The step size for incrementing the port number (used only in manual allocation mode). -- ``max_thread_num``: The maximum number of threads for concurrent file transfer operations. +- ``max_thread_num``: File send slots shared by ordinary batch sends and + opt-in one-to-one forwards. This is not a process-wide thread limit. - ``is_input_command_in_console``: A flag indicating whether to input commands in the console (interactive mode). - ``is_wait_server``: A flag indicating whether to keep retrying connection until the server is available. - ``max_custom_workers``: The maximum number of custom worker threads. @@ -99,6 +102,11 @@ The parameters of the ``__init__`` method are as follows: ``recv_network_speed`` (bytes per second, a rolling average over ``NETWORK_SPEED_WINDOW`` seconds). With ``False`` nothing is measured and every speed value is ``None``. +- ``is_forward_one_to_one``: On the sender only. ``True`` creates one native + forward per file entry and distinct target, each with its own upload FID, + pause state and final ACK. First sends and forwarded replays share file + slots. A paused transfer keeps its slot. Unstarted pairs belong only to the + original control connection and are cancelled when it closes. Every parameter has default values: @@ -142,6 +150,8 @@ Every parameter has default values: resume the interrupted transfers, see :ref:`transfer-pause-and-reconnect`. The dead session's socket is closed abortively first, so a configured ``client_port`` can be bound again — Windows refuses it otherwise) +- ``is_forward_one_to_one``: Default is ``False`` (one upload per file entry + shared by all accepted targets). Existing routes keep their original shape. The TCP Client Setup API will initialize all the necessary parameters and resources for the TCP client. diff --git a/docs/source/Network_APIs/TCP_Server_APIs.rst b/docs/source/Network_APIs/TCP_Server_APIs.rst index 12c4d26..3d48220 100644 --- a/docs/source/Network_APIs/TCP_Server_APIs.rst +++ b/docs/source/Network_APIs/TCP_Server_APIs.rst @@ -59,10 +59,11 @@ 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 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. +- ``max_mem_buff``: Shared queue budget for all native file and folder relays + on this server, in MiB (default 2048). Each downstream copy of a header or + body segment counts until its send returns or the copy is discarded. When + the shared budget is full, readers wait without changing user pause/start + state. This limits pending delivery bytes, not total process RAM. - ``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 diff --git a/docs/source/changes/forward-one-to-one.md b/docs/source/changes/forward-one-to-one.md new file mode 100644 index 0000000..23a7ed3 --- /dev/null +++ b/docs/source/changes/forward-one-to-one.md @@ -0,0 +1,11 @@ +# Native TCP file forwarding: shared server queue budget + +`max_mem_buff` now bounds the total pending downstream bytes of all native file and folder relays on one `TCP_Server_Base`. Previously each relay could buffer up to its own high-water mark plus one fan-out enqueue. Operators running concurrent relays should size **one** budget for their server. The constructor still takes MiB (default 2048); no Client or wire change is required. Updating only the Client does not change an older Server's behavior. + +Each header or body segment is charged per downstream copy, including a writer's current send. A full budget delays readers; it does not pause the user task or complete it early. The ordinary transfer path, encryption, and final recipient acknowledgements are unchanged. This is not a cap on process RSS. + +## Opt-in one-to-one scheduling on the Client + +`TCP_Client_Base(..., is_forward_one_to_one=True)` makes each file entry and distinct target a separate transfer. The sender uses its existing `max_thread_num` file slots for initial sends and forwarded replays. Each pair keeps its own transfer ID and holds one slot through pause and final ACK. Items waiting at disconnect are not persisted or submitted on a replacement connection. `False` remains the default, and neither setting changes a stored route or the wire format. + +With tracking enabled, two rows for the same source pathname can therefore be correct. A confirmed delivery to B does not retire C's interrupted transfer. C resumes on its retained route and destination, including when it has reached EOF but has not acknowledged delivery. In the default shared mode, the source still waits for every accepted target's ACK. diff --git a/test/integration/network_api/test_tcp_file_transfer.py b/test/integration/network_api/test_tcp_file_transfer.py index e84cb46..26f62a2 100644 --- a/test/integration/network_api/test_tcp_file_transfer.py +++ b/test/integration/network_api/test_tcp_file_transfer.py @@ -3,6 +3,7 @@ import os import threading import shlex +from contextlib import closing from pathlib import Path import pytest @@ -35,6 +36,8 @@ def _isolate_log_files(instance, log_dir, name): interrupted transfers another test left behind. """ isolate_instance_files(instance, Path(log_dir), name) + instance.sent_events_log_file = str(Path(log_dir) / f"{name}_sent_events_log.json") + instance.sent_messages_log_file = str(Path(log_dir) / f"{name}_sent_messages_log.json") @pytest.fixture @@ -587,7 +590,7 @@ def fake_input(): assert files[0].read_bytes() == payload -def _forward_client(server, recv_dir): +def _forward_client(server, recv_dir, **options): client = TCP_Client_Base( host="127.0.0.1", port=server.port, @@ -595,6 +598,7 @@ def _forward_client(server, recv_dir): is_extend_command=True, is_input_command_in_console=False, is_enable_encrypto=False, + **options, ) _isolate_log_files(client, recv_dir.parent, recv_dir.name) client.file_transfer_dir = str(recv_dir) @@ -694,6 +698,130 @@ def got(path): forwarder.close() +def _record_forward_acks(monkeypatch, source): + completed = [] + transfer = source.file_transfer_mode + + def record(path, *args, **kwargs): + result = transfer(path, *args, **kwargs) # True only after the real final ACK. + completed.append((Path(path), kwargs["peer"], kwargs["fid"], result)) + return result + + monkeypatch.setattr(source, "file_transfer_mode", record) + return completed + + +def test_forward_one_to_one_item_target_admission(pair, tmp_path, monkeypatch): + server, b, recv_b = pair + x, y = tmp_path / "x data.bin", tmp_path / "y data.bin" + x.write_bytes(b"first x") + y.write_bytes(b"only y") + collision = tmp_path / "later" / x.name + collision.parent.mkdir() + collision.write_bytes(b"must not overwrite x") + dest = "received files" + held, permits = [], threading.Semaphore(0) + + def gate_final_ack(target): + send = target.send_message + + def gated(sock, message, is_send_raw=False): + if message == target.server_received_file_data_sign: + held.append(sock) + assert permits.acquire(timeout=25), "target ACK was not released" + return send(sock, message, is_send_raw=is_send_raw) + + monkeypatch.setattr(target, "send_message", gated) + + with (closing(_forward_client(server, tmp_path / "recv_c")) as c, + closing(_forward_client(server, tmp_path / "source", is_forward_one_to_one=True, + max_thread_num=3)) as source): + peers = [target.client_socket.getsockname() for target in (b, c)] + expected = {(path, peer) for path in (x, y) for peer in peers} + assert wait_until(lambda: all(peer in server.clients for peer in peers)) + for target in (b, c): + gate_final_ack(target) + completed = _record_forward_acks(monkeypatch, source) + allocate_port = MagicMock(wraps=source.palloc) + monkeypatch.setattr(source, "palloc", allocate_port) + initial_counter = source._fid_alloc._counter + try: + source.forward_file_console(shlex.join([ + "/forward_file", str(x), str(collision), str(y), *map(str, peers), dest, + ])) + assert wait_until(lambda: len(held) == 3, timeout=15), "three slots must overlap" + # The fourth pair has no upstream FID, upload row or data port yet. + rows = source.file_upload_progress.copy() + active = {(Path(row[3]), row[4]) for row in rows.values()} + assert active < expected and len(active) == len(rows) == 3 + assert source._fid_alloc._counter - initial_counter == allocate_port.call_count == 3 + assert set(rows) == set(source._active_transfer_sockets) + assert not completed + for (_, fid), row in rows.items(): + assert set(server._fid_routes[fid]["targets"]) == {row[4]} + children = server._fid_route_index.copy() # (target, child FID) -> upstream FID + + permits.release() # One completion admits the fourth, without a batch barrier. + assert wait_until(lambda: len(held) == 4, timeout=15) + assert len(completed) == 1 and completed[0][3] is True + children.update(server._fid_route_index) + finally: + permits.release(4) + assert wait_until(lambda: len(completed) == 4, timeout=15) + assert {(path, peer) for path, peer, _, ok in completed if ok} == expected + assert len({fid for _, _, fid, _ in completed}) == 4 + assert source._fid_alloc._counter - initial_counter == allocate_port.call_count == 4 + assert len(children) == 4 and set(children.values()) == {fid for _, _, fid, _ in completed} + for root in (recv_b, Path(c.file_transfer_dir)): + assert (root / dest / x.name).read_bytes() == b"first x" + assert (root / dest / y.name).read_bytes() == b"only y" + assert wait_until(lambda: not server._fid_routes and not server._fid_route_index + and not source.file_upload_progress and not source._active_transfer_sockets + and not b.file_recv_progress and not c.file_recv_progress) + + +def test_forward_one_to_one_folder_destinations(pair, tmp_path, monkeypatch): + server, target, recv = pair + # Same root name and basename; only the second entry has the same relative path. + roots = [tmp_path / n / "shared root" for n in ("first", "collision", "distinct")] + paths = [root / sub / "same name.txt" for root, sub in zip(roots, ("left", "left", "right"))] + for path, payload in zip(paths, (b"winner", b"skip me", b"other dir")): + path.parent.mkdir(parents=True) + path.write_bytes(payload) + dest = "nested/output folder" + with closing(_forward_client(server, tmp_path / "source", is_forward_one_to_one=True, + max_thread_num=1)) as source: + peer, own = (client.client_socket.getsockname() for client in (target, source)) + refused = (server.host, server.port) # A real control endpoint, never a relay target. + assert wait_until(lambda: peer in server.clients and own in server.clients) + completed = _record_forward_acks(monkeypatch, source) + requests = MagicMock(wraps=server._forward_item_handler) + monkeypatch.setattr(server, "_forward_item_handler", requests) + initial_counter = source._fid_alloc._counter + source.forward_folder_console(shlex.join([ + "/forward_folder", *map(str, roots), *map(str, (own, refused, peer, peer)), dest, + ])) + assert wait_until(lambda: len(completed) == 2, timeout=20) + assert [(path, target_peer, ok) for path, target_peer, _, ok in completed] == [ + (paths[0], peer, True), (paths[2], peer, True), + ] + # One slot makes wire order observable: each refused request precedes its healthy sibling. + wire = [shlex.split(call.args[2]) for call in requests.call_args_list] + assert [tokens[3:] for tokens in wire] == [ + [f"/shared root/{sub}", "same name.txt", str(address), dest] + for sub in ("left", "right") for address in (refused, peer) + ] + assert len({tokens[2] for tokens in wire}) == source._fid_alloc._counter - initial_counter == 4 + output = recv / dest / "shared root" + assert (output / "left" / "same name.txt").read_bytes() == b"winner" + assert (output / "right" / "same name.txt").read_bytes() == b"other dir" + assert wait_until(lambda: not server._fid_routes and not target.file_recv_progress) + rejected = {(refused, int(tokens[2].split("=")[1])) + for tokens in wire if tokens[-2] == str(refused)} + assert set(source.file_upload_progress) == rejected + assert all(row[4] == refused for row in source.file_upload_progress.values()) + + def test_forward_folder_to_client(pair, tmp_path): """/forward_folder relays a folder (structure preserved) from a client to another client through the in-memory relay.""" @@ -750,6 +878,33 @@ def got(path): forwarder.close() +def _observe_forward_pumps(monkeypatch, server): + relays, downstream = {}, {} + real_pump = server._forward_pump + + def pump(up, connections, control, fid, name, relay, offset=0): + relays[name] = relay + downstream.update((sock, name) for _, _, sock in connections) + return real_pump(up, connections, control, fid, name, relay, offset) + + monkeypatch.setattr(server, "_forward_pump", pump) + return relays, downstream + + +def _forward_ack(monkeypatch, source, path, targets): + results = [] + real_transfer = source.file_transfer_mode + + def transfer(*args, **kwargs): + result = real_transfer(*args, **kwargs) # Includes the real upstream final ACK. + results.append(result) + return result + + monkeypatch.setattr(source, "file_transfer_mode", transfer) + source.forward_file_console(shlex.join(["/forward_file", str(path), *map(str, targets)])) + return results + + def test_forward_flow_control_pauses_uploader(pair, tmp_path, monkeypatch): """Local backpressure bounds queued bytes without changing user pause state.""" server, target, recv_dir = pair @@ -758,63 +913,124 @@ def test_forward_flow_control_pauses_uploader(pair, tmp_path, monkeypatch): payload = os.urandom(300 * 1024) src.write_bytes(payload) forwarder = _forward_client(server, tmp_path / "fwd") - 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) + writer_held, release_writer = threading.Event(), threading.Event() + relays, downstream = _observe_forward_pumps(monkeypatch, server) + controls = [] + real_send = server.send_message def send(sock, message, is_send_raw=False): - if isinstance(message, bytes) and len(message) > server.max_mem_buff: + if sock in downstream and isinstance(message, bytes): + sent = real_send(sock, message, is_send_raw=is_send_raw) writer_held.set() assert release_writer.wait(timeout=15) + return sent 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) - 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"] + acknowledgements = _forward_ack(monkeypatch, forwarder, src, [peer]) + assert writer_held.wait(timeout=10) + state = relays[src.name]["buffer"] + assert wait_until(lambda: state["backpressured"]) + assert state["buffered"] == server.max_mem_buff + budget = server._forward_budget + with budget.cond: + assert budget.used == budget.peak == server.max_mem_buff 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 budget.used == 0 and budget.peak == server.max_mem_buff assert controls == [], "automatic pressure must not send user pause/start" finally: release_writer.set() forwarder.close() +def test_forward_shared_budget_across_routes(pair, tmp_path, monkeypatch): + server, first_target, recv = pair + # Even a one-byte segment cannot be reserved for both targets at once. + server.max_mem_buff, server.file_transfer_chunk_len = 1, 128 + fan, single = tmp_path / "fan.bin", tmp_path / "single.bin" + fan_bytes, single_bytes = os.urandom(259), os.urandom(137) + fan.write_bytes(fan_bytes) + single.write_bytes(single_bytes) + budget = server._forward_budget + relays, downstream = _observe_forward_pumps(monkeypatch, server) + held, release_writer = threading.Event(), threading.Event() + body_held, release_body = threading.Event(), threading.Event() + single_write = threading.Event() + real_send = server.send_message + + def send(sock, message, is_send_raw=False): + route = downstream.get(sock) + if route and isinstance(message, bytes): + assert len(message) == 1 + if route == single.name: + single_write.set() + sent = real_send(sock, message, is_send_raw=is_send_raw) + if route == fan.name and isinstance(message, bytes) and not release_writer.is_set(): + held.set() # Dequeued and really written, but send_message hasn't returned. + assert release_writer.wait(20) + return sent + + monkeypatch.setattr(server, "send_message", send) + with (closing(_forward_client(server, tmp_path / "second")) as second_target, + closing(_forward_client(server, tmp_path / "source_a")) as source_a, + closing(_forward_client(server, tmp_path / "source_b")) as source_b): + peers = [target.client_socket.getsockname() for target in (first_target, second_target)] + assert wait_until(lambda: all(peer in server.clients for peer in peers)) + source_a.file_transfer_chunk_len = server.file_transfer_chunk_len + source_send = source_a.send_message + + def hold_body(sock, message, is_send_raw=False): + if message == fan_bytes[:source_a.file_transfer_chunk_len]: + body_held.set() + assert release_body.wait(30) + return source_send(sock, message, is_send_raw=is_send_raw) + + monkeypatch.setattr(source_a, "send_message", hold_body) + try: + fan_ack = _forward_ack(monkeypatch, source_a, fan, peers) + assert held.wait(10) and body_held.wait(10) + single_ack = _forward_ack(monkeypatch, source_b, single, peers[:1]) + assert wait_until(lambda: relays.get(single.name, {}).get("buffer", {}).get("backpressured"), + timeout=10) + shared, solo = relays[fan.name], relays[single.name] + with budget.cond: + assert shared["buffer"]["buffered"] == budget.used == budget.peak == 1 + assert solo["buffer"]["backpressured"] and solo["buffer"]["buffered"] == 0 + assert not single_write.is_set() and fan_ack == single_ack == [] + release_writer.set() + assert wait_until(lambda: single_ack == [True], timeout=15) + assert single_write.is_set() and (recv / single.name).read_bytes() == single_bytes + assert solo["route"]["completed"] == {peers[0]} + assert not fan_ack and server._fid_routes[shared["fid"]] is shared["route"] + release_body.set() + assert wait_until(lambda: fan_ack == [True], timeout=15) + assert shared["route"]["completed"] == set(peers) + for target in (first_target, second_target): + assert (Path(target.file_transfer_dir) / fan.name).read_bytes() == fan_bytes + assert wait_until(lambda: not server._forward_relays and not server._receive_transfers) + assert not server._fid_routes and not server._fid_route_index and not server._relay_recoveries + assert wait_until(lambda: all(not owner._active_transfer_sockets and not owner._receive_transfers + and not owner._transfer_controls._legs + for owner in (server, source_a, source_b, first_target, second_target))) + for relay in (shared, solo): + state = relay["buffer"] + assert state["complete"] and not state["failed"] and not state["backpressured"] + assert state["buffered"] == 0 and not relay["sockets"] and not relay["handshakes"] + assert budget.used == 0 and budget.peak == server.max_mem_buff + finally: + release_writer.set() + release_body.set() + + def test_forward_file_with_destination(pair, tmp_path): """/forward_file with a trailing destination dir: targets write the forwarded file under the destination instead of their default dir.""" diff --git a/test/integration/network_api/test_tcp_transfer_control.py b/test/integration/network_api/test_tcp_transfer_control.py index 5759882..56f7746 100644 --- a/test/integration/network_api/test_tcp_transfer_control.py +++ b/test/integration/network_api/test_tcp_transfer_control.py @@ -487,7 +487,7 @@ def _relay(relay_clients, tmp_path, monkeypatch, *, pressure=False): entered = [threading.Event() for _ in range(3)] gates = [threading.Event() for _ in range(3)] releases.extend(gates) - observed = {"reads": 0, "waits": 0, "controls": [], "frames": []} + observed = {"reads": 0, "controls": [], "frames": []} tail = threading.Event() releases.append(tail) observed["tail"] = tail @@ -510,15 +510,16 @@ def hold(instance, state, sock): def pump(up, connections, control, fid, name, relay, offset=0): observed["relay"] = relay - real_condition_wait = relay["cond"].wait + if pressure: + cond = server._forward_budget.cond + real_condition_wait = cond.wait - def pressure_wait(timeout=None): - if relay["buffer"]["backpressured"]: - observed["waits"] += 1 - waiting.set() - return real_condition_wait(timeout) + def pressure_wait(timeout=None): + if relay["buffer"]["backpressured"]: + waiting.set() + return real_condition_wait(timeout) - monkeypatch.setattr(relay["cond"], "wait", pressure_wait) + monkeypatch.setattr(cond, "wait", pressure_wait) return real_pump(up, connections, control, fid, name, relay, offset) def read(sock, count): @@ -573,8 +574,9 @@ def _relay_done(relay_clients, run, *, failed=False): 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) + assert wait_until(lambda: not server._forward_relays and not server._receive_transfers) + budget = server._forward_budget + assert budget.used == 0 and 0 < budget.peak <= server.max_mem_buff 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 @@ -592,6 +594,91 @@ def _relay_done(relay_clients, run, *, failed=False): assert not server._fid_routes and not server._fid_route_index +def test_forward_one_to_one_pause_isolation(relay_clients, tmp_path, monkeypatch): + """A paused x→B keeps its socket while x→C and both y deliveries finish.""" + server, source, (b, c), releases = relay_clients + source.is_forward_one_to_one = True + chunk = source.file_transfer_chunk_len = 1024 + x, y = tmp_path / "x.bin", tmp_path / "y.bin" + for path in (x, y): + path.write_bytes(os.urandom(chunk * 4)) + b_addr, c_addr = b.client_socket.getsockname(), c.client_socket.getsockname() + xb, xc = (x, b_addr), (x, c_addr) + siblings = {xc, (y, b_addr), (y, c_addr)} + server_peer = (source.host, source.port) + go_b, go_others, paused_at_reader = (threading.Event() for _ in range(3)) + releases.extend((go_b, go_others)) + local = threading.local() + fids, writes, results = {}, {}, {} + transfer, send = source.file_transfer_mode, source.send_message + wait = source._transfer_pause_cond.wait + + def record_transfer(path, *args, **kwargs): + local.pair = pair = (Path(path), kwargs["peer"]) + fids[pair] = kwargs["fid"] + results[pair] = transfer(path, *args, **kwargs) # Includes the real final ACK. + return results[pair] + + def hold_after_first_block(sock, data, is_send_raw=False): + sent = send(sock, data, is_send_raw=is_send_raw) + pair = getattr(local, "pair", None) + if sent and pair is not None and isinstance(data, bytes) and len(data) == chunk: + stream = writes.setdefault(pair, []) + stream.append(sock) + if len(stream) == 1: + assert (go_b if pair == xb else go_others).wait(30) + return sent + + def observe_pause_wait(timeout=None): + if getattr(local, "pair", None) == xb: + paused_at_reader.set() + return wait(timeout) + + monkeypatch.setattr(source, "file_transfer_mode", record_transfer) + monkeypatch.setattr(source, "send_message", hold_after_first_block) + monkeypatch.setattr(source._transfer_pause_cond, "wait", observe_pause_wait) + source.forward_file_console(shlex.join(["/forward_file", str(x), str(y), repr(b_addr), + repr(c_addr)])) + assert wait_until(lambda: writes.get(xb) and writes.get(xc), timeout=20) + original = writes[xb][0] + assert fids[xb] != fids[xc] and original is not writes[xc][0] + + def legs(pair, receiver): + route = server._fid_routes[fids[pair]] + assert set(route["targets"]) == {pair[1]} + child = route["targets"][pair[1]] + return (source._transfer_controls._legs[(server_peer, fids[pair], 1, 0)], + receiver._transfer_controls._legs[(server_peer, child, 1, 1)]) + + b_legs, c_legs = legs(xb, b), legs(xc, c) + assert _control(b, b_legs[1], True) + _confirmed(b_legs, True) + _confirmed(c_legs, False) + go_b.set() # Now only the user's pause, not the test gate, can hold x→B. + assert paused_at_reader.wait(10) + for pause in (True, False): + assert _control(c, c_legs[1], pause) + _confirmed(c_legs, pause) + assert all(leg["confirmed_state"] for leg in b_legs) + go_others.set() + assert wait_until(lambda: all(results.get(pair) is True for pair in siblings), timeout=20) + assert set(results) == siblings and writes[xb] == [original] + assert wait_until(lambda: set(server._fid_routes) == {fids[xb]}) + assert source._active_transfer_sockets[(server_peer, fids[xb])] is original + expected_rows = {(server_peer, fids[xb])} if source.is_enable_file_transfer_progress_bar else set() + assert set(source.file_upload_progress) == expected_rows + + assert _control(b, b_legs[1], False) + assert wait_until(lambda: results.get(xb) is True, timeout=15) + assert len(writes[xb]) > 1 and all(sock is original for sock in writes[xb]) + for receiver in (b, c): + for path in (x, y): + assert (Path(receiver.file_transfer_dir) / path.name).read_bytes() == path.read_bytes() + assert wait_until(lambda: not server._fid_routes and not server._forward_relays and + all(not obj._transfer_controls._legs and not obj._active_transfer_sockets + for obj in (source, server, b, c))) + + @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 @@ -679,25 +766,31 @@ def delay(sock, message, is_send_raw=False): def test_relay_pressure_preserves_user_intent_and_source_start_cannot_open_reader( relay_clients, tmp_path, monkeypatch, close_target ): + written, drained = _observe_target_writes(monkeypatch, tmp_path / "target_b" / "relay.bin", 1024) run = _relay(relay_clients, tmp_path, monkeypatch, pressure=True) server, source, targets, _ = relay_clients - relay, sender, gates, _, _, _, observed, waiting = run + relay, sender, gates, _, _, payload, observed, waiting = run + budget = server._forward_budget upstream, buffer = relay["upstream"], relay["buffer"] sockets = [state["owner"] for state in relay["controls"].values()] gates[0].set() assert waiting.wait(timeout=10) + assert observed["tail_waiting"].wait(10) # A full body block is in flight. _confirmed((sender, upstream), False) - assert buffer["backpressured"] + with budget.cond: + assert buffer["backpressured"] and budget.used == buffer["buffered"] == server.max_mem_buff + reads = observed["reads"] assert _control(server, upstream, True) _confirmed((sender, upstream), True) assert _control(source, sender, False) _confirmed((sender, upstream), False) - with relay["cond"]: - reads = observed["reads"] + with budget.cond: waiting.clear() - relay["cond"].notify_all() + budget.cond.notify_all() assert waiting.wait(timeout=10), "reader did not re-enter its pressure gate" - assert observed["reads"] == reads and buffer["backpressured"] + with budget.cond: + assert observed["reads"] == reads and buffer["backpressured"] + assert budget.used == budget.peak == server.max_mem_buff assert _control(source, sender, True) _confirmed((sender, upstream), True) assert _control(server, upstream, True) @@ -705,10 +798,10 @@ def test_relay_pressure_preserves_user_intent_and_source_start_cannot_open_reade targets[0].close() gates[1].set() gates[2].set() - assert wait_until(lambda: not buffer["backpressured"], timeout=10) + assert drained.wait(10) and written == payload[:1024] + assert wait_until(lambda: not buffer["backpressured"] and budget.used == 0, timeout=10) assert sender["confirmed_state"] and upstream["confirmed_state"] - assert buffer["peak"] <= buffer["high_water"] + buffer["max_enqueue"] - assert buffer["peak"] > buffer["high_water"] + assert budget.peak == server.max_mem_buff 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) diff --git a/test/integration/network_api/test_tcp_transfer_resume.py b/test/integration/network_api/test_tcp_transfer_resume.py index 22e0743..420da07 100644 --- a/test/integration/network_api/test_tcp_transfer_resume.py +++ b/test/integration/network_api/test_tcp_transfer_resume.py @@ -2520,6 +2520,154 @@ def observe_resume(client_socket, peer, requested_fid, offset, origin, target): _close_socket_workers(server, clients, workers) +@pytest.mark.parametrize("at_eof", [False, True], ids=["partial", "before-final-ack"]) +def test_forward_one_to_one_session_recovery(tmp_path, monkeypatch, at_eof): + """B's final ACK cannot erase C's same-path row; only C replays after reconnect.""" + chunk = 8192 + workers = _track_socket_workers(monkeypatch) + server = _start_server(tmp_path, file_transfer_chunk_len=chunk) + clients = [] + b_ready, c_ready, replay_ready = (threading.Event() for _ in range(3)) + finish_b, retire_c, finish_replay = (threading.Event() for _ in range(3)) + + def gate_ack(target, ready, release): + send = target.send_message + + def gated(sock, message, is_send_raw=False): + if message == target.server_received_file_data_sign and not release.is_set(): + ready.set() + assert release.wait(20), "final target ACK was not released" + return send(sock, message, is_send_raw=is_send_raw) + + monkeypatch.setattr(target, "send_message", gated) + + try: + source = _start_client(tmp_path, server, name="source", is_forward_one_to_one=True, + max_thread_num=2, file_transfer_chunk_len=chunk) + clients.append(source) + for name in ("B", "C"): + clients.append(_start_client(tmp_path, server, name=name, recv_dir=tmp_path / name, + client_port=free_port(), file_transfer_chunk_len=chunk)) + _, b, c = clients + origin, bp, cp = (node.client_socket.getsockname() for node in clients) + assert wait_until(lambda: {origin, bp, cp} <= server.clients.keys()) + path = tmp_path / "same source.bin" + payload = os.urandom(4 * chunk + 17) + path.write_bytes(payload) + destination = "original/nested path" + c_output = tmp_path / "C" / destination / path.name + gate_ack(b, b_ready, finish_b) + if at_eof: + gate_ack(c, c_ready, retire_c) + else: + receive = c.receive_message + + def stop_after_prefix(sock, size): + if sock is not c.client_socket and not retire_c.is_set() and any( + row[0] >= chunk for row in c.file_recv_progress.copy().values() + ): + c_ready.set() + assert retire_c.wait(20), "partial receiver was not released" + return receive(sock, size) + + monkeypatch.setattr(c, "receive_message", stop_after_prefix) + + outcomes, dispatches = [], [] + real_forward = source._forward_one + + def observe_forward(*args, **kwargs): + ok = real_forward(*args, **kwargs) + outcomes.append((tuple(args[4]), ok)) + return ok + + def observe_dispatch(peer, msg): + if isinstance(msg, str) and msg.startswith("/file "): + dispatches.append((peer, int(shlex.split(msg)[-1]))) + + monkeypatch.setattr(source, "_forward_one", observe_forward) + server.add_send_message_listener(observe_dispatch) + source.forward_file_console(shlex.join(["/forward_file", str(path), repr(bp), + repr(cp), destination])) + assert b_ready.wait(15) and c_ready.wait(15) + rows = source.file_upload_progress.copy() + assert len(rows) == 2 and all(row[3] == str(path) for row in rows.values()) + keys = {row[4]: key for key, row in rows.items()} + b_key, c_key = keys[bp], keys[cp] + assert b_key[0] == c_key[0] == (source.host, source.port) and b_key != c_key + route = server._fid_routes[c_key[1]] + child = route["targets"][cp] + b_child = server._fid_routes[b_key[1]]["targets"][bp] + assert child != b_child and set(route["targets"]) == {cp} + assert wait_until(lambda: source.file_upload_progress[c_key][0] == len(payload)) + old = c.client_socket + # Server FIN first keeps C's configured port reusable. Its native + # control teardown closes the blocked read/ACK socket, not B's leg. + server.clients[cp]["socket"].shutdown(socket.SHUT_WR) + c.receive_thread.join(10) + assert not c.receive_thread.is_alive() and not c.running + c._release_client_socket() + retire_c.set() + assert wait_until(lambda: outcomes == [((cp,), False)] and cp not in server.clients + and not c._receive_transfers, timeout=10) + offset = c_output.stat().st_size + if at_eof: + assert offset == len(payload) + else: + assert 0 < offset < len(payload) + assert c_output.read_bytes() == payload[:offset] + row = c.file_recv_progress[child] + assert row[:3] == [offset, len(payload), None] + # The destination from the wire can retain forward slashes on Windows. + assert os.path.normpath(row[3]) == str(c_output) + assert row[4:] == [origin] + finish_b.set() + assert wait_until(lambda: outcomes == [((cp,), False), ((bp,), True)] + and not server._forward_relays, timeout=15) + assert (tmp_path / "B" / destination / path.name).read_bytes() == payload + assert server._fid_routes == {c_key[1]: route} and not route["completed"] + assert server._fid_route_index == {(cp, child): c_key[1]} + assert set(source.file_upload_progress) == {c_key} and not b.file_recv_progress + with open(source.file_trans_progress_file, encoding="utf-8") as snapshot: + assert json.load(snapshot)["upload"] == { + json.dumps(c_key, separators=(",", ":")): + [len(payload), len(payload), None, str(path), list(cp)] + } + + # Count successful replay traffic, not attempted sends. C must request + # its disk offset even though the source had already uploaded everything. + requests, sizes = [], [] + + def observe_replay(_, msg): + if isinstance(msg, bytes): + sizes.append(len(msg)) + elif msg.startswith("/forward_item "): + requests.append(shlex.split(msg)) + + source.add_send_message_listener(observe_replay) + gate_ack(c, replay_ready, finish_replay) + assert c.connect() and c.client_socket is not old and c.client_socket.getsockname() == cp + assert replay_ready.wait(15) + assert requests == [["/forward_item", "file", f"fid={c_key[1]}", f"resume={offset}", + path.name, repr(cp)]] + assert server._fid_routes[c_key[1]] is route and not route["completed"] + assert c_key in source.file_upload_progress and len(outcomes) == 2 + finish_replay.set() + assert wait_until(lambda: outcomes == [((cp,), False), ((bp,), True), ((cp,), True)] + and not server._forward_relays, timeout=15) + assert sum(sizes) == 4 + len(path.name.encode()) + 8 + len(payload) - offset + initial = [(f"{bp[0]}:{bp[1]}", b_child), (f"{cp[0]}:{cp[1]}", child)] + assert sorted(dispatches[:2]) == sorted(initial) and dispatches[2:] == [initial[1]] + assert c_output.read_bytes() == payload + assert not server._fid_routes and not server._fid_route_index + assert wait_until(lambda: not source.file_upload_progress and not c.file_recv_progress + and not server._receive_transfers and not source._resume_sends) + finally: + retire_c.set() + finish_b.set() + finish_replay.set() + _close_socket_workers(server, clients, workers) + + def test_forward_route_is_removed_only_after_all_real_targets_complete(tmp_path, monkeypatch): """A completed sibling leaves the route live until the other real ACK arrives.""" workers = _track_socket_workers(monkeypatch) @@ -2554,12 +2702,18 @@ def hold_second_ack(sock, message, is_send_raw=False): payload = os.urandom(96 * 1024) src.write_bytes(payload) result = {} - sender = threading.Thread( - target=lambda: result.update(ack=source._forward_one( - "file", "", src.name, str(src), targets)), daemon=True, - ) - sender.start() + senders = [] + transfer = source.file_transfer_mode + + def observe_upload(*args, **kwargs): + senders.append(threading.current_thread()) + result["ack"] = transfer(*args, **kwargs) + return result["ack"] + + monkeypatch.setattr(source, "file_transfer_mode", observe_upload) + source.forward_file_console(shlex.join(["/forward_file", str(src), *map(repr, targets)])) assert held.wait(15), "the second Target never reached its final ACK" + sender, = senders # The default public command opened one shared upload. assert sender.is_alive() and result == {} assert len(server._fid_routes) == 1 fid, route = next(iter(server._fid_routes.items())) diff --git a/test/unit/network_api/test_TCP_client.py b/test/unit/network_api/test_TCP_client.py index a10f2da..a4499aa 100644 --- a/test/unit/network_api/test_TCP_client.py +++ b/test/unit/network_api/test_TCP_client.py @@ -234,3 +234,53 @@ def test_call_extension_functions_rejects_unregistered_commands(): assert "/ghost arg" in str(exc.value) with pytest.raises(CommandNotFoundError): # an empty line selects nothing client.call_extension_functions(" ") + + +@pytest.mark.parametrize("replace_before_driver", [True, False], ids=["submitted", "waiting"]) +def test_forward_pending_pairs_do_not_follow_a_replacement_socket( + replace_before_driver, tmp_path, monkeypatch, capsys +): + client = _client(is_enable_encrypto=False, is_forward_one_to_one=True, max_thread_num=1) + path = tmp_path / "unscheduled.bin" + path.write_bytes(b"not admitted") + client.file_trans_progress_file = str(tmp_path / "progress.json") + entered, proceed, waiting, done = (threading.Event() for _ in range(4)) + driver, acquire = client._forward_driver, client.file_semaphore.acquire + + def observe_driver(*args, **kwargs): + entered.set() + try: + assert proceed.wait(5) + return driver(*args, **kwargs) + finally: + done.set() + + def observe_acquire(*args, **kwargs): + waiting.set() + return acquire(*args, **kwargs) + + monkeypatch.setattr(client, "_forward_driver", observe_driver) + monkeypatch.setattr(client.file_semaphore, "acquire", observe_acquire) + old, wire = socket.socketpair() + new, new_wire = socket.socketpair() + with old, wire, new, new_wire, client.file_semaphore: + client.running, client.client_socket = True, old + try: + client.forward_file_console(f'''/forward_file "{path}" "('127.0.0.1', 6010)"''') + assert entered.wait(5) + if not replace_before_driver: + proceed.set() + assert waiting.wait(5) + client.client_socket = new # Old socket is still open; identity matters. + proceed.set() + assert done.wait(5) # Does not require the occupied slot to be released. + assert "cancel" in capsys.readouterr().out.lower() + assert client._fid_alloc._counter == 0 and not client.file_upload_progress + assert not (tmp_path / "progress.json").exists() + for peer in (wire, new_wire): + peer.setblocking(False) + with pytest.raises(BlockingIOError): + peer.recv(1) + finally: + client.running = False + proceed.set() diff --git a/test/unit/network_api/test_transfer_control.py b/test/unit/network_api/test_transfer_control.py index 9e9c901..b94cbf8 100644 --- a/test/unit/network_api/test_transfer_control.py +++ b/test/unit/network_api/test_transfer_control.py @@ -1,6 +1,7 @@ """Contracts for typed transfer control and connection-scoped endpoint identity.""" import json +import queue import socket import threading from collections import deque @@ -12,6 +13,7 @@ from PyFlow.network_api.connect_tcp import ( TCP_Client_Base, TCP_Server_Base, + _ForwardBudget, _TransferControlRegistry, _control_key, _is_control_endpoint, @@ -494,3 +496,21 @@ def test_relay_start_before_upstream_exists_overrides_a_preset_pause(): 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"] + + +def test_relay_publication_failure_returns_only_unpublished_credit(): + budget = _ForwardBudget() + slow, failed = {"buffered": 0}, {"buffered": 0} + pending = queue.Queue(maxsize=1) + with budget.cond: + initial = budget.publish(pending, b"abc", 0, 5, slow) + # Publication fails after reservation, while another delivery owns 3 B. + with pytest.raises(queue.Full): + budget.publish(pending, b"defg", 0, 5, failed) + assert (initial, budget.used, slow["buffered"], failed["buffered"]) == (3, 3, 3, 0) + current = pending.get_nowait() # in the writer, not yet released + accepted = budget.publish(pending, b"defg", 0, 5, failed) + assert (accepted, current, pending.get_nowait(), budget.peak) == (2, b"abc", b"de", 5) + budget.release(slow, 3) + budget.release(failed, 2) + assert (budget.used, slow["buffered"], failed["buffered"]) == (0, 0, 0) diff --git a/test/unit/test_flow_setup.py b/test/unit/test_flow_setup.py index d82644f..5610f54 100644 --- a/test/unit/test_flow_setup.py +++ b/test/unit/test_flow_setup.py @@ -91,6 +91,16 @@ def test_complete_config_does_not_mutate_defaults(complete_fn, defaults_dict): assert defaults_dict == before +def test_one_to_one_round_trips_only_in_client_config(tmp_config): + fs.save_config([{}], [{}, {"is_forward_one_to_one": True}]) + config = fs.load_existing_config() + assert "is_forward_one_to_one" not in config["servers"][0] + for saved, expected in zip(config["clients"], (False, True)): + assert saved["is_forward_one_to_one"] is expected + saved.update(is_extend_command=True, is_enable_encrypto=False) + assert fs.TCP_Client_Base(**saved).is_forward_one_to_one is expected + + def test_generate_configs_server(): args = argparse.Namespace( type=0, setup_addr_port="127.0.0.1:8080", connect_addr_port=None, setup_num=1