bal-electrum-plugin/REPORT_NETWORKING_PARALLELO.md

Report tecnico — Networking parallelo (anti-freeze Will-Executor)

Destinatario: programmatore esterno / manutentore del plugin Autore: refactoring AI (lavoro su GitHub Bitcoin-after-life/test) Data: 2026-06-15 Branch: feature/networking-parallelo Repository Gitea privato kaibot/bal-plugin-ai: NON modificato (per richiesta esplicita).

---

1. Problema

Quando il plugin contatta i server Will-Executor (invio transazioni, ping/aggiornamento eredità, download lista), lo fa in sequenza. Se un server non risponde, il thread resta bloccato sui timeout di connessione e, peggio, sui retry:

• send_request riprovava fino a 10 volte con time.sleep(3) ad ogni timeout → circa 130 secondi per ogni server irraggiungibile, sommati uno dopo l'altro.

Conseguenze:

• Con pochi server già si avverte; con 20 server diventa ingestibile.
• L'utente vede "Rimani in attesa — Non risponde" senza capire cosa succede.
• Un singolo server morto blocca l'intera operazione.

---

2. Soluzione (in sintesi)

1. Parallelismo con ThreadPoolExecutor: i server vengono contattati contemporaneamente. Il tempo totale ≈ server più lento, non la somma.
2. Fast-fail per le operazioni interattive (ping/info/download): niente retry-storm, un solo timeout breve e il server viene marcato "KO".
3. Feedback live: callback on_each(...) che aggiorna la finestra di attesa server-per-server, in modo thread-safe.
4. Push transazioni: parallelo, ma mantiene i retry per ogni singolo server (una transazione reale non deve andare persa per un hiccup transitorio).

Perché è thread-safe

Network.send_http_on_proxy() usa asyncio.run_coroutine_threadsafe(coro, loop) e poi coro.result(): ogni chiamata schedula la propria coroutine sullo stesso loop asyncio condiviso di Electrum e blocca solo il proprio worker thread. Più chiamate concorrenti sono quindi sicure → ThreadPoolExecutor dà vero parallelismo.

Gli aggiornamenti UI passano per BalWaitingDialog.update() che emette un pyqtSignal → marshalling automatico sul thread GUI. I callback dai worker thread possono quindi aggiornare il dialog in sicurezza.

---

3. File modificati (tutto su GitHub Bitcoin-after-life/test, branch feature/networking-parallelo)

3.1 bal/core/willexecutors.py

send_request(...) — aggiunti due parametri keyword-only:

def send_request(method, url, data=None, *, timeout=10, handle_response=None,
                 count_reply=0, max_retries=10, retry_sleep=3):

• max_retries / retry_sleep controllano i retry sui timeout.
• Default invariato (10 / 3s) → il push critico mantiene il comportamento storico.
• Le operazioni interattive passano max_retries=0 → fast-fail.

get_info_task(...) — fast-fail di default:

def get_info_task(url, willexecutor, *, timeout=DEFAULT_TIMEOUT,
                  max_retries=0, retry_sleep=0):

• Se la risposta non è un dict (timeout/vuoto) → status="KO".

NUOVO ping_servers_parallel(willexecutors, *, on_each=None, max_workers=8, timeout=DEFAULT_TIMEOUT)

• ThreadPoolExecutor + as_completed; un worker per server (_ping_one).
• Muta willexecutors in place (come il vecchio ping_servers).
• Invoca on_each(url, we, ok) man mano che arrivano i risultati.
• Un worker che esplode non blocca gli altri (try/except difensivo).

NUOVO push_transactions_parallel(willexecutors, *, on_each=None, max_workers=8)

• Push in parallelo solo verso le voci con chiave "txs".
• Ogni server mantiene i propri retry (push_transactions_to_willexecutor).
• on_each(url, we, ok, exc); raccoglie AlreadyPresentException separatamente.
• Ritorna {url: (ok, exc)}.

DEFAULT_TIMEOUT = 5 (costante a livello di modulo).

3.2 bal/gui/qt/window.py

• ping_willexecutors_task(self, wes) riscritto su ping_servers_parallel(...) con feedback live (set pinged/failed, get_title() mostra "Ok"/"Ko"/"waiting...").
• push_transactions_to_willexecutors(self, force=False) riscritto su push_transactions_parallel(...). on_each fa book-keeping + update UI thread-safe; i server "already present" sono raccolti in already_present[] e il loro check_transaction viene eseguito dopo, nel task thread (logica di check originale intatta).
• fetch_will_executors_list(...) download fast-fail: send_request("get", url, timeout=10, max_retries=1, retry_sleep=1).

3.3 bal/core/util.py — BUGFIX (regressione pre-esistente)

In get_value_amount (riga 324) era stato erroneamente usato Util.in_output(...) (ritorna bool) al posto di Util.din_output(...) (ritorna la tupla (same_amount, same_address)), causando:

TypeError: cannot unpack non-iterable bool object

Corretto ripristinando din_output. Bug scoperto eseguendo i test ufficiali del repo Gitea (tests/test_core_util.py::test_get_value_amount).

---

4. Verifica (ruff + test ufficiali)

4.1 ruff (lint / PEP8)

• ruff check sul codice nuovo: nessun nuovo problema introdotto (i F403/F405/F401 presenti derivano dal pattern from .common import * dell'originale; conteggio identico HEAD vs working tree: 121 = 121).
• Le funzioni parallele nuove rispettano il limite di 88 caratteri (0 E501).
• ruff check tests/parallel_ping_test.py → All checks passed.

4.2 Test ufficiali del repo Gitea kaibot/bal-plugin-ai/tests

Eseguiti contro il codice refactorizzato (con le modifiche networking):

Suite	Esito
test_core_* (pytest)	117 passed
test_gui_* (pytest)	65 passed
smoke_test.py	OK
external_zip_test.py	OK
windows_overflow_test.py	OK
gui_fixes_test.py	OK
parallel_ping_test.py (nuovo)	OK — 0.50s per 8 server (sequenziale ~4.00s)

Comandi (come da README):

QT_QPA_PLATFORM=offscreen PYTHONPATH=<electrum-src> \
    python3 -m pytest tests/ -q
QT_QPA_PLATFORM=offscreen PYTHONPATH=<electrum-src> \
    python3 tests/smoke_test.py electrum.plugins.bal
QT_QPA_PLATFORM=offscreen PYTHONPATH=<electrum-src> \
    python3 tests/external_zip_test.py bal-electrum-plugin.zip

---

5. Note di integrazione / rischi

• Nessuna modifica al protocollo server: solo il come (parallelo) e il quando (retry) delle chiamate cambia, non i payload.
• Push transazioni: i retry per-server sono mantenuti apposta, per non perdere una transazione reale per un hiccup. Solo il ping/info/download usa fast-fail.
• max_workers=8 è prudente; con molti server (es. 20) si può alzare, ma 8 worker già abbattono il tempo totale al server più lento.
• Thread/UI: tutti gli aggiornamenti UI dai worker passano per BalWaitingDialog.update() (pyqtSignal) → safe. Non toccare quel canale.
• Compatibilità: firme retro-compatibili (i nuovi parametri sono keyword-only con default che preservano il vecchio comportamento).

---

6. Come provare

1. Installare lo zip bal-electrum-plugin.zip (Tools → Plugins → install from file).
2. Configurare più Will-Executor, includendone almeno uno irraggiungibile.
3. Lanciare invio transazioni / ping: il dialog mostra lo stato server-per-server e non resta più bloccato sul server morto.

SHA-256 dello zip stampato da build_zip.py a fine build (verificare l'integrità).