Contribuer

Ce guide couvre tout ce dont vous avez besoin pour configurer un environnement de développement bext, exécuter la suite de tests et soumettre des modifications.

Conditions préalables#

Outil	Version	Remarques
Rouiller	1,80+ (stable)	Installer via rouiller
Chignon	1.1+	Requis pour les tests d'intégration JS et le développement de sites
Git	2.30+
Linux	Recommandé	Les tests complets des fonctionnalités nécessitent le noyau 5.15+ (eBPF, nsjail)

Facultatif (pour des fonctionnalités spécifiques) :

Outil	Fonctionnalité	Remarques
PHP8.2+	Fonctionnalité `php`	Compilé avec `--enable-embed --enable-zts`
Redis 7+	Fonctionnalité `redis`	Pour les tests de cache L2 et de relais en temps réel
Docker	Tests de conteneurs	Pour les tests d'intégration basés sur des conteneurs
Base de données MaxMind GeoIP	Tests géographiques WAF	Base de données GeoLite2-Pays
cible wasm32-wasi	Tests du plugin WASM	`rustup target add wasm32-wasi`

Commencer#

bash

git clone https://github.com/bext-dev/bext.git
cd bext

Créer l'édition communautaire (la plus rapide)#

bash

cargo build -p bext-server

Construire avec toutes les fonctionnalités#

bash

cargo build -p bext-server --all-features

Construire un binaire de version#

bash

cargo build --release -p bext-server

Le profil de version utilise opt-level = 3, Fat LTO, une seule unité de codegen et la suppression de symboles. Attendez-vous à environ 3 minutes pour une version complète sur un MacBook Pro M2.

Structure du projet#

code

bext/
  Cargo.toml           # Workspace root
  crates/              # Rust library and binary crates (~38 crates)
  harnesses/           # Conformance, ecosystem, and security test suites
  companion/           # Desktop companion app (Tauri + Svelte)
  sites/               # bext.dev ecosystem sites (docs, blog, main, etc.)
  docs/                # Internal platform documentation

Voir Présentation de l'architecture pour le graphique complet des dépendances de caisse.

Le référentiel frère tsc-rs#

L'interface TypeScript /TSX est un référentiel distinct, ts-rs (le compilateur tsc-rs). bext-core dépend de son tsc_rs_parser / tsc_rs_ast / tsc_rs_emitter / tsc_rs_symbols est créé en tant que dépendances git épinglées, et la racine de l'espace de travail Cargo.toml contient un [patch] qui les redirige vers ../ts-rs:

code

parent/
  bext/        # this repo
  ts-rs/       # checked out alongside → [patch] uses it automatically

Si vous extrayez ts-rs à côté de bext, les builds utilisent votre arborescence de travail locale, donc les modifications apportées à l'analyseur, à l'AST ou à l'émetteur prennent effet le prochain cargo build. Sans l'extraction frère, Cargo récupère la révision épinglée depuis git et le correctif n'est pas opérationnel. Le sous-processus tsc-rs --pipe bext apparaît lors de l'exécution et se résout en binaire tsc-rs construit à partir de cette même arborescence - voir Pipeline de rendu PRISM pour savoir comment le binaire et les caisses de bibliothèque sont chacun utilisés.

Exécution de tests#

Tests unitaires (toutes les caisses)#

bash

cargo test --workspace

Tests unitaires pour une caisse spécifique#

bash

cargo test -p bext-core
cargo test -p bext-plugin-api
cargo test -p bext-waf
cargo test -p bext-license

Tests avec toutes les fonctionnalités activées#

bash

cargo test --workspace --all-features

Ceci est nécessaire pour les tests WAF, plugin, eBPF et PHP, car ces modules se trouvent derrière les indicateurs de fonctionnalités.

Essai spécifique#

bash

cargo test -p bext-license -- roundtrip_early_bird --nocapture

Tests d'intégration#

bash

# Next.js conformance suite
cargo test -p conformance

# Framework ecosystem tests (requires Bun + Node)
cd harnesses/ecosystem && bun test

# Security / fuzzing harness
cargo test -p security

Tests sandbox des plugins#

bash

# QuickJS plugin tests
cargo test -p bext-plugin-quickjs

# WASM plugin tests (requires wasm32-wasi target)
cargo test -p bext-plugin-wasm

# nsjail plugin tests (Linux only)
cargo test -p bext-plugin-nsjail

Organisation du code#

L’espace de travail suit une discipline stricte de superposition :

Les caisses à feuilles ( bext-plugin-api, bext-license ) n'ont pas de dépendances bext et des dépendances externes minimes. Ils définissent des traits et des types.
Les caisses de fonctionnalités ( bext-tls, bext-waf, bext-realtime, bext-ebpf, bext-php, bext-plugin-* ) implémentent des fonctionnalités spécifiques. Ils peuvent dépendre de caisses de feuilles.
Core crate ( bext-core ) contient une logique métier partagée. Cela dépend des caisses feuilles mais pas des caisses de fonctionnalités (sauf via les fonctionnalités Cargo).
Les caisses binaires ( bext-server, bext-keygen, bext-nginx-shim ) connectent le tout ensemble. Ils dépendent de toutes les autres caisses via des indicateurs de fonctionnalités.

Lorsque vous ajoutez un nouveau code, placez-le dans la couche appropriée la plus basse. Si un type doit être partagé entre des caisses de fonctionnalités, placez-le dans bext-plugin-api ou bext-core.

