dig_ip/lib.rs
1//! # dig-ip — canonical address-family discovery + IPv6-first happy-eyeballs dial
2//!
3//! The ONE ecosystem implementation of CLAUDE.md §5.2 (IPv6-first, IPv4-fallback for peer comms).
4//! Before this crate, three drifting copies of the happy-eyeballs racer lived in `dig-nat`,
5//! `dig-gossip`, and `dig-node-core`, and NONE of them filtered by LOCAL capability — so an
6//! IPv4-only host still emitted IPv6 SYNs, and an IPv6-only peer from an IPv4-only host was
7//! attempted-then-timed-out rather than reported cleanly unreachable. `dig-ip` consolidates them and
8//! adds the missing half: the local∩peer family INTERSECTION.
9//!
10//! ## The pipeline
11//!
12//! 1. [`LocalStack`] — which families THIS host can reach (`detect` / `cached` / `from_flags`).
13//! 2. [`PeerCandidates`] — a peer's family-tagged candidate addresses, aggregated from every
14//! discovery source ([`CandidateSource`]) and de-duplicated.
15//! 3. [`dial_order`] — the local∩peer family intersection, IPv6-first, that FAILS OPEN when local
16//! detection cannot confidently name a common family; a typed [`NoCommonFamily`] only when the peer
17//! offers no candidate at all.
18//! 4. [`connect`] — the RFC-8305 happy-eyeballs racer over that order, IPv6-preferred with graceful
19//! IPv4 fallback; the transport dial is a caller-supplied closure so this crate stays a leaf with
20//! no TLS/socket dependency.
21//!
22//! ## The core guarantee
23//!
24//! When local detection is AFFIRMATIVE for at least one of the peer's families, the intersection is an
25//! optimization: an address of a family the local host affirmatively lacks, or a family the peer lacks,
26//! is not dialed ("an IPv6 client doesn't try to connect to an IPv4-only client", and vice-versa).
27//! Because negative detection is unreliable — an overlay / split-tunnel / pre-route host probes
28//! `ENETUNREACH` for a family it can actually reach — an EMPTY intersection over a peer that has
29//! candidates fails OPEN (attempts them all, IPv6-first) rather than stranding a reachable peer;
30//! [`NoCommonFamily`] means only "the peer offered nothing to dial".
31
32#![forbid(unsafe_code)]
33#![warn(missing_docs)]
34
35mod candidate;
36mod connect;
37mod dial;
38mod family;
39mod local;
40
41pub use candidate::{Candidate, CandidateSource, PeerCandidates};
42pub use connect::{connect, ConnectError, DialConfig, DialWinner, FromTimeout};
43pub use dial::{dial_order, NoCommonFamily};
44pub use family::Family;
45pub use local::LocalStack;