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

package/src/server/process-error-telemetry.ts

@@ -0,0 +1,174 @@
+// Reports the server process's own uncaught errors as review_client_error,
+// through the same cleaner, allowlist and per-session budget as every other
+// client error.
+//
+// Whether an uncaught error is fatal depends on the host. The Desktop utility
+// process runs behind VS Code's bootstrap-fork, which installs uncaughtException
+// and unhandledRejection handlers that log and keep the process up. Headless
+// runs as plain Node, where both exit. This module never adds a handler that
+// would change that: it observes through uncaughtExceptionMonitor, and watches
+// rejections only when something already handles them.
+//
+// A fatal error exits before any network send can finish, so it is written to a
+// file synchronously and sent by the next server start.
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { readFile, rm } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  type JsonObject,
+  type JsonValue,
+  parseJsonText,
+} from "@dev.fast/review-protocol";
+import { mergeErrorTelemetryProperties } from "@review/error-telemetry";
+import { devReviewHome } from "@review/review-home-paths";
+import { sanitizeUiTelemetryEvent } from "@review/ui-telemetry-events";
+
+import {
+  type ReviewTelemetryCapture,
+  admitUiTelemetryEvent,
+} from "./ui-telemetry";
+
+type ErrorTelemetry = Pick<ReviewTelemetryCapture, "captureUiEvent">;
+
+/** The slice of `process` this module uses; tests pass an EventEmitter. */
+type ProcessErrorEvents = Pick<
+  NodeJS.EventEmitter,
+  "on" | "off" | "listenerCount"
+>;
+
+export function serverCrashReportPath(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return path.join(devReviewHome(env), "telemetry", "server-crash.json");
+}
+
+export function installProcessErrorTelemetry(
+  telemetry: ErrorTelemetry,
+  options: {
+    process?: ProcessErrorEvents;
+    appSessionId?: string;
+    crashReportPath?: string;
+  } = {},
+): () => void {
+  const target = options.process ?? process;
+  const crashReportPath = options.crashReportPath ?? serverCrashReportPath();
+
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- process event boundary
+  const onUncaught = (cause: unknown) => {
+    const properties = serverErrorProperties(
+      toError(cause),
+      options.appSessionId,
+    );
+
+    // With no uncaughtException handler Node exits once the monitors return.
+    if (target.listenerCount("uncaughtException") === 0)
+      writeCrashReport(crashReportPath, properties);
+    else void sendServerError(telemetry, properties);
+  };
+
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- process event boundary
+  const onRejection = (cause: unknown) => {
+    void sendServerError(
+      telemetry,
+      serverErrorProperties(toError(cause), options.appSessionId),
+    );
+  };
+
+  // A first unhandledRejection listener would stop Node from throwing
+  // unhandled rejections. Without one they arrive at the monitor instead.
+  const watchRejections = target.listenerCount("unhandledRejection") > 0;
+
+  target.on("uncaughtExceptionMonitor", onUncaught);
+
+  if (watchRejections) target.on("unhandledRejection", onRejection);
+
+  return () => {
+    target.off("uncaughtExceptionMonitor", onUncaught);
+
+    if (watchRejections) target.off("unhandledRejection", onRejection);
+  };
+}
+
+/** Sends, once, the fatal error an earlier server process left behind. */
+export async function drainServerCrashReport(
+  telemetry: ErrorTelemetry,
+  crashReportPath: string = serverCrashReportPath(),
+): Promise<void> {
+  let properties: JsonValue;
+
+  try {
+    const text = await readFile(crashReportPath, "utf8");
+    await rm(crashReportPath, { force: true });
+    properties = parseJsonText(text);
+  } catch {
+    return;
+  }
+
+  await sendServerError(telemetry, properties);
+}
+
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- process event boundary
+function toError(cause: unknown): Error {
+  return cause instanceof Error ? cause : new Error(String(cause));
+}
+
+function serverErrorProperties(error: Error, appSessionId?: string) {
+  const properties: JsonObject = {
+    error_source: "server_unexpected",
+    error_process: "server",
+    error_name: error.name,
+  };
+
+  if (appSessionId) properties.app_session_id = appSessionId;
+
+  return mergeErrorTelemetryProperties(properties, {
+    name: error.name,
+    message: error.message,
+    stack: error.stack ?? "",
+  });
+}
+
+function writeCrashReport(
+  crashReportPath: string,
+  properties: JsonObject,
+): void {
+  // Only what the allowlist accepts is written, so the file holds nothing
+  // that could not have been sent.
+  const sanitized = sanitizeUiTelemetryEvent({
+    name: "client_error",
+    properties,
+  });
+
+  if (!sanitized) return;
+
+  try {
+    mkdirSync(path.dirname(crashReportPath), { recursive: true });
+    writeFileSync(crashReportPath, JSON.stringify(sanitized.properties), {
+      mode: 0o600,
+    });
+  } catch {
+    // The process is exiting; there is nowhere left to report this.
+  }
+}
+
+async function sendServerError(
+  telemetry: ErrorTelemetry,
+  properties: JsonValue,
+): Promise<void> {
+  const sanitized = sanitizeUiTelemetryEvent({
+    name: "client_error",
+    properties,
+  });
+
+  const admitted = sanitized ? admitUiTelemetryEvent(sanitized) : undefined;
+
+  if (!admitted) return;
+
+  try {
+    await telemetry.captureUiEvent?.(admitted.event, admitted.properties);
+  } catch {
+    // Telemetry must never add a second error to the one being reported.
+  }
+}

