@dev.fast/whiteboard 0.0.0-stage → 0.2.0

package/src/server/crash-report.ts

@@ -0,0 +1,273 @@
+import { createHash } from "node:crypto";
+import { readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { gzip } from "node:zlib";
+
+import { ReviewBugReportMetaV2Schema } from "@dev.fast/review-protocol";
+import type { PostHogCaptureProperties } from "@review/posthog-capture-client";
+import type { ReviewTelemetry } from "@review/review-telemetry";
+import { z } from "zod";
+
+const CRASH_REPORT_URL = "https://bug.dev.fast/api/v2/crashes";
+
+const gzipAsync = promisify(gzip);
+
+/** The Worker's limit on the gzip dump it stores. */
+const DEFAULT_MAX_DUMP_BYTES = 50_000_000;
+
+/** Reading a dump this large into memory is not worth it; it can never fit. */
+const MAX_RAW_DUMP_BYTES = 512 * 1024 * 1024;
+
+const DUMP_TOO_LARGE = {
+  ok: false,
+  status: 413,
+  error: "Crash dump is too large.",
+} as const;
+
+const UPSTREAM_TIMEOUT_MS = 60_000;
+
+const version = z.string().regex(/^[0-9A-Za-z.+_-]{1,64}$/);
+
+/**
+ * The envelope keys the Worker's strict crash meta accepts, with the values it
+ * accepts. Any other key is dropped, and a value that would not pass is left
+ * out rather than failing the whole upload.
+ */
+const CrashEnvelopeSchema = z.object({
+  app_version: version.optional().catch(undefined),
+  cli_version: version.optional().catch(undefined),
+  channel: z.enum(["stable", "preview", "dev"]).optional().catch(undefined),
+  environment: z
+    .enum(["production", "ci", "internal", "e2e", "smoke"])
+    .optional()
+    .catch(undefined),
+  surface: z
+    .enum(["desktop", "cli", "headless", "mcp", "api"])
+    .optional()
+    .catch(undefined),
+  platform: ReviewBugReportMetaV2Schema.shape.platform
+    .optional()
+    .catch(undefined),
+  arch: z
+    .enum([
+      "arm",
+      "arm64",
+      "ia32",
+      "loong64",
+      "mips",
+      "mipsel",
+      "ppc",
+      "ppc64",
+      "riscv64",
+      "s390",
+      "s390x",
+      "x64",
+    ])
+    .optional()
+    .catch(undefined),
+  os_version: version.optional().catch(undefined),
+  node_major: z.number().int().optional().catch(undefined),
+  ci: z.boolean().optional().catch(undefined),
+  internal: z.boolean().optional().catch(undefined),
+  app_session_id: z.uuid().optional().catch(undefined),
+});
+
+/** The launch a dump was written during, from Electron main's dump ledger. */
+const CrashLaunchSchema = CrashEnvelopeSchema.pick({
+  app_session_id: true,
+  app_version: true,
+  cli_version: true,
+});
+
+type CrashLaunch = z.infer<typeof CrashLaunchSchema>;
+
+/** The body Electron main posts to `/crash-reports`. */
+export const CrashReportRequestSchema = z.object({
+  dump_path: z.string().min(1),
+  crashed_at: z.number().int().nonnegative(),
+  covered: z.boolean(),
+  launch: CrashLaunchSchema.optional(),
+});
+
+export type CrashReportRequest = z.infer<typeof CrashReportRequestSchema>;
+
+export interface CrashUploadResult {
+  ok: boolean;
+  status?: number;
+  error?: string;
+}
+
+/**
+ * A dump belongs to the launch that wrote it, not to this one: its session id
+ * and versions override the current envelope. Without a matching launch the
+ * crashed session is unknown, so its id is left out; the versions stay the
+ * current launch's, the best guess there is.
+ */
+function crashedLaunchProperties(
+  launch: CrashLaunch | undefined,
+): PostHogCaptureProperties {
+  const properties = { app_session_id: launch?.app_session_id };
+
+  if (!launch) return properties;
+
+  return {
+    ...properties,
+    app_version: launch.app_version,
+    cli_version: launch.cli_version,
+  };
+}
+
+/**
+ * Upload one Crashpad minidump with the telemetry envelope as metadata. The
+ * caller has already checked the opt-out; this only packs and posts.
+ */
+export async function uploadCrashDump(input: {
+  dumpPath: string;
+  crashedAt: number;
+  covered: boolean;
+  distinctId: string;
+  envelope: PostHogCaptureProperties;
+  fetchImpl?: typeof fetch;
+  maxDumpBytes?: number;
+}): Promise<CrashUploadResult> {
+  const maxDumpBytes = input.maxDumpBytes ?? DEFAULT_MAX_DUMP_BYTES;
+
+  if ((await stat(input.dumpPath)).size > MAX_RAW_DUMP_BYTES)
+    return DUMP_TOO_LARGE;
+
+  const dump = await gzipAsync(await readFile(input.dumpPath), { level: 6 });
+
+  if (dump.byteLength > maxDumpBytes) return DUMP_TOO_LARGE;
+
+  const meta = {
+    schema_version: 1,
+    distinct_id: input.distinctId,
+    crashed_at: input.crashedAt,
+    covered: input.covered,
+    dump_bytes: dump.byteLength,
+    dump_sha256: createHash("sha256").update(dump).digest("hex"),
+    ...CrashEnvelopeSchema.parse(input.envelope),
+  };
+
+  const form = new FormData();
+  form.append("meta", JSON.stringify(meta));
+  form.append(
+    "dump",
+    new Blob([Uint8Array.from(dump)], { type: "application/gzip" }),
+    "minidump.dmp.gz",
+  );
+
+  try {
+    const response = await (input.fetchImpl ?? fetch)(CRASH_REPORT_URL, {
+      method: "POST",
+      body: form,
+      signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
+    });
+
+    if (!response.ok)
+      return {
+        ok: false,
+        status: response.status,
+        error: "Crash report service failed.",
+      };
+
+    return { ok: true };
+  } catch (error) {
+    return {
+      ok: false,
+      status: 502,
+      error:
+        error instanceof Error ? error.message : "Crash report service failed.",
+    };
+  }
+}
+
+/**
+ * `POST /crash-reports` from Electron main. The server token also reaches the
+ * canvas, so only a `.dmp` file whose real path sits inside the Review dump
+ * directory is ever read. A dump no live listener covered is counted here as
+ * `review_crash`, stamped with its own launch, which the `/telemetry/event`
+ * route cannot do: that route stamps the sender's session. Nothing is uploaded
+ * when telemetry is off or only printed (the debug sink).
+ */
+export async function reportCrashDump(
+  telemetry: Pick<
+    ReviewTelemetry,
+    "captureEvent" | "envelope" | "getInstallationId" | "sendsEvents"
+  >,
+  request: CrashReportRequest,
+  crashDumpsDir: string | undefined,
+  fetchImpl?: typeof fetch,
+): Promise<{
+  status: number;
+  body: CrashUploadResult & { counted?: boolean; skipped?: string };
+}> {
+  const dumpPath = await dumpInside(request.dump_path, crashDumpsDir);
+
+  if (!dumpPath)
+    return {
+      status: 403,
+      body: { ok: false, error: "Not a Whiteboard crash dump." },
+    };
+
+  const launch = crashedLaunchProperties(request.launch);
+  const counted = !request.covered;
+
+  if (counted)
+    await telemetry.captureEvent("review_crash", {
+      process: "unknown",
+      reason: "minidump",
+      source: "minidump",
+      ...launch,
+    });
+
+  if (!(await telemetry.sendsEvents()))
+    return {
+      status: 200,
+      body: { ok: true, counted, skipped: "telemetry_disabled" },
+    };
+
+  const result = await uploadCrashDump({
+    dumpPath,
+    crashedAt: request.crashed_at,
+    covered: request.covered,
+    distinctId: await telemetry.getInstallationId(),
+    envelope: { ...(await telemetry.envelope()), ...launch },
+    fetchImpl,
+  });
+
+  return {
+    status: result.ok ? 200 : (result.status ?? 502),
+    body: { ...result, counted },
+  };
+}
+
+async function dumpInside(
+  file: string,
+  directory: string | undefined,
+): Promise<string | undefined> {
+  if (!directory) return undefined;
+
+  try {
+    const [realFile, realDirectory] = await Promise.all([
+      realpath(file),
+      realpath(directory),
+    ]);
+
+    const relative = path.relative(realDirectory, realFile);
+
+    if (
+      !realFile.endsWith(".dmp") ||
+      !relative ||
+      relative === ".." ||
+      relative.startsWith(`..${path.sep}`) ||
+      path.isAbsolute(relative)
+    )
+      return undefined;
+
+    return realFile;
+  } catch {
+    return undefined;
+  }
+}

package/src/server/desktop-host-shutdown.ts

@@ -0,0 +1,64 @@
+import {
+  type JsonValue,
+  isJsonObject,
+  jsonBoolean,
+  jsonProperty,
+  jsonString,
+} from "@dev.fast/review-protocol";
+
+interface DesktopHostMessagePort {
+  on(event: "message", listener: (event: { data: JsonValue }) => void): void;
+  off(event: "message", listener: (event: { data: JsonValue }) => void): void;
+}
+
+interface DesktopHostProcess {
+  parentPort?: DesktopHostMessagePort;
+  on(event: "message", listener: (message: JsonValue) => void): void;
+  off(event: "message", listener: (message: JsonValue) => void): void;
+}
+
+export function listenForDesktopHostShutdown(
+  hostProcess: DesktopHostProcess,
+  onShutdown: () => void,
+  onTelemetrySetting?: (enabled: boolean) => void,
+  onStageRustAnalyzer?: (path: string) => void,
+): () => void {
+  const handleMessage = (message: JsonValue) => {
+    if (!isJsonObject(message)) return;
+    const type = jsonProperty(message, "type");
+
+    if (type === "shutdown") {
+      onShutdown();
+
+      return;
+    }
+
+    if (type === "telemetry-setting") {
+      const enabled = jsonBoolean(jsonProperty(message, "enabled"));
+
+      if (enabled !== undefined) onTelemetrySetting?.(enabled);
+
+      return;
+    }
+
+    if (type === "stage-rust-analyzer") {
+      const path = jsonString(jsonProperty(message, "path"));
+
+      if (path) onStageRustAnalyzer?.(path);
+    }
+  };
+
+  if (hostProcess.parentPort) {
+    const handleParentMessage = (event: { data: JsonValue }) => {
+      handleMessage(event.data);
+    };
+
+    hostProcess.parentPort.on("message", handleParentMessage);
+
+    return () => hostProcess.parentPort?.off("message", handleParentMessage);
+  }
+
+  hostProcess.on("message", handleMessage);
+
+  return () => hostProcess.off("message", handleMessage);
+}

package/src/server/desktop-host.ts

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+
+import { reviewInstanceIdentity } from "@review/desktop-discovery";
+import { findReviewPackageRoot } from "@review/package-paths";
+import { openReviewProfile } from "@review/review-api/profile";
+import { ensureBundledRustAnalyzer } from "@review/review-bundled-tools";
+import { devReviewHome } from "@review/review-home-paths";
+import { ReviewTelemetry } from "@review/review-telemetry";
+import { SharedReviewStore } from "@review/sharing/import.js";
+import { reviewTelemetryChannel } from "@review/telemetry-config";
+
+import { listenForDesktopHostShutdown } from "./desktop-host-shutdown";
+import { createGlobalReviewServer } from "./desktop-server";
+import {
+  drainServerCrashReport,
+  installProcessErrorTelemetry,
+  serverCrashReportPath,
+} from "./process-error-telemetry";
+
+export async function runDesktopHost(
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<void> {
+  // Port 0 lets the OS choose; the ready event below reports what was bound.
+  const port = requiredPort(env.DEV_FAST_REVIEW_SERVER_PORT);
+
+  const appPid = requiredPositiveInteger(
+    env.DEV_FAST_REVIEW_APP_PID,
+    "DEV_FAST_REVIEW_APP_PID",
+  );
+
+  const packageRoot = findReviewPackageRoot(import.meta.url);
+  const toolingRoot = env.DEV_FAST_REVIEW_TOOLING_ROOT || packageRoot;
+  const telemetryEnv = { ...env };
+  delete telemetryEnv.DEV_FAST_REVIEW_TELEMETRY_DISABLED;
+
+  const telemetry = ReviewTelemetry.fromEnv(telemetryEnv, {
+    surface: "desktop",
+  });
+
+  installProcessErrorTelemetry(telemetry, {
+    appSessionId: env.DEV_FAST_REVIEW_APP_SESSION_ID,
+    crashReportPath: serverCrashReportPath(env),
+  });
+
+  await telemetry.setEnabled(
+    !isEnabledEnvValue(env.DEV_FAST_REVIEW_TELEMETRY_DISABLED),
+  );
+
+  // An unpackaged Desktop is ours; remember that so every later process on
+  // this machine, CLI included, reports internal.
+  if (reviewTelemetryChannel(env) === "dev") await telemetry.setInternal(true);
+  await telemetry.captureInstallationCreated().catch(() => undefined);
+  await telemetry.reconcileOpenSessions().catch(() => undefined);
+  await drainServerCrashReport(telemetry, serverCrashReportPath(env));
+  const installationId = await telemetry.getInstallationId();
+  // This value bootstraps the stored setting. Remove it after persistence so
+  // a later in-app enable also reaches telemetry instances created elsewhere.
+  delete env.DEV_FAST_REVIEW_TELEMETRY_DISABLED;
+
+  const serverInput = {
+    appPid,
+    packageRoot,
+    toolingRoot,
+    port,
+    token: env.DEV_FAST_REVIEW_SERVER_TOKEN,
+    instanceId: env.DEV_FAST_REVIEW_INSTANCE_ID,
+    identity: reviewInstanceIdentity(env),
+    telemetry,
+  };
+
+  const home = devReviewHome(env);
+  await mkdir(home, { recursive: true });
+
+  const local = await openReviewProfile(home, {
+    manageWorkspaces: true,
+  });
+
+  // JSON is the sole user-review store. A failure is surfaced, never replaced
+  // by a second catalog or an old document renderer.
+
+  const shared = new SharedReviewStore(path.join(home, "shared-reviews"));
+  shared.connect(local.store, local.data);
+  await shared.load();
+
+  const server = createGlobalReviewServer({
+    ...serverInput,
+    sharedReviews: shared,
+    reviewStore: local.store,
+    reviewData: local.data,
+    cliRuntimePath: env.DEV_FAST_REVIEW_CLI_RUNTIME,
+    crashDumpsDir: env.DEV_FAST_REVIEW_CRASH_DUMPS_DIR,
+  });
+
+  try {
+    await server.listen();
+  } catch (error) {
+    await local?.data.close();
+    await local?.store.close();
+    throw error;
+  }
+
+  process.stdout.write(
+    `${JSON.stringify({ event: "ready", ...server.discovery, installationId })}\n`,
+  );
+
+  const stageRustAnalyzer = () =>
+    ensureBundledRustAnalyzer({ env }).catch((error) => {
+      const reason = error instanceof Error ? error.message : String(error);
+      process.stderr.write(
+        `[Review tools] Could not stage bundled rust-analyzer: ${reason}\n`,
+      );
+    });
+
+  void stageRustAnalyzer();
+
+  let stopping: Promise<void> | null = null;
+
+  const stop = () => {
+    if (!stopping) {
+      stopping = server
+        .close("app-exit")
+        .finally(() => shared.close())
+        .finally(() => local?.data.close())
+        .finally(() => local?.store.close());
+    }
+
+    return stopping;
+  };
+
+  listenForDesktopHostShutdown(
+    process,
+    () => {
+      void stop().then(() => process.exit(0));
+    },
+    (enabled) => {
+      void telemetry.setEnabled(enabled).catch(() => undefined);
+    },
+    (sourcePath) => {
+      env.DEV_FAST_REVIEW_RUST_ANALYZER = sourcePath;
+      void stageRustAnalyzer();
+    },
+  );
+  process.once("SIGINT", () => {
+    void stop().then(() => process.exit(0));
+  });
+  process.once("SIGTERM", () => {
+    void stop().then(() => process.exit(0));
+  });
+}
+
+function isEnabledEnvValue(value: string | undefined): boolean {
+  return value === "1" || value?.toLowerCase() === "true";
+}
+
+function requiredPort(value: string | undefined): number {
+  const parsed = Number(value);
+
+  if (!Number.isSafeInteger(parsed) || parsed < 0 || parsed > 65_535) {
+    throw new Error(
+      "DEV_FAST_REVIEW_SERVER_PORT must be a port between 0 and 65535.",
+    );
+  }
+
+  return parsed;
+}
+
+function requiredPositiveInteger(
+  value: string | undefined,
+  name: string,
+): number {
+  const parsed = Number(value);
+
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new Error(`${name} must be a positive integer.`);
+  }
+
+  return parsed;
+}
+
+if (process.env.DEV_FAST_REVIEW_DESKTOP_HOST_AUTOSTART !== "0") {
+  void runDesktopHost().catch((error) => {
+    process.stderr.write(
+      `${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`,
+    );
+    process.exitCode = 1;
+  });
+}