# MqttRecordOptions

**Kind:** Interface

**Source:** [`packages/microservices/record-builders/mqtt.record-builder.ts`](https://github.com/nestjs/nest/blob/master/packages/microservices/record-builders/mqtt.record-builder.ts#L4)

**Part of:** [Microservices](subsystem-packages-microservices)

`MqttRecordOptions` defines MQTT-specific delivery and message metadata used when building MQTT records in the microservices layer. It controls QoS, retained and duplicate delivery flags, and MQTT v5 properties such as expiry intervals, response topics, correlation data, and user properties.

## Properties

| Property | Type |
|---|---|
| `qos` | `0 | 1 | 2` |
| `retain` | `boolean` |
| `dup` | `boolean` |
| `properties` | `{ payloadFormatIndicator?: boolean; messageExpiryInterval?: number; topicAlias?: number; responseTopic?: string; correlationData?: Buffer; userProperties?: Record<string, string | string[]>; subscriptionIdentifier?: number; contentType?: string; }` |

## Diagram

```mermaid
graph LR
  Builder[Mqtt Record Builder] --> Options[MqttRecordOptions]
  Options --> Delivery[Delivery Flags]
  Options --> Properties[MQTT v5 Properties]

  Delivery --> QoS["qos: 0 | 1 | 2"]
  Delivery --> Retain["retain: boolean"]
  Delivery --> Dup["dup: boolean"]

  Properties --> PayloadFormat[payloadFormatIndicator]
  Properties --> Expiry[messageExpiryInterval]
  Properties --> Response[responseTopic]
  Properties --> Correlation[correlationData]
  Properties --> UserProps[userProperties]
```

## Usage

```ts
import type { MqttRecordOptions } from './mqtt.record-builder';

const options: MqttRecordOptions = {
  qos: 1,
  retain: false,
  dup: false,
  properties: {
    contentType: 'application/json',
    messageExpiryInterval: 300,
    responseTopic: 'devices/device-123/responses',
    correlationData: Buffer.from('request-abc'),
    userProperties: {
      source: 'api',
      tags: ['telemetry', 'priority'],
    },
  },
};

// Pass options to the MQTT record builder or publishing workflow.
```

## AI Coding Instructions

- Use `qos` values only from the supported MQTT levels: `0`, `1`, or `2`.
- Set `retain` only when the broker should store the message as the topic's latest retained value.
- Preserve `dup` when retrying an MQTT delivery; do not use it to indicate an application-level duplicate payload.
- Keep MQTT v5 metadata inside `properties`, including response/correlation fields for request-response flows.
- Use `Buffer` for `correlationData` and allow `userProperties` values to be either a single string or an array of strings.

## How it works

`MqttRecordOptions` is an exported, public TypeScript interface for optional MQTT publish settings attached to an `MqttRecord`. [`packages/microservices/record-builders/mqtt.record-builder.ts:1-4`](packages/microservices/record-builders/mqtt.record-builder.ts#L1-L4) [`packages/microservices/record-builders/mqtt.record-builder.ts:35-39`](packages/microservices/record-builders/mqtt.record-builder.ts#L35-L39)

- `qos` is optional and is typed as `0`, `1`, or `2`; `retain` and `dup` are optional booleans. [`packages/microservices/record-builders/mqtt.record-builder.ts:5-16`](packages/microservices/record-builders/mqtt.record-builder.ts#L5-L16)
- Its optional `properties` object declares `payloadFormatIndicator`, `messageExpiryInterval`, `topicAlias`, `responseTopic`, `correlationData`, `userProperties`, `subscriptionIdentifier`, and `contentType`. `userProperties` maps strings to either a string or an array of strings. [`packages/microservices/record-builders/mqtt.record-builder.ts:17-29`](packages/microservices/record-builders/mqtt.record-builder.ts#L17-L29)
- The interface declares no required members, runtime validation, or errors. Its declared type restricts `qos`, while the numeric property fields are declared as `number`. [`packages/microservices/record-builders/mqtt.record-builder.ts:4-30`](packages/microservices/record-builders/mqtt.record-builder.ts#L4-L30)

`MqttRecordBuilder` accumulates these fields through `setQoS`, `setRetain`, `setDup`, and `setProperties`; each method replaces the corresponding option while retaining previously set top-level options, then returns the builder. [`packages/microservices/record-builders/mqtt.record-builder.ts:45-85`](packages/microservices/record-builders/mqtt.record-builder.ts#L45-L85) `build()` passes the accumulated options to a new `MqttRecord`. [`packages/microservices/record-builders/mqtt.record-builder.ts:87-89`](packages/microservices/record-builders/mqtt.record-builder.ts#L87-L89)

When `ClientMqtt` sends a packet whose data is an `MqttRecord`, it reads `record.options`, deletes the record’s `options` property before serialization, and passes the options to the MQTT client’s `publish` call. [`packages/microservices/client/client-mqtt.ts:237-249`](packages/microservices/client/client-mqtt.ts#L237-L249) [`packages/microservices/client/client-mqtt.ts:271-286`](packages/microservices/client/client-mqtt.ts#L271-L286) The default MQTT record serializer serializes `record.data` as the packet’s `data`, not the options object. [`packages/microservices/serializers/mqtt-record.serializer.ts:5-14`](packages/microservices/serializers/mqtt-record.serializer.ts#L5-L14) If client-level `userProperties` are configured, `ClientMqtt` merges them with record-level `properties.userProperties`; record-level keys are spread last and therefore overwrite matching client-level keys. [`packages/microservices/client/client-mqtt.ts:303-326`](packages/microservices/client/client-mqtt.ts#L303-L326)