Invalidation et redémarrages en isolement

bext dessert N sites à partir d’un seul processus de mascarade. La règle stricte pour son fonctionnement : n'atteint jamais systemctl restart nginx lorsqu'il existe une surface par site ou par cache. : le redémarrage du processus maître draine brièvement chaque hôte virtuel co-hébergé. Cette page est la référence pour le rayon d'explosion le plus petit possible pour chaque type d'état.

La pile de cache est en couches. Choisissez la couche la plus basse que vous devez invalider ; les couches situées en dessous passent automatiquement à la requête suivante.

code

┌──────────────────────────────────────────────────────────┐
│ L0  in-process hot-path response cache (per (host,path)) │
│ ISR cached SSR responses (per route tag)                 │
│ Proxy / FastCGI response cache (per host+URI)            │
│ V8 isolate pool (per site)                               │
│ Compiled module registry (per abs source path)           │
│ Disk module cache (.bext/cache/modules/<hash>.js)        │
│ Source files on disk                                     │
└──────────────────────────────────────────────────────────┘

Tous les points de terminaison ci-dessous sont en boucle uniquement par défaut (porte à dispatch.rs:2393 ). De l'extérieur de la boîte, vous ne pouvez les frapper qu'avec un jeton administrateur Bearer. Les exemples supposent que vous êtes connecté en SSH à l'hôte.

Caches de réponses#

L0 – chemin chaud en cours de processus#

Supprime le cache de réponse par (host, path, query, encoding) qui court-circuite avant le middleware. À utiliser après un déploiement qui modifie le comportement du middleware/en-tête : le cache ISR ou proxy sous-jacent peut convenir, mais L0 sert les octets de pré-déploiement.

bash

# Whole-cache flush:
curl -X POST http://127.0.0.1/__bext/cache/purge-l0

# Targeted paths:
curl -X POST http://127.0.0.1/__bext/cache/purge-l0 \
  -H 'Content-Type: application/json' \
  -d '{"paths":["/","/blog","/about"]}'

L0 est saisi sur (host, path, …), de sorte que les chemins d'un site n'en affectent jamais un autre. ( crates/bext-server/src/vhost/dispatch.rs:2526 )

ISR — réponses SSR mises en cache#

Basé sur des balises ; efface le cache de réponses en RAM utilisé par les routes SSR. Les balises suivent la convention route:<tag> et * pour tout.

bash

# Per-route:
curl -X POST 'http://127.0.0.1/__bext/admin/api/cache/purge?tag=route:/blog/[slug]' \
  -H "Authorization: Bearer $BEXT_ADMIN_TOKEN"

# Per-site (requires the site's vhost label in the tag pattern):
curl -X POST 'http://127.0.0.1/__bext/admin/api/cache/purge?pattern=route:*' \
  -H "Authorization: Bearer $BEXT_ADMIN_TOKEN"

Cache de réponses proxy/FastCGI#

Purge par hôte, par chemin ou par préfixe du cache proxy_cache / FastCGI (format de clé host+URI ). Utilisé par le webhook de revalidation du CMS Next.js.

bash

curl -X POST http://127.0.0.1/__bext/cache/purge-proxy \
  -H 'Content-Type: application/json' \
  -d '{
    "host":   "blog.example.com",
    "paths":  ["/posts/abc", "/posts/def"],
    "prefixes": ["/tag/"]
  }'

L'isolation s'effectue par hôte car la clé de cache inclut Host. ( dispatch.rs:2466 )

Cache de module compilé (registre Turbopack)#

C'est le calque qui provoquait la douleur "J'ai édité layout.tsx et rien n'a changé". L'observateur fs appelle désormais automatiquement invalidate_file() à chaque mutation source détectée, mais vous devrez peut-être le forcer lorsque :

Les fichiers ont été échangés de manière atomique (mtime saute en arrière)
Un éditeur écrit via rename et inotify manque l'événement
Vous testez la logique de l'observateur elle-même

bash

# Targeted: evict specific source files (also evicts transitive dependents)
curl -X POST http://127.0.0.1/__bext/cache/purge-modules \
  -H 'Content-Type: application/json' \
  -d '{"paths":[
    "/home/infra-sj278/bext/sites/dufournaud-prism/src/app/layout.tsx",
    "/home/infra-sj278/bext/sites/dufournaud-prism/src/components/SiteNav.tsx"
  ]}'

# Per-site: evict every cached module under a directory prefix
curl -X POST http://127.0.0.1/__bext/cache/purge-modules \
  -H 'Content-Type: application/json' \
  -d '{"site":"/home/infra-sj278/bext/sites/dufournaud-prism"}'

# Nuclear: drop every compiled module (heavy — next request to every site
# recompiles its entry tree). Avoid in production.
curl -X POST http://127.0.0.1/__bext/cache/purge-modules

