Crate ipfrs_network 

IPFRS Network - libp2p-based networking layer

This crate provides the networking infrastructure for IPFRS including:

• libp2p node management with full protocol support
• QUIC transport with TCP fallback for reliable connectivity
• Kademlia DHT for content and peer discovery
• Bitswap protocol for block exchange
• mDNS for local peer discovery
• Bootstrap peer management with retry logic and circuit breaker
• Provider record caching with TTL and LRU eviction
• Connection limits and intelligent pruning
• Network metrics and Prometheus export
• NAT traversal (AutoNAT, DCUtR, Circuit Relay v2)
• Query optimization with early termination and pipelining
• Comprehensive health monitoring and logging

Features

Core Networking

• Multi-transport: QUIC (primary) with TCP fallback for maximum compatibility
• NAT Traversal: AutoNAT for detection, DCUtR for hole punching, Circuit Relay for fallback
• Peer Discovery: Kademlia DHT, mDNS for local peers, configurable bootstrap nodes
• Connection Management: Intelligent limits, priority-based pruning, bandwidth tracking

DHT Operations

• Content Routing: Provider record publishing and discovery with automatic refresh
• Peer Routing: Find closest peers, routing table management
• Query Optimization: Early termination, pipelining, quality scoring
• Caching: Query results and provider records with TTL-based expiration
• Semantic Routing: Vector-based content discovery using embeddings and LSH

Pub/Sub Messaging

• GossipSub: Topic-based publish/subscribe messaging
• Mesh Formation: Automatic peer mesh optimization for topic propagation
• Message Deduplication: Efficient duplicate detection
• Peer Scoring: Quality-based peer selection for reliable delivery

Reliability

• Retry Logic: Exponential backoff with configurable limits
• Circuit Breaker: Prevent cascading failures with failing peers
• Fallback Strategies: Alternative peers, relay fallback, degraded mode
• Health Monitoring: DHT health, connection health, bandwidth metrics

Monitoring & Observability

• Metrics: Connection stats, DHT stats, bandwidth tracking, query performance
• Prometheus Export: Ready-to-use metrics export for monitoring systems
• Structured Logging: Tracing spans with context propagation
• Health Checks: Component-level and overall health assessment

Quick Start

use ipfrs_network::{NetworkConfig, NetworkNode};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create configuration
    let config = NetworkConfig {
        listen_addrs: vec!["/ip4/0.0.0.0/udp/0/quic-v1".to_string()],
        enable_quic: true,
        enable_mdns: true,
        enable_nat_traversal: true,
        ..Default::default()
    };

    // Create and start network node
    let mut node = NetworkNode::new(config)?;
    node.start().await?;

    // Check network health
    let health = node.get_network_health();
    println!("Network status: {:?}", health.status);

    // Announce content to DHT
    let cid = cid::Cid::default();
    node.provide(&cid).await?;

    // Get network statistics
    let stats = node.stats();
    println!("Connected peers: {}", stats.connected_peers);

    Ok(())
}

High-Level Facade

For easy integration of all features, use the NetworkFacade:

use ipfrs_network::NetworkFacadeBuilder;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a mobile-optimized node with advanced features
    let mut facade = NetworkFacadeBuilder::new()
        .with_preset_mobile()
        .with_semantic_dht()
        .with_gossipsub()
        .build()?;

    facade.start().await?;
    println!("Peer ID: {}", facade.peer_id());
    Ok(())
}

Architecture

The crate is organized into several modules:

