import { useCallback, useEffect, useRef } from 'react'; import { useClient } from 'hooks/useClient'; import { useGlobal } from 'hooks/useGlobal'; import { readableError } from './errors'; /** * The state of `derived/` — what is running, what is outstanding, and how to start a pass. * * ── Why this is shared at all ── * * The button moved to the panel's action bar, beside Build and Publish, because syncing is one of the * things somebody does to a site rather than a detail of one card. The rest of it — the progress bar, * the failures, the run history — stayed in Administration, where there is room to read it. * * So one subject is drawn in two places at once, and they must not disagree. A header saying "Sync * now" beside a card saying "3 changed" is two components each deciding what is true. * * ── `useGlobal`, not a context ── * * A slot in the app-wide query cache, keyed by name: whoever reads the key gets the value, whoever * writes it re-renders every reader. No provider, so nothing has to wrap the bar and the panel * together, and a third place that wants this later just reads the key. * * ── One reader FETCHES, everyone else reads ── * * `useGlobal` shares the value, not the work: mount the same effects twice and the endpoint is polled * twice a second. So the fetching is a separate hook with exactly one caller — `SyncButton`, which * lives in the bar and is therefore mounted whenever anything in this plugin is open. The * Administration card is mounted only sometimes, which is precisely why it must not be the one asking. */ export type SyncError = { file: string; message: string }; export type SyncState = { running: boolean; total: number | null; done: number; built: number; skipped: number; /** Ladders renamed into place because their original moved, rather than rebuilt. */ moved: number; /** Derived folders removed because their original is gone. Whole-tree syncs only. */ pruned: number; errors: SyncError[]; current: string[]; startedAt: string | null; finishedAt: string | null; fatal: string | null; }; export type Run = { startedAt: string; finishedAt: string; trigger: 'manual' | 'watcher'; scope: string; total: number; built: number; skipped: number; moved: number; pruned: number; errors: SyncError[]; fatal: string | null; }; export type Reconciliation = { originals: number; current: number; missing: string[]; stale: string[] }; export type Ledger = { runs: Run[]; reconciliation: Reconciliation }; /** How often to ask, while something is happening. Fast enough to look live, slow enough to be free. */ const POLL_MS = 1000; /** The slot. One name, so a third reader is a one-line addition rather than a refactor. */ const KEY = ['fofos-admin', 'media-sync']; type Shared = { state: SyncState | null; ledger: Ledger | null; /** A start request is in flight — distinct from `state.running`, which is the SERVER's answer. */ busy: boolean; error: string | null; }; const EMPTY: Shared = { state: null, ledger: null, busy: false, error: null }; export type MediaSync = Shared & { /** A pass is under way. */ running: boolean; /** How far through, or null while the walk is still counting — nothing honest to divide by yet. */ percent: number | null; /** Files with no ladder plus files whose ladder is stale. Zero means `derived/` is current. */ outstanding: number; /** Whether the ledger has been read at all. Before that `outstanding` is 0 because it is unknown. */ known: boolean; start: () => Promise; }; /** Read the sync, and start one. Any number of callers. */ export const useMediaSync = (): MediaSync => { const client = useClient(); const clientRef = useRef(client); clientRef.current = client; const [shared, setShared] = useGlobal(KEY, EMPTY); const start = useCallback(async () => { setShared((was) => ({ ...was, busy: true, error: null })); try { const result = await clientRef.current.post<{ started: boolean; state: SyncState }>( '/fofos-admin/_config/media/sync', {}, ); setShared((was) => ({ ...was, state: result.state, busy: false })); } catch (caught) { setShared((was) => ({ ...was, busy: false, error: readableError(caught) })); } // `setShared` is rebuilt every render by useGlobal — see the note in SitePreview about verbs from // useClient. Left out of the deps on purpose, and it closes over nothing that changes. // eslint-disable-next-line react-hooks/exhaustive-deps }, []); const total = shared.state?.total ?? null; const done = shared.state?.done ?? 0; const reconciliation = shared.ledger?.reconciliation ?? null; return { ...shared, running: shared.state?.running ?? false, percent: total && total > 0 ? Math.round((done / total) * 100) : null, outstanding: (reconciliation?.missing.length ?? 0) + (reconciliation?.stale.length ?? 0), known: reconciliation !== null, start, }; }; /** * Keep the slot current. EXACTLY ONE caller — `SyncButton`. * * Separate from reading because `useGlobal` shares the value and not the work: two components running * these effects would poll the same endpoint twice a second and re-read the ledger twice per run. */ export const useMediaSyncFeed = (): void => { const client = useClient(); const clientRef = useRef(client); clientRef.current = client; const [shared, setShared] = useGlobal(KEY, EMPTY); const setRef = useRef(setShared); setRef.current = setShared; const load = useCallback(async () => { try { const state = await clientRef.current.get('/fofos-admin/_config/media/sync'); setRef.current((was) => ({ ...was, state })); } catch { // Owner-only. Root Location has already said so once if that is the reason. setRef.current((was) => ({ ...was, state: null })); } }, []); /* The ledger is NOT polled. It walks the whole tree reading manifests, so asking for it once a second beside a progress bar would have every tick re-read the library. It is read on arrival and again when a run stops, which are the only two moments its answer can have changed. */ const loadLedger = useCallback(async () => { try { const ledger = await clientRef.current.get('/fofos-admin/_config/media/ledger'); setRef.current((was) => ({ ...was, ledger })); } catch { setRef.current((was) => ({ ...was, ledger: null })); } }, []); useEffect(() => { void load(); void loadLedger(); }, [load, loadLedger]); const running = shared.state?.running ?? false; useEffect(() => { if (!running) return; const timer = setInterval(() => void load(), POLL_MS); return () => clearInterval(timer); }, [running, load]); // Re-read when a run STOPS. `running` going true→false is the edge, so a finished sync updates what // is left to do without the panel being reopened. const wasRunning = useRef(false); useEffect(() => { if (wasRunning.current && !running) void loadLedger(); wasRunning.current = running; }, [running, loadLedger]); };