Plugins WASM

Le niveau WASM exécute des plugins en tant que modules WebAssembly dans le runtime wasmtime. Il offre des performances quasi natives avec une forte isolation de la mémoire et des limites de ressources déterministes via les budgets de carburant. Il s'agit d'une fonctionnalité Pro.

Comment ça marche#

1. Vous écrivez votre plugin dans Rust (ou Go/C) et le compilez dans un module .wasm ciblant wasm32-wasi.
2. bext charge le module via wasmtime au démarrage du serveur.
3. Chaque appel de cycle de vie consomme du « carburant » – une abstraction de temps d’eau qui limite les calculs. Lorsque le carburant est épuisé, l'appel est terminé.
4. Les fonctions hôtes du module d'importation "bext" fournissent le stockage, HTTP, les métriques et l'accès à la file d'attente.

Budgets de carburant#

Chaque hook de cycle de vie a un budget de carburant par défaut. Une unité de carburant correspond à peu près à une instruction WASM.

Remplacer les budgets dans bext.config.toml :

[plugins.my-wasm-plugin]
sandbox = "wasm"
path = "./plugins/my-plugin.wasm"

[plugins.my-wasm-plugin.fuel]
on_server_start = 1_000_000_000
on_request_complete = 200_000_000

Importations de fonctions hôtes#

Les plugins WASM accèdent aux fonctionnalités de l'hôte via des fonctions importées du module "bext". Tous les types complexes sont transmis sous forme de chaînes codées JSON via des paires (ptr, len).

Fonctions hôtes disponibles#

La requête et la réponse http_fetch utilisent ce format JSON :

// Request
{ "url": "https://api.example.com/data", "method": "POST",
  "headers": [["Content-Type", "application/json"]], "body": "{}" }

// Response
{ "status": 200,
  "headers": [["content-type", "application/json"]],
  "body": "{\"result\": \"ok\"}" }

Autorisations du bac à sable#

[plugins.my-wasm-plugin.permissions]
allowed_urls = ["https://api.example.com/*"]
storage_quota_kb = 1024
max_fetch_per_minute = 30
kv_namespaces = ["analytics"]
queue_names = ["events"]

• Allowed_urls — modèles globaux pour HTTP sortant. Vide = pas d'accès au réseau.
• storage_quota_kb — stockage KV maximum par plugin (par défaut : 1 024 Ko).
• max_fetch_per_minute — limite de débit de compartiment de jetons pour les récupérations HTTP (par défaut : 30).
• kv_namespaces — espaces de noms KV partagés auxquels le plugin peut accéder. Vide = limité au plugin uniquement.
• queue_names — files d'attente de messages sur lesquelles le plugin peut publier ou consommer.

Construire un plugin Rust WASM#

1. Créez le projet#

cargo new --lib my-analytics-plugin
cd my-analytics-plugin

2. Configurez Cargo.toml#

[package]
name = "my-analytics-plugin"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]
bext-plugin-api = "0.1"
serde = { version = "1", features = ["derive"] }
serde_json = "1"

3. Implémentez le trait LifecyclePlugin#

use bext_plugin_api::lifecycle::LifecyclePlugin;
use serde::Deserialize;

#[derive(Deserialize)]
struct Config {
    endpoint: String,
    batch_size: usize,
}

struct AnalyticsPlugin {
    config: Option<Config>,
    buffer: Vec<String>,
}

impl LifecyclePlugin for AnalyticsPlugin {
    fn name(&self) -> &str {
        "my-analytics"
    }

    fn priority(&self) -> u32 {
        1000
    }

    fn on_server_start(&self, config_json: &str) -> Result<(), String> {
        let config: Config = serde_json::from_str(config_json)
            .map_err(|e| format!("parse config: {e}"))?;
        // Store config for later use
        bext::log("info", &format!("Analytics endpoint: {}", config.endpoint));
        Ok(())
    }

    fn on_request_complete(&self, event_json: &str) -> Result<(), String> {
        // Buffer events, flush when batch is full
        bext::storage_set("pending", event_json)?;
        bext::emit_metric("analytics_events", 1.0, &[("source", "wasm")]);
        Ok(())
    }

    fn cleanup(&self) -> Result<(), String> {
        bext::log("info", "Flushing remaining analytics events");
        Ok(())
    }
}

4. Compiler vers WASM#

cargo build --target wasm32-wasi --release
cp target/wasm32-wasi/release/my_analytics_plugin.wasm ./plugin.wasm

5. Configurer dans bext#

[plugins.my-analytics]
sandbox = "wasm"
path = "./plugins/my-analytics/plugin.wasm"

[plugins.my-analytics.config]
endpoint = "https://analytics.example.com/ingest"
batch_size = 100

[plugins.my-analytics.permissions]
allowed_urls = ["https://analytics.example.com/*"]
max_fetch_per_minute = 60

Débogage des plugins WASM#

Activez la journalisation WASI pour voir stdout/stderr depuis votre module WASM :

BEXT_PLUGIN_LOG=debug bext dev

Les interruptions wasmtime (manque de carburant, violations de mémoire, instructions inaccessibles) sont enregistrées avec une trace de pile complète lorsque la journalisation du débogage est activée.

Pour profiler la consommation de carburant :

bext plugin stats my-analytics

Cela rapporte la consommation de carburant par crochet, le nombre d'appels et le temps d'exécution moyen.

Plugins Go et C#

Tout langage compilé en wasm32-wasi fonctionne. Pour Go, utilisez TinyGo :

tinygo build -o plugin.wasm -target=wasi ./main.go

Pour C, utilisez wasi-sdk :

$WASI_SDK_PATH/bin/clang --sysroot=$WASI_SDK_PATH/share/wasi-sysroot \
  -o plugin.wasm plugin.c

La fonction hôte ABI est la même quelle que soit la langue source : chaînes JSON transmises via des paires (ptr, len).

En rapport#

• Présentation du système de plugins — Architecture sandbox à trois niveaux et types de fonctionnalités
• Construire un plugin — échafaudez et testez votre premier plugin
• Plugins Python — Python via Pyodide dans le runtime WASM
• Plugins V8 — Alternative JavaScript à WASM pour le middleware hot-path
• Plugins nsjail — lorsque vous avez besoin d'un espace utilisateur Linux complet au lieu de WASM
• Édition — partagez votre plugin sur le registre

Links#

• WebAssembly WASI aperçu 1 — l'appel système ABI wasm32-wasi cible
• c'était l'heure — le runtime WebAssembly bext intègre
• PetitGo — Compilateur Go qui cible wasm32-wasi