@dev.fast/whiteboard 0.0.0-stage → 0.2.1-preview.20261005.98

package/src/server/global-verb-relay.ts

@@ -0,0 +1,190 @@
+import crypto from "node:crypto";
+
+import {
+  type JsonValue,
+  type ReviewVerbRequest,
+  type ReviewVerbResponse,
+  parseReviewDesktopVerbResult,
+  parseReviewVerbRequest,
+} from "@dev.fast/review-protocol";
+
+const DEFAULT_VERB_TIMEOUT_MS = 45_000;
+
+const DEFAULT_MAX_CLIENTS = 16;
+
+const NOT_ATTACHED = "No Whiteboard Desktop is attached.";
+
+interface PendingVerb {
+  resolve(response: ReviewVerbResponse): void;
+  timer: ReturnType<typeof setTimeout>;
+  /** The clients yet to answer, by the frame id each was sent. */
+  waiting: Map<string, GlobalReviewDesktopVerbWriter>;
+  lastFailure?: ReviewVerbResponse;
+}
+
+export interface GlobalReviewDesktopVerbWriter {
+  readonly signal: AbortSignal;
+  write(frame: string): void | Promise<void>;
+  close(): void | Promise<void>;
+}
+
+/** The server's view of the desktop relay, so tests can supply their own. */
+export interface ReviewDesktopVerbRelay {
+  readonly attached: boolean;
+  attach(writer: GlobalReviewDesktopVerbWriter): boolean;
+  dispatch(value: JsonValue): Promise<ReviewVerbResponse>;
+  acceptResult(value: JsonValue): boolean;
+  close(): void;
+}
+
+/**
+ * Sends each verb to every attached client, each with its own frame id, and
+ * resolves with the first success, or with the last failure once no client
+ * is left to answer.
+ */
+export class GlobalReviewDesktopVerbRelay implements ReviewDesktopVerbRelay {
+  private readonly clients = new Map<
+    GlobalReviewDesktopVerbWriter,
+    () => void
+  >();
+  /** Each verb in flight, under every frame id it was sent with. */
+  private readonly pending = new Map<string, PendingVerb>();
+  private readonly timeoutMs: number;
+  private readonly maxClients: number;
+
+  constructor(options: { timeoutMs?: number; maxClients?: number } = {}) {
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_VERB_TIMEOUT_MS;
+    this.maxClients = options.maxClients ?? DEFAULT_MAX_CLIENTS;
+  }
+
+  get attached(): boolean {
+    return this.clients.size > 0;
+  }
+
+  attach(writer: GlobalReviewDesktopVerbWriter): boolean {
+    if (
+      this.clients.size >= this.maxClients ||
+      this.clients.has(writer) ||
+      writer.signal.aborted
+    )
+      return false;
+
+    const detach = () => this.detach(writer);
+    this.clients.set(writer, detach);
+    writer.signal.addEventListener("abort", detach, { once: true });
+
+    return true;
+  }
+
+  dispatch(value: JsonValue): Promise<ReviewVerbResponse> {
+    const request: ReviewVerbRequest = parseReviewVerbRequest(value);
+
+    if (this.clients.size === 0) {
+      return Promise.resolve({ ok: false, error: NOT_ATTACHED });
+    }
+
+    return new Promise<ReviewVerbResponse>((resolve) => {
+      const verb: PendingVerb = {
+        resolve,
+        waiting: new Map(
+          [...this.clients.keys()].map((client) => [
+            crypto.randomUUID(),
+            client,
+          ]),
+        ),
+        timer: setTimeout(
+          () =>
+            this.settle(
+              verb,
+              verb.lastFailure ?? {
+                ok: false,
+                error: "Whiteboard Desktop verb timed out.",
+              },
+            ),
+          this.timeoutMs,
+        ),
+      };
+
+      verb.timer.unref?.();
+
+      // Every id is registered before the first write, which may detach its
+      // client at once.
+      for (const id of verb.waiting.keys()) this.pending.set(id, verb);
+
+      for (const [id, client] of [...verb.waiting]) {
+        const frame = `data: ${JSON.stringify({ event: "desktop-verb", id, request })}\n\n`;
+
+        try {
+          void Promise.resolve(client.write(frame)).catch(() => {
+            this.detach(client);
+          });
+        } catch {
+          this.detach(client);
+        }
+      }
+    });
+  }
+
+  acceptResult(value: JsonValue): boolean {
+    const result = parseReviewDesktopVerbResult(value);
+    const verb = this.pending.get(result.id);
+
+    if (!verb) return false;
+
+    if (result.response.ok) {
+      this.settle(verb, result.response);
+    } else {
+      verb.lastFailure = result.response;
+      this.stopWaiting(verb, result.id);
+    }
+
+    return true;
+  }
+
+  close(): void {
+    for (const verb of new Set(this.pending.values())) {
+      this.settle(verb, {
+        ok: false,
+        error: "Whiteboard Desktop relay closed.",
+      });
+    }
+
+    for (const client of [...this.clients.keys()]) {
+      this.detach(client);
+
+      try {
+        void Promise.resolve(client.close()).catch(() => undefined);
+      } catch {
+        // Already closed.
+      }
+    }
+  }
+
+  private detach(writer: GlobalReviewDesktopVerbWriter): void {
+    const listener = this.clients.get(writer);
+
+    if (!listener) return;
+    writer.signal.removeEventListener("abort", listener);
+    this.clients.delete(writer);
+
+    for (const [id, verb] of [...this.pending]) {
+      if (verb.waiting.get(id) === writer) this.stopWaiting(verb, id);
+    }
+  }
+
+  /** Drops one client's id; with nobody left to answer, the verb fails. */
+  private stopWaiting(verb: PendingVerb, id: string): void {
+    verb.waiting.delete(id);
+    this.pending.delete(id);
+
+    if (verb.waiting.size === 0)
+      this.settle(verb, verb.lastFailure ?? { ok: false, error: NOT_ATTACHED });
+  }
+
+  private settle(verb: PendingVerb, response: ReviewVerbResponse): void {
+    for (const id of verb.waiting.keys()) this.pending.delete(id);
+    verb.waiting.clear();
+    clearTimeout(verb.timer);
+    verb.resolve(response);
+  }
+}

