Add telemetry diagnostics route

2026-05-09 05:31:04 -04:00
parent 4e85f31dac
commit c86091a81f
8 changed files with 486 additions and 0 deletions
@@ -51,6 +51,7 @@ export interface Env {
  ELY_STORAGE: ElyR2Bucket;
  ELY_RATE_LIMITER: ElyRateLimit;
  ELY_API_AUDIT: ElyAnalyticsDataset;
+  ELY_DIAGNOSTICS: ElyAnalyticsDataset;
  ELY_ENVIRONMENT: string;
  ELY_AUTH_BASE_URL: string;
  ELY_AUTH_SECRET: string;
@@ -33,6 +33,10 @@ import {
  publicSigningKeysKvKey,
 } from "./signing_keys.js";
 import { handleSyncRoute } from "./sync_routes.js";
+import {
+  TelemetrySchemaError,
+  telemetryEventAcceptedDocument,
+} from "./telemetry.js";
 import { jsonResponse } from "./responses.js";

 export default {
@@ -199,6 +203,32 @@ export async function handleRequest(request: Request, env: Env): Promise<Respons
      handleReleaseSignature(env, url),
    );
  }
+  if (url.pathname === "/api/telemetry/events") {
+    return withAuthenticatedApiControls(
+      request,
+      env,
+      "telemetry.events",
+      ["POST"],
+      async (context) => {
+        try {
+          return jsonResponse(
+            await telemetryEventAcceptedDocument(request, env, context),
+            202,
+            { "Cache-Control": "no-store" },
+          );
+        } catch (error) {
+          if (error instanceof TelemetrySchemaError) {
+            return jsonResponse(
+              { error: error.code },
+              400,
+              { "Cache-Control": "no-store" },
+            );
+          }
+          throw error;
+        }
+      },
+    );
+  }

  return jsonResponse({ error: "not_found" }, 404);
 }
