feat: implementa webapp FastAPI con API swagger e test

README.md

@@ -4,6 +4,12 @@ Tool Python dockerizzato pensato per mantenere "attivo" un database Supabase in
 
 L'idea e' semplice: il container resta in esecuzione fino a quando non viene fermato esplicitamente e, a intervalli regolari, esegue un'operazione verso il database Supabase per generare attivita' sufficiente a non far decadere l'istanza.
 
+In piu', il servizio espone una webapp/API con FastAPI servita da Uvicorn:
+
+- dashboard in stile SmokePing;
+- API read-only per stato e storico;
+- documentazione Swagger in `/docs` e OpenAPI in `/openapi.json`.
+
 ## Obiettivo
 
 I progetti Supabase in free tier possono diventare temporaneamente inaccessibili se rimangono inattivi troppo a lungo. Questo progetto serve a:
@@ -20,8 +26,9 @@ Il servizio viene eseguito all'interno di un container Docker e resta attivo in
 1. legge la configurazione dal file `.env`;
 2. apre una connessione al database Supabase/PostgreSQL;
 3. esegue una query o un'operazione leggera di keep-alive;
-4. attende l'intervallo configurato;
-5. ripete il processo fino allo stop del container.
+4. salva un campione storico (successo/errore + latenza) in uno storage locale a buffer circolare dimensionato per 48 ore;
+5. attende l'intervallo configurato;
+6. ripete il processo fino allo stop del container.
 
 ## Configurazione
 
@@ -40,6 +47,10 @@ SUPABASE_DB_PASSWORD=
 PING_INTERVAL_MINUTES=4320
 PING_QUERY=SELECT 1;
 TZ=Europe/Rome
+WEB_HOST=0.0.0.0
+WEB_PORT=8080
+RRD_DB_PATH=data/connection_rrd.sqlite3
+RRD_RETENTION_HOURS=48
 ```
 
 ### Significato delle variabili
@@ -52,6 +63,20 @@ TZ=Europe/Rome
 - `PING_INTERVAL_MINUTES`: intervallo tra un keep-alive e il successivo. Default `4320` (72 ore, circa 3 volte a settimana).
 - `PING_QUERY`: query leggera da eseguire per generare attivita'.
 - `TZ`: timezone del container per logging e scheduling coerenti.
+- `WEB_HOST`: host di bind del server Uvicorn.
+- `WEB_PORT`: porta HTTP della webapp/API.
+- `RRD_DB_PATH`: path del database storico locale (RRD-like a buffer circolare).
+- `RRD_RETENTION_HOURS`: retention dello storico, default `48`.
+
+## API e Swagger
+
+Endpoint principali:
+
+- `GET /api/status`: ultimo campione disponibile;
+- `GET /api/history?hours=48`: storico campioni (finestra max 48h);
+- `GET /`: dashboard web in stile SmokePing;
+- `GET /docs`: Swagger UI;
+- `GET /openapi.json`: schema OpenAPI.
 
 ## Docker
 
@@ -69,6 +94,7 @@ docker build -t supabase-pinger .
 docker run -d \
   --name supabase-pinger \
   --env-file .env \
+  -p 8080:8080 \
   --restart unless-stopped \
   supabase-pinger
 ```
@@ -90,6 +116,8 @@ services:
     container_name: supabase-pinger
     env_file:
       - .env
+    ports:
+      - "8080:8080"
     restart: unless-stopped
 ```
 
@@ -112,15 +140,24 @@ docker compose down
 |-- .env                  # credenziali locali (non versionato)
 |-- .env.example          # modello variabili senza segreti
 |-- .gitignore
-|-- app.py                # entrypoint del servizio
+|-- app.py                # app FastAPI + collector keep-alive
 |-- docker-compose.yml
 |-- Dockerfile
 |-- prd.md                # product requirements document
 |-- progress.md           # piano e stato di sviluppo
 |-- README.md
+|-- tests/
 `-- requirements.txt
 ```
 
+## Test
+
+Esecuzione test:
+
+```bash
+pytest -q
+```
+
 ## Note operative
 
 - Non committare mai il file `.env` con credenziali reali.