• facade: High-level facade for easy integration of all modules
• auto_tuner: Automatic network configuration tuning based on system resources
• benchmarking: Performance benchmarking utilities for network components
• node: Core NetworkNode implementation with libp2p swarm management
• dht: Kademlia DHT operations and caching
• peer: Peer store for tracking known peers and their metadata
• connection_manager: Connection limits and intelligent pruning
• bootstrap: Bootstrap peer management with retry logic
• providers: Provider record caching with TTL
• query_optimizer: Query optimization and performance tracking
• metrics: Network metrics and Prometheus export
• health: Health monitoring for network components
• logging: Structured logging and tracing
• protocol: Custom protocol support and version negotiation
• fallback: Fallback strategies for resilience
• semantic_dht: Vector-based semantic DHT for content routing by similarity
• gossipsub: Topic-based pub/sub messaging with mesh optimization
• geo_routing: Geographic routing optimization for proximity-based peer selection
• dht_provider: Pluggable DHT provider interface for custom DHT implementations
• peer_selector: Intelligent peer selection combining geographic proximity and quality metrics
• multipath_quic: QUIC multipath support for using multiple network paths simultaneously
• tor: Tor integration for privacy-preserving networking with onion routing and hidden services
• diagnostics: Network diagnostics and troubleshooting utilities
• session: Connection session management with lifecycle tracking and statistics
• rate_limiter: Connection rate limiting for preventing connection storms and resource exhaustion
• reputation: Peer reputation system for tracking and scoring peer behavior over time
• metrics_aggregator: Time-series metrics aggregation with statistical analysis and trend tracking
• load_tester: Load testing and stress testing utilities for performance validation
• traffic_analyzer: Traffic pattern analysis and anomaly detection for network insights
• network_simulator: Network condition simulation for testing under adverse conditions
• policy: Network policy engine for fine-grained control over operations
• utils: Common utility functions for formatting, parsing, and network operations

Examples

See the examples/ directory for more comprehensive examples:

• network_facade_demo.rs: Using the NetworkFacade for easy integration
• basic_node.rs: Creating and starting a basic network node
• dht_operations.rs: Content announcement and provider discovery
• connection_management.rs: Connection tracking and bandwidth monitoring

Re-exports

pub use adaptive_polling::ActivityLevel;

pub use adaptive_polling::AdaptivePolling;

pub use adaptive_polling::AdaptivePollingConfig;

pub use adaptive_polling::AdaptivePollingError;

pub use adaptive_polling::AdaptivePollingStats;

pub use arm_profiler::ArmDevice;

pub use arm_profiler::ArmProfiler;

pub use arm_profiler::PerformanceSample;

pub use arm_profiler::PerformanceStats;

pub use arm_profiler::ProfilerConfig;

pub use arm_profiler::ProfilerError;

pub use auto_tuner::AutoTuner;

pub use auto_tuner::AutoTunerConfig;

pub use auto_tuner::AutoTunerError;

pub use auto_tuner::AutoTunerStats;

pub use auto_tuner::SystemResources;

pub use auto_tuner::WorkloadProfile;

pub use background_mode::BackgroundModeConfig;

pub use background_mode::BackgroundModeError;

pub use background_mode::BackgroundModeManager;

pub use background_mode::BackgroundModeStats;

pub use background_mode::BackgroundState;

pub use benchmarking::BenchmarkConfig;

pub use benchmarking::BenchmarkError;

pub use benchmarking::BenchmarkResult;

pub use benchmarking::BenchmarkType;

pub use benchmarking::PerformanceBenchmark;

pub use bitswap::Bitswap;

pub use bitswap::BitswapEvent;

pub use bitswap::BitswapMessage;

pub use bitswap::BitswapStats;

pub use bootstrap::BootstrapConfig;

pub use bootstrap::BootstrapManager;

pub use bootstrap::BootstrapStats;

pub use connection_manager::ConnectionDirection;

pub use connection_manager::ConnectionLimitsConfig;

pub use connection_manager::ConnectionManager;

pub use connection_manager::ConnectionManagerStats;

pub use connection_migration::ConnectionMigrationManager;

pub use connection_migration::MigrationAttempt;

pub use connection_migration::MigrationConfig;

pub use connection_migration::MigrationError;

pub use connection_migration::MigrationState;

pub use connection_migration::MigrationStats;

pub use dht::DhtConfig;

pub use dht::DhtHealth;

pub use dht::DhtHealthStatus;

pub use dht::DhtManager;

pub use dht::DhtStats;

pub use dht_provider::DhtCapabilities;

pub use dht_provider::DhtPeerInfo;

pub use dht_provider::DhtProvider;

pub use dht_provider::DhtProviderError;

pub use dht_provider::DhtProviderRegistry;

pub use dht_provider::DhtProviderStats;

