fix(api): classify opaque Convex server errors as transient (koala73#4507)

* fix(api): treat opaque Convex server errors as transient

* Address PR review feedback (koala73#4507)

- Widen opaque Convex request-id matching while keeping the message anchored

- Add boundary tests for decorated request-id server-error variants

* Address follow-up PR feedback (koala73#4507)

- Share opaque Convex server-error matcher with Sentry tagging

- Add Sentry-context boundary coverage for request-id server errors

Author: koala73

api/_convex-error.js

@@ -35,6 +35,24 @@ function hasConvexCode(msg, code) {
   return new RegExp(`"code":\\s*"${code}"`).test(msg);
 }
 
+/**
+ * Match Convex opaque request-id server-error wrapper. The shape is ambiguous:
+ * it can represent platform/internal 5xxs or a deterministic function throw
+ * without structured ConvexError data. For /api/user-prefs, #4504 intentionally
+ * treats this exact wrapper as transient while Sentry keeps a distinct
+ * `convex_server_error` bucket for volume-based monitoring.
+ *
+ * Keep this helper shared between response classification and Sentry tagging so
+ * `SERVICE_UNAVAILABLE` responses never drift from the `convex_server_error`
+ * bucket.
+ *
+ * @param {string} msg
+ * @returns {boolean}
+ */
+export function isOpaqueConvexServerError(msg) {
+  return /^\[Request ID:\s*[\w-]+\]\s*Server Error$/i.test(msg);
+}
+
 /**
  * Extract the named-error `kind` from a Convex client throw. Prefers the
  * structured `err.data.kind` (server-side `ConvexError({ kind, ... })`),
@@ -118,6 +136,13 @@ export function extractConvexErrorKind(err, msg) {
   // classifier tags these `convex_worker_overloaded` so they stay queryable
   // apart from genuine ServiceUnavailable 503s and InternalServerError 500s.
   if (hasConvexCode(msg, 'WorkerOverloaded')) return 'SERVICE_UNAVAILABLE';
+  // Convex generic platform/internal 5xx: when the SDK receives only an
+  // opaque request-id wrapper (`[Request ID: X] Server Error`) with no
+  // machine-readable `code` JSON and no structured ConvexError data, treat
+  // it like the recognized Convex platform 5xx family above. Keep the
+  // matcher exact-ish so unrelated free-form server errors still fall
+  // through to the unknown/500 path.
+  if (isOpaqueConvexServerError(msg)) return 'SERVICE_UNAVAILABLE';
   if (msg.includes('CONFLICT')) return 'CONFLICT';
   if (msg.includes('BLOB_TOO_LARGE')) return 'BLOB_TOO_LARGE';
   if (msg.includes('UNAUTHENTICATED')) return 'UNAUTHENTICATED';

api/user-prefs.ts

@@ -17,7 +17,7 @@ import { jsonResponse } from './_json-response.js';
 // @ts-expect-error — JS module, no declaration file
 import { captureSilentError } from './_sentry-edge.js';
 // @ts-expect-error — JS module, no declaration file
-import { extractConvexErrorKind, readConvexErrorNumber } from './_convex-error.js';
+import { extractConvexErrorKind, isOpaqueConvexServerError, readConvexErrorNumber } from './_convex-error.js';
 import { ConvexHttpClient } from 'convex/browser';
 import { validateBearerToken } from '../server/auth-session';
 
@@ -390,7 +390,7 @@ export function buildSentryContext(
       // bucket so on-call can tell worker-saturation apart from internal-500s
       // and genuine 503s when triaging (WORLDMONITOR-PG).
       : /"code":\s*"WorkerOverloaded"/.test(msg) ? 'convex_worker_overloaded'
-      : /\[Request ID:\s*[a-f0-9]+\]\s*Server Error/i.test(msg) ? 'convex_server_error'
+      : isOpaqueConvexServerError(msg) ? 'convex_server_error'
       // Cloudflare edge error (520-527) fronting the Convex deployment — see
       // _convex-error.js. Mapped to SERVICE_UNAVAILABLE (503 + Retry-After)
       // there; kept as its own Sentry bucket so on-call can tell CDN-layer

tests/user-prefs-convex-error.test.mjs

@@ -252,13 +252,34 @@ describe('extractConvexErrorKind — Convex client error → kind', () => {
       assert.equal(extractConvexErrorKind(err, err.message), 'UNAUTHENTICATED');
     });
 
-    it('does NOT match a generic "Server Error" message (the bug pre-fix)', () => {
-      // This is the exact symptom the structured-data fix exists to address:
-      // Convex's `[Request ID: X] Server Error` wrapper used to bypass every
-      // catch branch in the edge handler. Confirm the fallback still returns
-      // null for it (so the caller treats it as a real 500).
-      const err = new Error('[Request ID: 9fee2a2bfa791253] Server Error');
-      assert.equal(extractConvexErrorKind(err, err.message), null);
+    it('maps opaque Convex request-id server errors to SERVICE_UNAVAILABLE', () => {
+      // Convex generic platform/internal 5xx wrapper carries no JSON `code`
+      // field, but it has the same transient retry profile as the classified
+      // platform 5xx shapes above. Map it to SERVICE_UNAVAILABLE so callers
+      // return 503 + Retry-After instead of a hard 500.
+      const hits = [
+        '[Request ID: 9fee2a2bfa791253] Server Error',
+        '[Request ID: ABCdef_123-456] Server Error',
+      ];
+      for (const msg of hits) {
+        const err = new Error(msg);
+        assert.equal(extractConvexErrorKind(err, err.message), 'SERVICE_UNAVAILABLE');
+      }
+    });
+
+    it('does NOT match partial or decorated request-id server error variants', () => {
+      const misses = [
+        '[Request ID: 9fee2a2bfa791253] Server Error: extra details',
+        'prefix [Request ID: 9fee2a2bfa791253] Server Error',
+        '[Request ID: ] Server Error',
+      ];
+      for (const msg of misses) {
+        const err = new Error(msg);
+        assert.equal(
+          extractConvexErrorKind(err, err.message), null,
+          `expected null for: ${msg}`,
+        );
+      }
     });
   });
 

tests/user-prefs-sentry-context.test.mts

@@ -57,6 +57,23 @@ describe('buildSentryContext — errorShapeOverride', () => {
     assert.equal(ctx.tags.error_shape, 'convex_server_error');
     assert.deepEqual(ctx.fingerprint, ['api/user-prefs', 'POST', 'convex_server_error']);
   });
+
+  it('shares opaque request-id server-error boundaries with the Convex classifier', () => {
+    const hit = new Error('[Request ID: ABCdef_123-456] Server Error');
+    const hitCtx = buildSentryContext(hit, hit.message, baseOpts);
+    assert.equal(hitCtx.tags.error_shape, 'convex_server_error');
+
+    const misses = [
+      '[Request ID: 9fee2a2bfa791253] Server Error: extra details',
+      'prefix [Request ID: 9fee2a2bfa791253] Server Error',
+      '[Request ID: ] Server Error',
+    ];
+    for (const msg of misses) {
+      const err = new Error(msg);
+      const ctx = buildSentryContext(err, err.message, baseOpts);
+      assert.equal(ctx.tags.error_shape, 'unknown', `expected unknown for: ${msg}`);
+    }
+  });
 });
 
 describe('buildSentryContext — extraTags', () => {