diff --git a/prd.md b/prd.md index 5cad75e..e545c09 100644 --- a/prd.md +++ b/prd.md @@ -11,7 +11,8 @@ La soluzione prevista e' un processo long-running eseguito in un container Docke - esegue periodicamente una query leggera di keep-alive; - registra esito e tempi di esecuzione; - salva i campioni di latenza/esito in un database RRD locale con finestra storica di 48 ore; -- espone una webapp con vista storica in stile SmokePing; +- espone una webapp con vista storica in stile SmokePing tramite backend FastAPI servito da Uvicorn; +- espone API HTTP documentate automaticamente con Swagger/OpenAPI; - continua a funzionare finche' il container non viene fermato. ## 2. Problema @@ -72,6 +73,12 @@ La soluzione target per questo repository e': - webapp per visualizzazione dello storico con UI ispirata a SmokePing; - configurazione tramite file `.env` e `.env.example`. +Stack applicativo vincolata per la componente web: + +- FastAPI per endpoint API e documentazione OpenAPI; +- Uvicorn come server ASGI runtime; +- Swagger UI (endpoint `/docs`) e schema OpenAPI (endpoint `/openapi.json`). + 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 @@ -191,6 +198,7 @@ Capacita' minime richieste: - grafico temporale con evidenza di latenza e fallimenti; - aggiornamento periodico automatico della vista senza riavvio del servizio; - accesso via porta HTTP configurabile. +- implementazione obbligatoria con FastAPI + Uvicorn. ### RF14. API di lettura dello storico @@ -202,7 +210,18 @@ Vincoli: - filtri minimi per finestra temporale entro il limite delle 48 ore; - risposta con formato stabile e documentato per supportare eventuali evoluzioni UI. -### RF15. Continuita' operativa tra collector e UI +### RF15. Documentazione API via Swagger/OpenAPI + +Le API devono essere auto-documentate tramite le funzionalita' native FastAPI. + +Capacita' minime richieste: + +- endpoint Swagger UI disponibile in `/docs`; +- schema OpenAPI disponibile in `/openapi.json`; +- descrizione chiara di parametri, risposta e codici errore degli endpoint principali; +- coerenza tra comportamento effettivo e documentazione generata. + +### RF16. Continuita' operativa tra collector e UI Il collector di ping e la webapp devono convivere nello stesso servizio/container senza bloccare il loop di keep-alive. @@ -240,6 +259,10 @@ Lo storage storico deve restare bounded: il database RRD deve mantenere esclusiv La webapp deve essere leggibile su desktop e mobile, con tempi di caricamento adeguati all'uso operativo (target iniziale: visualizzazione disponibile in pochi secondi su rete locale). +### RNF8. Contratto API documentato + +La documentazione OpenAPI/Swagger deve essere sempre disponibile in ambiente runtime V1.1+ e deve riflettere fedelmente gli endpoint esposti. + ## 12. Configurazione di Prodotto ### Variabili richieste @@ -281,7 +304,8 @@ Componenti logici previsti: - database client: apre connessione ed esegue la query; - collector metriche: misura latenza/esito e normalizza i campioni; - storage RRD: persiste i campioni con retention circolare 48 ore; -- API storico: espone i dati aggregati alla webapp in sola lettura; +- API storico FastAPI: espone i dati aggregati alla webapp in sola lettura; +- server Uvicorn: esegue l'app ASGI e pubblica endpoint API e docs Swagger; - web frontend: renderizza vista storica in stile SmokePing; - logger: stampa esiti ed errori su STDOUT/STDERR; - runtime Docker: mantiene il processo eseguito come container persistente. @@ -381,7 +405,13 @@ Componenti logici previsti: - Esiste una webapp accessibile via HTTP che mostra andamento temporale di latenza ed errori. - La dashboard si aggiorna automaticamente e riflette i nuovi campioni senza riavvio. -### AC9. Degrado controllato +### AC9. API e Swagger operativi + +- Gli endpoint API principali sono serviti da FastAPI tramite Uvicorn. +- L'endpoint `/docs` e' accessibile e mostra la documentazione Swagger UI. +- L'endpoint `/openapi.json` e' accessibile e coerente con le API realmente disponibili. + +### AC10. Degrado controllato - Se il modulo UI fallisce temporaneamente, il collector continua a registrare campioni su RRD. - Se una misura fallisce, la dashboard mantiene lo storico precedente e rende visibile il fallimento del nuovo campione. @@ -400,6 +430,12 @@ Componenti logici previsti: ### V1.1 +- Implementazione backend web con FastAPI servito da Uvicorn. +- API read-only per storico RRD. +- Documentazione API Swagger/OpenAPI esposta in runtime. + +### V1.1 + - Retry con backoff configurabile. - Miglioramento dei messaggi di health e startup. - Distinzione chiara tra errori di configurazione e di rete. diff --git a/progress.md b/progress.md index 4bf19c7..3e8473a 100644 --- a/progress.md +++ b/progress.md @@ -13,6 +13,12 @@ Il progetto ha oggi: - `.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. @@ -230,6 +236,40 @@ 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: + +- **pianificata** + ## Backlog Post-V1 - retry con backoff configurabile; @@ -239,6 +279,12 @@ Stato: - 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 @@ -248,6 +294,7 @@ Stato: 5. Fase 4 6. Fase 5 7. Fase 6 +8. Fase 7 ## Definizione di Done per la V1 @@ -263,6 +310,6 @@ La V1 e' completata quando: ## Prossima Attivita' Operativa -Fasi 0-6 completate. V1 chiusa con test operativo end-to-end su pooler Supabase IPv4. +Fasi 0-6 completate. Prossimo step: avvio Fase 7 per implementazione FastAPI + Uvicorn + API + Swagger della dashboard storico. Nota operativa: usare host pooler (`aws-1-eu-central-1.pooler.supabase.com`) su porta `6543` con utente `postgres.` per ambienti senza connettivita' IPv6.