Skip to content
Python
6.6 KB
Raw Blame
/** One scheduler for every periodic read.
 *
 * Before this module each page opened its own `setInterval`, which produced two
 * problems: the same data surface was polled by several timers (a library read
 * could happen twice per tick from two different effects), and the
 * hidden-tab / backoff / cleanup rules were re-implemented at every call site
 * and drifted.
 *
 * The key is the data surface, not the caller. Two subscribers that name the
 * same key share **one** timer, running at the fastest interval anyone asked
 * for; when the last subscriber leaves, the timer stops. That is what makes
 * "one source per surface" structural rather than a review checklist.
 *
 * No `EventSource`/`WebSocket` and no callback bus: this only de-duplicates and
 * paces polling, which is what the measured experience gate needs (click
 * feedback and page switches are driven by user actions, not by poll cadence).
 */

export type PollKey =
  | "sources"
  | "imports"
  | "incremental-sync"
  | "processing"
  | "memory-library"
  | "memory-detail"
  | "map-library"
  | "conversations"
  | "applications"
  | "calls"
  | "model-profiles"
  | "memory-add-processing"
  | "health";

export interface PollTask {
  key: PollKey;
  intervalMs: number;
  /** Fire-and-forget refresh for a surface only this caller polls. */
  run?(): void | Promise<void>;
  /** Shared read: the scheduler runs this **once per tick** for the key and
   * hands the value to every subscriber's `onValue`. Use this when several
   * pages read the same Core endpoint, so one tick cannot produce two reads. */
  fetch?(): Promise<unknown>;
  onValue?(value: unknown): void;
  /** Skip while the document is hidden. Defaults to true. */
  pauseWhenHidden?: boolean;
}

interface Entry {
  key: PollKey;
  intervalMs: number;
  timer: ReturnType<typeof setTimeout> | null;
  subscribers: Set<PollTask>;
  stopped: boolean;
}

const entries = new Map<PollKey, Entry>();
/** Per-task in-flight guard: a slow reader must not queue ticks on itself. */
const inFlight = new WeakSet<PollTask>();
/** Per-surface guard for the shared `fetch`, so one tick makes one request. */
const sharedInFlight = new Set<PollKey>();

/** Subscribe one caller to a surface. Returns the unsubscribe function. */
export function subscribePoll(task: PollTask): () => void {
  if (typeof window === "undefined") return () => {};
  const entry = entries.get(task.key) ?? {
    key: task.key,
    intervalMs: task.intervalMs,
    timer: null,
    subscribers: new Set<PollTask>(),
    stopped: false,
  };
  entries.set(task.key, entry);
  entry.subscribers.add(task);
  // Fastest subscriber wins: a surface that needs 3s must not be slowed to 12s
  // by another caller that is happy with 12s.
  const previousInterval = entry.intervalMs;
  entry.intervalMs = Math.min(previousInterval, task.intervalMs);
  entry.stopped = false;
  // A pending timer was armed with the old interval. When the faster
  // subscriber arrives (or the fastest one leaves and the interval grows),
  // that timer must be re-armed or the surface keeps the stale cadence.
  if (entry.timer !== null && entry.intervalMs !== previousInterval) {
    clearTimeout(entry.timer);
    entry.timer = null;
  }
  schedule(entry);
  return () => {
    const current = entries.get(task.key);
    if (!current) return;
    current.subscribers.delete(task);
    if (current.subscribers.size > 0) {
      // Recompute from what is left rather than remembering the leaver's value.
      const next = Math.min(
        ...[...current.subscribers].map((item) => item.intervalMs),
      );
      if (next !== current.intervalMs && current.timer !== null) {
        clearTimeout(current.timer);
        current.timer = null;
      }
      current.intervalMs = next;
      schedule(current);
      return;
    }
    current.stopped = true;
    if (current.timer !== null) clearTimeout(current.timer);
    current.timer = null;
    entries.delete(task.key);
  };
}

/** Run every subscriber of one surface once, in registration order. */
export async function pollNow(key: PollKey): Promise<void> {
  const entry = entries.get(key);
  if (!entry) return;
  await runSurface(entry);
}

function schedule(entry: Entry): void {
  if (entry.stopped || entry.timer !== null) return;
  entry.timer = setTimeout(() => {
    entry.timer = null;
    if (entry.stopped) return;
    void tick(entry);
  }, entry.intervalMs);
}

async function tick(entry: Entry): Promise<void> {
  // One tick per surface even if several subscribers exist: they are reading
  // the same data, so running them together is the point of sharing a key.
  const paused = [...entry.subscribers].every(
    (task) => (task.pauseWhenHidden ?? true) && document.hidden,
  );
  if (!paused) await runSurface(entry);
  schedule(entry);
}

async function runSurface(entry: Entry): Promise<void> {
  const tasks = [...entry.subscribers].filter(
    (task) => !((task.pauseWhenHidden ?? true) && document.hidden),
  );
  // Shared read first: several callers reading one endpoint must produce one
  // request per tick, not one per caller. `fetch` is de-duplicated by a single
  // in-flight promise per surface.
  const fetchers = tasks.filter((task) => task.fetch);
  if (fetchers.length > 0 && !sharedInFlight.has(entry.key)) {
    const promise = (async () => {
      try {
        const value = await fetchers[0].fetch?.();
        for (const task of fetchers) {
          try {
            task.onValue?.(value);
          } catch {
            // a subscriber's render error is its own to surface
          }
        }
      } catch {
        // The read failed; each subscriber keeps its last verified state.
      } finally {
        sharedInFlight.delete(entry.key);
      }
    })();
    sharedInFlight.add(entry.key);
    await promise;
  }
  for (const task of tasks) {
    if (!task.run) continue;
    // Each subscriber has its own in-flight guard, so a slow reader only skips
    // its own next turn rather than the whole surface.
    if (inFlight.has(task)) continue;
    inFlight.add(task);
    try {
      await task.run();
    } catch {
      // ignore: the subscriber renders its own error state
    } finally {
      inFlight.delete(task);
    }
  }
}

/** Test seam: number of live timers, so "one timer per surface" is assertable. */
export function scheduledPollCount(): number {
  return [...entries.values()].filter((entry) => entry.timer !== null).length;
}

/** Test seam: drop every entry and timer. */
export function resetPollScheduler(): void {
  for (const entry of entries.values()) {
    if (entry.timer !== null) clearTimeout(entry.timer);
    entry.timer = null;
    entry.stopped = true;
    entry.subscribers.clear();
  }
  entries.clear();
}