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.

feat(deploy): batched RunLogStream seam + streaming compose + deploy socket channel

Juan Denisa1c5d17d780a
diff --git a/backend/app/services/deployment_runner.py b/backend/app/services/deployment_runner.py
index a09f782a..f5351224 100644
--- a/backend/app/services/deployment_runner.py
+++ b/backend/app/services/deployment_runner.py
@@ -4,16 +4,16 @@ Executes the same deployment plan against the local server or a connected agent.
"""
import base64
-import json
import os
import time
from datetime import datetime
from typing import Any, Dict
from app import db
-from app.models.deployment_job import DeploymentJob, DeploymentJobLog
+from app.models.deployment_job import DeploymentJob
from app.services.agent_registry import agent_registry
from app.services.docker_service import DockerService
+from app.services.run_log_service import RunLogStream
from app.services.telemetry_service import TelemetryService, generate_correlation_id
@@ -29,6 +29,10 @@ class DeploymentPlanRunner:
self.correlation_id = job.correlation_id or generate_correlation_id()
if not job.correlation_id:
job.correlation_id = self.correlation_id
+ # All log/step/close writes funnel through the one batched, crash-proof
+ # seam (plan 51 D4). runner.log() stays a thin wrapper for call-site
+ # compatibility with the 98ad048 code.
+ self.stream = RunLogStream.for_job(job)
@property
def is_remote(self) -> bool:
@@ -69,9 +73,9 @@ class DeploymentPlanRunner:
for index, step in enumerate(steps, start=1):
name = step.get('name') or step.get('type') or f"Step {index}"
- self.job.current_step = index
- self.job.current_step_name = name
- db.session.commit()
+ # set_step flushes prior lines, updates the job row, records the
+ # previous step's duration, and emits a live status (D4).
+ self.stream.set_step(index, name)
self.log('info', name, step_index=index)
TelemetryService.emit(
@@ -106,6 +110,8 @@ class DeploymentPlanRunner:
payload={'job_id': self.job.id, 'kind': self.job.kind, 'total_steps': len(steps)},
commit=False,
)
+ # Final flush + persist step timings; terminal status emit.
+ self.stream.close('succeeded')
return {'success': True, 'steps': results}
except Exception as exc:
@@ -143,30 +149,15 @@ class DeploymentPlanRunner:
)
except Exception:
pass
+ # Final flush + persist failure tail / hint / step timings; terminal
+ # status emit. Marking-failed above never depends on this (D10).
+ self.stream.close('failed', error_message=str(exc))
return {'success': False, 'error': str(exc), 'steps': results}
def log(self, level: str, message: str, data: Any = None, step_index: int = None):
- payload = None
- if data is not None:
- try:
- payload = json.dumps(self._trim_data(data), default=str)
- except TypeError:
- payload = json.dumps(str(data))
-
- # Logging must never kill the deployment: a failed log insert rolls
- # back and is skipped rather than crashing the runner mid-job.
- try:
- entry = DeploymentJobLog(
- job_id=self.job.id,
- step_index=step_index,
- level=level,
- message=message,
- data=payload,
- )
- db.session.add(entry)
- db.session.commit()
- except Exception:
- db.session.rollback()
+ """Thin wrapper over the batched RunLogStream (kept for call-site
+ compatibility with the 98ad048 runner). Never raises."""
+ self.stream.log(level, message, step_index=step_index, data=data)
def _execute_step(self, step: Dict[str, Any]) -> Any:
step_type = step.get('type')
@@ -244,10 +235,22 @@ class DeploymentPlanRunner:
project_dir = step.get('project_dir') or step.get('project_path')
if not project_dir:
raise DeploymentStepError('docker.compose.up step requires project_dir for local targets')
- result = DockerService.compose_up(project_dir, detach=detach, build=build)
+ # Stream the real pull/build/start transcript into the run log so the
+ # Deploy Console shows it live and a failure persists a meaningful tail
+ # (plan 51 D5). The line callback rides the batched stream.
+ current_step = self.job.current_step
+ result = DockerService.compose_up_streaming(
+ project_dir,
+ on_line=lambda line: self.stream.log('info', line, step_index=current_step),
+ detach=detach,
+ build=build,
+ )
if not result.get('success'):
- raise DeploymentStepError(result.get('error') or 'docker compose up failed')
- self.log('debug', 'Local compose up finished', result)
+ raise DeploymentStepError(
+ result.get('error')
+ or f"docker compose up failed (exit code {result.get('exit_code')})"
+ )
+ self.log('debug', 'Local compose up finished')
return result
def _compose_ps(self, step: Dict[str, Any]) -> Dict[str, Any]:
@@ -304,15 +307,3 @@ class DeploymentPlanRunner:
raise DeploymentStepError(data.get('error') or f'Agent command failed: {action}')
return data if data is not None else {'success': True}
-
- def _trim_data(self, data: Any) -> Any:
- if isinstance(data, str):
- return data[:6000]
- if isinstance(data, dict):
- trimmed = {}
- for key, value in data.items():
- trimmed[key] = self._trim_data(value)
- return trimmed
- if isinstance(data, list):
- return [self._trim_data(item) for item in data[:50]]
- return data
diff --git a/backend/app/services/docker_service.py b/backend/app/services/docker_service.py
index ce8f87b3..213fcce2 100644
--- a/backend/app/services/docker_service.py
+++ b/backend/app/services/docker_service.py
@@ -1050,6 +1050,51 @@ class DockerService:
except Exception as e:
return {'success': False, 'error': str(e)}
+ @classmethod
+ def compose_up_streaming(cls, project_path, on_line, detach=True, build=False,
+ compose_file=None):
+ """Start Docker Compose services, streaming each output line to on_line.
+
+ Same overlay/command construction as ``compose_up``, but runs via Popen
+ with plain, ANSI-free progress (plan 51 D5) and delivers output
+ line-by-line so the Deploy Console shows the real pull/build/start
+ transcript live (the biggest reason template-install errors used to be
+ unreadable). Returns ``{success, exit_code}``; the actual failure output
+ lands in the stream (and thus the persisted failure tail), so no separate
+ stderr blob is returned. Never raises — the buffered ``compose_up``
+ remains for callers without a callback.
+ """
+ try:
+ cmd = cls._compose_cmd_with_overlay(project_path, compose_file)
+ # Global compose flags before the subcommand: no ANSI colors, plain
+ # (non-TTY) progress so the transcript greps/reads cleanly. The
+ # stream also strips residual ANSI/\r as a backstop.
+ cmd = cmd + ['--ansi', 'never', '--progress', 'plain', 'up']
+ if detach:
+ cmd.append('-d')
+ if build:
+ cmd.append('--build')
+
+ proc = subprocess.Popen(
+ cmd, cwd=project_path,
+ stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+ text=True, bufsize=1,
+ )
+ for line in iter(proc.stdout.readline, ''):
+ try:
+ on_line(line.rstrip('\n'))
+ except Exception:
+ pass
+ proc.stdout.close()
+ exit_code = proc.wait()
+ return {'success': exit_code == 0, 'exit_code': exit_code}
+ except Exception as e:
+ try:
+ on_line(f'docker compose up failed to start: {e}')
+ except Exception:
+ pass
+ return {'success': False, 'exit_code': -1, 'error': str(e)}
+
@classmethod
def compose_down(cls, project_path, volumes=False, remove_orphans=True, compose_file=None):
"""Stop Docker Compose services."""
diff --git a/backend/app/services/run_log_service.py b/backend/app/services/run_log_service.py
new file mode 100644
index 00000000..6fc2d115
--- /dev/null
+++ b/backend/app/services/run_log_service.py
@@ -0,0 +1,377 @@
+"""RunLogStream — the single write seam for all deploy-path logging.
+
+Every deployment/install log line (template installs, repo/app deploys, later
+WordPress creates) flows through one ``RunLogStream`` per job. It batches writes
+(one DB commit + one socket emit per flush instead of a commit-per-line), keeps a
+truthful in-memory tail of the last output for failure reporting, records per-step
+timings, sanitizes ANSI/`\\r` noise, caps the persisted row count, and matches a
+plain-language hint against the failure output.
+
+Design contract (plan 51, D4/D5/D6/D10):
+
+- ``stream.log(level, message, step_index=None, data=None)`` — NEVER raises.
+- ``stream.set_step(index, name)`` — flush, update the job row, emit a status.
+- ``stream.close(status, error_message=None)`` — final flush; persist
+ ``step_timings`` (always) and, on failure, ``failure_tail`` + ``hint`` into the
+ job's existing ``result`` JSON (no schema migration); emit a terminal status.
+
+Flush triggers: 50 buffered lines, 300 ms elapsed, a step change, or close.
+Row cap: 5000 persisted rows per job — past the cap we stop persisting detail
+(one ``warn`` marker row is written once) but keep maintaining the in-memory tail
+so the failure tail always reflects the true end of output.
+
+Socket emits go through injected callables (defaulting to lazy lookups of
+``app.sockets.emit_deploy_log`` / ``emit_deploy_status``) so this module stays
+import-light and fully testable with the emitter mocked. A failing/absent emitter
+never breaks logging.
+"""
+
+import json
+import re
+import time
+from collections import deque
+from datetime import datetime
+from typing import Any, Callable, List, Optional
+
+from app import db
+from app.models.deployment_job import DeploymentJob, DeploymentJobLog
+
+
+# ---------------------------------------------------------------------------
+# Sanitation (D5): strip ANSI escapes, resolve `\r` progress overwrites. We keep
+# clean text with level colors in the UI — we do NOT emulate an ANSI terminal.
+# ---------------------------------------------------------------------------
+_ANSI_RE = re.compile(
+ r'\x1b(?:'
+ r'\[[0-9;?]*[ -/]*[@-~]' # CSI ... final byte
+ r'|\].*?(?:\x07|\x1b\\)' # OSC ... BEL / ST
+ r'|[@-Z\\-_]' # two-char escapes (e.g. ESC c)
+ r')'
+)
+
+
+def sanitize(text: str) -> str:
+ """Strip ANSI escape sequences and resolve carriage-return overwrites.
+
+ A ``\\r`` in build output means "redraw this line" (progress bars); we keep
+ only the final segment so the stored/rendered text reads like the finished
+ line, not a smear of overwrites.
+ """
+ if text is None:
+ return ''
+ if not isinstance(text, str):
+ text = str(text)
+ text = _ANSI_RE.sub('', text)
+ if '\r' in text:
+ # Preserve a trailing newline, but collapse the overwrites before it.
+ trailing_nl = text.endswith('\n')
+ segment = text.rstrip('\n').split('\r')[-1]
+ text = segment + ('\n' if trailing_nl else '')
+ return text.rstrip('\n')
+
+
+# ---------------------------------------------------------------------------
+# Failure hints (D6 / §5.3): first match wins, evaluated against the failure tail
+# at close time. One sentence, action-first, never jokey.
+# ---------------------------------------------------------------------------
+HINTS: List = [
+ (re.compile(r'port is already allocated|address already in use', re.I),
+ 'Another service is already using this port — change the port mapping and retry.'),
+ (re.compile(r'pull access denied|unauthorized.*(pull|repository)|manifest unknown', re.I),
+ "The image couldn't be pulled — check the image name/tag, or add registry credentials."),
+ (re.compile(r'npm ERR!', re.I),
+ 'The Node build failed — the lines above show the failing package or script.'),
+ (re.compile(r'EBADENGINE', re.I),
+ 'The app needs a different Node version than the build image provides.'),
+ (re.compile(r'No matching distribution found|ResolutionImpossible', re.I),
+ "A Python dependency couldn't be resolved — check the requirements pins above."),
+ (re.compile(r'exited? with code 137|\bKilled\b|OOMKilled', re.I),
+ 'The build ran out of memory (OOM) — raise the server or app memory limit and retry.'),
+ (re.compile(r'no space left on device', re.I),
+ "The server's disk is full — free some space and retry."),
+ (re.compile(r'is invalid.*compose|yaml.*(parse|scan)|error converting YAML', re.I),
+ 'The compose file is invalid — the parser error above points at the line.'),
+ (re.compile(r'env file .* not found|variable is not set|required variable', re.I),
+ 'A required environment variable or file is missing — set it in the service settings and retry.'),
+]
+
+
+def match_hint(tail_text: str) -> Optional[str]:
+ """Return the first hint whose pattern matches the failure tail, else None."""
+ if not tail_text:
+ return None
+ for pattern, hint in HINTS:
+ if pattern.search(tail_text):
+ return hint
+ return None
+
+
+def _default_emit_log(job_id: str, lines: List[dict]) -> None:
+ """Lazy default emitter — resolves the socket helper at call time so this
+ module never imports sockets eagerly and stays safe when sockets aren't
+ wired (tests, CLI)."""
+ try:
+ from app.sockets import emit_deploy_log
+ emit_deploy_log(job_id, lines)
+ except Exception:
+ pass
+
+
+def _default_emit_status(job_id: str, status: dict) -> None:
+ try:
+ from app.sockets import emit_deploy_status
+ emit_deploy_status(job_id, status)
+ except Exception:
+ pass
+
+
+class RunLogStream:
+ """Batched, crash-proof log writer for one DeploymentJob."""
+
+ FLUSH_LINES = 50
+ FLUSH_INTERVAL = 0.3 # seconds
+ ROW_CAP = 5000
+ TAIL_SIZE = 80
+
+ def __init__(
+ self,
+ job: DeploymentJob,
+ emit_log: Optional[Callable] = None,
+ emit_status: Optional[Callable] = None,
+ clock: Callable[[], float] = time.monotonic,
+ ):
+ self.job = job
+ self._buffer: List[dict] = []
+ self._clock = clock
+ self._last_flush = clock()
+ self._tail = deque(maxlen=self.TAIL_SIZE)
+ self._cap_hit = False
+ self._emit_log = emit_log or _default_emit_log
+ self._emit_status = emit_status or _default_emit_status
+
+ # Per-step timing: index -> {'name', 'started'}; finalized into a list.
+ self._step_started_at: Optional[float] = None
+ self._step_started_index: Optional[int] = None
+ self._step_started_name: Optional[str] = None
+ self._step_timings: List[dict] = []
+
+ # How many rows already exist for this job (retries make fresh jobs, but
+ # a reconciled/resumed job could carry rows) — the cap is per job.
+ try:
+ self._rows_written = DeploymentJobLog.query.filter_by(job_id=job.id).count()
+ except Exception:
+ self._rows_written = 0
+
+ @classmethod
+ def for_job(cls, job: DeploymentJob, **kwargs) -> 'RunLogStream':
+ return cls(job, **kwargs)
+
+ # ------------------------------------------------------------------ log
+ def log(self, level: str, message: str, step_index: Optional[int] = None,
+ data: Any = None) -> None:
+ """Buffer a log line. NEVER raises (D10)."""
+ try:
+ clean = sanitize(message)
+ payload = None
+ if data is not None:
+ try:
+ payload = json.dumps(_trim_data(data), default=str)
+ except TypeError:
+ payload = json.dumps(str(data))
+
+ # The tail is always maintained, even past the row cap, so the
+ # failure tail reflects the true end of output.
+ self._tail.append(clean)
+
+ if self._cap_hit:
+ return
+
+ if self._rows_written + len(self._buffer) >= self.ROW_CAP:
+ # Write a single marker, drop the rest of the buffer, stop
+ # persisting detail. Tail keeps flowing above.
+ self._buffer.append({
+ 'step_index': step_index,
+ 'level': 'warn',
+ 'message': (
+ f'Log truncated at {self.ROW_CAP} lines — later output is '
+ 'not persisted, but the failure tail still reflects the end.'
+ ),
+ 'data': None,
+ })
+ self._cap_hit = True
+ self._flush()
+ return
+
+ self._buffer.append({
+ 'step_index': step_index,
+ 'level': level,
+ 'message': clean,
+ 'data': payload,
+ })
+
+ if (len(self._buffer) >= self.FLUSH_LINES
+ or (self._clock() - self._last_flush) >= self.FLUSH_INTERVAL):
+ self._flush()
+ except Exception:
+ # Logging must never kill a deployment.
+ try:
+ db.session.rollback()
+ except Exception:
+ pass
+
+ # ------------------------------------------------------------------ step
+ def set_step(self, index: int, name: Optional[str]) -> None:
+ """Persist the step boundary: flush prior lines, update the job row,
+ record timing for the previous step, emit a status. Non-raising."""
+ try:
+ self._flush()
+ # Finalize the previous step's duration.
+ self._finalize_current_step()
+ self._step_started_at = self._clock()
+ self._step_started_index = index
+ self._step_started_name = name
+
+ self.job.current_step = index
+ self.job.current_step_name = name
+ db.session.commit()
+ self._emit_status_safe()
+ except Exception:
+ try:
+ db.session.rollback()
+ except Exception:
+ pass
+
+ # ----------------------------------------------------------------- close
+ def close(self, status: str, error_message: Optional[str] = None) -> None:
+ """Final flush + persist timings/tail/hint into job.result; emit a
+ terminal status. Non-raising; job status is set by the caller — close()
+ only enriches the result and flushes."""
+ try:
+ self._flush()
+ self._finalize_current_step()
+
+ result = self.job.get_result() or {}
+ if self._step_timings:
+ result['step_timings'] = self._step_timings
+ if status == 'failed':
+ tail = list(self._tail)
+ result['failure_tail'] = tail
+ hint = match_hint('\n'.join(tail))
+ if hint:
+ result['hint'] = hint
+ self.job.set_result(result)
+ db.session.commit()
+ except Exception:
+ try:
+ db.session.rollback()
+ except Exception:
+ pass
+ # Emit the terminal status regardless of the persistence outcome.
+ self._emit_status_safe()
+
+ # --------------------------------------------------------------- flush
+ def _flush(self) -> None:
+ """Write buffered rows in ONE commit and emit ONE deploy_log batch."""
+ if not self._buffer:
+ self._last_flush = self._clock()
+ return
+ pending = self._buffer
+ self._buffer = []
+ try:
+ entries = [
+ DeploymentJobLog(
+ job_id=self.job.id,
+ step_index=row['step_index'],
+ level=row['level'],
+ message=row['message'],
+ data=row['data'],
+ )
+ for row in pending
+ ]
+ db.session.add_all(entries)
+ db.session.commit()
+ self._rows_written += len(entries)
+ self._last_flush = self._clock()
+
+ lines = [{
+ 'id': e.id,
+ 'step_index': e.step_index,
+ 'level': e.level,
+ 'message': e.message,
+ 'ts': e.created_at.isoformat() if e.created_at else None,
+ } for e in entries]
+ try:
+ self._emit_log(self.job.id, lines)
+ except Exception:
+ pass
+ except Exception:
+ # Buffered-drop on flush failure (D10): one telemetry event, then
+ # continue. A stuck deployment is worse than a missing log line.
+ try:
+ db.session.rollback()
+ except Exception:
+ pass
+ self._last_flush = self._clock()
+ try:
+ from app.services.telemetry_service import TelemetryService
+ TelemetryService.emit(
+ source='deployment',
+ event_type='deployment.log_flush_failed',
+ message='Deploy log flush failed; dropped a buffered batch',
+ severity='warning',
+ resource_type='deployment_job',
+ resource_id=self.job.id,
+ correlation_id=getattr(self.job, 'correlation_id', None),
+ payload={'job_id': self.job.id, 'dropped': len(pending)},
+ commit=True,
+ )
+ except Exception:
+ pass
+
+ def flush(self) -> None:
+ """Public flush for one-off writes (fire-and-forget annotations)."""
+ try:
+ self._flush()
+ except Exception:
+ pass
+
+ # --------------------------------------------------------------- helpers
+ def _finalize_current_step(self) -> None:
+ if self._step_started_index is not None and self._step_started_at is not None:
+ duration = max(0.0, self._clock() - self._step_started_at)
+ self._step_timings.append({
+ 'index': self._step_started_index,
+ 'name': self._step_started_name,
+ 'seconds': round(duration, 3),
+ })
+ self._step_started_index = None
+ self._step_started_at = None
+ self._step_started_name = None
+
+ def _emit_status_safe(self) -> None:
+ try:
+ self._emit_status(self.job.id, self.job.to_dict())
+ except Exception:
+ pass
+
+
+def _trim_data(data: Any) -> Any:
+ """Bound the size of structured `data` payloads (parity with the old
+ runner._trim_data), so a chatty step can't write a multi-MB row."""
+ if isinstance(data, str):
+ return data[:6000]
+ if isinstance(data, dict):
+ return {key: _trim_data(value) for key, value in data.items()}
+ if isinstance(data, list):
+ return [_trim_data(item) for item in data[:50]]
+ return data
+
+
+def append_log(job: DeploymentJob, level: str, message: str, data: Any = None,
+ step_index: Optional[int] = None) -> None:
+ """Immediate, persisted single log line for fire-and-forget annotations
+ (e.g. post-install notes) where no long-lived stream is open. Flushes at
+ once so the line is never left buffered. Non-raising."""
+ stream = RunLogStream.for_job(job)
+ stream.log(level, message, step_index=step_index, data=data)
+ stream.flush()
diff --git a/backend/app/sockets.py b/backend/app/sockets.py
index 19993728..721906a2 100644
--- a/backend/app/sockets.py
+++ b/backend/app/sockets.py
@@ -22,10 +22,6 @@ container_status_subscribers = set()
container_status_thread = None
container_status_stop_event = threading.Event()
-# Store active build subscriptions
-build_subscribers = {} # sid -> app_id
-build_log_queues = {} # app_id -> queue
-
# Store active container log streams
container_log_streams = {} # sid -> {'process': Popen, 'app_id': int, 'thread': Thread, 'stop_event': Event}
@@ -370,72 +366,67 @@ def handle_leave_room(data):
emit('left', {'room': room})
-# ==================== BUILD LOG STREAMING ====================
+# ==================== DEPLOY CONSOLE STREAMING ====================
+#
+# Live push for the Deploy Console (plan 51). Room is per DeploymentJob
+# (`deploy_{job_id}`); the RunLogStream seam batches writes and emits one
+# `deploy_log` (a batch of persisted lines) per flush plus `deploy_status`
+# (the job summary dict) on step/terminal transitions. This is an ACCELERATOR
+# on top of the `GET /deployment-jobs/<id>/logs?after_id=` polling endpoint —
+# the console stays 100% functional with sockets disabled (D2).
[email protected]('subscribe_build')
-def handle_subscribe_build(data):
- """Subscribe to build log streaming for an app."""
- sid = request.sid
- app_id = data.get('app_id')
[email protected]('subscribe_deploy')
+def handle_subscribe_deploy(data):
+ """Subscribe to live Deploy Console updates for a deployment job.
- if not app_id:
- emit('error', {'message': 'app_id required'})
+ Auth mirrors the read API (D3/§8): any authenticated user may watch — job
+ ids are unguessable UUIDs and the REST read endpoint exposes them the same
+ way. The connect handler already verified the JWT and recorded identity in
+ `connected_clients`; a socket missing from that set is not authenticated.
+ """
+ sid = request.sid
+ if sid not in connected_clients:
+ emit('error', {'message': 'Authentication required'})
return
- # Store subscription
- build_subscribers[sid] = app_id
-
- # Join a room for this app's builds
- join_room(f'build_{app_id}')
-
- emit('subscribed', {'channel': 'build', 'app_id': app_id})
-
+ job_id = (data or {}).get('job_id')
+ if not job_id:
+ emit('error', {'message': 'job_id required'})
+ return
[email protected]('unsubscribe_build')
-def handle_unsubscribe_build():
- """Unsubscribe from build log streaming."""
- sid = request.sid
+ join_room(f'deploy_{job_id}')
+ emit('subscribed', {'channel': 'deploy', 'job_id': job_id})
- if sid in build_subscribers:
- app_id = build_subscribers[sid]
- leave_room(f'build_{app_id}')
- del build_subscribers[sid]
- emit('unsubscribed', {'channel': 'build'})
[email protected]('unsubscribe_deploy')
+def handle_unsubscribe_deploy(data=None):
+ """Leave a deployment job's live room."""
+ job_id = (data or {}).get('job_id')
+ if job_id:
+ leave_room(f'deploy_{job_id}')
+ emit('unsubscribed', {'channel': 'deploy', 'job_id': job_id})
-def emit_build_log(app_id: int, message: str, level: str = 'info'):
- """Emit a build log message to all subscribers.
+def emit_deploy_log(job_id: str, lines: list):
+ """Emit a batch of persisted deploy log lines to a job's room.
- This function is called from the build service to stream logs.
+ Called from RunLogStream on each flush. `lines` is a list of
+ {id, step_index, level, message, ts} dicts (already persisted, carrying
+ real DB ids so the client can dedupe + after_id re-sync).
"""
- socketio.emit('build_log', {
- 'app_id': app_id,
- 'message': message,
- 'level': level,
- 'timestamp': time.time()
- }, room=f'build_{app_id}')
+ socketio.emit('deploy_log', {
+ 'job_id': job_id,
+ 'lines': lines,
+ }, room=f'deploy_{job_id}')
-def emit_build_status(app_id: int, status: str, details: dict = None):
- """Emit a build status update to all subscribers."""
- socketio.emit('build_status', {
- 'app_id': app_id,
+def emit_deploy_status(job_id: str, status: dict):
+ """Emit a deployment job status summary (same shape as
+ GET /deployment-jobs/<id>, without logs) to the job's room."""
+ socketio.emit('deploy_status', {
+ 'job_id': job_id,
'status': status,
- 'details': details or {},
- 'timestamp': time.time()
- }, room=f'build_{app_id}')
-
-
-def create_build_log_callback(app_id: int):
- """Create a log callback function for the build service.
-
- Returns a function that can be passed to BuildService.build()
- to stream logs in real-time via WebSocket.
- """
- def log_callback(message: str):
- emit_build_log(app_id, message)
- return log_callback
+ }, room=f'deploy_{job_id}')
# ==================== CONTAINER LOG STREAMING ====================
diff --git a/backend/tests/test_run_log_stream.py b/backend/tests/test_run_log_stream.py
new file mode 100644
index 00000000..e7eb7fcd
--- /dev/null
+++ b/backend/tests/test_run_log_stream.py
@@ -0,0 +1,259 @@
+"""RunLogStream — the batched, crash-proof deploy-log seam (plan 51, Phase 0).
+
+Proves: flush triggers (count / interval / step / close), one commit + one emit
+per flush, the 5000-row cap writes a marker + keeps the tail truthful, the
+failure tail equals the true last lines, every hint pattern matches, log() never
+raises on a wedged DB, and to_dict() surfaces the new result fields.
+"""
+import uuid
+
+import pytest
+
+from app import db
+from app.models.deployment_job import DeploymentJob, DeploymentJobLog
+from app.services.run_log_service import RunLogStream, match_hint, HINTS, sanitize
+
+
+def _make_job(kind='template_install'):
+ job = DeploymentJob(id=str(uuid.uuid4()), kind=kind, status='running')
+ job.set_plan({'steps': [{'name': 'A'}, {'name': 'B'}]})
+ db.session.add(job)
+ db.session.commit()
+ return job
+
+
+class _FakeClock:
+ def __init__(self):
+ self.t = 1000.0
+
+ def __call__(self):
+ return self.t
+
+ def advance(self, dt):
+ self.t += dt
+
+
+class _Emitter:
+ def __init__(self):
+ self.log_calls = []
+ self.status_calls = []
+
+ def emit_log(self, job_id, lines):
+ self.log_calls.append((job_id, lines))
+
+ def emit_status(self, job_id, status):
+ self.status_calls.append((job_id, status))
+
+
+def _stream(job, clock=None, emitter=None):
+ emitter = emitter or _Emitter()
+ clock = clock or _FakeClock()
+ return RunLogStream.for_job(
+ job, emit_log=emitter.emit_log, emit_status=emitter.emit_status, clock=clock
+ ), emitter, clock
+
+
+class TestFlushTriggers:
+ def test_no_flush_below_thresholds(self, app):
+ job = _make_job()
+ stream, emitter, clock = _stream(job)
+ for i in range(10): # < 50 lines, no time advance, no step change
+ stream.log('info', f'line {i}')
+ assert DeploymentJobLog.query.filter_by(job_id=job.id).count() == 0
+ assert emitter.log_calls == []
+
+ def test_flush_on_count(self, app):
+ job = _make_job()
+ stream, emitter, clock = _stream(job)
+ for i in range(50):
+ stream.log('info', f'line {i}')
+ assert DeploymentJobLog.query.filter_by(job_id=job.id).count() == 50
+ assert len(emitter.log_calls) == 1 # ONE emit for the batch
+ assert len(emitter.log_calls[0][1]) == 50
+
+ def test_flush_on_interval(self, app):
+ job = _make_job()
+ stream, emitter, clock = _stream(job)
+ stream.log('info', 'first')
+ assert DeploymentJobLog.query.filter_by(job_id=job.id).count() == 0
+ clock.advance(0.5) # > 300ms
+ stream.log('info', 'second')
+ assert DeploymentJobLog.query.filter_by(job_id=job.id).count() == 2
+
+ def test_flush_on_step_change(self, app):
+ job = _make_job()
+ stream, emitter, clock = _stream(job)
+ stream.log('info', 'before step')
+ stream.set_step(1, 'A')
+ assert DeploymentJobLog.query.filter_by(job_id=job.id).count() == 1
+ # set_step updates the job row and emits a live status
+ refreshed = DeploymentJob.query.get(job.id)
+ assert refreshed.current_step == 1
+ assert refreshed.current_step_name == 'A'
+ assert len(emitter.status_calls) == 1
+
+ def test_flush_on_close(self, app):
+ job = _make_job()
+ stream, emitter, clock = _stream(job)
+ stream.log('info', 'buffered')
+ stream.close('succeeded')
+ assert DeploymentJobLog.query.filter_by(job_id=job.id).count() == 1
+ # terminal status emitted
+ assert len(emitter.status_calls) == 1
+
+ def test_one_commit_one_emit_per_flush(self, app):
+ job = _make_job()
+ stream, emitter, clock = _stream(job)
+ for i in range(50):
+ stream.log('info', f'a{i}') # flush #1
+ for i in range(50):
+ stream.log('info', f'b{i}') # flush #2
+ assert len(emitter.log_calls) == 2
+ # every emitted line carries a real DB id
+ for _job_id, lines in emitter.log_calls:
+ assert all(isinstance(ln['id'], int) for ln in lines)
+
+
+class TestRowCap:
+ def test_cap_writes_marker_and_keeps_tail(self, app):
+ job = _make_job()
+ stream, emitter, clock = _stream(job)
+ # Emit more than the cap; last lines are uniquely identifiable.
+ total = RunLogStream.ROW_CAP + 200
+ for i in range(total):
+ stream.log('info', f'line-{i}')
+ stream.close('failed')
+
+ rows = DeploymentJobLog.query.filter_by(job_id=job.id).count()
+ # Persisted rows never exceed cap + the single marker row.
+ assert rows <= RunLogStream.ROW_CAP + 1
+ warn_rows = DeploymentJobLog.query.filter_by(job_id=job.id, level='warn').all()
+ assert any('truncated' in w.message.lower() for w in warn_rows)
+
+ # The failure tail reflects the TRUE end of output, past the cap.
+ result = DeploymentJob.query.get(job.id).get_result()
+ tail = result['failure_tail']
+ assert tail[-1] == f'line-{total - 1}'
+ assert len(tail) == RunLogStream.TAIL_SIZE
+
+
+class TestFailureTailAndTimings:
+ def test_failure_tail_is_true_last_lines(self, app):
+ job = _make_job()
+ stream, emitter, clock = _stream(job)
+ for i in range(200):
+ stream.log('info', f'out-{i}')
+ stream.close('failed', error_message='boom')
+ result = DeploymentJob.query.get(job.id).get_result()
+ assert result['failure_tail'][-1] == 'out-199'
+ assert result['failure_tail'][0] == f'out-{200 - RunLogStream.TAIL_SIZE}'
+
+ def test_step_timings_persisted_on_success(self, app):
+ job = _make_job()
+ stream, emitter, clock = _stream(job)
+ stream.set_step(1, 'Prepare')
+ clock.advance(3.0)
+ stream.set_step(2, 'Build')
+ clock.advance(5.0)
+ stream.close('succeeded')
+ result = DeploymentJob.query.get(job.id).get_result()
+ timings = {t['index']: t for t in result['step_timings']}
+ assert timings[1]['seconds'] == pytest.approx(3.0, abs=0.01)
+ assert timings[2]['seconds'] == pytest.approx(5.0, abs=0.01)
+ assert timings[1]['name'] == 'Prepare'
+
+ def test_success_has_no_failure_tail(self, app):
+ job = _make_job()
+ stream, emitter, clock = _stream(job)
+ stream.log('info', 'ok')
+ stream.close('succeeded')
+ result = DeploymentJob.query.get(job.id).get_result()
+ assert 'failure_tail' not in result
+ assert 'hint' not in result
+
+
+class TestHints:
+ @pytest.mark.parametrize('sample,expected_fragment', [
+ ('bind: port is already allocated', 'port'),
+ ('Error: pull access denied for ghcr.io/x', "couldn't be pulled"),
+ ('npm ERR! code E404', 'Node build'),
+ ('npm warn EBADENGINE Unsupported engine', 'Node version'),
+ ('ERROR: No matching distribution found for foo==9', "couldn't be resolved"),
+ ('container exited with code 137', 'memory'),
+ ('write /data: no space left on device', 'disk'),
+ ('services.web Additional property x is invalid compose', 'compose file is invalid'),
+ ('error: required variable DB_URL is not set', 'environment variable'),
+ ])
+ def test_each_hint_pattern_matches(self, app, sample, expected_fragment):
+ hint = match_hint(sample)
+ assert hint is not None
+ assert expected_fragment.lower() in hint.lower()
+
+ def test_no_hint_for_generic_failure(self, app):
+ assert match_hint('some unrelated failure text') is None
+
+ def test_hint_persisted_on_failure_close(self, app):
+ job = _make_job()
+ stream, emitter, clock = _stream(job)
+ stream.log('error', 'bind: port is already allocated 0.0.0.0:8080')
+ stream.close('failed')
+ result = DeploymentJob.query.get(job.id).get_result()
+ assert 'port' in result['hint'].lower()
+
+ def test_hints_table_nonempty(self, app):
+ assert len(HINTS) >= 9
+
+
+class TestSanitize:
+ def test_strips_ansi(self, app):
+ assert sanitize('\x1b[31mred\x1b[0m text') == 'red text'
+
+ def test_resolves_carriage_return(self, app):
+ # progress overwrite: keep the final segment
+ assert sanitize('Downloading 10%\rDownloading 100%') == 'Downloading 100%'
+
+ def test_mixed_ansi_and_cr(self, app):
+ assert sanitize('\x1b[2K\rStep 7/11 : COPY .') == 'Step 7/11 : COPY .'
+
+ def test_plain_passthrough(self, app):
+ assert sanitize('added 214 packages in 12s') == 'added 214 packages in 12s'
+
+
+class TestCrashProof:
+ def test_log_swallows_db_errors(self, app, monkeypatch):
+ job = _make_job()
+ stream, emitter, clock = _stream(job)
+
+ # Force every commit to blow up: log() must NOT raise.
+ def boom():
+ raise RuntimeError('db wedged')
+
+ monkeypatch.setattr(db.session, 'commit', boom)
+ for i in range(60): # crosses the flush-on-count threshold
+ stream.log('info', f'x{i}') # would flush → commit → boom, swallowed
+ # No exception escaped; the tail is still truthful in memory.
+ stream_result_ok = True
+ assert stream_result_ok
+
+ def test_close_never_raises_on_wedged_db(self, app, monkeypatch):
+ job = _make_job()
+ stream, emitter, clock = _stream(job)
+ stream.log('info', 'pre')
+ monkeypatch.setattr(db.session, 'commit', lambda: (_ for _ in ()).throw(RuntimeError('x')))
+ # Must not raise.
+ stream.close('failed', error_message='boom')
+
+
+class TestToDictSurfacesResultFields:
+ def test_to_dict_exposes_timings_and_tail(self, app):
+ job = _make_job()
+ stream, emitter, clock = _stream(job)
+ stream.set_step(1, 'Prepare')
+ clock.advance(1.0)
+ stream.log('error', 'bind: port is already allocated')
+ stream.close('failed', error_message='boom')
+
+ data = DeploymentJob.query.get(job.id).to_dict()
+ assert 'step_timings' in data['result']
+ assert 'failure_tail' in data['result']
+ assert 'hint' in data['result']