Struct S3Origin 

pub struct S3Origin { /* private fields */ }

Origin backed by an S3-compatible object store.

Clone is cheap: the inner Client is Clone and uses an Arc internally; the bucket and prefix fields use Arc<str> so adding labels to diagnostic logs doesn’t allocate.

Implementations

impl S3Origin

pub async fn new(cfg: &S3OriginConfig) -> Result<Self>

Build an S3Origin from validated config. Returns an error if a Static credential variant carries empty bytes (defense in depth against a config-resolver gap or a hand-built S3OriginConfig).

I/O posture: construction itself is non-blocking — aws_config builds lazy provider chains and resolves credentials on the first signed request, not at load() time. The one operator-visible caveat is the AWS SSO provider (enabled via the sso feature on aws-config): if the ~/.aws/config profile in use is configured for SSO and the cached SSO token has expired, the first fetch call may fire an HTTP request to the SSO endpoint to refresh the token. That’s a property of the AWS credential chain, not this constructor; the construction itself stays I/O-free.

BehaviorVersion::latest() is set explicitly even though aws-config’s behavior-version-latest feature would imply the same. Belt-and-braces against a future feature-flag edit dropping the implicit path — older SDK versions panicked when no BehaviorVersion was set; current versions surface a runtime error. Either way, the explicit call site cannot regress.

Runtime: the origin’s pooled connections live on the tokio runtime this future runs on, and every later request send runs there (see origin::io_runtime). Build it on a runtime that outlives every fetch — the node’s main runtime — never on a short-lived one such as a pull leg’s.

Errors

Fails when a Static credential carries an empty key or secret, or when this future does not run inside a tokio runtime.

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. Mirrors super::HttpOrigin::with_decompress_mode so the wiring layer can honour an operator-configured decompress knob uniformly across backends.

Trait Implementations

impl Clone for S3Origin

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 S3Origin

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

Formats the value using the given formatter.

impl Origin for S3Origin

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