Custom ext type registration

[SeanTAllen]

The problem

When working with MessagePack extension types, callers must manually manage the mapping between ext type codes and their serialization logic. The current API provides the raw building blocks -- MessagePackEncoder.ext writes an ext type code and byte payload, MessagePackDecoder.ext returns a (U8, Array[U8] val) tuple -- but the caller is responsible for dispatching on type codes in both directions.

For encoding, the caller must remember which ext type code maps to which application type, serialize the application value to bytes, and call ext with the correct code. For decoding, the caller reads the (code, data) tuple and writes a match or if/elseif chain to dispatch to the correct deserializer:

// Encoding: manual dispatch
let w: Writer ref = Writer
match value
| let p: Point val =>
  let payload: Array[U8] iso = recover iso
    let a = Array[U8](16)
    a.push_u64(p.x.bits().bswap())
    a.push_u64(p.y.bits().bswap())
    a
  end
  MessagePackEncoder.ext(w, 1, consume payload)?
| let c: Color val =>
  let payload: Array[U8] iso = recover iso
    [c.r; c.g; c.b]
  end
  MessagePackEncoder.ext(w, 2, consume payload)?
end

// Decoding: manual dispatch
(let code, let data) = MessagePackDecoder.ext(reader)?
match code
| 1 =>
  let r: Reader ref = Reader
  r.append(data)
  let x = r.f64_be()?
  let y = r.f64_be()?
  Point(x, y)
| 2 =>
  Color(data(0)?, data(1)?, data(2)?)
else
  error
end

This works, but it has problems:

• Dispatch logic is duplicated. Every call site that encodes or decodes ext values must repeat the code-to-type mapping. If a new ext type is added or a code changes, every call site must be updated.
• Codes are magic numbers. The mapping between 1 and Point or 2 and Color exists only in the programmer's head and in scattered match arms.
• No centralized validation. Nothing prevents two types from accidentally claiming the same ext code, or a decode site from forgetting to handle a code that an encode site produces.

A registration mechanism would centralize these mappings: define the (code, encoder, decoder) tuple once, then use it everywhere.

How other libraries handle this

Python (msgpack-python)

Python uses callback parameters on the packer and unpacker. The default parameter on packb handles encoding, and ext_hook on unpackb handles decoding:

import msgpack

def default(obj):
    if isinstance(obj, Point):
        return msgpack.ExtType(1, pack_point(obj))
    raise TypeError("Unknown type: %r" % (obj,))

def ext_hook(code, data):
    if code == 1:
        return unpack_point(data)
    return msgpack.ExtType(code, data)

packed = msgpack.packb(my_point, default=default)
unpacked = msgpack.unpackb(packed, ext_hook=ext_hook)

Encoding and decoding hooks are separate parameters, not a unified registry. The caller is responsible for keeping them in sync. Unrecognized codes in ext_hook fall through by returning ExtType(code, data).

Ruby (msgpack-ruby)

Ruby provides a MessagePack::Factory that centralizes registration:

factory = MessagePack::Factory.new
factory.register_type(0x01, Point,
  packer: :to_msgpack_ext,
  unpacker: :from_msgpack_ext)

packer = factory.packer
unpacker = factory.unpacker

Registration is on the factory, not the individual packer/unpacker. The factory creates packers and unpackers that share the same type registry. The packer: and unpacker: options default to to_msgpack_ext and from_msgpack_ext methods on the registered class, but can be overridden with procs. A recursive: true option passes the packer/unpacker to the callback for encoding nested msgpack structures.

JavaScript (@msgpack/msgpack)

JavaScript uses an ExtensionCodec class with a register method:

const extensionCodec = new ExtensionCodec();
extensionCodec.register({
  type: 0x01,
  encode: (object: unknown): Uint8Array | null => {
    if (object instanceof Point) {
      return encode_point(object);
    }
    return null;
  },
  decode: (data: Uint8Array) => {
    return decode_point(data);
  },
});

const encoded = encode(myPoint, { extensionCodec });
const decoded = decode(encoded, { extensionCodec });

The codec is passed as an option to encode/decode. The encode callback returns null for non-matching objects, which tells the encoder to try the next registered type. The codec is passed recursively when encoding nested structures.

Go (vmihailenco/msgpack)

Go provides package-level registration functions:

func RegisterExt(
    extID int8,
    value MarshalerUnmarshaler,
)

func RegisterExtEncoder(
    extID int8,
    value interface{},
    encoder func(enc *Encoder, v reflect.Value) ([]byte, error),
)

func RegisterExtDecoder(
    extID int8,
    value interface{},
    decoder func(dec *Decoder, v reflect.Value, extLen int) error,
)

