@open-mercato/shared 0.6.8-develop.7091.1.15ffbe30ce → 0.6.8-develop.7092.1.8bbdd53d2f

package/dist/lib/version.js

@@ -1,4 +1,4 @@
-const APP_VERSION = "0.6.8-develop.7091.1.15ffbe30ce";
+const APP_VERSION = "0.6.8-develop.7092.1.8bbdd53d2f";
 const appVersion = APP_VERSION;
 export {
   APP_VERSION,

package/dist/lib/version.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/version.ts"],
-  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.8-develop.7091.1.15ffbe30ce';\nexport const appVersion = APP_VERSION;\n"],
+  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.8-develop.7092.1.8bbdd53d2f';\nexport const appVersion = APP_VERSION;\n"],
   "mappings": "AACO,MAAM,cAAc;AACpB,MAAM,aAAa;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.6.8-develop.7091.1.15ffbe30ce",
+  "version": "0.6.8-develop.7092.1.8bbdd53d2f",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -109,7 +109,7 @@
     "@mikro-orm/core": "^7.1.8",
     "@mikro-orm/decorators": "^7.1.8",
     "@mikro-orm/postgresql": "^7.1.8",
-    "@open-mercato/cache": "0.6.8-develop.7091.1.15ffbe30ce",
+    "@open-mercato/cache": "0.6.8-develop.7092.1.8bbdd53d2f",
     "@types/html-to-text": "^9.0.4",
     "@types/sanitize-html": "^2.16.1",
     "dotenv": "^17.4.2",

package/src/lib/crud/__tests__/crud-factory.test.ts

@@ -12,6 +12,16 @@ import {
 import { loadCustomFieldDefinitionIndex } from '@open-mercato/shared/lib/crud/custom-fields'
 import { registerMutationGuards } from '@open-mercato/shared/lib/crud/mutation-guard-store'
 import { CommandInterceptorError } from '@open-mercato/shared/lib/commands/errors'
+import {
+  registerLoggerExtension,
+  resetLoggerExtension,
+  type LoggerExtensionRecord,
+} from '@open-mercato/shared/lib/logger'
+import {
+  registerTelemetryRuntime,
+  resetTelemetryRuntime,
+  type TelemetryRuntime,
+} from '@open-mercato/shared/lib/telemetry/runtime'
 import { z } from 'zod'
 
 // Keep the real custom-field helpers but spy on the definition loader so we can
@@ -1076,6 +1086,7 @@ describe('CRUD Factory', () => {
     await expect(res.json()).resolves.toEqual({
       error: 'Internal server error',
       message: 'Something went wrong. Please try again later.',
+      requestId: expect.any(String),
     })
   })
 
@@ -1114,6 +1125,138 @@ describe('CRUD Factory', () => {
     await expect(res.json()).resolves.toEqual({
       error: 'Internal server error',
       message: 'Something went wrong. Please try again later.',
+      requestId: expect.any(String),
+    })
+  })
+
+  // Issue #5608 — a generic 500 must carry a requestId the client/support can cite, and
+  // that same id must appear on the server log line so the two can be correlated.
+  describe('generic 500 requestId correlation', () => {
+    const logRecords: LoggerExtensionRecord[] = []
+    const reportError = jest.fn()
+
+    const postWithRequestId = (requestId: string) => interceptorErrorRoute().POST(
+      new Request('http://x/api/example/todos/command', {
+        method: 'POST',
+        body: JSON.stringify({ title: 'A' }),
+        headers: { 'content-type': 'application/json', 'x-request-id': requestId },
+      }),
+    )
+
+    beforeEach(() => {
+      logRecords.length = 0
+      reportError.mockClear()
+      registerLoggerExtension({ emit: (record) => logRecords.push(record) })
+      registerTelemetryRuntime({
+        canUseGlobalTracePropagation: () => false,
+        captureTraceContext: () => ({}),
+        continueTrace: (_carrier, _name, fn) => fn(),
+        recordHttpDuration: () => {},
+        reportError,
+        shutdown: async () => {},
+      } satisfies TelemetryRuntime)
+    })
+
+    afterEach(() => {
+      resetLoggerExtension()
+      resetTelemetryRuntime()
+    })
+
+    it('includes a requestId in the body that matches the server log line', async () => {
+      commandBus.execute.mockRejectedValue(new Error('boom'))
+
+      const res = await postInterceptorErrorRequest(interceptorErrorRoute())
+      const body = await res.json()
+
+      expect(res.status).toBe(500)
+      expect(typeof body.requestId).toBe('string')
+      expect(body.requestId.length).toBeGreaterThan(0)
+
+      const logRecord = logRecords.find((record) => record.message === 'Unexpected CRUD error')
+      expect(logRecord?.fields.requestId).toBe(body.requestId)
+    })
+
+    it('echoes the requestId on an x-request-id response header', async () => {
+      commandBus.execute.mockRejectedValue(new Error('boom'))
+
+      const res = await postInterceptorErrorRequest(interceptorErrorRoute())
+      const body = await res.json()
+
+      expect(res.headers.get('x-request-id')).toBe(body.requestId)
+    })
+
+    it('reuses an inbound x-request-id header instead of generating a new one', async () => {
+      commandBus.execute.mockRejectedValue(new Error('boom'))
+
+      const res = await postWithRequestId('req-fixed-123')
+      const body = await res.json()
+
+      expect(res.status).toBe(500)
+      expect(body.requestId).toBe('req-fixed-123')
+      const logRecord = logRecords.find((record) => record.message === 'Unexpected CRUD error')
+      expect(logRecord?.fields.requestId).toBe('req-fixed-123')
+    })
+
+    // `Headers.get()` returns '' for an empty or whitespace-only header, which a plain
+    // `?? randomUUID()` would hand straight through as a blank correlation id.
+    it.each([
+      ['an empty inbound header', ''],
+      ['a whitespace-only inbound header', '   '],
+    ])('generates a fresh id for %s', async (_label, inbound) => {
+      commandBus.execute.mockRejectedValue(new Error('boom'))
+
+      const res = await postWithRequestId(inbound)
+      const body = await res.json()
+
+      expect(res.status).toBe(500)
+      expect(typeof body.requestId).toBe('string')
+      expect(body.requestId.length).toBeGreaterThan(0)
+      const logRecord = logRecords.find((record) => record.message === 'Unexpected CRUD error')
+      expect(logRecord?.fields.requestId).toBe(body.requestId)
+    })
+
+    // A caller-controlled id lands verbatim in the unquoted `key=value` log line, so an
+    // over-long one or one carrying spaces/`=` is discarded rather than echoed.
+    it.each([
+      ['a value carrying log-field separators', 'a=1 tenantId=victim'],
+      ['an over-long value', 'x'.repeat(129)],
+    ])('discards %s in favor of a generated id', async (_label, inbound) => {
+      commandBus.execute.mockRejectedValue(new Error('boom'))
+
+      const res = await postWithRequestId(inbound)
+      const body = await res.json()
+
+      expect(res.status).toBe(500)
+      expect(body.requestId).not.toBe(inbound)
+      expect(body.requestId).toMatch(/^[A-Za-z0-9-]{36}$/)
+    })
+
+    it('reports the error to telemetry with the same requestId', async () => {
+      commandBus.execute.mockRejectedValue(new Error('boom'))
+
+      const res = await postWithRequestId('req-fixed-123')
+      const body = await res.json()
+
+      expect(body.requestId).toBe('req-fixed-123')
+      expect(reportError).toHaveBeenCalledTimes(1)
+      expect(reportError).toHaveBeenCalledWith(
+        expect.any(Error),
+        { module: 'crud', attributes: { requestId: 'req-fixed-123', errorName: 'Error' } },
+      )
+    })
+
+    // The 503/422 branches deliberately stay outside this change (issue #5608) — lock that
+    // in so a later refactor cannot quietly widen the correlation id across every branch.
+    it('leaves the interceptor-rejection branch without a requestId', async () => {
+      commandBus.execute.mockRejectedValue(
+        new CommandInterceptorError('Missing required fields: VAT id', { status: 422 }),
+      )
+
+      const res = await postWithRequestId('req-fixed-123')
+
+      expect(res.status).toBe(422)
+      await expect(res.json()).resolves.toEqual({ error: 'Missing required fields: VAT id' })
+      expect(res.headers.get('x-request-id')).toBeNull()
     })
   })
 

package/src/lib/crud/factory.ts

@@ -75,6 +75,8 @@ import { createGenericOptimisticLockReader } from './optimistic-lock'
 import { registerOptimisticLockReaderIfAbsent } from './optimistic-lock-store'
 import { createLogger } from '../logger'
 import { isTransientDbError } from '../db/pg-errors'
+import { getTelemetryRuntime } from '../telemetry/runtime'
+import { randomUUID } from 'node:crypto'
 
 type RbacServiceLike = {
   getGrantedFeatures: (userId: string, opts: { tenantId: string | null; organizationId: string | null }) => Promise<string[]>
@@ -594,7 +596,19 @@ function attachOperationHeader(res: Response, logEntry: any) {
   return res
 }
 
-function handleError(err: unknown): Response {
+// An inbound `x-request-id` is caller-controlled, so it is only reused when it still
+// looks like an id. `Headers.get()` yields '' for an empty or whitespace-only header —
+// which `??` would not replace — and an unbounded value carrying spaces or `=` would
+// forge fields in the unquoted `key=value` log line this id exists to be read from.
+const INBOUND_REQUEST_ID_PATTERN = /^[A-Za-z0-9._-]{1,128}$/
+
+function resolveRequestId(request?: Request): string {
+  const inbound = request?.headers.get('x-request-id')?.trim()
+  if (inbound && INBOUND_REQUEST_ID_PATTERN.test(inbound)) return inbound
+  return randomUUID()
+}
+
+function handleError(err: unknown, request?: Request): Response {
   if (err instanceof Response) return err
   if (isCrudHttpError(err)) return json(err.body, { status: err.status })
   // A command interceptor that blocked with an explicit status is a deliberate business
@@ -618,14 +632,25 @@ function handleError(err: unknown): Response {
     )
   }
 
+  // Unexpected exceptions still collapse into a generic 500 for the client (no internal
+  // detail leaked), but a requestId ties that response to this log line and to whatever
+  // reaches APM, so a client/support ticket citing it can be correlated with server-side
+  // detail (issue #5608).
   const message = err instanceof Error ? err.message : undefined
   const stack = err instanceof Error ? err.stack : undefined
-  logger.error('Unexpected CRUD error', { message, stack, err })
+  const errorName = err instanceof Error ? err.name : undefined
+  const requestId = resolveRequestId(request)
+  logger.error('Unexpected CRUD error', { message, stack, err, requestId })
+  getTelemetryRuntime()?.reportError(err, {
+    module: 'crud',
+    attributes: { requestId, errorName },
+  })
   const body: Record<string, unknown> = {
     error: 'Internal server error',
     message: 'Something went wrong. Please try again later.',
+    requestId,
   }
-  return json(body, { status: 500 })
+  return json(body, { status: 500, headers: { 'x-request-id': requestId } })
 }
 
 const LIFECYCLE_ACTION_MAP: Record<string, { before: string; after: string }> = {
@@ -2163,7 +2188,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
       return response
     } catch (e) {
       finishProfile({ result: 'error' })
-      return handleError(e)
+      return handleError(e, request)
     }
   }
 
@@ -2477,7 +2502,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
       payload = await enrichSingleRecord(payload, ctx)
       return json(payload, { status: 201 })
     } catch (e) {
-      return handleError(e)
+      return handleError(e, request)
     }
   }
 
@@ -2815,7 +2840,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
       }
       return json(payload)
     } catch (e) {
-      return handleError(e)
+      return handleError(e, request)
     }
   }
 
@@ -3104,7 +3129,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
       }
       return json(payload)
     } catch (e) {
-      return handleError(e)
+      return handleError(e, request)
     }
   }