supabase-pinger/prd.md

# PRD: Supabase Auto-Shutdown Prevention System

## 1. Executive Summary

Questo progetto definisce un servizio Python dockerizzato con il solo scopo di mantenere attivo un database Supabase in free tier, prevenendo la sospensione automatica dovuta a lunghi periodi di inattivita'.

La soluzione prevista e' un processo long-running eseguito in un container Docker che:

- carica la configurazione da file `.env`;
- si connette al database Supabase/PostgreSQL;
- esegue periodicamente una query leggera di keep-alive;
- registra esito e tempi di esecuzione;
- continua a funzionare finche' il container non viene fermato.

## 2. Problema

Nel piano gratuito di Supabase, un progetto puo' essere sospeso o parcheggiato dopo un periodo prolungato di inattivita'. Quando questo avviene:

- il database puo' diventare temporaneamente non raggiungibile;
- l'applicazione che lo usa puo' apparire guasta o lenta al primo accesso;
- l'esperienza di sviluppo, demo o staging peggiora sensibilmente.

Il problema da risolvere non e' l'alta disponibilita' in senso enterprise, ma la continuita' operativa minima per ambienti personali, prototipi, demo e staging leggeri.

## 3. Obiettivo di Prodotto

Garantire che Supabase rilevi attivita' reale sul database almeno una volta entro ogni finestra di 7 giorni, con un margine di sicurezza sufficiente a evitare la sospensione automatica nella pratica.

## 4. Obiettivi Specifici

- Eseguire automaticamente attivita' valida sul database senza intervento umano.
- Mantenere il processo attivo in modo continuativo tramite container Docker.
- Consentire configurazione interamente tramite `.env`.
- Rendere il comportamento osservabile con log chiari di successo e fallimento.
- Mantenere la soluzione minimale, portabile e facile da eseguire su qualsiasi host con Docker.

## 5. Non-Obiettivi

- Non e' un sistema di backup, replica o disaster recovery.
- Non e' un sistema di monitoraggio completo del database.
- Non deve gestire provisioning, creazione schema o migrazioni Supabase.
- Non deve introdurre traffico aggressivo o pattern assimilabili ad abuso del free tier.
- Non deve dipendere obbligatoriamente da GitHub Actions, servizi cron esterni o infrastrutture cloud aggiuntive.

## 6. Pubblico di Riferimento

- Sviluppatori individuali che usano Supabase free tier per prototipi.
- Team piccoli che usano Supabase come ambiente di staging leggero.
- Progetti personali o dimostrativi che devono restare pronti all'uso senza accessi frequenti.

## 7. User Stories

- Come sviluppatore, voglio che il mio database Supabase resti raggiungibile anche se non uso l'app per giorni.
- Come maintainer, voglio configurare il servizio con un semplice file `.env` senza modificare il codice.
- Come operatore, voglio eseguire il servizio in Docker e lasciarlo attivo finche' non decido di fermarlo.
- Come utente tecnico, voglio vedere nei log se il keep-alive sta funzionando oppure no.

## 8. Scope della Soluzione

La soluzione target per questo repository e':

- applicazione Python;
- esecuzione in container Docker;
- loop applicativo continuo;
- connessione diretta a PostgreSQL/Supabase;
- query di keep-alive configurabile;
- configurazione tramite file `.env` e `.env.example`.

Alternative come GitHub Actions, `pg_cron` o cron esterni restano opzioni comparabili, ma non rappresentano la soluzione primaria di questo repository.

## 9. Assunzioni di Prodotto

- Supabase considera una query SQL valida come attivita' sufficiente a evitare la sospensione per inattivita'.
- Un'attivita' 2 o 3 volte a settimana offre margine adeguato rispetto alla finestra di 7 giorni.
- L'host che esegue Docker resta normalmente acceso o comunque ripristina il container tramite restart policy.
- L'utente dispone delle credenziali di accesso al database Supabase.

## 10. Requisiti Funzionali

### RF1. Caricamento configurazione da `.env`

Il sistema deve caricare tutti i parametri necessari da file `.env`.

Parametri minimi richiesti:

- `SUPABASE_DB_HOST`
- `SUPABASE_DB_PORT`
- `SUPABASE_DB_NAME`
- `SUPABASE_DB_USER`
- `SUPABASE_DB_PASSWORD`
- `PING_INTERVAL_MINUTES`
- `PING_QUERY`
- `TZ`

### RF2. Presenza di `.env.example`

Il repository deve includere un file `.env.example` che documenti tutte le variabili necessarie senza contenere segreti reali.

### RF3. Connessione al database Supabase

Il sistema deve aprire una connessione verso il database PostgreSQL di Supabase usando le credenziali fornite.

