fix(kit): classify convex errors and asset 404s

Author: hyochan

packages/kit/scripts/smoke-server.sh

@@ -86,6 +86,9 @@ probe() {
 probe "/health" "200"
 probe "/" "200"
 probe "/api/v1" "200"
+probe "/intu/project/intu/apikeys" "200"
+probe "/assets/missing-build-asset.js" "404"
+probe "/missing-static-doc.json" "404"
 
 if [[ "$fail" -ne 0 ]]; then
   echo "---- server log ----" >&2

packages/kit/server/server.ts

@@ -6,6 +6,7 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 
 import { apiRoutes } from "./api/v1/routes";
+import { shouldReturnNotFoundForMissingStaticPath } from "./staticPaths";
 import { parsePort } from "./utils/env";
 
 const app = new Hono();
@@ -27,21 +28,15 @@ const STATIC_ROOT = process.env.STATIC_ROOT ?? "./dist";
 // Serve the built SPA (hashed assets, favicons, llms.txt, etc.).
 app.use("/*", serveStatic({ root: STATIC_ROOT }));
 
-// If a *root-level* static-document URL (`/llms.txt`, `/robots.txt`,
-// `/manifest.json`, …) reaches this point, `serveStatic` already
+// If a static-looking URL reaches this point, `serveStatic` already
 // couldn't match it, so return 404 instead of falling through to the
-// SPA shell. Otherwise a typo at `/llm.txt` would render `index.html`,
-// React Router's `:orgSlug` route would match the typo as a slug, and
-// the user (or a bot) would see "Organization not found" with a 200
-// status code — wrong for humans and doubly wrong for crawlers.
-//
-// Scope is deliberately narrow: only single-segment paths at the
-// site root. Hashed build assets under `/assets/*.json` (i18n, chunks)
-// and nested paths still fall through to the SPA handler below.
-const ROOT_STATIC_DOC =
-  /^\/[a-z0-9._-]+\.(txt|xml|json|pdf|csv|yaml|yml|md|webmanifest)$/i;
+// SPA shell. This covers root documents (`/llms.txt`), favicons, and
+// hashed Vite assets (`/assets/index-*.js`). Falling back to
+// `index.html` for a missing asset gives browsers the wrong MIME type
+// and makes Sentry source-context fetches display the HTML shell as
+// the suspect source.
 app.get("*", async (c, next) => {
-  if (ROOT_STATIC_DOC.test(c.req.path)) {
+  if (shouldReturnNotFoundForMissingStaticPath(c.req.path)) {
     return c.notFound();
   }
   return next();

packages/kit/server/staticPaths.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "vitest";
+
+import { shouldReturnNotFoundForMissingStaticPath } from "./staticPaths";
+
+describe("shouldReturnNotFoundForMissingStaticPath", () => {
+  test("treats missing build assets as static 404s", () => {
+    expect(
+      shouldReturnNotFoundForMissingStaticPath("/assets/index-QW95BJ-u.js"),
+    ).toBe(true);
+    expect(
+      shouldReturnNotFoundForMissingStaticPath(
+        "/assets/index-QW95BJ-u.js.map?debug=1",
+      ),
+    ).toBe(true);
+  });
+
+  test("treats missing root static documents and images as static 404s", () => {
+    expect(shouldReturnNotFoundForMissingStaticPath("/manifest.json")).toBe(
+      true,
+    );
+    expect(
+      shouldReturnNotFoundForMissingStaticPath("/apple-touch-icon.webp"),
+    ).toBe(true);
+  });
+
+  test("allows SPA routes to fall through to React Router", () => {
+    expect(shouldReturnNotFoundForMissingStaticPath("/")).toBe(false);
+    expect(
+      shouldReturnNotFoundForMissingStaticPath("/intu/project/intu/apikeys"),
+    ).toBe(false);
+    expect(
+      shouldReturnNotFoundForMissingStaticPath("/docs/verification-apple"),
+    ).toBe(false);
+  });
+});

packages/kit/server/staticPaths.ts

@@ -0,0 +1,11 @@
+const STATIC_FILE_EXTENSION =
+  /\.(?:avif|css|csv|gif|ico|jpe?g|js|json|map|md|mjs|otf|pdf|png|svg|ttf|txt|webmanifest|webp|woff2?|ya?ml|xml)$/i;
+
+const ASSET_PATH = /^\/assets(?:\/|$)/i;
+
+export function shouldReturnNotFoundForMissingStaticPath(
+  requestPath: string,
+): boolean {
+  const pathOnly = requestPath.split("?")[0] ?? "";
+  return ASSET_PATH.test(pathOnly) || STATIC_FILE_EXTENSION.test(pathOnly);
+}

packages/kit/src/lib/sentry.ts

@@ -1,5 +1,7 @@
 import * as Sentry from "@sentry/react";
 
+import { applySentryEventFilters } from "./sentryFilters";
+
 // Client-side Sentry init for the SPA. Kept separate from the server
 // init at `server/sentry.ts` — both point at distinct Sentry projects
 // (openiap-kit-node vs openiap-kit-react) so server bugs and UI bugs
@@ -48,36 +50,7 @@ if (typeof dsn === "string" && dsn.length > 0 && onAllowedHost) {
     // and floods Sentry as `TypeError: Load failed` noise that drowns
     // out real bugs. Tag those events so triage can filter them out
     // (or downsample) instead of treating each as a fresh signal.
-    beforeSend: (event, hint) => {
-      const exception = hint?.originalException;
-      // Sentry events occasionally arrive with no `originalException`
-      // (programmatic captureMessage, late-bound rejections that
-      // lost their cause), only an `event.message` /
-      // `logentry.message`. Build the classifier input from every
-      // available source so reconnect noise gets tagged regardless
-      // of where the message lives (CodeRabbit review on PR #127).
-      const message = [
-        exception instanceof Error
-          ? exception.message
-          : typeof exception === "string"
-            ? exception
-            : "",
-        event.message ?? "",
-        event.logentry?.message ?? "",
-      ]
-        .filter(Boolean)
-        .join(" ");
-      const isFetchLoadFailed =
-        /Load failed|Failed to fetch|NetworkError/i.test(message);
-      const looksConvex = /convex\.cloud|\/api\/(action|query|mutation)/i.test(
-        message + " " + (event.request?.url ?? ""),
-      );
-      if (isFetchLoadFailed && looksConvex) {
-        event.tags = { ...(event.tags ?? {}), source: "convex-reconnect" };
-        event.fingerprint = ["convex-reconnect-load-failed"];
-      }
-      return event;
-    },
+    beforeSend: applySentryEventFilters,
   });
 }
 

packages/kit/src/lib/sentryFilters.test.ts

@@ -0,0 +1,75 @@
+import type { Event } from "@sentry/react";
+import { describe, expect, test } from "vitest";
+
+import { applySentryEventFilters } from "./sentryFilters";
+
+describe("applySentryEventFilters", () => {
+  test("keeps Convex reconnect failures on a stable fingerprint", () => {
+    const event: Event = {
+      breadcrumbs: [
+        {
+          category: "fetch",
+          data: {
+            method: "POST",
+            url: "https://healthy-kudu-836.convex.cloud/api/action",
+          },
+        },
+      ],
+      request: { url: "https://kit.openiap.dev/intu/project/intu/apikeys" },
+    };
+
+    const result = applySentryEventFilters(event, {
+      originalException: new TypeError("Failed to fetch"),
+    });
+
+    expect(result?.tags?.source).toBe("convex-reconnect");
+    expect(result?.fingerprint).toEqual(["convex-reconnect-load-failed"]);
+  });
+
+  test("fingerprints generic Convex action server errors", () => {
+    const event: Event = {
+      breadcrumbs: [
+        {
+          category: "fetch",
+          data: {
+            method: "POST",
+            status_code: 200,
+            url: "https://healthy-kudu-836.convex.cloud/api/action",
+          },
+        },
+      ],
+      request: { url: "https://kit.openiap.dev/intu/project/intu/apikeys" },
+    };
+
+    const result = applySentryEventFilters(event, {
+      originalException: new Error(
+        "[Request ID: 79b077815fe97b2b] Server Error",
+      ),
+    });
+
+    expect(result?.tags?.source).toBe("convex-action-server-error");
+    expect(result?.fingerprint).toEqual(["convex-action-server-error"]);
+  });
+
+  test("does not rewrite unrelated server errors", () => {
+    const event: Event = {
+      breadcrumbs: [
+        {
+          category: "fetch",
+          data: {
+            method: "POST",
+            url: "https://api.example.test/action",
+          },
+        },
+      ],
+      request: { url: "https://kit.openiap.dev/intu/project/intu/apikeys" },
+    };
+
+    const result = applySentryEventFilters(event, {
+      originalException: new Error("[Request ID: abc123] Server Error"),
+    });
+
+    expect(result?.tags?.source).toBeUndefined();
+    expect(result?.fingerprint).toBeUndefined();
+  });
+});

packages/kit/src/lib/sentryFilters.ts

@@ -0,0 +1,93 @@
+import type { Event, EventHint } from "@sentry/react";
+
+function messageFromOriginalException(exception: unknown): string {
+  if (exception instanceof Error) {
+    return exception.message;
+  }
+  if (typeof exception === "string") {
+    return exception;
+  }
+  return "";
+}
+
+function stringFromUnknown(value: unknown): string {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return "";
+}
+
+function breadcrumbText(event: Event): string {
+  return (
+    event.breadcrumbs
+      ?.map((breadcrumb) =>
+        [
+          breadcrumb.category,
+          breadcrumb.message,
+          stringFromUnknown(breadcrumb.data?.url),
+          stringFromUnknown(breadcrumb.data?.method),
+          stringFromUnknown(breadcrumb.data?.status_code),
+        ]
+          .filter(Boolean)
+          .join(" "),
+      )
+      .filter(Boolean)
+      .join(" ") ?? ""
+  );
+}
+
+function eventMessage(event: Event, hint?: EventHint): string {
+  const exception = hint?.originalException;
+  return [
+    messageFromOriginalException(exception),
+    event.message ?? "",
+    event.logentry?.message ?? "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+}
+
+function hasConvexActionBreadcrumb(event: Event): boolean {
+  return /convex\.cloud\/api\/action|\/api\/action/i.test(
+    breadcrumbText(event),
+  );
+}
+
+export function applySentryEventFilters<TEvent extends Event>(
+  event: TEvent,
+  hint?: EventHint,
+): TEvent | null {
+  const message = eventMessage(event, hint);
+  const searchText = [
+    message,
+    event.request?.url ?? "",
+    breadcrumbText(event),
+  ].join(" ");
+
+  const isFetchLoadFailed = /Load failed|Failed to fetch|NetworkError/i.test(
+    message,
+  );
+  const looksConvex = /convex\.cloud|\/api\/(action|query|mutation)/i.test(
+    searchText,
+  );
+
+  if (isFetchLoadFailed && looksConvex) {
+    event.tags = { ...(event.tags ?? {}), source: "convex-reconnect" };
+    event.fingerprint = ["convex-reconnect-load-failed"];
+  }
+
+  const isGenericConvexServerError =
+    /^\[Request ID: [a-z0-9]+\] Server Error$/i.test(message.trim());
+  if (isGenericConvexServerError && hasConvexActionBreadcrumb(event)) {
+    event.tags = {
+      ...(event.tags ?? {}),
+      source: "convex-action-server-error",
+    };
+    event.fingerprint = ["convex-action-server-error"];
+  }
+
+  return event;
+}