The simplest path is RegisterExt, which takes an ext ID and a value implementing both Marshaler and Unmarshaler. The value parameter is used for its type only (typically passed as a nil pointer: (*MyType)(nil)). Registration is global and expected to happen at init time. The library panics if the type-to-ID mapping is not bijective (no two types sharing an ID, no type registered under two IDs).

C# (MessagePack-CSharp)

C# uses a formatter/resolver pattern. Custom types implement IMessagePackFormatter<T>, and formatters are registered through a resolver chain:

public class PointFormatter
    : IMessagePackFormatter<Point>
{
    public void Serialize(
        ref MessagePackWriter writer,
        Point value,
        MessagePackSerializerOptions options)
    { ... }

    public Point Deserialize(
        ref MessagePackReader reader,
        MessagePackSerializerOptions options)
    { ... }
}

Formatters are composed into resolvers using CompositeResolver. The resolver chain is set on MessagePackSerializerOptions, which is passed to serialize/deserialize calls. This is a general-purpose serialization framework, not specific to ext types.

C++ (msgpack-cxx)

C++ uses compile-time adaptor specialization. The intrusive approach uses a macro:

struct Point {
    double x, y;
    MSGPACK_DEFINE(x, y);
};

The non-intrusive approach specializes template structs in the msgpack::adaptor namespace. This is entirely compile-time -- there is no runtime registry. Custom types are serialized as msgpack arrays or maps of their fields, not as ext types.

Common patterns

Across these libraries, several patterns emerge:

1. Registration is centralized. A single registry (factory, codec, or package-level function) holds all type-code mappings. Individual encode/decode calls reference the registry rather than containing dispatch logic.

2. Encode and decode are paired. Registration takes both an encoder and decoder for the same type code, ensuring they stay in sync.

3. The registry is configured at startup, then used immutably. Ruby's factory creates packers/unpackers from it. JavaScript passes the codec as an option. Go registers at init time and panics on conflicts. None of these libraries support modifying the registry while encoding/decoding is in progress.

4. Type erasure is unavoidable. The registry maps type codes to generic byte blobs. Decoding returns a dynamically-typed value that the caller must cast or match. Python returns object, JavaScript returns unknown, Go returns interface{}. The type safety boundary is at registration time, not at decode time.

Design

The type erasure problem in Pony

The fundamental tension in ext type registration is between type safety and genericity. The registry must store handlers for different types under a uniform interface. In dynamically typed languages (Python, Ruby, JavaScript), this is natural -- everything is an object. In Go, interface{} serves as the universal type. In Pony, the equivalent is Any val.

A decode handler takes Array[U8] val (the ext payload) and returns something. That something must be a type that the registry can store uniformly. In Pony, this means the handler's return type must be part of a union or must be Any val:

// Option A: Return Any val
interface val ExtTypeHandler
  fun ext_type(): U8
  fun encode(v: Any val, w: Writer) ?
  fun decode(data: Array[U8] val): Any val ?

// Option B: Return a union type
type ExtValue is (... big union ...)

Option B is impractical -- the union would need to include every possible application type, which defeats the purpose of extensibility. Option A works but forces the caller to match or use as on the decoded value:

match registry.decode_ext(code, data)
| let d: ExtDecoded =>
  match d.value
  | let p: Point val => // use p
  end
end

This is the same pattern used by every other library. The type safety boundary moves from compile time to runtime at the point where the decoder returns a value. This is inherent to the problem: the registry doesn't know at compile time which type code will appear in the next byte of the stream.

The Any val capability constraint

Using Any val as the type erasure boundary imposes a capability constraint: all values flowing through the registry must be val. This is actually appropriate for a serialization library:

• Decoded values are constructed fresh from bytes and can naturally be val.
• Values being encoded should be readable but not necessarily mutable -- val satisfies this.
• A val registry can be shared across actors, which matters for concurrent decoding.

The constraint rules out encoding ref values directly. The caller would need to create a val snapshot before encoding. This is consistent with how msgpack works generally -- you are serializing data, not mutable state.

Interface design

