sdk_storage/README.md

# 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/`.

## 🆘 Support

- **Issues** : [GitLab Issues](https://git.4nkweb.com/4nk/sdk_storage/-/issues)
- **Documentation** : [docs/](docs/)
- **API** : Voir section API Reference ci-dessus