Whitelist the correlation header for CORS, rename it, and fix coalesced-search timing

- CORS: add the correlation header to the realm-server's `Access-Control-Allow-Headers`
  allowlist. Without it the cross-origin preflight blocks the prerender's
  `_federated-search` once the host stamps the header.
- Rename `x-boxel-request-id` → `x-boxel-logging-correlation-id` (and the
  internal field/vars to `loggingCorrelationId`, the log token to `corr=`):
  the old name read too much like the unrelated `x-boxel-client-request-id`,
  which is realm-event/write correlation, a different concern.
- searchCards in-flight coalescing: exclude the per-request `timings` collector
  from `searchInFlightKey` so it can't perturb the dedup key, and when a follower
  awaits an already-running identical search, record that wait as `coalescedWait`
  on the follower's own collector — otherwise its timing line would show no
  sql/loadLinks and look misleadingly instant under concurrent search load.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: habdelra

packages/host/app/lib/prerender-fetch-headers.ts

@@ -2,7 +2,7 @@ import {
   DURING_PRERENDER_HEADER,
   X_BOXEL_CONSUMING_REALM_HEADER,
   X_BOXEL_JOB_ID_HEADER,
-  X_BOXEL_REQUEST_ID_HEADER,
+  X_BOXEL_LOGGING_CORRELATION_ID_HEADER,
 } from '@cardstack/runtime-common';
 
 // Set by the prerender server's `evaluateOnNewDocument` before the
