supabase-pinger/progress.md

# Progress

## Stato Attuale

Data riferimento: 2026-04-24

Il progetto ha oggi:

- un README iniziale con obiettivo e modalita' d'uso target;
- un PRD esteso con requisiti funzionali e non funzionali;
- note di connessione tecniche da trattare con cautela;
- nessuna implementazione applicativa ancora presente.

## 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:

- da fare

### 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:

- da fare

### 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:

- da fare

### 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:

- da fare

### 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:

- da fare

### 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:

- da fare

### 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:

- da fare

## 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.

## 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

## 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

Task raccomandato immediato:

- eseguire la Fase 0 e poi creare lo scheletro minimo della V1 con `app.py`, `requirements.txt`, `.env.example` e `Dockerfile`.