Release v1.0.0 (#1)

Author: nrednav

.tool-versions

@@ -1 +1 @@
-local elixir 1.12.0-otp-24
+local elixir 1.18.4-otp-28

CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [v0.1.0] - 2025-08-02
+## [v1.0.0] - 2025-08-02
 
-- First release
+### Added
+
+- Initial release
+- Support for all MessagePack types, including `Integer`, `Float`, `String`,
+  `Binary`, `Array`, `Map`, `Ext`, and the `Timestamp` extension
+  - Encoding for the full 64-bit unsigned integer range
+- Native encoding and decoding for Elixir's `DateTime` and `NaiveDateTime`
+  structs
+- Protection against maliciously crafted decoding inputs via `:max_depth` and
+  `:max_byte_size` options
+- Added a `:string_validation` option to `encode/2` to bypass UTF-8 validation
+  for performance gains
+- Emits `:telemetry` events for all encode and decode operations
+- Includes `encode!/2` and `decode!/2` for raising exceptions on errors

README.md

@@ -1,14 +1,194 @@
 # msgpack_elixir
 
+[![Hex.pm](https://img.shields.io/hexpm/v/msgpack_elixir.svg)](https://hex.pm/packages/msgpack_elixir)
+
+A [MessagePack](https://msgpack.org/) serialization library for Elixir.
+
+## Features
+
+- **Full Specification Compliance:** Adheres to the MessagePack specification to
+  ensure compatibility with other MessagePack implementations
+  - Includes support for types such as `Booleans`, `Integers`, `Floats`, `Tuples`,
+    `Lists`, `Maps`, `Strings`, `Binaries`, `Extensions`, and `Timestamps`
+  - Encodes and decodes Elixir's `DateTime` and `NaiveDateTime` structs using
+    the MessagePack `Timestamp` extension
+- **Performant Encoding:** Implements efficient encoding for collections and
+  provides a `:string_validation` option to bypass UTF-8 validation in
+  performance-sensitive applications
+- **Exception-raising Variants:** Includes bang (`!`) variants like `encode!/2`
+  and `decode!/2` for contexts where raising an exception is preferred over
+  error tuples
+- **Telemetry Integration:** Emits standard `:telemetry` events for all encode
+  and decode operations, allowing for easy integration into monitoring and
+  observability tools
+
 ## Installation
 
-The package can be installed by adding `msgpack_elixir` to your list of
-dependencies in `mix.exs`:
+Add `msgpack_elixir` to your list of dependencies in `mix.exs`:
 
 ```elixir
 def deps do
-  [
-    {:msgpack_elixir, "~> 0.1.0"}
-  ]
+  [{:msgpack_elixir, "~> 1.0.0"}]
 end
 ```
+
+Then, run `mix deps.get`.
+
+## Usage
+
+### Basic Operations
+
+The library returns `{:ok, value}` tuples for successful operations and
+`{:error, reason}` tuples for failures.
+
+```elixir
+# Encode a map
+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"}}
+```
+
+### Exception-raising Operations
+
+If you prefer an exception to be raised on failure, use the bang (`!`) variants.
+
+```elixir
+iex> encoded = Msgpack.encode!(%{id: 1})
+<<129, 162, 105, 100, 1>>
+
+iex> Msgpack.decode!(<<192, 42>>)
+** (Msgpack.DecodeError) Failed to decode MessagePack binary. Reason = {:trailing_bytes, <<42>>}
+```
+
+## Options
+
+The following options can be passed as a second argument to the `encode` and
+`decode` functions.
+
+### For `encode/2`
+
+- `: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; encodes as `str` type if valid UTF-8,
+    `bin` type otherwise
+  - `false` - Skips validation and encodes all binaries as the `str` type.
+    Improves performance but should only be used if you are certain your data is
+    valid
+
+### For `decode/2`
+
+- `:max_depth`
+  - Sets a limit on the nesting level of arrays and maps to prevent stack
+    exhaustion attacks
+  - 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)
+
+## Telemetry
+
+The library emits `:telemetry` events which can be used for monitoring or
+logging.
+
+- `[:msgpack, :encode]` - Dispatched when `Msgpack.encode/2` is called
+- `[:msgpack, :decode]` - Dispatched when `Msgpack.decode/2` is called
+
+Example of attaching a logger:
+
+```elixir
+defmodule MyTelemetryHandler do
+  require Logger
+
+  def attach do
+    :telemetry.attach(
+      "msgpack-logger",
+      [:msgpack, :encode],
+      &__MODULE__.handle_event/4,
+      nil
+    )
+  end
+
+  def handle_event(event_name, measurements, metadata, _config) do
+    Logger.info("Telemetry Event: #{inspect(event_name)}",
+      measurements: measurements,
+      metadata: metadata
+    )
+  end
+end
+```
+
+## Development
+
+This section explains how to setup the project locally for development.
+
+### Dependencies
+
+- Elixir `~> 1.7` (OTP 21+)
+
+### Get the Source
+
+Clone the project locally:
+
+```bash
+# 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:
+
+```bash
+cd msgpack_elixir/
+mix deps.get
+```
+
+### Test
+
+Run the test suite:
+
+```bash
+mix test
+```
+
+### Benchmark
+
+Run the benchmarks:
+
+```bash
+mix run bench/run.exs
+```
+
+## Versioning
+
+This project uses [Semantic Versioning](https://semver.org/).
+For a list of available versions, see the [repository tag list](https://github.com/nrednav/msgpack_elixir/tags).
+
+## Issues & Requests
+
+If you encounter a bug or have a feature request, please [open an
+issue](https://github.com/nrednav/msgpack_elixir/issues) 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](./LICENSE)
+file for details.

bench/decode_bench.exs

@@ -0,0 +1,22 @@
+defmodule Bench.Decode do
+  def run do
+    IO.puts("\n--- Benchmarking Msgpack.decode!/2 ---")
+
+    encoded_inputs = Bench.Encode.prepare_decode_inputs()
+
+    Benchee.run(
+      %{
+        "Decode" => fn encoded_binary ->
+          Msgpack.decode!(encoded_binary)
+        end
+      },
+      inputs: encoded_inputs,
+      time: 5,
+      memory_time: 2,
+      warmup: 2,
+      formatters: [Benchee.Formatters.Console]
+    )
+  end
+end
+
+Bench.Decode.run()

bench/encode_bench.exs

@@ -0,0 +1,54 @@
+defmodule Bench.Encode do
+  @inputs %{
+    "Small Map" => %{
+      "id" => 123,
+      "name" => "Msgpack Elixir",
+      "is_awesome" => true,
+      "version" => 1.0
+    },
+    "Large List" => Enum.to_list(1..1000),
+    "Large Map" => Map.new(1..1000, &{&1, &1 * 2}),
+    "Nested Data" => %{
+      "user_id" => 456,
+      "data" => [
+        %{
+          "event" => "login",
+          "timestamp" => NaiveDateTime.utc_now(),
+          "details" => %{"ip" => "127.0.0.1"}
+        }
+      ]
+    },
+    "Large Binary" => %{
+      "key" => "data",
+      "payload" => :crypto.strong_rand_bytes(10_000)
+    }
+  }
+
+  def run do
+    IO.puts("\n--- Benchmarking Msgpack.encode!/2 ---")
+
+    Benchee.run(
+      %{
+        "Encode (Default)" => fn input ->
+          Msgpack.encode!(input)
+        end,
+        "Encode (Optimized)" => fn input ->
+          Msgpack.encode!(input, string_validation: false)
+        end
+      },
+      inputs: @inputs,
+      time: 5,
+      memory_time: 2,
+      warmup: 2,
+      formatters: [Benchee.Formatters.Console]
+    )
+  end
+
+  def prepare_decode_inputs do
+    for {name, term} <- @inputs, into: %{} do
+      {name, Msgpack.encode!(term)}
+    end
+  end
+end
+
+Bench.Encode.run()

bench/run.exs

@@ -0,0 +1,10 @@
+Mix.Task.run("compile")
+
+IO.puts("--- Running MessagePack Benchmark Suite ---")
+IO.puts("Loading benchmark files...")
+
+bench_path = __DIR__
+
+Path.join(bench_path, "encode_bench.exs") |> Code.require_file()
+Path.join(bench_path, "decode_bench.exs") |> Code.require_file()
+Path.join(bench_path, "string_validation_bench.exs") |> Code.require_file()

bench/string_validation_bench.exs

@@ -0,0 +1,23 @@
+defmodule Bench.StringValidation do
+  @large_string String.duplicate("a", 10_000)
+
+  def run do
+    IO.puts("==== Benchmarking String Validation ====")
+    IO.puts("Compares default encoding vs. encoding with string_validation: false")
+
+    Benchee.run(
+      %{
+        "Default (with validation)" => fn ->
+          Msgpack.encode!(@large_string, string_validation: true)
+        end,
+        "Fast Path (without validation)" => fn ->
+          Msgpack.encode!(@large_string, string_validation: false)
+        end,
+      },
+      time: 5,
+      memory_time: 2
+    )
+  end
+end
+
+Bench.StringValidation.run()