Cratetorrent

https://docs.rs/cratetorrent
Admin
Cratetorrent provides comprehensive documentation for a Rust-based library or application, likely...
Tokens:873,506
Snippets:6,353
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Spawn and run a cratetorrent download

Source: https://docs.rs/cratetorrent/latest/cratetorrent/index.html?search=

This example demonstrates how to spawn the cratetorrent engine, parse metainfo, start a download, and listen for alerts until the download is complete. Ensure the metainfo file exists and the download directory is accessible.

```rust
use cratetorrent::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // spawn the engine with a default config
    let conf = Conf::new("/tmp/downloads");
    let (engine, mut alert_rx) = engine::spawn(conf)?;

    // parse torrent metainfo and start the download (use tokio::fs)
    let metainfo = std::fs::read("/tmp/imaginary.torrent")?;
    let metainfo = Metainfo::from_bytes(&metainfo)?;
    let torrent_id = engine.create_torrent(TorrentParams {
        metainfo,
        // tell the engine to assign a randomly chosen free port
        listen_addr: None,
        mode: Mode::Download { seeds: Vec::new() },
        conf: None,
    })?;

    // listen to alerts from the engine
    while let Some(alert) = alert_rx.next().await {
        match alert {
            Alert::TorrentStats { id, stats } => {
                println!("{}: {:#?}", id, stats);
            }
            Alert::TorrentComplete(id) => {
                println!("{} complete, shutting down", id);
                break;
            }
            Alert::Error(e) => {
                // this is where you'd handle recoverable errors
                println!("Engine error: {}", e);
            }
            _ => (),
        }
    }

    // Don't forget to call shutdown on the engine to gracefully stop all
    // entities in the engine. This will wait for announcing the client's
    // leave to all trackers of torrent, finish pending disk and network IO,
    // as well as wait for peer connections to cleanly shut down.
    engine.shutdown().await?;

    Ok(())
}

```

--------------------------------

### Full Download Example

Source: https://docs.rs/cratetorrent/latest/cratetorrent?search=

Demonstrates how to spawn the cratetorrent engine, parse torrent metainfo, initiate a download, and listen for torrent completion alerts. This example requires a tokio runtime.

```Rust
use cratetorrent::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // spawn the engine with a default config
    let conf = Conf::new("/tmp/downloads");
    let (engine, mut alert_rx) = engine::spawn(conf)?;

    // parse torrent metainfo and start the download (use tokio::fs)
    let metainfo = std::fs::read("/tmp/imaginary.torrent")?;
    let metainfo = Metainfo::from_bytes(&metainfo)?;
    let torrent_id = engine.create_torrent(TorrentParams {
        metainfo,
        // tell the engine to assign a randomly chosen free port
        listen_addr: None,
        mode: Mode::Download { seeds: Vec::new() },
        conf: None,
    })?;

    // listen to alerts from the engine
    while let Some(alert) = alert_rx.next().await {
        match alert {
            Alert::TorrentStats { id, stats } => {
                println!(ירת{}: {:#?}", id, stats);
            }
            Alert::TorrentComplete(id) => {
                println!("{} complete, shutting down", id);
                break;
            }
            Alert::Error(e) => {
                // this is where you'd handle recoverable errors
                println!("Engine error: {}", e);
            }
            _ => (),
        }
    }

    // Don't forget to call shutdown on the engine to gracefully stop all
    // entities in the engine. This will wait for announcing the client's
    // leave to all trackers of torrent, finish pending disk and network IO,
    // as well as wait for peer connections to cleanly shut down.
    engine.shutdown().await?;

    Ok(())
}
```

--------------------------------

### Starting Outbound Peer Session

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/peer.rs.html?search=u32+-%3E+bool

Initiates an outbound connection to a peer, performs a handshake, and starts the session. This method handles the initial connection and setup for communicating with a peer.

```rust
    /// Starts an outbound peer session.
    ///
    /// This method tries to connect to the peer at the address given in the
    /// constructor, send a handshake, and start the session.
    /// It returns if the connection is closed or an error occurs.
    pub async fn start_outbound(&mut self) -> Result<()> {
        log::info!(target: &self.ctx.log_target, "Starting outbound session");

        // establish the TCP connection
        log::info!(target: &self.ctx.log_target, "Connecting to peer");
        self.ctx.set_connection_state(ConnectionState::Connecting);
        let socket = TcpStream::connect(self.peer.addr).await?;
        log::info!(target: &self.ctx.log_target, "Connected to peer");

        let socket = Framed::new(socket, HandshakeCodec);
        self.start(socket, Direction::Outbound).await
    }

```

--------------------------------

### Example Search: u32 to bool

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/lib.rs.html?search=

Demonstrates a search example for type conversions from 'u32' to 'bool'.

```text
u32 -> bool
```

--------------------------------

### Full Torrent Download Example

Source: https://docs.rs/cratetorrent

This example demonstrates how to set up the cratetorrent engine, parse torrent metainfo, initiate a download, and listen for alerts until the download is complete. It requires a tokio runtime and a local .torrent file.