### RF4. Esecuzione di attivita' reale

Il sistema deve eseguire un'operazione SQL reale che venga contabilizzata come attivita' dal database.

Comportamento previsto:

- default consigliato: query leggera come `SELECT 1;`;
- opzione futura: query custom o update su tabella tecnica di log;
- l'operazione deve essere configurabile tramite environment variable.

### RF5. Esecuzione periodica automatizzata

Il processo deve essere automatico e ciclico, senza intervento umano manuale dopo l'avvio del container.

Vincoli di frequenza:

- il sistema deve supportare un intervallo configurabile;
- l'intervallo operativo raccomandato deve garantire almeno 2 esecuzioni a settimana;
- il default di prodotto consigliato e' tra 72 e 96 ore;
- non devono essere usati intervalli inutilmente aggressivi come default.

### RF6. Processo long-running

Il processo Python non deve terminare dopo un singolo ping riuscito o fallito. Deve restare attivo e continuare a schedulare i cicli successivi finche' il container non viene fermato.

### RF7. Logging di esecuzione

Il sistema deve emettere log almeno per:

- avvio del servizio;
- lettura configurazione valida;
- tentativo di connessione;
- esecuzione query;
- successo dell'operazione;
- errore dell'operazione;
- attesa del prossimo ciclo.

### RF8. Gestione errori resiliente

In caso di fallimento di connessione o query, il processo non deve terminare immediatamente. Deve:

- loggare l'errore;
- chiudere in sicurezza eventuali risorse aperte;
- attendere il prossimo intervallo o un retry definito;
- riprovare automaticamente.

### RF9. Arresto controllato

Il processo deve supportare lo stop del container in modo ordinato, chiudendo connessioni e terminando il loop senza lasciare risorse sporche.

### RF10. Modalita' di esecuzione containerizzata

Il sistema deve essere eseguibile tramite Docker con restart policy adatta a mantenerlo operativo finche' non viene fermato esplicitamente.

Policy target:

- `unless-stopped` come impostazione raccomandata.

### RF11. Notifica di errore opzionale

La notifica all'utente in caso di fallimento e' opzionale in prima versione.

Per la V1, il requisito minimo e' il logging locale/STDOUT. In versioni successive, potranno essere introdotte integrazioni opzionali come email, webhook o Telegram.

## 11. Requisiti Non Funzionali

### RNF1. Semplicita'

La soluzione deve restare piccola, leggibile e con poche dipendenze.

### RNF2. Portabilita'

Il servizio deve poter girare su qualsiasi ambiente che supporti Docker: VPS, mini PC, NAS, server domestico o macchina di sviluppo.

### RNF3. Sicurezza

- Nessun segreto hardcoded nel codice.
- Nessun segreto committato nel repository.
- Tutti i segreti devono essere passati tramite `.env` o strumenti equivalenti.

### RNF4. Osservabilita' minima

I log devono essere sufficienti a diagnosticare se il job di keep-alive ha funzionato senza richiedere debugging interattivo.

### RNF5. Basso impatto

Il sistema deve usare query leggere e frequenza moderata per minimizzare costo computazionale e rischio di comportamento eccessivo verso il free tier.

## 12. Configurazione di Prodotto

### Variabili richieste

```env
SUPABASE_DB_HOST=
SUPABASE_DB_PORT=5432
SUPABASE_DB_NAME=
SUPABASE_DB_USER=
SUPABASE_DB_PASSWORD=
PING_INTERVAL_MINUTES=4320
PING_QUERY=SELECT 1;
TZ=Europe/Rome
```

### Note sulla configurazione

- `PING_INTERVAL_MINUTES=4320` equivale a 72 ore.
- Il valore effettivo puo' essere modificato, ma il default raccomandato deve restare prudente rispetto ai termini d'uso e al limite dei 7 giorni.
- Il file `.env.example` deve contenere le stesse chiavi, ma senza valori sensibili.

## 13. Flusso Operativo Atteso

1. L'utente crea il file `.env` partendo da `.env.example`.
2. L'utente avvia il container con `--env-file .env`.
3. Il processo Python parte e valida la configurazione.
4. Il servizio apre una connessione al database Supabase.
5. Il servizio esegue la query di keep-alive.
6. Il servizio registra esito e timestamp.
7. Il servizio attende fino al ciclo successivo.
8. Il loop continua finche' il container non viene fermato.

## 14. Architettura Logica

Componenti logici previsti:

- loader configurazione: valida e carica le variabili ambiente;
- scheduler loop: gestisce l'attesa fra i cicli;
- database client: apre connessione ed esegue la query;
- logger: stampa esiti ed errori su STDOUT/STDERR;
- runtime Docker: mantiene il processo eseguito come container persistente.

