supabase-pinger/progress.md

# Progress

## Stato Attuale

Data riferimento: 2026-04-24

Il progetto ha oggi:

- README, PRD e progress.md committati su remote;
- `.gitignore` con esclusione di `.env` e `connessione.md`;
- `app.py` — entrypoint Python con config loader, database client, loop resiliente e shutdown ordinato;
- `requirements.txt` con dipendenze minime (`psycopg2-binary`, `python-dotenv`);
- `.env.example` completo;
- `Dockerfile` e `docker-compose.yml`.

Aggiornamento scope post-V1:

- webapp storico connessione in stile SmokePing da implementare con FastAPI + Uvicorn;
- API read-only dedicate allo storico;
- documentazione API via Swagger/OpenAPI.

## Obiettivo di Sviluppo

Realizzare un servizio Python dockerizzato che mantenga attivo un database Supabase free tier tramite query periodiche di keep-alive, con configurazione via `.env`, processo long-running e documentazione operativa essenziale.

## Principi di Esecuzione

- tenere il perimetro minimale e focalizzato;
- evitare dipendenze inutili;
- non esporre segreti nel repository;
- validare ogni fase con una verifica eseguibile;
- rilasciare una V1 utilizzabile prima di aggiungere feature opzionali.

## Roadmap di Sviluppo

### Fase 0. Messa in sicurezza del repository

Obiettivo:
Ridurre subito il rischio di esposizione credenziali e allineare il repository a una baseline di sicurezza minima.

Attivita':

- verificare quali file contengono credenziali o connection string reali;
- rimuovere i segreti dal contenuto versionato e sostituirli con placeholder;
- assicurare che `.env` sia ignorato da git;
- mantenere `.env.example` come unico riferimento versionabile;
- rivedere la documentazione per evitare esempi che inducano a committare segreti.

Deliverable:

- repository senza credenziali reali in chiaro;
- `.gitignore` corretto;
- linee guida documentate per la gestione dei segreti.

Verifica:

- ricerca testuale nel repository per individuare host, password, key e DSN;
- conferma che `.env` non sia tracciato;
- review manuale dei file documentali.

Stato:

- **completata** — `connessione.md` non tracciato, `.env` escluso da `.gitignore`, nessuna credenziale in chiaro nel repository.

### Fase 1. Bootstrap del progetto Python

Obiettivo:
Creare la struttura minima eseguibile del servizio.

Attivita':

- creare `app.py` o entrypoint equivalente;
- definire `requirements.txt` con dipendenze minime;
- scegliere libreria di connessione PostgreSQL adatta al caso d'uso;
- predisporre struttura semplice senza over-engineering;
- definire convenzioni di logging e gestione errori.

Deliverable:

- scheletro applicativo Python avviabile;
- dipendenze dichiarate;
- entrypoint unico chiaro.

Verifica:

- avvio locale del processo Python;
- import delle dipendenze senza errori;
- controllo sintattico del file principale.

Stato:

- **completata** — `app.py` con logging strutturato, `requirements.txt` con `psycopg2-binary` e `python-dotenv`, sintassi verificata.

### Fase 2. Configurazione e validazione environment

Obiettivo:
Caricare e validare in modo affidabile tutte le variabili richieste dal PRD.

Attivita':

- implementare lettura delle env dal runtime;
- validare presenza di host, porta, database, user, password, query e intervallo;
- gestire messaggi di errore chiari per configurazioni incomplete;
- creare `.env.example` coerente con README e PRD;
- definire default prudenti solo dove sensato.

Deliverable:

- loader di configurazione affidabile;
- `.env.example` pronto all'uso;
- error handling per startup configuration.

Verifica:

- avvio con configurazione completa;
- fallimento atteso con env mancanti;
- coerenza tra `.env.example`, README e PRD.

Stato:

- **completata** — `load_config()` in `app.py` valida tutte le variabili obbligatorie con messaggi di errore espliciti e uscita controllata; `.env.example` coerente con PRD e README.

### Fase 3. Connessione a Supabase/PostgreSQL

Obiettivo:
Stabilire la connessione al database e isolare il layer di accesso.

Attivita':

- implementare apertura connessione al database;
- eseguire una query di test controllata;
- gestire timeout, eccezioni e chiusura connessione;
- evitare logging di segreti o DSN completi;
- preparare una funzione dedicata al keep-alive.

Deliverable:

- client database funzionante;
- funzione di ping riusabile;
- logging tecnico minimo ma utile.

Verifica:

- esecuzione riuscita di `SELECT 1;`;
- simulazione di errore credenziali o host non raggiungibile;
- log chiari e privi di segreti.

Stato:

- **completata** — funzione `ping()` in `app.py` con connect_timeout, gestione `OperationalError` e `Error`, chiusura connessione in `finally`, nessun segreto nei log.

### Fase 4. Loop di keep-alive e resilienza runtime

Obiettivo:
Trasformare il ping singolo in un servizio continuo e resiliente.

Attivita':

- implementare loop infinito controllato;
- usare `PING_INTERVAL_MINUTES` come scheduling applicativo;
- loggare avvio ciclo, esito e prossima esecuzione;
- mantenere il processo attivo anche in caso di errore operativo;
- gestire terminazione ordinata su stop del container.

Deliverable:

