Compatibilité SSI et ESI

<bext-include> est natif pour bext, mais les sites et configurations CDN existants utilisent deux autres syntaxes standard : SSI (nginx et Apache) et ESI (Varnish, Akamai, Fastly). bext les prend toutes deux en charge nativement. Les trois syntaxes sont analysées en une même directive et suivent la même chaîne de résolution : les balises SSI/ESI existantes bénéficient donc automatiquement du cache, du contrôle d’accès, des expérimentations et du streaming de bext.

html

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

<!-- W3C ESI -->
<esi:include src="/partials/nav" />

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

Les trois produisent le même HTML après résolution.

SSI — inclusions côté serveur de nginx et Apache#

bext prend en charge la directive SSI la plus couramment utilisée : #include.

``#

Chemin relatif au serveur. Résout en {site_root}/path.

html

<body>
  <!--#include virtual="/partials/header.html" -->
  <main>...</main>
  <!--#include virtual="/partials/footer.html" -->
</body>

``#

Chemin relatif au document. Résout par rapport au fichier en cours de traitement.

html

<!-- served from /blog/post.html -->
<!-- this resolves to /blog/_includes/sidebar.html -->
<!--#include file="_includes/sidebar.html" -->

``#

Avec un talon d'erreur :

html

<!--#include virtual="/optional/widget.html" stub="widget_error" -->

Lorsque l'inclusion échoue, le nom stub identifie le bloc d'erreur à émettre. bext transmet la valeur du stub au résolveur en tant qu'attribut.

Les directives SSI bext ne sont PAS prises en charge#

 — interpolation de variables d'environnement.
...  — blocs conditionnels.
 — affectation de variables.
 — exécution de commandes shell (raisons de sécurité).
 — Directives de configuration SSI.

Celles-ci sont rares en pratique et concernent principalement les métadonnées du serveur. Si vous en avez besoin, utilisez <bext-include> ou un composant rendu V8.

Conseil

Les directives SSI telles que ,  et  sont des et non des prises en charge. Si votre configuration nginx existante les utilise, convertissez ces balises en éléments <bext-include> ou en composants rendus V8 avant la migration.

ESI — Le côté bord comprend#

bext prend en charge les directives ESI les plus couramment utilisées.

`<esi:include src="..." />`#

Les bases comprennent :

html

<esi:include src="/partials/nav" />
<esi:include src="/partials/nav"></esi:include>  <!-- both forms OK -->

`<esi:include src="..." alt="..." />`#

Source de secours :

html

<esi:include src="/api/live" alt="/api/cached" />

Si /api/live échoue, bext essaie /api/cached. Si les deux échouent, suivez la stratégie onerror.

`<esi:include src="..." onerror="continue" />`#

Chute silencieuse en cas d'échec :

html

<esi:include src="/api/optional" onerror="continue" />

Si tous les chemins de résolution échouent, la balise est remplacée par une chaîne vide (pas de balisage <esi:include> restant).

`<esi:remove>...</esi:remove>`#

Bloc de contenu supprimé lorsque ESI est actif. Utilisez-le pour le balisage de secours qui indique quand ESI n'est pas en cours de traitement (par exemple, le fichier statique servi directement par origin sans CDN).

html

<!-- bext sees ESI; strips this block entirely -->
<esi:remove>
  <p>This is what you'd see without ESI processing.</p>
</esi:remove>

<esi:include src="/partials/live-content" />

``#

Contenu visible UNIQUEMENT lors du traitement par ESI. Le commentaire wrapper est supprimé, révélant le contenu interne :

html

<!-- Without ESI: browser sees the comment (ignored) -->
<!-- With ESI: wrapper stripped, content revealed -->
<!--esi <p>This shows only when ESI is processed.</p> -->

Le modèle : utilisez <esi:remove> pour « repli lorsque ESI n'est PAS en cours de traitement » et  pour « contenu lorsque ESI est en cours de traitement ». Ils sont complémentaires : ensemble, ils vous permettent d'écrire un seul document HTML qui fonctionne avec et sans ESI.

Les directives ESI bext ne prennent PAS en charge#

<esi:try> / <esi:attempt> / <esi:except> — gestion des erreurs complexe.
<esi:choose> / <esi:when> / <esi:otherwise> — conditionnels.
<esi:vars> — interpolation variable.
<esi:inline> — prélecture.

La plupart d'entre eux ont des analogues directs dans les attributs bext ( fallback, auth, experiment, etc.). Si vous en avez besoin pendant la migration, convertissez-les en <bext-include>.

Tous les trois ensemble#

Un seul document HTML peut mélanger les trois syntaxes :

html

<!DOCTYPE html>
<html>
<body>
  <!-- bext-native: full feature set -->
  <bext-include src="/__bext/nav" site="docs" ttl="5m"></bext-include>

  <main>
    <h1>Welcome</h1>

    <!-- Legacy SSI: kept from the nginx era -->
    <!--#include virtual="/_partials/promo-banner.html" -->

    <!-- ESI from the CDN era: works with or without ESI-aware cache -->
    <esi:include src="/_partials/live-ticker" alt="/_partials/static-ticker" />
    <esi:remove>
      <p>Ticker unavailable (legacy fallback).</p>
    </esi:remove>
  </main>

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

