Référence de configuration

Le système d'inclusion est configuré sous [include] dans bext.config.toml. Valeurs par défaut globales, règles par source, limites de sécurité : toutes déclaratives, toutes rechargeables sans modification de code.

[include]
enabled = true

[include.cache]
enabled = true
l1_max_entries = 5000
max_variants_per_include = 100

[[include.rules]]
pattern = "/__bext/nav*"
ttl = "5m"
swr = "1h"
tags = ["chrome"]

Cette page est la référence complète. Consultez les pages spécifiques au sujet pour savoir comment fonctionnent les fonctionnalités individuelles.

[include] — interrupteur principal#

[include]
enabled = true    # set false to disable the whole subsystem

Lorsqu'elles sont désactivées, les balises <bext-include>, SSI et ESI sont toutes transmises sans modification : pas d'analyse, pas de résolution.

[include.cache] — réglage du cache à plusieurs niveaux#

[include.cache]
enabled = true                   # default when any TTL is declared
l1_max_entries = 5000            # in-process LRU cap
l2_prefix = "bext:include:"      # Redis key prefix (when L2 is configured)
max_variants_per_include = 100   # cardinality cap per source
default_ttl = "0"                # no cache by default
default_swr = "0"                # no SWR by default

[include.cache.adaptive]
base_ttl_ms = 60_000             # 60s base for adaptive TTL
max_ttl_ms = 600_000             # 10min cap
extension_threshold = 10         # start extending after N hits

Voir La mise en cache inclut.

[include.vary] — déclarations de dimensions#

[include.vary]
dimensions = ["role", "locale", "geo", "device", "theme", "currency"]

[include.vary.custom]
"preferred-unit" = { source = "cookie", name = "unit" }
"api-version" = { source = "header", name = "x-api-version" }

Seules les dimensions répertoriées ici peuvent être référencées dans les attributs vary="...". Ajoutez des dimensions personnalisées à partir de cookies ou d'en-têtes. Voir Mise en cache adaptée aux variations.

[include.files] — partiels du système de fichiers#

[include.files]
enabled = true
root = "_partials"                              # relative to site root
max_size = "1MB"
allowed_extensions = ["html", "htm", "svg", "txt"]
enforce_jail = true                             # block symlinks outside root

Voir Fichiers partiels.

[include.v8] — rendu des composants#

[include.v8]
enabled = true        # requires v8 feature
max_execution_ms = 500
max_memory_mb = 64
pool_size = 4         # pre-warmed isolates

Voir Rendu des composants.

[include.circuit_breaker] — gestion des échecs#

[include.circuit_breaker]
enabled = true
failure_threshold = 5      # failures before opening circuit
cooldown = "30s"           # time before retrying
half_open_requests = 1     # test requests in half-open state

Disjoncteur par source. Voir Délai d'attente et repli.

[include.timeouts] — délais d'attente par défaut#

[include.timeouts]
default = "5s"       # global fallback
proxy = "3s"         # upstream HTTP fetches
v8 = "500ms"         # V8 renders

L'inclusion par inclusion de timeout="..." remplace ces valeurs par défaut.

[include.security] — limites et autorisation/refus#

[include.security]
max_depth = 3                           # nested include depth limit
max_includes_per_page = 50              # per-response cap
allowed_sources = []                    # empty = all allowed
blocked_sources = []                    # always denied

Profondeur d'inclusion imbriquée#

Une inclusion peut faire référence à une source qui contient elle-même des inclusions. Le compteur de profondeur empêche une récursion incontrôlable :

Page -> /_partials/layout.html (depth 1)
  -> /_partials/header.html (depth 2)
    -> /_partials/logo.html (depth 3)
      -> /_partials/svg-defs.html (depth 4 — REJECTED with max_depth=3)

Le dépassement de la limite émet un avertissement et remplace l'inclusion par une chaîne vide.

Nombre par page#

Le compteur max_includes_per_page empêche un modèle malveillant ou défectueux de provoquer des milliers de résolutions :

max_includes_per_page = 50

Après 50 inclusions sur une seule réponse, les balises supplémentaires sont remplacées par des chaînes vides. Ajustez en fonction de la complexité de votre page : la plupart des pages comportent 5 à 15 inclusions.

Listes d'autorisation/refus#

[include.security]
# Allowlist mode: only listed patterns are permitted
allowed_sources = [
  "/__bext/*",
  "/_partials/*",
  "/cms/*",
]

# Denylist: always blocked, even if in allowed_sources
blocked_sources = [
  "/admin/secrets/*",
  "/.env*",
]

Ordre d'évaluation :

1. Si src correspond à un modèle dans blocked_sources, rejetez.
2. Si allowed_sources n’est pas vide et que src ne correspond à aucun modèle, rejetez.
3. Sinon, autorisez.

Un allowed_sources vide signifie « tout autorisé sauf bloqué » (par défaut). Non vide signifie une liste blanche stricte.

[[include.rules]] — configuration par source#

Valeurs par défaut par modèle qui s'appliquent à toute inclusion (n'importe quelle syntaxe) dont src correspond.

[[include.rules]]
pattern = "/__bext/nav*"
ttl = "5m"
swr = "1h"
tags = ["chrome"]

[[include.rules]]
pattern = "/_partials/footer*"
ttl = "1d"
tags = ["chrome"]

[[include.rules]]
pattern = "/api/*"
timeout = "200ms"
fallback = "/_partials/api-fallback.html"
circuit_breaker = true