pub use dht_provider::DhtQueryResult;

pub use diagnostics::ConfigDiagnostics;

pub use diagnostics::ConfigIssue;

pub use diagnostics::DiagnosticResult;

pub use diagnostics::DiagnosticTest;

pub use diagnostics::NetworkDiagnostics;

pub use diagnostics::PerformanceMetrics;

pub use diagnostics::TroubleshootingGuide;

pub use facade::NetworkFacade;

pub use facade::NetworkFacadeBuilder;

pub use fallback::FallbackConfig;

pub use fallback::FallbackManager;

pub use fallback::FallbackResult;

pub use fallback::FallbackStrategy;

pub use fallback::RetryStats;

pub use geo_routing::GeoLocation;

pub use geo_routing::GeoPeer;

pub use geo_routing::GeoRegion;

pub use geo_routing::GeoRouter;

pub use geo_routing::GeoRouterConfig;

pub use geo_routing::GeoRouterStats;

pub use gossipsub::GossipSubConfig;

pub use gossipsub::GossipSubError;

pub use gossipsub::GossipSubManager;

pub use gossipsub::GossipSubMessage;

pub use gossipsub::GossipSubStats;

pub use gossipsub::MessageId;

pub use gossipsub::PeerScore;

pub use gossipsub::TopicId;

pub use gossipsub::TopicSubscription;

pub use health::ComponentHealth;

pub use health::HealthChecker;

pub use health::HealthHistory;

pub use health::NetworkHealth;

pub use health::NetworkHealthStatus;

pub use ipfs_compat::ipfs_test_config;

pub use ipfs_compat::test_ipfs_connectivity;

pub use ipfs_compat::IpfsCompatTestResults;

pub use ipfs_compat::IPFS_BOOTSTRAP_NODES;

pub use ipfs_compat::TEST_CIDS;

pub use load_tester::LoadTestConfig;

pub use load_tester::LoadTestError;

pub use load_tester::LoadTestMetrics;

pub use load_tester::LoadTestResults;

pub use load_tester::LoadTestType;

pub use load_tester::LoadTester;

pub use logging::connection_span;

pub use logging::dht_span;

pub use logging::network_span;

pub use logging::LogLevel;

pub use logging::LoggingConfig;

pub use logging::NetworkEventType;

pub use logging::OperationContext;

pub use memory_monitor::ComponentMemory;

pub use memory_monitor::MemoryMonitor;

pub use memory_monitor::MemoryMonitorConfig;

pub use memory_monitor::MemoryMonitorError;

pub use memory_monitor::MemoryStats;

pub use metrics::BandwidthMetricsSnapshot;

pub use metrics::ConnectionMetricsSnapshot;

pub use metrics::DhtMetricsSnapshot;

pub use metrics::MetricsSnapshot;

pub use metrics::NetworkMetrics;

pub use metrics::SharedMetrics;

pub use metrics_aggregator::AggregatedStatistics;

pub use metrics_aggregator::AggregatorConfig;

pub use metrics_aggregator::MetricStatistics;

pub use metrics_aggregator::MetricsAggregator;

pub use metrics_aggregator::TimeWindow;

pub use multipath_quic::MultipathConfig;

pub use multipath_quic::MultipathError;

pub use multipath_quic::MultipathQuicManager;

pub use multipath_quic::MultipathStats;

pub use multipath_quic::NetworkPath;

pub use multipath_quic::PathId;

pub use multipath_quic::PathQuality;

pub use multipath_quic::PathSelectionStrategy;

pub use multipath_quic::PathState;

pub use network_monitor::InterfaceType;

pub use network_monitor::NetworkChange;

pub use network_monitor::NetworkInterface;

pub use network_monitor::NetworkMonitor;

pub use network_monitor::NetworkMonitorConfig;

pub use network_monitor::NetworkMonitorError;

pub use network_monitor::NetworkMonitorStats;

pub use network_simulator::NetworkCondition;

pub use network_simulator::NetworkSimulator;

pub use network_simulator::SimulatorConfig;

pub use network_simulator::SimulatorError;

pub use network_simulator::SimulatorStats;

pub use node::BucketInfo;

pub use node::ConnectionEndpoint;