```rust
use cratetorrent::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // spawn the engine with a default config
    let conf = Conf::new("/tmp/downloads");
    let (engine, mut alert_rx) = engine::spawn(conf)?;

    // parse torrent metainfo and start the download (use tokio::fs)
    let metainfo = std::fs::read("/tmp/imaginary.torrent")?;
    let metainfo = Metainfo::from_bytes(&metainfo)?;
    let torrent_id = engine.create_torrent(TorrentParams {
        metainfo,
        // tell the engine to assign a randomly chosen free port
        listen_addr: None,
        mode: Mode::Download { seeds: Vec::new() },
        conf: None,
    })?;

    // listen to alerts from the engine
    while let Some(alert) = alert_rx.next().await {
        match alert {
            Alert::TorrentStats { id, stats } => {
                println!("{}: {:#?}", id, stats);
            }
            Alert::TorrentComplete(id) => {
                println!("{} complete, shutting down", id);
                break;
            }
            Alert::Error(e) => {
                // this is where you'd handle recoverable errors
                println!("Engine error: {}", e);
            }
            _ => (),
        }
    }

    // Don't forget to call shutdown on the engine to gracefully stop all
    // entities in the engine. This will wait for announcing the client's
    // leave to all trackers of torrent, finish pending disk and network IO, 
    // as well as wait for peer connections to cleanly shut down.
    engine.shutdown().await?;

    Ok(())
}
```

--------------------------------

### Example Search: std::vec

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/lib.rs.html?search=

Demonstrates a basic search example for 'std::vec'.

```text
std::vec
```

--------------------------------

### Spawn and run cratetorrent engine

Source: https://docs.rs/cratetorrent/latest/cratetorrent/index.html

Spawns the cratetorrent engine within a tokio context and listens for alerts. This example demonstrates starting a download, handling torrent completion, and engine errors.

```rust
use cratetorrent::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // spawn the engine with a default config
    let conf = Conf::new("/tmp/downloads");
    let (engine, mut alert_rx) = engine::spawn(conf)?;

    // parse torrent metainfo and start the download (use tokio::fs)
    let metainfo = std::fs::read("/tmp/imaginary.torrent")?;
    let metainfo = Metainfo::from_bytes(&metainfo)?;
    let torrent_id = engine.create_torrent(TorrentParams {
        metainfo,
        // tell the engine to assign a randomly chosen free port
        listen_addr: None,
        mode: Mode::Download { seeds: Vec::new() },
        conf: None,
    })?;

    // listen to alerts from the engine
    while let Some(alert) = alert_rx.next().await {
        match alert {
            Alert::TorrentStats { id, stats } => {
                println!("{}: {:#?}", id, stats);
            }
            Alert::TorrentComplete(id) => {
                println!("{} complete, shutting down", id);
                break;
            }
            Alert::Error(e) => {
                // this is where you'd handle recoverable errors
                println!("Engine error: {}", e);
            }
            _ => (),
        }
    }

    // Don't forget to call shutdown on the engine to gracefully stop all
    // entities in the engine. This will wait for announcing the client's
    // leave to all trackers of torrent, finish pending disk and network IO,
    // as well as wait for peer connections to cleanly shut down.
    engine.shutdown().await?;

    Ok(())
}
```

--------------------------------

### Common Session Setup Logic

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/peer.rs.html?search=

A helper method for common session setup steps, handling handshakes for both inbound and outbound connections, and switching to the peer message codec.

```rust
async fn start(
        &mut self,
        mut socket: Framed<TcpStream, HandshakeCodec>,
        direction: Direction,
    ) -> Result<()> {
        self.ctx.set_connection_state(ConnectionState::Handshaking);

        // if this is an outbound connection, we have to send the first
        // handshake
        if direction == Direction::Outbound {
            let handshake =
                Handshake::new(self.torrent.info_hash, self.torrent.client_id);
            log::info!(target: &self.ctx.log_target, "Sending handshake");
            self.ctx.counters.protocol.up += handshake.len();
            socket.send(handshake).await?;
        }

        // receive peer's handshake
        log::info!(target: &self.ctx.log_target, "Waiting for peer handshake");
        if let Some(peer_handshake) = socket.next().await {
            let peer_handshake = peer_handshake?;
            log::info!(target: &self.ctx.log_target, "Peer sent handshake");
            log::trace!(target: &self.ctx.log_target, "Peer handshake: {:?}", peer_handshake);
            // codec should only return handshake if the protocol string in it
            // is valid
            debug_assert_eq!(peer_handshake.prot, PROTOCOL_STRING.as_bytes());

            self.ctx.counters.protocol.down += peer_handshake.len();

            // verify that the advertised torrent info hash is the same as ours
            if peer_handshake.info_hash != self.torrent.info_hash {
                log::info!(target: &self.ctx.log_target, "Peer handshake invalid info hash");
                // abort session, info hash is invalid
                return Err(PeerError::InvalidInfoHash);
            }

            // set the peer's id
            self.peer.id = Some(peer_handshake.peer_id);

            // if this is an inbound connection, we reply with the handshake
            if direction == Direction::Inbound {
                let handshake = Handshake::new(
                    self.torrent.info_hash,
                    self.torrent.client_id,
                );
                log::info!(target: &self.ctx.log_target, "Sending handshake");
                self.ctx.counters.protocol.up += handshake.len();
                socket.send(handshake).await?;
            }

            // now that we have the handshake, we need to switch to the peer
            // message codec and save the socket in self (note that we need to
            // keep the buffer from the original codec as it may contain bytes
            // of any potential message the peer may have sent after the
            // handshake)
            let old_parts = socket.into_parts();
            let mut new_parts = FramedParts::new(old_parts.io, PeerCodec);
            // reuse buffers of previous codec
            new_parts.read_buf = old_parts.read_buf;
            new_parts.write_buf = old_parts.write_buf;
            let socket = Framed::from_parts(new_parts);

            // update torrent of connection
            self.torrent.cmd_tx.send(torrent::Command::PeerConnected {
                addr: self.peer.addr,
                id: peer_handshake.peer_id,
            })?;

            // enter the piece availability exchange state
            self.ctx
                .set_connection_state(ConnectionState::AvailabilityExchange);
            log::info!(target: &self.ctx.log_target, "Session state: {:?}", self.ctx.state.connection);

            // run the session
            if let Err(e) = self.run(socket).await {
                log::error(
                    target: &self.ctx.log_target,
                    "Session stopped due to an error: {}",
                    e
                );
                self.ctx.set_connection_state(ConnectionState::Disconnected);
                self.torrent.cmd_tx.send(torrent::Command::PeerState {
                    addr: self.peer.addr,
                    info: self.session_info(),
                })?;
                self.torrent.alert_tx.send(Alert::Error(Error::Peer {

```

