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; a typed NoCommonFamily when disjoint. Its output NEVER contains a family the local host or the peer lacks.
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

An address of a family the LOCAL host lacks, or a family the PEER lacks, is NEVER dialed — this is enforced structurally by dial_order (which connect builds its attempt list from), not by convention. That is the anti-mis-dial rule the user asked for: “an IPv6 client doesn’t try to connect to an IPv4-only client” (and vice-versa).

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 local host and the peer share no reachable address family, so there is no address 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 over the local∩peer family intersection.