Crate dig_ip 

dig-ip — canonical address-family discovery + IPv6-first happy-eyeballs dial

The ONE ecosystem implementation of CLAUDE.md §5.2 (IPv6-first, IPv4-fallback for peer comms). Before this crate, three drifting copies of the happy-eyeballs racer lived in dig-nat, dig-gossip, and dig-node-core, and NONE of them filtered by LOCAL capability — so an IPv4-only host still emitted IPv6 SYNs, and an IPv6-only peer from an IPv4-only host was attempted-then-timed-out rather than reported cleanly unreachable. dig-ip consolidates them and adds the missing half: the local∩peer family INTERSECTION.

The pipeline

1. LocalStack — which families THIS host can reach (detect / cached / from_flags).
2. PeerCandidates — a peer’s family-tagged candidate addresses, aggregated from every discovery source (CandidateSource) and de-duplicated.
3. dial_order — the local∩peer family intersection, IPv6-first, that FAILS OPEN when local detection cannot confidently name a common family; a typed NoCommonFamily only when the peer offers no candidate at all.
4. connect — the RFC-8305 happy-eyeballs racer over that order, IPv6-preferred with graceful IPv4 fallback; the transport dial is a caller-supplied closure so this crate stays a leaf with no TLS/socket dependency.

The core guarantee

When local detection is AFFIRMATIVE for at least one of the peer’s families, the intersection is an optimization: an address of a family the local host affirmatively lacks, or a family the peer lacks, is not dialed (“an IPv6 client doesn’t try to connect to an IPv4-only client”, and vice-versa). Because negative detection is unreliable — an overlay / split-tunnel / pre-route host probes ENETUNREACH for a family it can actually reach — an EMPTY intersection over a peer that has candidates fails OPEN (attempts them all, IPv6-first) rather than stranding a reachable peer; NoCommonFamily means only “the peer offered nothing to dial”.

Structs

Candidate

A single family-tagged candidate address for a peer.

DialConfig

Tuning for the happy-eyeballs candidate race.

DialWinner

The winning connection plus which candidate/family established it.

LocalStack

The address families THIS host can originate connections on.

NoCommonFamily

The peer offers no candidate address at all, so there is nothing to dial.

PeerCandidates

A peer’s aggregated, family-tagged, de-duplicated candidate addresses.

Enums

CandidateSource

Where a candidate address was learned — provenance, kept for observability and so a future policy could weight sources. It does not affect the family-intersection rule (that is family-only).

ConnectError

Why a connect attempt produced no connection.

Family

An IP address family: IPv6 (preferred) or IPv4 (fallback).

Traits

FromTimeout

How to construct the caller’s error type for a per-attempt timeout. Implemented for String (the common test/closure error) and any type convertible from a std::io::Error.

Functions

connect

Establish a connection to peer, IPv6-first with graceful IPv4 fallback, over the local∩peer family intersection (dial_order).

dial_order

The addresses to dial, in IPv6-first preference order.