Binary Messaging

Less to send. More room to build.

Celeris carries application payloads as bytes. You choose how to encode and decode them: MessagePack, Protobuf, a custom format, or JSON encoded as UTF-8. Your format. Your bytes. No required JSON conversion.

Compact formats can reduce payload size and the work spent encoding and decoding frequent updates. Smaller messages mean less payload bandwidth at the same delivery rate. Where infrastructure charges depend on transferred bytes, that can reduce costs. It does not guarantee a lower Celeris bill.

Binary transport does not automatically compress JSON or convert objects into MessagePack. Binary encoding and compression are separate operations; the application selects its serializer. The SDK specification places serialization above its byte API and does not require a serialization library.

One update, measured three ways

The same position-update values in each encoding:

{ "playerId": "p1", "x": 142, "y": 88, "action": "move" }

Measured with @msgpack/msgpack 3.1.3 using default encoding, without extensions or shared dictionaries. The decoded values are identical. Counts exclude Celeris protocol, WebSocket, TLS, and network overhead; no compression is applied. Protobuf was measured with protobufjs 8.8.0 using the schema below. One million payload deliveries would carry 48 MB, 32 MB, or 15 MB of payload data respectively (decimal units).

syntax = "proto3";
message PositionUpdate {
  string playerId = 1;
  uint32 x = 2;
  uint32 y = 3;
  string action = 4;
}

Unlike JSON and the MessagePack map, Protobuf uses field numbers instead of carrying field names in each message. Both ends must already have the matching schema. The 15-byte count excludes schema distribution; all three encodings decode to the same values for this example.

This is one example, not a typical reduction or a speed benchmark. Different data, numeric representations, encoders, and compression settings can change the result; binary can also be larger.

Encode and decode in your application

This standalone JavaScript example uses the independent MessagePack library. It demonstrates serialization before passing the bytes to the SDK.

import { encode, decode } from "@msgpack/msgpack";

const position = { playerId: "p1", x: 142, y: 88, action: "move" };
const jsonBytes = new TextEncoder().encode(JSON.stringify(position));
const binaryBytes = encode(position);

console.log(jsonBytes.byteLength); // 48
console.log(binaryBytes.byteLength); // 32
console.log(decode(binaryBytes)); // the original values

Your application passes encoded bytes to a segment's publish() and decodes received bytes with the matching codec. Follow Payload formats for SDK text/JSON helpers, validation, and createPayloadCodec.

For Protobuf, encode with your schema and decode with the compatible schema at the receiver. Celeris transports the resulting bytes; it does not supply your application schema or decoder.

Measure the work that matters

Compare representative production payloads, not only one small object. Record encoded byte size, encoding and decoding time, allocations, and the runtime/library versions. Include warm-up and repeat measurements. A compact representation may reduce processing work, but an optimized native JSON implementation can outperform a particular binary codec.

Measure end-to-end separately: smaller payloads are not proof of lower network latency or higher service throughput. Compression, fan-out, message rate, and connection traffic also affect actual bandwidth.

JSON remains a valid choice

JSON can be useful for interoperability, debugging, and lower-frequency events. Encode it with TextEncoder and decode with TextDecoder plus JSON.parse in your application. There is no need to change formats before you have a reason to do so.

Binary payloads do not establish ordering, deduplication, or delivery receipts. See Message Ordering and Reconnection and Recovery for those boundaries, and pricing to explore payload volume at your delivery rate.