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

All Known Implementing Classes:
NTCPTransport, TransportImpl, UDPTransport
```
public interface Transport
```
Core interface for I2P transport protocols. This interface defines the contract for all transport implementations that enable I2P routers to communicate with each other. Transports handle message sending, receiving, peer management, and network address configuration. Transport Types:
- NTCP - Stream-based TCP transport with encryption
- UDP - Datagram-based transport with reliability
- SSU - Sessionless UDP for introduction
Implementation Requirements:
- Implement all interface methods for proper functionality
- Handle both IPv4 and IPv6 addressing
- Support concurrent message sending and receiving
- Provide proper error handling and logging
- Integrate with TransportManager lifecycle
Plugin Development: To implement a new transport plugin:
1. Implement this interface and required base classes
2. Add transport to TransportManager.startListening()
3. Ensure proper configuration and discovery
4. Test with existing I2P network compatibility
Note: API is subject to change. Please contact the I2P development team if you're writing a new transport or transport plugin to ensure compatibility and guidance.

Nested Class Summary
Nested Classes
Modifier and Type Interface and Description
static class Transport.AddressSource
Source of transport address configuration.

Nested Classes
Modifier and Type	Interface and Description
`static class`	`Transport.AddressSource` Source of transport address configuration.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`TransportBid`	`bid(RouterInfo toAddress, int dataSize)` Request to send a message to the specified router.
`int`	`countActivePeers()` Number of active peers.
`int`	`countActiveSendPeers()` Number of active send peers.
`int`	`countPeers()` Number of peers.
`void`	`externalAddressReceived(Transport.AddressSource source, byte[] ip, int port)` Notify transport of an external address change event.
`void`	`externalAddressRemoved(Transport.AddressSource source, boolean ipv6)` Notify a transport of an external address change.
`void`	`forceDisconnect(Hash peer)` Force immediate disconnection from specified peer.
`void`	`forceDisconnect(Hash peer, String reason)` Forcefully disconnect from a peer with a reason for logging.
`void`	`forwardPortStatus(byte[] ip, int port, int externalPort, boolean success, String reason)` Notify a transport of the results of trying to forward a port.
`List<Long>`	`getClockSkews()` The list of clock skew measurements from peer communications.
`RouterAddress`	`getCurrentAddress(boolean ipv6)` The first currently listening address of specified IP version.
`List<RouterAddress>`	`getCurrentAddresses()` All addresses this transport is currently listening on.
`List<Hash>`	`getEstablished()` The list of peers this transport has established connections with.
`TransportUtil.IPv6Config`	`getIPv6Config()` The current IPv6 configuration.
`List<String>`	`getMostRecentErrorMessages()` The most recent error messages.
`int[]`	`getPeerCounts()` Detailed peer count statistics by IP version and direction.
`CommSystemFacade.Status`	`getReachabilityStatus()` The current reachability status of this transport.
`int`	`getRequestedPort()` The internal port that the transport wants forwarded via UPnP.
`String`	`getStyle()` The unique style identifier for this transport.
`boolean`	`hasCurrentAddress()` Do we have any current address?
`boolean`	`haveCapacity()` Whether capacity is available for a message.
`boolean`	`haveCapacity(int pct)` Whether capacity is available for the given percentage.
`boolean`	`isBacklogged(Hash peer)` Whether the given peer is backlogged.
`boolean`	`isConnecting(Hash peer)` Check if a connection attempt is in progress for the given peer.
`boolean`	`isEstablished(Hash peer)` Whether the given peer is established.
`boolean`	`isIPv4Firewalled()` Whether force-firewalled for IPv4.
`boolean`	`isIPv6Firewalled()` Whether force-firewalled for IPv6.
`boolean`	`isUnreachable(Hash peer)` Whether the given peer is unreachable.
`void`	`mayDisconnect(Hash peer)` Suggest that transport may disconnect from specified peer.
`void`	`renderStatusHTML(Writer out, String urlBase, int sortFlags)` Render the transport status HTML to the given writer.
`void`	`send(OutNetMessage msg)` Asynchronously send a message to the specified peer.
`void`	`setListener(TransportEventListener listener)` The event listener for transport-related notifications.
`void`	`startListening()` Start accepting connections.
`void`	`stopListening()` Stop accepting connections.
`List<RouterAddress>`	`updateAddress()` Request transport to update its addresses based on current conditions.
`boolean`	`wasUnreachable(Hash peer)` Check if peer was unreachable on last outbound attempt.

