Module mesh_swarm_fetch

Expand description

Multi-source swarm fetch (ADR-099 section 6, card mesh-placement-25).

ArtifactExchange::swarm_fetch pulls one artifact from several holders at once, on top of the card 11 piece protocol:

Sources. Candidates are ranked by trust tier, then locality, then measured link speed (order_peers); up to max_sources are dialed. The first peer that answers fixes the descriptor; every other source must present the same artifact id.
Scheduling. One worker per peer. Each worker asks the shared PiecePicker for the rarest piece its peer holds that nobody else is fetching, requests it, verifies its hash and stores it. A faster peer simply asks again sooner, so work follows measured speed.
Reliability. A worker whose peer drops, times out or lacks the piece hands its pieces back and another peer picks them up; a lost source is replaced from the remaining candidates. A peer that serves a corrupt piece is banned (artifact.piece_rejected, artifact.peer_ban) and its piece is fetched elsewhere.
Bandwidth. Received bytes are paced by the node’s download cap.
Limits. A descriptor with a piece size over max_piece_size, a total over max_artifact_bytes, or one that does not fit the caller’s Expect (exact size from a signed manifest) is refused before any piece is requested. At most one piece is buffered per source, so memory is bounded by max_sources x max_piece_size.
Verification. When every piece is held, the whole-content hash is checked (ArtifactExchange::promote). A verified artifact that a verified manifest allows is seeded from then on (artifact.seed).

The outcome is chained once as artifact.fetch, like the single-source fetch, with the sources, rejected and lost peers added.

Structs§

Expect: What the caller already knows about the artifact, from a signed manifest. A peer’s descriptor that does not fit is refused before any piece is requested.
SwarmFetchOptions: Per-fetch settings.