Struct HttpOrigin 

pub struct HttpOrigin { /* private fields */ }

Origin backed by a plain HTTP(S) endpoint serving content-addressed blobs at {base_url}/{blake3_hex}.

Implementations

impl HttpOrigin

pub fn new(base_url: OriginUrl) -> Result<Self>

Build an HttpOrigin around a validated OriginUrl. The only way to obtain one is parse_origin_url, so invariants are enforced at the type boundary rather than documented in prose. Timeouts default to the RESPONSE_HEADERS_TIMEOUT and CHUNK_IDLE_TIMEOUT constants; override with Self::with_timeouts if operator policy or tests require different values.

Sets DEFAULT_USER_AGENT on the inner reqwest client so origin access logs can attribute CDN pull-through traffic (#435). Override via Self::new_with_user_agent.

The origin’s connections live on the tokio runtime this is called on, so call it on a runtime that outlives every fetch (the node’s main runtime).

Errors

Fails outside a tokio runtime, or when the reqwest client cannot be built.

pub fn new_with_user_agent( base_url: OriginUrl, user_agent: &str, ) -> Result<Self>

Like Self::new but with a caller-supplied User-Agent. Used by the runtime to honour an operator-configured cache.user_agent without rebuilding the client through a separate code path. user_agent must be a valid header value (visible-ASCII; reqwest rejects others at build time and the error is surfaced as a startup failure).

Errors

Fails outside a tokio runtime, or when the reqwest client cannot be built (an invalid user_agent).

pub fn parse(raw: &str) -> Result<Self>

Convenience constructor that parses raw via parse_origin_url before delegating to Self::new. Prefer Self::new in runtime paths so URL validation happens at config-load time.

pub const fn with_timeouts( self, response_headers_timeout: Duration, chunk_idle_timeout: Duration, ) -> Self

Override the phase timeouts. Primarily exists for tests — runtime callers should use the defaults unless operator policy dictates otherwise.

pub const fn with_decompress_mode(self, mode: DecompressMode) -> Self

Set the DecompressMode. See that type for the semantics of Auto vs Strict. Defaults to Auto.

Trait Implementations

impl Clone for HttpOrigin

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 HttpOrigin

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

Formats the value using the given formatter.

impl Origin for HttpOrigin

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).