Skip to content

CorrelationOptions

Defined in: options/correlation.options.ts:49

Correlation ID configuration consumed by httpCorrelation.

The middleware is registered explicitly by the application. For non-HTTP transports (Bull, RabbitMQ, etc.), use runWithCorrelationId() directly in your processor/handler.

An incoming header value is accepted only when it passes the rules configureCorrelation sets, by default at most DEFAULT_CORRELATION_ID_MAX_LENGTH characters matching DEFAULT_CORRELATION_ID_PATTERN; otherwise a local ID is used. maxLength and validateIncoming replace those rules for this middleware.

// Custom header name
{ header: 'x-request-id' }

// `header: false` selects the default header; it does not disable the middleware.
{ header: false } // uses 'x-correlation-id'

Accept only UUIDs from clients

{
  maxLength: 36,
  trimIncoming: true,
  validateIncoming: (id) => /^[0-9a-f-]{36}$/i.test(id),
}

Ignore client IDs completely and always generate/use the local ID

{ acceptIncoming: false }

optional acceptIncoming?: boolean

Defined in: options/correlation.options.ts:67

Whether a non-empty incoming correlation ID may be used. Set to false when correlation IDs are internal-only and should never be controlled by the HTTP client.

true

optional header?: string | false

Defined in: options/correlation.options.ts:58

HTTP header name to extract the correlation ID from. A valid, non-empty HTTP field-name string selects that header. Invalid strings throw during middleware construction. Any non-string value, including false and undefined, makes the middleware use the default x-correlation-id header.

'x-correlation-id'

optional maxLength?: number

Defined in: options/correlation.options.ts:83

Maximum accepted incoming correlation-ID length. Longer values are discarded and replaced by the locally resolved/generated ID.

the maxLength of configureCorrelation, 128 unless configured


optional trimIncoming?: boolean

Defined in: options/correlation.options.ts:75

Trim surrounding whitespace before optional length/custom validation and before storing/echoing the ID.

false

optional validateIncoming?: (correlationId) => boolean

Defined in: options/correlation.options.ts:100

Validation predicate for incoming IDs; replaces the validateIncoming of configureCorrelation, by default the DEFAULT_CORRELATION_ID_PATTERN check. Returning false (or throwing) rejects the incoming value and falls back to the local correlation ID. maxLength still applies, and the predicate sees only values of printable ASCII (0x20 to 0x7E) that neither start nor end with a space.

string

boolean

{
  validateIncoming: (id) => /^[A-Za-z0-9._-]+$/.test(id),
}