Skip to content

armgit / Pulse

Public Imported from GitHub
0

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.

11.3 KB
Raw Blame
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,
  };
}