Struct CacheConfig 

pub struct CacheConfig {
    pub listen: String,
    pub backend: BackendConfig,
    pub signing_key: Option<PathBuf>,
    pub priority: u32,
    pub want_mass_query: bool,
    pub store_dir: String,
    pub require_sigs: bool,
    pub nar_codec: NarCodec,
}

Top-level cache configuration.

#[serde(default)] is what makes this an overlay rather than a replacement: shikumi’s Custom tier deserializes the operator’s YAML into this type whole, so without it a file that wants to change one field would have to restate every other one — and a file that failed to would be silently discarded (shikumi falls back to prescribed_default on a parse error). Absent fields now come from Default, which is TieredConfig::prescribed_default.

Fields

listen: String

Network address to listen on.

backend: BackendConfig

Storage backend configuration.

signing_key: Option<PathBuf>

Path to the ed25519 signing secret key file.

In production this path is a cofre/ESO-materialized Kubernetes Secret mount, never a plaintext literal. When set, the daemon signs every ingested narinfo (see serve).

priority: u32

Cache priority (lower = preferred). Reported in nix-cache-info.

want_mass_query: bool

Whether to want mass query (narinfo pipelining).

store_dir: String

The Nix store directory (almost always /nix/store).

require_sigs: bool

Whether this cache’s consumers should require a valid signature.

This is a serving-side advertisement of the fail-closed posture: a signing cache SHOULD publish require_sigs = true so operators know the served paths are signed and consumers must verify. It does not by itself change what the daemon serves (signing is driven by signing_key); it is the typed knob a consuming config reads to know the cache is trustworthy fail-closed. Defaults to false to preserve legacy behavior for caches that have not yet been given a key.

nar_codec: NarCodec

How a pushed NAR is packed — the codec and its level, as one inseparable value (see NarCodec).

This is the deployment knob the benchmark in NarCodec’s docs argues about. rio is a local origin serving a handful of fleet nodes over tailscale: CPU-bound, bandwidth-cheap, so zstd -12 is right and is the prescribed default. A bandwidth-bound origin — one paying egress, or seeding cold clients over the public internet — legitimately wants { codec: xz, level: 6 } and now gets it from a config file instead of a recompile.

A mixed cache needs no migration: every narinfo declares its own codec, so flipping this changes only what new pushes look like.

Implementations

impl CacheConfig

pub fn resolve() -> Self

Resolve this cache’s configuration the fleet-standard way — the one call site every entry point uses (★★ CONFIGURATION MANAGEMENT).

Precedence is shikumi’s: the CACHE_TIER_ENV environment variable selects the tier, and when it names a path that YAML file is overlaid on the prescribed default. Unset → the prescribed default, unchanged from what this cache did before it had a config surface.

Trait Implementations

impl Clone for CacheConfig

fn clone(&self) -> CacheConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for CacheConfig

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

Formats the value using the given formatter.

impl Default for CacheConfig

fn default() -> Self

Delegates to TieredConfig::prescribed_default so the standard idiom (CacheConfig::default()) and the tiered resolution can never describe two different caches.

impl<'de> Deserialize<'de> for CacheConfig

where CacheConfig: Default,

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for CacheConfig

impl PartialEq for CacheConfig

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for CacheConfig

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 CacheConfig

impl TieredConfig for CacheConfig

fn bare() -> Self

Tier 0 — the honest floor: sui-cache exactly as it shipped before 2026-08-05. xz -6 packing, no signing key, no fail-closed advertisement, the on-disk backend.

This tier is not a worse default, it is the documented past: every .nar.xz already in a fleet cache was written by it, and an origin that wants the old ratio back asks for it by name (SUI_CACHE_TIER=bare) rather than by editing a constant.

fn prescribed_default() -> Self

Tier 2 — the prescribed posture: identical to bare except that pushes pack with zstd, the measured fast path. The whole point of the 2026-08-05 change is that you get it without asking.

fn discovered() -> Self

Tier 1 — bare() overlaid with runtime auto-detect outputs. Default: returns bare() unchanged. Consumers with detect helpers override.

fn extend(self, _base: &Self) -> Self

Tier 3 — overlay this config on top of base. Default impl returns self.clone() (full replacement). Consumers with finer-grained per-field merge semantics override.

fn resolve_tier(tier: ConfigTier) -> Self

Materialize self from a tier selector — the operator-facing entry point. Wraps the tier methods + env-var resolution + optional YAML overlay into one call site every fleet app uses identically.

fn resolve_from_env(env_var: &str) -> Self

Convenience: resolve the tier from an env var (default <APP>_TIER) AND materialize the config in one call. The fleet-wide canonical entry point at app startup.

fn diff_against(&self, baseline: &Self) -> ConfigDiff

Diff self against baseline. Default: serialize both to YAML and produce a line-oriented diff.