Skip to content

Commit 03ec3bb

Browse files
josecelanojosecelano
committed
docs(agents): add packages/AGENTS.md with package architecture guide
1 parent 760fafc commit 03ec3bb

1 file changed

Lines changed: 152 additions & 0 deletions

File tree

‎packages/AGENTS.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# Torrust Tracker — Packages
2+
3+
This directory contains all Cargo workspace packages. All domain logic, protocol
4+
implementations, server infrastructure, and utility libraries live here.
5+
6+
For full project context see the [root AGENTS.md](../AGENTS.md).
7+
8+
## Architecture
9+
10+
Packages are organized in strict layers. Dependencies only flow downward — a package may only
11+
depend on packages in the same layer or a lower one.
12+
13+
```text
14+
┌────────────────────────────────────────────────────────────────┐
15+
│ Servers (delivery layer) │
16+
│ axum-http-tracker-server axum-rest-tracker-api-server │
17+
│ axum-health-check-api-server udp-tracker-server │
18+
├────────────────────────────────────────────────────────────────┤
19+
│ Core (domain layer) │
20+
│ http-tracker-core udp-tracker-core tracker-core │
21+
│ rest-tracker-api-core swarm-coordination-registry │
22+
├────────────────────────────────────────────────────────────────┤
23+
│ Protocols │
24+
│ http-protocol udp-protocol │
25+
├────────────────────────────────────────────────────────────────┤
26+
│ Domain / Shared │
27+
│ torrent-repository configuration primitives │
28+
│ events metrics clock located-error server-lib │
29+
├────────────────────────────────────────────────────────────────┤
30+
│ Utilities / Test support │
31+
│ test-helpers located-error clock │
32+
└────────────────────────────────────────────────────────────────┘
33+
```
34+
35+
**Key architectural rule**: Servers contain only network I/O logic. All business rules live in
36+
`*-core` packages. Protocol parsing is isolated in `*-protocol` packages.
37+
38+
See [docs/packages.md](../docs/packages.md) for a full diagram.
39+
40+
## Package Catalog
41+
42+
### Servers (`axum-*`, `udp-tracker-server`)
43+
44+
Delivery layer — accept network connections, dispatch to core handlers, return responses.
45+
These packages must not contain business logic.
46+
47+
| Package | Entry point | Protocol |
48+
| ------------------------------ | ------------ | ----------- |
49+
| `axum-http-tracker-server` | `src/lib.rs` | HTTP BEP 3 |
50+
| `axum-rest-tracker-api-server` | `src/lib.rs` | REST (JSON) |
51+
| `axum-health-check-api-server` | `src/lib.rs` | HTTP |
52+
| `axum-server` | `src/lib.rs` | Axum base |
53+
| `udp-tracker-server` | `src/lib.rs` | UDP BEP 15 |
54+
55+
### Core (`*-core`)
56+
57+
Domain layer — business rules, request validation, response building. No Axum or networking
58+
imports. Each core package exposes a `container` module that wires up its dependencies via
59+
dependency injection.
60+
61+
| Package | Purpose |
62+
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
63+
| `tracker-core` | Central peer management: announce/scrape handlers, auth, whitelist, database abstraction (SQLite/MySQL drivers in `src/databases/driver/`) |
64+
| `http-tracker-core` | HTTP-specific validation and response formatting |
65+
| `udp-tracker-core` | UDP connection cookies, crypto, banning logic |
66+
| `rest-tracker-api-core` | REST API statistics and container wiring |
67+
| `swarm-coordination-registry` | Registry of torrents and their peer swarms |
68+
69+
### Protocols (`*-protocol`)
70+
71+
Strict BEP implementations — parse and serialize wire formats only. No tracker logic.
72+
73+
| Package | BEP | Handles |
74+
| --------------- | ------ | -------------------------------------------------------------- |
75+
| `http-protocol` | BEP 3 | URL parameter parsing, bencoded responses, compact peer format |
76+
| `udp-protocol` | BEP 15 | Message framing, connection IDs, transaction IDs |
77+
78+
### Domain / Shared
79+
80+
| Package | Purpose |
81+
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
82+
| `torrent-repository` | Torrent metadata storage; InfoHash management; peer coordination |
83+
| `configuration` | Config file parsing (`share/default/config/`) and env var loading (`TORRUST_TRACKER_CONFIG_TOML`, `TORRUST_TRACKER_CONFIG_TOML_PATH`); versioned under `src/v2_0_0/` |
84+
| `primitives` | Core domain types: `InfoHash`, `PeerId`, `Peer`, `SwarmMetadata`, `ServiceBinding` |
85+
| `events` | Async event bus (broadcaster / receiver / shutdown) used across packages |
86+
| `metrics` | Prometheus-compatible metrics: counters, gauges, labels, samples |
87+
| `server-lib` | Shared HTTP server utilities: logging, service registrar, signal handling |
88+
| `clock` | Mockable time source — use `clock::Working` in production, `clock::Stopped` in tests |
89+
| `located-error` | Error decorator that captures the source file/line of the original error |
90+
91+
### Client Tools
92+
93+
| Package | Purpose |
94+
| ------------------------- | -------------------------------------------------------- |
95+
| `tracker-client` | Generic HTTP and UDP tracker clients (used by E2E tests) |
96+
| `rest-tracker-api-client` | Typed REST API client library |
97+
98+
### Utilities / Test support
99+
100+
| Package | Purpose |
101+
| --------------------------------- | ---------------------------------------------------------- |
102+
| `test-helpers` | Mock servers, test data generators, shared test fixtures |
103+
| `torrent-repository-benchmarking` | Criterion benchmarks for alternative torrent storage impls |
104+
105+
## Naming Conventions
106+
107+
| Prefix / Suffix | Responsibility | May depend on |
108+
| --------------- | ----------------------------------------- | ----------------------------- |
109+
| `axum-*` | HTTP server components using Axum | `*-core`, Axum framework |
110+
| `*-server` | Server implementations | Corresponding `*-core` |
111+
| `*-core` | Domain logic and business rules | `*-protocol`, domain packages |
112+
| `*-protocol` | BitTorrent protocol parsing/serialization | `primitives` |
113+
| `udp-*` | UDP-specific implementations | `tracker-core` |
114+
| `http-*` | HTTP-specific implementations | `tracker-core` |
115+
116+
## Adding or Modifying a Package
117+
118+
1. Create the directory under `packages/<new-package>/` with a `Cargo.toml` and `src/lib.rs`.
119+
2. Add the package to the workspace `[members]` in the root `Cargo.toml`.
120+
3. Follow the naming conventions above.
121+
4. Each package must have:
122+
- A crate-level doc comment in `src/lib.rs` explaining its purpose and layer.
123+
- At minimum one unit test (doc-test acceptable for simple utility crates).
124+
5. Run `cargo machete` after adding dependencies — unused deps must not be committed.
125+
6. Run `linter all` before committing.
126+
127+
## Testing Packages
128+
129+
```sh
130+
# All tests for a specific package
131+
cargo test -p <package-name>
132+
133+
# Doc tests only
134+
cargo test --doc -p <package-name>
135+
136+
# MySQL-specific tests in tracker-core (requires a running MySQL instance)
137+
TORRUST_TRACKER_CORE_RUN_MYSQL_DRIVER_TEST=true cargo test -p torrust-tracker-core
138+
```
139+
140+
Use `clock::Stopped` (from the `clock` package) in unit tests that need deterministic time.
141+
Use `test-helpers` for mock tracker servers in integration tests.
142+
143+
## Key Dependency Notes
144+
145+
- `swarm-coordination-registry` is the authoritative store for peer swarms; `tracker-core`
146+
delegates peer lookups to it.
147+
- `configuration` is the only package that reads from the filesystem or environment at startup;
148+
other packages receive config structs as arguments.
149+
- `located-error` wraps any `std::error::Error` — use it at module boundaries to preserve
150+
error origin context without losing the original error type.
151+
- `events` provides the only sanctioned inter-package async communication channel; avoid direct
152+
`tokio::sync` coupling between packages.

0 commit comments

Comments
 (0)