Rustwarden Constitution

Core Principles

I. Qualité de Code

Toutes les fonctions publiques DOIVENT être documentées avec /// (doc comments Rust). Le code DOIT respecter les bonnes pratiques Rust (clippy warnings = 0). Les structures de données DOIVENT utiliser #[derive(Debug, Clone)] où approprié. La gestion d'erreurs DOIT utiliser Result<T, E> avec des types d'erreur explicites.

Documentation Language (amendement v0.5.3): Tous les commentaires rustdoc (/// et //!) DOIVENT être rédigés en anglais. La documentation humaine dans /docs/ reste en français. Cela garantit que la sortie de cargo doc est accessible à la communauté Rust internationale. Le lint missing_docs est activé au niveau workspace (warn) pour prévenir les régressions.

Rationale: La documentation et la qualité du code facilitent la maintenance, la collaboration et réduisent les bugs. Rust offre des outils puissants (clippy, rustfmt) qui doivent être utilisés.

II. Architecture Axum et SeaORM

Toutes les routes HTTP DOIVENT être définies avec Axum uniquement (axum::Router). Toutes les interactions avec la base de données DOIVENT passer par SeaORM (aucun raw SQL autorisé). Les migrations DOIVENT être gérées via le système de migrations SeaORM (migrations/src/). Le serveur DOIT utiliser Tokio comme runtime async (requis par Axum).

Documentation SeaORM (amendement v0.4.1): Toutes les interactions avec la base de données DOIVENT être implémentées en référence à la documentation officielle SeaORM. Avant d'implémenter une nouvelle fonctionnalité de base de données (requêtes, relations, transactions, etc.), la documentation SeaORM DOIT être consultée pour garantir l'utilisation des bonnes pratiques et des patterns recommandés. Les exemples de code et les patterns documentés dans la documentation SeaORM DOIVENT être privilégiés par rapport aux approches personnalisées.

Implémentation obligatoire des handlers serveur (amendement v0.5.0): TOUJOURS implémenter les handlers serveur pour que l'API soit fonctionnelle. Les handlers stub (retournant 501 Not Implemented) sont INTERDITS dans le code de production. Chaque route définie DOIT avoir un handler complet qui :

Injecte l'état nécessaire (State<DatabaseConnection>, Extension<Claims>, etc.)
Utilise les services métier appropriés
Retourne des réponses fonctionnelles avec données réelles
Gère les erreurs de manière appropriée

Les handlers stub sont uniquement autorisés temporairement pendant le développement incrémental, mais DOIVENT être remplacés par des implémentations complètes avant que la feature soit considérée comme terminée. Toute documentation d'API (OpenAPI, guides, exemples) qui référence un endpoint DOIT correspondre à un handler serveur fonctionnel.

Rationale: Axum et SeaORM sont les frameworks standard pour Rust, offrant sécurité, performance et maintenabilité. L'utilisation exclusive de ces outils garantit la cohérence de l'architecture. La documentation officielle SeaORM contient les meilleures pratiques, les patterns recommandés et les solutions aux problèmes courants. En s'y référant systématiquement, on évite les erreurs d'implémentation, on améliore la maintenabilité et on garantit la compatibilité avec les futures versions de SeaORM. L'implémentation complète des handlers serveur est essentielle pour que l'API soit réellement utilisable par les clients. Des handlers stub créent une fausse impression de fonctionnalité et empêchent les tests d'intégration réels. Cette règle garantit que toute documentation d'API correspond à une implémentation fonctionnelle, évitant les frustrations des développeurs clients.

III. Développement Incrémental

Chaque fonctionnalité DOIT être complète et testée avant de passer à la suivante. L'architecture DOIT être modulaire (structure de dossiers claire, séparation des responsabilités). Les user stories DOIVENT être indépendantes et testables individuellement.

Rationale: Le développement incrémental permet de livrer de la valeur rapidement, facilite les tests et réduit la complexité. Chaque étape doit être validée avant de continuer.

IV. Sécurité par Défaut

Tous les secrets DOIVENT être stockés dans des variables d'environnement, JAMAIS dans le code. La validation et la sanitization des entrées utilisateur DOIVENT être effectuées systématiquement. L'authentification et l'autorisation RBAC DOIVENT être implémentées pour toutes les routes protégées.

JWT Authentication Standard (amendement v0.3.1): Le système DOIT extraire et vérifier les JWT tokens depuis le header Authorization au format Bearer <token>. Cette extraction DOIT être la méthode principale pour l'authentification API. Les cookies HttpOnly peuvent être utilisés comme méthode alternative pour les clients web, mais le header Authorization a priorité pour permettre aux clients API de surcharger l'authentification par cookie.

Conformité ANSSI Rust (amendement v0.4.0): Le code DOIT respecter les recommandations du Guide ANSSI pour le développement sécurisé en Rust. Spécifiquement :

Le code DOIT compiler avec #![deny(warnings)] activé (ou au minimum #![warn(warnings)])
Toute utilisation de unsafe DOIT être justifiée et documentée avec un commentaire // SAFETY: expliquant pourquoi unsafe est nécessaire et quels invariants doivent être respectés
Les unwrap() et expect() sont INTERDITS dans le code de production (sauf dans les tests unitaires). Toutes les erreurs DOIVENT être gérées explicitement avec Result<T, E> et l'opérateur ?
L'utilisation de std::mem::uninitialized est INTERDITE (dépréciée). L'utilisation de std::mem::MaybeUninit DOIT être justifiée pour chaque cas d'usage
Les outils cargo-audit et cargo-outdated DOIVENT être exécutés régulièrement. Les vulnérabilités détectées DOIVENT être corrigées avant chaque release
Toutes les considérations de sécurité, invariants et garanties DOIVENT être documentées

Voir docs/ANSSI_COMPLIANCE_REPORT.md pour le rapport de conformité détaillé et les actions prioritaires.

Rationale: La sécurité est critique pour un système cloud. Les secrets dans le code sont une vulnérabilité majeure. La validation des entrées prévient les attaques par injection. L'authentification JWT via header Authorization est le standard de l'industrie pour les APIs REST et permet une authentification stateless sécurisée. Les guidelines ANSSI représentent les meilleures pratiques pour le développement sécurisé en Rust. Leur respect garantit que les garanties de sécurité offertes par Rust ne sont pas invalidées par une utilisation incorrecte du langage.

V. Tests et Validation Continue

Tous les composants DOIVENT avoir des tests unitaires et d'intégration. La couverture de tests DOIT être > 80% (objectif > 90% pour les composants critiques). Les tests DOIVENT être exécutés avant chaque commit (cargo test). Les tests DOIVENT suivre les bonnes pratiques Rust (structure #[cfg(test)], tests d'intégration dans tests/integration/).

