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 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 Map<Hash,Long>`	`_provenResponders` Peers whose most recent tunnel participation succeeded, mapped to the time of that success.
`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 int`	`FAILURE_MAP_MAX_SIZE` Size bound for the cooldown maps (`_peerCooldowns`, `_firstHopFails`, `ExploratoryPeerSelector._exploratoryCooldowns`).
`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`	`PROVEN_RESPONDER_WINDOW_MS` Recency window for proven-responder proof
`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 static int`	`addFreshCooldownExclusions(Map<Hash,Long> cooldowns, long cutoff, Set<Hash> exclude)` Add cooldown entries still inside their window (value > cutoff) to the exclusion set without mutating the map; returns the count added.
`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.
`(package private) static boolean`	`allowFirewalledUnderAttack(String capabilities, double buildSuccess)` Should we allow a firewalled (U-cap) peer? During attacks (build success below `ATTACK_THRESHOLD`), allow U-cap peers that also publish M, N, O, P, or X capability.
`protected boolean`	`checkTunnel(boolean isInbound, boolean isExploratory, List<Hash> tunnel)` Connectivity check.
`(package private) static int`	`compareProven(long t1, long t2, long now)` Proven-responder comparison for the quality cascade: a peer whose last tunnel participation succeeded within the recency window sorts before one without; two peers on the same side compare equal so later cascade stages decide.
`(package private) static int`	`countKnownCaps(String cap)` Count the meaningful capabilities a peer publishes, used to reject peers with no useful caps when there are plenty of fast peers.
`protected boolean`	`filterSlow(boolean isInbound, boolean isExploratory)` Whether to skip peers that are slow.
`protected static String`	`formatExcludedPeers(Set<Hash> peers)` Format a set of excluded peers for logging, with exclusion reasons when the set is an `TunnelPeerSelector.Excluder` or `ExcluderBase`.
`static long`	`getActivityWindow(RouterContext ctx)` Compute the activity window for peer selection based on current network visibility.
`static long`	`getActivityWindow(RouterContext ctx, double buildSuccess)` Compute the activity window for peer selection based on current network visibility.
`(package private) static double`	`getBuildSuccess(RouterContext ctx)` Current tunnel build success ratio, 1.0 when no data is available.
`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)` All non-self peers in active tunnels of the given pool.
`static int`	`getWindowMultiplier()` Current Tuner-controlled activity-window multiplier.
`(package private) static boolean`	`hasConnectivitySignal(PeerProfile profile, long now, long activityWindow)` Pre-qualification signal check: does the peer profile show recent connectivity evidence? Heard from or successfully sent to within the last 30 minutes, a successful tunnel test within the activity window, or any test history at all with a >50% acceptance ratio.
`protected static boolean`	`hasRecoveredFromFailure(RouterContext ctx, Hash peer)` Check if a peer has recovered from failure and can be reconsidered.
`protected static boolean`	`hasTunnelLongerThanOne(TunnelPool pool)` True if the pool has at least one active tunnel longer than one hop.
`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`	`isOutdatedVersion(String version)` True if the peer runs a version too old to interoperate: not the published version and older than `MIN_VERSION`.
`(package private) static boolean`	`isProvenResponder(long lastJoin, long now)` Whether a proven-join timestamp falls inside the recency window.
`(package private) static boolean`	`isStalePeer(RouterContext ctx, Hash peer)` Check whether a peer is stale — no contact (heard from or heard about) within the dynamic activity window.
`(package private) static boolean`	`isStalePeer(RouterContext ctx, Hash peer, double buildSuccess)` Check whether a peer is stale — no contact (heard from or heard about) within the dynamic activity window.
`(package private) static boolean`	`isUsableRouterAddress(RouterAddress ra)` Is the RouterAddress usable for tunnel building? SSU requires protocol v2 plus a valid IP/port or an introduction; SSU2 requires a valid IP/port or an introduction; NTCP/NTCP2 require a valid IP/port.
`protected static boolean`	`isZeroHopSettings(TunnelPoolSettings settings)` True if the settings describe a zero-hop pair: length <= 0, length override == 0, or length + variance <= 0.
`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.
`(package private) static boolean`	`matchesExistingTunnel(TunnelInfo existing, List<Hash> newPeers, boolean isInbound)` Compare a newly selected peer sequence (excluding self) against one existing tunnel.
`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, int attempt)` Regenerate tunnel peers to avoid duplicate sequence.
`(package private) static String`	`relaxedExcludeCaps(String configured, double buildSuccess, long uptimeMs)` Strip the M, N, O, D, P capability exclusions from the configured caps when the build success ratio is below `ATTACK_THRESHOLD` or the router is within its first `STARTUP_WARNING_SUPPRESS_MS` of uptime (when the ratio is not yet meaningful).
`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)` Tuner-controlled activity-window multiplier, clamped to [1, 8].
`static boolean`	`shouldExclude(RouterContext ctx, RouterInfo peer)` Should the peer be excluded based on its published caps, crypto, and version?
`static boolean`	`shouldExclude(RouterContext ctx, RouterInfo peer, double buildSuccess)` 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
  - _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
  - _provenResponders
```
protected static final Map<Hash,Long> _provenResponders
```
    Peers whose most recent tunnel participation succeeded, mapped to the time of that success. Selection prefers fresh entries via ClientPeerSelector.compareQuality; entries older than PROVEN_RESPONDER_WINDOW_MS carry no weight and are pruned.
  - 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
  - FAILURE_MAP_MAX_SIZE
```
protected static final int FAILURE_MAP_MAX_SIZE
```
    Size bound for the cooldown maps (_peerCooldowns, _firstHopFails, ExploratoryPeerSelector._exploratoryCooldowns). Entries are recorded on selection failures, tunnel rejects, and tunnel reuse. They expire lazily (read-time filtering during selection) and are bulk-pruned only when a map exceeds this bound, so these maps stay small — 128 entries is already generous. This bound only limits growth between selections; it does not evict live entries.
    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
  - PROVEN_RESPONDER_WINDOW_MS
```
protected static final long PROVEN_RESPONDER_WINDOW_MS
```
    Recency window for proven-responder proof
    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
  - addFreshCooldownExclusions
```
protected static int addFreshCooldownExclusions(Map<Hash,Long> cooldowns,
                                                long cutoff,
                                                Set<Hash> exclude)
