Il 2 aprile, beads ha rilasciato v1.0.0. La feature principale era embedded Dolt: un backend zero-config che esegue il database in-process, nessun server separato da gestire. Per gli sviluppatori singoli, era la promessa di bd init e basta. Nessuna porta, nessun daemon, nessuna configurazione.

Abbiamo iniziato ad aggiungere il supporto in Beadbox immediatamente. Sei hotfix, un rollback pubblico e un'immersione profonda nel codice sorgente di bd dopo, siamo usciti dall'altra parte con un layer di resilienza che probabilmente avremmo dovuto costruire mesi fa.

La mattina prima che tutto si rompesse

La giornata è iniziata pulita. Avevamo condotto una caccia al codice morto nella codebase e rilasciato v0.20.0 con 5.350 righe rimosse e un miglioramento di 2 secondi all'avvio a freddo. Quarantadue bead chiusi. Una buona mattina.

Poi abbiamo aggiornato bd alla 0.63.3, la prima release costruita sul backend embedded Dolt di beads v1.0.0.

Beadbox non riusciva a trovare il database. La modalità embedded salva i dati in .beads/embeddeddolt/ invece di .beads/dolt/. Anche il nome del database è cambiato, da beads hardcoded a un prefisso progetto letto da metadata.json. E bd sql, che il nostro server WebSocket usava per il rilevamento modifiche O(1) via DOLT_HASHOF_TABLE, non è supportato in modalità embedded.

Tre assunzioni rotte nei primi dieci minuti.

Sei release in un giorno

Scopri, correggi, rilascia, riscopri.

v0.20.1 ha aggiunto la persistenza delle credenziali tramite il keychain dell'OS (sei bead di lavoro già in corso), corretto un bug del filtro stato personalizzato e patchato problemi specifici di Windows.

v0.20.2 ha insegnato a Beadbox a leggere dolt_database da metadata.json per trovare il database rinominato.

v0.20.3 ha aggiunto le guardie per la modalità embedded. Ogni chiamata a bd sql è stata wrappata con un controllo: se siamo in modalità embedded, fallback al polling CLI invece di query SQL dirette. La funzione getDoltDir ha imparato a cercare prima in embeddeddolt/.

v0.20.4 ha corretto la normalizzazione dei path --db per il layout embedded. I path che funzionavano con la vecchia struttura di directory si rompevano con la nuova.

Ogni fix rivelava il problema successivo.

Il flock

Dopo v0.20.4, pensavamo di essere stabili. Poi abbiamo eseguito un semplice test di concorrenza: cinque chiamate bd list simultanee.

Quattro sono fallite.

Embedded Dolt acquisisce un file lock esclusivo (flock) sul database per l'intera durata di ogni comando. Da PersistentPreRun a PersistentPostRun, nient'altro può toccarlo. Questo è voluto. Senza di esso, l'inizializzazione concorrente del motore causa un nil-pointer panic (beads#2571). Il flock previene il crash. Ma significa anche che in modalità embedded, bd è effettivamente single-process.

Beadbox non è single-process. Il nostro server WebSocket esegue il polling dei cambiamenti ogni secondo. La UI lancia multiple server action al caricamento della pagina. Un utente che naviga nell'app mentre il poller in background è attivo genererà chiamate bd concorrenti. Il flock le blocca tutte tranne la prima.

Il post del blog DoltHub sull'implementazione embedded descriveva il comportamento previsto: i chiamanti concorrenti dovrebbero "accodarsi naturalmente con backoff esponenziale." Ma arch ha esaminato il codice sorgente rilasciato e ha trovato che bd usa TryLock con LOCK_NB (non-bloccante). Non aspetta. Fallisce immediatamente. Ci sono due layer di lock: il flock di bd in alto e il backoff a livello driver di Dolt sotto. Il primo layer cortocircuita il secondo. La logica di retry esiste nella codebase, ma non viene mai eseguita perché il flock rifiuta la connessione prima che il backoff di Dolt abbia la possibilità di attivarsi.

Il fix (lock condivisi per le operazioni di lettura via FlockSharedNonBlock) esiste nel codice sorgente di bd. Semplicemente non è ancora collegato.

Abbiamo fatto rollback

Potevamo continuare a rilasciare hotfix contro un bersaglio mobile, o fare un passo indietro e costruire un layer di resilienza appropriato. Abbiamo fatto un passo indietro.

Tutte le release v0.20.x sono state rimosse dal repo pubblico. v0.19.0 è tornata come versione raccomandata. Abbiamo pubblicato una discussione spiegando cosa era successo e cosa fare, e aggiunto un banner su beadbox.app. Trenta minuti dalla decisione al completamento.

Ogni ora che una release rotta resta pubblica è un'ora in cui qualcuno la scarica, incontra il problema del flock e dà la colpa al prodotto. Preferiamo spiegare un rollback che fare debugging della brutta prima esperienza di qualcun altro.

