Struct GetAvailabilityParams 

#[non_exhaustive]
pub struct GetAvailabilityParams {
    pub items: Vec<AvailabilityQuery>,
    pub redirect_depth: Option<u64>,
    pub budget_ms: Option<u64>,
    pub ask_id: Option<String>,
}

Params for dig.getAvailability.

Construction

Like FetchRangeParams, this type is #[non_exhaustive]: build it with new plus the with_* setters rather than a struct literal, so a future additive field is a PATCH for every consumer instead of a semver cascade.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

items: Vec<AvailabilityQuery>

The items to check. Capped at 512 per batch (past-cap items are dropped).

redirect_depth: Option<u64>

The hop budget already consumed by this ask. Absent means zero — read it through hops_consumed, never directly.

What it means for an availability ask

An availability answer is not only this node’s holdings: on a miss it may name the holders it located, in AvailabilityAnswer::providers — the same enrichment a RedirectInfo carries. A responder that cannot answer from what it holds MAY ask its own peers, so one caller’s question can walk several hops, and each hop is a node spending someone else’s bandwidth. This field is what bounds that walk.

It is the SAME budget, counted the SAME way, as RedirectInfo::redirect_depth and as the redirect_depth that GetContentParams and FetchRangeParams already echo: the number of hops ALREADY CONSUMED when this ask arrives, counting UP from zero — never a remaining allowance counting down. A responder that asks onward sends hops_consumed() + 1 (saturating at the type maximum), and MUST NOT ask onward when that would reach the budget it advertises as RedirectInfo::max_redirects.

Absent reads as a fresh, unhopped ask, so a client written before this field existed is served unchanged.

budget_ms: Option<u64>

The wall-clock TIME this ask may still spend, in milliseconds. Absent means unbudgeted — read it through budget_ms, never directly.

Why this is its OWN field and not the hop budget

redirect_depth counts hops UP from zero toward a ceiling; this counts milliseconds DOWN toward zero. The two move in opposite directions along different axes, so one integer cannot carry both, and folding them together would make “one more hop” and “more time” the same request.

The contract a relaying responder MUST honour

A responder that asks its own peers onward MUST pass a value it has decremented by the time it has itself already spent, and it MUST NOT grant a child less time than the work it asks that child to do. Concretely: a parent that asks n children SEQUENTIALLY must divide the remaining budget between them, and a parent with less time left than one round trip needs MUST answer ContentMissInconclusive rather than ask onward and then time out.

This exists because the alternative is measurable: a FIXED per-ask bound with sequential asks and a fan-out greater than one guarantees the second hop times out, and a responder that reads that timeout as a miss reports a CONFIDENT not-found for content it never looked for.

Absent reads as unbudgeted, so a client written before this field existed is served exactly as it was.

ask_id: Option<String>

An opaque identity for this ask, for cross-path dedup. Absent means the caller opted out of dedup — read it through ask_id.

What it is for

A recursive ask walks a graph, not a tree. Two disjoint paths can arrive at the same responder, and without a shared identity that responder cannot tell a re-walk from a fresh question — so a diamond in the peer graph does not terminate. A responder that has already seen an ask_id MUST answer from what it already knows instead of asking onward again.

What it is NOT

It is not the JSON-RPC id. That field correlates one request with one response on one connection; it is chosen per-connection, is commonly a small constant, and says nothing about whether two arrivals are the same ask. An implementation that reused the JSON-RPC id for dedup would either collide every unrelated ask together or dedup nothing at all.

Requirements

32 lowercase hex characters: 16 unpredictable random bytes, freshly drawn by the ORIGINATOR and copied verbatim by every relaying hop. It MUST be unpredictable, because a value an attacker can guess lets that attacker pre-poison a responder dedup memo and suppress an ask that has not happened yet. A responder MUST NOT derive anything from its value beyond EQUALITY — it carries no structure, no origin, no timestamp and no ordering.

Implementations

impl GetAvailabilityParams

pub fn new(items: Vec<AvailabilityQuery>) -> Self

An availability batch for items, asked at hop zero.

pub fn with_redirect_depth(self, redirect_depth: u64) -> Self

Echo the hop budget already consumed — from a -32008 redirect, or from the ask this one is being made on behalf of. See redirect_depth.

pub fn hops_consumed(&self) -> u64

The hops already consumed by this ask.

The single home for the “absent means zero” rule. A responder that reached for redirect_depth.is_some() instead would read every pre-0.8 client’s ask as budget-free and forward it without bound — the amplification the budget exists to stop.

pub fn with_budget_ms(self, budget_ms: u64) -> Self

Set the remaining time budget for this ask. See budget_ms.

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

The time this ask may still spend, or None when the caller sent no budget.

Deliberately NOT collapsed to a number, unlike hops_consumed: there is no safe scalar default. Zero would refuse every older caller ask outright, and any positive default would silently impose one node idea of patience on another node question. A responder that receives None applies its OWN policy and passes on what it granted.

pub fn with_ask_id(self, ask_id: impl Into<String>) -> Self

Set the cross-path dedup identity. See ask_id.

pub fn ask_id(&self) -> Option<&str>

The dedup identity, or None when the caller opted out of dedup.

Trait Implementations

impl Clone for GetAvailabilityParams

fn clone(&self) -> GetAvailabilityParams

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for GetAvailabilityParams

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for GetAvailabilityParams

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for GetAvailabilityParams

impl PartialEq for GetAvailabilityParams

fn eq(&self, other: &GetAvailabilityParams) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for GetAvailabilityParams

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for GetAvailabilityParams