@dev.fast/whiteboard 0.2.5-preview.20261013.113 → 0.2.5-preview.20261015.115

package/src/server/review-gateway-hosts.ts

@@ -0,0 +1,379 @@
+import {
+  type REVIEW_REMOTE_INSTALL_STEPS,
+  type ReviewGatewayHost,
+  type ReviewGatewayHostState,
+} from "@dev.fast/review-protocol";
+import { Agent } from "undici";
+import { z } from "zod";
+
+import {
+  FIRST_RETRY_MS,
+  MAX_RETRY_MS,
+  errorText,
+  jitter,
+  readBody,
+  send,
+} from "./review-gateway-transport.js";
+
+const HEALTH_TIMEOUT_MS = 3_000;
+
+const HEARTBEAT_MS = 10_000;
+
+const INSTALLS = new Set<ReviewGatewayHostState["state"]>([
+  "incompatible",
+  "not-installed",
+]);
+
+const INSTALL_STEPS: Record<
+  (typeof REVIEW_REMOTE_INSTALL_STEPS)[number],
+  string
+> = {
+  preparing: "Preparing to install Whiteboard",
+  "waiting-for-lock": "Waiting for another install to finish",
+  package: "Installing the Whiteboard package",
+  done: "Installed; starting the server",
+};
+
+const healthSchema = z.object({
+  ok: z.literal(true),
+  serverId: z.string().optional(),
+  version: z.string(),
+});
+
+export interface GatewayRemote {
+  readonly alias: string;
+  readonly endpoint?: { url: string; token: string };
+  readonly dispatcher?: Agent;
+  readonly serverId?: string;
+  readonly unauthorized?: () => void;
+}
+
+interface Host extends GatewayRemote {
+  endpoint?: { url: string; token: string };
+  dispatcher?: Agent;
+  unauthorized?: () => void;
+  problem?: ReviewGatewayHost["problem"];
+  languageFeatures?: boolean;
+  languageFeaturesDetail?: string;
+  languageGroups?: ReviewGatewayHost["languageGroups"];
+  installing?: ReviewGatewayHost["installing"];
+  declined?: true;
+  asking?: string;
+  installFailure?: string;
+  target?: ReviewGatewayHost["target"];
+  serverId?: string;
+  status: ReviewGatewayHostState["state"];
+  detail?: string;
+  retryMs: number;
+  retry?: NodeJS.Timeout;
+  checking?: AbortController;
+}
+
+export function createGatewayHosts(input: {
+  version: string;
+  log?(message: string): void;
+  machine?(serverId: string, alias: string): void;
+  changed?(): void;
+  restarted?(alias: string): void;
+  heartbeatMs?: number;
+}) {
+  const log = input.log ?? (() => {});
+  let hosts: Host[] = [];
+  let closed = false;
+  const reported = new Map<string, string>();
+
+  const sharing = (host: Host) =>
+    host.serverId === undefined
+      ? [host]
+      : hosts.filter((other) => other.serverId === host.serverId);
+
+  const serving = (serverId: string | undefined) =>
+    serverId === undefined
+      ? undefined
+      : hosts.find(
+          (host) =>
+            host.status === "online" &&
+            host.serverId === serverId &&
+            sharing(host).length === 1,
+        );
+
+  function stateOf(host: Host): ReviewGatewayHostState {
+    const known = {
+      alias: host.alias,
+      ...(host.serverId !== undefined && { serverId: host.serverId }),
+    };
+
+    const aliases = sharing(host).map((other) => other.alias);
+
+    if (aliases.length > 1)
+      return {
+        ...known,
+        state: "duplicate",
+        detail: `${aliases.join(", ")} report the same server id, so Whiteboard uses none of them. If they are one machine, keep one alias. If they are separate machines, run \`whiteboard server stop\` and then \`whiteboard server reset-id\` on all but one.`,
+      };
+
+    const detail =
+      host.status === "incompatible" && host.installFailure
+        ? `${host.detail ? `${host.detail} ` : ""}${host.installFailure}`
+        : host.detail;
+
+    return {
+      ...known,
+      state: host.status,
+      ...(detail !== undefined && { detail }),
+      ...(INSTALLS.has(host.status) &&
+        host.problem?.state !== "incompatible" && {
+          installCommand: [
+            `mkdir -p ~/.dev/whiteboard-remote && rm -rf ~/.dev/whiteboard-remote/whiteboard-remote && curl -fsSL https://install.dev.fast/releases/${input.version}/remote/whiteboard-remote-${input.version}-${host.target ?? "linux-x64"}.tar.xz | tar -xJ -C ~/.dev/whiteboard-remote`,
+            "mkdir -p ~/.local/bin && ln -sf ~/.dev/whiteboard-remote/whiteboard-remote/whiteboard ~/.local/bin/whiteboard",
+          ].join("\n"),
+        }),
+      ...(host.declined &&
+        host.status !== "online" &&
+        host.status !== "connecting" && { declined: true as const }),
+      ...(host.status === "online" && languageOf(host)),
+    };
+  }
+
+  function report() {
+    const states = hosts.map(stateOf);
+
+    for (const host of hosts)
+      if (host.serverId !== undefined && serving(host.serverId) === host)
+        input.machine?.(host.serverId, host.alias);
+
+    for (const state of states) {
+      const line = `${state.state}${state.detail ? ` (${state.detail})` : ""}`;
+
+      if (reported.get(state.alias) === line) continue;
+      reported.set(state.alias, line);
+      log(`Host ${state.alias}: ${line}`);
+    }
+
+    for (const alias of reported.keys())
+      if (!states.some((state) => state.alias === alias))
+        reported.delete(alias);
+
+    input.changed?.();
+  }
+
+  function restartedHost(
+    host: Host,
+    detail = `${host.alias} restarted; attaching again.`,
+  ) {
+    if (closed || !host.endpoint) return;
+    host.endpoint = undefined;
+    clearTimeout(host.retry);
+    host.checking?.abort();
+    host.checking = undefined;
+    host.status = "offline";
+    host.detail = detail;
+    report();
+    input.restarted?.(host.alias);
+  }
+
+  function dispose(host: Host) {
+    clearTimeout(host.retry);
+    host.checking?.abort();
+    host.checking = undefined;
+    void host.dispatcher?.destroy();
+  }
+
+  function create(given: ReviewGatewayHost): Host {
+    const host: Host = {
+      alias: given.alias,
+      status: "connecting",
+      retryMs: FIRST_RETRY_MS,
+      ...languageOf(given),
+      ...(given.target && { target: given.target }),
+    };
+
+    if (given.endpoint) host.endpoint = given.endpoint;
+
+    if (given.declined) host.declined = true;
+
+    if (given.installFailure) host.installFailure = given.installFailure;
+
+    if (given.problem) {
+      host.problem = given.problem;
+      host.status = given.problem.state;
+      host.detail = given.problem.detail;
+    } else if (given.installing && !given.endpoint) {
+      host.installing = given.installing;
+      host.status = "installing";
+      host.detail = `${INSTALL_STEPS[given.installing.step]}.`;
+    } else if (given.asking && !given.endpoint) {
+      host.asking = given.asking;
+      host.detail = `Waiting for an answer: install Whiteboard ${given.asking} on ${given.alias}?`;
+    } else if (!given.endpoint)
+      host.detail = `Waiting for a connection to ${given.alias}.`;
+    else {
+      host.dispatcher = new Agent();
+      host.unauthorized = () => restartedHost(host);
+    }
+
+    return host;
+  }
+
+  function schedule(host: Host, ms: number) {
+    host.retry = setTimeout(() => void check(host), ms);
+    host.retry.unref();
+  }
+
+  function retryLater(host: Host) {
+    schedule(host, jitter(host.retryMs));
+    host.retryMs = Math.min(host.retryMs * 2, MAX_RETRY_MS);
+  }
+
+  async function check(host: Host) {
+    if (closed || !host.endpoint || host.problem) return;
+    clearTimeout(host.retry);
+    host.checking?.abort();
+    const abort = new AbortController();
+    host.checking = abort;
+    const timeout = AbortSignal.timeout(HEALTH_TIMEOUT_MS);
+    let health: z.infer<typeof healthSchema> | undefined;
+    let reason = "it did not answer";
+
+    try {
+      const response = await send(host, {
+        method: "GET",
+        path: "/health",
+        headers: { "x-review-token": host.endpoint.token },
+        signal: AbortSignal.any([abort.signal, timeout]),
+      });
+
+      const parsed = healthSchema.safeParse(
+        JSON.parse((await readBody(response.body, 64 * 1024)).toString()),
+      );
+
+      if (parsed.success) health = parsed.data;
+      else reason = "it did not answer as a Whiteboard server";
+    } catch (error) {
+      if (timeout.aborted)
+        reason = `it did not answer within ${HEALTH_TIMEOUT_MS / 1_000} seconds`;
+      else if (!abort.signal.aborted) reason = errorText(error);
+    }
+
+    if (host.checking !== abort) return;
+    host.checking = undefined;
+
+    // /health leaves out serverId when it refuses the token, as after a restart.
+    if (health && health.serverId === undefined) return restartedHost(host);
+
+    if (!health && host.serverId !== undefined)
+      return restartedHost(
+        host,
+        `${host.alias} is offline: ${reason}; attaching again.`,
+      );
+
+    if (!health) {
+      host.status = "offline";
+      host.detail = `${host.alias} is offline: ${reason}.`;
+      retryLater(host);
+    } else {
+      host.serverId = health.serverId;
+      host.retryMs = FIRST_RETRY_MS;
+
+      if (health.version === "unknown" || health.version !== input.version) {
+        host.status = "incompatible";
+        host.detail = `${host.alias} runs Whiteboard ${health.version}; this Desktop runs ${input.version}. Install Whiteboard ${input.version} on ${host.alias}.`;
+      } else {
+        host.status = "online";
+        host.detail = undefined;
+      }
+
+      schedule(host, input.heartbeatMs ?? HEARTBEAT_MS);
+    }
+
+    report();
+  }
+
+  return {
+    set(list: ReviewGatewayHost[]) {
+      const previous = new Map(hosts.map((host) => [host.alias, host]));
+      const next: Host[] = [];
+      const changed: Host[] = [];
+
+      for (const given of list) {
+        if (next.some((host) => host.alias === given.alias)) continue;
+        const current = previous.get(given.alias);
+
+        if (
+          current &&
+          JSON.stringify([
+            current.endpoint,
+            current.problem,
+            current.installing,
+            current.declined,
+            current.asking,
+            current.installFailure,
+          ]) ===
+            JSON.stringify([
+              given.endpoint,
+              given.problem,
+              given.installing,
+              given.declined,
+              given.asking,
+              given.installFailure,
+            ])
+        ) {
+          previous.delete(given.alias);
+          current.languageFeatures = given.languageFeatures;
+          current.languageFeaturesDetail = given.languageFeaturesDetail;
+          current.languageGroups = given.languageGroups;
+          current.target = given.target;
+          next.push(current);
+        } else {
+          const host = create(given);
+          next.push(host);
+          changed.push(host);
+        }
+      }
+
+      for (const gone of previous.values()) dispose(gone);
+      hosts = next;
+
+      for (const host of changed) void check(host);
+      report();
+    },
+    states: () => hosts.map(stateOf),
+    serving: (serverId: string): GatewayRemote | undefined => serving(serverId),
+    online: (): GatewayRemote[] =>
+      hosts.filter((host) => serving(host.serverId) === host),
+    failed(remote: GatewayRemote, reason: string) {
+      const host = hosts.find((candidate) => candidate === remote);
+
+      if (!host || host.status !== "online") return;
+      host.status = "offline";
+      host.detail = `${host.alias} is offline: ${reason}.`;
+      report();
+      void check(host);
+    },
+    recheck(remote: GatewayRemote) {
+      const host = hosts.find((candidate) => candidate === remote);
+
+      if (host && !host.checking) void check(host);
+    },
+    close() {
+      closed = true;
+
+      for (const host of hosts) dispose(host);
+    },
+  };
+}
+
+export type GatewayHosts = ReturnType<typeof createGatewayHosts>;
+
+const languageOf = ({
+  languageFeatures,
+  languageFeaturesDetail,
+  languageGroups,
+}: Pick<
+  ReviewGatewayHost,
+  "languageFeatures" | "languageFeaturesDetail" | "languageGroups"
+>) => ({
+  ...(languageFeatures !== undefined && { languageFeatures }),
+  ...(languageFeaturesDetail !== undefined && { languageFeaturesDetail }),
+  ...(languageGroups !== undefined && { languageGroups }),
+});

