Skip to content

Commit d918e47

Browse files
josecelanojosecelano
committed
Merge #1337: Refactor packages: write docs
b76eff6 fix: clippy error (Jose Celano) a8224e8 docs: [#1290] add documentation for packages (Jose Celano) Pull request description: Refactor packages: write docs Added documentation for pacakges. ACKs for top commit: josecelano: ACK b76eff6 Tree-SHA512: 513adb54c9b5435e3fe3438a748ba2571d01f054004e0337635d23a0f16c9bae85fe66b427c99d87a7369a8563e6e6b748bd9854bd94b2130ca16e51be9d675a
2 parents 77c8395 + b76eff6 commit d918e47

10 files changed

+140
-14
lines changed

‎README.md

+9-3
Original file line numberDiff line numberDiff line change
@@ -40,12 +40,12 @@ Protocols:
4040

4141
Integrations:
4242

43-
- [ ] Monitoring (Prometheus).
43+
- [x] Monitoring (Prometheus).
4444

4545
Utils:
4646

47-
- [ ] Tracker client.
48-
- [ ] Tracker checker.
47+
- [ ] Tracker client. WIP.
48+
- [ ] Tracker checker. WIP.
4949

5050
Others:
5151

@@ -65,6 +65,10 @@ Others:
6565
- [BEP 27]: Private Torrents.
6666
- [BEP 48]: Tracker Protocol Extension: Scrape.
6767

68+
## Architecture
69+
70+
![Torrust Tracker Layers with main packages](./docs/media/packages/torrust-tracker-layers-with-packages.png)
71+
6872
## Getting Started
6973

7074
### Container Version
@@ -167,6 +171,8 @@ Some specific sections:
167171
- [Tracker (HTTP/TLS)][HTTP]
168172
- [Tracker (UDP)][UDP]
169173

174+
There is also extra documentation in the [docs](./docs) folder.
175+
170176
## Benchmarking
171177

172178
- [Benchmarking](./docs/benchmarking.md)

‎cSpell.json

+1
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
"bdecode",
1616
"bencode",
1717
"bencoded",
18+
"bencoding",
1819
"beps",
1920
"binascii",
2021
"binstall",

‎docs/index.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Torrust Tracker Documentation
2+
3+
For more detailed instructions, please view our [crate documentation][docs].
4+
5+
- [Benchmarking](benchmarking.md)
6+
- [Containers](containers.md)
7+
- [Packages](packages.md)
8+
- [Profiling](profiling.md)
9+
- [Releases process](release_process.md)
10+
11+
[docs]: https://docs.rs/torrust-tracker/latest/torrust_tracker/

‎docs/media/packages/packages-dependencies-http-tracker.png

32.4 KB
Loading

‎docs/media/packages/packages-dependencies-udp-tracker.png

32.8 KB
Loading

‎docs/media/packages/torrust-tracker-layers-with-packages.png

66.6 KB
Loading

‎docs/media/torrust-tracker-components.png

-82.9 KB
Binary file not shown.

‎docs/packages.md

+115
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Torrust Tracker Package Architecture
2+
3+
- [Package Conventions](#package-conventions)
4+
- [Package Catalog](#package-catalog)
5+
- [Architectural Philosophy](#architectural-philosophy)
6+
- [Protocol Implementation Details](#protocol-implementation-details)
7+
- [Architectural Philosophy](#architectural-philosophy)
8+
9+
```output
10+
packages/
11+
├── axum-health-check-api-server
12+
├── axum-http-tracker-server
13+
├── axum-rest-tracker-api-server
14+
├── axum-server
15+
├── clock
16+
├── configuration
17+
├── http-protocol
18+
├── http-tracker-core
19+
├── located-error
20+
├── primitives
21+
├── rest-tracker-api-client
22+
├── rest-tracker-api-core
23+
├── server-lib
24+
├── test-helpers
25+
├── torrent-repository
26+
├── tracker-client
27+
├── tracker-core
28+
├── udp-protocol
29+
├── udp-tracker-core
30+
└── udp-tracker-server
31+
```
32+
33+
```output
34+
console/
35+
└── tracker-client # Client for interacting with trackers
36+
```
37+
38+
```output
39+
contrib/
40+
└── bencode # Community-contributed Bencode utilities
41+
```
42+
43+
## Package Conventions
44+
45+
| Prefix | Responsibility | Dependencies |
46+
|-----------------|-----------------------------------------|---------------------------|
47+
| `axum-*` | HTTP server components using Axum | Axum framework |
48+
| `*-server` | Server implementations | Corresponding *-core |
49+
| `*-core` | Domain logic & business rules | Protocol implementations |
50+
| `*-protocol` | BitTorrent protocol implementations | BitTorrent protocol |
51+
| `udp-*` | UDP Protocol-specific implementations | Tracker core |
52+
| `http-*` | HTTP Protocol-specific implementations | Tracker core |
53+
54+
Key Architectural Principles:
55+
56+
1. **Separation of Concerns**: Servers contain only network I/O logic.
57+
2. **Protocol Compliance**: `*-protocol` packages strictly implement BEP specifications.
58+
3. **Extensibility**: Core logic is framework-agnostic for easy protocol additions.
59+
60+
## Package Catalog
61+
62+
| Package | Description | Key Responsibilities |
63+
|---------|-------------|----------------------|
64+
| **axum-*** | | |
65+
| `axum-server` | Base Axum HTTP server infrastructure | HTTP server lifecycle management |
66+
| `axum-http-tracker-server` | BitTorrent HTTP tracker (BEP 3/23) | Handle announce/scrape requests |
67+
| `axum-rest-tracker-api-server` | Management REST API | Tracker configuration & monitoring |
68+
| `axum-health-check-api-server` | Health monitoring endpoint | System health reporting |
69+
| **Core Components** | | |
70+
| `http-tracker-core` | HTTP-specific implementation | Request validation, Response formatting |
71+
| `udp-tracker-core` | UDP-specific implementation | Connectionless request handling |
72+
| `tracker-core` | Central tracker logic | Peer management |
73+
| **Protocols** | | |
74+
| `http-protocol` | HTTP tracker protocol (BEP 3/23) | Announce/scrape request parsing |
75+
| `udp-protocol` | UDP tracker protocol (BEP 15) | UDP message framing/parsing |
76+
| **Domain** | | |
77+
| `torrent-repository` | Torrent metadata storage | InfoHash management, Peer coordination |
78+
| `configuration` | Runtime configuration | Config file parsing, Environment variables |
79+
| `primitives` | Domain-specific types | InfoHash, PeerId, Byte handling |
80+
| **Utilities** | | |
81+
| `clock` | Time abstraction | Mockable time source for testing |
82+
| `located-error` | Diagnostic errors | Error tracing with source locations |
83+
| `test-helpers` | Testing utilities | Mock servers, Test data generation |
84+
| **Client Tools** | | |
85+
| `tracker-client` | CLI client | Tracker interaction/testing |
86+
| `rest-tracker-api-client` | API client library | REST API integration |
87+
88+
## Protocol Implementation Details
89+
90+
### HTTP Tracker (BEP 3/23)
91+
92+
- `http-protocol` implements:
93+
- URL parameter parsing
94+
- Response bencoding
95+
- Error code mapping
96+
- Compact peer formatting
97+
98+
### UDP Tracker (BEP 15)
99+
100+
- `udp-protocol` handles:
101+
- Connection ID management
102+
- Message framing (32-bit big-endian)
103+
- Transaction ID tracking
104+
- Error response codes
105+
106+
## Architectural Philosophy
107+
108+
1. **Testability**: Core packages have minimal dependencies for easy unit testing
109+
2. **Observability**: Health checks and metrics built into server packages
110+
3. **Modularity**: Protocol implementations decoupled from transport layers
111+
4. **Extensibility**: New protocols can be added without modifying core logic
112+
113+
![Torrust Tracker Architecture Diagram](./media/packages/torrust-tracker-layers-with-packages.png)
114+
115+
> Diagram shows clean separation between network I/O (servers), protocol handling, and core tracker logic

‎src/console/ci/e2e/runner.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -137,7 +137,7 @@ fn load_tracker_configuration(args: &Args) -> anyhow::Result<String> {
137137
}
138138

139139
fn load_config_from_file(path: &PathBuf) -> anyhow::Result<String> {
140-
let config = std::fs::read_to_string(path).with_context(|| format!("CSan't read config file {path:?}"))?;
140+
let config = std::fs::read_to_string(path).with_context(|| format!("CSan't read config file {}", path.display()))?;
141141

142142
Ok(config)
143143
}

‎src/lib.rs

+3-10
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@
3636
//! - [API](#api)
3737
//! - [HTTP Tracker](#http-tracker)
3838
//! - [UDP Tracker](#udp-tracker)
39-
//! - [Components](#components)
39+
//! - [Packages](#packages)
4040
//! - [Implemented BEPs](#implemented-beps)
4141
//! - [Contributing](#contributing)
4242
//! - [Documentation](#documentation)
@@ -401,16 +401,9 @@
401401
//!
402402
//! - [BEP 15. UDP Tracker Protocol for `BitTorrent`](https://www.bittorrent.org/beps/bep_0015.html)
403403
//!
404-
//! # Components
404+
//! # Packages
405405
//!
406-
//! Torrust Tracker has four main components:
407-
//!
408-
//! - The core tracker [`core`]
409-
//! - The tracker REST [`API`](torrust_axum_rest_tracker_api_server)
410-
//! - The [`UDP`](torrust_udp_tracker_server) tracker
411-
//! - The [`HTTP`](torrust_axum_http_tracker_server) tracker
412-
//!
413-
//! ![Torrust Tracker Components](https://raw.githubusercontent.com/torrust/torrust-tracker/main/docs/media/torrust-tracker-components.png)
406+
//! ![Torrust Tracker Layers with Main Packages](https://raw.githubusercontent.com/torrust/torrust-tracker/main/docs/media/packages/torrust-tracker-layers-with-packages.png)
414407
//!
415408
//! ## Core tracker
416409
//!

0 commit comments

Comments
 (0)