package/src/server/review-api-parsers.ts

@@ -0,0 +1,90 @@
+import {
+  type JsonValue,
+  ReviewBugReportRequestSchema,
+  parseZod,
+} from "@dev.fast/review-protocol";
+import type { ReviewTabTelemetryEvent } from "@review/telemetry";
+import { REVIEW_TELEMETRY_TABS } from "@review/ui-telemetry-events";
+import { z } from "zod";
+
+import { HttpJsonError } from "./http-json";
+
+const MIN_REVIEW_TAB_DWELL_MS = 250;
+
+const MAX_REVIEW_TAB_DWELL_MS = 4 * 60 * 60 * 1_000;
+
+const APP_SESSION_ID_PATTERN = /^[A-Za-z0-9_-][A-Za-z0-9_.-]{15,127}$/;
+
+const MAX_BUG_REPORT_DESCRIPTION_BYTES = 64 * 1024;
+
+const MAX_BUG_REPORT_SCREENSHOT_BYTES = 3 * 1024 * 1024;
+
+export function parseReviewBugReportInput(value: JsonValue) {
+  const parsed = ReviewBugReportRequestSchema.parse(value);
+
+  if (
+    Buffer.byteLength(parsed.description, "utf8") >
+    MAX_BUG_REPORT_DESCRIPTION_BYTES
+  ) {
+    throw new HttpJsonError(
+      `description must not exceed ${MAX_BUG_REPORT_DESCRIPTION_BYTES} UTF-8 bytes`,
+      413,
+    );
+  }
+
+  if (parsed.screenshot) {
+    const screenshot = Buffer.from(parsed.screenshot.base64, "base64");
+
+    if (screenshot.toString("base64") !== parsed.screenshot.base64) {
+      throw new HttpJsonError("screenshot.base64 must be valid base64", 400);
+    }
+
+    if (screenshot.byteLength > MAX_BUG_REPORT_SCREENSHOT_BYTES) {
+      throw new HttpJsonError(
+        `screenshot must not exceed ${MAX_BUG_REPORT_SCREENSHOT_BYTES} decoded bytes`,
+        413,
+      );
+    }
+  }
+
+  return parsed;
+}
+
+export const ReviewTabTelemetryInputSchema = z
+  .strictObject({
+    tab: z.enum(REVIEW_TELEMETRY_TABS, {
+      error: "must be review, commits, map, files, or trace",
+    }),
+    reason: z.enum(["tab_change", "visibility_hidden", "pagehide", "unmount"], {
+      error: "must be tab_change, visibility_hidden, pagehide, or unmount",
+    }),
+    duration_ms: z
+      .number()
+      .int("must be an integer from 250ms to 4h")
+      .min(MIN_REVIEW_TAB_DWELL_MS, "must be an integer from 250ms to 4h")
+      .max(MAX_REVIEW_TAB_DWELL_MS, "must be an integer from 250ms to 4h"),
+    app_session_id: z
+      .string()
+      .regex(APP_SESSION_ID_PATTERN, "must be a valid session id"),
+    document: z.unknown().optional(),
+  })
+  .transform((event) => ({
+    tab: event.tab,
+    reason: event.reason,
+    durationMs: event.duration_ms,
+    appSessionId: event.app_session_id,
+  }));
+
+export function requestJsonErrorStatus(cause: unknown): number {
+  return cause instanceof HttpJsonError ? cause.statusCode : 400;
+}
+
+export function parseReviewTabTelemetryInput(
+  value: JsonValue,
+): ReviewTabTelemetryEvent {
+  return parseZod(
+    ReviewTabTelemetryInputSchema,
+    value,
+    "Review tab telemetry event",
+  );
+}

