Expand description
Crash-safe write helper used by agents.lock, agents.yml, and the
federated-registry response cache.
The pattern is: write the body to <path>.tmp and rename it into
place. POSIX rename(2) is atomic within the same filesystem, and on
Windows std::fs::rename lowers to MoveFileExW(MOVEFILE_REPLACE_EXISTING)
which is also atomic for files. Either way: a crash mid-write leaves
the destination either untouched or fully written, never half.
Why bother. The previous fs::write(path, body) path could leave a
corrupt agents.lock on disk if the process died after open but
before the last byte hit. A corrupt lockfile fails the next pakx install / pakx test hard rather than self-healing — exactly the
scenario the user least wants to debug.
Permission bits are NOT set here. The ~/.pakx/credentials.json
writer needs 0600 and handles that itself via OpenOptions::mode
at the open call (see credentials::Credentials::write_to) —
mode-at-open is the only atomic way to get sensitive bits onto disk.
For everything else (lockfile, manifest, cache) the default umask is
the right call: cache entries are public registry responses, the
lockfile is meant to be committed to source control, and manifests
are user-authored config.
Functions§
- atomic_
write - Write
bytestopathatomically. - tmp_
path_ for - Compute the temp path used by
atomic_write. Splitting this out lets callers reason about the rename target shape (and unit-test the orphan-cleanup path) without going through the filesystem.