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
MqttX.Payload.Raw- Pass-through, no encoding, declares nothingMqttX.Payload.JSON- JSON via the OTP 27+ built-inJSONmodule; declarespayload_format_indicator: 1,content_type: "application/json"MqttX.Payload.Protobuf- Protocol Buffers via Protox; declarescontent_type: "application/protobuf"
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
@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 a binary to a term.
Encode a term to binary.
@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 using the specified codec.
Encode using the specified codec.
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.
The codec's metadata/0, or %{} if it does not define one.