interface val ExtTypeHandler
  """
  Handles encoding and decoding of a single MessagePack
  extension type. Implementations must be `val` so the
  handler can be stored in an immutable registry and shared
  across actors.
  """
  fun ext_type(): U8
    """
    The extension type code (0-127 for user-defined types).
    """

  fun encode(v: Any val, w: Writer) ?
    """
    Encode a value into the writer as the ext payload
    bytes. The registry handles writing the ext header
    (type code and length). This method writes only the
    payload content.

    The payload is whatever the ext type definition
    specifies. For most ext types, this is raw bytes
    (use Writer methods like `f64_be`, `u32_be`). For
    ext types whose payloads contain nested MessagePack
    structures, using `MessagePackEncoder` methods is
    appropriate. Be careful not to confuse the two:
    `w.f64_be(v)` writes 8 raw bytes, while
    `MessagePackEncoder.f64(w, v)` writes 9 bytes
    (1-byte msgpack header + 8-byte float).

    Errors if `v` is not the expected application type.
    """

  fun decode(data: Array[U8] val): Any val ?
    """
    Decode ext payload bytes into an application value.

    Errors if the data is malformed.
    """

The encode method takes Any val because the registry dispatches based on ext type code, not on the Pony type of the value. The caller is responsible for passing the correct value to the correct handler. A handler implementation would match or as-cast the input:

primitive PointHandler is ExtTypeHandler
  fun ext_type(): U8 => 1

  fun encode(v: Any val, w: Writer) ? =>
    let p = v as Point val
    w.f64_be(p.x)
    w.f64_be(p.y)

  fun decode(data: Array[U8] val): Any val ? =>
    let r: Reader ref = Reader
    r.append(data)
    let x = r.f64_be()?
    let y = r.f64_be()?
    Point(x, y)

Handlers are val (primitives are naturally val, and class instances can be constructed as val). This means they can be stored in an immutable map and shared freely.

Result types

The registry methods return union types instead of using bare ?, following the pattern established by MessagePackStreamingDecoder's DecodeResult. This lets callers distinguish between "no handler registered" and "handler failed" without relying on context to diagnose errors.

