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.

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

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

Fasi 0-6 completate. V1 chiusa con test operativo end-to-end su pooler Supabase IPv4.

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.