4NK_node/specs/spec-technique.md

# Spécification Technique - Synchronisation entre Relais

## Vue d'ensemble

Cette spécification décrit l'implémentation de la synchronisation entre relais dans le réseau 4NK, permettant la communication et le partage de données entre plusieurs instances de `sdk_relay`.

## Architecture de Synchronisation

### 1. Gestionnaire de Synchronisation (`SyncManager`)

Le `SyncManager` est le composant central qui gère toute la logique de synchronisation :

```rust
pub struct SyncManager {
    relay_id: String,
    sequence_counter: Arc<Mutex<u64>>,
    sync_cache: Arc<Mutex<HashMap<String, Instant>>>,
    last_sync: Arc<Mutex<HashMap<SyncType, u64>>>,
    mesh_connections: Arc<Mutex<HashMap<String, MeshConnection>>>,
    known_relays: Arc<Mutex<HashMap<String, RelayInfo>>>,
    metrics: Arc<Mutex<SyncMetrics>>,
}
```

### 2. Types de Synchronisation

Les types de synchronisation supportés :

- **StateSync** : Synchronisation de l'état général du relais
- **ProcessSync** : Synchronisation des processus en cours
- **MemberSync** : Synchronisation des membres
- **TxSync** : Synchronisation des transactions
- **BlockSync** : Synchronisation des blocs
- **PeerSync** : Synchronisation des pairs connectés
- **RelaySync** : Synchronisation des informations des relais
- **HealthSync** : Synchronisation de la santé du relais
- **MetricsSync** : Synchronisation des métriques
- **ConfigSync** : Synchronisation de la configuration
- **CapabilitySync** : Synchronisation des capacités

### 3. Messages de Synchronisation

#### Structure des Messages

```rust
pub struct SyncMessage {
    pub sync_type: SyncType,
    pub relay_id: String,
    pub sequence: u64,
    pub timestamp: u64,
    pub payload: SyncPayload,
}
```

#### Types de Payload

```rust
pub enum SyncPayload {
    StateData { state: String, version: String },
    ProcessData { processes: HashMap<String, String> },
    MemberData { members: HashMap<String, String> },
    HealthData { status: HealthStatus, uptime: u64, cpu_usage: f64 },
    MetricsData { metrics: SyncMetrics },
    PeerData { peers: Vec<PeerInfo>, last_seen: u64 },
    RelayData { relays: Vec<RelayInfo>, network_topology: NetworkTopology },
}
```

## Fonctionnalités Implémentées

### 1. Découverte Automatique des Relais

Le système implémente une découverte automatique des relais dans le réseau :

```rust
pub async fn discover_relays(&self) -> Result<()> {
    let relay_hosts = vec![
        "sdk_relay_1",
        "sdk_relay_2",
        "sdk_relay_3",
    ];

    for host in relay_hosts {
        if host == self.relay_id {
            continue; // Ignorer soi-même
        }

        let relay_info = RelayInfo {
            relay_id: host.to_string(),
            address: format!("{}:8090", host),
            // ... autres champs
        };

        self.add_relay(relay_info)?;
    }

    Ok(())
}
```

### 2. Cache de Déduplication

Pour éviter les doublons, un cache de déduplication est implémenté :

```rust
pub struct MessageCache {
    cache: Arc<Mutex<HashMap<String, Instant>>>,
}

impl MessageCache {
    pub fn is_duplicate(&self, message_id: &str) -> bool {
        let mut cache = self.cache.lock().unwrap();
        if cache.contains_key(message_id) {
            true
        } else {
            cache.insert(message_id.to_string(), Instant::now());
            false
        }
    }
}
```

### 3. Synchronisation Périodique

Le système effectue une synchronisation périodique :

- **Synchronisation d'état** : Toutes les 30 secondes
- **Synchronisation de santé** : Toutes les 60 secondes
- **Synchronisation de métriques** : Toutes les 120 secondes
- **Synchronisation des relais** : Toutes les 300 secondes (5 minutes)

