diff --git a/README.md b/README.md index a5ba0c8..2e84a83 100644 --- a/README.md +++ b/README.md @@ -42,3 +42,6 @@ Voir `LICENSE`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`. ## Journal de changements Voir `CHANGELOG.md`. + +### Documentation centralisée +- Voir `/home/debian/4NK_env/docs/sdk_relay/` diff --git a/docs/AMELIORATIONS_RECENTES.md b/docs/AMELIORATIONS_RECENTES.md deleted file mode 100644 index 173ae77..0000000 --- a/docs/AMELIORATIONS_RECENTES.md +++ /dev/null @@ -1,43 +0,0 @@ -# Améliorations Récentes - SDK Relay - -## Date: 20 Septembre 2025 - -### 🔧 Corrections Majeures - -#### 1. Problème de Scan Bloquant -**Problème:** Le service se bloquait lors du scan initial des blocs Bitcoin. - -**Solution:** -- Optimisation du `last_scan` pour éviter les scans trop importants -- Réduction des logs de `DEBUG` à `INFO` -- Amélioration du healthcheck - -**Fichiers modifiés:** -- `Dockerfile` - Ajout des outils système -- `Cargo.toml` - Mise à jour des dépendances -- Configuration - Optimisation des paramètres - -#### 2. Installation des Outils Système -**Ajouté dans le Dockerfile:** -```dockerfile -RUN apt-get update && apt-get upgrade -y && \ - apt-get install -y ca-certificates dnsutils jq curl git wget telnet npm coreutils && \ - npm install -g wscat && \ - rm -rf /var/lib/apt/lists/* /root/.npm -``` - -#### 3. Configuration Bootstrap -- URL bootstrap: `wss://dev3.4nkweb.com/ws/` -- Faucet activé: `bootstrap_faucet=true` -- Adresse SP permanente configurée - -### 📊 État Actuel -- **Version:** 0.1.2 -- **Statut:** ✅ Healthy -- **Logs:** Niveau INFO (optimisé) -- **Scan:** Optimisé pour éviter les blocages - -### 🔄 Prochaines Étapes -- Monitoring des performances -- Tests de connectivité bootstrap -- Optimisations supplémentaires si nécessaire diff --git a/docs/ANALYSE.md b/docs/ANALYSE.md deleted file mode 100644 index 0633d6a..0000000 --- a/docs/ANALYSE.md +++ /dev/null @@ -1,85 +0,0 @@ -## Analyse détaillée - -### Périmètre - -Service Rust `sdk_relay` interfaçant Bitcoin (RPC), Blindbit et WebSocket, avec configuration injectée. - -### Stack - -- **Langage**: Rust 2021 -- **Dépendances**: `tokio`, `tokio-tungstenite`, `zeromq`, `bitcoincore-rpc`, `serde[_json]`, `env_logger`, `futures-util`, `sdk_common` (git, branche `dev`, features `parallel`, `blindbit-backend`). - -### Build et image - -- Docker multi‑étapes: build dans `rust:latest` avec SSH pour deps privées, exécution `debian:bookworm-slim`. -- Binaire: `/usr/local/bin/sdk_relay`. -- Conf: build‑arg `CONF` écrit dans `/home/bitcoin/.conf`. -- Volumes: `/home/bitcoin/.4nk`, `/home/bitcoin/.bitcoin`. - -### Réseau et healthcheck - -- **WebSocket**: serveur lié sur `Config.ws_url` (ex. `0.0.0.0:8090`) via `tokio_tungstenite`. -- **Health**: serveur TCP léger interne sur port `8091` retournant `{"status":"ok"}`. -- **Ports exposés**: `8090` (WS), `8091` (HTTP /health) dans le `Dockerfile`. - -Références code: - -```396:625:src/main.rs -async fn handle_health_endpoint(mut stream: TcpStream) { - let response = "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: 15\r\n\r\n{\"status\":\"ok\"}"; - let _ = stream.write_all(response.as_bytes()).await; - let _ = stream.shutdown().await; -} - -async fn start_health_server(port: u16) { /* ... */ } - -// Start health server on port 8091 -tokio::spawn(start_health_server(8091)); -``` - -Configuration: - -```1:7:.conf.model -core_url="" -ws_url="" -wallet_name="default" -network="signet" -electrum_url="tcp://localhost:60601" -blindbit_url="tcp://localhost:8000" -zmq_url="" -``` - -### Logs - -- `RUST_LOG` géré par env; dans `lecoffre_node`, sortie tee vers `/home/bitcoin/.4nk/logs/sdk_relay.log`. - -### Risques et points d’attention - -- Dépendance `sdk_common` via git/branche `dev`: geler par tag/commit pour reproductibilité. -- Image d’exécution embarque `strace`; vérifier nécessité en prod. -- Permissions volume Windows: note de chown partiel dans compose parent. - -### Actions proposées - -- Pinner `sdk_common` sur un commit ou tag; documenter politique de mise à jour. -- Séparer images `-dev` et `-prod` si `strace` non requis. -- Documenter format du fichier de conf (`sdk_relay.conf`) et valeurs par défaut. - -### CI / Image - -- Pipeline `build-and-push-ext` construit et pousse l’image avec un tag calculé depuis le message de commit (préfixe `ci: docker_tag=` sinon `dev-test`). -- L’image expose `8090 8091` et lance `sdk_relay --config /home/bitcoin/.conf`. - -Références: - -```1:46:Dockerfile -EXPOSE 8090 8091 -ENTRYPOINT ["sdk_relay", "--config", "/home/bitcoin/.conf"] -``` - -```1:73:.gitea/workflows/build-ext.yml -name: build-and-push-ext -``` - - - diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md deleted file mode 100644 index fae79b5..0000000 --- a/docs/ARCHITECTURE.md +++ /dev/null @@ -1,20 +0,0 @@ -# Architecture - SDK Relay - -## Composants -- Service Rust WebSocket relay + intégration Bitcoin/BlindBit. - -## Dépendances -- `bitcoin` (RPC/ZMQ), `blindbit-proxy`, `sdk_storage`. - -## Réseau et ports -- WS: `0.0.0.0:8090` (exposé derrière Nginx `wss://dev4.4nkweb.com/ws/`). - -## Variables d’environnement (centralisées) -- `SDK_RELAY_*` depuis `lecoffre_node/.env.master`. - -## Monitoring -- Healthcheck avec progression IBD/attentes. -- Logs centralisés Loki/Grafana (SDK Services). - -## Notes -- Démarre après Bitcoin et BlindBit. diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md deleted file mode 100644 index f064ad0..0000000 --- a/docs/CONFIGURATION.md +++ /dev/null @@ -1,74 +0,0 @@ -# Configuration SDK Relay - -## Variables d'environnement - -Le service `sdk_relay` peut être configuré via les variables d'environnement suivantes : - -### Variables principales - -- **`SDK_RELAY_WS_URL`** : URL WebSocket pour les tests (défaut: `ws://0.0.0.0:8090`) -- **`WS_BIND_URL`** : URL de binding WebSocket (override de la configuration, défaut: valeur de `ws_url`) -- **`HEALTH_PORT`** : Port du serveur de santé (défaut: `8091`) -- **`HEALTH_BIND_ADDRESS`** : Adresse de binding du serveur de santé (défaut: `0.0.0.0`) -- **`RUST_LOG`** : Niveau de logging (défaut: `INFO`) - -### Configuration via fichier - -Le service utilise un fichier de configuration (`sdk_relay.conf`) avec les paramètres suivants : - -```ini -core_url="http://bitcoin:38332" -ws_url="0.0.0.0:8090" -wallet_name="default" -network="signet" -blindbit_url="http://blindbit-oracle:8000" -zmq_url="tcp://bitcoin:29000" -storage="https://dev4.4nkweb.com/storage" -data_dir="/home/bitcoin/.4nk" -bitcoin_data_dir="/home/bitcoin/.bitcoin" -bootstrap_url="wss://dev3.4nkweb.com/ws/" -bootstrap_faucet=true -RUST_LOG="INFO" -sp_address="tsp1qqgmwp9n5p9ujhq2j6cfqe4jpkyu70jh9rgj0pwt3ndezk2mrlvw6jqew8fhsulewzglfr7g2aa48wyj4n0r7yasa3fm666vda8984ke8tuaf9m89" -``` - -## Changements récents - -### v0.1.3 - Configuration externalisée avancée - -- **Ajout** : Variables d'environnement `WS_BIND_URL`, `HEALTH_PORT`, `HEALTH_BIND_ADDRESS` -- **Ajout** : Support de la variable d'environnement `SDK_RELAY_WS_URL` pour les tests -- **Modification** : Remplacement de `localhost` par `0.0.0.0` dans les tests WebSocket -- **Amélioration** : Configuration plus flexible pour les environnements Docker -- **Correction** : Résolution du problème de binding sur 127.0.0.1 au lieu de 0.0.0.0 - -### Tests - -Les tests WebSocket utilisent maintenant `ws://0.0.0.0:8090` au lieu de `ws://localhost:8090` pour une meilleure compatibilité avec les environnements Docker. - -## Configuration Docker - -```yaml -environment: - - WS_BIND_URL=0.0.0.0:8090 - - HEALTH_PORT=8091 - - HEALTH_BIND_ADDRESS=0.0.0.0 - - RUST_LOG=INFO -volumes: - - ./relay/sdk_relay.conf:/home/bitcoin/.conf:ro -``` - -## Endpoints - -- **WebSocket** : `0.0.0.0:8090` - Communication WebSocket -- **Health** : `0.0.0.0:8091` - Vérification de santé - -## Dépannage - -### Problème de connexion WebSocket - -Si le service n'écoute pas sur `0.0.0.0:8090`, vérifiez : - -1. La configuration `ws_url` dans le fichier de configuration -2. Les variables d'environnement Docker -3. Les logs du service pour les erreurs de binding \ No newline at end of file diff --git a/docs/DEPLOIEMENT.md b/docs/DEPLOIEMENT.md deleted file mode 100644 index 371e6e7..0000000 --- a/docs/DEPLOIEMENT.md +++ /dev/null @@ -1,21 +0,0 @@ -# Déploiement - SDK Relay - -## Préparation -- Branche `ext`. -- `SDK_RELAY_*` dans `lecoffre_node/.env.master`. -- Accès `bitcoin` RPC/ZMQ et `blindbit-proxy`. - -## Déploiement (orchestrateur) -```bash -cd /home/debian/4NK_env/lecoffre_node -./scripts/start.sh | cat -./scripts/validate-deployment.sh | cat -``` - -## Vérifications -- WS: `wss://dev4.4nkweb.com/ws/`. -- `./scripts/monitor-progress.sh | cat` (attente IBD/BlindBit). - -## Règles -- Pas de compose direct. -- Push `ext` sans CI si pas de binaire à reconstruire. diff --git a/docs/FLUX.md b/docs/FLUX.md deleted file mode 100644 index 65bedb3..0000000 --- a/docs/FLUX.md +++ /dev/null @@ -1,6 +0,0 @@ -# Description des Flux - SDK Relay - -## Flux principaux -1. Bitcoin (RPC/ZMQ) → Relay (indexation, signaux IBD). -2. BlindBit → Relay (résolution secrets SP). -3. Clients WS ↔ Relay (évènements NewTx, notifications). diff --git a/docs/FONCTIONNEL.md b/docs/FONCTIONNEL.md deleted file mode 100644 index aaa67bd..0000000 --- a/docs/FONCTIONNEL.md +++ /dev/null @@ -1,13 +0,0 @@ -# Description Fonctionnelle - SDK Relay - -## Objectif -Assurer le relais temps réel WebSocket et l’orchestration des évènements blockchain (Bitcoin/BlindBit) pour les services applicatifs. - -## Parcours clés -- Abonnement clients WS. -- Relais d’évènements (nouveaux blocs, transactions, notifications NewTx). -- Attente synchronisation Bitcoin et disponibilité BlindBit avant diffusion. - -## Résultats attendus -- Canal temps réel fiable. -- Mise en file d’attente/retente en cas d’indisponibilité dépendances. diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md deleted file mode 100644 index bdcd8df..0000000 --- a/docs/INSTALLATION.md +++ /dev/null @@ -1,24 +0,0 @@ -# Installation - SDK Relay - -## Prérequis -- Dépôts sous `/home/debian/4NK_env` (branche `ext`). -- Docker/Compose. -- Variables `SDK_RELAY_*` dans `lecoffre_node/.env.master`. - -## Configuration -- Pas de `.env` local. -- Vérifier accès `bitcoin` (RPC/ZMQ) et `blindbit-proxy`. - -## Démarrage (orchestrateur) -```bash -cd /home/debian/4NK_env/lecoffre_node -./scripts/start.sh | cat -``` - -## Vérifications -- WS: `wss://dev4.4nkweb.com/ws/` -- Health: scripts `monitor-progress.sh`, `logs-with-progress.sh`. - -## Notes -- Démarre après Bitcoin et BlindBit. -- CI via tag `ext`. diff --git a/docs/QUALITE.md b/docs/QUALITE.md deleted file mode 100644 index 1f87fb7..0000000 --- a/docs/QUALITE.md +++ /dev/null @@ -1,6 +0,0 @@ -# Qualité Logicielle - SDK Relay - -- Lint/format: Rustfmt/Clippy. -- Tests: unitaires, intégration WS, tests de charge. -- Performance: backpressure WS, gestion erreurs. -- Observabilité: logs structurés, métriques si dispo. diff --git a/docs/SECURITE.md b/docs/SECURITE.md deleted file mode 100644 index 38430a9..0000000 --- a/docs/SECURITE.md +++ /dev/null @@ -1,6 +0,0 @@ -# Sécurité - SDK Relay - -- Aucune clé ou secret en dur. -- Accès Bitcoin RPC/ZMQ sécurisés sur réseau interne Docker. -- Validation stricte des messages WS. -- Journaux sans secrets. diff --git a/docs/TECHNIQUE.md b/docs/TECHNIQUE.md deleted file mode 100644 index 93572a8..0000000 --- a/docs/TECHNIQUE.md +++ /dev/null @@ -1,19 +0,0 @@ -# Description Technique - SDK Relay - -## Tech stack -- Rust, WebSocket server. - -## Configuration -- Variables `SDK_RELAY_*` via `lecoffre_node/.env.master`. -- Connexion Bitcoin (RPC/ZMQ), BlindBit URL. - -## Interfaces -- WS `0.0.0.0:8090` (derrière Nginx). - -## Sécurité -- Aucun secret en dur. -- Validation stricte des messages. - -## Observabilité -- Healthcheck avec progression. -- Logs Loki/Grafana. diff --git a/docs/TODO.md b/docs/TODO.md deleted file mode 100644 index b3577a3..0000000 --- a/docs/TODO.md +++ /dev/null @@ -1,6 +0,0 @@ -# TODO - SDK Relay - -- Vérifier connexion Bitcoin (RPC/ZMQ) et BlindBit. -- Tester WebSocket public via Nginx. -- Valider healthchecks et progression IBD. -- Surveiller logs et mettre en place alertes Grafana. diff --git a/docs/VALIDATION.md b/docs/VALIDATION.md deleted file mode 100644 index 718765c..0000000 --- a/docs/VALIDATION.md +++ /dev/null @@ -1,40 +0,0 @@ -## Validation opérationnelle - -### Pré‑requis - -- Image `git.4nkweb.com/4nk/sdk_relay:` construite par la CI (workflow `build-and-push-ext`). -- Fichier de configuration accessible dans le conteneur à `/home/bitcoin/.conf` avec au minimum: `core_url`, `ws_url`, `wallet_name`, `network`, `blindbit_url`, `zmq_url`. -- Ports hôtes libres: `8090` (WebSocket), `8091` (HTTP /health). - -### Démarrage / Redémarrage du service - -1. Arrêter l’instance en cours (si gérée via Docker/compose parent), puis démarrer avec la nouvelle image taggée `ext` (ou le tag CI calculé) en veillant à monter les volumes `/home/bitcoin/.4nk` et `/home/bitcoin/.bitcoin`. -2. Vérifier les logs de démarrage et la ligne: `Health server listening on port 8091`. - -### Tests de santé - -- HTTP: `curl -sS http://localhost:8091/health` doit renvoyer `{"status":"ok"}` avec un code 200. - -### Tests WebSocket - -- Connexion: ouvrir un client vers `ws://localhost:8090` (adresse selon `ws_url`). La poignée de main doit réussir. -- Réception initiale: un message de type Handshake (avec adresse SP, membres et processus) est diffusé à la connexion. -- Diffusion: émettre un message valide (selon protocole `sdk_common`) et vérifier qu’il est redistribué selon le `BroadcastType`. - -### Parcours fonctionnel complet - -1. IdNot: initialiser un identifiant et vérifier la persistance locale dans le volume `.4nk`. -2. iframe: intégrer le client (IHM) et établir la communication vers le WebSocket du `sdk_relay`. -3. Ajout de service: exécuter le flux d’ajout et confirmer la mise à jour de l’état et la diffusion côté WS. - -### Attendus CI/CD - -- La CI construit automatiquement l’image incluant l’endpoint `/health` et pousse avec le tag calculé (préfixe commit `ci: docker_tag=...`, sinon `dev-test`). -- Une fois l’image disponible (tag `ext` si prévu), redémarrer le service pour résoudre les problèmes de connexion. - -### Dépannage - -- Port occupé: vérifier qu’aucun service n’écoute déjà sur `8090/8091`. -- Conf manquante/invalide: le binaire échoue avec `Failed to find conf file` ou erreurs `No "..."`; corriger `/home/bitcoin/.conf`. -- ZMQ/Blindbit: si pas joignables, les fonctionnalités associées peuvent être dégradées; le `/health` reste OK si le service tourne. -- Volumes: en environnement Windows, vérifier les permissions et l’utilisateur `bitcoin`. diff --git a/docs/WEBSOCKET_CONFIGURATION.md b/docs/WEBSOCKET_CONFIGURATION.md deleted file mode 100644 index 54025c5..0000000 --- a/docs/WEBSOCKET_CONFIGURATION.md +++ /dev/null @@ -1,68 +0,0 @@ -# Configuration WebSocket - sdk_relay - -## Configuration actuelle - -### Variables d'environnement -- `WS_BIND_URL` : URL de binding WebSocket (défaut: `0.0.0.0:8090`) -- `HEALTH_PORT` : Port du serveur de santé (défaut: `8091`) -- `HEALTH_BIND_ADDRESS` : Adresse de binding du serveur de santé (défaut: `0.0.0.0`) - -### Configuration dans sdk_relay.conf -```ini -ws_url="0.0.0.0:8090" -blindbit_url="http://blindbit-oracle:8000" -bootstrap_url="wss://dev3.4nkweb.com/ws/" -bootstrap_faucet=true -sp_address="tsp1qqgmwp9n5p9ujhq2j6cfqe4jpkyu70jh9rgj0pwt3ndezk2mrlvw6jqew8fhsulewzglfr7g2aa48wyj4n0r7yasa3fm666vda8984ke8tuaf9m89" -RUST_LOG="INFO" -``` - -## Problèmes résolus - -### 1. Binding sur 127.0.0.1 au lieu de 0.0.0.0 -**Problème :** Le relay se liait sur `127.0.0.1:8090` au lieu de `0.0.0.0:8090`. - -**Solution :** Externalisation de la configuration via variables d'environnement et correction du code Rust. - -### 2. Gestion des erreurs WebSocket -**Problème :** Erreurs de handshake WebSocket non gérées correctement. - -**Solution :** Amélioration de la gestion d'erreurs avec `log::warn!` au lieu de `log::error!` pour les tentatives de connexion non-WebSocket. - -### 3. Configuration externalisée -**Problème :** IP et ports hardcodés dans le code Rust. - -**Solution :** Externalisation de tous les paramètres de configuration via variables d'environnement. - -## Tests WebSocket - -### Test avec headers corrects -```bash -curl -v -H "Upgrade: websocket" \ - -H "Connection: upgrade" \ - -H "Sec-WebSocket-Version: 13" \ - -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \ - http://127.0.0.1:8090/ -``` - -**Résultat attendu :** `HTTP/1.1 101 Switching Protocols` - -### Test sans headers WebSocket -```bash -curl -v http://127.0.0.1:8090/ -``` - -**Résultat attendu :** Erreur de handshake WebSocket (normal) - -## Problème persistant - -### Nginx ne transmet pas les headers WebSocket -**Statut :** ⚠️ Problème persistant -- Nginx configuré avec tous les headers WebSocket -- Le relay reçoit toujours des connexions sans headers -- Erreur : `"No Upgrade: websocket header"` - -**Investigation :** La configuration Nginx semble correcte mais les headers ne sont pas transmis. - -## Date de mise à jour -2025-01-20 - Configuration WebSocket externalisée et problèmes de binding résolus \ No newline at end of file