@gmickel/gno 1.34.5 → 1.35.0

package/src/serve/watch-service-state.ts

@@ -0,0 +1,146 @@
+/**
+ * Per-collection pending queues, caps, and flush scheduling helpers.
+ *
+ * @module src/serve/watch-service-state
+ */
+
+import {
+  WATCHER_MAX_DIRTY_HINTS,
+  WATCHER_MAX_EXACT_PATHS,
+  WATCHER_MAX_FLUSH_DELAY_MS,
+  WATCHER_FLUSH_DEBOUNCE_MS,
+  addToCappedSet,
+} from "./watch-reconciliation";
+
+export interface CollectionPending {
+  exact: Set<string>;
+  dirty: Set<string>;
+  /** When true, dirty overflow forced a root-wide fallback hint. */
+  overflow: boolean;
+  /**
+   * Ambiguous work arrived before snapshot readiness for this generation.
+   * Classification must use store/disk fallback so baseline absorption cannot
+   * suppress content-hash of present eligible finals.
+   */
+  forceFallback: boolean;
+  /**
+   * Config-generation full reconcile failed or was interrupted; next flush must
+   * retry even if exact/dirty event hints are exhausted.
+   */
+  generationReconcile: boolean;
+}
+
+export function emptyPending(): CollectionPending {
+  return {
+    exact: new Set(),
+    dirty: new Set(),
+    overflow: false,
+    forceFallback: false,
+    generationReconcile: false,
+  };
+}
+
+export function pendingHasWork(
+  pending: CollectionPending | undefined
+): boolean {
+  return Boolean(
+    pending &&
+    (pending.exact.size > 0 ||
+      pending.dirty.size > 0 ||
+      pending.generationReconcile)
+  );
+}
+
+export function queueExactPath(
+  pending: CollectionPending,
+  relPath: string,
+  maxExact: number = WATCHER_MAX_EXACT_PATHS
+): CollectionPending {
+  const result = addToCappedSet(pending.exact, relPath, maxExact);
+  if (result === "overflow") {
+    pending.overflow = true;
+    pending.dirty.add("");
+  }
+  return pending;
+}
+
+export function queueDirtyHint(
+  pending: CollectionPending,
+  hint: string,
+  maxDirty: number = WATCHER_MAX_DIRTY_HINTS
+): CollectionPending {
+  const result = addToCappedSet(pending.dirty, hint, maxDirty);
+  if (result === "overflow") {
+    pending.overflow = true;
+    pending.dirty.clear();
+    pending.dirty.add("");
+  }
+  return pending;
+}
+
+/** Flags that must survive take → failed flush → requeue. */
+export interface PendingForceFlags {
+  forceFallback: boolean;
+  overflow: boolean;
+}
+
+/** Drain pending work for one flush attempt. */
+export function takePending(pending: CollectionPending): {
+  exact: string[];
+  dirty: string[];
+  forceFallback: boolean;
+  overflow: boolean;
+  generationReconcile: boolean;
+} {
+  return {
+    exact: [...pending.exact],
+    dirty: pending.overflow ? ["", ...pending.dirty] : [...pending.dirty],
+    forceFallback: pending.forceFallback || pending.overflow,
+    overflow: pending.overflow,
+    generationReconcile: pending.generationReconcile,
+  };
+}
+
+/** Restore durable force flags after a failed classification/sync attempt. */
+export function applyPendingForceFlags(
+  pending: CollectionPending,
+  flags: PendingForceFlags | undefined
+): CollectionPending {
+  if (!flags) {
+    return pending;
+  }
+  if (flags.forceFallback) {
+    pending.forceFallback = true;
+  }
+  if (flags.overflow) {
+    pending.overflow = true;
+    pending.dirty.add("");
+  }
+  return pending;
+}
+
+export interface FlushSchedule {
+  delayMs: number;
+  deadlineAt: number;
+}
+
+/**
+ * Compute debounce delay respecting the hard maximum flush deadline.
+ * `deadlineAt` is created on the first event of a window and retained until drain.
+ */
+export function computeFlushDelay(options: {
+  nowMs: number;
+  existingDeadlineAt: number | undefined;
+  debounceMs?: number;
+  maxFlushDelayMs?: number;
+}): FlushSchedule {
+  const debounceMs = options.debounceMs ?? WATCHER_FLUSH_DEBOUNCE_MS;
+  const maxFlushDelayMs = options.maxFlushDelayMs ?? WATCHER_MAX_FLUSH_DELAY_MS;
+  const deadlineAt =
+    options.existingDeadlineAt ?? options.nowMs + maxFlushDelayMs;
+  const untilDeadline = Math.max(0, deadlineAt - options.nowMs);
+  return {
+    delayMs: Math.min(debounceMs, untilDeadline),
+    deadlineAt,
+  };
+}