Enum NarCodec 

pub enum NarCodec {
    Zstd,
    Xz,
}

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.

Variants

Zstd

zstd at [ZSTD_LEVEL], multithreaded. The default.

Xz

xz level 6 — 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.

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.

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.

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() -> NarCodec

Returns the “default value” for a type.

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 StructuralPartialEq for NarCodec