net.i2p.router.tunnel.pool

## Class TunnelPoolManager

- java.lang.Object
- - net.i2p.router.tunnel.pool.TunnelPoolManager

- All Implemented Interfaces:
    Service, TunnelManagerFacade

      public class TunnelPoolManager
      extends Object
      implements TunnelManagerFacade

  Manage all the exploratory and client tunnel pools. Run the tunnel builder and handler threads.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `TunnelPoolManager(RouterContext ctx)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `addAlias(Destination dest, ClientTunnelSettings settings, Destination existingClient)` Add another destination to the same tunnels.
    `(package private) void` | `buildComplete(PooledTunnelCreatorConfig cfg)` queue a recurring test job if appropriate
    `void` | `buildTunnels(Destination client, ClientTunnelSettings settings)` Used only at session startup.
    `boolean` | `disableTunnelTesting()`
    `void` | `fail(Hash peer)` Fail all outbound tunnels with this peer as first hop, and all inbound tunnels with this peer as the last hop, baecause we can't contact it any more.
    `(package private) BuildExecutor` | `getExecutor()`
    `int` | `getFreeTunnelCount()` how many free inbound tunnels do we have available?
    `int` | `getInboundBuildQueueSize()` count how many inbound tunnel requests we have received but not yet processed
    `Map<Hash,TunnelPool>` | `getInboundClientPools()` for TunnelRenderer in router console
    `int` | `getInboundClientTunnelCount()` how many free inbound client tunnels do we have available?
    `TunnelPool` | `getInboundExploratoryPool()` For TunnelRenderer in router console
    `TunnelPool` | `getInboundPool(Hash client)`
    `TunnelPoolSettings` | `getInboundSettings()` exploratory
    `TunnelPoolSettings` | `getInboundSettings(Hash client)`
    `long` | `getLastParticipatingExpiration()` When does the last tunnel we are participating in expire?
    `Map<Hash,TunnelPool>` | `getOutboundClientPools()` for TunnelRenderer in router console
    `int` | `getOutboundClientTunnelCount()` how many outbound client tunnels do we have available?
    `int` | `getOutboundClientTunnelCount(Hash destination)` Use to verify a tunnel pool is alive
    `TunnelPool` | `getOutboundExploratoryPool()` For TunnelRenderer in router console
    `TunnelPool` | `getOutboundPool(Hash client)`
    `TunnelPoolSettings` | `getOutboundSettings()` exploratory
    `TunnelPoolSettings` | `getOutboundSettings(Hash client)`
    `int` | `getOutboundTunnelCount()` how many outbound tunnels do we have available?
    `int` | `getParticipatingCount()` how many tunnels are we participating in?
    `double` | `getShareRatio()`
    `boolean` | `isFirewalled()`
    `(package private) boolean` | `isShutdown()`
    `boolean` | `isValidTunnel(Hash client, TunnelInfo tunnel)` Is a tunnel a valid member of the pool?
    `void` | `listPools(List<TunnelPool> out)` list of TunnelPool instances currently in play
    `void` | `removeAlias(Destination dest)` Remove a destination for the same tunnels as another.
    `void` | `removeTunnels(Destination dest)` Must be called AFTER deregistration by the client manager.
    `void` | `removeTunnels(Hash destination)` This will be called twice, once by the inbound and once by the outbound pool.
    `void` | `restart()` Perform a soft restart.
    `TunnelInfo` | `selectInboundExploratoryTunnel(Hash closestTo)` Pick the inbound exploratory tunnel with the gateway closest to the given hash.
    `TunnelInfo` | `selectInboundTunnel()` Pick a random inbound exploratory tunnel.
    `TunnelInfo` | `selectInboundTunnel(Hash destination)` Pick a random inbound tunnel from the given destination's pool.
    `TunnelInfo` | `selectInboundTunnel(Hash destination, Hash closestTo)` Pick the inbound tunnel with the gateway closest to the given hash from the given destination's pool.
    `TunnelInfo` | `selectOutboundExploratoryTunnel(Hash closestTo)` Pick the outbound exploratory tunnel with the endpoint closest to the given hash.
    `TunnelInfo` | `selectOutboundTunnel()` Pick a random outbound exploratory tunnel.
    `TunnelInfo` | `selectOutboundTunnel(Hash destination)` Pick a random outbound tunnel from the given destination's pool.
    `TunnelInfo` | `selectOutboundTunnel(Hash destination, Hash closestTo)` Pick the outbound tunnel with the endpoint closest to the given hash from the given destination's pool.
    `Set<Hash>` | `selectPeersInTooManyTunnels()` For reliability reasons, don't allow a peer in more than x% of client and exploratory tunnels.
    `void` | `setInboundSettings(Hash client, TunnelPoolSettings settings)`
    `void` | `setInboundSettings(TunnelPoolSettings settings)` exploratory
    `void` | `setOutboundSettings(Hash client, TunnelPoolSettings settings)`
    `void` | `setOutboundSettings(TunnelPoolSettings settings)` exploratory
    `void` | `shutdown()` Cannot be restarted
    `void` | `startup()` Instruct the service that it should start normal operation.
    `(package private) void` | `tunnelFailed()` Poke the build executor to build more tunnels.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface net.i2p.router.Service

      `renderStatusHTML`

- - ### Constructor Detail

    - #### TunnelPoolManager

          public TunnelPoolManager(RouterContext ctx)

  - ### Method Detail

    - #### addAlias

          public 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.
      Specified by:
        `addAlias` in interface `TunnelManagerFacade`
      Returns:
        success
      Throws:
        `IllegalArgumentException` - if not

    - #### buildComplete

          void buildComplete(PooledTunnelCreatorConfig cfg)

      queue a recurring test job if appropriate

    - #### buildTunnels

          public void buildTunnels(Destination client,
                                   ClientTunnelSettings settings)

      Used only at session startup. Do not use to change settings. Do not use for aliased destinations; use addAlias().
      Specified by:
        `buildTunnels` in interface `TunnelManagerFacade`

    - #### disableTunnelTesting

          public boolean disableTunnelTesting()

    - #### fail

          public void fail(Hash peer)

      Fail all outbound tunnels with this peer as first hop, and all inbound tunnels with this peer as the last hop, baecause we can't contact it any more. This is most likely to be triggered by an outbound tunnel.
      Specified by:
        `fail` in interface `TunnelManagerFacade`

    - #### getExecutor

          BuildExecutor getExecutor()

    - #### getFreeTunnelCount

          public int getFreeTunnelCount()

      Description copied from interface: `TunnelManagerFacade`
      how many free inbound tunnels do we have available?
      Specified by:
        `getFreeTunnelCount` in interface `TunnelManagerFacade`
      Returns:
        number of inbound exploratory tunnels

    - #### getInboundBuildQueueSize

          public int getInboundBuildQueueSize()

      Description copied from interface: `TunnelManagerFacade`
      count how many inbound tunnel requests we have received but not yet processed
      Specified by:
        `getInboundBuildQueueSize` in interface `TunnelManagerFacade`

    - #### getInboundClientPools

          public Map<Hash,TunnelPool> getInboundClientPools()

      for TunnelRenderer in router console
      Specified by:
        `getInboundClientPools` in interface `TunnelManagerFacade`

    - #### getInboundClientTunnelCount

          public int getInboundClientTunnelCount()

      Description copied from interface: `TunnelManagerFacade`
      how many free inbound client tunnels do we have available?
      Specified by:
        `getInboundClientTunnelCount` in interface `TunnelManagerFacade`

    - #### getInboundExploratoryPool

          public TunnelPool getInboundExploratoryPool()

      For TunnelRenderer in router console
      Specified by:
        `getInboundExploratoryPool` in interface `TunnelManagerFacade`
      Returns:
        non-null

    - #### getInboundPool

          public TunnelPool getInboundPool(Hash client)

      Specified by:
        `getInboundPool` in interface `TunnelManagerFacade`
      Returns:
        pool or null

    - #### getInboundSettings

          public TunnelPoolSettings getInboundSettings()

      exploratory
      Specified by:
        `getInboundSettings` in interface `TunnelManagerFacade`

    - #### getInboundSettings

          public TunnelPoolSettings getInboundSettings(Hash client)

      Specified by:
        `getInboundSettings` in interface `TunnelManagerFacade`

    - #### getLastParticipatingExpiration

          public long getLastParticipatingExpiration()

      Description copied from interface: `TunnelManagerFacade`
      When does the last tunnel we are participating in expire?
      Specified by:
        `getLastParticipatingExpiration` in interface `TunnelManagerFacade`

    - #### getOutboundClientPools

          public Map<Hash,TunnelPool> getOutboundClientPools()

      for TunnelRenderer in router console
      Specified by:
        `getOutboundClientPools` in interface `TunnelManagerFacade`

    - #### getOutboundClientTunnelCount

          public int getOutboundClientTunnelCount()

      Description copied from interface: `TunnelManagerFacade`
      how many outbound client tunnels do we have available?
      Specified by:
        `getOutboundClientTunnelCount` in interface `TunnelManagerFacade`

    - #### getOutboundClientTunnelCount

          public int getOutboundClientTunnelCount(Hash destination)

      Use to verify a tunnel pool is alive
      Specified by:
        `getOutboundClientTunnelCount` in interface `TunnelManagerFacade`

    - #### getOutboundExploratoryPool

          public TunnelPool getOutboundExploratoryPool()

      For TunnelRenderer in router console
      Specified by:
        `getOutboundExploratoryPool` in interface `TunnelManagerFacade`
      Returns:
        non-null

    - #### getOutboundPool

          public TunnelPool getOutboundPool(Hash client)

      Specified by:
        `getOutboundPool` in interface `TunnelManagerFacade`
      Returns:
        pool or null

    - #### getOutboundSettings

          public TunnelPoolSettings getOutboundSettings()

      exploratory
      Specified by:
        `getOutboundSettings` in interface `TunnelManagerFacade`

    - #### getOutboundSettings

          public TunnelPoolSettings getOutboundSettings(Hash client)

      Specified by:
        `getOutboundSettings` in interface `TunnelManagerFacade`

    - #### getOutboundTunnelCount

          public int getOutboundTunnelCount()

      Description copied from interface: `TunnelManagerFacade`
      how many outbound tunnels do we have available?
      Specified by:
        `getOutboundTunnelCount` in interface `TunnelManagerFacade`
      Returns:
        number of outbound exploratory tunnels

    - #### getParticipatingCount

          public int getParticipatingCount()

      Description copied from interface: `TunnelManagerFacade`
      how many tunnels are we participating in?
      Specified by:
        `getParticipatingCount` in interface `TunnelManagerFacade`

    - #### getShareRatio

          public double getShareRatio()

      Specified by:
        `getShareRatio` in interface `TunnelManagerFacade`
      Returns:
        (number of part. tunnels) / (estimated total number of hops in our expl.+client tunnels) We just use length setting, not variance, for speed

    - #### isFirewalled

          public boolean isFirewalled()

    - #### isShutdown

          boolean isShutdown()

    - #### isValidTunnel

          public boolean isValidTunnel(Hash client,
                                       TunnelInfo tunnel)

      Description copied from interface: `TunnelManagerFacade`
      Is a tunnel a valid member of the pool?
      Specified by:
        `isValidTunnel` in interface `TunnelManagerFacade`

    - #### listPools

          public void listPools(List<TunnelPool> out)

      list of TunnelPool instances currently in play
      Specified by:
        `listPools` in interface `TunnelManagerFacade`

    - #### removeAlias

          public void removeAlias(Destination dest)

      Remove a destination for the same tunnels as another.
      Specified by:
        `removeAlias` in interface `TunnelManagerFacade`

    - #### removeTunnels

          public void removeTunnels(Destination dest)

      Must be called AFTER deregistration by the client manager.
      Specified by:
        `removeTunnels` in interface `TunnelManagerFacade`

    - #### removeTunnels

          public void removeTunnels(Hash destination)

      This will be called twice, once by the inbound and once by the outbound pool. Synched with buildTunnels() above. Must be called AFTER deregistration by the client manager.

    - #### restart

          public void restart()

      Description copied from interface: `Service`
      Perform a soft restart.
      Specified by:
        `restart` in interface `Service`

    - #### selectInboundExploratoryTunnel

          public 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.
      Specified by:
        `selectInboundExploratoryTunnel` in interface `TunnelManagerFacade`
      Parameters:
        `closestTo` - non-null
      Returns:
        null if none

    - #### selectInboundTunnel

          public TunnelInfo selectInboundTunnel()

      Pick a random inbound exploratory tunnel. Warning - selectInboundExploratoryTunnel(Hash) is preferred.
      Specified by:
        `selectInboundTunnel` in interface `TunnelManagerFacade`
      Returns:
        null if none

    - #### selectInboundTunnel

          public TunnelInfo selectInboundTunnel(Hash destination)

      Pick a random inbound tunnel from the given destination's pool. Warning - selectInboundTunnel(Hash, Hash) is preferred.
      Specified by:
        `selectInboundTunnel` in interface `TunnelManagerFacade`
      Parameters:
        `destination` - if null, returns inbound exploratory tunnel
      Returns:
        null if none

    - #### selectInboundTunnel

          public 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.
      Specified by:
        `selectInboundTunnel` in interface `TunnelManagerFacade`
      Parameters:
        `destination` - if null, returns inbound exploratory tunnel
        `closestTo` - non-null
      Returns:
        null if none

    - #### selectOutboundExploratoryTunnel

          public 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.
      Specified by:
        `selectOutboundExploratoryTunnel` in interface `TunnelManagerFacade`
      Parameters:
        `closestTo` - non-null
      Returns:
        null if none

    - #### selectOutboundTunnel

          public TunnelInfo selectOutboundTunnel()

      Pick a random outbound exploratory tunnel. Warning - selectOutboundExploratoryTunnel(Hash) is preferred.
      Specified by:
        `selectOutboundTunnel` in interface `TunnelManagerFacade`
      Returns:
        null if none

    - #### selectOutboundTunnel

          public TunnelInfo selectOutboundTunnel(Hash destination)

      Pick a random outbound tunnel from the given destination's pool. Warning - selectOutboundTunnel(Hash, Hash) is preferred.
      Specified by:
        `selectOutboundTunnel` in interface `TunnelManagerFacade`
      Parameters:
        `destination` - if null, returns outbound exploratory tunnel
      Returns:
        null if none

    - #### selectOutboundTunnel

          public 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.
      Specified by:
        `selectOutboundTunnel` in interface `TunnelManagerFacade`
      Parameters:
        `destination` - if null, returns outbound exploratory tunnel
        `closestTo` - non-null
      Returns:
        null if none

    - #### selectPeersInTooManyTunnels

          public Set<Hash> selectPeersInTooManyTunnels()

      For reliability reasons, don't allow a peer in more than x% of client and exploratory tunnels. This also will prevent a single huge-capacity (or malicious) peer from taking all the tunnels in the network (although it would be nice to limit the % of total network tunnels to 10% or so, but that appears to be too low to set as a default here... much lower than 33% will push client tunnels out of the fast tier into high cap or beyond...) Possible improvement - restrict based on count per IP, or IP block, to slightly increase costs of collusion
      Specified by:
        `selectPeersInTooManyTunnels` in interface `TunnelManagerFacade`
      Returns:
        Set of peers that should not be allowed in another tunnel

    - #### setInboundSettings

          public void setInboundSettings(Hash client,
                                         TunnelPoolSettings settings)

      Specified by:
        `setInboundSettings` in interface `TunnelManagerFacade`

    - #### setInboundSettings

          public void setInboundSettings(TunnelPoolSettings settings)

      exploratory
      Specified by:
        `setInboundSettings` in interface `TunnelManagerFacade`

    - #### setOutboundSettings

          public void setOutboundSettings(Hash client,
                                          TunnelPoolSettings settings)

      Specified by:
        `setOutboundSettings` in interface `TunnelManagerFacade`

    - #### setOutboundSettings

          public void setOutboundSettings(TunnelPoolSettings settings)

      exploratory
      Specified by:
        `setOutboundSettings` in interface `TunnelManagerFacade`

    - #### shutdown

          public void shutdown()

      Cannot be restarted
      Specified by:
        `shutdown` in interface `Service`

    - #### startup

          public void startup()

      Description copied from interface: `Service`
      Instruct the service that it should start normal operation. This call DOES block until the service is ready.
      Specified by:
        `startup` in interface `Service`

    - #### tunnelFailed

          void tunnelFailed()

      Poke the build executor to build more tunnels.