--------------------------------

### Common Session Setup Logic

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/peer.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

A helper method for common session setup steps, including sending and receiving handshakes, verifying info hashes, and switching codecs.

```rust
async fn start(
        &mut self,
        mut socket: Framed<TcpStream, HandshakeCodec>,
        direction: Direction,
    ) -> Result<()> {
        self.ctx.set_connection_state(ConnectionState::Handshaking);

        // if this is an outbound connection, we have to send the first
        // handshake
        if direction == Direction::Outbound {
            let handshake = 
                Handshake::new(self.torrent.info_hash, self.torrent.client_id);
            log::info!(target: &self.ctx.log_target, "Sending handshake");
            self.ctx.counters.protocol.up += handshake.len();
            socket.send(handshake).await?;
        }

        // receive peer's handshake
        log::info!(target: &self.ctx.log_target, "Waiting for peer handshake");
        if let Some(peer_handshake) = socket.next().await {
            let peer_handshake = peer_handshake?;
            log::info!(target: &self.ctx.log_target, "Peer sent handshake");
            log::trace!(target: &self.ctx.log_target, "Peer handshake: {:?}", peer_handshake);
            // codec should only return handshake if the protocol string in it
            // is valid
            debug_assert_eq!(peer_handshake.prot, PROTOCOL_STRING.as_bytes());

            self.ctx.counters.protocol.down += peer_handshake.len();

            // verify that the advertised torrent info hash is the same as ours
            if peer_handshake.info_hash != self.torrent.info_hash {
                log::info!(target: &self.ctx.log_target, "Peer handshake invalid info hash");
                // abort session, info hash is invalid
                return Err(PeerError::InvalidInfoHash);
            }

            // set the peer's id
            self.peer.id = Some(peer_handshake.peer_id);

            // if this is an inbound connection, we reply with the handshake
            if direction == Direction::Inbound {
                let handshake = Handshake::new(
                    self.torrent.info_hash,
                    self.torrent.client_id,
                );
                log::info!(target: &self.ctx.log_target, "Sending handshake");
                self.ctx.counters.protocol.up += handshake.len();
                socket.send(handshake).await?;
            }

            // now that we have the handshake, we need to switch to the peer
            // message codec and save the socket in self (note that we need to
            // keep the buffer from the original codec as it may contain bytes
            // of any potential message the peer may have sent after the
            // handshake)
            let old_parts = socket.into_parts();
            let mut new_parts = FramedParts::new(old_parts.io, PeerCodec);
            // reuse buffers of previous codec
            new_parts.read_buf = old_parts.read_buf;
            new_parts.write_buf = old_parts.write_buf;
            let socket = Framed::from_parts(new_parts);

            // update torrent of connection
            self.torrent.cmd_tx.send(torrent::Command::PeerConnected {
                addr: self.peer.addr,
                id: peer_handshake.peer_id,
            })?;

            // enter the piece availability exchange state
            self.ctx
                .set_connection_state(ConnectionState::AvailabilityExchange);
            log::info!(target: &self.ctx.log_target, "Session state: {:?}", self.ctx.state.connection);

            // run the session
            if let Err(e) = self.run(socket).await {
                log::error!(
                    target: &self.ctx.log_target,
                    "Session stopped due to an error: {}",
                    e
                );
                self.ctx.set_connection_state(ConnectionState::Disconnected);
                self.torrent.cmd_tx.send(torrent::Command::PeerState {
                    addr: self.peer.addr,
                    info: self.session_info(),
                })?;
                self.torrent.alert_tx.send(Alert::Error(Error::Peer {

```

--------------------------------

### Common Session Setup Steps

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/peer.rs.html

A helper method for common session setup steps, including sending and receiving handshakes, validating peer information, and transitioning to the message exchange phase. It handles both outbound and inbound connection logic.

