Package-level declarations

Thrown by PeerConnection.receiveLoop when a peer announces a frame longer than an addressable ByteArray (>Int.MAX_VALUE). Such a frame is malformed or hostile. It is distinct from ProtocolException so callers can log the offending length.

The minimal byte-duplex a PeerConnection needs: read exactly N bytes, write a frame. This is the seam between the protocol state machine and the concrete socket. libtorrent keeps the equivalent inside peer_connection's m_recv_buffer and send_buffer code, which couples the protocol to Boost.Asio. Separating it lets you test PeerConnection against an in-memory duplex with no live sockets.

Thrown by PeerConnection.performHandshake when the peer is not speaking BitTorrent or offers the wrong info-hash. libtorrent turns the same conditions into an errors::invalid_info_hash disconnect.

The validated outcome of PeerConnection.performHandshake: the remote peer's id and its 8 reserved capability bytes, with the three feature flags BitTorrent negotiates through them decoded for convenience. Mirrors what libtorrent stashes in set_pid() + m_reserved_bits after a successful handshake.

One HTTP byte range to fetch from a web seed: the fully-qualified url plus an inclusive [firstByte, lastByte] interval, ready to drop straight into a Range: bytes=$firstByte-$lastByte header.

Fetch a torrent's metadata (the info dict) from a peer over BEP-9 (ut_metadata), negotiated via the BEP-10 extension handshake. This is how a download starts from a magnet link, where we have only the info-hash. Port of libtorrent's ut_metadata plugin driving metadata_transfer.

The MSE/PE (Message Stream Encryption / Protocol Encryption) handshake. This is the live automaton libtorrent runs in bt_peer_connection.cpp (write_pe1_2_dhkey, write_pe3_sync, write_pe4_sync, read_pe_*). It performs the Diffie-Hellman exchange, the sync-hash and VC obfuscation steps, and crypto negotiation, then returns a transport (MseByteStream when RC4 is selected, the raw stream when plaintext is) over which the normal BitTorrent handshake proceeds.

A ByteStream that transparently RC4-encrypts writes and decrypts reads for an established MSE/PE connection. This is the live counterpart of libtorrent's rc4_handler sitting in bt_peer_connection's send/recv path. RC4 is a byte-stream cipher, so the chunk boundaries a PeerConnection happens to read/write in are irrelevant; only the total byte order matters, and the per-direction locks keep encrypt-order == wire-order.

Raised when the MSE/PE handshake fails (bad VC, unknown torrent, sync not found, …).

One BitTorrent peer session over a single byte-duplex. This is the coroutine port of libtorrent's peer_connection and bt_peer_connection (src/peer_connection.cpp, src/bt_peer_connection.cpp). It drives the wire protocol for one peer.

The per-connection choke/interest state: the Kotlin counterpart of the four m_choked / m_peer_choked / m_interesting / m_peer_interested flag bits in libtorrent's peer_connection (peer_connection.hpp), plus the peer's piece availability (m_have_piece).

A ByteStream that serves prefix bytes first, then delegates to raw. Lets the engine peek the opening bytes of an inbound connection (to tell plaintext from MSE) and then hand them back to the chosen handler as if never consumed.

Thrown by PeerConnection.receiveLoop when a peer violates the wire protocol (for example a wrong-sized bitfield, or an oversized frame). These match the family of peer_error disconnects in libtorrent. The connection must be closed.

A BEP-19 web seed (url-list, "GetRight" style): a plain HTTP(S) server that hosts the torrent's files so a client can download them with ordinary ranged GETs instead of the BitTorrent wire protocol.

Adapt a proven TcpConnection to the ByteStream seam. The connection itself is untouched; this is a thin forwarding wrapper so production code feeds a real socket into PeerConnection while tests feed a fake.