Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
import { type Accessor, batch, createEffect, createSignal, onCleanup } from 'solid-js';
import { eventBus } from '@/stores/events';
import { getAPIReadAccessErrorMessage } from '@/utils/apiAccessError';
interface CreateNonSuspendingQueryOptions<T, K> {
source: Accessor<K | null>;
fetcher: (key: K, signal: AbortSignal) => Promise<T>;
initialValue: T;
cacheKey?: (key: K) => string | null;
// A fixed interval, or an accessor when the cadence follows state (polling
// faster while a job runs); an accessor that returns undefined stops polling.
pollMs?: number | Accessor<number | undefined>;
retainPreviousValueOnSourceChange?: boolean;
}
interface QueryRunOptions {
background?: boolean;
}
/**
* Keep query-backed surfaces out of the app-level Suspense boundary by
* retaining the last fulfilled value while the next request is in flight.
*
* This cache is shared across route/drawer remounts, so it needs an explicit
* ownership boundary. In particular, history responses can be large and their
* keys contain resource IDs and time ranges that continually change during a
* long-lived browser session.
*/
const RETAINED_QUERY_CACHE_MAX_ENTRIES = 64;
const RETAINED_QUERY_CACHE_MAX_AGE_MS = 5 * 60_000;
// A poll does not replace a read an earlier poll started while it is still in
// flight: a read slower than the poll interval (the API answers 429 with
// Retry-After: 60, and apiFetch honours up to two minutes) would otherwise be
// discarded on every tick and never settle. Other reads stay replaceable at
// the next tick, so a slow refresh is replaced at most once. Past this age a
// polled read is presumed stalled: the next poll replaces it and reports it as
// a failed read, so a consumer that never loaded shows its error and Retry
// rather than spinning while every read hangs.
export const STALLED_QUERY_READ_MS = 150_000;
type RetainedQueryCacheEntry = {
cachedAt: number;
error: unknown;
resolvedOnce: boolean;
value: unknown;
};
const retainedQueryCache = new Map<string, RetainedQueryCacheEntry>();
let retainedQueryCacheGeneration = 0;
let retainedQueryCacheExpiryTimer: ReturnType<typeof setTimeout> | null = null;
const clearRetainedQueryCacheExpiryTimer = () => {
if (retainedQueryCacheExpiryTimer !== null) {
clearTimeout(retainedQueryCacheExpiryTimer);
retainedQueryCacheExpiryTimer = null;
}
};
const pruneExpiredRetainedQueryEntries = (now = Date.now()) => {
for (const [key, entry] of retainedQueryCache) {
if (now - entry.cachedAt >= RETAINED_QUERY_CACHE_MAX_AGE_MS) {
retainedQueryCache.delete(key);
}
}
};
const scheduleRetainedQueryCacheExpiry = () => {
clearRetainedQueryCacheExpiryTimer();
if (retainedQueryCache.size === 0) {
return;
}
let nextExpiryAt = Number.POSITIVE_INFINITY;
for (const entry of retainedQueryCache.values()) {
nextExpiryAt = Math.min(nextExpiryAt, entry.cachedAt + RETAINED_QUERY_CACHE_MAX_AGE_MS);
}
retainedQueryCacheExpiryTimer = setTimeout(
() => {
retainedQueryCacheExpiryTimer = null;
pruneExpiredRetainedQueryEntries();
scheduleRetainedQueryCacheExpiry();
},
Math.max(0, nextExpiryAt - Date.now()),
);
};
const clearRetainedQueryCache = () => {
retainedQueryCacheGeneration += 1;
retainedQueryCache.clear();
clearRetainedQueryCacheExpiryTimer();
};
const readRetainedQueryCacheEntry = (key: string): RetainedQueryCacheEntry | null => {
const cached = retainedQueryCache.get(key);
if (!cached) {
return null;
}
if (Date.now() - cached.cachedAt >= RETAINED_QUERY_CACHE_MAX_AGE_MS) {
retainedQueryCache.delete(key);
scheduleRetainedQueryCacheExpiry();
return null;
}
// Map insertion order is the LRU order. A cache hit keeps a remounted
// surface's value ahead of older, inactive resource/range combinations.
retainedQueryCache.delete(key);
retainedQueryCache.set(key, cached);
return cached;
};
const writeRetainedQueryCacheEntry = (
key: string,
value: Omit<RetainedQueryCacheEntry, 'cachedAt'>,
) => {
pruneExpiredRetainedQueryEntries();
retainedQueryCache.delete(key);
retainedQueryCache.set(key, {
...value,
cachedAt: Date.now(),
});
while (retainedQueryCache.size > RETAINED_QUERY_CACHE_MAX_ENTRIES) {
const oldestKey = retainedQueryCache.keys().next().value;
if (oldestKey === undefined) {
break;
}
retainedQueryCache.delete(oldestKey);
}
scheduleRetainedQueryCacheExpiry();
};
export function resetCreateNonSuspendingQueryCacheForTest() {
clearRetainedQueryCache();
}
export function getCreateNonSuspendingQueryCacheDiagnosticsForTest() {
pruneExpiredRetainedQueryEntries();
return {
keys: Array.from(retainedQueryCache.keys()),
maxAgeMs: RETAINED_QUERY_CACHE_MAX_AGE_MS,
maxEntries: RETAINED_QUERY_CACHE_MAX_ENTRIES,
size: retainedQueryCache.size,
};
}
const unsubscribeRetainedQueryOrgSwitch = eventBus.on('org_switched', () => {
clearRetainedQueryCache();
});
if (import.meta.hot) {
import.meta.hot.dispose(() => {
unsubscribeRetainedQueryOrgSwitch();
clearRetainedQueryCache();
});
}
export function createNonSuspendingQuery<T, K>(options: CreateNonSuspendingQueryOptions<T, K>) {
const getRetainedCacheKey = (key: K | null): string | null => {
if (key === null || !options.cacheKey) {
return null;
}
return options.cacheKey(key);
};
const readRetainedValue = (key: K | null) => {
const cacheKey = getRetainedCacheKey(key);
if (!cacheKey) {
return null;
}
const cached = readRetainedQueryCacheEntry(cacheKey);
if (!cached) {
return null;
}
return cached as { error: unknown; resolvedOnce: boolean; value: T };
};
const applyRetainedValue = (cached: { error: unknown; resolvedOnce: boolean; value: T }) => {
setValue(() => cached.value);
setError(cached.error);
setResolvedOnce(cached.resolvedOnce);
};
const initialCached = readRetainedValue(options.source());
const [value, setValue] = createSignal<T>(initialCached?.value ?? options.initialValue);
const [loading, setLoading] = createSignal(false);
const [error, setError] = createSignal<unknown>(initialCached?.error ?? null);
const [resolvedOnce, setResolvedOnce] = createSignal(initialCached?.resolvedOnce ?? false);
let latestRequestId = 0;
let activeAbortController: AbortController | null = null;
let activeRequestStartedAt = 0;
let activeRequestIsPoll = false;
const cancelActiveRequest = () => {
activeAbortController?.abort();
activeAbortController = null;
};
const reset = () => {
cancelActiveRequest();
latestRequestId += 1;
setValue(() => options.initialValue);
setLoading(false);
setError(null);
setResolvedOnce(false);
return options.initialValue;
};
const unsubscribeLiveQueryOrgSwitch = eventBus.on('org_switched', () => {
reset();
// reset() only writes signals the source effect does not track, so it
// cannot re-run the query on its own. A consumer with a constant source
// and no polling would otherwise sit empty until it remounted. Refetch
// here, matching every other org-switch handler in the app.
const key = options.source();
if (key === null) {
return;
}
void run(key);
});
onCleanup(unsubscribeLiveQueryOrgSwitch);
const run = async (key: K, runOptions: QueryRunOptions = {}, poll = false): Promise<T> => {
cancelActiveRequest();
const abortController = new AbortController();
activeAbortController = abortController;
activeRequestStartedAt = Date.now();
activeRequestIsPoll = poll;
const requestId = ++latestRequestId;
const retainedCacheKey = getRetainedCacheKey(key);
const cacheGeneration = retainedQueryCacheGeneration;
if (!runOptions.background) {
setLoading(true);
}
try {
const nextValue = await options.fetcher(key, abortController.signal);
if (requestId !== latestRequestId) {
return value();
}
setValue(() => nextValue);
setError(null);
return nextValue;
} catch (nextError) {
if (requestId === latestRequestId) {
batch(() => {
if (getAPIReadAccessErrorMessage(nextError)) {
// A permission/session/plan failure is not a transient outage.
// Withdraw this value and all remount entries: the same access
// context may own other resource/range keys. The generation also
// prevents pre-denial reads from repopulating the shared cache.
clearRetainedQueryCache();
setValue(() => options.initialValue);
}
setError(nextError);
});
}
return value();
} finally {
if (requestId === latestRequestId) {
activeAbortController = null;
setResolvedOnce(true);
if (retainedCacheKey && cacheGeneration === retainedQueryCacheGeneration) {
writeRetainedQueryCacheEntry(retainedCacheKey, {
error: error(),
resolvedOnce: true,
value: value(),
});
}
// A background poll can replace a pending foreground refresh. The
// latest read owns settlement, regardless of how that read started.
setLoading(false);
}
}
};
createEffect(() => {
const key = options.source();
if (key === null) {
reset();
return;
}
const cached = readRetainedValue(key);
if (cached) {
applyRetainedValue(cached);
} else if (options.retainPreviousValueOnSourceChange === false) {
// A retained value is only honest when it belongs to the active source.
// Range-sensitive history consumers opt out of showing the prior range
// while its replacement is loading or has failed.
setValue(() => options.initialValue);
setError(null);
setResolvedOnce(false);
}
void run(key, { background: Boolean(cached) });
});
onCleanup(() => {
cancelActiveRequest();
latestRequestId += 1;
});
const refetch = async (runOptions: QueryRunOptions = {}): Promise<T> => {
const key = options.source();
if (key === null) {
return reset();
}
return run(key, runOptions);
};
const poll = () => {
if (activeAbortController !== null && activeRequestIsPoll) {
if (Date.now() - activeRequestStartedAt < STALLED_QUERY_READ_MS) return;
// The stalled read is abandoned and settles as a failure: its
// replacement runs in the background and may hang too, so nothing
// else would clear a spinner or a never-loaded state.
batch(() => {
setLoading(false);
setError(new Error('The request timed out.'));
setResolvedOnce(true);
});
}
const key = options.source();
if (key === null) {
reset();
return;
}
void run(key, { background: true }, true);
};
const pollMs = options.pollMs;
if (typeof pollMs === 'function') {
// A new cadence restarts the interval. A read already in flight keeps its
// protection, which belongs to the request rather than the timer.
createEffect(() => {
const ms = pollMs();
if (typeof ms !== 'number' || ms <= 0) return;
const interval = setInterval(poll, ms);
onCleanup(() => clearInterval(interval));
});
} else if (typeof pollMs === 'number' && pollMs > 0) {
const interval = setInterval(poll, pollMs);
onCleanup(() => clearInterval(interval));
}
return {
error,
loading,
refetch,
resolvedOnce,
value,
};
}