diff --git a/README.md b/README.md index 6d611d9a5..671a484e6 100644 --- a/README.md +++ b/README.md @@ -40,12 +40,12 @@ Protocols: Integrations: -- [ ] Monitoring (Prometheus). +- [x] Monitoring (Prometheus). Utils: -- [ ] Tracker client. -- [ ] Tracker checker. +- [ ] Tracker client. WIP. +- [ ] Tracker checker. WIP. Others: @@ -65,6 +65,10 @@ Others: - [BEP 27]: Private Torrents. - [BEP 48]: Tracker Protocol Extension: Scrape. +## Architecture + +![Torrust Tracker Layers with main packages](./docs/media/packages/torrust-tracker-layers-with-packages.png) + ## Getting Started ### Container Version @@ -167,6 +171,8 @@ Some specific sections: - [Tracker (HTTP/TLS)][HTTP] - [Tracker (UDP)][UDP] +There is also extra documentation in the [docs](./docs) folder. + ## Benchmarking - [Benchmarking](./docs/benchmarking.md) diff --git a/cSpell.json b/cSpell.json index dcdcc9cf6..3121d6175 100644 --- a/cSpell.json +++ b/cSpell.json @@ -15,6 +15,7 @@ "bdecode", "bencode", "bencoded", + "bencoding", "beps", "binascii", "binstall", diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..873f3758b --- /dev/null +++ b/docs/index.md @@ -0,0 +1,11 @@ +# Torrust Tracker Documentation + +For more detailed instructions, please view our [crate documentation][docs]. + +- [Benchmarking](benchmarking.md) +- [Containers](containers.md) +- [Packages](packages.md) +- [Profiling](profiling.md) +- [Releases process](release_process.md) + +[docs]: https://docs.rs/torrust-tracker/latest/torrust_tracker/ diff --git a/docs/media/packages/packages-dependencies-http-tracker.png b/docs/media/packages/packages-dependencies-http-tracker.png new file mode 100644 index 000000000..45dbd9839 Binary files /dev/null and b/docs/media/packages/packages-dependencies-http-tracker.png differ diff --git a/docs/media/packages/packages-dependencies-udp-tracker.png b/docs/media/packages/packages-dependencies-udp-tracker.png new file mode 100644 index 000000000..57987a31e Binary files /dev/null and b/docs/media/packages/packages-dependencies-udp-tracker.png differ diff --git a/docs/media/packages/torrust-tracker-layers-with-packages.png b/docs/media/packages/torrust-tracker-layers-with-packages.png new file mode 100644 index 000000000..9da465806 Binary files /dev/null and b/docs/media/packages/torrust-tracker-layers-with-packages.png differ diff --git a/docs/media/torrust-tracker-components.png b/docs/media/torrust-tracker-components.png deleted file mode 100644 index 19fe3c0b8..000000000 Binary files a/docs/media/torrust-tracker-components.png and /dev/null differ diff --git a/docs/packages.md b/docs/packages.md new file mode 100644 index 000000000..118046a87 --- /dev/null +++ b/docs/packages.md @@ -0,0 +1,115 @@ +# Torrust Tracker Package Architecture + +- [Package Conventions](#package-conventions) +- [Package Catalog](#package-catalog) +- [Architectural Philosophy](#architectural-philosophy) +- [Protocol Implementation Details](#protocol-implementation-details) +- [Architectural Philosophy](#architectural-philosophy) + +```output +packages/ +├── axum-health-check-api-server +├── axum-http-tracker-server +├── axum-rest-tracker-api-server +├── axum-server +├── clock +├── configuration +├── http-protocol +├── http-tracker-core +├── located-error +├── primitives +├── rest-tracker-api-client +├── rest-tracker-api-core +├── server-lib +├── test-helpers +├── torrent-repository +├── tracker-client +├── tracker-core +├── udp-protocol +├── udp-tracker-core +└── udp-tracker-server +``` + +```output +console/ +└── tracker-client # Client for interacting with trackers +``` + +```output +contrib/ +└── bencode # Community-contributed Bencode utilities +``` + +## Package Conventions + +| Prefix | Responsibility | Dependencies | +|-----------------|-----------------------------------------|---------------------------| +| `axum-*` | HTTP server components using Axum | Axum framework | +| `*-server` | Server implementations | Corresponding *-core | +| `*-core` | Domain logic & business rules | Protocol implementations | +| `*-protocol` | BitTorrent protocol implementations | BitTorrent protocol | +| `udp-*` | UDP Protocol-specific implementations | Tracker core | +| `http-*` | HTTP Protocol-specific implementations | Tracker core | + +Key Architectural Principles: + +1. **Separation of Concerns**: Servers contain only network I/O logic. +2. **Protocol Compliance**: `*-protocol` packages strictly implement BEP specifications. +3. **Extensibility**: Core logic is framework-agnostic for easy protocol additions. + +## Package Catalog + +| Package | Description | Key Responsibilities | +|---------|-------------|----------------------| +| **axum-*** | | | +| `axum-server` | Base Axum HTTP server infrastructure | HTTP server lifecycle management | +| `axum-http-tracker-server` | BitTorrent HTTP tracker (BEP 3/23) | Handle announce/scrape requests | +| `axum-rest-tracker-api-server` | Management REST API | Tracker configuration & monitoring | +| `axum-health-check-api-server` | Health monitoring endpoint | System health reporting | +| **Core Components** | | | +| `http-tracker-core` | HTTP-specific implementation | Request validation, Response formatting | +| `udp-tracker-core` | UDP-specific implementation | Connectionless request handling | +| `tracker-core` | Central tracker logic | Peer management | +| **Protocols** | | | +| `http-protocol` | HTTP tracker protocol (BEP 3/23) | Announce/scrape request parsing | +| `udp-protocol` | UDP tracker protocol (BEP 15) | UDP message framing/parsing | +| **Domain** | | | +| `torrent-repository` | Torrent metadata storage | InfoHash management, Peer coordination | +| `configuration` | Runtime configuration | Config file parsing, Environment variables | +| `primitives` | Domain-specific types | InfoHash, PeerId, Byte handling | +| **Utilities** | | | +| `clock` | Time abstraction | Mockable time source for testing | +| `located-error` | Diagnostic errors | Error tracing with source locations | +| `test-helpers` | Testing utilities | Mock servers, Test data generation | +| **Client Tools** | | | +| `tracker-client` | CLI client | Tracker interaction/testing | +| `rest-tracker-api-client` | API client library | REST API integration | + +## Protocol Implementation Details + +### HTTP Tracker (BEP 3/23) + +- `http-protocol` implements: + - URL parameter parsing + - Response bencoding + - Error code mapping + - Compact peer formatting + +### UDP Tracker (BEP 15) + +- `udp-protocol` handles: + - Connection ID management + - Message framing (32-bit big-endian) + - Transaction ID tracking + - Error response codes + +## Architectural Philosophy + +1. **Testability**: Core packages have minimal dependencies for easy unit testing +2. **Observability**: Health checks and metrics built into server packages +3. **Modularity**: Protocol implementations decoupled from transport layers +4. **Extensibility**: New protocols can be added without modifying core logic + +![Torrust Tracker Architecture Diagram](./media/packages/torrust-tracker-layers-with-packages.png) + +> Diagram shows clean separation between network I/O (servers), protocol handling, and core tracker logic diff --git a/src/console/ci/e2e/runner.rs b/src/console/ci/e2e/runner.rs index 118ecda42..624878c70 100644 --- a/src/console/ci/e2e/runner.rs +++ b/src/console/ci/e2e/runner.rs @@ -137,7 +137,7 @@ fn load_tracker_configuration(args: &Args) -> anyhow::Result { } fn load_config_from_file(path: &PathBuf) -> anyhow::Result { - let config = std::fs::read_to_string(path).with_context(|| format!("CSan't read config file {path:?}"))?; + let config = std::fs::read_to_string(path).with_context(|| format!("CSan't read config file {}", path.display()))?; Ok(config) } diff --git a/src/lib.rs b/src/lib.rs index e947d2ab5..0aaf34fe4 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -36,7 +36,7 @@ //! - [API](#api) //! - [HTTP Tracker](#http-tracker) //! - [UDP Tracker](#udp-tracker) -//! - [Components](#components) +//! - [Packages](#packages) //! - [Implemented BEPs](#implemented-beps) //! - [Contributing](#contributing) //! - [Documentation](#documentation) @@ -401,16 +401,9 @@ //! //! - [BEP 15. UDP Tracker Protocol for `BitTorrent`](https://www.bittorrent.org/beps/bep_0015.html) //! -//! # Components +//! # Packages //! -//! Torrust Tracker has four main components: -//! -//! - The core tracker [`core`] -//! - The tracker REST [`API`](torrust_axum_rest_tracker_api_server) -//! - The [`UDP`](torrust_udp_tracker_server) tracker -//! - The [`HTTP`](torrust_axum_http_tracker_server) tracker -//! -//! ![Torrust Tracker Components](https://raw.githubusercontent.com/torrust/torrust-tracker/main/docs/media/torrust-tracker-components.png) +//! ![Torrust Tracker Layers with Main Packages](https://raw.githubusercontent.com/torrust/torrust-tracker/main/docs/media/packages/torrust-tracker-layers-with-packages.png) //! //! ## Core tracker //!