KRPC (Javadocs [I2P+ 2.13.0+] - API Version 0.9.70+)

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

All Implemented Interfaces:: I2PSessionListener, I2PSessionMuxedListener, DHT

Direct Known Subclasses:: TorrentKRPC

public class KRPC
extends Object
implements I2PSessionMuxedListener, DHT

Kademlia Remote Procedure Call implementation for BitTorrent DHT (BEP 5) adapted for I2P.

This class implements the DHT node communication protocol used for decentralized peer discovery in BitTorrent networks. It handles:

Kademlia routing table management
DHT queries (ping, find_node, get_peers, announce_peer)
Token-based peer announcement system
Node discovery and maintenance
Blacklist management for unreachable nodes

I2P-Specific Modifications:

 - The UDP port need not be pinged after receiving a PORT message.

 - The UDP (datagram) port listed in the compact node info is used
   to receive repliable (signed) datagrams.
   This is used for queries, except for announces.
   We call this the "query port".
   In addition to that UDP port, we use a second datagram
   port equal to the signed port + 1. This is used to receive
   unsigned (raw) datagrams for replies, errors, and announce queries.
   We call this the "response port".

 - Compact peer info is 32 bytes (32 byte SHA256 Hash)
   instead of 4 byte IP + 2 byte port. There is no peer port.

 - Compact node info is 54 bytes (20 byte SHA1 Hash + 32 byte SHA256 Hash + 2 byte port)
   instead of 20 byte SHA1 Hash + 4 byte IP + 2 byte port.
   Port is the query port, the response port is always the query port + 1.

 - The trackerless torrent dictionary "nodes" key is a list of
   32 byte binary strings (SHA256 Hashes) instead of a list of lists
   containing a host string and a port integer.

This implementation uses I2P's datagram infrastructure for secure, anonymous DHT operations within the I2P network.

Nested Class Summary
Nested Classes
Modifier and Type Class and Description
protected class KRPC.ReplyWaiter
Callback for replies

Nested Classes
Modifier and Type	Class and Description
`protected class`	`KRPC.ReplyWaiter` Callback for replies

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`_isRunning`
`protected int`	`_qPort` Signed datagrams.
`protected int`	`_rPort` Unsigned datagrams.
`protected I2PSession`	`_session` Hook to inject and receive datagrams.
`static String`	`DHT_FILE_SUFFIX` File suffix for DHT persistent storage.
`static NID`	`FAKE_NID` All-zero NID used for pings.
`static boolean`	`SECURE_NID` When true, generated NIDs must satisfy a cryptographic puzzle.

Constructor Summary

Constructors
Modifier	Constructor and Description
	`KRPC(I2PAppContext ctx, String baseName, I2PSession session)` Create the DHT instance.
`protected`	`KRPC(I2PAppContext ctx, String baseName, I2PSession session, KRPC shared)` Create the DHT instance sharing state.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addServedTorrent(InfoHash ih)` Serve tracker queries for the given infohash in addition to any already served.
`void`	`announce(byte[] ih, boolean isSeed)` Announce to ourselves.
`void`	`announce(byte[] ih, byte[] peerHash, boolean isSeed)` Announce somebody else we know about to ourselves.
`int`	`announce(byte[] ih, int max, long maxWait, boolean isSeed)` Not recommended - use getPeersAndAnnounce().
`void`	`clear()` Clears the tracker and DHT data.
`void`	`disconnected(I2PSession session)` Handle a session disconnect.
`void`	`errorOccurred(I2PSession session, String message, Throwable error)` Handle a session error.
`List<NodeInfo>`	`findClosest(byte[] ih, int max)` Local lookup only
`Collection<Hash>`	`getPeersAndAnnounce(byte[] ih, int max, long maxWait, int annMax, long annMaxWait, boolean isSeed, boolean noSeeds)` Find peers for a torrent, announcing to the closest annMax nodes found.
`int`	`getPort()` The UDP query port.
`int`	`getRPort()` The UDP response port.
`(package private) NodeInfo`	`heardAbout(NodeInfo nInfo)` Called for bootstrap or for all nodes in a receiveNodes reply.
`void`	`messageAvailable(I2PSession session, int msgId, long size)` For non-muxed.
`void`	`messageAvailable(I2PSession session, int msgId, long size, int proto, int fromPort, int toPort)` Instruct the client that the given session has received a message
`void`	`ping(Destination dest, int port)` Ping.
`(package private) static List<NodeInfo>`	`removeSelf(List<NodeInfo> nodes, NodeInfo self)` Remove any entries equal to ourselves from a list of candidate nodes.
`void`	`removeServedTorrent(InfoHash ih)` Stop serving tracker queries for the given infohash.
`String`	`renderStatusHTML()` Debug info, HTML formatted.
`void`	`reportAbuse(I2PSession session, int severity)` Handle a reportAbuse message from the session.
`void`	`setServeAll(boolean serveAll)` Whether tracker queries are served for every infohash.
`int`	`size()` Known nodes, not estimated total network size.
`void`	`start()` Start the DHT.
`void`	`stop()` Stop everything.
`void`	`unannounce(byte[] ih)` Remove reference to ourselves in the local tracker.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - _isRunning
```
protected volatile boolean _isRunning
```
  - _qPort
```
protected int _qPort
```
    Signed datagrams.
  - _rPort
```
protected int _rPort
```
    Unsigned datagrams.
  - _session
```
protected I2PSession _session
```
    Hook to inject and receive datagrams.
  - DHT_FILE_SUFFIX
```
public static final String DHT_FILE_SUFFIX
```
    File suffix for DHT persistent storage.
    See Also:
    Constant Field Values
  - FAKE_NID
```
public static final NID FAKE_NID
```
    All-zero NID used for pings.
  - SECURE_NID
```
public static final boolean SECURE_NID
```
    When true, generated NIDs must satisfy a cryptographic puzzle.
    See Also:
    Constant Field Values
- Constructor Detail
  - KRPC
```
public KRPC(I2PAppContext ctx,
            String baseName,
            I2PSession session)