Tous les trois se résolvent via le même pipeline. Appliquez la mise en cache, l'authentification ou les expériences via des règles de configuration, qui ciblent le src résolu, et non la syntaxe :

toml

[[include.rules]]
# Applies to ALL THREE above — bext-include, SSI, and ESI
pattern = "/_partials/*"
ttl = "1h"
tags = ["chrome"]

[[include.rules]]
pattern = "/api/live*"
ttl = "10s"
timeout = "200ms"
fallback = "/_partials/fallback.html"

Remarque

Les fonctionnalités non disponibles en tant qu'attributs de balise SSI/ESI (TTL, varie, authentification, expériences) sont configurées via [[include.rules]] dans bext.config.toml. Une règle correspond au modèle src, donc la même configuration s'applique à toute syntaxe qui résout ce chemin.

Chemin de migration#

À partir de nginx avec SSI#

Le bext détecte automatiquement le SSI. Les balises  existantes fonctionnent inchangées.

nginx

# existing nginx config
server {
    root /var/www/site;
    location / {
        ssi on;
        try_files $uri $uri/index.html;
    }
}

Avec bext :

toml

# bext.config.toml — SSI enabled by default
[[apps]]
hostname = "example.com"
root = "./site"

Aucune modification de votre code HTML. Vous gagnez immédiatement :

Mise en cache (ajoutez [[include.rules]] avec ttl ).
Invalidation basée sur le temps (fonctionne automatiquement).
Timeout + chaîne de repli (ajouter aux règles).
Purge basée sur les balises (ajoutez tags aux règles).

Depuis un CDN avec ESI#

Portage direct des configurations Varnish / Akamai / Fastly ESI :

vcl

# Varnish VCL
sub vcl_backend_response {
    set beresp.do_esi = true;
}

Avec bext :

toml

# bext.config.toml — ESI always on

Pas de VCL, pas de syntaxe spécifique au CDN. bext traite l'ESI à l'origine. Vous bénéficiez également de fonctionnalités que CDN ESI ne possède pas : mise en cache variable, streaming, mises à jour en temps réel, auth gating.

Amélioration progressive#

Vous n’avez rien à réécrire. Le SSI/ESI existant continue de fonctionner. Utilisez les règles de configuration pour ajouter progressivement les fonctionnalités bext :

toml

# Week 1: add caching to the hottest partials
[[include.rules]]
pattern = "/_partials/nav*"
ttl = "10m"
tags = ["chrome"]

# Week 2: add timeout+fallback to API includes
[[include.rules]]
pattern = "/api/*"
timeout = "200ms"
fallback = "/_partials/api-fallback.html"

# Week 3: add vary for personalized fragments
[[include.rules]]
pattern = "/partials/personalized*"
vary = ["role", "locale"]
ttl = "5m"

Aucune modification HTML. Chaque règle prend effet lors du prochain déploiement.

Tableau de parité des fonctionnalités#

Fonctionnalité	`<bext-include>`	SSI	ESI
Inclut de base	✅ `src=`	✅ `virtual=`, `file=`	✅ `src=`
Source de secours	✅ `fallback=`	❌ (via la configuration)	✅ `alt=`
Silencieux en cas d'erreur	✅ `onerror=`	❌ (via la configuration)	✅ `onerror=`
Durée de vie / cache	✅ `ttl=`	❌ (via la configuration)	❌ (via la configuration)
Varier	✅ `vary=`	❌ (via la configuration)	❌ (via la configuration)
Porte d'authentification	✅ `auth=`	❌ (via la configuration)	❌ (via la configuration)
Expérience	✅ `experiment=`	❌ (via la configuration)	❌ (via la configuration)
Temps réel	✅ `realtime=`	❌	❌
Streaming	✅ `loading=`	❌	❌
Supprimer le bloc	❌	❌	✅ `<esi:remove>`
Révélation ESI uniquement	❌	❌	✅ `<!--esi -->`

Pour SSI et ESI, les fonctionnalités non disponibles en tant qu'attributs fonctionnent via des règles de configuration correspondant au chemin src. Cela signifie que vous pouvez obtenir toutes les fonctionnalités de bext avec la syntaxe SSI/ESI : il suffit de déclarer le comportement dans bext.config.toml plutôt que sur la balise.

Voir aussi#

Aperçu — système d'inclusion complet
Migration depuis nginx — guide de migration complet
Configuration — règles par source pour les fonctionnalités SSI/ESI

Compatibilité SSI et ESI

SSI — inclusions côté serveur de nginx et Apache#

#

#

#

Les directives SSI bext ne sont PAS prises en charge#

ESI — Le côté bord comprend#

<esi:include src="..." />#

<esi:include src="..." alt="..." />#

<esi:include src="..." onerror="continue" />#

<esi:remove>...</esi:remove>#

#

Les directives ESI bext ne prennent PAS en charge#

Tous les trois ensemble#

Chemin de migration#

À partir de nginx avec SSI#

Depuis un CDN avec ESI#

Amélioration progressive#

Tableau de parité des fonctionnalités#

Voir aussi#

``#

``#

``#

`<esi:include src="..." />`#

`<esi:include src="..." alt="..." />`#

`<esi:include src="..." onerror="continue" />`#

`<esi:remove>...</esi:remove>`#

``#