package/src/server/review-lifecycle-telemetry.ts

@@ -0,0 +1,73 @@
+import type { PostHogCaptureProperties } from "@review/posthog-capture-client";
+import type { ReviewApiHooks } from "@review/review-api/http.js";
+import type {
+  ReviewSessionAgent,
+  ReviewTelemetry,
+} from "@review/review-telemetry";
+
+/**
+ * Review created, published and revoked, and agent authoring completed, as
+ * server events. Authoring is complete at the first publish of a review an
+ * agent created through `whiteboard api` or `whiteboard mcp`, timed from the review's
+ * creation. Which reviews an agent created is known only to this process, so
+ * a server restart between create and publish loses that one completion.
+ * Sign-in reports its funnel, and a success calls `onLoggedIn`.
+ */
+export function reviewLifecycleTelemetry(
+  telemetry: Pick<ReviewTelemetry, "captureEvent">,
+  firstCreatedAt: (reviewId: string) => string | undefined,
+  onLoggedIn: () => Promise<void>,
+  now: () => number = Date.now,
+): ReviewApiHooks {
+  const reported = new Set<string>();
+  const authoring = new Map<string, ReviewSessionAgent | undefined>();
+
+  const capture = (
+    event: string,
+    properties?: PostHogCaptureProperties,
+    reviewUuid?: string,
+  ) =>
+    void telemetry.captureEvent(
+      event,
+      properties,
+      reviewUuid ? { reviewUuid } : undefined,
+    );
+
+  return {
+    onReviewCreated: ({ reviewId, kind, blocks, via, agentKind }) => {
+      if (reported.has(reviewId)) return;
+      reported.add(reviewId);
+
+      if (via === "api" || via === "mcp") authoring.set(reviewId, agentKind);
+      const properties: PostHogCaptureProperties = { kind, blocks, via };
+
+      if (agentKind) properties.agent_kind = agentKind;
+      capture("review_review_created", properties, reviewId);
+    },
+    sharing: {
+      onPublished: ({ reviewId, version }) => {
+        capture("review_review_published", { version }, reviewId);
+
+        if (!authoring.has(reviewId)) return;
+        const agentKind = authoring.get(reviewId);
+        authoring.delete(reviewId);
+        const createdAt = Date.parse(firstCreatedAt(reviewId) ?? "");
+
+        if (Number.isNaN(createdAt)) return;
+
+        const properties: PostHogCaptureProperties = {
+          duration_ms: Math.max(0, now() - createdAt),
+        };
+
+        if (agentKind) properties.agent_kind = agentKind;
+        capture("review_authoring_completed", properties, reviewId);
+      },
+      onRevoked: () => capture("review_review_revoked"),
+      onLogin: (outcome, reason) => {
+        capture(`review_login_${outcome}`, reason ? { reason } : {});
+
+        if (outcome === "succeeded") void onLoggedIn();
+      },
+    },
+  };
+}

package/src/server/review-open-watchdog.ts

@@ -0,0 +1,46 @@
+const OPEN_TIMEOUT_MS = 30_000;
+
+export interface ReviewOpenContext {
+  reviewUuid: string;
+  presentationSessionId: string;
+}
+
+/**
+ * "Opened but never presented" as an explicit event: one timer per
+ * presentation from its session start, cleared when the canvas reports it
+ * presented or the session ends. Keyed by presentation because a resume starts
+ * a new session for the same review.
+ */
+export class ReviewOpenWatchdog {
+  private readonly pending = new Map<string, ReturnType<typeof setTimeout>>();
+
+  constructor(
+    private readonly options: {
+      onTimeout: (context: ReviewOpenContext, elapsedMs: number) => void;
+    },
+  ) {}
+
+  started(context: ReviewOpenContext): void {
+    const id = context.presentationSessionId;
+    this.presented(id);
+    const startedAt = Date.now();
+
+    const timer = setTimeout(() => {
+      this.pending.delete(id);
+      this.options.onTimeout(context, Date.now() - startedAt);
+    }, OPEN_TIMEOUT_MS);
+
+    timer.unref?.();
+    this.pending.set(id, timer);
+  }
+
+  presented(presentationSessionId: string): void {
+    clearTimeout(this.pending.get(presentationSessionId));
+    this.pending.delete(presentationSessionId);
+  }
+
+  dispose(): void {
+    for (const timer of this.pending.values()) clearTimeout(timer);
+    this.pending.clear();
+  }
+}

