headless-reaper 0.1.0__py3-none-win_amd64.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,23 @@
1
+ """Find and stop orphaned headless browsers left behind by tests and automation."""
2
+
3
+ from __future__ import annotations
4
+
5
+ __version__ = "0.1.0"
6
+
7
+ from .clones import clean_clones # noqa: E402
8
+ from .detect import Group, find_groups # noqa: E402
9
+ from .proc import Proc, UnsupportedPlatform, list_processes # noqa: E402
10
+ from .reap import ReapResult, cleanup_profiles, reap # noqa: E402
11
+
12
+ __all__ = [
13
+ "Group",
14
+ "Proc",
15
+ "ReapResult",
16
+ "UnsupportedPlatform",
17
+ "__version__",
18
+ "cleanup_profiles",
19
+ "clean_clones",
20
+ "find_groups",
21
+ "list_processes",
22
+ "reap",
23
+ ]
@@ -0,0 +1,6 @@
1
+ """Allow `python -m headless_reaper`."""
2
+
3
+ from .cli import main
4
+
5
+ if __name__ == "__main__":
6
+ raise SystemExit(main())
headless_reaper/cli.py ADDED
@@ -0,0 +1,260 @@
1
+ """Command line entry point: `headless-reaper`."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import json
7
+ import os
8
+ import re
9
+ import sys
10
+ import time
11
+
12
+ from . import __version__
13
+ from .clones import clean_clones, render_clones
14
+ from .detect import Group, find_groups
15
+ from .proc import UnsupportedPlatform, list_processes
16
+ from .reap import ReapResult, cleanup_profiles, reap
17
+ from .report import human_bytes, human_duration, render_dry_run, render_reap
18
+
19
+ ENV_MIN_AGE = "HEADLESS_REAPER_MIN_AGE"
20
+ ENV_PATH = "HEADLESS_REAPER_PATH"
21
+ ENV_GRACE = "HEADLESS_REAPER_GRACE"
22
+
23
+ _DURATION_RE = re.compile(r"^(\d+(?:\.\d+)?)\s*([smhd]?)$", re.IGNORECASE)
24
+ _UNIT_SECONDS = {"": 1.0, "s": 1.0, "m": 60.0, "h": 3600.0, "d": 86400.0}
25
+
26
+
27
+ class _Parser(argparse.ArgumentParser):
28
+ """argparse that reports its errors through the one exit path below."""
29
+
30
+ def error(self, message: str) -> None: # type: ignore[override]
31
+ raise ValueError(message)
32
+
33
+
34
+ def parse_duration(text: str, option: str) -> float:
35
+ match = _DURATION_RE.match((text or "").strip())
36
+ if match is None:
37
+ raise ValueError(
38
+ f"{option}: expected a duration such as 30s, 10m, 2h or 1d, got {text!r}"
39
+ )
40
+ return float(match.group(1)) * _UNIT_SECONDS[match.group(2).lower()]
41
+
42
+
43
+ def build_parser() -> argparse.ArgumentParser:
44
+ parser = _Parser(
45
+ prog="headless-reaper",
46
+ description=(
47
+ "Find headless browser processes that a test or automation tool left "
48
+ "behind after its launcher exited. Dry run by default."
49
+ ),
50
+ formatter_class=argparse.RawDescriptionHelpFormatter,
51
+ epilog=(
52
+ "A process is a target only when it is a browser main process, carries an\n"
53
+ "automation signal (--headless, a temp/automation --user-data-dir, or a\n"
54
+ "remote debugging switch with such a profile), and its launcher is gone.\n"
55
+ "A visible browser on a real user profile is never touched.\n"
56
+ "\n"
57
+ "exit codes: 0 dry run or every target reaped, 1 a target survived or the\n"
58
+ "process table could not be read, 2 bad usage or an unsupported platform."
59
+ ),
60
+ )
61
+ parser.add_argument(
62
+ "--kill",
63
+ action="store_true",
64
+ help="terminate the groups (SIGTERM, wait, then SIGKILL)",
65
+ )
66
+ parser.add_argument("--clean-clones", action="store_true",
67
+ help="inspect macOS browser code-sign clones; with --kill, remove unused old clones")
68
+ parser.add_argument("--all-leftovers", action="store_true",
69
+ help="same as --kill --clean-clones --remove-profiles")
70
+ parser.add_argument(
71
+ "--min-age",
72
+ metavar="DURATION",
73
+ default=None,
74
+ help=f"skip groups younger than this, e.g. 10m or 2h (default: 0, or 10m with --clean-clones; or {ENV_MIN_AGE})",
75
+ )
76
+ parser.add_argument(
77
+ "--path",
78
+ action="append",
79
+ default=[],
80
+ metavar="PREFIX",
81
+ help=(
82
+ "only user-data-dirs under PREFIX; repeatable "
83
+ f"(default: every path; or {ENV_PATH})"
84
+ ),
85
+ )
86
+ parser.add_argument(
87
+ "--remove-profiles",
88
+ action="store_true",
89
+ help="with --kill, delete the temp profile of a reaped group when nothing uses it",
90
+ )
91
+ parser.add_argument(
92
+ "--grace",
93
+ metavar="DURATION",
94
+ default=None,
95
+ help=f"wait between SIGTERM and SIGKILL (default: 10s; or {ENV_GRACE})",
96
+ )
97
+ parser.add_argument(
98
+ "--json", action="store_true", help="print one machine-readable object"
99
+ )
100
+ parser.add_argument("--version", action="version", version=f"headless-reaper {__version__}")
101
+ return parser
102
+
103
+
104
+ def _env_paths() -> tuple[str, ...]:
105
+ raw = os.environ.get(ENV_PATH, "")
106
+ return tuple(part.strip() for part in raw.split(os.pathsep) if part.strip())
107
+
108
+
109
+ def _json_requested(argv: list[str]) -> bool:
110
+ return "--json" in argv
111
+
112
+
113
+ def _fail(message: str, code: int, json_mode: bool) -> int:
114
+ if json_mode:
115
+ print(json.dumps({"ok": False, "error": message}))
116
+ else:
117
+ print(f"headless-reaper: {message}", file=sys.stderr)
118
+ return code
119
+
120
+
121
+ def _group_object(group: Group, now: float) -> dict:
122
+ age = group.age_seconds(now)
123
+ return {
124
+ "root_pid": group.root.pid,
125
+ "pids": group.pids,
126
+ "processes": len(group.members),
127
+ "profile": group.profile,
128
+ "signals": list(group.signals),
129
+ "reason": group.reason,
130
+ "age_seconds": int(age),
131
+ "age": human_duration(age),
132
+ "rss_bytes": group.rss_bytes(),
133
+ "rss": human_bytes(group.rss_bytes()),
134
+ }
135
+
136
+
137
+ def _payload(
138
+ groups: list[Group],
139
+ scanned: int,
140
+ now: float,
141
+ min_age: float,
142
+ paths: tuple[str, ...],
143
+ dry_run: bool,
144
+ result: ReapResult | None,
145
+ removed: list[str],
146
+ kept: list[tuple[str, str]],
147
+ clones: dict | None = None,
148
+ ) -> dict:
149
+ payload = {
150
+ "ok": True,
151
+ "version": __version__,
152
+ "platform": sys.platform,
153
+ "dry_run": dry_run,
154
+ "scanned": scanned,
155
+ "min_age_seconds": int(min_age),
156
+ "paths": list(paths),
157
+ "totals": {
158
+ "groups": len(groups),
159
+ "processes": sum(len(group.members) for group in groups),
160
+ "rss_bytes": sum(group.rss_bytes() for group in groups),
161
+ },
162
+ "groups": [_group_object(group, now) for group in groups],
163
+ "reap": None,
164
+ }
165
+ if result is not None:
166
+ payload["reap"] = {
167
+ "targets": result.targets,
168
+ "sigterm": result.sigterm,
169
+ "sigkill": result.sigkill,
170
+ "survivors": result.survivors,
171
+ "already_gone": result.already_gone,
172
+ "denied": result.denied,
173
+ "removed_profiles": removed,
174
+ "kept_profiles": [{"path": path, "reason": reason} for path, reason in kept],
175
+ }
176
+ if clones is not None:
177
+ payload["clones"] = clones
178
+ payload["ok"] = not _clone_failed(clones)
179
+ return payload
180
+
181
+
182
+ def _clone_failed(clones: dict | None) -> bool:
183
+ return bool(clones and clones["supported"] and (clones["message"] or any(
184
+ item["reason"] == "clone deletion failed" for item in clones["kept"])))
185
+
186
+
187
+ def _run(
188
+ args: argparse.Namespace, min_age: float, grace: float, paths: tuple[str, ...]
189
+ ) -> int:
190
+ try:
191
+ procs = [] if args.clean_clones and not args.kill else list_processes()
192
+ except UnsupportedPlatform as error:
193
+ message = str(error) + ("; code-sign clones: nothing to do on this OS" if args.clean_clones else "")
194
+ return _fail(message, 2, args.json)
195
+ except RuntimeError as error:
196
+ return _fail(str(error), 1, args.json)
197
+
198
+ now = time.time()
199
+ groups = find_groups(procs, now, min_age=min_age, paths=paths)
200
+
201
+ if not args.kill:
202
+ clones = clean_clones(min_age=min_age) if args.clean_clones else None
203
+ if args.json:
204
+ print(json.dumps(_payload(groups, len(procs), now, min_age, paths, True, None, [], [], clones)))
205
+ else:
206
+ print(render_clones(clones) if clones is not None else render_dry_run(__version__, groups, len(procs), now, min_age, paths))
207
+ return 1 if _clone_failed(clones) else 0
208
+
209
+ result = reap(groups, grace=grace)
210
+ still_running = set(result.survivors) | set(result.denied)
211
+ clean = [group for group in groups if not still_running.intersection(group.pids)]
212
+ removed, kept = (
213
+ cleanup_profiles(clean) if args.remove_profiles else ([], [])
214
+ )
215
+
216
+ clones = clean_clones(kill=True, min_age=min_age) if args.clean_clones else None
217
+ if args.json:
218
+ print(
219
+ json.dumps(
220
+ _payload(
221
+ groups, len(procs), now, min_age, paths, False, result, removed, kept, clones
222
+ )
223
+ )
224
+ )
225
+ else:
226
+ print(
227
+ render_reap(
228
+ __version__, groups, len(procs), now, min_age, paths, result, removed, kept
229
+ )
230
+ )
231
+ if clones is not None:
232
+ print(render_clones(clones))
233
+ return 1 if result.survivors or _clone_failed(clones) else 0
234
+
235
+
236
+ def main(argv: list[str] | None = None) -> int:
237
+ arguments = list(sys.argv[1:] if argv is None else argv)
238
+ parser = build_parser()
239
+ try:
240
+ args = parser.parse_args(arguments)
241
+ if args.all_leftovers:
242
+ args.kill = args.clean_clones = args.remove_profiles = True
243
+ min_age = parse_duration(
244
+ args.min_age if args.min_age is not None else os.environ.get(ENV_MIN_AGE, "10m" if args.clean_clones else "0"),
245
+ "--min-age",
246
+ )
247
+ grace = parse_duration(
248
+ args.grace if args.grace is not None else os.environ.get(ENV_GRACE, "10s"),
249
+ "--grace",
250
+ )
251
+ paths = tuple(args.path) if args.path else _env_paths()
252
+ if args.remove_profiles and not args.kill:
253
+ raise ValueError("--remove-profiles requires --kill")
254
+ return _run(args, min_age, grace, paths)
255
+ except ValueError as error:
256
+ return _fail(str(error), 2, _json_requested(arguments))
257
+
258
+
259
+ if __name__ == "__main__":
260
+ raise SystemExit(main())
@@ -0,0 +1,176 @@
1
+ """Inspect only browser code-signing clones in this user's macOS X temp root."""
2
+ from __future__ import annotations
3
+
4
+ import ctypes
5
+ import os
6
+ from pathlib import Path
7
+ import shutil
8
+ import subprocess
9
+ import sys
10
+ import time
11
+
12
+ from .report import human_bytes
13
+
14
+ _BUNDLES = frozenset(("com.google.chrome", "org.chromium.chromium", "com.microsoft.edgemac",
15
+ "com.google.chrome.for_testing", "com.google.chrome.fortesting"))
16
+
17
+
18
+ def _clone_parent(name: str) -> bool:
19
+ suffix = ".code_sign_clone"
20
+ return name.lower().endswith(suffix) and name[:-len(suffix)].lower() in _BUNDLES
21
+
22
+
23
+ def _x_root() -> Path:
24
+ temp = subprocess.check_output(["getconf", "DARWIN_USER_TEMP_DIR"], text=True, timeout=5).strip()
25
+ root = Path(temp).resolve(strict=True).parent / "X"
26
+ if not root.is_dir() or root.is_symlink():
27
+ raise OSError("user X temp directory is unavailable")
28
+ return root
29
+
30
+
31
+ def _open_paths() -> set[str]:
32
+ """Read exact executable paths natively and open/mapped files with lsof.
33
+
34
+ SIP denies some descriptor-path queries even for same-user processes.
35
+ lsof can inspect those paths and mapped files through its existing route.
36
+ A failed lsof scan prevents removal of any clone.
37
+ """
38
+ lib = ctypes.CDLL("/usr/lib/libproc.dylib", use_errno=True)
39
+ lib.proc_listpids.argtypes = [ctypes.c_uint32, ctypes.c_uint32, ctypes.c_void_p, ctypes.c_int]
40
+ lib.proc_pidpath.argtypes = [ctypes.c_int, ctypes.c_void_p, ctypes.c_uint32]
41
+ size = lib.proc_listpids(1, 0, None, 0)
42
+ if size <= 0:
43
+ raise OSError("cannot enumerate processes for clone cleanup")
44
+ buffer = (ctypes.c_int * (size // 4 + 1024))()
45
+ size = lib.proc_listpids(1, 0, buffer, ctypes.sizeof(buffer))
46
+ if size <= 0:
47
+ raise OSError("cannot enumerate processes for clone cleanup")
48
+ paths: set[str] = set()
49
+ for pid in buffer[:size // 4]:
50
+ if pid <= 0:
51
+ continue
52
+ buf = ctypes.create_string_buffer(4096)
53
+ if lib.proc_pidpath(pid, buf, len(buf)) > 0:
54
+ paths.add(os.fsdecode(buf.value))
55
+ opened = subprocess.run(["lsof", "-nP", "-Fpn"], capture_output=True, text=True, timeout=30)
56
+ if opened.returncode != 0 or opened.stderr.strip():
57
+ raise OSError("open-file scan failed; preserving code-sign clones")
58
+ paths.update(line[1:] for line in opened.stdout.splitlines() if line.startswith("n/"))
59
+ return {os.path.realpath(path) for path in paths}
60
+
61
+
62
+ def _identities(paths: set[str]) -> set[tuple[int, int]]:
63
+ identities = set()
64
+ for path in paths:
65
+ try:
66
+ stat = os.stat(path)
67
+ identities.add((stat.st_dev, stat.st_ino))
68
+ except OSError:
69
+ pass
70
+ return identities
71
+
72
+
73
+ def _size(path: Path, opened: set[tuple[int, int]]) -> tuple[int, int, bool]:
74
+ apparent = allocated = 0
75
+ used = False
76
+ stack = [path]
77
+ while stack:
78
+ entry = stack.pop()
79
+ stat = entry.lstat()
80
+ used |= (stat.st_dev, stat.st_ino) in opened
81
+ apparent += stat.st_size
82
+ allocated += stat.st_blocks * 512
83
+ if entry.is_dir() and not entry.is_symlink():
84
+ stack.extend(entry.iterdir())
85
+ return apparent, allocated, used
86
+
87
+
88
+ def clean_clones(*, kill: bool = False, min_age: float = 600) -> dict:
89
+ result = {"supported": sys.platform == "darwin", "dry_run": not kill, "root": None,
90
+ "min_age_seconds": int(min_age), "candidates": [], "kept": [], "removed": [],
91
+ "apparent_bytes": 0, "allocated_bytes": 0, "reclaimable_bytes_estimate": None,
92
+ "free_space_change_bytes": None, "message": "nothing to do on this OS"}
93
+ if sys.platform != "darwin":
94
+ return result
95
+ result["message"] = ""
96
+ try:
97
+ root = _x_root()
98
+ result["root"] = str(root)
99
+ paths = sorted(p for parent in root.iterdir() if _clone_parent(parent.name)
100
+ and parent.is_dir() and not parent.is_symlink()
101
+ for p in parent.iterdir() if p.name.startswith("code_sign_clone."))
102
+ if not paths:
103
+ return result
104
+ opened = _open_paths()
105
+ identities = _identities(opened)
106
+ except (OSError, subprocess.SubprocessError) as error:
107
+ result["message"] = f"clone scan unavailable: {error}"
108
+ return result
109
+ now = time.time()
110
+ for path in paths:
111
+ try:
112
+ stat = path.lstat()
113
+ if not path.is_dir() or path.is_symlink() or path.resolve() != path:
114
+ result["kept"].append({"path": str(path), "reason": "not a plain clone directory"})
115
+ continue
116
+ if now - stat.st_birthtime < min_age:
117
+ result["kept"].append({"path": str(path), "reason": "younger than min age"})
118
+ continue
119
+ if any(p == str(path) or p.startswith(str(path) + os.sep) for p in opened):
120
+ result["kept"].append({"path": str(path), "reason": "used by a running process"})
121
+ continue
122
+ apparent, allocated, used = _size(path, identities)
123
+ if used:
124
+ result["kept"].append({"path": str(path), "reason": "used by a running process"})
125
+ continue
126
+ result["candidates"].append({"path": str(path), "age_seconds": int(max(0, now - stat.st_birthtime)),
127
+ "apparent_bytes": apparent, "allocated_bytes": allocated})
128
+ result["apparent_bytes"] += apparent
129
+ result["allocated_bytes"] += allocated
130
+ except OSError:
131
+ result["kept"].append({"path": str(path), "reason": "clone directory is unreadable or changed"})
132
+ if kill and result["candidates"]:
133
+ before = shutil.disk_usage(root).free
134
+ try:
135
+ # Recheck after sizing: a launch may have claimed a clone meanwhile.
136
+ opened = _open_paths()
137
+ identities = _identities(opened)
138
+ except (OSError, subprocess.SubprocessError) as error:
139
+ result["message"] = f"clone scan unavailable: {error}"
140
+ return result
141
+ for candidate in result["candidates"]:
142
+ path = Path(candidate["path"])
143
+ try:
144
+ if path.is_symlink() or path.parent.is_symlink() or path.resolve() != path:
145
+ result["kept"].append({"path": str(path), "reason": "clone directory changed"})
146
+ elif time.time() - path.stat().st_birthtime < min_age:
147
+ result["kept"].append({"path": str(path), "reason": "younger than min age"})
148
+ elif any(p == str(path) or p.startswith(str(path) + os.sep) for p in opened) or _size(path, identities)[2]:
149
+ result["kept"].append({"path": str(path), "reason": "used by a running process"})
150
+ else:
151
+ try:
152
+ shutil.rmtree(path)
153
+ result["removed"].append(str(path))
154
+ except OSError:
155
+ result["kept"].append({"path": str(path), "reason": "clone deletion failed"})
156
+ except OSError:
157
+ result["kept"].append({"path": str(path), "reason": "clone directory changed"})
158
+ result["free_space_change_bytes"] = shutil.disk_usage(root).free - before
159
+ return result
160
+
161
+
162
+ def render_clones(result: dict) -> str:
163
+ if not result["supported"]:
164
+ return "code-sign clones: nothing to do on this OS."
165
+ if result["message"]:
166
+ return f"code-sign clones: {result['message']}."
167
+ text = (f"code-sign clones: {len(result['candidates'])} eligible, {len(result['kept'])} kept, "
168
+ f"{human_bytes(result['apparent_bytes'])} apparent; reclaimable space: unknown (shared APFS blocks).")
169
+ if not result["dry_run"]:
170
+ text += f"\nremoved {len(result['removed'])} code-sign clones."
171
+ change = result["free_space_change_bytes"]
172
+ if change is not None:
173
+ text += f" filesystem free-space change: {'-' if change < 0 else '+'}{human_bytes(abs(change))}."
174
+ else:
175
+ text += "\ndry run: no code-sign clones were removed. Rerun with --kill --clean-clones."
176
+ return text