Make history refresh button SSE-aware

The refresh button's title and red-when-stale logic was designed for
the polling era and is misleading under SSE: lastCheckedTime only ticks
on real history changes (so the "Last refreshed Xs ago" text describes
nothing actionable), the 2-minute idle cutoff goes red even when SSE
is healthy, and the click handler called the idempotent
startWatchingHistory which short-circuits once initialized — clicking
did nothing.

In SSE mode the button now shows "Refresh history" with a normal link
variant, and only turns red ("Live updates disconnected. Click to
refresh.") when the SSE socket actually drops after a previous
successful open (gated on the new sseEverConnected latch in
useNotificationSSE so the brief initial-connect window isn't flagged
as an outage). Clicking now forces a real refresh via
refreshHistoryFromPush in both modes. Polling-mode title/variant is
unchanged.

Adds a HistoryCounter Vitest covering the SSE healthy / initial /
lost transitions plus the polling-mode legacy behavior.

Author: mvdbeek

client/src/components/History/CurrentHistory/HistoryCounter.test.ts

@@ -0,0 +1,202 @@
+import { getLocalVue } from "@tests/vitest/helpers";
+import { shallowMount } from "@vue/test-utils";
+import flushPromises from "flush-promises";
+import { createPinia, setActivePinia } from "pinia";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { RegisteredUser } from "@/api";
+import { useServerMock } from "@/api/client/__mocks__";
+import { setSseConnected, setSseHasEverConnected, sseMockFactory } from "@/stores/_testing/sseStoreSupport";
+import { useConfigStore } from "@/stores/configurationStore";
+import { useUserStore } from "@/stores/userStore";
+
+import HistoryCounter from "./HistoryCounter.vue";
+
+const sseState = vi.hoisted(() => ({
+    onEvent: null as ((event: MessageEvent) => void) | null,
+    connect: vi.fn(),
+    disconnect: vi.fn(),
+}));
+
+vi.mock("@/composables/useNotificationSSE", () => sseMockFactory(sseState));
+
+// userStore wires its localStorage-backed refs through this composable; the
+// real watcher hits ``window.localStorage`` which jsdom doesn't expose with a
+// usable Storage prototype here. We don't read any of those refs in this
+// test, so a ref-returning stub is enough to keep userStore initialization
+// happy.
+vi.mock("@/composables/userLocalStorageFromHashedId", async () => {
+    const { ref } = await import("vue");
+    return {
+        useUserLocalStorageFromHashId: <T>(_key: string, initialValue: T) => ref(initialValue),
+    };
+});
+
+const { server, http } = useServerMock();
+
+const localVue = getLocalVue();
+
+const baseHistory = {
+    id: "hist-1",
+    name: "Test history",
+    user_id: "user-1",
+    size: 0,
+    contents_active: { active: 0, deleted: 0, hidden: 0 },
+    update_time: new Date().toISOString(),
+    create_time: new Date().toISOString(),
+    deleted: false,
+    archived: false,
+    purged: false,
+    published: false,
+};
+
+function registerConfigHandler(enableSse: boolean): void {
+    server.use(
+        http.get("/api/configuration", ({ response }) => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return response(200).json({ enable_sse_updates: enableSse } as any);
+        }),
+    );
+}
+
+function setEnableSse(enabled: boolean): void {
+    registerConfigHandler(enabled);
+    // The store kicks off ``loadConfig`` on creation; ``setConfiguration``
+    // makes the value visible synchronously regardless of the network round
+    // trip so the component reads it on mount.
+    useConfigStore().setConfiguration({ enable_sse_updates: enabled } as never);
+    // The refresh button is gated on ``currentUser``; without a logged-in
+    // user the BButtonGroup that contains it is never rendered.
+    useUserStore().currentUser = { id: "user-1", email: "u@example.com" } as RegisteredUser;
+}
+
+function mountCounter(props: Partial<{ lastChecked: Date; isWatching: boolean }> = {}) {
+    return shallowMount(HistoryCounter as unknown as object, {
+        propsData: {
+            history: baseHistory,
+            lastChecked: props.lastChecked ?? new Date(),
+            isWatching: props.isWatching ?? true,
+        },
+        localVue,
+    });
+}
+
+function refreshButton(wrapper: ReturnType<typeof shallowMount>) {
+    return wrapper.get(".history-refresh-button");
+}
+
+describe("HistoryCounter — refresh button", () => {
+    beforeEach(() => {
+        setActivePinia(createPinia());
+        sseState.connect.mockClear();
+        sseState.disconnect.mockClear();
+        // sseMockFactory lazily creates these refs on first call; reset to a
+        // known state for each test.
+        Reflect.deleteProperty(sseState, "connected");
+        Reflect.deleteProperty(sseState, "hasEverConnected");
+        // Re-create refs by invoking the factory once — every component mount
+        // already triggers this, but doing it explicitly makes the per-test
+        // state setup obvious.
+        sseMockFactory(sseState);
+        vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+
+    describe("SSE mode", () => {
+        beforeEach(() => {
+            setEnableSse(true);
+        });
+
+        it('shows "Refresh history" with a link variant when the connection is healthy', async () => {
+            setSseConnected(sseState, true);
+            setSseHasEverConnected(sseState, true);
+
+            const wrapper = mountCounter();
+            await flushPromises();
+
+            const button = refreshButton(wrapper);
+            expect(button.attributes("title")).toBe("Refresh history");
+            expect(button.attributes("variant")).toBe("link");
+        });
+
+        it("does not flag the initial-connect window as a connection loss", async () => {
+            // EventSource hasn't opened yet — connected=false, hasEverConnected=false.
+            setSseConnected(sseState, false);
+            setSseHasEverConnected(sseState, false);
+
+            const wrapper = mountCounter();
+            await flushPromises();
+
+            const button = refreshButton(wrapper);
+            expect(button.attributes("title")).toBe("Refresh history");
+            expect(button.attributes("variant")).toBe("link");
+        });
+
+        it("turns red when the SSE connection is lost after a successful open", async () => {
+            setSseConnected(sseState, true);
+            setSseHasEverConnected(sseState, true);
+
+            const wrapper = mountCounter();
+            await flushPromises();
+
+            // Simulate the EventSource onerror path: connection drops after
+            // it had previously been established.
+            setSseConnected(sseState, false);
+            await flushPromises();
+
+            const button = refreshButton(wrapper);
+            expect(button.attributes("title")).toBe("Live updates disconnected. Click to refresh.");
+            expect(button.attributes("variant")).toBe("danger");
+        });
+    });
+
+    describe("polling mode", () => {
+        beforeEach(() => {
+            setEnableSse(false);
+        });
+
+        it("shows the legacy 'Last refreshed …' title with a link variant when fresh", async () => {
+            const wrapper = mountCounter({ lastChecked: new Date(), isWatching: true });
+            await flushPromises();
+
+            const button = refreshButton(wrapper);
+            expect(button.attributes("title")).toMatch(/^Last refreshed .+ ago$/);
+            expect(button.attributes("variant")).toBe("link");
+        });
+
+        it("turns red after 2 minutes of staleness", async () => {
+            // 3 minutes ago — past the 120000ms cutoff in HistoryCounter.
+            const stale = new Date(Date.now() - 3 * 60 * 1000);
+            const wrapper = mountCounter({ lastChecked: stale, isWatching: true });
+            await flushPromises();
+
+            const button = refreshButton(wrapper);
+            expect(button.attributes("title")).toMatch(/Consider reloading the page\.$/);
+            expect(button.attributes("variant")).toBe("danger");
+        });
+
+        it("turns red when the resource watcher reports it is no longer watching", async () => {
+            const wrapper = mountCounter({ lastChecked: new Date(), isWatching: false });
+            await flushPromises();
+
+            const button = refreshButton(wrapper);
+            expect(button.attributes("variant")).toBe("danger");
+        });
+    });
+
+    it("emits reloadContents when the refresh button is clicked", async () => {
+        setEnableSse(true);
+        setSseConnected(sseState, true);
+        setSseHasEverConnected(sseState, true);
+
+        const wrapper = mountCounter();
+        await flushPromises();
+        await refreshButton(wrapper).trigger("click");
+
+        expect(wrapper.emitted("reloadContents")).toBeTruthy();
+        expect(wrapper.emitted("reloadContents")?.length).toBe(1);
+    });
+});

client/src/components/History/CurrentHistory/HistoryCounter.vue

@@ -11,7 +11,9 @@ import { useRouter } from "vue-router/composables";
 
 import { type HistorySummaryExtended, userOwnsHistory } from "@/api";
 import { HistoryFilters } from "@/components/History/HistoryFilters.js";
+import { useConfig } from "@/composables/config";
 import { useHistoryContentStats } from "@/composables/historyContentStats";
+import { useSSEConnectionStatus } from "@/composables/useNotificationSSE";
 import { useUserStore } from "@/stores/userStore";
 import localize from "@/utils/localization";
 
@@ -39,10 +41,18 @@ const emit = defineEmits(["update:filter-text", "reloadContents"]);
 
 const router = useRouter();
 const { currentUser, isAnonymous } = storeToRefs(useUserStore());
+const { config } = useConfig();
+const { connected: sseConnected, hasEverConnected: sseHasEverConnected } = useSSEConnectionStatus();
 const { historySize, numItemsActive, numItemsDeleted, numItemsHidden } = useHistoryContentStats(
     toRef(props, "history"),
 );
 
+const sseMode = computed(() => config.value?.enable_sse_updates === true);
+// Treat the connection as "lost" only after a successful open: the brief
+// initial-connect window where ``sseConnected`` is still false isn't a
+// real outage and shouldn't go red.
+const sseLost = computed(() => sseMode.value && sseHasEverConnected.value && !sseConnected.value);
+
 const reloadButtonLoading = ref(false);
 const reloadButtonTitle = ref("");
 const reloadButtonVariant = ref("link");
@@ -84,6 +94,20 @@ function getCurrentFilterVal(filter: string) {
 }
 
 function updateTime() {
+    if (sseMode.value) {
+        // Under SSE the "last checked" timestamp ticks only when the history
+        // actually changes — a 2-minute idle window is normal and shouldn't
+        // be presented as staleness. Surface a connection-lost warning
+        // instead, gated on a previous successful open.
+        if (sseLost.value) {
+            reloadButtonTitle.value = "Live updates disconnected. Click to refresh.";
+            reloadButtonVariant.value = "danger";
+        } else {
+            reloadButtonTitle.value = "Refresh history";
+            reloadButtonVariant.value = "link";
+        }
+        return;
+    }
     const diffToNow = formatDistanceToNowStrict(props.lastChecked, { addSuffix: true });
     const diffToNowSec = Date.now().valueOf() - props.lastChecked.valueOf();
     // if history isn't being watched or hasn't been watched/polled for over 2 minutes
@@ -104,9 +128,14 @@ async function reloadContents() {
     }, 1000);
 }
 
+// Re-render the button as soon as the SSE state flips, instead of waiting up
+// to a second for the next setInterval tick — connection-loss feedback should
+// be immediate.
+watchImmediate([sseMode, sseLost], updateTime);
+
 onMounted(() => {
-    updateTime();
-    // update every second
+    // The polling-mode title is derived from a wall-clock diff that has no
+    // reactive dependency, so a 1s tick keeps "Last refreshed Xs ago" fresh.
     setInterval(updateTime, 1000);
 });
 </script>

client/src/components/History/CurrentHistory/HistoryPanel.vue

@@ -4,6 +4,7 @@ import { storeToRefs } from "pinia";
 import { computed, onMounted, ref, set as VueSet, unref, watch } from "vue";
 
 import { type HistoryItemSummary, type HistorySummaryExtended, userOwnsHistory } from "@/api";
+import { getGalaxyInstance } from "@/app";
 import ExpandedItems from "@/components/History/Content/ExpandedItems";
 import { HistoryFilters } from "@/components/History/HistoryFilters";
 import { deleteContent, updateContentFields } from "@/components/History/model/queries";
@@ -13,6 +14,7 @@ import { useHistoryStore } from "@/stores/historyStore";
 import { useUserStore } from "@/stores/userStore";
 import { type Alias, getOperatorForAlias } from "@/utils/filtering";
 import { setItemDragstart } from "@/utils/setDrag";
+import { refreshHistoryFromPush } from "@/watch/watchHistory";
 
 import { useHistoryDragDrop } from "../../../composables/historyDragDrop";
 
@@ -328,7 +330,11 @@ function updateContentStats() {
 }
 
 function reloadContents() {
-    historyStore.startWatchingHistory();
+    // ``startWatchingHistory`` is idempotent, so the prior call did nothing
+    // once SSE/polling was already initialized. Force a refresh through the
+    // same code path SSE pushes use so the user-initiated click actually
+    // re-fetches the history and items.
+    refreshHistoryFromPush(getGalaxyInstance()).catch((err) => console.error("Manual history refresh failed:", err));
 }
 
 function setInvisible(item: HistoryItemSummary) {

client/src/composables/useNotificationSSE.ts

@@ -1,4 +1,4 @@
-import { onScopeDispose, ref } from "vue";
+import { onScopeDispose, readonly, ref } from "vue";
 
 import { withPrefix } from "@/utils/redirect";
 
@@ -39,6 +39,10 @@ type Handler = (event: MessageEvent) => void;
 
 let sharedSource: EventSource | null = null;
 const sharedConnected = ref(false);
+// True once the SSE connection has succeeded at least once in this session.
+// Used by UI to distinguish "still connecting" from "was connected, dropped"
+// — only the latter should surface a connection-lost warning.
+const sseEverConnected = ref(false);
 const subscribers: Map<SSEEventType, Set<Handler>> = new Map();
 // Track the per-type dispatchers we registered so ``closeSource`` removes the
 // exact same listeners (``addEventListener`` matches by reference).
@@ -70,6 +74,7 @@ function openSourceIfNeeded() {
 
     sharedSource.onopen = () => {
         sharedConnected.value = true;
+        sseEverConnected.value = true;
         // Global readiness flag so Selenium tests can distinguish a working
         // SSE pipeline from the polling fallback.
         sseGlobals().__galaxy_sse_connected = true;
@@ -189,3 +194,16 @@ export function useSSE(onEvent: Handler, eventTypes: readonly SSEEventType[] = S
  * @deprecated Use `useSSE` instead. This alias exists for backward compatibility.
  */
 export const useNotificationSSE = useSSE;
+
+/**
+ * Read-only handle on the shared SSE connection state. ``connected`` flips
+ * with the EventSource lifecycle; ``hasEverConnected`` latches true on the
+ * first successful open so callers can ignore the initial-connect window
+ * when surfacing a "connection lost" warning.
+ */
+export function useSSEConnectionStatus() {
+    return {
+        connected: readonly(sharedConnected),
+        hasEverConnected: readonly(sseEverConnected),
+    };
+}

client/src/stores/_testing/sseStoreSupport.ts

@@ -21,20 +21,28 @@ export interface SSEMockState {
     connect: ReturnType<typeof vi.fn>;
     disconnect: ReturnType<typeof vi.fn>;
     connected?: Ref<boolean>;
+    hasEverConnected?: Ref<boolean>;
 }
 
 /** Build the factory used with ``vi.mock("@/composables/useNotificationSSE", ...)``. */
 export function sseMockFactory(state: SSEMockState) {
-    // Lazily initialize ``connected`` so existing callers that don't pass it
-    // still get a working ref.
+    // Lazily initialize the connection refs so existing callers that don't
+    // pre-populate them still get working refs.
     if (!state.connected) {
         state.connected = ref(false);
     }
+    if (!state.hasEverConnected) {
+        state.hasEverConnected = ref(false);
+    }
     return {
         useSSE: vi.fn((onEvent: (event: MessageEvent) => void) => {
             state.onEvent = onEvent;
             return { connect: state.connect, disconnect: state.disconnect, connected: state.connected };
         }),
+        useSSEConnectionStatus: vi.fn(() => ({
+            connected: state.connected,
+            hasEverConnected: state.hasEverConnected,
+        })),
     };
 }
 
@@ -46,6 +54,25 @@ export function emitSse(state: SSEMockState, type: string, payload: unknown): vo
     state.onEvent(new MessageEvent(type, { data: JSON.stringify(payload) }));
 }
 
+/** Set the mocked ``connected`` flag, lazy-initializing the ref if a test reads
+ *  it before any component has mounted. */
+export function setSseConnected(state: SSEMockState, value: boolean): void {
+    if (!state.connected) {
+        state.connected = ref(value);
+    } else {
+        state.connected.value = value;
+    }
+}
+
+/** Set the mocked ``hasEverConnected`` latch, lazy-initializing the ref. */
+export function setSseHasEverConnected(state: SSEMockState, value: boolean): void {
+    if (!state.hasEverConnected) {
+        state.hasEverConnected = ref(value);
+    } else {
+        state.hasEverConnected.value = value;
+    }
+}
+
 /**
  * Save the current ``document.visibilityState`` descriptor and return a restorer.
  * Call the restorer in ``afterEach`` to prevent patching from leaking into later tests.