Struct FetchRequest 

pub struct FetchRequest<'a> { /* private fields */ }

The inputs to one fetch.

Fetch::fetch takes its inputs as this value rather than as loose parameters, so that per-request context an implementation comes to need — a byte range, an expected digest, a conditional-request stamp, extra headers — can be added as accessors without changing the trait method’s signature.

A Fetch implementation reads what it understands and ignores the rest.

Implementations

impl<'a> FetchRequest<'a>

pub fn new(url: &'a str) -> FetchRequest<'a>

Returns a request for url.

pub fn sized(self, bytes: u64) -> FetchRequest<'a>

Records the size the body is expected to be, in bytes.

The provisioner states it wherever a verified source declares it: the signed release records the length of every index alongside its digest, and the index records the length of every package. Both are known before the request is made and are as trustworthy as the signature they hang from.

pub fn url(&self) -> &'a str

The URL to fetch.

The scheme is case-insensitive (RFC 3986 §3.1); the rest of the URL is not. An implementation that routes on the scheme — handing https:// URLs to a TLS transport and delegating the rest, say — reaches it through scheme rather than by splitting this string, so that the two layers cannot disagree about which URLs name TLS.

pub fn scheme(&self) -> Option<&'a str>

The scheme the URL names, or None for a reference that names none.

This is the accessor a transport routes on. The scheme is the text before ://, spelled ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ) by RFC 3986 §3.1, so a path reference that happens to contain :// does not read as one. None is a real input rather than a broken one: a caller may name a mirror by a bare path, and a transport that serves only absolute URLs answers it with FetchError::url.

It is returned exactly as written. Schemes are case-insensitive, so a comparison against it must be too — this crate’s own client matches HTTP:// and http:// alike, and a transport that matched literally would refuse URLs the layer above it had already accepted.

Example

Routing by scheme, compared the way the rule requires:

use ferroday_cage::provision::FetchRequest;

let request = FetchRequest::new("HTTPS://deb.debian.org/debian/Release");
let scheme = request.scheme().unwrap_or_default();

// `eq_ignore_ascii_case`, not `==`: the archive may be configured in
// any case, and the two spellings name one transport.
assert!(scheme.eq_ignore_ascii_case("https"));
assert_eq!(scheme, "HTTPS", "the scheme is returned as written");

pub fn size(&self) -> Option<u64>

The size the body is expected to be, or None where nothing declares one — a release file, which is the trust root and so has no signed length of its own.

An implementation that honours it refuses a body larger than the stated size, and may refuse a declared framing larger than it before reading anything: a mirror that answers a request for a few megabytes with gigabytes is not serving the resource that was asked for, and the digest check that would catch the substitution runs only after the bytes have been spent. It is a ceiling, not a promise — an implementation is free to ignore it, and the provisioner bounds its own sink regardless.

Trait Implementations

impl<'a> Clone for FetchRequest<'a>

fn clone(&self) -> FetchRequest<'a>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Copy for FetchRequest<'a>

impl<'a> Debug for FetchRequest<'a>

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

Formats the value using the given formatter.