temp
This commit is contained in:
1 parent
61efbb0e37
commit
c5e7daa9c7
15 files changed
+4514
-1172
No files matched your search
+271
-67
@@ -19,29 +19,45 @@ flowchart LR
|
||||
C -- "HTTP app:8123<br/>(rete interna compose)" --> A["Container app<br/>1 processo uvicorn<br/>FastAPI + 6 task asyncio"]
|
||||
A -- "aiosqlite" --> D[("./data/db/plm_lottery.db<br/>SQLite, WAL")]
|
||||
A -- "legge" --> K["./data/keys/master.xprv.enc"]
|
||||
A -- "scrive" --> L["./data/logs/app.log"]
|
||||
A -- "scrive" --> L["./data/logs/app.log<br/>(e stdout, B-92)"]
|
||||
A -- "Electrum (TCP/SSL)<br/>una connessione attiva" --> E["Server Electrum PLM<br/>primario + riserve"]
|
||||
```
|
||||
|
||||
- **[ARC-01]** Il server gira sempre in Docker, con lo stesso
|
||||
`docker-compose.yml` in sviluppo e in produzione: due container, `app`
|
||||
(questo codice) e `caddy` (reverse proxy con TLS automatico). Cambia solo
|
||||
`SITE_ADDRESS`: non impostato vale `localhost` (certificato autofirmato
|
||||
dalla CA interna di Caddy), impostato a un dominio produce un certificato
|
||||
Let's Encrypt. Non esiste un modo supportato di lanciare `uvicorn` fuori da
|
||||
Docker.
|
||||
`SITE_ADDRESS`, che sta in `.env` ed è obbligatorio: il compose lo legge
|
||||
come `${SITE_ADDRESS:?}` e si rifiuta di partire se manca. `localhost`
|
||||
produce un certificato autofirmato dalla CA interna di Caddy, un dominio un
|
||||
certificato Let's Encrypt. Non esiste un modo supportato di lanciare
|
||||
`uvicorn` fuori da Docker.
|
||||
*Codice:* `docker-compose.yml` · `Caddyfile` ·
|
||||
*Test:* `tests/unit/test_docs_no_bare_uvicorn.py`
|
||||
*Stato:* da implementare (B-93) · *Oggi:* `SITE_ADDRESS` si passa sul
|
||||
comando e non impostato vale `localhost`, quindi un `docker compose up`
|
||||
senza variabile riporta un server di produzione su `localhost`.
|
||||
- **[ARC-02]** Il container `app` esegue **un solo processo** uvicorn (nessun
|
||||
`--workers`), in ascolto su `0.0.0.0:8123`. Tutto lo stato in memoria
|
||||
descritto in [Assunzioni di processo singolo](#assunzioni-di-processo-singolo)
|
||||
dipende da questo.
|
||||
*Codice:* `Dockerfile` (`CMD`)
|
||||
`--workers`), in ascolto su `0.0.0.0:8123`, con `--proxy-headers` e
|
||||
`--forwarded-allow-ips` limitato all'indirizzo di Caddy: la rete di compose
|
||||
ha una sottorete fissa e Caddy un indirizzo IPv4 fisso in essa. Così il log
|
||||
di accesso registra l'IP del client invece di quello di Caddy. Tutto lo
|
||||
stato in memoria descritto in
|
||||
[Assunzioni di processo singolo](#assunzioni-di-processo-singolo) dipende da
|
||||
questo.
|
||||
*Codice:* `Dockerfile` (`CMD`) · `docker-compose.yml`
|
||||
*Stato:* da implementare (B-92) · *Oggi:* uvicorn non legge gli header del
|
||||
proxy e il log di accesso registra l'IP di Caddy.
|
||||
- **[ARC-03]** All'avvio il container `app`, nell'ordine: rifiuta di partire
|
||||
se il file indicato da `MASTER_KEY_PATH` non esiste (stampando il comando
|
||||
per generarlo), poi esegue `alembic upgrade head`, poi avvia uvicorn con
|
||||
`exec`. Le migrazioni non si lanciano mai a mano.
|
||||
`exec`. Le migrazioni non si lanciano mai a mano. Il processo gira come
|
||||
utente non root, su un'immagine di base fissata per digest e con dipendenze
|
||||
installate da un file di lock con gli hash
|
||||
([sicurezza.md](sicurezza.md) (B-91)). I controlli che richiedono il codice
|
||||
applicativo (chiave, quorum, ripristino) sono nel lifespan ([ARC-60]).
|
||||
*Codice:* `Dockerfile` (`CMD`) · `migrations/env.py`
|
||||
*Stato:* da implementare (B-91) · *Oggi:* il container gira come root,
|
||||
`python:3.12-slim` non è fissato per digest e le dipendenze sono `>=`.
|
||||
- **[ARC-04]** `app` è solo `expose`d sulla rete interna di compose (porta
|
||||
8123), mai pubblicato sull'host: l'unico ingresso è Caddy, che pubblica 80 e
|
||||
443. Su questo si basa la lettura dell'IP del client (vedi
|
||||
@@ -54,8 +70,34 @@ flowchart LR
|
||||
`./data/logs` → `/app/logs`. Il compose sovrascrive `DATABASE_URL` e
|
||||
`MASTER_KEY_PATH` perché puntino a quei percorsi; tutte le altre variabili
|
||||
arrivano da `.env` (`env_file`). Entrambi i container hanno
|
||||
`restart: unless-stopped`.
|
||||
`restart: unless-stopped`. La chiave di cifratura della master key è un
|
||||
file a parte, `./secrets/xprv_encryption.key` (permessi `0600`, fuori da
|
||||
`./data/` così un backup dei dati non la contiene), montato in sola lettura
|
||||
come secret di compose in `/run/secrets/xprv_encryption_key` e indicato da
|
||||
`XPRV_ENCRYPTION_KEY_FILE` ([ARC-30]). Le directory di `./data/` hanno
|
||||
permessi `0700`, i file di chiave `0600`. Le immagini sono etichettate per
|
||||
rilascio, così un rollback sa quale immagine rimettere
|
||||
([operativita.md](operativita.md) (B-93)).
|
||||
*Codice:* `docker-compose.yml`
|
||||
*Stato:* da implementare (B-91, B-93) · *Oggi:* la chiave di cifratura è la
|
||||
variabile `XPRV_ENCRYPTION_KEY` in `.env`, i permessi sono quelli di default
|
||||
(`.env` e file di chiave leggibili da tutti) e l'immagine non ha etichetta.
|
||||
|
||||
- **[ARC-61]** **Salute del container.** Il container `app` ha un
|
||||
`healthcheck` che interroga `http://127.0.0.1:8123/health/ready` ogni 30s
|
||||
(timeout 5s, 3 tentativi, `start_period` 60s). `/health/ready` risponde 200
|
||||
solo se la connessione Electrum è attiva, l'ultimo header è recente e lo
|
||||
scheduler ha battuto da poco; le soglie sono di
|
||||
[api.md](api.md#servizio) (B-92). Lo scheduler aggiorna il battito a ogni
|
||||
giro **e** a ogni iterazione dell'attesa del blocco di estrazione, perché
|
||||
quell'attesa gira dentro il giro ([ARC-27]) e dura più blocchi. Docker non
|
||||
riavvia un container `unhealthy`: lo stato serve al monitoraggio
|
||||
([operativita.md](operativita.md#segnali-da-tenere-docchio)), e il riavvio
|
||||
resta affidato a `restart: unless-stopped` quando il processo esce.
|
||||
*Codice:* `docker-compose.yml` · `app/main.py:health` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-92) · *Oggi:* nessun `healthcheck`; esiste solo
|
||||
`/health`, che risponde sempre `ok` ([ARC-17]).
|
||||
|
||||
### Database
|
||||
|
||||
@@ -67,12 +109,23 @@ flowchart LR
|
||||
proprie sessioni.
|
||||
*Codice:* `app/db/base.py` · `app/db/session.py:get_session`
|
||||
- **[ARC-07]** A ogni nuova connessione SQLite vengono impostati
|
||||
`journal_mode=WAL`, `synchronous=NORMAL` e `busy_timeout=5000` ms: in WAL
|
||||
lettori e scrittori non si bloccano a vicenda, e uno scrittore che trova il
|
||||
database occupato aspetta fino a 5 secondi invece di fallire subito. Con un
|
||||
dialetto diverso da SQLite le pragma non vengono applicate.
|
||||
`journal_mode=WAL`, `synchronous=FULL` e `busy_timeout=5000` ms: in WAL
|
||||
lettori e scrittori non si bloccano a vicenda, uno scrittore che trova il
|
||||
database occupato aspetta fino a 5 secondi invece di fallire subito, e
|
||||
`FULL` fa sì che un commit riuscito sopravviva a una mancanza di corrente
|
||||
(con `NORMAL` si potevano perdere gli ultimi commit, per esempio una
|
||||
registrazione, riusandone poi l'indice di derivazione). Ogni transazione che
|
||||
sposta denaro si apre con `BEGIN IMMEDIATE`, così le letture su cui decide
|
||||
sono isolate e l'attesa del lock avviene all'inizio, non alla prima
|
||||
scrittura; un `database is locked` dopo un invio è gestito esplicitamente
|
||||
(la riga resta al riconciliatore). Con un dialetto diverso da SQLite le
|
||||
pragma non vengono applicate.
|
||||
*Codice:* `app/db/base.py:_register_sqlite_pragmas` ·
|
||||
*Test:* `tests/unit/test_db_base.py`
|
||||
*Stato:* da implementare (B-88) · *Oggi:* `synchronous=NORMAL`, e pysqlite
|
||||
in modalità legacy emette `BEGIN` solo alla prima scrittura, quindi le
|
||||
letture precedenti non sono isolate e l'attesa del lock può scattare in
|
||||
punti qualsiasi.
|
||||
- **[ARC-08]** Lo schema è definito in `app/db/models.py` ed evolve solo
|
||||
tramite migrazioni Alembic in `migrations/versions/` (generate con
|
||||
`alembic revision --autogenerate`); `migrations/env.py` prende l'URL del
|
||||
@@ -85,9 +138,14 @@ flowchart LR
|
||||
- **[ARC-09]** Tutti i log dell'applicazione e di uvicorn (`uvicorn.error`,
|
||||
`uvicorn.access`) finiscono in `logs/app.log` (nel container
|
||||
`/app/logs/app.log`, cioè `./data/logs/app.log` sull'host), a rotazione da
|
||||
10 MB con 5 file di storico, livello `INFO`. La configurazione avviene
|
||||
all'import di `app/main.py`, prima di qualunque altro modulo applicativo.
|
||||
10 MB con 5 file di storico, livello `INFO`, **e anche su stdout**, così
|
||||
`docker compose logs` li mostra senza entrare nel volume. La configurazione
|
||||
avviene all'import di `app/main.py`, prima di qualunque altro modulo
|
||||
applicativo.
|
||||
*Codice:* `app/logging_config.py:setup_logging`
|
||||
*Stato:* da implementare (B-92) · *Oggi:* i log dell'applicazione vanno solo
|
||||
nel file; su console arrivano solo quelli di uvicorn, per la sua
|
||||
configurazione predefinita.
|
||||
|
||||
## Mappa del codice
|
||||
|
||||
@@ -136,17 +194,17 @@ sono vuoti e non sono elencati.
|
||||
|---|---|
|
||||
| `app/wallet/plm_network.py` | Parametri della rete PLM per embit (`PLM_MAINNET`), coin type 746, `ACCOUNT_PATH` |
|
||||
| `app/wallet/keystore.py` | Cifratura/decifratura Fernet della master xprv |
|
||||
| `app/wallet/hd.py` | Generazione della master key, derivazione di indirizzi/chiavi utente (`0/i`) e del pool (`1/0`), export WIF; la chiave d'account decifrata resta in cache nel processo |
|
||||
| `app/wallet/hd.py` | Generazione della master key, derivazione di indirizzi/chiavi utente (`0/i`) e del pool (`1/0`), export WIF; la chiave d'account decifrata resta in cache nel processo. *Da implementare:* indirizzo del montepremi per round (`2/<round_id>`), con `1/0` come indirizzo di riserva (B-80) |
|
||||
| `app/wallet/address.py` | `is_valid_plm_address`: checksum bech32 + HRP `plm` |
|
||||
| `app/wallet/balance.py` | `recompute_balance` (saldo confermato), `compute_pending_balance` (saldo mostrato) — vedi [registrazione-e-depositi.md](registrazione-e-depositi.md) |
|
||||
| `app/wallet/psbt_builder.py` | Selezione UTXO, costruzione e firma di scommessa, prelievo e pagamento; limiti `MAX_TX_INPUTS`, `MAX_PAYOUT_TX_INPUTS`, `MAX_PARTICIPANTS_PER_ROUND`, `DUST_LIMIT_SATS` |
|
||||
| `app/wallet/psbt_builder.py` | Selezione UTXO, costruzione e firma di scommessa, prelievo e pagamento; limiti `MAX_TX_INPUTS`, `MAX_PAYOUT_TX_INPUTS`, `MAX_PARTICIPANTS_PER_ROUND`, `DUST_LIMIT_SATS`. *Da implementare:* uscita di riserva per l'RBF sul pagamento (B-79), UTXO sotto `DUST_LIMIT_SATS` esclusi dalla selezione (B-75) |
|
||||
|
||||
### Rete Electrum
|
||||
|
||||
| File | Responsabilità |
|
||||
|---|---|
|
||||
| `app/electrum/client.py` | `ElectrumClient` (JSON-RPC, timeout per richiesta), `ElectrumEndpoint`, `parse_endpoints` |
|
||||
| `app/electrum/listener.py` | `ElectrumListener`: l'unica connessione, rotazione, keepalive, validazione header, corroborazione, sottoscrizioni e accredito — vedi [connessione-electrum.md](connessione-electrum.md) |
|
||||
| `app/electrum/client.py` | `ElectrumClient` (JSON-RPC, timeout per richiesta), `ElectrumEndpoint`, `parse_endpoints`. *Da implementare:* limite di lettura di 16 MiB per riga, risposta troppo grande o malformata come errore della richiesta e non della connessione (B-75); pin del certificato per endpoint (B-84) |
|
||||
| `app/electrum/listener.py` | `ElectrumListener`: l'unica connessione, rotazione, keepalive, validazione header, corroborazione, sottoscrizioni e accredito — vedi [connessione-electrum.md](connessione-electrum.md). Il docstring della classe cita un metodo `add_address` che non esiste: l'indirizzo di un nuovo utente si aggiunge con `address_for_new_user` |
|
||||
| `app/electrum/scripthash.py` | `address_to_scripthash`: scripthash Electrum di un indirizzo |
|
||||
|
||||
### Dominio
|
||||
@@ -161,7 +219,7 @@ sono vuoti e non sono elencati.
|
||||
| `app/withdrawals/confirmation.py` | Gestore di conferma per il tipo `withdrawal` |
|
||||
| `app/rounds/service.py` | Round attivo, scadenza, accettazione scommesse, `rounds_can_open`, apertura del round, quota del vincitore |
|
||||
| `app/rounds/scheduler.py` | `RoundScheduler`: chiusura, estrazione, pagamento e suoi tentativi |
|
||||
| `app/rounds/draw.py` | Matematica degli header (hash, prev-hash, target) e scelta del vincitore |
|
||||
| `app/rounds/draw.py` | Matematica degli header (hash, prev-hash, target) e scelta del vincitore. *Da implementare:* seme commit-reveal e impronta dei partecipanti (B-73), confronto del bersaglio con `powLimit` (B-74) |
|
||||
| `app/rounds/config.py` | `get_round_config`: la riga unica di `round_config`, creata se manca |
|
||||
| `app/rounds/confirmation.py` | Gestore di conferma per il tipo `payout` |
|
||||
| `app/rounds/events.py` | `RoundEventBroadcaster` e il singleton `broadcaster` (SSE) |
|
||||
@@ -287,13 +345,20 @@ sequenceDiagram
|
||||
U->>L: startup
|
||||
L->>L: validate_runtime_secrets()
|
||||
L->>L: parse_endpoints(...)
|
||||
L->>L: quorum minimo (B-84, da implementare)
|
||||
L->>L: verifica della master key (B-89, da implementare)
|
||||
L->>L: START_PAUSED (B-90, da implementare)
|
||||
L->>L: app.state.electrum_listener, app.state.user_locks
|
||||
L->>L: create_task ×6
|
||||
Note over L: il server serve richieste
|
||||
Note over L: il server serve richieste<br/>(controllo dei buchi di indici alla prima connessione, B-90)
|
||||
U->>L: shutdown
|
||||
L->>L: cancel() dei 6 task, chiusura del client Electrum
|
||||
L->>L: chiusura dei flussi SSE (B-93, da implementare)
|
||||
L->>L: cancel() dei 6 task (e attesa della fine, B-93), chiusura del client Electrum
|
||||
```
|
||||
|
||||
Il diagramma mostra il comportamento atteso; i passi marcati «da
|
||||
implementare» non esistono ancora nel codice (vedi [ARC-60] e [ARC-22]).
|
||||
|
||||
### All'import
|
||||
|
||||
- **[ARC-12]** `setup_logging()` è chiamata come prima istruzione applicativa
|
||||
@@ -321,34 +386,76 @@ sequenceDiagram
|
||||
*Codice:* `app/main.py:log_unhandled_exception` ·
|
||||
*Test:* `tests/unit/test_rounds_route.py`
|
||||
- **[ARC-17]** `GET /health` risponde `{"status": "ok"}` senza toccare
|
||||
database né rete.
|
||||
database né rete: dice solo che il processo risponde (*liveness*). Se il
|
||||
servizio è davvero in grado di lavorare lo dice `GET /health/ready`
|
||||
([ARC-61], [api.md](api.md#servizio) (B-92)).
|
||||
*Codice:* `app/main.py:health`
|
||||
- **[ARC-18]** Le quattro pagine HTML hanno route esplicite che servono il
|
||||
file con `Cache-Control: no-store`: `/` → `index.html`, `/admin` →
|
||||
`admin.html`, `/guida` → `guida.html`, `/report-bug` → `report-bug.html`.
|
||||
Per ultimo, l'intera cartella `app/static/` è montata su `/` con
|
||||
`StaticFiles(html=True)`: JS, CSS e ogni altro file vi sono serviti con il
|
||||
loro nome (`/app.js`, `/i18n.js`, `/admin.css`…). I percorsi sono relativi
|
||||
alla directory di lavoro, che nel container è `/app`.
|
||||
loro nome (`/app.js`, `/i18n.js`, `/admin.css`…), con
|
||||
`Cache-Control: no-cache` (il browser li riconvalida a ogni caricamento).
|
||||
I percorsi sono relativi alla directory di lavoro, che nel container è
|
||||
`/app`.
|
||||
*Codice:* `app/main.py:index_page` · `app/main.py:admin_panel` ·
|
||||
`app/main.py:user_guide` · `app/main.py:report_bug_page`
|
||||
*Stato:* da implementare (B-94) · *Oggi:* `Cache-Control` c'è **solo** sulle
|
||||
quattro pagine HTML; i file serviti da `StaticFiles` (e `/index.html`
|
||||
chiesto per nome) non ne hanno, e il browser può usare uno script vecchio
|
||||
con una pagina nuova.
|
||||
|
||||
### Nel lifespan
|
||||
|
||||
- **[ARC-19]** Come primo passo, `validate_runtime_secrets()` fa rifiutare
|
||||
l'avvio (solleva `ConfigError`) se `JWT_SECRET` è più corto di 32
|
||||
caratteri o `XPRV_ENCRYPTION_KEY` è vuota, riportando tutti i problemi
|
||||
insieme. `ADMIN_TOKEN` vuoto **non** blocca l'avvio: il pannello resta
|
||||
semplicemente chiuso. Il controllo sta nel lifespan e non in un validatore
|
||||
di `Settings`, così import e test non hanno bisogno di segreti veri.
|
||||
caratteri o la chiave di cifratura della master key è vuota (il file
|
||||
indicato da `XPRV_ENCRYPTION_KEY_FILE` manca o è vuoto), riportando tutti i
|
||||
problemi insieme. `ADMIN_TOKEN` vuoto **non** blocca l'avvio: il pannello
|
||||
resta semplicemente chiuso. Il controllo sta nel lifespan e non in un
|
||||
validatore di `Settings`, così import e test non hanno bisogno di segreti
|
||||
veri.
|
||||
*Codice:* `app/config.py:validate_runtime_secrets` ·
|
||||
*Test:* `tests/unit/test_config.py`
|
||||
*Stato:* da implementare (B-91) · *Oggi:* si controlla che la variabile
|
||||
`XPRV_ENCRYPTION_KEY` non sia vuota.
|
||||
- **[ARC-20]** Gli endpoint Electrum vengono letti da `ELECTRUM_HOST`,
|
||||
`ELECTRUM_PORT`, `ELECTRUM_USE_SSL` ed `ELECTRUM_FALLBACK_SERVERS`; un
|
||||
`ELECTRUM_PORT`, `ELECTRUM_USE_SSL` ed `ELECTRUM_FALLBACK_SERVERS`
|
||||
(`host:porta[:notls][:pin=<sha256>]` separati da virgola, [ARC-30]); un
|
||||
elenco di riserva malformato blocca l'avvio. L'ordine di rotazione viene
|
||||
scritto nel log.
|
||||
*Codice:* `app/electrum/client.py:parse_endpoints` ·
|
||||
*Test:* `tests/unit/test_electrum_client.py`
|
||||
*Stato:* da implementare (B-84) · *Oggi:* la sintassi è `host:porta[:notls]`,
|
||||
senza pin del certificato.
|
||||
|
||||
- **[ARC-60]** **Controlli di avvio.** Dopo [ARC-19] e [ARC-20] e prima di
|
||||
creare i task, il lifespan esegue nell'ordine, e ogni controllo fallito
|
||||
impedisce di servire:
|
||||
1. **quorum minimo**: almeno 2 server di riserva, salvo
|
||||
`ALLOW_NO_QUORUM=true` (solo sviluppo, scritto nel log come
|
||||
avvertimento) — regola in
|
||||
[connessione-electrum.md](connessione-electrum.md#5-il-quorum) (B-84);
|
||||
2. **master key**: la chiave viene decifrata e l'indirizzo di riserva del
|
||||
montepremi e un campione degli indirizzi utente salvati vengono
|
||||
ricalcolati e confrontati con il database — regola in
|
||||
[sicurezza.md](sicurezza.md#regole-di-avvio) (B-89);
|
||||
3. **avvio in pausa**: con `START_PAUSED=true` la lotteria viene messa in
|
||||
pausa prima che lo scheduler parta — procedura in
|
||||
[operativita.md](operativita.md#ripristino) (B-90).
|
||||
|
||||
Il controllo dei **buchi negli indici di derivazione** dopo un ripristino
|
||||
(i 20 indici successivi al più alto assegnato, che non devono avere
|
||||
cronologia in catena) ha bisogno della rete, quindi non può stare prima
|
||||
dei task: gira alla prima connessione del listener, e finché non si è
|
||||
concluso senza trovare cronologia la registrazione è rifiutata
|
||||
([operativita.md](operativita.md#ripristino), B-90).
|
||||
*Codice:* `app/main.py:lifespan` · `app/config.py:validate_runtime_secrets` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-84, B-89, B-90) · *Oggi:* dopo i segreti e gli
|
||||
endpoint il lifespan crea subito i task; la chiave si decifra alla prima
|
||||
registrazione o al primo pagamento.
|
||||
- **[ARC-21]** Lo stato condiviso con le route vive su `app.state`:
|
||||
`electrum_listener` (l'`ElectrumListener`) e `user_locks` (un
|
||||
`UserLocks`), creati nel lifespan; `auth_rate_limiters` viene invece creato
|
||||
@@ -356,10 +463,17 @@ sequenceDiagram
|
||||
*Codice:* `app/main.py:lifespan` · `app/auth/routes.py:_rate_limiters`
|
||||
- **[ARC-22]** Il lifespan crea esattamente sei task asyncio, nell'ordine
|
||||
`ElectrumListener`, `RoundScheduler`, `ConfirmationPoller`, `RbfBumper`,
|
||||
`PendingTransactionReconciler`, `DepositReconciler`. Allo spegnimento
|
||||
ciascun task riceve `cancel()` (senza attenderne la fine) e il client
|
||||
Electrum, se presente, viene chiuso.
|
||||
*Codice:* `app/main.py:lifespan` · *Test:* `tests/unit/test_code_comments.py`
|
||||
`PendingTransactionReconciler`, `DepositReconciler`. Allo spegnimento, in
|
||||
quest'ordine: ogni flusso SSE aperto viene chiuso (altrimenti uvicorn
|
||||
aspetta le connessioni aperte e Docker lo uccide), ciascun task riceve
|
||||
`cancel()` e il lifespan **ne attende la fine**, poi il client Electrum, se
|
||||
presente, viene chiuso. Il compose dà al container `stop_grace_period: 30s`
|
||||
per completare questa sequenza prima del `SIGKILL`.
|
||||
*Codice:* `app/main.py:lifespan` · `app/rounds/events.py:RoundEventBroadcaster` · `docker-compose.yml` ·
|
||||
*Test:* `tests/unit/test_code_comments.py`
|
||||
*Stato:* da implementare (B-93) · *Oggi:* i task ricevono `cancel()` senza
|
||||
attesa, i flussi SSE restano aperti, e con uno stream collegato Docker uccide
|
||||
il container dopo i 10s predefiniti.
|
||||
|
||||
## Attività in background
|
||||
|
||||
@@ -414,24 +528,53 @@ sequenceDiagram
|
||||
subito al server successivo; l'attesa crescente (1s raddoppiando fino a 30s)
|
||||
scatta solo quando tutti i server hanno fallito nello stesso giro.
|
||||
Rotazione, keepalive, validazione e corroborazione sono in
|
||||
[connessione-electrum.md](connessione-electrum.md).
|
||||
[connessione-electrum.md](connessione-electrum.md). Tre cambiamenti di
|
||||
struttura sono attesi dal piano, con le regole in quel documento:
|
||||
- il listener conserva gli ultimi 10 header ricevuti; un salto di più
|
||||
blocchi scarica e valida gli header intermedi, e un header che si
|
||||
concatena a uno di quelli conservati ma non alla punta è una
|
||||
riorganizzazione da seguire, non la fine della sessione (B-74, B-85);
|
||||
- una sessione connessa la cui punta non avanza da 360s, mentre un altro
|
||||
server ne riporta una più alta, viene chiusa e si passa al server
|
||||
successivo (B-86);
|
||||
- il client legge righe fino a 16 MiB, e una risposta oltre il limite o
|
||||
malformata fa fallire la sola richiesta, non la connessione (B-75).
|
||||
|
||||
*Codice:* `app/electrum/listener.py:ElectrumListener.run` ·
|
||||
`app/electrum/listener.py:ElectrumListener._apply_header` ·
|
||||
`app/electrum/client.py:ElectrumClient.connect` ·
|
||||
*Test:* `tests/unit/test_electrum_listener.py`
|
||||
*Stato:* da implementare (B-74, B-75, B-85, B-86) · *Oggi:* il listener
|
||||
tiene solo la punta, chiude la sessione su ogni header che non si concatena,
|
||||
non confronta la propria punta con gli altri server, e il client usa il
|
||||
limite predefinito di 64 KiB di `asyncio.open_connection`, oltre il quale
|
||||
cade l'intera connessione.
|
||||
- **[ARC-27]** **`RoundScheduler`.** A ogni giro (5s) chiama
|
||||
`open_new_round_if_needed` e poi avanza il round attivo. L'estrazione
|
||||
(`_close_and_draw`, con l'attesa del blocco successivo) viene eseguita
|
||||
**dentro** il giro: finché dura, lo scheduler non fa altro. Dopo un riavvio
|
||||
un round rimasto in `drawing` non viene ripreso (limite accettato, vedi
|
||||
[decisioni-e-limiti.md](decisioni-e-limiti.md)). Logica del round in
|
||||
[ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md).
|
||||
`open_new_round_if_needed` e poi avanza il round attivo, in qualunque stato
|
||||
sia, `drawing` compreso: per un round in `drawing` il giro rientra
|
||||
nell'attesa del blocco di estrazione a partire da ciò che è salvato sulla
|
||||
riga del round (`draw_height`, `participants_hash`, posizioni dei
|
||||
partecipanti), in modo idempotente. L'attesa **resta dentro il giro**:
|
||||
finché dura, lo scheduler non fa altro, il che è corretto perché nessun
|
||||
altro round può aprirsi finché questo non è `closed`. Un'eccezione durante
|
||||
l'attesa termina il giro ([ARC-25]) e il giro successivo riparte dallo stato
|
||||
salvato, con lo stesso esito; lo stesso vale dopo un riavvio. Logica del
|
||||
round in [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#3--estrazione).
|
||||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick` ·
|
||||
`app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
|
||||
`app/rounds/scheduler.py:RoundScheduler._wait_for_next_block` ·
|
||||
*Test:* `tests/unit/test_scheduler.py`
|
||||
*Stato:* da implementare (B-81) · *Oggi:* `_tick` salta i round in
|
||||
`drawing`; `tip_at_close` e i partecipanti vivono solo nella chiamata a
|
||||
`_close_and_draw`, quindi un'eccezione o un riavvio lasciano il round in
|
||||
`drawing` per sempre
|
||||
([LIM-01](decisioni-e-limiti.md#robustezza-del-ciclo-di-vita)).
|
||||
- **[ARC-28]** **`ConfirmationPoller`** (10s), **`RbfBumper`** (30s) e
|
||||
**`PendingTransactionReconciler`** (al primo giro subito, poi ogni 120s)
|
||||
lavorano sulla tabella `pending_transactions`; il riconciliatore parte
|
||||
subito perché un crash durante un invio lascia proprio una riga `building`
|
||||
da risolvere al riavvio. Regole in
|
||||
lavorano sulla tabella `pending_transactions` (e, dal piano, sulla tabella
|
||||
di tutti i txid di ogni riga, B-77); il riconciliatore parte subito perché
|
||||
un crash durante un invio lascia proprio una riga `building` da risolvere
|
||||
al riavvio. Regole in
|
||||
[transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md).
|
||||
*Codice:* `app/tx/confirmation.py:ConfirmationPoller` ·
|
||||
`app/tx/broadcast.py:RbfBumper` ·
|
||||
@@ -459,8 +602,10 @@ La configurazione è divisa in due posti con regole diverse.
|
||||
| `electrum_host` | `ELECTRUM_HOST` | `santantonio.sytes.net` | Server Electrum primario |
|
||||
| `electrum_port` | `ELECTRUM_PORT` | `50002` | Porta del primario |
|
||||
| `electrum_use_ssl` | `ELECTRUM_USE_SSL` | `True` | TLS verso il primario |
|
||||
| `electrum_fallback_servers` | `ELECTRUM_FALLBACK_SERVERS` | `""` | Riserve, `host:porta[:notls]` separati da virgola |
|
||||
| `xprv_encryption_key` | `XPRV_ENCRYPTION_KEY` | `""` | Chiave Fernet della master xprv (obbligatoria, [ARC-19]) |
|
||||
| `electrum_fallback_servers` | `ELECTRUM_FALLBACK_SERVERS` | `""` | Riserve, `host:porta[:notls][:pin=<sha256>]` separati da virgola; almeno 2 ([ARC-60]) |
|
||||
| `allow_no_quorum` | `ALLOW_NO_QUORUM` | `False` | Permette di partire con meno di 2 server di riserva; solo sviluppo ([ARC-60]) |
|
||||
| `xprv_encryption_key_file` | `XPRV_ENCRYPTION_KEY_FILE` | `/run/secrets/xprv_encryption_key` | File con la chiave Fernet della master xprv (obbligatorio, [ARC-19]); sostituisce `XPRV_ENCRYPTION_KEY` |
|
||||
| `start_paused` | `START_PAUSED` | `False` | Avvia con la lotteria in pausa, dopo un ripristino ([ARC-60]) |
|
||||
| `master_key_path` | `MASTER_KEY_PATH` | `./master.xprv.enc` | File della master xprv cifrata (in Docker sovrascritto dal compose) |
|
||||
| `jwt_secret` | `JWT_SECRET` | `""` | Chiave HS256 dei token (≥ 32 caratteri, [ARC-19]) |
|
||||
| `jwt_algorithm` | `JWT_ALGORITHM` | `HS256` | Algoritmo JWT |
|
||||
@@ -469,22 +614,35 @@ La configurazione è divisa in due posti con regole diverse.
|
||||
| `enable_api_docs` | `ENABLE_API_DOCS` | `False` | Espone Swagger/ReDoc/OpenAPI ([ARC-14]) |
|
||||
|
||||
*Codice:* `app/config.py:Settings` · *Test:* `tests/unit/test_config.py`
|
||||
*Stato:* da implementare (B-84, B-90, B-91) · *Oggi:* `ALLOW_NO_QUORUM`,
|
||||
`START_PAUSED` e `XPRV_ENCRYPTION_KEY_FILE` non esistono, la chiave Fernet è
|
||||
la variabile `XPRV_ENCRYPTION_KEY` e la sintassi delle riserve non ha
|
||||
`pin=`.
|
||||
- **[ARC-31]** **Parametri operativi e di business** (costo della scommessa,
|
||||
durata e pausa del round, animazione, commissione di rete, timeout RBF,
|
||||
indirizzo commissioni, pausa di manutenzione) stanno nell'unica riga della
|
||||
tabella `round_config`, modificabile a caldo da `/admin` senza riavvio. I
|
||||
valori iniziali sono i default delle colonne di `RoundConfig`, non
|
||||
`app/config.py`. Se la riga manca, viene creata al primo accesso con
|
||||
`fee_address` vuoto. Campi in [modello-dati.md](modello-dati.md), effetti
|
||||
in [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md).
|
||||
indirizzo commissioni, pausa di manutenzione e suo motivo, conferme dei
|
||||
depositi `deposit_confirmations`, conferme del blocco di estrazione
|
||||
`draw_confirmations`, tetto al montepremi `max_round_pool_sats`) stanno
|
||||
nell'unica riga della tabella `round_config`, modificabile a caldo da
|
||||
`/admin` senza riavvio. I valori iniziali sono i default delle colonne di
|
||||
`RoundConfig`, non `app/config.py`. Se la riga manca, viene creata al primo
|
||||
accesso con `fee_address` vuoto. Campi in [modello-dati.md](modello-dati.md),
|
||||
effetti in [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md).
|
||||
*Codice:* `app/rounds/config.py:get_round_config` ·
|
||||
`app/db/models.py:RoundConfig`
|
||||
*Stato:* da implementare (B-73, B-82, B-85, B-95) · *Oggi:*
|
||||
`deposit_confirmations`, `draw_confirmations`, `max_round_pool_sats` e il
|
||||
motivo della pausa non esistono.
|
||||
- **[ARC-32]** Alcuni valori sono costanti nel codice e non configurabili:
|
||||
la ripartizione 70/30, le conferme richieste (1), i limiti di input e di
|
||||
la ripartizione 70/30, le conferme richieste per le transazioni della
|
||||
piattaforma (1) e per le uscite coinbase (120), i limiti di input e di
|
||||
partecipanti, le cadenze dei task. Si cambiano solo con una modifica al
|
||||
codice (vedi [decisioni-e-limiti.md](decisioni-e-limiti.md)).
|
||||
codice (vedi [decisioni-e-limiti.md](decisioni-e-limiti.md)). Le conferme
|
||||
dei depositi sono invece configurabili ([ARC-31]).
|
||||
*Codice:* `app/rounds/service.py:winner_share` ·
|
||||
`app/wallet/psbt_builder.py` · `app/tx/confirmation.py`
|
||||
*Stato:* da implementare (B-82) · *Oggi:* 1 conferma per ogni moneta e
|
||||
transazione, depositi e coinbase compresi.
|
||||
|
||||
## Aggiornamenti in tempo reale (SSE)
|
||||
|
||||
@@ -551,7 +709,9 @@ flowchart LR
|
||||
`app/withdrawals/service.py:_release_failed_withdrawal`;
|
||||
- transazione confermata — `app/tx/confirmation.py:poll_once`;
|
||||
- riga promossa o abbandonata dal riconciliatore —
|
||||
`app/tx/reconcile.py:reconcile_once`;
|
||||
`app/tx/reconcile.py:reconcile_once`. Oggi il riconciliatore pubblica per
|
||||
**ogni** riga che ricontrolla, anche quando non cambia nulla; la
|
||||
pubblicazione solo sui cambiamenti è in B-96;
|
||||
- deposito accreditato, UTXO segnata come spesa fuori piattaforma, UTXO
|
||||
ripristinata — `app/deposits/service.py:credit_confirmed_utxos`,
|
||||
`app/deposits/service.py:mark_utxos_spent_externally`,
|
||||
@@ -559,6 +719,8 @@ flowchart LR
|
||||
- nuovo header ricevuto — `app/electrum/listener.py:ElectrumListener._consume_headers`.
|
||||
|
||||
*Test:* `tests/unit/test_bets.py` (verifica la notifica di una scommessa)
|
||||
*Stato:* da implementare (B-96) · *Oggi:* il riconciliatore pubblica una
|
||||
notifica per ogni riga ricontrollata, anche senza cambiamenti.
|
||||
|
||||
## Lock per utente
|
||||
|
||||
@@ -636,11 +798,17 @@ flowchart LR
|
||||
barra di stato (stato del round e altezza della catena). Le sezioni Utenti,
|
||||
Round, Transazioni pendenti, Audit log e Bug report si caricano quando le
|
||||
si apre e si ricaricano a ogni evento SSE (`update` o `open`) mentre sono
|
||||
aperte; non hanno un polling periodico proprio. La sezione Parametri non
|
||||
viene ricaricata dagli eventi.
|
||||
aperte; non hanno un polling periodico proprio, quindi se il canale SSE è
|
||||
bloccato o caduto si aggiornano **solo** riaprendo la sezione. La sezione
|
||||
Parametri non viene ricaricata dagli eventi. Il piano aggiunge al pannello
|
||||
lo stato della connessione Electrum (endpoint, età dell'ultimo header) e i
|
||||
filtri dell'audit log (B-86, B-92).
|
||||
*Codice:* `app/static/admin.js:startChainStatusPolling` ·
|
||||
`app/static/admin.js:connectAdminEvents` ·
|
||||
`app/static/admin.js:onAdminServerEvent`
|
||||
*Stato:* da implementare (B-86, B-92), solo per lo stato Electrum e i
|
||||
filtri dell'audit · *Oggi:* il pannello mostra solo l'altezza della catena,
|
||||
e l'audit log le ultime righe senza filtri.
|
||||
|
||||
### `/report-bug` e `/guida`
|
||||
|
||||
@@ -762,14 +930,50 @@ italiano.
|
||||
`tests/unit/test_code_comments.py` ·
|
||||
`tests/unit/test_caddyfile_security_headers.py` ·
|
||||
`tests/unit/test_withdrawals.py`
|
||||
- **[ARC-58]** Ciò che la suite **non** copre: nessun test contro una
|
||||
connessione Electrum reale; il `lifespan` e l'avvio dei sei task; la route
|
||||
SSE `round_stream` (è testato solo il broadcaster); `UserLocks` e la sua
|
||||
acquisizione nelle route di scommessa e prelievo; il codice JavaScript dei
|
||||
frontend; la parità delle chiavi tra le lingue di `i18n.js`. Le verifiche
|
||||
dal vivo sono state manuali (`scripts/electrum_smoke_test.py` e transazioni
|
||||
reali su mainnet; prelievo e RBF mai trasmessi dal vivo, vedi
|
||||
[decisioni-e-limiti.md](decisioni-e-limiti.md)).
|
||||
- **[ARC-58]** Ciò che la suite **non** copre oggi: nessun test contro una
|
||||
connessione Electrum reale né contro guasti di rete realistici (ritardi,
|
||||
cadute a metà richiesta, risposte enormi, catene divergenti); il `lifespan`
|
||||
e l'avvio dei sei task; la route SSE `round_stream` (è testato solo il
|
||||
broadcaster); `UserLocks` e la sua acquisizione nelle route di scommessa e
|
||||
prelievo; il codice JavaScript dei frontend; la parità delle chiavi tra le
|
||||
lingue di `i18n.js`; le migrazioni Alembic (lo schema dei test nasce da
|
||||
`Base.metadata.create_all`). Le verifiche dal vivo sono state manuali
|
||||
(`scripts/electrum_smoke_test.py` e transazioni reali su mainnet; prelievo e
|
||||
RBF mai trasmessi dal vivo, vedi [decisioni-e-limiti.md](decisioni-e-limiti.md)).
|
||||
La revisione del 2026-09-28 ha osservato che nessuna delle sue falle
|
||||
critiche sarebbe stata trovata da questa suite, che simula tutto: da qui
|
||||
[ARC-62], [ARC-63] e [ARC-64].
|
||||
- **[ARC-62]** **Test delle migrazioni.** Un test esegue `alembic upgrade head`
|
||||
su un database vuoto e verifica che esistano gli indici su espressione
|
||||
`ix_rounds_single_active` e `ix_users_username_lower`, che l'autogenerate
|
||||
non vede e che `batch_alter_table` su SQLite elimina ricostruendo la
|
||||
tabella con un solo avviso. Ogni migrazione batch su `rounds` o `users` li
|
||||
ricrea esplicitamente.
|
||||
*Codice:* `migrations/env.py` · `migrations/versions/` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-97) · *Oggi:* nessun test esegue le migrazioni.
|
||||
- **[ARC-63]** **Test di parità delle traduzioni.** Un test legge
|
||||
`TRANSLATIONS` da `app/static/i18n.js` e fallisce se una delle sette lingue
|
||||
ha un insieme di chiavi diverso da quello di `en` ([ARC-51]).
|
||||
*Codice:* `app/static/i18n.js` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (senza B-nn: chiude
|
||||
[LIM-21](decisioni-e-limiti.md#prodotto-e-interfacce)) · *Oggi:* la parità è
|
||||
verificata solo a mano.
|
||||
- **[ARC-64]** **Strato di test di guasto e di integrazione**, in
|
||||
`tests/integration/`, separato dalla suite unitaria: server Electrum
|
||||
simulati a livello di socket che rispondono in ritardo, chiudono la
|
||||
connessione dopo aver ricevuto un invio, mandano risposte oltre 16 MiB,
|
||||
header a difficoltà minima o catene che si biforcano; più il database SQLite
|
||||
su file con scrittori concorrenti. Non sostituisce la prova con denaro vero
|
||||
e guasti provocati di
|
||||
[operativita.md](operativita.md#prova-su-rete-reale), che resta obbligatoria
|
||||
prima dell'apertura al pubblico.
|
||||
*Codice:* `tests/integration/__init__.py` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (fase 7 del
|
||||
[piano](piano-correzioni.md#fase-7--prova-su-rete-reale)) · *Oggi:*
|
||||
`tests/integration/` contiene solo `__init__.py`.
|
||||
|
||||
## Assunzioni di processo singolo
|
||||
|
||||
|
||||
Reference in new issue
Block a user