[[include.rules]]
pattern = "/partials/pricing*"
vary = ["role", "locale"]
ttl = "10m"

[[include.rules]]
pattern = "/partials/admin-*"
auth = "required"
roles = ["admin"]
vary = ["role"]
ttl = "30m"

Champs de règle#

Tous les champs sont facultatifs ; les champs omis reviennent aux valeurs par défaut globales.

Correspondance des règles#

• La première règle de correspondance l'emporte — l'ordre dans le fichier TOML est important.
• Syntaxe globale : * correspond à tous les caractères sauf / ; ** correspond à tous les séparateurs de chemin.
• L'attribut remplace la règle : si l'élément HTML spécifie ttl="1h", cela l'emporte sur le ttl="5m" d'une règle.

Exemples#

Mettez tout en cache sous /__bext/ pendant 5 minutes avec la balise chrome :

[[include.rules]]
pattern = "/__bext/*"
ttl = "5m"
tags = ["chrome"]

Règles distinctes pour les différents points de terminaison de l'API :

[[include.rules]]
pattern = "/api/live/*"
ttl = "10s"
timeout = "100ms"

[[include.rules]]
pattern = "/api/*"          # catch-all AFTER specific rules
ttl = "1m"
timeout = "300ms"

Tarification basée sur les rôles avec des règles distinctes par niveau de rôle :

[[include.rules]]
pattern = "/partials/pricing/enterprise*"
auth = "required"
roles = ["enterprise"]
vary = ["role"]
ttl = "1h"

[[include.rules]]
pattern = "/partials/pricing/*"
ttl = "10m"
vary = ["role"]

[[experiments]] — Définitions des expériences A/B#

[[experiments]]
name = "hero-redesign"
cookie = "bext_exp_hero"
cookie_ttl = "30d"
variants = [
  { name = "control",   weight = 50, src_suffix = "" },
  { name = "variant-a", weight = 25, src_suffix = "-v2" },
  { name = "variant-b", weight = 25, src_suffix = "-v3" },
]

Voir Variantes d'expérimentation.

Intégration des règles de routage#

La configuration d'inclusion peut être colocalisée avec les règles de routage pour les remplacements spécifiques à la page :

[[route_rules]]
pattern = "/blog/*"
rendering = "isr"
revalidate = 3600

[route_rules.includes]
"/__bext/nav" = { ttl = "1h" }
"/partials/sidebar" = { loading = "lazy", ttl = "10m" }
"/partials/comments" = { timeout = "500ms", fallback = "/_partials/comments-fallback.html" }

Sur les pages de blog, ces valeurs par défaut s'appliquent. Sur les autres pages, le [[include.rules]] global s'applique.

Interpolation des variables d'environnement#

Les valeurs de configuration prennent en charge ${VAR} et ${VAR:-default} :

[include.v8]
pool_size = "${BEXT_V8_POOL_SIZE:-4}"

[include.circuit_breaker]
failure_threshold = "${BEXT_CIRCUIT_THRESHOLD:-5}"

[[include.rules]]
pattern = "/cms/*"
timeout = "${CMS_TIMEOUT:-500ms}"
fallback = "${CMS_FALLBACK:-/_partials/cms-offline.html}"

Utile pour le réglage spécifique à l'environnement sans bifurquer la configuration.

Validation de la configuration#

Au démarrage du serveur, bext valide la configuration d'inclusion :

• Syntaxe du modèle — glob.
• Analyse de durée — format reconnu.
• Pondérations d'expérience — différentes de zéro, variantes non vides.
• Dimensions variables — déclarées dans [include.vary] ou intégrées.
• Rôle sans authentification — avertit si roles est défini mais que auth ne l'est pas.
• Cache sans variation (pour authentifié) — avertit du risque d'empoisonnement.
• Extensions — valeurs par défaut raisonnables appliquées.

Les erreurs sont fatales — le serveur ne démarre pas avec une configuration non valide. Les avertissements sont enregistrés mais non fatals — le serveur démarre et enregistre le problème.

Rechargement de la configuration#

La configuration d'inclusion peut être rechargée sans redémarrage via SIGHUP (en mode mascarade) ou l'API d'administration :

# SIGHUP for config reload
kill -HUP $(cat /run/bext.pid)

# or via admin API
curl -X POST http://localhost/__bext/admin/reload-config

Les modifications apportées à [include.rules] et [include.cache] s'appliquent aux nouvelles demandes sans abandonner celles en cours.

Configuration de travail minimale#

Pour un démarrage rapide, le système d'inclusion fonctionne sans configuration : des valeurs par défaut raisonnables sont fournies dans le binaire. Mais une configuration de production typique ressemble à :

[include]
enabled = true

[include.cache]
enabled = true
l1_max_entries = 5000

[include.security]
max_depth = 3
max_includes_per_page = 50

[include.timeouts]
default = "3s"
proxy = "1s"

[[include.rules]]
pattern = "/__bext/*"
ttl = "5m"
tags = ["chrome"]

[[include.rules]]
pattern = "/_partials/*"
ttl = "1h"
tags = ["chrome"]

[[include.rules]]
pattern = "/api/*"
timeout = "500ms"
fallback = "/_partials/api-fallback.html"

Voir aussi#

• Aperçu — système d'inclusion de niveau supérieur
• bext.config.toml — référence complète du fichier de configuration
• API du plugin — enregistrement de résolveurs personnalisés