Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

11.2 KB
Raw Blame
import { useEffect, useRef, useState } from 'react';
import { safeParseJSON } from '../lib/genUtils';
import { maybeRedirectToLogin } from '../services/apiCore';

/**
 * Shared streaming lifecycle for the BYO runtime install modals
 * (Flux2InstallModal, RuntimeInstallModal). Both streamed the same shape of
 * SSE install log — open on `open`, dispatch `stage`/`log`/`complete`/`error`
 * frames, cap the retained log, surface a "connection lost" error when the
 * socket drops before `complete`, and auto-scroll the log to the bottom — so
 * the plumbing lives here once and each modal keeps only its own chrome.
 *
 * Frame contract (matches the server emitters in pythonSetup.js /
 * setup-image-video.sh):
 *   { type: 'stage',    stage, message? }  → advances currentStage + logs it
 *   { type: 'log',      message }          → appends a log line
 *   { type: 'complete', message }          → done=true, onComplete(frame), closes
 *   { type: 'error',    message }          → error set, closes
 *
 * Closing the EventSource or aborting the fetch stream (via `close()` on
 * cancel, or unmount/disable) is what the server interprets as a cancel — it
 * SIGTERMs the underlying pip/bash child.
 *
 * Deliberately NOT built on `useSseProgress`: this needs kind-tagged log
 * accumulation with a cap + optional debounced flush, stage tracking, a
 * `streamStarted` signal, `doneRef`-gated connection-lost suppression, an
 * `onComplete` callback, and auto-scroll — all beyond what `useSseProgress`
 * exposes. Wrapping it would add indirection without removing code.
 *
 * `flushMs` controls log batching: 0 flushes each line synchronously (fine for
 * the structured, bounded FLUX.2 stream); >0 buffers and flushes on a debounce
 * so a chatty pip/git stream re-renders the log list at ~1/flushMs Hz instead
 * of once per line.
 *
 * @param {string|null} url - SSE endpoint; null/empty leaves the stream closed.
 * @param {object} opts
 * @param {boolean} [opts.enabled=true] - when false, the stream stays closed and state resets.
 * @param {(frame: object) => void} [opts.onComplete] - fired once on the `complete` frame.
 * @param {number} [opts.maxLogLines=500] - cap on retained log lines.
 * @param {number} [opts.flushMs=0] - 0 = per-line flush; >0 = debounce window.
 * @param {'GET'|'POST'} [opts.method='GET'] - GET uses EventSource; POST uses
 *   a single fetch-read SSE response for a non-idempotent install.
 * @returns {{ logs, currentStage, done, error, streamStarted, logsEndRef, close }}
 */

const DEFAULT_MAX_LOG_LINES = 500;
const CONNECTION_LOST_MESSAGE = 'Connection to installer lost. Restart PortOS or try again.';