- Method Detail
  - bid
```
TransportBid bid(RouterInfo toAddress,
                 int dataSize)
```
    Request to send a message to the specified router. This method allows the transport to evaluate whether it can and wants to send a message to the target router. The transport may decline based on current load, peer reputation, or transport-specific constraints.
    Parameters:
    toAddress - the target router's contact information
    dataSize - size of message payload, assumes full 16-byte header, transports should adjust as necessary for their overhead
    Returns:
    a TransportBid containing send details, or null if unwilling to send
  - countActivePeers
```
int countActivePeers()
```
    Number of active peers.
    Returns:
    active peer count
  - countActiveSendPeers
```
int countActiveSendPeers()
```
    Number of active send peers.
    Returns:
    active send peer count
  - countPeers
```
int countPeers()
```
    Number of peers.
    Returns:
    peer count
  - externalAddressReceived
```
void externalAddressReceived(Transport.AddressSource source,
                             byte[] ip,
                             int port)
```
    Notify transport of an external address change event. This method informs the transport that its external address has changed due to various sources like UPnP discovery, interface changes, or configuration updates. The transport should evaluate whether to accept this change based on the source and current state. Call Conditions:
    - Should NOT be called if IP didn't change from source's perspective
    - Should NOT be called for local/private addresses
    - May be called multiple times (once for IPv4, once for IPv6)
    - Transport should validate source before accepting
    Timing: Can be called before startListening() to set initial address, or after transport is already running.
    Parameters:
    source - the source
    ip - the new external IP address (IPv4 or IPv6), may be null to indicate IPv4 failure or port-only change
    port - the new external port number, 0 if unknown or unchanged
  - externalAddressRemoved
```
void externalAddressRemoved(Transport.AddressSource source,
                            boolean ipv6)
```
    Notify a transport of an external address change. This may be from a local interface, UPnP, a config change, etc. This should not be called if the ip didn't change (from that source's point of view), or is a local address. May be called multiple times for IPv4 or IPv6. The transport should also do its own checking on whether to accept notifications from this source. This can be called after the transport is running.
    Parameters:
    source - the source
    ipv6 - true for IPv6, false for IPv4
  - forceDisconnect
```
void forceDisconnect(Hash peer)
```
    Force immediate disconnection from specified peer. This method commands the transport to immediately terminate the connection to the specified peer. Unlike mayDisconnect(), this is not advisory - the transport must comply and disconnect as soon as possible. Use Cases:
    - Peer misbehavior or protocol violations
    - Router shutdown or transport shutdown
    - Network topology changes requiring disconnection
    - Administrative or manual disconnection requests
    Parameters:
    peer - hash of the peer to forcefully disconnect from
  - forceDisconnect
```
void forceDisconnect(Hash peer,
                     String reason)
```
    Forcefully disconnect from a peer with a reason for logging.
    Parameters:
    peer - hash of the peer to forcefully disconnect from
    reason - reason for disconnection (for logging)
  - forwardPortStatus
```
void forwardPortStatus(byte[] ip,
                       int port,
                       int externalPort,
                       boolean success,
                       String reason)
```
    Notify a transport of the results of trying to forward a port.
    Parameters:
    ip - may be null
    port - the internal port
    externalPort - the external port, which for now should always be the same as the internal port if the forwarding was successful.
  - getClockSkews
```
List<Long> getClockSkews()
```
    The list of clock skew measurements from peer communications. This method returns a list of measured clock differences (in milliseconds) between this router and various peers. Clock skew is important for network time synchronization and can affect message validation and routing. Historical Note: This method previously returned a Vector, now returns a List as of 0.9.46.
    Returns:
    list of clock skew measurements in milliseconds, may be empty if no measurements available
  - getCurrentAddress
```
RouterAddress getCurrentAddress(boolean ipv6)
```
    The first currently listening address of specified IP version. This method returns the first RouterAddress matching the requested IP version from the list of current addresses. This is useful when a specific address type is needed rather than all addresses. Note: An address without a host component is considered IPv4. This method replaces the older getCurrentAddress() method.
    Parameters:
    ipv6 - true to return IPv6 address only; false to return IPv4 address only
    Returns:
    first matching address for the specified IP version, or null if no such address exists
  - getCurrentAddresses