```
    Create the DHT instance.
    Parameters:
    baseName - generally "i2psnark"
  - KRPC
```
protected KRPC(I2PAppContext ctx,
               String baseName,
               I2PSession session,
               KRPC shared)
```
    Create the DHT instance sharing state.
    Parameters:
    baseName - generally "i2psnark"
    shared - the KRPC instance whose routing table, tracker, and blacklist are shared with this instance, or null for a standalone instance; a TorrentKRPC passes the main instance and overrides start() and stop() to run only the message listener
- Method Detail
  - addServedTorrent
```
public void addServedTorrent(InfoHash ih)
```
    Serve tracker queries for the given infohash in addition to any already served. A per-torrent DHT instance registers its own torrent; a pooled destination registers each torrent assigned to it, so probing one destination never reveals torrents hosted elsewhere.
    Parameters:
    ih - the infohash to serve
  - announce
```
public void announce(byte[] ih,
                     boolean isSeed)
```
    Announce to ourselves. Non-blocking.
    Specified by:
    announce in interface DHT
    Parameters:
    ih - the Info Hash (torrent)
    isSeed - true if seed, false if leech
  - announce
```
public void announce(byte[] ih,
                     byte[] peerHash,
                     boolean isSeed)
```
    Announce somebody else we know about to ourselves. Non-blocking.
    Specified by:
    announce in interface DHT
    Parameters:
    ih - the Info Hash (torrent)
    peerHash - the peer's Hash
    isSeed - true if seed, false if leech
  - announce
```
public int announce(byte[] ih,
                    int max,
                    long maxWait,
                    boolean isSeed)
```
    Not recommended - use getPeersAndAnnounce().
    Announce to the closest peers in the local DHT. This is NOT iterative - call getPeers() first to get the closest peers into the local DHT. Blocking unless maxWait <= 0 Caller should run in a thread. This also automatically announces ourself to our local tracker. For best results do a getPeersAndAnnounce() instead, as this announces to the closest in the kbuckets, it does NOT sort through the known nodes hashmap.
    Specified by:
    announce in interface DHT
    Parameters:
    ih - the Info Hash (torrent)
    max - maximum number of peers to announce to
    maxWait - the maximum total time to wait (ms) or 0 to do all in parallel and return
    isSeed - true if seed, false if leech
    Returns:
    the number of successful announces, not counting ourselves.
  - clear
```
public void clear()
```
    Clears the tracker and DHT data. Call after saving DHT data to disk.
  - disconnected
```
public void disconnected(I2PSession session)
```
    Handle a session disconnect.
    Specified by:
    disconnected in interface I2PSessionListener
    Specified by:
    disconnected in interface I2PSessionMuxedListener
    Parameters:
    session - the session
  - errorOccurred
```
public void errorOccurred(I2PSession session,
                          String message,
                          Throwable error)
```
    Handle a session error.
    Specified by:
    errorOccurred in interface I2PSessionListener
    Specified by:
    errorOccurred in interface I2PSessionMuxedListener
    Parameters:
    session - the session
    message - the error message
    error - the error
  - findClosest
```
public List<NodeInfo> findClosest(byte[] ih,
                                  int max)
```
    Local lookup only
    Parameters:
    ih - a 20-byte info hash
    max - max to return
    Returns:
    list or empty list (never null)
  - getPeersAndAnnounce
```
public Collection<Hash> getPeersAndAnnounce(byte[] ih,
                                            int max,
                                            long maxWait,
                                            int annMax,
                                            long annMaxWait,
                                            boolean isSeed,
                                            boolean noSeeds)
