Update docs, cleanup for 4.0.0 release

README.md

@@ -30,7 +30,7 @@ Access with http://localhost:3030/web/
 ## Desktop app
 The desktop app is a [thin wrapper](https://github.com/ikatson/rqbit/blob/main/desktop/src-tauri/src/main.rs) on top of the Web UI frontend.
 
-Download it in [Releases](https://github.com/ikatson/rqbit/releases) starting from [4.0.0-beta.3](https://github.com/ikatson/rqbit/releases/tag/v4.0.0-beta.3).
+Download it in [Releases](https://github.com/ikatson/rqbit/releases).
 
 ## Installation
 

crates/dht/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "librqbit-dht"
-version = "4.0.0-beta.3"
+version = "4.0.0"
 edition = "2021"
 description = "DHT implementation, used in rqbit torrent client."
 license = "Apache-2.0"
@@ -34,7 +34,7 @@ indexmap = "2"
 dashmap = {version = "5.5.3", features = ["serde"]}
 
 clone_to_owned = {path="../clone_to_owned", package="librqbit-clone-to-owned", version = "2.2.1"}
-librqbit-core = {path="../librqbit_core", version = "3.2.0"}
+librqbit-core = {path="../librqbit_core", version = "3.2.1"}
 chrono = {version = "0.4.31", features = ["serde"]}
 
 [dev-dependencies]

crates/dht/src/peer_store.rs

@@ -209,6 +209,7 @@ impl PeerStore {
         Vec::new()
     }
 
+    #[allow(dead_code)]
     pub fn garbage_collect_peers(&self) {
         todo!()
     }

crates/librqbit/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "librqbit"
-version = "4.0.0-beta.3"
+version = "4.0.0"
 authors = ["Igor Katson <[email protected]>"]
 edition = "2021"
 description = "The main library used by rqbit torrent client. The binary is just a small wrapper on top of it."
@@ -24,11 +24,11 @@ rust-tls = ["reqwest/rustls-tls"]
 [dependencies]
 bencode = {path = "../bencode", default-features=false, package="librqbit-bencode", version="2.2.1"}
 buffers = {path = "../buffers", package="librqbit-buffers", version = "2.2.1"}
-librqbit-core = {path = "../librqbit_core", version = "3.2.0"}
+librqbit-core = {path = "../librqbit_core", version = "3.2.1"}
 clone_to_owned = {path = "../clone_to_owned", package="librqbit-clone-to-owned", version = "2.2.1"}
-peer_binary_protocol = {path = "../peer_binary_protocol", package="librqbit-peer-protocol", version = "3.2.0"}
+peer_binary_protocol = {path = "../peer_binary_protocol", package="librqbit-peer-protocol", version = "3.2.1"}
 sha1w = {path = "../sha1w", default-features=false, package="librqbit-sha1-wrapper", version="2.2.1"}
-dht = {path = "../dht", package="librqbit-dht", version="4.0.0-beta.3"}
+dht = {path = "../dht", package="librqbit-dht", version="4.0.0"}
 
 tokio = {version = "1", features = ["macros", "rt-multi-thread"]}
 axum = {version = "0.7"}
@@ -67,3 +67,4 @@ serde_with = "3.4.0"
 [dev-dependencies]
 futures = {version = "0.3"}
 tracing-subscriber = "0.3"
+tokio-test = "0.4"

crates/librqbit/README.md

@@ -1,6 +1,9 @@
 # librqbit
 
-A fully featured, easy to use torrent downloading library used as a backbone of [rqbit](https://github.com/ikatson/rqbit) CLI.
+A fully featured, easy to use torrent downloading library used as a backbone of [rqbit](https://github.com/ikatson/rqbit).
 
 ## Basic example
-See [examples on GitHub](https://github.com/ikatson/rqbit/tree/main/crates/librqbit/examples).
+See [examples on GitHub](https://github.com/ikatson/rqbit/tree/main/crates/librqbit/examples).
+
+## Documentation
+[librqbit at docs.rs](https://docs.rs/librqbit/latest/librqbit/)

crates/librqbit/examples/ubuntu.rs

@@ -6,7 +6,7 @@
 use std::time::Duration;
 
 use anyhow::Context;
-use librqbit::session::{AddTorrent, AddTorrentOptions, AddTorrentResponse, Session};
+use librqbit::{AddTorrent, AddTorrentOptions, AddTorrentResponse, Session};
 use tracing::info;
 
 // This is ubuntu-21.04-live-server-amd64.iso.torrent
@@ -27,7 +27,7 @@ async fn main() -> Result<(), anyhow::Error> {
         .expect("the first argument should be the output directory");
 
     // Create the session
-    let session = Session::new(output_dir.into(), Default::default())
+    let session = Session::new(output_dir.into())
         .await
         .context("error creating session")?;
 

crates/librqbit/src/api.rs

@@ -16,15 +16,16 @@ use crate::{
     },
     torrent_state::{
         peer::stats::snapshot::{PeerStatsFilter, PeerStatsSnapshot},
-        stats::{LiveStats, TorrentStats},
         ManagedTorrentHandle,
     },
 };
 
+pub use crate::torrent_state::stats::{LiveStats, TorrentStats};
+
 pub type Result<T> = std::result::Result<T, ApiError>;
 
-// Library API for use in different web frameworks.
-// Contains all methods you might want to expose with (de)serializable inputs/outputs.
+/// Library API for use in different web frameworks.
+/// Contains all methods you might want to expose with (de)serializable inputs/outputs.
 pub struct Api {
     session: Arc<Session>,
     rust_log_reload_tx: Option<UnboundedSender<String>>,

crates/librqbit/src/dht_utils.rs

@@ -106,7 +106,7 @@ mod tests {
     async fn read_metainfo_from_dht() {
         init_logging();
 
-        let info_hash = Id20::from_str("cf3ea75e2ebbd30e0da6e6e215e2226bf35f2e33").unwrap();
+        let info_hash = Id20::from_str("cab507494d02ebb1178b38f2e9d7be299c86b862").unwrap();
         let dht = DhtBuilder::new().await.unwrap();
         let peer_rx = dht.get_peers(info_hash).unwrap();
         let peer_id = generate_peer_id();

crates/librqbit/src/http_api.rs

@@ -24,7 +24,7 @@ type ApiState = Arc<Api>;
 
 use crate::api::Result;
 
-// Public API
+/// An HTTP server for the API.
 #[derive(Clone)]
 pub struct HttpApi {
     inner: ApiState,
@@ -37,6 +37,8 @@ impl HttpApi {
         }
     }
 
+    /// Run the HTTP server forever on the given address.
+    /// If read_only is passed, no state-modifying methods will be exposed.
     pub async fn make_http_api_and_run(
         self,
         addr: SocketAddr,
@@ -267,11 +269,11 @@ impl HttpApi {
     }
 }
 
-pub struct OnlyFiles(Vec<usize>);
-pub struct InitialPeers(pub Vec<SocketAddr>);
+pub(crate) struct OnlyFiles(Vec<usize>);
+pub(crate) struct InitialPeers(pub Vec<SocketAddr>);
 
 #[derive(Serialize, Deserialize, Default)]
-pub struct TorrentAddQueryParams {
+pub(crate) struct TorrentAddQueryParams {
     pub overwrite: Option<bool>,
     pub output_folder: Option<String>,
     pub sub_folder: Option<String>,

crates/librqbit/src/lib.rs

@@ -1,17 +1,52 @@
+//!
+//! This crate provides everything necessary to download [torrents](https://en.wikipedia.org/wiki/BitTorrent).
+//!
+//! # Quick usage example
+//!
+//! ```no_run
+//! use librqbit::*;
+//!
+//! tokio_test::block_on(async {
+//!     let session = Session::new("/tmp/where-to-download".into()).await.unwrap();
+//!     let managed_torrent_handle = session.add_torrent(
+//!        AddTorrent::from_url("magnet:?xt=urn:btih:cab507494d02ebb1178b38f2e9d7be299c86b862"),
+//!        None // options
+//!     ).await.unwrap().into_handle().unwrap();
+//!     managed_torrent_handle.wait_until_completed().await.unwrap();
+//! })
+//! ```
+//!
+//! # Overview
+//! The main type to start off with is [`Session`].
+//!
+//! It also proved useful to use the [`Api`] when building the rqbit desktop app, as it provides
+//! a facade that works with simple serializable types.
+
 pub mod api;
-pub mod api_error;
-pub mod chunk_tracker;
-pub mod dht_utils;
-pub mod file_ops;
+mod api_error;
+mod chunk_tracker;
+mod dht_utils;
+mod file_ops;
 pub mod http_api;
 pub mod http_api_client;
-pub mod peer_connection;
-pub mod peer_info_reader;
-pub mod session;
-pub mod spawn_utils;
-pub mod torrent_state;
-pub mod tracker_comms;
-pub mod type_aliases;
+mod peer_connection;
+mod peer_info_reader;
+mod session;
+mod spawn_utils;
+mod torrent_state;
+mod tracker_comms;
+mod type_aliases;
+
+pub use api::Api;
+pub use api_error::ApiError;
+pub use dht;
+pub use peer_connection::PeerConnectionOptions;
+pub use session::{
+    AddTorrent, AddTorrentOptions, AddTorrentResponse, ListOnlyResponse, Session, SessionOptions,
+    SUPPORTED_SCHEMES,
+};
+pub use spawn_utils::spawn as librqbit_spawn;
+pub use torrent_state::{ManagedTorrent, ManagedTorrentState};
 
 pub use buffers::*;
 pub use clone_to_owned::CloneToOwned;

crates/librqbit/src/peer_connection.rs

@@ -119,9 +119,7 @@ impl<H: PeerConnectionHandler> PeerConnection<H> {
             options: options.unwrap_or_default(),
         }
     }
-    pub fn into_handler(self) -> H {
-        self.handler
-    }
+
     pub async fn manage_peer(
         &self,
         mut outgoing_chan: tokio::sync::mpsc::UnboundedReceiver<WriterRequest>,