Documentation
Mbolo tient en trois binaires : mbolo-node fait tourner un nœud, mbolo-cli lui parle, mbolo-sim rejoue le simulateur des tests.
Installer
Le script détecte le système et le processeur, télécharge l’archive depuis assets.zaleo.dev, vérifie sa somme SHA-256 puis copie les binaires dans ~/.local/bin.
$ curl -fsSL https://mbolo.zaleo.dev/install.sh | sh $ mbolo-cli --version mbolo-cli 0.1.0
Deux variables changent son comportement : MBOLO_INSTALL_DIR (le dossier cible) et MBOLO_VERSION. À la main :
$ curl -fsSLO https://assets.zaleo.dev/mbolo/0.1.0/mbolo-0.1.0-linux-x86_64.tar.gz $ curl -fsSLO https://assets.zaleo.dev/mbolo/0.1.0/SHA256SUMS $ sha256sum -c --ignore-missing SHA256SUMS mbolo-0.1.0-linux-x86_64.tar.gz: OK
Les archives Linux sont statiques (musl) : elles tournent sur toute distribution. Pour désinstaller, supprimez ~/.local/bin/mbolo-*.
Lancer un cluster
--peers liste tous les nœuds et leur adresse entre pairs ; l’entrée de son propre identifiant est l’adresse où le nœud écoute. --client est l’adresse des clients, --data le dossier du journal.
$ P=1=127.0.0.1:7001,2=127.0.0.1:7002,3=127.0.0.1:7003 $ for i in 1 2 3; do mbolo-node --id $i --peers $P --client 127.0.0.1:800$i --data mbolo/n$i 2>/dev/null & done $ mbolo-cli status $ pkill mbolo-node # tout arrêter ; les données restent dans mbolo/
Pour cinq nœuds, ajoutez 4=…:7004,5=…:7005 à P, bouclez jusqu’à 5 et donnez au client les cinq adresses avec MBOLO_NODES. Sur plusieurs machines, remplacez 127.0.0.1 par les vraies adresses : les échanges ne sont ni chiffrés ni authentifiés, gardez-les sur un réseau privé.
mbolo-cli
Le client essaie les nœuds dans l’ordre, suit les redirections vers le leader et renvoie la même requête (même numéro de séquence) en cas d’échec : une écriture n’est jamais appliquée deux fois.
| Commande | Effet |
|---|---|
get CLÉ | Lecture linéarisable. Affiche la valeur, ou (nil). |
put CLÉ VALEUR | Écrit la valeur. Affiche OK une fois validée par une majorité. |
cas CLÉ AVANT APRÈS | Compare-and-set. - pour AVANT veut dire « la clé n’existe pas ». |
status | Rôle, mandat, leader, index validé, appliqué et dernier, instantané, nombre de fsync et votants, pour chaque nœud. |
transfer N | Demande au leader de passer la main au nœud N. |
add N, remove N | Ajoute ou retire un votant (un seul changement à la fois). |
--nodes A,B,C | Adresses clients des nœuds. Sinon MBOLO_NODES, sinon 127.0.0.1:8001-8003. |
Si une commande échoue avec « may or may not have been applied », le cluster n’a pas répondu à temps : l’opération a pu être appliquée ou non. Relisez avant de réessayer.
mbolo-node
| Option | Défaut | Rôle |
|---|---|---|
--id N | Identifiant du nœud, présent dans --peers. | |
--peers ID=ADDR,… | Tous les nœuds et leur adresse entre pairs. | |
--client ADDR | Adresse d’écoute des clients. | |
--data DIR | Journal (WAL avec CRC) et instantanés. | |
--read-mode | readindex | log, readindex ou lease : comment une lecture prouve qu’elle est à jour. |
--batch on|off | on | Un fsync pour toutes les écritures en attente. |
--pipeline on|off | on | Plusieurs AppendEntries en vol par suiveur. |
--snapshot-every N | 10000 | Instantané toutes les N entrées appliquées. |
--tick-ms | 10 | Durée d’un tick. Élection après 15 à 30 ticks, battement tous les 3. |
--voters 1,2,3 | tous | Votants au départ ; les autres nœuds attendent un add. |
--unsafe-no-fsync | Pour comparer en benchmark seulement : perd des écritures validées en cas de panne. |
Changer les membres
Démarrez quatre nœuds dont trois votants, puis ajoutez le quatrième et retirez le premier. Un deuxième changement est refusé tant que le premier n’est pas validé.
$ P=1=127.0.0.1:7001,2=127.0.0.1:7002,3=127.0.0.1:7003,4=127.0.0.1:7004 $ for i in 1 2 3 4; do mbolo-node --id $i --peers $P --client 127.0.0.1:800$i --data mbolo/n$i --voters 1,2,3 2>/dev/null & done $ export MBOLO_NODES=127.0.0.1:8001,127.0.0.1:8002,127.0.0.1:8003,127.0.0.1:8004 $ mbolo-cli add 4 $ mbolo-cli remove 1
mbolo-sim
Le simulateur fait tourner le même code serveur que mbolo-node, mais le temps, le réseau et le disque sont simulés à partir d’une graine. Une graine décrit toute une exécution : un échec se rejoue à l’identique.
$ mbolo-sim --seeds 0..200 --threads 4 seeds: 200 failed: 0 conf changes: 0 wall: 1.1s (174.5 seeds/s) simulated: 3156082 events, 1544507 messages (133341 dropped), 858 crashes (465 torn), 600 partitions, 1076 elections, 162074 client ops ok, 1 indeterminate $ mbolo-sim --seeds 0..2000 --bug read-without-quorum --stop-on-failure FAIL seed 19: t=11999ms: linearizability violation on keys ["k0"] (976 ops) replay: mbolo-sim --seed 19 --bug read-without-quorum --trace
| Option | Rôle |
|---|---|
--seed N, --seeds A..B | Une graine, ou un intervalle. |
--threads T | Graines en parallèle. |
--trace | Imprime les changements de rôle, les pannes et les réponses aux clients. |
--read-mode | log, readindex (défaut) ou lease. |
--drift F | Erreur d’horloge maximale par nœud (0,3 = ±30 %). |
--membership | 5 emplacements, votants {1,2,3}, ajouts et retraits pendant les pannes. |
--no-crashes, --no-partitions | Retire une famille de pannes. |
--duration-ms MS | Durée simulée (12 000 par défaut, pannes pendant les 8 premières secondes). |
--bug NOM | Injecte un bug connu, pour vérifier que les tests l’attrapent. |
--stop-on-failure, --json PATH | S’arrêter au premier échec ; écrire le résumé en JSON. |
Tests et mesures
Après chaque étape simulée, quatre invariants de Raft sont vérifiés : un seul leader par mandat, journaux cohérents, leader complet, entrées validées immuables. À la fin, chaque opération client est vérifiée linéarisable (recherche de Wing-Gong-Lowe, par clé), les répliques doivent converger et le cluster doit recommencer à répondre.
| Campagne | Résultat |
|---|---|
| Simulation | 30 000 graines, 0 échec ; 135 860 crashs dont 77 608 au milieu d’une écriture, 89 031 coupures, dérive d’horloge jusqu’à ±50 %. |
| Façon Jepsen | 12 runs de 60 s sur de vrais processus, 162 028 opérations, 58 kill -9, 98 coupures, 7 changements de membres : 0 anomalie. |
| Mutations | 7 bugs plantés sur 8 attrapés. Le bug de la figure 8 ne l’est jamais en 20 000 graines : le no-op du nouveau leader le masque. |
Performances
3 nœuds sur un i7-10510U (4 cœurs, WSL2, ext4 sur disque virtuel), chaque écriture fsyncée sur le leader et un suiveur. Médianes de 3 runs.
| Mesure | Débit | p50 | p99 |
|---|---|---|---|
| Écritures, 64 clients | 2 295/s | 26 ms | 49 ms |
| Lectures par bail | 19 656/s | 3 ms | |
| Lectures ReadIndex | 12 011/s | 4,9 ms | |
| Lectures par le journal | 1 972/s | 30 ms | |
Bascule après kill -9 du leader, 3 nœuds | 268 ms | 636 ms | |
| Bascule, 5 nœuds | 228 ms |
Les binaires publiés ne contiennent pas le banc Jepsen ni les benchmarks. Le code source est privé pour l’instant ; écrivez à [email protected] pour y accéder.