```rust
async fn start(
        &mut self,
        mut socket: Framed<TcpStream, HandshakeCodec>,
        direction: Direction,
    ) -> Result<()> {
        self.ctx.set_connection_state(ConnectionState::Handshaking);

        // if this is an outbound connection, we have to send the first
        // handshake
        if direction == Direction::Outbound {
            let handshake =
                Handshake::new(self.torrent.info_hash, self.torrent.client_id);
            log::info!(target: &self.ctx.log_target, "Sending handshake");
            self.ctx.counters.protocol.up += handshake.len();
            socket.send(handshake).await?;
        }

        // receive peer's handshake
        log::info!(target: &self.ctx.log_target, "Waiting for peer handshake");
        if let Some(peer_handshake) = socket.next().await {
            let peer_handshake = peer_handshake?;
            log::info!(target: &self.ctx.log_target, "Peer sent handshake");
            log::trace!(target: &self.ctx.log_target, "Peer handshake: {:?}", peer_handshake);
            // codec should only return handshake if the protocol string in it
            // is valid
            debug_assert_eq!(peer_handshake.prot, PROTOCOL_STRING.as_bytes());

            self.ctx.counters.protocol.down += peer_handshake.len();

            // verify that the advertised torrent info hash is the same as ours
            if peer_handshake.info_hash != self.torrent.info_hash {
                log::info!(target: &self.ctx.log_target, "Peer handshake invalid info hash");
                // abort session, info hash is invalid
                return Err(PeerError::InvalidInfoHash);
            }

            // set the peer's id
            self.peer.id = Some(peer_handshake.peer_id);

            // if this is an inbound connection, we reply with the handshake
            if direction == Direction::Inbound {
                let handshake = Handshake::new(
                    self.torrent.info_hash,
                    self.torrent.client_id,
                );
                log::info!(target: &self.ctx.log_target, "Sending handshake");
                self.ctx.counters.protocol.up += handshake.len();
                socket.send(handshake).await?;
            }

            // now that we have the handshake, we need to switch to the peer
            // message codec and save the socket in self (note that we need to
            // keep the buffer from the original codec as it may contain bytes
            // of any potential message the peer may have sent after the
            // handshake)
            let old_parts = socket.into_parts();
            let mut new_parts = FramedParts::new(old_parts.io, PeerCodec);
            // reuse buffers of previous codec
            new_parts.read_buf = old_parts.read_buf;
            new_parts.write_buf = old_parts.write_buf;
            let socket = Framed::from_parts(new_parts);

            // update torrent of connection
            self.torrent.cmd_tx.send(torrent::Command::PeerConnected {
                addr: self.peer.addr,
                id: peer_handshake.peer_id,
            })?;

            // enter the piece availability exchange state
            self.ctx
                .set_connection_state(ConnectionState::AvailabilityExchange);
            log::info!(target: &self.ctx.log_target, "Session state: {:?}", self.ctx.state.connection);

            // run the session
            if let Err(e) = self.run(socket).await {
                log::error!(
                    target: &self.ctx.log_target,
                    "Session stopped due to an error: {}",
                    e
                );
                self.ctx.set_connection_state(ConnectionState::Disconnected);
                self.torrent.cmd_tx.send(torrent::Command::PeerState {
                    addr: self.peer.addr,
                    info: self.session_info(),
                })?;
            }
            Ok(())
        } else {
            // peer disconnected before sending handshake
            self.ctx.set_connection_state(ConnectionState::Disconnected);
            Err(PeerError::Disconnected)
        }
    }
```

--------------------------------

### Example Search: Option<T> map

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/lib.rs.html?search=

Demonstrates a search example for mapping operations on 'Option<T>' with a function 'T -> U'.

```text
Option<T>, (T -> U) -> Option<U>
```

--------------------------------

### PeerSessionStats Search Examples

Source: https://docs.rs/cratetorrent/latest/cratetorrent/torrent/stats/struct.PeerSessionStats.html?search=

Provides examples of how to perform searches within PeerSessionStats. These examples demonstrate searching for specific types, type conversions, and using subscribers.

```APIDOC
## Search Examples

This section provides examples of search queries that can be performed.

### Example Searches

- `std::vec`
- `u32 -> bool`
- `Option<T>, (T -> U) -> Option<U>`
```

--------------------------------

### FileInfo Search Examples

Source: https://docs.rs/cratetorrent/latest/cratetorrent/storage_info/struct.FileInfo.html?search=

Provides examples of how to perform searches for file information.

```APIDOC
## Example Searches

### Search for a specific type
```
std::vec
```

### Search for type conversion
```
u32 -> bool
```

### Search for generic type conversion with Option
```
Option<T>, (T -> U) -> Option<U>
```
```

--------------------------------

### IoError Search Examples

Source: https://docs.rs/cratetorrent/latest/cratetorrent/peer/error/struct.IoError.html?search=

Examples of how to search for IoError types and related conversions within the CrateTorrent library.

```APIDOC
## Search Examples

This section provides examples of search queries that can be used to find specific types and conversions related to `IoError`.

### Example Searches

- `std::vec`
- `u32 -> bool`
- `Option<T>, (T -> U) -> Option<U>`
```

--------------------------------

### Prepare Session for Download

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/peer/state.rs.html?search=

Initializes the SessionContext for a download by setting interest, unchoking, and enabling slow start.

```rust
let mut s = SessionContext::default();

s.state.is_interested = true;
s.state.is_choked = false;

s.prepare_for_download();

assert!(s.target_request_queue_len > Some(0));
assert!(s.in_slow_start);
```

--------------------------------

### Start Torrent and Announce

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/torrent.rs.html?search=std%3A%3Avec

Initiates the torrent process by extending the available peers list, recording the start time, and announcing the torrent's status to trackers. It handles cases where the torrent is already seeded by sending an empty announce.

