mpetazzoni/ttorrent

Purpose and entry points

Ttorrent is a Maven multi-module, pure-Java BitTorrent implementation usable as an embedded client, embedded tracker, or torrent-metainfo tool. Standalone CLI entry points are:

• cli/src/main/java/com/turn/ttorrent/cli/ClientMain.java

• cli/src/main/java/com/turn/ttorrent/cli/TrackerMain.java

• cli/src/main/java/com/turn/ttorrent/cli/TorrentMain.java

The main library APIs are SimpleClient for download/seeding and Tracker for serving announces.

Module boundaries

common owns protocol-neutral torrent metadata, peer identity/value types, and BitTorrent/tracker wire models. bencoding is the serialization substrate. network supplies reusable nonblocking channel management. ttorrent-client composes these into a peer client; ttorrent-tracker implements tracker state and HTTP request handling.

• common/src/main/java/com/turn/ttorrent/common/TorrentParser.java

• bencoding/src/main/java/com/turn/ttorrent/bcodec/BDecoder.java

• network/src/main/java/com/turn/ttorrent/network/ConnectionManager.java

Metainfo creation and parsing

Torrent creation reads source files, divides them into pieces, calculates hashes (single- or multi-threaded), builds metadata, and bencodes it. Parsing performs the inverse to expose immutable torrent metadata for clients and trackers.

• common/src/main/java/com/turn/ttorrent/common/TorrentCreator.java

• common/src/main/java/com/turn/ttorrent/common/creation/MetadataBuilder.java

• common/src/main/java/com/turn/ttorrent/common/TorrentSerializer.java

Client orchestration and lifecycle

SimpleClient is the embedding façade. It loads torrent metadata, creates/manages active torrents, dispatches lifecycle events, and coordinates tracker discovery, peer sessions, storage, and completion/seeding state.

• ttorrent-client/src/main/java/com/turn/ttorrent/client/SimpleClient.java

• ttorrent-client/src/main/java/com/turn/ttorrent/client/TorrentManagerImpl.java

• ttorrent-client/src/main/java/com/turn/ttorrent/client/SharedTorrent.java

Tracker discovery and peer protocol

The client announces torrent status to HTTP or UDP tracker endpoints, consumes peer lists, then opens peer connections. Peer sessions exchange BitTorrent handshakes and messages; connection admission and session-state listeners form a boundary between generic NIO transport and torrent semantics.

• ttorrent-client/src/main/java/com/turn/ttorrent/client/announce/TrackerClientFactoryImpl.java

• ttorrent-client/src/main/java/com/turn/ttorrent/client/network/HandshakeReceiver.java

• common/src/main/java/com/turn/ttorrent/common/protocol/PeerMessage.java

Piece transfer, selection, and disk persistence

Peer messages drive piece availability and requests. Request strategies choose interesting pieces and end-game behavior; received blocks are assembled, validated against torrent hashes, and persisted to single-file or multi-file storage. Storage is a client-local filesystem boundary.

• ttorrent-client/src/main/java/com/turn/ttorrent/client/strategy/RequestStrategy.java

• ttorrent-client/src/main/java/com/turn/ttorrent/client/Piece.java

• ttorrent-client/src/main/java/com/turn/ttorrent/client/storage/FileCollectionStorage.java

Tracker service

The tracker accepts announce requests, resolves each info hash to a tracked torrent, records peers, expires stale peers, and returns compact peer lists. It can optionally admit previously unknown torrents. The service is stateful in process; no persistent datastore is represented in this tree.

• ttorrent-tracker/src/main/java/com/turn/ttorrent/tracker/Tracker.java

• ttorrent-tracker/src/main/java/com/turn/ttorrent/tracker/TorrentsRepository.java

• ttorrent-tracker/src/main/java/com/turn/ttorrent/tracker/TrackerRequestProcessor.java

Runtime and external interfaces

Runtime is Java with Maven reactor modules. External interfaces are local filesystem reads/writes, TCP peer connections through Java NIO selectors, and tracker HTTP/UDP protocols. The client supports UDP tracker announces; tracker protocol message models cover HTTP and UDP, while tracker service implementation is centered on request processing.

• network/src/main/java/com/turn/ttorrent/network/ConnectionWorker.java

• common/src/main/java/com/turn/ttorrent/common/protocol/http/HTTPAnnounceRequestMessage.java

• common/src/main/java/com/turn/ttorrent/common/protocol/udp/UDPAnnounceRequestMessage.java