@@ -0,0 +1,262 @@
+import type { AuthContext } from "./auth.js";
+import type { Env } from "./bindings.js";
+
+const EVENT_TYPES = new Set([
+  "app_startup",
+  "app_crash",
+  "webview_crash",
+  "sync_error",
+  "plugin_crash",
+  "update_result",
+]);
+const OUTCOMES = new Set(["success", "failure"]);
+const PLATFORMS = new Set(["macos", "windows", "linux"]);
+const ALLOWED_FIELDS = new Set([
+  "version",
+  "event_type",
+  "occurred_at",
+  "app_version",
+  "platform",
+  "outcome",
+  "error_code",
+  "component",
+  "crash_kind",
+  "plugin_id",
+]);
+const SENSITIVE_FIELDS = new Set([
+  "url",
+  "loaded_url",
+  "loadedurl",
+  "page_url",
+  "pageurl",
+  "title",
+  "page_title",
+  "pagetitle",
+  "search_term",
+  "searchterm",
+  "query",
+  "bookmark",
+  "bookmark_content",
+  "bookmarkcontent",
+  "history",
+  "history_content",
+  "historycontent",
+  "note",
+  "notes",
+  "notes_content",
+  "notescontent",
+  "cookie",
+  "cookies",
+  "form",
+  "form_input",
+  "forminput",
+  "input",
+  "field_value",
+  "fieldvalue",
+  "payload",
+  "body",
+  "page_text",
+  "pagetext",
+]);
+const APP_VERSION_PATTERN = /^[0-9A-Za-z][0-9A-Za-z._+-]{0,63}$/;
+const CODE_PATTERN = /^[0-9A-Za-z][0-9A-Za-z._:-]{0,79}$/;
+
+type TelemetryRequestBody = Record<string, unknown>;
+type TelemetryEventType =
+  | "app_startup"
+  | "app_crash"
+  | "webview_crash"
+  | "sync_error"
+  | "plugin_crash"
+  | "update_result";
+type TelemetryOutcome = "success" | "failure";
+type TelemetryPlatform = "macos" | "windows" | "linux";
+
+export interface TelemetryAcceptedDocument {
+  version: 1;
+  accepted: true;
+}
+
+interface TelemetryEvent {
+  eventType: TelemetryEventType;
+  occurredAt: number;
+  appVersion: string;
+  platform: TelemetryPlatform;
+  outcome?: TelemetryOutcome;
+  errorCode?: string;
+  component?: string;
+  crashKind?: string;
+  pluginId?: string;
+}
+
+export class TelemetrySchemaError extends Error {
+  constructor(readonly code: string) {
+    super(code);
+    this.name = "TelemetrySchemaError";
+  }
+}
+
+export async function telemetryEventAcceptedDocument(
+  request: Request,
+  env: Env,
+  context: AuthContext,
+): Promise<TelemetryAcceptedDocument> {
+  const event = await telemetryEvent(request);
+  env.ELY_DIAGNOSTICS.writeDataPoint({
+    indexes: [env.ELY_ENVIRONMENT],
+    blobs: [
+      event.eventType,
+      event.appVersion,
+      event.platform,
+      event.outcome ?? "",
+      event.errorCode ?? "",
+      event.component ?? "",
+      event.crashKind ?? "",
+      event.pluginId ?? "",
+      context.userId,
+      context.deviceId ?? "",
+    ],
+    doubles: [event.occurredAt, Date.now()],
+  });
+  return { version: 1, accepted: true };
+}
+
+async function telemetryEvent(request: Request): Promise<TelemetryEvent> {
+  const body = await requestBody(request);
+  assertNoSensitiveFields(body);
+  assertOnlyFields(body);
+  if (body.version !== 1) {
+    throw new TelemetrySchemaError("telemetry_version_invalid");
+  }
+
+  const event: TelemetryEvent = {
+    eventType: eventType(body.event_type),
+    occurredAt: integer(body.occurred_at, "telemetry_occurred_at_invalid"),
+    appVersion: appVersion(body.app_version),
+    platform: platform(body.platform),
+  };
+  assignOptionalString(event, "outcome", outcome(body.outcome));
+  assignOptionalString(event, "errorCode", code(body.error_code, "telemetry_error_code_invalid"));
+  assignOptionalString(event, "component", code(body.component, "telemetry_component_invalid"));
+  assignOptionalString(event, "crashKind", code(body.crash_kind, "telemetry_crash_kind_invalid"));
+  assignOptionalString(event, "pluginId", code(body.plugin_id, "telemetry_plugin_id_invalid"));
+  assertRequiredEventFields(event);
+  return event;
+}
+
+async function requestBody(request: Request): Promise<TelemetryRequestBody> {
+  let value: unknown;
+  try {
+    value = await request.json();
+  } catch {
+    throw new TelemetrySchemaError("telemetry_json_invalid");
+  }
+  if (!isRecord(value)) {
+    throw new TelemetrySchemaError("telemetry_body_invalid");
+  }
+  return value;
+}
+
+function assertNoSensitiveFields(value: unknown): void {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      assertNoSensitiveFields(item);
+    }
+    return;
+  }
+  if (!isRecord(value)) {
+    return;
+  }
+  for (const [field, fieldValue] of Object.entries(value)) {
+    if (SENSITIVE_FIELDS.has(field.toLowerCase())) {
+      throw new TelemetrySchemaError("telemetry_sensitive_field");
+    }
+    assertNoSensitiveFields(fieldValue);
+  }
+}
+
+function assertOnlyFields(value: TelemetryRequestBody): void {
+  for (const field of Object.keys(value)) {
+    if (!ALLOWED_FIELDS.has(field)) {
+      throw new TelemetrySchemaError("telemetry_unknown_field");
+    }
+  }
+}
+
+function eventType(value: unknown): TelemetryEventType {
+  if (typeof value !== "string" || !EVENT_TYPES.has(value)) {
+    throw new TelemetrySchemaError("telemetry_event_type_invalid");
+  }
+  return value as TelemetryEventType;
+}
+
+function platform(value: unknown): TelemetryPlatform {
+  if (typeof value !== "string" || !PLATFORMS.has(value)) {
+    throw new TelemetrySchemaError("telemetry_platform_invalid");
+  }
+  return value as TelemetryPlatform;
+}
+
+function outcome(value: unknown): TelemetryOutcome | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "string" || !OUTCOMES.has(value)) {
+    throw new TelemetrySchemaError("telemetry_outcome_invalid");
+  }
+  return value as TelemetryOutcome;
+}
+
+function appVersion(value: unknown): string {
+  if (typeof value !== "string" || !APP_VERSION_PATTERN.test(value)) {
+    throw new TelemetrySchemaError("telemetry_app_version_invalid");
+  }
+  return value;
+}
+
+function code(value: unknown, errorCode: string): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "string" || !CODE_PATTERN.test(value)) {
+    throw new TelemetrySchemaError(errorCode);
+  }
+  return value;
+}
+
+function integer(value: unknown, errorCode: string): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new TelemetrySchemaError(errorCode);
+  }
+  return value;
+}
+
+function assignOptionalString<T extends object, K extends keyof T>(
+  target: T,
+  field: K,
+  value: T[K] | undefined,
+): void {
+  if (value !== undefined) {
+    target[field] = value;
+  }
+}
+
+function assertRequiredEventFields(event: TelemetryEvent): void {
+  if ((event.eventType === "app_startup" || event.eventType === "update_result")
+    && event.outcome === undefined) {
+    throw new TelemetrySchemaError("telemetry_outcome_required");
+  }
+  if (event.eventType === "sync_error" && event.errorCode === undefined) {
+    throw new TelemetrySchemaError("telemetry_error_code_required");
+  }
+  if (event.eventType === "webview_crash" && event.crashKind === undefined) {
+    throw new TelemetrySchemaError("telemetry_crash_kind_required");
+  }
+  if (event.eventType === "plugin_crash" && event.pluginId === undefined) {
+    throw new TelemetrySchemaError("telemetry_plugin_id_required");
+  }
+}
+
+function isRecord(value: unknown): value is TelemetryRequestBody {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}