Couche Web sur Cloudflare Workers

La conception est décrite à la section 6 de docs/architecture/23-ops.md. Workers exécute une couche Web réduite. La parité complète des fonctions avec Workers est hors de portée (section 12 du PRD) : les fonctions non prises en charge par cette cible sont refusées au démarrage et indiquées par leur nom.

État de cette version

La configuration est en place (apps/web/wrangler.jsonc, le préréglage Nitro cloudflare-module, le pont Hyperdrive et les vérifications au démarrage). Un Worker exige un stockage compatible S3 pour R2 (QUIRE_STORAGE_DRIVER=s3), un pilote temps réel fonctionnant d’une requête à l’autre (QUIRE_REALTIME_DRIVER=durable_objects ou centrifugo), un cache partagé (QUIRE_CACHE_DRIVER=postgres ou valkey) et un fournisseur de courriel HTTP. Sans ces éléments, le Worker refuse de démarrer et son journal indique chaque paramètre manquant. Le pilote Durable Objects est un client du Worker temps réel à apps/realtime-worker (un objet Durable par canal pour la diffusion, la présence et l’historique, et un par personne pour les déconnexions); déployez-le en parallèle, comme ci-dessous, ou utilisez Centrifugo.

Composants

Composant	Sur Cloudflare
`web`	Worker avec `nodejs_compat`
Postgres	Externe, accessible par Hyperdrive : `HYPERDRIVE` pour le rôle d’application, `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 par son API S3 (`S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com`); le lien `FILES` associe le compartiment
Tâches en arrière-plan	pg-boss par Hyperdrive lorsque la tâche doit être ajoutée en même temps qu’une écriture. Avec `QUIRE_QUEUE_DRIVER=cloudflare` sur le processus compagnon, les tâches légères (livraisons non ordonnées de notifications et de webhooks) passent plutôt par Cloudflare Queues, évitant l’interrogation de Postgres. Le processus compagnon exécute les deux types
Temps réel	Worker temps réel `apps/realtime-worker`, avec Durable Objects
`worker`, `scheduler`, `collab`, `content`, ClamAV, Gotenberg, ffmpeg	Hôte compagnon de conteneurs. Un Worker ne peut pas les exécuter
Traces	Observabilité Workers, activée dans `wrangler.jsonc`

REPORT_HYPERDRIVE fournit le rôle de rapport pour la base physique indiquée par HYPERDRIVE. Comme décrit ci-dessous, cette cible ne dessert pas les locataires rattachés à d’autres bases physiques.

Limites de cette cible

Le démarrage est refusé et tous les problèmes sont indiqués à la fois :

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 temps réel ni de cache en processus. Workers ne partage aucune mémoire entre les requêtes; QUIRE_REALTIME_DRIVER=inprocess et QUIRE_CACHE_DRIVER=memory sont donc refusés.
Pas de ClamAV, Gotenberg ni ffmpeg dans le Worker. Le Worker refuse les paramètres CLAMAV_URL, GOTENBERG_URL et FFMPEG_PATH; définissez-les plutôt sur le processus compagnon.
Aucune organisation utilisant une base dédiée. Les liens Hyperdrive d’un Worker sont fixes au déploiement; une organisation ayant sa propre base obtient une page indiquant clairement que le service n’y est pas disponible. Hébergez-la avec Compose ou Vercel.

Autre limite à connaître, bien qu’elle ne soit pas refusée : le prérendu et la régénération statique incrémentielle ne fonctionnent pas sur Workers, quels que soient les propos de la documentation du cadre logiciel. Chaque itinéraire est rendu à chaque requête.

Sur cette cible, gardez les transactions courtes et ne les gardez jamais pendant un appel réseau : Hyperdrive réinitialise l’état de session lorsqu’une connexion retourne au bassin; le contexte du locataire est donc défini pour 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

Inscrivez les deux identifiants Hyperdrive dans apps/web/wrangler.jsonc.

Définissez les secrets, un à la fois 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 et QUIRE_REALTIME_WORKER_SECRET. Définissez les paramètres simples (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 avec le paramètre QUIRE_REALTIME_WORKER_SECRET de la couche Web et son secret de jeton sous le nom QUIRE_REALTIME_TOKEN_SECRET (la couche Web signe les jetons temps réel avec son propre QUIRE_REALTIME_TOKEN_SECRET ou, si ce paramètre n’est pas défini, avec QUIRE_SECRET_KEY; utilisez donc la valeur effectivement utilisée), puis définissez QUIRE_REALTIME_WORKER_URL sur la couche Web pour indiquer son adresse :
```
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 tâches légères dans Cloudflare Queues, créez une file par file légère et définissez ces paramètres sur le processus compagnon (un jeton d’API autorisé à lire et écrire dans 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 le préfixe 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 du Worker.

Une configuration refusée est signalée par bun run --bun wrangler tail par le message « The web tier did not start on cloudflare », suivi de chaque paramètre à modifier.