sdk_relay/docs/API.md

API Reference - sdk_relay

Vue d'Ensemble

sdk_relay expose deux interfaces principales :

• WebSocket (port 8090) : Communication temps réel
• HTTP (port 8091) : API REST

Interface WebSocket

Connexion

const ws = new WebSocket('ws://localhost:8090');

Handshake Initial

// Message de handshake
const handshake = {
    "type": "handshake",
    "client_id": "my-client",
    "version": "1.0.0",
    "capabilities": ["sync", "notifications"]
};

ws.send(JSON.stringify(handshake));

Types de Messages

1. Messages de Synchronisation

{
    "type": "sync",
    "sync_type": "StateSync",
    "relay_id": "relay-1",
    "payload": {
        "state": {
            "uptime": "3600",
            "version": "1.0.0",
            "network": "signet"
        }
    },
    "timestamp": 1703001600,
    "message_id": "msg-123"
}

2. Messages de Notification

{
    "type": "notification",
    "notification_type": "payment_detected",
    "data": {
        "txid": "abc123...",
        "block_height": 12345,
        "amount": "0.001",
        "address": "sp1..."
    },
    "timestamp": 1703001600
}

3. Messages de Santé

{
    "type": "health",
    "status": "healthy",
    "metrics": {
        "uptime": 3600,
        "memory_usage": "128MB",
        "cpu_usage": "5%",
        "connections": 10
    },
    "timestamp": 1703001600
}

Événements WebSocket

Connexion

ws.onopen = function() {
    console.log('Connecté à sdk_relay');
    // Envoyer le handshake
    ws.send(JSON.stringify(handshake));
};

Réception de Messages

ws.onmessage = function(event) {
    const message = JSON.parse(event.data);
    
    switch(message.type) {
        case 'handshake_response':
            console.log('Handshake accepté');
            break;
        case 'sync':
            handleSyncMessage(message);
            break;
        case 'notification':
            handleNotification(message);
            break;
        case 'health':
            handleHealthUpdate(message);
            break;
    }
};

Gestion d'Erreurs

ws.onerror = function(error) {
    console.error('Erreur WebSocket:', error);
};

ws.onclose = function(event) {
    console.log('Connexion fermée:', event.code, event.reason);
};

Interface HTTP

Base URL

http://localhost:8091

Endpoints

1. Santé du Service

GET /health

Réponse :

{
    "status": "healthy",
    "uptime": 3600,
    "version": "1.0.0",
    "timestamp": 1703001600
}

2. Métriques

GET /metrics

Réponse :

{
    "sync_metrics": {
        "known_relays": 3,
        "mesh_connections": 6,
        "sync_requests": 150,
        "sync_responses": 150,
        "cache_hits": 120,
        "cache_misses": 30,
        "avg_latency": 45.2,
        "error_count": 0
    },
    "system_metrics": {
        "memory_usage": "128MB",
        "cpu_usage": "5%",
        "active_connections": 10,
        "total_requests": 1000
    }
}

3. Configuration

GET /config

Réponse :

{
    "relay_id": "relay-1",
    "network": "signet",
    "ws_url": "0.0.0.0:8090",
    "http_url": "0.0.0.0:8091",
    "bitcoin_core": {
        "url": "http://bitcoin:18443",
        "wallet": "relay_wallet"
    },
    "blindbit": {
        "url": "http://blindbit:8000"
    },
    "sync": {
        "interval": 30,
        "health_interval": 60
    }
}

4. Relais Connus

GET /relays

Réponse :

{
    "relays": [
        {
            "relay_id": "relay-1",
            "address": "sdk_relay_1:8090",
            "version": "1.0.0",
            "uptime": 3600,
            "health": "healthy",
            "last_seen": 1703001600
        },
        {
            "relay_id": "relay-2",
            "address": "sdk_relay_2:8090",
            "version": "1.0.0",
            "uptime": 3600,
            "health": "healthy",
            "last_seen": 1703001600
        }
    ]
}

5. Statut de Synchronisation

GET /sync/status

Réponse :

{
    "status": "syncing",
    "last_sync": 1703001600,
    "next_sync": 1703001630,
    "sync_types": [
        "StateSync",
        "HealthSync",
        "MetricsSync"
    ],
    "errors": []
}

6. Forcer la Synchronisation

POST /sync/force
Content-Type: application/json

{
    "sync_types": ["StateSync", "HealthSync"]
}

Réponse :

{
    "status": "sync_triggered",
    "sync_types": ["StateSync", "HealthSync"],
    "timestamp": 1703001600
}