export function useInstallStream(url, {
  enabled = true,
  onComplete,
  maxLogLines = DEFAULT_MAX_LOG_LINES,
  flushMs = 0,
  method = 'GET',
} = {}) {
  const [logs, setLogs] = useState([]);
  const [currentStage, setCurrentStage] = useState(null);
  const [done, setDone] = useState(false);
  const [error, setError] = useState(null);
  const [streamStarted, setStreamStarted] = useState(false);
  const logsEndRef = useRef(null);
  const esRef = useRef(null);
  const abortRef = useRef(null);
  // Mirror `done` into a ref so es.onerror reads the latest value — the effect
  // closure captures the initial done=false and never refreshes, so without
  // this the modal can flash "Connection lost" when the server cleanly closes
  // the socket right after sending `complete`.
  const doneRef = useRef(false);
  // Stash onComplete in a ref so the EventSource effect doesn't tear down the
  // SSE connection on every parent re-render with a fresh inline arrow.
  const onCompleteRef = useRef(onComplete);
  useEffect(() => { onCompleteRef.current = onComplete; }, [onComplete]);

  // Buffer incoming lines and flush them together. Pip and git can each emit
  // hundreds of lines/sec; per-line setState would re-render the whole log list
  // on every line.
  const pendingRef = useRef([]);
  const flushTimerRef = useRef(null);
  const flush = () => {
    flushTimerRef.current = null;
    if (pendingRef.current.length === 0) return;
    const incoming = pendingRef.current;
    pendingRef.current = [];
    setLogs((prev) => {
      const combined = [...prev, ...incoming];
      return combined.length > maxLogLines ? combined.slice(-maxLogLines) : combined;
    });
  };
  const appendLog = (entry) => {
    pendingRef.current.push(entry);
    if (flushMs > 0) {
      if (flushTimerRef.current == null) flushTimerRef.current = setTimeout(flush, flushMs);
    } else {
      flush();
    }
  };

  useEffect(() => {
    const clearFlush = () => {
      if (flushTimerRef.current != null) { clearTimeout(flushTimerRef.current); flushTimerRef.current = null; }
      // Drop any un-flushed lines too: with flushMs > 0 a superseded stream can
      // leave buffered lines behind, and the next stream's flush would render
      // them into its own log.
      pendingRef.current = [];
    };
    const closeStream = () => {
      if (esRef.current) { esRef.current.close(); esRef.current = null; }
      if (abortRef.current) { abortRef.current.abort(); abortRef.current = null; }
    };

    if (!enabled || !url) {
      setLogs([]);
      setCurrentStage(null);
      setDone(false);
      doneRef.current = false;
      setError(null);
      setStreamStarted(false);
      clearFlush();
      closeStream();
      return undefined;
    }

    // Reset state on every (re)subscribe, not just on disable — a url change
    // while enabled (e.g. a retry that bumps an attempt counter) must start
    // the new stream clean, or a prior run's `error`/`done`/log lines leak
    // into it (wedging consumers that derive "installing" from those flags).
    setLogs([]);
    setCurrentStage(null);
    setDone(false);
    doneRef.current = false;
    setError(null);
    setStreamStarted(true);
    const handleMessage = (msg, closeThis) => {
      if (msg.type === 'stage') {
        setCurrentStage(msg.stage);
        appendLog({ kind: 'stage', text: msg.message || msg.stage });
      } else if (msg.type === 'log') {
        appendLog({ kind: 'log', text: msg.message });
      } else if (msg.type === 'complete') {
        setDone(true);
        doneRef.current = true;
        appendLog({ kind: 'success', text: msg.message });
        flush();
        closeThis();
        onCompleteRef.current?.(msg);
      } else if (msg.type === 'error') {
        const message = msg.message || 'Installer failed.';
        setError(message);
        appendLog({ kind: 'error', text: message });
        flush();
        closeThis();
      }
    };

    // A global CLI install changes host state. EventSource transparently
    // reconnects after a transport drop, which would replay a non-idempotent
    // request. POST callers use exactly one fetch stream instead. Delay the
    // fetch one task turn so React's development-only strict-effect probe
    // tears down before any request leaves the browser; otherwise its setup →
    // cleanup → setup cycle can briefly start and cancel the same install.
    if (String(method).toUpperCase() === 'POST') {
      const controller = new AbortController();
      abortRef.current = controller;
      const isCurrent = () => abortRef.current === controller && !controller.signal.aborted;
      const closeThis = () => {
        if (abortRef.current === controller) abortRef.current = null;
        controller.abort();
      };
      const startTimer = setTimeout(() => {
        if (!isCurrent()) return;
        const run = async () => {
          let reader = null;
          try {
            const response = await fetch(url, { method: 'POST', signal: controller.signal });
            if (!response.ok || !response.body?.getReader) {
              const err = await response.json().catch(() => ({ error: `HTTP ${response.status}` }));
              maybeRedirectToLogin(response, err);
              throw new Error(err.error || `HTTP ${response.status}`);
            }

            reader = response.body.getReader();
            const decoder = new TextDecoder();
            let buffer = '';
            let terminalFrame = false;
            const consumeFrame = (frame) => {
              const dataLine = frame.split(/\r?\n/).find(line => line.startsWith('data:'));
              if (!dataLine || !isCurrent()) return;
              const msg = safeParseJSON(dataLine.slice('data:'.length).trim());
              if (!msg) return;
              terminalFrame ||= msg.type === 'complete' || msg.type === 'error';
              handleMessage(msg, closeThis);
            };

            for (;;) {
              const { done: streamDone, value } = await reader.read();
              if (streamDone) break;
              buffer += decoder.decode(value, { stream: true });
              const frames = buffer.split(/\r?\n\r?\n/);
              buffer = frames.pop() || '';
              for (const frame of frames) consumeFrame(frame);
              if (!isCurrent()) break;
            }
            buffer += decoder.decode();
            if (isCurrent() && buffer.trim()) consumeFrame(buffer);
            if (isCurrent() && !terminalFrame && !doneRef.current) {
              setError((prev) => prev ?? CONNECTION_LOST_MESSAGE);
            }
          } catch (err) {
            if (isCurrent()) setError((prev) => prev ?? (err?.message || CONNECTION_LOST_MESSAGE));
          } finally {
            if (reader) await reader.cancel().catch(() => {});
            if (abortRef.current === controller) abortRef.current = null;
          }
        };
        run();
      }, 0);

      return () => {
        clearTimeout(startTimer);
        clearFlush();
        closeThis();
      };
    }

    const es = new EventSource(url);
    esRef.current = es;
    // Close the instance that fired this event, not whatever esRef currently
    // points at — so a late callback from a superseded stream can't tear down
    // (or null out) a newer one after a url/enabled change.
    const closeThis = () => { if (esRef.current === es) esRef.current = null; es.close(); };

    es.onmessage = (ev) => {
      if (esRef.current !== es) return; // stale callback from a superseded stream
      const msg = safeParseJSON(ev.data);
      if (!msg) return;
      handleMessage(msg, closeThis);
    };

    es.onerror = () => {
      if (esRef.current !== es) return; // stale callback from a superseded stream
      // Network drop or server killed the stream. If we already saw `complete`
      // this is harmless; otherwise surface it so the user isn't stuck on a
      // forever-spinning modal.
      setError((prev) => prev ?? (doneRef.current ? null : CONNECTION_LOST_MESSAGE));
      closeThis();
    };

    return () => {
      clearFlush();
      closeThis();
    };
    // onComplete intentionally excluded — it lives in onCompleteRef.
  }, [url, enabled, maxLogLines, flushMs, method]);

  // Auto-scroll on every new line. behavior:'auto' (instant) avoids queueing
  // hundreds of smooth-scroll animations during a chatty install.
  useEffect(() => {
    if (logsEndRef.current) {
      logsEndRef.current.scrollIntoView({ behavior: 'auto', block: 'end' });
    }
  }, [logs.length]);

  const close = () => {
    if (esRef.current) { esRef.current.close(); esRef.current = null; }
    if (abortRef.current) { abortRef.current.abort(); abortRef.current = null; }
  };

  return { logs, currentStage, done, error, streamStarted, logsEndRef, close };
}