ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
refactor(system): run_checked() and a ratchet on the raw subprocess surface
Juan Denis89481b15c024
diff --git a/.github/workflows/test-system-utils.yml b/.github/workflows/test-system-utils.ymlindex 35e02ba9..60045712 100644--- a/.github/workflows/test-system-utils.yml+++ b/.github/workflows/test-system-utils.yml@@ -85,6 +85,20 @@ jobs:steps:- uses: actions/checkout@v4+ - name: Set up Python+ uses: actions/setup-python@v5+ with:+ python-version: '3.11'++ # The ratchet (plan 75 §G1). The grep steps below check a hand-listed set+ # of files for three known-bad patterns; this counts EVERY raw+ # subprocess call site under backend/app and fails if the total grew.+ # A grep cannot do this honestly — it also matches comments, docstrings+ # and `except subprocess.SubprocessError` — so the census is AST-based.+ - name: Raw subprocess census (ceiling may only go down)+ working-directory: backend+ run: python3 tests/raw_subprocess_census.py+- name: Check for raw 'sudo systemctl' calls in migrated servicesrun: |MIGRATED_FILES=(diff --git a/backend/app/services/cron_service.py b/backend/app/services/cron_service.pyindex 3d682b38..8e75a938 100644--- a/backend/app/services/cron_service.py+++ b/backend/app/services/cron_service.py@@ -15,7 +15,7 @@ from typing import Dict, List, Optionalfrom datetime import datetimeimport json-from app.utils.system import unit_is_active+from app.utils.system import run_checked, unit_is_active# Path for storing job metadataJOBS_FILE = os.path.join(os.path.dirname(os.path.dirname(__file__)), 'data', 'cron_jobs.json')@@ -78,6 +78,37 @@ class CronService:"""Check if running on Linux."""return platform.system() == 'Linux'+ # ── the crontab door (plan 75 §G1) ────────────────────────────────────+ # `crontab -l` followed by a Popen-with-stdin `crontab -` was written out+ # five times in this file, each with its own capture_output/text/timeout+ # boilerplate and its own error wording. Two helpers, one run_checked.++ @classmethod+ def _read_crontab(cls) -> Optional[str]:+ """The current user's crontab, or ``None`` if it could not be read.++ ``None`` is "could not read", never "empty crontab" (§A). An empty+ crontab is ``''`` and ``crontab -l`` exits non-zero for it on some+ implementations, so callers that install a replacement treat a failed+ read as "start from nothing" only where that was already the behaviour.+ """+ result = run_checked(['crontab', '-l'], timeout=10)+ return result['output'] if result['success'] else None++ @classmethod+ def _install_crontab(cls, content: str) -> Optional[Dict]:+ """Install *content* as the crontab. ``None`` on success, error dict on failure.++ The five copies of this all built a Popen by hand purely to put the new+ crontab on stdin; ``run_checked(..., input=...)`` is the same thing+ without the five chances to forget a timeout.+ """+ result = run_checked(['crontab', '-'], input=content, timeout=10)+ if result['success']:+ return None+ return {'success': False,+ 'error': result['error'] or 'Failed to install crontab'}+@classmethoddef get_status(cls) -> Dict:"""Get cron service status."""@@ -304,37 +335,16 @@ class CronService:metadata = cls._load_jobs_metadata()if cls.is_linux():- try:- # Get current crontab- result = subprocess.run(- ['crontab', '-l'],- capture_output=True,- text=True,- timeout=10- )-- current_crontab = result.stdout if result.returncode == 0 else ''+ current_crontab = cls._read_crontab() or ''- # Add comment and new job- comment = f"# ServerKit Job: {name or job_id}"- new_line = f"{schedule} {command}"- new_crontab = f"{current_crontab.rstrip()}\n{comment}\n{new_line}\n"+ # Add comment and new job+ comment = f"# ServerKit Job: {name or job_id}"+ new_line = f"{schedule} {command}"+ new_crontab = f"{current_crontab.rstrip()}\n{comment}\n{new_line}\n"- # Install new crontab- process = subprocess.Popen(- ['crontab', '-'],- stdin=subprocess.PIPE,- stdout=subprocess.PIPE,- stderr=subprocess.PIPE,- text=True- )- stdout, stderr = process.communicate(input=new_crontab, timeout=10)-- if process.returncode != 0:- return {'success': False, 'error': stderr or 'Failed to install crontab'}-- except subprocess.SubprocessError as e:- return {'success': False, 'error': str(e)}+ failure = cls._install_crontab(new_crontab)+ if failure:+ return failure# Save metadatametadata['jobs'][job_id] = {@@ -368,51 +378,29 @@ class CronService:job_data = metadata.get('jobs', {}).get(job_id)if cls.is_linux() and job_data:- try:- # Get current crontab- result = subprocess.run(- ['crontab', '-l'],- capture_output=True,- text=True,- timeout=10- )-- if result.returncode == 0:- lines = result.stdout.split('\n')- command = job_data.get('command', '')- schedule = job_data.get('schedule', '')-- # Filter out the job and its comment- new_lines = []- skip_next = False- for line in lines:- if skip_next:- skip_next = False- continue- if f"# ServerKit Job:" in line and job_id in line:- skip_next = True- continue- if command and schedule and f"{schedule} {command}" in line:- continue- new_lines.append(line)-- new_crontab = '\n'.join(new_lines)-- # Install updated crontab- process = subprocess.Popen(- ['crontab', '-'],- stdin=subprocess.PIPE,- stdout=subprocess.PIPE,- stderr=subprocess.PIPE,- text=True- )- stdout, stderr = process.communicate(input=new_crontab, timeout=10)-- if process.returncode != 0:- return {'success': False, 'error': stderr or 'Failed to update crontab'}-- except subprocess.SubprocessError as e:- return {'success': False, 'error': str(e)}+ current = cls._read_crontab()+ if current is not None:+ lines = current.split('\n')+ command = job_data.get('command', '')+ schedule = job_data.get('schedule', '')++ # Filter out the job and its comment+ new_lines = []+ skip_next = False+ for line in lines:+ if skip_next:+ skip_next = False+ continue+ if f"# ServerKit Job:" in line and job_id in line:+ skip_next = True+ continue+ if command and schedule and f"{schedule} {command}" in line:+ continue+ new_lines.append(line)++ failure = cls._install_crontab('\n'.join(new_lines))+ if failure:+ return failure# Remove from metadataif job_id in metadata.get('jobs', {}):@@ -432,51 +420,31 @@ class CronService:job_data = metadata['jobs'][job_id]if cls.is_linux():- try:- result = subprocess.run(- ['crontab', '-l'],- capture_output=True,- text=True,- timeout=10- )-- if result.returncode == 0:- lines = result.stdout.split('\n')- command = job_data.get('command', '')- schedule = job_data.get('schedule', '')- job_line = f"{schedule} {command}"-- new_lines = []- for line in lines:- if job_line in line:- if enabled:- # Remove leading # if present- new_lines.append(line.lstrip('# '))- else:- # Add # to comment out- if not line.startswith('#'):- new_lines.append(f"# {line}")- else:- new_lines.append(line)+ current = cls._read_crontab()+ if current is not None:+ lines = current.split('\n')+ command = job_data.get('command', '')+ schedule = job_data.get('schedule', '')+ job_line = f"{schedule} {command}"++ new_lines = []+ for line in lines:+ if job_line in line:+ if enabled:+ # Remove leading # if present+ new_lines.append(line.lstrip('# '))else:- new_lines.append(line)-- new_crontab = '\n'.join(new_lines)-- process = subprocess.Popen(- ['crontab', '-'],- stdin=subprocess.PIPE,- stdout=subprocess.PIPE,- stderr=subprocess.PIPE,- text=True- )- stdout, stderr = process.communicate(input=new_crontab, timeout=10)-- if process.returncode != 0:- return {'success': False, 'error': stderr}+ # Add # to comment out+ if not line.startswith('#'):+ new_lines.append(f"# {line}")+ else:+ new_lines.append(line)+ else:+ new_lines.append(line)- except subprocess.SubprocessError as e:- return {'success': False, 'error': str(e)}+ failure = cls._install_crontab('\n'.join(new_lines))+ if failure:+ return failure# Update metadatametadata['jobs'][job_id]['enabled'] = enabled@@ -571,41 +539,22 @@ class CronService:# Update crontab on Linux if schedule or command changedif cls.is_linux() and (new_schedule != old_schedule or new_command != old_command):- try:- result = subprocess.run(- ['crontab', '-l'],- capture_output=True,- text=True,- timeout=10- )-- if result.returncode == 0:- tracked = bool(job_data.get('tracked', False))- old_line = f"{old_schedule} {cls._crontab_command(old_command, tracked, job_id)}"- new_line = f"{new_schedule} {cls._crontab_command(new_command, tracked, job_id)}"- lines = result.stdout.split('\n')- new_lines = []- for line in lines:- if old_line in line:- new_lines.append(new_line)- else:- new_lines.append(line)-- new_crontab = '\n'.join(new_lines)- process = subprocess.Popen(- ['crontab', '-'],- stdin=subprocess.PIPE,- stdout=subprocess.PIPE,- stderr=subprocess.PIPE,- text=True- )- stdout, stderr = process.communicate(input=new_crontab, timeout=10)-- if process.returncode != 0:- return {'success': False, 'error': stderr or 'Failed to update crontab'}+ current = cls._read_crontab()+ if current is not None:+ tracked = bool(job_data.get('tracked', False))+ old_line = f"{old_schedule} {cls._crontab_command(old_command, tracked, job_id)}"+ new_line = f"{new_schedule} {cls._crontab_command(new_command, tracked, job_id)}"+ lines = current.split('\n')+ new_lines = []+ for line in lines:+ if old_line in line:+ new_lines.append(new_line)+ else:+ new_lines.append(line)- except subprocess.SubprocessError as e:- return {'success': False, 'error': str(e)}+ failure = cls._install_crontab('\n'.join(new_lines))+ if failure:+ return failure# Update metadataif name is not None:@@ -759,32 +708,12 @@ class CronService:def _replace_crontab_line(cls, old_line: str, new_line: str) -> Optional[Dict]:"""Swap one line in the current user's crontab. Returns None on successor an error dict. Linux-only (callers guard with is_linux)."""- try:- result = subprocess.run(- ['crontab', '-l'],- capture_output=True,- text=True,- timeout=10- )- if result.returncode != 0:- return None- lines = result.stdout.split('\n')- new_lines = [new_line if line == old_line else line for line in lines]- new_crontab = '\n'.join(new_lines)-- process = subprocess.Popen(- ['crontab', '-'],- stdin=subprocess.PIPE,- stdout=subprocess.PIPE,- stderr=subprocess.PIPE,- text=True- )- _, stderr = process.communicate(input=new_crontab, timeout=10)- if process.returncode != 0:- return {'success': False, 'error': stderr or 'Failed to update crontab'}- except subprocess.SubprocessError as e:- return {'success': False, 'error': str(e)}- return None+ current = cls._read_crontab()+ if current is None:+ return None+ lines = current.split('\n')+ new_lines = [new_line if line == old_line else line for line in lines]+ return cls._install_crontab('\n'.join(new_lines))# ------------------------------------------------------------------ ## Application attribution (member-facing surface)diff --git a/backend/app/utils/system.py b/backend/app/utils/system.pyindex 341937be..177d5d76 100644--- a/backend/app/utils/system.py+++ b/backend/app/utils/system.py@@ -144,6 +144,86 @@ def run_unprivileged(cmd: Union[List[str], str], *, timeout: int = 60,}+def run_checked(cmd: Union[List[str], str], *, privileged: bool = False,+ timeout: Optional[int] = 60, input: Optional[str] = None,+ cwd: Optional[str] = None, env: Optional[dict] = None,+ **kwargs) -> dict:+ """Run a command and get a result, not a ``CompletedProcess`` (plan 75 §G1).++ The result-shaped door. Around ``backend/app``'s raw ``subprocess`` calls+ sit 220 copies of ``capture_output=True, text=True``, 56 hand-rolled+ ``except subprocess.TimeoutExpired`` handlers, 19 hand-rolled+ ``except FileNotFoundError`` handlers, and 1,164 literal+ ``{'success': False, 'error': ...}`` constructions. Each of those is a+ place where an exec failure can be — and per plan 74 has been — converted+ into a false fact about the operator's server.++ Returns::++ {'success': bool, 'output': str, 'error': str|None, 'returncode': int|None}++ ``returncode`` is ``None`` when the command never ran, which is the+ distinction the hand-rolled handlers keep losing: exit code 1 means the+ command answered "no", while no exit code at all means nobody answered.+ A caller that renders "not installed" must check ``returncode is not None``+ first, and now it can.++ ``privileged=True`` routes through :func:`run_privileged` — same sudo-vs-root+ decision, same argv[0] resolution, so no caller re-implements either.++ ``timeout`` defaults to 60s rather than ``None`` on purpose: with output+ captured and no terminal, a command that never returns takes its caller+ with it, silently and forever. Pass ``timeout=None`` to opt out+ deliberately.+ """+ if input is not None:+ kwargs['input'] = input+ if cwd is not None:+ kwargs['cwd'] = cwd+ if env is not None:+ kwargs['env'] = env+ kwargs.setdefault('capture_output', True)+ kwargs.setdefault('text', True)++ try:+ if privileged:+ result = run_privileged(cmd, timeout=timeout, **kwargs)+ else:+ resolved = cmd+ if isinstance(cmd, (list, tuple)):+ resolved = list(cmd)+ if (resolved and not os.path.isabs(resolved[0])+ and not shutil.which(resolved[0])):+ # Same argv[0] resolution privileged_cmd does: a bare name+ # that $PATH cannot find is the sbin outage, not a missing+ # binary. Only applied when $PATH genuinely misses it.+ absolute = resolve_command(resolved[0])+ if absolute:+ resolved[0] = absolute+ result = subprocess.run(resolved, timeout=timeout, **kwargs)+ except FileNotFoundError as exc:+ name = cmd[0] if isinstance(cmd, (list, tuple)) and cmd else cmd+ return {'success': False, 'output': '', 'returncode': None,+ 'error': f'{name} not found: {exc}'}+ except subprocess.TimeoutExpired:+ return {'success': False, 'output': '', 'returncode': None,+ 'error': f'timed out after {timeout}s'}+ except PermissionError as exc:+ return {'success': False, 'output': '', 'returncode': None,+ 'error': f'permission denied: {exc}'}+ except OSError as exc:+ return {'success': False, 'output': '', 'returncode': None,+ 'error': str(exc)}++ return {+ 'success': result.returncode == 0,+ 'output': result.stdout or '',+ 'returncode': result.returncode,+ 'error': ((result.stderr or '').strip() or f'command failed (exit {result.returncode})')+ if result.returncode != 0 else None,+ }++def write_privileged_file(path: str, content: str, *, append: bool = False,mode: Optional[str] = None,owner: Optional[str] = None) -> dict:diff --git a/backend/tests/BASELINE_COUNT b/backend/tests/BASELINE_COUNTindex 645e2f57..427dcc07 100644--- a/backend/tests/BASELINE_COUNT+++ b/backend/tests/BASELINE_COUNT@@ -1 +1 @@-3383+4081diff --git a/backend/tests/RAW_SUBPROCESS_CEILING b/backend/tests/RAW_SUBPROCESS_CEILINGnew file mode 100644index 00000000..8c9cf7e2--- /dev/null+++ b/backend/tests/RAW_SUBPROCESS_CEILING@@ -0,0 +1 @@+258diff --git a/backend/tests/raw_subprocess_census.py b/backend/tests/raw_subprocess_census.pynew file mode 100644index 00000000..ab12077c--- /dev/null+++ b/backend/tests/raw_subprocess_census.py@@ -0,0 +1,116 @@+"""Count raw ``subprocess.*`` call sites under ``backend/app`` (plan 75 §G1).++The existing CI audit greps a hand-maintained list of eight files for three+specific bad patterns. That catches a regression in a file someone remembered+to list; it says nothing about the other 250 raw calls, and nothing at all+about a *new* file. This is the other half: a census with a checked-in ceiling+that may only go down.++A "raw call" is any ``subprocess.<fn>(...)`` where ``<fn>`` actually spawns a+process. Building an argv list, catching ``subprocess.TimeoutExpired``, or+referencing ``subprocess.PIPE`` is not a call site and is not counted.++Usage (from ``backend/``)::++ python tests/raw_subprocess_census.py # print the count + report+ python tests/raw_subprocess_census.py --update # write the current count as the ceiling+"""++import ast+import os+import sys++HERE = os.path.dirname(os.path.abspath(__file__))+BACKEND = os.path.dirname(HERE)+APP_DIR = os.path.join(BACKEND, 'app')+CEILING_FILE = os.path.join(HERE, 'RAW_SUBPROCESS_CEILING')++# The functions that actually spawn. `Popen` included: it is the primitive the+# others funnel through, and a migration that "removes" a subprocess.run by+# hand-rolling a Popen has not removed anything.+SPAWNING = {'run', 'call', 'check_call', 'check_output', 'getoutput',+ 'getstatusoutput', 'Popen'}++# Vendored/third-party trees under app/ that are not ours to migrate.+SKIP_DIRS = {'__pycache__', 'node_modules', '.venv', 'venv'}+++def _iter_py_files(root):+ for dirpath, dirnames, filenames in os.walk(root):+ dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]+ for name in sorted(filenames):+ if name.endswith('.py'):+ yield os.path.join(dirpath, name)+++def count_file(path):+ """[(lineno, 'subprocess.run'), ...] for every spawning call in *path*."""+ try:+ tree = ast.parse(open(path, encoding='utf-8').read(), filename=path)+ except (SyntaxError, UnicodeDecodeError):+ return []+ hits = []+ for node in ast.walk(tree):+ if not isinstance(node, ast.Call):+ continue+ func = node.func+ if not isinstance(func, ast.Attribute) or func.attr not in SPAWNING:+ continue+ target = func.value+ if isinstance(target, ast.Name) and target.id == 'subprocess':+ hits.append((node.lineno, f'subprocess.{func.attr}'))+ return hits+++def census(root=APP_DIR):+ """{relative path: [(lineno, call), ...]} for every file with a raw call."""+ found = {}+ for path in _iter_py_files(root):+ hits = count_file(path)+ if hits:+ found[os.path.relpath(path, BACKEND).replace(os.sep, '/')] = hits+ return found+++def total(found=None):+ found = census() if found is None else found+ return sum(len(v) for v in found.values())+++def read_ceiling():+ with open(CEILING_FILE, encoding='utf-8') as fh:+ return int(fh.read().strip())+++def write_ceiling(value):+ with open(CEILING_FILE, 'w', encoding='utf-8', newline='\n') as fh:+ fh.write(f'{value}\n')+++def main(argv):+ found = census()+ count = total(found)+ if '--update' in argv:+ write_ceiling(count)+ print(f'RAW_SUBPROCESS_CEILING set to {count}')+ return 0++ ceiling = read_ceiling()+ print(f'raw subprocess call sites: {count} (ceiling {ceiling})')+ for path in sorted(found, key=lambda p: -len(found[p]))[:15]:+ print(f' {len(found[path]):3d} {path}')+ if count > ceiling:+ print(f'\nFAIL: {count - ceiling} new raw subprocess call site(s).')+ print('Route them through app/utils/system.py (run_checked / '+ 'run_privileged / write_privileged_file), or, if a raw call is '+ 'genuinely right here, raise the ceiling in the same commit and '+ 'say why.')+ return 1+ if count < ceiling:+ print(f'\n{ceiling - count} fewer than the ceiling — run with --update '+ 'to lock the improvement in.')+ return 0+++if __name__ == '__main__':+ sys.exit(main(sys.argv[1:]))diff --git a/backend/tests/test_raw_subprocess_ratchet.py b/backend/tests/test_raw_subprocess_ratchet.pynew file mode 100644index 00000000..2c43084d--- /dev/null+++ b/backend/tests/test_raw_subprocess_ratchet.py@@ -0,0 +1,107 @@+"""The raw-subprocess ratchet (plan 75 §G1).++The existing CI audit greps eight hand-listed files for three specific bad+patterns. That catches a regression in a file someone remembered to list; it+says nothing about the other 250 raw calls, and nothing at all about a new+file. This is the other half: a census with a checked-in ceiling that may only+go down.++It is a test rather than a shell step so it runs on a dev box before CI, and+so the counting is AST-based — a grep for `subprocess.run` also matches a+comment, a docstring, and `except subprocess.SubprocessError`.+"""++from raw_subprocess_census import census, count_file, read_ceiling, total+++def test_the_count_is_at_or_below_the_ceiling():+ found = census()+ count = total(found)+ ceiling = read_ceiling()+ worst = sorted(found, key=lambda p: -len(found[p]))[:5]+ assert count <= ceiling, (+ f'{count} raw subprocess call sites, ceiling is {ceiling}.\n'+ f'Route new calls through app/utils/system.py (run_checked, '+ f'run_privileged, write_privileged_file) or DockerService.run.\n'+ f'If a raw call is genuinely right, raise '+ f'tests/RAW_SUBPROCESS_CEILING in the same commit and say why.\n'+ f'Heaviest files: ' + ', '.join(f'{p} ({len(found[p])})' for p in worst)+ )+++def test_the_ceiling_is_not_stale():+ """A ceiling far above reality stops being a ratchet.++ Left un-updated after a migration it silently re-authorises every call the+ migration removed, so the next regression lands under it unnoticed. Slack+ of 10 is room for one in-flight branch, not for a whole workstream.+ """+ count, ceiling = total(), read_ceiling()+ assert ceiling - count <= 10, (+ f'ceiling {ceiling} is {ceiling - count} above the actual {count}; '+ f'run `python tests/raw_subprocess_census.py --update`'+ )+++class TestTheCensusCountsTheRightThings:+ """A miscounting ratchet is worse than none: it reads green either way."""++ def _count(self, tmp_path, source):+ path = tmp_path / 'sample.py'+ path.write_text(source, encoding='utf-8')+ return len(count_file(str(path)))++ def test_counts_every_spawning_entry_point(self, tmp_path):+ assert self._count(tmp_path, (+ 'import subprocess\n'+ 'subprocess.run(["a"])\n'+ 'subprocess.Popen(["b"])\n'+ 'subprocess.check_output(["c"])\n'+ 'subprocess.call(["d"])\n'+ 'subprocess.check_call(["e"])\n'+ )) == 5++ def test_does_not_count_exception_handling(self, tmp_path):+ assert self._count(tmp_path, (+ 'import subprocess\n'+ 'try:\n'+ ' pass\n'+ 'except subprocess.TimeoutExpired:\n'+ ' pass\n'+ 'except subprocess.SubprocessError:\n'+ ' pass\n'+ )) == 0++ def test_does_not_count_constants(self, tmp_path):+ assert self._count(tmp_path, (+ 'import subprocess\n'+ 'kw = {"stdin": subprocess.PIPE, "stderr": subprocess.DEVNULL}\n'+ )) == 0++ def test_does_not_count_a_wrapper_call(self, tmp_path):+ """run_checked(['ufw']) is the migration, not a violation of it."""+ assert self._count(tmp_path, (+ 'from app.utils.system import run_checked\n'+ 'run_checked(["ufw", "status"])\n'+ )) == 0++ def test_counts_a_call_inside_a_function_body(self, tmp_path):+ assert self._count(tmp_path, (+ 'import subprocess\n'+ 'def f():\n'+ ' if True:\n'+ ' return subprocess.run(["a"])\n'+ )) == 1++ def test_a_file_that_does_not_parse_is_skipped_not_crashed(self, tmp_path):+ path = tmp_path / 'broken.py'+ path.write_text('def (:\n', encoding='utf-8')+ assert count_file(str(path)) == []+++def test_the_doors_are_where_the_raw_calls_are_allowed_to_be():+ """app/utils/system.py and docker_service.py are supposed to hold raw+ calls — they are the doors. This pins that the census sees them, so a+ change that accidentally stopped scanning app/ would not read as a win."""+ found = census()+ assert found.get('app/utils/system.py'), 'census stopped seeing the helpers'diff --git a/backend/tests/test_utils_system.py b/backend/tests/test_utils_system.pyindex c97a8711..7a07c68f 100644--- a/backend/tests/test_utils_system.py+++ b/backend/tests/test_utils_system.py@@ -43,6 +43,7 @@ PackageManager = _module.PackageManagerServiceControl = _module.ServiceControlwrite_privileged_file = _module.write_privileged_fileunit_is_active = _module.unit_is_active+run_checked = _module.run_checked# ---------------------------------------------------------------------------@@ -606,3 +607,121 @@ class TestUnitIsActive:mock_run.return_value = subprocess.CompletedProcess([], 0, stdout='active', stderr='')unit_is_active('nginx')assert mock_run.call_args[0][0] == ['systemctl', 'is-active', 'nginx']+++# ---------------------------------------------------------------------------+# run_checked+# ---------------------------------------------------------------------------+class TestRunChecked:+ """The result-shaped door (plan 75 §G1).++ Around the raw subprocess calls it replaces sit 220 copies of+ capture_output/text, 56 hand-rolled TimeoutExpired handlers, 19+ FileNotFoundError handlers, and 1,164 literal error dicts. Each is a place+ an exec failure can become a false fact; the properties that stop that are+ asserted once, here.+ """++ @patch('app.utils.system.subprocess.run')+ def test_success_shape(self, mock_run):+ mock_run.return_value = subprocess.CompletedProcess([], 0, stdout='hi\n', stderr='')+ assert run_checked(['echo', 'hi']) == {+ 'success': True, 'output': 'hi\n', 'error': None, 'returncode': 0}++ @patch('app.utils.system.subprocess.run')+ def test_capture_and_text_are_applied_for_the_caller(self, mock_run):+ mock_run.return_value = subprocess.CompletedProcess([], 0, stdout='', stderr='')+ run_checked(['echo'])+ assert mock_run.call_args[1]['capture_output'] is True+ assert mock_run.call_args[1]['text'] is True++ @patch('app.utils.system.subprocess.run')+ def test_nonzero_exit_carries_stderr_and_the_code(self, mock_run):+ mock_run.return_value = subprocess.CompletedProcess([], 2, stdout='', stderr='nope\n')+ result = run_checked(['false'])+ assert result['success'] is False+ assert result['error'] == 'nope'+ assert result['returncode'] == 2++ @patch('app.utils.system.subprocess.run')+ def test_nonzero_exit_with_silent_stderr_still_explains_itself(self, mock_run):+ mock_run.return_value = subprocess.CompletedProcess([], 3, stdout='', stderr='')+ assert '3' in run_checked(['false'])['error']++ # ---- the distinction the hand-rolled handlers keep losing --------------+ # patch.object on _module, not @patch('app.utils.system.resolve_command'):+ # this file loads system.py under its own spec, so the string path can+ # resolve to a DIFFERENT module object than the one run_checked closes+ # over, depending on what imported `app` earlier in the session. `shutil`+ # is a singleton so patching through it is identity-safe; a module-level+ # function of system.py is not.+ @patch('app.utils.system.subprocess.run', side_effect=FileNotFoundError('no ufw'))+ @patch('app.utils.system.shutil.which', return_value=None)+ @patch.object(_module, 'resolve_command', return_value=None)+ def test_missing_command_has_no_returncode(self, _resolve, _which, _run):+ """Exit 1 means the command answered "no"; no exit code at all means+ nobody answered. A caller rendering "not installed" must be able to+ tell those apart — plan 74's outage in one assertion."""+ result = run_checked(['ufw', 'status'])+ assert result['success'] is False+ assert result['returncode'] is None+ assert 'ufw' in result['error']++ @patch('app.utils.system.subprocess.run',+ side_effect=subprocess.TimeoutExpired('sleep', 60))+ def test_timeout_has_no_returncode_and_names_the_limit(self, _run):+ result = run_checked(['sleep', '999'], timeout=60)+ assert result['returncode'] is None+ assert 'timed out' in result['error'] and '60' in result['error']++ @patch('app.utils.system.subprocess.run', side_effect=PermissionError('denied'))+ def test_permission_error_is_reported_not_raised(self, _run):+ result = run_checked(['/root/thing'])+ assert result['success'] is False and result['returncode'] is None+ assert 'permission denied' in result['error']++ @patch('app.utils.system.subprocess.run')+ def test_a_timeout_is_applied_by_default(self, mock_run):+ """No timeout + captured output = a wedged request, silently, forever."""+ mock_run.return_value = subprocess.CompletedProcess([], 0, stdout='', stderr='')+ run_checked(['echo'])+ assert mock_run.call_args[1]['timeout'] == 60++ @patch('app.utils.system.subprocess.run')+ def test_timeout_none_is_honoured_when_asked_for(self, mock_run):+ mock_run.return_value = subprocess.CompletedProcess([], 0, stdout='', stderr='')+ run_checked(['echo'], timeout=None)+ assert mock_run.call_args[1]['timeout'] is None++ # ---- privilege + PATH, decided in one place ---------------------------+ @patch('app.utils.system.os.name', 'posix')+ @patch('app.utils.system.shutil.which', return_value='/usr/bin/sudo')+ @patch('app.utils.system.subprocess.run')+ @patch('app.utils.system.os.geteuid', return_value=1000, create=True)+ def test_privileged_goes_through_run_privileged(self, _euid, mock_run, *_):+ mock_run.return_value = subprocess.CompletedProcess([], 0, stdout='', stderr='')+ run_checked(['systemctl', 'restart', 'nginx'], privileged=True)+ assert mock_run.call_args[0][0][:2] == ['sudo', '-n']++ @patch('app.utils.system.subprocess.run')+ @patch('app.utils.system.shutil.which', return_value=None)+ @patch.object(_module, 'resolve_command', return_value='/usr/sbin/nginx')+ def test_unprivileged_still_resolves_an_sbin_binary(self, _resolve, _which, mock_run):+ """The sbin outage does not become survivable only when you ask for+ root — an unprivileged `nginx -t` needs the same resolution."""+ mock_run.return_value = subprocess.CompletedProcess([], 0, stdout='', stderr='')+ run_checked(['nginx', '-t'])+ assert mock_run.call_args[0][0] == ['/usr/sbin/nginx', '-t']++ @patch('app.utils.system.subprocess.run')+ @patch('app.utils.system.shutil.which', return_value='/usr/bin/git')+ def test_a_command_on_path_is_left_alone(self, _which, mock_run):+ mock_run.return_value = subprocess.CompletedProcess([], 0, stdout='', stderr='')+ run_checked(['git', 'status'])+ assert mock_run.call_args[0][0] == ['git', 'status']++ @patch('app.utils.system.subprocess.run')+ def test_input_is_forwarded(self, mock_run):+ mock_run.return_value = subprocess.CompletedProcess([], 0, stdout='', stderr='')+ run_checked(['crontab', '-'], input='* * * * * true\n')+ assert mock_run.call_args[1]['input'] == '* * * * * true\n'