MqttRecordOptions

Kind: Interface

Source: packages/microservices/record-builders/mqtt.record-builder.ts

Part of: 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

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:35-39

• 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
• 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
• 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

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 build() passes the accumulated options to a new MqttRecord. packages/microservices/record-builders/mqtt.record-builder.ts:87-89

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:271-286 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 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