- runtime long-running stabile;
- gestione errori non distruttiva;
- shutdown ordinato.

Verifica:

- il processo resta attivo dopo un ping riuscito;
- il processo resta attivo dopo un ping fallito;
- stop manuale con chiusura ordinata.

Stato:

- **completata** — `run()` in `app.py` con loop `while not _shutdown`, sleep a blocchi da 10s per risposta rapida a SIGTERM/SIGINT, handler segnali registrati, log di next-run ad ogni ciclo.

### Fase 5. Containerizzazione Docker

Obiettivo:
Rendere il servizio distribuibile e persistente tramite Docker.

Attivita':

- scrivere `Dockerfile` minimale;
- configurare comando di avvio del processo Python;
- verificare passaggio variabili con `--env-file .env`;
- definire uso raccomandato di `--restart unless-stopped`;
- aggiungere eventuale supporto `docker compose`.

Deliverable:

- immagine Docker buildabile;
- esecuzione container funzionante;
- esempio compose essenziale.

Verifica:

- `docker build` completato con successo;
- container avviato e logs leggibili;
- persistenza del processo finche' non viene fermato.

Stato:

- **completata** — `Dockerfile` con python:3.12-slim, flag `-u` per output non bufferizzato, `docker-compose.yml` con `restart: unless-stopped`.

### Fase 6. Documentazione operativa e rifinitura V1

Obiettivo:
Concludere la prima versione con documentazione e uso coerente.

Attivita':

- allineare README, PRD, `.env.example` e struttura reale del repository;
- documentare build, run, stop e troubleshooting base;
- rimuovere ambiguita' su intervallo di ping raccomandato;
- chiarire i limiti del tool rispetto ai termini del free tier;
- aggiungere checklist rapida di avvio.

Deliverable:

- documentazione finale coerente con il codice;
- repository pronto per primo utilizzo;
- baseline V1 chiusa.

Verifica:

- review incrociata documentazione vs file reali;
- onboarding test: un utente tecnico deve riuscire ad avviare il servizio dai documenti;
- lint markdown senza errori.

Stato:

- completata

### Fase 7. Webapp storico con FastAPI, Uvicorn e Swagger

Obiettivo:
Implementare la componente web/API per visualizzare lo storico connessione (48 ore) in stile SmokePing, usando stack FastAPI + Uvicorn con documentazione Swagger/OpenAPI.

Attivita':

- integrare dipendenze FastAPI/Uvicorn nel progetto Python;
- progettare endpoint API read-only per stato corrente e storico RRD 48h;
- implementare backend FastAPI con validazione input e codici errore chiari;
- esporre documentazione automatica Swagger (`/docs`) e schema OpenAPI (`/openapi.json`);
- collegare la webapp allo strato API per rendering trend e fallimenti;
- aggiornare Dockerfile e compose per runtime Uvicorn e porta HTTP configurabile;
- allineare README, PRD, `.env.example` e note operative.

Deliverable:

- app FastAPI avviabile con Uvicorn;
- endpoint API storico funzionanti;
- Swagger UI e OpenAPI accessibili;
- dashboard storica collegata ai dati RRD.

Verifica:

- avvio container e raggiungibilita' endpoint API;
- verifica endpoint `/docs` e `/openapi.json`;
- chiamata API con finestra temporale valida e risposta coerente;
- riscontro visuale dashboard con nuovi campioni;
- controllo che il collector keep-alive continui anche in caso di errore UI.

Stato:

- **completata** — implementata app FastAPI con runtime Uvicorn, endpoint `/api/status` e `/api/history`, dashboard web in `/`, documentazione Swagger/OpenAPI in `/docs` e `/openapi.json`, storage storico RRD-like con retention 48h e test automatici `pytest` verdi (3 passed).

## Backlog Post-V1

- retry con backoff configurabile;
- healthcheck Docker dedicato;
- endpoint o comando di self-test;
- notifiche opzionali via webhook o Telegram;
- metriche esportabili;
- supporto a query alternativa di keep-alive con tabella di log.

## Backlog Post-V1.1

- autenticazione opzionale per endpoint dashboard/API;
- downsampling avanzato per viste storiche aggiuntive oltre 48h;
- export CSV/JSON dello storico per analisi esterne.

## Ordine di Esecuzione Consigliato

1. Fase 0
2. Fase 1
3. Fase 2
4. Fase 3
5. Fase 4
6. Fase 5
7. Fase 6
8. Fase 7

## Definizione di Done per la V1

La V1 e' completata quando:

- il repository non contiene segreti reali;
- esiste `.env.example` completo;
- il servizio Python si avvia con configurazione valida;
- il servizio esegue la query di keep-alive verso Supabase;
- il processo resta attivo nel tempo;
- il container Docker funziona con `--env-file .env` e `--restart unless-stopped`;
- la documentazione corrisponde ai file realmente presenti nel repository.

## Prossima Attivita' Operativa

Fasi 0-7 completate. V1.1 consegnata con FastAPI/Uvicorn, API read-only, Swagger/OpenAPI, dashboard storico e test automatici.

Nota operativa: usare host pooler (`aws-1-eu-central-1.pooler.supabase.com`) su porta `6543` con utente `postgres.<project-ref>` per ambienti senza connettivita' IPv6.