## 15. Soluzioni Tecniche Valutate

| Soluzione | Descrizione | Pro | Contro | Esito |
| --- | --- | --- | --- | --- |
| Python + Docker long-running | Processo residente che esegue query periodiche via connessione DB diretta. | Indipendente da servizi terzi, semplice da portare ovunque, coerente con il repository. | Richiede un host sempre acceso. | Scelta primaria |
| GitHub Actions | Workflow schedulato con chiamata HTTP o query indiretta. | Facile da configurare, economico. | Dipende da GitHub e da scheduling esterno. | Alternativa |
| pg_cron | Job schedulati internamente al database. | Soluzione interna a Postgres. | Affidabilita' e disponibilita' non sempre ideali su free tier. | Non primaria |
| External Cron | Servizi terzi che attivano un endpoint o una function. | Molto affidabile. | Dipendenza esterna aggiuntiva. | Alternativa |

## 16. Vincoli e Rischi

### Vincoli

- Uso del piano gratuito Supabase.
- Necessita' di rispettare termini e limiti del servizio.
- Presenza di un host Docker sempre disponibile o quasi sempre disponibile.

### Rischi

- Una frequenza troppo alta potrebbe essere interpretata come utilizzo artificiale o eccessivo.
- Una frequenza troppo bassa potrebbe non prevenire il parking.
- Credenziali esposte in repository o log rappresentano rischio di sicurezza.
- Cambiamenti futuri nelle policy Supabase potrebbero ridurre l'efficacia della soluzione.

### Mitigazioni

- Default conservativo a poche esecuzioni settimanali.
- Query molto leggere.
- Segreti solo in `.env`.
- Logging senza stampa delle credenziali.

## 17. Requisiti di Sicurezza

- Il sistema non deve stampare password o DSN completi nei log.
- Il file `.env` deve essere escluso dal versionamento.
- Il file `.env.example` deve essere versionato come riferimento.
- Eventuali errori devono essere sanitizzati per evitare leak accidentali di segreti.

## 18. Requisiti di Deployment

- Il progetto deve essere buildabile tramite `docker build`.
- Il progetto deve poter essere eseguito con `docker run --env-file .env`.
- Deve essere compatibile anche con `docker compose`.
- La restart policy raccomandata deve essere `unless-stopped`.

## 19. Metriche di Successo

- Il database Supabase non entra in stato paused durante normali periodi di mancato utilizzo dell'applicazione.
- Ogni esecuzione pianificata produce un log di successo oppure un log di errore esplicito.
- Il container resta in esecuzione senza terminare dopo il primo ciclo.
- La configurazione puo' essere modificata senza cambiare il codice applicativo.

## 20. Acceptance Criteria

### AC1. Configurazione

- Esiste un file `.env.example` completo con tutte le variabili richieste.
- Il servizio fallisce in modo chiaro se manca una variabile obbligatoria.

### AC2. Keep-alive riuscito

- A container avviato, il servizio esegue con successo almeno una query di keep-alive verso Supabase.
- I log mostrano chiaramente l'avvenuta esecuzione con timestamp.

### AC3. Continuita' del processo

- Dopo una query riuscita, il processo non termina.
- Il container rimane in stato attivo fino a stop manuale o errore esterno del runtime.

### AC4. Tolleranza ai fallimenti

- Se una query fallisce, il processo logga l'errore e continua a riprovare nei cicli successivi.

### AC5. Sicurezza di configurazione

- Nessuna credenziale reale compare nel repository tracciato.
- Le istruzioni d'uso spiegano chiaramente la differenza tra `.env` e `.env.example`.

### AC6. Coerenza con il free tier

- Il sistema consente una schedulazione moderata, raccomandata su 2-3 esecuzioni a settimana.

## 21. Roadmap Evolutiva

### V1

- Connessione diretta al database.
- Query di keep-alive configurabile.
- Loop continuo.
- Logging base.
- Container Docker con restart policy consigliata.

### V1.1

- Retry con backoff configurabile.
- Miglioramento dei messaggi di health e startup.
- Distinzione chiara tra errori di configurazione e di rete.

### V2

- Notifiche opzionali su webhook o email.
- Healthcheck Docker dedicato.
- Modalita' dry-run o startup check.
- Supporto a metriche esportabili.

## 22. Decisione di Prodotto

La soluzione da implementare in questo repository e' un servizio Python sempre attivo, eseguito in Docker, configurato via `.env`, con query di keep-alive leggera e frequenza moderata. Questa scelta massimizza semplicita', portabilita' e controllo operativo, riducendo dipendenze esterne rispetto alle alternative basate su scheduler di terze parti.