Style de code#

Exécutez cargo fmt avant de valider.
Exécutez cargo clippy --workspace --all-features et corrigez tous les avertissements.
Suivez les modèles existants dans la caisse que vous modifiez.
Ajoutez des commentaires de document ( /// ou //! ) à tous les nouveaux types, fonctions et modules publics.
bext propose plus de 2 500 tests : ajoutez des tests pour toute nouvelle fonctionnalité.

Format du message de validation#

Suivez les commits conventionnels :

code

feat(waf): add custom rule DSL for request matching

Add a declarative rule format that lets users define WAF rules
in bext.config.toml without writing Rust code.

Closes #142

Préfixes : feat, fix, docs, refactor, test, perf, ci, chore.

La portée entre parenthèses doit être un nom de caisse ou une zone (par exemple, waf, cache, render, cli, docs, plugin-quickjs ).

Directives pour les demandes de tirage#

Une préoccupation selon le PR : ne mélangez pas une correction de bogue avec une fonctionnalité.
Ajoutez des tests pour tout nouveau comportement.
Mettez à jour les documents si vous modifiez le comportement face à l'utilisateur.
Exécutez la suite de tests complète avant de pousser : cargo test --workspace --all-features.
Gardez les PR petits - moins de 500 lignes modifiées lorsque cela est possible.

Liste de contrôle avant de soumettre#

cargo test --workspace --all-features passe
cargo clippy --workspace --all-features -- -D warnings ne signale aucun avertissement
cargo fmt --check passe
Les nouveaux types publics ont des commentaires doc
Le code basé sur les fonctionnalités utilise correctement #[cfg(feature = "...")]
Aucune nouvelle dépendance ajoutée sans justification dans la description du PR

Processus de révision#

Ouvrez un PR contre master.
CI gère le pipeline complet (voir ci-dessous).
Une approbation du responsable requise pour la fusion.
La fusion Squash est la valeur par défaut. Utilisez les validations de fusion uniquement pour les grandes branches de fonctionnalités avec des validations intermédiaires significatives.

Ajout d'un nouvel indicateur de fonctionnalité#

Si votre contribution ajoute un nouveau sous-système facultatif :

Créez la caisse dans crates/bext-your-feature/.
Ajoutez la dépendance en option dans crates/bext-server/Cargo.toml :

toml

bext-your-feature = { path = "../bext-your-feature", optional = true }

Définissez la fonctionnalité dans [features] :

toml

[features]
your-feature = ["dep:bext-your-feature"]

Initialisation de la garde avec #[cfg(feature = "your-feature")] dans main.rs et tous les modules faisant référence à la caisse.
Ajoutez un nom de fonctionnalité de licence dans crates/bext-license/src/tier.rs.
Ajoutez la fonctionnalité à la liste des fonctionnalités du niveau approprié (Communauté, Pro ou Entreprise).
Ajoutez un mappage cargo_feature_to_license.
Exécutez les tests du sur-ensemble de niveau : cargo test -p bext-license.

Pipeline CI#

Chaque PR exécute :

Emploi	Ce que ça fait	Durée
`fmt`	`cargo fmt --check`	~5s
`clippy`	`cargo clippy --workspace --all-features -- -D warnings`	~2 minutes
`test`	`cargo test --workspace --all-features`	~4 minutes
`build`	`cargo build --release -p bext-server`	~3 minutes
`conformance`	Tests de spécifications Next.js sur le serveur bext	~3 minutes
`ecosystem`	Tests d'intégration pour Next.js, Hono, Express, Laravel, Symfony, PHP	~5 minutes
`security`	Tests d'évasion Sandbox + courte exécution de fuzzing	~2 minutes

Les versions de version produisent également des binaires pour Linux (x86_64, aarch64) et macOS (aarch64).

Conseils de débogage#

Activer la journalisation des traces#

bash

RUST_LOG=bext_server=trace,bext_core=debug cargo run

Profiler une transformation spécifique#

bash

cargo test -p bext-core transform::barrel_optimize -- --nocapture

Inspecter l’activité du bac à sable du plugin#

bash

BEXT_PLUGIN_LOG=trace cargo run --features plugins

Exécuter un seul test de conformité#

bash

cargo test -p conformance test_name -- --nocapture

Conseil

Exécutez cargo test --workspace --all-features avant d'ouvrir un PR — certains tests (WAF, eBPF, plugins) ne sont compilés et exécutés que lorsque leurs indicateurs de fonctionnalité sont activés. Le travail CI test utilise --all-features ; les échecs locaux sous --no-default-features ne garantissent pas une exécution verte du CI.

Obtenir de l'aide#

Problèmes : github.com/ bext -dev/ bext /issues
Discussions sur : github.com/ bext -dev/ bext /discussions

En rapport#

Présentation de l'architecture — disposition de l'espace de travail et graphique des dépendances de la caisse
Référence de caisse — listes de modules par caisse, indicateurs de fonctionnalités et règles de superposition
Frontend TypeScript (tsc-rs) — le dépôt frère ts-rs et comment le développer localement
Pipeline de rendu PRISM — le chemin de bout en bout auquel la plupart des nouvelles fonctionnalités touchent
Indicateurs de construction et de fonctionnalités — comment Cargo propose des sous-systèmes de porte en CI et en production
Extensions — comment ajouter de nouveaux points d'extension sans toucher à bext-server