Recipe

FlatBuffers Primer

FlatBuffers is a zero-copy serialization format originally built at Google for game development. Unlike JSON or Protobuf, it lets you read structured data directly from a byte buffer without parsing or allocating intermediate objects. This makes it ideal for latency-sensitive Meridian pipelines where every microsecond counts.

1. Defining a Schema

Schemas live in .fbs files. A schema declares tables, structs, enums, and root types. The flatc compiler emits idiomatic code for C++, Rust, Go, Python, and TypeScript.

namespace meridian.events;

table InferenceEvent {
  request_id: string (key);
  model: string;
  latency_ms: uint32;
  tokens_in: uint32;
  tokens_out: uint32;
}

root_type InferenceEvent;

2. Building Buffers

FlatBuffers writes are append-only into a growing byte vector. You construct strings and vectors first, then tables that reference their offsets. The buffer is finalized with a single Finish() call, after which the bytes are immutable and ready to ship over the wire or persist to disk.

3. Reading Without Parsing

The killer feature: readers do not parse. A typed accessor object simply offsets into the existing byte buffer to fetch a field. There are no allocations, no copies, and no deserialization phase. This is why Meridian uses FlatBuffers for the hot path between the gateway and worker shards — a 4KB event can be inspected in well under a microsecond.