pub use node::KademliaConfig;

pub use node::NetworkConfig;

pub use node::NetworkEvent;

pub use node::NetworkHealthLevel;

pub use node::NetworkHealthSummary;

pub use node::NetworkNode;

pub use node::NetworkStats;

pub use node::RoutingTableInfo;

pub use offline_queue::OfflineQueue;

pub use offline_queue::OfflineQueueConfig;

pub use offline_queue::OfflineQueueError;

pub use offline_queue::OfflineQueueStats;

pub use offline_queue::QueuedRequest;

pub use offline_queue::QueuedRequestType;

pub use offline_queue::RequestPriority;

pub use peer::PeerInfo;

pub use peer::PeerStore;

pub use peer::PeerStoreConfig;

pub use peer::PeerStoreStats;

pub use peer_selector::PeerSelector;

pub use peer_selector::PeerSelectorConfig;

pub use peer_selector::PeerSelectorStats;

pub use peer_selector::SelectedPeer;

pub use peer_selector::SelectionCriteria;

pub use policy::BandwidthPolicy;

pub use policy::ConnectionPolicy;

pub use policy::ContentPolicy;

pub use policy::PolicyAction;

pub use policy::PolicyConfig;

pub use policy::PolicyEngine;

pub use policy::PolicyError;

pub use policy::PolicyResult;

pub use policy::PolicyStats;

pub use presets::NetworkPreset;

pub use protocol::ProtocolCapabilities;

pub use protocol::ProtocolHandler;

pub use protocol::ProtocolId;

pub use protocol::ProtocolRegistry;

pub use protocol::ProtocolVersion;

pub use providers::ProviderCache;

pub use providers::ProviderCacheConfig;

pub use providers::ProviderCacheStats;

pub use quality_predictor::QualityPrediction;

pub use quality_predictor::QualityPredictor;

pub use quality_predictor::QualityPredictorConfig;

pub use quality_predictor::QualityPredictorError;

pub use quality_predictor::QualityPredictorStats;

pub use query_batcher::PendingQuery;

pub use query_batcher::QueryBatchResult;

pub use query_batcher::QueryBatcher;

pub use query_batcher::QueryBatcherConfig;

pub use query_batcher::QueryBatcherError;

pub use query_batcher::QueryBatcherStats;

pub use query_batcher::QueryType;

pub use query_optimizer::QueryMetrics;

pub use query_optimizer::QueryOptimizer;

pub use query_optimizer::QueryOptimizerConfig;

pub use query_optimizer::QueryResult;

pub use quic::CongestionControl;

pub use quic::QuicConfig;

pub use quic::QuicConnectionInfo;

pub use quic::QuicConnectionState;

pub use quic::QuicMonitor;

pub use quic::QuicStats;

pub use rate_limiter::ConnectionPriority;

pub use rate_limiter::ConnectionRateLimiter;

pub use rate_limiter::RateLimiterConfig;

pub use rate_limiter::RateLimiterError;

pub use rate_limiter::RateLimiterStats;

pub use reputation::ReputationConfig;

pub use reputation::ReputationEvent;

pub use reputation::ReputationManager;

pub use reputation::ReputationScore;

pub use reputation::ReputationStats;

pub use semantic_dht::DistanceMetric;

pub use semantic_dht::LshConfig;

pub use semantic_dht::LshHash;

pub use semantic_dht::NamespaceId;

pub use semantic_dht::SemanticDht;

pub use semantic_dht::SemanticDhtConfig;

pub use semantic_dht::SemanticDhtError;

pub use semantic_dht::SemanticDhtStats;

pub use semantic_dht::SemanticNamespace;

pub use semantic_dht::SemanticQuery;

pub use semantic_dht::SemanticResult;

pub use session::Session;

pub use session::SessionConfig;

pub use session::SessionManager;

pub use session::SessionMetadata;

pub use session::SessionState;

pub use session::SessionStats;

pub use throttle::BandwidthThrottle;

pub use throttle::ThrottleConfig;

pub use throttle::ThrottleError;

pub use throttle::ThrottleStats;

pub use throttle::TrafficDirection;

pub use tor::CircuitId;

