vole

Clone

Read only, no credentials:

https://rodent.software/vole.git

Write over SSH with a registered key:

git clone ssh://git@rodent.software:2222/vole.git

A free and open-source forge that lives in your Git repo.

Metadata writers queue on the branch instead of racing for it

122cbe4f62bf87a941538450584ba1b20444c135 · Keenan Nemetz · 7d ago · parent 4739664b

Metadata writers queue on the branch instead of racing for it

Every write to refs/heads/vole read the whole branch, decided, and moved the
ref with a compare-and-swap, retrying up to 64 times with no backoff and no
coordination. Concurrent writers therefore did not queue: they each paid a full
read, lost, and paid it again. Measured on a 2,000-file branch, one write needed
one attempt alone and 21 with 32 writers, and throughput fell as writers were
added because the retries were the load. At 64 simultaneous writers the loop ran
out and the write failed for being unlucky.

The read-modify-write now runs with one writer at a time, holding a flock in the
repository so the SSH hook and the server queue behind each other. The
compare-and-swap stays for writers that go around the lock — a push, a hand-run
git command, another host — and losing one now waits with jittered backoff
before deciding again.

Writers read the branch once. The load and the decision happen inside the commit
instead of before it, which also stops an edit from replacing a change that
landed while the page was open: the decision is made against the tree it writes.

A push only does that work when it has metadata to move. Post-receive asks the
index which open requests follow the branch it moved, and a branch nobody is
proposing from now writes an audit line and no commit.

Measurements, 32 concurrent writers: 21.3 CAS attempts per write before, 1.0
after. Through the web, posting comments at concurrency 32: p99 4.7 s -> 0.95 s,
and throughput no longer falls as workers are added. The load harness gains a
`comment` scenario so the number is visible.

Closes: 01M6D9G8H6E0RCQ3AD5TMAGX34

docs/architecture.md +14

@@ -78,6 +78,20 @@ already did. Every read still checks the branch it was built from — reading th
	78	78	loose ref, which is a file, rather than starting a process — and repairs the rows
	79	79	if a hook did not run. `vole admin index rebuild` is the last resort.
	80	80
		81	Writers of that branch take turns. A write reads the branch, decides, and moves the
		82	ref only if nobody else moved it first, so two people commenting at the same time
		83	cannot lose either comment; the price of that safety is that a writer which loses
		84	the race reads the branch again. Under load that price is the whole cost, so writers
		85	of one repository queue behind each other instead: the read, the decision, and the
		86	ref move happen while one writer holds the branch, and the compare-and-swap is left
		87	for a push or a hand-run git command that could not wait.
		88
		89	A push only queues behind those writers when it has metadata to move. Most do not:
		90	a branch becomes interesting to a change request when one is opened from it, and
		91	post-receive asks the index which open requests follow the branch before it reads
		92	the metadata branch at all. A push to a branch nobody is proposing from therefore
		93	writes an audit line and nothing else.
		94
	81	95	The `vole` branch contains:
	82	96
	83	97	```text