Task: Send raw bytes instead of base64 for image-carrying NATS messages
Table of Contents
This page documents a task in the Fix image-batch NATS payload overflow, add SVG compression story. It captures the goal, current status, acceptance, and any notes or results.
Goal
Image byte payloads currently travel base64-encoded inside a JSON
string field (via rfl::json's default std::vector<uint8_t>
handling), even though the compression task's generic transport-level
gzip already compresses that JSON+base64 text as opaque bytes. This
task removes the base64 layer specifically for image-carrying
messages, so the raw SVG bytes go straight into the (already
compressed) NATS payload with no encode-then-immediately-decode
round trip.
Not load-bearing: the compression task's own data shows gzip-with-
base64 already gives a 2.5x margin against the worst measured case.
This is a further ~25% payload reduction plus removing pure CPU/
bandwidth waste, not a bug fix. Needs a custom wire encoding for
image-carrying messages specifically (bypassing rfl::json's default
behaviour for that field), which is why it's split from the
compression task rather than bundled with it.
Status
| Field | Value |
|---|---|
| State | ABANDONED |
| Parent story | Fix image-batch NATS payload overflow, add SVG compression |
| Now | Superseded – see Notes. |
| Waiting on | Nothing. |
| Next | Nothing (superseded). |
| Last touched | 2026-07-28 |
Acceptance
Plan
(Implementation strategy. Written when work starts; key decisions
are distilled into the parent story's * Decisions at close, but the
plan itself stays — it is the historical record of what we did.)
Notes
Superseded on 2026-07-28 by
Make NATS wire format configurable: JSON/MessagePack, decided once
at startup. While scoping this task's custom binary framing for
image-carrying messages specifically, it became clear the base64
overhead isn't image-specific – every rfl::json-encoded NATS
message pays it for any byte-vector field. reflect-cpp already
supports MessagePack (rfl::msgpack), which natively packs
std::vector<uint8_t> as binary with zero custom framing code. The
new story solves this task's goal generically, for every message
type, via a single .env-driven format choice rather than a bespoke
per-message wire format.
Test Scenarios
Manual QA scenarios (scaffolded via compass add test_scenario, run
through the QA Validation Runner panel) that verify this task. Link
new ones here as they're created; the scenario doc itself links back
via its "Verifies task" field.
| Scenario | State | Notes |
|---|---|---|
PRs
| PR | Title |
|---|---|
Review
| Comment summary | File | Decision | Notes |
|---|---|---|---|