package/src/server/review-gateway-list.ts

@@ -0,0 +1,109 @@
+import {
+  type ReviewApiSummary,
+  type ReviewGatewayHostState,
+  reviewHostStatus,
+} from "@dev.fast/review-protocol";
+
+import { LIST_MODES, type ListMode } from "./review-gateway-memory.js";
+
+export interface ListSource {
+  states: readonly ReviewGatewayHostState[];
+  serving(serverId: string): boolean;
+  serverIdOf(alias: string): string | undefined;
+  list(serverId: string, mode: ListMode): ReviewApiSummary[] | undefined;
+}
+
+function decorate(
+  entry: ReviewApiSummary,
+  state: ReviewGatewayHostState,
+  hostState: NonNullable<ReviewApiSummary["hostState"]>,
+): ReviewApiSummary {
+  const { alias } = state;
+  const online = hostState === "online";
+  const features = online && state.languageFeatures === true;
+
+  const reason = online
+    ? features
+      ? undefined
+      : state.languageFeaturesDetail
+    : reviewHostStatus({
+        alias,
+        state: hostState,
+        detail: hostState === state.state ? state.detail : undefined,
+      }).sentence;
+
+  return {
+    ...entry,
+    ...(entry.repositoryGroup && {
+      repositoryGroup: {
+        key: `${alias}:${entry.repositoryGroup.key}`,
+        label: entry.repositoryGroup.label,
+      },
+    }),
+    host: alias,
+    hostState,
+    available: {
+      sourceWindows: features,
+      ...(reason && { reason }),
+    },
+  };
+}
+
+const hostStateOf = (
+  state: ReviewGatewayHostState,
+  serving: boolean,
+): NonNullable<ReviewApiSummary["hostState"]> => {
+  if (serving) return "online";
+
+  return state.state === "online" || state.state === "duplicate"
+    ? "offline"
+    : state.state;
+};
+
+// Settings order, one entry per server: the first to list an id owns it.
+function* servers(source: ListSource) {
+  const seen = new Set<string>();
+
+  for (const state of source.states) {
+    const serverId = state.serverId ?? source.serverIdOf(state.alias);
+
+    if (serverId === undefined || seen.has(serverId)) continue;
+    seen.add(serverId);
+    yield { state, serverId };
+  }
+}
+
+export function listedBy(reviewId: string, source: ListSource) {
+  for (const server of servers(source))
+    if (
+      LIST_MODES.some((mode) =>
+        source
+          .list(server.serverId, mode)
+          ?.some((entry) => entry.reviewId === reviewId),
+      )
+    )
+      return server;
+
+  return undefined;
+}
+
+export function mergeLists(
+  mode: ListMode,
+  local: readonly ReviewApiSummary[],
+  source: ListSource,
+) {
+  const ids = new Set(local.map((entry) => entry.reviewId));
+  const merged = [...local];
+
+  for (const { state, serverId } of servers(source)) {
+    const hostState = hostStateOf(state, source.serving(serverId));
+
+    for (const entry of source.list(serverId, mode) ?? [])
+      if (!ids.has(entry.reviewId)) {
+        ids.add(entry.reviewId);
+        merged.push(decorate(entry, state, hostState));
+      }
+  }
+
+  return merged;
+}

