From ccdb2d69fb80bdb3fe4353a12530a8e63ae13547 Mon Sep 17 00:00:00 2001 From: Nicolas Cantu Date: Mon, 25 Aug 2025 15:31:34 +0200 Subject: [PATCH] docs(sdk_relay): alignement avec 4NK_node (installation, usage, configuration, testing, quick ref, dev, performance, troubleshooting, open source, gitea, release, roadmap, security audit) --- docs/API.md | 42 +++++++++++++++++------------------ docs/CONFIGURATION.md | 27 ++++++++++++++++++++++ docs/DEVELOPMENT.md | 32 ++++++++++++++++++++++++++ docs/GITEA_SETUP.md | 21 ++++++++++++++++++ docs/INDEX.md | 12 ++++++++++ docs/INSTALLATION.md | 25 +++++++++++++++++++++ docs/OPEN_SOURCE_CHECKLIST.md | 28 +++++++++++++++++++++++ docs/PERFORMANCE.md | 26 ++++++++++++++++++++++ docs/QUICK_REFERENCE.md | 31 ++++++++++++++++++++++++++ docs/RELEASE_PLAN.md | 19 ++++++++++++++++ docs/ROADMAP.md | 25 +++++++++++++++++++++ docs/SECURITY_AUDIT.md | 28 +++++++++++++++++++++++ docs/TESTING.md | 34 ++++++++++++++++++++++++++++ docs/TROUBLESHOOTING.md | 28 +++++++++++++++++++++++ docs/USAGE.md | 26 ++++++++++++++++++++++ 15 files changed, 383 insertions(+), 21 deletions(-) create mode 100644 docs/CONFIGURATION.md create mode 100644 docs/DEVELOPMENT.md create mode 100644 docs/GITEA_SETUP.md create mode 100644 docs/INSTALLATION.md create mode 100644 docs/OPEN_SOURCE_CHECKLIST.md create mode 100644 docs/PERFORMANCE.md create mode 100644 docs/QUICK_REFERENCE.md create mode 100644 docs/RELEASE_PLAN.md create mode 100644 docs/ROADMAP.md create mode 100644 docs/SECURITY_AUDIT.md create mode 100644 docs/TESTING.md create mode 100644 docs/TROUBLESHOOTING.md create mode 100644 docs/USAGE.md diff --git a/docs/API.md b/docs/API.md index d420692..c4016eb 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1006,18 +1006,18 @@ class SdkRelayClient { async connect() { return new Promise((resolve, reject) => { this.ws = new WebSocket(this.wsUrl); - + this.ws.onopen = () => { console.log('Connecté à sdk_relay'); this.sendHandshake(); resolve(); }; - + this.ws.onmessage = (event) => { const message = JSON.parse(event.data); this.handleMessage(message); }; - + this.ws.onerror = (error) => { console.error('Erreur WebSocket:', error); reject(error); @@ -1097,11 +1097,11 @@ const client = new SdkRelayClient('ws://localhost:8090', 'http://localhost:8091' async function main() { await client.connect(); - + // Obtenir les métriques const metrics = await client.getMetrics(); console.log('Métriques:', metrics); - + // Forcer une synchronisation await client.forceSync(['HealthSync']); } @@ -1124,11 +1124,11 @@ class SdkRelayClient: self.http_url = http_url self.websocket = None self.client_id = f"python-client-{int(datetime.now().timestamp())}" - + async def connect(self): self.websocket = await websockets.connect(self.ws_url) await self.send_handshake() - + async def send_handshake(self): handshake = { "type": "handshake", @@ -1137,12 +1137,12 @@ class SdkRelayClient: "capabilities": ["sync", "notifications", "health"] } await self.websocket.send(json.dumps(handshake)) - + async def listen(self): async for message in self.websocket: data = json.loads(message) await self.handle_message(data) - + async def handle_message(self, message): if message['type'] == 'handshake_response': print(f"Handshake accepté par {message['relay_id']}") @@ -1150,57 +1150,57 @@ class SdkRelayClient: await self.handle_notification(message) elif message['type'] == 'sync': await self.handle_sync(message) - + async def handle_notification(self, message): print(f"Notification {message['notification_type']}: {message['data']}") - + async def handle_sync(self, message): print(f"Sync {message['sync_type']}: {message['payload']}") - + # Méthodes HTTP async def get_health(self): async with aiohttp.ClientSession() as session: async with session.get(f"{self.http_url}/health") as response: return await response.json() - + async def get_metrics(self): async with aiohttp.ClientSession() as session: async with session.get(f"{self.http_url}/metrics") as response: return await response.json() - + async def get_relays(self): async with aiohttp.ClientSession() as session: async with session.get(f"{self.http_url}/relays") as response: return await response.json() - + async def force_sync(self, sync_types=None): if sync_types is None: sync_types = ['StateSync'] - + async with aiohttp.ClientSession() as session: async with session.post( f"{self.http_url}/sync/force", json={"sync_types": sync_types} ) as response: return await response.json() - + async def close(self): if self.websocket: await self.websocket.close() async def main(): client = SdkRelayClient('ws://localhost:8090', 'http://localhost:8091') - + try: await client.connect() - + # Obtenir les métriques metrics = await client.get_metrics() print("Métriques:", metrics) - + # Écouter les messages await client.listen() - + except Exception as e: print(f"Erreur: {e}") finally: diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md new file mode 100644 index 0000000..887a172 --- /dev/null +++ b/docs/CONFIGURATION.md @@ -0,0 +1,27 @@ +# Configuration - sdk_relay + +## Fichier `.conf` + +Champs principaux: + +- core_url=http://bitcoin:18443 +- core_wallet=relay_wallet +- ws_url=0.0.0.0:8090 +- blindbit_url=http://blindbit:8000 +- zmq_url=tcp://bitcoin:29000 +- network=signet +- relay_id=relay-1 +- sync_interval=30 +- health_interval=60 + +## Variables d'environnement + +- RUST_LOG=debug,bitcoincore_rpc=trace +- BITCOIN_COOKIE_PATH=/home/bitcoin/.4nk/bitcoin.cookie +- ENABLE_SYNC_TEST=1 + +## Hiérarchie de configuration + +1. Variables d'environnement +2. Fichier `.conf` +3. Valeurs par défaut diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md new file mode 100644 index 0000000..33612cf --- /dev/null +++ b/docs/DEVELOPMENT.md @@ -0,0 +1,32 @@ +# Développement - sdk_relay + +## Environnement + +- Rust 1.70+ +- cargo, rustfmt, clippy + +## Commandes + +```bash +# Lancer en dev +RUST_LOG=debug cargo run -- --config .conf + +# Lint et format +cargo clippy -- -D warnings +cargo fmt + +# Tests +cargo test --all +``` + +## Conventions + +- Messages de commit conventionnels (feat/fix/docs/test/chore) +- Code lisible, erreurs gérées, early returns +- Pas de secrets en dur + +## Structure + +- `src/` modules (websocket, http, sync, daemon) +- `docs/` documentation utilisateur/technique +- `tests/` scripts et artefacts diff --git a/docs/GITEA_SETUP.md b/docs/GITEA_SETUP.md new file mode 100644 index 0000000..a5df5f0 --- /dev/null +++ b/docs/GITEA_SETUP.md @@ -0,0 +1,21 @@ +# Gitea Setup - sdk_relay + +## Dépôt +- Hébergeur: `git.4nkweb.com` +- Protocole: SSH recommandé +- Protection des branches (main) + +## Templates +- `.gitea/ISSUE_TEMPLATE/*` +- `.gitea/PULL_REQUEST_TEMPLATE.md` +- `.gitea/workflows/ci.yml` + +## Droits et revues +- Reviews requises pour PR → main +- Checks CI obligatoires +- Stratégie de merge: squash + rebase + +## Releases +- Tags SemVer +- CHANGELOG mis à jour +- Artefacts (binaires/images) optionnels diff --git a/docs/INDEX.md b/docs/INDEX.md index f526c91..da9d060 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -3,6 +3,18 @@ ## Guides - [Architecture](ARCHITECTURE.md) - Architecture technique détaillée - [API](API.md) - Référence complète des APIs WebSocket et HTTP +- [Installation](INSTALLATION.md) - Installation et vérifications +- [Utilisation](USAGE.md) - Guide d'utilisation +- [Configuration](CONFIGURATION.md) - Paramètres et env vars +- [Développement](DEVELOPMENT.md) - Environnement développeur +- [Tests](TESTING.md) - Stratégie et commandes +- [Performance](PERFORMANCE.md) - Objectifs et mesures +- [Dépannage](TROUBLESHOOTING.md) - Problèmes courants +- [Open Source Checklist](OPEN_SOURCE_CHECKLIST.md) - Préparation open source +- [Gitea Setup](GITEA_SETUP.md) - CI/TEMPLATES Gitea +- [Plan de Release](RELEASE_PLAN.md) - Processus de release +- [Roadmap](ROADMAP.md) - Évolution +- [Audit de Sécurité](SECURITY_AUDIT.md) - Contrôles et recommandations - [Contribution](../CONTRIBUTING.md) - Guide de contribution - [Sécurité](../SECURITY.md) - Politique de sécurité - [Changelog](../CHANGELOG.md) - Historique des versions diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md new file mode 100644 index 0000000..79a6635 --- /dev/null +++ b/docs/INSTALLATION.md @@ -0,0 +1,25 @@ +# Installation - sdk_relay + +## Prérequis + +- Docker 24+ ou Rust 1.70+ +- Bitcoin Core (signet) accessible via RPC +- Blindbit (oracle) accessible via HTTP + +## Méthodes d'installation + +### Docker (recommandé) +- Construire l'image locale puis exécuter le conteneur +- Exposer les ports 8090 (WebSocket) et 8091 (HTTP) +- Fournir la configuration via fichier `.conf` ou variables d'environnement + +### Binaire Rust +- Compiler en profil release +- Lancer avec un fichier `.conf` + +## Vérifications post-installation + +- Endpoint `HTTP /health` répond avec `status=healthy` +- Port WebSocket en écoute sur 8090 +- Connexion RPC à Bitcoin Core opérationnelle +- Accès au service Blindbit opérationnel diff --git a/docs/OPEN_SOURCE_CHECKLIST.md b/docs/OPEN_SOURCE_CHECKLIST.md new file mode 100644 index 0000000..2afe548 --- /dev/null +++ b/docs/OPEN_SOURCE_CHECKLIST.md @@ -0,0 +1,28 @@ +# Open Source Checklist - sdk_relay + +## Fichiers requis +- LICENSE (MIT) +- CONTRIBUTING.md +- CODE_OF_CONDUCT.md +- SECURITY.md +- CHANGELOG.md +- docs/ (complet) +- .gitea/ (templates + workflows) + +## CI/CD (Gitea Actions) +- Lint (clippy, fmt) +- Tests unitaires/integration +- Audit de sécurité (cargo audit) +- Build Docker +- Vérif docs + +## Qualité et sécurité +- Pas de secrets en dur +- Dépendances à jour +- Politique de versions (SemVer) +- Changelog maintenu + +## Communication +- Templates Issues/PR +- Guide Communauté +- Plan de release diff --git a/docs/PERFORMANCE.md b/docs/PERFORMANCE.md new file mode 100644 index 0000000..dbf849d --- /dev/null +++ b/docs/PERFORMANCE.md @@ -0,0 +1,26 @@ +# Performance - sdk_relay + +## Objectifs + +- Latence sync < 100 ms (local) +- Messages/s > 1000 (agrégé) +- CPU < 70% en nominal +- Mémoire < 512MB/relais + +## Tests de performance + +- Tests WebSocket de charge +- Mesure latence/percentiles +- Monitoring CPU/Mem/FDs + +## Optimisations + +- Async `tokio` +- Cache de déduplication +- Batching raisonnable +- Backpressure côté clients + +## Monitoring + +- Scripts d’observation (stats système) +- Export métriques endpoints `/metrics` diff --git a/docs/QUICK_REFERENCE.md b/docs/QUICK_REFERENCE.md new file mode 100644 index 0000000..b804122 --- /dev/null +++ b/docs/QUICK_REFERENCE.md @@ -0,0 +1,31 @@ +# Référence Rapide - sdk_relay + +## Endpoints clés + +- WS: `ws://host:8090` +- HTTP: `http://host:8091` +- Health: `GET /health` +- Métriques: `GET /metrics` + +## Messages WS + +- handshake → handshake_response +- ping → pong +- subscribe/unsubscribe +- notifications: payment_detected, block_mined + +## Sync + +- Types: StateSync, HealthSync, MetricsSync +- Forcer: `POST /sync/force` + +## Logs + +- Niveau: `RUST_LOG=debug` +- Fichiers: selon l’outil de lancement + +## Dépannage rapide + +- Ports 8090/8091 ouverts +- Bitcoin Core RPC OK +- Blindbit HTTP OK diff --git a/docs/RELEASE_PLAN.md b/docs/RELEASE_PLAN.md new file mode 100644 index 0000000..f7486fc --- /dev/null +++ b/docs/RELEASE_PLAN.md @@ -0,0 +1,19 @@ +# Plan de Release - sdk_relay + +## Versioning +- SemVer: MAJOR.MINOR.PATCH +- Branches: `main`, `develop`, `feature/*` + +## Phases +1. Gel des fonctionnalités +2. Stabilisation et correctifs +3. Mise à jour CHANGELOG +4. Tag et build +5. Publication et communication + +## Checklist release +- CI verte (lint, tests, audit) +- Docs à jour (API, INSTALLATION, USAGE) +- CHANGELOG complété +- Tag créé (`vX.Y.Z`) +- Annonce préparée (Gitea release notes) diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..1ab591e --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,25 @@ +# Roadmap - sdk_relay + +## Court terme (1-2 mois) +- Finaliser API HTTP (statut détaillé, relays) +- Stabiliser sync (State/Health/Metrics) +- Tests de performance et robustesse +- Documentation complète + +## Moyen terme (3-6 mois) +- Signatures des messages de sync +- Compression et fragmentation des messages +- Persistences des états (CRDT/Log) +- Export Prometheus + +## Long terme (6-12 mois) +- Mode cluster (HA) +- Découverte via DNS/bootstrap +- Webhooks/REST complets +- Intégrations wallets externes + +## Indicateurs +- Latence moyenne sync +- Taux d’erreurs +- Couverture de tests +- SLO disponibilité diff --git a/docs/SECURITY_AUDIT.md b/docs/SECURITY_AUDIT.md new file mode 100644 index 0000000..c0e677d --- /dev/null +++ b/docs/SECURITY_AUDIT.md @@ -0,0 +1,28 @@ +# Audit de Sécurité - sdk_relay + +## Portée +- Serveur WebSocket (8090) +- Serveur HTTP (8091) +- Sync Manager +- Intégration Bitcoin Core/Blindbit + +## Contrôles +- Dépendances (`cargo audit`) +- Secrets en dur (grep tokens/password/key) +- Permissions de fichiers (cookies, clés) +- Validation des entrées (WS/HTTP) + +## Tests +- Tests automatiques (scripts + cargo) +- Fuzzing (cibles parsing JSON) +- Charge et DoS (rate limiting) + +## Recommandations +- Activer WSS/HTTPS en prod +- Signer/valider les messages de sync +- Journalisation sécurisée (sans secrets) +- Mise à jour régulière des deps + +## Résultats et suivi +- Issues Gitea créées pour findings +- Plan de remédiation par priorité diff --git a/docs/TESTING.md b/docs/TESTING.md new file mode 100644 index 0000000..9931a9b --- /dev/null +++ b/docs/TESTING.md @@ -0,0 +1,34 @@ +# Tests - sdk_relay + +## Catégories + +- Unitaires: tests de fonctions/méthodes +- Intégration: interaction HTTP/WS +- Connectivité: accès réseau et ports +- Externes: tests contre nœuds externes (ex: dev3) +- Performance: charge et latence + +## Commandes + +```bash +# Tous les tests Rust +cargo test --all + +# Lint et format +cargo clippy -- -D warnings +cargo fmt -- --check + +# Scripts (si présents) +./tests/run_all_tests.sh +``` + +## Rapports + +- logs: `tests/logs/` +- reports: `tests/reports/` + +## Bonnes pratiques + +- Tests déterministes +- Données de test isolées +- Nettoyage après exécution diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000..8996b81 --- /dev/null +++ b/docs/TROUBLESHOOTING.md @@ -0,0 +1,28 @@ +# Dépannage - sdk_relay + +## Problèmes courants + +### 1) `/health` renvoie erreur +- Vérifier Bitcoin Core RPC (`bitcoin-cli -signet getblockchaininfo`) +- Vérifier Blindbit (`curl http://blindbit:8000/health`) +- Vérifier variables `BITCOIN_COOKIE_PATH` + +### 2) Port 8090 non accessible +- Vérifier pare-feu +- Vérifier que le processus écoute (netstat/ss) +- Conflit de ports ? + +### 3) Messages WS non reçus +- Handshake bien envoyé ? +- Capabilities compatibles ? +- Heartbeat actif (ping/pong) ? + +### 4) Sync inopérante +- Relais voisins connus ? (`GET /relays`) +- `StateSync` visible dans logs ? +- Latence réseau élevée ? + +## Outils utiles +- `docker logs`, `journalctl` (si service) +- `RUST_LOG=debug` +- Scripts de tests/monitoring diff --git a/docs/USAGE.md b/docs/USAGE.md new file mode 100644 index 0000000..fb99512 --- /dev/null +++ b/docs/USAGE.md @@ -0,0 +1,26 @@ +# Utilisation - sdk_relay + +## Démarrage rapide + +- Démarrer le service (Docker ou binaire) +- Vérifier `GET /health` +- Connecter un client WebSocket à `ws://host:8090` + +## WebSocket + +- Envoyer un handshake JSON avec `type=handshake` +- Recevoir `handshake_response` +- S'abonner aux notifications si nécessaire (`subscribe`) + +## HTTP + +- `GET /health` : santé +- `GET /metrics` : métriques +- `GET /relays` : relais connus +- `POST /sync/force` : forcer une synchronisation + +## Bonnes pratiques + +- Reconnexion automatique côté client +- Heartbeat régulier (ping/pong) +- Limiter la taille des messages (< 1MB)