package/src/server/headless-host.ts

@@ -0,0 +1,149 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { once } from "node:events";
+import { mkdir, realpath, rm } from "node:fs/promises";
+import { createServer } from "node:http";
+
+import { isObjectValue } from "@dev.fast/json";
+import { withFileLock, writePrivateJsonAtomic } from "@dev.fast/trace-core";
+import { openReviewProfile } from "@review/review-api/profile.js";
+import {
+  type ReviewServerDiscovery,
+  headlessServerLockPath,
+  reviewServerDiscoveryPath,
+} from "@review/server-discovery.js";
+
+import { GlobalReviewDesktopVerbRelay } from "./global-verb-relay.js";
+import { createNodeRequestListener } from "./hono-http.js";
+import {
+  drainServerCrashReport,
+  installProcessErrorTelemetry,
+} from "./process-error-telemetry.js";
+import { createWhiteboardCore } from "./review-server-core.js";
+import type { ReviewTelemetryCapture } from "./ui-telemetry.js";
+
+interface HeadlessServerInput {
+  stateDir: string;
+  port?: number;
+  softwareMapEnabled?: boolean;
+  signal: AbortSignal;
+  /** The CLI's instance, already on the `headless` surface. */
+  telemetry?: Pick<ReviewTelemetryCapture, "captureUiEvent">;
+  onReady(discovery: ReviewServerDiscovery): void;
+}
+
+/** One foreground headless endpoint per profile; Desktop shares its database. */
+export async function runHeadlessServer(input: HeadlessServerInput) {
+  await mkdir(input.stateDir, { recursive: true, mode: 0o700 });
+  const stateDir = await realpath(input.stateDir);
+
+  const stopErrorTelemetry =
+    input.telemetry && installProcessErrorTelemetry(input.telemetry);
+
+  const outcome = await withHeadlessServerLock(stateDir, () =>
+    serve({ ...input, stateDir }),
+  ).finally(() => stopErrorTelemetry?.());
+
+  if (!outcome.acquired)
+    throw new Error(
+      `A Whiteboard server already owns ${stateDir}. Stop it first, or choose another --state-dir.`,
+    );
+}
+
+/** Held by a running server, so also by anything that must not run beside one. */
+export function withHeadlessServerLock<T>(
+  stateDir: string,
+  operation: () => Promise<T>,
+) {
+  return withFileLock(
+    headlessServerLockPath(stateDir),
+    {
+      timeoutMs: 0,
+      retryMs: 20,
+      // A paused live owner must never lose exclusive access to its store.
+      staleMs: Infinity,
+      unownedGraceMs: 1_000,
+      // A reboot or kill can hand the pid to an unrelated live process.
+      identifyOwner: true,
+    },
+    operation,
+  );
+}
+
+async function serve(input: HeadlessServerInput) {
+  if (input.signal.aborted) return;
+
+  if (input.telemetry) await drainServerCrashReport(input.telemetry);
+
+  const local = await openReviewProfile(input.stateDir, {
+    manageWorkspaces: false,
+  });
+
+  const discovery: ReviewServerDiscovery = {
+    version: 1,
+    instanceId: randomUUID(),
+    url: "http://127.0.0.1:0",
+    serverPid: process.pid,
+    token: randomBytes(32).toString("base64url"),
+  };
+
+  const relay = new GlobalReviewDesktopVerbRelay();
+
+  const { app, api } = createWhiteboardCore({
+    profile: local,
+    relay,
+    token: discovery.token,
+    instanceId: discovery.instanceId,
+    softwareMapEnabled: input.softwareMapEnabled,
+    // The scratchpad is the laptop's alone, even with a Desktop attached.
+    scratchpad: () => false,
+    status: () => ({ key: "headless", home: input.stateDir }),
+  });
+
+  app.route("/reviews-api", api);
+
+  const server = createServer(createNodeRequestListener(app));
+  let published = false;
+
+  try {
+    const listening = once(server, "listening");
+    server.listen(input.port ?? 0, "127.0.0.1");
+    await listening;
+    const address = server.address();
+
+    if (!isObjectValue(address))
+      throw new Error("Whiteboard server did not bind a TCP port.");
+    discovery.url = `http://127.0.0.1:${address.port}`;
+    await writePrivateJsonAtomic(
+      reviewServerDiscoveryPath(input.stateDir),
+      discovery,
+    );
+    published = true;
+    input.onReady(discovery);
+
+    await new Promise<void>((resolve) => {
+      if (input.signal.aborted) resolve();
+      else
+        input.signal.addEventListener("abort", () => resolve(), { once: true });
+    });
+  } finally {
+    // Watch streams may live forever. Drain ordinary requests, then bound shutdown.
+    const forceClose = setTimeout(() => server.closeAllConnections(), 5_000);
+    forceClose.unref();
+
+    try {
+      if (published)
+        await rm(reviewServerDiscoveryPath(input.stateDir), { force: true });
+    } finally {
+      // An attached Desktop's stream would otherwise hold the close open.
+      relay.close();
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      clearTimeout(forceClose);
+
+      try {
+        await local.data.close();
+      } finally {
+        await local.store.close();
+      }
+    }
+  }
+}

