@reviewflow/sdk 0.0.0-stage → 6.22.0

package/src/reviewflow/follow.ts

@@ -0,0 +1,345 @@
+import type { PullRequestChange } from "../api/pullRequest.ts";
+import { accountOfOwnerRepo } from "./board.ts";
+import { changedPullRequestParts } from "./changedParts.ts";
+import type {
+  ReviewflowClient,
+  ReviewflowGroup,
+  ReviewflowPrDetail,
+} from "./client.ts";
+import { isReviewflowFailure } from "./client.ts";
+import type { ReviewflowStreamEvent } from "./stream.ts";
+
+/**
+ * reviewflow's stream, followed while someone looks: open while at least one
+ * watcher is connected, closed `lingerMs` after the last one leaves. A stream
+ * nobody watches holds one of the live connections reviewflow allows per user
+ * and in total.
+ *
+ * Storage is the caller's: the follower reports what it learned through
+ * callbacks, and all it keeps is what the lifecycle needs.
+ */
+
+export const lingerMs = 5 * 60_000;
+export const boardReadDelayMs = 3000;
+export const reconnectDelayMs = 1000;
+const minRetryMs = 2000;
+export const maxRetryMs = 5 * 60_000;
+
+export type ReviewflowStreamState = "connecting" | "error" | "live" | "off";
+
+export interface ReviewflowConnection {
+  client: Pick<ReviewflowClient, "board">;
+  events: (signal: AbortSignal) => AsyncIterable<ReviewflowStreamEvent>;
+}
+
+export interface ReviewflowFollower {
+  /** whether anyone is watching */
+  setWatched: (watched: boolean) => void;
+  /** the token changed: the open stream is the old token's */
+  restart: () => void;
+  state: () => ReviewflowStreamState;
+  close: () => void;
+}
+
+export interface ReviewflowFollowerLog {
+  level: "error" | "info" | "warn";
+  message: string;
+  /** the thrown value itself, for a caller that serializes its stack */
+  error?: unknown;
+  /** what the message is about, without the error */
+  fields?: Record<string, unknown>;
+}
+
+export interface CreateReviewflowFollowerParams {
+  /** null without a token; read again at each connection */
+  connect: () => ReviewflowConnection | null;
+  /** the accounts whose board is read, as the caller spells them */
+  accounts: () => string[];
+  /** the scope the stream sent before `ready`, then each later `pr` */
+  onPr: (pr: ReviewflowPrDetail, phase: "change" | "scope") => void;
+  onPrRemoved: (id: string) => void;
+  /** an account's board was read again */
+  onAccountBoard: (account: string, groups: ReviewflowGroup[]) => void;
+  onBoardError?: (account: string, message: string) => void;
+  /** parts of a pull request's screen went stale */
+  onPullRequestChanged?: (change: PullRequestChange) => void;
+  onStateChanged?: (state: ReviewflowStreamState, error: string | null) => void;
+  /** the stream connected, failed or ended; for a log */
+  onLog?: (entry: ReviewflowFollowerLog) => void;
+}
+
+const messageOf = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+const retryDelayMs = (error: unknown, failures: number): number => {
+  if (isReviewflowFailure(error)) {
+    if (error.retryAfterMs !== undefined) return error.retryAfterMs;
+    // a revoked token stays revoked until another is stored: `restart`
+    if (error.status === 401) return maxRetryMs;
+  }
+  return Math.min(minRetryMs * 2 ** (failures - 1), maxRetryMs);
+};
+
+const wait = async (ms: number, signal: AbortSignal): Promise<void> =>
+  new Promise((resolve) => {
+    const done = (): void => {
+      // oxlint-disable-next-line no-use-before-define
+      clearTimeout(timer);
+      signal.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal.addEventListener("abort", done, { once: true });
+  });
+
+interface BoardRead {
+  timer?: ReturnType<typeof setTimeout>;
+  inFlight: boolean;
+  again: boolean;
+}
+
+export const createReviewflowFollower = ({
+  connect,
+  accounts,
+  onPr,
+  onPrRemoved,
+  onAccountBoard,
+  onBoardError,
+  onPullRequestChanged,
+  onStateChanged,
+  onLog,
+}: CreateReviewflowFollowerParams): ReviewflowFollower => {
+  let watched = false;
+  let state: ReviewflowStreamState = "off";
+  let controller: AbortController | null = null;
+  let linger: ReturnType<typeof setTimeout> | undefined;
+  const boardReads = new Map<string, BoardRead>();
+  /** which account a pull request is from, for a `prRemoved` that only names it */
+  const accountOfPr = new Map<string, string>();
+  /** kept across connections: a scope sent anew reports what changed meanwhile */
+  const lastSeen = new Map<string, ReviewflowPrDetail>();
+
+  const setState = (next: ReviewflowStreamState, error?: string): void => {
+    if (state === next && error === undefined) return;
+    state = next;
+    onStateChanged?.(next, error ?? null);
+  };
+
+  const comparePr = (pr: ReviewflowPrDetail): void => {
+    const previous = lastSeen.get(pr.id);
+    lastSeen.set(pr.id, pr);
+    if (previous === undefined || onPullRequestChanged === undefined) return;
+    const parts = changedPullRequestParts(previous, pr);
+    if (parts.length === 0) return;
+    onPullRequestChanged({ ownerRepo: pr.ownerRepo, number: pr.number, parts });
+  };
+
+  const linked = (account: string): string | undefined =>
+    accounts().find((owner) => owner.toLowerCase() === account.toLowerCase());
+
+  /** true when an event arrived during the read, whose answer may predate it */
+  const readBoard = async (
+    connection: ReviewflowConnection,
+    account: string,
+    signal: AbortSignal,
+  ): Promise<boolean> => {
+    const read = boardReads.get(account);
+    if (read === undefined || signal.aborted) return false;
+    read.timer = undefined;
+    read.inFlight = true;
+    read.again = false;
+    try {
+      const groups = await connection.client.board(account);
+      if (signal.aborted) return false;
+      onAccountBoard(account, groups);
+    } catch (error) {
+      if (signal.aborted) return false;
+      onBoardError?.(account, messageOf(error));
+    } finally {
+      read.inFlight = false;
+    }
+    return read.again;
+  };
+
+  const scheduleBoard = (
+    connection: ReviewflowConnection,
+    account: string,
+    signal: AbortSignal,
+  ): void => {
+    const owner = linked(account);
+    if (owner === undefined) return;
+    const read = boardReads.get(owner) ?? { inFlight: false, again: false };
+    boardReads.set(owner, read);
+    if (read.inFlight) {
+      read.again = true;
+      return;
+    }
+    read.timer ??= setTimeout(() => {
+      readBoard(connection, owner, signal)
+        .then((again) => {
+          if (again) scheduleBoard(connection, owner, signal);
+        })
+        .catch((error: unknown) => {
+          onLog?.({
+            level: "warn",
+            message: "reviewflow board read failed",
+            error,
+          });
+        });
+    }, boardReadDelayMs);
+  };
+
+  const scheduleEveryBoard = (
+    connection: ReviewflowConnection,
+    signal: AbortSignal,
+  ): void => {
+    for (const owner of accounts()) scheduleBoard(connection, owner, signal);
+  };
+
+  /**
+   * Returns when the server ends the stream, telling whether it got as far as
+   * `ready`; throws when it fails.
+   */
+  const follow = async (
+    connection: ReviewflowConnection,
+    signal: AbortSignal,
+    onReady: () => void,
+  ): Promise<boolean> => {
+    const scope: ReviewflowPrDetail[] = [];
+    let ready = false;
+    for await (const event of connection.events(signal)) {
+      if (event.type === "end") {
+        onLog?.({
+          level: "info",
+          message: "reviewflow ended the stream",
+          fields: { reason: event.reason },
+        });
+        // a reset or a scope change: what the board holds may be stale
+        scheduleEveryBoard(connection, signal);
+        return ready;
+      }
+      if (event.type === "ready") {
+        ready = true;
+        onReady();
+        onLog?.({
+          level: "info",
+          message: "reviewflow stream ready",
+          fields: { prs: scope.length },
+        });
+        for (const pr of scope.splice(0)) onPr(pr, "scope");
+        setState("live");
+        scheduleEveryBoard(connection, signal);
+      } else if (event.type === "pr") {
+        accountOfPr.set(event.pr.id, accountOfOwnerRepo(event.pr.ownerRepo));
+        comparePr(event.pr);
+        if (ready) {
+          onPr(event.pr, "change");
+          scheduleBoard(
+            connection,
+            accountOfOwnerRepo(event.pr.ownerRepo),
+            signal,
+          );
+        } else {
+          scope.push(event.pr);
+        }
+      } else if (ready) {
+        const account = accountOfPr.get(event.id);
+        accountOfPr.delete(event.id);
+        lastSeen.delete(event.id);
+        onPrRemoved(event.id);
+        if (account === undefined) scheduleEveryBoard(connection, signal);
+        else scheduleBoard(connection, account, signal);
+      }
+    }
+    return ready;
+  };
+
+  const run = async (signal: AbortSignal): Promise<void> => {
+    let failures = 0;
+    const resetFailures = (): void => {
+      failures = 0;
+    };
+    while (!signal.aborted) {
+      const connection = connect();
+      if (connection === null) {
+        setState("off");
+        return;
+      }
+      let delayMs = reconnectDelayMs;
+      setState("connecting");
+      try {
+        const reachedReady = await follow(connection, signal, resetFailures);
+        if (!reachedReady && !signal.aborted) {
+          failures++;
+          delayMs = retryDelayMs(undefined, failures);
+          onLog?.({
+            level: "warn",
+            message: "reviewflow ended the stream before it was ready",
+            fields: { retryInMs: delayMs },
+          });
+        }
+      } catch (error) {
+        if (signal.aborted) return;
+        failures++;
+        delayMs = retryDelayMs(error, failures);
+        onLog?.({
+          level: "warn",
+          message: "reviewflow stream failed",
+          error,
+          fields: { retryInMs: delayMs },
+        });
+        setState("error", messageOf(error));
+      }
+      if (state === "live") setState("connecting");
+      await wait(delayMs, signal);
+    }
+  };
+
+  const stop = (): void => {
+    controller?.abort();
+    controller = null;
+    for (const read of boardReads.values()) clearTimeout(read.timer);
+    boardReads.clear();
+    accountOfPr.clear();
+    setState("off");
+  };
+
+  const start = (): void => {
+    if (controller !== null) return;
+    const current = new AbortController();
+    controller = current;
+    run(current.signal)
+      .catch((error: unknown) => {
+        onLog?.({
+          level: "error",
+          message: "reviewflow stream stopped",
+          error,
+        });
+      })
+      .finally(() => {
+        if (controller === current) controller = null;
+      });
+  };
+
+  return {
+    setWatched: (value) => {
+      watched = value;
+      clearTimeout(linger);
+      linger = undefined;
+      if (value) start();
+      else if (controller !== null) linger = setTimeout(stop, lingerMs);
+    },
+    restart: () => {
+      const wasOpen = controller !== null;
+      stop();
+      lastSeen.clear();
+      if (watched || wasOpen) start();
+    },
+    state: () => state,
+    close: () => {
+      watched = false;
+      clearTimeout(linger);
+      stop();
+    },
+  };
+};

package/src/reviewflow/status.ts

@@ -0,0 +1,17 @@
+/**
+ * How a client of the reviewflow API stands: whether a token is held, whose it
+ * is, and whether the live stream is followed. Carries no token material by
+ * construction, so it can be sent to a page and logged.
+ */
+export interface ReviewflowConnectionStatus {
+  configured: boolean;
+  /** the reviewflow server, e.g. `https://reviewflow.example.com` */
+  url: string | null;
+  /** the GitHub login the token belongs to, as of the last verification */
+  login: string | null;
+  /** the accounts the token reads, as of the last verification */
+  accounts: string[];
+  stream: "connecting" | "error" | "live" | "off";
+  /** why the credentials are unreadable or the stream failed; never the token */
+  error: string | null;
+}

package/src/reviewflow/stream.ts

@@ -0,0 +1,199 @@
+import type { ReviewflowPrDetail } from "./client.ts";
+import {
+  fail,
+  isReviewflowFailure,
+  readPrDetail,
+  responseFailure,
+} from "./client.ts";
+
+/**
+ * `GET /api/stream/v1` (`reviewflow/docs/api.md`): every pull request in the
+ * reader's scope as `pr` events, then `ready`, then each change as the whole
+ * pull request again. There is no resume: a reconnection sends the scope anew.
+ */
+
+/** reviewflow heartbeats every 25s: two missed is a dead connection, a laptop that slept */
+export const streamIdleTimeoutMs = 60_000;
+/**
+ * Pull requests closed while no stream was open still reach the tracked
+ * branches at the next connection, as long as it is within this many days.
+ */
+export const streamClosedWithinDays = 7;
+
+export type ReviewflowStreamEvent =
+  | { type: "end"; reason: string }
+  | { type: "pr"; pr: ReviewflowPrDetail }
+  | { type: "prRemoved"; id: string }
+  | { type: "ready" };
+
+/** Optional sink for what the stream drops; nothing is logged without one. */
+export interface ReviewflowStreamLogger {
+  /** `error` is the thrown value itself, for a caller that serializes its stack */
+  warn: (message: string, context: { error: unknown }) => void;
+}
+
+interface Frame {
+  event: string;
+  data: string;
+}
+
+const parseFrame = (block: string): Frame => {
+  let event = "message";
+  const data: string[] = [];
+  for (const line of block.split("\n")) {
+    if (line.startsWith(":")) continue;
+    const separator = line.indexOf(":");
+    const field = separator === -1 ? line : line.slice(0, separator);
+    const value =
+      separator === -1 ? "" : line.slice(separator + 1).replace(/^ /, "");
+    if (field === "event") event = value;
+    else if (field === "data") data.push(value);
+  }
+  return { event, data: data.join("\n") };
+};
+
+const parseData = (frame: Frame): unknown => {
+  try {
+    return JSON.parse(frame.data) as unknown;
+  } catch {
+    return null;
+  }
+};
+
+/** null for a frame that changes nothing: a heartbeat, an event added later */
+const toStreamEvent = (
+  frame: Frame,
+  logger: ReviewflowStreamLogger | undefined,
+): ReviewflowStreamEvent | null => {
+  switch (frame.event) {
+    case "pr": {
+      try {
+        return { type: "pr", pr: readPrDetail(parseData(frame)) };
+      } catch (error) {
+        // one unreadable pull request must not end the stream for the others
+        logger?.warn(
+          "reviewflow streamed a pull request the client cannot read",
+          { error },
+        );
+        return null;
+      }
+    }
+    case "prRemoved": {
+      const data = parseData(frame) as { _id?: unknown } | null;
+      return typeof data?._id === "string"
+        ? { type: "prRemoved", id: data._id }
+        : null;
+    }
+    case "ready":
+      return { type: "ready" };
+    case "scopeChanged":
+      return { type: "end", reason: "scopeChanged" };
+    case "reset": {
+      const data = parseData(frame) as { reason?: unknown } | null;
+      return {
+        type: "end",
+        reason: `reset: ${typeof data?.reason === "string" ? data.reason : "unknown"}`,
+      };
+    }
+    default:
+      return null;
+  }
+};
+
+interface ReadReviewflowStreamParams {
+  url: string;
+  token: string;
+  signal: AbortSignal;
+  /** injected by tests: nothing in the suite reaches the network */
+  fetch?: typeof globalThis.fetch;
+  idleTimeoutMs?: number;
+  logger?: ReviewflowStreamLogger;
+}
+
+/**
+ * Yields until the server ends the stream (`end`, or the body closing) and
+ * throws on a refusal or a connection gone silent, so the caller decides when
+ * to connect again. Aborting `signal` ends it quietly.
+ */
+export async function* readReviewflowStream({
+  url,
+  token,
+  signal,
+  fetch = globalThis.fetch,
+  idleTimeoutMs = streamIdleTimeoutMs,
+  logger,
+}: ReadReviewflowStreamParams): AsyncGenerator<ReviewflowStreamEvent> {
+  const controller = new AbortController();
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  // the body is cancelled too: a dead socket does not always reject a read
+  const cancel = (): void => {
+    controller.abort();
+    reader?.cancel().catch(() => undefined);
+  };
+  signal.addEventListener("abort", cancel, { once: true });
+  let silent = false;
+  let idle: ReturnType<typeof setTimeout> | undefined;
+  const armIdle = (): void => {
+    clearTimeout(idle);
+    idle = setTimeout(() => {
+      silent = true;
+      cancel();
+    }, idleTimeoutMs);
+  };
+  const silence = (): Error =>
+    fail(
+      `reviewflow's stream went silent for ${String(idleTimeoutMs / 1000)}s`,
+    );
+
+  try {
+    armIdle();
+    const query = new URLSearchParams({
+      closedWithinDays: String(streamClosedWithinDays),
+    });
+    const response = await fetch(`${url}/api/stream/v1?${query.toString()}`, {
+      headers: {
+        authorization: `Bearer ${token}`,
+        accept: "text/event-stream",
+      },
+      signal: controller.signal,
+    });
+    if (!response.ok) throw await responseFailure(response);
+    if (response.body === null) {
+      throw fail("reviewflow answered the stream with no body");
+    }
+
+    reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      armIdle();
+      buffer = (buffer + decoder.decode(value, { stream: true })).replaceAll(
+        "\r\n",
+        "\n",
+      );
+      let end = buffer.indexOf("\n\n");
+      while (end !== -1) {
+        const event = toStreamEvent(parseFrame(buffer.slice(0, end)), logger);
+        buffer = buffer.slice(end + 2);
+        if (event !== null) {
+          yield event;
+          if (event.type === "end") return;
+        }
+        end = buffer.indexOf("\n\n");
+      }
+    }
+    if (silent) throw silence();
+  } catch (error) {
+    if (signal.aborted) return;
+    if (silent) throw silence();
+    if (isReviewflowFailure(error)) throw error;
+    const cause = error instanceof Error ? error.message : String(error);
+    throw fail(`reviewflow's stream could not be read at ${url}: ${cause}`);
+  } finally {
+    clearTimeout(idle);
+    signal.removeEventListener("abort", cancel);
+    cancel();
+  }
+}

