713 lines
11 KiB
Markdown
713 lines
11 KiB
Markdown
# 📖 Guide d'Utilisation - sdk_relay
|
|
|
|
Guide complet pour utiliser le service de relais sdk_relay au quotidien.
|
|
|
|
## 🚀 Démarrage Rapide
|
|
|
|
### Démarrage du Service
|
|
|
|
#### Avec Docker (Recommandé)
|
|
|
|
```bash
|
|
# Build de l'image
|
|
docker build -f Dockerfile -t sdk_relay .
|
|
|
|
# Démarrage du service
|
|
docker run -d \
|
|
--name sdk_relay \
|
|
-p 8090:8090 \
|
|
-p 8091:8091 \
|
|
-v $(pwd)/.conf:/app/.conf \
|
|
-e RUST_LOG=info \
|
|
sdk_relay
|
|
|
|
# Vérifier le statut
|
|
docker ps | grep sdk_relay
|
|
```
|
|
|
|
#### Avec Rust (Compilation native)
|
|
|
|
```bash
|
|
# Compilation release
|
|
cargo build --release
|
|
|
|
# Démarrage du service
|
|
cargo run --release -- --config .conf
|
|
|
|
# Ou en arrière-plan
|
|
nohup cargo run --release -- --config .conf > sdk_relay.log 2>&1 &
|
|
```
|
|
|
|
### Vérification du Démarrage
|
|
|
|
```bash
|
|
# Test de santé HTTP
|
|
curl http://localhost:8091/health
|
|
|
|
# Réponse attendue
|
|
{
|
|
"status": "healthy",
|
|
"timestamp": "2024-01-01T12:00:00Z",
|
|
"version": "1.0.0"
|
|
}
|
|
|
|
# Test WebSocket
|
|
wscat -c ws://localhost:8090
|
|
|
|
# Test métriques
|
|
curl http://localhost:8091/metrics
|
|
```
|
|
|
|
## 🔌 Connexion WebSocket
|
|
|
|
### Handshake Initial
|
|
|
|
#### Envoi du Handshake
|
|
|
|
```json
|
|
{
|
|
"type": "handshake",
|
|
"version": "1.0",
|
|
"client_id": "my_client_001",
|
|
"capabilities": ["silent_payments", "relay_sync"]
|
|
}
|
|
```
|
|
|
|
#### Réponse du Handshake
|
|
|
|
```json
|
|
{
|
|
"type": "handshake_response",
|
|
"status": "success",
|
|
"server_version": "1.0.0",
|
|
"capabilities": ["silent_payments", "relay_sync", "metrics"],
|
|
"session_id": "session_12345"
|
|
}
|
|
```
|
|
|
|
### Gestion des Sessions
|
|
|
|
#### Reconnexion Automatique
|
|
|
|
```javascript
|
|
// Exemple JavaScript
|
|
const ws = new WebSocket('ws://localhost:8090');
|
|
|
|
ws.onopen = function() {
|
|
// Envoyer handshake
|
|
ws.send(JSON.stringify({
|
|
type: "handshake",
|
|
version: "1.0",
|
|
client_id: "my_client_001"
|
|
}));
|
|
};
|
|
|
|
ws.onclose = function() {
|
|
// Reconnexion automatique après 5 secondes
|
|
setTimeout(() => {
|
|
connectWebSocket();
|
|
}, 5000);
|
|
};
|
|
```
|
|
|
|
#### Heartbeat
|
|
|
|
```json
|
|
// Ping toutes les 30 secondes
|
|
{
|
|
"type": "ping",
|
|
"timestamp": "2024-01-01T12:00:00Z"
|
|
}
|
|
|
|
// Réponse pong
|
|
{
|
|
"type": "pong",
|
|
"timestamp": "2024-01-01T12:00:00Z"
|
|
}
|
|
```
|
|
|
|
## 📡 API HTTP REST
|
|
|
|
### Endpoints de Base
|
|
|
|
#### GET /health
|
|
```bash
|
|
curl http://localhost:8091/health
|
|
```
|
|
|
|
**Réponse :**
|
|
```json
|
|
{
|
|
"status": "healthy",
|
|
"uptime": 3600,
|
|
"version": "1.0.0",
|
|
"connections": {
|
|
"websocket": 5,
|
|
"http": 2
|
|
}
|
|
}
|
|
```
|
|
|
|
#### GET /metrics
|
|
```bash
|
|
curl http://localhost:8091/metrics
|
|
```
|
|
|
|
**Réponse :**
|
|
```json
|
|
{
|
|
"requests_total": 1250,
|
|
"requests_per_second": 2.5,
|
|
"websocket_connections": 5,
|
|
"memory_usage_mb": 45.2,
|
|
"cpu_usage_percent": 12.5
|
|
}
|
|
```
|
|
|
|
#### GET /relays
|
|
```bash
|
|
curl http://localhost:8091/relays
|
|
```
|
|
|
|
**Réponse :**
|
|
```json
|
|
{
|
|
"relays": [
|
|
{
|
|
"id": "relay_001",
|
|
"address": "ws://relay1.example.com:8090",
|
|
"status": "connected",
|
|
"last_seen": "2024-01-01T12:00:00Z"
|
|
},
|
|
{
|
|
"id": "relay_002",
|
|
"address": "ws://relay2.example.com:8090",
|
|
"status": "disconnected",
|
|
"last_seen": "2024-01-01T11:30:00Z"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Endpoints de Gestion
|
|
|
|
#### POST /sync/force
|
|
```bash
|
|
curl -X POST http://localhost:8091/sync/force
|
|
```
|
|
|
|
**Réponse :**
|
|
```json
|
|
{
|
|
"status": "sync_started",
|
|
"relays_count": 3,
|
|
"estimated_duration": 30
|
|
}
|
|
```
|
|
|
|
#### POST /relays/add
|
|
```bash
|
|
curl -X POST http://localhost:8091/relays/add \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"address": "ws://newrelay.example.com:8090",
|
|
"description": "Nouveau relais"
|
|
}'
|
|
```
|
|
|
|
#### DELETE /relays/{id}
|
|
```bash
|
|
curl -X DELETE http://localhost:8091/relays/relay_001
|
|
```
|
|
|
|
## 🔄 Synchronisation des Relais
|
|
|
|
### Architecture Mesh
|
|
|
|
#### Découverte des Relais
|
|
|
|
```json
|
|
// Message de découverte
|
|
{
|
|
"type": "discovery",
|
|
"relay_id": "relay_001",
|
|
"timestamp": "2024-01-01T12:00:00Z"
|
|
}
|
|
|
|
// Réponse avec liste des relais
|
|
{
|
|
"type": "discovery_response",
|
|
"relays": [
|
|
{
|
|
"id": "relay_002",
|
|
"address": "ws://relay2.example.com:8090",
|
|
"capabilities": ["silent_payments"]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### Synchronisation des Messages
|
|
|
|
```json
|
|
// Message de synchronisation
|
|
{
|
|
"type": "sync_message",
|
|
"message_id": "msg_12345",
|
|
"content": {
|
|
"type": "silent_payment",
|
|
"data": "..."
|
|
},
|
|
"timestamp": "2024-01-01T12:00:00Z",
|
|
"ttl": 3600
|
|
}
|
|
|
|
// Accusé de réception
|
|
{
|
|
"type": "sync_ack",
|
|
"message_id": "msg_12345",
|
|
"status": "received"
|
|
}
|
|
```
|
|
|
|
### Gestion des Conflits
|
|
|
|
#### Résolution de Conflits
|
|
|
|
```json
|
|
// Détection de conflit
|
|
{
|
|
"type": "conflict_detected",
|
|
"message_id": "msg_12345",
|
|
"conflict_type": "duplicate",
|
|
"resolution": "keep_latest"
|
|
}
|
|
```
|
|
|
|
## 💰 Silent Payments
|
|
|
|
### Gestion des Paiements
|
|
|
|
#### Création d'un Paiement
|
|
|
|
```json
|
|
// Demande de création
|
|
{
|
|
"type": "create_payment",
|
|
"payment_id": "pay_12345",
|
|
"amount_sats": 100000,
|
|
"recipient": "sp1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
|
|
"metadata": {
|
|
"description": "Paiement test"
|
|
}
|
|
}
|
|
|
|
// Confirmation
|
|
{
|
|
"type": "payment_created",
|
|
"payment_id": "pay_12345",
|
|
"status": "pending",
|
|
"created_at": "2024-01-01T12:00:00Z"
|
|
}
|
|
```
|
|
|
|
#### Suivi des Paiements
|
|
|
|
```json
|
|
// Mise à jour de statut
|
|
{
|
|
"type": "payment_update",
|
|
"payment_id": "pay_12345",
|
|
"status": "confirmed",
|
|
"block_height": 800000,
|
|
"txid": "abc123...",
|
|
"updated_at": "2024-01-01T12:05:00Z"
|
|
}
|
|
```
|
|
|
|
### Intégration Bitcoin Core
|
|
|
|
#### Vérification des Blocs
|
|
|
|
```json
|
|
// Notification de nouveau bloc
|
|
{
|
|
"type": "block_notification",
|
|
"block_height": 800001,
|
|
"block_hash": "def456...",
|
|
"timestamp": "2024-01-01T12:10:00Z"
|
|
}
|
|
```
|
|
|
|
#### Scan des Transactions
|
|
|
|
```json
|
|
// Demande de scan
|
|
{
|
|
"type": "scan_request",
|
|
"addresses": [
|
|
"sp1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
|
|
],
|
|
"from_block": 800000,
|
|
"to_block": 800001
|
|
}
|
|
|
|
// Résultats du scan
|
|
{
|
|
"type": "scan_response",
|
|
"results": [
|
|
{
|
|
"address": "sp1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
|
|
"transactions": [
|
|
{
|
|
"txid": "abc123...",
|
|
"amount_sats": 100000,
|
|
"block_height": 800001
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## 📊 Monitoring et Métriques
|
|
|
|
### Métriques en Temps Réel
|
|
|
|
#### Métriques Système
|
|
|
|
```bash
|
|
# Métriques système
|
|
curl http://localhost:8091/metrics/system
|
|
|
|
# Réponse
|
|
{
|
|
"cpu_usage_percent": 12.5,
|
|
"memory_usage_mb": 45.2,
|
|
"disk_usage_percent": 25.0,
|
|
"network_io_mbps": 1.2
|
|
}
|
|
```
|
|
|
|
#### Métriques Métier
|
|
|
|
```bash
|
|
# Métriques métier
|
|
curl http://localhost:8091/metrics/business
|
|
|
|
# Réponse
|
|
{
|
|
"payments_processed": 1250,
|
|
"payments_confirmed": 1200,
|
|
"relays_connected": 5,
|
|
"messages_synced": 5000
|
|
}
|
|
```
|
|
|
|
### Alertes et Notifications
|
|
|
|
#### Configuration des Alertes
|
|
|
|
```json
|
|
// Configuration d'alerte
|
|
{
|
|
"type": "alert_config",
|
|
"alert_id": "high_cpu",
|
|
"condition": "cpu_usage > 80",
|
|
"action": "notify_admin",
|
|
"enabled": true
|
|
}
|
|
```
|
|
|
|
#### Notifications
|
|
|
|
```json
|
|
// Notification d'alerte
|
|
{
|
|
"type": "alert",
|
|
"alert_id": "high_cpu",
|
|
"severity": "warning",
|
|
"message": "CPU usage is 85%",
|
|
"timestamp": "2024-01-01T12:00:00Z"
|
|
}
|
|
```
|
|
|
|
## 🔧 Gestion des Erreurs
|
|
|
|
### Types d'Erreurs
|
|
|
|
#### Erreurs de Connexion
|
|
|
|
```json
|
|
// Erreur de connexion WebSocket
|
|
{
|
|
"type": "error",
|
|
"error_code": "WS_CONNECTION_FAILED",
|
|
"message": "Failed to connect to relay",
|
|
"details": {
|
|
"relay_id": "relay_001",
|
|
"attempt": 3
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Erreurs de Validation
|
|
|
|
```json
|
|
// Erreur de validation
|
|
{
|
|
"type": "error",
|
|
"error_code": "VALIDATION_ERROR",
|
|
"message": "Invalid payment amount",
|
|
"details": {
|
|
"field": "amount_sats",
|
|
"value": -100,
|
|
"expected": "positive integer"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Gestion des Erreurs
|
|
|
|
#### Retry Automatique
|
|
|
|
```json
|
|
// Configuration retry
|
|
{
|
|
"type": "retry_config",
|
|
"max_attempts": 3,
|
|
"backoff_ms": 1000,
|
|
"max_backoff_ms": 30000
|
|
}
|
|
```
|
|
|
|
#### Fallback
|
|
|
|
```json
|
|
// Stratégie de fallback
|
|
{
|
|
"type": "fallback_config",
|
|
"primary_relay": "relay_001",
|
|
"backup_relays": ["relay_002", "relay_003"],
|
|
"failover_timeout_ms": 5000
|
|
}
|
|
```
|
|
|
|
## 🛠️ Maintenance
|
|
|
|
### Sauvegarde
|
|
|
|
#### Sauvegarde de Configuration
|
|
|
|
```bash
|
|
# Sauvegarde de la configuration
|
|
cp .conf .conf.backup.$(date +%Y%m%d)
|
|
|
|
# Sauvegarde des logs
|
|
tar -czf logs_$(date +%Y%m%d).tar.gz logs/
|
|
```
|
|
|
|
#### Sauvegarde des Données
|
|
|
|
```bash
|
|
# Export des données
|
|
curl http://localhost:8091/export/data > data_export_$(date +%Y%m%d).json
|
|
|
|
# Import des données
|
|
curl -X POST http://localhost:8091/import/data \
|
|
-H "Content-Type: application/json" \
|
|
-d @data_export_20240101.json
|
|
```
|
|
|
|
### Mise à Jour
|
|
|
|
#### Mise à Jour du Service
|
|
|
|
```bash
|
|
# Arrêt du service
|
|
docker stop sdk_relay
|
|
|
|
# Pull de la nouvelle image
|
|
docker pull sdk_relay:latest
|
|
|
|
# Redémarrage
|
|
docker run -d \
|
|
--name sdk_relay_new \
|
|
-p 8090:8090 \
|
|
-p 8091:8091 \
|
|
-v $(pwd)/.conf:/app/.conf \
|
|
sdk_relay:latest
|
|
|
|
# Vérification
|
|
curl http://localhost:8091/health
|
|
```
|
|
|
|
#### Migration des Données
|
|
|
|
```bash
|
|
# Script de migration
|
|
./scripts/migrate_data.sh
|
|
|
|
# Vérification post-migration
|
|
cargo test --test migration
|
|
```
|
|
|
|
## 🔒 Sécurité
|
|
|
|
### Authentification
|
|
|
|
#### Authentification par Token
|
|
|
|
```bash
|
|
# Génération de token
|
|
curl -X POST http://localhost:8091/auth/token \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"username": "admin",
|
|
"password": "secure_password"
|
|
}'
|
|
|
|
# Utilisation du token
|
|
curl -H "Authorization: Bearer YOUR_TOKEN" \
|
|
http://localhost:8091/admin/status
|
|
```
|
|
|
|
#### Authentification par Certificat
|
|
|
|
```bash
|
|
# Connexion avec certificat client
|
|
curl --cert client.pem --key client.key \
|
|
https://localhost:8091/secure/endpoint
|
|
```
|
|
|
|
### Chiffrement
|
|
|
|
#### Chiffrement des Messages
|
|
|
|
```json
|
|
// Message chiffré
|
|
{
|
|
"type": "encrypted_message",
|
|
"encryption": "AES-256-GCM",
|
|
"data": "encrypted_payload_here",
|
|
"iv": "initialization_vector"
|
|
}
|
|
```
|
|
|
|
## 📈 Performance
|
|
|
|
### Optimisations
|
|
|
|
#### Pool de Connexions
|
|
|
|
```json
|
|
// Configuration du pool
|
|
{
|
|
"type": "pool_config",
|
|
"max_connections": 100,
|
|
"min_connections": 10,
|
|
"connection_timeout_ms": 5000
|
|
}
|
|
```
|
|
|
|
#### Cache
|
|
|
|
```json
|
|
// Configuration du cache
|
|
{
|
|
"type": "cache_config",
|
|
"max_size_mb": 100,
|
|
"ttl_seconds": 3600,
|
|
"eviction_policy": "lru"
|
|
}
|
|
```
|
|
|
|
### Benchmarks
|
|
|
|
#### Tests de Performance
|
|
|
|
```bash
|
|
# Test de charge
|
|
ab -n 1000 -c 10 http://localhost:8091/health
|
|
|
|
# Test WebSocket
|
|
./scripts/websocket_benchmark.sh
|
|
|
|
# Test de synchronisation
|
|
cargo test --test performance
|
|
```
|
|
|
|
## 🚨 Dépannage
|
|
|
|
### Problèmes Courants
|
|
|
|
#### Service ne démarre pas
|
|
|
|
```bash
|
|
# Vérifier les logs
|
|
docker logs sdk_relay
|
|
|
|
# Vérifier la configuration
|
|
cargo run -- --config .conf --check
|
|
|
|
# Vérifier les ports
|
|
netstat -tlnp | grep 809
|
|
```
|
|
|
|
#### Connexions WebSocket échouent
|
|
|
|
```bash
|
|
# Test de connectivité
|
|
telnet localhost 8090
|
|
|
|
# Vérifier le firewall
|
|
sudo ufw status
|
|
|
|
# Test avec wscat
|
|
wscat -c ws://localhost:8090
|
|
```
|
|
|
|
#### Synchronisation lente
|
|
|
|
```bash
|
|
# Vérifier les métriques
|
|
curl http://localhost:8091/metrics
|
|
|
|
# Vérifier les relais
|
|
curl http://localhost:8091/relays
|
|
|
|
# Forcer une synchronisation
|
|
curl -X POST http://localhost:8091/sync/force
|
|
```
|
|
|
|
### Logs et Debugging
|
|
|
|
#### Niveaux de Log
|
|
|
|
```bash
|
|
# Log détaillé
|
|
RUST_LOG=debug cargo run -- --config .conf
|
|
|
|
# Log spécifique
|
|
RUST_LOG=sdk_relay::websocket=debug cargo run -- --config .conf
|
|
```
|
|
|
|
#### Analyse des Logs
|
|
|
|
```bash
|
|
# Logs en temps réel
|
|
tail -f logs/sdk_relay.log
|
|
|
|
# Recherche d'erreurs
|
|
grep ERROR logs/sdk_relay.log
|
|
|
|
# Statistiques des logs
|
|
awk '/ERROR/ {count++} END {print count}' logs/sdk_relay.log
|
|
```
|
|
|
|
---
|
|
|
|
**🎯 Service sdk_relay - Prêt pour une utilisation en production !** ✨
|
|
|
|
|