Cloudflare Workers

A cosa serve

Cloudflare Workers esegue i due componenti distribuiti di Architecture Coffee: un API Worker con logica runtime e un Frontend Worker che serve asset statici.

Componenti che lo usano

API, route pubbliche JSON, feedback e Admin API;
consumatori Queue per generazione Issue e Campaign Draft;
Frontend Next.js esportato come asset-only;
diagnostica /health, /version e /db/health.

Dati e artefatti scambiati

L'API riceve richieste HTTP, assertion Access, comandi Queue e risposte provider; legge e scrive D1 e restituisce proiezioni JSON/HTML limitate. Il Frontend riceve l'output statico out/ e restituisce HTML, asset, sitemap, robots e 404.

Autenticazione e autorizzazione

Workers non autentica autonomamente l'utente: l'API verifica l'assertion di Cloudflare Access e poi applica i permessi server-owned. Il Frontend non riceve segreti di autenticazione; la shell Admin usa la sessione Access verso l'API.

Cosa possiede il provider

Cloudflare possiede l'infrastruttura di esecuzione, versioni/deployment Worker, binding runtime, custom domain e telemetria del servizio.

Cosa possiede Architecture Coffee

Il repository possiede codice, configurazioni wrangler.jsonc, route, separazione API/Frontend, policy applicativa e contratti di build/smoke. D1 possiede lo stato runtime; Workers lo esegue ma non diventa autorità editoriale.

Operazioni automatiche, manuali e protette

Build e dry-run sono automatici in CI e non mutano Cloudflare. Deployment, version upload, activation e rollback sono manuali/protetti e richiedono Issue operativo e go/no-go. API, Frontend e D1 restano operazioni distinte.

Fallimenti e comportamento fail-closed

Configurazione assente, binding errato, route ambigua o risposta provider incerta bloccano l'operazione. Il Frontend deve restare binding-free; l'API mantiene Admin fallito chiuso se Access o autorizzazione non sono autorevoli.

Verifiche operative

dry-run API e Frontend indipendenti;
ispezione del pacchetto statico e dei binding;
health, version e D1 health;
route ownership, custom domain, Access e CORS;
smoke GET-only e rollback del solo componente.