package/src/server/review-gateway-memory.ts

@@ -0,0 +1,130 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+import type { ReviewApiSummary } from "@dev.fast/review-protocol";
+import { errorMessage, writePrivateJsonAtomic } from "@dev.fast/trace-core";
+import { z } from "zod";
+
+export const LIST_MODES = ["structural", "textual"] as const;
+
+export type ListMode = (typeof LIST_MODES)[number];
+
+export const UUID =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+const listEntrySchema = z.looseObject({
+  reviewId: z.string().regex(UUID),
+  version: z.number(),
+  title: z.string(),
+  createdAt: z.string(),
+  repositoryName: z.string(),
+  viewedAt: z.string().nullable(),
+  trashedAt: z.string().nullable(),
+  repositoryGroup: z.object({ key: z.string(), label: z.string() }).optional(),
+});
+
+export const listEntriesSchema = z.array(z.unknown()).transform(
+  (entries) =>
+    // SAFETY: the schema checks the fields the gateway and Home rely on.
+    entries.filter(
+      (entry) => listEntrySchema.safeParse(entry).success,
+    ) as ReviewApiSummary[],
+);
+
+const lastListSchema = z.object({
+  structural: listEntriesSchema.optional(),
+  textual: listEntriesSchema.optional(),
+});
+
+const memorySchema = z.record(
+  z.string(),
+  z.object({ alias: z.string(), lastList: lastListSchema.optional() }),
+);
+
+interface Server {
+  alias: string;
+  lastList: Partial<Record<ListMode, ReviewApiSummary[]>>;
+}
+
+export function gatewayMemoryPath(home: string) {
+  return path.join(home, "remotes.json");
+}
+
+export function openGatewayMemory(
+  home: string,
+  log: (message: string) => void = () => {},
+) {
+  const file = gatewayMemoryPath(home);
+  const servers = new Map<string, Server>();
+
+  try {
+    const saved = memorySchema.parse(JSON.parse(readFileSync(file, "utf8")));
+
+    for (const [serverId, { alias, lastList }] of Object.entries(saved))
+      servers.set(serverId, { alias, lastList: lastList ?? {} });
+  } catch (error) {
+    // SAFETY: fs rejects with a Node ErrnoException carrying `code`.
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT")
+      log(`Ignoring unreadable remote review memory ${file}: ${String(error)}`);
+  }
+
+  let writing = Promise.resolve();
+  let queued = false;
+
+  const save = () => {
+    if (queued) return;
+    queued = true;
+
+    writing = writing
+      .then(() => {
+        queued = false;
+
+        return writePrivateJsonAtomic(file, Object.fromEntries(servers));
+      })
+      .catch((cause: unknown) =>
+        log(`Could not save remote review memory: ${errorMessage(cause)}`),
+      );
+  };
+
+  return {
+    serverIdOf(alias: string) {
+      for (const [serverId, server] of servers)
+        if (server.alias === alias) return serverId;
+
+      return undefined;
+    },
+    list: (serverId: string, mode: ListMode) =>
+      servers.get(serverId)?.lastList[mode],
+    setList(
+      serverId: string,
+      alias: string,
+      mode: ListMode,
+      reviews: ReviewApiSummary[],
+    ) {
+      let server = servers.get(serverId);
+
+      if (!server) {
+        server = { alias, lastList: {} };
+        servers.set(serverId, server);
+      } else if (
+        server.alias === alias &&
+        JSON.stringify(server.lastList[mode]) === JSON.stringify(reviews)
+      )
+        return;
+
+      server.alias = alias;
+      server.lastList[mode] = reviews;
+      save();
+    },
+    rename(serverId: string, alias: string) {
+      const server = servers.get(serverId);
+
+      if (!server || server.alias === alias) return;
+      server.alias = alias;
+      save();
+    },
+    flush: () => writing,
+  };
+}
+
+export type GatewayMemory = ReturnType<typeof openGatewayMemory>;