Skip to content

README.md

Latest commit

 

History

History
150 lines (105 loc) · 3.89 KB

README.md

File metadata and controls

150 lines (105 loc) · 3.89 KB

msgpack_elixir

Hex.pm

An implementation of the MessagePack serialization format for Elixir.

It provides functions for encoding and decoding Elixir terms and supports the full MessagePack specification, including the Timestamp and custom Extension types.

Features

  • Specification Compliance: Implements the complete MessagePack type system.
  • Elixir Struct Support: Encodes and decodes DateTime and NaiveDateTime structs via the Timestamp extension type.
  • Configurable Validation: Provides an option to bypass UTF-8 validation on strings for performance-critical paths.
  • Resource Limiting: Includes configurable :max_depth and :max_byte_size limits to mitigate resource exhaustion from malformed or malicious payloads.
  • Telemetry Integration: Emits standard :telemetry events for integration with monitoring tools.
  • Streaming API: Process large collections or continuous data streams with low memory overhead using Msgpack.encode_stream/2 and Msgpack.decode_stream/2.

Installation

Add msgpack_elixir to your list of dependencies in mix.exs:

def deps do
  [{:msgpack_elixir, "~> 1.0.0"}]
end

Then, run mix deps.get.

Quick Start

# Encode a map. Atom keys are converted to strings by default.
iex> data = %{id: 1, name: "Elixir"}
iex> {:ok, encoded} = Msgpack.encode(data)
<<130, 162, 105, 100, 1, 164, 110, 97, 109, 101, 166, 69, 108, 105, 120, 105, 114>>

# Decode a binary.
iex> Msgpack.decode(encoded)
{:ok, %{"id" => 1, "name" => "Elixir"}}

# Use the exception-raising variants for exceptional failure cases.
iex> Msgpack.decode!(<<0xC1>>)
** (Msgpack.DecodeError) Unknown type prefix: 193. The byte `0xC1` is not a valid MessagePack type marker.

Streaming Large Collections

For datasets that may not fit in memory, you can use the streaming API, which processes one term at a time.

# Create a lazy stream of terms to be encoded.
iex> terms = Stream.cycle([1, "elixir", true])

# The output is a lazy stream of encoded binaries.
iex> encoded_stream = Msgpack.encode_stream(terms)

# The stream is only consumed when you enumerate it.
iex> encoded_stream |> Stream.take(3) |> Enum.to_list()
[
  {:ok, <<1>>},
  {:ok, <<166, 101, 108, 105, 120, 105, 114>>},
  {:ok, <<195>>}
]

Full Documentation

For detailed information on all features, options, and functions, see the full documentation on HexDocs, which contains a complete API reference for all public modules and functions.

Development

This section explains how to setup the project locally for development.

Dependencies

Get the Source

Clone the project locally:

# via HTTPS
git clone https://github.com/nrednav/msgpack_elixir.git

# via SSH
git clone git@github.com:nrednav/msgpack_elixir.git

Install

Install the project's dependencies:

cd msgpack_elixir/
mix deps.get

Test

Run the test suite:

mix test

Benchmark

Run the benchmarks:

mix run bench/run.exs

Versioning

This project uses Semantic Versioning. For a list of available versions, see the repository tag list.

Issues & Requests

If you encounter a bug or have a feature request, please open an issue on the GitHub repository.

Contributing

Public contributions are welcome! If you would like to contribute, please fork the repository and create a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.