Safe Haskell	None
Language	GHC2021

LibP2P.NAT.DCUtR

Contents

Types
Protocol operations
Variants for testing

Description

DCUtR (Direct Connection Upgrade through Relay) protocol.

Protocol: libp2pdcutr Coordinates hole punching over a relayed connection using a 3-message exchange with RTT-based timing synchronization.

Message flow: B (initiator) sends CONNECT with B's observed addresses A (handler) sends CONNECT with A's observed addresses B sends SYNC B waits RTT/2, then dials A's addresses A receives SYNC, then dials B's addresses immediately Both peers attempt direct connections at approximately the same time

Per the spec, every exchanged address is dialled in parallel (hole punching depends on near-simultaneous packets), and on failure the whole exchange is re-run from the CONNECT step so RTT is re-measured (3 attempts total).

Synopsis

data DCUtRConfig = DCUtRConfig {
- dcMaxAttempts :: !Int
- dcDialer :: !(Multiaddr -> IO (Either String ()))
}
data DCUtRResult
- = DCUtRSuccess
- | DCUtRFailed String
initiateDCUtR :: DCUtRConfig -> StreamIO -> [Multiaddr] -> IO DCUtRResult
handleDCUtR :: DCUtRConfig -> StreamIO -> [Multiaddr] -> IO DCUtRResult
initiateDCUtRWithRTT :: DCUtRConfig -> StreamIO -> [Multiaddr] -> IORef (Maybe NominalDiffTime) -> IO DCUtRResult
initiateDCUtRCapture :: DCUtRConfig -> StreamIO -> [Multiaddr] -> IORef [ByteString] -> IO DCUtRResult
handleDCUtRCapture :: DCUtRConfig -> StreamIO -> [Multiaddr] -> IORef [ByteString] -> IO DCUtRResult

Types

data DCUtRConfig Source #

DCUtR configuration.

Constructors

DCUtRConfig
Fields dcMaxAttempts :: !Int Total number of hole punch attempts; the full CONNECT/SYNC exchange is re-run for each attempt so RTT is re-measured (spec: 3 total = 1 initial + 2 retries) dcDialer :: !(Multiaddr -> IO (Either String ())) Injectable dial function for testing

data DCUtRResult Source #

DCUtR result.

Constructors

DCUtRSuccess
DCUtRFailed String

Instances

Instances details

Show DCUtRResult Source #
Instance details Defined in LibP2P.NAT.DCUtR Methods showsPrec :: Int -> DCUtRResult -> ShowS # show :: DCUtRResult -> String # showList :: [DCUtRResult] -> ShowS #
Eq DCUtRResult Source #
Instance details Defined in LibP2P.NAT.DCUtR Methods (==) :: DCUtRResult -> DCUtRResult -> Bool # (/=) :: DCUtRResult -> DCUtRResult -> Bool #

Protocol operations

initiateDCUtR :: DCUtRConfig -> StreamIO -> [Multiaddr] -> IO DCUtRResult Source #

Peer B (initiator): run the DCUtR exchange over a relayed stream.

Flow (repeated up to dcMaxAttempts times while the hole punch fails): 1. Send CONNECT with own observed addresses 2. Read A's CONNECT (measure RTT) 3. Send SYNC 4. Wait RTT/2, then dial all of A's addresses in parallel

handleDCUtR :: DCUtRConfig -> StreamIO -> [Multiaddr] -> IO DCUtRResult Source #

Peer A (handler): handle the DCUtR exchange over a relayed stream.

Flow (repeated up to dcMaxAttempts times while the hole punch fails, matching the initiator's retries of the exchange): 1. Read B's CONNECT 2. Send CONNECT with own observed addresses 3. Read SYNC 4. Dial all of B's addresses in parallel immediately

Variants for testing

initiateDCUtRWithRTT :: DCUtRConfig -> StreamIO -> [Multiaddr] -> IORef (Maybe NominalDiffTime) -> IO DCUtRResult Source #

Initiator variant that captures RTT for testing.

initiateDCUtRCapture :: DCUtRConfig -> StreamIO -> [Multiaddr] -> IORef [ByteString] -> IO DCUtRResult Source #

Initiator variant that captures received addresses for testing.

handleDCUtRCapture :: DCUtRConfig -> StreamIO -> [Multiaddr] -> IORef [ByteString] -> IO DCUtRResult Source #

Handler variant that captures received addresses for testing.