La capa web en Cloudflare Workers

El diseño se describe en la sección 6 de docs/architecture/23-ops.md. Workers ejecuta una capa web reducida. La compatibilidad total de funciones en Workers queda fuera del alcance (sección 12 del PRD): las funciones incompatibles con este destino se rechazan al iniciar, indicando su nombre.

Estado de esta versión

La configuración está preparada (apps/web/wrangler.jsonc, el preajuste Nitro cloudflare-module, el puente Hyperdrive y las comprobaciones de inicio). Un Worker necesita almacenamiento compatible con S3 en R2 (QUIRE_STORAGE_DRIVER=s3), un controlador en tiempo real que funcione entre solicitudes (QUIRE_REALTIME_DRIVER=durable_objects o centrifugo), una caché compartida (QUIRE_CACHE_DRIVER=postgres o valkey) y un proveedor de correo HTTP. Sin ellos, el Worker se niega a iniciarse y su registro indica cada parámetro. El controlador Durable Objects es cliente del Worker en tiempo real de apps/realtime-worker (un Durable Object por canal para distribuir eventos, la presencia y el historial, y uno por persona para desconexiones); despliégalo junto con este, como se indica a continuación, o usa Centrifugo.

Componentes

Componente	En Cloudflare
`web`	Un Worker con `nodejs_compat`
Postgres	Externa, accesible mediante Hyperdrive: `HYPERDRIVE` para el rol de aplicación y `REPORT_HYPERDRIVE` para el rol de informes de esa misma base de datos física. Al iniciarse, la capa web copia cada cadena de conexión en `DATABASE_URL` y `QUIRE_REPORT_DATABASE_URL`
Archivos	R2, mediante su API S3 (`S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com`); el enlace `FILES` conecta el bucket
Trabajos en segundo plano	pg-boss mediante Hyperdrive cuando el trabajo debe añadirse dentro de una escritura. Con `QUIRE_QUEUE_DRIVER=cloudflare` en el worker complementario, los trabajos ligeros (entregas desordenadas de notificaciones y webhooks) pasan por Cloudflare Queues, y no se consulta Postgres para ellos. El worker complementario ejecuta ambos tipos
Tiempo real	El Worker en tiempo real `apps/realtime-worker`, con Durable Objects
`worker`, `scheduler`, `collab`, `content`, ClamAV, Gotenberg y ffmpeg	Un host de contenedores complementario. Un Worker no puede ejecutarlos
Trazas	Observabilidad de Workers, activada en `wrangler.jsonc`

REPORT_HYPERDRIVE proporciona el rol de informes para la base de datos física indicada por HYPERDRIVE. Tal como se describe a continuación, este destino no ofrece servicio a tenants fijados a otras bases de datos físicas.

Limitaciones de este destino

Al iniciarse, se rechaza la configuración si hay algún problema y se enumeran todos a la vez:

No admite SMTP. Usa un proveedor HTTP en QUIRE_EMAIL_PROVIDER_CONFIG.
No hay disco local. QUIRE_STORAGE_DRIVER debe indicar un almacenamiento de objetos.
No admite caché ni tiempo real en el mismo proceso. Como los Workers no comparten memoria entre solicitudes, se rechazan QUIRE_REALTIME_DRIVER=inprocess y QUIRE_CACHE_DRIVER=memory.
El Worker no puede ejecutar ClamAV, Gotenberg ni ffmpeg. Se rechazan CLAMAV_URL, GOTENBERG_URL y FFMPEG_PATH si se configuran en el Worker; configúralos en el worker complementario.
No admite organizaciones con bases de datos dedicadas. Los enlaces Hyperdrive de un Worker quedan fijados al desplegar, así que una organización con su propia base de datos verá una página clara de «no disponible aquí». Ofrécele el servicio desde Compose o Vercel.

Además, hay un detalle que no se rechaza, pero que debes conocer: la generación previa y la regeneración estática incremental no funcionan en Workers, independientemente de lo que indique la documentación del framework. Todas las rutas se generan con cada solicitud.

En este destino, mantén las transacciones breves y no las mantengas abiertas durante una llamada de red: Hyperdrive restablece el estado de sesión cuando una conexión vuelve al pool, por lo que el contexto del tenant se establece para cada transacción.

Despliegue

Crea los 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

Añade los dos ID de Hyperdrive a apps/web/wrangler.jsonc.

Configura los secretos, uno por uno con bun run --bun wrangler secret put <NAME> desde apps/web: QUIRE_SECRET_KEY, QUIRE_MASTER_KEY, QUIRE_EMAIL_PROVIDER_CONFIG, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, QUIRE_COLLAB_SIGNING_KEY y QUIRE_REALTIME_WORKER_SECRET. Los parámetros simples (QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN, QUIRE_PLATFORM_DOMAINS, QUIRE_DATABASE_ID, S3_ENDPOINT, S3_BUCKET y QUIRE_COLLAB_URL) van en vars.

Compila y despliega desde apps/web:

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

Despliega el Worker en tiempo real con QUIRE_REALTIME_WORKER_SECRET de la capa web y su secreto de token como QUIRE_REALTIME_TOKEN_SECRET (la capa web firma los tokens de tiempo real con su propio QUIRE_REALTIME_TOKEN_SECRET o, si no está configurado, con QUIRE_SECRET_KEY; usa el que corresponda). Establece QUIRE_REALTIME_WORKER_URL en la capa web con la dirección 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
```
Para usar Cloudflare Queues con trabajos ligeros, crea una cola por cada cola de trabajos ligeros y configura estas variables en el worker complementario (se necesita un token de API con permisos de lectura y escritura de 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
```
Configura QUIRE_QUEUE_DRIVER=cloudflare, CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_QUEUES_TOKEN y QUIRE_QUEUE_PREFIX si el prefijo no es quire-.
Ejecuta el host complementario como se indica en el paso 3 de la guía de Vercel. Allí se ejecutan las migraciones antes de cada despliegue de Worker.

Una configuración rechazada aparece en bun run --bun wrangler tail como «The web tier did not start on cloudflare», seguida de cada parámetro que debes cambiar.