```
    Add cooldown entries still inside their window (value > cutoff) to the exclusion set without mutating the map; returns the count added. Shared by both selectors; the maps themselves stay separate (_peerCooldowns for client pools, the exploratory map for exploratory selections).
    Parameters:
    cooldowns - the cooldown map to scan (never mutated)
    cutoff - entries with value <= cutoff are expired and skipped
    exclude - the exclusion set to add fresh entries to
    Returns:
    the number of entries added
  - 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
  - allowFirewalledUnderAttack
```
static boolean allowFirewalledUnderAttack(String capabilities,
                                          double buildSuccess)
```
    Should we allow a firewalled (U-cap) peer? During attacks (build success below ATTACK_THRESHOLD), allow U-cap peers that also publish M, N, O, P, or X capability. Peers without the U cap are always allowed. Pure decision — no context access, safe for unit tests.
    Parameters:
    capabilities - the peer's capability string, possibly null
    buildSuccess - the build success ratio, fetched once per selection
    Returns:
    true if the peer may be used despite the U cap
  - 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
  - compareProven
```
static int compareProven(long t1,
                         long t2,
                         long now)
```
    Proven-responder comparison for the quality cascade: a peer whose last tunnel participation succeeded within the recency window sorts before one without; two peers on the same side compare equal so later cascade stages decide.
    Parameters:
    t1 - last proven-join time of the first peer, 0 if none
    t2 - last proven-join time of the second peer, 0 if none
    now - current time from the router clock
    Returns:
    negative if only p1 is proven, positive if only p2 is, else 0
  - countKnownCaps
```
static int countKnownCaps(String cap)
```
    Count the meaningful capabilities a peer publishes, used to reject peers with no useful caps when there are plenty of fast peers. Pure — safe for unit tests.
    Parameters:
    cap - the peer's capability string
    Returns:
    the count of known caps (0-2+)
  - filterSlow
```
protected boolean filterSlow(boolean isInbound,
                             boolean isExploratory)
```
    Whether to skip peers that are slow.
    Parameters:
    isInbound - true for inbound tunnels
    isExploratory - true for exploratory tunnels
    Returns:
    true unless configured otherwise
  - formatExcludedPeers
```
protected static String formatExcludedPeers(Set<Hash> peers)
```
    Format a set of excluded peers for logging, with exclusion reasons when the set is an TunnelPeerSelector.Excluder or ExcluderBase.
  - 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
  - getActivityWindow
```
public static long getActivityWindow(RouterContext ctx,
                                     double buildSuccess)
