Skip to content
Python
4.6 KB
Raw Blame
import { Buffer } from "node:buffer";

const DEFAULT_EVENT_BUDGET = 1024 * 1024;

export interface WatchRead<T> {
  instanceId?: string;
  value: T;
}

export interface WatchEvent<T = unknown> {
  schema_version: 1;
  event: "status" | "progress";
  sequence: number;
  observed_at: string;
  instance_id?: string;
  state?: "unavailable" | "untrusted";
  code?: string;
  data?: T;
  expected_instance_id?: string;
  actual_instance_id?: string;
}

export type WatchResult =
  | { state: "complete" | "cancelled"; events: number }
  | { state: "failed"; code: string; events: number };

/**
 * Serial polling only: the next read starts after the current read and the
 * interval have both completed. A failed read emits a current failure event,
 * never the previous value. Identity drift is terminal because snapshots from
 * two data instances cannot be one timeline.
 */
export async function runWatchLoop<T>(options: {
  kind: "status" | "progress";
  intervalMs: number;
  signal: AbortSignal;
  read(signal: AbortSignal): Promise<WatchRead<T>>;
  emit(event: WatchEvent<T>): void;
  maxEvents?: number;
  maxEventBytes?: number;
  wait?: (milliseconds: number, signal: AbortSignal) => Promise<void>;
  now?: () => string;
}): Promise<WatchResult> {
  const maxEvents = options.maxEvents ?? Number.POSITIVE_INFINITY;
  const maxEventBytes = options.maxEventBytes ?? DEFAULT_EVENT_BUDGET;
  const wait = options.wait ?? abortableWait;
  const now = options.now ?? (() => new Date().toISOString());
  let emitted = 0;
  let expectedInstanceId: string | undefined;

  while (emitted < maxEvents) {
    if (options.signal.aborted) return { state: "cancelled", events: emitted };
    const sequence = emitted + 1;
    let snapshot: WatchRead<T>;
    try {
      snapshot = await options.read(options.signal);
    } catch {
      if (options.signal.aborted)
        return { state: "cancelled", events: emitted };
      const event: WatchEvent<T> = {
        schema_version: 1,
        event: options.kind,
        sequence,
        observed_at: now(),
        state: "unavailable",
        code: "watch_read_failed",
      };
      options.emit(event);
      emitted += 1;
      if (emitted >= maxEvents) break;
      if (!(await waitForNext(wait, options.intervalMs, options.signal))) {
        return { state: "cancelled", events: emitted };
      }
      continue;
    }

    if (
      expectedInstanceId !== undefined &&
      snapshot.instanceId !== undefined &&
      snapshot.instanceId !== expectedInstanceId
    ) {
      options.emit({
        schema_version: 1,
        event: options.kind,
        sequence,
        observed_at: now(),
        state: "untrusted",
        code: "watch_instance_changed",
        expected_instance_id: expectedInstanceId,
        actual_instance_id: snapshot.instanceId,
      });
      return {
        state: "failed",
        code: "watch_instance_changed",
        events: emitted + 1,
      };
    }
    expectedInstanceId ??= snapshot.instanceId;
    const event: WatchEvent<T> = {
      schema_version: 1,
      event: options.kind,
      sequence,
      observed_at: now(),
      ...(snapshot.instanceId ? { instance_id: snapshot.instanceId } : {}),
      data: snapshot.value,
    };
    if (Buffer.byteLength(JSON.stringify(event), "utf8") > maxEventBytes) {
      options.emit({
        schema_version: 1,
        event: options.kind,
        sequence,
        observed_at: now(),
        state: "unavailable",
        code: "watch_event_too_large",
      });
      return {
        state: "failed",
        code: "watch_event_too_large",
        events: emitted + 1,
      };
    }
    options.emit(event);
    emitted += 1;
    if (emitted >= maxEvents) break;
    if (!(await waitForNext(wait, options.intervalMs, options.signal))) {
      return { state: "cancelled", events: emitted };
    }
  }
  return { state: "complete", events: emitted };
}

async function waitForNext(
  wait: (milliseconds: number, signal: AbortSignal) => Promise<void>,
  milliseconds: number,
  signal: AbortSignal,
): Promise<boolean> {
  try {
    await wait(milliseconds, signal);
    return !signal.aborted;
  } catch {
    return false;
  }
}

function abortableWait(
  milliseconds: number,
  signal: AbortSignal,
): Promise<void> {
  return new Promise((resolve, reject) => {
    if (signal.aborted) {
      reject(new DOMException("aborted", "AbortError"));
      return;
    }
    const onAbort = () => {
      clearTimeout(timer);
      reject(new DOMException("aborted", "AbortError"));
    };
    const timer = setTimeout(() => {
      signal.removeEventListener("abort", onAbort);
      resolve();
    }, milliseconds);
    signal.addEventListener("abort", onAbort, { once: true });
  });
}