package/src/server/hono-http.ts

@@ -0,0 +1,162 @@
+import crypto from "node:crypto";
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import { type JsonValue, parseJsonText } from "@dev.fast/review-protocol";
+import { type HttpBindings, getRequestListener } from "@hono/node-server";
+import { REVIEW_APP_SESSION_ID_HEADER } from "@review/ui-telemetry-events";
+import type { Hono } from "hono";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+
+import { StreamLimitError, readBoundedStream } from "./bounded-stream.js";
+import { DEFAULT_MAX_REQUEST_BYTES, HttpJsonError } from "./http-json";
+
+export type ReviewHonoEnv = {
+  Bindings: HttpBindings;
+};
+
+export function createNodeRequestListener(
+  app: Hono<ReviewHonoEnv>,
+): (request: IncomingMessage, response: ServerResponse) => Promise<void> {
+  return getRequestListener(app.fetch);
+}
+
+export function jsonResponse<T>(
+  body: T,
+  status: ContentfulStatusCode,
+  options: {
+    cacheControl?: string;
+    contentType?: string;
+    newline?: boolean;
+  } = {},
+): Response {
+  const headers = new Headers({
+    "content-type": options.contentType ?? "application/json; charset=utf-8",
+  });
+
+  if (options.cacheControl) {
+    headers.set("cache-control", options.cacheControl);
+  }
+
+  const serialized = JSON.stringify(body);
+
+  return new Response(
+    options.newline === false ? serialized : `${serialized}\n`,
+    {
+      status,
+      headers,
+    },
+  );
+}
+
+export function applyCorsHeaders(
+  request: Request,
+  response: Response,
+): Response {
+  const origin = request.headers.get("origin");
+
+  if (origin) {
+    response.headers.set("access-control-allow-origin", origin);
+    const vary = response.headers.get("vary");
+
+    const varyFields = vary
+      ?.split(",")
+      .map((field) => field.trim().toLowerCase());
+
+    if (!varyFields?.includes("*") && !varyFields?.includes("origin")) {
+      response.headers.set("vary", vary ? `${vary}, Origin` : "Origin");
+    }
+  }
+
+  response.headers.set(
+    "access-control-allow-headers",
+    `content-type, x-review-token, ${REVIEW_APP_SESSION_ID_HEADER}`,
+  );
+  response.headers.set(
+    "access-control-allow-methods",
+    "GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS",
+  );
+  response.headers.set("access-control-allow-private-network", "true");
+
+  return response;
+}
+
+export function corsPreflightResponse(request: Request): Response {
+  return applyCorsHeaders(request, new Response(null, { status: 204 }));
+}
+
+export function isAuthorizedRequest(
+  request: Request,
+  expectedToken: string,
+): boolean {
+  const supplied =
+    request.headers.get("x-review-token") ??
+    new URL(request.url).searchParams.get("token");
+
+  if (!supplied) return false;
+  const expected = Buffer.from(expectedToken);
+  const actual = Buffer.from(supplied);
+
+  return (
+    expected.length === actual.length &&
+    crypto.timingSafeEqual(expected, actual)
+  );
+}
+
+export async function readBoundedRequestJson(
+  request: Request,
+  maxBytes = DEFAULT_MAX_REQUEST_BYTES,
+  emptyValue?: JsonValue,
+  options: { allowTextPlain?: boolean } = {},
+): Promise<JsonValue> {
+  assertJsonContentType(request, options);
+  const contentLength = Number(request.headers.get("content-length"));
+
+  if (Number.isFinite(contentLength) && contentLength > maxBytes) {
+    throw requestTooLarge(maxBytes);
+  }
+
+  let body: string;
+
+  try {
+    body = request.body
+      ? (await readBoundedStream(request.body, maxBytes)).toString("utf8")
+      : "";
+  } catch (error) {
+    if (error instanceof StreamLimitError) throw requestTooLarge(maxBytes);
+    throw error;
+  }
+
+  if (!body && emptyValue !== undefined) return emptyValue;
+
+  try {
+    return parseJsonText(body);
+  } catch {
+    throw new HttpJsonError("Invalid JSON body.", 400);
+  }
+}
+
+function assertJsonContentType(
+  request: Request,
+  options: { allowTextPlain?: boolean },
+): void {
+  const mediaType = request.headers
+    .get("content-type")
+    ?.split(";", 1)[0]
+    ?.trim()
+    .toLowerCase();
+
+  if (
+    mediaType !== "application/json" &&
+    !mediaType?.endsWith("+json") &&
+    !(options.allowTextPlain && mediaType === "text/plain")
+  ) {
+    throw new HttpJsonError("Content-Type must be application/json.", 415);
+  }
+}
+
+function requestTooLarge(maxBytes: number): HttpJsonError {
+  return new HttpJsonError(
+    `Request body exceeds ${maxBytes === DEFAULT_MAX_REQUEST_BYTES ? "1 MiB" : `${maxBytes} bytes`}.`,
+    413,
+  );
+}

