Inclut côté serveur

<bext-include> est la primitive de composition de bext. Il se situe à l'intersection de la mise en cache, du streaming, de l'authentification, de l'expérimentation et du temps réel pour assembler des pages à partir de fragments indépendants, le tout au niveau du serveur, avant que la réponse ne quitte la périphérie.

<bext-include src="/__bext/nav" site="docs"></bext-include>

Le serveur remplace cet élément par le HTML résolu avant d'envoyer la réponse. Chaque intégration (mise en cache, authentification, tests A/B, mises à jour en direct) est un attribut déclaratif sur l'élément.

bext prend également en charge les syntaxes standard SSI ( <!--#include virtual="..." --> ) et ESI ( <esi:include> ), de sorte que les configurations nginx et CDN existantes migrent vers bext sans changement de code et obtenez automatiquement l'ensemble complet des fonctionnalités de bext.

Trois syntaxes, un système#

Les trois syntaxes sont analysées dans la même directive et transitent par le même pipeline de résolution :

<!-- bext-native, richest feature set -->
<bext-include src="/__bext/nav" site="docs"></bext-include>

<!-- nginx / Apache SSI -->
<!--#include virtual="/__bext/nav" -->

<!-- W3C ESI (Varnish, Akamai, Fastly) -->
<esi:include src="/__bext/nav" />

Utilisez <bext-include> pour les nouveaux sites. Utilisez SSI lors de la migration depuis nginx. Utilisez ESI lors de la migration depuis un CDN.

Ce que vous pouvez faire avec inclut#

Chaque fonctionnalité est un attribut unique sur <bext-include>. Mélangez et assortissez.

Cache avec TTL et périmé pendant la revalidation#

<bext-include src="/__bext/nav"
  ttl="5m" swr="1h" tags="chrome"
></bext-include>

La navigation est rendue une fois, servie à partir du cache pendant 5 minutes, puis servie pendant une heure maximum lors de la revalidation en arrière-plan. Marqué chrome afin que vous puissiez purger tous les fragments de chrome en même temps via l'API de purge du cache. Soutenu par le cache L0/L1/L2 hiérarchisé de bext.

→ Mise en cache et TTL

Varier selon les dimensions#

<bext-include src="/partials/pricing-table"
  vary="role,locale,geo"
  ttl="10m"
></bext-include>

Un élément, des entrées de cache distinctes par combinaison (rôle × paramètres régionaux × géo). Les administrateurs français voient des prix différents de ceux des téléspectateurs américains, et chaque variante est mise en cache indépendamment.

→ Mise en cache adaptée aux variations

Le flux paresseux inclut#

<bext-include src="/partials/recommendations"
  loading="lazy"
>Loading recommendations...</bext-include>

Le shell de la page arrive immédiatement avec un espace réservé. Les recommandations lentes incluent les résolutions en arrière-plan et les flux en tant que bloc ultérieur. Aucun blocage.

→ Le streaming comprend

Contrôle d'authentification côté serveur#

<bext-include src="/partials/admin-toolbar"
  auth="required" role="admin"
  vary="role" ttl="30m"
>
  <!-- fallback: hidden from non-admins entirely -->
</bext-include>

La barre d'outils d'administration n'est affichée que pour les administrateurs authentifiés. Les non-administrateurs voient le contenu de secours (ou rien). Pas de changement de mise en page, pas de scintillement côté client, pas de fuite de balisage.

→ Les inclusions authentifiées

Expériences A/B#

<bext-include src="/partials/hero"
  experiment="hero-redesign"
></bext-include>

Attribue à chaque utilisateur une variante (cookie aléatoire pondéré et collant), réécrit src dans la source spécifique à la variante et met en cache chaque bras indépendamment.

→ Variantes d'expérimentation

Fragments de mise à jour en direct#

<bext-include src="/partials/order-status"
  realtime="orders:123"
></bext-include>

SSR au premier chargement ; par la suite, un abonnement SSE côté client récupère le fragment chaque fois que le serveur publie sur le canal orders:123. Tableaux de bord et badges de notification sans bibliothèque de gestion d'état.

→ Le temps réel inclut

Partiels basés sur des fichiers#

<bext-include src="/_partials/footer.html"></bext-include>

<!-- SSI-compatible -->
<!--#include virtual="/_partials/footer.html" -->

Fichiers HTML statiques du répertoire _partials/ du site. L'invalidation du cache basée sur le temps signifie que la modification du fichier détruit automatiquement le cache.

→ Fichiers partiels

Timeout, repli, coupure de circuit#

<bext-include src="/api/live-scores"
  timeout="200ms"
  fallback="/_partials/cached-scores.html"
  onerror="continue"
></bext-include>

Abandonnez après 200 ms, essayez un repli partiel et abandonnez silencieusement si tout échoue. Plus un disjoncteur qui ignore les appels vers des sources constamment défaillantes.

→ Délai d'attente et repli

Rendu des composants via V8#

<bext-include src="./components/PricingTable.tsx"
  render="v8" props='{"plan":"pro"}'
></bext-include>

Compilez et SSR un composant React dans le pool d'isolation V8 de bext — aucun processus Bun n'est nécessaire. Ponts d'attributs hydrate en option vers le système d'îlot pour l'interactivité côté client.

→ Rendu des composants

Référence d'attribut complète#

<bext-include
  src="/partials/example"

  ttl="5m" swr="1h" tags="chrome,nav"
  vary="role,locale,geo,device"
  loading="eager"

  auth="required" role="admin,editor"
  experiment="layout-test"

  realtime="channel-name"
  realtime-mode="replace"
  realtime-event="update"

  timeout="200ms"
  fallback="/cache/primary" fallback-2="/static/default.html"
  onerror="continue"

  render="v8" props='{"x":1}' hydrate
></bext-include>

Comment fonctionne la chaîne de résolution#

Chaque inclusion (de n'importe quelle syntaxe) passe par le même pipeline :

Parse directive
  ↓
Security (depth, count, allow/deny)
  ↓
Cache (hit = return stored HTML)
  ↓
Auth gate (reject before resolution cost)
  ↓
Experiment (rewrite src to variant)
  ↓
Plugin resolvers (custom, pattern-matched)
  ↓
Built-in resolvers (/__bext/* sources)
  ↓
File resolver (/_partials/*)
  ↓
V8 renderer (render="...")
  ↓
Fallback resolver (fallback, onerror, inline)

Chaque résolveur de la chaîne renvoie du contenu (arrêt) ou passe au suivant. Cette composition indique comment une seule balise <bext-include> peut être mise en cache, authentifiée, modifiée selon le rôle et diffusée paresseusement, simplement en combinant des attributs.

Performance#

• Aucune allocation par requête lorsque le HTML n'a pas de balises d'inclusion - caution anticipée via .contains().
• Le garde de bousculade empêche le troupeau de tonnerre en cas d'échec de cache.
• TTL adaptatif conserve les inclusions populaires en cache plus longtemps (en fonction du nombre d'accès).
• Compression par morceau sur le streaming paresseux inclus.
• Mtime cache sur les fichiers partiels signifie que les fichiers inchangés ne sont jamais relus à partir du disque.
• Le disjoncteur ignore la résolution pour les sources défaillantes persistantes.

Où aller ensuite#

• Mise en cache et TTL — cycle de vie du cache par inclusion
• Mise en cache adaptée aux variations — clés de cache basées sur les dimensions
• Les inclusions authentifiées — autorisation côté serveur
• Le streaming comprend — livraison progressive
• Variantes d'expérimentation — Tests A/B
• Le temps réel inclut — mises à jour de fragments en direct
• Fichiers partiels — inclusions basées sur le système de fichiers
• Délai d'attente et repli — résilience
• Rendu des composants — SSR soutenu par V8
• Compatibilité SSI et ESI — nginx et migration CDN
• Référence de configuration — bext.config.toml
• API du plugin — résolveurs et crochets personnalisés