← All posts

· OTA

An ampersand that broke every firmware link

Go’s JSON encoder escapes & by default. A device that copies bytes raw lost its signature and fell back to MQTT.

When Rootheon offers a firmware update, the device receives a short-lived download link on the Cloudflare edge, something like:

https://fw.example/pkg/1234?e=1763211600&t=Qm9vdHN0cmFw...

e is the expiry and t an HMAC over the path and the expiry. The Worker in front of R2 checks both and answers 404 to anything else, so a link that was changed on the way is useless.

The symptom

On the first real board update the download took the slow path: the device fetched the image in MQTT chunks instead of over HTTPS. It worked, so nothing failed loudly, but a 1.7 MB image is exactly what the HTTPS path is for.

The cause

Go’s encoding/json escapes &, < and > by default, so that JSON can be pasted into HTML safely. The link went out as:

…?e=1763211600&t=Qm9vdHN0cmFw…

Any JSON parser turns & back into &. The device does not parse the whole document; it copies the value between the quotes as raw bytes. Its request therefore asked for a URL with a literal & in it, the Worker saw no t parameter and answered 404, and the device did the right thing after three attempts: it fell back to MQTT chunks.

Our end-to-end test had not caught it because it decoded the JSON before comparing the link.

The fix

Every attribute message is now encoded with SetEscapeHTML(false), and the tests compare the raw bytes on the wire, not the decoded value. With that in place the same board downloaded the image over HTTPS in about 25 seconds, resuming with a Range request when interrupted, and confirmed the update after the MCUboot swap.

The lesson we wrote down: when the other end is a microcontroller, test what is on the wire, not what a library would make of it.