org.klomp.snark.dht

## Class KBTrimmer

- java.lang.Object
- - org.klomp.snark.dht.KBTrimmer

- All Implemented Interfaces:
    KBucketTrimmer<NID>

      class KBTrimmer
      extends Object
      implements KBucketTrimmer<NID>

  Kademlia bucket trimmer for DHT node management.

  Implements a conservative bucket trimming strategy that removes stale nodes while preserving recently active routing information. This trimmer follows Kademlia best practices by only removing nodes that haven't been seen for an extended period, and only when the bucket has been stable.

  Trimming strategy:
  - Only removes nodes older than 15 minutes
  - Only trims if the bucket hasn't changed in the last 5 minutes
  - Prioritizes keeping recently active nodes in the routing table
  - Helps maintain DHT health by preventing premature eviction of good nodes

  This conservative approach helps maintain DHT stability and prevents thrashing where nodes are frequently added and removed from buckets.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `KBTrimmer(I2PAppContext ctx, int max)` Creates a new bucket trimmer with the specified maximum bucket size.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `trim(KBucket<NID> kbucket, NID toAdd)` Attempts to trim a Kademlia bucket to make room for a new node.

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

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

- - ### Constructor Detail

    - #### KBTrimmer

          public KBTrimmer(I2PAppContext ctx,
                           int max)

      Creates a new bucket trimmer with the specified maximum bucket size.
      Parameters:
        `ctx` - the I2P application context for clock access
        `max` - the maximum number of entries allowed in a bucket

  - ### Method Detail

    - #### trim

          public boolean trim(KBucket<NID> kbucket,
                              NID toAdd)

      Attempts to trim a Kademlia bucket to make room for a new node.

      This method implements a conservative trimming strategy that only removes stale nodes under specific conditions. The trimming logic is designed to maintain DHT health by preserving recently active nodes while allowing removal of nodes that are likely no longer reachable.

      Trimming conditions:
      1. The bucket must not have changed in the last 5 minutes
      2. Only nodes not seen in the last 15 minutes are candidates for removal
      3. If no stale nodes are found, trimming only succeeds if bucket is under capacity

      Specified by:
        `trim` in interface `KBucketTrimmer<NID>`
      Parameters:
        `kbucket` - the Kademlia bucket to trim
        `toAdd` - the node ID that will be added if trimming succeeds
      Returns:
        true if trimming was successful and space is available for the new node, false otherwise