La couche Web sur Cloudflare Workers

Exécutez une version réduite de la couche Web de Quire sur Cloudflare Workers.

La conception est décrite dans la section 6 de docs/architecture/23-ops.md. Workers exécute une couche Web réduite. La parité fonctionnelle sur Workers n’est pas prévue (section 12 du PRD) : au démarrage, les fonctions non prises en charge par cette cible sont refusées et nommées.

État dans cette version

La configuration est en place (apps/web/wrangler.jsonc, le préréglage Nitro cloudflare-module, le pont Hyperdrive et les contrôles au démarrage). Un Worker nécessite un stockage compatible S3 pour R2 (QUIRE_STORAGE_DRIVER=s3), un moteur temps réel entre requêtes (QUIRE_REALTIME_DRIVER=durable_objects ou centrifugo), un cache partagé (QUIRE_CACHE_DRIVER=postgres ou valkey) et un fournisseur d’e-mails HTTP. Sans ces éléments, le Worker refuse de démarrer et son journal nomme chaque paramètre manquant. Le moteur Durable Objects est un client du Worker temps réel dans apps/realtime-worker (un Durable Object par canal pour la diffusion, la présence et l’historique, et un par personne pour les déconnexions) ; déployez-le en même temps, comme indiqué ci-dessous, ou utilisez Centrifugo.

Composants

Composant	Sur Cloudflare
`web`	Un Worker avec `nodejs_compat`
Postgres	Externe, accessible via Hyperdrive : `HYPERDRIVE` pour le rôle applicatif, `REPORT_HYPERDRIVE` pour le rôle de rapport sur cette même base physique. Au démarrage, la couche Web copie chaque chaîne de connexion dans `DATABASE_URL` et `QUIRE_REPORT_DATABASE_URL`
Fichiers	R2 via son API S3 (`S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com`) ; la liaison `FILES` rattache le bucket
Travaux d’arrière-plan	pg-boss via Hyperdrive lorsque le travail doit être mis en file avec une écriture. Avec `QUIRE_QUEUE_DRIVER=cloudflare` sur le worker compagnon, les travaux légers (envois non ordonnés de notifications et de webhooks) passent plutôt par Cloudflare Queues ; Postgres n’est donc pas interrogé pour les récupérer. Le worker compagnon exécute les deux types de travaux
Temps réel	Worker temps réel `apps/realtime-worker`, avec Durable Objects
`worker`, `scheduler`, `collab`, `content`, ClamAV, Gotenberg, ffmpeg	Hôte compagnon pour conteneurs. Un Worker ne peut pas les exécuter
Traçage	Observabilité Workers, activée dans `wrangler.jsonc`

REPORT_HYPERDRIVE fournit le rôle de rapport pour la base physique nommée dans HYPERDRIVE. Comme indiqué ci-dessous, cette cible ne sert pas les locataires épinglés à d’autres bases de données physiques.

Limites de cette cible

Tous les problèmes sont indiqués ensemble en cas de refus au démarrage :

Pas de SMTP. Utilisez un fournisseur HTTP dans QUIRE_EMAIL_PROVIDER_CONFIG.
Pas de disque local. QUIRE_STORAGE_DRIVER doit désigner un stockage d’objets.
Pas de cache ni de temps réel en mémoire de processus. Les Workers ne partagent pas leur mémoire entre les requêtes ; QUIRE_REALTIME_DRIVER=inprocess et QUIRE_CACHE_DRIVER=memory sont donc refusés.
Pas de ClamAV, Gotenberg ou ffmpeg dans le Worker. Les variables CLAMAV_URL, GOTENBERG_URL et FFMPEG_PATH définies sur le Worker sont refusées ; définissez-les plutôt sur le worker compagnon.
Pas d’organisations disposant d’une base dédiée. Les liaisons Hyperdrive du Worker sont fixées au déploiement ; une organisation ayant sa propre base reçoit donc une page indiquant clairement “unavailable here”. Servez-la depuis Compose ou Vercel.

Enfin, un élément n’est pas refusé mais doit être connu : le prérendu et la génération statique incrémentielle ne fonctionnent pas sur Workers, contrairement à ce qu’indique la documentation du framework. Chaque route est rendue à chaque requête.

Sur cette cible, gardez les transactions courtes et n’en maintenez jamais une ouverte pendant un appel réseau : Hyperdrive réinitialise l’état de la session lorsqu’une connexion revient dans le pool ; le contexte du locataire est donc défini dans chaque transaction.

Déploiement

Créez les ressources :

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

Ajoutez les deux identifiants Hyperdrive à apps/web/wrangler.jsonc.

Définissez les secrets un par un avec bun run --bun wrangler secret put <NAME> depuis 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. Placez les paramètres ordinaires (QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN, QUIRE_PLATFORM_DOMAINS, QUIRE_DATABASE_ID, S3_ENDPOINT, S3_BUCKET, QUIRE_COLLAB_URL) dans vars.

Compilez et déployez depuis apps/web :

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

Déployez le Worker temps réel en lui donnant le QUIRE_REALTIME_WORKER_SECRET de la couche Web et son secret de jeton sous QUIRE_REALTIME_TOKEN_SECRET (la couche Web signe les jetons temps réel avec son propre QUIRE_REALTIME_TOKEN_SECRET, ou avec QUIRE_SECRET_KEY si celui-ci n’est pas défini ; utilisez donc la valeur qu’elle emploie). Définissez sur la couche Web l’adresse du Worker dans QUIRE_REALTIME_WORKER_URL :
```
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
```
Pour les travaux légers sur Cloudflare Queues, créez une file pour chaque file légère et définissez les paramètres suivants sur le worker compagnon (avec un jeton API disposant des droits de lecture et d’écriture sur 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
```
Définissez QUIRE_QUEUE_DRIVER=cloudflare, CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_QUEUES_TOKEN et QUIRE_QUEUE_PREFIX si sa valeur n’est pas quire-.
Exécutez l’hôte compagnon comme à l’étape 3 du guide Vercel. Les migrations s’y exécutent avant chaque déploiement Worker.

En cas de refus de la configuration, bun run --bun wrangler tail affiche “The web tier did not start on cloudflare”, suivi de chaque paramètre à modifier.