Message Serialisation
debt(d7/e7/b7/t7)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints explicitly state automated=no, and the tools listed (kafka, avro, protobuf) are runtime/infrastructure tools rather than static analysis tools that flag bad serialisation choices. PHP serialize() misuse, missing schema versioning, and breaking Protobuf field number changes are not caught by standard linters — they surface during code review or when consumers start failing in production.
Closest to 'cross-cutting refactor across the codebase' (e7). The quick_fix suggests a conceptually simple swap, but the common_mistakes reveal the reality: changing serialisation format (e.g. PHP serialize() to Protobuf) affects every producer and consumer across the system, requires schema registry setup, consumer coordination, and message envelope versioning. This is a cross-cutting concern touching multiple services and deployment pipelines, well beyond a single-file fix.
Closest to 'strong gravitational pull' (b7). Applies_to is queue-worker context, but serialisation format is a cross-cutting architectural decision — every producer, consumer, and schema change is shaped by the initial format choice. Changing field numbers in Protobuf breaks all existing consumers; Avro requires a schema registry for all teams. The choice exerts gravitational pull on every future message schema design and consumer implementation.
Closest to 'serious trap' (t7). The misconception field states 'JSON is always sufficient' — a belief that contradicts production-scale reality at 10M messages/day where Protobuf yields 10x storage/bandwidth savings. Additionally, the common_mistakes reveal multiple non-obvious traps: Protobuf field numbers being permanent, Avro requiring a schema registry, and PHP serialize() introducing silent deserialization vulnerabilities. These contradict reasonable developer intuitions about backward-compatible schema evolution.
Also Known As
TL;DR
Explanation
Message serialisation formats: JSON — human-readable, schema-free, widely supported, but verbose (35 bytes for a simple event). MessagePack — binary JSON, 2-3x smaller. Avro — schema stored in a schema registry; consumer must have schema; excellent for Kafka; schema evolution rules prevent breaking consumers. Protocol Buffers (Protobuf) — strongly typed .proto schema, 5-10x smaller and faster than JSON, excellent cross-language support. Never use PHP serialize() for messages — PHP-only format and a deserialization vulnerability source.
Common Misconception
Why It Matters
Common Mistakes
- PHP serialize() for messages — PHP-only, insecure deserialization vulnerability
- No schema validation for JSON messages — malformed messages corrupt consumer state silently
- Avro without a schema registry — consumers need schemas; registry provides versioned schema access
- Changing Protobuf field numbers — field numbers are permanent; changing breaks all existing consumers
Code Examples
// PHP serialize — PHP-only, deserialization risk:
$message = serialize(['order_id' => 42, 'amount' => 99.99]);
$queue->publish($message);
// Cannot consume from Node.js, Python, Go services
// Consumer must unserialize() — deserialization vulnerability// JSON — simple, cross-language:
$message = json_encode(['order_id' => 42, 'amount' => 99.99]);
// Protobuf — typed, compact, cross-language:
// payment.proto: message PaymentEvent { int64 order_id = 1; double amount = 2; }
$event = new PaymentEvent();
$event->setOrderId(42);
$event->setAmount(99.99);
$binary = $event->serializeToString(); // ~10 bytes vs JSON ~35 bytes