7. Logs

GET /logs?level=info&limit=100

Paramètres :

• level : debug, info, warn, error
• limit : nombre de lignes (défaut: 100)

Réponse :

{
    "logs": [
        {
            "timestamp": "2024-12-19T10:00:00Z",
            "level": "info",
            "message": "Relay started successfully"
        },
        {
            "timestamp": "2024-12-19T10:00:30Z",
            "level": "info",
            "message": "Sync completed"
        }
    ]
}

Codes d'Erreur

WebSocket

• 1000 : Fermeture normale
• 1001 : Client part
• 1002 : Erreur de protocole
• 1003 : Type de données non supporté
• 1006 : Connexion fermée anormalement
• 1011 : Erreur serveur

HTTP

• 200 : Succès
• 400 : Requête invalide
• 404 : Endpoint non trouvé
• 500 : Erreur serveur interne
• 503 : Service indisponible

Exemples d'Utilisation

Client JavaScript

class SdkRelayClient {
    constructor(url) {
        this.ws = new WebSocket(url);
        this.setupEventHandlers();
    }

    setupEventHandlers() {
        this.ws.onopen = () => this.onConnect();
        this.ws.onmessage = (event) => this.onMessage(event);
        this.ws.onerror = (error) => this.onError(error);
        this.ws.onclose = (event) => this.onClose(event);
    }

    onConnect() {
        console.log('Connecté à sdk_relay');
        this.sendHandshake();
    }

    sendHandshake() {
        const handshake = {
            type: 'handshake',
            client_id: 'js-client',
            version: '1.0.0',
            capabilities: ['sync', 'notifications']
        };
        this.ws.send(JSON.stringify(handshake));
    }

    onMessage(event) {
        const message = JSON.parse(event.data);
        console.log('Message reçu:', message);
    }

    onError(error) {
        console.error('Erreur WebSocket:', error);
    }

    onClose(event) {
        console.log('Connexion fermée:', event.code, event.reason);
    }
}

// Utilisation
const client = new SdkRelayClient('ws://localhost:8090');

Client Python

import asyncio
import websockets
import json

class SdkRelayClient:
    def __init__(self, url):
        self.url = url
        self.websocket = None

    async def connect(self):
        self.websocket = await websockets.connect(self.url)
        await self.send_handshake()

    async def send_handshake(self):
        handshake = {
            "type": "handshake",
            "client_id": "python-client",
            "version": "1.0.0",
            "capabilities": ["sync", "notifications"]
        }
        await self.websocket.send(json.dumps(handshake))

    async def listen(self):
        async for message in self.websocket:
            data = json.loads(message)
            print(f"Message reçu: {data}")

    async def close(self):
        if self.websocket:
            await self.websocket.close()

# Utilisation
async def main():
    client = SdkRelayClient('ws://localhost:8090')
    await client.connect()
    await client.listen()

asyncio.run(main())

Client cURL

# Vérifier la santé
curl http://localhost:8091/health

# Obtenir les métriques
curl http://localhost:8091/metrics

# Obtenir la configuration
curl http://localhost:8091/config

# Forcer la synchronisation
curl -X POST http://localhost:8091/sync/force \
  -H "Content-Type: application/json" \
  -d '{"sync_types": ["StateSync"]}'

Limites et Quotas

WebSocket

• Connexions simultanées : 1000 par défaut
• Taille des messages : 1MB maximum
• Heartbeat : 30 secondes
• Timeout de connexion : 60 secondes

HTTP

• Taux limite : 1000 requêtes/minute
• Taille des requêtes : 10MB maximum
• Timeout : 30 secondes
• Connexions simultanées : 100

Sécurité

Authentification

• WebSocket : Authentification optionnelle via handshake
• HTTP : Authentification basique (à configurer)

Validation

• Validation JSON des messages
• Rate limiting
• Protection contre les attaques DoS

Chiffrement

• WebSocket : WSS (WebSocket Secure) recommandé
• HTTP : HTTPS recommandé

Monitoring

Métriques Clés

• Latence : Temps de réponse des APIs
• Débit : Messages par seconde
• Erreurs : Taux d'erreur
• Connexions : Nombre de connexions actives

Alertes

• Service indisponible
• Latence élevée (> 1s)
• Taux d'erreur élevé (> 5%)
• Mémoire/CPU élevés

---

Cette API permet une intégration complète avec sdk_relay pour les clients WebSocket et HTTP. 🚀