### 4. Gestion des Connexions Mesh

```rust
pub struct MeshConnection {
    pub relay_id: String,
    pub address: String,
    pub connected_since: u64,
    pub last_heartbeat: u64,
    pub status: ConnectionStatus,
}
```

## Configuration Multi-Relais

### Configuration Docker

Le système supporte la configuration de plusieurs relais via Docker :

```yaml
services:
  sdk_relay_1:
    container_name: sdk_relay_1
    ports:
      - "8090:8090"
      - "8091:8091"
    environment:
      - ENABLE_SYNC_TEST=1

  sdk_relay_2:
    container_name: sdk_relay_2
    ports:
      - "8092:8090"
      - "8093:8091"
    environment:
      - ENABLE_SYNC_TEST=1

  sdk_relay_3:
    container_name: sdk_relay_3
    ports:
      - "8094:8090"
      - "8095:8091"
    environment:
      - ENABLE_SYNC_TEST=1
```

### Configuration par Relais

Chaque relais a sa propre configuration :

```ini
# .conf.docker.relay1
relay_id=relay-1
ws_url=0.0.0.0:8090

# .conf.docker.relay2
relay_id=relay-2
ws_url=0.0.0.0:8090

# .conf.docker.relay3
relay_id=relay-3
ws_url=0.0.0.0:8090
```

## Métriques de Synchronisation

```rust
pub struct SyncMetrics {
    pub messages_sent: u64,
    pub messages_received: u64,
    pub sync_requests: u64,
    pub sync_responses: u64,
    pub errors: u64,
    pub last_sync: u64,
    pub avg_latency: f64,
}
```

## Sécurité et Validation

### 1. Validation des Messages

- Vérification de l'ID du relais émetteur
- Validation du timestamp pour éviter les attaques par rejeu
- Vérification de la séquence pour détecter les messages manquants

### 2. Déduplication

- Cache des messages reçus avec TTL
- Nettoyage automatique du cache toutes les 5 minutes
- Prévention des boucles de synchronisation

## Tests et Validation

### Script de Test

Un script de test automatisé est fourni :

```bash
#!/bin/bash
# test_3_relays.sh

echo "🚀 Test de synchronisation avec 3 relais"
echo "========================================"

# Démarrage des services
docker-compose up -d tor bitcoin blindbit
sleep 30

# Démarrage des 3 relais
docker-compose up -d sdk_relay_1 sdk_relay_2 sdk_relay_3
sleep 60

# Surveillance des logs
docker-compose logs -f sdk_relay_1 sdk_relay_2 sdk_relay_3
```

### Validation des Fonctionnalités

1. **Découverte automatique** : Les relais se découvrent mutuellement
2. **Partage des listes** : Les relais partagent leurs listes de relais connus
3. **Synchronisation d'état** : Les états sont synchronisés périodiquement
4. **Métriques** : Les métriques sont collectées et partagées
5. **Santé** : Le statut de santé est surveillé et partagé

## Prochaines Étapes

### 1. Améliorations Planifiées

- [ ] Implémentation de la signature des messages
- [ ] Optimisation des performances pour de gros volumes
- [ ] Implémentation de la fusion des données entre relais
- [ ] Ajout de la compression des messages

### 2. Fonctionnalités Avancées

- [ ] Routage intelligent des messages
- [ ] Gestion de la tolérance aux pannes
- [ ] Synchronisation différentielle
- [ ] Monitoring en temps réel

### 3. Tests Avancés

- [ ] Tests de charge avec de nombreux relais
- [ ] Tests de résilience (arrêt/redémarrage de relais)
- [ ] Tests de sécurité (messages malveillants)
- [ ] Tests de performance (latence, débit)

## Conclusion

L'implémentation de la synchronisation entre relais fournit une base solide pour la communication distribuée dans le réseau 4NK. Le système est conçu pour être extensible, sécurisé et performant, permettant une croissance future du réseau tout en maintenant la cohérence des données.