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(operations): add generalized run stream

Juan Denisee58075fae0b
diff --git a/frontend/scripts/check-frontend-boundaries.mjs b/frontend/scripts/check-frontend-boundaries.mjs
index 8508ea35..4bfad483 100644
--- a/frontend/scripts/check-frontend-boundaries.mjs
+++ b/frontend/scripts/check-frontend-boundaries.mjs
@@ -92,7 +92,6 @@ const LEGACY_POLLERS = new Map(Object.entries({
'components/dashboard/widgets/renderers.jsx': 1,
'components/deploy-console/SuccessBanner.jsx': 1,
'components/server/OnboardingWizard.jsx': 1,
- 'hooks/useDeployJobStream.js': 1,
'hooks/useMetrics.js': 1,
'pages/Dashboard.jsx': 2,
'pages/DeployConsole.jsx': 1,
diff --git a/frontend/src/hooks/runStream.js b/frontend/src/hooks/runStream.js
new file mode 100644
index 00000000..7d862b5f
--- /dev/null
+++ b/frontend/src/hooks/runStream.js
@@ -0,0 +1,32 @@
+export const TERMINAL_RUN_STATUSES = new Set(['succeeded', 'failed', 'cancelled']);
+export const MAX_RUN_LOG_LINES = 5000;
+
+export function isTerminalRunStatus(status) {
+ return TERMINAL_RUN_STATUSES.has(status);
+}
+
+export function mergeRunLogLines(previous, incoming, seenIds, maxLines = MAX_RUN_LOG_LINES) {
+ if (!Array.isArray(incoming) || incoming.length === 0) {
+ return { lines: previous, maxId: 0 };
+ }
+
+ const fresh = [];
+ let maxId = 0;
+ for (const line of incoming) {
+ if (line?.id != null) {
+ const key = String(line.id);
+ if (seenIds.has(key)) continue;
+ seenIds.add(key);
+ const numericId = Number(line.id);
+ if (Number.isFinite(numericId)) maxId = Math.max(maxId, numericId);
+ }
+ fresh.push(line);
+ }
+
+ if (fresh.length === 0) return { lines: previous, maxId };
+ const combined = previous.concat(fresh);
+ return {
+ lines: combined.length > maxLines ? combined.slice(-maxLines) : combined,
+ maxId,
+ };
+}
diff --git a/frontend/src/hooks/useDeployJobStream.js b/frontend/src/hooks/useDeployJobStream.js
index 40589d16..e9aecc33 100644
--- a/frontend/src/hooks/useDeployJobStream.js
+++ b/frontend/src/hooks/useDeployJobStream.js
@@ -1,195 +1,34 @@
-import { useState, useEffect, useRef, useCallback } from 'react';
-import socketService from '../services/socket';
-import api from '../services/api';
+import { useCallback } from 'react';
-// Terminal statuses freeze the stream (unsubscribe + stop polling).
-const TERMINAL = new Set(['succeeded', 'failed', 'cancelled']);
-// Mirror the backend's per-job row cap (plan 51 D4): keep the tail bounded so a
-// very chatty build can't grow the DOM unboundedly.
-const MAX_LINES = 5000;
-// Fall back to polling if the socket hasn't connected shortly after mount.
-const SOCKET_GRACE_MS = 2500;
+import api from '../services/api';
+import useRunStream from './useRunStream';
/**
- * Single transport hook for the Deploy Console, the compact progress widget,
- * the LogsTab banner, and the topbar pill (plan 51 §5.5).
- *
- * Boot fetches a full snapshot (GET /deployment-jobs/<id>?logs=true), then
- * prefers the live `deploy_log`/`deploy_status` socket channel and falls back to
- * `after_id` polling when sockets are unavailable. Log rows are de-duplicated by
- * DB id; after any (re)connect the hook re-syncs with `after_id=<max seen id>`
- * so lines emitted while disconnected are never lost.
- *
- * @param {string} jobId
- * @param {object} [opts]
- * @param {number} [opts.pollInterval=2000]
- * @param {boolean} [opts.enabled=true]
- * @returns {{job, lines, isLive, transport, error, loading, refetch}}
+ * Deployment compatibility adapter for the generalized run stream.
+ * Deploy Console still receives its richer job snapshot and public `job`
+ * result shape while transport, reconnect catch-up, and de-duplication use the
+ * shared run envelope.
*/
-export default function useDeployJobStream(jobId, opts = {}) {
- const { pollInterval = 2000, enabled = true, includePlan = false } = opts;
-
- const [job, setJob] = useState(null);
- const [lines, setLines] = useState([]);
- const [transport, setTransport] = useState('poll');
- const [error, setError] = useState(null);
- const [loading, setLoading] = useState(true);
-
- const maxIdRef = useRef(0);
- const seenRef = useRef(new Set());
- const stoppedRef = useRef(false);
- const pollRef = useRef(null);
-
- // Merge a batch of log rows, de-duping by id and tracking the high-water id.
- const mergeLines = useCallback((incoming) => {
- if (!incoming || incoming.length === 0) return;
- const fresh = [];
- for (const ln of incoming) {
- if (ln.id != null) {
- if (seenRef.current.has(ln.id)) continue;
- seenRef.current.add(ln.id);
- if (ln.id > maxIdRef.current) maxIdRef.current = ln.id;
- }
- fresh.push(ln);
- }
- if (fresh.length === 0) return;
- setLines((prev) => {
- const next = prev.concat(fresh);
- return next.length > MAX_LINES ? next.slice(next.length - MAX_LINES) : next;
- });
- }, []);
-
- const applyJob = useCallback((next) => {
- if (!next) return;
- // The plan is fetched once on boot and never changes; socket status
- // updates don't carry it, so preserve it across replacements.
- setJob((prev) => (prev?.plan && !next.plan ? { ...next, plan: prev.plan } : next));
- if (TERMINAL.has(next.status)) {
- stoppedRef.current = true;
- }
- }, []);
-
- const stopPolling = useCallback(() => {
- if (pollRef.current) {
- clearInterval(pollRef.current);
- pollRef.current = null;
- }
- }, []);
-
- // after_id poll: pull new log rows + the current job status.
- const pollOnce = useCallback(async () => {
- if (stoppedRef.current || !jobId) return;
- try {
- const [logsRes, jobRes] = await Promise.all([
- api.getDeploymentJobLogs(jobId, maxIdRef.current || null),
- api.getDeploymentJob(jobId, false),
- ]);
- setError(null);
- mergeLines(logsRes?.logs || []);
- applyJob(jobRes?.job);
- if (jobRes?.job && TERMINAL.has(jobRes.job.status)) {
- stopPolling();
- }
- } catch (err) {
- setError(err?.data?.error || err?.message || 'Failed to reach the deployment');
- }
- }, [jobId, mergeLines, applyJob, stopPolling]);
-
- const startPolling = useCallback(() => {
- if (pollRef.current || stoppedRef.current || pollInterval <= 0) return;
- setTransport('poll');
- pollRef.current = setInterval(pollOnce, pollInterval);
- }, [pollOnce, pollInterval]);
-
- const refetch = useCallback(() => pollOnce(), [pollOnce]);
-
- useEffect(() => {
- if (!jobId || !enabled) return undefined;
-
- // Reset per-job state (the hook may be reused as jobId changes on retry).
- stoppedRef.current = false;
- maxIdRef.current = 0;
- seenRef.current = new Set();
- setJob(null);
- setLines([]);
- setError(null);
- setLoading(true);
-
- let cancelled = false;
-
- // 1) Full snapshot boot.
- (async () => {
- try {
- const data = await api.getDeploymentJob(jobId, true, includePlan);
- if (cancelled) return;
- const snapshot = data?.job;
- if (snapshot?.logs) mergeLines(snapshot.logs);
- applyJob(snapshot);
- } catch (err) {
- if (!cancelled) {
- setError(err?.data?.error || err?.message || 'Deployment job not found');
- }
- } finally {
- if (!cancelled) setLoading(false);
- }
- })();
-
- // 2) Live socket path, with a graceful fall back to polling.
- socketService.connect();
-
- const resyncAndSubscribe = () => {
- if (stoppedRef.current) return;
- setTransport('socket');
- stopPolling();
- // Re-sync any rows emitted while we were disconnected, THEN trust the
- // stream (dedupe makes overlapping ids harmless).
- api.getDeploymentJobLogs(jobId, maxIdRef.current || null)
- .then((res) => mergeLines(res?.logs || []))
- .catch(() => {});
- socketService.subscribeDeploy(jobId);
- };
-
- const onDeployLog = (payload) => {
- if (payload?.job_id && String(payload.job_id) !== String(jobId)) return;
- mergeLines(payload?.lines || []);
- };
- const onDeployStatus = (payload) => {
- if (payload?.job_id && String(payload.job_id) !== String(jobId)) return;
- if (payload?.status) {
- applyJob(payload.status);
- if (TERMINAL.has(payload.status.status)) {
- socketService.unsubscribeDeploy(jobId);
- stopPolling();
- }
- }
- };
-
- if (socketService.socket?.connected) resyncAndSubscribe();
- const unsubConnect = socketService.on('connected', resyncAndSubscribe);
- const unsubDisconnect = socketService.on('disconnected', () => {
- if (!stoppedRef.current) startPolling();
- });
- const unsubLog = socketService.on('deploy_log', onDeployLog);
- const unsubStatus = socketService.on('deploy_status', onDeployStatus);
-
- // If the socket never connects, poll.
- const grace = setTimeout(() => {
- if (!socketService.socket?.connected && !stoppedRef.current) startPolling();
- }, SOCKET_GRACE_MS);
-
- return () => {
- cancelled = true;
- clearTimeout(grace);
- unsubConnect();
- unsubDisconnect();
- unsubLog();
- unsubStatus();
- socketService.unsubscribeDeploy(jobId);
- stopPolling();
- };
- }, [jobId, enabled, includePlan, mergeLines, applyJob, startPolling, stopPolling]);
-
- const isLive = !!job && !TERMINAL.has(job.status);
-
- return { job, lines, isLive, transport, error, loading, refetch };
+export default function useDeployJobStream(jobId, options = {}) {
+ const {
+ pollInterval = 2000,
+ enabled = true,
+ includePlan = false,
+ } = options;
+
+ const loadRun = useCallback(async ({ includeLogs }) => {
+ const response = await api.getDeploymentJob(jobId, includeLogs, includePlan && includeLogs);
+ return response?.job || null;
+ }, [jobId, includePlan]);
+
+ const stream = useRunStream('deploy', jobId, {
+ pollInterval,
+ enabled,
+ loadRun,
+ });
+
+ return {
+ ...stream,
+ job: stream.run,
+ };
}
diff --git a/frontend/src/hooks/useRunStream.js b/frontend/src/hooks/useRunStream.js
new file mode 100644
index 00000000..b776a53b
--- /dev/null
+++ b/frontend/src/hooks/useRunStream.js
@@ -0,0 +1,185 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { SOCKET_EVENTS } from '../constants/events';
+import api from '../services/api';
+import socketService from '../services/socket';
+import { isTerminalRunStatus, mergeRunLogLines } from './runStream';
+import usePolling from './usePolling';
+
+const SOCKET_GRACE_MS = 2500;
+
+function runFromResponse(response) {
+ return response?.run || response?.job || response || null;
+}
+
+/**
+ * Generalized browser transport for the backend run envelope.
+ *
+ * Every run kind shares persisted after_id log catch-up and run_log/run_status
+ * socket events. Callers may supply loadRun when their domain has a richer
+ * status/snapshot endpoint; logs always fall back to the common /runs twin.
+ */
+export default function useRunStream(runKind, runId, options = {}) {
+ const {
+ enabled = true,
+ pollInterval = 2000,
+ loadRun,
+ initialRun = null,
+ } = options;
+
+ const [run, setRun] = useState(initialRun);
+ const [lines, setLines] = useState([]);
+ const [transport, setTransport] = useState('poll');
+ const [error, setError] = useState(null);
+ const [loading, setLoading] = useState(true);
+ const [pollingEnabled, setPollingEnabled] = useState(false);
+
+ const maxIdRef = useRef(0);
+ const seenRef = useRef(new Set());
+ const stoppedRef = useRef(false);
+
+ const mergeLines = useCallback((incoming) => {
+ setLines((previous) => {
+ const merged = mergeRunLogLines(previous, incoming, seenRef.current);
+ maxIdRef.current = Math.max(maxIdRef.current, merged.maxId);
+ return merged.lines;
+ });
+ }, []);
+
+ const applyRun = useCallback((next) => {
+ if (!next) return;
+ setRun((previous) => ({ ...(previous || {}), ...next }));
+ if (isTerminalRunStatus(next.status)) stoppedRef.current = true;
+ }, []);
+
+ const stopPolling = useCallback(() => {
+ setPollingEnabled(false);
+ }, []);
+
+ const pollOnce = useCallback(async ({ force = false } = {}) => {
+ if ((!force && stoppedRef.current) || !runKind || runId == null) return;
+ try {
+ const requests = [api.getRunLogs(runKind, runId, maxIdRef.current || null)];
+ if (loadRun) requests.push(loadRun({ includeLogs: false }));
+ const [logsResponse, runResponse] = await Promise.all(requests);
+ mergeLines(logsResponse?.logs || []);
+ applyRun(runFromResponse(runResponse));
+ setError(null);
+ if (isTerminalRunStatus(runFromResponse(runResponse)?.status)) stopPolling();
+ } catch (nextError) {
+ setError(nextError?.data?.error || nextError?.message || null);
+ }
+ }, [runKind, runId, loadRun, mergeLines, applyRun, stopPolling]);
+
+ const startPolling = useCallback(() => {
+ if (stoppedRef.current || pollInterval <= 0) return;
+ setTransport('poll');
+ setPollingEnabled(true);
+ }, [pollInterval]);
+
+ usePolling(pollOnce, pollInterval, {
+ enabled: enabled && pollingEnabled && !isTerminalRunStatus(run?.status),
+ immediate: false,
+ });
+
+ const refetch = useCallback(() => pollOnce({ force: true }), [pollOnce]);
+
+ useEffect(() => {
+ if (!runKind || runId == null || !enabled) {
+ setLoading(false);
+ return undefined;
+ }
+
+ stoppedRef.current = isTerminalRunStatus(initialRun?.status);
+ maxIdRef.current = 0;
+ seenRef.current = new Set();
+ setRun(initialRun);
+ setLines([]);
+ setError(null);
+ setLoading(true);
+ setPollingEnabled(false);
+
+ let cancelled = false;
+
+ const boot = async () => {
+ try {
+ if (loadRun) {
+ const response = await loadRun({ includeLogs: true });
+ if (cancelled) return;
+ const snapshot = runFromResponse(response);
+ mergeLines(snapshot?.logs || response?.logs || []);
+ applyRun(snapshot);
+ if (isTerminalRunStatus(snapshot?.status)) {
+ socketService.unsubscribeRun(runKind, runId);
+ stopPolling();
+ }
+ } else {
+ await pollOnce({ force: true });
+ }
+ } catch (nextError) {
+ if (!cancelled) {
+ setError(nextError?.data?.error || nextError?.message || null);
+ }
+ } finally {
+ if (!cancelled) setLoading(false);
+ }
+ };
+ boot();
+
+ socketService.connect();
+
+ const resyncAndSubscribe = () => {
+ if (stoppedRef.current) return;
+ setTransport('socket');
+ stopPolling();
+ api.getRunLogs(runKind, runId, maxIdRef.current || null)
+ .then((response) => mergeLines(response?.logs || []))
+ .catch(() => {});
+ socketService.subscribeRun(runKind, runId);
+ };
+
+ const matchesRun = (payload) => (
+ payload?.run_kind === runKind && String(payload?.run_id) === String(runId)
+ );
+ const onRunLog = (payload) => {
+ if (matchesRun(payload)) mergeLines(payload?.lines || []);
+ };
+ const onRunStatus = (payload) => {
+ if (!matchesRun(payload) || !payload?.status) return;
+ applyRun(payload.status);
+ if (isTerminalRunStatus(payload.status.status)) {
+ socketService.unsubscribeRun(runKind, runId);
+ stopPolling();
+ }
+ };
+
+ if (socketService.socket?.connected) resyncAndSubscribe();
+ const offConnect = socketService.on(SOCKET_EVENTS.CONNECTED, resyncAndSubscribe);
+ const offDisconnect = socketService.on('disconnected', startPolling);
+ const offLog = socketService.on(SOCKET_EVENTS.RUN_LOG, onRunLog);
+ const offStatus = socketService.on(SOCKET_EVENTS.RUN_STATUS, onRunStatus);
+ const grace = setTimeout(() => {
+ if (!socketService.socket?.connected && !stoppedRef.current) startPolling();
+ }, SOCKET_GRACE_MS);
+
+ return () => {
+ cancelled = true;
+ clearTimeout(grace);
+ offConnect();
+ offDisconnect();
+ offLog();
+ offStatus();
+ socketService.unsubscribeRun(runKind, runId);
+ };
+ }, [runKind, runId, enabled, initialRun, loadRun, mergeLines, applyRun, pollOnce, startPolling, stopPolling]);
+
+ return {
+ run,
+ lines,
+ isLive: !!run && !isTerminalRunStatus(run.status),
+ transport,
+ error,
+ loading,
+ refetch,
+ };
+}
diff --git a/frontend/src/services/__tests__/runStream.test.mjs b/frontend/src/services/__tests__/runStream.test.mjs
new file mode 100644
index 00000000..584be34c
--- /dev/null
+++ b/frontend/src/services/__tests__/runStream.test.mjs
@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { buildRunLogsPath } from '../api/runs.js';
+import {
+ isTerminalRunStatus,
+ mergeRunLogLines,
+} from '../../hooks/runStream.js';
+
+test('builds an encoded generalized run log catch-up path', () => {
+ assert.equal(
+ buildRunLogsPath('doctor repair', 'run/42', 19),
+ '/runs/doctor%20repair/run%2F42/logs?after_id=19',
+ );
+});
+
+test('recognizes only the unified terminal run statuses', () => {
+ assert.equal(isTerminalRunStatus('succeeded'), true);
+ assert.equal(isTerminalRunStatus('failed'), true);
+ assert.equal(isTerminalRunStatus('cancelled'), true);
+ assert.equal(isTerminalRunStatus('completed'), false);
+ assert.equal(isTerminalRunStatus('running'), false);
+});
+
+test('de-duplicates persisted log ids and retains a bounded tail', () => {
+ const seen = new Set(['1']);
+ const merged = mergeRunLogLines(
+ [{ id: 1, message: 'old' }],
+ [{ id: 1, message: 'duplicate' }, { id: 2 }, { id: 3 }, { message: 'live' }],
+ seen,
+ 3,
+ );
+
+ assert.deepEqual(merged.lines, [{ id: 2 }, { id: 3 }, { message: 'live' }]);
+ assert.equal(merged.maxId, 3);
+ assert.deepEqual([...seen], ['1', '2', '3']);
+});
diff --git a/frontend/src/services/api/index.js b/frontend/src/services/api/index.js
index dd639c23..c6e7b17d 100644
--- a/frontend/src/services/api/index.js
+++ b/frontend/src/services/api/index.js
@@ -43,6 +43,7 @@ import * as manifestMethods from './manifests.js';
import * as surveyMethods from './survey.js';
import * as dnsCutoverMethods from './dnsCutover.js';
import * as searchMethods from './search.js';
+import * as runMethods from './runs.js';
import * as testSandboxMethods from './testSandbox.js';
import * as themeMethods from './themes.js';
import * as dashboardMethods from './dashboards.js';
@@ -100,6 +101,7 @@ class ApiService extends ApiClient {
surveyMethods,
dnsCutoverMethods,
searchMethods,
+ runMethods,
testSandboxMethods,
themeMethods,
dashboardMethods,
diff --git a/frontend/src/services/api/runs.js b/frontend/src/services/api/runs.js
new file mode 100644
index 00000000..d2f7715d
--- /dev/null
+++ b/frontend/src/services/api/runs.js
@@ -0,0 +1,10 @@
+export function buildRunLogsPath(runKind, runId, afterId = null) {
+ const kind = encodeURIComponent(String(runKind));
+ const id = encodeURIComponent(String(runId));
+ const suffix = afterId == null ? '' : `?after_id=${encodeURIComponent(String(afterId))}`;
+ return `/runs/${kind}/${id}/logs${suffix}`;
+}
+
+export async function getRunLogs(runKind, runId, afterId = null) {
+ return this.request(buildRunLogsPath(runKind, runId, afterId));
+}
diff --git a/frontend/src/services/socket.js b/frontend/src/services/socket.js
index 91b9595c..67f94be4 100644
--- a/frontend/src/services/socket.js
+++ b/frontend/src/services/socket.js
@@ -1,4 +1,5 @@
import { io } from 'socket.io-client';
+import { SOCKET_EVENTS } from '../constants/events';
const getSocketUrl = () => {
if (import.meta.env.DEV) return window.location.origin;
@@ -73,6 +74,14 @@ class SocketService {
this.socket.on('deploy_status', (data) => {
this.emit('deploy_status', data);
});
+
+ this.socket.on(SOCKET_EVENTS.RUN_LOG, (data) => {
+ this.emit(SOCKET_EVENTS.RUN_LOG, data);
+ });
+
+ this.socket.on(SOCKET_EVENTS.RUN_STATUS, (data) => {
+ this.emit(SOCKET_EVENTS.RUN_STATUS, data);
+ });
}
disconnect() {
@@ -118,6 +127,18 @@ class SocketService {
}
}
+ subscribeRun(runKind, runId) {
+ if (this.socket?.connected && runKind && runId != null) {
+ this.socket.emit('subscribe_run', { run_kind: runKind, run_id: runId });
+ }
+ }
+
+ unsubscribeRun(runKind, runId) {
+ if (this.socket?.connected && runKind && runId != null) {
+ this.socket.emit('unsubscribe_run', { run_kind: runKind, run_id: runId });
+ }
+ }
+
on(event, callback) {
if (!this.listeners.has(event)) {
this.listeners.set(event, new Set());