```rust
pub async fn start(&mut self, peers: &[SocketAddr]) -> Result<()> {
        log::info!("Starting torrent");

        self.available_peers.extend_from_slice(peers);

        // record the torrent starttime
        self.start_time = Some(Instant::now());

        // if the torrent is a seed, don't send the started event, just an
        // empty announce
        let tracker_event =
            if self.ctx.piece_picker.read().await.missing_piece_count() == 0 {
                None
            } else {
                Some(Event::Started)
            };
        if let Err(e) = self
            .announce_to_trackers(Instant::now(), tracker_event)
            .await
        {
            // this is a torrent error, not a tracker error, as that is handled
            // inside the function
            self.ctx
                .alert_tx
                .send(Alert::Error(Error::Torrent {
                    id: self.ctx.id,
                    error: e,
                }))
                .ok();
        }

        if let Err(e) = self.run().await {
            // send alert of torrent failure to user
            self.ctx
                .alert_tx
                .send(Alert::Error(Error::Torrent {
                    id: self.ctx.id,
                    error: e,
                }))
                .ok();
        }

        Ok(())
    }
```

--------------------------------

### Start a New Torrent

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/engine.rs.html

Initiates a new torrent by sending a command to the disk manager for storage allocation and then spawning a new task to start the torrent's operation. Handles potential errors during disk command sending.

```rust
self.disk_tx.send(disk::Command::NewTorrent {
            id,
            storage_info: storage_info.clone(),
            piece_hashes: params.metainfo.pieces,
            torrent_tx: torrent_tx.clone(),
        })?;

        let seeds = params.mode.seeds();
        let join_handle =
            task::spawn(async move { torrent.start(&seeds).await });

        self.torrents.insert(
            id,
            TorrentEntry {
                tx: torrent_tx,
                join_handle: Some(join_handle),
            },
        );

        Ok(())
    }
```

--------------------------------

### Using StreamExt::enumerate

Source: https://docs.rs/cratetorrent/latest/cratetorrent/prelude/trait.StreamExt.html?search=

Demonstrates how to use `enumerate` to get both the index and the value from a stream. The index is a `usize` and starts from 0.

```rust
use futures::stream::{self, StreamExt};

let stream = stream::iter(vec!['a', 'b', 'c']);

let mut stream = stream.enumerate();

assert_eq!(stream.next().await, Some((0, 'a')));
assert_eq!(stream.next().await, Some((1, 'b')));
assert_eq!(stream.next().await, Some((2, 'c')));
assert_eq!(stream.next().await, None);
```

--------------------------------

### Get File Slice

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/storage_info.rs.html

Calculates the offset and length of a slice within a file, given a starting offset and a maximum length. Used for testing file slice calculations.

```rust
assert_eq!(
            file.get_slice(300, 1000),
            FileSlice {
                offset: 300 - 200,
                len: 500 - (300 - 200),
            },
            "file slice for byte range longer than file should return "
```

--------------------------------

### prepare_for_download

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/peer/state.rs.html?search=std%3A%3Avec

Prepares the session context for initiating a download by setting the slow start mode and initializing the target request queue size.

```APIDOC
## prepare_for_download

### Description
Prepares for requesting blocks. This should be called after being unchoked and becoming interested.

### Method
`pub fn prepare_for_download(&mut self)`

### Parameters
None

### Returns
None
```

--------------------------------

### Initialize Peer State for Download

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/peer/state.rs.html?search=u32+-%3E+bool

Prepares the session context for initiating a download. Ensures that the peer is interested and not choked, and sets initial slow start parameters.

```rust
s.state.is_interested = true;
s.state.is_choked = false;

s.prepare_for_download();

assert!(s.target_request_queue_len > Some(0));
assert!(s.in_slow_start);
```

--------------------------------

### PieceStats Search Examples

Source: https://docs.rs/cratetorrent/latest/cratetorrent/torrent/stats/struct.PieceStats.html?search=

Examples demonstrating how to search PieceStats. These examples cover searching for specific types, type conversions, and generic patterns.

```APIDOC
## Search Examples

### Example 1: Searching for a specific type

```
std::vec
```

### Example 2: Searching for a type conversion

```
u32 -> bool
```

### Example 3: Searching for a generic conversion pattern

```
Option<T>, (T -> U) -> Option<U>
```
```

--------------------------------

### start

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/peer.rs.html?search=std%3A%3Avec

A helper method for the common steps of setting up a peer session, handling handshake logic for both inbound and outbound connections.

```APIDOC
## start

### Description
Helper method for the common steps of setting up a session. It handles sending and receiving handshakes based on the connection direction and prepares the socket for peer message exchange.

### Method
`async fn start(&mut self, mut socket: Framed<TcpStream, HandshakeCodec>, direction: Direction) -> Result<()>`

### Parameters
* `socket` (Framed<TcpStream, HandshakeCodec>) - The framed socket for communication.
* `direction` (Direction) - The direction of the connection (Inbound or Outbound).
```

--------------------------------

### Torrent Error Search Examples

Source: https://docs.rs/cratetorrent/latest/cratetorrent/torrent/error/enum.TorrentError.html?search=

Provides examples of how to search for torrent errors. These examples demonstrate different query patterns for finding specific error types or conversions.

```APIDOC
## Torrent Error Search Examples

### Description
Examples of how to search for torrent errors, including searching for specific types, conversions, and options.

### Example Searches

- `std::vec`
- `u32 -> bool`
- `Option<T>, (T -> U) -> Option<U>`
```

--------------------------------

### Prepare for Download

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/peer/state.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes the session state for downloading by setting `in_slow_start` to true and resetting the target request queue size.

