Streaming Protocol

Overview

The I2P Streaming Library provides reliable, in-order, authenticated transport over I2P’s message layer, similar to TCP over IP.
It sits above the I2CP protocol and is used by nearly all interactive I2P applications, including HTTP proxies, IRC, BitTorrent, and email.

Core Characteristics

• One-phase connection setup using SYN, ACK, and FIN flags that can be bundled with payload data to reduce round-trips.
• Sliding-window congestion control, with slow start and congestion avoidance tuned for I2P’s high-latency environment.
• Packet compression (default 4KB compressed segments) balancing retransmission cost and fragmentation latency.
• Fully authenticated, encrypted, and reliable channel abstraction between I2P destinations.

This design enables small HTTP requests and responses to complete in a single round-trip.
A SYN packet may carry the request payload, while the responder’s SYN/ACK/FIN may contain the full response body.

API Basics

The Java streaming API mirrors standard Java socket programming:

I2PSocketManager mgr = I2PSocketManagerFactory.createManager(host, port, options);
I2PSocket socket       = mgr.connect(destination);
I2PServerSocket server = mgr.getServerSocket();

• I2PSocketManagerFactory negotiates or reuses a router session via I2CP.
• If no key is provided, a new destination is automatically generated.
• Developers can pass I2CP options (e.g., tunnel lengths, encryption types, or connection settings) through the options map.
• I2PSocket and I2PServerSocket mirror standard Java Socket interfaces, making migration straightforward.

Full Javadocs are available from the I2P router console or here.

Configuration and Tuning

You can pass configuration properties when creating a socket manager via:

I2PSocketManagerFactory.createManager(host, port, properties);

Key Options

Behavior by Workload

Newer features since version 0.9.4 include reject log suppression, DSA list support (0.9.21), and mandatory protocol enforcement (0.9.36).
Routers since 2.10.0 include post-quantum hybrid encryption (ML-KEM + X25519) at the transport layer.

Protocol Details

Each stream is identified by a Stream ID. Packets carry control flags similar to TCP: SYNCHRONIZE, ACK, FIN, and RESET.
Packets may contain both data and control flags simultaneously, improving efficiency for short-lived connections.

Connection Lifecycle

1. SYN sent — initiator includes optional data.
2. SYN/ACK response — responder includes optional data.
3. ACK finalization — establishes reliability and session state.
4. FIN/RESET — used for orderly closure or abrupt termination.

Fragmentation and Reordering

Because I2P tunnels introduce latency and message reordering, the library buffers packets from unknown or early-arriving streams.
Buffered messages are stored until synchronization completes, ensuring complete, in-order delivery.

Protocol Enforcement

The option i2p.streaming.enforceProtocol=true (default since 0.9.36) ensures connections use the correct I2CP protocol number, preventing conflicts between multiple subsystems sharing one destination.

Interoperability and Best Practices

The streaming protocol coexists with the Datagram API, giving developers the choice between connection-oriented and connectionless transports.

Shared Clients

Applications can reuse existing tunnels by running as shared clients, allowing multiple services to share the same destination.
While this reduces overhead, it increases cross-service correlation risk—use with care.

Congestion Control

• The streaming layer continuously adapts to network latency and throughput via RTT-based feedback.
• Applications perform best when routers are contributing peers (participating tunnels enabled).
• TCP-like congestion control mechanisms prevent overloading slow peers and help balance bandwidth use across tunnels.

Latency Considerations

Because I2P adds several hundred milliseconds of base latency, applications should minimize round-trips.
Bundle data with connection setup where possible (e.g., HTTP requests in SYN).
Avoid designs relying on many small sequential exchanges.

Testing and Compatibility

• Always test against both Java I2P and i2pd to ensure full compatibility.
• Although the protocol is standardized, minor implementation differences may exist.
• Handle older routers gracefully—many peers still run pre-2.0 versions.
• Monitor connection stats using I2PSocket.getOptions() and getSession() to read RTT and retransmission metrics.

Performance depends heavily on tunnel configuration:

• Short tunnels (1–2 hops) → lower latency, reduced anonymity.
• Long tunnels (3+ hops) → higher anonymity, increased RTT.

Key Improvements (2.0.0–2.10.0)

Summary

The I2P Streaming Library is the backbone of all reliable communication within I2P.
It ensures in-order, authenticated, encrypted message delivery and provides a near drop-in replacement for TCP in anonymous environments.

To achieve optimal performance:

• Minimize round-trips with SYN+payload bundling.
• Tune window and timeout parameters for your workload.
• Favor shorter tunnels for latency-sensitive applications.
• Use congestion-friendly designs to avoid overloading peers.