docs: Mise à jour complète du README.md avec API REST et configuration Docker
Some checks failed
Docker Image / docker (push) Failing after 20s
Some checks failed
Docker Image / docker (push) Failing after 20s
This commit is contained in:
Debian
parent
9642616bcd
commit
59821b1d41
322
README.md
322
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/`.
|
Voir la documentation détaillée dans `docs/`.
|
||||||
|
|
||||||
## Démarrage rapide
|
## 🆘 Support
|
||||||
|
|
||||||
- Construire: `cargo build`
|
- **Issues** : [GitLab Issues](https://git.4nkweb.com/4nk/sdk_storage/-/issues)
|
||||||
- Lancer: `cargo run -- --permanent` (clé sans TTL = permanente)
|
- **Documentation** : [docs/](docs/)
|
||||||
- Tester: `cargo test`
|
- **API** : Voir section API Reference ci-dessus
|
||||||
|
|
||||||
## 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).
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user