```rust
pub fn prepare_for_download(&mut self) {
        debug_assert!(self.state.is_interested);
        debug_assert!(!self.state.is_choked);

        self.in_slow_start = true;
        // reset the target request queue size, which will be adjusted as the
        // download progresses
        self.target_request_queue_len = Some(Self::START_REQUEST_QUEUE_LEN);
    }
```

--------------------------------

### Exit Slow Start Based on Download Rate

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/peer/state.rs.html?search=u32+-%3E+bool

Determines whether to exit the slow start phase based on the download rate. The slow start phase is exited when the download rate increase significantly drops.

```rust
s.state.is_interested = true;
s.state.is_choked = false;
s.in_slow_start = true;
s.target_request_queue_len = Some(1);

// rate increasing
s.counters.payload.down += 10 * BLOCK_LEN as u64;
// should not exit slow start
s.maybe_exit_slow_start();
assert!(s.in_slow_start);

// reset counter for next round
// download rate using weighed average:
// 0 + (10 * 16384) / 5 = 32768
s.counters.payload.down.reset();

// rate still increasing
s.counters.payload.down += 10 * BLOCK_LEN as u64;
// should not exit slow start yet
s.maybe_exit_slow_start();
assert!(s.in_slow_start);

// reset counter for next round
// download rate using weighed average:
// 32768 + (10 * 16384) / 5 = 65536
// (FIXME: in practice this seems to be 58982)
s.counters.payload.down.reset();

// this round's increase is much less than that of the previous round,
// should exit slow start
s.counters.payload.down += 2 * BLOCK_LEN as u64 + 9000;
s.maybe_exit_slow_start();
assert!(!s.in_slow_start);
```

--------------------------------

### Torrent::new

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/torrent.rs.html?search=

Creates a new Torrent instance. This constructor initializes the torrent components but does not start it. Use `Self::start` to begin the torrent process.

```APIDOC
## Torrent::new

### Description
Creates a new `Torrent` instance for downloading or seeding a torrent. This constructor only initializes the torrent components but does not actually start it. See [`Self::start`].

### Signature
```rust
pub fn new(params: Params) -> (Self, Sender)
```

### Parameters
- **params** (`Params`): A struct containing all necessary parameters to initialize the torrent.
  - **id** (`TorrentId`): Unique identifier for the torrent.
  - **disk_tx** (`Sender`): Sender for disk operations.
  - **info_hash** (`InfoHash`): The info hash of the torrent.
  - **storage_info** (`StorageInfo`): Information about the torrent's storage.
  - **own_pieces** (`Bitfield`): A bitfield representing the pieces the torrent already has.
  - **trackers** (`Vec<Tracker>`): A list of trackers for the torrent.
  - **client_id** (`PeerId`): The client identifier.
  - **listen_addr** (`SocketAddr`): The address on which the torrent should listen for new peers.
  - **conf** (`TorrentConf`): The configuration for this specific torrent.
  - **alert_tx** (`AlertSender`): Sender for alerts related to the torrent.

### Returns
- `(Self, Sender)`: A tuple containing the newly created `Torrent` instance and a `Sender` for commands.
```

--------------------------------

### TrackerError Search Examples

Source: https://docs.rs/cratetorrent/latest/cratetorrent/error/enum.TrackerError.html?search=

Provides examples of how to search for tracker errors, including specific types and conversions.

```APIDOC
## Search Examples

### Example Searches

- `std::vec`
- `u32 -> bool`
- `Option<T>, (T -> U) -> Option<U>`
```

--------------------------------

### Disk IO Test Environment Setup

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/disk.rs.html?search=

Initializes a test environment for disk IO operations. It generates mock piece data, calculates hashes, and sets up storage information. Ensures cleanup of previous test files.

```rust
/// The disk IO test environment containing information of a valid torrent.
    struct Env {
        id: TorrentId,
        pieces: Vec<Vec<u8>>,
        piece_hashes: Vec<u8>,
        info: StorageInfo,
        torrent_tx: torrent::Sender,
        torrent_rx: torrent::Receiver,
    }

    impl Env {
        /// Creates a new test environment.
        ///
        /// Tests are run in parallel so multiple environments must not clash,
        /// therefore the test name must be unique, which is included in the
        /// test environment's path. This also helps debugging.
        fn new(test_name: &str) -> Self {
            let id = TorrentId::new();
            let download_dir = Path::new("/tmp");
            let download_rel_path =
                PathBuf::from(format!("torrent_disk_test_{}", test_name));
            let piece_len: u32 = 4 * 0x4000;
            // last piece is slightly shorter, to test that it is handled
            // correctly
            let last_piece_len: u32 = piece_len - 935;
            let pieces: Vec<Vec<u8>> = vec![
                (0..piece_len).map(|b| (b % 256) as u8).collect(),
                (0..piece_len)
                    .map(|b| b + 1)
                    .map(|b| (b % 256) as u8)
                    .collect(),
                (0..piece_len)
                    .map(|b| b + 2)
                    .map(|b| (b % 256) as u8)
                    .collect(),
                (0..last_piece_len)
                    .map(|b| b + 3)
                    .map(|b| (b % 256) as u8)
                    .collect(),
            ];
            // build up expected piece hashes
            let mut piece_hashes = Vec::with_capacity(pieces.len() * 20);
            for piece in pieces.iter() {
                let hash = Sha1::digest(&piece);
                piece_hashes.extend(hash.as_slice());
            }
            assert_eq!(piece_hashes.len(), pieces.len() * 20);

            // clean up any potential previous test env
            {
                let download_path = download_dir.join(&download_rel_path);
                if download_path.is_file() {
                    fs::remove_file(&download_path).expect(
                        "cannot clean up previous disk test torrent file",
                    );
                } else if download_path.is_dir() {
                    fs::remove_dir_all(&download_path).expect(
                        "cannot clean up previous disk test torrent dir",
                    );
                }
            }

            let download_len = pieces.iter().fold(0, |mut len, piece| {
                len += piece.len() as u64;
                len
            });
            let info = StorageInfo {
                piece_count: pieces.len(),
                piece_len,
                last_piece_len,
                download_len,
                download_dir: download_dir.to_path_buf(),
                files: vec![FileInfo {
                    path: download_rel_path,
                    torrent_offset: 0,
                    len: download_len,
                }],
            };

            let (torrent_tx, torrent_rx) = mpsc::unbounded_channel();

            Self {
                id,
                pieces,
                piece_hashes,
                info,
                torrent_tx,
                torrent_rx,
            }
        }
    }
}
```