package/src/types/entities.ts

@@ -0,0 +1,8 @@
+export type PrState = "closed" | "draft" | "merged" | "open";
+export type PrReviewDecision =
+  | "approved"
+  | "changesRequested"
+  | "reviewRequired"
+  | null;
+/** `unknown` while GitHub has not computed it yet, which it does lazily */
+export type PrMergeable = "conflicting" | "mergeable" | "unknown";

package/src/types/ids.ts

@@ -0,0 +1 @@
+export type IsoDateTime = string;

package/src/types/reviewflow.ts

@@ -0,0 +1,32 @@
+export type ReviewflowReviewState =
+  | "approved"
+  | "changesRequested"
+  | "none"
+  | "requested";
+
+export type ReviewflowMergeable = "conflicting" | "mergeable" | "unknown";
+
+/** `unknown` is a pull request with no check at all */
+export type ReviewflowChecksConclusion =
+  | "failed"
+  | "inProgress"
+  | "passed"
+  | "unknown";
+
+/** a link reviewflow resolved on the pull request, a ticket key among them */
+export interface ReviewflowStatusLink {
+  name: string;
+  label: string;
+  url: string;
+}
+
+export interface ReviewflowPrChanges {
+  changedFiles: number;
+  additions: number;
+  deletions: number;
+}
+
+export interface ReviewflowAccount {
+  login: string;
+  type: "Organization" | "User";
+}