@moondeck/station 0.0.0-stage → 1.0.0

package/lib/managed-update-scheduler.ts

@@ -0,0 +1,125 @@
+export const MANAGED_UPDATE_INITIAL_DELAY_MS = 2 * 60_000;
+export const MANAGED_UPDATE_DAILY_DELAY_MS = 24 * 60 * 60_000;
+export const MANAGED_UPDATE_BUSY_RETRY_MS = 10 * 60_000;
+export const MANAGED_UPDATE_FAILURE_RETRY_MS = 15 * 60_000;
+export const MANAGED_UPDATE_MAX_FAILURE_RETRY_MS = 6 * 60 * 60_000;
+export const MANAGED_UPDATE_JITTER_FRACTION = 0.2;
+
+export type ManagedScheduledCheckResult =
+  | "current"
+  | "updated"
+  | "busy"
+  | "not-managed";
+
+export interface ManagedUpdateSchedulerOptions {
+  readonly isIdle: () => boolean;
+  readonly check: () => Promise<ManagedScheduledCheckResult>;
+  readonly onUpdated: () => void;
+  readonly onError?: (error: unknown) => void;
+  readonly random?: () => number;
+  readonly setTimer?: (callback: () => void, delayMs: number) => NodeJS.Timeout;
+  readonly clearTimer?: (timer: NodeJS.Timeout) => void;
+}
+
+/**
+ * Availability-first automatic update loop. It never blocks boot, never even
+ * fetches while a task is active, rechecks idle at activation through the
+ * caller's `check`, and jitters every fleet-wide edge.
+ */
+export class ManagedUpdateScheduler {
+  private timer: NodeJS.Timeout | null = null;
+  private running = false;
+  private stopped = false;
+  private pendingRestart = false;
+  private failureCount = 0;
+  private readonly random: () => number;
+  private readonly setTimer: NonNullable<ManagedUpdateSchedulerOptions["setTimer"]>;
+  private readonly clearTimer: NonNullable<ManagedUpdateSchedulerOptions["clearTimer"]>;
+
+  constructor(private readonly options: ManagedUpdateSchedulerOptions) {
+    this.random = options.random ?? Math.random;
+    this.setTimer = options.setTimer ?? ((callback, delayMs) => setTimeout(callback, delayMs));
+    this.clearTimer = options.clearTimer ?? clearTimeout;
+  }
+
+  start(): void {
+    if (this.stopped || this.timer || this.running) return;
+    this.schedule(MANAGED_UPDATE_INITIAL_DELAY_MS);
+  }
+
+  stop(): void {
+    this.stopped = true;
+    if (this.timer) this.clearTimer(this.timer);
+    this.timer = null;
+  }
+
+  private schedule(baseDelayMs: number): void {
+    if (this.stopped) return;
+    const delay = jitterDelay(baseDelayMs, this.random());
+    this.timer = this.setTimer(() => {
+      this.timer = null;
+      void this.run();
+    }, delay);
+    this.timer.unref?.();
+  }
+
+  private async run(): Promise<void> {
+    if (this.stopped || this.running) return;
+    this.running = true;
+    try {
+      if (!this.options.isIdle()) {
+        this.schedule(MANAGED_UPDATE_BUSY_RETRY_MS);
+        return;
+      }
+      if (this.pendingRestart) {
+        this.stop();
+        this.options.onUpdated();
+        return;
+      }
+      const result = await this.options.check();
+      if (this.stopped) return;
+      if (result === "updated") {
+        this.pendingRestart = true;
+        // Work may have appeared while the network/extraction pass awaited.
+        // This second synchronous check is immediately adjacent to the
+        // synchronous shutdown request, leaving no event-loop race between.
+        if (this.options.isIdle()) {
+          this.stop();
+          this.options.onUpdated();
+        } else {
+          this.schedule(MANAGED_UPDATE_BUSY_RETRY_MS);
+        }
+        return;
+      }
+      if (result === "not-managed") {
+        this.stop();
+        return;
+      }
+      this.failureCount = 0;
+      this.schedule(
+        result === "busy"
+          ? MANAGED_UPDATE_BUSY_RETRY_MS
+          : MANAGED_UPDATE_DAILY_DELAY_MS,
+      );
+    } catch (error) {
+      this.options.onError?.(error);
+      const backoff = Math.min(
+        MANAGED_UPDATE_FAILURE_RETRY_MS * 2 ** this.failureCount,
+        MANAGED_UPDATE_MAX_FAILURE_RETRY_MS,
+      );
+      this.failureCount += 1;
+      this.schedule(backoff);
+    } finally {
+      this.running = false;
+    }
+  }
+}
+
+export function jitterDelay(baseDelayMs: number, random: number): number {
+  if (!Number.isFinite(random) || random < 0 || random > 1) {
+    throw new Error("managed update jitter source must be between 0 and 1");
+  }
+  const factor = 1 - MANAGED_UPDATE_JITTER_FRACTION +
+    2 * MANAGED_UPDATE_JITTER_FRACTION * random;
+  return Math.round(baseDelayMs * factor);
+}