Le point de terminaison appelle également clear_compile_cache, clear_path_memo et clear_context_cache afin que la requête suivante soit réellement recompilée à partir du disque. ( dispatch.rs:2579 )

Nouveaux itinéraires et modifications — désormais automatiques (2026-06-12)#

L'ajout d'un nouveau page.tsx / route.ts, ou la modification d'un existant, ne nécessite plus de purge manuelle ni de redémarrage :

Mode Worker — l'observateur site_worker par site invalide lors de l'enregistrement.
Mode en cours de mascarade — le maître masquerade_route_watcher interroge le app_dir de chaque site et, lors d'un ajout/suppression d'itinéraire ou d'une modification, réinitialise le scanned_routes_cache + table de routage + caches de compilation Turbopack de ce site en cours. Les nouvelles modifications des itinéraires et sont mises en ligne dans un délai d'environ 2 s. Paramètres réglables : BEXT_MASQUERADE_ROUTE_WATCH_MS (par défaut 2000), BEXT_MASQUERADE_ROUTE_WATCH=0 à désactiver.
Scripté/forcé — le bouclage POST /nginx-cache/purge-app {app_root} réinitialise les caches de route d'un site par app_root (aucune résolution d'hôte requise) pour le chemin de travail bifurqué ou les scripts CI.

Survie au redémarrage : les caches disque persistants de compilation + bytecode ( /var/cache/bext/{compile,bytecode} ) survivent au processus, donc un redéploiement ne compile plus à froid chaque route - les routes inchangées sont servies à partir du disque (compilez ~ 80 µs contre ~ 8 ms, plus une restauration de bytecode V8). C'est pourquoi rm -rf .bext + systemctl restart nginx est et non plus la recette de routine pour récupérer les modifications de source.

Pool d'isolation V8 — par site#

Si les modules d'un site sont obsolètes dans un isolat de longue durée (par exemple, vous avez modifié l'état mutable au niveau du module), supprimez uniquement le pool de ce site. Les anciennes demandes en vol s’épuisent naturellement ; les nouvelles demandes reçoivent un nouveau pool via ArcSwap.

bash

# Per-site flush (loopback):
curl -X POST http://127.0.0.1/__bext/api/sites/dufournaud-prism/v8/flush

# Per-site flush via super-admin label (zeros last_build_ms + clears
# response cache for every vhost on that label):
curl -X POST 'http://127.0.0.1/__bext/admin/api/v8/flush?site_label=dufournaud-prism' \
  -H "Authorization: Bearer $BEXT_ADMIN_TOKEN"

Les ID/étiquettes de site proviennent de bext.config.toml ou du nom de l'hôte virtuel. ( dispatch.rs:2445, admin/handlers.rs:1643 )

TLS/SSL#

Le rechargement du certificat par hôte virtuel n'a pas sa propre surface. Le résolveur TLS relit chaque certificat + clé du disque sur SIGHUP ( main.rs:6891 ). Après un renouvellement de certbot :

bash

sudo systemctl reload nginx

Le gestionnaire de mascarade SIGHUP échange le résolveur de certificat de manière atomique et draine les anciens travailleurs pendant 10 secondes maximum : les connexions TLS existantes ne sont pas supprimées, les nouvelles connexions récupèrent le nouveau certificat. Il s'agit du rechargement "doux" et il est sûr même dans le trafic.

Écart :, il n’existe pas de POST /__bext/api/ssl/reload?host=… aujourd’hui. Si le rechargement par hôte virtuel devient important, ajoutez un gestionnaire qui appelle uniquement le chemin de rechargement TLS de la routine SIGHUP (ne reconstruisez pas la configuration de routage).

Configuration Vhost/routage#

La modification de la configuration nginx d'un site (amont, en-têtes, emplacements) nécessite un SIGHUP complet : l'analyseur reconstruit NginxCompatState pour chaque hôte virtuel.

bash

sudo systemctl reload nginx

Cela réanalyse nginx.conf, échange atomiquement le SiteRouter via ArcSwap et draine gracieusement les anciens travailleurs ( main.rs:6814–7037 ). Affecte brièvement tous les sites co-hébergés, mais n'abandonne jamais les demandes en cours.

Écart : aucun rechargement de configuration par hôte virtuel n'existe. Si cela devient important, créez un POST /__bext/api/vhosts/reload?host=… qui réanalyse un seul bloc serveur et le corrige dans le SiteRouter.

Unités systemd par site#

Une poignée de sites disposent de leurs propres processus bext (par exemple bext-gto, bext-avivre, bext-demo-bun ). Ceux-ci vous permettent de redémarrer sans toucher au maître :

bash

sudo systemctl restart bext-gto

Cela tue + réapparaît le travailleur de ce site unique. La mascarade principale continue de router tous les autres sites sans interruption. Liste avec :

bash