```
    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 6 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
    buildSuccess - the build success ratio, fetched once by the caller
    Returns:
    activity window in milliseconds
  - getBuildSuccess
```
static double getBuildSuccess(RouterContext ctx)
```
    Current tunnel build success ratio, 1.0 when no data is available.
    Expensive: each call performs 6 RateStat lookups and 6 rate fetches (ProfileOrganizer.getTunnelBuildSuccess()). Fetch once per selection or scan and pass the value down; never call per candidate peer. A value of 1.0 (no data) keeps the attack-threshold gates closed at boot instead of treating missing stats as an attack.
    Parameters:
    ctx - the router context
    Returns:
    the ratio in [0.0, 1.0]
  - 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)
```
    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()
```
    Current Tuner-controlled activity-window multiplier.
    Returns:
    the current multiplier, in [1, 8]
  - hasConnectivitySignal
```
static boolean hasConnectivitySignal(PeerProfile profile,
                                     long now,
                                     long activityWindow)
```
    Pre-qualification signal check: does the peer profile show recent connectivity evidence? Heard from or successfully sent to within the last 30 minutes, a successful tunnel test within the activity window, or any test history at all with a >50% acceptance ratio. Pure decision — no context access, safe for unit tests.
    Parameters:
    profile - the peer profile (non-null)
    now - current time in milliseconds
    activityWindow - the dynamic activity window in milliseconds
    Returns:
    true if the profile shows recent connectivity signal
  - 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
  - hasTunnelLongerThanOne
```
protected static boolean hasTunnelLongerThanOne(TunnelPool pool)
```
    True if the pool has at least one active tunnel longer than one hop.
    Parameters:
    pool - the tunnel pool to scan (non-null)
    Returns:
    true if any tunnel has length > 1
  - 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
  - isOutdatedVersion
```
static boolean isOutdatedVersion(String version)
```
    True if the peer runs a version too old to interoperate: not the published version and older than MIN_VERSION. Pure — safe for unit tests.
    Parameters:
    version - the peer's version string
    Returns:
    true if the version is outdated
  - isProvenResponder
```
static boolean isProvenResponder(long lastJoin,
                                 long now)
```
    Whether a proven-join timestamp falls inside the recency window.
    Parameters:
    lastJoin - the last successful-participation time, 0 if none
    now - current time from the router clock
    Returns:
    true if the proof is fresh
  - isStalePeer
```
static boolean isStalePeer(RouterContext ctx,
                           Hash peer)
```
    Check whether a peer is stale — no contact (heard from or heard about) within the dynamic activity window. The window adapts to network visibility: 500+ active peers use 1 hour, 200+ use 2 hours, 100+ use 4 hours, fewer than 100 use 8 hours (fresh router building up picture). Stale peers are skipped during first-hop selection and keepalive to avoid wasting resources on peers that are likely offline. Skipped during the first 15 minutes of uptime (startup grace).
    Parameters:
    ctx - the router context
    peer - hash of the peer to check
    Returns:
    true if the peer has not been heard from or about within the activity window
  - isStalePeer
```
static boolean isStalePeer(RouterContext ctx,
                           Hash peer,
                           double buildSuccess)
```
    Check whether a peer is stale — no contact (heard from or heard about) within the dynamic activity window. The window adapts to network visibility: 500+ active peers use 1 hour, 200+ use 2 hours, 100+ use 4 hours, fewer than 100 use 8 hours (fresh router building up picture). Stale peers are skipped during first-hop selection and keepalive to avoid wasting resources on peers that are likely offline. Skipped during the first 15 minutes of uptime (startup grace). Unprofiled (never-heard-of) peers are NOT stale: excluding them would starve the pool of newcomers during recovery — the activity window below only applies once we have profile data to judge.
    Parameters:
    ctx - the router context
    peer - hash of the peer to check
    buildSuccess - the build success ratio, fetched once by the caller
    Returns:
    true if the peer has a profile and has not been heard from or about within the activity window
  - isUsableRouterAddress
```
static boolean isUsableRouterAddress(RouterAddress ra)
```
    Is the RouterAddress usable for tunnel building? SSU requires protocol v2 plus a valid IP/port or an introduction; SSU2 requires a valid IP/port or an introduction; NTCP/NTCP2 require a valid IP/port. Pure decision — no context access, safe for unit tests.
    Parameters:
    ra - the router address to check (non-null)
    Returns:
    true if the address is usable
  - isZeroHopSettings
```
protected static boolean isZeroHopSettings(TunnelPoolSettings settings)
```
    True if the settings describe a zero-hop pair: length <= 0, length override == 0, or length + variance <= 0. Used to decide whether the paired (inbound) pool needs a connected furthest hop (OBEP) so the build reply can be delivered.
    Parameters:
    settings - the paired pool's settings
    Returns:
    true if the pair is effectively zero-hop
  - 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)
  - matchesExistingTunnel
```
static boolean matchesExistingTunnel(TunnelInfo existing,
                                     List<Hash> newPeers,
                                     boolean isInbound)
