Struct FilesystemOrigin 

pub struct FilesystemOrigin { /* private fields */ }

Origin backed by a local filesystem directory. Blobs live at {base}/{hex[0..2]}/{hex}; the engine is responsible for BLAKE3 verification after the bytes come back (same contract as every other Origin impl).

Implementations

impl FilesystemOrigin

pub async fn new(base: impl Into<PathBuf>) -> Result<Self>

Construct an origin rooted at base. Fails fast if base doesn’t exist or isn’t a directory — a typo in the config shouldn’t surface as a per-request miss.

base is canonicalized so the per-request containment check in Origin::fetch can compare a resolved blob path against a resolved root. Without this, an operator who configured the origin via a symlinked path would have every fetch look “outside” itself.

pub fn base(&self) -> &Path

Expose the configured base for diagnostics / logging.

Trait Implementations

impl Clone for FilesystemOrigin

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for FilesystemOrigin

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

Formats the value using the given formatter.

impl Origin for FilesystemOrigin

fn kind(&self) -> OriginKind

Tag identifying the backend type. Surfaced through crate::EvictionPreview::origin_kinds so admin dry-run callers can estimate origin egress cost (#439) — Filesystem is a local read; Http may bill metered bandwidth.

fn fetch( &self, hash: Hash, max_bytes: u64, ) -> Pin<Box<dyn Future<Output = Result<OriginFetch, OriginPullError>> + Send + '_>>

Fetch the blob with the given hash. max_bytes is an advisory cap — implementations should short-circuit if they can cheaply detect the payload would exceed it (e.g. from a Content-Length header), and the cache engine enforces the cap on the returned bytes regardless.

fn fetch_range_data( &self, hash: Hash, req: OriginRangeRequest, ) -> Pin<Box<dyn Future<Output = Result<OriginRangeFetch, OriginPullError>> + Send + '_>>

Fetch the chunk-group-aligned byte span req of the blob hash, for a range-scoped pull (ADR 037 §Origin-tier pull-through, #823). Each call covers at most crate::RANGE_PULL_WINDOW_BYTES; a longer span takes several calls, in order. The engine fetches the sibling {H}.obao4 outboard separately through Self::fetch_outboard.

fn fetch_outboard( &self, hash: Hash, outboard_max_bytes: u64, ) -> Pin<Box<dyn Future<Output = Result<OutboardFetch, OriginPullError>> + Send + '_>>

Fetch just the sibling {H}.obao4 outboard for the blob hash — no accompanying blob data (#1130, feeds a later “stream-while-store” serve path: a node that holds the outboard can start verifying against H before the full blob has finished pulling through). outboard_max_bytes caps the read — the engine derives it from the blob size (an outboard is O(blob/256)), and an oversize outboard is malformed/foreign. The engine caches a non-empty outboard of at most 256 MiB (a blob of up to 64 GiB) per hash across range pulls, so it reads such an outboard once while the entry stays cached. It reads an empty outboard, or a larger one, again on each draw. Each pull fetches its span window by window through Self::fetch_range_data.

fn size( &self, hash: Hash, ) -> Pin<Box<dyn Future<Output = Result<Option<u64>, OriginPullError>> + Send + '_>>

Best-effort total byte size of the blob hash, used to scope a range-pull (Self::fetch_range_data, #823): the bao tree needs the blob’s exact total length to verify a sub-range against the root H, and the {H}.obao4 outboard alone only pins the size to within one chunk group (IROH_BLOCK_SIZE, 16 KiB — the final group’s true length isn’t in the tree). The cdn/client/v1 serving handler calls this on a cold cache miss — via crate::CacheEngine::origin_size — before it signs a response and runs the two-leg serve-miss spine over crate::CacheEngine::origin_range_wire.

fn enumerate( &self, ) -> Pin<Box<dyn Future<Output = Result<Vec<Hash>, OriginPullError>> + Send + '_>>

Enumerate the hashes this origin currently holds, so a node can advertise them (probe has_blob / DHT announce) before any pull-through — closing the “cold origin blob is undiscoverable until first pulled” gap (#1130).