--------------------------------

### Prepare for Download in CrateTorrent

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/peer/state.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes the session context for downloading by setting interest and choke states, and preparing for the initial slow start phase.

```rust
#[test]
    fn should_prepare_for_download() {
        let mut s = SessionContext::default();

        s.state.is_interested = true;
        s.state.is_choked = false;

        s.prepare_for_download();

        assert!(s.target_request_queue_len > Some(0));
        assert!(s.in_slow_start);
    }
```

--------------------------------

### Common Session Setup Logic

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/peer.rs.html?search=std%3A%3Avec

A helper method that handles the common steps for setting up a peer session, including sending and receiving handshakes based on connection direction. It transitions the connection state and prepares for the next phase of the session.

```rust
async fn start(
        &mut self,
        mut socket: Framed<TcpStream, HandshakeCodec>,
        direction: Direction,
    ) -> Result<()> {
        self.ctx.set_connection_state(ConnectionState::Handshaking);

        // if this is an outbound connection, we have to send the first
        // handshake
        if direction == Direction::Outbound {
            let handshake = 
                Handshake::new(self.torrent.info_hash, self.torrent.client_id);
            log::info!(target: &self.ctx.log_target, "Sending handshake");
            self.ctx.counters.protocol.up += handshake.len();
            socket.send(handshake).await?;
        }

        // receive peer's handshake
        log::info!(target: &self.ctx.log_target, "Waiting for peer handshake");
        if let Some(peer_handshake) = socket.next().await {
            let peer_handshake = peer_handshake?;
            log::info!(target: &self.ctx.log_target, "Peer sent handshake");
            log::trace!(target: &self.ctx.log_target, "Peer handshake: {:?}", peer_handshake);
            // codec should only return handshake if the protocol string in it
            // is valid
            debug_assert_eq!(peer_handshake.prot, PROTOCOL_STRING.as_bytes());

            self.ctx.counters.protocol.down += peer_handshake.len();

            // verify that the advertised torrent info hash is the same as ours
            if peer_handshake.info_hash != self.torrent.info_hash {
                log::info!(target: &self.ctx.log_target, "Peer handshake invalid info hash");
                // abort session, info hash is invalid
                return Err(PeerError::InvalidInfoHash);
            }

            // set the peer's id
            self.peer.id = Some(peer_handshake.peer_id);

            // if this is an inbound connection, we reply with the handshake
            if direction == Direction::Inbound {
                let handshake = Handshake::new(
                    self.torrent.info_hash,
                    self.torrent.client_id,
                );
                log::info!(target: &self.ctx.log_target, "Sending handshake");
                self.ctx.counters.protocol.up += handshake.len();
                socket.send(handshake).await?;
            }

            // now that we have the handshake, we need to switch to the peer
            // message codec and save the socket in self (note that we need to
            // keep the buffer from the original codec as it may contain bytes
            // of any potential message the peer may have sent after the
            // handshake)
            let old_parts = socket.into_parts();
            let mut new_parts = FramedParts::new(old_parts.io, PeerCodec);
            // reuse buffers of previous codec
            new_parts.read_buf = old_parts.read_buf;
            new_parts.write_buf = old_parts.write_buf;
            let socket = Framed::from_parts(new_parts);

            // update torrent of connection
            self.torrent.cmd_tx.send(torrent::Command::PeerConnected {
                addr: self.peer.addr,
                id: peer_handshake.peer_id,
            })?;

            // enter the piece availability exchange state
            self.ctx
                .set_connection_state(ConnectionState::AvailabilityExchange);
            log::info!(target: &self.ctx.log_target, "Session state: {:?}", self.ctx.state.connection);

            // run the session
            if let Err(e) = self.run(socket).await {
                log::error(
                    target: &self.ctx.log_target,
                    "Session stopped due to an error: {}",
                    e
                );
                self.ctx.set_connection_state(ConnectionState::Disconnected);
                self.torrent.cmd_tx.send(torrent::Command::PeerState {
                    addr: self.peer.addr,
                    info: self.session_info(),
                })?;
                self.torrent.alert_tx.send(Alert::Error(Error::Peer {

```

--------------------------------

### Exit Slow Start Logic in CrateTorrent

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/peer/state.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Determines when to exit the slow start phase based on download rate increases. The system exits slow start if the current download rate increase is significantly less than the previous round's increase.

