nordisk/holger

znippy format-version pin — for idiots

Class: idiot · Function: znippy-format-pin. The real detail: znippy-format-pin-design.md.

The one-sentence version

Holger now checks "was this archive written by a znippy newer than the one I can read?" before it reads it — and says no, politely, to that one archive, instead of falling over.

The story

Holger stores artifacts in znippy archives. An archive is a file with a little label inside saying which version of the znippy file format it was written in. Think of it as a "made in 2026" stamp.

Holger used to ignore the stamp and just start reading. That is fine while everyone uses the same znippy. But holger's whole job is to accept archives from elsewhere — an agent carried one across the airgap on a USB stick, a client uploaded one. If that archive came from a newer znippy, its insides are laid out in a way this holger has never seen. It would start parsing a shape it doesn't know, and fall over — and take the server down with it. Every other repository, everybody else's downloads: gone. Because one person uploaded one file.

That is a bad property for a registry.

What we did

Holger now reads the stamp first, before it reads anything else.

• Stamp says a version holger knows → carry on exactly as before.
• No stamp at all (older archives) → carry on exactly as before.
• Stamp says something from the future → refuse this one archive, say why in plain words, and keep serving everything else.

What "refuse" looks like

If it happens when the server starts, that one repository is switched off and the rest of the server starts normally. If it happens while the server is running, the request that touched it gets an error back — 503, with the reason written out:

holger refuses znippy archive /srv/holger/drift.znippy: it records format version 4,
which this build does not read (supports up to v3) — re-pack the archive with a
matching znippy, or upgrade holger

Notice it tells you three things: which file, what it claimed, and what holger can actually read. You can act on that without reading any code.

What you do about it

Either re-make the archive with the same znippy your holger has, or install a newer holger. Nothing else.

Is it slow now?

No. Reading the stamp means reading a few hundred bytes of the archive's table of contents — not the archive. And for the one repository type that re-opens its file on every download, holger remembers the answer for as long as the file hasn't changed, so the ongoing cost is one "has this file changed?" question.

How we know it works

There is a test that takes a real archive, changes only the stamp to say a future version, and checks three things: the archive worked before the change, holger refuses it after, and a different repository keeps serving its files perfectly the whole time. If somebody deletes the check, that test goes red immediately — we verified that by switching the check off and watching it fail.