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.

CommandeEffet
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ÈSCompare-and-set. - pour AVANT veut dire « la clé n’existe pas ».
statusRôle, mandat, leader, index validé, appliqué et dernier, instantané, nombre de fsync et votants, pour chaque nœud.
transfer NDemande au leader de passer la main au nœud N.
add N, remove NAjoute ou retire un votant (un seul changement à la fois).
--nodes A,B,CAdresses 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

OptionDéfautRôle
--id NIdentifiant du nœud, présent dans --peers.
--peers ID=ADDR,…Tous les nœuds et leur adresse entre pairs.
--client ADDRAdresse d’écoute des clients.
--data DIRJournal (WAL avec CRC) et instantanés.
--read-modereadindexlog, readindex ou lease : comment une lecture prouve qu’elle est à jour.
--batch on|offonUn fsync pour toutes les écritures en attente.
--pipeline on|offonPlusieurs AppendEntries en vol par suiveur.
--snapshot-every N10000Instantané toutes les N entrées appliquées.
--tick-ms10Durée d’un tick. Élection après 15 à 30 ticks, battement tous les 3.
--voters 1,2,3tousVotants au départ ; les autres nœuds attendent un add.
--unsafe-no-fsyncPour 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
OptionRôle
--seed N, --seeds A..BUne graine, ou un intervalle.
--threads TGraines en parallèle.
--traceImprime les changements de rôle, les pannes et les réponses aux clients.
--read-modelog, readindex (défaut) ou lease.
--drift FErreur d’horloge maximale par nœud (0,3 = ±30 %).
--membership5 emplacements, votants {1,2,3}, ajouts et retraits pendant les pannes.
--no-crashes, --no-partitionsRetire une famille de pannes.
--duration-ms MSDurée simulée (12 000 par défaut, pannes pendant les 8 premières secondes).
--bug NOMInjecte un bug connu, pour vérifier que les tests l’attrapent.
--stop-on-failure, --json PATHS’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.

CampagneRésultat
Simulation30 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 Jepsen12 runs de 60 s sur de vrais processus, 162 028 opérations, 58 kill -9, 98 coupures, 7 changements de membres : 0 anomalie.
Mutations7 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.

MesureDébitp50p99
Écritures, 64 clients2 295/s26 ms49 ms
Lectures par bail19 656/s3 ms
Lectures ReadIndex12 011/s4,9 ms
Lectures par le journal1 972/s30 ms
Bascule après kill -9 du leader, 3 nœuds268 ms636 ms
Bascule, 5 nœuds228 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.