Enum NarCodec 

pub enum NarCodec {
    Zstd {
        level: ZstdLevel,
    },
    Xz {
        level: XzLevel,
    },
}

How a NAR is packed for the cache.

── ★ ONE VALUE — THE BYTES, THE SUFFIX AND THE NARINFO ALL DERIVE ────── The codec used to be stated in THREE disconnected places in push_path: the call to compress_xz, the literal .nar.xz in the URL, and compression: "xz".to_string() in the narinfo. Three declarations of one fact, free to disagree — and disagreement is not a cosmetic bug: a narinfo that says xz over zstd bytes makes EVERY client fail to decompress, so the cache would serve corruption while reporting success. That is the failure mode this type removes, by leaving no way to state the codec twice.

── WHY zstd IS THE DEFAULT — MEASURED, NOT ASSUMED ───────────────────── Benchmarked on a real 48 MB NAR (git 2.51.2), 10 cores, 2026-08-05:

  codec              ms     size   %orig
  xz -6  (previous)  8368   8 MB    17%
  xz -6 -T0          7615   8 MB    17%     <- multithreading xz buys 9%
  zstd -19 -T0      11298   8 MB    17%     <- SLOWER than xz for the ratio
  zstd -12 -T0        440  10 MB    21%     <- 19x faster than xz -6
  zstd -9  -T0        243  10 MB    22%     <- 34x faster

Two beliefs died there. “Just add -T0 to xz” gains 9%, not the order of magnitude it promises — liblzma’s block splitting barely engages at this size. And zstd is only faster at lower levels; at -19 it loses to xz on both axes. The knee is -12: 19x the speed for four percentage points of ratio.

That trade is obviously right HERE and the reason is architectural: this cache is a LOCAL origin serving a handful of fleet nodes over tailscale. Bandwidth is cheap; CPU-hours on the fleet’s only x86_64-linux builder are not. MEASURED cost of the old default on rio 2026-08-05: a 2483-path closure spent FOUR HOURS in single-threaded xz, and because nix runs the post-build hook synchronously it blocked every build on that node — which is a different bug (fixed by detaching the hook) that this default made unsurvivable.

A mixed cache is fine and needs no migration: each narinfo declares its own codec, so paths already stored as .nar.xz keep resolving while new pushes land as .nar.zst.

── WHY THE LEVEL LIVES INSIDE THE VARIANT ──────────────────────────── The level used to be a free-standing const ZSTD_LEVEL. Lifting it to a sibling config field ({ codec, level }) would have been the obvious move and is wrong: level = 12 means nothing when codec = Xz, and level = 9 means two completely different things across the two codecs (near-max for xz, mid-range for zstd). A pair whose second component is only meaningful for some values of the first is a variant payload, not a field — so the codec choice and its one tuning knob travel as one value that cannot be split, reordered, or half-applied.

The levels are ZstdLevel / XzLevel, not bare integers: xz2’s encoder panics on a preset above 9, so an out-of-range level in a config file used to be a crash waiting on the first push. It is now rejected where the value is built.

Variants

Zstd

zstd, multithreaded. The prescribed default at ZstdLevel::PRESCRIBED.

Fields

level: ZstdLevel

The compression level, bounded to zstd’s accepted band.

Xz

xz — what this cache used before 2026-08-05. Kept selectable rather than deleted (★★ MODULARIZE, DON’T DELETE): it is still the right choice for an origin that is bandwidth-bound rather than CPU-bound, and it is what every already-stored path is packed with.

Fields

level: XzLevel

The preset, bounded to xz’s accepted band.

Implementations

impl NarCodec

pub fn narinfo_name(self) -> &'static str

The Compression: field value. nix’s wire vocabulary, not ours — verified 2026-08-05 by having nix write a zstd cache itself (nix copy --to 'file://…?compression=zstd') and reading back what it emitted.

The level is deliberately absent from this value: it is an encoder setting, and a decompressor reads it out of the frame header. A codec reconfigured from level 12 to level 3 still publishes zstd, and every client still reads it.

pub fn url_suffix(self) -> &'static str

The NAR URL suffix.

.nar.zst, NOT .nar.zstd — taken from nix’s own output in the same experiment above. Guessing here would have produced a cache whose URLs no client resolves, and nothing in our own types would have objected.

pub fn compress(self, data: &[u8]) -> Result<Vec<u8>, CacheError>

Compress a NAR under this codec.

zstd runs multithreaded across the machine’s cores; workers(0) asks the library for one worker per core. A failure to enable threading is deliberately NOT fatal — it costs speed, never correctness, and a cache push that refuses to run is worse than a slow one.

Errors

CacheError::Io if the encoder cannot be built or the write fails. The level cannot be the cause: it is bounded at construction.

pub fn decompress(self, data: &[u8]) -> Result<Vec<u8>, CacheError>

Decompress a NAR packed under this codec.

The inverse of compress, on the same value — so a test (or a future serve-side verifier) can prove that what a narinfo declares actually decodes the bytes it points at, rather than asserting two strings match.

Errors

CacheError::Io if the data is not a valid frame for this codec.

pub fn from_narinfo_name(name: &str) -> Option<Self>

Resolve a codec from the Compression: field of a narinfo — the reader’s half of the one-value invariant.

Level is irrelevant on the decode side (it lives in the frame header), so the returned value carries the prescribed level as a placeholder and is only ever used for its decompress / url_suffix projections.

Trait Implementations

impl Clone for NarCodec

fn clone(&self) -> NarCodec

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for NarCodec

impl Debug for NarCodec

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for NarCodec

fn default() -> Self

The fast path is what you get without asking — see the benchmark in the NarCodec docs.

impl<'de> Deserialize<'de> for NarCodec

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for NarCodec

impl PartialEq for NarCodec

fn eq(&self, other: &NarCodec) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for NarCodec

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for NarCodec