Green-Scale: backend event-driven con Go e SQS

Green-Scale Event Ledger è un progetto dimostrativo che esplora la costruzione progressiva di un backend event-driven. Collega un gateway HTTP scritto in Go a una coda SQS locale, un worker TypeScript per la validazione degli eventi e una prima persistenza PostgreSQL.

Il progetto viene eseguito in locale: Docker Compose avvia LocalStack, PostgreSQL con pgvector e Redis. Non è un prodotto commerciale né un servizio ospitato e non richiede un account AWS.

Il problema affrontato

Nei sistemi asincroni, accettare una richiesta non significa aver completato l’elaborazione. Il progetto nasce per rendere osservabili e verificabili alcuni passaggi spesso nascosti dietro un’unica API:

ricezione e controllo iniziale della richiesta HTTP;
invio del messaggio a una coda;
lettura e validazione runtime del contratto;
gestione delle riconsegne e persistenza idempotente;
separazione tra errori temporanei, eventi non validi e conflitti applicativi.

Architettura attuale

Client HTTP → gateway Go → SQS locale → worker TypeScript → validazione Zod

TypeScript → PostgreSQL

Il gateway risponde con 202 Accepted soltanto dopo la conferma della coda. Questa risposta indica che il messaggio è stato accettato da SQS, non che sia già stato validato o salvato.

Componenti disponibili

Gateway Go: espone POST /events, controlla formato JSON, dimensione e content type, quindi invia il corpo a SQS.
Infrastruttura locale: Docker Compose configura LocalStack, coda principale, dead-letter queue, PostgreSQL e Redis.
Contratto TypeScript: Zod valida UUID, timestamp UTC, tipo evento, sorgente, metadati e payload.
Consumatore SQS: esegue long polling, parsing JSON e validazione del messaggio ricevuto.
Persistenza iniziale: PostgreSQL conserva l’evento completo in JSONB; il repository distingue inserimento, riconsegna identica e conflitto sullo stesso identificativo.

Scelte tecniche

Responsabilità separate

Il gateway applica soltanto controlli di trasporto. La validazione del contratto appartiene al worker: in questo modo l’accettazione HTTP resta distinta dall’elaborazione applicativa.

Idempotenza esplicita

eventId è la chiave primaria. Una riconsegna con lo stesso ID e lo stesso contenuto viene riconosciuta; lo stesso ID associato a dati diversi produce un conflitto senza sovrascrivere l’evento originale.

Infrastruttura riproducibile

LocalStack permette di sperimentare SQS senza utilizzare risorse cloud reali. Le credenziali presenti negli esempi sono fittizie e limitate all’ambiente locale.

Verifiche documentate

Il repository descrive le prove già completate e i relativi comandi. Tra queste:

test e race detector del gateway Go;
invio HTTP reale verso la coda LocalStack;
rifiuto di JSON malformato e gestione di un endpoint SQS non raggiungibile;
controllo statico e build TypeScript;
ricezione di eventi validi e non conformi;
connessione a PostgreSQL e salvataggio idempotente sequenziale;
rifiuto di un conflitto senza modifica del contenuto originale.

Queste evidenze provengono dalla documentazione pubblica del progetto. Il repository non è stato installato o eseguito sul server di produzione di matcode.dev.

Limiti attuali

La pagina distingue intenzionalmente ciò che funziona da ciò che è ancora da sviluppare:

il consumo SQS non è ancora collegato al salvataggio PostgreSQL;
i messaggi validi non vengono ancora cancellati dalla coda;
il percorso completo verso la dead-letter queue deve essere verificato;
Redis e ricerca vettoriale non sono ancora usati dal codice applicativo;
mancano test automatici del worker, benchmark e pipeline CI;
non sono ancora state provate riconsegne concorrenti.

Come esaminare il progetto

Il README contiene prerequisiti, comandi Docker Compose, avvio del gateway, esempi HTTP, build del worker e controlli PostgreSQL. Alcuni passaggi modificano il database locale: vanno eseguiti esclusivamente nell’ambiente di sviluppo descritto dal repository.

Che cosa dimostra

Green-Scale documenta un percorso di apprendimento applicato: progettazione di API, messaggistica asincrona, contratti runtime, idempotenza e distinzione tra componenti verificati e lavoro futuro. Il valore del progetto non è una demo “finita”, ma la tracciabilità delle decisioni e dei limiti.

Consulta il repository su GitHub oppure torna alla raccolta dei progetti recenti. Se il tuo team lavora su backend, API o integrazioni asincrone, puoi contattarmi.