Skip to content

Commit 5593dd2

Browse files
josecelanojosecelano
committed
docs(agents): add root AGENTS.md
1 parent fa1f6d1 commit 5593dd2

4 files changed

Lines changed: 392 additions & 1 deletion

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,4 +17,5 @@ codecov.json
1717
integration_tests_sqlite3.db
1818
lcov.info
1919
perf.data*
20+
repomix-output.xml
2021
rustc-ice-*.txt

‎AGENTS.md‎

Lines changed: 388 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,388 @@
1+
# Torrust Tracker — AI Assistant Instructions
2+
3+
**Repository**: [torrust/torrust-tracker](https://github.com/torrust/torrust-tracker)
4+
5+
## 📋 Project Overview
6+
7+
**Torrust Tracker** is a high-quality, production-grade BitTorrent tracker written in Rust. It
8+
matchmakes peers and collects statistics, supporting the UDP, HTTP, and TLS socket types with
9+
native IPv4/IPv6 support, private/whitelisted mode, and a management REST API.
10+
11+
- **Language**: Rust (edition 2021, MSRV 1.72)
12+
- **License**: AGPL-3.0-only
13+
- **Version**: 3.0.0-develop
14+
- **Web framework**: [Axum](https://github.com/tokio-rs/axum)
15+
- **Async runtime**: Tokio
16+
- **Protocols**: BitTorrent UDP (BEP 15), HTTP (BEP 3/23), REST management API
17+
- **Databases**: SQLite3, MySQL
18+
- **Workspace type**: Cargo workspace (multi-crate monorepo)
19+
20+
## 🏗️ Tech Stack
21+
22+
- **Languages**: Rust, YAML, TOML, Markdown, Shell scripts
23+
- **Web framework**: Axum (HTTP server + REST API)
24+
- **Async runtime**: Tokio (multi-thread)
25+
- **Testing**: testcontainers (E2E)
26+
- **Databases**: SQLite3, MySQL
27+
- **Containerization**: Docker / Podman (`Containerfile`)
28+
- **CI**: GitHub Actions
29+
- **Linting tools**: markdownlint, yamllint, taplo, cspell, shellcheck, clippy, rustfmt (unified
30+
under the `linter` binary from [torrust/torrust-linting](https://github.com/torrust/torrust-linting))
31+
32+
## 📁 Key Directories
33+
34+
- `src/` — Main binary and library entry points (`main.rs`, `lib.rs`, `app.rs`, `container.rs`)
35+
- `src/bin/` — Additional binary targets (`e2e_tests_runner`, `http_health_check`, `profiling`)
36+
- `src/bootstrap/` — Application bootstrap logic
37+
- `src/console/` — Console entry points
38+
- `packages/` — Cargo workspace packages (all domain logic lives here; see package catalog below)
39+
- `console/` — Console tools (e.g., `tracker-client`)
40+
- `contrib/` — Community-contributed utilities (`bencode`) and developer tooling
41+
- `contrib/dev-tools/` — Developer tools: git hooks (`pre-commit.sh`, `pre-push.sh`),
42+
container scripts, and init scripts
43+
- `tests/` — Integration tests (`integration.rs`, `servers/`)
44+
- `docs/` — Project documentation, ADRs, issue specs, and benchmarking guides
45+
- `docs/adrs/` — Architectural Decision Records
46+
- `docs/issues/` — Issue specs / implementation plans
47+
- `share/default/` — Default configuration files and fixtures
48+
- `storage/` — Runtime data (git-ignored); databases, logs, config
49+
- `.github/workflows/` — CI/CD workflows (testing, coverage, container, deployment)
50+
- `.github/skills/` — Agent Skills for specialized workflows _(to be added — see issue #1697)_
51+
- `.github/agents/` — Custom Copilot agents _(to be added — see issue #1697)_
52+
53+
## 📦 Package Catalog
54+
55+
All packages live under `packages/`. The workspace version is `3.0.0-develop`.
56+
57+
| Package | Prefix / Layer | Description |
58+
| --------------------------------- | -------------- | ------------------------------------------------ |
59+
| `axum-server` | `axum-*` | Base Axum HTTP server infrastructure |
60+
| `axum-http-tracker-server` | `axum-*` | BitTorrent HTTP tracker server (BEP 3/23) |
61+
| `axum-rest-tracker-api-server` | `axum-*` | Management REST API server |
62+
| `axum-health-check-api-server` | `axum-*` | Health monitoring endpoint |
63+
| `http-tracker-core` | `*-core` | HTTP-specific tracker domain logic |
64+
| `udp-tracker-core` | `*-core` | UDP-specific tracker domain logic |
65+
| `tracker-core` | `*-core` | Central tracker peer-management logic |
66+
| `http-protocol` | `*-protocol` | HTTP tracker protocol (BEP 3/23) parsing |
67+
| `udp-protocol` | `*-protocol` | UDP tracker protocol (BEP 15) framing/parsing |
68+
| `swarm-coordination-registry` | domain | Torrent/peer coordination registry |
69+
| `configuration` | domain | Config file parsing, environment variables |
70+
| `primitives` | domain | Core domain types (InfoHash, PeerId, …) |
71+
| `clock` | utilities | Mockable time source for deterministic testing |
72+
| `located-error` | utilities | Diagnostic errors with source locations |
73+
| `test-helpers` | utilities | Mock servers, test data generation |
74+
| `server-lib` | shared | Shared server library utilities |
75+
| `tracker-client` | client tools | CLI tracker interaction/testing client |
76+
| `rest-tracker-api-client` | client tools | REST API client library |
77+
| `rest-tracker-api-core` | client tools | REST API core logic |
78+
| `udp-tracker-server` | server | UDP tracker server implementation |
79+
| `torrent-repository` | domain | Torrent metadata storage and InfoHash management |
80+
| `events` | domain | Domain event definitions |
81+
| `metrics` | domain | Prometheus metrics integration |
82+
| `torrent-repository-benchmarking` | benchmarking | Torrent storage benchmarks |
83+
84+
**Console tools** (under `console/`):
85+
86+
| Tool | Description |
87+
| ---------------- | ------------------------------------ |
88+
| `tracker-client` | Client for interacting with trackers |
89+
90+
**Community contributions** (under `contrib/`):
91+
92+
| Crate | Description |
93+
| --------- | ------------------------------- |
94+
| `bencode` | Bencode encode/decode utilities |
95+
96+
## 🏷️ Package Naming Conventions
97+
98+
| Prefix | Responsibility | Dependencies |
99+
| ------------ | -------------------------------------- | ------------------------ |
100+
| `axum-*` | HTTP server components using Axum | Axum framework |
101+
| `*-server` | Server implementations | Corresponding `*-core` |
102+
| `*-core` | Domain logic and business rules | Protocol implementations |
103+
| `*-protocol` | BitTorrent protocol implementations | BEP specifications |
104+
| `udp-*` | UDP protocol-specific implementations | Tracker core |
105+
| `http-*` | HTTP protocol-specific implementations | Tracker core |
106+
107+
## 📄 Key Configuration Files
108+
109+
| File | Used by |
110+
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
111+
| `.markdownlint.json` | markdownlint |
112+
| `.yamllint-ci.yml` | yamllint |
113+
| `.taplo.toml` | taplo (TOML formatting) |
114+
| `cspell.json` / `cSpell.json` | cspell (spell checker) — both filenames exist in the repo |
115+
| `project-words.txt` | cspell project-specific dictionary |
116+
| `rustfmt.toml` | rustfmt (`group_imports = "StdExternalCrate"`, `max_width = 130`) |
117+
| `.cargo/config.toml` | Cargo aliases (`cov`, `cov-lcov`, `cov-html`, `time`) and global `rustflags` (`-D warnings`, `-D unused`, `-D rust-2018-idioms`, …) |
118+
| `Cargo.toml` | Cargo workspace root |
119+
| `compose.yaml` | Docker Compose for local dev and demo |
120+
| `Containerfile` | Container image definition |
121+
| `codecov.yaml` | Code coverage configuration |
122+
123+
## 🧪 Build & Test
124+
125+
### Setup
126+
127+
```sh
128+
rustup show # Check active toolchain
129+
rustup update # Update toolchain
130+
rustup toolchain install nightly # Required: pre-commit hooks use cargo +nightly fmt/check/doc
131+
```
132+
133+
### Build
134+
135+
```sh
136+
cargo build # Build all workspace crates
137+
cargo build --release # Release build
138+
cargo build --package <pkg> # Build a specific package
139+
```
140+
141+
### Test
142+
143+
```sh
144+
cargo test --doc --workspace # Documentation tests
145+
cargo test --tests --benches --examples --workspace \
146+
--all-targets --all-features # All tests
147+
cargo test -p <package-name> # Single package
148+
149+
# MySQL-specific tests (requires a running MySQL instance)
150+
TORRUST_TRACKER_CORE_RUN_MYSQL_DRIVER_TEST=true \
151+
cargo test --package bittorrent-tracker-core
152+
153+
# Integration tests (root)
154+
cargo test --test integration # tests/integration.rs
155+
```
156+
157+
### E2E Tests
158+
159+
```sh
160+
cargo run --bin e2e_tests_runner -- \
161+
--config-toml-path "./share/default/config/tracker.e2e.container.sqlite3.toml"
162+
```
163+
164+
### Documentation
165+
166+
```sh
167+
cargo +nightly doc --no-deps --bins --examples --workspace --all-features
168+
```
169+
170+
### Benchmarks
171+
172+
```sh
173+
cargo bench --package torrent-repository-benchmarking
174+
```
175+
176+
See [docs/benchmarking.md](docs/benchmarking.md) and [docs/profiling.md](docs/profiling.md).
177+
178+
## 🔍 Lint Commands
179+
180+
The project uses the `linter` binary from
181+
[torrust/torrust-linting](https://github.com/torrust/torrust-linting).
182+
183+
```sh
184+
# Install the linter binary
185+
cargo install --locked --git https://github.com/torrust/torrust-linting --bin linter
186+
187+
# Run all linters (MANDATORY before every commit and PR)
188+
linter all
189+
190+
# Run individual linters
191+
linter markdown # markdownlint
192+
linter yaml # yamllint
193+
linter toml # taplo
194+
linter cspell # spell checker
195+
linter clippy # Rust linter
196+
linter rustfmt # Rust formatter check
197+
linter shellcheck # shell scripts
198+
```
199+
200+
**`linter all` must exit with code `0` before every commit. PRs that fail CI linting are
201+
rejected without review.**
202+
203+
## 🔗 Dependencies Check
204+
205+
```sh
206+
cargo machete # Check for unused dependencies (mandatory before commits)
207+
```
208+
209+
Install via: `cargo install cargo-machete`
210+
211+
## 🎨 Code Style
212+
213+
- **rustfmt**: Format with `cargo fmt` before committing. Config: `rustfmt.toml`
214+
(`group_imports = "StdExternalCrate"`, `imports_granularity = "Module"`, `max_width = 130`).
215+
- **Compile flags**: `.cargo/config.toml` enables strict global `rustflags` (`-D warnings`,
216+
`-D unused`, `-D rust-2018-idioms`, `-D future-incompatible`, and others). All code must
217+
compile cleanly with these flags — no suppressions unless absolutely necessary.
218+
- **clippy**: No warnings allowed (`cargo clippy -- -D warnings`).
219+
- **Imports**: All imports at the top of the file, grouped (std → external crates → internal
220+
crate). Prefer short imported names over fully-qualified paths
221+
(e.g., `Arc<MyType>` not `std::sync::Arc<crate::my::MyType>`). Use full paths only to
222+
disambiguate naming conflicts.
223+
- **TOML**: Must pass `taplo fmt --check **/*.toml`. Auto-fix with `taplo fmt **/*.toml`.
224+
- **Markdown**: Must pass markdownlint.
225+
- **YAML**: Must pass `yamllint -c .yamllint-ci.yml`.
226+
- **Spell checking**: Add new technical terms to `project-words.txt` (one word per line,
227+
alphabetical order).
228+
229+
## 🤝 Collaboration Principles
230+
231+
These rules apply repository-wide to every assistant, including custom agents.
232+
233+
When acting as an assistant in this repository:
234+
235+
- Do not flatter the user or agree with weak ideas by default.
236+
- Push back when a request, diff, or proposed commit looks wrong.
237+
- Flag unclear but important points before they become problems.
238+
- Ask a clarifying question instead of making a random choice when the decision matters.
239+
- Call out likely misses: naming inconsistencies, accidental generated files,
240+
staged-versus-unstaged mismatches, missing docs updates, or suspicious commit scope.
241+
242+
When raising a likely mistake or blocker, say so clearly and early instead of burying it after
243+
routine status updates.
244+
245+
## 🔧 Essential Rules
246+
247+
1. **Linting gate**: `linter all` must exit `0` before every commit. No exceptions.
248+
2. **GPG commit signing**: All commits **must** be signed with GPG (`git commit -S`).
249+
3. **Never commit `storage/` or `target/`**: These directories contain runtime data and build
250+
artifacts. They are git-ignored; never force-add them.
251+
4. **Unused dependencies**: Run `cargo machete` before committing. Remove any unused
252+
dependencies immediately.
253+
5. **Rust imports**: All imports at the top of the file, grouped (std → external crates →
254+
internal crate). Prefer short imported names over fully-qualified paths.
255+
6. **Continuous self-review**: Review your own work against project quality standards. Apply
256+
self-review at three levels:
257+
- **Mandatory** — before opening a pull request
258+
- **Strongly recommended** — before each commit
259+
- **Recommended** — after completing each small, independent, deployable change
260+
7. **Security**: Do not report security vulnerabilities through public GitHub issues. Send an
261+
email to `info@nautilus-cyberneering.de` instead. See [SECURITY.md](SECURITY.md).
262+
263+
## 🌿 Git Workflow
264+
265+
**Branch naming**:
266+
267+
```text
268+
<issue-number>-<short-description> # e.g. 1697-ai-agent-configuration (preferred)
269+
feat/<short-description> # for features without a tracked issue
270+
fix/<short-description> # for bug fixes
271+
chore/<short-description> # for maintenance tasks
272+
```
273+
274+
**Commit messages** follow [Conventional Commits](https://www.conventionalcommits.org/):
275+
276+
```text
277+
feat(<scope>): add X
278+
fix(<scope>): resolve Y
279+
chore(<scope>): update Z
280+
docs(<scope>): document W
281+
refactor(<scope>): restructure V
282+
ci(<scope>): adjust pipeline U
283+
test(<scope>): add tests for T
284+
```
285+
286+
Scope should reflect the affected package or area (e.g., `tracker-core`, `udp-protocol`, `ci`, `docs`).
287+
288+
**Branch strategy**:
289+
290+
- Feature branches are cut from `develop`
291+
- PRs target `develop`
292+
- `develop` → `staging/main` → `main` (release pipeline)
293+
- PRs must pass all CI status checks before merge
294+
295+
See [docs/release_process.md](docs/release_process.md) for the full release workflow.
296+
297+
## 🧭 Development Principles
298+
299+
For detailed information see [`docs/`](docs/).
300+
301+
**Core Principles:**
302+
303+
- **Observability**: If it happens, we can see it — even after it happens (deep traceability)
304+
- **Testability**: Every component must be testable in isolation and as part of the whole
305+
- **Modularity**: Clear package boundaries; servers contain only network I/O logic
306+
- **Extensibility**: Core logic is framework-agnostic for easy protocol additions
307+
308+
**Code Quality Standards** — both production and test code must be:
309+
310+
- **Clean**: Well-structured with clear naming and minimal complexity
311+
- **Maintainable**: Easy to modify and extend without breaking existing functionality
312+
- **Readable**: Clear intent that can be understood by other developers
313+
- **Testable**: Designed to support comprehensive testing at all levels
314+
315+
**Beck's Four Rules of Simple Design** (in priority order):
316+
317+
1. **Passes the tests**: The code must work as intended — testing is a first-class activity
318+
2. **Reveals intention**: Code should be easy to understand, expressing purpose clearly
319+
3. **No duplication**: Apply DRY — eliminating duplication drives out good designs
320+
4. **Fewest elements**: Remove anything that doesn't serve the prior three rules
321+
322+
Reference: [Beck Design Rules](https://martinfowler.com/bliki/BeckDesignRules.html)
323+
324+
## 🐳 Container / Docker
325+
326+
```sh
327+
# Run the latest image
328+
docker run -it torrust/tracker:latest
329+
# or with Podman
330+
podman run -it docker.io/torrust/tracker:latest
331+
332+
# Build and run via Docker Compose
333+
docker compose up -d # Start all services (detached)
334+
docker compose logs -f tracker # Follow tracker logs
335+
docker compose down # Stop and remove containers
336+
```
337+
338+
**Volume mappings** (local `storage/` → container paths):
339+
340+
```text
341+
./storage/tracker/lib → /var/lib/torrust/tracker
342+
./storage/tracker/log → /var/log/torrust/tracker
343+
./storage/tracker/etc → /etc/torrust/tracker
344+
```
345+
346+
**Ports**: UDP tracker: `6969`, HTTP tracker: `7070`, REST API: `1212`
347+
348+
See [docs/containers.md](docs/containers.md) for detailed container documentation.
349+
350+
## 🎯 Auto-Invoke Skills
351+
352+
Agent Skills will be available under `.github/skills/` once issue #1697 is implemented.
353+
354+
> Skills supplement (not replace) the rules in this file. Rules apply always; skills activate
355+
> when their workflows are needed.
356+
357+
**For VS Code**: Enable `chat.useAgentSkills` in settings to activate skill discovery.
358+
359+
**Learn more**: See [Agent Skills Specification (agentskills.io)](https://agentskills.io/specification).
360+
361+
## 📚 Documentation
362+
363+
- [Documentation Index](docs/index.md)
364+
- [Package Architecture](docs/packages.md)
365+
- [Benchmarking](docs/benchmarking.md)
366+
- [Profiling](docs/profiling.md)
367+
- [Containers](docs/containers.md)
368+
- [Release Process](docs/release_process.md)
369+
- [ADRs](docs/adrs/README.md)
370+
- [Issues / Implementation Plans](docs/issues/)
371+
- [API docs (docs.rs)](https://docs.rs/torrust-tracker/)
372+
- [Report a security vulnerability](SECURITY.md)
373+
374+
### Quick Navigation
375+
376+
| Task | Start Here |
377+
| ------------------------------------ | ---------------------------------------------------- |
378+
| Understand the architecture | [`docs/packages.md`](docs/packages.md) |
379+
| Run the tracker in a container | [`docs/containers.md`](docs/containers.md) |
380+
| Read all docs | [`docs/index.md`](docs/index.md) |
381+
| Understand an architectural decision | [`docs/adrs/README.md`](docs/adrs/README.md) |
382+
| Read or write an issue spec | [`docs/issues/`](docs/issues/) |
383+
| Run benchmarks | [`docs/benchmarking.md`](docs/benchmarking.md) |
384+
| Run profiling | [`docs/profiling.md`](docs/profiling.md) |
385+
| Understand the release process | [`docs/release_process.md`](docs/release_process.md) |
386+
| Report a security vulnerability | [`SECURITY.md`](SECURITY.md) |
387+
| Agent skills reference | `.github/skills/` _(coming — see issue #1697)_ |
388+
| Custom agents reference | `.github/agents/` _(coming — see issue #1697)_ |

0 commit comments

Comments
 (0)