La capa web a Cloudflare Workers

El disseny es descriu a docs/architecture/23-ops.md, secció 6. Workers executa una capa web reduïda. La paritat funcional amb Workers no forma part dels objectius (PRD, secció 12): en iniciar-se, aquest entorn rebutja les funcions que no pot executar i n’indica el nom.

Estat d’aquesta versió

La configuració està preparada (apps/web/wrangler.jsonc, el preset Nitro cloudflare-module, el pont Hyperdrive i les comprovacions d’inici). Un Worker necessita emmagatzematge compatible amb S3 per a R2 (QUIRE_STORAGE_DRIVER=s3), un driver de temps real entre peticions (QUIRE_REALTIME_DRIVER=durable_objects o centrifugo), una memòria cau compartida (QUIRE_CACHE_DRIVER=postgres o valkey) i un proveïdor de correu electrònic HTTP. Si en falta algun, el Worker es nega a iniciar-se i el registre n’indica el nom. El driver Durable Objects és client del realtime Worker d’apps/realtime-worker (un Durable Object per canal per a la distribució, la presència i l’historial, i un per persona per a les desconnexions). Desplegueu-lo alhora, com s’indica més avall, o feu servir Centrifugo.

Components

Component	A Cloudflare
`web`	Un Worker amb `nodejs_compat`
Postgres	Extern, accessible mitjançant Hyperdrive: `HYPERDRIVE` per al rol d’aplicació i `REPORT_HYPERDRIVE` per al rol d’informes, a la mateixa base de dades física. En iniciar-se, la capa web copia cada cadena de connexió a `DATABASE_URL` i `QUIRE_REPORT_DATABASE_URL`
Fitxers	R2, mitjançant la seva API S3 (`S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com`); el binding `FILES` connecta el bucket
Tasques en segon pla	pg-boss a través d’Hyperdrive quan cal encuar la tasca amb una escriptura. Si s’estableix `QUIRE_QUEUE_DRIVER=cloudflare` al worker complementari, les tasques lleugeres (notificacions no ordenades i lliuraments de webhooks) passen per Cloudflare Queues i no es consulta Postgres. El worker complementari executa totes dues cues
Temps real	El realtime Worker, `apps/realtime-worker`, amb Durable Objects
`worker`, `scheduler`, `collab`, `content`, ClamAV, Gotenberg, ffmpeg	Un host complementari de contenidors. Un Worker no els pot executar
Traçat	Observabilitat de Workers, activada a `wrangler.jsonc`

REPORT_HYPERDRIVE proporciona el rol d’informes per a la base de dades física indicada per HYPERDRIVE. Tal com s’explica més avall, aquest entorn no pot servir tenants assignats a altres bases de dades físiques.

Què no pot fer aquest entorn

En iniciar-se, rebutja la configuració i enumera tots els problemes alhora:

No hi ha SMTP. Feu servir un proveïdor HTTP a QUIRE_EMAIL_PROVIDER_CONFIG.
No hi ha disc local. QUIRE_STORAGE_DRIVER ha d’indicar un emmagatzematge d’objectes.
No hi ha temps real ni memòria cau en procés. Workers no comparteix memòria entre peticions; es rebutgen QUIRE_REALTIME_DRIVER=inprocess i QUIRE_CACHE_DRIVER=memory.
El Worker no pot executar ClamAV, Gotenberg ni ffmpeg. Es rebutgen CLAMAV_URL, GOTENBERG_URL i FFMPEG_PATH si es configuren al Worker; configureu-los al worker complementari.
No hi ha organitzacions amb base de dades dedicada. Els bindings Hyperdrive d’un Worker es fixen en desplegar-lo, de manera que a les organitzacions amb base de dades pròpia se’ls mostra una pàgina clara d’indisponibilitat. Executeu-les a Compose o a Vercel.

I cal tenir en compte una altra limitació, que no provoca rebuig: Workers no admet la renderització prèvia ni la regeneració incremental de contingut estàtic, digui el que digui la documentació del framework. Totes les rutes es renderitzen per a cada petició.

En aquest entorn, manteniu les transaccions curtes i no en deixeu cap oberta durant una crida de xarxa: quan la connexió torna al grup, Hyperdrive reinicia l’estat de sessió, de manera que el context del tenant s’estableix a cada transacció.

Desplegament

Creeu els recursos:

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

Afegiu els dos ID d’Hyperdrive a apps/web/wrangler.jsonc.

Establiu els secrets d’un en un amb bun run --bun wrangler secret put <NAME> des de apps/web: QUIRE_SECRET_KEY, QUIRE_MASTER_KEY, QUIRE_EMAIL_PROVIDER_CONFIG, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, QUIRE_COLLAB_SIGNING_KEY i QUIRE_REALTIME_WORKER_SECRET. Les opcions normals (QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN, QUIRE_PLATFORM_DOMAINS, QUIRE_DATABASE_ID, S3_ENDPOINT, S3_BUCKET i QUIRE_COLLAB_URL) van a vars.

Compileu i desplegueu des de apps/web:

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

Desplegueu el realtime Worker amb QUIRE_REALTIME_WORKER_SECRET de la capa web i establiu-hi el seu secret de token com a QUIRE_REALTIME_TOKEN_SECRET. La capa web signa els tokens de temps real amb el seu propi QUIRE_REALTIME_TOKEN_SECRET o, si no està configurat, amb QUIRE_SECRET_KEY; feu servir el que utilitzi. Al nivell web, configureu QUIRE_REALTIME_WORKER_URL amb l’adreça del Worker:
```
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 executar tasques lleugeres a Cloudflare Queues, creeu una cua per a cada tipus i establiu-ho al worker complementari (amb un token d’API que permeti llegir i escriure cues):
```
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
```
Configureu QUIRE_QUEUE_DRIVER=cloudflare, CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_QUEUES_TOKEN i QUIRE_QUEUE_PREFIX si el prefix no és quire-.
Executeu l’host complementari tal com s’indica al pas 3 de la guia de Vercel. Les migracions s’hi executen abans de cada desplegament del Worker.

Si la configuració no és vàlida, bun run --bun wrangler tail mostra «The web tier did not start on cloudflare» seguit de cadascun dels valors que cal canviar.