Protox

When decoding, Protox retains fields present on the wire that do not correspond to the protobuf definition (unknown fields). This ensures forward compatibility.

To access these fields, use the unknown_fields/1 function on the decoded message. It returns a list of {tag, wire_type, bytes} tuples.

# Accessing unknown fields
msg = Msg.decode!(<<8, 42, 42, 4, 121, 97, 121, 101, 136, 241, 4, 83>>)
fields = Msg.unknown_fields(msg)
# Returns: [{5, 2, <<121, 97, 121, 101>>]}]

By default, the module in which use Protox is called is ignored in the generated module names. To nest generated modules under a specific prefix, use the namespace: option.

Protox also honors the package directive in .proto files, converting package abc.def; to the Elixir module Abc.Def.

defmodule Bar do
  use Protox, 
    schema: """
    syntax = "proto3";
    package abc;
    message Msg { int32 a = 1; }
    """,
    namespace: __MODULE__
end

# Resulting module: Bar.Abc.Msg
msg = %Bar.Abc.Msg{a: 42}

When reading profiling output, keep these two rules in mind:

1. Hot functions are at the bottom: Rows are sorted ascending. Use tail instead of head to find the most impactful functions.
2. Encoding vs. Decoding attribution:
   • Encode profiles provide per-field attribution (e.g., encode_<field>/2).
   • Decode profiles do not provide per-field attribution because the decoder uses a single self-recursive parse_key_value/2 function. To get a type-level breakdown for decoding, use --profile-scope codec combined with edge_* inputs to isolate specific paths.

When using the Protox macro, note the following changes to configuration options:

• :path is removed: Use the :paths option instead. It expects a list, so provide a list containing a single path: paths: ["path/to/schema.proto"].
• :keep_unknown_fields is removed: Unknown fields are now always kept by default. If you do not want to process them, you must ignore them in your application logic.

The benchmark corpus is stored in ./benchmark/benchmark_payloads.bin. It is a compressed :erlang.term_to_binary map of input_name => {module, [{message, size, bytes}]}.

Commands:

• Regenerate payloads: mix protox.benchmark.generate.payloads.
  • Warning: Generation is not seeded. Regenerating will produce a different corpus and make previous .benchee files incomparable.
• Add a new .proto: Add the file to the list in compile_benchmark_protos.ex. This ensures the file is registered as an @external_resource and triggers a recompile on edits.

You can define your protobuf schemas directly within an Elixir module using the Protox macro. This generates Elixir structs for your messages.

Using an inlined schema

Pass the schema string to the schema: option in the use Protox macro.

Using external files

Pass a list of file paths to the files: option.

Specifying include paths

Use the paths: option to specify directories where Protox should search for imports (equivalent to the -I option in protoc).

# Inlined schema
defmodule MyModule do
  use Protox, schema: """
  syntax = "proto3";
  message Baz { }
  message Foo {
    int32 a = 1;
    map<int32, Baz> b = 2;
  }
  """
end

# Using files and include paths
defmodule Baz do
  use Protox,
    files: [
      "./defs1/prefix/foo.proto",
      "./defs1/prefix/bar.proto"
    ],
    paths: [
      "./defs1"
    ]
end

Add :protox to your mix.exs dependencies.

Prerequisites:

• Elixir >= 1.15 and OTP >= 26
• protoc >= 3.0 must be available in your $PATH (required at compile-time only).

def deps do
  [{:protox, "~> 2.0"}]
end

In version 2, Protox.encode/1 returns a tuple containing the encoded data and the size of that data. If you do not require the size, you can ignore the third element of the tuple using pattern matching.

{:ok, iodata, _iodata_size} = Protox.encode(msg)

Use mix protox.benchmark.report to compare benchmark runs. This command prints a comparison to the console and generates an HTML report in ./benchmark/output/html/.

Note: Benchee matches scenarios across runs by input name. If you rename an input, the suites will be incomparable.

mix protox.benchmark.report ./benchmark/output/benchee/encode-*