bedrock-kv / bedrock / 0850df93b9ea4ea28180ff458bb454f490642e5f

82%

Build Type

push

github

Committed by web-flow

Commit Message

302: Make LocalFilesystem version-matched writes atomic (#305)

Concurrent writers holding the same version token could all succeed
against the LocalFilesystem backend, because its compare-and-swap was an
unlocked read, a hash comparison, and a plain rename. Every mutation now
runs inside a small native call that holds a per-directory `flock` while
it re-checks the current bytes and publishes, so one observed version
authorizes at most one replacement, even across independent BEAMs
sharing a root.

Ticket: bedrock-162
Closes #302

## Why

The cluster bootstrap record is replaced through the conditional write,
and the recovery-generation work in #296 (bedrock-7i1) needs that to be
a single-winner operation.

On the base, `put_if_version_matches` read the object, compared its hash
to the token, then renamed the new file over the key. Nothing tied the
rename to the comparison. Eight writers with one token could all pass
the comparison, all rename, and all be told `:ok`, with seven of them
silently overwritten. Issue #302 reproduced this through the public API
(logs `302-red-1.log` through `302-red-5.log` under
`/tmp/bedrock-followups-20260905.zKTZxP/`).

A BEAM-side mutex would not do, since one root is routinely shared by
several VMs, and locking only the CAS path would still let a plain put
or delete slip in between comparison and rename. So every publication
takes an OS lock.

## What changed

- A new NIF, `Native.mutate/5`, performs put, create-only link, CAS
rename, and delete under a per-directory lock; all four mutators route
through it, with no unlocked fallback.
- New errors: `{:error, :invalid_key}` for absolute keys, `.` or `..`
components, or any component under the reserved `.bedrock-lock` prefix;
`{:error, :eloop}` for a symlink target. A malformed token returns
`:version_mismatch` instead of raising.
- Source builds now need a C compiler, make, and OTP headers on Linux or
macOS; `guides/local-filesystem.md` states the filesystem and upgrad... (continued)

Coverage Stats

34 of 37 new or added lines in 2 files covered. (91.89%)

3 existing lines in 2 files now uncovered.

7088 of 8778 relevant lines covered (80.75%)

1153.08 hits per line