systemctl list-units 'bext-*'

Caches de routage/découverte#

Les modifications du fichier source qui ajoutent ou suppriment des routes invalident automatiquement trois caches de découverte lorsque l'observateur fs se déclenche ( bundler.rs:597–607 ) :

scanned_routes_cache — Table de routage PRISM
prism_discover_cache — dispositions par itinéraire, conventions, pages de machines à sous, métadonnées, middleware
route_table_cache — ssr_pipeline::prism::clear_route_table_cache()

Pas de surface HTTP pour ceux-ci : ils dépendent de l'événement d'invalidation de l'observateur. Si vous devez forcer une nouvelle analyse sans modifier un fichier, touchez n'importe quel page.tsx / route.ts / layout.tsx sur le site :

bash

touch /home/infra-sj278/bext/sites/dufournaud-prism/src/app/layout.tsx

Cycle de vie du processus#

Tu veux…	Utilisez ceci	Rayon de souffle
Recharger la configuration nginx + les certificats TLS	`sudo systemctl reload nginx` (SOUPIR)	Tous les vhosts (vidange gracieuse, aucune demande abandonnée)
Redémarrez la mascarade bext	`sudo systemctl restart nginx`	Tous les vhosts (bref écart)
Redémarrez un PRISM/site suivant	`sudo systemctl restart bext-<site>`	Juste ce site
Faire pivoter le pool de travailleurs JSC	`POST /__bext/admin/api/workers/restart`	Tous les ouvriers, roulant
Échange binaire atomique	`./scripts/deploy-local.sh --swap-only`	Bref écart sur swap + redémarrage

Arbre de décision#

code

Source files changed?
  └─ Yes: wait — the fs watcher invalidates modules + ISR + L0 + discovery automatically.
     If still stale: POST /__bext/cache/purge-modules with {site: "<abs/dir>"}.

Stale cached SSR response?
  └─ Yes: POST /__bext/cache/purge-l0 (paths) + ISR purge by tag.
     Don't touch modules or V8 — those layers are upstream.

Edited module state behaves stale even with fresh source?
  └─ Yes: per-site V8 flush. The isolate is holding old module bindings.

Cert renewed?
  └─ Yes: sudo systemctl reload nginx. SIGHUP picks up new certs atomically.

Site config (nginx server block) changed?
  └─ Yes: sudo systemctl reload nginx. Per-site reload doesn't exist (yet).

Site process crashed or wedged?
  └─ Yes: sudo systemctl restart bext-<site> if it has its own unit;
     otherwise sudo systemctl restart nginx.

bext-server binary rebuilt?
  └─ Yes: ./scripts/deploy-local.sh --swap-only. Never edit the running
     binary at /usr/local/bin/bext-server in place.

Authentification#

Tous les chemins /__bext/cache/*, /__bext/api/* et /__bext/debug/* sont en bouclage uniquement par défaut (porte à dispatch.rs:2393 ). Pour les appeler depuis une autre boîte, envoyez le Authorization: Bearer <admin-jwt> émis par le JwtValidator::new_admin de la mascarade.

/__bext/admin/api/* (administrateur côté navigateur) nécessite toujours le jeton du porteur ou un cookie de session d'administrateur.

Découverte de points de terminaison existants#

Un 404 sur n'importe quel chemin /__bext/* renvoie la liste complète des points de terminaison disponibles dans son corps. Utile pour vérifier ponctuellement ce que le binaire en cours d'exécution prend en charge :

bash

curl http://127.0.0.1/__bext/does-not-exist

Attention

N'utilisez jamais systemctl restart nginx comme première réponse à un problème de contenu obsolète ou de rendu lent. Il draine brièvement chaque hôte virtuel co-hébergé. Utilisez les points de terminaison par site ou par cache ci-dessus : ils sont conçus pour avoir un rayon d'explosion nul sur les sites non liés.

Conseil

Les caches disque persistants de compilation et de bytecode sur /var/cache/bext/{compile,bytecode} survivent aux redémarrages du processus, de sorte qu'un deploy-local.sh --swap-only ne compile plus à froid chaque itinéraire. rm -rf .bext + le redémarrage n'est nécessaire que lorsque vous soupçonnez un cache sur disque corrompu.

En rapport#

Mises à niveau sans temps d'arrêt — échange binaire et héritage socket FD pour le chemin de mise à niveau sans redémarrage
Surveillance — render_pool_active, isr_revalidations_total et mesures du taux de réussite du cache
Guides : mise en cache — Mécanismes de garde ISR TTL, périmés pendant la revalidation et de bousculade
Architecture : pool de rendu V8 : comment les pools d'isolation V8 par site sont gérés
Architecture : Pipeline de rendu PRISM — registre de modules compilé et comment l'observateur l'invalide
Dépannage : contenu obsolète, échecs SSR et diagnostics de problèmes de cache