Msgpax v1.1.0 Msgpax.Ext

A struct used to represent the MessagePack Extension type.


Let’s say we want to be able to serialize a custom type that consists of a byte data repeated reps times. We could represent this as a RepByte struct in Elixir:

defmodule RepByte do
  defstruct [:data, :reps]

A simple (albeit not space efficient) approach to encoding such data is simply a binary containing data for reps times: %RepByte{data: ?a, reps: 2} would be encoded as "aa".

We can now define the Msgpax.Packer protocol for the RepByte struct to tell Msgpax how to encode this struct (we’ll choose 10 as an arbitrary integer to identify the type of this extension).

defimpl Msgpax.Packer, for: RepByte do
  def pack(%RepByte{data: b, reps: reps}) do, String.duplicate(<<b>>, reps))
    |> Msgpax.Packer.pack()

Now, we can pack RepBytes:

iex> packed = Msgpax.pack!(%RepByte{data: ?a, reps: 3})
iex> Msgpax.unpack!(packed)
#Msgpax.Ext<10, "aaa">


As seen in the example above, since the RepByte struct is packed as a MessagePack extension, it will be unpacked as that extension later on; what we may want, however, is to unpack that extension back to a RepByte struct.

To do this, we can pass an :ext option to Msgpax.unpack/2 (and other unpacking functions). This option has to be a module that implements the Msgpax.Ext.Unpacker behaviour; it will be used to unpack extensions to arbitrary Elixir terms.

For our RepByte example, we could create an unpacker module like this:

defmodule MyExtUnpacker do
  @behaviour Msgpax.Ext.Unpacker
  @rep_byte_ext_type 10

  def unpack(%Msgpax.Ext{type: @rep_byte_ext_type, data: data}) do
    <<byte, _rest::binary>> = data
    {:ok, %RepByte{data: byte, reps: byte_size(data)}}

With this in place, we can now unpack a packed RepByte back to a RepByte struct:

iex> packed = Msgpax.pack!(%RepByte{data: ?a, reps: 3})
iex> Msgpax.unpack!(packed, ext: MyExtUnpacker)
%RepByte{data: ?a, reps: 3}



Creates a new Msgpax.Ext struct


t :: %Msgpax.Ext{data: binary, type: type}
type :: 0..127


new(type, data)

Creates a new Msgpax.Ext struct.

type must be an integer in 0..127 and it will be used as the type of the extension (whose meaning depends on your application). data must be a binary containing the serialized extension (whose serialization depends on your application).


iex>, "foo")
#Msgpax.Ext<24, "foo">