Recipe

MessagePack primer

MessagePack is a binary serialization format that drops onto Meridian's wire protocol as a near-drop-in for JSON. It's smaller, faster to parse, and preserves typed buffers natively. This primer covers when to reach for it, how to wire it into the gateway, and the gotchas worth knowing.

1. When to choose msgpack over JSON

Pick msgpack when your payload contains binary blobs (embeddings, image tensors, audio frames) or when latency-sensitive endpoints hit multi-megabyte JSON. Stay on JSON for browser-visible debug logs and anywhere a human inspects the raw frame. Meridian's gateway accepts both via the Content-Type header.

2. Wiring it into a client

The msgpackr package gives you sync and streaming codecs. Pack the request body, set the content type to application/msgpack, and the gateway routes it through the same model selector as JSON.

import { pack, unpack } from 'msgpackr';

// Encode a payload for the Meridian gateway
const payload = {
  model: 'azure/model-router',
  messages: [{ role: 'user', content: 'Hello' }],
  stream: false,
};

const buffer = pack(payload);
// buffer is a compact Uint8Array, typically 30-50% smaller than JSON

// Decode a response from the wire
const decoded = unpack(buffer);
console.log(decoded.model);

// Stream-friendly: chunk-decode incremental frames
import { Unpackr } from 'msgpackr';
const unpackr = new Unpackr({ structuredClone: true });
for await (const frame of unpackr.decodeStream(socket)) {
  process(frame);
}

3. Gotchas and tuning

Watch for three traps. First, undefined becomes null on the wire; coerce before packing. Second, large maps with string keys benefit from the shared-structures option, which interns repeated keys across frames. Third, streaming consumers must call structuredClone: true if they retain decoded buffers past the next frame boundary, otherwise the decoder reuses memory and overwrites prior values.