Runbook: server grafi etl serve (HTTP read-only)

Sintesi

• Cosa fa: processo daemon che espone via HTTP la topologia dei grafi delle pipeline (nodi/archi, PlanSpec). All'avvio calcola gli spec di tutte le pipeline del registro PIPELINES (via getSpec(), puro e deterministico) e li tiene in una cache in-memory immutabile; li serve poi read-only. Sostituisce la generazione a build-time del vecchio plans.generated.json lato UI (ADR-0024).
• Owner: team ETL.
• Consumatore: noeva-etl-ui via VITE_ETL_API_BASE_URL.
• Criticità: bassa. Se è fermo, la UI non popola il selettore pipeline né il grafo (mostra lo stato di errore), ma nessun dato viene perso: al riavvio la cache viene ricostruita dal registro. Nessuno stato persistente, nessun I/O verso DB.

Esecuzione normale

pnpm run etl:serve         # oppure: pnpm run etl serve

Nel container: node dist/cli.js serve (o l'equivalente entrypoint), con la porta esposta.

Endpoint

• GET /health → { "status": "ok" }
• GET /graphs → [{ "name": "...", "description": "..." }]
• GET /graphs/:name → PlanSpec ({ name, nodes, edges }), 404 { message } se il nome non esiste.

Configurazione (env)

• ETL_HTTP_PORT — porta di ascolto (default 3005, distinta da noeva-server-api = 3002).
• ETL_HTTP_CORS_ORIGIN — origine consentita da CORS (default *). In produzione impostare l'origine della UI.

Nessuna autenticazione: espone solo topologia + descriptor non sensibili (ADR-0020), già pubblici nel bundle della UI. La protezione in prod è la restrizione dell'origine.

Verifica rapida

curl -s localhost:3005/health
curl -s localhost:3005/graphs
curl -s localhost:3005/graphs/orders-enriched-daily

Diagnosi

• La UI non carica i grafi → verificare che il server sia su e raggiungibile (curl diretto isola server vs UI) e che VITE_ETL_API_BASE_URL punti alla porta giusta; in prod controllare ETL_HTTP_CORS_ORIGIN (un CORS troppo stretto blocca il browser ma non curl).
• 404 su un grafo atteso → il nome non è nel registro PIPELINES; confrontare con GET /graphs.

Deploy

Il server va deployato come servizio distinto dal worker (stesso codice/immagine, comando diverso), con la porta esposta. Aggiornare Dockerfile/docker-compose.yml/ deploy-ecr.sh di conseguenza (follow-up operativo tracciato in ADR-0024).