Crate saorsa_gossip_coordinator

Expand description

Coordinator advertisements for seedless bootstrap

Implements SPEC2 §8 Coordinator Adverts for NAT traversal and seedless discovery.

§Overview

Coordinators are self-elected nodes that attempt to provide:

Bootstrap: Seedless network entry
Reflection: Address observation for NAT detection
Rendezvous: Connection coordination for hole punching
Relay: Last-resort message forwarding

Roles are hints, not trusted claims. Peers are selected based on observed reachability and success rates (“measure, don’t trust”).

§Cache Architecture

This crate uses a two-layer cache architecture:

ant-quic’s BootstrapCache: Handles peer quality scoring, epsilon-greedy selection, persistent storage, and connection statistics.
GossipCacheAdapter: Extends the bootstrap cache with gossip-specific data (coordinator adverts with ML-DSA signatures, expiry times, role information).

§Ownership Pattern

The application owns the Arc<BootstrapCache> and shares it with the gossip layer:

┌─────────────────────────────────────────────────────┐
│  Application (saorsa-node / communitas)             │
│  ┌───────────────────────────────────┐              │
│  │ Arc<BootstrapCache>               │ ← App owns   │
│  └───────────────────────────────────┘              │
│              │                                       │
│              ▼                                       │
│  ┌───────────────────────────────────┐              │
│  │ GossipCacheAdapter                │ ← Wraps      │
│  │ - cache: Arc<BootstrapCache>      │              │
│  │ - adverts: HashMap<PeerId, Advert>│              │
│  └───────────────────────────────────┘              │
└─────────────────────────────────────────────────────┘

§Quick Start

§Creating a Cache

use saorsa_gossip_coordinator::{GossipCacheAdapter, bootstrap_cache::*};
use std::sync::Arc;

// Application creates and owns the bootstrap cache
let config = BootstrapCacheConfig::builder()
    .cache_dir("/path/to/cache".into())
    .build();
let cache = Arc::new(BootstrapCache::open(config).await?);

// Gossip layer wraps it with adapter
let adapter = GossipCacheAdapter::new(cache);

// Use for coordinator discovery
let coordinators = adapter.select_coordinators(3).await;

§Bootstrap Flow

use saorsa_gossip_coordinator::{Bootstrap, GossipCacheAdapter, CoordinatorHandler, BootstrapAction};

// Create handler and bootstrap with shared cache
let handler = CoordinatorHandler::with_cache(peer_id, adapter.clone());
let bootstrap = Bootstrap::new(peer_id, adapter, handler);

// Find a coordinator
match bootstrap.find_coordinator().await {
    BootstrapAction::Connect(result) => {
        // Connect to result.selected_peer at result.addrs
    }
    BootstrapAction::Query(query) => {
        // Send FOAF query to discover coordinators
    }
    BootstrapAction::Wait => {
        // Wait and retry later
    }
}

§Creating Adverts

use saorsa_gossip_coordinator::{CoordinatorAdvert, CoordinatorRoles, NatClass};
use saorsa_gossip_types::PeerId;

// Create a coordinator advert
let peer = PeerId::new([1u8; 32]);
let roles = CoordinatorRoles {
    coordinator: true,
    reflector: true,
    rendezvous: false,
    relay: false,
};

let advert = CoordinatorAdvert::new(
    peer,
    roles,
    vec![],
    NatClass::Eim,
    3600_000, // 1 hour validity
);

assert!(advert.is_valid());

§Migration from Deprecated Types

The following types are deprecated and will be removed in a future version:

Deprecated	Replacement
`PeerCache`	`GossipCacheAdapter` with `bootstrap_cache::BootstrapCache`
`PeerCacheEntry`	`bootstrap_cache::CachedPeer` + `CoordinatorAdvert`
`AdvertCache`	`GossipCacheAdapter`

See the documentation on each deprecated type for migration examples.

Modules§

bootstrap_cache: Re-exports from ant-quic bootstrap cache.

Structs§

AddrHint: Address hint for NAT traversal
AdvertCacheDeprecated: LRU cache for coordinator advertisements
Bootstrap: Bootstrap coordinator for network entry
BootstrapResult: Result of a successful bootstrap (found coordinator)
CoordinatorAdvert: Coordinator Advertisement per SPEC2 §8
CoordinatorHandler: Handler for coordinator advertisements and FOAF queries
CoordinatorPublisher: Publisher for coordinator advertisements
FindCoordinatorQuery: FOAF query for finding coordinators
FindCoordinatorResponse: Response to a FIND_COORDINATOR query
GossipCacheAdapter: Adapter that wraps ant-quic’s BootstrapCache with gossip-specific extensions.
PeerCacheDeprecated: Persistent peer cache for bootstrap coordination
PeerCacheEntryDeprecated: Peer cache entry per SPEC2 §7.2
PeerRoles: Roles a peer can provide (per SPEC2 §8)
PeriodicPublisher: Periodic coordinator advertisement publisher
TransportHint: Transport capability hint for multi-transport peer discovery.

Enums§

BootstrapAction: Action required after bootstrap attempt per SPEC2 §7.4
NatClass: NAT class detection per SPEC2 §8
TraversalMethod: Traversal method preference order per SPEC2 §7.4

Constants§

DEFAULT_FIND_COORDINATOR_FANOUT: Default fanout for FIND_COORDINATOR queries (SPEC2 §7.3)
MAX_FIND_COORDINATOR_TTL: Maximum TTL for FIND_COORDINATOR queries (SPEC2 §7.3)

Functions§

capabilities_to_roles: Convert ant-quic PeerCapabilities to gossip PeerRoles.
coordinator_topic: Well-known topic for coordinator advertisements
nat_type_to_nat_class: Convert ant-quic NatType to gossip NatClass.

Type Aliases§

CoordinatorRoles: Coordinator roles per SPEC2 §8