Struct PeerSelector 

pub struct PeerSelector { /* private fields */ }

The self-optimizing peer selector (SPEC §5, §11). Construct with PeerSelector::new, feed it registry churn + DHT candidates, ask it to select a source subset, and stream every measured outcome back via record_outcome.

Implementations

impl PeerSelector

pub fn new(config: SelectorConfig) -> Self

Construct a selector from wiring-only SelectorConfig (SPEC §5.6). No behavior knobs — every tradeoff is learned.

pub fn select( &self, req: &ContentRequest, candidates: &[Candidate], ) -> Selection

select — rank a candidate set for a request (SPEC §5.1).

Registers any fresh candidate (cold — its first pick is exploratory, SPEC §2.3, §4.4-E), scores every eligible candidate against the learned models, and returns a ranked chosen subset bounded by the request’s parallelism. Each chosen peer carries its recommended max_concurrency (its learned saturation headroom, SPEC §4.1/§4.5) and its exploratory flag. Anti-herd: total dispatched concurrency is filled peer-by-peer up to each peer’s headroom, spilling to the next (SPEC §4.4-B). Dispatch bumps in-flight so the very next select/rebalance sees it.

pub fn rebalance( &self, req: &ContentRequest, active: &[PeerId], need: &RangePlanDelta, ) -> Selection

rebalance — re-query the up-to-the-moment models for still-needed ranges (SPEC §5.5).

Mid-transfer, when a source drops or a range must be relocated, the executor calls this to get a replacement subset for the needed ranges, de-ranking the already-active peers (they are counted as busy so their headroom shrinks) and reflecting every record_outcome received so far. It obeys the same invariants as select (SPEC §4.4).

pub fn record_outcome(&self, outcome: &TransferOutcome)

record_outcome — fold a measured result back into the models in real time (SPEC §5.2).

Derives throughput strictly from measured bytes / duration_ms (never a self-reported rate, SPEC §9.3); updates throughput/RTT/reliability (SPEC §3.2, §3.4), the per-class saturation model (SPEC §4.1), the adaptive relayed penalty (SPEC §4.2), and decrements in-flight (SPEC §5.3). An outcome for an unknown peer upserts a cold entry first (self-healing, SPEC §5.2).

pub fn on_pool_event(&self, event: &PoolEvent)

Consume a dig-gossip churn event to keep the registry live (SPEC §5.4, §2.3). Byte-compatible with dig_gossip::PoolEvent (see crate::pool_event).

pub fn on_connection_class(&self, peer: &PeerId, class: TraversalKind)

Attach / update a live peer’s connection class from dig-nat (SPEC §5.4, §7.3).

pub fn upsert_candidate(&self, candidate: &Candidate)

Manually upsert a candidate (seed / bootstrap feed, SPEC §5.4). A fresh peer is cold.

pub fn remove_peer(&self, peer: &PeerId)

Explicitly remove a peer (rare; churn usually drives this — SPEC §5.4). A peer with a range in flight is retained until it settles.

pub fn on_dispatch(&self, peer: &PeerId, count: u32)

Explicitly note that count ranges were dispatched to peer (SPEC §5.3). Optional: select already accounts the dispatch it returns; the host uses this only if it dispatches outside a select result.

pub fn peer_snapshot(&self, peer: &PeerId) -> Option<PeerSnapshot>

A read-only snapshot of one peer’s learned model, or None if unknown (SPEC §5.7).

pub fn snapshot(&self) -> SelectorSnapshot

A read-only snapshot of the selector’s learned aggregate state (SPEC §5.7). Includes the engine’s internal side-map sizes (last_selected_len, dispatched_len) so a host can confirm they track the live registry population rather than growing unboundedly (#179 finding 2).

pub fn registry_size(&self) -> usize

The current registry size (SPEC §5.7).