Présentation du système de plugins

bext est livré avec un système de plugins qui vous permet d'étendre le serveur à trois niveaux : middleware de requête/réponse, transformations de code source et hooks de cycle de vie du serveur. Chaque plugin s'exécute dans un bac à sable et vous choisissez parmi trois niveaux d'isolation en fonction de vos exigences en matière de performances, de sécurité et de flexibilité.

Trois niveaux d'isolement#

QuickJS — Bac à sable JS léger#

Le niveau par défaut. Incorpore le moteur QuickJS via rquickjs pour exécuter JavaScript dans un bac à sable à mémoire limitée et à durée limitée. Les plugins bénéficient d'une surface API contrôlée ( bext.storage, bext.fetch, bext.config, bext.metric ) sans système de fichiers direct ni accès réseau. Idéal pour les scripts fournis par le locataire pour lesquels vous ne souhaitez aucune surcharge de démarrage à froid.

WASM — bac à sable wasmtime#

Compilez votre plugin dans Rust, Go ou C dans un module .wasm. bext le charge via wasmtime avec des budgets de carburant configurables par appel de cycle de vie (par exemple, 100 M de carburant pour on_request_complete, 500 M pour on_server_start ). Les fonctions hôtes sont exposées sous le module d'importation "bext" pour le stockage, la récupération HTTP, les métriques et l'accès aux files d'attente. Ce niveau vous offre une vitesse quasi native avec de solides garanties d’isolation.

nsjail — Isolation au niveau du processus#

Exécutez n'importe quel exécutable (Python, Ruby, binaires compilés) en tant que processus enfant avec JSON-over-stdio IPC. Sous Linux avec root, bext applique l'isolation de l'espace de noms PID/NET/MOUNT, les limites du groupe de contrôle et les filtres seccomp. Sans racine, les plugins s'exécutent toujours en tant que processus distincts avec des délais d'attente stdio et wall-clock. Idéal lorsque WASM et QuickJS sont trop restrictifs.

Capacités du plugin#

Les plugins déclarent les fonctionnalités qu'ils fournissent dans leur manifeste :

# plugin.toml
[manifest]
name = "rate-limiter"
version = "1.0.0"
capabilities = ["middleware"]

Les quatre types de capacités sont :

• Middleware — intercepte les requêtes ( on_request ) et modifie les réponses ( on_response ). Peut court-circuiter avec une réponse personnalisée.
• Transform — réécrivez le code source au moment de la construction. S'exécute par ordre de priorité aux côtés des 14 transformations intégrées de bext.
• Cycle de vie  : recevez des notifications au démarrage, à l'arrêt du serveur, aux écritures dans le cache, aux invalidations du cache, aux rechargements ISR et à l'achèvement des demandes.
• CacheBackend — fournit un backend de stockage de cache personnalisé.

Cycle de vie des plugins#

Chaque plugin suit le même cycle de vie quel que soit le niveau sandbox :

1. Init — bext lit plugin.toml, valide le manifeste et charge le plugin dans son bac à sable. Le plugin reçoit sa section de configuration de bext.config.toml.
2. on_server_start — appelé une fois après l'initialisation de tous les sous-systèmes. Utilisez-le pour configurer des connexions, des caches chauds ou enregistrer des métriques.
3. on_request / on_response — appelé à chaque requête HTTP pour les plugins middleware. on_request s'exécute avant le routage ; on_response s'exécute après que le gestionnaire ait produit une réponse.
4. on_request_complete — se déclenche de manière asynchrone après l'envoi de la réponse. Reçoit le chemin, la méthode, l’état, l’état du cache, l’heure de rendu et les informations sur le locataire.
5. on_cache_write / on_cache_invalidate — Événements de cache ISR pour l'analyse ou la synchronisation du cache.
6. on_reload — se déclenche après un rechargement réussi du pool V8 (nouveau bundle déployé).
7. Nettoyage — appelé lors d'un arrêt progressif. Libérez les ressources ici.

Pile de priorités middleware#

Le middleware intégré s'exécute avec des priorités fixes. Le middleware du plugin a par défaut la priorité 600 (après tous les éléments intégrés) :

Définissez une priorité personnalisée dans la configuration de votre plugin pour qu'elle s'exécute plus tôt ou plus tard dans la pile.

Registre des plugins#

Découvrez et installez les plugins communautaires de plugins. bext.dev :

bext plugins install security-headers
bext plugins install geo-redirect

Les plugins installés sont configurés dans bext.config.toml :

[plugins.security-headers]
sandbox = "quickjs"

[plugins.security-headers.config]
hsts_max_age = 31536000
x_frame_options = "DENY"

Quand utiliser quel niveau#

• QuickJS : vous avez besoin d'une simple interception de requêtes, de transformations de données ou de gestionnaires de webhook, et votre plugin est écrit en JavaScript.
• WASM : vous avez besoin de performances maximales avec une forte isolation, et vous pouvez compiler votre code sur WebAssembly.
• nsjail : vous devez exécuter des outils et des scripts existants dans n'importe quel langage ou gérer du code tiers non fiable avec une isolation complète au niveau du système d'exploitation.

Voir les pages dédiées à chaque niveau : QuickJS, WASM, nsjail.

En rapport#

• Construire un plugin — guide étape par étape pour échafauder votre premier plugin
• Plugins QuickJS — référence API complète pour le bac à sable JS intégré
• Plugins WASM — compilez Rust/Go/C vers WebAssembly pour une vitesse quasi native
• Plugins V8 — partagez le moteur V8 existant de bext avec votre plugin
• Plugins Lua — scripts rechargeables à chaud avec une empreinte mémoire minime
• Plugins nsjail — isolation complète au niveau du processus pour le code non fiable
• Édition — partager des plugins sur le registre