Raven-1/tests/test_utils_processes.py
Dizhan Xue 4226055fd3
fix(cli): decide a stale serve.json by identity, not by pid liveness (#879)
## Summary

A stale `serve.json` can name a PID recycled to an unrelated process.
Liveness alone then prevents `raven web` from starting and lets `raven
web --stop` signal the wrong process. Check the instance lock and the
recorded process's command line before treating that PID as a Raven
resident.

- Preserve resident, foreign, and unknown identities. An unavailable
argv probe keeps a live process's record and prevents duplicate startup;
stopping requires positive identity evidence.
- Read Linux argv directly from `/proc/<pid>/cmdline`, retaining
argument boundaries when rendering spaces. Fall back to untruncated
GNU/BSD `ps -ww`; Windows uses CIM. Decoding uses UTF-8 with
replacement. Recognize module and console-script launches of `serve`,
`web`, and `gateway`.
- Examine every console-script candidate. An earlier directory such as
`Raven copy` or a Windows profile named `Raven Smith` no longer hides
the actual executable and causes removal of a live resident's record.
- Return exit 1 when any resident stop is refused or fails, including
partial stops. The CLI no longer reports "nothing to stop" after
retaining live records. Unknown-identity refusals name the exact
serve.json, web.json, or viewer.pid record. Restore process access, or
remove that record only after confirming it is stale; the warning no
longer suggests signalling an unverified PID.
- Share the platform reader with the tracing viewer. Recognize `nodejs`
and versioned Node names as well as `node`/`node.exe`. An unreadable
live viewer keeps its record, cannot be signalled, and prevents a second
viewer from starting; a dead or proven foreign process can still be
cleared. Recognize unquoted spaced executable paths from POSIX ps as
well as quoted paths.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

Linux, Python 3.12, after rebasing onto current main:

```text
uv run --frozen --all-extras pytest tests/test_cli_serve_commands.py tests/test_utils_processes.py tests/test_cli_tracing_commands.py tests/test_cli_gateway_commands.py tests/test_cli_gateway_health.py tests/test_cli_gateway_page.py tests/test_rpc_serve_control.py -q -x --tb=short
```

Result: 328 passed, 1 skipped (the native Windows CIM case), using the
default four workers. The live procfs regression now waits for a bounded
child readiness signal before its single identity assertion, eliminating
the transient empty-cmdline startup race reported in review. The
container uses an init process to reap children from the real
process-group tests.

A follow-up CI run exposed two assertions that assumed Rich would not
wrap viewer.pid inside a long path. The assertions now tolerate display
line breaks. Re-running the entire tracing CLI test file with the
CI-shaped temporary path
(`--basetemp=/tmp/pytest-of-runner/pytest-0/popen-gw3`) passed all 40
tests.

Native Windows, Python 3.12:

```text
uv run --frozen pytest tests/test_cli_serve_commands.py::TestAnUnreadableIdentity tests/test_cli_serve_commands.py::TestARecycledPid tests/test_cli_serve_commands.py::TestAStopThatLosesItsTarget tests/test_cli_serve_commands.py::test_web_stop_reports_a_refused_or_partial_stop tests/test_cli_serve_commands.py::test_a_resident_below_a_raven_named_directory_keeps_its_record tests/test_utils_processes.py tests/test_cli_tracing_commands.py -n 0 -q -x --tb=short
```

Result: 102 passed, 7 Linux/POSIX-only skips. The Linux selection
includes a real child identified with ps absent from PATH. Tests force
the ps fallback when measuring its behavior, pin lowercase Raven
directories and uppercase executable names separately, and drive the
public viewer stop for an unquoted spaced Node path. Both new
spaced-path regressions failed before the viewer fix.

Four additional isolated mutations were caught: skipping procfs,
dropping the ps fallback, restoring first-match resident parsing while
removing case-insensitivity, and truncating the Node path at its first
space. The sources were restored and compared with the committed Git
blobs.

Additional checks passed:

```text
uv run --frozen pre-commit run --from-ref origin/main --to-ref HEAD
uv run --frozen --all-extras ty check raven/utils/processes.py raven/cli/serve_commands.py raven/cli/tracing_commands.py
uv run --frozen --all-extras lint-imports
uv run --frozen python scripts/check_commit_messages.py origin/main..HEAD
commitlint --from origin/main --to HEAD
uv run --frozen python scripts/check_source_language.py origin/main..HEAD
uv run --frozen python scripts/check_large_files.py origin/main..HEAD
git diff --check origin/main...HEAD
```

Import-linter kept all 10 contracts. The full repository suite and
native macOS were not rerun locally. No new command, setting, or visual
UI requires a screenshot or user guide; the affected code contracts and
this description are updated.

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

A live process with an unreadable identity deliberately blocks
replacement and cannot be stopped through these commands. Restore the
process reader, or confirm the state record is stale before removing the
exact file named by the command. Scripts now receive failure for refused
or incomplete stops instead of a misleading success. Process recognition
remains a command-line heuristic, and the check and signal do not hold a
single OS process handle; this does not eliminate PID-reuse races.

Rollback: revert the squash commit, restoring the previous PID-based
behavior and its recycled-PID risk.

## Related Issues

N/A

---------

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-10-11 23:05:43 +08:00

306 lines
12 KiB
Python

"""Process identity decisions and the POSIX and Windows command-line readers."""
from __future__ import annotations
import subprocess
import sys
import pytest
from raven.utils import processes
@pytest.mark.skipif(not sys.platform.startswith("linux"), reason="procfs is the Linux reader")
def test_linux_reads_a_live_resident_without_ps(monkeypatch) -> None:
import select
script = "import os, sys, time; os.write(sys.stdout.fileno(), b'ready\\n'); time.sleep(30)"
sleeper = subprocess.Popen([sys.executable, "-c", script, "-m", "raven", "web"], stdout=subprocess.PIPE)
try:
assert sleeper.stdout is not None
assert select.select([sleeper.stdout], [], [], 5)[0], "the child did not reach its script"
assert sleeper.stdout.readline() == b"ready\n"
monkeypatch.setenv("PATH", "/nonexistent")
assert processes.raven_identity(sleeper.pid) is True
finally:
sleeper.terminate()
sleeper.wait(timeout=10)
if sleeper.stdout is not None:
sleeper.stdout.close()
def test_procfs_preserves_spaces_without_starting_a_probe(monkeypatch) -> None:
monkeypatch.setattr(processes.sys, "platform", "linux")
monkeypatch.setattr(processes.Path, "read_bytes", lambda _path: b"/home/u/Raven copy/bin/raven\0serve\0")
monkeypatch.setattr(processes.subprocess, "run", lambda *_args, **_kwargs: pytest.fail("called ps"))
assert processes.command_line(1234) == '"/home/u/Raven copy/bin/raven" serve'
assert processes.raven_identity(1234) is True
@pytest.mark.parametrize("unavailable", [b"", PermissionError("not readable"), FileNotFoundError("gone")])
def test_missing_procfs_falls_back_to_ps(monkeypatch, unavailable) -> None:
def read(_path):
if isinstance(unavailable, Exception):
raise unavailable
return unavailable
monkeypatch.setattr(processes.sys, "platform", "linux")
monkeypatch.setattr(processes.Path, "read_bytes", read)
monkeypatch.setattr(processes, "_command_line_posix", lambda pid: "python -m raven serve" if pid == 1234 else None)
assert processes.command_line(1234) == "python -m raven serve"
def test_a_module_invocation_is_recognised_anywhere_in_the_argv(monkeypatch) -> None:
"""``-P`` and friends land between the interpreter and ``-m raven``."""
monkeypatch.setattr(
processes,
"command_line",
lambda _pid: "c:/py/python.exe -P -m raven gateway --page-port 18792",
)
assert processes.looks_like_raven(1234)
def test_a_console_script_serve_is_recognised(monkeypatch) -> None:
"""The documented entry point: ``raven serve`` runs ``entry:run`` in
this process, so its argv is the console script plus the subcommand."""
monkeypatch.setattr(processes, "command_line", lambda _pid: "C:/raven/Scripts/raven.exe serve --port 18792")
assert processes.looks_like_raven(1234)
monkeypatch.setattr(processes, "command_line", lambda _pid: "/usr/local/bin/raven web --supervise")
assert processes.looks_like_raven(1234)
monkeypatch.setattr(processes, "command_line", lambda _pid: "raven gateway --page-port 18792")
assert processes.looks_like_raven(1234)
def test_a_console_script_of_another_verb_is_not(monkeypatch) -> None:
"""``raven tui`` and ``raven --version`` are run-and-done: no state file
names them, so a pid that is one of them is not this module's business."""
monkeypatch.setattr(processes, "command_line", lambda _pid: "C:/raven/Scripts/raven.exe tui")
assert not processes.looks_like_raven(1234)
monkeypatch.setattr(processes, "command_line", lambda _pid: "raven --version")
assert not processes.looks_like_raven(1234)
def test_a_subdirectory_named_raven_does_not_read_as_a_module_flag(monkeypatch) -> None:
monkeypatch.setattr(processes, "command_line", lambda _pid: "d:/projects/raven/python.exe app.py")
assert not processes.looks_like_raven(1234)
def test_a_process_named_raven_running_something_else_is_not(monkeypatch) -> None:
monkeypatch.setattr(processes, "command_line", lambda _pid: "raven app.py")
assert not processes.looks_like_raven(1234)
def test_an_unreadable_command_line_is_never_ours(monkeypatch) -> None:
monkeypatch.setattr(processes, "command_line", lambda _pid: None)
assert not processes.looks_like_raven(1234)
@pytest.mark.parametrize("line", [None, ""])
def test_an_unreadable_command_line_has_an_unknown_identity(monkeypatch, line) -> None:
monkeypatch.setattr(processes, "command_line", lambda _pid: line)
assert processes.raven_identity(1234) is None
@pytest.mark.parametrize(
"line",
[
"python -P -m raven serve --port 18792",
"python -m raven -- gateway --page-port 18792",
'python -m "raven" web --supervise',
'"C:/Program Files/Raven/raven.exe" serve --port 18792',
"/usr/local/bin/raven -- web --supervise",
],
)
def test_a_resident_command_has_a_positive_identity(monkeypatch, line: str) -> None:
monkeypatch.setattr(processes, "command_line", lambda _pid: line)
assert processes.raven_identity(1234) is True
@pytest.mark.parametrize(
"line",
[
"/Users/x/Raven copy/.venv/bin/python3 /Users/x/Raven copy/.venv/bin/raven serve --port 8765",
r"C:\Users\Raven Smith\.venv\Scripts\raven.exe serve",
r'"C:\Users\Raven Smith\python.exe" "C:\Users\Raven Smith\raven.exe" web --supervise',
"/Users/x/Raven 2/.venv/bin/raven web --supervise --port 9",
"/home/u/raven copy/.venv/bin/python3 /home/u/raven copy/.venv/bin/raven serve --port 8765",
"/home/u/bin/RAVEN serve --port 8765",
],
)
def test_a_raven_named_directory_does_not_hide_the_resident(monkeypatch, line: str) -> None:
monkeypatch.setattr(processes, "command_line", lambda _pid: line)
assert processes.raven_identity(1234) is True
@pytest.mark.parametrize(
"line",
[
"python -m raven acp",
"python -m raven tui",
"python -m raven --version serve",
"python -m raven --help web",
"python -m raven_tools serve",
"python -m ravenx serve",
"python -m raven.other serve",
"python -m raven-tools serve",
"python -m raven serve_other",
"python -m raven serve-other",
"python -m raven",
"python app.py",
],
)
def test_a_foreign_command_has_a_negative_identity(monkeypatch, line: str) -> None:
monkeypatch.setattr(processes, "command_line", lambda _pid: line)
assert processes.raven_identity(1234) is False
assert processes.looks_like_raven(1234) is False
@pytest.mark.parametrize("reader", [processes._command_line_posix, processes._command_line_windows])
def test_undecodable_argv_does_not_crash_the_reader(monkeypatch, reader) -> None:
monkeypatch.setattr("shutil.which", lambda _name: "powershell.exe")
run = subprocess.run
def emit_bytes(_argv, **kwargs):
script = r"import sys; sys.stdout.buffer.write(b'python /tmp/profil\xe9/worker.py\n')"
return run([sys.executable, "-c", script], **kwargs)
monkeypatch.setattr(subprocess, "run", emit_bytes)
assert reader(1234) == "python /tmp/profil\ufffd/worker.py"
@pytest.mark.parametrize("reader", [processes._command_line_posix, processes._command_line_windows])
@pytest.mark.parametrize("error", [OSError("unavailable"), subprocess.TimeoutExpired("probe", 1)])
def test_a_failed_reader_keeps_the_identity_unknown(monkeypatch, reader, error) -> None:
monkeypatch.setattr("shutil.which", lambda _name: "powershell.exe")
def fail(*_args, **_kwargs):
raise error
monkeypatch.setattr(subprocess, "run", fail)
assert reader(1234) is None
@pytest.mark.skipif(sys.platform != "win32", reason="CIM is the Windows reader")
@pytest.mark.slow
def test_windows_reads_unicode_arguments_from_a_live_process() -> None:
argument = "profile-\u00fc"
sleeper = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(30)", argument])
try:
line = processes.command_line(sleeper.pid)
assert line is not None
assert argument in line
assert "time.sleep" in line
finally:
sleeper.terminate()
sleeper.wait(timeout=10)
class TestThePosixReader:
"""Drive the real ``ps`` against a real process, not a stub, so the
reader the suite ships is the reader the suite measures. Skipped on
Windows, whose reader is a different mechanism."""
@pytest.fixture(autouse=True)
def _without_procfs(self, monkeypatch):
monkeypatch.setattr(processes, "_command_line_proc", lambda _pid: None)
def test_a_live_process_s_argv_is_read_back(self) -> None:
import os
import sys
if sys.platform == "win32":
import pytest
pytest.skip("the POSIX reader is not the Windows reader")
line = processes.command_line(os.getpid())
assert line is not None
assert "pytest" in line or "python" in line
def test_a_dead_pid_reads_as_none(self) -> None:
import sys
if sys.platform == "win32":
import pytest
pytest.skip("the POSIX reader is not the Windows reader")
assert processes.command_line(99999999) is None
def test_an_invalid_pid_reads_as_none(self) -> None:
assert processes.command_line(0) is None
assert processes.command_line(-1) is None
def test_a_ps_that_fails_reads_as_none(self, monkeypatch) -> None:
import subprocess
import sys
if sys.platform == "win32":
import pytest
pytest.skip("the POSIX reader is not the Windows reader")
completed = subprocess.CompletedProcess([], 1, "", "")
monkeypatch.setattr(subprocess, "run", lambda *_a, **_k: completed)
assert processes._command_line_posix(1) is None
def test_a_ps_that_cannot_run_reads_as_none(self, monkeypatch) -> None:
"""A missing probe establishes no identity; liveness is a separate read."""
import subprocess
import sys
if sys.platform == "win32":
import pytest
pytest.skip("the POSIX reader is not the Windows reader")
def _unavailable(*_a, **_k):
raise OSError("ps: not found")
monkeypatch.setattr(subprocess, "run", _unavailable)
assert processes._command_line_posix(1) is None
def test_a_subprocess_s_own_flag_is_seen(self) -> None:
import subprocess
import sys
if sys.platform == "win32":
import pytest
pytest.skip("the POSIX reader is not the Windows reader")
sleeper = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(30)"])
try:
line = processes.command_line(sleeper.pid)
assert line is not None
assert "time.sleep" in line
finally:
sleeper.terminate()
sleeper.wait(timeout=10)
def test_a_narrow_terminal_does_not_truncate_the_argv(self, monkeypatch) -> None:
"""``ps`` sizes its output from the display width it inherits, and the
whole point of this reader is to find a flag that can sit past it."""
import os
import subprocess
import sys
if sys.platform == "win32":
import pytest
pytest.skip("the POSIX reader is not the Windows reader")
monkeypatch.setenv("COLUMNS", "40")
argv = [sys.executable, "-c", "import time; time.sleep(30)"]
sleeper = subprocess.Popen(argv, env={**os.environ, "COLUMNS": "40"})
try:
line = processes.command_line(sleeper.pid)
assert line is not None
assert argv[0] in line
assert "time.sleep" in line
finally:
sleeper.terminate()
sleeper.wait(timeout=10)