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.

1. 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.

2. 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

3. Acceptance

4. 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.)

5. 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.

6. 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
     

7. PRs

PR Title
   

8. Review

Comment summary File Decision Notes
       

9. Result

Emacs 29.3 (Org mode 9.6.15)