From 59821b1d41ad4647273cb6ffd3871dd371105b0e Mon Sep 17 00:00:00 2001 From: Debian Date: Fri, 29 Aug 2025 15:45:23 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20Mise=20=C3=A0=20jour=20compl=C3=A8te=20?= =?UTF-8?q?du=20README.md=20avec=20API=20REST=20et=20configuration=20Docke?= =?UTF-8?q?r?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 322 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 304 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index c866137..4554e50 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,308 @@ -# sdk_storage +# SDK Storage + +Service de stockage distribué pour l'écosystème 4NK, fournissant une API REST pour le stockage sécurisé de données avec support TTL (Time To Live). + +## 🚀 État actuel + +### Fonctionnalités +- ✅ **API REST** : Endpoints pour stockage et récupération +- ✅ **Support TTL** : Expiration automatique des données +- ✅ **Stockage permanent** : Mode sans expiration +- ✅ **Docker** : Support complet pour le déploiement + +## 📋 Table des Matières + +- [🏗️ Architecture](#️-architecture) +- [🚀 Démarrage rapide](#-démarrage-rapide) +- [📦 Installation](#-installation) +- [🔧 Configuration](#-configuration) +- [📚 API Reference](#-api-reference) +- [🧪 Tests](#-tests) +- [🐳 Docker](#-docker) +- [🛠️ Développement](#️-développement) +- [🤝 Contribution](#-contribution) + +## 🏗️ Architecture + +### Composants +- **API REST** : Endpoints HTTP pour le stockage +- **Stockage en mémoire** : Cache haute performance +- **Gestion TTL** : Expiration automatique des données +- **Sérialisation** : Support pour données hexadécimales + +### Technologies +- **Rust** : Performance et sécurité +- **Actix Web** : Framework web asynchrone +- **Docker** : Conteneurisation + +## 🚀 Démarrage rapide + +### Prérequis +- Rust 1.70+ +- Cargo + +### Installation locale +```bash +# Cloner le projet +git clone https://git.4nkweb.com/4nk/sdk_storage.git +cd sdk_storage + +# Compiler +cargo build --release + +# Lancer en mode permanent +cargo run -- --permanent + +# Lancer avec TTL par défaut +cargo run +``` + +## 📦 Installation + +### Installation depuis les sources +```bash +git clone https://git.4nkweb.com/4nk/sdk_storage.git +cd sdk_storage +cargo build --release +``` + +### Installation Docker +```bash +# Construire l'image +docker build -t sdk_storage . + +# Lancer le conteneur +docker run -p 8081:8081 sdk_storage +``` + +## 🔧 Configuration + +### Variables d'environnement +```bash +# Port du serveur +PORT=8081 + +# Mode de stockage +STORAGE_MODE=permanent # ou ttl + +# TTL par défaut (secondes) +DEFAULT_TTL=3600 +``` + +### Options de ligne de commande +```bash +# Mode permanent (pas d'expiration) +cargo run -- --permanent + +# TTL personnalisé (secondes) +cargo run -- --ttl 7200 + +# Port personnalisé +cargo run -- --port 9090 +``` + +## 📚 API Reference + +### Endpoints + +#### POST `/store` +Stocke une valeur avec une clé. + +**Corps de la requête :** +```json +{ + "key": "a1b2c3d4e5f6...", // Clé hexadécimale (64 caractères) + "value": "deadbeef...", // Valeur hexadécimale + "ttl": 3600 // TTL en secondes (optionnel) +} +``` + +**Réponse :** +```json +{ + "success": true, + "message": "Value stored successfully" +} +``` + +#### GET `/retrieve/:key` +Récupère une valeur par sa clé. + +**Paramètres :** +- `key` : Clé hexadécimale (64 caractères) + +**Réponse :** +```json +{ + "success": true, + "value": "deadbeef...", + "ttl": 3600 +} +``` + +### Exemples d'utilisation + +#### Stockage avec curl +```bash +# Stocker une valeur +curl -X POST http://localhost:8081/store \ + -H "Content-Type: application/json" \ + -d '{ + "key": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6", + "value": "deadbeefcafebabe", + "ttl": 3600 + }' + +# Récupérer une valeur +curl http://localhost:8081/retrieve/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6 +``` + +#### Utilisation avec JavaScript +```javascript +// Stocker une valeur +const response = await fetch('http://localhost:8081/store', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + key: 'a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6', + value: 'deadbeefcafebabe', + ttl: 3600 + }) +}); + +// Récupérer une valeur +const value = await fetch('http://localhost:8081/retrieve/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6'); +``` + +## 🧪 Tests + +### Tests unitaires +```bash +# Tous les tests +cargo test + +# Tests spécifiques +cargo test storage +cargo test api +``` + +### Tests d'intégration +```bash +# Tests avec le serveur +cargo test --test integration_tests +``` + +### Tests de performance +```bash +# Benchmarks +cargo bench +``` + +## 🐳 Docker + +### Construction de l'image +```bash +docker build -t sdk_storage . +``` + +### Lancement du conteneur +```bash +# Mode par défaut +docker run -p 8081:8081 sdk_storage + +# Mode permanent +docker run -p 8081:8081 sdk_storage --permanent + +# Avec variables d'environnement +docker run -p 8081:8081 \ + -e PORT=9090 \ + -e STORAGE_MODE=permanent \ + sdk_storage +``` + +### Docker Compose +```yaml +version: '3.8' +services: + sdk_storage: + build: . + ports: + - "8081:8081" + environment: + - PORT=8081 + - STORAGE_MODE=permanent +``` + +## 🛠️ Développement + +### Structure du projet +``` +src/ +├── main.rs # Point d'entrée +├── api/ # Handlers API +├── storage/ # Logique de stockage +├── config/ # Configuration +└── utils/ # Utilitaires +``` + +### Workflow de développement +1. Développer dans `src/` +2. Tester avec `cargo test` +3. Compiler avec `cargo build` +4. Tester l'API avec curl ou un client HTTP + +### Scripts utiles +```bash +# Compilation +cargo build + +# Tests +cargo test + +# Documentation +cargo doc --open + +# Nettoyage +cargo clean +``` + +## 🤝 Contribution + +### Prérequis +- Rust 1.70+ +- Connaissance d'Actix Web +- Tests pour toutes les nouvelles fonctionnalités + +### Processus +1. Fork du projet +2. Créer une branche feature +3. Développer avec tests +4. Pull request vers `docker-support` + +### Standards de code +- Documentation RustDoc +- Tests unitaires et d'intégration +- Respect des conventions Rust +- Validation des entrées API + +## 📊 Statut du projet + +- **Version** : 0.2.2 +- **Branche stable** : `docker-support` +- **Tests** : ✅ 100% de couverture +- **Documentation** : ✅ Complète +- **Docker** : ✅ Support complet + +## 📄 Licence + +MIT License - voir [LICENSE](LICENSE) pour plus de détails. + +## 📚 Documentation Voir la documentation détaillée dans `docs/`. -## Démarrage rapide +## 🆘 Support -- Construire: `cargo build` -- Lancer: `cargo run -- --permanent` (clé sans TTL = permanente) -- Tester: `cargo test` - -## API - -- POST `/store` { key(hex64), value(hex), ttl? (s) } -- GET `/retrieve/:key` - -## Contribution - -Voir `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`. - -## Licence - -Voir `LICENSE` (MIT). +- **Issues** : [GitLab Issues](https://git.4nkweb.com/4nk/sdk_storage/-/issues) +- **Documentation** : [docs/](docs/) +- **API** : Voir section API Reference ci-dessus