package/src/server/http-json.ts

@@ -0,0 +1,24 @@
+export const DEFAULT_MAX_REQUEST_BYTES = 1024 * 1024;
+
+export class HttpJsonError extends Error {
+  constructor(
+    message: string,
+    readonly statusCode: 400 | 413 | 415,
+  ) {
+    super(message);
+    this.name = "HttpJsonError";
+  }
+}
+
+/** An error whose status and machine code the JSON routes hand straight back. */
+export class ReviewServerError extends Error {
+  override readonly name = "ReviewServerError";
+
+  constructor(
+    message: string,
+    readonly statusCode: number,
+    readonly code?: string,
+  ) {
+    super(message);
+  }
+}

package/src/server/json-review-reporting.ts

@@ -0,0 +1,174 @@
+import { isJsonObject } from "@dev.fast/review-protocol";
+import {
+  ReviewInputError,
+  resourceReferences,
+} from "@review/review-api/document";
+import { readQuerySchemas } from "@review/review-api/read-schemas";
+import { ReviewStore, type Snapshot } from "@review/review-api/store";
+import { resolveReviewDiffFiles } from "@review/review-diff-files";
+import type { SharedReviewStore } from "@review/sharing/import.js";
+import type { ReviewTelemetry } from "@review/telemetry";
+import { Hono } from "hono";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+
+import {
+  type BugReportSource,
+  BugReportUpstreamError,
+  submitReviewBugReport,
+} from "./bug-report";
+import { readBoundedRequestJson } from "./hono-http";
+import {
+  parseReviewBugReportInput,
+  parseReviewTabTelemetryInput,
+  requestJsonErrorStatus,
+} from "./review-api-parsers";
+import {
+  captureSanitizedUiTelemetry,
+  clientErrorsForSession,
+  recordClientError,
+} from "./ui-telemetry";
+
+export function jsonReviewBugReportSource(
+  store: ReviewStore,
+  snapshot: Snapshot,
+): BugReportSource {
+  return {
+    async review() {
+      return {
+        files: { "review.json": JSON.stringify(snapshot, null, 2) },
+        omitted: [],
+      };
+    },
+    async map() {
+      const ids = [
+        ...new Set(
+          resourceReferences(snapshot.document).flatMap((block) =>
+            block.type === "software_map" ? [block.mapVersionId] : [],
+          ),
+        ),
+      ];
+
+      return ids.length
+        ? JSON.stringify(
+            ids.map((id) =>
+              JSON.parse(Buffer.from(store.resource(id).data).toString()),
+            ),
+          )
+        : null;
+    },
+    async diff() {
+      if (!snapshot.pins) return { files: [] };
+
+      return resolveReviewDiffFiles({
+        rootPath: store.repositoryPath(snapshot.pins.repositoryId),
+        baseRef: snapshot.pins.base,
+        headRef: snapshot.pins.head,
+        includePatch: true,
+      });
+    },
+  };
+}
+
+/** Telemetry and report uploads for a pinned native review. */
+export function createJsonReviewReporting(
+  store: ReviewStore,
+  telemetry: Pick<
+    ReviewTelemetry,
+    "captureUiEvent" | "captureTabViewed" | "envelope"
+  >,
+  options: {
+    submit?: typeof submitReviewBugReport;
+    shared?: SharedReviewStore;
+  } = {},
+) {
+  const { submit = submitReviewBugReport, shared } = options;
+  const app = new Hono();
+  app.onError((error, context) =>
+    context.json(
+      { ok: false, error: error.message },
+      // SAFETY: the report uploader returns HTTP error statuses; parser failures are 4xx.
+      (error instanceof BugReportUpstreamError
+        ? error.status
+        : error instanceof ReviewInputError
+          ? error.status
+          : requestJsonErrorStatus(error)) as ContentfulStatusCode,
+    ),
+  );
+  app.use("/:id/telemetry/*", async (context, next) => {
+    const id = context.req.param("id")!;
+
+    if (id.startsWith("shared-")) {
+      if (!shared)
+        throw new ReviewInputError("Shared review is not available.", 404);
+      shared.get(id);
+    } else store.assertExists(id);
+    await next();
+  });
+  app.post("/:id/telemetry/event", async (c) => {
+    const body = await readBoundedRequestJson(c.req.raw, undefined, {});
+    const payload = isJsonObject(body) ? body : {};
+    const rawContext = isJsonObject(payload.context) ? payload.context : {};
+    await captureSanitizedUiTelemetry(
+      telemetry,
+      c.req.raw,
+      payload.name,
+      payload.properties,
+      recordClientError,
+      payload.error,
+      // The path id wins: the middleware above already asserted it exists,
+      // so a payload trying to assert a different review id is overridden.
+      { ...rawContext, reviewUuid: c.req.param("id") },
+      payload.occurredAt,
+    );
+
+    return c.json({ ok: true });
+  });
+  app.post("/:id/telemetry/tab", async (context) => {
+    const input = await readBoundedRequestJson(
+      context.req.raw,
+      undefined,
+      {},
+      { allowTextPlain: true },
+    );
+
+    await telemetry.captureTabViewed(parseReviewTabTelemetryInput(input), {
+      reviewUuid: context.req.param("id"),
+    });
+
+    return context.json({ ok: true });
+  });
+  app.post("/:id/telemetry/bug-report", async (context) => {
+    const query = readQuerySchemas.get.parse({
+      version: context.req.query("version"),
+    });
+
+    const id = context.req.param("id");
+    const imported = id.startsWith("shared-") ? shared?.get(id) : undefined;
+    const snapshot = imported?.snapshot ?? store.read(id, query.version);
+
+    const report = parseReviewBugReportInput(
+      await readBoundedRequestJson(context.req.raw, 6 * 1024 * 1024, {}),
+    );
+
+    return context.json(
+      await submit({
+        report,
+        source: imported
+          ? {
+              review: async () => ({
+                files: { "review.json": JSON.stringify(snapshot) },
+                omitted: [],
+              }),
+              map: async () => JSON.stringify(imported.presentation.maps),
+              diff: () => jsonReviewBugReportSource(store, snapshot).diff(),
+            }
+          : jsonReviewBugReportSource(store, snapshot),
+        clientErrorNames: clientErrorsForSession(report.app_session_id),
+        // A locked telemetry config must not cost the user their report.
+        telemetryEnvelope: await telemetry.envelope().catch(() => undefined),
+      }),
+    );
+  });
+
+  return app;
+}