Rationale: Les tests garantissent la qualité et la fiabilité du code. Une couverture élevée réduit les régressions et facilite les refactorings. L'exécution automatique des tests avant commit maintient la qualité du codebase.

Technical Constraints

Framework Requirements

Rust Version: Rust 1.91.1+ (Edition 2024) - IMPORTANT: Version minimale requise pour Axum/SeaORM
Web Framework: Axum 0.8.7+ (dernière version stable)
ORM: SeaORM 2.0.x+ (requis pour toutes les interactions DB)
Runtime: Tokio 1.x (requis par Axum)
Database: PostgreSQL 18+ (recommandé)

Development Environment

Docker pour Base de Données (amendement v0.5.2): En développement, la base de données PostgreSQL DOIT être lancée via Docker depuis le dossier database/ à la racine du projet. Le développeur DOIT utiliser le fichier database/docker-compose.yml pour démarrer la base de données. La base de données est lancée et gérée par le développeur (pas automatiquement par le système). Cette configuration garantit un environnement de développement cohérent et isolé, facilite le partage de configuration entre développeurs, et permet un reset rapide de la base de données pour les tests.

Rationale: L'utilisation de Docker pour PostgreSQL en développement standardise l'environnement de développement, évite les conflits de versions entre développeurs, et simplifie la configuration initiale. Le développeur garde le contrôle sur le démarrage/arrêt de la base de données, permettant une meilleure gestion des ressources et une flexibilité dans le workflow de développement.

Code Quality Requirements

Toutes les fonctions publiques DOIVENT avoir une documentation ///
cargo clippy -- -D warnings DOIT passer sans erreur
cargo fmt DOIT être appliqué avant chaque commit
Les erreurs DOIVENT utiliser des types explicites (Result<T, AppError>)
#![deny(warnings)] DOIT être activé dans src/lib.rs ou src/main.rs (conformité ANSSI)
Les unwrap() et expect() sont INTERDITS dans le code de production (conformité ANSSI)
Toute utilisation de unsafe DOIT être documentée avec // SAFETY: (conformité ANSSI)

Testing Requirements

Tests unitaires dans le même fichier avec #[cfg(test)] ou dans tests/unit/
Tests d'intégration dans tests/integration/
Tests de contrat dans tests/contract/
Couverture > 80% (objectif > 90% pour auth, security, core services)

Security Requirements

Pas de secrets hardcodés (variables d'environnement uniquement)
Validation de toutes les entrées utilisateur
Hashing des mots de passe (bcrypt, jamais en clair)
JWT tokens: extraction depuis header Authorization: Bearer <token> (priorité 1)
Cookies HttpOnly pour les clients web (fallback, priorité 2)
Rate limiting sur les endpoints d'authentification
Logging de tous les événements d'authentification (succès et échecs)
Conformité aux guidelines ANSSI Rust (voir docs/ANSSI_COMPLIANCE_REPORT.md)
Code unsafe minimisé et documenté avec // SAFETY:
Gestion d'erreurs explicite (pas de panics en production)

Development Workflow

Code Review Process

Toutes les pull requests DOIVENT être revues avant merge. Les reviewers DOIVENT vérifier la conformité avec cette constitution. Les violations constitutionnelles DOIVENT être corrigées avant merge.

Quality Gates

✅ cargo build passe sans erreur
✅ cargo test passe (tous les tests)
✅ cargo clippy -- -D warnings passe
✅ cargo fmt --check passe
✅ Couverture de tests > 80%
✅ Documentation complète (cargo doc génère sans warnings)
✅ cargo audit ne signale pas de vulnérabilités (avant release, conformité ANSSI)
✅ cargo outdated a été vérifié (avant release, conformité ANSSI)
✅ Aucun unwrap()/expect() dans le code de production (sauf tests, conformité ANSSI)
✅ Tous les blocs unsafe sont documentés avec // SAFETY: (conformité ANSSI)

Testing Strategy

TDD recommandé: Écrire les tests avant l'implémentation pour les nouvelles fonctionnalités
Tests unitaires: Pour chaque fonction publique, tester les cas normaux et d'erreur
Tests d'intégration: Pour chaque endpoint API, tester les scénarios complets
Tests de contrat: Pour chaque endpoint public, valider le format de réponse

Governance

Cette constitution prévaut sur toutes les autres pratiques du projet. Les amendements nécessitent une documentation, une approbation et un plan de migration si nécessaire.

Version: 0.5.2 | Ratified: 2025-12-09 | Last Amended: 2025-01-29

Compliance: Toutes les PRs et reviews DOIVENT vérifier la conformité avec cette constitution. La complexité DOIT être justifiée. Utiliser les templates dans .specify/templates/ pour la documentation des features.

eric / rustwarden