```rust
#[test]
    fn should_exit_slow_start() {
        let mut s = SessionContext::default();

        s.state.is_interested = true;
        s.state.is_choked = false;
        s.in_slow_start = true;
        s.target_request_queue_len = Some(1);

        // rate increasing
        s.counters.payload.down += 10 * BLOCK_LEN as u64;
        // should not exit slow start
        s.maybe_exit_slow_start();
        assert!(s.in_slow_start);

        // reset counter for next round
        // download rate using weighed average:
        // 0 + (10 * 16384) / 5 = 32768
        s.counters.payload.down.reset();

        // rate still increasing
        s.counters.payload.down += 10 * BLOCK_LEN as u64;
        // should not exit slow start yet
        s.maybe_exit_slow_start();
        assert!(s.in_slow_start);

        // reset counter for next round
        // download rate using weighed average:
        // 32768 + (10 * 16384) / 5 = 65536
        // (FIXME: in practice this seems to be 58982)
        s.counters.payload.down.reset();

        // this round's increase is much less than that of the previous round,
        // should exit slow start
        s.counters.payload.down += 2 * BLOCK_LEN as u64 + 9000;
        s.maybe_exit_slow_start();
        assert!(!s.in_slow_start);
    }
```

--------------------------------

### Check for Slow Start Exit Condition

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/peer/state.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Determines if the peer should exit slow start mode. This occurs if the peer is not choked, is currently in slow start, has a target request queue length, and the download rate has not increased significantly since the last round.

```rust
fn maybe_exit_slow_start(&mut self) {
        if !self.state.is_choked
            && self.in_slow_start
            && self.target_request_queue_len.is_some()
            && self.counters.payload.down.round() > 0
            && self.counters.payload.down.round()
                + Self::SLOW_START_ERROR_MARGIN
                < self.counters.payload.down.avg()
        {
            self.in_slow_start = false;
        }
    }
```

--------------------------------

### Common Session Setup Logic

Source: https://docs.rs/cratetorrent/latest/src/cratetorrent/peer.rs.html?search=u32+-%3E+bool

A helper method that handles the common steps for setting up a peer session, including sending and receiving handshakes based on connection direction. It transitions the connection state and prepares for message exchange.

```rust
async fn start(
        &mut self,
        mut socket: Framed<TcpStream, HandshakeCodec>,
        direction: Direction,
    ) -> Result<()> {
        self.ctx.set_connection_state(ConnectionState::Handshaking);

        // if this is an outbound connection, we have to send the first
        // handshake
        if direction == Direction::Outbound {
            let handshake = 
                Handshake::new(self.torrent.info_hash, self.torrent.client_id);
            log::info!(target: &self.ctx.log_target, "Sending handshake");
            self.ctx.counters.protocol.up += handshake.len();
            socket.send(handshake).await?;
        }

        // receive peer's handshake
        log::info!(target: &self.ctx.log_target, "Waiting for peer handshake");
        if let Some(peer_handshake) = socket.next().await {
            let peer_handshake = peer_handshake?;
            log::info!(target: &self.ctx.log_target, "Peer sent handshake");
            log::trace!(target: &self.ctx.log_target, "Peer handshake: {:?}", peer_handshake);
            // codec should only return handshake if the protocol string in it
            // is valid
            debug_assert_eq!(peer_handshake.prot, PROTOCOL_STRING.as_bytes());

            self.ctx.counters.protocol.down += peer_handshake.len();

            // verify that the advertised torrent info hash is the same as ours
            if peer_handshake.info_hash != self.torrent.info_hash {
                log::info!(target: &self.ctx.log_target, "Peer handshake invalid info hash");
                // abort session, info hash is invalid
                return Err(PeerError::InvalidInfoHash);
            }

            // set the peer's id
            self.peer.id = Some(peer_handshake.peer_id);

            // if this is an inbound connection, we reply with the handshake
            if direction == Direction::Inbound {
                let handshake = Handshake::new(
                    self.torrent.info_hash,
                    self.torrent.client_id,
                );
                log::info!(target: &self.ctx.log_log, "Sending handshake");
                self.ctx.counters.protocol.up += handshake.len();
                socket.send(handshake).await?;
            }

            // now that we have the handshake, we need to switch to the peer
            // message codec and save the socket in self (note that we need to
            // keep the buffer from the original codec as it may contain bytes
            // of any potential message the peer may have sent after the
            // handshake)
            let old_parts = socket.into_parts();
            let mut new_parts = FramedParts::new(old_parts.io, PeerCodec);
            // reuse buffers of previous codec
            new_parts.read_buf = old_parts.read_buf;
            new_parts.write_buf = old_parts.write_buf;
            let socket = Framed::from_parts(new_parts);

            // update torrent of connection
            self.torrent.cmd_tx.send(torrent::Command::PeerConnected {
                addr: self.peer.addr,
                id: peer_handshake.peer_id,
            })?;

            // enter the piece availability exchange state
            self.ctx
                .set_connection_state(ConnectionState::AvailabilityExchange);
            log::info!(target: &self.ctx.log_target, "Session state: {:?}", self.ctx.state.connection);

            // run the session
            if let Err(e) = self.run(socket).await {
                log::error!(
                    target: &self.ctx.log_target,
                    "Session stopped due to an error: {}",
                    e
                );
                self.ctx.set_connection_state(ConnectionState::Disconnected);
                self.torrent.cmd_tx.send(torrent::Command::PeerState {
                    addr: self.peer.addr,
                    info: self.session_info(),
                })?;
                self.torrent.alert_tx.send(Alert::Error(Error::Peer {
 
```
Tokens:
Raw