pub use tor::CircuitInfo;

pub use tor::CircuitState;

pub use tor::HiddenServiceConfig;

pub use tor::OnionAddress;

pub use tor::StreamId;

pub use tor::TorConfig;

pub use tor::TorError;

pub use tor::TorManager;

pub use tor::TorStats;

pub use traffic_analyzer::AnomalyType;

pub use traffic_analyzer::PatternType;

pub use traffic_analyzer::PeerProfile;

pub use traffic_analyzer::TrafficAnalysis;

pub use traffic_analyzer::TrafficAnalyzer;

pub use traffic_analyzer::TrafficAnalyzerConfig;

pub use traffic_analyzer::TrafficAnalyzerError;

pub use traffic_analyzer::TrafficAnalyzerStats;

pub use traffic_analyzer::TrafficAnomaly;

pub use traffic_analyzer::TrafficEvent;

pub use traffic_analyzer::TrafficPattern;

pub use traffic_analyzer::TrendDirection;

pub use utils::exponential_backoff;

pub use utils::format_bandwidth;

pub use utils::format_bytes;

pub use utils::format_duration;

pub use utils::is_local_addr;

pub use utils::is_public_addr;

pub use utils::jittered_backoff;

pub use utils::moving_average;

pub use utils::parse_multiaddr;

pub use utils::parse_multiaddrs;

pub use utils::peers_match;

pub use utils::percentage;

pub use utils::truncate_peer_id;

pub use utils::validate_alpha;

pub use libp2p;

Modules

adaptive_polling

Adaptive polling intervals for power-efficient network operations

arm_profiler

ARM Performance Profiling for Network Operations

auto_tuner

Automatic network configuration tuning based on system resources and usage patterns.

background_mode

Background mode support with pause/resume functionality

benchmarking

Performance Benchmarking - Comprehensive benchmarking utilities for network components

bitswap

Bitswap protocol implementation for block exchange

bootstrap

Bootstrap peer management with retry logic

connection_manager

Connection management with limits and pruning

connection_migration

QUIC Connection Migration for Mobile Support

dht

Distributed Hash Table (Kademlia DHT) implementation

dht_provider

Custom DHT provider interface for pluggable DHT implementations

diagnostics

Network Diagnostics and Troubleshooting Utilities

facade

High-level network facade integrating all IPFRS network modules

fallback

Fallback strategies for network error handling

geo_routing

Geographic routing optimization for IPFRS network

gossipsub

GossipSub - Topic-based pub/sub messaging

health

Network health check endpoints

ipfs_compat

IPFS compatibility and connectivity testing

load_tester

Network Load Testing and Stress Testing Utilities

logging

Structured logging and tracing support

memory_monitor

Memory usage monitoring for network components

metrics

Network metrics collection and reporting

metrics_aggregator

Metrics time-series aggregator for historical tracking and analysis

multipath_quic

QUIC Multipath Support

network_monitor

Network interface monitoring and switch detection

network_simulator

Network Simulator - Simulate various network conditions for testing

node

Network node implementation with full libp2p integration

offline_queue

Offline request queue for mobile and intermittent connectivity

peer

Peer information and management

peer_selector

Intelligent peer selection combining geographic proximity and connection quality

policy

Network Policy Engine - Fine-grained control over network operations

presets

Configuration presets for common use cases

protocol

Protocol handler registry and version negotiation

providers

Provider record cache with TTL

quality_predictor

Connection Quality Predictor

query_batcher

DHT query batching and frequency optimization

query_optimizer

DHT Query Optimization Module

quic

QUIC transport utilities and configuration

rate_limiter

Connection rate limiting for preventing connection storms and resource exhaustion.

reputation

Peer reputation system for tracking and scoring peer behavior

semantic_dht

Semantic DHT - Vector-based content routing

session

Connection Session Management

throttle

Bandwidth throttling for network traffic control

tor

Tor Integration for Privacy-Preserving Networking

traffic_analyzer

Network Traffic Analysis and Pattern Detection

utils

Network Utilities

Macros

log_network_error

Log a network error with context

log_network_event

Log a structured network event

log_network_warn

Log a network warning with context