```
List<RouterAddress> getCurrentAddresses()
```
    All addresses this transport is currently listening on. This method returns the complete list of RouterAddress objects representing all network endpoints (both IPv4 and IPv6) that this transport is actively listening for connections on. This method replaces the older getCurrentAddress() method to support multiple addresses per transport.
    Returns:
    list of all currently listening addresses, never null
  - getEstablished
```
List<Hash> getEstablished()
```
    The list of peers this transport has established connections with. This method returns the current set of peer hashes that have successfully completed connection establishment. These are peers that the transport can actively communicate with. Note: The returned list may or may not be modifiable depending on implementation. Callers should not modify the returned list directly.
    Returns:
    list of established peer hashes, may be unmodifiable
  - getIPv6Config
```
TransportUtil.IPv6Config getIPv6Config()
```
    The current IPv6 configuration.
    Returns:
    IPv6 config
  - getMostRecentErrorMessages
```
List<String> getMostRecentErrorMessages()
```
    The most recent error messages.
    Returns:
    recent error messages
  - getPeerCounts
```
int[] getPeerCounts()
```
    Detailed peer count statistics by IP version and direction. This method returns an array containing peer counts broken down by IP version and connection direction. This provides detailed visibility into transport usage patterns and network composition. Array Format:
    - Version 1 (8 bytes): IPv4 inbound/outbound counts
    - Version 2 (8 bytes): IPv4 inbound/outbound, IPv6 inbound/outbound counts
    Returns:
    8-byte array with peer counts: version 1: [ipv4_in, ipv4_out, ipv6_in, ipv6_out, 0, 0, 0, 0] version 2: [ipv4_in, ipv4_out, ipv6_in, ipv6_out, 0, 0, 0, 0]
  - getReachabilityStatus
```
CommSystemFacade.Status getReachabilityStatus()
```
    The current reachability status of this transport. This method returns the transport's ability to establish and maintain connections with other peers. The status indicates whether the transport can successfully communicate through firewalls, NAT, and network restrictions. Historical Note: This method previously returned a short value, now returns a Status enum as of 0.9.20.
    Returns:
    current reachability status indicating transport's network accessibility
  - getRequestedPort
```
int getRequestedPort()
```
    The internal port that the transport wants forwarded via UPnP. This method returns the preferred internal port that the transport would like to have mapped to an external port through UPnP port forwarding. This is different from the actual listening port because UPnP may map a different external port. Note: This cannot be determined from getCurrentAddress() because:
    - Transport must open the port before publishing address
    - UPnP may map different external port
    - External port is what gets advertised, not internal
    Returns:
    preferred internal port for UPnP forwarding, -1 for no preference, or 0 for any port
  - getStyle
```
String getStyle()
```
    The unique style identifier for this transport. This method returns a string that uniquely identifies the transport type (e.g., "NTCP", "UDP", "SSU"). This is used for configuration, logging, and transport selection.
    Returns:
    unique transport style identifier
  - hasCurrentAddress
```
boolean hasCurrentAddress()
```
    Do we have any current address?
    Returns:
    whether current address is present
  - haveCapacity
```
boolean haveCapacity()
```
    Whether capacity is available for a message.
    Returns:
    true if capacity available
  - haveCapacity
```
boolean haveCapacity(int pct)
```
    Whether capacity is available for the given percentage.
    Parameters:
    pct - percent 0-100
    Returns:
    true if capacity available
  - isBacklogged
```
boolean isBacklogged(Hash peer)
```
    Whether the given peer is backlogged.
    Parameters:
    peer - peer hash
    Returns:
    true if backlogged
  - isConnecting
```
boolean isConnecting(Hash peer)
```
    Check if a connection attempt is in progress for the given peer. This method returns true when the transport has accepted a message for this peer and initiated a connection handshake, but the handshake has not yet completed. Unlike isEstablished(), which only returns true for fully-connected peers, this method detects connections that are still being set up. Used by the tunnel build system to distinguish between peers that are genuinely unreachable vs. peers that just need more time for the initial NTCP2/SSU2 handshake.
    Parameters:
    peer - hash of the peer to check
    Returns:
    true if a connection attempt is in progress
  - isEstablished
