MqttX.Payload behaviour (MqttX v0.13.0)

Copy Markdown View Source

Behaviour for payload codecs.

Payload codecs handle encoding and decoding of MQTT message payloads, and declare what they produce — the MQTT 5.0 Payload Format Indicator and Content Type (§3.3.2.3.2, §3.3.2.3.9) — so a publish can carry both without the caller spelling them out.

Built-in Codecs

Publishing with a codec

Pass codec: to MqttX.Client.publish/4 (or the publish/3 injected by use MqttX), and the payload is a term:

MqttX.Client.publish(client, "sensors/room1", %{temp: 21.5},
  qos: 1,
  codec: MqttX.Payload.JSON
)

The term is encoded in the calling process, and the codec's metadata/0 is merged into the PUBLISH properties underneath any you pass explicitly. A broker handler can do the same from handle_info/2 with {:publish, topic, term, %{qos: 1, codec: MqttX.Payload.JSON}, state}. On the receiving side content_type arrives in the packet's properties, so a handler can pick the codec to decode/1 with.

Custom Codec Example

defmodule MyCodec do
  @behaviour MqttX.Payload

  @impl true
  def encode(term) do
    {:ok, :erlang.term_to_binary(term)}
  end

  # [:safe]: the bytes come from the network; without it a peer could
  # fill the atom table or send funs. Even so, External Term Format is
  # for payloads from peers you trust.
  @impl true
  def decode(binary) do
    {:ok, :erlang.binary_to_term(binary, [:safe])}
  rescue
    ArgumentError -> {:error, :not_a_term}
  end

  # Optional: what to tell receivers about the bytes
  @impl true
  def metadata, do: %{content_type: "application/x-erlang-binary"}
end

Summary

Types

What a codec declares about its output, as PUBLISH properties: :payload_format_indicator is 1 when the bytes are UTF-8 text (§3.3.2.3.2), :content_type a MIME type (§3.3.2.3.9).

Callbacks

Decode a binary to a term.

Encode a term to binary.

Properties describing this codec's encoding, merged into every PUBLISH sent with codec: __MODULE__. Optional — a codec that does not define it declares nothing.

Functions

Decode using the specified codec.

Encode using the specified codec.

Encode term with codec for publishing.

The codec's metadata/0, or %{} if it does not define one.

Types

metadata()

@type metadata() :: %{
  optional(:payload_format_indicator) => 0 | 1,
  optional(:content_type) => String.t()
}

What a codec declares about its output, as PUBLISH properties: :payload_format_indicator is 1 when the bytes are UTF-8 text (§3.3.2.3.2), :content_type a MIME type (§3.3.2.3.9).

Callbacks

decode(binary)

@callback decode(binary()) :: {:ok, term()} | {:error, term()}

Decode a binary to a term.

encode(term)

@callback encode(term()) :: {:ok, binary()} | {:error, term()}

Encode a term to binary.

metadata()

(optional)
@callback metadata() :: metadata()

Properties describing this codec's encoding, merged into every PUBLISH sent with codec: __MODULE__. Optional — a codec that does not define it declares nothing.

Functions

decode(codec, binary)

@spec decode(module(), binary()) :: {:ok, term()} | {:error, term()}

Decode using the specified codec.

encode(codec, term)

@spec encode(module(), term()) :: {:ok, binary()} | {:error, term()}

Encode using the specified codec.

encode_with(codec, term, properties \\ %{})

@spec encode_with(module(), term(), map() | nil) ::
  {:ok, binary(), map()} | {:error, term()}

Encode term with codec for publishing.

Returns the binary payload and properties with the codec's metadata merged underneath — an explicit :content_type or :payload_format_indicator in properties wins. Encoding errors are the codec's, unchanged.

metadata(codec)

@spec metadata(module()) :: metadata()

The codec's metadata/0, or %{} if it does not define one.