WORM & object locking

Concurrent re-PUT while a write is in flight

Each PUT streams into a private temp file and is published atomically (a rename for plain keys, a create-only link for WORM keys), so a key only ever exists on disk as a complete, checksum-verified object. A re-PUT that races an in-flight write to the same key therefore can never observe a partial: it either wins the create itself (201) or, if the other writer commits first, gets the usual 409/204. There is no false success and no lock contention – an aborted or failed upload leaves only its own temp, never a half-written key.

In-flight temp files

While a PUT streams, its temp lives beside the target as .putfs-tmp.<random> in the same directory, so the atomic publish never crosses a filesystem boundary. Temp files are filtered from listings, and the .putfs-tmp. prefix is reserved – a key whose path uses it is rejected with 400. A hard crash (SIGKILL, power loss) can orphan a temp before it is published; reclaim them out of band, e.g. a cron find /srv/putfs -name '.putfs-tmp.*' -mmin +120 -delete with the age set comfortably above your longest expected upload so it never removes a live temp.

Regex portability and systemd escaping

The pattern is a Python re regex in the reference build. The Go and Rust ports compile it with RE2-family engines (regexp and the regex crate), which reject lookarounds ((?=...)) and backreferences (\1): patterns using those run only under Python and abort at startup on the ports. Named groups ((?P<sha256>...)) work in all three, so keep cross-build patterns to that subset.

Setting the value in a systemd Environment= line is a common trap: systemd unescapes C-style backslashes, so every regex backslash must be doubled (\d becomes \\d) or the whole line is rejected (Invalid syntax, ignoring) and the variable is left unset. An EnvironmentFile= with the value in single quotes, or a systemctl edit drop-in, lets you keep the pattern verbatim.

Checksum paths are automatically write-once

PUTFS_CHECKSUM_PATHS is only safe paired with WORM. Without it, a bad PUT to a key that already holds correct content truncates the existing file via O_TRUNC before the mismatch is detected; the bad bytes are then unlinked, but the original is gone too. This is true even of a single sequential re-upload, not just under concurrency. Because there is no safe use for content-addressed validation without WORM, the checksum patterns are folded into the PUTFS_WORM_PATHS set automatically – every checksum'd key is write-once by construction, with no separate WORM entry required and nothing to keep in sync. Add PUTFS_WORM_PATHS only for prefixes that are not content-addressed:

PUTFS_WORM_STRICT=true
PUTFS_CHECKSUM_PATHS=^acme-corp/lake/(?P<sha256>[0-9a-f]{64})/blob$

With this layout, re-PUTs of an existing key answer 409 strict / 204 lenient without reading the body, and only fresh keys ever reach the hashing (and temp-write) path.