feat: support optional Encoder protocol for structs

Structs (maps with an atom __struct__ key) are rejected by the NIF
encoder with {:error, :unhandled_struct}; the Elixir layer then runs
the term through the Torque.Encoder protocol and retries once.

- NIF detects structs while encoding maps (zero cost when absent)
- Torque.Encoder protocol with Any fallback (opt-in per struct type)
- normalize/1 recursively encodes protocol output
- consolidation deferred to the host project so it can implement
  the protocol for its own structs (e.g. Decimal)

A struct without an implementation still fails with
:unhandled_struct — never silently dropped.

Author: gilbertwong96

lib/torque.ex

@@ -146,18 +146,24 @@ defmodule Torque do
       {:ok, ~s({"id":"abc"})}
   """
   @doc group: :encode
-  @spec encode(term(), keyword()) :: {:ok, binary()} | {:error, binary() | :nesting_too_deep}
+  @spec encode(term(), keyword()) ::
+          {:ok, binary()}
+          | {:error, binary() | :nesting_too_deep | :unhandled_struct}
   def encode(term, opts \\ [])
 
   def encode(term, []) do
-    Torque.Native.encode(term)
+    case Torque.Native.encode(term) do
+      {:error, :unhandled_struct} -> encode_retry(term, false)
+      other -> other
+    end
   end
 
   def encode(term, opts) do
-    if Keyword.get(opts, :dirty, false) do
-      Torque.Native.encode_dirty(term)
-    else
-      Torque.Native.encode(term)
+    dirty = Keyword.get(opts, :dirty, false)
+
+    case encode_native(term, dirty) do
+      {:error, :unhandled_struct} -> encode_retry(term, dirty)
+      other -> other
     end
   end
 
@@ -199,19 +205,23 @@ defmodule Torque do
   def encode_to_iodata(term, opts \\ [])
 
   def encode_to_iodata(term, []) do
-    Torque.Native.encode_iodata(term)
+    encode_iodata_native(term, false)
   catch
-    :error, value -> raise ArgumentError, "encode error: #{inspect(value)}"
+    :error, :unhandled_struct ->
+      term |> normalize() |> encode_iodata_retry(false)
+
+    :error, value ->
+      raise ArgumentError, "encode error: #{inspect(value)}"
   end
 
   def encode_to_iodata(term, opts) do
-    if Keyword.get(opts, :dirty, false) do
-      Torque.Native.encode_iodata_dirty(term)
-    else
-      Torque.Native.encode_iodata(term)
-    end
+    encode_iodata_native(term, Keyword.get(opts, :dirty, false))
   catch
-    :error, value -> raise ArgumentError, "encode error: #{inspect(value)}"
+    :error, :unhandled_struct ->
+      term |> normalize() |> encode_iodata_retry(Keyword.get(opts, :dirty, false))
+
+    :error, value ->
+      raise ArgumentError, "encode error: #{inspect(value)}"
   end
 
   @doc """
@@ -231,6 +241,137 @@ defmodule Torque do
   @spec encode_to_iodata!(term(), keyword()) :: binary()
   def encode_to_iodata!(term, opts \\ []), do: encode_to_iodata(term, opts)
 
