Persist widget data across reloads

This commit is contained in:
Thomas Camlong committed 2026-08-23 09:00:33 +02:00
1 parent 0d9eeb5752
commit a2a408410a
30 files changed
+713 -127

No files matched your search

@@ -0,0 +1,215 @@
// @vitest-environment jsdom
import { dehydrate, QueryClient } from "@tanstack/react-query";
import type { PersistedClient } from "@tanstack/react-query-persist-client";
import { persistQueryClientRestore, removeOldestQuery } from "@tanstack/react-query-persist-client";
import { afterEach, describe, expect, test, vi } from "vitest";
import {
createSessionQueryPersister,
getQueryPersistenceBuster,
getQueryPersistenceStorageKey,
queryPersistenceMaxDataBytes,
removeSessionQueryCache,
scheduleRestoredDashboardQueryRefresh,
shouldPersistDashboardQuery,
} from "./query-persistence";
const createSuccessfulQuery = (queryKey: readonly unknown[], data: unknown, updatedAt = Date.now()) => {
const queryClient = new QueryClient();
queryClient.setQueryData(queryKey, data, { updatedAt });
const query = queryClient.getQueryCache().find({ queryKey });
if (!query) throw new Error("Expected query to be present");
return { query, queryClient };
};
afterEach(() => {
vi.useRealTimers();
vi.restoreAllMocks();
window.sessionStorage.clear();
});
describe("widget query persistence", () => {
test("persists successful dashboard data but not unrelated, ping, pending, or oversized queries", () => {
const widget = createSuccessfulQuery([["widget", "weather", "getWeather"], { type: "query" }], { temp: 21 });
const supporting = createSuccessfulQuery([["app", "byIds"], { type: "query" }], [{ id: "app-1" }]);
const unrelated = createSuccessfulQuery([["board", "getBoardByName"], { type: "query" }], { name: "Home" });
const ping = createSuccessfulQuery([["widget", "app", "ping"], { type: "query" }], { status: "online" });
const oversized = createSuccessfulQuery([["widget", "example"], { type: "query" }], {
value: "x".repeat(queryPersistenceMaxDataBytes + 1),
});
const pendingClient = new QueryClient();
const pending = pendingClient.getQueryCache().build(pendingClient, {
queryKey: [["widget", "calendar", "findAllEvents"], { type: "query" }],
queryFn: () => Promise.resolve([]),
});
expect(shouldPersistDashboardQuery(widget.query)).toBe(true);
expect(shouldPersistDashboardQuery(supporting.query)).toBe(true);
expect(shouldPersistDashboardQuery(unrelated.query)).toBe(false);
expect(shouldPersistDashboardQuery(ping.query)).toBe(false);
expect(shouldPersistDashboardQuery(oversized.query)).toBe(false);
expect(shouldPersistDashboardQuery(pending)).toBe(false);
});
test("uses stable, isolated storage keys for anonymous and authenticated scopes", () => {
expect(getQueryPersistenceStorageKey("user-a")).toBe(getQueryPersistenceStorageKey("user-a"));
expect(getQueryPersistenceStorageKey("user-a")).not.toBe(getQueryPersistenceStorageKey("user-b"));
expect(getQueryPersistenceStorageKey(null)).not.toBe(getQueryPersistenceStorageKey("user-a"));
expect(getQueryPersistenceStorageKey("user-a")).not.toContain("user-a");
const userAKey = getQueryPersistenceStorageKey("user-a");
const userBKey = getQueryPersistenceStorageKey("user-b");
window.sessionStorage.setItem(userAKey, "a");
window.sessionStorage.setItem(userBKey, "b");
removeSessionQueryCache("user-a");
expect(window.sessionStorage.getItem(userAKey)).toBeNull();
expect(window.sessionStorage.getItem(userBKey)).toBe("b");
});
test("round-trips SuperJSON data, strips refresh errors, and removes corrupted storage", async () => {
vi.useFakeTimers();
const scope = "user-a";
const key = getQueryPersistenceStorageKey(scope);
const persister = createSessionQueryPersister(scope);
const { query, queryClient } = createSuccessfulQuery([["widget", "calendar", "findAllEvents"], { type: "query" }], {
startsAt: new Date("2026-08-22T12:00:00.000Z"),
});
query.setState({ ...query.state, error: new Error("private refresh error"), status: "error" });
expect(shouldPersistDashboardQuery(query)).toBe(true);
const persistedClient: PersistedClient = {
timestamp: Date.now(),
buster: getQueryPersistenceBuster(scope),
clientState: dehydrate(queryClient, { shouldDehydrateQuery: shouldPersistDashboardQuery }),
};
void persister.persistClient(persistedClient);
await vi.advanceTimersByTimeAsync(1_000);
const restored = await persister.restoreClient();
const restoredData = restored?.clientState.queries[0]?.state.data as { startsAt?: Date } | undefined;
expect(restoredData?.startsAt).toEqual(new Date("2026-08-22T12:00:00.000Z"));
expect(restored?.clientState.queries[0]?.state.status).toBe("success");
expect(restored?.clientState.queries[0]?.state.error).toBeNull();
expect(window.sessionStorage.getItem(key)).not.toContain("private refresh error");
const restoredPredicate = persister.takeRestoredDashboardQueryPredicate();
expect(restoredPredicate?.(query)).toBe(true);
expect(persister.takeRestoredDashboardQueryPredicate()).toBeUndefined();
window.sessionStorage.setItem(key, "not-valid-superjson");
await expect(persister.restoreClient()).resolves.toBeUndefined();
expect(window.sessionStorage.getItem(key)).toBeNull();
});
test.each([
["expired", 1, getQueryPersistenceBuster("user-a")],
["different buster", new Date("2026-08-22T12:00:00.000Z").getTime(), getQueryPersistenceBuster("user-b")],
])("discards %s cache entries", async (_case, timestamp, storedBuster) => {
vi.useFakeTimers();
vi.setSystemTime(new Date("2026-08-22T12:00:00.000Z"));
const scope = "user-a";
const persister = createSessionQueryPersister(scope);
const { queryClient } = createSuccessfulQuery([["widget", "weather", "getWeather"], { type: "query" }], {
temp: 21,
});
void persister.persistClient({ timestamp, buster: storedBuster, clientState: dehydrate(queryClient) });
await vi.advanceTimersByTimeAsync(1_000);
const restoredClient = new QueryClient();
await persistQueryClientRestore({
queryClient: restoredClient,
persister,
maxAge: 5 * 60 * 1_000,
buster: getQueryPersistenceBuster(scope),
});
expect(restoredClient.getQueryData([["widget", "weather", "getWeather"], { type: "query" }])).toBeUndefined();
expect(window.sessionStorage.getItem(getQueryPersistenceStorageKey(scope))).toBeNull();
});
test("quota retry removes the oldest query first", () => {
const old = createSuccessfulQuery([["widget", "old"], { type: "query" }], "old", 1);
const recent = createSuccessfulQuery([["widget", "recent"], { type: "query" }], "recent", 2);
const persistedClient: PersistedClient = {
timestamp: Date.now(),
buster: getQueryPersistenceBuster("user-a"),
clientState: {
mutations: [],
queries: [...dehydrate(old.queryClient).queries, ...dehydrate(recent.queryClient).queries],
},
};
const retried = removeOldestQuery({ persistedClient, error: new Error("quota"), errorCount: 1 });
expect(retried?.clientState.queries).toHaveLength(1);
expect(retried?.clientState.queries[0]?.queryKey).toEqual([["widget", "recent"], { type: "query" }]);
});
test("refreshes only restored cache data without awaiting the refresh", async () => {
vi.useFakeTimers();
const scope = "user-a";
const queryKey = [["widget", "weather", "getWeather"], { type: "query" }] as const;
const cached = createSuccessfulQuery(queryKey, { temp: 20 }, 10);
const persister = createSessionQueryPersister(scope);
void persister.persistClient({
timestamp: Date.now(),
buster: getQueryPersistenceBuster(scope),
clientState: dehydrate(cached.queryClient),
});
await vi.advanceTimersByTimeAsync(1_000);
await persister.restoreClient();
const fresh = createSuccessfulQuery(queryKey, { temp: 21 }, 20);
const neverSettles = new Promise<void>(() => undefined);
const invalidateQueries = vi.spyOn(fresh.queryClient, "invalidateQueries").mockReturnValue(neverSettles);
expect(scheduleRestoredDashboardQueryRefresh(fresh.queryClient, persister)).toBeUndefined();
expect(invalidateQueries).not.toHaveBeenCalled();
await vi.advanceTimersByTimeAsync(0);
expect(invalidateQueries).toHaveBeenCalledOnce();
const predicate = invalidateQueries.mock.calls[0]?.[0]?.predicate;
expect(predicate?.(cached.query)).toBe(true);
expect(predicate?.(fresh.query)).toBe(false);
});
test("does not invalidate fresh queries when no cache was restored", async () => {
vi.useFakeTimers();
const persister = createSessionQueryPersister("empty");
await persister.restoreClient();
const fresh = createSuccessfulQuery([["widget", "weather", "getWeather"], { type: "query" }], { temp: 21 });
const invalidateQueries = vi.spyOn(fresh.queryClient, "invalidateQueries");
scheduleRestoredDashboardQueryRefresh(fresh.queryClient, persister);
await vi.advanceTimersByTimeAsync(0);
expect(invalidateQueries).not.toHaveBeenCalled();
});
test("treats blocked storage operations as an empty cache", async () => {
const blockedStorage = {
getItem: () => {
throw new DOMException("blocked", "SecurityError");
},
removeItem: () => {
throw new DOMException("blocked", "SecurityError");
},
setItem: () => {
throw new DOMException("blocked", "SecurityError");
},
} as unknown as Storage;
const persister = createSessionQueryPersister("blocked", blockedStorage);
await expect(persister.restoreClient()).resolves.toBeUndefined();
expect(() => persister.removeClient()).not.toThrow();
expect(() => removeSessionQueryCache("blocked", blockedStorage)).not.toThrow();
});
test("treats an unavailable session storage getter as an empty cache", async () => {
vi.spyOn(window, "sessionStorage", "get").mockImplementation(() => {
throw new DOMException("blocked", "SecurityError");
});
expect(() => createSessionQueryPersister("blocked-getter")).not.toThrow();
expect(() => removeSessionQueryCache("blocked-getter")).not.toThrow();
await expect(createSessionQueryPersister("blocked-getter").restoreClient()).resolves.toBeUndefined();
});
});
@@ -0,0 +1,158 @@
import type { QueryClient, QueryKey } from "@tanstack/react-query";
import type { PersistedClient, Persister } from "@tanstack/react-query-persist-client";
import { removeOldestQuery } from "@tanstack/react-query-persist-client";
import { createSyncStoragePersister } from "@tanstack/query-sync-storage-persister";
import { parse, stringify } from "superjson";
import { isWidgetDataQueryKey, queryCacheDefaultGcTimeMs } from "@homarr/api/query-cache";
export const queryPersistenceMaxAgeMs = queryCacheDefaultGcTimeMs;
export const queryPersistenceMaxDataBytes = 256 * 1024;
const queryPersistenceBuster = "v1-session-superjson";
const queryPersistenceStoragePrefix = "homarr:widget-query-cache:v1";
const hashScope = (scope: string) => {
let hash = 2_166_136_261;
for (let index = 0; index < scope.length; index += 1) {
hash ^= scope.charCodeAt(index);
hash = Math.imul(hash, 16_777_619);
}
return (hash >>> 0).toString(36);
};
export const getQueryPersistenceStorageKey = (scope: string | null) =>
`${queryPersistenceStoragePrefix}:${hashScope(scope ?? "anonymous")}`;
export const getQueryPersistenceBuster = (scope: string | null) => `${queryPersistenceBuster}:${scope ?? "anonymous"}`;
interface PersistableQuery {
queryHash?: string;
queryKey: QueryKey;
state: {
data: unknown;
dataUpdatedAt: number;
status: string;
};
}
type RestoredDashboardQueryPredicate = (query: PersistableQuery) => boolean;
export interface SessionQueryPersister extends Persister {
takeRestoredDashboardQueryPredicate: () => RestoredDashboardQueryPredicate | undefined;
}
export const shouldPersistDashboardQuery = (query: PersistableQuery) => {
if (query.state.data === undefined || query.state.dataUpdatedAt <= 0 || !isWidgetDataQueryKey(query.queryKey)) {
return false;
}
try {
return new TextEncoder().encode(stringify(query.state.data)).byteLength <= queryPersistenceMaxDataBytes;
} catch {
return false;
}
};
const sanitizePersistedClient = (client: PersistedClient): PersistedClient => ({
...client,
clientState: {
mutations: [],
queries: client.clientState.queries.map((query) => ({
...query,
state: {
...query.state,
error: null,
errorUpdateCount: 0,
errorUpdatedAt: 0,
fetchFailureCount: 0,
fetchFailureReason: null,
status: "success",
},
})),
},
});
const getSessionStorage = (): Storage | undefined => {
if (typeof window === "undefined") return undefined;
try {
return window.sessionStorage;
} catch {
return undefined;
}
};
const removeStorageItem = (storage: Storage | undefined, key: string) => {
try {
storage?.removeItem(key);
} catch {
// Persistence is optional. Treat blocked or unavailable storage as an empty cache.
}
};
export const createSessionQueryPersister = (
scope: string | null,
storage: Storage | undefined = getSessionStorage(),
): SessionQueryPersister => {
const key = getQueryPersistenceStorageKey(scope);
const buster = getQueryPersistenceBuster(scope);
let restoredQueries = new Map<string, number>();
const persister = createSyncStoragePersister({
storage,
key,
retry: removeOldestQuery,
serialize: (client) => stringify(sanitizePersistedClient(client)),
deserialize: (value) => parse<PersistedClient>(value),
});
return {
...persister,
async restoreClient() {
restoredQueries = new Map();
try {
const client = await persister.restoreClient();
if (
client &&
client.timestamp > 0 &&
Date.now() - client.timestamp <= queryPersistenceMaxAgeMs &&
client.buster === buster
) {
restoredQueries = new Map(
client.clientState.queries.map((query) => [query.queryHash, query.state.dataUpdatedAt]),
);
}
return client;
} catch {
removeStorageItem(storage, key);
return undefined;
}
},
removeClient() {
restoredQueries = new Map();
removeStorageItem(storage, key);
},
takeRestoredDashboardQueryPredicate() {
if (restoredQueries.size === 0) return undefined;
const restoredSnapshot = restoredQueries;
restoredQueries = new Map();
return (query) =>
query.queryHash !== undefined &&
restoredSnapshot.get(query.queryHash) === query.state.dataUpdatedAt &&
shouldPersistDashboardQuery(query);
},
};
};
export const scheduleRestoredDashboardQueryRefresh = (queryClient: QueryClient, persister: SessionQueryPersister) => {
const predicate = persister.takeRestoredDashboardQueryPredicate();
if (!predicate) return;
setTimeout(() => {
void queryClient.invalidateQueries({ type: "active", predicate });
}, 0);
};
export const removeSessionQueryCache = (scope: string | null, storage: Storage | undefined = getSessionStorage()) => {
removeStorageItem(storage, getQueryPersistenceStorageKey(scope));
};
@@ -3,8 +3,9 @@
import type { PropsWithChildren } from "react";
import { useEffect, useMemo, useState } from "react";
import dynamic from "next/dynamic";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { QueryClient } from "@tanstack/react-query";
import { ReactQueryStreamedHydration } from "@tanstack/react-query-next-experimental";
import { PersistQueryClientProvider } from "@tanstack/react-query-persist-client";
import {
createWSClient,
httpBatchStreamLink,
@@ -35,6 +36,14 @@ import { showWarningNotification } from "@homarr/notifications";
import { widgetQueryRefetchIntervals } from "@homarr/widgets/refetch-intervals";
import { getSessionQueryScope, SessionQueryScopeGuard } from "./session-query-scope";
import {
createSessionQueryPersister,
getQueryPersistenceBuster,
queryPersistenceMaxAgeMs,
removeSessionQueryCache,
scheduleRestoredDashboardQueryRefresh,
shouldPersistDashboardQuery,
} from "./query-persistence";
import { createQueryRetry } from "./query-retry";
const DevelopmentTools =
@@ -72,16 +81,22 @@ export function TRPCReactProvider({ children }: PropsWithChildren) {
<SessionQueryScopeGuard
initialScope={initialSessionQueryScope}
currentScope={sessionQueryScope}
onScopeChange={reloadPage}
onScopeChange={() => {
removeSessionQueryCache(initialSessionQueryScope);
reloadPage();
}}
>
<ScopedTRPCReactProvider>{children}</ScopedTRPCReactProvider>
<ScopedTRPCReactProvider sessionQueryScope={initialSessionQueryScope}>{children}</ScopedTRPCReactProvider>
</SessionQueryScopeGuard>
);
}
const reloadPage = () => window.location.reload();
const ScopedTRPCReactProvider = ({ children }: PropsWithChildren) => {
const ScopedTRPCReactProvider = ({
children,
sessionQueryScope,
}: PropsWithChildren<{ sessionQueryScope: string | null }>) => {
const wsClient = useMemo(
() =>
createWSClient({
@@ -137,6 +152,7 @@ const ScopedTRPCReactProvider = ({ children }: PropsWithChildren) => {
});
useEffect(() => () => queryClient.clear(), [queryClient]);
const [queryPersister] = useState(() => createSessionQueryPersister(sessionQueryScope));
const trpcClient = useMemo(() => {
return clientApi.createClient({
@@ -186,10 +202,21 @@ const ScopedTRPCReactProvider = ({ children }: PropsWithChildren) => {
return (
<clientApi.Provider client={trpcClient} queryClient={queryClient}>
<QueryClientProvider client={queryClient}>
<PersistQueryClientProvider
client={queryClient}
persistOptions={{
persister: queryPersister,
maxAge: queryPersistenceMaxAgeMs,
buster: getQueryPersistenceBuster(sessionQueryScope),
dehydrateOptions: { shouldDehydrateQuery: shouldPersistDashboardQuery },
}}
onSuccess={() => {
scheduleRestoredDashboardQueryRefresh(queryClient, queryPersister);
}}
>
<ReactQueryStreamedHydration transformer={superjson}>{children}</ReactQueryStreamedHydration>
{process.env.NODE_ENV === "development" && <DevelopmentTools />}
</QueryClientProvider>
</PersistQueryClientProvider>
</clientApi.Provider>
);
};
@@ -9,6 +9,7 @@ import { useEditMode } from "@homarr/boards/edit-mode";
import { getRepresentativeLayoutWidth } from "@homarr/boards/layout-preview";
import { useI18n } from "@homarr/translation/client";
import { FloatingTip } from "@homarr/ui";
import { WidgetTimeProvider } from "@homarr/widgets/time";
import { BoardAdvancedFocusProvider } from "~/components/board/advanced-focus/context";
import { BoardEmptyState } from "~/components/board/board-empty-state";
@@ -39,7 +40,7 @@ const BoardSelectionGridProvider = ({ children }: PropsWithChildren) => (
</GridEditorRegistryProvider>
);
export const ClientBoard = () => {
export const ClientBoard = ({ initialTimestamp }: { initialTimestamp: number }) => {
const board = useRequiredBoard();
const t = useI18n("board.landmark");
const tPreview = useI18n("board.setting.section.layout.preview");
@@ -155,23 +156,27 @@ export const ClientBoard = () => {
</BoardSelectionGridProvider>
);
if (representativeWidth === null) return content;
if (representativeWidth === null) {
return <WidgetTimeProvider initialTimestamp={initialTimestamp}>{content}</WidgetTimeProvider>;
}
return (
<Stack align="center" gap="xs" p="md" mih="100%">
<Text size="xs" c="dimmed" fw={500}>
{tPreview("editorWidthLabel", { layoutName: currentLayout.name, width: representativeWidth })}
</Text>
<Paper
withBorder
shadow="sm"
radius="md"
w={`min(${representativeWidth}px, calc(100vw - 2rem))`}
mih="calc(100dvh - 8rem)"
style={{ overflow: "hidden" }}
>
{content}
</Paper>
</Stack>
<WidgetTimeProvider initialTimestamp={initialTimestamp}>
<Stack align="center" gap="xs" p="md" mih="100%">
<Text size="xs" c="dimmed" fw={500}>
{tPreview("editorWidthLabel", { layoutName: currentLayout.name, width: representativeWidth })}
</Text>
<Paper
withBorder
shadow="sm"
radius="md"
w={`min(${representativeWidth}px, calc(100vw - 2rem))`}
mih="calc(100dvh - 8rem)"
style={{ overflow: "hidden" }}
>
{content}
</Paper>
</Stack>
</WidgetTimeProvider>
);
};
@@ -96,7 +96,7 @@ export const createBoardContentPage = <TParams extends Record<string, unknown>>(
return (
<HydrationBoundary state={dehydrate(queryClient)}>
<IntegrationProvider integrations={integrations}>
<ClientBoard />
<ClientBoard initialTimestamp={Date.now()} />
</IntegrationProvider>
</HydrationBoundary>
);