Module selection 

Provider selection algorithm (ADR 001 § Node Selection Algorithm + ADR 008 § Tie-Breaking).

rank_candidates returns the input list ordered best-first (lowest score first) with the three-tier tie-breaker applied. The caller iterates the result in order and stops after MAX_PROVIDER_ATTEMPTS failed providers.

Structs

Candidate

A candidate provider produced by content discovery, ready to be ranked.

RankedCandidate

A candidate paired with its computed selection score. Lower score is better.

Constants

CHANNEL_OPEN_CALLER_BUDGET

How long a pull is willing to WAIT on a buyer-channel open before giving up on that candidate — not how long the open itself is allowed to take (#1143).

MAX_PROVIDER_ATTEMPTS

Maximum providers to attempt before reporting a fetch failure to the caller (issue #322 — “max 3 provider attempts before returning error”).

PROBE_EARLY_EXIT_CANDIDATES

How many blob-holding candidates a SINGLE-SOURCE probe round collects before it stops waiting on the rest. PROBE_TIMEOUT stays the ceiling — a sparse round that never reaches this count still waits it out — but when this many good providers have already answered, the round selects among them instead of waiting the full window for a straggler or a dead peer that will only time out. The count leaves at least one alternate in hand for per-blob failover while keeping cold-miss discovery latency at the speed of the fastest good answers rather than the ceiling. ADR 001 § Probe response collection.

PROBE_TIMEOUT

Per-candidate probe timeout. Because candidates are probed concurrently, this also bounds the whole probe-collection phase. The budget covers connection setup plus one unpaid probe request/response. probe_once dials a fresh connection every call, and the protocol has no 0-RTT path, so even a resumable session pays a handshake round trip before the request goes out — every probe costs two RTTs, not one. At the 250-300 ms inter-continental RTTs this budget is sized against, that puts the furthest candidates at or past this ceiling. Dropping them is the intended trade (a slow candidate must not burn the caller’s miss-latency budget), but this is the first term to revisit if distant-region selection looks too sparse. Both the figure and the trade are ADR 001 § Probe response collection.

PULL_THROUGH_OUTER_SLACK

One-time headroom added on top of the MAX_PROVIDER_ATTEMPTS sequential per-candidate costs when computing the outer pull-through deadline (#859). It covers the one-time discover → probe → rank overhead: work that runs under the outer deadline but does not scale with the attempt count.

Functions

outer_pull_deadline

Outer deadline for a node-to-node pull-through, derived from the two configured per-candidate budgets: the stream-open timeout (cache.node_pull_timeout_sec) and the streaming throughput-floor window (cache.node_pull_stall_window_sec).

rank_candidates

Rank candidates by selection score, lowest (best) first.