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

Decodes a MessagePack binary into an Elixir term.

Returns {:ok, term} on success, or {:error, reason} on failure.

Options

• :max_depth - Sets a limit on the nesting level of arrays and maps to prevent stack exhaustion from maliciously crafted inputs. Defaults to 100.

• :max_byte_size - Sets a limit on the declared byte size of any single string, binary, array, or map to prevent memory exhaustion attacks. Defaults to 10_000_000 (10MB).

Examples

Standard Decoding

For trusted inputs, you can decode directly without custom options.

iex> encoded = <<0x81, 0xA5, "hello", 0xA5, "world">>
iex> Msgpack.decode(encoded)
{:ok, %{"hello" => "world"}}

Securely Handling Untrusted Input

When decoding data from an external source, set limits to prevent denial-of-service attacks.

A deeply nested payload may exhaust the process stack:

iex> payload = <<0x91, 0x91, 0x91, 1>> # [[[1]]]
iex> Msgpack.decode(payload, max_depth: 2)
{:error, {:max_depth_reached, 2}}

A payload declaring a huge string can cause excessive memory allocation:

iex> payload = <<0xDB, 0xFFFFFFFF::32>> # A string of 4GB
iex> Msgpack.decode(payload, max_byte_size: 1_000_000)
{:error, {:max_byte_size_exceeded, 1_000_000}}

Detecting Malformed Data

The decoder will return an error tuple for malformed data, such as incomplete data or trailing bytes left over after a successful decode.

# A valid term followed by extra bytes
iex> Msgpack.decode(<<192, 42>>)
{:error, {:trailing_bytes, <<42>>}}

# Incomplete map data
iex> Msgpack.decode(<<0x81, 0xA3, "foo">>)
{:error, :unexpected_eof}

@spec decode!(
  binary(),
  keyword()
) :: term()

Decodes a MessagePack binary, raising a Msgpack.DecodeError on failure.

This variant raises an exception on failure. It is intended for use when a decoding failure is considered an exceptional state, for example, when decoding data from a trusted internal service that is assumed to be well-formed.

For decoding data from external or untrusted sources where failure is a possible outcome, use decode/2 to handle the returned {:error, reason} tuple.

Options

Accepts the same options as decode/2.

Raises

• Msgpack.DecodeError - If the binary is malformed, contains an unknown prefix, or has trailing bytes.

Examples

Basic success case:

iex> encoded = <<0x81, 0xA5, "hello", 0xA5, "world">>
iex> Msgpack.decode!(encoded)
%{"hello" => "world"}

Failure case:

iex> Msgpack.decode!(<<192, 42>>)
** (Msgpack.DecodeError) Failed to decode MessagePack binary. Reason = {:trailing_bytes, "*"}

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

Encodes an Elixir term into a MessagePack binary.

Returns {:ok, binary} on success, or {:error, reason} on failure.

Options

• :atoms - Controls how atoms are encoded.

  • :string (default) - Encodes atoms as MessagePack strings.
  • :error - Returns an {:error, {:unsupported_atom, atom}} tuple if an atom is encountered.

• :string_validation - Controls whether to perform UTF-8 validation on binaries.

  • true (default) - Validates binaries and encodes them as the str type if they are valid UTF-8, otherwise encodes them as the bin type. This ensures the output is compliant with the MessagePack specification's distinction between string and binary data, but has a performance cost.
  • false - Skips validation and encodes all binaries as the str type. This avoids the performance cost of validation but risks creating a payload with non-UTF-8 strings, which may be incompatible with other MessagePack decoders.

Examples

Standard Encoding

The default options encode atoms as strings, a common requirement when sending data between Elixir services.

iex> data = %{id: 1, name: "Elixir"}
iex> {:ok, encoded} = Msgpack.encode(data)
iex> Msgpack.decode(encoded)
{:ok, %{"id" => 1, "name" => "Elixir"}}

Strict Atom Handling

If you are interoperating with systems that do not have a concept of atoms, it is safer to disallow them completely during encoding.

iex> Msgpack.encode(%{name: "Elixir"}, atoms: :error)
{:error, {:unsupported_atom, :name}}

Encoding without String Validation (Unsafe)

For performance-critical paths where you can guarantee all binaries are valid UTF-8 strings, you can disable string validation.

iex> data = "What did the fish say when it swam into a wall? Dam!"
iex> {:ok, _} = Msgpack.encode(data, string_validation: false)

Encoding Raw Binary Data

If your data contains non-UTF-8 binary content (e.g., an image thumbnail), the default validator will encode it with the bin family type.

iex> Msgpack.encode(<<255, 128, 0>>)
{:ok, <<0xC4, 3, 255, 128, 0>>}

@spec encode!(
  term(),
  keyword()
) :: binary()

Encodes an Elixir term into a MessagePack binary, raising an error on failure.

This variant raises an exception on failure instead of returning an error tuple. It is intended for use in pipelines (|>) or in functions where an encoding failure is considered an exceptional event to be handled by try/rescue.

Options

Accepts the same options as encode/2.

Raises

• Msgpack.EncodeError - If an unsupported Elixir term is encountered.
• Msgpack.UnsupportedAtomError - If an atom is encountered and the :atoms option is set to :error.

Examples

iex> Msgpack.encode!(%{hello: "world"})
<<129, 165, 104, 101, 108, 108, 111, 165, 119, 111, 114, 108, 100>>