Non eravamo gli unici

Mentre facevamo debugging, un utente beads di nome Kevin ha pubblicato beads#2938: "Beads feels painful to use." Aveva passato 9,5 ore a fare debugging di problemi che includevano esattamente la confusione embedded-server che stavamo affrontando. L'aggiornamento a v1.0.0 aveva silenziosamente cambiato il suo workspace dalla modalità server alla modalità embedded (beads#2949), nascondendo le sue issue esistenti dietro un database fresco e vuoto.

9,5 ore. Un utente esperto, non un principiante. Se questa è l'esperienza per qualcuno che conosce bene beads, il problema non è l'utente. È il percorso di migrazione.

Cosa abbiamo costruito per v0.21.0

Invece di patchare singoli fallimenti, abbiamo costruito un layer che tratta la contesa dei lock come una condizione operativa normale.

Flock retry con backoff esponenziale. Ogni chiamata al CLI bd ritenta fino a 5 volte, da 100ms a 1,6 secondi tra i tentativi. Vive in un unico punto in lib/bd.ts, quindi ogni comando lo ottiene gratis. Copre il caso comune: due chiamate collidono, una aspetta brevemente, entrambe riescono.

UI di degradazione graduale. La contesa dei lock non significa più una schermata di errore. L'app mostra dati obsoleti con un indicatore di aggiornamento. Se la contesa persiste oltre 30 secondi, un banner ambra spiega la situazione. Quando il lock si libera, il banner scompare e i dati si aggiornano automaticamente.

Suggerimento auto-promote. La contesa ripetuta attiva un suggerimento per migrare alla modalità server: backup, reinizializzazione con --server, ripristino. Un click. Questa è la risposta giusta per chiunque esegua Beadbox insieme ad altri consumatori bd, e ora l'app te lo dice invece di farti scoprire da solo.

Rilevamento modalità embedded. getDoltDir controlla embeddeddolt/ e instrada di conseguenza. Le chiamate bd sql sono protette. La pipeline WebSocket ricade sul polling CLI in modalità embedded (più lento, ma rispetta il vincolo single-process).

Cosa abbiamo imparato

Embedded Dolt è single-process per design. Non è un bug. Il flock previene panic reali. Qualsiasi strumento che consuma un workspace beads in concorrenza deve serializzare l'accesso o funzionare in modalità server. Per Beadbox, la modalità server è il default giusto. Embedded funziona per uso leggero con il layer di retry che assorbe le collisioni occasionali.

La documentazione descriveva l'intento, non l'implementazione. Il blog DoltHub parlava di backoff. Il codice diceva TryLock con LOCK_NB. Abbiamo speso tempo assumendo che le letture concorrenti dovessero funzionare perché la documentazione lo diceva. Leggere il sorgente ha risolto la confusione in pochi minuti. Quando il comportamento non corrisponde alla documentazione, leggi il codice.

Testa la concorrenza prima di rilasciare. Non abbiamo eseguito chiamate bd concorrenti fino a quando v0.20.4 era pubblica. for i in {1..5}; do bd list & done; wait avrebbe catturato il problema del flock prima di qualsiasi release. Cinque secondi di test ci avrebbero risparmiato un rollback.

Fai rollback presto. L'istinto di continuare ad andare avanti è forte. Sei vicino, vedi il fix, ancora una release. Ma ogni release rotta che resta pubblica è un prelievo di fiducia che non puoi facilmente annullare. Tornare a v0.19.0 ci ha dato lo spazio per costruire il layer di resilienza correttamente invece di rilasciarlo in incrementi dettati dal panico.

Controlla le variabili d'ambiente. Abbiamo perso ore perché BEADS_DIR puntava bd al workspace sbagliato. bd stava scoprendo un database diverso da quello che Beadbox monitorava, e i sintomi sembravano corruzione dati. Se i tuoi comandi bd restituiscono risultati inattesi, env | grep BEADS prima di qualsiasi altra cosa.

Situazione attuale

v0.21.0 è uscito con supporto beads v1.0.0, il layer di resilienza e persistenza delle credenziali via keychain dell'OS. La discussione della release ha tutti i dettagli.

Se sei su beads v1.0.0 con modalità embedded e incontri fallimenti intermittenti, il layer di retry di v0.21.0 dovrebbe gestirli. Se esegui Beadbox insieme ad altri strumenti che accedono allo stesso workspace, passa alla modalità server. Il flusso auto-promote lo rende un click.

E se sei Steve o qualcuno del team beads che legge questo: flock condivisi per le letture risolverebbero la causa root a monte. beads#2939 (Unix domain sockets) renderebbe anche le connessioni locali più pulite. Continueremo a costruire intorno a qualsiasi cosa venga rilasciata.

Abbiamo rilasciato il supporto a beads v1.0.0. C'è voluto un rollback, un bug di flock e 6 hotfix.