+  # --- Encoding protocol ---
+
+  defprotocol Encoder do
+    @moduledoc """
+    Optional protocol for encoding Elixir structs as JSON.
+
+    Torque's NIF encoder rejects structs (maps carrying an atom
+    `__struct__` key) with `{:error, :unhandled_struct}`. When a struct
+    implements this protocol, `encode/1` runs it first and encodes the
+    returned term instead, recursively.
+
+    The protocol is deliberately opt-in: a struct without an
+    implementation is an error, never silently dropped fields.
+
+    ## Deriving
+
+    Structs can derive the implementation, encoding all fields or a
+    subset via `:only` / `:except`:
+
+        @derive {Torque.Encoder, only: [:id, :name]}
+        defstruct [:id, :name, :secret]
+
+        @derive {Torque.Encoder, except: [:secret]}
+        defstruct [:id, :name, :secret]
+
+    > Prefer `:only` to avoid accidentally leaking private information
+    > when new fields are added later.
+
+    ## Example
+
+        defimpl Torque.Encoder, for: Decimal do
+          def encode(decimal), do: Decimal.to_string(decimal)
+        end
+
+        Torque.encode!(%{price: Decimal.new("37.50")})
+        #=> ~s({"price":"37.50"})
+    """
+
+    @fallback_to_any true
+
+    @spec encode(term()) :: term()
+    def encode(term)
+
+    @impl true
+    defmacro __deriving__(module, opts) do
+      fields = module |> Macro.struct_info!(__CALLER__) |> Enum.map(& &1.field)
+      fields = fields_to_encode(fields, opts)
+
+      quote do
+        defimpl Torque.Encoder, for: unquote(module) do
+          def encode(struct) do
+            Map.take(struct, unquote(fields))
+          end
+        end
+      end
+    end
+
+    defp fields_to_encode(fields, opts) do
+      cond do
+        only = Keyword.get(opts, :only) ->
+          case only -- fields do
+            [] ->
+              only
+
+            error_keys ->
+              raise ArgumentError,
+                    "unknown struct fields #{inspect(error_keys)} specified in :only. " <>
+                      "Expected one of: #{inspect(fields -- [:__struct__])}"
+          end
+
+        except = Keyword.get(opts, :except) ->
+          case except -- fields do
+            [] ->
+              fields -- [:__struct__ | except]
+
+            error_keys ->
+              raise ArgumentError,
+                    "unknown struct fields #{inspect(error_keys)} specified in :except. " <>
+                      "Expected one of: #{inspect(fields -- [:__struct__])}"
+          end
+
+        true ->
+          fields -- [:__struct__]
+      end
+    end
+  end
+
+  # The Any fallback passes structs through untouched, so a struct without
+  # an explicit implementation still fails in the NIF with
+  # `:unhandled_struct` after the retry — it is never silently dropped.
+  defimpl Encoder, for: Any do
+    def encode(term), do: term
+  end
+
+  defp encode_native(term, dirty) do
+    if dirty, do: Torque.Native.encode_dirty(term), else: Torque.Native.encode(term)
+  end
+
+  defp encode_retry(term, dirty) do
+    term |> normalize() |> encode_native(dirty)
+  end
+
+  defp encode_iodata_native(term, true), do: Torque.Native.encode_iodata_dirty(term)
+  defp encode_iodata_native(term, false), do: Torque.Native.encode_iodata(term)
+
+  # Retry path: a struct that still has no protocol implementation fails
+  # with the same ArgumentError as every other encode error.
+  defp encode_iodata_retry(term, dirty) do
+    encode_iodata_native(term, dirty)
+  catch
+    :error, value -> raise ArgumentError, "encode error: #{inspect(value)}"
+  end
+
+  defp normalize(%_{} = struct) do
+    if Encoder.impl_for(struct) != Encoder.Any do
+      normalize(Encoder.encode(struct))
+    else
+      struct
+    end
+  end
+
+  defp normalize(list) when is_list(list) do
+    Enum.map(list, &normalize/1)
+  end
+
+  defp normalize(map) when is_map(map) do
+    Map.new(map, fn {k, v} -> {k, normalize(v)} end)
+  end
+
+  defp normalize(term), do: term
+
   # --- Parse + Get ---
 
   @doc """

mix.exs

@@ -10,6 +10,10 @@ defmodule Torque.MixProject do
       version: @version,
       elixir: "~> 1.15",
       start_permanent: Mix.env() == :prod,
+      # Keep the protocol open in test so this repo's own tests can
+      # implement Torque.Encoder for local structs. Host projects
+      # consolidate it (with their own implementations) at build time.
+      consolidate_protocols: Mix.env() != :test,
       deps: deps(),
       package: package(),
       description: "High-performance JSON library for Elixir via Rustler NIFs (sonic-rs)",

native/torque_nif/src/atoms.rs

@@ -13,4 +13,7 @@ rustler::atoms! {
     invalid_key,
     malformed_proplist,
     invalid_utf8,
+    unhandled_struct,
+    // struct marker key (atom `__struct__` in Elixir structs)
+    __struct__ = "__struct__",
 }

native/torque_nif/src/encoder.rs

@@ -3,8 +3,8 @@ use crate::nif_util::{make_tuple2, timeslice_percent};
 use crate::types::MAX_DEPTH;
 use rustler::sys::{
     c_int, c_uint, enif_get_atom, enif_get_atom_length, enif_get_double, enif_get_int64,
-    enif_get_list_cell, enif_get_tuple, enif_get_uint64, enif_inspect_binary, enif_is_empty_list,
-    ErlNifBinary, ErlNifCharEncoding, ErlNifEnv, ERL_NIF_TERM,
+    enif_get_list_cell, enif_get_map_value, enif_get_tuple, enif_get_uint64, enif_inspect_binary,
+    enif_is_empty_list, ErlNifBinary, ErlNifCharEncoding, ErlNifEnv, ERL_NIF_TERM,
 };
 use rustler::{schedule, Env, MapIterator, NewBinary, Term, TermType};
 use std::cell::RefCell;
@@ -35,6 +35,7 @@ enum EncodeError {
     MalformedProplist,
     DepthExceeded,
     InvalidUtf8,
+    UnhandledStruct,
 }
 
 #[inline]
@@ -46,6 +47,7 @@ fn error_reason(e: EncodeError) -> ERL_NIF_TERM {
         EncodeError::InvalidKey => atoms::invalid_key().as_c_arg(),
         EncodeError::MalformedProplist => atoms::malformed_proplist().as_c_arg(),
         EncodeError::InvalidUtf8 => atoms::invalid_utf8().as_c_arg(),
+        EncodeError::UnhandledStruct => atoms::unhandled_struct().as_c_arg(),
     }
 }
 
@@ -222,6 +224,13 @@ fn encode_map(
     if depth == 0 {
         return Err(EncodeError::DepthExceeded);
     }
+    // Elixir structs (maps carrying an atom `__struct__` key) are not
+    // encodable as-is: they must opt into Torque.Encoder. The Elixir layer
+    // normalizes them through the protocol and retries once, so failing
+    // here on any struct keeps that fast path (no struct) at zero cost.
+    if unsafe { is_struct(env_raw, term.as_c_arg()) } {
+        return Err(EncodeError::UnhandledStruct);
+    }
     let iter = MapIterator::new(term).ok_or(EncodeError::UnsupportedType)?;
     buf.push(b'{');
     let mut first = true;
@@ -238,6 +247,15 @@ fn encode_map(
     Ok(())
 }
 
+/// A map with an atom `__struct__` key is an Elixir struct.
+///
+/// Plain maps that merely use a binary `"__struct__"` key are unaffected.
+#[inline]
+unsafe fn is_struct(env_raw: *mut ErlNifEnv, map: ERL_NIF_TERM) -> bool {
+    let mut value = MaybeUninit::uninit();
+    enif_get_map_value(env_raw, map, atoms::__struct__().as_c_arg(), value.as_mut_ptr()) == 1
+}
+
 #[inline]
 fn encode_map_key(
     env_raw: *mut ErlNifEnv,