@@ -50,19 +50,19 @@ export function jobIdHeader(): Record<string, string> {
 
 // Per-search correlation id. Minted fresh for each `_federated-search`
 // fetch the SPA issues while rendering inside a prerender tab, and stamped
-// as `x-boxel-request-id`. The realm-server reads it back out and keys its
+// as `x-boxel-logging-correlation-id`. The realm-server reads it back out and keys its
 // `realm:search-timing` line on it, so a search the prerender observes as
 // slow (surfaced in its `queryLoadsInFlight` diagnostics) can be joined to
 // the realm-server's stage-by-stage view of the same request. Gated on the
 // prerender context — exactly like the job-id / consuming-realm headers —
 // so live SPA traffic is unaffected and emits no server-side timing line.
-export function requestIdHeader(): Record<string, string> {
+export function loggingCorrelationIdHeader(): Record<string, string> {
   let flag = (globalThis as unknown as { __boxelRenderContext?: boolean })
     .__boxelRenderContext;
   if (flag !== true) {
     return {};
   }
-  return { [X_BOXEL_REQUEST_ID_HEADER]: newCorrelationId() };
+  return { [X_BOXEL_LOGGING_CORRELATION_ID_HEADER]: newCorrelationId() };
 }
 
 function newCorrelationId(): string {

packages/host/app/services/store.ts

@@ -89,7 +89,7 @@ import {
   consumingRealmHeader,
   duringPrerenderHeaders,
   jobIdHeader,
-  requestIdHeader,
+  loggingCorrelationIdHeader,
 } from '../lib/prerender-fetch-headers';
 import { searchCacheKey } from '../lib/search-cache-key';
 import { searchInFlightKey } from '../lib/search-in-flight-key';
@@ -1154,7 +1154,7 @@ export default class StoreService extends Service implements StoreInterface {
           ...consumingRealmHeader(),
           ...jobIdHeader(),
           ...jobPriorityHeader(),
-          ...requestIdHeader(),
+          ...loggingCorrelationIdHeader(),
         },
         body: JSON.stringify({ ...query, realms }),
       },

packages/host/tests/helpers/realm-server-mock/routes.ts

@@ -7,11 +7,11 @@ import {
   parseSearchQueryFromPayload,
   parseSearchRequestPayload,
   SearchRequestError,
-  sanitizeRequestId,
+  sanitizeLoggingCorrelationId,
   searchPrerenderedRealms,
   searchRealms,
   SupportedMimeType,
-  X_BOXEL_REQUEST_ID_HEADER,
+  X_BOXEL_LOGGING_CORRELATION_ID_HEADER,
   type RealmInfo,
   type Query,
 } from '@cardstack/runtime-common';
@@ -124,13 +124,13 @@ function registerSearchRoutes() {
       // correlation id off the request and thread it into searchRealms, so
       // the real `realm:search-timing` line is emitted (and observable by
       // host integration tests) keyed by the id the client minted.
-      let requestId = sanitizeRequestId(
-        req.headers.get(X_BOXEL_REQUEST_ID_HEADER),
+      let loggingCorrelationId = sanitizeLoggingCorrelationId(
+        req.headers.get(X_BOXEL_LOGGING_CORRELATION_ID_HEADER),
       );
       let combined = await searchRealms(
         realmList.map((realmURL) => getSearchableRealmForURL(realmURL)),
         cardsQuery,
-        requestId ? { requestId } : undefined,
+        loggingCorrelationId ? { loggingCorrelationId } : undefined,
       );
 
       return new Response(JSON.stringify(combined), {

packages/host/tests/integration/search-correlation-id-test.gts

@@ -8,7 +8,7 @@ import {
   baseRealm,
   rri,
   setSearchTimingSinkForTests,
-  X_BOXEL_REQUEST_ID_HEADER,
+  X_BOXEL_LOGGING_CORRELATION_ID_HEADER,
 } from '@cardstack/runtime-common';
 import type { Loader } from '@cardstack/runtime-common/loader';
 import type { Query } from '@cardstack/runtime-common/query';
@@ -26,14 +26,14 @@ import { setupMockMatrix } from '../helpers/mock-matrix';
 import { setupRenderingTest } from '../helpers/setup';
 
 // End-to-end coverage for the search correlation id: the in-realm browser
-// (the prerendered host SPA) mints `x-boxel-request-id` on its
+// (the prerendered host SPA) mints `x-boxel-logging-correlation-id` on its
 // `_federated-search` fetch, and the realm-server's search path emits a
 // `realm:search-timing` line keyed by that same id. This proves the id
 // threads all the way from the client that originated it through to the
 // server log a triage would join against.
 //
 // The host test exercises the *real* code on both ends: the SPA's
-// `requestIdHeader()` stamps the header, and the realm-server-mock hands it
+// `loggingCorrelationIdHeader()` stamps the header, and the realm-server-mock hands it
 // to the real `searchRealms`, which emits the line. Only the prerender
 // context flag is simulated (the host normally sets it inside a prerender
 // tab).
@@ -108,7 +108,7 @@ module('Integration | search correlation id', function (hooks) {
     let sentRequestIds: string[] = [];
     let spy = async (request: Request) => {
       if (new URL(request.url).pathname.endsWith('/_federated-search')) {
-        let id = request.headers.get(X_BOXEL_REQUEST_ID_HEADER);
+        let id = request.headers.get(X_BOXEL_LOGGING_CORRELATION_ID_HEADER);
         if (id) {
           sentRequestIds.push(id);
         }
@@ -139,7 +139,9 @@ module('Integration | search correlation id', function (hooks) {
       `client-minted correlation id looks well-formed (${sentId})`,
     );
 
-    let matching = timingLines.filter((line) => line.includes(`req=${sentId}`));
+    let matching = timingLines.filter((line) =>
+      line.includes(`corr=${sentId}`),
+    );
     assert.strictEqual(
       matching.length,
       1,
@@ -168,7 +170,7 @@ module('Integration | search correlation id', function (hooks) {
     let spy = async (request: Request) => {
       if (
         new URL(request.url).pathname.endsWith('/_federated-search') &&
-        request.headers.get(X_BOXEL_REQUEST_ID_HEADER)
+        request.headers.get(X_BOXEL_LOGGING_CORRELATION_ID_HEADER)
       ) {
         sawHeader = true;
       }
@@ -184,7 +186,7 @@ module('Integration | search correlation id', function (hooks) {
     assert.strictEqual(results.length, 2, 'the search still returns results');
     assert.false(
       sawHeader,
-      'live (non-prerender) traffic sends no x-boxel-request-id header',
+      'live (non-prerender) traffic sends no x-boxel-logging-correlation-id header',
     );
     assert.strictEqual(
       timingLines.length,

packages/realm-server/handlers/handle-search.ts

@@ -10,8 +10,8 @@ import {
   sanitizeConsumingRealmHeader,
   SearchRequestError,
   searchRealms,
-  sanitizeRequestId,
-  X_BOXEL_REQUEST_ID_HEADER,
+  sanitizeLoggingCorrelationId,
+  X_BOXEL_LOGGING_CORRELATION_ID_HEADER,
   RequestTimings,
   emitSearchTiming,
 } from '@cardstack/runtime-common';
@@ -47,8 +47,11 @@ export default function handleSearch(opts: {
     // outermost request→response bound (incl. body read + send) is the
     // `realm:requests` middleware's `dur=`, keyed by the same id.
     let handlerStart = Date.now();
-    let requestId = sanitizeRequestId(ctxt.get(X_BOXEL_REQUEST_ID_HEADER));
-    let timings = requestId !== null ? new RequestTimings() : undefined;
+    let loggingCorrelationId = sanitizeLoggingCorrelationId(
+      ctxt.get(X_BOXEL_LOGGING_CORRELATION_ID_HEADER),
+    );
+    let timings =
+      loggingCorrelationId !== null ? new RequestTimings() : undefined;
 
     let { realmList } = getMultiRealmAuthorization(ctxt);
 
@@ -123,18 +126,18 @@ export default function handleSearch(opts: {
     if (prerenderJobId) searchOpts.jobIdentity = prerenderJobId;
     let normalizedSearchOpts =
       Object.keys(searchOpts).length > 0 ? searchOpts : undefined;
-    // `requestId` / `timings` are deliberately kept OUT of `searchOpts`:
+    // `loggingCorrelationId` / `timings` are deliberately kept OUT of `searchOpts`:
     // that object is the job-scoped search cache's key material (see
     // `computeETag` / `getOrPopulate` below), and per-request values would
     // make every key unique and defeat the cache. They only need to reach
     // `searchRealms` (which stamps the SQL + loadLinks stages onto the same
     // collector this handler emits), so they ride on the run-time opts and
     // never touch the cache key.
     let runSearchOpts =
-      requestId !== null
+      loggingCorrelationId !== null
         ? {
             ...(normalizedSearchOpts ?? {}),
-            requestId,
+            loggingCorrelationId,
             ...(timings ? { timings } : {}),
           }
         : normalizedSearchOpts;
@@ -168,11 +171,11 @@ export default function handleSearch(opts: {
     // error early returns above, which never reach here). No-op without a
     // correlation id.
     let emitTimeline = () => {
-      if (!timings || requestId === null) {
+      if (!timings || loggingCorrelationId === null) {
         return;
       }
       emitSearchTiming(
-        `req=${requestId}` +
+        `corr=${loggingCorrelationId}` +
           (prerenderJobId ? ` job=${prerenderJobId}` : '') +
           ` handler=${Date.now() - handlerStart}ms ` +
           timings.toLogFragment(),

packages/realm-server/middleware/index.ts

@@ -4,8 +4,8 @@ import type { ResponseWithNodeStream } from '@cardstack/runtime-common';
 import {
   logger as getLogger,
   webStreamToText,
-  sanitizeRequestId,
-  X_BOXEL_REQUEST_ID_HEADER,
+  sanitizeLoggingCorrelationId,
+  X_BOXEL_LOGGING_CORRELATION_ID_HEADER,
 } from '@cardstack/runtime-common';
 import type Koa from 'koa';
 import mime from 'mime-types';
@@ -173,10 +173,12 @@ export function httpLogging(ctxt: Koa.Context, next: Koa.Next) {
   // joins to the realm-server's view of the same request. The matching
   // `realm:search-timing` line (emitted by `searchRealms`) is keyed by the
   // same value.
-  let requestId = sanitizeRequestId(ctxt.get(X_BOXEL_REQUEST_ID_HEADER));
-  let reqTag = requestId ? ` req=${requestId}` : '';
-  if (requestId) {
-    ctxt.set(X_BOXEL_REQUEST_ID_HEADER, requestId);
+  let loggingCorrelationId = sanitizeLoggingCorrelationId(
+    ctxt.get(X_BOXEL_LOGGING_CORRELATION_ID_HEADER),
+  );
+  let corrTag = loggingCorrelationId ? ` corr=${loggingCorrelationId}` : '';
+  if (loggingCorrelationId) {
+    ctxt.set(X_BOXEL_LOGGING_CORRELATION_ID_HEADER, loggingCorrelationId);
   }
   let startedAt = Date.now();
 
@@ -199,7 +201,7 @@ export function httpLogging(ctxt: Koa.Context, next: Koa.Next) {
   logger.info(
     `<-- ${ctxt.method} ${ctxt.req.headers.accept} ${
       fullRequestURL(ctxt).href
-    }${jobTag}${reqTag}`,
+    }${jobTag}${corrTag}`,
   );
 
   let onSettled = () => {
@@ -209,7 +211,7 @@ export function httpLogging(ctxt: Koa.Context, next: Koa.Next) {
     logger.info(
       `--> ${ctxt.method} ${ctxt.req.headers.accept} ${
         fullRequestURL(ctxt).href
-      }: ${ctxt.status}${jobTag}${reqTag} dur=${Date.now() - startedAt}ms`,
+      }: ${ctxt.status}${jobTag}${corrTag} dur=${Date.now() - startedAt}ms`,
     );
     logger.debug(JSON.stringify(ctxt.req.headers));
   };

packages/realm-server/server.ts

@@ -728,7 +728,7 @@ export class RealmServer {
         cors({
           origin: '*',
           allowHeaders:
-            'Authorization, Content-Type, If-Match, If-None-Match, X-Requested-With, X-Boxel-Client-Request-Id, X-Boxel-Assume-User, X-HTTP-Method-Override, X-Boxel-Disable-Module-Cache, X-Filename, X-Boxel-During-Prerender, X-Boxel-Consuming-Realm, X-Boxel-Job-Id, X-Boxel-Job-Priority, X-Grafana-Device-Id, X-Grafana-Action',
+            'Authorization, Content-Type, If-Match, If-None-Match, X-Requested-With, X-Boxel-Client-Request-Id, X-Boxel-Assume-User, X-HTTP-Method-Override, X-Boxel-Disable-Module-Cache, X-Filename, X-Boxel-During-Prerender, X-Boxel-Consuming-Realm, X-Boxel-Job-Id, X-Boxel-Job-Priority, X-Boxel-Logging-Correlation-Id, X-Grafana-Device-Id, X-Grafana-Action',
           // Without an explicit expose list, @koa/cors only emits the
           // CORS-safelisted response headers (cache-control, content-*,
           // expires, last-modified, pragma). ETag is not on that list,

packages/runtime-common/prerender-headers.ts

@@ -102,14 +102,15 @@ export function sanitizeJobPriorityHeader(
 // can be joined to where the realm-server actually spent the time. Lives
 // here so the host SPA can import the header name without depending on
 // the realm-server package.
-export const X_BOXEL_REQUEST_ID_HEADER = 'x-boxel-request-id';
+export const X_BOXEL_LOGGING_CORRELATION_ID_HEADER =
+  'x-boxel-logging-correlation-id';
 
 // Sanitize the inbound request-id header. It's echoed into log lines, so
 // admit only a bounded run of URL-safe id characters (covers a UUID and
 // then some) and reject anything with whitespace or control characters
 // that could forge a log line.
 const REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
-export function sanitizeRequestId(
+export function sanitizeLoggingCorrelationId(
   raw: string | null | undefined,
 ): string | null {
   if (typeof raw !== 'string') return null;

packages/runtime-common/realm-index-query-engine.ts

@@ -227,10 +227,19 @@ export function searchInFlightKey(
   // values inside query/opts — e.g. a `matches: 'a|b'` string — can never
   // collide with the delimiter and cause unrelated searches to coalesce.
   try {
+    // `timings` is a per-request diagnostic collector, not part of the
+    // result-shaping opts. Exclude it from the key so it can't perturb the
+    // in-flight coalescing — two otherwise-identical searches must still
+    // dedupe even though each carries its own collector.
+    let keyOpts = opts;
+    if (opts && 'timings' in opts) {
+      let { timings: _omitTimings, ...rest } = opts;
+      keyOpts = rest;
+    }
     return JSON.stringify([
       realmURL,
       normalizeQueryForSignature(query),
-      opts ? sortKeysDeep(opts) : null,
+      keyOpts ? sortKeysDeep(keyOpts) : null,
     ]);
   } catch {
     return undefined;
@@ -341,7 +350,15 @@ export class RealmIndexQueryEngine {
     if (key !== undefined) {
       let existing = this.#inFlightSearch.get(key);
       if (existing) {
-        return await existing;
+        // A concurrent identical search is already running; this follower
+        // awaits its result instead of re-running the work. Record that wait
+        // as `coalescedWait` on the follower's own collector so its
+        // `realm:search-timing` line reflects the time spent — otherwise the
+        // follower would show no `sql`/`loadLinks` and look misleadingly
+        // instant exactly under the concurrent search load we're diagnosing.
+        return opts?.timings
+          ? await opts.timings.time('coalescedWait', () => existing)
+          : await existing;
       }
       let pending = this.searchCardsUncoalesced(query, opts).finally(() => {
         // Identity-check before deletion: a concurrent invalidation path

packages/runtime-common/search-utils.ts

@@ -329,14 +329,14 @@ export type SearchOpts = {
   priority?: number;
   jobIdentity?: string;
   // Correlation id minted by the client (the prerendered host stamps
-  // `x-boxel-request-id` on its `_federated-search` fetch) and read back
+  // `x-boxel-logging-correlation-id` on its `_federated-search` fetch) and read back
   // out by the request handler into opts. When present, `searchRealms`
   // instruments the server-side search pipeline and emits one
   // `realm:search-timing` line keyed by this id, so a client-observed
   // slow search can be joined to where the realm-server spent the time.
-  requestId?: string;
+  loggingCorrelationId?: string;
   // Per-request wall-clock collector. `searchRealms` creates it when a
-  // `requestId` is present and threads it down through `Realm.search` →
+  // `loggingCorrelationId` is present and threads it down through `Realm.search` →
   // `searchCards` → `loadLinks` so each post-SQL stage stamps its
   // elapsed time. Callers never supply this directly.
   timings?: RequestTimings;
@@ -384,9 +384,9 @@ export async function searchRealms(
   // Two callers: the realm-server's `handle-search` threads a collector it
   // owns (so it can emit one complete request→response line itself —
   // `opts.timings` is set, `ownsTimings` is false, we don't emit), and the
-  // host-test realm-server mock calls us with just a `requestId` (we create
+  // host-test realm-server mock calls us with just a `loggingCorrelationId` (we create
   // the collector and emit the line ourselves, which the host test observes).
-  let ownsTimings = Boolean(opts?.requestId) && !opts?.timings;
+  let ownsTimings = Boolean(opts?.loggingCorrelationId) && !opts?.timings;
   let timings =
     opts?.timings ?? (ownsTimings ? new RequestTimings() : undefined);
   let perRealmOpts = ownsTimings && opts ? { ...opts, timings } : opts;
@@ -425,7 +425,7 @@ export async function searchRealms(
   }
   if (ownsTimings && timings) {
     emitSearchTiming(
-      `req=${opts!.requestId}` +
+      `corr=${opts!.loggingCorrelationId}` +
         (opts!.jobIdentity ? ` job=${opts!.jobIdentity}` : '') +
         ` realms=${realmEntries.length}` +
         ` total=${Date.now() - startedAt}ms ` +