Module peer_capability_negotiator 

Peer Capability Negotiation

This module implements PeerCapabilityNegotiator, a production-grade system for discovering, advertising, and negotiating compatible protocol capabilities between peers during connection establishment.

Overview

When two IPFRS nodes connect, they exchange NegotiationOffer messages describing their supported capabilities (e.g. “bitswap/2.0.0”, “graphsync/1.1.0”). The negotiator evaluates each offer against its local NegotiatorConfig and returns a NegotiationResult indicating which capabilities were agreed upon or why the negotiation was rejected.

Policies

Three CapabilityPolicy variants control strictness:

• RequireAll – Every required local capability must appear in the peer’s offer; any mismatch yields an immediate NegotiationResult::Rejected.
• RequireSubset(names) – Only the named subset of capabilities must match.
• BestEffort – Always produces NegotiationResult::Accepted; unmatched required capabilities are listed in rejected_optional for caller visibility.

Example

use ipfrs_network::peer_capability_negotiator::{
    CapabilityPolicy, CapabilityVersion, NegotiationOffer, NegotiatorConfig,
    PeerCapabilityNegotiator, PeerCapability,
};
use std::collections::HashMap;

let local_cap = PeerCapability {
    name: "bitswap".to_string(),
    version: CapabilityVersion { major: 2, minor: 0, patch: 0 },
    required: true,
    metadata: HashMap::new(),
};

let config = NegotiatorConfig {
    local_capabilities: vec![local_cap],
    policy: CapabilityPolicy::RequireAll,
    min_protocol_version: 1,
    negotiation_timeout_ms: 5_000,
};

let mut negotiator = PeerCapabilityNegotiator::new(config, 128);

let offer = NegotiationOffer {
    peer_id: "QmPeer".to_string(),
    capabilities: vec![PeerCapability {
        name: "bitswap".to_string(),
        version: CapabilityVersion { major: 2, minor: 1, patch: 0 },
        required: false,
        metadata: HashMap::new(),
    }],
    protocol_version: 2,
    timestamp: 1_000,
};

let result = negotiator.negotiate("QmPeer".to_string(), offer, 1_000, 1_050);
// "bitswap" v2.1.0 is compatible with required v2.0.0 → Accepted.
assert!(matches!(result, ipfrs_network::peer_capability_negotiator::NegotiationResult::Accepted { .. }));

Structs

CapabilityVersion

Semantic version triple for a single capability.

NegotiationOffer

A capability advertisement sent by a remote peer at connection time.

NegotiationRecord

A historical record of a completed negotiation with a specific peer.

NegotiatorConfig

Configuration for a PeerCapabilityNegotiator.

NegotiatorStats

Aggregate statistics for a PeerCapabilityNegotiator.

PeerCapability

A single named capability with version and optional metadata key-value pairs.

PeerCapabilityNegotiator

Production-grade peer capability negotiator.

Enums

CapabilityPolicy

Governs how strictly the negotiator validates a peer’s offer.

NegotiationResult

Outcome of a capability negotiation attempt.