org.klomp.snark.dht

## Class NID

- java.lang.Object
- - net.i2p.data.SimpleDataStructure
  - - net.i2p.crypto.SHA1Hash
    - - org.klomp.snark.dht.NID

- All Implemented Interfaces:
    DataStructure

      public class NID
      extends SHA1Hash

  Node Identifier (NID) for Kademlia DHT operations.

  A NID is a 20-byte SHA1 hash that uniquely identifies a node in the DHT keyspace. It serves as the primary key for routing table entries and is used extensively throughout the DHT system for node identification, distance calculations, and bucket placement.

  Beyond the basic SHA1 hash functionality, this class tracks node health metrics including last seen time and failure count. This information is crucial for maintaining a healthy routing table by identifying and removing unreliable or unreachable nodes.

  Key features:
  - Extends SHA1Hash for efficient storage and comparison
  - Tracks last seen time for node freshness assessment
  - Maintains failure count to detect unreachable nodes
  - Provides timeout detection after multiple consecutive failures
  - Used extensively as map keys throughout the DHT system

  Failure handling allows up to 5 consecutive timeouts before marking a node as problematic, providing resilience against temporary network issues while eventually removing persistently unreachable nodes.

- - ### Field Summary

    - ### Fields inherited from class net.i2p.crypto.SHA1Hash

      `HASH_LENGTH`

    - ### Fields inherited from class net.i2p.data.SimpleDataStructure

      `_data`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `NID()` Creates a new empty NID.
    `NID(byte[] data)` Creates a new NID with the specified data.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `long` | `lastSeen()` Returns the timestamp when this node was last successfully seen.
    `void` | `setLastSeen()` Updates the last seen timestamp and resets failure count.
    `boolean` | `timeout()` Records a timeout and checks if the node should be considered problematic.

    - ### Methods inherited from class net.i2p.crypto.SHA1Hash

      `hashCode, length, readBytes, setData`

    - ### Methods inherited from class net.i2p.data.SimpleDataStructure

      `calculateHash, equals, fromBase64, fromByteArray, getData, read, toBase64, toByteArray, toString, writeBytes`

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### NID

          public NID()

      Creates a new empty NID.

      Creates an NID with null data, typically used as a placeholder or for initialization purposes where the actual NID value will be set later.

    - #### NID

          public NID(byte[] data)

      Creates a new NID with the specified data.
      Parameters:
        `data` - the 20-byte SHA1 hash data for this node identifier

  - ### Method Detail

    - #### lastSeen

          public long lastSeen()

      Returns the timestamp when this node was last successfully seen.
      Returns:
        the timestamp in milliseconds since epoch, or 0 if never seen

    - #### setLastSeen

          public void setLastSeen()

      Updates the last seen timestamp and resets failure count.

      This method should be called whenever successful communication with the node occurs. It updates the freshness metric and resets the failure counter, indicating the node is currently reachable.

    - #### timeout

          public boolean timeout()

      Records a timeout and checks if the node should be considered problematic.

      Increments the failure counter and returns whether the node has exceeded the maximum allowed consecutive failures. This helps identify nodes that are consistently unreachable and should be removed from the routing table.

      Returns:
        true if the node has exceeded the maximum allowed failures, false otherwise