class val UnregisteredExtType
  """
  No handler is registered for the given ext type code.
  """
  let ext_type: U8

  new val create(ext_type': U8) =>
    ext_type = ext_type'

class val ExtEncodeError
  """
  The handler's encode method failed. This typically
  means the value passed was not the expected application
  type for this ext code, or the resulting payload was
  too large for any ext format.
  """
  let ext_type: U8

  new val create(ext_type': U8) =>
    ext_type = ext_type'

class val ExtDecodeError
  """
  The handler's decode method failed. This typically
  means the ext payload bytes were malformed.
  """
  let ext_type: U8

  new val create(ext_type': U8) =>
    ext_type = ext_type'

On the encode side, the result type is straightforward:

type EncodeExtResult is
  ( None
  | UnregisteredExtType
  | ExtEncodeError )

On the decode side, the success value is Any val (type-erased). Naively writing (Any val | UnregisteredExtType | ExtDecodeError) collapses to just Any val because every val type is a subtype of Any val. A wrapper class resolves this:

class val ExtDecoded
  """
  Wraps a successfully decoded ext type value. The
  `value` field holds the application type returned by
  the handler's `decode` method.
  """
  let value: Any val

  new val create(value': Any val) =>
    value = value'

type DecodeExtResult is
  ( ExtDecoded
  | UnregisteredExtType
  | ExtDecodeError )

The caller unwraps d.value and then matches on the application type -- the same runtime cast that would be needed regardless, but now with explicit error discrimination at the registry layer.

Registry design

The registry is a val class holding an immutable map from type codes to handlers:

class val ExtTypeRegistry
  """
  An immutable registry mapping extension type codes to
  their handlers. Built using `ExtTypeRegistryBuilder`, then
  frozen into a `val` that can be shared across actors.
  """
  let _handlers: Map[U8, ExtTypeHandler] val

  new val _create(
    handlers: Map[U8, ExtTypeHandler] val)
  =>
    _handlers = handlers

  fun encode_ext(
    code: U8,
    v: Any val,
    w: Writer)
    : EncodeExtResult
  =>
    """
    Encode a value using the handler registered for `code`.
    Writes the complete ext value (header + payload) to
    `w`.

    Returns `None` on success, `UnregisteredExtType` if no
    handler is registered for `code`, or `ExtEncodeError`
    if the handler's encode method fails or the payload
    is too large.
    """
    let handler = try
      _handlers(code)?
    else
      return UnregisteredExtType(code)
    end
    let payload: Writer ref = Writer
    try
      handler.encode(v, payload)?
    else
      return ExtEncodeError(code)
    end
    // Collect payload bytes
    let payload_data: Array[U8] iso =
      recover iso
        let arr = Array[U8]
        for chunk in payload.done().values() do
          match chunk
          | let s: String val =>
            arr.append(s.array())
          | let a: Array[U8] val =>
            arr.append(a)
          end
        end
        arr
      end
    try
      MessagePackEncoder.ext(
        w, code, consume payload_data)?
    else
      return ExtEncodeError(code)
    end
    None

  fun decode_ext(
    code: U8,
    data: Array[U8] val)
    : DecodeExtResult
  =>
    """
    Decode ext payload bytes using the handler registered
    for `code`.

    Returns `ExtDecoded` wrapping the application value on
    success, `UnregisteredExtType` if no handler is
    registered for `code`, or `ExtDecodeError` if the
    handler's decode method fails.
    """
    let handler = try
      _handlers(code)?
    else
      return UnregisteredExtType(code)
    end
    try
      ExtDecoded(handler.decode(data)?)
    else
      ExtDecodeError(code)
    end

  fun has(code: U8): Bool =>
    """
    Returns true if a handler is registered for `code`.
    """
    _handlers.contains(code)

Builder pattern for construction

The registry is immutable after construction. A mutable builder accumulates registrations, then produces the frozen registry:

class ref ExtTypeRegistryBuilder
  """
  Mutable builder for constructing an `ExtTypeRegistry`.
  Register handlers, then call `build()` to produce the
  immutable registry.
  """
  let _handlers: Map[U8, ExtTypeHandler]

  new ref create() =>
    _handlers = Map[U8, ExtTypeHandler]

  fun ref register(handler: ExtTypeHandler) ? =>
    """
    Register a handler. Errors if a handler is already
    registered for this type code, or if the type code
    is in the reserved range (128-255 unsigned, which
    corresponds to -1 through -128 signed in the
    MessagePack spec).
    """
    let code = handler.ext_type()
    if code > 127 then error end
    if _handlers.contains(code) then error end
    _handlers(code) = handler

  fun ref build(): ExtTypeRegistry =>
    """
    Produce an immutable registry from the current
    registrations. The builder should not be used after
    calling build (registrations are cleared).
    """
    let handlers: Map[U8, ExtTypeHandler] iso =
      recover iso
        let m = Map[U8, ExtTypeHandler]
        for (k, v) in _handlers.pairs() do
          m(k) = v
        end
        m
      end
    _handlers.clear()
    ExtTypeRegistry._create(consume handlers)

The builder errors on duplicate codes at registration time, following Go's approach of treating code conflicts as programmer errors. This catches a common mistake early rather than producing surprising behavior at encode/decode time.

The builder also validates that registered codes fall in the user-defined range (0-127). The MessagePack spec reserves codes -1 through -128 (unsigned 0xFF through 0x80) for predefined types -- timestamps already use ext type -1 (0xFF). The MessagePackStreamingDecoder already treats code 0xFF specially, returning MessagePackTimestamp instead of MessagePackExt, so a user handler registered for 0xFF would silently never be reached through the streaming decoder path. Enforcing the range prevents this class of bugs. Callers who need custom handling for reserved codes can use the low-level MessagePackEncoder and MessagePackDecoder primitives directly.

Interaction with existing APIs

The registry is a companion to the existing primitives, not a replacement. The stateless MessagePackEncoder and MessagePackDecoder remain unchanged. The registry provides convenience on top of them.

With MessagePackDecoder: The caller decodes an ext value using MessagePackDecoder.ext(reader)? to get the (code, data) tuple, then passes it to the registry:

(let code, let data) = MessagePackDecoder.ext(reader)?
match registry.decode_ext(code, data)
| let d: ExtDecoded =>
  match d.value
  | let p: Point val => // use p
  end
| let e: UnregisteredExtType =>
  // no handler for e.ext_type
| let e: ExtDecodeError =>
  // handler failed for e.ext_type
end

With MessagePackStreamingDecoder: The streaming decoder already returns MessagePackExt for ext values, which contains ext_type and data fields. The caller passes these to the registry:

match decoder.next()
| let e: MessagePackExt =>
  match registry.decode_ext(e.ext_type, e.data)
  | let d: ExtDecoded =>
    match d.value
    | let p: Point val => // use p
    end
  | let err: UnregisteredExtType =>
    // no handler for err.ext_type
  | let err: ExtDecodeError =>
    // handler failed for err.ext_type
  end
end

In both cases, the registry is used after the low-level decoder has done its work. The registry does not need to be integrated into the decoder itself -- it operates on the already-decoded (code, data) pair.

For encoding: The registry wraps the encoder to handle the ext header and payload assembly:

let w: Writer ref = Writer
// Encode a point using registered handler
match registry.encode_ext(1, my_point, w)
| None => None // success, bytes are in w
| let e: UnregisteredExtType =>
  // no handler for ext type 1
| let e: ExtEncodeError =>
  // handler failed for ext type 1
end
// Encode non-ext values using the encoder directly
MessagePackEncoder.str(w, "hello")?

Encode-side asymmetry: The registry fully solves decode-side dispatch -- the ext type code arrives from the wire and the registry maps it to the correct handler automatically. On the encode side, the improvement is the centralization of serialization logic in the handler, but the caller must still know which ext code maps to which application type (e.g., that Point uses code 1). This asymmetry is inherent: decode dispatch is data-driven (the code is in the wire format), while encode dispatch is caller-driven (the application knows its own types). This matches how all surveyed libraries work -- none of them provide fully automatic encode-side dispatch without the caller specifying which type to encode as.

Encoding overhead: payload assembly

The encode_ext method uses a temporary Writer for the handler to write payload bytes into, then collects the writer's chunks into a single Array[U8] before passing it to MessagePackEncoder.ext. This involves an extra allocation and copy because ext needs the total payload size upfront to write the ext header.

For small payloads (the common case for ext types -- UUIDs, coordinates, custom scalars), this overhead is negligible. For large payloads, the copy is proportional to the payload size. An alternative design could have the handler report its payload size before encoding, allowing the registry to write the ext header first and then let the handler write directly to the output writer. This would avoid the intermediate buffer but complicate the handler interface. The simpler approach (temporary writer + collect) is proposed as the starting point, with the optimized path available as a future enhancement if profiling shows the overhead matters.

Why the registry is separate from the decoder

The registry could be integrated into the streaming decoder, so that next() returns application types directly instead of MessagePackExt. This was considered and rejected for several reasons:

1. It would change DecodeResult. The streaming decoder's return type is (MessagePackValue | NotEnoughData | InvalidData). Adding Any val to this union would make every match on the result less precise -- the caller would need to handle an opaque type alongside the well-typed msgpack primitives.

2. It couples the decoder to application types. The streaming decoder is a general-purpose msgpack decoder. Coupling it to a specific set of application-defined handlers makes it less reusable.

3. The composition is trivial. Using the registry as a post-processing step on the decoder's output is straightforward and doesn't sacrifice ergonomics. The two-step pattern (decode ext, then dispatch via registry) is explicit about what happens at each stage.

Thread safety and capability model

The registry is val after construction. This means:

• It can be shared across actors without restriction.
• Multiple actors can decode concurrently using the same registry.
• No synchronization is needed.
• The registry cannot be modified after construction -- new type registrations require building a new registry.

Encoding requires a Writer ref parameter, which is inherently single-actor. Each actor that encodes needs its own Writer. This is the same constraint as using MessagePackEncoder directly -- the registry does not change it. The sharing benefit is for the registry itself and for decode operations, which create new values from data.

The builder is ref during construction, ensuring that registration happens in a single-actor context where mutation is safe. The build() method produces an immutable registry from the builder's mutable state, using a recover block to lift the handler map from ref to iso and then to val. The builder clears its internal state after building, so a second call to build() produces an empty registry. This is the standard Pony pattern for constructing shareable data structures.

Alternative: per-type decode without Any val

An alternative design avoids Any val by providing typed decode methods on the registry:

fun decode_ext_as[T: Any val](
  code: U8,
  data: Array[U8] val)
  : (T | UnregisteredExtType | ExtDecodeError) ?

This doesn't actually help. The registry stores handlers as ExtTypeHandler values, so the decode method returns Any val internally. The generic method would just unwrap ExtDecoded and add an as cast:

fun decode_ext_as[T: Any val](
  code: U8,
  data: Array[U8] val)
  : (T | UnregisteredExtType | ExtDecodeError) ?
=>
  match decode_ext(code, data)
  | let d: ExtDecoded => d.value as T
  | let e: UnregisteredExtType => e
  | let e: ExtDecodeError => e
  end

The caller can do this unwrap and cast themselves. Adding a generic wrapper provides no additional type safety -- the as cast can still fail at runtime -- and adds API surface without value.

Scope

This proposal covers:

• An ExtTypeHandler interface for implementing ext type encode/decode logic
• An ExtTypeRegistry class for storing handler mappings
• An ExtTypeRegistryBuilder class for constructing registries
• The interaction pattern with existing encoder, decoder, and streaming decoder APIs
• The capability model for thread safety

This proposal does not cover:

• Modifying MessagePackEncoder, MessagePackDecoder, or MessagePackStreamingDecoder to accept registries directly
• A higher-level "typed packer/unpacker" that dispatches all types (not just ext) through a registry
• Automatic type detection on the encode side (the caller must specify the ext code explicitly)
• Schema or contract validation (verifying that both sides of a connection agree on ext code assignments)

[SeanTAllen]

if we implement this, we should remember to add an example of its usage to examples/