```
    Compare a newly selected peer sequence (excluding self) against one existing tunnel. Lengths must match (existing includes self, so one longer than newPeers) and every peer must be equal in order, starting from the gateway side for inbound (index 0) or after self for outbound (index 1). Pure decision — no context access, safe for unit tests.
    Parameters:
    existing - the existing tunnel to compare against
    newPeers - the newly selected peers (excluding self)
    isInbound - true for inbound tunnels
    Returns:
    true if the sequences match
  - 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,
                                     int attempt)
```
    Regenerate tunnel peers to avoid duplicate sequence.
    The canonical order is the key-distance sort from orderPeers(java.util.List<net.i2p.data.Hash>, net.i2p.data.SessionKey). Because that sort is deterministic, regenerating always reproduced the identical sequence and could not avoid duplicates. Each regeneration attempt now rotates the canonical order by a step derived from the pool key, so successive attempts yield different sequences while staying key-derived (attacker-unpredictable).
    Parameters:
    settings - the tunnel pool settings
    peers - the peers to regenerate (not modified)
    attempt - 1-based regeneration attempt number
    Returns:
    regenerated peer list (same or different)
  - relaxedExcludeCaps
```
static String relaxedExcludeCaps(String configured,
                                 double buildSuccess,
                                 long uptimeMs)
```
    Strip the M, N, O, D, P capability exclusions from the configured caps when the build success ratio is below ATTACK_THRESHOLD or the router is within its first STARTUP_WARNING_SUPPRESS_MS of uptime (when the ratio is not yet meaningful). A ratio of 0.0 (no data) relaxes as well, matching the conservative startup behavior. Pure decision — no context access, safe for unit tests.
    Parameters:
    configured - the configured exclude caps, possibly null or empty
    buildSuccess - the build success ratio in [0.0, 1.0]
    uptimeMs - router uptime in milliseconds
    Returns:
    the configured caps with M/N/O/D/P removed when relaxing, otherwise unchanged
  - 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. Never null; an empty list means no peers could be selected.
  - setWindowMultiplier
```
public static void setWindowMultiplier(int mult)
```
    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
  - shouldExclude
```
public static boolean shouldExclude(RouterContext ctx,
                                    RouterInfo peer,
                                    double buildSuccess)
```
    Should the peer be excluded based on its published caps, crypto, and version?
    Variant for per-peer selection loops that already fetched the build success ratio once; avoids re-reading router statistics per peer.
    Parameters:
    ctx - Router context for peer count checks
    peer - The peer to evaluate
    buildSuccess - the build success ratio in [0.0, 1.0]
    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

_firstHopFails

_peerCooldowns

_provenResponders

ATTACK_THRESHOLD

DEGRADED_BUILD_THRESHOLD

FAILURE_MAP_MAX_SIZE

FIRST_HOP_FAIL_COOLDOWN_MS

PEER_SELECTION_COOLDOWN_MS

PROVEN_RESPONDER_WINDOW_MS

STARTUP_WARNING_SUPPRESS_MS

Constructor Detail

TunnelPeerSelector

Method Detail

addFreshCooldownExclusions

allowAsIBGW

allowAsOBEP

allowFirewalledUnderAttack

checkTunnel

compareProven

countKnownCaps

filterSlow

formatExcludedPeers

getActivityWindow

getActivityWindow

getBuildSuccess

getClosestHopExclude

getExclude

getLength

getPeersInPool

getWindowMultiplier

hasConnectivitySignal

hasRecoveredFromFailure

hasTunnelLongerThanOne

hasValidTransportAddress

isDuplicateSequence

isFirstHopFailing

isInStartupGracePeriod

isInStartupGracePeriod

isIPv6Only

isLowAcceptanceRatio

isOutdatedVersion

isProvenResponder

isStalePeer

isStalePeer

isUsableRouterAddress

isZeroHopSettings

keepAlive

matchesExistingTunnel

orderPeers

preConnectTo

prunePeerMaps

recordFirstHopFail

recordPeerFailure

regeneratePeers

relaxedExcludeCaps

selectExplicit

selectPeers

setWindowMultiplier

shouldExclude

shouldExclude

shouldSelectExplicit

supportsNTCP2