All Superinterfaces:
Service
All Known Implementing Classes:
DummyTunnelManagerFacade, TunnelPoolManager
public interface TunnelManagerFacade extends Service
Manages tunnel creation, maintenance, and selection for encrypted routing. Coordinates exploratory and client-specific tunnels for secure message delivery.

  • Method Details

    • selectInboundTunnel

      TunnelInfo selectInboundTunnel()
      Pick a random inbound exploratory tunnel.
      Returns:
      null if none

    • selectInboundTunnel

      TunnelInfo selectInboundTunnel(Hash destination)
      Pick a random inbound tunnel from the given destination's pool.
      Parameters:
      destination - if null, returns inbound exploratory tunnel
      Returns:
      null if none

    • selectOutboundTunnel

      TunnelInfo selectOutboundTunnel()
      Pick a random outbound exploratory tunnel.
      Returns:
      null if none

    • selectOutboundTunnel

      TunnelInfo selectOutboundTunnel(Hash destination)
      Pick a random outbound tunnel from the given destination's pool.
      Parameters:
      destination - if null, returns outbound exploratory tunnel
      Returns:
      null if none

    • selectAnyOutboundTunnel

      TunnelInfo selectAnyOutboundTunnel()
      Pick a random outbound tunnel from any pool — client pools first, then exploratory.
      Returns:
      null if none

    • selectAnyInboundTunnel

      TunnelInfo selectAnyInboundTunnel()
      Pick a random inbound tunnel from any pool — client pools first, then exploratory.
      Returns:
      null if none

    • selectInboundExploratoryTunnel

      TunnelInfo selectInboundExploratoryTunnel(Hash closestTo)
      Pick the inbound exploratory tunnel with the gateway closest to the given hash. By using this instead of the random selectTunnel(), we force some locality in OBEP-IBGW connections to minimize those connections network-wide.
      Parameters:
      closestTo - non-null
      Returns:
      null if none

    • selectInboundTunnel

      TunnelInfo selectInboundTunnel(Hash destination, Hash closestTo)
      Pick the inbound tunnel with the gateway closest to the given hash from the given destination's pool. By using this instead of the random selectTunnel(), we force some locality in OBEP-IBGW connections to minimize those connections network-wide.
      Parameters:
      destination - if null, returns inbound exploratory tunnel
      closestTo - non-null
      Returns:
      null if none

    • selectOutboundExploratoryTunnel

      TunnelInfo selectOutboundExploratoryTunnel(Hash closestTo)
      Pick the outbound exploratory tunnel with the endpoint closest to the given hash. By using this instead of the random selectTunnel(), we force some locality in OBEP-IBGW connections to minimize those connections network-wide.
      Parameters:
      closestTo - non-null
      Returns:
      null if none

    • selectOutboundTunnel

      TunnelInfo selectOutboundTunnel(Hash destination, Hash closestTo)
      Pick the outbound tunnel with the endpoint closest to the given hash from the given destination's pool. By using this instead of the random selectTunnel(), we force some locality in OBEP-IBGW connections to minimize those connections network-wide.
      Parameters:
      destination - if null, returns outbound exploratory tunnel
      closestTo - non-null
      Returns:
      null if none

    • isValidTunnel

      boolean isValidTunnel(Hash client, TunnelInfo tunnel)
      Is a tunnel a valid member of the pool?
      Parameters:
      client - hash of the destination whose pool is checked
      tunnel - candidate, rejected if failed or expired
      Returns:
      true only if unfailed, unexpired and listed in that client's inbound or outbound pool, matching the tunnel's direction

    • getParticipatingCount

      int getParticipatingCount()
      How many tunnels are we participating in?
      Returns:
      number of tunnels where we are a gateway or an endpoint

    • getFreeTunnelCount

      int getFreeTunnelCount()
      How many free inbound tunnels do we have available?
      Returns:
      number of valid, unfailed inbound exploratory tunnels

    • getOutboundTunnelCount

      int getOutboundTunnelCount()
      How many outbound tunnels do we have available?
      Returns:
      number of valid, unfailed outbound exploratory tunnels

    • getInboundClientTunnelCount

      int getInboundClientTunnelCount()
      How many free inbound client tunnels do we have available?
      Returns:
      total over all destinations of GOOD (tested and passed) inbound client tunnels

    • getOutboundClientTunnelCount

      int getOutboundClientTunnelCount()
      How many outbound client tunnels do we have available?
      Returns:
      total over all destinations of GOOD (tested and passed) outbound client tunnels

    • getOutboundClientTunnelCount

      int getOutboundClientTunnelCount(Hash destination)
      How many outbound client tunnels in this pool?
      Parameters:
      destination - hash of the destination owning the outbound pool
      Returns:
      GOOD tunnel count, or the count including untested tunnels while bootstrapping, or 0 if no pool is registered

    • getInboundClientTunnelCount

      int getInboundClientTunnelCount(Hash destination)
      How many inbound client tunnels in this pool?
      Parameters:
      destination - hash of the destination owning the inbound pool
      Returns:
      GOOD tunnel count, or the count including untested tunnels while bootstrapping, or 0 if no pool is registered

    • getShareRatio

      double getShareRatio()
      The share ratio of tunnel bandwidth allocated to the network.
      Returns:
      the share ratio

    • getLastParticipatingExpiration

      long getLastParticipatingExpiration()
      When does the last tunnel we are participating in expire?
      Returns:
      expiration of the latest-expiring participating tunnel in milliseconds since the epoch, or -1 if we participate in none

    • getInboundBuildQueueSize

      int getInboundBuildQueueSize()
      Count how many inbound tunnel requests we have received but not yet processed.
      Returns:
      number of inbound build requests waiting in the queue

    • selectPeersInTooManyTunnels

      Set<Hash> selectPeersInTooManyTunnels()
      Peers that should not be allowed to be in another tunnel.
      Returns:
      Set of peers that should not be allowed to be in another tunnel

    • buildTunnels

      void buildTunnels(Destination client, ClientTunnelSettings settings)
      The client connected (or updated their settings), so make sure we have the tunnels for them, and whenever necessary, ask them to authorize leases.
      Parameters:
      client - connecting destination, whose hash keys the pools created here
      settings - per-destination inbound and outbound pool settings, which replace those of any pools that already exist

    • removeTunnels

      void removeTunnels(Destination client)
      Must be called AFTER deregistration by the client manager.
      Parameters:
      client - destination whose pools are scheduled for removal, deferred so its tunnels keep operating until they expire

    • addAlias

      boolean addAlias(Destination dest, ClientTunnelSettings settings, Destination existingClient)
      Add another destination to the same tunnels. Must have same encryption key and a different signing key.
      Parameters:
      dest - alias destination, which gets its own pools flagged as aliased
      settings - settings for the alias pools, retained under the primary hash
      existingClient - primary destination whose tunnels are being shared
      Returns:
      true if the alias pools were created, false if the destination already had pools or the primary has none
      Throws:
      IllegalArgumentException - if the signing keys match or the encryption keys differ

    • removeAlias

      void removeAlias(Destination dest)
      Remove another destination to the same tunnels.
      Parameters:
      dest - alias destination to drop from the primary's alias set

    • getInboundSettings

      TunnelPoolSettings getInboundSettings()
      The inbound settings for the exploratory pool.
      Returns:
      the inbound settings

    • getOutboundSettings

      TunnelPoolSettings getOutboundSettings()
      The outbound settings for the exploratory pool.
      Returns:
      the outbound settings

    • getInboundSettings

      TunnelPoolSettings getInboundSettings(Hash client)
      The inbound settings for the given client.
      Parameters:
      client - the client hash
      Returns:
      the inbound settings

    • getOutboundSettings

      TunnelPoolSettings getOutboundSettings(Hash client)
      The outbound settings for the given client.
      Parameters:
      client - the client hash
      Returns:
      the outbound settings

    • setInboundSettings

      void setInboundSettings(TunnelPoolSettings settings)
      The inbound settings for the exploratory pool.
      Parameters:
      settings - the inbound settings

    • setOutboundSettings

      void setOutboundSettings(TunnelPoolSettings settings)
      The outbound settings for the exploratory pool.
      Parameters:
      settings - the outbound settings

    • setInboundSettings

      void setInboundSettings(Hash client, TunnelPoolSettings settings)
      The inbound settings for the given client.
      Parameters:
      client - the client hash
      settings - the inbound settings

    • setOutboundSettings

      void setOutboundSettings(Hash client, TunnelPoolSettings settings)
      The outbound settings for the given client.
      Parameters:
      client - the client hash
      settings - the outbound settings

    • listPools

      void listPools(List<TunnelPool> out)
      For TunnelRenderer in router console.
      Parameters:
      out - list that the client inbound, client outbound and both exploratory pools are appended to

    • getInboundClientPools

      Map<Hash, TunnelPool> getInboundClientPools()
      For TunnelRenderer in router console.
      Returns:
      snapshot of the inbound pools, keyed by destination hash

    • getOutboundClientPools

      Map<Hash, TunnelPool> getOutboundClientPools()
      For TunnelRenderer in router console.
      Returns:
      snapshot of the outbound pools, keyed by destination hash

    • getInboundExploratoryPool

      TunnelPool getInboundExploratoryPool()
      For TunnelRenderer in router console.
      Returns:
      the shared inbound exploratory pool, never null

    • getOutboundExploratoryPool

      TunnelPool getOutboundExploratoryPool()
      For TunnelRenderer in router console.
      Returns:
      the shared outbound exploratory pool, never null

    • getInboundPool

      TunnelPool getInboundPool(Hash client)
      Inbound tunnel pool for the given client, or null if none.
      Parameters:
      client - hash of the destination that owns the pool
      Returns:
      pool or null

    • getOutboundPool

      TunnelPool getOutboundPool(Hash client)
      Outbound tunnel pool for the given client, or null if none.
      Parameters:
      client - hash of the destination that owns the pool
      Returns:
      pool or null

    • ensurePoolsFor

      int ensurePoolsFor(Hash client)
      Run both of a client's pools' ensure logic on demand instead of waiting for the next build-timer interval. Called from the data phase when a send failed for pool-empty reasons (message expired while queued, no tunnels available). A liveness signal that the pools need rebuilding now. Each pool's internal ensure throttle still applies, so a failure storm cannot become a build storm.

      The pool maps are keyed by the local client (source) destination hash, never the remote destination: passing a remote hash finds no pools and silently does nothing.

      Additive ABI: this method and its int return both postdate 0.9.70+ (no release ever shipped a void variant), so implementations and callers only ever saw this signature; callers may still ignore the returned count.

      Parameters:
      client - the LOCAL client destination hash whose pools should rebuild
      Returns:
      how many pools were nudged; 0 when none are registered for the client

    • fail

      void fail(Hash peer)
      Fail every tunnel that depends on a peer we can no longer reach: outbound tunnels with it as first hop, inbound tunnels with it as last hop.
      Parameters:
      peer - hash of the unreachable peer

    • getGhostPeerManager

      GhostPeerManager getGhostPeerManager()
      The ghost peer manager for tracking peers with consistent tunnel build timeouts.
      Returns:
      the GhostPeerManager instance

    • reportSendFailure

      void reportSendFailure(TunnelInfo tunnel, int status)
      Report a data-phase send failure for a specific tunnel. Called from the I2CP message dispatch path when a message fails through a known tunnel (e.g. expired, local overflow, no tunnels available). Increments the tunnel's failure counter and triggers replacement builds when the threshold is reached, so the pool rotates away from the failing tunnel faster than TestJob alone.
      Parameters:
      tunnel - the outbound tunnel that carried the failed message
      status - the I2CP MessageStatusMessage failure code

    • forceTunnelFailure

      void forceTunnelFailure(TunnelInfo tunnel)
      Force a tunnel to fail immediately and trigger a replacement build. Used when rotation is saturated and the pool has no viable alternative tunnels (e.g., all tunnels in the pool match the cached tunnel). This bypasses the incremental failure counter and directly removes the tunnel, ensuring the pool builds a replacement without waiting for multiple failure reports.
      Parameters:
      tunnel - the outbound tunnel to force-fail