Skip to content

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.

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.yml
index 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 services
run: |
MIGRATED_FILES=(
diff --git a/backend/app/services/cron_service.py b/backend/app/services/cron_service.py
index 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, Optional
from datetime import datetime
import json
-from app.utils.system import unit_is_active
+from app.utils.system import run_checked, unit_is_active
# Path for storing job metadata
JOBS_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'}
+
@classmethod
def 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 metadata
metadata['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 metadata
if 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 metadata
metadata['jobs'][job_id]['enabled'] = enabled
@@ -571,41 +539,22 @@ class CronService:
# Update crontab on Linux if schedule or command changed
if 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 metadata
if 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 success
or 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.py
index 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_COUNT
index 645e2f57..427dcc07 100644
--- a/backend/tests/BASELINE_COUNT
+++ b/backend/tests/BASELINE_COUNT
@@ -1 +1 @@
-3383
+4081
diff --git a/backend/tests/RAW_SUBPROCESS_CEILING b/backend/tests/RAW_SUBPROCESS_CEILING
new file mode 100644
index 00000000..8c9cf7e2
--- /dev/null
+++ b/backend/tests/RAW_SUBPROCESS_CEILING
@@ -0,0 +1 @@
+258
diff --git a/backend/tests/raw_subprocess_census.py b/backend/tests/raw_subprocess_census.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index c97a8711..7a07c68f 100644
--- a/backend/tests/test_utils_system.py
+++ b/backend/tests/test_utils_system.py
@@ -43,6 +43,7 @@ PackageManager = _module.PackageManager
ServiceControl = _module.ServiceControl
write_privileged_file = _module.write_privileged_file
unit_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'