package/src/server/review-server-core.ts

@@ -0,0 +1,290 @@
+import type { JsonObject } from "@dev.fast/json";
+import type {
+  ReviewServerHealth,
+  ReviewServerHealthWithToken,
+} from "@dev.fast/review-protocol";
+import { traceMachineEnabled } from "@dev.fast/trace-core";
+import { detectAskAgents, launchAskAgent } from "@review/ask/agents.js";
+import { AskThreads, type AskTools } from "@review/ask/threads.js";
+import {
+  readBuildCommit,
+  readReviewPackageVersion,
+} from "@review/package-paths.js";
+import { ReviewInputError } from "@review/review-api/document.js";
+import {
+  type AuthoringCapabilities,
+  type ReviewApiHooks,
+  createReviewApi,
+} from "@review/review-api/http.js";
+import type { LocalReviewData } from "@review/review-api/local-data.js";
+import type { ReviewStore } from "@review/review-api/store.js";
+import { mountSharingPublisher } from "@review/sharing/host.js";
+import type { SharedReviewStore } from "@review/sharing/import.js";
+import { type Context, Hono } from "hono";
+import { streamSSE } from "hono/streaming";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import { z } from "zod";
+
+import type { ReviewDesktopVerbRelay } from "./global-verb-relay";
+import {
+  type ReviewHonoEnv,
+  applyCorsHeaders,
+  corsPreflightResponse,
+  isAuthorizedRequest,
+  jsonResponse,
+  readBoundedRequestJson,
+} from "./hono-http";
+import { HttpJsonError, ReviewServerError } from "./http-json";
+
+const version = readReviewPackageVersion(import.meta.url);
+
+const commit = readBuildCommit(import.meta.url);
+
+/**
+ * What every review server shares: CORS, an open /health, token auth, and
+ * the /control relay a Desktop attaches to, with errors answered as JSON.
+ * Callers add their routes after.
+ */
+export function createReviewServerApp(input: {
+  token: string;
+  instanceId: string;
+  /** The review store's `serverId()`. */
+  serverId: string;
+  relay: ReviewDesktopVerbRelay;
+}): Hono<ReviewHonoEnv> {
+  const app = new Hono<ReviewHonoEnv>();
+  app.use("*", async (context, next) => {
+    await next();
+    applyCorsHeaders(context.req.raw, context.res);
+  });
+  app.options("*", (context) => corsPreflightResponse(context.req.raw));
+  // Open to any caller, but the stable ids only to one holding the token.
+  app.get("/health", (context) => {
+    const health: ReviewServerHealth = {
+      ok: true,
+      instanceId: input.instanceId,
+      desktopAttached: input.relay.attached,
+      version,
+    };
+
+    return serverJson(
+      200,
+      isAuthorizedRequest(context.req.raw, input.token)
+        ? ({
+            ...health,
+            serverId: input.serverId,
+            serverPid: process.pid,
+            commit,
+          } satisfies ReviewServerHealthWithToken)
+        : health,
+    );
+  });
+  app.use("*", async (context, next) => {
+    if (!isAuthorizedRequest(context.req.raw, input.token)) {
+      return serverJson(401, { ok: false, error: "Unauthorized" });
+    }
+
+    await next();
+  });
+  app.get("/control", (context) => openControlEvents(context, input.relay));
+  app.post("/control/result", async (context) => {
+    const accepted = input.relay.acceptResult(
+      await readBoundedRequestJson(context.req.raw),
+    );
+
+    return serverJson(accepted ? 200 : 404, { ok: accepted });
+  });
+  app.notFound(() => serverJson(404, { ok: false, error: "Not found." }));
+  app.onError((error) => {
+    const serverError = error instanceof ReviewServerError ? error : undefined;
+
+    const message = toError(error).message;
+
+    return serverJson(
+      serverError?.statusCode ?? httpJsonStatus(error),
+      serverError?.code
+        ? { ok: false, code: serverError.code, error: message }
+        : { ok: false, error: message },
+    );
+  });
+
+  return app;
+}
+
+export interface WhiteboardCoreInput {
+  profile: {
+    store: ReviewStore;
+    data: LocalReviewData;
+    shared?: SharedReviewStore;
+  };
+  relay: ReviewDesktopVerbRelay;
+  token: string;
+  instanceId: string;
+  softwareMapEnabled?: boolean;
+  scratchpad: () => boolean;
+  status: () => JsonObject;
+  hooks?: ReviewApiHooks;
+  ask?: { tools: AskTools };
+}
+
+export function createWhiteboardCore(input: WhiteboardCoreInput) {
+  const { store, data, shared } = input.profile;
+
+  const app = createReviewServerApp({
+    token: input.token,
+    instanceId: input.instanceId,
+    serverId: store.serverId(),
+    relay: input.relay,
+  });
+
+  const callbacks = relayReviewCallbacks(input.relay, input.softwareMapEnabled);
+
+  const askThreads =
+    input.ask && new AskThreads(launchAskAgent, input.ask.tools);
+
+  const api = createReviewApi(
+    store,
+    data,
+    callbacks.open,
+    shared,
+    callbacks.capabilities,
+    input.scratchpad,
+    () => traceMachineEnabled(),
+    input.status,
+    input.hooks,
+    askThreads && { threads: askThreads, agents: () => detectAskAgents() },
+  );
+
+  // A shared store mounts the publisher with the rest of sharing.
+  if (!shared) mountSharingPublisher(api, store, data);
+
+  return { app, api, close: () => askThreads?.closeAll() };
+}
+
+/** The Desktop callbacks `createReviewApi` takes, answered over the relay. */
+export function relayReviewCallbacks(
+  relay: ReviewDesktopVerbRelay,
+  softwareMapEnabled = false,
+) {
+  return {
+    async open(review: {
+      reviewId: string;
+      title: string;
+    }): Promise<{ softwareMapEnabled: boolean }> {
+      const result = await relay.dispatch({
+        name: "openApiReview",
+        args: review,
+      });
+
+      if (!result.ok) throw new ReviewInputError(result.error, 409);
+
+      return z.object({ softwareMapEnabled: z.boolean() }).parse(result.result);
+    },
+    async capabilities(): Promise<
+      Omit<AuthoringCapabilities, "scratchpadEnabled">
+    > {
+      if (!relay.attached)
+        return { desktopAvailable: false, softwareMapEnabled };
+
+      const result = await relay.dispatch({
+        name: "authoringCapabilities",
+        args: {},
+      });
+
+      if (!result.ok) throw new ReviewInputError(result.error, 409);
+
+      return {
+        desktopAvailable: true,
+        ...z.object({ softwareMapEnabled: z.boolean() }).parse(result.result),
+      };
+    },
+  };
+}
+
+function openControlEvents(
+  context: Context<ReviewHonoEnv>,
+  relay: ReviewDesktopVerbRelay,
+): Response {
+  let attached = false;
+
+  const response = streamSSE(context, async (output) => {
+    let finish!: () => void;
+
+    const disconnected = new Promise<void>((resolve) => {
+      finish = resolve;
+    });
+
+    const abort = new AbortController();
+
+    let pending: Promise<void> = output
+      .write(": attached\n\n")
+      .then(() => undefined);
+
+    const writer = {
+      signal: abort.signal,
+      write(frame: string) {
+        pending = pending.then(async () => {
+          await output.write(frame);
+        });
+      },
+      close() {
+        finish();
+        void output.close();
+      },
+    };
+
+    output.onAbort(() => {
+      abort.abort();
+      finish();
+    });
+    attached = relay.attach(writer);
+
+    if (!attached) {
+      finish();
+
+      return;
+    }
+
+    try {
+      await disconnected;
+      await pending;
+    } finally {
+      abort.abort();
+    }
+  });
+
+  if (!attached) {
+    void response.body?.cancel();
+
+    // A new Response: one built on the stream's context would keep its
+    // chunked framing beside a Content-Length.
+    return serverJson(409, {
+      ok: false,
+      error: "This server has no room for another Whiteboard Desktop.",
+    });
+  }
+
+  // Never reused: a kept-alive socket would hold shutdown open after the
+  // relay ends the stream.
+  response.headers.set("connection", "close");
+  response.headers.set("cache-control", "no-cache, no-transform");
+  response.headers.set("content-type", "text/event-stream; charset=utf-8");
+
+  return response;
+}
+
+export function serverJson<T>(status: number, body: T): Response {
+  // SAFETY: callers pass 2xx/4xx/5xx codes (literals, ReviewServerError and
+  // HttpJsonError statusCode); none is a bodyless 1xx/204/205/304 status.
+  return jsonResponse(body, status as ContentfulStatusCode, {
+    cacheControl: "no-store",
+  });
+}
+
+function httpJsonStatus(cause: unknown): number {
+  return cause instanceof HttpJsonError ? cause.statusCode : 400;
+}
+
+function toError(cause: unknown): Error {
+  return cause instanceof Error ? cause : new Error(String(cause));
+}