From 8f2e22ea65662f6c7cbb660837cec8228d5976aa Mon Sep 17 00:00:00 2001 From: Cameron Garnham Date: Fri, 13 Oct 2023 11:23:05 +0200 Subject: [PATCH 1/5] ci: maintaince update for labelsync --- .github/workflows/labels.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/labels.yaml b/.github/workflows/labels.yaml index 4d049eb0..bb8283f3 100644 --- a/.github/workflows/labels.yaml +++ b/.github/workflows/labels.yaml @@ -33,4 +33,4 @@ jobs: with: config-file: .github/labels.json delete-other-labels: true - token: ${{ secrets.UPDATE_ISSUES }} + token: ${{ secrets.UPDATE_LABELS }} From 308f490e34d31ee64774993af8d939662f6f4061 Mon Sep 17 00:00:00 2001 From: Cameron Garnham Date: Thu, 12 Oct 2023 10:28:18 +0200 Subject: [PATCH 2/5] deps: update cargo lockfile --- Cargo.lock | 130 ++++++++++++++++++++++++----------------------------- 1 file changed, 59 insertions(+), 71 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 142fa521..ef5e1a4e 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -41,9 +41,9 @@ dependencies = [ [[package]] name = "aho-corasick" -version = "1.1.1" +version = "1.1.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ea5d730647d4fadd988536d06fecce94b7b4f2a7efdae548f1cf4b63205518ab" +checksum = "b2969dcb958b36655471fc61f7e416fa76033bdd4bfed0678d8fee1e2d07a1f0" dependencies = [ "memchr", ] @@ -142,7 +142,7 @@ checksum = "bc00ceb34980c03614e35a3a4e218276a0a824e911d07651cd0d858a51e8c0f0" dependencies = [ "proc-macro2", "quote", - "syn 2.0.37", + "syn 2.0.38", ] [[package]] @@ -292,7 +292,7 @@ dependencies = [ "regex", "rustc-hash", "shlex", - "syn 2.0.37", + "syn 2.0.38", ] [[package]] @@ -430,9 +430,9 @@ dependencies = [ [[package]] name = "byteorder" -version = "1.4.3" +version = "1.5.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "14c189c53d098945499cdfa7ecc63567cf3886b3332b312a5b4585d8d3a6a610" +checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b" [[package]] name = "bytes" @@ -749,7 +749,7 @@ dependencies = [ "proc-macro2", "quote", "strsim", - "syn 2.0.37", + "syn 2.0.38", ] [[package]] @@ -760,7 +760,7 @@ checksum = "836a9bbc7ad63342d6d6e7b815ccab164bc77a2d95d84bc3117a8c0d5c98e2d5" dependencies = [ "darling_core", "quote", - "syn 2.0.37", + "syn 2.0.38", ] [[package]] @@ -793,7 +793,7 @@ checksum = "9abcad25e9720609ccb3dcdb795d845e37d8ce34183330a9f48b03a1a71c8e21" dependencies = [ "proc-macro2", "quote", - "syn 2.0.37", + "syn 2.0.38", ] [[package]] @@ -847,25 +847,14 @@ checksum = "5443807d6dff69373d433ab9ef5378ad8df50ca6298caf15de6e52e24aaf54d5" [[package]] name = "errno" -version = "0.3.4" +version = "0.3.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "add4f07d43996f76ef320709726a556a9d4f965d9410d8d0271132d2f8293480" +checksum = "ac3e13f66a2f95e32a39eaa81f6b95d42878ca0e1db0c7543723dfe12557e860" dependencies = [ - "errno-dragonfly", "libc", "windows-sys", ] -[[package]] -name = "errno-dragonfly" -version = "0.1.2" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "aa68f1b12764fab894d2755d2518754e71b4fd80ecfb822714a1206c2aab39bf" -dependencies = [ - "cc", - "libc", -] - [[package]] name = "error-chain" version = "0.12.4" @@ -994,7 +983,7 @@ checksum = "b0fa992f1656e1707946bbba340ad244f0814009ef8c0118eb7b658395f19a2e" dependencies = [ "frunk_proc_macro_helpers", "quote", - "syn 2.0.37", + "syn 2.0.38", ] [[package]] @@ -1006,7 +995,7 @@ dependencies = [ "frunk_core", "proc-macro2", "quote", - "syn 2.0.37", + "syn 2.0.38", ] [[package]] @@ -1018,7 +1007,7 @@ dependencies = [ "frunk_core", "frunk_proc_macro_helpers", "quote", - "syn 2.0.37", + "syn 2.0.38", ] [[package]] @@ -1083,7 +1072,7 @@ checksum = "89ca545a94061b6365f2c7355b4b32bd20df3ff95f02da9329b34ccc3bd6ee72" dependencies = [ "proc-macro2", "quote", - "syn 2.0.37", + "syn 2.0.38", ] [[package]] @@ -1374,7 +1363,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "5305557fa27b460072ae15ce07617e999f5879f14d376c8449f0bfb9f9d8e91e" dependencies = [ "derive_utils", - "syn 2.0.37", + "syn 2.0.38", ] [[package]] @@ -1411,9 +1400,9 @@ checksum = "af150ab688ff2122fcef229be89cb50dd66af9e01a4ff320cc137eecc9bacc38" [[package]] name = "jobserver" -version = "0.1.26" +version = "0.1.27" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "936cfd212a0155903bcbc060e316fb6cc7cbf2e1907329391ebadc1fe0ce77c2" +checksum = "8c37f63953c4c63420ed5fd3d6d398c719489b9f872b9fa683262f8edd363c7d" dependencies = [ "libc", ] @@ -1525,9 +1514,9 @@ dependencies = [ [[package]] name = "libc" -version = "0.2.148" +version = "0.2.149" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9cdc71e17332e86d2e1d38c1f99edcb6288ee11b815fb1a4b049eaa2114d369b" +checksum = "a08173bc88b7955d1b3145aa561539096c421ac8debde8cbc3612ec635fee29b" [[package]] name = "libloading" @@ -1569,9 +1558,9 @@ checksum = "0717cef1bc8b636c6e1c1bbdefc09e6322da8a9321966e8928ef80d20f7f770f" [[package]] name = "linux-raw-sys" -version = "0.4.8" +version = "0.4.10" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3852614a3bd9ca9804678ba6be5e3b8ce76dfc902cae004e3e0c44051b6e88db" +checksum = "da2479e8c062e40bf0066ffa0bc823de0a9368974af99c9f6df941d2c231e03f" [[package]] name = "local-ip-address" @@ -1738,7 +1727,7 @@ dependencies = [ "proc-macro-error", "proc-macro2", "quote", - "syn 2.0.37", + "syn 2.0.38", "termcolor", "thiserror", ] @@ -1878,9 +1867,9 @@ dependencies = [ [[package]] name = "num-traits" -version = "0.2.16" +version = "0.2.17" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f30b0abd723be7e2ffca1272140fac1a2f084c77ec3e123c192b66af1ee9e6c2" +checksum = "39e3200413f237f41ab11ad6d161bc7239c84dcb631773ccd7de3dfe4b5c267c" dependencies = [ "autocfg", ] @@ -1939,7 +1928,7 @@ checksum = "a948666b637a0f465e8564c73e89d4dde00d72d4d473cc972f390fc3dcee7d9c" dependencies = [ "proc-macro2", "quote", - "syn 2.0.37", + "syn 2.0.38", ] [[package]] @@ -2062,7 +2051,7 @@ dependencies = [ "pest_meta", "proc-macro2", "quote", - "syn 2.0.37", + "syn 2.0.38", ] [[package]] @@ -2093,7 +2082,7 @@ checksum = "4359fd9c9171ec6e8c62926d6faaf553a8dc3f64e1507e76da7911b4f6a04405" dependencies = [ "proc-macro2", "quote", - "syn 2.0.37", + "syn 2.0.38", ] [[package]] @@ -2223,9 +2212,9 @@ dependencies = [ [[package]] name = "proc-macro2" -version = "1.0.67" +version = "1.0.69" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3d433d9f1a3e8c1263d9456598b16fec66f4acc9a74dacffd35c7bb09b3a1328" +checksum = "134c189feb4956b20f6f547d2cf727d4c0fe06722b20a0eec87ed445a97f92da" dependencies = [ "unicode-ident", ] @@ -2358,9 +2347,9 @@ dependencies = [ [[package]] name = "regex" -version = "1.9.6" +version = "1.10.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ebee201405406dbf528b8b672104ae6d6d63e6d118cb10e4d51abbc7b58044ff" +checksum = "d119d7c7ca818f8a53c300863d4f87566aac09943aef5b355bb83969dae75d87" dependencies = [ "aho-corasick", "memchr", @@ -2370,9 +2359,9 @@ dependencies = [ [[package]] name = "regex-automata" -version = "0.3.9" +version = "0.4.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "59b23e92ee4318893fa3fe3e6fb365258efbfe6ac6ab30f090cdcbb7aa37efa9" +checksum = "465c6fc0621e4abc4187a2bda0937bfd4f722c2730b29562e19689ea796c9a4b" dependencies = [ "aho-corasick", "memchr", @@ -2381,9 +2370,9 @@ dependencies = [ [[package]] name = "regex-syntax" -version = "0.7.5" +version = "0.8.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "dbb5fb1acd8a1a18b3dd5be62d25485eb770e05afb408a9627d14d451bae12da" +checksum = "56d84fdd47036b038fc80dd333d10b6aab10d5d31f4a366e20014def75328d33" [[package]] name = "rend" @@ -2396,9 +2385,9 @@ dependencies = [ [[package]] name = "reqwest" -version = "0.11.21" +version = "0.11.22" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "78fdbab6a7e1d7b13cc8ff10197f47986b41c639300cc3c8158cac7847c9bbef" +checksum = "046cd98826c46c2ac8ddecae268eb5c2e58628688a5fc7a2643704a73faba95b" dependencies = [ "base64 0.21.4", "bytes", @@ -2549,9 +2538,9 @@ dependencies = [ [[package]] name = "rustix" -version = "0.38.15" +version = "0.38.18" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d2f9da0cbd88f9f09e7814e388301c8414c51c62aa6ce1e4b5c551d49d96e531" +checksum = "5a74ee2d7c2581cd139b42447d7d9389b889bdaad3a73f1ebb16f2a3237bb19c" dependencies = [ "bitflags 2.4.0", "errno", @@ -2683,9 +2672,9 @@ dependencies = [ [[package]] name = "semver" -version = "1.0.19" +version = "1.0.20" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ad977052201c6de01a8ef2aa3378c4bd23217a056337d1d6da40468d267a4fb0" +checksum = "836fa6a3e1e547f9a2c4040802ec865b5d85f4014efe00555d7090a3dcaa1090" [[package]] name = "serde" @@ -2698,9 +2687,9 @@ dependencies = [ [[package]] name = "serde_bencode" -version = "0.2.3" +version = "0.2.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "934d8bdbaa0126dafaea9a8833424a211d9661897717846c6bb782349ca1c30d" +checksum = "a70dfc7b7438b99896e7f8992363ab8e2c4ba26aa5ec675d32d1c3c2c33d413e" dependencies = [ "serde", "serde_bytes", @@ -2723,7 +2712,7 @@ checksum = "4eca7ac642d82aa35b60049a6eccb4be6be75e599bd2e9adb5f875a737654af2" dependencies = [ "proc-macro2", "quote", - "syn 2.0.37", + "syn 2.0.38", ] [[package]] @@ -2755,7 +2744,7 @@ checksum = "8725e1dfadb3a50f7e5ce0b1a540466f6ed3fe7a0fca2ac2b8b831d31316bd00" dependencies = [ "proc-macro2", "quote", - "syn 2.0.37", + "syn 2.0.38", ] [[package]] @@ -2805,7 +2794,7 @@ dependencies = [ "darling", "proc-macro2", "quote", - "syn 2.0.37", + "syn 2.0.38", ] [[package]] @@ -2927,9 +2916,9 @@ dependencies = [ [[package]] name = "syn" -version = "2.0.37" +version = "2.0.38" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7303ef2c05cd654186cb250d29049a24840ca25d2747c25c0381c8d9e2f582e8" +checksum = "e96b79aaa137db8f61e26363a0c9b47d8b4ec75da28b7d1d614c2303e232408b" dependencies = [ "proc-macro2", "quote", @@ -3014,7 +3003,7 @@ checksum = "10712f02019e9288794769fba95cd6847df9874d49d871d062172f9dd41bc4cc" dependencies = [ "proc-macro2", "quote", - "syn 2.0.37", + "syn 2.0.38", ] [[package]] @@ -3072,9 +3061,9 @@ checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20" [[package]] name = "tokio" -version = "1.32.0" +version = "1.33.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "17ed6077ed6cd6c74735e21f37eb16dc3935f96878b1fe961074089cc80893f9" +checksum = "4f38200e3ef7995e5ef13baec2f432a6da0aa9ac495b2c0e8f3b7eec2c92d653" dependencies = [ "backtrace", "bytes", @@ -3096,7 +3085,7 @@ checksum = "630bdcf245f78637c13ec01ffae6187cca34625e8c63150d424b59e55af2675e" dependencies = [ "proc-macro2", "quote", - "syn 2.0.37", + "syn 2.0.38", ] [[package]] @@ -3487,7 +3476,7 @@ dependencies = [ "once_cell", "proc-macro2", "quote", - "syn 2.0.37", + "syn 2.0.38", "wasm-bindgen-shared", ] @@ -3521,7 +3510,7 @@ checksum = "54681b18a46765f095758388f2d0cf16eb8d4169b639ab575a8f5693af210c7b" dependencies = [ "proc-macro2", "quote", - "syn 2.0.37", + "syn 2.0.38", "wasm-bindgen-backend", "wasm-bindgen-shared", ] @@ -3650,9 +3639,9 @@ checksum = "ed94fce61571a4006852b7389a063ab983c02eb1bb37b47f8272ce92d06d9538" [[package]] name = "winnow" -version = "0.5.15" +version = "0.5.16" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7c2e3184b9c4e92ad5167ca73039d0c42476302ab603e2fec4487511f38ccefc" +checksum = "037711d82167854aff2018dfd193aa0fef5370f456732f0d5a0c59b0f1b4b907" dependencies = [ "memchr", ] @@ -3706,11 +3695,10 @@ dependencies = [ [[package]] name = "zstd-sys" -version = "2.0.8+zstd.1.5.5" +version = "2.0.9+zstd.1.5.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5556e6ee25d32df2586c098bbfa278803692a20d0ab9565e049480d52707ec8c" +checksum = "9e16efa8a874a0481a574084d34cc26fdb3b99627480f785888deb6386506656" dependencies = [ "cc", - "libc", "pkg-config", ] From 7dbca2bb8ec1f9f08dca8f752369ec00a4bec429 Mon Sep 17 00:00:00 2001 From: Cameron Garnham Date: Thu, 12 Oct 2023 10:28:50 +0200 Subject: [PATCH 3/5] ci: move doc tests to unit section --- .github/workflows/testing.yaml | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/.github/workflows/testing.yaml b/.github/workflows/testing.yaml index f138a95c..3ae18e4d 100644 --- a/.github/workflows/testing.yaml +++ b/.github/workflows/testing.yaml @@ -65,10 +65,6 @@ jobs: name: Run Lint Checks run: cargo clippy --tests --benches --examples --workspace --all-targets --all-features -- -D clippy::correctness -D clippy::suspicious -D clippy::complexity -D clippy::perf -D clippy::style -D clippy::pedantic - - id: doc - name: Run Documentation Checks - run: cargo test --doc - unit: name: Units runs-on: ubuntu-latest @@ -100,6 +96,14 @@ jobs: with: tool: cargo-llvm-cov, cargo-nextest + - id: docs + name: Build Documentation + run: cargo doc --no-deps --bins --examples --workspace --all-features + + - id: test-docs + name: Run Documentation Tests + run: cargo test --doc + - id: test name: Run Unit Tests run: cargo test --tests --benches --examples --workspace --all-targets --all-features From 417ad73d6c288374b98be2b0ff1819714ae62beb Mon Sep 17 00:00:00 2001 From: Cameron Garnham Date: Thu, 12 Oct 2023 10:54:42 +0200 Subject: [PATCH 4/5] chore: fix doc warnings --- src/bootstrap/app.rs | 4 ++-- src/bootstrap/jobs/http_tracker.rs | 2 +- src/bootstrap/jobs/tracker_apis.rs | 2 +- src/lib.rs | 4 ++-- src/servers/apis/mod.rs | 6 +++--- .../apis/v1/context/auth_key/handlers.rs | 2 +- src/servers/apis/v1/context/stats/handlers.rs | 2 +- .../apis/v1/context/stats/responses.rs | 2 +- .../apis/v1/context/torrent/handlers.rs | 2 +- .../apis/v1/context/torrent/resources/peer.rs | 2 +- .../v1/context/torrent/resources/torrent.rs | 4 ++-- .../apis/v1/context/torrent/responses.rs | 4 ++-- src/servers/http/mod.rs | 4 ++-- src/servers/http/percent_encoding.rs | 6 +++--- .../http/v1/extractors/announce_request.rs | 6 +++--- .../http/v1/extractors/authentication_key.rs | 4 ++-- .../http/v1/extractors/client_ip_sources.rs | 2 +- .../http/v1/extractors/scrape_request.rs | 6 +++--- src/servers/http/v1/handlers/common/auth.rs | 2 +- .../http/v1/handlers/common/peer_ip.rs | 2 +- src/servers/http/v1/query.rs | 2 +- src/servers/http/v1/responses/announce.rs | 4 ++-- src/servers/http/v1/services/announce.rs | 6 +++--- src/servers/http/v1/services/scrape.rs | 6 +++--- src/servers/udp/mod.rs | 2 +- src/servers/udp/peer_builder.rs | 2 +- src/servers/udp/request.rs | 4 ++-- src/servers/udp/server.rs | 6 +++--- src/tracker/auth.rs | 8 ++++---- src/tracker/databases/mod.rs | 4 ++-- src/tracker/mod.rs | 20 +++++++++---------- src/tracker/services/statistics/mod.rs | 4 ++-- src/tracker/services/statistics/setup.rs | 2 +- src/tracker/services/torrent.rs | 10 +++++----- src/tracker/torrent.rs | 6 +++--- 35 files changed, 77 insertions(+), 77 deletions(-) diff --git a/src/bootstrap/app.rs b/src/bootstrap/app.rs index 6961e15f..78c16a0a 100644 --- a/src/bootstrap/app.rs +++ b/src/bootstrap/app.rs @@ -1,6 +1,6 @@ //! Setup for the main tracker application. //! -//! The [`setup`](bootstrap::app::setup) only builds the application and its dependencies but it does not start the application. +//! The [`setup`] only builds the application and its dependencies but it does not start the application. //! In fact, there is no such thing as the main application process. When the application starts, the only thing it does is //! starting a bunch of independent jobs. If you are looking for how things are started you should read [`app::start`](crate::app::start) //! function documentation. @@ -22,7 +22,7 @@ use crate::shared::crypto::ephemeral_instance_keys; use crate::tracker::services::tracker_factory; use crate::tracker::Tracker; -/// It loads the configuration from the environment and builds the main domain [`tracker`](crate::tracker::Tracker) struct. +/// It loads the configuration from the environment and builds the main domain [`Tracker`] struct. #[must_use] pub fn setup() -> (Arc, Arc) { let configuration = Arc::new(initialize_configuration()); diff --git a/src/bootstrap/jobs/http_tracker.rs b/src/bootstrap/jobs/http_tracker.rs index ac016164..a38fe3a5 100644 --- a/src/bootstrap/jobs/http_tracker.rs +++ b/src/bootstrap/jobs/http_tracker.rs @@ -7,7 +7,7 @@ //! //! The [`http_tracker::start_job`](crate::bootstrap::jobs::http_tracker::start_job) function spawns a new asynchronous task, //! that tasks is the "**launcher**". The "**launcher**" starts the actual server and sends a message back to the main application. -//! The main application waits until receives the message [`ServerJobStarted`](crate::bootstrap::jobs::http_tracker::ServerJobStarted) from the "**launcher**". +//! The main application waits until receives the message [`ServerJobStarted`] from the "**launcher**". //! //! The "**launcher**" is an intermediary thread that decouples the HTTP servers from the process that handles it. The HTTP could be used independently in the future. //! In that case it would not need to notify a parent process. diff --git a/src/bootstrap/jobs/tracker_apis.rs b/src/bootstrap/jobs/tracker_apis.rs index 9afe4ab2..33b9b6e4 100644 --- a/src/bootstrap/jobs/tracker_apis.rs +++ b/src/bootstrap/jobs/tracker_apis.rs @@ -11,7 +11,7 @@ //! function spawns a new asynchronous task, that tasks is the "**launcher**". //! The "**launcher**" starts the actual server and sends a message back //! to the main application. The main application waits until receives -//! the message [`ApiServerJobStarted`](crate::bootstrap::jobs::tracker_apis::ApiServerJobStarted) +//! the message [`ApiServerJobStarted`] //! from the "**launcher**". //! //! The "**launcher**" is an intermediary thread that decouples the API server diff --git a/src/lib.rs b/src/lib.rs index c862d373..c2e70a8b 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -384,7 +384,7 @@ //! //! Torrust Tracker has four main components: //! -//! - The core [`tracker`](crate::tracker) +//! - The core [`tracker`] //! - The tracker REST [`API`](crate::servers::apis) //! - The [`UDP`](crate::servers::udp) tracker //! - The [`HTTP`](crate::servers::http) tracker @@ -402,7 +402,7 @@ //! - Statistics //! - Persistence //! -//! See [`tracker`](crate::tracker) for more details on the [`tracker`](crate::tracker) module. +//! See [`tracker`] for more details on the [`tracker`] module. //! //! ## Tracker API //! diff --git a/src/servers/apis/mod.rs b/src/servers/apis/mod.rs index afed9ff1..5f8c581d 100644 --- a/src/servers/apis/mod.rs +++ b/src/servers/apis/mod.rs @@ -3,7 +3,7 @@ //! > **NOTICE**: This API should not be exposed directly to the internet, it is //! intended for internal use only. //! -//! Endpoints for the latest API: [v1](crate::servers::apis::v1). +//! Endpoints for the latest API: [v1]. //! //! All endpoints require an authorization token which must be set in the //! configuration before running the tracker. The default configuration uses @@ -139,13 +139,13 @@ //! //! The API is versioned and each version has its own module. //! The API server runs all the API versions on the same server using -//! the same port. Currently there is only one API version: [v1](crate::servers::apis::v1) +//! the same port. Currently there is only one API version: [v1] //! but a version [`v2`](https://github.com/torrust/torrust-tracker/issues/144) //! is planned. //! //! # Endpoints //! -//! Refer to the [v1](crate::servers::apis::v1) module for the list of available +//! Refer to the [v1] module for the list of available //! API endpoints. //! //! # Documentation diff --git a/src/servers/apis/v1/context/auth_key/handlers.rs b/src/servers/apis/v1/context/auth_key/handlers.rs index 85158c69..d6a2992f 100644 --- a/src/servers/apis/v1/context/auth_key/handlers.rs +++ b/src/servers/apis/v1/context/auth_key/handlers.rs @@ -19,7 +19,7 @@ use crate::tracker::Tracker; /// /// It returns two types of responses: /// -/// - `200` with an json [`AuthKey`](crate::servers::apis::v1::context::auth_key::resources::AuthKey) +/// - `200` with an json [`AuthKey`] /// resource. If the key was generated successfully. /// - `500` with serialized error in debug format. If the key couldn't be /// generated. diff --git a/src/servers/apis/v1/context/stats/handlers.rs b/src/servers/apis/v1/context/stats/handlers.rs index dfb983f7..bb531c80 100644 --- a/src/servers/apis/v1/context/stats/handlers.rs +++ b/src/servers/apis/v1/context/stats/handlers.rs @@ -12,7 +12,7 @@ use crate::tracker::Tracker; /// It handles the request to get the tracker statistics. /// -/// It returns a `200` response with a json [`Stats`](crate::servers::apis::v1::context::stats::resources::Stats) +/// It returns a `200` response with a json [`Stats`] /// /// Refer to the [API endpoint documentation](crate::servers::apis::v1::context::stats#get-tracker-statistics) /// for more information about this endpoint. diff --git a/src/servers/apis/v1/context/stats/responses.rs b/src/servers/apis/v1/context/stats/responses.rs index a4dad77e..e8e7cb84 100644 --- a/src/servers/apis/v1/context/stats/responses.rs +++ b/src/servers/apis/v1/context/stats/responses.rs @@ -5,7 +5,7 @@ use axum::response::Json; use super::resources::Stats; use crate::tracker::services::statistics::TrackerMetrics; -/// `200` response that contains the [`Stats`](crate::servers::apis::v1::context::stats::resources::Stats) resource as json. +/// `200` response that contains the [`Stats`] resource as json. pub fn stats_response(tracker_metrics: TrackerMetrics) -> Json { Json(Stats::from(tracker_metrics)) } diff --git a/src/servers/apis/v1/context/torrent/handlers.rs b/src/servers/apis/v1/context/torrent/handlers.rs index 002d4356..1f38ab47 100644 --- a/src/servers/apis/v1/context/torrent/handlers.rs +++ b/src/servers/apis/v1/context/torrent/handlers.rs @@ -51,7 +51,7 @@ pub struct PaginationParams { /// It handles the request to get a list of torrents. /// /// It returns a `200` response with a json array with -/// [`ListItem`](crate::servers::apis::v1::context::torrent::resources::torrent::ListItem) +/// [`ListItem`] /// resources. /// /// Refer to the [API endpoint documentation](crate::servers::apis::v1::context::torrent#list-torrents) diff --git a/src/servers/apis/v1/context/torrent/resources/peer.rs b/src/servers/apis/v1/context/torrent/resources/peer.rs index 539637b3..4989cec5 100644 --- a/src/servers/apis/v1/context/torrent/resources/peer.rs +++ b/src/servers/apis/v1/context/torrent/resources/peer.rs @@ -6,7 +6,7 @@ use crate::tracker; /// `Peer` API resource. #[derive(Serialize, Deserialize, Debug, PartialEq, Eq)] pub struct Peer { - /// The peer's ID. See [`Id`](crate::servers::apis::v1::context::torrent::resources::peer::Id). + /// The peer's ID. See [`Id`]. pub peer_id: Id, /// The peer's socket address. For example: `192.168.1.88:17548`. pub peer_addr: String, diff --git a/src/servers/apis/v1/context/torrent/resources/torrent.rs b/src/servers/apis/v1/context/torrent/resources/torrent.rs index c9dbd1c0..ebebda79 100644 --- a/src/servers/apis/v1/context/torrent/resources/torrent.rs +++ b/src/servers/apis/v1/context/torrent/resources/torrent.rs @@ -59,8 +59,8 @@ impl ListItem { } } -/// Maps an array of the domain type [`BasicInfo`](crate::tracker::services::torrent::BasicInfo) -/// to the API resource type [`ListItem`](crate::servers::apis::v1::context::torrent::resources::torrent::ListItem). +/// Maps an array of the domain type [`BasicInfo`] +/// to the API resource type [`ListItem`]. #[must_use] pub fn to_resource(basic_info_vec: &[BasicInfo]) -> Vec { basic_info_vec diff --git a/src/servers/apis/v1/context/torrent/responses.rs b/src/servers/apis/v1/context/torrent/responses.rs index d3be092e..99c2fcae 100644 --- a/src/servers/apis/v1/context/torrent/responses.rs +++ b/src/servers/apis/v1/context/torrent/responses.rs @@ -7,14 +7,14 @@ use super::resources::torrent::{ListItem, Torrent}; use crate::tracker::services::torrent::{BasicInfo, Info}; /// `200` response that contains an array of -/// [`ListItem`](crate::servers::apis::v1::context::torrent::resources::torrent::ListItem) +/// [`ListItem`] /// resources as json. pub fn torrent_list_response(basic_infos: &[BasicInfo]) -> Json> { Json(ListItem::new_vec(basic_infos)) } /// `200` response that contains a -/// [`Torrent`](crate::servers::apis::v1::context::torrent::resources::torrent::Torrent) +/// [`Torrent`] /// resources as json. pub fn torrent_info_response(info: Info) -> Json { Json(Torrent::from(info)) diff --git a/src/servers/http/mod.rs b/src/servers/http/mod.rs index 067e88fd..e6dd808b 100644 --- a/src/servers/http/mod.rs +++ b/src/servers/http/mod.rs @@ -78,13 +78,13 @@ //! > **NOTICE**: the `info_hash` parameter is NOT a `URL` encoded string param. //! It is percent encode of the raw `info_hash` bytes (40 bytes). URL `GET` params //! can contain any bytes, not only well-formed UTF-8. The `info_hash` is a -//! 20-byte SHA1. Check the [`percent_encoding`](crate::servers::http::percent_encoding) +//! 20-byte SHA1. Check the [`percent_encoding`] //! module to know more about the encoding. //! //! > **NOTICE**: the `peer_id` parameter is NOT a `URL` encoded string param. //! It is percent encode of the raw peer ID bytes (20 bytes). URL `GET` params //! can contain any bytes, not only well-formed UTF-8. The `info_hash` is a -//! 20-byte SHA1. Check the [`percent_encoding`](crate::servers::http::percent_encoding) +//! 20-byte SHA1. Check the [`percent_encoding`] //! module to know more about the encoding. //! //! > **NOTICE**: by default, the tracker returns the non-compact peer list when diff --git a/src/servers/http/percent_encoding.rs b/src/servers/http/percent_encoding.rs index c8f0f7f1..b674f047 100644 --- a/src/servers/http/percent_encoding.rs +++ b/src/servers/http/percent_encoding.rs @@ -19,7 +19,7 @@ use crate::shared::bit_torrent::info_hash::{ConversionError, InfoHash}; use crate::tracker::peer::{self, IdConversionError}; /// Percent decodes a percent encoded infohash. Internally an -/// [`InfoHash`](crate::shared::bit_torrent::info_hash::InfoHash) is a 20-byte array. +/// [`InfoHash`] is a 20-byte array. /// /// For example, given the infohash `3b245504cf5f11bbdbe1201cea6a6bf45aee1bc0`, /// it's percent encoded representation is `%3B%24U%04%CF%5F%11%BB%DB%E1%20%1C%EAjk%F4Z%EE%1B%C0`. @@ -43,7 +43,7 @@ use crate::tracker::peer::{self, IdConversionError}; /// # Errors /// /// Will return `Err` if the decoded bytes do not represent a valid -/// [`InfoHash`](crate::shared::bit_torrent::info_hash::InfoHash). +/// [`InfoHash`]. pub fn percent_decode_info_hash(raw_info_hash: &str) -> Result { let bytes = percent_encoding::percent_decode_str(raw_info_hash).collect::>(); InfoHash::try_from(bytes) @@ -70,7 +70,7 @@ pub fn percent_decode_info_hash(raw_info_hash: &str) -> Result Result { let bytes = percent_encoding::percent_decode_str(raw_peer_id).collect::>(); peer::Id::try_from(bytes) diff --git a/src/servers/http/v1/extractors/announce_request.rs b/src/servers/http/v1/extractors/announce_request.rs index 5d947ef9..1778f78c 100644 --- a/src/servers/http/v1/extractors/announce_request.rs +++ b/src/servers/http/v1/extractors/announce_request.rs @@ -1,7 +1,7 @@ -//! Axum [`extractor`](axum::extract) for the [`Announce`](crate::servers::http::v1::requests::announce::Announce) +//! Axum [`extractor`](axum::extract) for the [`Announce`] //! request. //! -//! It parses the query parameters returning an [`Announce`](crate::servers::http::v1::requests::announce::Announce) +//! It parses the query parameters returning an [`Announce`] //! request. //! //! Refer to [`Announce`](crate::servers::http::v1::requests::announce) for more @@ -38,7 +38,7 @@ use crate::servers::http::v1::query::Query; use crate::servers::http::v1::requests::announce::{Announce, ParseAnnounceQueryError}; use crate::servers::http::v1::responses; -/// Extractor for the [`Announce`](crate::servers::http::v1::requests::announce::Announce) +/// Extractor for the [`Announce`] /// request. pub struct ExtractRequest(pub Announce); diff --git a/src/servers/http/v1/extractors/authentication_key.rs b/src/servers/http/v1/extractors/authentication_key.rs index 20dc1c90..3f2a2a24 100644 --- a/src/servers/http/v1/extractors/authentication_key.rs +++ b/src/servers/http/v1/extractors/authentication_key.rs @@ -1,4 +1,4 @@ -//! Axum [`extractor`](axum::extract) to extract the authentication [`Key`](crate::tracker::auth::Key) +//! Axum [`extractor`](axum::extract) to extract the authentication [`Key`] //! from the URL path. //! //! It's only used when the tracker is running in private mode. @@ -55,7 +55,7 @@ use crate::servers::http::v1::handlers::common::auth; use crate::servers::http::v1::responses; use crate::tracker::auth::Key; -/// Extractor for the [`Key`](crate::tracker::auth::Key) struct. +/// Extractor for the [`Key`] struct. pub struct Extract(pub Key); #[derive(Deserialize)] diff --git a/src/servers/http/v1/extractors/client_ip_sources.rs b/src/servers/http/v1/extractors/client_ip_sources.rs index f0430040..18eff26b 100644 --- a/src/servers/http/v1/extractors/client_ip_sources.rs +++ b/src/servers/http/v1/extractors/client_ip_sources.rs @@ -45,7 +45,7 @@ use axum_client_ip::RightmostXForwardedFor; use crate::servers::http::v1::services::peer_ip_resolver::ClientIpSources; -/// Extractor for the [`ClientIpSources`](crate::servers::http::v1::services::peer_ip_resolver::ClientIpSources) +/// Extractor for the [`ClientIpSources`] /// struct. pub struct Extract(pub ClientIpSources); diff --git a/src/servers/http/v1/extractors/scrape_request.rs b/src/servers/http/v1/extractors/scrape_request.rs index 63c4dba6..1437ede4 100644 --- a/src/servers/http/v1/extractors/scrape_request.rs +++ b/src/servers/http/v1/extractors/scrape_request.rs @@ -1,7 +1,7 @@ -//! Axum [`extractor`](axum::extract) for the [`Scrape`](crate::servers::http::v1::requests::scrape::Scrape) +//! Axum [`extractor`](axum::extract) for the [`Scrape`] //! request. //! -//! It parses the query parameters returning an [`Scrape`](crate::servers::http::v1::requests::scrape::Scrape) +//! It parses the query parameters returning an [`Scrape`] //! request. //! //! Refer to [`Scrape`](crate::servers::http::v1::requests::scrape) for more @@ -38,7 +38,7 @@ use crate::servers::http::v1::query::Query; use crate::servers::http::v1::requests::scrape::{ParseScrapeQueryError, Scrape}; use crate::servers::http::v1::responses; -/// Extractor for the [`Scrape`](crate::servers::http::v1::requests::scrape::Scrape) +/// Extractor for the [`Scrape`] /// request. pub struct ExtractRequest(pub Scrape); diff --git a/src/servers/http/v1/handlers/common/auth.rs b/src/servers/http/v1/handlers/common/auth.rs index f41635d6..720ed765 100644 --- a/src/servers/http/v1/handlers/common/auth.rs +++ b/src/servers/http/v1/handlers/common/auth.rs @@ -1,5 +1,5 @@ //! HTTP server authentication error and conversion to -//! [`responses::error::Error`](crate::servers::http::v1::responses::error::Error) +//! [`responses::error::Error`] //! response. use std::panic::Location; diff --git a/src/servers/http/v1/handlers/common/peer_ip.rs b/src/servers/http/v1/handlers/common/peer_ip.rs index d65efbc7..5602bd26 100644 --- a/src/servers/http/v1/handlers/common/peer_ip.rs +++ b/src/servers/http/v1/handlers/common/peer_ip.rs @@ -2,7 +2,7 @@ //! //! The HTTP tracker may fail to resolve the peer IP address. This module //! contains the logic to convert those -//! [`PeerIpResolutionError`](crate::servers::http::v1::services::peer_ip_resolver::PeerIpResolutionError) +//! [`PeerIpResolutionError`] //! errors into responses. use crate::servers::http::v1::responses; use crate::servers::http::v1::services::peer_ip_resolver::PeerIpResolutionError; diff --git a/src/servers/http/v1/query.rs b/src/servers/http/v1/query.rs index 745796b6..3a078daa 100644 --- a/src/servers/http/v1/query.rs +++ b/src/servers/http/v1/query.rs @@ -93,7 +93,7 @@ impl Query { } } -/// This error can be returned when parsing a [`Query`](crate::servers::http::v1::query::Query) +/// This error can be returned when parsing a [`Query`] /// from a string. #[derive(Error, Debug)] pub enum ParseQueryError { diff --git a/src/servers/http/v1/responses/announce.rs b/src/servers/http/v1/responses/announce.rs index 3596275f..f45f4c82 100644 --- a/src/servers/http/v1/responses/announce.rs +++ b/src/servers/http/v1/responses/announce.rs @@ -91,7 +91,7 @@ pub struct NonCompact { pub peers: Vec, } -/// Peer information in the [`NonCompact`](crate::servers::http::v1::responses::announce::NonCompact) +/// Peer information in the [`NonCompact`] /// response. /// /// ```rust @@ -261,7 +261,7 @@ pub struct Compact { pub peers: Vec, } -/// Compact peer. It's used in the [`Compact`](crate::servers::http::v1::responses::announce::Compact) +/// Compact peer. It's used in the [`Compact`] /// response. /// /// _"To reduce the size of tracker responses and to reduce memory and diff --git a/src/servers/http/v1/services/announce.rs b/src/servers/http/v1/services/announce.rs index 4c1b262b..ddb3b122 100644 --- a/src/servers/http/v1/services/announce.rs +++ b/src/servers/http/v1/services/announce.rs @@ -3,10 +3,10 @@ //! The service is responsible for handling the `announce` requests. //! //! It delegates the `announce` logic to the [`Tracker`](crate::tracker::Tracker::announce) -//! and it returns the [`AnnounceData`](crate::tracker::AnnounceData) returned -//! by the [`Tracker`](crate::tracker::Tracker). +//! and it returns the [`AnnounceData`] returned +//! by the [`Tracker`]. //! -//! It also sends an [`statistics::Event`](crate::tracker::statistics::Event) +//! It also sends an [`statistics::Event`] //! because events are specific for the HTTP tracker. use std::net::IpAddr; use std::sync::Arc; diff --git a/src/servers/http/v1/services/scrape.rs b/src/servers/http/v1/services/scrape.rs index 240680ca..adea2808 100644 --- a/src/servers/http/v1/services/scrape.rs +++ b/src/servers/http/v1/services/scrape.rs @@ -3,10 +3,10 @@ //! The service is responsible for handling the `scrape` requests. //! //! It delegates the `scrape` logic to the [`Tracker`](crate::tracker::Tracker::scrape) -//! and it returns the [`ScrapeData`](crate::tracker::ScrapeData) returned -//! by the [`Tracker`](crate::tracker::Tracker). +//! and it returns the [`ScrapeData`] returned +//! by the [`Tracker`]. //! -//! It also sends an [`statistics::Event`](crate::tracker::statistics::Event) +//! It also sends an [`statistics::Event`] //! because events are specific for the HTTP tracker. use std::net::IpAddr; use std::sync::Arc; diff --git a/src/servers/udp/mod.rs b/src/servers/udp/mod.rs index edbfd77d..63086721 100644 --- a/src/servers/udp/mod.rs +++ b/src/servers/udp/mod.rs @@ -109,7 +109,7 @@ //! connection ID = hash(client IP + current time slot + secret seed) //! ``` //! -//! The BEP-15 recommends a two-minute time slot. Refer to [`connection_cookie`](crate::servers::udp::connection_cookie) +//! The BEP-15 recommends a two-minute time slot. Refer to [`connection_cookie`] //! for more information about the connection ID generation with this method. //! //! #### Connect Request diff --git a/src/servers/udp/peer_builder.rs b/src/servers/udp/peer_builder.rs index ac62a7ec..7c83089b 100644 --- a/src/servers/udp/peer_builder.rs +++ b/src/servers/udp/peer_builder.rs @@ -5,7 +5,7 @@ use super::request::AnnounceWrapper; use crate::shared::clock::{Current, Time}; use crate::tracker::peer::{Id, Peer}; -/// Extracts the [`Peer`](crate::tracker::peer::Peer) info from the +/// Extracts the [`Peer`] info from the /// announce request. /// /// # Arguments diff --git a/src/servers/udp/request.rs b/src/servers/udp/request.rs index 0afa0280..f655fd36 100644 --- a/src/servers/udp/request.rs +++ b/src/servers/udp/request.rs @@ -9,9 +9,9 @@ use aquatic_udp_protocol::AnnounceRequest; use crate::shared::bit_torrent::info_hash::InfoHash; -/// Wrapper around [`AnnounceRequest`](aquatic_udp_protocol::request::AnnounceRequest). +/// Wrapper around [`AnnounceRequest`]. pub struct AnnounceWrapper { - /// [`AnnounceRequest`](aquatic_udp_protocol::request::AnnounceRequest) to wrap. + /// [`AnnounceRequest`] to wrap. pub announce_request: AnnounceRequest, /// Info hash of the torrent. pub info_hash: InfoHash, diff --git a/src/servers/udp/server.rs b/src/servers/udp/server.rs index 5e5c9870..428b76fa 100644 --- a/src/servers/udp/server.rs +++ b/src/servers/udp/server.rs @@ -2,9 +2,9 @@ //! //! There are two main types in this module: //! -//! - [`UdpServer`](crate::servers::udp::server::UdpServer): a controller to +//! - [`UdpServer`]: a controller to //! start and stop the server. -//! - [`Udp`](crate::servers::udp::server::Udp): the server launcher. +//! - [`Udp`]: the server launcher. //! //! The `UdpServer` is an state machine for a given configuration. This struct //! represents concrete configuration and state. It allows to start and @@ -42,7 +42,7 @@ use crate::tracker::Tracker; /// /// Some errors triggered while stopping the server are: /// -/// - The [`UdpServer`](crate::servers::udp::server::UdpServer) cannot send the +/// - The [`UdpServer`] cannot send the /// shutdown signal to the spawned UDP service thread. #[derive(Debug)] pub enum Error { diff --git a/src/tracker/auth.rs b/src/tracker/auth.rs index 466187af..2759c8d0 100644 --- a/src/tracker/auth.rs +++ b/src/tracker/auth.rs @@ -4,7 +4,7 @@ //! Tracker keys are tokens used to authenticate the tracker clients when the tracker runs //! in `private` or `private_listed` modes. //! -//! There are services to [`generate`](crate::tracker::auth::generate) and [`verify`](crate::tracker::auth::verify) authentication keys. +//! There are services to [`generate`] and [`verify`] authentication keys. //! //! Authentication keys are used only by [`HTTP`](crate::servers::http) trackers. All keys have an expiration time, that means //! they are only valid during a period of time. After that time the expiring key will no longer be valid. @@ -53,7 +53,7 @@ use crate::shared::bit_torrent::common::AUTH_KEY_LENGTH; use crate::shared::clock::{convert_from_timestamp_to_datetime_utc, Current, DurationSinceUnixEpoch, Time, TimeNow}; #[must_use] -/// It generates a new random 32-char authentication [`ExpiringKey`](crate::tracker::auth::ExpiringKey) +/// It generates a new random 32-char authentication [`ExpiringKey`] /// /// # Panics /// @@ -73,7 +73,7 @@ pub fn generate(lifetime: Duration) -> ExpiringKey { } } -/// It verifies an [`ExpiringKey`](crate::tracker::auth::ExpiringKey). It checks if the expiration date has passed. +/// It verifies an [`ExpiringKey`]. It checks if the expiration date has passed. /// /// # Errors /// @@ -164,7 +164,7 @@ impl FromStr for Key { } } -/// Verification error. Error returned when an [`ExpiringKey`](crate::tracker::auth::ExpiringKey) cannot be verified with the [`verify(...)`](crate::tracker::auth::verify) function. +/// Verification error. Error returned when an [`ExpiringKey`] cannot be verified with the [`verify(...)`](crate::tracker::auth::verify) function. /// #[derive(Debug, Error)] #[allow(dead_code)] diff --git a/src/tracker/databases/mod.rs b/src/tracker/databases/mod.rs index e0a26be2..90288049 100644 --- a/src/tracker/databases/mod.rs +++ b/src/tracker/databases/mod.rs @@ -1,6 +1,6 @@ //! The persistence module. //! -//! Persistence is currently implemented with one [`Database`](crate::tracker::databases::Database) trait. +//! Persistence is currently implemented with one [`Database`] trait. //! //! There are two implementations of the trait (two drivers): //! @@ -115,7 +115,7 @@ pub trait Database: Sync + Send { /// It loads the torrent metrics data from the database. /// /// It returns an array of tuples with the torrent - /// [`InfoHash`](crate::shared::bit_torrent::info_hash::InfoHash) and the + /// [`InfoHash`] and the /// [`completed`](crate::tracker::torrent::Entry::completed) counter /// which is the number of times the torrent has been downloaded. /// See [`Entry::completed`](crate::tracker::torrent::Entry::completed). diff --git a/src/tracker/mod.rs b/src/tracker/mod.rs index 040751e1..94d75a8c 100644 --- a/src/tracker/mod.rs +++ b/src/tracker/mod.rs @@ -52,7 +52,7 @@ //! The tracker responds to the peer with the list of other peers in the swarm so that //! the peer can contact them to start downloading pieces of the file from them. //! -//! Once you have instantiated the `Tracker` you can `announce` a new [`peer`](crate::tracker::peer::Peer) with: +//! Once you have instantiated the `Tracker` you can `announce` a new [`Peer`] with: //! //! ```rust,no_run //! use torrust_tracker::tracker::peer; @@ -183,7 +183,7 @@ //! //! ## Torrents //! -//! The [`torrent`](crate::tracker::torrent) module contains all the data structures stored by the `Tracker` except for peers. +//! The [`torrent`] module contains all the data structures stored by the `Tracker` except for peers. //! //! We can represent the data stored in memory internally by the `Tracker` with this JSON object: //! @@ -222,7 +222,7 @@ //! they have a full version of the torrent data, and they can provide the full data to other peers. That's why they are also known as "seeders". //! - `peers`: an indexed and orderer list of peer for the torrent. Each peer contains the data received from the peer in the `announce` request. //! -//! The [`torrent`](crate::tracker::torrent) module not only contains the original data obtained from peer via `announce` requests, it also contains +//! The [`torrent`] module not only contains the original data obtained from peer via `announce` requests, it also contains //! aggregate data that can be derived from the original data. For example: //! //! ```rust,no_run @@ -244,7 +244,7 @@ //! `SwarmStats` struct follows name conventions for `scrape` responses. See [BEP 48](https://www.bittorrent.org/beps/bep_0048.html), while `SwarmStats` //! is used for the rest of cases. //! -//! Refer to [`torrent`](crate::tracker::torrent) module for more details about these data structures. +//! Refer to [`torrent`] module for more details about these data structures. //! //! ## Peers //! @@ -310,7 +310,7 @@ //! `c1277613db1d28709b034a017ab2cae4be07ae10` is the torrent infohash and `completed` contains the number of peers //! that have a full version of the torrent data, also known as seeders. //! -//! Refer to [`peer`](crate::tracker::peer) module for more information about peers. +//! Refer to [`peer`] module for more information about peers. //! //! # Configuration //! @@ -348,7 +348,7 @@ //! //! Services can include extra features like pagination, for example. //! -//! Refer to [`services`](crate::tracker::services) module for more information about services. +//! Refer to [`services`] module for more information about services. //! //! # Authentication //! @@ -363,7 +363,7 @@ //! //! To learn more about tracker authentication, refer to the following modules : //! -//! - [`auth`](crate::tracker::auth) module. +//! - [`auth`] module. //! - [`tracker`](crate::tracker) module. //! - [`http`](crate::servers::http) module. //! @@ -417,7 +417,7 @@ //! tracker.send_stats_event(statistics::Event::Tcp4Announce).await //! ``` //! -//! Refer to [`statistics`](crate::tracker::statistics) module for more information about statistics. +//! Refer to [`statistics`] module for more information about statistics. //! //! # Persistence //! @@ -430,7 +430,7 @@ //! - Torrent whitelist //! - Torrent metrics //! -//! Refer to [`databases`](crate::tracker::databases) module for more information about persistence. +//! Refer to [`databases`] module for more information about persistence. pub mod auth; pub mod databases; pub mod error; @@ -753,7 +753,7 @@ impl Tracker { } /// It calculates and returns the general `Tracker` - /// [`TorrentsMetrics`](crate::tracker::TorrentsMetrics) + /// [`TorrentsMetrics`] /// /// # Context: Tracker pub async fn get_torrents_metrics(&self) -> TorrentsMetrics { diff --git a/src/tracker/services/statistics/mod.rs b/src/tracker/services/statistics/mod.rs index 3761e38d..3ef8b52b 100644 --- a/src/tracker/services/statistics/mod.rs +++ b/src/tracker/services/statistics/mod.rs @@ -3,7 +3,7 @@ //! It includes: //! //! - A [`factory`](crate::tracker::services::statistics::setup::factory) function to build the structs needed to collect the tracker metrics. -//! - A [`get_metrics`](crate::tracker::services::statistics::get_metrics) service to get the [`tracker metrics`](crate::tracker::statistics::Metrics). +//! - A [`get_metrics`] service to get the [`tracker metrics`](crate::tracker::statistics::Metrics). //! //! Tracker metrics are collected using a Publisher-Subscribe pattern. //! @@ -57,7 +57,7 @@ pub struct TrackerMetrics { pub protocol_metrics: Metrics, } -/// It returns all the [`TrackerMetrics`](crate::tracker::services::statistics::TrackerMetrics) +/// It returns all the [`TrackerMetrics`] pub async fn get_metrics(tracker: Arc) -> TrackerMetrics { let torrents_metrics = tracker.get_torrents_metrics().await; let stats = tracker.get_stats().await; diff --git a/src/tracker/services/statistics/setup.rs b/src/tracker/services/statistics/setup.rs index b8d325ab..4bf5a827 100644 --- a/src/tracker/services/statistics/setup.rs +++ b/src/tracker/services/statistics/setup.rs @@ -1,6 +1,6 @@ //! Setup for the tracker statistics. //! -//! The [`factory`](crate::tracker::services::statistics::setup::factory) function builds the structs needed for handling the tracker metrics. +//! The [`factory`] function builds the structs needed for handling the tracker metrics. use crate::tracker::statistics; /// It builds the structs needed for handling the tracker metrics. diff --git a/src/tracker/services/torrent.rs b/src/tracker/services/torrent.rs index 0db044d0..934fa6b7 100644 --- a/src/tracker/services/torrent.rs +++ b/src/tracker/services/torrent.rs @@ -2,8 +2,8 @@ //! //! There are two services: //! -//! - [`get_torrent_info`](crate::tracker::services::torrent::get_torrent_info): it returns all the data about one torrent. -//! - [`get_torrents`](crate::tracker::services::torrent::get_torrents): it returns data about some torrent in bulk excluding the peer list. +//! - [`get_torrent_info`]: it returns all the data about one torrent. +//! - [`get_torrents`]: it returns data about some torrent in bulk excluding the peer list. use std::sync::Arc; use serde::Deserialize; @@ -29,7 +29,7 @@ pub struct Info { /// It contains only part of the information the tracker has about a torrent /// -/// It contains the same data as [Info](crate::tracker::services::torrent::Info) but without the list of peers in the swarm. +/// It contains the same data as [Info] but without the list of peers in the swarm. #[derive(Debug, PartialEq, Clone)] pub struct BasicInfo { /// The infohash of the torrent this data is related to @@ -91,7 +91,7 @@ impl Default for Pagination { } } -/// It returns all the information the tracker has about one torrent in a [Info](crate::tracker::services::torrent::Info) struct. +/// It returns all the information the tracker has about one torrent in a [Info] struct. pub async fn get_torrent_info(tracker: Arc, info_hash: &InfoHash) -> Option { let db = tracker.get_torrents().await; @@ -116,7 +116,7 @@ pub async fn get_torrent_info(tracker: Arc, info_hash: &InfoHash) -> Op }) } -/// It returns all the information the tracker has about multiple torrents in a [`BasicInfo`](crate::tracker::services::torrent::BasicInfo) struct, excluding the peer list. +/// It returns all the information the tracker has about multiple torrents in a [`BasicInfo`] struct, excluding the peer list. pub async fn get_torrents(tracker: Arc, pagination: &Pagination) -> Vec { let db = tracker.get_torrents().await; diff --git a/src/tracker/torrent.rs b/src/tracker/torrent.rs index 4f7e28b6..de520aeb 100644 --- a/src/tracker/torrent.rs +++ b/src/tracker/torrent.rs @@ -2,8 +2,8 @@ //! //! There are to main data structures: //! -//! - A torrent [`Entry`](crate::tracker::torrent::Entry): it contains all the information stored by the tracker for one torrent. -//! - The [`SwarmMetadata`](crate::tracker::torrent::SwarmMetadata): it contains aggregate information that can me derived from the torrent entries. +//! - A torrent [`Entry`]: it contains all the information stored by the tracker for one torrent. +//! - The [`SwarmMetadata`]: it contains aggregate information that can me derived from the torrent entries. //! //! A "swarm" is a network of peers that are trying to download the same torrent. //! @@ -27,7 +27,7 @@ //! - The number of peers that have NOT completed downloading the torrent and are still active, that means they are actively participating in the network. //! Peer that don not have a full copy of the torrent data are called "leechers". //! -//! > **NOTICE**: that both [`SwarmMetadata`](crate::tracker::torrent::SwarmMetadata) and [`SwarmStats`](crate::tracker::torrent::SwarmStats) contain the same information. [`SwarmMetadata`](crate::tracker::torrent::SwarmMetadata) is using the names used on [BEP 48: Tracker Protocol Extension: Scrape](https://www.bittorrent.org/beps/bep_0048.html). +//! > **NOTICE**: that both [`SwarmMetadata`] and [`SwarmStats`] contain the same information. [`SwarmMetadata`] is using the names used on [BEP 48: Tracker Protocol Extension: Scrape](https://www.bittorrent.org/beps/bep_0048.html). use std::time::Duration; use aquatic_udp_protocol::AnnounceEvent; From ccfb06fbc8fe0a35aeaf4d6fdca6ce9ee4e67ec6 Mon Sep 17 00:00:00 2001 From: Cameron Garnham Date: Thu, 12 Oct 2023 10:55:09 +0200 Subject: [PATCH 5/5] ci: deny doc warnings --- .github/workflows/testing.yaml | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/.github/workflows/testing.yaml b/.github/workflows/testing.yaml index 3ae18e4d..f60f03e5 100644 --- a/.github/workflows/testing.yaml +++ b/.github/workflows/testing.yaml @@ -65,6 +65,13 @@ jobs: name: Run Lint Checks run: cargo clippy --tests --benches --examples --workspace --all-targets --all-features -- -D clippy::correctness -D clippy::suspicious -D clippy::complexity -D clippy::perf -D clippy::style -D clippy::pedantic + - id: docs + name: Lint Documentation + env: + RUSTDOCFLAGS: "-D warnings" + run: cargo doc --no-deps --bins --examples --workspace --all-features + + unit: name: Units runs-on: ubuntu-latest @@ -96,10 +103,6 @@ jobs: with: tool: cargo-llvm-cov, cargo-nextest - - id: docs - name: Build Documentation - run: cargo doc --no-deps --bins --examples --workspace --all-features - - id: test-docs name: Run Documentation Tests run: cargo test --doc