Building a Raft KV Store

Fri, 14 Aug 2026 00:00:00 GMT

I set out to write a Raft implementation because I wanted to understand the paper, not because the world needed another one. What I got instead was three weeks of staring at logs from a five-node cluster that would elect a leader, run happily for a few minutes, and then quietly stop making progress.

##The symptom

Under a clean run everything worked. The failure only appeared once I started partitioning nodes at random. The cluster would settle into a state where every node believed a leader existed, but no entries were being committed.

Node	Term	State	Commit index
n1	14	leader	812
n2	14	follower	812
n3	15	candidate	809
n4	15	candidate	809
n5	14	follower	812

Two nodes stuck as candidates in a higher term, three nodes happily following a leader from the previous one. Nobody was wrong, exactly. Everybody was stale.

##The tick loop

Here is the shape of the code that caused it:

func (r *Raft) tick() {
	r.mu.Lock()
	defer r.mu.Unlock()

	r.elapsed++
	if r.state == Leader {
		if r.elapsed >= r.heartbeatTimeout {
			r.elapsed = 0
			r.broadcastAppendEntries()
		}
		return
	}
	if r.elapsed >= r.electionTimeout {
		r.elapsed = 0
		r.becomeCandidate()
	}
}

The bug is not in this function. The bug is that broadcastAppendEntries sent RPCs while holding r.mu, and the RPC layer blocked on a partitioned peer. The leader's tick loop stalled, heartbeats stopped, and the two reachable followers timed out and started an election that they could never win — because the partition kept them from reaching a quorum.

##The fix

Never hold a lock across a network call. It is the oldest advice in the book, and I still had to rediscover it the hard way.

The repair was to snapshot the state under the lock, release it, and only then talk to the network:

func (r *Raft) broadcastAppendEntries() {
	peers, term, entries := r.snapshotForReplication()
	r.mu.Unlock()
	defer r.mu.Lock()

	for _, p := range peers {
		go r.sendAppendEntries(p, term, entries)
	}
}

One line of real change. Three weeks to find it.

##What I would do differently

Write the partition test first. The happy path proves nothing.
Log the full cluster state on every term change, not just on errors.
Treat any lock held for more than a millisecond as a bug worth explaining.

If you want to read the paper that started all this, it is In Search of an Understandable Consensus Algorithm, and it is genuinely as readable as it claims to be.

Why I Rewrote My Nvim Config

Sat, 02 May 2026 00:00:00 GMT

My init.lua had grown to just over two thousand lines. I could not have told you what half of it did. Every plugin I had ever been curious about was still in there, disabled by a commented-out line I was afraid to delete.

##The rule I gave myself

One rule: every line has to earn its place. If I could not explain what a setting did and why I wanted it, it did not survive the rewrite.

That killed about sixty percent of the config immediately.

##Structure

The old config was one file. The new one is a directory where each module owns exactly one concern:

-- lua/config/lazy.lua
require("lazy").setup({
  spec = { { import = "plugins" } },
  defaults = { lazy = true },
  install = { colorscheme = { "catppuccin" } },
  checker = { enabled = false },
})

Each plugin gets its own file under lua/plugins/, returning a spec table. Adding a plugin is creating a file. Removing one is deleting a file. There is no central list to keep in sync, which is where the old config rotted.

##What I actually kept

telescope.nvim — the only fuzzy finder I have never wanted to replace.
nvim-treesitter — worth it for textobjects alone.
neo-tree.nvim — I use it perhaps once a day, and that once matters.
lualine.nvim — mostly for the mode indicator.
catppuccin — mocha at night, latte when the sun is out.

##What I dropped

Every completion plugin except one. Every "productivity" plugin I had installed after reading a blog post and never opened again. Three separate git integrations.

The result is around four hundred lines, and I can explain all of them. Startup went from 180ms to 41ms, which was not the point, but I will take it.

The best config is the one you can delete from confidently.

Harikeshav Rameshkumar — blog