```
    Find peers for a torrent, announcing to the closest annMax nodes found. This is an iterative lookup in the DHT. Blocking! Caller should run in a thread.
    Specified by:
    getPeersAndAnnounce in interface DHT
    Parameters:
    ih - the Info Hash (torrent)
    max - maximum number of peers to return
    maxWait - the maximum time to wait (ms) must be > 0
    annMax - the number of peers to announce to
    annMaxWait - the maximum total time to wait for announces, may be 0 to return immediately without waiting for acks
    isSeed - true if seed, false if leech
    noSeeds - true if we do not want seeds in the result
    Returns:
    possibly empty (never null)
  - getPort
```
public int getPort()
```
    The UDP query port.
    Specified by:
    getPort in interface DHT
    Returns:
    The UDP query port
  - getRPort
```
public int getRPort()
```
    The UDP response port.
    Specified by:
    getRPort in interface DHT
    Returns:
    The UDP response port
  - heardAbout
```
NodeInfo heardAbout(NodeInfo nInfo)
```
    Called for bootstrap or for all nodes in a receiveNodes reply. Package private for PersistDHT.
    Returns:
    non-null nodeInfo from DB if present, otherwise the nInfo parameter is returned
  - messageAvailable
```
public void messageAvailable(I2PSession session,
                             int msgId,
                             long size)
```
    For non-muxed.
    Specified by:
    messageAvailable in interface I2PSessionListener
    Specified by:
    messageAvailable in interface I2PSessionMuxedListener
    Parameters:
    session - session to notify
    msgId - message number available
    size - size of the message - why it's a long and not an int is a mystery
  - messageAvailable
```
public void messageAvailable(I2PSession session,
                             int msgId,
                             long size,
                             int proto,
                             int fromPort,
                             int toPort)
```
    Instruct the client that the given session has received a message
    Will be called only if you register via addMuxedSessionListener(). Will be called only for the proto(s) and toPort(s) you register for.
    Specified by:
    messageAvailable in interface I2PSessionMuxedListener
    Parameters:
    session - session to notify
    msgId - message number available
    size - size of the message - why it's a long and not an int is a mystery
    proto - 1-254 or 0 for unspecified
    fromPort - 1-65535 or 0 for unspecified
    toPort - 1-65535 or 0 for unspecified
  - ping
```
public void ping(Destination dest,
                 int port)
```
    Ping. We don't have a NID yet so the node is presumed to be absent from our DHT. Non-blocking, does not wait for pong. If and when the pong is received the node will be inserted in our DHT.
    Specified by:
    ping in interface DHT
    Parameters:
    dest - the destination to ping
    port - the UDP port to ping
  - removeSelf
```
static List<NodeInfo> removeSelf(List<NodeInfo> nodes,
                                 NodeInfo self)
```
    Remove any entries equal to ourselves from a list of candidate nodes. Peers may echo our own node entry back to us (we include our NID in every query), and we must never query, respond to, or announce to ourselves. Near-misses (same hash with a different NID or port) are kept; they are distinct nodes and only the exact self entry is dropped here.
    Parameters:
    nodes - candidate nodes, not modified
    self - our own node info
    Returns:
    a list without any entry equal to self, possibly empty, never null
  - removeServedTorrent
```
public void removeServedTorrent(InfoHash ih)
```
    Stop serving tracker queries for the given infohash. Called when a torrent is removed from a pooled destination.
    Parameters:
    ih - the infohash to stop serving
  - renderStatusHTML
```
public String renderStatusHTML()
```
    Debug info, HTML formatted.
    Specified by:
    renderStatusHTML in interface DHT
    Returns:
    HTML string with DHT status information
  - reportAbuse
```
public void reportAbuse(I2PSession session,
                        int severity)
```
    Handle a reportAbuse message from the session.
    Specified by:
    reportAbuse in interface I2PSessionListener
    Specified by:
    reportAbuse in interface I2PSessionMuxedListener
    Parameters:
    session - the session
    severity - the abuse severity
  - setServeAll
```
public void setServeAll(boolean serveAll)
```
    Whether tracker queries are served for every infohash. Multi-dest mode passes false, keeping the main instance a routing-table-only node so probing the primary destination never reveals torrents hosted on per-torrent destinations.
    Parameters:
    serveAll - true to serve every infohash, false to serve none
  - size
```
public int size()
```
    Known nodes, not estimated total network size.
    Specified by:
    size in interface DHT
    Returns:
    the number of known nodes
  - start
```
public void start()
```
    Start the DHT. Loads the DHT from file. Can't be restarted after stopping.
  - stop
```
public void stop()
```
    Stop everything.
    Specified by:
    stop in interface DHT
  - unannounce
```
public void unannounce(byte[] ih)
```
    Remove reference to ourselves in the local tracker. Use when shutting down the torrent locally. Non-blocking.
    Specified by:
    unannounce in interface DHT
    Parameters:
    ih - the Info Hash (torrent)

Class KRPC

I2P-Specific Modifications:

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

_isRunning

_qPort

_rPort

_session

DHT_FILE_SUFFIX

FAKE_NID

SECURE_NID

Constructor Detail

KRPC

KRPC

Method Detail

addServedTorrent

announce

announce

announce

clear

disconnected

errorOccurred

findClosest

getPeersAndAnnounce

getPort

getRPort

heardAbout

messageAvailable

messageAvailable

ping

removeSelf

removeServedTorrent

renderStatusHTML

reportAbuse

setServeAll

size

start

stop

unannounce