Il livello web su Cloudflare Workers

Il progetto è nella sezione 6 di docs/architecture/23-ops.md. Workers esegue un livello web ridotto. La parità di funzionalità su Workers è fuori ambito (sezione 12 del PRD): ciò che questo target non può fare viene rifiutato all’avvio, per nome.

Stato in questa release

La configurazione è pronta (apps/web/wrangler.jsonc, il preset Nitro cloudflare-module, il bridge Hyperdrive e i controlli di avvio). Un Worker richiede storage compatibile S3 per R2 (QUIRE_STORAGE_DRIVER=s3), un driver realtime tra richieste (QUIRE_REALTIME_DRIVER=durable_objects oppure centrifugo), una cache condivisa (QUIRE_CACHE_DRIVER=postgres oppure valkey) e un provider email HTTP. Senza di essi il Worker rifiuta di avviarsi e il suo registro nomina ciascuna impostazione. Il driver Durable Objects è un client del Worker realtime in apps/realtime-worker (un Durable Object per canale per fan-out, presenza e cronologia, uno per persona per le disconnessioni); distribuiscilo accanto, come sotto, oppure usa Centrifugo.

I componenti

Componente	Su Cloudflare
`web`	Un Worker con `nodejs_compat`
Postgres	Esterno, raggiunto tramite Hyperdrive: `HYPERDRIVE` per il ruolo applicativo, `REPORT_HYPERDRIVE` per il ruolo report sullo stesso database fisico. Il livello web copia ciascuna stringa di connessione in `DATABASE_URL` e `QUIRE_REPORT_DATABASE_URL` all’avvio
File	R2, tramite la sua API S3 (`S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com`); il binding `FILES` collega il bucket
Job in background	pg-boss su Hyperdrive quando il job deve essere accodato con una scrittura. Con `QUIRE_QUEUE_DRIVER=cloudflare` sul worker companion, i job leggeri (consegne non ordinate di notifiche e webhook) passano invece per Cloudflare Queues, così Postgres non viene interrogato per essi. Il worker companion esegue entrambi
Realtime	Il Worker realtime, `apps/realtime-worker`, con Durable Objects
`worker`, `scheduler`, `collab`, `content`, ClamAV, Gotenberg, ffmpeg	Un host companion per contenitori. Un Worker non può eseguirli
Tracciamento	Osservabilità di Workers, abilitata in `wrangler.jsonc`

REPORT_HYPERDRIVE fornisce il ruolo report per il database fisico nominato da HYPERDRIVE. Questo target non serve tenant fissati ad altri database fisici, come descritto sotto.

Cosa questo target non può fare

Rifiutato all’avvio, con ogni problema elencato in una volta sola:

Niente SMTP. Usa un provider HTTP in QUIRE_EMAIL_PROVIDER_CONFIG.
Niente disco locale. QUIRE_STORAGE_DRIVER deve nominare object storage.
Niente realtime o cache in-process. I Worker non condividono memoria tra richieste, quindi QUIRE_REALTIME_DRIVER=inprocess e QUIRE_CACHE_DRIVER=memory vengono rifiutati.
Niente ClamAV, Gotenberg o ffmpeg nel Worker. CLAMAV_URL, GOTENBERG_URL e FFMPEG_PATH impostati sul Worker vengono rifiutati; impostali invece sul worker companion.
Niente organizzazioni con database dedicato. I binding Hyperdrive di un Worker sono fissati al deploy, quindi un’organizzazione con un proprio database riceve una chiara pagina “non disponibile qui”. Servila da Compose o Vercel.

E una cosa non rifiutata ma da sapere: prerendering e rigenerazione statica incrementale non funzionano su Workers, qualunque cosa dica la documentazione del framework. Ogni rotta viene renderizzata per richiesta.

Su questo target mantieni brevi le transazioni e non trattenerne mai una durante una chiamata di rete: Hyperdrive azzera lo stato di sessione quando una connessione torna al pool, quindi il contesto tenant è impostato per transazione.

Distribuzione

Crea le risorse:

bun run --bun wrangler hyperdrive create quire-app --connection-string="postgres://quire_app:...@db.example.com:5432/quire"
bun run --bun wrangler hyperdrive create quire-report --connection-string="postgres://quire_report:...@db.example.com:5432/quire"
bun run --bun wrangler r2 bucket create quire-files
bun run --bun wrangler queues create quire-jobs

Metti i due id Hyperdrive in apps/web/wrangler.jsonc.

Imposta i segreti, uno alla volta con bun run --bun wrangler secret put <NAME> da apps/web: QUIRE_SECRET_KEY, QUIRE_MASTER_KEY, QUIRE_EMAIL_PROVIDER_CONFIG, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, QUIRE_COLLAB_SIGNING_KEY, QUIRE_REALTIME_WORKER_SECRET. Le impostazioni semplici (QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN, QUIRE_PLATFORM_DOMAINS, QUIRE_DATABASE_ID, S3_ENDPOINT, S3_BUCKET, QUIRE_COLLAB_URL) vanno in vars.

Compila e distribuisci da apps/web:

NITRO_PRESET=cloudflare-module bun run build
bun run --bun wrangler deploy

Distribuisci il Worker realtime, con il QUIRE_REALTIME_WORKER_SECRET del livello web e il suo segreto token come QUIRE_REALTIME_TOKEN_SECRET (il livello web firma i token realtime con il proprio QUIRE_REALTIME_TOKEN_SECRET, oppure con QUIRE_SECRET_KEY quando quello non è impostato, quindi usa quello che usa), e imposta QUIRE_REALTIME_WORKER_URL sul livello web al suo indirizzo:
```
cd apps/realtime-worker
bun run --bun wrangler secret put QUIRE_REALTIME_WORKER_SECRET
bun run --bun wrangler secret put QUIRE_REALTIME_TOKEN_SECRET
bun run --bun wrangler deploy
```

Per i job leggeri su Cloudflare Queues, crea una coda per coda leggera e imposta questi sul worker companion (un token API con lettura e scrittura Queues):

bun run --bun wrangler queues create quire-events-notifications
bun run --bun wrangler queues create quire-events-notifications-dead
bun run --bun wrangler queues create quire-events-webhooks
bun run --bun wrangler queues create quire-events-webhooks-dead

QUIRE_QUEUE_DRIVER=cloudflare, CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_QUEUES_TOKEN, e QUIRE_QUEUE_PREFIX se non quire-.

Esegui l’host companion come nella guida Vercel, passaggio 3. Le migrazioni girano lì, prima di ogni distribuzione del Worker.

Una configurazione rifiutata si mostra in bun run --bun wrangler tail come “The web tier did not start on cloudflare”, seguita da ciascuna impostazione da cambiare.