Crate decdn_cache 

Cache engine for deCDN.

Wraps iroh-blobs with origin pull-through logic. The buffered entry points (engine::CacheEngine::get / populate) fetch from a configured Origin backend on a cache miss, verify the BLAKE3 hash, and insert the bytes before returning them to the caller. The streaming entry points do not buffer whole-blob first: engine::CacheEngine::origin_range_wire streams one verified sub-range per draw, window by window, for the node’s two-leg serve-miss spine. Node-to-node pull-through is one such backend — the node crate supplies an Origin (NodeOrigin, #831) that pays a peer over cdn/client/v1 — so this crate needs no knowledge of the paid path.

Leaf crate per adr/appendix-poc-production-seams.md — no #[cfg(...)] mode branching or feature flags here. The node crate’s wiring layer selects which origin backend to construct.

Re-exports

pub use circuit_breaker::Admission;

pub use circuit_breaker::BreakerState;

pub use circuit_breaker::Clock;

pub use circuit_breaker::ManualClock;

pub use circuit_breaker::OriginBreaker;

pub use circuit_breaker::OriginOutcome;

pub use circuit_breaker::SystemClock;

pub use engine::CacheEngine;

pub use engine::EvictionCandidates;

pub use engine::EvictionPreview;

pub use engine::OriginHeldReport;

pub use engine::OriginPresence;

pub use engine::PresentRanges;

pub use engine::ServeAudit;

pub use error::CacheError;

pub use error::CacheResult;

pub use error::ErrorChain;

pub use error::OriginError;

pub use error::OriginPullError;

pub use error::SupportedEncoding;

pub use fill_session::Demand;

pub use fill_session::DemandSlot;

pub use fill_session::DownstreamWatch;

pub use fill_session::FillClaim;

pub use fill_session::FillError;

pub use fill_session::FillRegistry;

pub use fill_session::FillSession;

pub use fill_session::Frontier;

pub use fill_session::HashOutboard;

pub use fill_session::ObserverLease;

pub use fill_session::SessionOutboardReader;

pub use metrics::CacheMetrics;

pub use origin::FilesystemOrigin;

pub use origin::HttpOrigin;

pub use origin::Origin;

pub use origin::OriginFetch;

pub use origin::OriginRangeFetch;

pub use origin::OriginRangeRequest;

pub use origin::OutboardFetch;

pub use origin::S3Credentials;

pub use origin::S3Origin;

pub use origin::S3OriginConfig;

pub use origin_range::MAX_CONCURRENT_RANGE_PULLS;

pub use origin_range::OriginRangeWire;

pub use origin_range::RANGE_PULL_WINDOW_BYTES;

pub use policy::AdmissionContext;

pub use policy::AdmissionDecision;

pub use policy::AdmissionPolicy;

pub use policy::AlwaysAdmit;

pub use policy::EvictionContext;

pub use policy::EvictionPlan;

pub use policy::EvictionPolicy;

pub use policy::FrequencyEstimator;

pub use policy::LruEviction;

pub use policy::Segment;

pub use probe_hold::PROBE_HOLD_DURATION;

pub use probe_hold::PROBE_HOLD_MARGIN;

pub use probe_hold::PROBE_SLASH_WINDOW;

pub use probe_hold::ProbeHoldOutcome;

pub use ranged_store::NodeRangedStore;

pub use serve_store::EncodeStream;

pub use serve_store::PresentRangeWatch;

pub use serve_store::ServeStore;

Modules

circuit_breaker

Per-origin half-open circuit-breaker for pull-through (#963).

engine

Cache engine: local iroh-blobs store fronted by an Origin for misses.

error

Error type for the cache engine.

fill_session

FillSession — the cache-resident fill-coordination primitive the serve-miss legs share (ADR 038).

metrics

Cache-engine OpenMetrics metrics.

origin

Origin backends — the source of truth a node falls back to on a cache miss.

origin_probe

Live-origin probe memo (#1130 pt3): a bounded, TTL’d cache of HEAD/HeadObject existence answers so a per-probe origin existence check does not hammer the backend.

origin_range

Windowed origin range pulls (#2065): the requested span is fetched in bounded windows of RANGE_PULL_WINDOW_BYTES against an {H}.obao4 outboard that the engine caches per hash, so a range pull holds O(window + outboard) bytes whatever its length. Each origin read runs under a time budget (see crate::CacheEngine::set_origin_read_budget).

policy

Pluggable cache admission and eviction policy traits (ADR 040).

probe_hold

Probe-triggered eviction-hold constants (ADR 005 §Probe-triggered eviction hold, §Hold budget; ADR 040 §Pinning, durable operator-evict, and the probe-hold stay engine-enforced).

range_pull

Bao verified-range helpers — re-exported from the iroh-blobs-free decdn_bao_range leaf crate (#578) so decdn-client can share the exact same alignment / encoded-size / verify logic without linking iroh-blobs. The serve (engine::export_bao_range), origin range encode (engine::origin_range_wire), and client-receive paths therefore all agree by construction. See ADR 038 §Wire format.

ranged_store

NodeRangedStore: the node-side RangedStore backend over the iroh-blobs cache (#1621).

retry

Origin pull-through retry policy with exponential backoff and jitter (#285).

serve_store

ServeStore: node-only extension of RangedStore for progressive serve-while-filling (#1621).

Structs

Bytes

A quantity of bytes. Wraps u64; the wire form is a bare integer.

CircuitBreakerPolicy

Per-origin circuit-breaker policy (#963). Field-level validation lives at config-resolve time (crates/common/src/config/mod.rs::resolve_circuit_breaker); this struct just carries the values.

DeniedHashes

Operator-denied blob hashes — the local denylist from ADR 011 §Local Denylist ([content] denied_hashes). A hash here is refused at the delivery path immediately, whether or not the node holds it.

Hash

The blob-store hash. decdn_cache::Hash continues to mean iroh_blobs::Hash (the BLAKE3 digest the iroh-blobs store keys on) so every existing decdn_cache::Hash path in decdn-node and the cache crate is unchanged. The config-vocabulary hash that crosses operator-facing config/admin surfaces is the distinct decdn_config_types::Hash; to_store_hash/from_store_hash convert between the two (both are the same 32 bytes — issue #578). Hash type used throughout.

LeafHash

The config-vocabulary hash type (decdn_config_types::Hash), re-exported so callers can build a DeniedHashes / PinnedHashes without taking a direct dependency on the leaf crate. Distinct from Hash, which is the iroh-blobs store hash — see the hash_bridge conversions. 32-byte BLAKE3 content address. The serde representation is the lowercase 64-char hex string — byte-identical to the form iroh_blobs::Hash produces, so admin JSON-RPC and config TOML stay wire-compatible. decdn-cache converts between this and iroh_blobs::Hash at its public boundary (both are the same 32-byte digest).

OriginUrl

Parsed, scheme-validated, and path-normalized origin base URL. The only way to construct one is parse_origin_url — once you have an OriginUrl, the following invariants are guaranteed by the type:

PinDiff

Cheap diff of two hash-set snapshots (PinnedHashes or DeniedHashes), for the reload log line.

PinnedHashes

Operator-pinned blob hashes (#276). Hashes here are excluded from the LRU eviction-candidate snapshot. Constructing this type is the only way to feed pinned hashes into CacheEngine::open_with_pinned or CacheEngine::set_pinned, so a future “blocklist” or similar HashSet<Hash>-shaped feature can’t be silently passed into the pinning slot.

RetryPolicy

Origin retry policy. Field-level validation lives at config-resolve time (crates/common/src/config/mod.rs::resolve_origin_retry); this struct just carries the values.

Enums

DecompressMode

How the HTTP origin handles Content-Encoding on the response.

HashParseError

Error returned when a string is not a valid 64-char lowercase-or-mixed hex BLAKE3 digest.

OriginKind

Tag identifying which origin backend a cache engine is configured against (#439). Surfaced through the admin eviction-preview so dry-run callers can estimate origin egress cost — re-fetching from a Filesystem origin is a local read; Http and S3 may consume metered bandwidth.

Constants

CHUNK_GROUP_BYTES

Bao chunk-group granularity (16 KiB, ADR 038), re-exported because it is a billing-visible property of CacheEngine::export_bao_range_stream: the export snaps a requested range out to the enclosing group boundaries and the serve path does not trim back, so the payer is charged for the aligned superset. Any caller pricing a range before serving it must align first or it under-reserves by up to two groups. Bytes per chunk group, derived from IROH_BLOCK_SIZE (2^chunk_log 1 KiB chunks) — the granularity an origin range must snap to, because a bao proof anchors whole chunk groups to the root.

DEFAULT_MAX_PROBE_HOLDS

Default ceiling on concurrently-held probe slots before the cache engine starts rejecting new probe holds (#276 / ADR 005). Shared so the config default and the cache engine’s own default cannot drift.

DEFAULT_USER_AGENT

Default User-Agent header set on every origin request unless overridden via the operator-configured cache.user_agent. Embeds CARGO_PKG_VERSION of this crate (decdn-config-types). The workspace does not version-link its members, so this can drift from the running decdn-node binary’s version — that is acceptable: the decdn-node/ prefix is the stable contract operators grep on in access logs; the version segment is best-effort attribution (#435, #578). Lets origin operators attribute CDN pull-through traffic and apply origin-side rate limits or routing rules separately from anonymous client traffic.

Functions

from_store_hash

Convert a blob-store Hash into a config-vocabulary decdn_config_types::Hash.

parse_origin_url

Parse and normalize an origin base URL. This is the single source of truth for origin-URL validation — config resolution and test helpers both go through it, and the returned OriginUrl carries the scheme/path/query invariants in the type.

redact_for_log

Return a loggable form of an origin URL with userinfo (user:pass@) stripped. Operators may legitimately use basic-auth-in-URL for internal origins, but those credentials must not reach logs or error messages.

to_store_hash

Convert a config-vocabulary decdn_config_types::Hash into the blob-store Hash. Both are 32-byte BLAKE3 digests; this is a pure byte-for-byte reinterpretation (issue #578). Used at the node’s admin boundary where parse_hash_arg yields the config-vocabulary hash that must then index the store.