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(docker): route docker_service through the shared doors

Juan Denis7383820085b5
diff --git a/backend/app/services/docker_service.py b/backend/app/services/docker_service.py
index 0b110d6c..8f214a0d 100644
--- a/backend/app/services/docker_service.py
+++ b/backend/app/services/docker_service.py
@@ -7,6 +7,8 @@ import shlex
import yaml
from datetime import datetime
+from app.utils.system import run_checked
+
logger = logging.getLogger(__name__)
# Docker-style memory limit: a number plus a one-letter unit (bytes/kilo/mega/giga).
@@ -23,15 +25,19 @@ class DockerService:
"""Detect whether to use 'docker compose' (v2) or 'docker-compose' (v1)."""
if cls._compose_cmd is not None:
return cls._compose_cmd
+ # run_checked, not cls.run: this probe decides what `run_compose` will
+ # invoke, so it must not depend on anything compose-shaped itself.
+ #
+ # Still wrapped: run_checked converts the exec failures it knows about
+ # into a result, but this probe runs before anything else in the
+ # compose path and must not be able to raise into its caller at all —
+ # dropping the guard here made a broken Popen surface as
+ # `compose up` exit_code -1 instead of falling back to v1.
try:
- result = subprocess.run(
- ['docker', 'compose', 'version'],
- capture_output=True, text=True
- )
- if result.returncode == 0:
+ if run_checked(['docker', 'compose', 'version'], timeout=None)['success']:
cls._compose_cmd = ['docker', 'compose']
return cls._compose_cmd
- except Exception as e:
+ except Exception as e: # noqa: BLE001
logger.error(f"Failed to detect docker compose v2: {e}")
# Fallback to docker-compose (v1)
cls._compose_cmd = ['docker-compose']
@@ -48,8 +54,11 @@ class DockerService:
"""
return cls._get_compose_cmd() == ['docker', 'compose']
+ # Long docker operations (pull, build, compose up) are unbounded today.
+ # `None` is passed explicitly at those call sites so the 60s default here
+ # cannot silently cap a build; see COMPOSE/LONG notes below.
@staticmethod
- def run(args, timeout=60):
+ def run(args, timeout=60, **kwargs):
"""Run ``docker <args>``; one result shape for every caller (§G3).
Three services kept private ``_docker()`` wrappers around this exact
@@ -60,28 +69,15 @@ class DockerService:
``result['success']`` against the third silently got a ``KeyError``
rather than an answer.
- Returns ``{'success': bool, 'output': str, 'error': str|None}``.
- ``error`` distinguishes the three things that are not "the command said
- no": docker absent, docker too slow, and everything else. A caller that
+ Sits on ``run_checked`` (§G1) rather than re-implementing it, so the
+ result shape and the error handling have exactly one definition:
+ ``{'success', 'output', 'stderr', 'error', 'returncode'}``. ``error``
+ distinguishes the three things that are not "the command said no":
+ docker absent, docker too slow, and everything else. A caller that
cannot tell those apart is the caller that reports "not installed"
because a probe timed out (§A).
"""
- try:
- result = subprocess.run(['docker', *args], capture_output=True,
- text=True, timeout=timeout)
- except FileNotFoundError:
- return {'success': False, 'output': '', 'error': 'Docker not found'}
- except subprocess.TimeoutExpired:
- return {'success': False, 'output': '',
- 'error': f'Docker command timed out after {timeout}s'}
- except Exception as e: # noqa: BLE001
- return {'success': False, 'output': '', 'error': str(e)}
- return {
- 'success': result.returncode == 0,
- 'output': result.stdout or '',
- 'error': ((result.stderr or '').strip() or 'docker command failed')
- if result.returncode != 0 else None,
- }
+ return run_checked(['docker', *args], timeout=timeout, **kwargs)
@classmethod
def available(cls):
@@ -100,31 +96,24 @@ class DockerService:
@staticmethod
def is_docker_installed():
"""Check if Docker is installed and running."""
+ result = DockerService.run(['version', '--format', 'json'], timeout=None)
+ if not result['success']:
+ return {'installed': False, 'error': result['error']}
try:
- result = subprocess.run(
- ['docker', 'version', '--format', 'json'],
- capture_output=True, text=True
- )
- if result.returncode == 0:
- return {'installed': True, 'info': json.loads(result.stdout)}
- return {'installed': False, 'error': result.stderr}
- except FileNotFoundError:
- return {'installed': False, 'error': 'Docker not found'}
- except Exception as e:
- return {'installed': False, 'error': str(e)}
+ return {'installed': True, 'info': json.loads(result['output'])}
+ except ValueError as e:
+ return {'installed': False, 'error': f'unreadable docker version output: {e}'}
@staticmethod
def get_docker_info():
"""Get Docker system information."""
- try:
- result = subprocess.run(
- ['docker', 'info', '--format', '{{json .}}'],
- capture_output=True, text=True
- )
- if result.returncode == 0:
- return json.loads(result.stdout)
+ result = DockerService.run(['info', '--format', '{{json .}}'], timeout=None)
+ if not result['success']:
+ logger.error('Failed to get Docker info: %s', result['error'])
return None
- except Exception as e:
+ try:
+ return json.loads(result['output'])
+ except ValueError as e:
logger.error(f"Failed to get Docker info: {e}")
return None
@@ -165,16 +154,16 @@ class DockerService:
def list_containers(all_containers=True):
"""List Docker containers."""
try:
- cmd = ['docker', 'ps', '--format', '{{json .}}']
+ args = ['ps', '--format', '{{json .}}']
if all_containers:
- cmd.insert(2, '-a')
+ args.insert(1, '-a')
- result = subprocess.run(cmd, capture_output=True, text=True)
- if result.returncode != 0:
+ result = DockerService.run(args, timeout=None)
+ if not result['success']:
return []
containers = []
- for line in result.stdout.strip().split('\n'):
+ for line in result['output'].strip().split('\n'):
if line:
container = json.loads(line)
name = container.get('Names')
@@ -236,21 +225,17 @@ class DockerService:
"""
keys = [k for k, _ in cls._PS_LABEL_FIELDS]
fmt = '\t'.join(tpl for _, tpl in cls._PS_LABEL_FIELDS)
- cmd = ['docker', 'ps', '--no-trunc', '--format', fmt]
+ args = ['ps', '--no-trunc', '--format', fmt]
if all_containers:
- cmd.insert(2, '-a')
+ args.insert(1, '-a')
- try:
- result = subprocess.run(cmd, capture_output=True, text=True)
- if result.returncode != 0:
- logger.warning('docker ps (bulk) failed: %s', result.stderr.strip())
- return []
- except Exception as e:
- logger.error(f"Failed to bulk-list containers: {e}")
+ result = cls.run(args, timeout=None)
+ if not result['success']:
+ logger.warning('docker ps (bulk) failed: %s', result['error'])
return []
containers = []
- for line in (result.stdout or '').splitlines():
+ for line in result['output'].splitlines():
if not line.strip():
continue
parts = line.split('\t')
@@ -269,26 +254,22 @@ class DockerService:
@staticmethod
def get_container(container_id):
"""Get detailed container information."""
- try:
- result = subprocess.run(
- ['docker', 'inspect', container_id],
- capture_output=True, text=True
- )
- if result.returncode == 0:
- data = json.loads(result.stdout)
- if data:
- return data[0]
+ result = DockerService.run(['inspect', container_id], timeout=None)
+ if not result['success']:
return None
- except Exception as e:
+ try:
+ data = json.loads(result['output'])
+ except ValueError as e:
logger.error(f"Failed to inspect container {container_id}: {e}")
return None
+ return data[0] if data else None
@staticmethod
def create_container(image, name=None, ports=None, volumes=None, env=None,
network=None, restart_policy='unless-stopped', command=None):
"""Create a new container."""
try:
- cmd = ['docker', 'create']
+ cmd = ['create']
if name:
cmd.extend(['--name', name])
@@ -316,12 +297,11 @@ class DockerService:
if command:
cmd.extend(shlex.split(command))
- result = subprocess.run(cmd, capture_output=True, text=True)
-
- if result.returncode == 0:
- container_id = result.stdout.strip()
- return {'success': True, 'container_id': container_id}
- return {'success': False, 'error': result.stderr}
+ # LONG: `docker create`/`run` pulls the image when it is absent.
+ result = DockerService.run(cmd, timeout=None)
+ if result['success']:
+ return {'success': True, 'container_id': result['output'].strip()}
+ return {'success': False, 'error': result['error']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -330,7 +310,7 @@ class DockerService:
network=None, restart_policy='unless-stopped', command=None, detach=True):
"""Run a new container (create and start)."""
try:
- cmd = ['docker', 'run']
+ cmd = ['run']
if detach:
cmd.append('-d')
@@ -361,12 +341,11 @@ class DockerService:
if command:
cmd.extend(shlex.split(command))
- result = subprocess.run(cmd, capture_output=True, text=True)
-
- if result.returncode == 0:
- container_id = result.stdout.strip()
- return {'success': True, 'container_id': container_id}
- return {'success': False, 'error': result.stderr}
+ # LONG: `docker create`/`run` pulls the image when it is absent.
+ result = DockerService.run(cmd, timeout=None)
+ if result['success']:
+ return {'success': True, 'container_id': result['output'].strip()}
+ return {'success': False, 'error': result['error']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -374,13 +353,10 @@ class DockerService:
def start_container(container_id):
"""Start a container."""
try:
- result = subprocess.run(
- ['docker', 'start', container_id],
- capture_output=True, text=True
- )
- if result.returncode == 0:
+ result = DockerService.run(['start', container_id], timeout=None)
+ if result['success']:
return {'success': True}
- return {'success': False, 'error': result.stderr}
+ return {'success': False, 'error': result['error']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -388,17 +364,15 @@ class DockerService:
def stop_container(container_id, timeout=10):
"""Stop a container."""
try:
- result = subprocess.run(
- ['docker', 'stop', '-t', str(timeout), container_id],
- capture_output=True, text=True
- )
- if result.returncode == 0:
+ result = DockerService.run(['stop', '-t', str(timeout), container_id],
+ timeout=None)
+ if result['success']:
# The panel emits the `app.stopped` event via the audit trail
# (AuditService.log('app.stop') -> EventService.emit_for_audit),
# so this low-level helper no longer emits its own event -- doing
# so would double-fire it for Automations triggers (plan 45 Ph4).
return {'success': True}
- return {'success': False, 'error': result.stderr}
+ return {'success': False, 'error': result['error']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -406,13 +380,11 @@ class DockerService:
def restart_container(container_id, timeout=10):
"""Restart a container."""
try:
- result = subprocess.run(
- ['docker', 'restart', '-t', str(timeout), container_id],
- capture_output=True, text=True
- )
- if result.returncode == 0:
+ result = DockerService.run(['restart', '-t', str(timeout), container_id],
+ timeout=None)
+ if result['success']:
return {'success': True}
- return {'success': False, 'error': result.stderr}
+ return {'success': False, 'error': result['error']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -420,17 +392,17 @@ class DockerService:
def remove_container(container_id, force=False, volumes=False):
"""Remove a container."""
try:
- cmd = ['docker', 'rm']
+ cmd = ['rm']
if force:
cmd.append('-f')
if volumes:
cmd.append('-v')
cmd.append(container_id)
- result = subprocess.run(cmd, capture_output=True, text=True)
- if result.returncode == 0:
+ result = DockerService.run(cmd, timeout=None)
+ if result['success']:
return {'success': True}
- return {'success': False, 'error': result.stderr}
+ return {'success': False, 'error': result['error']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -438,7 +410,7 @@ class DockerService:
def get_container_logs(container_id, tail=100, since=None, timestamps=True):
"""Get container logs."""
try:
- cmd = ['docker', 'logs']
+ cmd = ['logs']
if tail:
cmd.extend(['--tail', str(tail)])
if since:
@@ -447,10 +419,11 @@ class DockerService:
cmd.append('-t')
cmd.append(container_id)
- result = subprocess.run(cmd, capture_output=True, text=True)
- # Docker logs go to both stdout and stderr
- logs = result.stdout + result.stderr
- return {'success': True, 'logs': logs}
+ # merge_stderr, not stdout + stderr: a container writes its log to
+ # both streams and concatenating them loses the interleaving, so
+ # the tail of a crash landed above the lines that led to it.
+ result = DockerService.run(cmd, timeout=None, merge_stderr=True)
+ return {'success': True, 'logs': result['output']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -686,12 +659,11 @@ class DockerService:
def get_container_stats(container_id):
"""Get container resource usage stats."""
try:
- result = subprocess.run(
- ['docker', 'stats', '--no-stream', '--format', '{{json .}}', container_id],
- capture_output=True, text=True
- )
- if result.returncode == 0 and result.stdout.strip():
- return json.loads(result.stdout.strip())
+ result = DockerService.run(
+ ['stats', '--no-stream', '--format', '{{json .}}', container_id],
+ timeout=None)
+ if result['success'] and result['output'].strip():
+ return json.loads(result['output'].strip())
return None
except Exception as e:
logger.error(f"Failed to get stats for container {container_id}: {e}")
@@ -708,16 +680,15 @@ class DockerService:
if not cleaned_ids:
return {}
- result = subprocess.run(
- ['docker', 'stats', '--no-stream', '--format', '{{json .}}', *cleaned_ids],
- capture_output=True, text=True
- )
- if result.returncode != 0:
- logger.error(f"Failed to get container stats: {result.stderr.strip()}")
+ result = DockerService.run(
+ ['stats', '--no-stream', '--format', '{{json .}}', *cleaned_ids],
+ timeout=None)
+ if not result['success']:
+ logger.error(f"Failed to get container stats: {result['error']}")
return {}
stats_map = {}
- for line in result.stdout.splitlines():
+ for line in result['output'].splitlines():
if not line.strip():
continue
stats = json.loads(line)
@@ -733,7 +704,7 @@ class DockerService:
def exec_command(container_id, command, interactive=False, tty=False):
"""Execute a command in a running container."""
try:
- cmd = ['docker', 'exec']
+ cmd = ['exec']
if interactive:
cmd.append('-i')
if tty:
@@ -741,15 +712,17 @@ class DockerService:
cmd.append(container_id)
cmd.extend(shlex.split(command))
- result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
+ result = DockerService.run(cmd, timeout=60)
+ if result['returncode'] is None:
+ # The command never ran (no docker, timed out). Reporting a
+ # return_code here would claim the container answered.
+ return {'success': False, 'error': result['error']}
return {
- 'success': result.returncode == 0,
- 'stdout': result.stdout,
- 'stderr': result.stderr,
- 'return_code': result.returncode
+ 'success': result['success'],
+ 'stdout': result['output'],
+ 'stderr': result['stderr'],
+ 'return_code': result['returncode'],
}
- except subprocess.TimeoutExpired:
- return {'success': False, 'error': 'Command timed out'}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -759,15 +732,13 @@ class DockerService:
def list_images():
"""List Docker images."""
try:
- result = subprocess.run(
- ['docker', 'images', '--format', '{{json .}}'],
- capture_output=True, text=True
- )
- if result.returncode != 0:
+ result = DockerService.run(['images', '--format', '{{json .}}'],
+ timeout=None)
+ if not result['success']:
return []
images = []
- for line in result.stdout.strip().split('\n'):
+ for line in result['output'].strip().split('\n'):
if line:
image = json.loads(line)
images.append({
@@ -804,13 +775,12 @@ class DockerService:
'error': f"Registry login failed: {login.get('error')}"}
logged_in = True
- result = subprocess.run(
- ['docker', 'pull', full_name],
- capture_output=True, text=True
- )
- if result.returncode == 0:
- return {'success': True, 'output': result.stdout}
- return {'success': False, 'error': result.stderr}
+ # LONG: a pull is unbounded today and can legitimately run for
+ # many minutes on a slow link.
+ result = DockerService.run(['pull', full_name], timeout=None)
+ if result['success']:
+ return {'success': True, 'output': result['output']}
+ return {'success': False, 'error': result['error']}
except Exception as e:
return {'success': False, 'error': str(e)}
finally:
@@ -822,15 +792,15 @@ class DockerService:
def remove_image(image_id, force=False):
"""Remove an image."""
try:
- cmd = ['docker', 'rmi']
+ cmd = ['rmi']
if force:
cmd.append('-f')
cmd.append(image_id)
- result = subprocess.run(cmd, capture_output=True, text=True)
- if result.returncode == 0:
+ result = DockerService.run(cmd, timeout=None)
+ if result['success']:
return {'success': True}
- return {'success': False, 'error': result.stderr}
+ return {'success': False, 'error': result['error']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -838,17 +808,18 @@ class DockerService:
def build_image(path, tag, dockerfile='Dockerfile', no_cache=False):
"""Build an image from Dockerfile."""
try:
- cmd = ['docker', 'build', '-t', tag]
+ cmd = ['build', '-t', tag]
if dockerfile != 'Dockerfile':
cmd.extend(['-f', dockerfile])
if no_cache:
cmd.append('--no-cache')
cmd.append(path)
- result = subprocess.run(cmd, capture_output=True, text=True)
- if result.returncode == 0:
- return {'success': True, 'output': result.stdout}
- return {'success': False, 'error': result.stderr, 'output': result.stdout}
+ # LONG: a build is unbounded today.
+ result = DockerService.run(cmd, timeout=None)
+ if result['success']:
+ return {'success': True, 'output': result['output']}
+ return {'success': False, 'error': result['error'], 'output': result['output']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -856,13 +827,10 @@ class DockerService:
def tag_image(source, target):
"""Tag an image."""
try:
- result = subprocess.run(
- ['docker', 'tag', source, target],
- capture_output=True, text=True
- )
- if result.returncode == 0:
+ result = DockerService.run(['tag', source, target], timeout=None)
+ if result['success']:
return {'success': True}
- return {'success': False, 'error': result.stderr}
+ return {'success': False, 'error': result['error']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -872,15 +840,13 @@ class DockerService:
def list_networks():
"""List Docker networks."""
try:
- result = subprocess.run(
- ['docker', 'network', 'ls', '--format', '{{json .}}'],
- capture_output=True, text=True
- )
- if result.returncode != 0:
+ result = DockerService.run(['network', 'ls', '--format', '{{json .}}'],
+ timeout=None)
+ if not result['success']:
return []
networks = []
- for line in result.stdout.strip().split('\n'):
+ for line in result['output'].strip().split('\n'):
if line:
network = json.loads(line)
networks.append({
@@ -898,13 +864,11 @@ class DockerService:
def create_network(name, driver='bridge'):
"""Create a Docker network."""
try:
- result = subprocess.run(
- ['docker', 'network', 'create', '--driver', driver, name],
- capture_output=True, text=True
- )
- if result.returncode == 0:
- return {'success': True, 'network_id': result.stdout.strip()}
- return {'success': False, 'error': result.stderr}
+ result = DockerService.run(['network', 'create', '--driver', driver, name],
+ timeout=None)
+ if result['success']:
+ return {'success': True, 'network_id': result['output'].strip()}
+ return {'success': False, 'error': result['error']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -914,14 +878,8 @@ class DockerService:
The shared external ``serverkit`` network lets manifest-generated app
projects resolve each other by container name (fromService.host)."""
- try:
- inspect = subprocess.run(
- ['docker', 'network', 'inspect', name],
- capture_output=True, text=True)
- if inspect.returncode == 0:
- return {'success': True, 'existed': True}
- except Exception as e:
- return {'success': False, 'error': str(e)}
+ if DockerService.run(['network', 'inspect', name], timeout=None)['success']:
+ return {'success': True, 'existed': True}
created = DockerService.create_network(name, driver=driver)
created['existed'] = False
return created
@@ -930,13 +888,10 @@ class DockerService:
def remove_network(network_id):
"""Remove a Docker network."""
try:
- result = subprocess.run(
- ['docker', 'network', 'rm', network_id],
- capture_output=True, text=True
- )
- if result.returncode == 0:
+ result = DockerService.run(['network', 'rm', network_id], timeout=None)
+ if result['success']:
return {'success': True}
- return {'success': False, 'error': result.stderr}
+ return {'success': False, 'error': result['error']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -946,15 +901,13 @@ class DockerService:
def list_volumes():
"""List Docker volumes."""
try:
- result = subprocess.run(
- ['docker', 'volume', 'ls', '--format', '{{json .}}'],
- capture_output=True, text=True
- )
- if result.returncode != 0:
+ result = DockerService.run(['volume', 'ls', '--format', '{{json .}}'],
+ timeout=None)
+ if not result['success']:
return []
volumes = []
- for line in result.stdout.strip().split('\n'):
+ for line in result['output'].strip().split('\n'):
if line:
volume = json.loads(line)
volumes.append({
@@ -971,13 +924,11 @@ class DockerService:
def create_volume(name, driver='local'):
"""Create a Docker volume."""
try:
- result = subprocess.run(
- ['docker', 'volume', 'create', '--driver', driver, name],
- capture_output=True, text=True
- )
- if result.returncode == 0:
- return {'success': True, 'volume_name': result.stdout.strip()}
- return {'success': False, 'error': result.stderr}
+ result = DockerService.run(['volume', 'create', '--driver', driver, name],
+ timeout=None)
+ if result['success']:
+ return {'success': True, 'volume_name': result['output'].strip()}
+ return {'success': False, 'error': result['error']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -985,15 +936,15 @@ class DockerService:
def remove_volume(volume_name, force=False):
"""Remove a Docker volume."""
try:
- cmd = ['docker', 'volume', 'rm']
+ cmd = ['volume', 'rm']
if force:
cmd.append('-f')
cmd.append(volume_name)
- result = subprocess.run(cmd, capture_output=True, text=True)
- if result.returncode == 0:
+ result = DockerService.run(cmd, timeout=None)
+ if result['success']:
return {'success': True}
- return {'success': False, 'error': result.stderr}
+ return {'success': False, 'error': result['error']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -1001,13 +952,10 @@ class DockerService:
def inspect_volume(name):
"""Live state of a named volume: {'present', 'mountpoint', 'driver'}."""
try:
- result = subprocess.run(
- ['docker', 'volume', 'inspect', name],
- capture_output=True, text=True
- )
- if result.returncode != 0:
+ result = DockerService.run(['volume', 'inspect', name], timeout=None)
+ if not result['success']:
return {'present': False, 'mountpoint': None, 'driver': None}
- data = json.loads(result.stdout or '[]')
+ data = json.loads(result['output'] or '[]')
info = data[0] if data else {}
return {'present': True, 'mountpoint': info.get('Mountpoint'),
'driver': info.get('Driver')}
@@ -1019,14 +967,14 @@ class DockerService:
"""Names of containers referencing a volume. ``running_only`` limits it to
currently-running containers (the guard for a safe wipe)."""
try:
- cmd = ['docker', 'ps']
+ cmd = ['ps']
if not running_only:
cmd.append('-a')
cmd += ['--filter', f'volume={name}', '--format', '{{.Names}}']
- result = subprocess.run(cmd, capture_output=True, text=True)
- if result.returncode != 0:
+ result = DockerService.run(cmd, timeout=None)
+ if not result['success']:
return []
- return [n for n in result.stdout.strip().split('\n') if n]
+ return [n for n in result['output'].strip().split('\n') if n]
except Exception:
return []
@@ -1064,16 +1012,30 @@ class DockerService:
logger.debug('compose overlay command build failed for %s: %s', project_path, e)
return cls._compose_base_cmd(compose_file)
+ @classmethod
+ def run_compose(cls, cmd, *, cwd=None, timeout=None):
+ """Run an already-built compose argv; the shared result shape (§G1).
+
+ Separate from :meth:`run` because the argv head is whatever
+ ``_get_compose_cmd()`` resolved — ``docker compose`` (v2) or
+ ``docker-compose`` (v1) — not a literal ``docker``.
+
+ ``timeout=None`` by default, unlike :meth:`run`. Every compose call in
+ this file is unbounded today, and ``compose up --build`` on a small VPS
+ routinely runs longer than a minute; inheriting a 60s default here
+ would turn working deploys into timeouts. Bounding them is a real
+ improvement and a deliberate behaviour change, not a side effect of
+ this collapse.
+ """
+ return run_checked(cmd, cwd=cwd, timeout=timeout)
+
@classmethod
def compose_list(cls):
"""List Docker Compose projects known to the Docker CLI."""
try:
- result = subprocess.run(
- cls._get_compose_cmd() + ['ls', '--format', 'json'],
- capture_output=True, text=True
- )
- if result.returncode == 0 and result.stdout.strip():
- output = result.stdout.strip()
+ result = cls.run_compose(cls._get_compose_cmd() + ['ls', '--format', 'json'])
+ if result['success'] and result['output'].strip():
+ output = result['output'].strip()
try:
parsed = json.loads(output)
if isinstance(parsed, list):
@@ -1105,15 +1067,13 @@ class DockerService:
def _compose_list_from_container_labels():
"""Fallback for older compose binaries without `compose ls --format json`."""
try:
- result = subprocess.run(
- ['docker', 'ps', '-a', '--format', '{{json .}}'],
- capture_output=True, text=True
- )
- if result.returncode != 0:
+ result = DockerService.run(['ps', '-a', '--format', '{{json .}}'],
+ timeout=None)
+ if not result['success']:
return []
projects = {}
- for line in result.stdout.strip().split('\n'):
+ for line in result['output'].strip().split('\n'):
if not line:
continue
container = json.loads(line)
@@ -1170,13 +1130,10 @@ class DockerService:
if build:
cmd.append('--build')
- result = subprocess.run(
- cmd, cwd=project_path,
- capture_output=True, text=True
- )
- if result.returncode == 0:
- return {'success': True, 'output': result.stdout}
- return {'success': False, 'error': result.stderr, 'output': result.stdout}
+ result = cls.run_compose(cmd, cwd=project_path)
+ if result['success']:
+ return {'success': True, 'output': result['output']}
+ return {'success': False, 'error': result['error'], 'output': result['output']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -1244,13 +1201,10 @@ class DockerService:
if remove_orphans:
cmd.append('--remove-orphans')
- result = subprocess.run(
- cmd, cwd=project_path,
- capture_output=True, text=True
- )
- if result.returncode == 0:
- return {'success': True, 'output': result.stdout}
- return {'success': False, 'error': result.stderr}
+ result = cls.run_compose(cmd, cwd=project_path)
+ if result['success']:
+ return {'success': True, 'output': result['output']}
+ return {'success': False, 'error': result['error']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -1266,14 +1220,12 @@ class DockerService:
Returns a list of container dictionaries.
"""
try:
- result = subprocess.run(
+ result = cls.run_compose(
cls._compose_base_cmd(compose_file) + ['ps', '--format', 'json'],
- cwd=project_path,
- capture_output=True, text=True
- )
- if result.returncode == 0 and result.stdout.strip():
+ cwd=project_path)
+ if result['success'] and result['output'].strip():
containers = []
- for line in result.stdout.strip().split('\n'):
+ for line in result['output'].strip().split('\n'):
line = line.strip()
# Skip empty lines and warning messages (e.g., "time=..." from docker)
if not line or line.startswith('time=') or line.startswith('WARN'):
@@ -1304,11 +1256,9 @@ class DockerService:
if service:
cmd.append(service)
- result = subprocess.run(
- cmd, cwd=project_path,
- capture_output=True, text=True
- )
- return {'success': True, 'logs': result.stdout + result.stderr}
+ result = run_checked(cmd, cwd=project_path, timeout=None,
+ merge_stderr=True)
+ return {'success': True, 'logs': result['output']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -1320,13 +1270,10 @@ class DockerService:
if service:
cmd.append(service)
- result = subprocess.run(
- cmd, cwd=project_path,
- capture_output=True, text=True
- )
- if result.returncode == 0:
+ result = cls.run_compose(cmd, cwd=project_path)
+ if result['success']:
return {'success': True}
- return {'success': False, 'error': result.stderr}
+ return {'success': False, 'error': result['error']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -1338,13 +1285,10 @@ class DockerService:
if service:
cmd.append(service)
- result = subprocess.run(
- cmd, cwd=project_path,
- capture_output=True, text=True
- )
- if result.returncode == 0:
- return {'success': True, 'output': result.stdout}
- return {'success': False, 'error': result.stderr}
+ result = cls.run_compose(cmd, cwd=project_path)
+ if result['success']:
+ return {'success': True, 'output': result['output']}
+ return {'success': False, 'error': result['error']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -1363,13 +1307,10 @@ class DockerService:
if service:
cmd.append(service)
- result = subprocess.run(
- cmd, cwd=project_path,
- capture_output=True, text=True
- )
- if result.returncode == 0:
- return {'success': True, 'output': result.stdout}
- return {'success': False, 'error': result.stderr, 'output': result.stdout}
+ result = cls.run_compose(cmd, cwd=project_path)
+ if result['success']:
+ return {'success': True, 'output': result['output']}
+ return {'success': False, 'error': result['error'], 'output': result['output']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -1377,11 +1318,8 @@ class DockerService:
def image_exists(image_ref):
"""True when the image is already in the local image store."""
try:
- result = subprocess.run(
- ['docker', 'image', 'inspect', image_ref],
- capture_output=True, text=True
- )
- return result.returncode == 0
+ return DockerService.run(['image', 'inspect', image_ref],
+ timeout=None)['success']
except Exception:
return False
@@ -1389,14 +1327,12 @@ class DockerService:
def validate_compose_file(cls, project_path, compose_file=None):
"""Validate a Docker Compose file."""
try:
- result = subprocess.run(
+ result = cls.run_compose(
cls._compose_base_cmd(compose_file) + ['config', '--quiet'],
- cwd=project_path,
- capture_output=True, text=True
- )
- if result.returncode == 0:
+ cwd=project_path)
+ if result['success']:
return {'valid': True}
- return {'valid': False, 'error': result.stderr}
+ return {'valid': False, 'error': result['error']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -1404,14 +1340,12 @@ class DockerService:
def get_compose_config(cls, project_path, compose_file=None):
"""Get parsed Docker Compose configuration."""
try:
- result = subprocess.run(
+ result = cls.run_compose(
cls._compose_base_cmd(compose_file) + ['config'],
- cwd=project_path,
- capture_output=True, text=True
- )
- if result.returncode == 0:
- return {'success': True, 'config': yaml.safe_load(result.stdout)}
- return {'success': False, 'error': result.stderr}
+ cwd=project_path)
+ if result['success']:
+ return {'success': True, 'config': yaml.safe_load(result['output'])}
+ return {'success': False, 'error': result['error']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -1421,16 +1355,17 @@ class DockerService:
def prune_system(all_unused=False, volumes=False):
"""Remove unused Docker resources."""
try:
- cmd = ['docker', 'system', 'prune', '-f']
+ cmd = ['system', 'prune', '-f']
if all_unused:
cmd.append('-a')
if volumes:
cmd.append('--volumes')
- result = subprocess.run(cmd, capture_output=True, text=True)
- if result.returncode == 0:
- return {'success': True, 'output': result.stdout}
- return {'success': False, 'error': result.stderr}
+ # LONG: reclaiming a large layer cache is unbounded today.
+ result = DockerService.run(cmd, timeout=None)
+ if result['success']:
+ return {'success': True, 'output': result['output']}
+ return {'success': False, 'error': result['error']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -1438,15 +1373,13 @@ class DockerService:
def get_disk_usage():
"""Get Docker disk usage."""
try:
- result = subprocess.run(
- ['docker', 'system', 'df', '--format', '{{json .}}'],
- capture_output=True, text=True
- )
- if result.returncode != 0:
+ result = DockerService.run(['system', 'df', '--format', '{{json .}}'],
+ timeout=None)
+ if not result['success']:
return []
usage = []
- for line in result.stdout.strip().split('\n'):
+ for line in result['output'].strip().split('\n'):
if line:
usage.append(json.loads(line))
return usage
@@ -1584,14 +1517,12 @@ class DockerService:
Dict with 'success' boolean and 'ports' mapping
"""
try:
- result = subprocess.run(
- ['docker', 'inspect', '--format', '{{json .NetworkSettings.Ports}}', container_name],
- capture_output=True, text=True
- )
- if result.returncode == 0:
- ports = json.loads(result.stdout.strip())
- return {'success': True, 'ports': ports}
- return {'success': False, 'error': result.stderr}
+ result = DockerService.run(
+ ['inspect', '--format', '{{json .NetworkSettings.Ports}}', container_name],
+ timeout=None)
+ if result['success']:
+ return {'success': True, 'ports': json.loads(result['output'].strip())}
+ return {'success': False, 'error': result['error']}
except Exception as e:
return {'success': False, 'error': str(e)}
@@ -1606,12 +1537,11 @@ class DockerService:
Dict with network settings including IP addresses and ports
"""
try:
- result = subprocess.run(
- ['docker', 'inspect', '--format', '{{json .NetworkSettings}}', container_name],
- capture_output=True, text=True
- )
- if result.returncode == 0:
- network_settings = json.loads(result.stdout.strip())
+ result = DockerService.run(
+ ['inspect', '--format', '{{json .NetworkSettings}}', container_name],
+ timeout=None)
+ if result['success']:
+ network_settings = json.loads(result['output'].strip())
return {
'success': True,
'ip_address': network_settings.get('IPAddress'),
@@ -1619,6 +1549,6 @@ class DockerService:
'networks': network_settings.get('Networks'),
'gateway': network_settings.get('Gateway')
}
- return {'success': False, 'error': result.stderr}
+ return {'success': False, 'error': result['error']}
except Exception as e:
return {'success': False, 'error': str(e)}
diff --git a/backend/app/utils/system.py b/backend/app/utils/system.py
index 177d5d76..9d944198 100644
--- a/backend/app/utils/system.py
+++ b/backend/app/utils/system.py
@@ -147,7 +147,7 @@ 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:
+ merge_stderr: bool = False, **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
@@ -160,7 +160,8 @@ def run_checked(cmd: Union[List[str], str], *, privileged: bool = False,
Returns::
- {'success': bool, 'output': str, 'error': str|None, 'returncode': int|None}
+ {'success': bool, 'output': str, 'stderr': 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
@@ -168,6 +169,19 @@ def run_checked(cmd: Union[List[str], str], *, privileged: bool = False,
A caller that renders "not installed" must check ``returncode is not None``
first, and now it can.
+ ``stderr`` is the raw stream; ``error`` is the verdict — a human-facing
+ message, ``None`` on success. They are separate because plenty of commands
+ write to stderr and still succeed (``docker exec``, ``git``), so folding
+ the stream into the verdict would invent failures. Callers that show
+ command output want ``stderr``; callers that report a problem want
+ ``error``.
+
+ ``merge_stderr=True`` interleaves stderr into ``output`` the way a terminal
+ would (``stderr=STDOUT``). ``docker logs`` needs it — a container's stderr
+ is part of its log, not an error about fetching the log — and hand-rolled
+ ``result.stdout + result.stderr`` concatenation is not the same thing: it
+ loses the ordering.
+
``privileged=True`` routes through :func:`run_privileged` — same sudo-vs-root
decision, same argv[0] resolution, so no caller re-implements either.
@@ -182,7 +196,12 @@ def run_checked(cmd: Union[List[str], str], *, privileged: bool = False,
kwargs['cwd'] = cwd
if env is not None:
kwargs['env'] = env
- kwargs.setdefault('capture_output', True)
+ if merge_stderr:
+ # capture_output and an explicit stderr= are mutually exclusive.
+ kwargs.setdefault('stdout', subprocess.PIPE)
+ kwargs.setdefault('stderr', subprocess.STDOUT)
+ else:
+ kwargs.setdefault('capture_output', True)
kwargs.setdefault('text', True)
try:
@@ -203,27 +222,34 @@ def run_checked(cmd: Union[List[str], str], *, privileged: bool = False,
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}'}
+ return _never_ran(f'{name} not found: {exc}')
except subprocess.TimeoutExpired:
- return {'success': False, 'output': '', 'returncode': None,
- 'error': f'timed out after {timeout}s'}
+ return _never_ran(f'timed out after {timeout}s')
except PermissionError as exc:
- return {'success': False, 'output': '', 'returncode': None,
- 'error': f'permission denied: {exc}'}
+ return _never_ran(f'permission denied: {exc}')
except OSError as exc:
- return {'success': False, 'output': '', 'returncode': None,
- 'error': str(exc)}
+ return _never_ran(str(exc))
+ stderr = result.stderr or ''
return {
'success': result.returncode == 0,
'output': result.stdout or '',
+ 'stderr': stderr,
'returncode': result.returncode,
- 'error': ((result.stderr or '').strip() or f'command failed (exit {result.returncode})')
+ 'error': (stderr.strip() or f'command failed (exit {result.returncode})')
if result.returncode != 0 else None,
}
+def _never_ran(error: str) -> dict:
+ """The result shape for a command that never produced an exit code.
+
+ ``returncode is None`` is the whole point — see :func:`run_checked`.
+ """
+ return {'success': False, 'output': '', 'stderr': '',
+ 'returncode': None, 'error': error}
+
+
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 427dcc07..7193414d 100644
--- a/backend/tests/BASELINE_COUNT
+++ b/backend/tests/BASELINE_COUNT
@@ -1 +1 @@
-4081
+4097
diff --git a/backend/tests/RAW_SUBPROCESS_CEILING b/backend/tests/RAW_SUBPROCESS_CEILING
index 8c9cf7e2..dba40afc 100644
--- a/backend/tests/RAW_SUBPROCESS_CEILING
+++ b/backend/tests/RAW_SUBPROCESS_CEILING
@@ -1 +1 @@
-258
+211
diff --git a/backend/tests/test_docker_protection.py b/backend/tests/test_docker_protection.py
index 18f34942..3b67b02b 100644
--- a/backend/tests/test_docker_protection.py
+++ b/backend/tests/test_docker_protection.py
@@ -39,23 +39,26 @@ class TestIsProtectedName:
class TestListContainersAnnotation:
- def _fake_ps(self, names):
- lines = '\n'.join(
+ @staticmethod
+ def _ps_output(names):
+ return '\n'.join(
'{"ID": "abc%d", "Names": "%s", "Image": "img", "Status": "Up", '
'"State": "running", "Ports": "", "CreatedAt": "now", "Size": "0B"}'
% (i, n)
for i, n in enumerate(names)
)
- class _Result:
- returncode = 0
- stdout = lines
-
- return _Result()
-
- def test_protected_flag_set_per_container(self):
- with patch('subprocess.run', return_value=self._fake_ps(['serverkit-backend', 'nginx'])):
- containers = DockerService.list_containers()
+ def test_protected_flag_set_per_container(self, fake_subprocess):
+ # Scripted through the shared stub kit (plan 75 §G7). The private fake
+ # this replaced had only `returncode` and `stdout`; once list_containers
+ # went through run_checked, reading `.stderr` off it raised
+ # AttributeError, the caller's blanket except swallowed it, and the
+ # test saw an empty container list instead of an error. A hand-rolled
+ # CompletedProcess stand-in is only correct until something reads the
+ # attribute it forgot.
+ fake_subprocess.script(['docker', 'ps'],
+ stdout=self._ps_output(['serverkit-backend', 'nginx']))
+ containers = DockerService.list_containers()
by_name = {c['name']: c for c in containers}
assert by_name['serverkit-backend']['protected'] is True
diff --git a/backend/tests/test_docker_runner.py b/backend/tests/test_docker_runner.py
index d6d02b3f..06182d3b 100644
--- a/backend/tests/test_docker_runner.py
+++ b/backend/tests/test_docker_runner.py
@@ -21,8 +21,20 @@ from app.services.docker_service import DockerService
class TestResultShape:
def test_success_carries_stdout(self, fake_subprocess):
fake_subprocess.script(['docker', 'ps'], stdout='CONTAINER\n')
- assert DockerService.run(['ps']) == {
- 'success': True, 'output': 'CONTAINER\n', 'error': None}
+ # DockerService.run sits on run_checked (§G1), so the shape is the
+ # shared one — asserted by key here rather than by whole-dict equality,
+ # which would have to be edited in every suite each time the door
+ # gains a field.
+ result = DockerService.run(['ps'])
+ assert result['success'] is True
+ assert result['output'] == 'CONTAINER\n'
+ assert result['error'] is None
+ assert result['returncode'] == 0
+
+ def test_the_shape_is_run_checkeds(self, fake_subprocess):
+ fake_subprocess.script(['docker', 'ps'])
+ assert set(DockerService.run(['ps'])) == {
+ 'success', 'output', 'stderr', 'error', 'returncode'}
def test_failure_carries_stderr(self, fake_subprocess):
fake_subprocess.script(['docker'], returncode=1, stderr='No such container\n')
@@ -110,5 +122,98 @@ class TestTheWrappersDelegate:
service = getattr(importlib.import_module(module_path), attr)
fake_subprocess.script(['docker'], stdout='ok\n')
result = service._docker(['ps'])
- assert set(result) == {'success', 'output', 'error'}
+ assert {'success', 'output', 'error'} <= set(result)
assert result['success'] is True and result['output'] == 'ok\n'
+
+
+class TestLongOperationsAreNotCapped:
+ """The one way this migration could have broken a real deployment.
+
+ `run_checked` defaults to a 60s timeout. Every docker call in
+ docker_service is unbounded today, and `compose up --build` on a small VPS
+ routinely runs longer than a minute — inheriting the default would have
+ turned working deploys into timeouts. These pin the opt-out at the sites
+ where it matters.
+ """
+
+ def _timeout_for(self, fake, prefix):
+ return fake.kwargs_for(prefix).get('timeout')
+
+ def test_pull_image_is_unbounded(self, fake_subprocess):
+ fake_subprocess.script(['docker', 'pull'])
+ DockerService.pull_image('nginx', tag='latest')
+ assert self._timeout_for(fake_subprocess, ['docker', 'pull']) is None
+
+ def test_build_image_is_unbounded(self, fake_subprocess):
+ fake_subprocess.script(['docker', 'build'])
+ DockerService.build_image('/srv/app', 'app:latest')
+ assert self._timeout_for(fake_subprocess, ['docker', 'build']) is None
+
+ def test_run_container_is_unbounded(self, fake_subprocess):
+ """`docker run` pulls the image when it is absent."""
+ fake_subprocess.script(['docker', 'run'], stdout='cid\n')
+ DockerService.run_container('nginx')
+ assert self._timeout_for(fake_subprocess, ['docker', 'run']) is None
+
+ def test_prune_is_unbounded(self, fake_subprocess):
+ fake_subprocess.script(['docker', 'system'])
+ DockerService.prune_system()
+ assert self._timeout_for(fake_subprocess, ['docker', 'system']) is None
+
+ def test_run_compose_defaults_to_unbounded(self, fake_subprocess):
+ fake_subprocess.script(['docker-compose'])
+ DockerService.run_compose(['docker-compose', 'up', '-d'], cwd='/srv/x')
+ assert self._timeout_for(fake_subprocess, ['docker-compose']) is None
+
+ def test_exec_command_keeps_its_60s_bound(self, fake_subprocess):
+ """The one site that DID have a timeout keeps it."""
+ fake_subprocess.script(['docker', 'exec'])
+ DockerService.exec_command('c1', 'ls')
+ assert self._timeout_for(fake_subprocess, ['docker', 'exec']) == 60
+
+
+class TestLogsKeepInterleaving:
+ def test_container_logs_merge_stderr_rather_than_concatenating(self, fake_subprocess):
+ """A container writes its log to both streams. `stdout + stderr`
+ concatenation put the crash tail above the lines that led to it."""
+ fake_subprocess.script(['docker', 'logs'], stdout='one\ntwo\n')
+ result = DockerService.get_container_logs('c1')
+ assert result['logs'] == 'one\ntwo\n'
+ assert fake_subprocess.kwargs_for(['docker', 'logs'])['stderr'] is not None
+
+
+class TestExecCommandHonesty:
+ def test_a_real_nonzero_exit_reports_the_code(self, fake_subprocess):
+ fake_subprocess.script(['docker', 'exec'], returncode=2, stderr='nope')
+ result = DockerService.exec_command('c1', 'false')
+ assert result['success'] is False
+ assert result['return_code'] == 2
+ assert result['stderr'] == 'nope'
+
+ def test_stderr_on_a_successful_exec_is_not_an_error(self, fake_subprocess):
+ fake_subprocess.script(['docker', 'exec'], stdout='out', stderr='warn')
+ result = DockerService.exec_command('c1', 'thing')
+ assert result['success'] is True
+ assert result['stdout'] == 'out' and result['stderr'] == 'warn'
+
+ def test_a_command_that_never_ran_claims_no_return_code(self, fake_subprocess):
+ """Reporting return_code here would say the container answered."""
+ fake_subprocess.script(['docker'], raises=FileNotFoundError)
+ result = DockerService.exec_command('c1', 'ls')
+ assert result['success'] is False
+ assert 'return_code' not in result
+ assert result['error']
+
+
+class TestProbesStillFallBack:
+ def test_compose_detection_never_raises_into_its_caller(self, fake_subprocess,
+ monkeypatch):
+ """Dropping this guard made a broken probe surface as `compose up`
+ exit_code -1 instead of a v1 fallback — caught by test_deploy_console."""
+ monkeypatch.setattr(DockerService, '_compose_cmd', None)
+
+ def explode(argv, kwargs):
+ raise RuntimeError('probe blew up')
+
+ fake_subprocess.when(['docker'], explode)
+ assert DockerService._get_compose_cmd() == ['docker-compose']
diff --git a/backend/tests/test_utils_system.py b/backend/tests/test_utils_system.py
index 7a07c68f..7c959937 100644
--- a/backend/tests/test_utils_system.py
+++ b/backend/tests/test_utils_system.py
@@ -626,7 +626,48 @@ class TestRunChecked:
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}
+ 'success': True, 'output': 'hi\n', 'stderr': '',
+ 'error': None, 'returncode': 0}
+
+ @patch('app.utils.system.subprocess.run')
+ def test_stderr_on_a_SUCCESSFUL_command_is_not_an_error(self, mock_run):
+ """git, docker exec and friends write to stderr and still succeed.
+
+ Folding the stream into the verdict would invent failures, so
+ `stderr` (the stream) and `error` (the verdict) are separate keys.
+ """
+ mock_run.return_value = subprocess.CompletedProcess(
+ [], 0, stdout='', stderr='Cloning into ...\n')
+ result = run_checked(['git', 'clone', 'x'])
+ assert result['success'] is True
+ assert result['error'] is None
+ assert result['stderr'] == 'Cloning into ...\n'
+
+ @patch('app.utils.system.subprocess.run')
+ def test_stderr_is_raw_while_error_is_stripped(self, mock_run):
+ mock_run.return_value = subprocess.CompletedProcess([], 1, stdout='', stderr=' boom \n')
+ result = run_checked(['false'])
+ assert result['stderr'] == ' boom \n'
+ assert result['error'] == 'boom'
+
+ @patch('app.utils.system.subprocess.run')
+ def test_merge_stderr_interleaves_into_output(self, mock_run):
+ """`docker logs` needs it: a container's stderr is part of its log,
+ not an error about fetching the log."""
+ mock_run.return_value = subprocess.CompletedProcess([], 0, stdout='a\nb\n', stderr=None)
+ result = run_checked(['docker', 'logs', 'x'], merge_stderr=True)
+ assert result['output'] == 'a\nb\n'
+ kwargs = mock_run.call_args[1]
+ assert kwargs['stderr'] is subprocess.STDOUT
+ assert 'capture_output' not in kwargs # mutually exclusive with stderr=
+
+ def test_a_command_that_never_ran_still_has_every_key(self):
+ """A caller destructuring the result must not KeyError on the failure
+ path — that is how an exec failure becomes a 500 instead of a message."""
+ with patch('app.utils.system.subprocess.run', side_effect=FileNotFoundError('x')), \
+ patch('app.utils.system.shutil.which', return_value='/bin/x'):
+ result = run_checked(['x'])
+ assert set(result) == {'success', 'output', 'stderr', 'error', 'returncode'}
@patch('app.utils.system.subprocess.run')
def test_capture_and_text_are_applied_for_the_caller(self, mock_run):