```
boolean isEstablished(Hash peer)
```
    Whether the given peer is established.
    Parameters:
    peer - peer hash
    Returns:
    true if established
  - isIPv4Firewalled
```
boolean isIPv4Firewalled()
```
    Whether force-firewalled for IPv4.
    Returns:
    true if force-firewalled for IPv4
  - isIPv6Firewalled
```
boolean isIPv6Firewalled()
```
    Whether force-firewalled for IPv6.
    Returns:
    true if force-firewalled for IPv6
  - isUnreachable
```
boolean isUnreachable(Hash peer)
```
    Whether the given peer is unreachable.
    Parameters:
    peer - peer hash
    Returns:
    true if unreachable
  - mayDisconnect
```
void mayDisconnect(Hash peer)
```
    Suggest that transport may disconnect from specified peer. This method provides an advisory recommendation that the transport should consider disconnecting from the specified peer. The transport may choose to ignore this suggestion based on its own criteria and current state. Advisory Nature:
    - Transport is not required to disconnect
    - Used for peer management and load balancing
    - May be called by router or other components
    - Transport should evaluate based on its own state
    Parameters:
    peer - hash of the peer that may be disconnected
  - renderStatusHTML
```
void renderStatusHTML(Writer out,
                      String urlBase,
                      int sortFlags)
               throws IOException
```
    Render the transport status HTML to the given writer.
    Parameters:
    out - writer
    urlBase - base URL
    sortFlags - flags
    Throws:
    IOException
  - send
```
void send(OutNetMessage msg)
```
    Asynchronously send a message to the specified peer. This method handles the actual message transmission. If the send operation succeeds, it queues up any follow-up jobs defined in msg.getOnSendJob() and registers them with OutboundMessageRegistry (if the message has a reply selector). If the send fails, it queues up any failure handling jobs from msg.getOnFailedSendJob(). The method should return immediately and perform the actual sending asynchronously to avoid blocking the calling thread.
    Parameters:
    msg - the message to send, containing destination, payload, and callbacks
  - setListener
```
void setListener(TransportEventListener listener)
```
    The event listener for transport-related notifications. The listener will be notified of various transport events such as message availability, peer status changes, and transport state changes. Only one listener can be active at a time.
    Parameters:
    listener - the event listener to receive transport notifications
  - startListening
```
void startListening()
```
    Start accepting connections.
  - stopListening
```
void stopListening()
```
    Stop accepting connections.
  - updateAddress
```
List<RouterAddress> updateAddress()
```
    Request transport to update its addresses based on current conditions. This method asks the transport to re-evaluate its current network configuration and update its advertised addresses accordingly. The transport should consider:
    - Current network interface status
    - UPnP discovery results
    - Configuration file settings
    - Firewall and NAT constraints
    Returns:
    updated list of all addresses the transport is now advertising, never null
  - wasUnreachable
```
boolean wasUnreachable(Hash peer)
```
    Check if peer was unreachable on last outbound attempt. This method determines whether the last attempt to contact the specified peer failed due to reachability issues. This is specifically for outbound connection attempts only. Important Notes:
    - This is NOT reset if the peer contacts us successfully
    - Status persists until peer is contacted or expires
    - Used for connection retry decisions
    - Different from isUnreachable() which checks current state
    Parameters:
    peer - hash of the peer to check reachability for
    Returns:
    true if peer was unreachable on last outbound attempt

Interface Transport

Nested Class Summary

Method Summary

Method Detail

bid

countActivePeers

countActiveSendPeers

countPeers

externalAddressReceived

externalAddressRemoved

forceDisconnect

forceDisconnect

forwardPortStatus

getClockSkews

getCurrentAddress

getCurrentAddresses

getEstablished

getIPv6Config

getMostRecentErrorMessages

getPeerCounts

getReachabilityStatus

getRequestedPort

getStyle

hasCurrentAddress

haveCapacity

haveCapacity

isBacklogged

isConnecting

isEstablished

isIPv4Firewalled

isIPv6Firewalled

isUnreachable

mayDisconnect

renderStatusHTML

send

setListener

startListening

stopListening

updateAddress

wasUnreachable