Skip to content

armgit / peach

Public Imported from GitHub
0

Peach: Local-first video metadata scraper and media manager.

fix(tray): 支持系统共享 Job 并完成单次独立交接

longmeidaob2bdb529b536
diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md
index 9ee3de5e8..9c3cda15c 100644
--- a/docs/OPERATIONS.md
+++ b/docs/OPERATIONS.md
@@ -376,9 +376,11 @@ curl -s --noproxy '*' -o /dev/null -w '%{http_code}\n' https://peach.local/healt
#### 刷新源码运行态:`restart_windows_tray.py`
-Windows 托盘独立于启动它的终端和智能体运行。启动、重启与异常恢复由当前会话的 Windows 桌面进程承接父身份;关闭 Codex、Claude 或终端不会停止托盘。直接从 Job 中运行托盘入口时,托盘在取得单实例锁和启动子服务前完成交接。数据根、源码路径和启动参数保持一致;未取得桌面进程或独立启动失败时明确报错,不在启动器的 Job 中继续运行。
+Windows 托盘独立于启动它的终端和智能体运行。启动、重启与异常恢复由当前会话的 Windows 桌面进程承接父身份;关闭 Codex、Claude 或终端不会停止托盘。入口先只读探测当前数据根的单实例锁;已有托盘时按启动参数打开页面或静默退出。首次启动从 Job 中交接时,父进程不占用单实例锁,新托盘取得锁后启动子服务。数据根、源码路径和启动参数保持一致;未取得桌面进程或 Windows 拒绝创建时明确报错,不在启动器的私有 Job 中继续运行。
-桌面进程可以处于允许脱离的 Job 中。托盘先挂起创建子进程,确认已脱离 Job 后才执行代码;仍继承 Job 时,回收这次子进程并显式请求脱离一次。若 Windows 拒绝请求,启动报告保留 `CreateProcessW(breakaway)` 与系统错误码;子进程不执行托盘代码,不创建服务或重复交接。
+桌面进程及托盘可以保留系统管理的共享 Job。子进程由 `PROC_THREAD_ATTRIBUTE_PARENT_PROCESS` 指定的桌面进程提供 Job 继承关系,独立性按关闭启动器私有 Job 后仍存活来验收。一次性交接标记由托盘入口消费,适用于源码、目录包及 onefile 引导进程;子服务不继承该标记。创建被拒绝时仅重试一次显式脱离,错误保留 API 与系统错误码。退出 Windows 会话及系统 Job 自身结束属于系统生命周期。
+
+独立启动取证记录调用者、桌面与子进程 PID 及 Job 成员状态、调用进程直接 Job 的原始限制值与已识别标志。失败上下文进入脱敏诊断报告;无法取得的 Job 句柄链和归属明确标为未取得,不推断 Job 所有者,也不要求管理员权限枚举系统句柄。
Windows 托盘在取得单实例锁后启动独立监视器。监视器用 Win32 进程句柄等待托盘退出,核对进程创建时间,避免 PID 复用;意外退出(包括未登记退出意图的零退出码)按 2、5、10 秒延迟恢复,5 分钟内至多 3 次。恢复保持当前数据根和源码入口,以静默模式启动。新托盘的监视器就绪后完成交接;导入或启动失败计入同一重试预算。手动启动的新实例会取消旧实例尚未执行的恢复。达到上限后保持停止,需检查日志后手动启动。
diff --git a/docs/REUSE.md b/docs/REUSE.md
index 40b06d6d5..0e9537908 100644
--- a/docs/REUSE.md
+++ b/docs/REUSE.md
@@ -46,9 +46,9 @@ Folia(`chthollyphile/folia-major`,AGPL-3.0,revision `9a01e788ed52d25ea01b1
## Windows 常驻托盘
-独立启动复用 Windows `CreateProcessW`、`STARTUPINFOEX` 与 [`PROC_THREAD_ATTRIBUTE_PARENT_PROCESS`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-updateprocthreadattribute),经标准库 `ctypes` 调用;父身份取当前会话的桌面进程。子进程挂起创建,确认不属于 Job 后才用 [`ResumeThread`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-resumethread) 执行;允许自动脱离的桌面 Job 直接通过,仍继承 Job 或创建被拒绝时再尝试一次 `CREATE_BREAKAWAY_FROM_JOB`。禁止脱离时回收未执行代码的子进程并保留系统错误。官方系统 API 无额外包、固定版本或第三方许可,适用于项目支持的 Windows,2026-10-15 核对。Peach 保留参数、数据根、源码与 PyInstaller 环境处理、单实例交接及启动验收。
+独立启动复用 Windows `CreateProcessW`、`STARTUPINFOEX` 与 [`PROC_THREAD_ATTRIBUTE_PARENT_PROCESS`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-updateprocthreadattribute),经标准库 `ctypes` 调用;父身份及 Job 继承来自当前会话的桌面进程。子进程可以保留系统共享 Job,验收判据为关闭启动器的私有 Job 后仍存活;[嵌套 Job](https://learn.microsoft.com/en-us/windows/win32/procthread/nested-jobs) 可能只允许部分脱离。子进程挂起创建,记录归属后以 `ResumeThread` 执行;创建被拒绝时仅重试一次 `CREATE_BREAKAWAY_FROM_JOB`,恢复主线程失败时回收未执行的子进程。官方系统 API 无额外包、固定版本或第三方许可,适用于项目支持的 Windows,2026-10-15 核对。Peach 保留参数、数据根、源码与 PyInstaller 环境处理,并消费一次性交接标记。入口先复用 `SingleInstance` 的只读锁探测,已运行时直接打开页面;锁探测不创建文件,不阻塞子进程取得锁。
-当前树与 Git 历史已有 `windows_restart`、`tray_lifecycle` 和 `process_job`,继续复用各自的重启、恢复及子服务清理行为。`DETACHED_PROCESS` 只脱离控制台;`CREATE_BREAKAWAY_FROM_JOB` 依赖所选父进程的 Job 允许脱离;[`Win32_Process.Create`](https://learn.microsoft.com/en-us/windows/win32/cimwin32prov/create-method-in-class-win32-process) 额外引入 WMI 命令、环境交接及服务自身 Job 配额,未采用;`pywin32` 不属于运行依赖,监视器又必须只加载标准库,因此采用原生 API,无新增依赖。源码托盘直接调用基础解释器,按 [CPython 3.14.7 venv 启动器](https://github.com/python/cpython/blob/v3.14.7/PC/venvlauncher.c) 的 `__PYVENV_LAUNCHER__` 协议保留虚拟环境身份,避免 venv 启动器自己的 kill-on-close Job 导致重复交接。仅参照协议,没有复制 PSF 许可源码。临时 Job 回归覆盖启动器禁止脱离、桌面允许自动或显式脱离、桌面禁止脱离三类情况:普通子进程随启动器退出,独立子进程保持运行,受限子进程不执行代码且被完整回收;同时核对 Unicode 参数、环境、工作目录、虚拟环境身份和实际解释器的 Job,并清理全部测试进程。真实 Explorer 不加入测试 Job。
+当前树与 Git 历史已有 `windows_restart`、`tray_lifecycle` 和 `process_job`,继续复用各自的重启、恢复及子服务清理行为。`DETACHED_PROCESS` 只脱离控制台;`CREATE_BREAKAWAY_FROM_JOB` 依赖所选父进程的 Job 允许脱离;WMI、Shell COM 与计划任务额外引入服务、环境交接或注册生命周期,未采用;`pywin32` 不属于运行依赖,监视器又必须只加载标准库,因此采用原生 API,无新增依赖。源码托盘直接调用基础解释器,按 [CPython 3.14.7 venv 启动器](https://github.com/python/cpython/blob/v3.14.7/PC/venvlauncher.c) 的 `__PYVENV_LAUNCHER__` 协议保留虚拟环境身份。仅参照协议,没有复制 PSF 许可源码。临时进程回归覆盖多层共享 Job、内层自动脱离与启动器私有 kill-on-close Job:普通子进程随启动器退出,桌面子进程仍在共享 Job 中存活,并消费交接标记。另核对 Unicode 参数、环境、工作目录、虚拟环境身份与进程清理;真实 Explorer 不加入测试 Job。诊断只记录可取得的进程成员状态和调用进程直接 Job 的原始限制值,位定义复用 [Microsoft 文档](https://learn.microsoft.com/en-us/windows/win32/api/winnt/ns-winnt-jobobject_basic_limit_information);完整句柄链与所有者未取得时明确标记,不通过全系统提权扫描推断。
## 西方人像与官方封面
diff --git a/src/peach/error_reporting.py b/src/peach/error_reporting.py
index 6769eb432..9b8436b18 100644
--- a/src/peach/error_reporting.py
+++ b/src/peach/error_reporting.py
@@ -103,7 +103,8 @@ def exception_facts(error: BaseException) -> dict:
seen.add(id(current))
chain.append({"type": type(current).__name__, "message": redact(str(current))[:4000],
"winerror": getattr(current, "winerror", None), "errno": getattr(current, "errno", None),
- "operation": getattr(current, "peach_operation", None)})
+ "operation": getattr(current, "peach_operation", None),
+ "context": getattr(current, "peach_context", None)})
for frame in traceback.extract_tb(current.__traceback__)[-40:]:
frames.append({"file": Path(frame.filename).name, "line": frame.lineno, "function": frame.name})
current = current.__cause__ or (None if current.__suppress_context__ else current.__context__)
diff --git a/src/peach/tray.py b/src/peach/tray.py
index 7fd60af14..e925f012b 100644
--- a/src/peach/tray.py
+++ b/src/peach/tray.py
@@ -6,6 +6,7 @@ if __name__ == "__main__":
import argparse
import ctypes
+import errno
import json
import logging
import os
@@ -171,6 +172,28 @@ class SingleInstance:
else:
self._acquire_posix()
+ def is_running(self) -> bool:
+ """只读探测现有锁;探测结束即释放,不创建文件或接管实例。"""
+ try:
+ handle = self.path.open("rb")
+ except FileNotFoundError:
+ return False
+ with handle:
+ try:
+ if os.name == "nt":
+ import msvcrt
+ msvcrt.locking(handle.fileno(), msvcrt.LK_NBRLCK, 1)
+ msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+ else:
+ import fcntl
+ fcntl.flock(handle.fileno(), fcntl.LOCK_SH | fcntl.LOCK_NB)
+ fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+ except OSError as error:
+ if error.errno in (errno.EACCES, errno.EAGAIN, errno.EDEADLK):
+ return True
+ raise
+ return False
+
def _acquire_posix(self) -> None:
import fcntl
@@ -1687,6 +1710,14 @@ def _main(argv: list[str] | None = None) -> int:
# 单实例锁和目录创建之前退出,否则一条试探命令就会在磁盘上凭空造出一个数据根,
# 让之后的安装探测把这台机器误判成已配置。
args = build_parser().parse_args(argv)
+ config = settings_file.load_config()
+ error_reporting.install(config.directory("logs"))
+ waiting = needs_setup(config)
+ instance = SingleInstance(config.directory("state") / "peach-tray.lock")
+ if instance.is_running():
+ if not args.silent:
+ webbrowser.open(setup_url(config) if waiting else normal_url(config))
+ return 0
try:
if handoff_tray(sys.argv[1:] if argv is None else argv, PROJECT_ROOT):
return 0
@@ -1697,12 +1728,6 @@ def _main(argv: list[str] | None = None) -> int:
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
logging.getLogger().setLevel(logging.INFO)
enable_hidpi()
- # 设置文件新鲜读一次。`config.py` 的常量是 import 期算的,而首次设置正要改变它们
- # 指向的数据根;这里只用它判断该起哪一组服务,之后由 `SetupGate` 接手。
- config = settings_file.load_config()
- error_reporting.install(config.directory("logs"))
- waiting = needs_setup(config)
- instance = SingleInstance(config.directory("state") / "peach-tray.lock")
manager = None
lifecycle = None
exit_code = 1
diff --git a/src/peach/tray_detached.py b/src/peach/tray_detached.py
index e8677e754..65b5cd2af 100644
--- a/src/peach/tray_detached.py
+++ b/src/peach/tray_detached.py
@@ -1,4 +1,4 @@
-"""Windows 桌面进程启动常驻托盘,不继承终端或智能体的 Job。"""
+"""通过 Windows 桌面父身份启动常驻托盘,独立于启动器的私有 Job。"""
from __future__ import annotations
import ctypes
@@ -9,6 +9,14 @@ from ctypes import wintypes
from pathlib import Path
_CREATE_SUSPENDED = 0x00000004
+_HANDOFF_ENV = "PEACH_TRAY_DESKTOP_HANDOFF"
+
+
+class _JobBasicLimits(ctypes.Structure):
+ _fields_ = [("times", ctypes.c_longlong * 2), ("flags", wintypes.DWORD),
+ ("working_set", ctypes.c_size_t * 2), ("active_limit", wintypes.DWORD),
+ ("affinity", ctypes.c_size_t), ("priority", wintypes.DWORD),
+ ("scheduling", wintypes.DWORD)]
class _StartupInfo(ctypes.Structure):
@@ -51,6 +59,8 @@ def _kernel():
wintypes.LPVOID, wintypes.LPCWSTR, ctypes.POINTER(_StartupInfoEx),
ctypes.POINTER(_ProcessInfo)]),
"ResumeThread": (wintypes.DWORD, [wintypes.HANDLE]),
+ "QueryInformationJobObject": (wintypes.BOOL, [wintypes.HANDLE, ctypes.c_int,
+ wintypes.LPVOID, wintypes.DWORD, wintypes.LPVOID]),
}
for name, (result, arguments) in signatures.items():
function = getattr(kernel, name)
@@ -58,9 +68,9 @@ def _kernel():
return kernel
-def _in_job(kernel, handle) -> bool:
+def _in_job(kernel, handle, job=None) -> bool:
result = wintypes.BOOL()
- if not kernel.IsProcessInJob(handle, None, ctypes.byref(result)):
+ if not kernel.IsProcessInJob(handle, job, ctypes.byref(result)):
raise _windows_error("IsProcessInJob")
return bool(result.value)
@@ -79,7 +89,8 @@ def in_job() -> bool:
def handoff_tray(arguments, root) -> bool:
"""托盘取得单实例锁前完成独立启动;保留参数、数据根与源码路径。"""
- if not in_job():
+ handed_off = os.environ.pop(_HANDOFF_ENV, None) == "1"
+ if handed_off or not in_job():
return False
environment = os.environ.copy()
environment["PYINSTALLER_RESET_ENVIRONMENT"] = "1"
@@ -127,8 +138,29 @@ class DetachedProcess:
self.close()
-def _create_verified(kernel, executable, argv, cwd, block, startup, flags):
- """挂起创建,在用户代码执行前验收 Job 归属,再恢复主线程。"""
+def _job_facts(kernel, handle, *, current=False):
+ """记录已知进程的 Job 归属;限制查询只适用于调用进程的直接 Job。"""
+ facts = {}
+ try:
+ member = _in_job(kernel, handle)
+ facts = {"in_job": member}
+ if current and member:
+ limits = _JobBasicLimits()
+ if not kernel.QueryInformationJobObject(None, 2, ctypes.byref(limits), ctypes.sizeof(limits), None):
+ raise _windows_error("QueryInformationJobObject(current)")
+ facts["immediate_limit_flags"] = hex(limits.flags)
+ facts["immediate_limit_names"] = [name for flag, name in (
+ (0x0400, "DIE_ON_UNHANDLED_EXCEPTION"), (0x0800, "BREAKAWAY_OK"),
+ (0x1000, "SILENT_BREAKAWAY_OK"), (0x2000, "KILL_ON_JOB_CLOSE"),
+ (0x4000, "SUBSET_AFFINITY")) if limits.flags & flag]
+ return facts
+ except OSError as error:
+ return {**facts, "status": "unavailable", "winerror": getattr(error, "winerror", None),
+ "operation": getattr(error, "peach_operation", None)}
+
+
+def _create_child(kernel, executable, argv, cwd, block, startup, flags, context):
+ """按桌面父身份挂起创建,记录归属后恢复主线程。"""
child = _ProcessInfo()
command = ctypes.create_unicode_buffer(subprocess.list2cmdline([os.fspath(a) for a in argv]))
if not kernel.CreateProcessW(str(executable), command, None, None, False,
@@ -139,8 +171,7 @@ def _create_verified(kernel, executable, argv, cwd, block, startup, flags):
process = DetachedProcess(child.hProcess, child.dwProcessId)
verified = False
try:
- if _in_job(kernel, child.hProcess):
- return None
+ context["child"] = {"pid": process.pid, **_job_facts(kernel, child.hProcess)}
if kernel.ResumeThread(child.hThread) == 0xFFFFFFFF:
raise _windows_error("ResumeThread")
verified = True
@@ -173,16 +204,28 @@ def launch_detached(argv, *, cwd, env=None) -> DetachedProcess:
environment["__PYVENV_LAUNCHER__"] = str(executable.resolve())
executable = Path(home) / executable.name
kernel = _kernel()
+ context = {"caller": {"pid": os.getpid(), **_job_facts(kernel, wintypes.HANDLE(-1), current=True)},
+ "parent_source": "Windows desktop",
+ "job_chain": {"status": "unavailable", "reason": "未取得各层 Job 句柄与归属;仅记录已知进程和直接 Job"}}
user = ctypes.WinDLL("user32", use_last_error=True)
user.GetShellWindow.restype = wintypes.HWND
user.GetWindowThreadProcessId.argtypes = [wintypes.HWND, ctypes.POINTER(wintypes.DWORD)]
shell = user.GetShellWindow()
pid = wintypes.DWORD()
if not shell or not user.GetWindowThreadProcessId(shell, ctypes.byref(pid)):
- raise OSError("未取得当前会话的 Windows 桌面进程")
+ error = OSError("未取得当前会话的 Windows 桌面进程,请确认已登录 Windows 桌面")
+ error.peach_context = context
+ raise error
+ context["desktop"] = {"pid": pid.value}
parent = kernel.OpenProcess(0x0080 | 0x1000, False, pid.value)
if not parent:
- raise _windows_error("OpenProcess(desktop)")
+ error = _windows_error("OpenProcess(desktop)")
+ error.peach_context = context
+ raise error
+ context["desktop"].update(_job_facts(kernel, parent))
+ # 标记由桌面父身份创建的这一跳;托盘入口消费后不向普通子服务传播。
+ # PyInstaller onefile 的引导进程会把环境传给实际应用进程。
+ environment[_HANDOFF_ENV] = "1"
initialized = False
try:
size = ctypes.c_size_t()
@@ -204,17 +247,22 @@ def launch_detached(argv, *, cwd, env=None) -> DetachedProcess:
) + "\0\0")
flags = 0x00080000 | 0x00000400 | subprocess.DETACHED_PROCESS
try:
- process = _create_verified(kernel, executable, argv, cwd, block, startup, flags)
+ process = _create_child(kernel, executable, argv, cwd, block, startup, flags, context)
except OSError as error:
if getattr(error, "winerror", None) != 5 or getattr(error, "peach_operation", "") != "CreateProcessW":
raise
- process = None
- if process is None:
- process = _create_verified(kernel, executable, argv, cwd, block, startup,
- flags | subprocess.CREATE_BREAKAWAY_FROM_JOB)
- if process is None:
- raise OSError(f"托盘进程仍受 Windows Job 约束,独立启动未成立(桌面 PID:{pid.value})")
+ context["retry"] = "CREATE_BREAKAWAY_FROM_JOB"
+ process = _create_child(kernel, executable, argv, cwd, block, startup,
+ flags | subprocess.CREATE_BREAKAWAY_FROM_JOB, context)
+ try:
+ from .error_reporting import event
+ event("tray-detached", context=context)
+ except Exception:
+ pass
return process
+ except OSError as error:
+ error.peach_context = context
+ raise
finally:
if initialized:
kernel.DeleteProcThreadAttributeList(attributes)
diff --git a/tests/test_error_reporting.py b/tests/test_error_reporting.py
index 0a3c6e4e8..d482efb84 100644
--- a/tests/test_error_reporting.py
+++ b/tests/test_error_reporting.py
@@ -76,6 +76,24 @@ class ErrorReportingTests(unittest.TestCase):
self.assertEqual(path.parent, fallback)
self.assertTrue(path.is_file())
+ def test_shared_job_failure_context_is_preserved_in_the_redacted_report(self):
+ error = OSError("desktop process creation denied")
+ error.peach_operation = "CreateProcessW(breakaway)"
+ error.peach_context = {
+ "caller": {"pid": 123, "in_job": True, "immediate_limit_flags": "0x2000",
+ "immediate_limit_names": ["KILL_ON_JOB_CLOSE"]},
+ "desktop": {"pid": 456, "in_job": True},
+ "job_chain": {"status": "unavailable"}, "token": "private-job-token"}
+ error_reporting.event("tray-handoff", error)
+ with zipfile.ZipFile(io.BytesIO(support_bundle.bundle_bytes())) as archive:
+ name = next(name for name in archive.namelist() if 'errors-' in name)
+ payload = archive.read(name).decode()
+ context = json.loads(payload)["exception"][0]["context"]
+ self.assertEqual(context["caller"], error.peach_context["caller"])
+ self.assertEqual(context["desktop"], {"pid": 456, "in_job": True})
+ self.assertEqual(context["job_chain"]["status"], "unavailable")
+ self.assertNotIn("private-job-token", payload)
+
def test_bundle_is_available_with_corrupt_configuration_and_excludes_private_files(self):
(self.root / "config.toml").write_text('secret = "unclosed-private-config', encoding="utf-8")
(self.root / "ledger.db").write_text("private-database", encoding="utf-8")
diff --git a/tests/test_tray.py b/tests/test_tray.py
index 42e1b7735..0ec30f9c7 100644
--- a/tests/test_tray.py
+++ b/tests/test_tray.py
@@ -656,7 +656,7 @@ class LogRetentionAtStartupTests(unittest.TestCase):
with mock.patch.object(tray, "handoff_tray", return_value=False), \
mock.patch.object(tray.settings_file, "load_config", return_value=config), \
mock.patch.object(tray.error_reporting, "install"), \
- mock.patch.object(tray, "SingleInstance"), \
+ mock.patch.object(tray, "SingleInstance") as instance, \
mock.patch.object(tray, "Lifecycle"), \
mock.patch.object(tray.log_retention, "sweep", side_effect=sweep), \
mock.patch.object(tray, "log_to_file"), \
@@ -666,6 +666,7 @@ class LogRetentionAtStartupTests(unittest.TestCase):
mock.patch.object(tray, "tray_preparation"), \
mock.patch.object(tray, "show_message"), \
self.assertLogs(level="WARNING"):
+ instance.return_value.is_running.return_value = False
self.assertEqual(tray_main(["--silent"]), 0)
self.assertEqual(events, ["sweep", "manager", "run"])
diff --git a/tests/test_tray_detached.py b/tests/test_tray_detached.py
index b7b3ffb60..18ace2be7 100644
--- a/tests/test_tray_detached.py
+++ b/tests/test_tray_detached.py
@@ -30,36 +30,139 @@ class _JobLimits(ctypes.Structure):
("memory", ctypes.c_size_t * 4)]
-class _JobAccounting(ctypes.Structure):
- _fields_ = [("times", ctypes.c_longlong * 4), ("page_faults", wintypes.DWORD),
- ("total", wintypes.DWORD), ("active", wintypes.DWORD),
- ("terminated", wintypes.DWORD)]
-
-
class DetachedLaunchTests(unittest.TestCase):
+ def setUp(self):
+ events = mock.patch("peach.error_reporting.event")
+ self.events = events.start()
+ self.addCleanup(events.stop)
+
def test_source_sync_restarts_for_detachment_and_lifecycle_changes(self):
from peach.tray import tray_restart_required
for path in ("src/peach/tray_detached.py", "src/peach/tray_lifecycle.py"):
with self.subTest(path=path):
self.assertTrue(tray_restart_required((path,)))
- def test_tray_handoff_precedes_the_single_instance_lock(self):
+ def test_tray_handoff_leaves_the_single_instance_lock_for_the_child(self):
from peach.tray import main
with mock.patch("peach.tray.handoff_tray", return_value=True) as handoff, \
- mock.patch("peach.tray.SingleInstance") as instance:
+ mock.patch("peach.tray.SingleInstance") as instance, \
+ mock.patch("peach.tray.settings_file.load_config"), \
+ mock.patch("peach.tray.error_reporting.install"), \
+ mock.patch("peach.tray.needs_setup", return_value=False):
+ instance.return_value.is_running.return_value = False
self.assertEqual(main(["--silent"]), 0)
self.assertEqual(handoff.call_args.args[0], ["--silent"])
- instance.assert_not_called()
+ instance.return_value.acquire.assert_not_called()
+
+ def test_existing_tray_opens_its_page_without_attempting_handoff(self):
+ from peach.tray import main
+ for waiting, silent in ((False, False), (True, False), (False, True)):
+ with self.subTest(waiting=waiting, silent=silent), \
+ mock.patch("peach.tray.handoff_tray", side_effect=OSError("desktop denied")) as handoff, \
+ mock.patch("peach.tray.SingleInstance") as instance, \
+ mock.patch("peach.tray.settings_file.load_config") as config, \
+ mock.patch("peach.tray.error_reporting.install"), \
+ mock.patch("peach.tray.error_reporting.failure_details", return_value="desktop denied"), \
+ mock.patch("peach.tray.show_message"), \
+ mock.patch("peach.tray.needs_setup", return_value=waiting), \
+ mock.patch("peach.tray.normal_url", return_value="https://peach.invalid") as normal, \
+ mock.patch("peach.tray.setup_url", return_value="http://peach.invalid/setup") as setup, \
+ mock.patch("peach.tray.webbrowser.open") as browser:
+ instance.return_value.is_running.return_value = True
+ self.assertEqual(main(["--silent"] if silent else ["--show"]), 0)
+ handoff.assert_not_called()
+ instance.return_value.acquire.assert_not_called()
+ if silent:
+ browser.assert_not_called()
+ else:
+ browser.assert_called_once_with("http://peach.invalid/setup" if waiting else "https://peach.invalid")
+ (setup if waiting else normal).assert_called_once_with(config.return_value)
def test_failed_handoff_stops_before_services_or_state_are_created(self):
from peach.tray import main
with mock.patch("peach.tray.handoff_tray", side_effect=OSError("desktop unavailable")), \
mock.patch("peach.tray.error_reporting.failure_details", return_value="desktop unavailable"), \
mock.patch("peach.tray.show_message") as message, \
- mock.patch("peach.tray.SingleInstance") as instance:
+ mock.patch("peach.tray.SingleInstance") as instance, \
+ mock.patch("peach.tray.settings_file.load_config"), \
+ mock.patch("peach.tray.error_reporting.install"), \
+ mock.patch("peach.tray.needs_setup", return_value=False):
+ instance.return_value.is_running.return_value = False
self.assertEqual(main(["--silent"]), 1)
self.assertIn("desktop unavailable", message.call_args.args[1])
- instance.assert_not_called()
+ instance.return_value.acquire.assert_not_called()
+
+ def test_handoff_marker_is_consumed_once_even_in_a_system_job(self):
+ with mock.patch.dict(os.environ, {"PEACH_TRAY_DESKTOP_HANDOFF": "1"}), \
+ mock.patch.object(tray_detached, "in_job", return_value=True), \
+ mock.patch.object(tray_detached, "launch_detached") as launch:
+ self.assertFalse(tray_detached.handoff_tray([], ROOT))
+ self.assertNotIn("PEACH_TRAY_DESKTOP_HANDOFF", os.environ)
+ launch.assert_not_called()
+ self.assertTrue(tray_detached.handoff_tray([], ROOT))
+ launch.assert_called_once()
+
+ def test_instance_probe_is_read_only_and_does_not_hold_the_lock(self):
+ from peach.tray import SingleInstance
+ with tempfile.TemporaryDirectory() as directory:
+ path = Path(directory).resolve() / "state" / "tray.lock"
+ first, second = SingleInstance(path), SingleInstance(path)
+ self.assertFalse(second.is_running())
+ self.assertFalse(path.parent.exists())
+ first.acquire()
+ try:
+ self.assertTrue(second.is_running())
+ finally:
+ first.close()
+ content = path.read_bytes()
+ self.assertFalse(second.is_running())
+ self.assertEqual(path.read_bytes(), content)
+ second.acquire()
+ second.close()
+
+ def test_job_flag_names_follow_windows_limit_values(self):
+ kernel = mock.Mock()
+
+ def query(_job, _kind, output, _size, _returned):
+ ctypes.cast(output, ctypes.POINTER(tray_detached._JobBasicLimits)).contents.flags = 0x3800
+ return 1
+
+ kernel.QueryInformationJobObject.side_effect = query
+ with mock.patch.object(tray_detached, "_in_job", return_value=True):
+ facts = tray_detached._job_facts(kernel, -1, current=True)
+ self.assertEqual(facts["immediate_limit_flags"], "0x3800")
+ self.assertEqual(facts["immediate_limit_names"],
+ ["BREAKAWAY_OK", "SILENT_BREAKAWAY_OK", "KILL_ON_JOB_CLOSE"])
+
+ @unittest.skipUnless(os.name == "nt", "Windows 挂起创建与线程恢复")
+ def test_resume_failure_reaps_the_child_and_keeps_diagnostic_context(self):
+ with tempfile.TemporaryDirectory() as directory:
+ root = Path(directory).resolve()
+ marker = root / "executed"
+ kernel = tray_detached._kernel()
+ failing = mock.Mock(wraps=kernel)
+
+ def resume(_thread):
+ ctypes.set_last_error(31)
+ return 0xFFFFFFFF
+
+ failing.ResumeThread.side_effect = resume
+ with mock.patch.object(tray_detached, "_kernel", return_value=failing):
+ with self.assertRaises(OSError) as raised:
+ tray_detached.launch_detached([sys._base_executable, '-c',
+ 'from pathlib import Path; import sys; Path(sys.argv[1]).touch()', str(marker)], cwd=root)
+ self.assertEqual(raised.exception.peach_operation, "ResumeThread")
+ self.assertEqual(raised.exception.winerror, 31)
+ self.assertIn("desktop", raised.exception.peach_context)
+ self.assertFalse(marker.exists())
+ pid = raised.exception.peach_context["child"]["pid"]
+ handle = kernel.OpenProcess(0x00100000 | 0x1000, False, pid)
+ if handle:
+ process = tray_detached.DetachedProcess(handle, pid)
+ try:
+ self.assertEqual(process.wait(timeout=5), 1)
+ finally:
+ process.close()
def test_source_handoff_preserves_arguments_and_environment(self):
child = mock.Mock()
@@ -139,6 +242,8 @@ time.sleep(60)
self.assertTrue(handle)
handles.append(tray_detached.DetachedProcess(handle, pid))
control, child = handles
+ self.assertTrue(tray_detached._in_job(kernel, control._handle, job))
+ self.assertFalse(tray_detached._in_job(kernel, child._handle, job))
with self.assertRaises(subprocess.TimeoutExpired):
child.wait(timeout=.01)
close_job(job)
@@ -146,12 +251,10 @@ time.sleep(60)
worker.wait(timeout=10)
control.wait(timeout=10)
self.assertIsNone(child.poll(), "独立托盘子进程必须存活")
- self.assertFalse(tray_detached._in_job(kernel, child._handle))
payload = json.loads((root / "child.json").read_text(encoding="utf-8"))
self.assertEqual(payload[:2], [str(root), "测试 env"])
self.assertEqual(payload[2], '引号 " 和 \\ 路径')
self.assertEqual(payload[3:5], [sys.executable, sys.prefix])
- self.assertFalse(payload[5], "实际解释器必须独立于 venv 启动器的 Job")
child.terminate()
self.assertEqual(child.wait(timeout=10), 1)
finally:
@@ -166,74 +269,64 @@ time.sleep(60)
process.close()
@unittest.skipUnless(os.name == "nt", "Windows 桌面 Job 的实际继承与脱离")
- def test_child_escapes_desktop_jobs_that_allow_automatic_or_explicit_breakaway(self):
- for flags in (0x1000, 0x0800):
+ def test_children_can_share_desktop_jobs_with_various_breakaway_policies(self):
+ for flags in (0, 0x1000, 0x0800):
with self.subTest(flags=hex(flags)):
- self._desktop_job_launch(flags, allowed=True)
+ self._desktop_job_launch(flags)
- @unittest.skipUnless(os.name == "nt", "Windows 桌面 Job 的实际继承与脱离")
- def test_restricted_desktop_job_never_executes_the_child(self):
- self._desktop_job_launch(0, allowed=False)
+ def _job(self, flags):
+ job = create_kill_on_close_job()
+ self.assertIsNotNone(job)
+ kernel = tray_detached._kernel()
+ kernel.SetInformationJobObject.argtypes = [wintypes.HANDLE, ctypes.c_int,
+ wintypes.LPVOID, wintypes.DWORD]
+ limits = _JobLimits()
+ limits.basic.flags = flags
+ self.assertTrue(kernel.SetInformationJobObject(job, 9, ctypes.byref(limits), ctypes.sizeof(limits)))
+ return job
- def _desktop_job_launch(self, flags, *, allowed):
+ @staticmethod
+ def _desktop_dll(desktop):
+ user = mock.Mock()
+ user.GetShellWindow.return_value = 1
+
+ def desktop_pid(_window, output):
+ ctypes.cast(output, ctypes.POINTER(wintypes.DWORD)).contents.value = desktop.pid
+ return 1
+
+ user.GetWindowThreadProcessId.side_effect = desktop_pid
+ native_dll = ctypes.WinDLL
+ return lambda name, *args, **kwargs: user if name == "user32" else native_dll(name, *args, **kwargs)
+
+ def _desktop_job_launch(self, flags):
with tempfile.TemporaryDirectory() as directory:
root = Path(directory).resolve()
- job = create_kill_on_close_job()
- self.assertIsNotNone(job)
+ job = self._job(0x2000 | flags)
kernel = tray_detached._kernel()
- kernel.SetInformationJobObject.argtypes = [wintypes.HANDLE, ctypes.c_int,
- wintypes.LPVOID, wintypes.DWORD]
- limits = _JobLimits()
- limits.basic.flags = 0x2000 | flags
- self.assertTrue(kernel.SetInformationJobObject(job, 9, ctypes.byref(limits), ctypes.sizeof(limits)))
desktop = child = None
try:
desktop = tray_detached.launch_detached(
[sys._base_executable, "-c", "import time; time.sleep(60)"], cwd=root)
assign_to_job(job, desktop)
self.assertTrue(tray_detached._in_job(kernel, desktop._handle))
- user = mock.Mock()
- user.GetShellWindow.return_value = 1
-
- def desktop_pid(_window, output):
- ctypes.cast(output, ctypes.POINTER(wintypes.DWORD)).contents.value = desktop.pid
- return 1
-
- user.GetWindowThreadProcessId.side_effect = desktop_pid
- native_dll = ctypes.WinDLL
-
- def load_dll(name, *args, **kwargs):
- return user if name == "user32" else native_dll(name, *args, **kwargs)
-
marker = root / "executed"
code = "from pathlib import Path; import sys, time; Path(sys.argv[1]).touch(); time.sleep(60)"
- with mock.patch.object(ctypes, "WinDLL", side_effect=load_dll):
- if allowed:
- child = tray_detached.launch_detached(
- [sys._base_executable, "-c", code, str(marker)], cwd=root)
- else:
- with self.assertRaises(OSError):
- tray_detached.launch_detached([sys._base_executable, "-c", code, str(marker)], cwd=root)
- if allowed:
- deadline = time.monotonic() + 10
- while not marker.exists() and time.monotonic() < deadline:
- self.assertIsNone(child.poll())
- time.sleep(.05)
- self.assertTrue(marker.exists(), "通过独立性检查后应执行子进程")
- self.assertFalse(tray_detached._in_job(kernel, child._handle))
- close_job(job)
- job = None
- desktop.wait(timeout=10)
- self.assertIsNone(child.poll(), "关闭桌面 Job 后独立子进程必须存活")
+ with mock.patch.object(ctypes, "WinDLL", side_effect=self._desktop_dll(desktop)):
+ child = tray_detached.launch_detached(
+ [sys._base_executable, "-c", code, str(marker)], cwd=root)
+ deadline = time.monotonic() + 10
+ while not marker.exists() and time.monotonic() < deadline:
+ self.assertIsNone(child.poll())
+ time.sleep(.05)
+ self.assertTrue(marker.exists(), "桌面 Job 内的子进程应执行")
+ self.assertEqual(tray_detached._in_job(kernel, child._handle, job), not bool(flags & 0x1000))
+ close_job(job)
+ job = None
+ desktop.wait(timeout=10)
+ if flags & 0x1000:
+ self.assertIsNone(child.poll())
else:
- self.assertFalse(marker.exists(), "受限子进程必须在执行代码前停止")
- kernel.QueryInformationJobObject.argtypes = [wintypes.HANDLE, ctypes.c_int,
- wintypes.LPVOID, wintypes.DWORD, wintypes.LPVOID]
- accounting = _JobAccounting()
- self.assertTrue(kernel.QueryInformationJobObject(
- job, 1, ctypes.byref(accounting), ctypes.sizeof(accounting), None))
- self.assertGreaterEqual(accounting.total, 2, "必须按实际子进程结果判断独立性")
- self.assertEqual(accounting.active, 1, "拒绝的子进程必须完整回收")
+ child.wait(timeout=10)
finally:
close_job(job)
for process in (child, desktop):
@@ -249,6 +342,118 @@ time.sleep(60)
process.close()
+NESTED_WORKER = """
+import ctypes, json, os, subprocess, sys, time
+from ctypes import wintypes
+from pathlib import Path
+from unittest.mock import Mock, patch
+from peach.tray_detached import launch_detached
+root = Path(sys.argv[1])
+os.environ.pop('PEACH_TRAY_DESKTOP_HANDOFF', None)
+deadline = time.monotonic() + 20
+while not (root / 'go').exists():
+ if time.monotonic() > deadline:
+ raise TimeoutError('gate')
+ time.sleep(.05)
+control = subprocess.Popen([sys._base_executable, '-c', 'import time; time.sleep(60)'],
+ stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+ creationflags=subprocess.CREATE_NO_WINDOW)
+user = Mock()
+user.GetShellWindow.return_value = 1
+def desktop_pid(window, output):
+ ctypes.cast(output, ctypes.POINTER(wintypes.DWORD)).contents.value = int(sys.argv[2])
+ return 1
+user.GetWindowThreadProcessId.side_effect = desktop_pid
+native_dll = ctypes.WinDLL
+def dll(name, *args, **kwargs):
+ return user if name == 'user32' else native_dll(name, *args, **kwargs)
+with patch.object(ctypes, 'WinDLL', side_effect=dll):
+ child = launch_detached([sys.executable, '-c', sys.argv[3], str(root)], cwd=root)
+(root / 'pids.json').write_text(json.dumps([control.pid, child.pid]))
+time.sleep(60)
+"""
+
+NESTED_CHILD = """
+import json, os, sys, time
+from pathlib import Path
+from unittest.mock import patch
+from peach.tray_detached import handoff_tray, in_job
+root = Path(sys.argv[1])
+with patch('peach.tray_detached.launch_detached', side_effect=RuntimeError('repeated handoff')):
+ handed_off = handoff_tray([], root)
+(root / 'child.json').write_text(json.dumps(dict(in_job=in_job(), handed_off=handed_off,
+ marker_consumed='PEACH_TRAY_DESKTOP_HANDOFF' not in os.environ)))
+time.sleep(60)
+"""
+
+
[email protected](os.name == "nt", "Windows 多层 Job 的实际继承与关闭")
+class NestedJobTests(unittest.TestCase):
+ _job = DetachedLaunchTests._job
+ setUp = DetachedLaunchTests.setUp
+
+ def test_child_shares_system_jobs_and_survives_its_launcher_job_closing(self):
+ with tempfile.TemporaryDirectory() as directory:
+ root = Path(directory).resolve()
+ jobs = [self._job(flags) for flags in (0x2000, 0x2000, 0x3800, 0x2000)]
+ processes = []
+ try:
+ desktop = tray_detached.launch_detached(
+ [sys._base_executable, '-c', 'import time; time.sleep(60)'], cwd=root)
+ processes.append(desktop)
+ for job in jobs[:3]:
+ assign_to_job(job, desktop)
+ worker = tray_detached.launch_detached(
+ [sys._base_executable, '-c', NESTED_WORKER, str(root), str(desktop.pid), NESTED_CHILD],
+ cwd=root, env={**os.environ, "PYTHONPATH": str(ROOT / "src"), "PEACH_DATA_ROOT": str(root)})
+ processes.append(worker)
+ for job in (jobs[0], jobs[1], jobs[3]):
+ assign_to_job(job, worker)
+ kernel = tray_detached._kernel()
+ self.assertTrue(tray_detached._in_job(kernel, worker._handle, jobs[3]))
+ (root / 'go').touch()
+ self._wait_for_nested_child(root, worker)
+ for pid in json.loads((root / 'pids.json').read_text()):
+ handle = kernel.OpenProcess(0x00100000 | 0x1000 | 0x0001, False, pid)
+ self.assertTrue(handle)
+ processes.append(tray_detached.DetachedProcess(handle, pid))
+ control, child = processes[-2:]
+ self.assertTrue(tray_detached._in_job(kernel, child._handle, jobs[1]))
+ self.assertTrue(tray_detached._in_job(kernel, control._handle, jobs[3]))
+ self.assertFalse(tray_detached._in_job(kernel, child._handle, jobs[3]))
+ close_job(jobs.pop())
+ worker.wait(timeout=10)
+ control.wait(timeout=10)
+ self.assertIsNone(child.poll(), "退出启动器的私有 Job 后托盘必须存活")
+ self.assertEqual(json.loads((root / 'child.json').read_text()),
+ dict(in_job=True, handed_off=False, marker_consumed=True))
+ records = [json.loads(line) for path in (root / 'logs').glob('errors-*.log')
+ for line in path.read_text(encoding='utf-8').splitlines()]
+ context = next(row['context'] for row in records if row['stage'] == 'tray-detached')
+ self.assertEqual(context['caller']['immediate_limit_flags'], '0x2000')
+ self.assertEqual(context['caller']['immediate_limit_names'], ['KILL_ON_JOB_CLOSE'])
+ self.assertTrue(context['desktop']['in_job'])
+ self.assertTrue(context['child']['in_job'])
+ finally:
+ for job in reversed(jobs):
+ close_job(job)
+ for process in processes:
+ try:
+ process.wait(timeout=5)
+ except subprocess.TimeoutExpired:
+ process.terminate()
+ process.wait(timeout=10)
+ finally:
+ process.close()
+
+ def _wait_for_nested_child(self, root, worker):
+ deadline = time.monotonic() + 20
+ while not (root / 'child.json').exists() or not (root / 'pids.json').exists():
+ self.assertIsNone(worker.poll(), "多层 Job 启动器失败")
+ self.assertLess(time.monotonic(), deadline, "多层 Job 托盘未就绪")
+ time.sleep(.05)
+
+
if __name__ == "__main__":
unittest.main()