OAPI
OAPI is a high-performance, asynchronous orchestration API built with Rust. It serves as the backbone logic for the Antre des Loutres community, handling complex image generation, real-time infrastructure monitoring, and external API integration.
- Statut
- en production
- Contribution
- 165 commits
- Type
- Api rest
- Stack
- Rust
- Version
- v1.2.1
- Début
- mai 2026
- Dernière activité
- oct. 2026
OAPI is the asynchronous Rust API (Axum + Tokio) behind the Antre des Loutres community. It generates Discord and Minecraft profile cards, monitors the community infrastructure, handles Discord authentication and exposes community data stored in PocketBase.
Features
| Area | Description |
|---|---|
| Profile cards | PNG summary cards for Discord and Minecraft profiles (messages, voice time, playtime, distance, blocks). Generation is skipped when the SHA-256 hash of the profile state is unchanged. |
| Monitoring | Parallel health checks of HTTP(S) services and Minecraft servers (Server List Ping), with a web dashboard. |
| Authentication | Discord OAuth2 login, stateless JWT session cookie, roles (Admin, LoutreInvesti, …), service API key for trusted servers and read-only rom_ tokens for games. |
| Friends | Friendship system between Discord accounts. |
| Badges | Automatic badge attribution from Discord and Minecraft statistics, rules defined in badges.yaml. |
| Discord activity | JSON endpoints for Discord activity statistics, with request limits. |
| Investor statistics | PocketBase record counts, restricted to LoutreInvesti and Admin accounts. Returns 503 rather than partial data when the database fails. |
| Daily tasks | Background scheduler: account purge, badge refresh, then Minecraft head and skin refresh from Mojang. |
| API documentation | OpenAPI 3 specification generated with utoipa, served through Swagger UI. |
Architecture
OAPI uses a layered architecture. Each layer only depends on the layers below it.
| Layer | Directory | Responsibility |
|---|---|---|
| Routes | src/routes/ |
Router assembly and middleware (authentication, CORS, rate limiting). |
| Handlers | src/handlers/ |
HTTP entry points: parameter extraction, status codes. |
| Actions | src/actions/ |
Use-case orchestration and external data fetching. |
| Services | src/services/ |
Business logic: image rendering, badges, scheduler, Mojang skins. |
| Models | src/models/ |
Typed DTOs and OpenAPI schemas. |
| Utils | src/utils/ |
PocketBase client, formatters, paths and constants. |
Static web pages are in public/, front-end tests in tests/, deployment files in deploy/.
See docs/architecture.md for details.
External dependencies: PocketBase (data storage), the Discord API (OAuth2, profiles) and the Mojang API (Minecraft skins).
Environment variables
Defined in .env, see .env.example. Never commit .env.
| Variable | Required | Description |
|---|---|---|
OAPI_ENV |
Yes | development or production. |
PB_URL |
Yes | PocketBase URL. |
PB_EMAIL |
Yes | PocketBase administrator email. |
PB_PASSWORD |
Yes | PocketBase administrator password. |
DISCORD_CLIENT_ID |
Yes | Discord application client ID. |
DISCORD_CLIENT_SECRET |
Yes | Discord application client secret. |
DISCORD_REDIRECT_URL |
Yes | OAuth2 callback, ending with /api/auth/callback. Must be HTTPS in production. |
JWT_SECRET |
Yes | Random secret of at least 32 bytes (openssl rand -hex 32). Startup fails if it is missing or too short. |
OAPI_SERVICE_API_KEY |
No | Key for trusted server-to-server calls, with administrator rights. Never expose it to browser code. |
RUST_LOG |
No | Log filter, for example info,OAPI=debug,tower_http=debug. |
POCKETBASE_NETWORK |
No | Docker network shared with PocketBase (Compose only). Default: pocketbase_network. |
Testing and quality
The project follows a zero-warnings policy. CI (.github/workflows/ci.yml)
runs formatting, Clippy, tests, release build and a Semgrep scan on every push to master and
feat/*, and on every pull request to master.
Run the same checks locally before pushing:
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
node --test tests/*.test.cjs
Documentation
Documentation is written in French. English versions are available for some pages.
| Topic | French | English |
|---|---|---|
| Architecture | architecture.md | EN |
| Configuration | configuration.md | EN |
| Authentication | AUTH.md | EN |
| PocketBase integration | pocketbase.md | EN |
| Image generation | generation_images.md | EN |
| Monitoring | monitoring.md | EN |
| Web interfaces | interfaces.md | — |
| Badges | badges.md | — |
| Friends API | friends.md | — |
| Discord activity | discord_statistics.md | — |
ROM linking (rom_ tokens) |
rom_auth.md, rom_contract.md | — |
| Astro site integration | astro.md | — |
| Daily tasks | daily_tasks.md | — |
| Production deployment | production.md | — |