ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
feat(operations): add generalized run stream
Juan Denisee58075fae0b
diff --git a/frontend/scripts/check-frontend-boundaries.mjs b/frontend/scripts/check-frontend-boundaries.mjsindex 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.jsnew file mode 100644index 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.jsindex 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.jsnew file mode 100644index 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.mjsnew file mode 100644index 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.jsindex 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.jsnew file mode 100644index 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.jsindex 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());