TunnelPeerSelector (Javadocs [I2P+ 2.13.0+]

java.lang.Object
- net.i2p.router.tunnel.pool.ConnectChecker
- - net.i2p.router.tunnel.pool.TunnelPeerSelector

Direct Known Subclasses:
ClientPeerSelector, ExploratoryPeerSelector
```
public abstract class TunnelPeerSelector
extends ConnectChecker
```
Coordinate the selection of peers to go into a tunnel for one particular pool.

Nested Class Summary
Nested Classes
Modifier and Type Class and Description
protected class TunnelPeerSelector.Excluder
Excluder that automatically adds peers to the set when they should be excluded.

Nested Classes
Modifier and Type	Class and Description
`protected class`	`TunnelPeerSelector.Excluder` Excluder that automatically adds peers to the set when they should be excluded.

Field Summary

Fields
Modifier and Type	Field and Description
`protected static Object`	`_cooldownLock` Lock for atomic cooldown check+record across peer selectors
`protected static Map<Hash,Long>`	`_firstHopFails` Tracks when a peer last failed as first hop
`protected static Map<Hash,Long>`	`_peerCooldowns` Shared cooldown map across all peer selectors
`protected static double`	`ATTACK_THRESHOLD` Threshold for detecting tunnel build attacks
`protected static double`	`DEGRADED_BUILD_THRESHOLD` Build success at or below this widens the activity window to counter the purgatory band (40-79% success) where the recency gate prunes good peers faster than they can be re-tested, tightening the eligible pool in a self-reinforcing loop.
`protected static long`	`FIRST_HOP_FAIL_COOLDOWN_MS` Peers that failed as first hop (first hop unreachable) excluded for this long
`protected static long`	`PEER_SELECTION_COOLDOWN_MS` Peers selected within this window are excluded from further selection to ensure diversity
`protected static long`	`STARTUP_WARNING_SUPPRESS_MS` Duration in ms to suppress startup warnings

Fields inherited from class net.i2p.router.tunnel.pool.ConnectChecker
ANY_V4, ctx, log

Constructor Summary
Constructors
Modifier Constructor and Description
protected TunnelPeerSelector(RouterContext context)
TunnelPeerSelector.

Constructors
Modifier	Constructor and Description
`protected`	`TunnelPeerSelector(RouterContext context)` TunnelPeerSelector.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected boolean`	`allowAsIBGW(Hash h)` Should we allow as IBGW? This just checks for the "R" capability and IPv4 support.
`protected boolean`	`allowAsOBEP(Hash h)` Should we allow as OBEP? This just checks for IPv4 support.
`protected boolean`	`checkTunnel(boolean isInbound, boolean isExploratory, List<Hash> tunnel)` Connectivity check.
`protected boolean`	`filterSlow(boolean isInbound, boolean isExploratory)` do we want to skip peers that are slow?
`static long`	`getActivityWindow(RouterContext ctx)` Compute the activity window for peer selection based on current network visibility.
`protected Set<Hash>`	`getClosestHopExclude(boolean isInbound, Set<Hash> toAdd)` Pick peers that we want to avoid for the first OB hop or last IB hop.
`protected Set<Hash>`	`getExclude(boolean isInbound, boolean isExploratory)` As of 0.9.58, this returns a set populated only by TunnelManager.selectPeersInTooManyTunnels(), for passing to ProfileOrganizer.
`protected int`	`getLength(TunnelPoolSettings settings)` Determine the tunnel length (number of hops).
`protected static Set<Hash>`	`getPeersInPool(RouterContext ctx, TunnelPool pool)` Get all non-self peers in active tunnels of the given pool.
`static int`	`getWindowMultiplier()` Get the current Tuner-controlled activity-window multiplier.
`protected static boolean`	`hasRecoveredFromFailure(RouterContext ctx, Hash peer)` Check if a peer has recovered from failure and can be reconsidered.
`protected static boolean`	`hasValidTransportAddress(RouterContext ctx, Hash peer)` Check if a peer's RouterInfo has at least one reachable SSU or NTCP address.
`protected boolean`	`isDuplicateSequence(TunnelPoolSettings settings, List<Hash> newPeers)` Check if the selected peer sequence matches an existing tunnel in the pool.
`static boolean`	`isFirstHopFailing(RouterContext ctx, Hash peer)` Check if a peer recently failed as first hop and should be excluded.
`protected boolean`	`isInStartupGracePeriod()` Convenience instance method wrapping the static helper.
`protected static boolean`	`isInStartupGracePeriod(RouterContext ctx)` Is the router in the startup grace period? During startup, peers haven't accumulated test history yet, so quality filters (pre-qualification, tier capping) should be relaxed to allow tunnels to build.
`protected boolean`	`isIPv6Only()` Are we IPv6 only?
`protected static boolean`	`isLowAcceptanceRatio(RouterContext ctx, Hash peer)` Check if a peer has a history of rejecting tunnel build requests.
`(package private) static boolean`	`isStalePeer(RouterContext ctx, Hash peer)` Check if a peer is stale — no contact (heard from or heard about) within the dynamic activity window.
`static void`	`keepAlive(RouterContext ctx, boolean aggressive)` Periodically called to keep transport sessions alive for top-tier peers and proactively establish connections to Fast/HighCap peers before builds need them.
`protected void`	`orderPeers(List<Hash> rv, SessionKey key)` Order peers using the given key.
`protected static void`	`preConnectTo(RouterContext ctx, Hash peer)` Trigger an outbound connection establishment to a peer.
`protected static void`	`prunePeerMaps(RouterContext ctx)` Prune expired entries from static peer maps.
`protected static void`	`recordFirstHopFail(RouterContext ctx, Hash peer)` Record that a peer failed as first hop (first hop unreachable).
`protected static void`	`recordPeerFailure(RouterContext ctx, Hash peer)` Record that a peer failed during peer selection (first-hop or adjacent).
`protected List<Hash>`	`regeneratePeers(TunnelPoolSettings settings, List<Hash> peers)` Regenerate tunnel peers to avoid duplicate sequence.
`protected List<Hash>`	`selectExplicit(TunnelPoolSettings settings, int length)` For debugging, also possibly for restricted routes.
`abstract List<Hash>`	`selectPeers(TunnelPoolSettings settings)` Which peers should go into the next tunnel for the given settings?
`static void`	`setWindowMultiplier(int mult)` Set the Tuner-controlled activity-window multiplier.
`static boolean`	`shouldExclude(RouterContext ctx, RouterInfo peer)` Should the peer be excluded based on its published caps, crypto, and version?
`protected boolean`	`shouldSelectExplicit(TunnelPoolSettings settings)` For debugging, also possibly for restricted routes? Needs analysis and testing
`protected static boolean`	`supportsNTCP2(RouterContext ctx, Hash peer)` Check if a peer supports NTCP2 transport.

Methods inherited from class net.i2p.router.tunnel.pool.ConnectChecker
canConnect, canConnect, canConnect, getInboundMask, getOutboundMask, isNTCPDisabled, isSSUDisabled

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - _cooldownLock
```
protected static final Object _cooldownLock
```
    Lock for atomic cooldown check+record across peer selectors
  - _firstHopFails
```
protected static final Map<Hash,Long> _firstHopFails
```
    Tracks when a peer last failed as first hop
  - _peerCooldowns
```
protected static final Map<Hash,Long> _peerCooldowns
```
    Shared cooldown map across all peer selectors
  - ATTACK_THRESHOLD
```
protected static final double ATTACK_THRESHOLD
```
    Threshold for detecting tunnel build attacks
    See Also:
    Constant Field Values
  - DEGRADED_BUILD_THRESHOLD
```
protected static final double DEGRADED_BUILD_THRESHOLD
```
    Build success at or below this widens the activity window to counter the purgatory band (40-79% success) where the recency gate prunes good peers faster than they can be re-tested, tightening the eligible pool in a self-reinforcing loop. Higher than ATTACK_THRESHOLD because relaxing recency is far safer than relaxing capability exclusions.
    See Also:
    Constant Field Values
  - FIRST_HOP_FAIL_COOLDOWN_MS
```
protected static final long FIRST_HOP_FAIL_COOLDOWN_MS
```
    Peers that failed as first hop (first hop unreachable) excluded for this long
    See Also:
    Constant Field Values
  - PEER_SELECTION_COOLDOWN_MS
```
protected static final long PEER_SELECTION_COOLDOWN_MS
```
    Peers selected within this window are excluded from further selection to ensure diversity
    See Also:
    Constant Field Values
  - STARTUP_WARNING_SUPPRESS_MS
```
protected static final long STARTUP_WARNING_SUPPRESS_MS
```
    Duration in ms to suppress startup warnings
    See Also:
    Constant Field Values
- Constructor Detail
  - TunnelPeerSelector
```
protected TunnelPeerSelector(RouterContext context)
```
    TunnelPeerSelector.
- Method Detail
  - allowAsIBGW
```
protected boolean allowAsIBGW(Hash h)
```
    Should we allow as IBGW? This just checks for the "R" capability and IPv4 support. Will return false for hidden or IPv6-only. This is intended for tunnel candidates, where we already have the RI. Will not force RI lookups. Default true.
    Parameters:
    h - the peer hash
    Returns:
    true if the peer can be used as IBGW
  - allowAsOBEP
```
protected boolean allowAsOBEP(Hash h)
```
    Should we allow as OBEP? This just checks for IPv4 support. Will return false for IPv6-only. This is intended for tunnel candidates, where we already have the RI. Will not force RI lookups. Default true.
    Parameters:
    h - the peer hash
    Returns:
    true if the peer can be used as OBEP
  - checkTunnel
```
protected boolean checkTunnel(boolean isInbound,
                              boolean isExploratory,
                              List<Hash> tunnel)
```
    Connectivity check. Check that each hop can connect to the next, including us. Check that the OBEP is not IPv6-only, and the IBGW is reachable and not hidden or IPv6-only. Tells the profile manager to blame the hop, and returns false on failure.
    Parameters:
    isInbound - true for inbound tunnels
    isExploratory - true for exploratory tunnels
    tunnel - ENDPOINT FIRST, GATEWAY LAST!!!!, length 2 or greater
    Returns:
    ok
  - filterSlow
```
protected boolean filterSlow(boolean isInbound,
                             boolean isExploratory)
```
    do we want to skip peers that are slow?
    Parameters:
    isInbound - true for inbound tunnels
    isExploratory - true for exploratory tunnels
    Returns:
    true unless configured otherwise
  - getActivityWindow
```
public static long getActivityWindow(RouterContext ctx)
```
    Compute the activity window for peer selection based on current network visibility. When we hear from many peers, we can be selective (short window). When the router is fresh or the network is sparse, use a wider window to avoid starving peer pools. The base window (from active-peer count) is scaled by the Tuner-controlled multiplier (setWindowMultiplier(int)) and floored to at least 4 hours when build success is in the degraded/purgatory band, so good peers whose last successful test has aged out are re-admitted instead of pruned in a self-reinforcing loop.
    Parameters:
    ctx - the router context
    Returns:
    activity window in milliseconds
  - getClosestHopExclude
```
protected Set<Hash> getClosestHopExclude(boolean isInbound,
                                         Set<Hash> toAdd)
```
    Pick peers that we want to avoid for the first OB hop or last IB hop. There's several cases of importance:
    1. Inbound and we are hidden - Exclude all unless connected. This is taken care of in ClientPeerSelector and TunnelPeerSelector selectPeers(), not here.
    2. We are IPv6-only. Exclude all v4-only peers, unless connected This is taken care of here.
    3. We have NTCP or SSU disabled. Exclude all incompatible peers, unless connected This is taken care of here.
    4. Minimum version check, if we are some brand-new sig type, or are using some new tunnel build method. Not currently used, but this is where to implement the checks if needed. Make sure that ClientPeerSelector and TunnelPeerSelector selectPeers() call this when needed.
    As of 0.9.58, this a set with only toAdd, for use in ProfileOrganizer. The set will be populated via the contains() calls.
    Parameters:
    isInbound - true for inbound tunnels
    toAdd - set of peers to initially populate the exclusion set
    Returns:
    non-null
  - getExclude
```
protected Set<Hash> getExclude(boolean isInbound,
                               boolean isExploratory)
```
    As of 0.9.58, this returns a set populated only by TunnelManager.selectPeersInTooManyTunnels(), for passing to ProfileOrganizer. The set will be populated via the contains() calls.
    Parameters:
    isInbound - true for inbound tunnels
    isExploratory - true for exploratory tunnels
    Returns:
    set of excluded peers
  - getLength
```
protected int getLength(TunnelPoolSettings settings)
```
    Determine the tunnel length (number of hops).
    Parameters:
    settings - the tunnel pool settings
    Returns:
    randomized number of hops 0-7, not including ourselves
  - getPeersInPool
```
protected static Set<Hash> getPeersInPool(RouterContext ctx,
                                          TunnelPool pool)
```
    Get all non-self peers in active tunnels of the given pool. Used to enforce per-pool diversity: no peer in more than 1 tunnel per pool.
    Parameters:
    ctx - the router context
    pool - the tunnel pool to scan
    Returns:
    set of peer hashes already in active tunnels of this pool
  - getWindowMultiplier
```
public static int getWindowMultiplier()
```
    Get the current Tuner-controlled activity-window multiplier.
    Returns:
    the current multiplier, in [1, 8]
  - hasRecoveredFromFailure
```
protected static boolean hasRecoveredFromFailure(RouterContext ctx,
                                                 Hash peer)
```
    Check if a peer has recovered from failure and can be reconsidered. Uses the effective first-hop cooldown (shortened during ghost cascades).
    Parameters:
    ctx - the router context
    peer - the peer
    Returns:
    true if the peer has recovered
  - hasValidTransportAddress
```
protected static boolean hasValidTransportAddress(RouterContext ctx,
                                                  Hash peer)
```
    Check if a peer's RouterInfo has at least one reachable SSU or NTCP address. Peers without valid transport addresses always fail as first hops and trigger bans in EstablishmentManager.establish() — they should be excluded from selection.
    Parameters:
    ctx - the router context
    peer - hash of the peer to check
    Returns:
    true if the peer has a valid SSU or NTCP address
  - isDuplicateSequence
```
protected boolean isDuplicateSequence(TunnelPoolSettings settings,
                                      List<Hash> newPeers)
```
    Check if the selected peer sequence matches an existing tunnel in the pool. Prevents duplicate peer sequences which could weaken anonymity.
    Parameters:
    settings - the tunnel pool settings
    newPeers - the newly selected peers (excluding self)
    Returns:
    true if duplicate detected
  - isFirstHopFailing
```
public static boolean isFirstHopFailing(RouterContext ctx,
                                        Hash peer)
```
    Check if a peer recently failed as first hop and should be excluded. During ghost cascades (high ghost count), the cooldown is shortened from 5 min to 60s to rehabilitate peers faster when the network is stressed — many peers are ghosted through no fault of their own.
    Parameters:
    ctx - the router context
    peer - the peer
    Returns:
    true if the peer should be excluded
  - isInStartupGracePeriod
```
protected boolean isInStartupGracePeriod()
```
    Convenience instance method wrapping the static helper.
    Returns:
    true if the router is in the startup grace period
  - isInStartupGracePeriod
```
protected static boolean isInStartupGracePeriod(RouterContext ctx)
```
    Is the router in the startup grace period? During startup, peers haven't accumulated test history yet, so quality filters (pre-qualification, tier capping) should be relaxed to allow tunnels to build.
    Parameters:
    ctx - the router context
    Returns:
    true if uptime is between 1ms and STARTUP_WARNING_SUPPRESS_MS
  - isIPv6Only
```
protected boolean isIPv6Only()
```
    Are we IPv6 only?
    Returns:
    true if configured for IPv6 only
  - isLowAcceptanceRatio
```
protected static boolean isLowAcceptanceRatio(RouterContext ctx,
                                              Hash peer)
```
    Check if a peer has a history of rejecting tunnel build requests. Returns true when the lifetime acceptance ratio drops below 30%. Defaults to false (accept) when no data is available.
    Parameters:
    ctx - the router context
    peer - hash of the peer to check
    Returns:
    true if the acceptance ratio is below threshold
  - isStalePeer
```
static boolean isStalePeer(RouterContext ctx,
                           Hash peer)
```
    Check if a peer is stale — no contact (heard from or heard about) within the dynamic activity window. Window adapts to network visibility: - 500+ active peers → 1 hour (very selective) - 200+ active peers → 2 hours - 100+ active peers → 4 hours - <100 active peers → 8 hours (fresh router, building up picture) Peers in the netDb often go offline silently; this avoids wasting first-hop selection and keepalive resources on peers that are likely dead. Skipped during the first 15 minutes of uptime (startup grace) to allow the router to build initial tunnels before profile data accumulates.
    Parameters:
    ctx - the router context
    peer - hash of the peer to check
    Returns:
    true if the peer hasn't been heard from or about within the activity window
  - keepAlive
```
public static void keepAlive(RouterContext ctx,
                             boolean aggressive)
```
    Periodically called to keep transport sessions alive for top-tier peers and proactively establish connections to Fast/HighCap peers before builds need them. This prevents the natural session aging that drops the active peer count from ~600 to ~300 in the first 30 minutes, which starves first-hop selection and causes tunnel pool collapse.
    Parameters:
    ctx - the router context
    aggressive - if true, also pre-connect to non-established eligible peers (used when any pool has 0 tunnels)
  - orderPeers
```
protected void orderPeers(List<Hash> rv,
                          SessionKey key)
```
    Order peers using the given key.
    Parameters:
    rv - the list to order
    key - the session key for ordering
  - preConnectTo
```
protected static void preConnectTo(RouterContext ctx,
                                   Hash peer)
```
    Trigger an outbound connection establishment to a peer. Creates a low-priority dummy OutNetMessage that causes the transport layer to initiate a connection. Used to pre-warm connections for first-hop peers before the build message is sent.
    Parameters:
    ctx - the router context
    peer - hash of the peer to connect to
  - prunePeerMaps
```
protected static void prunePeerMaps(RouterContext ctx)
```
    Prune expired entries from static peer maps. Called periodically from peer selection to prevent unbounded growth.
    Parameters:
    ctx - the router context
  - recordFirstHopFail
```
protected static void recordFirstHopFail(RouterContext ctx,
                                         Hash peer)
```
    Record that a peer failed as first hop (first hop unreachable).
    Parameters:
    ctx - the router context
    peer - the peer
  - recordPeerFailure
```
protected static void recordPeerFailure(RouterContext ctx,
                                        Hash peer)
```
    Record that a peer failed during peer selection (first-hop or adjacent). Used by ClientPeerSelector and ExploratoryPeerSelector to mark peers that failed selection criteria, preventing re-selection for the cooldown.
    Parameters:
    ctx - the router context
    peer - the peer
  - regeneratePeers
```
protected List<Hash> regeneratePeers(TunnelPoolSettings settings,
                                     List<Hash> peers)
```
    Regenerate tunnel peers to avoid duplicate sequence. Shuffles the peer selection and re-orders.
    Parameters:
    settings - the tunnel pool settings
    peers - the peers to regenerate
    Returns:
    regenerated peer list (same or different)
  - selectExplicit
```
protected List<Hash> selectExplicit(TunnelPoolSettings settings,
                                    int length)
```
    For debugging, also possibly for restricted routes. Needs analysis and testing
    Parameters:
    settings - the tunnel pool settings
    length - the desired length of the tunnel
    Returns:
    the list of explicit peer hashes for the tunnel
  - selectPeers
```
public abstract List<Hash> selectPeers(TunnelPoolSettings settings)
```
    Which peers should go into the next tunnel for the given settings?
    Parameters:
    settings - the tunnel pool settings
    Returns:
    ordered list of Hash objects (one per peer) specifying what order they should appear in a tunnel (ENDPOINT FIRST). This includes the local router in the list. If there are no tunnels or peers to build through, and the settings reject 0 hop tunnels, this will return null.
  - setWindowMultiplier
```
public static void setWindowMultiplier(int mult)
```
    Set the Tuner-controlled activity-window multiplier. Clamped to [1, 8].
    Parameters:
    mult - the multiplier applied to the base activity window
  - shouldExclude
```
public static boolean shouldExclude(RouterContext ctx,
                                    RouterInfo peer)
```
    Should the peer be excluded based on its published caps, crypto, and version?
    Parameters:
    ctx - Router context for peer count checks
    peer - The peer to evaluate
    Returns:
    true if the peer should be excluded
  - shouldSelectExplicit
```
protected boolean shouldSelectExplicit(TunnelPoolSettings settings)
```
    For debugging, also possibly for restricted routes? Needs analysis and testing
    Parameters:
    settings - the tunnel pool settings
    Returns:
    usually false
  - supportsNTCP2
```
protected static boolean supportsNTCP2(RouterContext ctx,
                                       Hash peer)
```
    Check if a peer supports NTCP2 transport. NTCP2 is preferred for direct connections (first hop / IBGW) because SSU2-only peers are typically firewalled, requiring introduction-based connections that are slower and less reliable.
    Parameters:
    ctx - the router context
    peer - hash of the peer to check
    Returns:
    true if the peer has an NTCP2 address

Class TunnelPeerSelector

Nested Class Summary

Field Summary

Fields inherited from class net.i2p.router.tunnel.pool.ConnectChecker

Constructor Summary

Method Summary

Methods inherited from class net.i2p.router.tunnel.pool.ConnectChecker

Methods inherited from class java.lang.Object

Field Detail

_cooldownLock

_firstHopFails

_peerCooldowns

ATTACK_THRESHOLD

DEGRADED_BUILD_THRESHOLD

FIRST_HOP_FAIL_COOLDOWN_MS

PEER_SELECTION_COOLDOWN_MS

STARTUP_WARNING_SUPPRESS_MS

Constructor Detail

TunnelPeerSelector

Method Detail

allowAsIBGW

allowAsOBEP

checkTunnel

filterSlow

getActivityWindow

getClosestHopExclude

getExclude

getLength

getPeersInPool

getWindowMultiplier

hasRecoveredFromFailure

hasValidTransportAddress

isDuplicateSequence

isFirstHopFailing

isInStartupGracePeriod

isInStartupGracePeriod

isIPv6Only

isLowAcceptanceRatio

isStalePeer

keepAlive

orderPeers

preConnectTo

prunePeerMaps

recordFirstHopFail

recordPeerFailure

regeneratePeers

selectExplicit

selectPeers

setWindowMultiplier

shouldExclude

shouldSelectExplicit

supportsNTCP2